yft-design-engine

yft-design 的 WebGL2 画布引擎。接受 fabric toObject 格式的 JSON（objects 数组），输出 GL 画布 / 位图（任意倍率 FBO 读回）/ SVG（纯数据序列化器）。

当前状态：独立仓（GitHub more-strive/yft-design-engine，私有），npm 发布走 @yft-design/engine（public）——推 v* tag 触发 publish.yml：tag/版本一致性校验 → typecheck → 全量测试 → build → 闭包预检 → publish。主仓自批次 350 起撤出 workspace，从 registry 消费（^0.0.17），不再吃本地源码。包内单测自持：pnpm install && pnpm test。

构建产物（批次418 bundle 化）

pnpm build 产出两类互不感知的产物：

• 运行时：esbuild 单文件 bundle + minify（scripts/bundle.mjs）——dist/index.js（主入口，内部标识符 mangle、注释剥除、模块边界内联）+ 两个 debug 小入口（dist/debug/pixelDiff.js、dist/debug/seed.js，主仓 Engine 页运行时深导入的消费面）。
• 类型：tsc 全量多文件 .d.ts 镜像树（tsconfig.build.json emitDeclarationOnly），消费方 type-check 照常按模块路径解析。

固化口径（红线，改动前先读 scripts/bundle.mjs 头注）：

• 不开 mangle-props：引擎靠属性名匹配 fabric 序列化 JSON（left/top/fill/type…），mangle 即刻破坏兼容。
• 不产 sourcemap：发布包不携带源映射（要线上可调试就自存 hidden map，勿入 tarball）。
• runtime 依赖 external：rbush/gifuct-js/warpvas 保留在 dependencies 由消费方解析；gif2sprite 的 await import('gifuct-js') 懒加载语义原样保留。
• 深子路径自本批起仅存类型面（.d.ts）：运行时深子路径只有 debug/* 两个入口；主仓对引擎的消费一律走根导出（主仓 engineImportSurface.spec.ts 门禁白名单制），深路径 vi.mock 已翻根（textRaw.spec 先例——spread 保真）。
• 产物形态由 src/__tests__/distBundle.spec.ts 三层锁（形态/导出面/语义），tarball 闭包由 scripts/checkPackClosure.mjs 预检。

目录结构

| 目录 | 职责 | |---|---| | src/core/ | 基础原语：2D 仿射矩阵（mat2d）、事件总线、性能埋点（canvasPerf）、颜色 | | src/model/ | 文档模型：SceneNode 族（38 类元素）/ EngineDocument / 动画求值器 / 裁剪与蒙版纯函数 | | src/render/ | 渲染管线：批渲染（Quad/Mesh）、纹理缓存、字形图集、滤镜 GLSL 链、文本排版与烘焙 | | src/interact/ | 交互手势：指针/选择/裁剪/扩图/路径锚点/表格/文本编辑/动画播放编排 | | src/decoders/ | 动图解码：GIF（gifuct-js）/ 动 WebP → canvas sprite | | src/export/ | 导出：FBO 位图读回（SceneExporter）、SVG 序列化器 | | src/debug/ | 开发调试口（dev 页种子场景等；fabricReference 为主仓工具链专属 parity 参照域，不进发布产物） | | src/EngineCanvas.ts | 装配层（GL 生命周期/视口/帧循环/宿主薄委托——编排一律外拆 controller，见主仓架构文档 D16） |

运行时第三方依赖 rbush + gifuct-js + warpvas；fabric 零运行时引用。

消费方式（registry）

// yft-design-pro/package.json
"@yft-design/engine": "^0.0.17"

import { EngineCanvas, layoutTextbox } from '@yft-design/engine'

主仓对引擎包的 import/export 一律走根导出面（新符号先扩引擎 index.ts，门禁见主仓 src/app/engineImportSurface.spec.ts）；debug/* 深子路径仅限开发/e2e 链路白名单。

相关文档

• 路线图与进度（唯一事实源）：yft-design-pro/docs/2026-09-18_webgl2-engine-roadmap.md