@allbluecn/web-app 0.17.2 → 0.18.1

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

@@ -0,0 +1,376 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+import type { ILeaf } from "leafer-editor"
+
+import { getNodeFactory } from "@/components/design/canvas/registry/registry"
+import { projectedNode } from "@/components/design/canvas/document/style/style-mapper"
+import { BOARD_NODE_ID, createBoardNode, type SceneDocument, type SceneNode } from "@/components/design/canvas/document/types"
+import type { DocSceneResult } from "./serialize-read"
+
+// 画板名称标签与画板顶边的垂直距离（board 空间，负方向朝上）
+export const FRAME_LABEL_OFFSET_Y = 28
+
+// 标签 leaf id 前缀：dblclick 命中标签时由此解析所属画板 id
+export const FRAME_LABEL_ID_PREFIX = "frame_label:"
+
+type LeaferCtor = {
+  one?: (config: Record<string, unknown>, x?: number, y?: number, w?: number, h?: number) => ILeaf
+  new (config?: Record<string, unknown>): ILeaf
+}
+
+// doc 层 fill/stroke:"none"（无填充/无描边语义：钢笔 FS-1.1 默认样式 / 空
+// paints 投影）→ leafer 渲染修正：leafer-ui 2.3 对 fill:"none" 渲染默认黑填充
+// （实测像素采样：三角内部 [0,0,0,255]），stroke:"none" 同风险。增量 patch
+// 路径 leaf.set 缺键不清除旧值——翻译为显式 null 才能清除（探针实测
+// set({fill:null}) → __fill undefined）。doc 存储保持 "none" 字面不变，
+// 构造（buildOne）与增量（leafConfigOf）两路径共用本翻译
+function normalizeLeaferPaintEmpties(config: Record<string, unknown>): void {
+  if (config.fill === "none") config.fill = null
+  if (config.stroke === "none") config.stroke = null
+}
+
+function buildOne(
+  ctor: unknown,
+  config: Record<string, unknown>,
+  x: number,
+  y: number,
+  w: number,
+  h: number,
+): ILeaf {
+  const target = ctor as LeaferCtor
+  normalizeLeaferPaintEmpties(config)
+  if (typeof target.one === "function") return target.one(config, x, y, w, h)
+  return new target(config)
+}
+
+export function addLeaf(parent: ILeaf, child: ILeaf) {
+  if (typeof (parent as { add?: (c: ILeaf) => void }).add === "function") {
+    ;(parent as { add: (c: ILeaf) => void }).add(child)
+  }
+}
+
+function setLeafId(leaf: ILeaf, id: string) {
+  const target = leaf as { id?: string }
+  if (!target.id) target.id = id
+}
+
+// FS-2.4：leafer 原生图形参数白名单（圆环/扇形/正多边形/星形/折线/箭头端形等
+// 绘制变体落库 props）。白名单式直传而非全量透传，避免任意字段注入 leafer
+// config——与下方 text/path/font 内容通道同风格；均为 leafer 原生属性，无需转换。
+// 读侧 descToNode（serialize-read）复用同一白名单做 style → props 恢复
+export const SHAPE_PROP_KEYS = [
+  "innerRadius",
+  "startAngle",
+  "endAngle",
+  "sides",
+  "corners",
+  "cornerRadius",
+  "curve",
+  "closed",
+  "points",
+  "windingRule",
+  // FS-9 箭头插件：两端箭头形（13 种 IArrowStyle，缺省 none）
+  "startArrow",
+  "endArrow",
+] as const
+
+// 图形参数白名单直传（genericElement/leafConfigOf/buildElement 工厂补写共用）
+export function applyShapePropsToConfig(
+  props: Record<string, unknown> | undefined,
+  base: Record<string, unknown>,
+): void {
+  if (!props) return
+  for (const key of SHAPE_PROP_KEYS) {
+    const value = props[key]
+    if (value !== undefined) base[key] = value
+  }
+}
+
+// props（text/path/font + 图形原生参数）→ leaf config 键映射（genericElement 与
+// 增量 reconcile 共用，保证两条路径写入一致）
+export function applyPropsToConfig(
+  props: Record<string, unknown> | undefined,
+  base: Record<string, unknown>,
+): void {
+  if (!props) return
+  const { text, path, font } = props
+  if (text !== undefined) base.text = text
+  if (path !== undefined) base.path = path
+  if (font !== undefined) {
+    const f = font as {
+      size?: number
+      weight?: number | string
+      lineHeight?: number
+      letterSpacing?: number
+      family?: string
+    }
+    if (f.size !== undefined) base.fontSize = f.size
+    if (f.weight !== undefined) base.fontWeight = f.weight
+    if (f.lineHeight !== undefined) base.lineHeight = f.lineHeight
+    if (f.letterSpacing !== undefined) base.letterSpacing = f.letterSpacing
+    if (f.family !== undefined) base.fontFamily = f.family
+  }
+  applyShapePropsToConfig(props, base)
+}
+
+function genericElement(node: SceneNode, mod: typeof import("leafer-editor")): ILeaf {
+  // editable:true：leafer 点选（findOne）只选 path 中第一个 editable 元素，
+  // 基础元素不设则不可被点选（frame 在下方分支显式关闭）
+  const base: Record<string, unknown> = { editable: true, ...(node.style ?? {}) }
+  applyPropsToConfig(node.props, base)
+  const x = node.x
+  const y = node.y
+  const w = node.width
+  const h = node.height
+  switch (node.type) {
+    case "group":
+      return buildOne(mod.Group, base, x, y, w, h)
+    case "frame":
+      return buildOne(mod.Frame, base, x, y, w, h)
+    case "ellipse":
+      return buildOne(mod.Ellipse, base, x, y, w, h)
+    case "line":
+      // Line 仅支持 x/y/width（内部画 (0,0)→(width,0)），x1/y1/x2/y2 会被静默忽略
+      return buildOne(
+        mod.Line,
+        { ...base, x, y, width: w },
+        x,
+        y,
+        w,
+        h,
+      )
+    case "text":
+      return buildOne(mod.Text, base, x, y, w, h)
+    case "polygon":
+      return buildOne(mod.Polygon, base, x, y, w, h)
+    case "star":
+      return buildOne(mod.Star, base, x, y, w, h)
+    case "path":
+    case "pen-path":
+      // pen-path 为旧钢笔类型（读侧迁移为 path），写侧同走 leafer Path
+      return buildOne(mod.Path, base, x, y, w, h)
+    case "arrow":
+      // Arrow 继承 Line（x/y/width 语义），自带箭头头部
+      return buildOne(mod.Arrow, { ...base, x, y, width: w }, x, y, w, h)
+    default:
+      return buildOne(mod.Rect, base, x, y, w, h)
+  }
+}
+
+function buildElement(node: SceneNode, mod: typeof import("leafer-editor")): ILeaf {
+  const factory = getNodeFactory(node.type)
+  const target = projectedNode(node)
+  const leaf = factory ? factory.buildTree(target) : genericElement(target, mod)
+  applyProjectedKeys(leaf, target.style)
+  // 图形原生参数（props）补写到 leaf：注册工厂只消费样式键，圆环/扇形/正多边形/
+  // 星形等 shape 参数经白名单直传（与 leafConfigOf 增量 patch 同一通道）。对 leaf
+  // 直接赋值与 applyProjectedKeys 同模式（leafer 运行时接受动态 config 键赋值）；
+  // genericElement 路径已在 config 内写入过，重复赋值幂等
+  applyShapePropsToConfig(node.props, leaf as unknown as Record<string, unknown>)
+  // node.rotation 是 doc 层旋转权威：增量 patch 经 leafConfigOf 写入，全量重建
+  // （undo/redo force、loadDoc）经此处补写——否则画布视觉转正而 doc/属性面板
+  // 仍显示旋转，直到该节点下一次 patch 才自愈
+  if (node.rotation !== undefined) {
+    ;(leaf as unknown as Record<string, unknown>).rotation = node.rotation
+  }
+  return leaf
+}
+
+// 注册工厂只消费 fill/stroke/strokeWidth/cornerRadius，此处补写工厂遗漏的投影值
+// 只写幂等键：opacity 读回落 style.opacity、blendMode 读回落 node.blendMode、
+// 效果键经 STYLE_EXCLUDE 不进 style，重复写入不会产生"删除效果后仍渲染"的陈旧副本
+const PROJECTED_KEYS = [
+  "scaleX",
+  "scaleY",
+  "opacity",
+  "blendMode",
+  "shadow",
+  "innerShadow",
+  "blur",
+  "backgroundBlur",
+] as const
+
+function isLeafShadow(
+  value: unknown,
+): value is { x?: number; y?: number; blur?: number; spread?: number; color?: string }[] {
+  if (!Array.isArray(value) || !value.length) return false
+  return value.every((entry) => typeof entry === "object" && entry !== null && !Array.isArray(entry))
+}
+
+function applyProjectedKeys(leaf: ILeaf, style: Record<string, unknown> | undefined) {
+  if (!style) return
+  // SAFETY: ILeaf 的动态样式键（opacity/blendMode/shadow/scaleX 等）不在其
+  // TS 类型上，但 leafer 运行时接受任意 config 键赋值，写入前均逐键校验类型
+  const target = leaf as unknown as Record<string, unknown>
+  for (const key of PROJECTED_KEYS) {
+    const value = style[key]
+    if (key === "opacity") {
+      if (typeof value === "number" && Number.isFinite(value) && value >= 0 && value <= 1) target[key] = value
+    } else if (key === "blendMode") {
+      if (typeof value === "string" && value.length > 0) target[key] = value
+    } else if (key === "shadow" || key === "innerShadow") {
+      if (isLeafShadow(value)) target[key] = value
+    } else if (key === "blur" || key === "backgroundBlur") {
+      if (typeof value === "number" && Number.isFinite(value) && value > 0) target[key] = value
+    } else if (typeof value === "number" && Number.isFinite(value)) {
+      target[key] = value
+    }
+  }
+}
+
+// 画板名称标签构建（docToScene/buildSceneElement 与增量 reconcile 共用）
+export function buildFrameLabel(node: SceneNode, mod: typeof import("leafer-editor")): ILeaf {
+  const labelY = node.y - FRAME_LABEL_OFFSET_Y
+  return buildOne(
+    mod.Text,
+    {
+      id: `${FRAME_LABEL_ID_PREFIX}${node.id}`,
+      text: node.name,
+      x: node.x,
+      y: labelY,
+      fontSize: 13,
+      fill: "rgba(128,128,128,0.95)",
+      // 不可加 locked：leafer hit 测试跳过 locked 元素，会导致
+      // 双击重命名/拖拽联动永远无法命中标签
+      draggable: true,
+      skipJSON: true,
+    },
+    node.x,
+    labelY,
+    0,
+    0,
+  )
+}
+
+// 单节点 → leafer leaf 的构建（docToScene 与增量 reconcile 共用）：
+// 含工厂/通用构建、翻转平移写侧、frame tag/editable/name、名称标签构建。
+// 标签不在此挂载（由调用方挂 sky）
+export function buildSceneElement(
+  node: SceneNode,
+  mod: typeof import("leafer-editor"),
+): { element: ILeaf; label: ILeaf | null } {
+  const element = buildElement(node, mod)
+  // locked → 不可编辑（与 leafConfigOf 增量路径同映射：locked 剪命中 +
+  // editable 剪选中；全量重建路径 base config 恒 editable:true，需在此覆写）
+  if (node.locked === true && node.type !== "frame") {
+    ;(element as { editable?: boolean }).editable = false
+  }
+  // 翻转节点写入平移（与 leaferToDoc 读侧对称）：doc 层 x/y 是视觉左/上边界，
+  // Leafer 负 scale 绕左上角翻转，写侧需平移使视觉框 = [x, x+width]。
+  const sx = node.style?.scaleX
+  if (typeof sx === "number" && sx < 0) element.x = node.x + node.width
+  const sy = node.style?.scaleY
+  if (typeof sy === "number" && sy < 0) element.y = node.y + node.height
+  setLeafId(element, node.id)
+  let label: ILeaf | null = null
+  if (node.type === "frame") {
+    const el = element as { tag?: string; editable?: boolean; name?: string }
+    el.tag = "Frame"
+    // 画板不选中仅靠 editable:false（官方模型：selector 只选 editable 元素）。
+    // 禁止 hitSelf:false——Frame（Box 子类、overflow hide、有 fill）的
+    // __clipAfterFill 为真时，eachFind 会对 BranchLeaf 检查
+    // `__clipAfterFill && !__hitWorld → continue`，跳过整棵子树，
+    // 画板内元素将全部无法点选/框选（真实页面实测确认）。
+    // locked 同理禁止（editor 框选递归遇 locked 剪枝子树）。
+    // 选中画板：点名称标签 → pickFrameLabel → editor.select 显式设置
+    // （engine.select 会先动态开启 editable），不依赖命中链路
+    el.editable = false
+    if (typeof node.name === "string") el.name = node.name
+    if (
+      typeof node.name === "string" &&
+      node.name
+      // 标签位置由引擎按 leaf 世界包围盒统一投影（含嵌套画框），此处不限定父层级
+    ) {
+      label = buildFrameLabel(node, mod)
+    }
+  }
+  return { element, label }
+}
+
+// leaf.set 的扁平 config（增量 patch 与构建共用投影）：几何 + 样式投影 +
+// props 映射 + 状态位。翻转节点平移与 buildSceneElement 写侧一致
+export function leafConfigOf(node: SceneNode): Record<string, unknown> {
+  const projected = projectedNode(node)
+  const config: Record<string, unknown> = {
+    x: projected.x,
+    y: projected.y,
+    width: projected.width,
+    height: projected.height,
+    visible: node.visible ?? true,
+    // frame 不投影 locked：leafer 框选递归遇 locked 剪枝子树（画板内元素全部
+    // 不可选中，P0 实踩）。frame.locked 仅存 doc 层（锁定/解锁命令 + extensions
+    // 持久化），leaf 以 editable:false 表达「画板自身不可选中」
+    locked: node.type !== "frame" && node.locked === true,
+    ...(projected.style ?? {}),
+  }
+  if (node.rotation !== undefined) config.rotation = node.rotation
+  if (node.name !== undefined) config.name = node.name
+  // locked → 不可编辑双保险（selector 只选 editable 元素）：locked 剪命中链路、
+  // editable 剪选中链路。leaf.set 为合并语义，缺键不清除旧值——解锁必须显式
+  // 写回 editable:true，故非 frame 节点恒写该键
+  config.editable = node.type === "frame" ? false : node.locked !== true
+  const sx = node.style?.scaleX
+  if (typeof sx === "number" && sx < 0) config.x = node.x + node.width
+  const sy = node.style?.scaleY
+  if (typeof sy === "number" && sy < 0) config.y = node.y + node.height
+  applyPropsToConfig(node.props, config)
+  normalizeLeaferPaintEmpties(config)
+  return config
+}
+
+// 节点挂载到父容器（增量 reconcile 与 docToScene 共用）：parentId 指向的
+// 父不是 board 时挂父，否则挂 board 顶层
+export function attachElement(
+  board: ILeaf,
+  parentIndex: Map<string, ILeaf>,
+  node: SceneNode,
+  element: ILeaf,
+): void {
+  const parentElement = node.parentId ? parentIndex.get(node.parentId) : undefined
+  if (parentElement && parentElement !== board) addLeaf(parentElement, element)
+  else addLeaf(board, element)
+}
+
+export function docToScene(
+  doc: SceneDocument,
+  mod: typeof import("leafer-editor"),
+): DocSceneResult & { frameLabels: Map<string, ILeaf> } {
+  const boardNode = doc.nodes.find((node) => node.id === BOARD_NODE_ID) ?? doc.nodes[0]
+  const fallback = createBoardNode(doc.meta.device ?? "desktop")
+  const target = boardNode ?? fallback
+  const board = buildOne(
+    mod.Group,
+    {
+      editable: false,
+      x: 0,
+      y: 0,
+      width: target.width,
+      height: target.height,
+    },
+    0,
+    0,
+    target.width,
+    target.height,
+  )
+  setLeafId(board, BOARD_NODE_ID)
+  const nodeIndex = new Map<string, ILeaf>([[BOARD_NODE_ID, board]])
+  // 画板名称标签（画板外部左上）：由引擎挂到 app.sky 层（不参与缩放、不入
+  // 序列化），docToScene 只负责构建与登记，坐标由引擎按画板世界包围盒同步
+  const frameLabels = new Map<string, ILeaf>()
+
+  for (const node of doc.nodes) {
+    if (node.id === BOARD_NODE_ID) continue
+    const { element, label } = buildSceneElement(node, mod)
+    if (label) frameLabels.set(node.id, label)
+    nodeIndex.set(node.id, element)
+  }
+
+  for (const node of doc.nodes) {
+    if (node.id === BOARD_NODE_ID) continue
+    const element = nodeIndex.get(node.id)
+    if (!element) continue
+    attachElement(board, nodeIndex, node, element)
+  }
+
+  return { leafer: board, nodeIndex, frameLabels }
+}

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

@@ -0,0 +1,60 @@
+// 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/>.
+
+/**
+ * 场景序列化聚合出口（COMP-04.4 拆分）：本文件只做 re-export，且显式列出
+ * 拆分前的全部公共导出（不放大导出面，各模块内部 helper 保持私有）。
+ * 消费方 import 路径不变。各域实现：
+ * - serialize-shared：安全克隆 / 守卫 / 体积上限（叶子模块，无域依赖，
+ *   不经本出口导出）
+ * - serialize-read：leafer toJSON → SceneDocument（leaferToDoc）
+ * - serialize-write：SceneDocument → leafer（docToScene / leafConfigOf /
+ *   buildSceneElement；经 registry.getNodeFactory 消费 mapper 注册表，
+ *   运行时逐节点查表，注册时序与拆分前一致）
+ * - serialize-sanitize：脏数据守卫清洗（sanitizeScene / trimScene）
+ * - serialize-leafer-json：leafer-json 权威持久化包装（extensions 回填）
+ */
+
+// 读侧：leafer 树 → SceneDocument
+export { leaferToDoc, type DocSceneResult } from "./serialize-read"
+
+// 写侧：SceneDocument → leafer（含增量 patch 投影与画板名称标签）
+export {
+  addLeaf,
+  applyShapePropsToConfig,
+  applyPropsToConfig,
+  buildFrameLabel,
+  buildSceneElement,
+  leafConfigOf,
+  attachElement,
+  docToScene,
+  FRAME_LABEL_OFFSET_Y,
+  FRAME_LABEL_ID_PREFIX,
+} from "./serialize-write"
+
+// 守卫清洗与体积裁剪
+export { sanitizeScene, trimScene } from "./serialize-sanitize"
+
+// leafer-json 权威持久化包装
+export {
+  isLeaferJSONPackage,
+  exportLeaferJSON,
+  parseLeaferJSON,
+  normalizeSceneDocument,
+  type SceneNodeExtensions,
+  type LeaferJSONPackage,
+} from "./serialize-leafer-json"