@allbluecn/web-app 0.17.1 → 0.18.0

package/src/components/design/canvas/plugins/leafer-x-history-lite/index.ts

@@ -0,0 +1,501 @@
+// SPDX-License-Identifier: MIT
+//
+// leafer-x-history-lite — 轻量撤销/重做历史插件（LeaferJS 社区插件规范）
+//
+// 基于 PropertyEvent / ChildEvent 的 diff 快照栈（官方「历史记录」页推荐
+// 做法：https://www.leaferjs.com/ui/plugin/in/editor/Editor/history.html ）。
+// 官方不内置 undo/redo 栈；本插件以增量 diff（而非全量快照）记录变更，
+// 内存占用与树规模解耦。
+//
+// 契约（自包含，可整体搬移发布）：
+// - 仅 type-import leafer 类型 + 插件自身文件；leafer 运行时模块经
+//   installWithModule 注入（与消费方持有的 leafer 实例同源，SSR 友好）
+// - 对外唯一入口 installWithModule(mod, target, options?)，框架无关
+// - 持久化经 options.storage 注入（IndexedDB/localStorage 由消费方决定）
+//
+// 已知限制（leafer 事件模型的边界，详见 README）：
+// - ChildEvent.REMOVE 派发时 child 已脱离父容器，原 index 不可得——undo
+//   重建时 append 到原父末尾（z 序可能与删除前不同）
+// - undo 重建（UI.one）产生新 innerId，插件内部维护 old→leaf 别名表保证
+//   后续 prop 步仍可命中重建子树
+
+import type { ILeaf, IUI } from "leafer-editor"
+
+// ===== 类型 =====
+
+/** 属性变更条目（innerId 为 leafer 自增稳定标识，不依赖用户 id） */
+export interface PropChange {
+  kind: "prop"
+  innerId: number
+  key: string
+  before: unknown
+  after: unknown
+}
+
+/** 子树新增条目（json 为官方 toJSON 产物） */
+export interface AddChange {
+  kind: "add"
+  innerId: number
+  json: Record<string, unknown>
+  parentInnerId: number
+  index: number
+}
+
+/** 子树移除条目（index=-1 表示位置未知，重建时 append 到原父末尾） */
+export interface RemoveChange {
+  kind: "remove"
+  innerId: number
+  json: Record<string, unknown>
+  parentInnerId: number
+  index: number
+}
+
+export type HistoryChange = PropChange | AddChange | RemoveChange
+
+/** 一步用户操作（一批变更，undo/redo 以步为原子） */
+export type HistoryStep = HistoryChange[]
+
+/** 注入式持久化（IndexedDB/localStorage/远端均由消费方实现） */
+export interface HistoryStorage {
+  load(): Promise<HistoryStep[] | null>
+  save(steps: HistoryStep[]): Promise<void>
+}
+
+export interface HistoryLiteOptions {
+  /** 步数上限（默认 50，淘汰最旧） */
+  limit?: number
+  /** 事件监听与 undo 作用的目标树（默认 target.tree；也可直接传 ILeaf 分支） */
+  target?: ILeaf
+  /** 可选持久化：每步封步后 save，install 时异步 load 恢复 */
+  storage?: HistoryStorage
+  /**
+   * 交互切步（默认 true）：在目标树上监听官方 DragEvent.START/END 封步
+   * （官方「以 drag 交互为记录时机」指导；编辑器拖拽跨多帧，微批会把
+   * 一次拖拽切成多步）。无 drag 场景退化为微批聚合
+   */
+  splitOnInteraction?: boolean
+}
+
+export interface HistoryLite {
+  undo(): boolean
+  redo(): boolean
+  get canUndo(): boolean
+  get canRedo(): boolean
+  /** 已记录步数 */
+  get steps(): number
+  /** 清空全部历史 */
+  clear(): void
+  /** 暂停记录（程序化批量变更时使用，如导入/算法重排/undo 应用期间） */
+  pause(): void
+  /** 恢复记录 */
+  resume(): void
+  /** 手动封步：把自上次封步以来的变更合为一步（自定义记录时机时调用） */
+  commit(): void
+  destroy(): void
+}
+
+const DEFAULT_LIMIT = 50
+
+// ===== 事件载荷最小面（避免依赖 leafer 内部类型导出） =====
+
+interface PropEventPayload {
+  target?: unknown
+  attrName?: string
+  oldValue?: unknown
+  newValue?: unknown
+}
+
+interface ChildEventPayload {
+  type?: string
+  child?: ILeaf
+  parent?: ILeaf
+}
+
+export interface LeaferHistoryModule {
+  PropertyEvent: { CHANGE: string }
+  ChildEvent: { ADD: string; REMOVE: string }
+  DragEvent?: { START: string; END: string }
+  UI: { one: (data: unknown, x?: number, y?: number) => IUI }
+}
+
+// ===== 工具 =====
+
+function innerIdOf(leaf: unknown): number {
+  return (leaf as { innerId?: number }).innerId ?? -1
+}
+
+function parentOf(leaf: unknown): ILeaf | undefined {
+  return (leaf as { parent?: ILeaf }).parent
+}
+
+// ===== 插件主体 =====
+
+class HistoryLitePlugin implements HistoryLite {
+  private root: ILeaf
+  private limit: number
+  private storage?: HistoryStorage
+
+  private past: HistoryStep[] = []
+  private future: HistoryStep[] = []
+  private pending: HistoryStep = []
+  private pendingTimer: ReturnType<typeof setTimeout> | null = null
+  // 同步段内同 leaf 同 key 合并：before 保留最早值、after 取最新
+  private pendingProps = new Map<string, PropChange>()
+  // undo 重建后的 innerId 别名（重建 leaf 的新 innerId 不同于原值）
+  private alias = new Map<number, ILeaf>()
+  private paused = 0
+  private destroyed = false
+  private eventIds: unknown[] = []
+
+  constructor(
+    private mod: LeaferHistoryModule,
+    root: ILeaf,
+    options: HistoryLiteOptions = {},
+  ) {
+    this.root = root
+    this.limit = options.limit ?? DEFAULT_LIMIT
+    this.storage = options.storage
+    this.listen(options.splitOnInteraction ?? true)
+    void this.restore()
+  }
+
+  // ===== 公共 API =====
+
+  undo(): boolean {
+    if (this.paused || this.destroyed) return false
+    this.commit()
+    const step = this.past.pop()
+    if (!step) return false
+    this.paused++
+    try {
+      for (let i = step.length - 1; i >= 0; i--) {
+        const change = step[i]
+        if (change.kind === "prop") {
+          this.locate(change.innerId)?.set({ [change.key]: change.before })
+        } else if (change.kind === "add") {
+          // 反向：移除新增子树（leaf 通常仍存活，直接摘除）
+          this.detach(change.innerId)
+        } else {
+          // 反向：重建被移除子树（append 语义，见 RemoveChange 注释）
+          this.reinsert(change.innerId, change.json, change.parentInnerId, change.index)
+        }
+      }
+    } finally {
+      this.paused--
+    }
+    this.future.push(step)
+    while (this.future.length > this.limit) this.future.shift()
+    void this.persist()
+    return true
+  }
+
+  redo(): boolean {
+    if (this.paused || this.destroyed) return false
+    const step = this.future.pop()
+    if (!step) return false
+    this.paused++
+    try {
+      for (const change of step) {
+        if (change.kind === "prop") {
+          this.locate(change.innerId)?.set({ [change.key]: change.after })
+        } else if (change.kind === "add") {
+          this.reinsert(change.innerId, change.json, change.parentInnerId, change.index)
+        } else {
+          this.detach(change.innerId)
+        }
+      }
+    } finally {
+      this.paused--
+    }
+    this.past.push(step)
+    while (this.past.length > this.limit) this.past.shift()
+    void this.persist()
+    return true
+  }
+
+  get canUndo(): boolean {
+    return this.past.length > 0
+  }
+
+  get canRedo(): boolean {
+    return this.future.length > 0
+  }
+
+  get steps(): number {
+    return this.past.length
+  }
+
+  clear(): void {
+    this.past = []
+    this.future = []
+    this.pending = []
+    this.pendingProps.clear()
+    this.alias.clear()
+    if (this.pendingTimer) {
+      clearTimeout(this.pendingTimer)
+      this.pendingTimer = null
+    }
+    void this.persist()
+  }
+
+  pause(): void {
+    this.paused++
+  }
+
+  resume(): void {
+    if (this.paused > 0) this.paused--
+  }
+
+  commit(): void {
+    this.flushPending()
+  }
+
+  destroy(): void {
+    if (this.destroyed) return
+    this.destroyed = true
+    if (this.pendingTimer) clearTimeout(this.pendingTimer)
+    const target = this.root as unknown as {
+      off_: (ids: unknown) => void
+    }
+    try {
+      target.off_(this.eventIds)
+    } catch {
+      // 目标树可能已销毁
+    }
+    this.eventIds = []
+    this.past = []
+    this.future = []
+    this.pending = []
+    this.alias.clear()
+  }
+
+  // ===== 记录侧 =====
+
+  private listen(splitOnInteraction: boolean): void {
+    const target = this.root as unknown as {
+      on_: (
+        type: string | [string, string],
+        listener: (e?: unknown) => void,
+        bind?: unknown,
+      ) => unknown
+      off_: (ids: unknown) => void
+    }
+    const ids: unknown[] = [
+      target.on_(this.mod.PropertyEvent.CHANGE, (e?: unknown) => {
+        this.onPropChange(e as PropEventPayload)
+      }),
+      target.on_(
+        [this.mod.ChildEvent.ADD, this.mod.ChildEvent.REMOVE],
+        (e?: unknown) => {
+          this.onChildEvent(e as ChildEventPayload)
+        },
+      ),
+    ]
+    const drag = this.mod.DragEvent
+    if (splitOnInteraction && drag) {
+      // drag 事件从被拖元素冒泡到树根；start/end 各封一次步
+      ids.push(
+        target.on_(drag.START, () => {
+          this.flushPending()
+        }),
+      )
+      ids.push(
+        target.on_(drag.END, () => {
+          this.flushPending()
+        }),
+      )
+    }
+    this.eventIds = ids
+  }
+
+  private onPropChange(e: PropEventPayload): void {
+    if (this.paused || this.destroyed || !e?.target) return
+    const innerId = innerIdOf(e.target)
+    if (innerId < 0 || !e.attrName) return
+    const mergeKey = `${innerId}:${e.attrName}`
+    const existing = this.pendingProps.get(mergeKey)
+    if (existing) {
+      existing.after = e.newValue
+      return
+    }
+    const change: PropChange = {
+      kind: "prop",
+      innerId,
+      key: e.attrName,
+      before: e.oldValue,
+      after: e.newValue,
+    }
+    this.pendingProps.set(mergeKey, change)
+    this.pending.push(change)
+    this.scheduleFlush()
+  }
+
+  private onChildEvent(e: ChildEventPayload): void {
+    if (this.paused || this.destroyed || !e?.child) return
+    const parent = e.parent ?? parentOf(e.child)
+    if (!parent) return
+    let json: Record<string, unknown>
+    try {
+      json = (e.child as unknown as { toJSON: () => Record<string, unknown> }).toJSON()
+    } catch {
+      return
+    }
+    const innerId = innerIdOf(e.child)
+    if (e.type === this.mod.ChildEvent.ADD) {
+      // add 派发时 child 已插入 children，indexOf 即真实 index
+      const siblings = (parent as unknown as { children?: ILeaf[] }).children ?? []
+      const index = Math.max(0, siblings.indexOf(e.child))
+      this.pending.push({
+        kind: "add",
+        innerId,
+        json,
+        parentInnerId: innerIdOf(parent),
+        index,
+      })
+    } else {
+      // remove 派发时 child 已脱离（parent=null、不在 siblings），index 不可得
+      this.pending.push({
+        kind: "remove",
+        innerId,
+        json,
+        parentInnerId: innerIdOf(parent),
+        index: -1,
+      })
+    }
+    this.scheduleFlush()
+  }
+
+  private scheduleFlush(): void {
+    if (this.pendingTimer || this.destroyed) return
+    this.pendingTimer = setTimeout(() => this.flushPending(), 0)
+  }
+
+  private flushPending(): void {
+    if (this.pendingTimer) {
+      clearTimeout(this.pendingTimer)
+      this.pendingTimer = null
+    }
+    if (!this.pending.length) return
+    this.pendingProps.clear()
+    const step = this.pending
+    this.pending = []
+    this.past.push(step)
+    this.future = []
+    while (this.past.length > this.limit) this.past.shift()
+    void this.persist()
+  }
+
+  // ===== 应用侧 =====
+
+  private locate(innerId: number): ILeaf | undefined {
+    const aliased = this.alias.get(innerId)
+    if (aliased) return aliased
+    return findByInnerId(this.root, innerId)
+  }
+
+  private detach(innerId: number): void {
+    const leaf = this.locate(innerId)
+    if (!leaf) return
+    const parent = parentOf(leaf)
+    parent?.remove(leaf)
+  }
+
+  private reinsert(
+    innerId: number,
+    json: Record<string, unknown>,
+    parentInnerId: number,
+    index: number,
+  ): void {
+    const parent = this.locate(parentInnerId)
+    if (!parent) return
+    // 已存在则先摘除（重复应用保护 + 保证 index 语义）
+    this.detach(innerId)
+    let leaf: ILeaf
+    try {
+      const UI = this.mod.UI
+      leaf = UI.one(json) as ILeaf
+    } catch {
+      return
+    }
+    this.alias.set(innerId, leaf)
+    const branch = parent as unknown as {
+      add?: (child: ILeaf) => void
+      addAt?: (child: ILeaf, index: number) => void
+    }
+    if (index >= 0 && typeof branch.addAt === "function") {
+      branch.addAt(leaf, index)
+    } else {
+      branch.add?.(leaf)
+    }
+  }
+
+  // ===== 持久化 =====
+
+  private async restore(): Promise<void> {
+    if (!this.storage) return
+    try {
+      const steps = await this.storage.load()
+      if (steps && !this.destroyed) {
+        // 恢复为可撤销历史（不自动重放）；别名失效——跨会话的重建步不可
+        // undo 到位，直接丢弃涉及重建的步（prop 步照常保留）
+        this.past = steps
+          .slice(-this.limit)
+          .filter((step) => step.every((change) => change.kind === "prop"))
+      }
+    } catch {
+      // 持久化恢复失败静默跳过（历史不可用不阻塞画布）
+    }
+  }
+
+  private async persist(): Promise<void> {
+    if (!this.storage || this.destroyed) return
+    try {
+      await this.storage.save(this.past)
+    } catch {
+      // 存储失败静默（quota/私有模式等），内存历史不受影响
+    }
+  }
+}
+
+// 深度优先按 innerId 查找（undo 频率低，O(n) 可接受；不依赖 find 插件）
+function findByInnerId(root: ILeaf, innerId: number): ILeaf | undefined {
+  if (innerId < 0) return undefined
+  if (innerIdOf(root) === innerId) return root
+  const children = (root as unknown as { children?: ILeaf[] }).children
+  if (!children) return undefined
+  for (const child of children) {
+    const hit = findByInnerId(child, innerId)
+    if (hit) return hit
+  }
+  return undefined
+}
+
+// ===== 入口 =====
+
+/**
+ * 安装轻量历史插件。
+ *
+ * @param mod leafer 运行时模块（与消费方持有的实例同源；engine 场景传
+ *            `await import("leafer-editor")` 的结果）
+ * @param target App（监听其 tree）或任意 ILeaf 分支
+ * @param options 见 {@link HistoryLiteOptions}
+ */
+export function installWithModule(
+  mod: LeaferHistoryModule,
+  target: unknown,
+  options: HistoryLiteOptions = {},
+): HistoryLite {
+  const root = resolveRoot(target, options)
+  if (!root) {
+    throw new Error("[leafer-x-history-lite] target must be an App or ILeaf with tree")
+  }
+  return new HistoryLitePlugin(mod, root, options)
+}
+
+function resolveRoot(target: unknown, options: HistoryLiteOptions): ILeaf | null {
+  if (options.target) return options.target
+  const asApp = target as { tree?: ILeaf }
+  if (asApp.tree) return asApp.tree
+  if ((target as { innerId?: number }).innerId !== undefined) return target as ILeaf
+  return null
+}

package/src/components/design/canvas/plugins/leafer-x-pages/README.md

@@ -0,0 +1,30 @@
+# leafer-x-pages
+
+多画板管理插件（LeaferJS 社区插件规范，leafer-x 系列）：画板自动排布（按行填充、行满换行）、递增命名。
+
+纯数据函数集——排布/命名作用于业务文档层的画板记录（`{x, y, width, height}` 形态），无 leafer 运行时依赖。
+
+## 特性
+
+- **自动排布**：`findNextPosition(existing)`——行未满接同行右侧，行满换行对齐首列（Figma 式画板阵列）；按 y 分行（同行 y 差 ≤ 行内最大高度 + 容差）
+- **递增命名**：`nextName(existingCount)`——命名文案经 `nameTemplate` 注入（框架无关，不绑定任何 i18n 实现），默认 `画板 ${n}`
+- **可配置**：`perRow`（每行容量，默认 4）、`gap`（画板间距，默认 80）
+
+## 使用
+
+```ts
+import { installWithModule } from "./leafer-x-pages"
+
+const pages = installWithModule(null, null, {
+  perRow: 4,
+  gap: 80,
+  nameTemplate: (n) => `画板 ${n}`, // 或任意 i18n 实现
+})
+
+const pos = pages.findNextPosition(existingFrames)
+const name = pages.nextName(existingFrames.length)
+```
+
+## License
+
+MIT

package/src/components/design/canvas/plugins/leafer-x-pages/__tests__/pages.test.ts

@@ -0,0 +1,59 @@
+// SPDX-License-Identifier: MIT
+
+// leafer-x-pages 插件测试：纯数据函数集（无 leafer 运行时依赖）
+
+import { describe, expect, it } from "vitest"
+import { installWithModule } from "../index"
+
+describe("leafer-x-pages", () => {
+  const plugin = installWithModule(null, null)
+
+  it("空画板集合：下一位置为原点", () => {
+    expect(plugin.findNextPosition([])).toEqual({ x: 0, y: 0 })
+  })
+
+  it("行未满：接同行右侧", () => {
+    const next = plugin.findNextPosition([
+      { x: 0, y: 0, width: 390, height: 844 },
+      { x: 470, y: 0, width: 390, height: 844 },
+    ])
+    // maxX(860) + gap(80)
+    expect(next).toEqual({ x: 940, y: 0 })
+  })
+
+  it("行满：换行对齐首列", () => {
+    const w = 390
+    const h = 844
+    const gap = 80
+    const existing = Array.from({ length: 4 }, (_, i) => ({
+      x: i * (w + gap),
+      y: 0,
+      width: w,
+      height: h,
+    }))
+    const next = plugin.findNextPosition(existing)
+    expect(next).toEqual({ x: 0, y: h + gap })
+  })
+
+  it("nextName 递增命名（默认模板）", () => {
+    expect(plugin.nextName(0)).toBe("画板 1")
+    expect(plugin.nextName(3)).toBe("画板 4")
+  })
+
+  it("命名模板可注入（i18n 解耦）", () => {
+    const custom = installWithModule(null, null, {
+      nameTemplate: (n) => `Frame ${n}`,
+    })
+    expect(custom.nextName(5)).toBe("Frame 6")
+  })
+
+  it("perRow/gap 可配置", () => {
+    const custom = installWithModule(null, null, { perRow: 2, gap: 40 })
+    const next = custom.findNextPosition([
+      { x: 0, y: 0, width: 100, height: 100 },
+      { x: 140, y: 0, width: 100, height: 100 },
+    ])
+    expect(next).toEqual({ x: 0, y: 140 })
+    expect(custom.perRow).toBe(2)
+  })
+})

package/src/components/design/canvas/plugins/leafer-x-pages/index.ts

@@ -0,0 +1,81 @@
+// SPDX-License-Identifier: MIT
+//
+// leafer-x-pages — 多画板管理插件（LeaferJS 社区插件规范，leafer-x 系列）
+//
+// 画板的自动排布（按行填充、行满换行）、递增命名、下一个位置计算。
+// 纯数据函数集（无 leafer 运行时依赖）——排布/命名作用于业务文档层的
+// 画板记录（{x, y, width, height} 形态），业务在文档模型层消费。
+//
+// 契约（自包含，可整体搬移发布）：
+// - 零依赖（连 leafer 类型都不需要）；命名文案经 options 注入（框架无关，
+//   不绑定任何 i18n 实现）
+
+export interface FrameRect {
+  x: number
+  y: number
+  width: number
+  height: number
+}
+
+export interface PagesOptions {
+  /** 每行最大画板数（默认 4） */
+  perRow?: number
+  /** 画板间距（默认 80，水平/垂直同值） */
+  gap?: number
+  /**
+   * 递增命名模板（注入替代硬编码 i18n）：参数为现有画板数 + 1。
+   * 默认 `(n) => \`画板 ${n}\``
+   */
+  nameTemplate?: (index: number) => string
+}
+
+export interface PagesPlugin {
+  /** 下一个画板位置：按行填充（未满接同行右侧），行满换行对齐首列 */
+  findNextPosition(existing: FrameRect[]): { x: number; y: number }
+  /** 递增命名：模板注入，index = 现有画板数 + 1 */
+  nextName(existingCount: number): string
+  /** 建议尺寸下的一行容量（业务 UI 提示用） */
+  readonly perRow: number
+  readonly gap: number
+}
+
+export function installWithModule(
+  _mod: unknown,
+  _target: unknown,
+  options: PagesOptions = {},
+): PagesPlugin {
+  const perRow = options.perRow ?? 4
+  const gap = options.gap ?? 80
+  const nameTemplate =
+    options.nameTemplate ?? ((index: number) => `画板 ${index}`)
+
+  return {
+    perRow,
+    gap,
+    findNextPosition(existing: FrameRect[]): { x: number; y: number } {
+      if (existing.length === 0) return { x: 0, y: 0 }
+      const tolerance = 1
+      // 按 y 分行（同行 y 差 ≤ 行内最大高度 + 容差）
+      const sorted = [...existing].sort((a, b) => a.y - b.y)
+      const rows: FrameRect[][] = []
+      for (const f of sorted) {
+        const row = rows.find(
+          (r) => Math.abs(r[0].y - f.y) <= Math.max(...r.map((n) => n.height)) + tolerance,
+        )
+        if (row) row.push(f)
+        else rows.push([f])
+      }
+      const lastRow = rows[rows.length - 1]
+      if (lastRow.length < perRow) {
+        const maxX = Math.max(...lastRow.map((f) => f.x + f.width))
+        return { x: maxX + gap, y: lastRow[0].y }
+      }
+      const maxY = Math.max(...lastRow.map((f) => f.y + f.height))
+      const firstColX = Math.min(...rows[0].map((f) => f.x))
+      return { x: firstColX, y: maxY + gap }
+    },
+    nextName(existingCount: number): string {
+      return nameTemplate(existingCount + 1)
+    },
+  }
+}

package/src/components/design/canvas/plugins/shader/README.md

@@ -0,0 +1,23 @@
+# plugins/shader — 着色器运行时（业务插件模块）
+
+@paper-design/shaders（ShaderMount/WebGL）→ leafer 画布的运行时桥接。**业务插件模块**，非 leafer-x 社区插件规范。
+
+## 模块组成
+
+| 文件 | 职责 |
+|---|---|
+| `bridge.ts` | ShaderMount → leafer `Resource.setImage` 桥接（FS-7.1/7.2）：每个 shader paint 实例 = 隐藏宿主 div + ShaderMount，`mount.canvasElement` 注册为 `leafer://shader/<nodeId>/<paintId>`（url 工具的事实源在 `document/style/paints.ts`，本文件 re-export 保持 API）；含 props → uniforms 装配、活跃实例限额（≤8）、静态单帧/暂停三态模型 |
+| `presets.ts` | 12 预设注册表（FS-7.3）纯数据：id + defaultProps + maxColors，panels 消费的单一事实源；禁止 import leafer-editor / @paper-design/shaders |
+| `lifecycle.ts` | 生命周期同步（FS-7.2）：引擎 applyScene 后按 doc diff 驱动 attach/updatePaint/resize/detach；zoom/pan 视口交集惰性判定暂停；`ShaderFrameLoop` rAF 帧失效循环（活跃集为空自停）。对 runtime 仅 type import，零副作用纯逻辑 |
+
+## 与 plugins/ 下 leafer-x-* 社区插件的区别
+
+`leafer-x-*` 遵循 LeaferJS 社区插件规范：**零业务依赖**、只消费 leafer 官方 API、不感知文档模型。本目录**深度耦合业务 NodePaint 模型**（paint 类型投影、doc diff 同步、panels 预设面板共用数据源），不做 leafer-x 规范，故无 `leafer-x-` 前缀，仅为业务插件模块。
+
+**添加新着色器效果**：在 `presets.ts` 的 `SHADER_PRESET_DEFS` 增加一项（id/defaultProps/maxColors），并在 `bridge.ts` 的 `FRAGMENT_SHADERS` / `UNIFORM_SPECS` / `PRESET_NAMES` 补对应条目。
+
+## 重依赖隔离约束（分层红线）
+
+- 本目录是 **`@paper-design/shaders` + `leafer-editor` 运行时 import 的唯一所在**（bridge.ts 顶层 import；lifecycle.ts 仅 type import）。
+- **`document/` 静态链禁止反向依赖本目录**：paints.ts（SHADER_URL_PREFIX/shaderUrlOf 纯函数事实源）一旦 import 本目录，WebGL 依赖即进入 document 静态链，jsdom 测试链崩溃。引擎侧（engine/app.ts、engine/export-node.ts）对 bridge 一律**动态 import**，jsdom 测试经注入点/mock 隔离。
+- 面板（panels）只允许消费纯模块 `presets.ts`，不得 import bridge/lifecycle。