@allbluecn/web-app 0.17.2 → 0.18.1

package/src/design-engine/engine/engine-decor.ts

@@ -0,0 +1,719 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// AllBlue - 理想之海
+// Copyright (C) 2026 AllBlue Contributors
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+import type { IEventListenerId, ILeaf, IUI } from "leafer-editor"
+
+import { applyConstraintsDiff } from "@/components/design/canvas/document/constraints"
+import { pickDropContainer, type FramePick } from "@/components/design/canvas/document/reparent"
+import { leaferToDoc, leafConfigOf } from "../document/serialize"
+import { BOARD_NODE_ID, type SceneDocument } from "@/components/design/canvas/document/types"
+import type { PenDecorState, ToolDecorationPort } from "@/components/design/canvas/tools/shape-tools"
+import {
+  ShaderFrameLoop,
+  collectShaderSpecs,
+  syncShaderFills,
+  syncShaderViewport,
+  type ShaderBoundsLike,
+} from "@/components/design/canvas/plugins/shader/lifecycle"
+import type { BoardFramePlugin } from "@/components/design/canvas/plugins/leafer-x-board/index"
+import { MeasureOverlay, computeMeasureGaps, type MeasureOverlayModule, type MeasureRect, type MeasureSegment } from "./measure-overlay"
+import {
+  PEN_ANCHOR_SIZE,
+  PEN_DECOR_ID_PREFIX,
+  PEN_HANDLE_DOT_SIZE,
+  PEN_HOVER_CIRCLE_SIZE,
+  VERTEX_DECOR_ID_PREFIX,
+  VERTEX_DECOR_SIZE,
+  collectDescendantIds,
+  leafId,
+  measureLeafBounds,
+} from "./helpers"
+import type { AppLike, PointLike, ReparentLeaf, ReparentTarget } from "./types"
+import { LeaferEngineBase } from "./engine-base"
+
+export class DecorEngine extends LeaferEngineBase {
+  // 帧失效循环（R18 动画闭环）：changeful 不驱动 leafer 重绘（实测证伪），
+  // 活跃动画实例存在时逐帧对目标 leaf forceRender；目标集每帧重读，
+  // 活跃集空自停。目标/失效回调延迟到调用时读 this（runtime 后装配）
+  protected shaderFrameLoop = new ShaderFrameLoop(
+    () => this.shaderRuntime?.animatingNodeIds() ?? [],
+    (nodeId) => this.forceRenderShaderLeaf(nodeId),
+  )
+  // 标签层插件（mount 后安装；标签构建/挂载/同步/命中/拖拽/视口跟随全托管）
+  protected boardPlugin: BoardFramePlugin | null = null
+
+  // 工具层（tools/pen-tool、tools/polyline-tools）消费的装饰端口：结构化满足 ToolEngine
+  readonly decorations: ToolDecorationPort = {
+    showVertices: (nodeId, points) => this.showVertexDecor(nodeId, points),
+    clearVertices: (nodeId) => this.clearVertexDecor(nodeId),
+    showPen: (nodeId, state) => this.showPenDecor(nodeId, state),
+    clearPen: (nodeId) => this.clearPenDecor(nodeId),
+  }
+
+  // ===== 测量距离线（按住 Cmd/Ctrl）=====
+
+  // 测量覆盖层与按键/指针状态；readOnly 不绑定（无编辑无测量语义）
+  private measureOverlay?: MeasureOverlay
+  private measureKeys = new Set<string>()
+  private measurePointer: { clientX: number; clientY: number } | null = null
+  private measureDisposers: Array<() => void> = []
+
+  // 按键用 window 级监听（画布外按下也生效），指针用 host 级（仅在画布上取点）。
+  // 不 preventDefault——Cmd/Ctrl 与既有快捷键（复制/粘贴/撤销）互不干扰
+  protected bindMeasureOverlay(app: AppLike): void {
+    const host = this.host
+    // 无头 mock 环境（vitest 假 el/window）无 DOM 事件面，测量绑定整体跳过
+    if (!host || typeof host.addEventListener !== "function") return
+    this.measureOverlay = new MeasureOverlay(
+      this.mod as unknown as MeasureOverlayModule,
+      app.tree as never,
+      app.sky as never,
+    )
+    const onKeyDown = (e: KeyboardEvent): void => {
+      if (e.key !== "Meta" && e.key !== "Control") return
+      if (this.measureKeys.has(e.key)) return
+      this.measureKeys.add(e.key)
+      this.measureRefresh()
+    }
+    const onKeyUp = (e: KeyboardEvent): void => {
+      if (e.key !== "Meta" && e.key !== "Control") return
+      this.measureKeys.delete(e.key)
+      if (!this.measureKeys.size) {
+        this.measureOverlay?.clear()
+        return
+      }
+      this.measureRefresh()
+    }
+    const onBlur = (): void => {
+      this.measureKeys.clear()
+      this.measureOverlay?.clear()
+    }
+    const onPointerMove = (e: PointerEvent): void => {
+      if (!this.measureKeys.size) return
+      this.measurePointer = { clientX: e.clientX, clientY: e.clientY }
+      this.measureRefresh()
+    }
+    window.addEventListener("keydown", onKeyDown)
+    window.addEventListener("keyup", onKeyUp)
+    window.addEventListener("blur", onBlur)
+    host.addEventListener("pointermove", onPointerMove)
+    this.measureDisposers = [
+      () => window.removeEventListener("keydown", onKeyDown),
+      () => window.removeEventListener("keyup", onKeyUp),
+      () => window.removeEventListener("blur", onBlur),
+      () => host.removeEventListener("pointermove", onPointerMove),
+    ]
+  }
+
+  // 按住 Cmd/Ctrl 期间的刷新入口：测量源 = 指针下内容元素（几何命中，容器
+  // 空白内部不算命中），无命中且指针落在单选元素父容器 bounds 内时回退该
+  // 单选元素（指针在别的容器/空白区不回退，避免线出现在无关容器里）；
+  // 算出线段后整批重绘（量少，≤8 段，无需增量 diff）
+  private measureRefresh(): void {
+    const overlay = this.measureOverlay
+    const tree = this.app?.tree
+    if (!overlay || !tree) return
+    let sourceId: string | null = null
+    let world: { x: number; y: number } | null = null
+    if (this.measurePointer) {
+      try {
+        world = (
+          tree as unknown as {
+            getWorldPointByClient: (p: { clientX: number; clientY: number }) => { x: number; y: number }
+          }
+        ).getWorldPointByClient({ clientX: this.measurePointer.clientX, clientY: this.measurePointer.clientY })
+        sourceId = this.pickMeasureSource(world)
+      } catch {
+        sourceId = null
+        world = null
+      }
+    }
+    if (!sourceId) {
+      const selection = this.getSelection().filter((id) => id !== BOARD_NODE_ID)
+      if (selection.length === 1) {
+        const selected = this.currentDoc.nodes.find((n) => n.id === selection[0])
+        // 回退前置条件：指针在选中元素的父容器（board 级即根画板）bounds 内。
+        // 指针在别的容器或画板外空白区 → 不显示，防止线画到选中元素所在
+        // 容器之外（用户视角即「线出现在错误的一侧」）
+        const parentLeaf = selected?.parentId ? this.nodeIndex.get(selected.parentId) : this.nodeIndex.get(BOARD_NODE_ID)
+        const parentRect = parentLeaf ? measureLeafBounds(parentLeaf) : null
+        if (!world || !parentRect || this.containsPoint(parentRect, world)) {
+          sourceId = selection[0]
+        }
+      }
+    }
+    overlay.update(sourceId ? this.computeMeasureSegments(sourceId) : [])
+  }
+
+  private containsPoint(rect: MeasureRect, point: { x: number; y: number }): boolean {
+    return (
+      point.x >= rect.x &&
+      point.x <= rect.x + rect.width &&
+      point.y >= rect.y &&
+      point.y <= rect.y + rect.height
+    )
+  }
+
+  // 几何命中：world AABB 包含指针的最深「内容元素」（kind shape/component；
+  // 容器 kind group 的空白内部不作为测量源——否则悬停画板空白会把线画到
+  // 画板外侧的兄弟元素上）。排除 board/隐藏/锁定（leafer 命中测试同样跳过
+  // 锁定元素）
+  private pickMeasureSource(world: { x: number; y: number }): string | null {
+    let bestId: string | null = null
+    let bestDepth = -1
+    const depthOf = new Map<string, number>()
+    for (const node of this.currentDoc.nodes) {
+      if (node.id === BOARD_NODE_ID || node.kind === "group" || node.locked === true || node.visible === false) continue
+      const leaf = this.nodeIndex.get(node.id)
+      if (!leaf) continue
+      let depth: number
+      if (node.parentId) {
+        depth = depthOf.get(node.parentId) ?? (() => {
+          let d = 0
+          let cursor: string | null = node.parentId ?? null
+          while (cursor && cursor !== BOARD_NODE_ID) {
+            d += 1
+            cursor = this.currentDoc.nodes.find((n) => n.id === cursor)?.parentId ?? null
+          }
+          depthOf.set(node.parentId, d)
+          return d
+        })()
+      } else {
+        depth = 0
+      }
+      depthOf.set(node.id, depth)
+      const b = measureLeafBounds(leaf)
+      if (!b) continue
+      if (world.x < b.x || world.x > b.x + b.width || world.y < b.y || world.y > b.y + b.height) continue
+      if (depth >= bestDepth) {
+        bestDepth = depth
+        bestId = node.id
+      }
+    }
+    return bestId
+  }
+
+  // 线段计算：候选 = 同父兄弟 + 父容器四边（Figma 式，不跨容器测量避免噪声）
+  private computeMeasureSegments(sourceId: string): MeasureSegment[] {
+    const src = this.currentDoc.nodes.find((n) => n.id === sourceId)
+    const srcLeaf = this.nodeIndex.get(sourceId)
+    if (!src || !srcLeaf) return []
+    const srcRect = measureLeafBounds(srcLeaf)
+    if (!srcRect) return []
+
+    const candidates: MeasureRect[] = []
+    for (const node of this.currentDoc.nodes) {
+      if (node.id === sourceId || node.id === BOARD_NODE_ID || node.visible === false) continue
+      if (node.parentId !== src.parentId) continue
+      const leaf = this.nodeIndex.get(node.id)
+      if (!leaf) continue
+      const rect = measureLeafBounds(leaf)
+      if (rect) candidates.push(rect)
+    }
+
+    const parentNode = src.parentId
+      ? this.currentDoc.nodes.find((n) => n.id === src.parentId)
+      : undefined
+    const parentLeaf = parentNode ? this.nodeIndex.get(parentNode.id) : undefined
+    const parentRect = parentLeaf ? measureLeafBounds(parentLeaf) : null
+
+    return computeMeasureGaps(srcRect, candidates, parentRect)
+  }
+
+  protected unbindMeasureOverlay(): void {
+    for (const dispose of this.measureDisposers) dispose()
+    this.measureDisposers = []
+    this.measureKeys.clear()
+    this.measureOverlay?.destroy()
+    this.measureOverlay = undefined
+  }
+  protected syncDocFromTree(): void {
+    const app = this.app
+    if (!app) return
+    this.syncBoardLabels()
+    const prev = this.currentDoc
+    const readback = leaferToDoc(app.tree, { device: this.opts.device, preserveFrom: prev })
+    this.currentDoc = { ...readback, nodes: applyConstraintsDiff(prev, readback) }
+    // 编辑器交互（拖拽/缩放）读回后树已是最新，增量 diff base 同步推进
+    this.appliedDoc = this.currentDoc
+    this.notifyDocChange()
+  }
+
+  // ===== 顶点装饰实现：canvas 坐标 → world → client → sky 内部坐标（sky 无
+  // 变换即内部坐标），与画板标签插件 place() 同一条投影链；zoomLayer CHANGE
+  // 时重投影。装饰仅绘制中存在，end/undo/dispose 即清除 =====
+
+  private canvasPointToSky(point: PointLike): PointLike | null {
+    const tree = this.app?.tree
+    const sky = this.app?.sky
+    if (!tree || !sky) return null
+    const world = tree.getWorldPoint(point)
+    const client = tree.getClientPointByWorld(world)
+    return sky.getWorldPointByClient({ clientX: client.x, clientY: client.y }, true) as PointLike
+  }
+
+  protected viewportLayer(): ILeaf | undefined {
+    const tree = this.app?.tree as unknown as { zoomLayer?: ILeaf; leafer?: { zoomLayer?: ILeaf } }
+    if (!tree) return undefined
+    return tree.zoomLayer ?? tree.leafer?.zoomLayer
+  }
+
+  // ===== shader fill 生命周期（FS-7.2，runtime 为引擎层单例不进 React）=====
+
+  /** applyScene（全量与增量）后的统一同步点：doc diff 驱动 attach/update/resize/detach */
+  protected syncShaderLifecycle(prev: SceneDocument | null, next: SceneDocument): void {
+    if (!this.shaderRuntime) return
+    // prev=null 的 detachAll 语义在 syncShaderFills 内部（首建/loadDoc/remount/
+    // undo 全量重建 = 全新挂载，先清空旧文档残留实例）
+    // readOnly（分享只读视图）走静态帧语义：FS-7.4「静态渲染一帧（speed 强制 0）」
+    const attached = syncShaderFills(prev, next, this.shaderRuntime, { staticFrame: this.opts.readOnly })
+    // 新挂载的 leaf 重设投影：paint 的 image 在 Resource 注册前解析会缓存失败
+    // 结果（实测 url fill 渲染为空），leafConfigOf 产出全新 paint 对象触发
+    // ImageManager → Resource 重新解析，命中 canvas view（静态单帧立即可见）
+    if (attached.size) {
+      const byId = new Map(next.nodes.map((node) => [node.id, node]))
+      for (const id of attached) {
+        const node = byId.get(id)
+        const leaf = this.nodeIndex.get(id)
+        if (!node || !leaf) continue
+        try {
+          ;(leaf as unknown as { set: (config: Record<string, unknown>) => void }).set(leafConfigOf(node))
+        } catch {
+          // 重设失败不阻塞同步（下一次 applyScene 会再走投影）
+        }
+      }
+    }
+    this.scheduleShaderViewportSync()
+    // attach/detach/updatePaint（speed/preset）后刷新帧失效循环状态
+    this.shaderFrameLoop.refresh()
+  }
+
+  /** 帧失效循环的单节点失效：leaf.forceRender（单帧失败不中断循环） */
+  private forceRenderShaderLeaf(nodeId: string): void {
+    const leaf = this.nodeIndex.get(nodeId)
+    if (!leaf) return
+    try {
+      ;(leaf as unknown as { forceRender?: () => void }).forceRender?.()
+    } catch {
+      // 下帧重试
+    }
+  }
+
+  /** 节点世界包围盒（leafer 官方 world 口径，含全部祖先变换）；读取失败视为缺失。
+   *  注意 leafer 2.3 签名：getBounds(type: 'content'|'box'|'stroke'|'render',
+   *  relative: 'world'|'page'|'local'|'inner')——'world' 是 relative 参数，
+   *  传进 type 会得到 undefined（实测） */
+  private shaderBoundsOf = (nodeId: string): ShaderBoundsLike | null => {
+    const leaf = this.nodeIndex.get(nodeId)
+    if (!leaf) return null
+    try {
+      const bounds = (leaf as unknown as { getBounds?: (type: string, relative?: string) => ShaderBoundsLike }).getBounds?.("box", "world")
+      return bounds ?? null
+    } catch {
+      return null
+    }
+  }
+
+  /** 视口矩形：host 容器尺寸（视图铺满容器），world 即画布像素坐标系 */
+  private shaderViewport(): ShaderBoundsLike | null {
+    const host = this.host
+    if (!host) return null
+    const width = host.clientWidth
+    const height = host.clientHeight
+    if (width <= 0 || height <= 0) return null
+    return { x: 0, y: 0, width, height }
+  }
+
+  /** 惰性判定（rAF 防布局失效周期内重入，与顶点装饰视口监听同纪律） */
+  private scheduleShaderViewportSync(): void {
+    if (this.shaderViewportPending) return
+    this.shaderViewportPending = true
+    requestAnimationFrame(() => {
+      this.shaderViewportPending = false
+      if (this.disposed || !this.app || !this.shaderRuntime) return
+      const viewport = this.shaderViewport()
+      if (!viewport) return
+      syncShaderViewport(collectShaderSpecs(this.currentDoc), this.shaderBoundsOf, viewport, this.shaderRuntime)
+      // 视口暂停/恢复改变活跃集，刷新帧失效循环
+      this.shaderFrameLoop.refresh()
+    })
+  }
+
+  /** zoom/pan 监听（zoomLayer CHANGE）：缩放/平移后重判可见性暂停 */
+  protected bindShaderViewport(): void {
+    if (this.shaderViewportIds.length) return
+    const layer = this.viewportLayer()
+    const change = this.mod.PropertyEvent?.CHANGE
+    if (!layer || !change || typeof layer.on_ !== "function") return
+    this.shaderViewportIds = [
+      layer.on_(change, (event: unknown) => {
+        // 仅响应 zoomLayer 自身属性变化（同顶点装饰监听：CHANGE 会从后代冒泡）
+        if ((event as { target?: unknown } | undefined)?.target !== layer) return
+        this.scheduleShaderViewportSync()
+      }),
+    ]
+  }
+
+  protected unbindShaderViewport(): void {
+    if (!this.shaderViewportIds.length) return
+    const layer = this.viewportLayer() as unknown as {
+      off_?: (ids: IEventListenerId | IEventListenerId[]) => void
+    }
+    layer.off_?.(this.shaderViewportIds)
+    this.shaderViewportIds = []
+  }
+
+  private bindVertexViewport(): void {
+    if (this.vertexViewportIds.length) return
+    const layer = this.viewportLayer()
+    const change = this.mod.PropertyEvent?.CHANGE
+    if (!layer || !change || typeof layer.on_ !== "function") return
+    this.vertexViewportIds = [
+      layer.on_(change, (event: unknown) => {
+        // 仅响应 zoomLayer 自身属性变化（缩放/平移）：PropertyEvent.CHANGE
+        // 会从后代元素冒泡，绘图中每次 leaf.set 都会触发本回调；回调内的
+        // 世界矩阵读取会打断当次 set 的布局失效周期，导致预览节点不重渲染
+        // （实踩：折线绘制中橡皮筋 patch 后画布不更新）。rAF 再延迟一帧，
+        // 彻底避开失效周期内的同步重入
+        if ((event as { target?: unknown } | undefined)?.target !== layer) return
+        requestAnimationFrame(() => {
+          this.reprojectVertexDecor()
+          this.reprojectPenDecor()
+        })
+      }),
+    ]
+  }
+
+  private unbindVertexViewport(): void {
+    if (!this.vertexViewportIds.length) return
+    const layer = this.viewportLayer() as unknown as {
+      off_?: (ids: IEventListenerId | IEventListenerId[]) => void
+    }
+    layer.off_?.(this.vertexViewportIds)
+    this.vertexViewportIds = []
+  }
+
+  protected removeVertexLeaves(): void {
+    const sky = this.app?.sky
+    if (sky) {
+      for (const leaf of this.vertexLeaves) sky.remove(leaf)
+    }
+    this.vertexLeaves = []
+    this.vertexDecor = null
+    // 两套装饰共用一个视口监听：仅在钢笔装饰也不活跃时才解绑
+    if (!this.penDecor) this.unbindVertexViewport()
+  }
+
+  private showVertexDecor(nodeId: string, points: readonly PointLike[]): void {
+    const app = this.app
+    const Square = this.mod.Rect
+    if (!app || this.opts.readOnly || !Square) return
+    this.removeVertexLeaves()
+    if (!points.length) return
+    this.vertexDecor = { nodeId, points: points.map((point) => ({ x: point.x, y: point.y })) }
+    points.forEach((point, index) => {
+      const pos = this.canvasPointToSky(point)
+      if (!pos) return
+      const leaf = Square.one({
+        id: `${VERTEX_DECOR_ID_PREFIX}${nodeId}:${index}`,
+        x: pos.x - VERTEX_DECOR_SIZE / 2,
+        y: pos.y - VERTEX_DECOR_SIZE / 2,
+        width: VERTEX_DECOR_SIZE,
+        height: VERTEX_DECOR_SIZE,
+        fill: "rgba(255,255,255,0.95)",
+        stroke: "rgba(99,102,241,0.9)",
+        strokeWidth: 1,
+        // 纯视觉反馈：不在 tree 命中链路（sky 层），hittable 双保险
+        hittable: false,
+        skipJSON: true,
+      })
+      app.sky.add(leaf)
+      this.vertexLeaves.push(leaf)
+    })
+    this.bindVertexViewport()
+  }
+
+  private clearVertexDecor(nodeId: string): void {
+    // 严格匹配：只清自己那一份，避免误清其他会话（当前单会话，防御性保留）
+    if (this.vertexDecor && this.vertexDecor.nodeId !== nodeId) return
+    this.removeVertexLeaves()
+  }
+
+  private reprojectVertexDecor(): void {
+    const decor = this.vertexDecor
+    if (!decor) return
+    decor.points.forEach((point, index) => {
+      const leaf = this.vertexLeaves[index]
+      if (!leaf) return
+      const pos = this.canvasPointToSky(point)
+      if (!pos) return
+      ;(leaf as unknown as { x: number; y: number }).x = pos.x - VERTEX_DECOR_SIZE / 2
+      ;(leaf as unknown as { x: number; y: number }).y = pos.y - VERTEX_DECOR_SIZE / 2
+    })
+  }
+
+  // ===== FS-1.1 锚点钢笔绘制装饰实现：与顶点装饰同一条投影链（canvas →
+  // world → client → sky）；视口变化时整组重建即重投影（leaf 数量少，等价
+  // 且免逐元素几何换算）。装饰仅绘制中存在，finish/cancel/undo/dispose 清除 =====
+
+  protected removePenLeaves(): void {
+    const sky = this.app?.sky
+    if (sky) {
+      for (const leaf of this.penLeaves) sky.remove(leaf)
+    }
+    this.penLeaves = []
+    this.penDecor = null
+    if (!this.vertexDecor) this.unbindVertexViewport()
+  }
+
+  // 深拷贝装饰状态：重投影重建需与最近一次 show 的入参解耦（调用方可复用/变更数组）
+  private clonePenState(state: PenDecorState): PenDecorState {
+    return {
+      anchors: state.anchors.map((point) => ({ x: point.x, y: point.y })),
+      handleLines: state.handleLines.map((line) => ({
+        from: { x: line.from.x, y: line.from.y },
+        to: { x: line.to.x, y: line.to.y },
+      })),
+      handleDots: state.handleDots.map((point) => ({ x: point.x, y: point.y })),
+      hoverStart: state.hoverStart,
+    }
+  }
+
+  private showPenDecor(nodeId: string, state: PenDecorState): void {
+    const app = this.app
+    const Rect = this.mod.Rect
+    const Line = this.mod.Line
+    const Ellipse = this.mod.Ellipse
+    if (!app || this.opts.readOnly || !Rect || !Line || !Ellipse) return
+    this.removePenLeaves()
+    this.penDecor = { nodeId, state: this.clonePenState(state) }
+    const add = (leaf: IUI) => {
+      app.sky.add(leaf)
+      this.penLeaves.push(leaf)
+    }
+    // 叠放次序：起点悬停圆圈（最底）→ 手柄细线 → 手柄圆点 → 锚点方块（最顶）
+    if (state.hoverStart && state.anchors.length) {
+      const pos = this.canvasPointToSky(state.anchors[0])
+      if (pos) {
+        add(
+          Ellipse.one({
+            id: `${PEN_DECOR_ID_PREFIX}${nodeId}:hover`,
+            x: pos.x - PEN_HOVER_CIRCLE_SIZE / 2,
+            y: pos.y - PEN_HOVER_CIRCLE_SIZE / 2,
+            width: PEN_HOVER_CIRCLE_SIZE,
+            height: PEN_HOVER_CIRCLE_SIZE,
+            stroke: "rgba(99,102,241,0.9)",
+            strokeWidth: 1.5,
+            hittable: false,
+            skipJSON: true,
+          }),
+        )
+      }
+    }
+    state.handleLines.forEach((line, index) => {
+      const from = this.canvasPointToSky(line.from)
+      const to = this.canvasPointToSky(line.to)
+      if (!from || !to) return
+      add(
+        Line.one({
+          id: `${PEN_DECOR_ID_PREFIX}${nodeId}:line:${index}`,
+          x: from.x,
+          y: from.y,
+          // Line.points 为相对 x/y 的相对坐标
+          points: [0, 0, to.x - from.x, to.y - from.y],
+          stroke: "rgba(99,102,241,0.9)",
+          strokeWidth: 1,
+          hittable: false,
+          skipJSON: true,
+        }),
+      )
+    })
+    state.handleDots.forEach((dot, index) => {
+      const pos = this.canvasPointToSky(dot)
+      if (!pos) return
+      add(
+        Ellipse.one({
+          id: `${PEN_DECOR_ID_PREFIX}${nodeId}:dot:${index}`,
+          x: pos.x - PEN_HANDLE_DOT_SIZE / 2,
+          y: pos.y - PEN_HANDLE_DOT_SIZE / 2,
+          width: PEN_HANDLE_DOT_SIZE,
+          height: PEN_HANDLE_DOT_SIZE,
+          fill: "rgba(255,255,255,0.95)",
+          stroke: "rgba(99,102,241,0.9)",
+          strokeWidth: 1,
+          hittable: false,
+          skipJSON: true,
+        }),
+      )
+    })
+    state.anchors.forEach((anchor, index) => {
+      const pos = this.canvasPointToSky(anchor)
+      if (!pos) return
+      add(
+        Rect.one({
+          id: `${PEN_DECOR_ID_PREFIX}${nodeId}:anchor:${index}`,
+          x: pos.x - PEN_ANCHOR_SIZE / 2,
+          y: pos.y - PEN_ANCHOR_SIZE / 2,
+          width: PEN_ANCHOR_SIZE,
+          height: PEN_ANCHOR_SIZE,
+          fill: "rgba(255,255,255,0.95)",
+          stroke: "rgba(99,102,241,0.9)",
+          strokeWidth: 1,
+          hittable: false,
+          skipJSON: true,
+        }),
+      )
+    })
+    this.bindVertexViewport()
+  }
+
+  private clearPenDecor(nodeId: string): void {
+    // 严格匹配：只清自己那一份，避免误清其他会话（当前单会话，防御性保留）
+    if (this.penDecor && this.penDecor.nodeId !== nodeId) return
+    this.removePenLeaves()
+  }
+
+  private reprojectPenDecor(): void {
+    const decor = this.penDecor
+    if (!decor) return
+    this.showPenDecor(decor.nodeId, decor.state)
+  }
+
+  // 文档变更后驱动标签插件同步：收集顶层有名称的画板 → 插件内部 diff
+  // （新增/改名/移除）并重投影。视口变化的重投影由插件监听 zoomLayer
+  // CHANGE 自理，此处只需在画板集合/位置变化时调用。FS-8.3：props._generating
+  // 标记透传为生成中脉冲态（面板流式生成期间由 done/中断清理）
+  protected syncBoardLabels(): void {
+    if (!this.boardPlugin) return
+    const frames = this.currentDoc.nodes
+      .filter(
+        (node) =>
+          node.type === "frame" &&
+          typeof node.name === "string" &&
+          node.name.length > 0 &&
+          // 嵌套画板（画板内拖拽落点产出）同样挂标签：标签由 sky 世界投影，
+          // 插件 place/bindDrag 均按 leaf 世界包围盒/父空间换算，嵌套天然正确。
+          // 不放行则嵌套画板 editable:false 且无标签，画布上完全无法选中
+          (node.visible ?? true),
+      )
+      .map((node) => {
+        const leaf = this.nodeIndex.get(node.id)
+        if (!leaf) return null
+        return {
+          id: node.id,
+          leaf,
+          name: node.name as string,
+          generating: node.props?._generating === true,
+        }
+      })
+      .filter((item): item is { id: string; leaf: ILeaf; name: string; generating: boolean } => item !== null)
+    this.boardPlugin.sync(frames)
+  }
+
+  // 拖拽结束后把落点在容器内的元素 re-parent 进容器（保持世界位置不变），
+  // 拖出容器（落点不在任何容器内）则回归 board 顶层；落点仍在原父元素内则不动。
+  // FS-4.3：落点容器从「仅顶层画板」扩展为「顶层 frame 或 group」——两者的
+  // 矩形在 doc 坐标（board 空间）同为 AABB，pickDropContainer 统一判定；
+  // 嵌套容器 doc 坐标是父相对空间，v1 仍限顶层（坐标换算需 worldToLocal 链，
+  // 官方 dropTo 侧已按世界坐标守恒处理目标为任意容器时的落位）
+  protected reparentOnDrop(): void {
+    const app = this.app
+    const editor = app?.editor
+    // SAFETY: tree.children 元素是 leafer UI 叶面，board Group 运行时必有 add/getInnerPoint/children
+    const board = app?.tree.children?.find(
+      (child) => leafId(child) === BOARD_NODE_ID,
+    ) as unknown as ReparentTarget | undefined
+    if (!app || !editor || !board || this.opts.readOnly) return
+    const containerPicks: FramePick[] = this.currentDoc.nodes
+      .filter(
+        (node) =>
+          (node.type === "frame" || node.type === "group") &&
+          node.id !== BOARD_NODE_ID &&
+          (node.visible ?? true) &&
+          (node.parentId === null || node.parentId === BOARD_NODE_ID),
+      )
+      .map((f) => ({ id: f.id, x: f.x, y: f.y, width: f.width, height: f.height }))
+    let changed = false
+    for (const leaf of editor.list) {
+      const targetId = this.reparentLeafOnDrop(leaf, board, containerPicks)
+      if (!targetId) continue
+      changed = true
+      // 拖入成员后组 bounds 重算（最终审查 B3）：leafer 只在子元素 MOVE 事件内
+      // 维护组尺寸，dropTo 挂载不触发——组 bounds 停留在建组时值，落在 bounds
+      // 外的成员点击命中丢失（selection=[]）。frames 尺寸固定不重算
+      const targetNode = this.currentDoc.nodes.find((node) => node.id === targetId)
+      if (targetNode?.type === "group") {
+        const groupLeaf = this.nodeIndex.get(targetId)
+        if (groupLeaf) this.resizeGroupLeafToChildren(groupLeaf)
+      }
+    }
+    if (changed) this.syncDocFromTree()
+  }
+
+  /** 组 leaf 尺寸 = 孩子组空间坐标 union（组原点到最远边缘，与 groupNodes 建组口径一致） */
+  private resizeGroupLeafToChildren(groupLeaf: ILeaf): void {
+    const children = (groupLeaf as { children?: ILeaf[] }).children
+    if (!children?.length) return
+    let maxX = 0
+    let maxY = 0
+    for (const child of children) {
+      const x = (child as { x?: number }).x ?? 0
+      const y = (child as { y?: number }).y ?? 0
+      const w = (child as { width?: number }).width ?? 0
+      const h = (child as { height?: number }).height ?? 0
+      if (!Number.isFinite(x) || !Number.isFinite(y)) continue
+      maxX = Math.max(maxX, x + w)
+      maxY = Math.max(maxY, y + h)
+    }
+    ;(groupLeaf as unknown as { set: (config: Record<string, unknown>) => void }).set({
+      width: maxX,
+      height: maxY,
+    })
+  }
+
+  // 返回落点容器 id（未发生 re-parent 返回 null）
+  private reparentLeafOnDrop(
+    leaf: ILeaf,
+    board: ReparentTarget,
+    containerPicks: readonly FramePick[],
+  ): string | null {
+    const id = leafId(leaf)
+    if (!id || id === BOARD_NODE_ID) return null
+    const exclude = new Set<string>([id])
+    collectDescendantIds(leaf, exclude)
+    const w = (leaf as { width?: number }).width ?? 0
+    const h = (leaf as { height?: number }).height ?? 0
+    // SAFETY: leafer ILeaf 运行时必有 getWorldPoint/getInnerPoint，类型声明拆分在子接口未随 ILeaf 导出
+    const movable = leaf as unknown as Pick<ReparentTarget, "getWorldPoint" | "getInnerPoint">
+    const worldCenter = movable.getWorldPoint({ x: w / 2, y: h / 2 })
+    const boardPoint = board.getInnerPoint(worldCenter)
+    const targetContainerId = pickDropContainer(boardPoint, containerPicks, exclude)
+    // SAFETY: nodeIndex 值均为 leafer UI 叶面，Board 实例运行时必有 add/getInnerPoint/children
+    const target: ReparentTarget | undefined = targetContainerId
+      ? (this.nodeIndex.get(targetContainerId) as unknown as ReparentTarget | undefined)
+      : board
+    if (!target || target === leaf.parent) return null
+    // 官方 dropTo API：一步完成 re-parent + 世界坐标守恒，免手算 getInnerPoint + 写 leaf.x/y。
+    // 手算在 Frame（Group 子类、overflow hide、__clipAfterFill）跨分支迁移时会漏处理坐标变换
+    // （leafer-ui issue #740/#741）。
+    ;(leaf as ReparentLeaf).dropTo(target)
+    // 落点为 board 时返回 BOARD_NODE_ID（合法容器 id）而非 null：dropTo(board)
+    // 同样改变了树的父子关系，caller 靠非空返回驱动 syncDocFromTree——返回
+    // null 会让「拖出容器到空白区」丢 doc 同步（回修 Important）
+    return targetContainerId ?? BOARD_NODE_ID
+  }
+}