@@ -142,3 +142,73 @@ Core `subgraphs.member_positions` 能力启用时，最终落点（源画布局
上传图片时立即在画布显示本地预览，并在后台上传原始文件；上传成功才把稳定附件引用加入快照。服务端预览加载完成前继续显示本地图片，避免网络等待期间空白。失败保留文件供重试/取消，重试沿用同一幂等键；本地 blob URL 不保存到服务端。
上传中的图片也是正常本地节点，可立即选中、拖动、缩放、改名、删除和撤销；上传完成只补齐附件引用，不重置节点。上传前改变分区归属会先在本地完成，文件准备好后保存到当时的实际所属画布。临时上传标记和 blob 地址由传输层排除，不发送给 Core；文件仍未可用时，依赖服务端文件的 AI 生成需等待上传完成。
## 配置与生成数据阅读说明
本节为不适合内嵌注释的配置和严格 JSON 提供旁注；实际值仍以对应文件为准。源码、脚本和测试中的函数说明保留在各自文件内。包版本、TypeScript 输出目标、服务协议版本、文档格式版本和组件数据版本是不同概念。
### 应用包与执行入口
根 `package.json` 的 `private: true` 防止常规 npm 发布，`version: 0.1.0` 是应用包版本。`dependencies` 是应用运行/构建引用的库，`devDependencies` 包含编译器、类型声明和 Tailwind 工具；它们的精确版本及传递依赖由 `package-lock.json` 锁定。lock 文件由包管理器维护，不在其中手写说明或改某个嵌套版本。
| scripts 项 | 执行内容与边界 |
| --- | --- |
| `dev` | 在 localhost:17321 启动 Next 开发服务器，会按需编译。 |
| `build` / `start` | 前者执行 Next 生产构建，后者在 localhost:17321 运行已有构建。 |
| `typecheck` | `tsc --noEmit` 检查类型，不生成应用 JS。 |
| `test:headless` | 运行 `tests/headless/*.test.mjs` ；不自动执行所有 `.integration.mjs` 或浏览器场景。 |
| `test:headless:browser` | 浏览器存储、Worker 等适配器场景入口，环境装配见 `browser-storage.mjs` 。 |
| `test:headless:proxy` | Foundry 同源代理的隔离集成入口，启动与替身链路见 `proxy.integration.mjs` 。 |
| `test:headless:renderer` / `test:headless:performance` | 运行页面集成入口；后者附加 `--performance` 选择性能场景。 |
| `build:headless` | 清理并重建 `.headless-dist` 的 ESM、声明和 Worker 引用，再复制包清单/文档。 |
| `test:headless:package` | 构建、打包到隔离目录并运行消费方及浏览器验收，不是单纯语法检查。 |
集成入口可能编译或启动本地进程，具体动作见各脚本模块注释；本节列出命令不表示这些检查已经运行或通过。
### 应用 TypeScript 配置
`tsconfig.json` 面向应用检查；以下选项共同作用，并非运行时开关：
| 配置项 | 用途 |
| --- | --- |
| `target: ES2020` / `lib` | 声明语言输出目标和可用类型库；`dom` 、`dom.iterable` 、`esnext` 提供 API 类型，不会安装浏览器 polyfill。 |
| `allowJs` / `skipLibCheck` | 允许 JS 进入项目；跳过声明文件内部的完整检查。它们不关闭项目 TS 源码的检查。 |
| `strict` / `noEmit` | 启用严格类型检查，默认只检查而不生成 JS/声明。 |
| `allowImportingTsExtensions` | 允许源码相对导入使用 `.ts` 等 TS 扩展名；独立包输出由另一配置重写扩展名。 |
| `esModuleInterop` | 为 CommonJS/ESM 互操作提供 TypeScript 的兼容处理，不把整个项目改成 CommonJS。 |
| `module: esnext` / `moduleResolution: bundler` | 使用 ESM 语法并按 bundler 模式解析依赖；应用最终交由 Next 构建链处理。 |
| `resolveJsonModule` | 允许 TS 引用并推断 JSON 模块，例如图标 manifest。 |
| `isolatedModules` / `jsx: react-jsx` | 按单文件转换约束检查源码，并使用 React 自动 JSX 转换形式。 |
| `incremental` | 允许 TypeScript 使用增量检查缓存；生成的 `*.tsbuildinfo` 被忽略。 |
| `paths` | `@/*` 在 TS 解析时指向 `src/*` ，这不是把字符串路径写进业务文档。 |
| `plugins` | 登记 Next TypeScript 插件供支持它的工具使用。 |
| `include` / `exclude` | 纳入应用 TS/TSX、`next-env.d.ts` 与 Next 生成类型入口；排除依赖和独立包输出目录。由这些源码导入的依赖仍可参与类型解析。 |
`next-env.d.ts` 是 Next 维护的类型入口，引用框架/图片和生成路由类型。其路径会随开发/构建环境变化，不在这个生成文件中追加维护注释。
### 独立 headless 包
`tsconfig.headless.json` 继承应用配置，显式覆盖输出部分：`target` /`module` 为 ES2022， `rootDir` 为 `src/lib` ， `outDir` 为 `.headless-dist/modules` ； `noEmit: false` 与 `declaration: true` 生成 JS 和 `.d.ts` 。`incremental: false` 不使用这次编译的增量缓存，`rewriteRelativeImportExtensions` 将可重写的相对 TS 导入转成输出扩展名。`types: []` 和 `plugins: []` 清空自动纳入的类型包列表与继承插件条目，不禁止源码显式导入类型；未覆盖的 `lib` 等项仍继承。四组 `include` 从 core/runtime/service/bindings 的 `.ts` 入口收集源码，导入关系还会带入所需依赖。
`headless/package.json` 是复制到产物根的包模板，源目录本身没有生成后的 `modules` 。它的 `type: module` 声明 ESM， `>=22` 。`exports` 为每个公开入口分别指定类型声明和 ESM 文件：根及 `/core` 指向 core，另有 `/runtime` 、`/browser` 、`/service` 、`/bindings` 、`/react-flow` 与 `/react` 。这些是产物目录中的路径，不是指向 `src` 的别名，也没有声明 CommonJS `require` 入口。
`files` 限定包收录的模块、消费示例和验收文档。React、React DOM、React Flow 以带版本范围的可选 peer 声明，供选择相关适配入口的宿主提供；“可选”不表示调用 UI 适配器时可以缺少它依赖的框架。便携入口的使用和依赖边界见 `headless/README.md` 。`private: true` 保持预览包私有，不代表已经发布到 registry。
### 组件生成器配置
`components.json` 是 UI 组件生成器读取的配置，不是应用运行时组件 registry。`$schema` 指向配置的 schema； `style: new-york` 、`tsx: true` 和 `rsc: false` 记录生成风格、TSX 和 RSC 选项，不改变整个 App Router 的路由/渲染模式。`tailwind.css` 指向 `src/styles/globals.css` ，空 `tailwind.config` 没有指定独立配置路径，`baseColor: neutral` 与 `cssVariables: true` 是生成器的配色约定。`aliases` 指示生成文件的组件、工具、UI、lib 和 hooks 导入位置；其中 `@/hooks` 不保证已经存在对应目录。
### 图标生成数据
`src/components/canvas/icon-catalog-data.json` 是检索目录数组，每项包含 `name` （持久引用的图标 ID）、`slug` 、`source` 、`label` 、`categories` 、`common` 和 `keywords` ；不包含 SVG 路径。`icon-catalog.ts` 用它构建名称 Map 并执行筛选，选择器的虚拟窗口另由 UI 控制。
`src/lib/canvas-icon-assets.json` 保存 `root` URL 前缀与 `assets` 桶名到摘要文件名的映射。`iconAsset()` 对 Lucide 名称做 31 进制滚动散列并模 96，Tabler 名称统一使用 `tabler` 桶。`public/canvas-icons/<版本目录>/*.json` 每个分片以图标名索引 `[tag, props][]` ，消费端 `validateIconShard()` 再检查支持的图形与属性。
这三类数据由 `scripts/generate-canvas-icons.mjs` 同批生成，中文标注来自 `scripts/canvas-icon-labels.mjs` 。文件名摘要是紧凑 JSON 内容的 SHA-256 前 12 位，写盘时另加换行；它与分桶散列用途不同。分片变更须同步目录/manifest 并更新摘要名；脚本不会自动删除旧分片。不要在 JSON 中插入注释或只手改其中一份，否则会破坏读取、引用或缓存命名约定。
### 协议样例与忽略规则
`tests/headless/fixtures/foundry-model-operation-v2.json` 是服务适配器单测的完整请求样例。协议 2 的 `request_id` 标识冻结请求，`expected_versions` 是参与 canvas 的已确认版本，`operations[].id` 是逻辑操作 ID。样例把第一代元素 `a` 的 `data.title` 从 `a` 改为 `renamed` ； `beforePresent` /`afterPresent` 区分字段缺失与有值。字段旁注与断言在 `tests/headless/service.test.mjs` ，静态样例不代表真实服务已执行。
`.gitignore` 排除依赖、Next/headless 产物、环境变量、增量缓存和系统文件；仅放行 `.env.example` 作为模板。根 `/docs/` 当前作为本地研究目录忽略。忽略规则只影响未跟踪文件，不会把已经跟踪的文件自动移出 Git。`.env.example` 的公开项目标识与服务端源站说明写在模板内；实际凭据不应写进示例或公开构建变量。
