@allbluecn/web-app 0.17.2 → 0.18.1

package/src/components/design/canvas/document/style/style-mapper.ts

@@ -0,0 +1,214 @@
+// src/components/design/canvas/core/style-mapper.ts
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+import { legacyRgba, parseColor, rgbaString } from "./color-utils"
+import { shaderUrlOf } from "./paints"
+import type { NodeEffect, NodePaint, PaintPoint } from "./paints"
+import type { SceneNode } from "../types"
+
+type LeafSolidPaint = {
+  type: "solid"
+  color: string
+  opacity: number
+  visible: boolean
+}
+
+type LeafShadow = { x: number; y: number; blur: number; spread: number; color: string }
+
+function cornerRadiusOf(corners: readonly number[]): number | number[] {
+  const [tl, tr, br, bl] = corners
+  return tl === tr && tr === br && br === bl ? tl : [tl, tr, br, bl]
+}
+
+export function isCornerRadiusValue(value: unknown): value is number | number[] {
+  if (typeof value === "number" && Number.isFinite(value) && value >= 0) return true
+  return (
+    Array.isArray(value) &&
+    value.length === 4 &&
+    value.every((c) => typeof c === "number" && Number.isFinite(c) && c >= 0)
+  )
+}
+
+export function parseCornerRadii(value: unknown): [number, number, number, number] | undefined {
+  if (typeof value === "number" && Number.isFinite(value) && value >= 0) {
+    return [value, value, value, value]
+  }
+  if (isCornerRadiusValue(value)) return value as [number, number, number, number]
+  return undefined
+}
+
+export function projectedCornerRadius(
+  style: Record<string, unknown> | undefined,
+): number | number[] | undefined {
+  const value = style?.cornerRadius
+  return isCornerRadiusValue(value) ? value : undefined
+}
+
+// doc 相对坐标（0~1）→ leafer percent 点；未定义时按类型给默认值，
+// 投影产物自包含（不依赖 leafer 版本默认值变化）
+function percentPoint(p: PaintPoint | undefined, fallbackX: number, fallbackY: number): { type: "percent"; x: number; y: number } {
+  const x = typeof p?.x === "number" && Number.isFinite(p.x) ? p.x : fallbackX
+  const y = typeof p?.y === "number" && Number.isFinite(p.y) ? p.y : fallbackY
+  return { type: "percent", x, y }
+}
+
+// 单个结构化 paint → leafer paint 对象（fills/strokes 共用）。
+// 每次调用产出全新对象图（leafer paint 子属性修改不触发 setter，官方要求
+// 数组整体赋值），doc 数据零别名。solid 烘焙不动；渐变/图片层 opacity
+// 直传（@leafer-in/color 生效）；shader 投影为 bridge 的 image paint url
+// （FS-7.1，width/height 不进 paint——宿主 div 几何由引擎生命周期维护）
+function projectPaint(p: NodePaint, nodeId: string): Record<string, unknown> {
+  const blend = p.blendMode !== undefined ? { blendMode: p.blendMode } : {}
+  switch (p.type) {
+    case "solid":
+      return {
+        type: "solid",
+        // leafer 不渲染 paint.opacity，须把透明度烘进色值（#rrggbbaa）
+        color: legacyRgba(p.color, typeof p.opacity === "number" ? p.opacity : 1),
+        opacity: 1,
+        visible: true,
+        ...blend,
+      } satisfies LeafSolidPaint
+    case "linear":
+      return {
+        type: "linear",
+        stops: p.stops.map((s) => ({ offset: s.offset, color: s.color })),
+        from: percentPoint(p.from, 0, 0),
+        to: percentPoint(p.to, 1, 1),
+        opacity: p.opacity,
+        visible: true,
+        ...blend,
+      }
+    case "radial": {
+      const paint: Record<string, unknown> = {
+        type: "radial",
+        stops: p.stops.map((s) => ({ offset: s.offset, color: s.color })),
+        from: percentPoint(p.from, 0, 0),
+        to: percentPoint(p.to, 1, 1),
+        opacity: p.opacity,
+        visible: true,
+        ...blend,
+      }
+      if (p.stretch !== undefined) paint.stretch = p.stretch
+      return paint
+    }
+    case "angular": {
+      const paint: Record<string, unknown> = {
+        type: "angular",
+        stops: p.stops.map((s) => ({ offset: s.offset, color: s.color })),
+        from: percentPoint(p.from, 0.5, 0.5),
+        opacity: p.opacity,
+        visible: true,
+        ...blend,
+      }
+      if (p.rotation !== undefined) paint.rotation = p.rotation
+      return paint
+    }
+    case "image": {
+      const paint: Record<string, unknown> = {
+        type: "image",
+        url: p.url,
+        mode: p.mode,
+        opacity: p.opacity,
+        visible: true,
+        ...blend,
+      }
+      if (p.scale !== undefined) paint.scale = p.scale
+      if (p.rotation !== undefined) paint.rotation = p.rotation
+      if (p.offset !== undefined) paint.offset = { x: p.offset.x, y: p.offset.y }
+      if (p.gap !== undefined) paint.gap = p.gap
+      if (p.interlace !== undefined) paint.interlace = p.interlace
+      return paint
+    }
+    case "shader":
+      // shaderId/props/speed 不入 leafer paint（runtime 持有）；url 由
+      // bridge 的 Resource.setImage 注册（leafer://shader/<nodeId>/<paintId>），
+      // 序列化读回时经 extensions.fills 优先恢复（FS-7.4）。
+      // changeful: true（leafer image paint 官方标）：跳过 CanvasPattern 缓存，
+      // 每次重绘直读 canvas view——实测缺省时 forceRender 也只画陈旧 pattern
+      return {
+        type: "image",
+        url: shaderUrlOf(nodeId, p.id),
+        opacity: p.opacity,
+        visible: true,
+        changeful: true,
+        ...blend,
+      }
+  }
+}
+
+export function projectStyle(node: SceneNode): Record<string, unknown> {
+  const out: Record<string, unknown> = {}
+
+  if (node.fills !== undefined) {
+    const paints = node.fills.filter((p) => p.visible)
+    out.fill = paints.length ? paints.map((p) => projectPaint(p, node.id)) : "none"
+  }
+
+  if (node.strokes !== undefined) {
+    const strokes = node.strokes.filter((s) => s.visible)
+    out.stroke = strokes.length ? strokes.map((s) => projectPaint(s.paint, node.id)) : "none"
+    const top = strokes[strokes.length - 1]
+    if (top) {
+      out.strokeWidth = top.width
+      if (top.cap !== undefined) out.strokeCap = top.cap
+      if (top.join !== undefined) out.strokeJoin = top.join
+      if (top.dashPattern !== undefined) out.dashPattern = [...top.dashPattern]
+      if (top.dashOffset !== undefined) out.dashOffset = top.dashOffset
+    }
+    // strokeAlign 已提升为节点级 style.strokeAlign（FS-6.1，多描边共享）
+    const align = typeof node.style?.strokeAlign === "string" ? node.style.strokeAlign : undefined
+    if (align !== undefined) out.strokeAlign = align
+  }
+
+  if (node.effects !== undefined) {
+    const shadows: LeafShadow[] = []
+    const innerShadows: LeafShadow[] = []
+    let blur: number | undefined
+    let backgroundBlur: number | undefined
+    const toShadow = (e: NodeEffect): LeafShadow => ({
+      x: e.offsetX ?? 0,
+      y: e.offsetY ?? 0,
+      blur: e.blur,
+      spread: e.spread ?? 0,
+      color: shadowColor(e),
+    })
+    for (const e of node.effects) {
+      if (!e.visible) continue
+      if (e.type === "drop-shadow") shadows.push(toShadow(e))
+      else if (e.type === "inner-shadow") innerShadows.push(toShadow(e))
+      else if (e.type === "layer-blur" && blur === undefined) blur = e.blur
+      else if (e.type === "background-blur" && backgroundBlur === undefined) backgroundBlur = e.blur
+    }
+    if (shadows.length) out.shadow = shadows
+    if (innerShadows.length) out.innerShadow = innerShadows
+    // 零强度模糊是无操作，不投影：genericElement 会把 style 整体展开进 leaf config，
+    // 零值也会落到 leaf 上（且经 STYLE_EXCLUDE 无法在读回侧清除）
+    if (blur !== undefined && blur > 0) out.blur = blur
+    if (backgroundBlur !== undefined && backgroundBlur > 0) out.backgroundBlur = backgroundBlur
+  }
+
+  if (node.corners !== undefined) out.cornerRadius = cornerRadiusOf(node.corners)
+
+  if (node.blendMode !== undefined) out.blendMode = node.blendMode
+
+  for (const key of ["scaleX", "scaleY"] as const) {
+    const value = node.style?.[key]
+    if (typeof value === "number" && Number.isFinite(value)) out[key] = value
+  }
+
+  return out
+}
+
+function shadowColor(e: NodeEffect): string {
+  const color = e.color ?? "#000000"
+  const parsed = parseColor(color)
+  return parsed ? rgbaString(parsed) : color
+}
+
+export function projectedNode(node: SceneNode): SceneNode {
+  const projected = projectStyle(node)
+  const keys = Object.keys(projected)
+  if (!keys.length) return node
+  return { ...node, style: { ...(node.style ?? {}), ...projected } }
+}

package/src/components/design/canvas/document/style/style-migrate.ts

@@ -0,0 +1,291 @@
+// src/components/design/canvas/core/style-migrate.ts
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+import { parseCornerRadii } from "./style-mapper"
+import {
+  createPaint,
+  createStroke,
+  isColorString,
+  isFiniteNumber,
+  paintId,
+  type ImagePaintMode,
+  type NodePaint,
+  type NodeStroke,
+  type PaintPoint,
+  type PaintStop,
+  type StrokeAlign,
+  type StrokeCap,
+  type StrokeJoin,
+} from "./paints"
+import { BOARD_NODE_ID, type SceneDocument, type SceneNode } from "../types"
+
+// 无法识别的 paint 条目降级灰（FS-6.2：不丢节点）
+const PAINT_FALLBACK_COLOR = "#9ca3af"
+
+// leafer 节点级线型/对齐键 → doc 字面量联合（非法值回落 undefined 走默认）
+function strokeAlignOf(v: unknown): StrokeAlign | undefined {
+  return v === "inside" || v === "outside" || v === "center" ? v : undefined
+}
+
+function strokeCapOf(v: unknown): StrokeCap | undefined {
+  return v === "none" || v === "round" || v === "square" ? v : undefined
+}
+
+function strokeJoinOf(v: unknown): StrokeJoin | undefined {
+  return v === "miter" || v === "bevel" || v === "round" ? v : undefined
+}
+
+function imageModeOf(v: unknown): ImagePaintMode | undefined {
+  return v === "cover" || v === "fit" || v === "stretch" || v === "repeat" || v === "clip"
+    ? v
+    : undefined
+}
+
+// v1 旧描边（顶层 color/align）→ 新 paint 嵌套结构的单条转换；
+// 非法旧描边返回 null（交由 isNodeStroke 守卫剔除）
+function migrateLegacyStroke(s: Record<string, unknown>): NodeStroke | null {
+  const { id, color, opacity, width, visible } = s as {
+    id?: unknown
+    color?: unknown
+    opacity?: unknown
+    width?: unknown
+    visible?: unknown
+  }
+  if (!isColorString(color)) return null
+  return createStroke({
+    id: typeof id === "string" && id ? id : undefined,
+    color,
+    opacity: isFiniteNumber(opacity) ? opacity : undefined,
+    width: isFiniteNumber(width) ? width : undefined,
+    visible: typeof visible === "boolean" ? visible : undefined,
+  })
+}
+
+// v1 → v2 描边惰性迁移（FS-6.1）：旧 NodeStroke{color,opacity,align,width}
+// 转为 {paint: solid, width}，align 提升回填节点级 style.strokeAlign（leafer
+// 约束：多描边共享 align，取最后一条合法值）；已是新结构（含 paint 字段）的
+// stroke 原样透传，无旧描边的节点原引用返回，整体幂等
+export function migrateNodePaints(node: SceneNode): SceneNode {
+  if (!Array.isArray(node.strokes)) return node
+  let align: string | undefined
+  let changed = false
+  const nextStrokes: unknown[] = []
+  for (const s of node.strokes) {
+    if (!s || typeof s !== "object" || "paint" in s || !("color" in s)) {
+      nextStrokes.push(s)
+      continue
+    }
+    const record = s as Record<string, unknown>
+    const recordAlign = strokeAlignOf(record.align)
+    if (recordAlign) align = recordAlign
+    const converted = migrateLegacyStroke(record)
+    if (!converted) {
+      nextStrokes.push(s)
+      continue
+    }
+    nextStrokes.push(converted)
+    changed = true
+  }
+  if (!changed) return node
+  const prevStyle = node.style
+  const style =
+    prevStyle && typeof prevStyle === "object" && !Array.isArray(prevStyle)
+      ? { ...(prevStyle as Record<string, unknown>), strokeAlign: align }
+      : { strokeAlign: align }
+  // 迁移边界处理 v1 持久化脏数据（旧描边无 paint 字段），未转换条目原样
+  // 保留、由下游 isNodeStroke 守卫剔除，故此处收窄回 SceneNode 形状
+  return { ...node, strokes: nextStrokes as SceneNode["strokes"], style }
+}
+
+// leafer percent 点（{type:"percent",x,y}）→ doc 相对坐标（标记剥离）；
+// 非法点位返回 null（还原时省略，写侧按类型给默认值）
+function restorePoint(v: unknown): PaintPoint | null {
+  if (!v || typeof v !== "object" || Array.isArray(v)) return null
+  const p = v as Record<string, unknown>
+  if (!isFiniteNumber(p.x) || !isFiniteNumber(p.y)) return null
+  return { x: p.x, y: p.y }
+}
+
+// 渐变色标还原：offset 0~1 + 颜色串合法（与 isNodePaint 守卫同口径），
+// 任一标非法即整体拒绝（交由降级路径）
+function restoreStops(v: unknown): PaintStop[] | null {
+  if (!Array.isArray(v) || v.length === 0) return null
+  const stops: PaintStop[] = []
+  for (const item of v) {
+    if (!item || typeof item !== "object" || Array.isArray(item)) return null
+    const s = item as Record<string, unknown>
+    if (!isFiniteNumber(s.offset) || s.offset < 0 || s.offset > 1 || !isColorString(s.color)) {
+      return null
+    }
+    stops.push({ offset: s.offset, color: s.color })
+  }
+  return stops
+}
+
+// leafer 投影条目 → 结构化 NodePaint（FS-6.2 读侧，按 type 判别还原）；
+// 无法识别/必填字段非法返回 null（调用方降级 solid 灰，不丢节点）。
+// solid 烘焙色原样保留保证幂等；id 由 paintId 补齐（投影产物不携带）
+function restorePaint(raw: unknown): NodePaint | null {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return null
+  const p = raw as Record<string, unknown>
+  const opacity = isFiniteNumber(p.opacity) ? p.opacity : 1
+  const blend = typeof p.blendMode === "string" && p.blendMode ? { blendMode: p.blendMode } : {}
+  switch (p.type) {
+    case "solid":
+      if (!isColorString(p.color)) return null
+      return { id: paintId("p"), type: "solid", color: p.color, opacity, visible: true, ...blend }
+    case "linear":
+    case "radial":
+    case "angular": {
+      const stops = restoreStops(p.stops)
+      if (!stops) return null
+      const from = restorePoint(p.from)
+      const to = p.type === "angular" ? null : restorePoint(p.to)
+      if (p.type === "angular") {
+        return {
+          id: paintId("p"),
+          type: "angular",
+          stops,
+          ...(from ? { from } : {}),
+          ...(isFiniteNumber(p.rotation) ? { rotation: p.rotation } : {}),
+          opacity,
+          visible: true,
+          ...blend,
+        }
+      }
+      return {
+        id: paintId("p"),
+        type: p.type,
+        stops,
+        ...(from ? { from } : {}),
+        ...(to ? { to } : {}),
+        ...(p.type === "radial" && isFiniteNumber(p.stretch) ? { stretch: p.stretch } : {}),
+        opacity,
+        visible: true,
+        ...blend,
+      }
+    }
+    case "image": {
+      if (typeof p.url !== "string" || p.url.length === 0) return null
+      const mode = imageModeOf(p.mode)
+      if (!mode) return null
+      const offset = restorePoint(p.offset)
+      return {
+        id: paintId("p"),
+        type: "image",
+        url: p.url,
+        mode,
+        ...(isFiniteNumber(p.scale) ? { scale: p.scale } : {}),
+        ...(isFiniteNumber(p.rotation) ? { rotation: p.rotation } : {}),
+        ...(offset ? { offset } : {}),
+        ...(isFiniteNumber(p.gap) ? { gap: p.gap } : {}),
+        ...(typeof p.interlace === "boolean" ? { interlace: p.interlace } : {}),
+        opacity,
+        visible: true,
+        ...blend,
+      }
+    }
+    default:
+      return null
+  }
+}
+
+export function normalizeNode(node: SceneNode): SceneNode {
+  if (node.id === BOARD_NODE_ID) return node
+  const style = node.style
+  if (!style || typeof style !== "object") return node
+  let next: SceneNode | null = null
+  const withField = (key: keyof SceneNode, value: unknown): void => {
+    if (node[key] !== undefined) return
+    next = next ?? { ...node }
+    ;(next as unknown as Record<string, unknown>)[key] = value
+  }
+
+  if (typeof style.fill === "string" && style.fill !== "none") {
+    withField("fills", [createPaint({ color: style.fill })])
+  } else if (Array.isArray(style.fill) && node.fills === undefined) {
+    // 官方 JSON 树（R2）的 fill 是 paint 数组投影（写侧 projectStyle 产物）：
+    // 按 type 判别还原五类结构化 paint；无法识别的条目降级 solid 灰并告警，
+    // 不丢节点（FS-6.2）。solid 烘焙色原样保留保证幂等。
+    // fills 已定义（extensions 优先恢复，FS-7.4）时整段跳过——shader url 等
+    // 不可逆投影项走 restorePaint 必 null，重跑只会误报降级告警
+    const paints: NodePaint[] = []
+    for (const item of style.fill) {
+      const paint = restorePaint(item)
+      if (paint) {
+        paints.push(paint)
+        continue
+      }
+      console.warn("normalizeNode: unrecognized fill paint, degraded to solid #9ca3af", item)
+      paints.push(createPaint({ color: PAINT_FALLBACK_COLOR }))
+    }
+    if (paints.length) withField("fills", paints)
+  }
+  if (
+    typeof style.stroke === "string" &&
+    style.stroke !== "none" &&
+    typeof style.strokeWidth === "number" &&
+    Number.isFinite(style.strokeWidth) &&
+    style.strokeWidth >= 0
+  ) {
+    withField("strokes", [createStroke({ color: style.stroke, width: style.strokeWidth })])
+  } else if (Array.isArray(style.stroke) && node.strokes === undefined) {
+    // 同 fill：官方 paint 数组按 type 判别还原结构化 strokes（strokes 已定义时
+    // 跳过，见上）。宽度/线型取写侧投影的节点级单值（leafer 约束：多描边共享
+    // 线型），应用到每条
+    const width =
+      typeof style.strokeWidth === "number" && Number.isFinite(style.strokeWidth)
+        ? style.strokeWidth
+        : undefined
+    const cap = strokeCapOf(style.strokeCap)
+    const join = strokeJoinOf(style.strokeJoin)
+    const dashPattern =
+      Array.isArray(style.dashPattern) && style.dashPattern.every((d) => isFiniteNumber(d))
+        ? style.dashPattern
+        : undefined
+    const dashOffset = isFiniteNumber(style.dashOffset) ? style.dashOffset : undefined
+    // R6 读侧闭环：对齐还原。节点级 style.strokeAlign（新写侧产物）优先；
+    // 旧写侧产物对齐嵌在每个 paint 条目上，取末位合法值回填节点级
+    const nodeAlign = strokeAlignOf(style.strokeAlign)
+    let itemAlign: StrokeAlign | undefined
+    const strokes: NodeStroke[] = []
+    for (const item of style.stroke) {
+      const alignOfItem =
+        item && typeof item === "object" && !Array.isArray(item)
+          ? strokeAlignOf((item as Record<string, unknown>).strokeAlign)
+          : undefined
+      if (alignOfItem) itemAlign = alignOfItem
+      const paint = restorePaint(item)
+      if (paint) {
+        strokes.push(createStroke({ paint, width, cap, join, dashPattern, dashOffset }))
+        continue
+      }
+      console.warn("normalizeNode: unrecognized stroke paint, degraded to solid #9ca3af", item)
+      strokes.push(createStroke({ color: PAINT_FALLBACK_COLOR, width }))
+    }
+    const resolvedAlign = nodeAlign ?? itemAlign
+    if (strokes.length) {
+      withField("strokes", strokes)
+      if (resolvedAlign !== undefined && style.strokeAlign !== resolvedAlign) {
+        next = next ?? { ...node }
+        next.style = { ...(style as Record<string, unknown>), strokeAlign: resolvedAlign }
+      }
+    }
+  }
+  const radii = parseCornerRadii(style.cornerRadius)
+  if (radii) withField("corners", radii)
+  if (typeof style.blendMode === "string" && style.blendMode) {
+    withField("blendMode", style.blendMode)
+  }
+  return next ?? node
+}
+
+export function normalizeScene(doc: SceneDocument): SceneDocument {
+  let changed = false
+  const nodes = doc.nodes.map((node) => {
+    const normalized = normalizeNode(node)
+    if (normalized !== node) changed = true
+    return normalized
+  })
+  return changed ? { ...doc, nodes } : doc
+}

package/src/components/design/canvas/document/style/theme-color.ts

@@ -0,0 +1,65 @@
+// 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/>.
+
+export type ThemeName =
+  | "--primary"
+  | "--primary-foreground"
+  | "--foreground"
+  | "--background"
+  | "--border"
+  | "--input"
+  | "--muted"
+  | "--muted-foreground"
+  | "--card"
+
+export const FALLBACKS: Record<ThemeName, string> = {
+  "--primary": "#0f172a",
+  "--primary-foreground": "#ffffff",
+  "--foreground": "#0f172a",
+  "--background": "#ffffff",
+  "--border": "oklch(1 0 0 / 10%)",
+  "--input": "oklch(1 0 0 / 10%)",
+  "--muted": "oklch(0.97 0 0)",
+  "--muted-foreground": "oklch(0.5 0 0)",
+  "--card": "#ffffff",
+}
+
+const THEME_NAMES = Object.keys(FALLBACKS) as ThemeName[]
+
+let cache = new Map<ThemeName, string>()
+let cacheTime = 0
+const TTL = 30_000
+
+export function resolveThemeColor(name: ThemeName): string {
+  if (typeof document === "undefined") return FALLBACKS[name]
+  const now = Date.now()
+  if (cacheTime === 0 || now - cacheTime > TTL) {
+    const cs = getComputedStyle(document.documentElement)
+    cache = new Map()
+    for (const k of THEME_NAMES) {
+      const v = cs.getPropertyValue(k).trim()
+      cache.set(k, v || FALLBACKS[k])
+    }
+    cacheTime = now
+  }
+  return cache.get(name) ?? FALLBACKS[name]
+}
+
+export function clearThemeColorCache() {
+  cache = new Map()
+  cacheTime = 0
+}

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

@@ -0,0 +1,123 @@
+// 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 { createPaint, type ExportPreset, type NodeConstraints, type NodeEffect, type NodePaint, type NodeStroke, type RefCorner } from "./style/paints"
+
+export const DEVICE_SIZES = { desktop: null, tablet: 768, mobile: 375 } as const
+export type DeviceType = keyof typeof DEVICE_SIZES
+export const BOARD_DEFAULT_HEIGHT = 812
+export const BOARD_NODE_ID = "board"
+
+export type SceneNodeKind = "shape" | "component" | "group"
+export type SceneNodeType =
+  | "board"
+  | "group"
+  | "rect"
+  | "ellipse"
+  | "line"
+  | "arrow"
+  | "text"
+  | "pen-path"
+  | "path"
+  | "polygon"
+  | "star"
+  | string
+
+export const STRUCTURAL_TYPES = new Set<SceneNodeType>(["board", "group", "frame"])
+
+export type SceneNode = {
+  id: string
+  kind: SceneNodeKind
+  type: SceneNodeType
+  parentId: string | null
+  name?: string
+  x: number
+  y: number
+  width: number
+  height: number
+  rotation?: number
+  zIndex?: number
+  locked?: boolean
+  visible?: boolean
+  style?: Record<string, unknown>
+  props?: Record<string, unknown>
+  overrides?: Record<string, unknown>
+  fills?: NodePaint[]
+  strokes?: NodeStroke[]
+  effects?: NodeEffect[]
+  exports?: ExportPreset[]
+  constraints?: NodeConstraints
+  corners?: [number, number, number, number]
+  blendMode?: string
+  aspectLocked?: boolean
+  refCorner?: RefCorner
+}
+
+export type SceneDocument = {
+  version: 1
+  meta: { device?: DeviceType; background?: string }
+  nodes: SceneNode[] // nodes[0] 恒为 board
+}
+
+export type ToolId =
+  | "select"
+  | "frame"
+  | "rect"
+  | "ellipse"
+  | "line"
+  | "arrow"
+  | "pen"
+  | "text"
+  | "polygon"
+  | "star"
+
+const DEFAULT_BOARD_WIDTH = 1200
+
+export function createBoardNode(device: DeviceType = "desktop"): SceneNode {
+  const width = DEVICE_SIZES[device] ?? DEFAULT_BOARD_WIDTH
+  return {
+    id: BOARD_NODE_ID,
+    kind: "group",
+    type: "board",
+    parentId: null,
+    name: "Board",
+    x: 0,
+    y: 0,
+    width,
+    height: BOARD_DEFAULT_HEIGHT,
+    // 默认填充走结构化 fills（与 frame 工厂一致）；读侧对 board 的
+    // style.fill/fills 剥离语义不变（防主题色污染入库）
+    fills: [createPaint({ color: "#ffffff" })],
+    locked: true,
+  }
+}
+
+export function createEmptyDoc(device: DeviceType = "desktop"): SceneDocument {
+  return {
+    version: 1,
+    meta: { device },
+    nodes: [createBoardNode(device)],
+  }
+}
+
+export function isSceneDocument(v: unknown): v is SceneDocument {
+  if (!v || typeof v !== "object") return false
+  const d = v as Partial<SceneDocument>
+  if (d.version !== 1) return false
+  if (!Array.isArray(d.nodes)) return false
+  return d.nodes.some((n) => n?.id === BOARD_NODE_ID)
+}