# 开发与验证

## 开发

```bash
node --test "tests/*.test.js"     # 主入口（Node 原生测试运行器）
node scripts/run-tests.mjs        # 沙箱兜底：同进程顺序 import，不派生子进程
node tests/codegen.test.js        # 单个文件也能直接跑
```

> 两种 runner 都留着：`node --test` 会为每个测试文件派生子进程，
> 在受限文件沙箱下这个 spawn 会被拒（EPERM），兜底 runner 改成同进程顺序 import。
> 对应 `pnpm test` 与 `pnpm test:sandbox`。

| 测试文件 | 用例 | 验什么 |
|---|---|---|
| `codegen.test.js` | 21 | 生成器正确性、类型转换、**连接规则与生成器一致性**、错误码 |
| `workspace.test.js` | 10 | 路径安全、项目/材质/快照/纹理全流程 |
| `http.test.js` | 14 | action 分发、错误码、同源、纹理字节、模块送发 |
| `plugin-load.test.js` | 10 | 假 Cordis context 下 `apply()` 的注册形状 + 工具真执行 |
| `module-graph.test.js` | 6 | 面板模块可解析 + 导出契约 + `__ModuleLoader__` 载荷 |
| `glsl-compile.test.js` | 4 | 真 WebGL2 编译 50 个节点的 GLSL |
| `panel-smoke.test.js` | 2 | **真浏览器**：面板整块挂起来、打开材质、编译、渲染 |
| `render-gpu.test.js` | 1 | **真浏览器 + 读像素**：iChannel0-3 / 多 Pass 反馈 / iMouse |
| `editor-interaction.test.js` | 1 | **真浏览器 + 真鼠标**：拖节点、连端口、重复连接替换 |
| `perf-1080p.test.js` | 1 | **真浏览器**：1080p 帧率、GPU 单帧耗时、隐藏时空转 |

共用夹具在 `tests/helpers/browser.mjs`。

最有价值的四个测试：

1. **真机 GLSL 编译**（`glsl-compile`）——抓到过 6 个只有编译器才能发现的 bug
   （缺 `#version`、uniform 带初始化器、重载返回类型不一致、常量类型不符、表达式不递归展开……）。
2. **GPU 像素回读**（`render-gpu`）——编译通过 ≠ 画得对。
   读回像素验证纹理真的绑上了、兜底路径走了、Buffer 反馈拿的是上一帧、
   iMouse 位置与公式精确吻合。
3. **真鼠标拖拽**（`editor-interaction`）——抓到过一个**致命 bug**：
   `_onPointerUp` 先把 `this.drag` 清空、`_canDrop()` 又去读它，
   结果**手动连线从来没成功过**（编译过、单测过、模板看不出来）。
4. **1080p 性能**（`perf-1080p`）——用 `EXT_disjoint_timer_query_webgl2` 拿
   **GPU 侧真实耗时**，而不是量 CPU 的 draw 调用（后者只有 0.03ms，说明不了问题）。

后三个在受限沙箱下会**自动跳过**而不是假失败。

### 实测性能（无头 Edge + SwiftShader 软件渲染，1920×1080）

| 场景 | rAF 帧率 | CPU `render()` p95 | GPU 单帧 p95 |
|---|---|---|---|
| 简单图（uv→渐变→调色板） | 139.7 FPS | 0.10 ms | **0.07 ms** |
| 重负载（fbm 4 层 + BufferA 多 Pass） | 143.9 FPS | 0.10 ms | **0.86 ms** |

60 FPS 的预算是 16.7 ms/帧，即软件渲染下也有约 20 倍余量。真机有独显只会更快。
页面隐藏时 1 秒内渲染次数 = **0**。

详细文档见 [`docs/接口契约.md`](接口契约.md) 与 [`docs/架构说明.md`](架构说明.md)。

---

---

## 体积

| 部分 | 源码 | gzip |
|---|---|---|
| 核心 runtime（`client/runtime/` + `shared/`） | 94.8 KB | **32.0 KB** |
| 编辑器（`client/panel/`，按需加载） | 122.7 KB | — |
| Host 侧 | 65.5 KB | — |

第三方运行时依赖：**0**。

---

---

## 本版没做的

| 需求 | 状态 |
|---|---|
| FR-01 分组 / 注释 / 撤销重做 | 未做（增删连线复制删除、真鼠标拖拽都已验证） |
| FR-05 ComfyUI 集成（M4） | 未实现，接口已预留 |
| FR-06 HLSL / MSL / SPIR-V 跨编译（M5） | 未实现，只导出 GLSL + JSON |
| FR-10 Shadertoy 代码导入 / ZIP 导出 | 未做（材质文件导入已有） |
| 材质导出的 DDS 直读 | 只按普通图片绑槽位，不做 mipmap/ASTC 转码 |