mini-three-adapter 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (73) hide show
  1. package/AGENTS.md +85 -0
  2. package/LICENSE +21 -0
  3. package/README.md +158 -2
  4. package/dist/build/rollup.d.ts +8 -0
  5. package/dist/build/rollup.js +393 -0
  6. package/dist/build/rollup.js.map +1 -0
  7. package/dist/build/vite.d.ts +15 -0
  8. package/dist/build/vite.js +395 -0
  9. package/dist/build/vite.js.map +1 -0
  10. package/dist/chunk-34RWHAW4.js +128 -0
  11. package/dist/chunk-34RWHAW4.js.map +1 -0
  12. package/dist/chunk-3UGQWFH3.js +1246 -0
  13. package/dist/chunk-3UGQWFH3.js.map +1 -0
  14. package/dist/chunk-4UEBRAK6.js +711 -0
  15. package/dist/chunk-4UEBRAK6.js.map +1 -0
  16. package/dist/chunk-LB3WL24R.js +91 -0
  17. package/dist/chunk-LB3WL24R.js.map +1 -0
  18. package/dist/chunk-MTBMOFAL.js +132 -0
  19. package/dist/chunk-MTBMOFAL.js.map +1 -0
  20. package/dist/chunk-QYQQ5J6E.js +3 -0
  21. package/dist/chunk-QYQQ5J6E.js.map +1 -0
  22. package/dist/chunk-V6TY7KAL.js +7 -0
  23. package/dist/chunk-V6TY7KAL.js.map +1 -0
  24. package/dist/chunk-WLRQDTSZ.js +145 -0
  25. package/dist/chunk-WLRQDTSZ.js.map +1 -0
  26. package/dist/chunk-Z7AMDRN3.js +66 -0
  27. package/dist/chunk-Z7AMDRN3.js.map +1 -0
  28. package/dist/core/index.d.ts +101 -0
  29. package/dist/core/index.js +7 -0
  30. package/dist/core/index.js.map +1 -0
  31. package/dist/index.d.ts +8 -0
  32. package/dist/index.js +11 -0
  33. package/dist/index.js.map +1 -0
  34. package/dist/platforms/browser.d.ts +23 -0
  35. package/dist/platforms/browser.js +7 -0
  36. package/dist/platforms/browser.js.map +1 -0
  37. package/dist/platforms/wechat-game.d.ts +31 -0
  38. package/dist/platforms/wechat-game.js +8 -0
  39. package/dist/platforms/wechat-game.js.map +1 -0
  40. package/dist/platforms/wechat-miniprogram.d.ts +26 -0
  41. package/dist/platforms/wechat-miniprogram.js +8 -0
  42. package/dist/platforms/wechat-miniprogram.js.map +1 -0
  43. package/dist/plugin-core-BuqW9C-L.d.ts +127 -0
  44. package/dist/polyfills/index.d.ts +291 -0
  45. package/dist/polyfills/index.js +4 -0
  46. package/dist/polyfills/index.js.map +1 -0
  47. package/dist/runtime-7uUOoFhC.d.ts +263 -0
  48. package/dist/scope.d.ts +146 -0
  49. package/dist/scope.js +4 -0
  50. package/dist/scope.js.map +1 -0
  51. package/dist/types-BzK0LQMa.d.ts +153 -0
  52. package/dist/wx-types-NMNyrsWO.d.ts +150 -0
  53. package/docs/01-design-principles.md +105 -0
  54. package/docs/02-architecture.md +126 -0
  55. package/docs/03-module-map.md +99 -0
  56. package/docs/04-api-reference.md +291 -0
  57. package/docs/05-build-plugin.md +146 -0
  58. package/docs/06-platform-notes.md +108 -0
  59. package/docs/07-integration-guide.md +211 -0
  60. package/docs/08-extension-guide.md +101 -0
  61. package/docs/09-testing-and-release.md +206 -0
  62. package/docs/10-ai-playbook.md +140 -0
  63. package/docs/11-compat-matrix.md +94 -0
  64. package/docs/README.md +41 -0
  65. package/docs/adr/0001-scoped-globals.md +41 -0
  66. package/docs/adr/0002-unified-runtime-lifecycle.md +40 -0
  67. package/docs/adr/0003-ast-rewrite.md +51 -0
  68. package/docs/adr/0004-in-place-patching.md +42 -0
  69. package/docs/adr/0005-webgl2-only.md +44 -0
  70. package/docs/adr/0006-zero-three-dependency.md +43 -0
  71. package/docs/adr/README.md +28 -0
  72. package/llms.txt +65 -0
  73. package/package.json +117 -4
@@ -0,0 +1,126 @@
1
+ # 02 · 架构设计
2
+
3
+ ## 2.1 两阶段模型
4
+
5
+ 适配层被刻意拆成**构建期**与**运行期**两个互不依赖的部分。运行期不需要 Node、不需要构建工具;构建期不接触 `wx`。
6
+
7
+ ```mermaid
8
+ flowchart LR
9
+ subgraph BUILD["构建期 (Node)"]
10
+ A["three / addons / three-stdlib 源码"] --> B["@babel/parser + scope"]
11
+ B --> C["MagicString: window → __m3().window"]
12
+ A --> D["资产扫描: *.wasm / *worker*.js"]
13
+ D --> E["collectAssets + emitFile"]
14
+ C --> F["bundle"]
15
+ E --> F
16
+ E --> G["mini-three-assets.json<br/>game.json 建议"]
17
+ end
18
+ subgraph RUN["运行期 (小游戏 JS 引擎)"]
19
+ H["PlatformBinding<br/>canvas/metrics/image/touch/raf"] --> I["createRuntime()"]
20
+ I --> J["patchCanvas (in-place)"]
21
+ I --> K["MiniThreeScope"]
22
+ I --> L["PointerBridge"]
23
+ I --> M["FrameScheduler"]
24
+ I --> N["WindowInfoStore"]
25
+ J & K & L & M & N --> O["MiniThreeRuntime"]
26
+ end
27
+ F --> RUN
28
+ C -.->|"__m3 = getActiveScope()"| K
29
+ ```
30
+
31
+ ## 2.2 分层与依赖方向
32
+
33
+ ```
34
+ src/types.ts 纯类型,零依赖
35
+ src/scope.ts 作用域协议(依赖 types)
36
+ src/polyfills/* 自包含 W3C 迷你实现(依赖 types / 彼此)
37
+ src/core/* 平台无关运行时(依赖 polyfills / scope / types)
38
+ src/platforms/* 平台适配(依赖 core / wx-types)
39
+ src/build/* 构建插件(Node,只依赖 scope-rewrite / assets,不依赖 core)
40
+ src/index.ts 汇总导出
41
+ ```
42
+
43
+ 依赖规则(由 CI 与 `AGENTS.md` 共同约束):
44
+
45
+ - `core/*` **不得** import `platforms/*`;
46
+ - `build/*` **不得** import `core/*` 或 `platforms/*`;
47
+ - `polyfills/*` **不得** import `core/*`;
48
+ - `src/**` **不得** import `three`(`three` 只是可选 peer);
49
+ - 任何文件都不得直接写 `globalThis.window = ...`,只有 `installGlobals()` 可以,且必须返回还原函数。
50
+
51
+ ## 2.3 运行期数据流
52
+
53
+ ### 初始化
54
+
55
+ 1. `createWeChatGameRuntime(options)` → `createWeChatGameBinding()`。
56
+ 2. `getScreenCanvas(wx)` 按 `options.canvas` → `GameGlobal.screencanvas` → `globalThis.canvas` → `wx.createCanvas()` 的顺序取**唯一**上屏画布,并做模块级缓存。
57
+ 3. `detectCapabilities()` 只用 `wx.createOffscreenCanvas()` 探测 WebGL2,**绝不调用 `wx.createCanvas()`**。
58
+ 4. `createDocument()` 建出 `document` / `body` / `screen` 等容器;`createElement('canvas')` 走 `webgl2` 离屏画布,失败降级 `2d` 并告警。
59
+ 5. `patchCanvas()` 在原对象上定义 `style` / `clientWidth` / `getBoundingClientRect` / `getContext` / EventTarget 方法,并注册到 `HTMLCanvasElementShim` 的 `WeakSet`。
60
+ 6. 组装 `MiniThreeScope`(polyfill 构造器 + 领域对象 + live getter),`setActiveScope(scope)` 让 `__m3()` 生效。
61
+ 7. `PointerBridge` 订阅 `wx.onTouch*`;`WindowInfoStore` 订阅 `wx.onWindowResize`;`FrameScheduler` 包住 rAF。
62
+ 8. 返回可 `dispose()` 的 `MiniThreeRuntime`。
63
+
64
+ ### 一帧内发生的事
65
+
66
+ ```mermaid
67
+ sequenceDiagram
68
+ participant WX as wx runtime
69
+ participant B as PlatformBinding
70
+ participant PB as PointerBridge
71
+ participant F as FrameScheduler
72
+ participant T as three.js
73
+
74
+ WX->>B: onTouchStart(touchEvent)
75
+ B->>PB: dispatch(touchEvent)
76
+ PB->>PB: normalize coords (rect.left/top)
77
+ PB->>T: pointerdown → canvas / document / window
78
+ WX->>F: rAF callback
79
+ F->>T: setAnimationLoop tick (delta, fps)
80
+ T->>B: canvas.getContext('webgl2') (cached)
81
+ T->>WX: gl.draw*
82
+ WX->>B: onWindowResize
83
+ B->>F: windowInfo.refresh()
84
+ B->>T: runtime.emit('resize')
85
+ ```
86
+
87
+ ## 2.4 关键抽象
88
+
89
+ | 抽象 | 文件 | 契约要点 |
90
+ | --- | --- | --- |
91
+ | `PlatformBinding` | `core/platform.ts` | 平台向运行时提供的一切:`rawCanvas`、`capabilities`、`imageFactory`、`getCanvasRect`、`createOffscreenCanvas`、`watchTouch`、`watchVisibility`、rAF、`now`、`dispose` |
92
+ | `MiniThreeScope` | `scope.ts` | 三方代码可见的「伪 window」;`window === self === globalThis === scope` |
93
+ | `MiniThreeRuntime` | `core/runtime.ts` | 唯一生命周期对象;只读能力 + `handleTouch` / `resize` / `installGlobals` / `on` / `dispose` |
94
+ | `PointerBridge` | `core/pointer.ts` | touch → pointer/mouse 状态机,pointerId、capture、cancel |
95
+ | `FrameScheduler` | `core/frames.ts` | rAF 包装、delta、fpsCap、FPS 测量 |
96
+ | `WindowInfoStore` | `core/window-info.ts` | 尺寸/DPR、封顶、resize 广播 |
97
+ | `Diagnostics` | `core/diagnostics.ts` | 分级日志、`warnOnce`、`capabilityReport` |
98
+
99
+ ## 2.5 架构不变量(AI 必读,不得破坏)
100
+
101
+ 1. **只有一个上屏画布**:`wx.createCanvas()` 只在 `getScreenCanvas()` 中调用一次并被缓存;任何新增代码不得再调用它。
102
+ 2. **对象身份不变**:canvas / image 永远是 `wx` 返回的那个对象;禁止 `new Proxy` 包装、禁止 `Object.setPrototypeOf`、禁止返回克隆体。
103
+ 3. **默认零全局污染**:只有 `installGlobals()` 会写 `globalThis`,且必须可逆;`getActiveScope()` 是三方代码访问 shim 的唯一通道。
104
+ 4. **`three` 零运行时依赖**:`src/` 不 import `three`,`package.json` 中它只是 optional peer。
105
+ 5. **平台无关核心**:`core/` 不认识 `wx`;平台差异全部收敛到 `platforms/` 的 `PlatformBinding`。
106
+ 6. **构建/运行隔离**:`build/` 只在 Node 执行,不引用运行时模块,不引入 `fs` 到小游戏 bundle。
107
+ 7. **单一生命周期**:所有订阅、定时器、全局注入都登记到 `disposers`,`dispose()` 后不留副作用。
108
+ 8. **WebGL2 优先**:`document.createElement('canvas')` 默认 `webgl2`;无 WebGL2 时必须发出明确告警。
109
+ 9. **改写只针对自由变量**:AST 重写必须通过 `path.scope.hasBinding(name, true)` 判定,禁止全局字符串替换。
110
+ 10. **破坏性行为必须显式**:全局注入、WebGPU 重写、深度缓冲补丁等一律 opt-in。
111
+
112
+ ## 2.6 失败模式与降级
113
+
114
+ | 情况 | 行为 |
115
+ | --- | --- |
116
+ | 没有 `wx`(Node/浏览器) | `createWeChatGameRuntime({ wx })` 可注入;`browser` 平台用真实 DOM |
117
+ | `createOffscreenCanvas` 不可用 | 能力探测返回 false;`createCanvas()` 抛明确错误;文档提示升级基础库 |
118
+ | WebGL2 不可用 | `diagnostics.warn` + 能力报告;不静默降级到 WebGL1(three ≥ r163 也无法工作) |
119
+ | `wx.createImage` 缺失 | 回退 `OffscreenCanvas.createImage()`,再失败抛可操作错误 |
120
+ | `typeof window` 在 runtime 之前被读取 | `emptyScope` 让 `typeof` 返回 `'object'`,真正取属性时抛带指引的错误 |
121
+ | AST 解析失败 | 插件记录 `parseFailures`、告警并跳过该模块,绝不产出半改写代码 |
122
+ | 找不到 wasm/worker | 记录 `missingAssets` 并告警,不中断构建 |
123
+
124
+ ## 2.7 与 H5 双端的关系
125
+
126
+ `browser` 平台用真实 `document.createElement('canvas')`,同样走 `patchCanvas`(幂等地补充属性)。因为 shim 全部在 `MiniThreeScope` 里,**真实 `window` / `document` 从未被覆盖**,所以同一份 `scene.ts` 能在浏览器与小游戏里同时运行。这也是 H5 双端构建可以复用同一套业务代码的基础。
@@ -0,0 +1,99 @@
1
+ # 03 · 模块地图(AI 修改入口索引)
2
+
3
+ > **给 AI 用**:动手前先在这张表里定位目标文件;「改这里」列给出常见需求的最小改动面,「会影响」列给出必须同步检查的下游。
4
+ > 依赖层级:`types → scope / polyfills → core → platforms`;`build` 是独立分支。
5
+
6
+ ## 3.1 根与协议层
7
+
8
+ | 文件 | 职责 | 关键导出 | 改这里 | 会影响 |
9
+ | --- | --- | --- | --- | --- |
10
+ | `src/types.ts` | 全部公开类型,纯 type-only | `Rect`、`WindowInfo`、`Capabilities`、`PatchedCanvas`、`TouchLikeEvent`、`FrameScheduler`、`RuntimeEvents` 等 | 新增平台能力字段、事件名称 | `core/*`、`platforms/*`、`dist/*.d.ts`、`docs/04` |
11
+ | `src/scope.ts` | 作用域协议:`MiniThreeScope`、活动作用域单例、显式全局注入 | `createScope`、`getActiveScope`、`setActiveScope`、`hasActiveScope`、`installGlobals` | 新增三方代码可能访问的浏览器全局 | **构建插件注入的 import**、[ADR-0001](./adr/0001-scoped-globals.md)、`docs/04` |
12
+ | `src/index.ts` | 汇总导出 | 全部公开 API | 新增公共入口 | `package.json` `exports`、`docs/04` |
13
+ | `src/core/index.ts` | core 子路径导出 | core API | 同上 | `docs/04` |
14
+ | `src/polyfills/index.ts` | polyfills 子路径导出 | polyfill API | 同上 | `docs/04` |
15
+
16
+ ## 3.2 polyfills(自包含,无平台知识)
17
+
18
+ | 文件 | 职责 | 关键导出 | 改这里 | 会影响 / 测试 |
19
+ | --- | --- | --- | --- | --- |
20
+ | `src/polyfills/event.ts` | W3C 事件系统 | `MiniEvent`、`MiniPointerEvent`、`MiniMouseEvent`、`MiniEventTarget`、`patchEventTarget`、`MiniDOMException` | 事件字段缺失(如 controls 读 `movementX`)、`onxxx` 内联处理器 | `pointer.ts`、`dom.ts`;`tests/polyfills.test.ts` |
21
+ | `src/polyfills/blob-url.ts` | Blob / URL / base64 / URL 相对解析 | `MiniBlob`、`MiniURL`、`bytesToBase64`、`resolveUrl` | `createObjectURL` 的目标格式、URL 解析边界 | `image.ts` 的 `src` 解析;`tests/polyfills.test.ts` |
22
+ | `src/polyfills/text-encoding.ts` | `atob`/`btoa`/`TextEncoder`/`TextDecoder` | 同名 | 编码边界、BOM、utf-16 | `network.ts`、`blob-url.ts`;`tests/polyfills.test.ts` |
23
+ | `src/polyfills/network.ts` | `fetch`、`XMLHttpRequest`、`AbortController` | `createFetch`、`createXMLHttpRequestFactory`、`MiniAbortController` | `wx.request` 返回结构差异、进度事件 | `runtime.ts` 的 scope 组装;`tests/polyfills.test.ts` |
24
+
25
+ > 约束:polyfills 不得 import `core/*`,不得读取 `globalThis.wx`。
26
+
27
+ ## 3.3 core(平台无关运行时)
28
+
29
+ | 文件 | 职责 | 关键导出 | 改这里 | 会影响 / 测试 |
30
+ | --- | --- | --- | --- | --- |
31
+ | `src/core/platform.ts` | **平台契约**(结构化接口,替代抽象基类) | `PlatformBinding`、`PlatformFactory` | 平台要新增能力时**先改这里** | 所有 `platforms/*`、`runtime.ts` |
32
+ | `src/core/runtime.ts` | **总装配**:画布补丁、scope 组装、订阅、生命周期 | `createRuntime`、`MiniThreeRuntime`、`RuntimeOptions`、`RendererHints` | 新增 runtime API、新增/移除全局项、调整启动顺序 | 几乎所有模块;`tests/runtime.test.ts` |
33
+ | `src/core/element.ts` | 就地 DOM 属性补丁 + `Symbol.hasInstance` 注册表 | `patchElement`、`createMockClass`、`*Shim`、`normalizeRect` | three 报「DOM 属性缺失」、`instanceof` 失败 | `canvas.ts`、`image.ts`、`dom.ts` |
34
+ | `src/core/canvas.ts` | canvas 补丁:getContext 缓存、WebGL 归一化、离屏画布 | `patchCanvas`、`createOffscreenCanvas` | 上下文丢失、扩展返回值异常、`canvas.canvas` 指向 | `dom.ts`、`runtime.ts`;`tests/runtime.test.ts` |
35
+ | `src/core/image.ts` | Image / ImageData 工厂,blob URL → data URL | `createImageFactory`、`ShimImageData` | 图片加载、crossOrigin、decode | `platforms/*`、`dom.ts` |
36
+ | `src/core/dom.ts` | `document` / `body` / `screen` / `DOMRect` / `OffscreenCanvas` 构造器 | `createDocument`、`createScreen`、`ShimDOMRect`、`createOffscreenCanvasCtor` | `document.createElement` 新标签、`visibilityState` | `runtime.ts` |
37
+ | `src/core/pointer.ts` | **touch → pointer/mouse 状态机** | `PointerBridge` | 多指、capture、`tap` 无 touches、坐标换算 | `runtime.ts`、`examples/*`;`tests/runtime.test.ts` |
38
+ | `src/core/frames.ts` | rAF 包装、delta、fpsCap、FPS 测量 | `createFrameScheduler` | 帧率限制、慢帧告警 | `runtime.ts` |
39
+ | `src/core/window-info.ts` | 窗口信息 + DPR 封顶 + resize 广播 | `createWindowInfoStore`、`readWindowInfo` | 新 API 替代 `getWindowInfo`、安全区 | `runtime.ts`;`tests/runtime.test.ts` |
40
+ | `src/core/capabilities.ts` | 能力探测(不消费上屏画布) | `detectCapabilities`、`versionAtLeast` | 新增探测项、基础库版本判断 | 所有 `platforms/*`、`runtime.report()` |
41
+ | `src/core/diagnostics.ts` | 分级日志、`warnOnce`、能力报告 | `createDiagnostics`、`capabilityReport` | 日志格式、报告字段 | 全局;`tests/runtime.test.ts` |
42
+
43
+ > 约束:`core/*` 不得 import `platforms/*`,不得 import `three`,不得直接写 `globalThis`。
44
+
45
+ ## 3.4 platforms(平台差异收敛点)
46
+
47
+ | 文件 | 职责 | 关键导出 | 改这里 | 会影响 |
48
+ | --- | --- | --- | --- | --- |
49
+ | `src/platforms/wx-types.ts` | 手写最小 `wx` 结构化类型(不依赖官方 typings) | `WxLike`、`WxCanvas`、`WxTouchEvent`、`resolveWx` | 用到新的 `wx.*` API 时补类型 | 所有平台;`docs/04` |
50
+ | `src/platforms/wechat-common.ts` | rAF / now / touch / visibility / 离屏画布 / 能力探测共用实现 | `watchWxTouch`、`createRafPair`、`probeContext` 等 | 微信 API 变更 | `wechat-game.ts`、`wechat-miniprogram.ts` |
51
+ | `src/platforms/wechat-game.ts` | 小游戏绑定 + 入口 | `createWeChatGameRuntime`、`createWeChatGameBinding`、`getScreenCanvas` | **上屏画布获取顺序**、锁帧 | `examples/wechat-minigame` |
52
+ | `src/platforms/wechat-miniprogram.ts` | 小程序绑定(`createSelectorQuery`) | `createWeChatMiniProgramRuntime` | 选择器查询、组件作用域 `selectorCtx` | `examples/wechat-miniprogram` |
53
+ | `src/platforms/browser.ts` | 浏览器 / Node 测试平台 | `createBrowserRuntime`、`createBrowserBinding` | H5 双端能力 | `examples/h5` |
54
+
55
+ ## 3.5 build(Node 侧,不进小游戏 bundle)
56
+
57
+ | 文件 | 职责 | 关键导出 | 改这里 | 会影响 / 测试 |
58
+ | --- | --- | --- | --- | --- |
59
+ | `src/build/scope-rewrite.ts` | **AST 全局重写**,`@babel/parser` + `path.scope.hasBinding` | `rewriteGlobals`、`DEFAULT_GLOBAL_NAMES`、`DEFAULT_FORCE_UNDEF` | 需要改写的全局清单、访问器名、注入的 import | 所有三方模块;`tests/scope-rewrite.test.ts`、[ADR-0003](./adr/0003-ast-rewrite.md) |
60
+ | `src/build/assets.ts` | worker/wasm 引用扫描、解析、拷贝、manifest | `collectAssetReferences`、`collectAssets`、`copyAssets`、`AssetManifest` | 新 decoder 类型、输出目录、`game.json` 建议 | `plugin-core.ts`;`tests/plugin.test.ts` |
61
+ | `src/build/plugin-core.ts` | Rollup/Vite 兼容插件核心 | `miniThreePlugin`、`BuildReport` | include 规则、WebGPU 策略、构建报告 | `vite.ts`、`rollup.ts`;`tests/plugin.test.ts` |
62
+ | `src/build/vite.ts` | Vite 入口 + `optimizeDeps.exclude` 配置 | `miniThree`(default) | Vite 版本兼容 | `examples/*/vite.config.ts` |
63
+ | `src/build/rollup.ts` | Rollup 入口 + 高级 API 再导出 | `miniThree`、`rewriteGlobals` 等 | Rollup 集成 | `docs/05` |
64
+
65
+ > 约束:`build/*` 不得 import `core/*` / `platforms/*`;`node:fs` 只允许出现在这里。
66
+
67
+ ## 3.6 配置与示例
68
+
69
+ | 文件 | 作用 |
70
+ | --- | --- |
71
+ | `package.json` | `exports` 子路径、`sideEffects`、peer(`three`/`vite`/`rollup` 均 optional) |
72
+ | `tsconfig.json` | strict + `noUncheckedIndexedAccess` + `verbatimModuleSyntax`;`include` 覆盖 `src/tests/config` |
73
+ | `tsup.config.ts` | 两套构建:runtime(es2019 / neutral / dts / splitting)与 build tooling(node18 / 无 splitting) |
74
+ | `vitest.config.ts` | 单 fork 执行(规避 Windows 临时目录权限),`cache: false` |
75
+ | `tests/helpers/mock-wx.ts` | 可注入的 wx 模拟器;`__setSize` 触发 resize,`__touch` 触发触摸 |
76
+ | `examples/wechat-minigame/` | 小游戏完整工程(vite + game.json + project.config.json + postbuild) |
77
+ | `examples/wechat-miniprogram/` | 小程序页面(WXML 事件转发) |
78
+ | `examples/h5/` | H5 双端 |
79
+
80
+ ## 3.7 常见任务 → 文件清单(AI 速查)
81
+
82
+ | 需求 | 最小改动面 |
83
+ | --- | --- |
84
+ | three 报 `xxx is not defined` | `src/build/scope-rewrite.ts` 的 `DEFAULT_GLOBAL_NAMES` → `src/scope.ts` 的 `MiniThreeScope` → `src/core/runtime.ts` 组装 |
85
+ | 新 three 版本用了新的 DOM 属性 | `src/core/element.ts` `patchElement`(+ canvas 的 `extra`)→ 补 `tests/runtime.test.ts` |
86
+ | 触摸在小程序里不生效 | `src/core/pointer.ts`(`tap`/无 touches)→ `examples/wechat-miniprogram/pages/index/index.ts` 转发 |
87
+ | 新增一个平台(如抖音小游戏) | 新建 `src/platforms/xxx.ts` 实现 `PlatformBinding` → `src/index.ts` 导出 → `package.json` exports → `docs/08` |
88
+ | 新增 decoder 资源 | `src/build/assets.ts` 的 `DECODER_KEYWORDS` / `defaultRoots` → `examples/*/vite.config.ts` 的 `roots` |
89
+ | WebGPU 相关代码报错 | `src/build/plugin-core.ts` `webgpu` 策略 → `docs/06` |
90
+ | resize 后画面变形 | `src/core/window-info.ts`、`src/core/runtime.ts` 的 `resize()`、`docs/06` |
91
+ | 包体过大 | `docs/06`(分包 / Brotli / manualChunks)+ `src/build/assets.ts` |
92
+ | 发布新版本 | `docs/09-testing-and-release.md` + `CHANGELOG.md` + `package.json` |
93
+
94
+ ## 3.8 修改后必做
95
+
96
+ 1. `npm run check`(typecheck + 32 例单测 + tsup 构建)。
97
+ 2. 更新本表(若职责变化)、`docs/04-api-reference.md`(若导出变化)、`CHANGELOG.md`。
98
+ 3. 若触及架构不变量,新增或修订 `docs/adr/*.md`。
99
+ 4. 若新增了平台能力,更新 `docs/11-compat-matrix.md`。
@@ -0,0 +1,291 @@
1
+ # 04 · API 参考
2
+
3
+ > 版本:0.1.0。所有签名以 `src/**` 与 `npm run build` 生成的 `dist/*.d.ts` 为准。
4
+ > 子路径导入可最大化 tree-shaking;`mini-three-adapter` 是汇总入口。
5
+
6
+ ## 4.1 子路径
7
+
8
+ | 子路径 | 内容 |
9
+ | --- | --- |
10
+ | `mini-three-adapter` | 全部公开 API |
11
+ | `mini-three-adapter/core` | 平台无关运行时 |
12
+ | `mini-three-adapter/scope` | `getActiveScope()` 等(**构建插件注入的 import 目标**) |
13
+ | `mini-three-adapter/wechat-game` | 小游戏入口 |
14
+ | `mini-three-adapter/wechat-miniprogram` | 小程序入口 |
15
+ | `mini-three-adapter/browser` | 浏览器 / H5 / Node 测试 |
16
+ | `mini-three-adapter/polyfills` | 独立 polyfill |
17
+ | `mini-three-adapter/vite` | Vite 插件 |
18
+ | `mini-three-adapter/rollup` | Rollup 插件 + 高级 API |
19
+ | `mini-three-adapter/plugin` | `vite` 的别名 |
20
+ | `mini-three-adapter/package.json` | 读取包元信息(`version`、`exports`) |
21
+
22
+ ---
23
+
24
+ ## 4.2 生命周期
25
+
26
+ ### `createRuntime(platform, options?) => Promise<MiniThreeRuntime>`
27
+
28
+ 平台无关的总装配入口。通常不直接调用,而用下面的平台快捷函数。
29
+
30
+ ```ts
31
+ function createRuntime(
32
+ platform: PlatformBinding | PlatformFactory,
33
+ options?: RuntimeOptions,
34
+ ): Promise<MiniThreeRuntime>;
35
+ ```
36
+
37
+ ### `createWeChatGameRuntime(options?) => Promise<MiniThreeRuntime>`
38
+
39
+ ```ts
40
+ interface WeChatGameOptions {
41
+ wx?: WxLike; // 注入 wx(测试/非微信宿主)
42
+ canvas?: WxCanvas; // 复用已有上屏画布
43
+ capabilities?: Partial<Capabilities>;
44
+ diagnostics?: Diagnostics;
45
+ preferredFps?: number; // wx.setPreferredFramesPerSecond
46
+ }
47
+ type WeChatGameRuntimeOptions = WeChatGameOptions & RuntimeOptions;
48
+ ```
49
+
50
+ 另有 `createWeChatGameBinding(options) => PlatformBinding`(同步)、`getScreenCanvas(wx, supplied?)`、`resetScreenCanvasCache()`(测试用)。
51
+
52
+ ### `createWeChatMiniProgramRuntime(options) => Promise<MiniThreeRuntime>`
53
+
54
+ ```ts
55
+ interface WeChatMiniProgramOptions {
56
+ wx?: WxLike;
57
+ selector: string; // 例如 '#gl'
58
+ selectorCtx?: SelectorCtx; // 自定义组件内传 this
59
+ queryDelay?: number; // 等待布局的毫秒数
60
+ capabilities?: Partial<Capabilities>;
61
+ diagnostics?: Diagnostics;
62
+ }
63
+ ```
64
+
65
+ 另有 `createWeChatMiniProgramBinding(options) => Promise<PlatformBinding>`。
66
+
67
+ ### `createBrowserRuntime(options?) => Promise<MiniThreeRuntime>`
68
+
69
+ ```ts
70
+ interface BrowserPlatformOptions {
71
+ canvas?: HTMLCanvasElement;
72
+ capabilities?: Partial<Capabilities>;
73
+ diagnostics?: Diagnostics;
74
+ }
75
+ ```
76
+
77
+ ---
78
+
79
+ ### `RuntimeOptions`
80
+
81
+ | 选项 | 类型 | 默认 | 说明 |
82
+ | --- | --- | --- | --- |
83
+ | `pixelRatioCap` | `number` | `2` | 限制 DPR,`0` 表示不封顶 |
84
+ | `propagatePointerEvents` | `boolean` | `true` | 是否同时派发到 `document` / `window` |
85
+ | `emitMouseEvents` | `boolean` | `true` | 是否额外发 `mouse*` / `click` |
86
+ | `defaultContextType` | `'webgl2' \| 'webgl' \| '2d'` | `'webgl2'` | `document.createElement('canvas')` 的默认上下文 |
87
+ | `cacheContexts` | `boolean` | `true` | 缓存 `getContext()` 结果,保证上下文身份稳定 |
88
+ | `normalizeWebGL` | `boolean` | `true` | 修正 `getExtension` 返回值、`drawingBufferWidth/Height` |
89
+ | `fpsCap` | `number` | `0` | 逻辑帧率上限 |
90
+ | `slowFrameThreshold` | `number` | `0` | 慢帧告警阈值(ms) |
91
+ | `logLevel` | `'silent' \| 'error' \| 'warn' \| 'info' \| 'debug'` | `'warn'` | 日志级别 |
92
+ | `reporter` | `Reporter` | console | 自定义日志出口 |
93
+ | `capabilities` | `Partial<Capabilities>` | — | 覆盖探测结果 |
94
+ | `installGlobals` | `boolean` | `false` | 启动时立即注入全局(可逆) |
95
+ | `diagnostics` | `Diagnostics` | — | 平台层注入(平台 options) |
96
+
97
+ ### `MiniThreeRuntime`
98
+
99
+ | 成员 | 类型 | 说明 |
100
+ | --- | --- | --- |
101
+ | `canvas` | `HTMLCanvasElement` | 已就地补丁的上屏/节点画布 |
102
+ | `scope` | `MiniThreeScope` | 三方代码可见的作用域对象 |
103
+ | `document` | `DocumentLike` | `createElement` / `createElementNS` / `body` / `defaultView` |
104
+ | `capabilities` | `Capabilities` | 探测结果 |
105
+ | `diagnostics` | `Diagnostics` | 日志与报告 |
106
+ | `frames` | `FrameScheduler` | rAF / delta / fps |
107
+ | `bridge` | `PointerBridge` | 事件桥 |
108
+ | `windowInfo` | `WindowInfo` | 实时尺寸与 DPR(getter) |
109
+ | `rendererHints` | `RendererHints` | 可直接展开给 `new THREE.WebGLRenderer()` |
110
+ | `disposed` | `boolean` | 是否已释放 |
111
+ | `handleTouch(event, opts?)` | `(TouchLikeEvent, {propagate?, computeRect?}) => void` | 手动转发触摸(小程序必需) |
112
+ | `resize()` | `() => Promise<void>` | 重新测量并广播 resize |
113
+ | `installGlobals(opts?)` | `() => Disposer` | 显式全局注入并返回还原函数 |
114
+ | `createCanvas(w?, h?, type?)` | `() => HTMLCanvasElement` | 额外的离屏画布 |
115
+ | `on(event, listener)` | `() => Disposer` | 见下表 |
116
+ | `report()` | `() => string` | 能力报告文本 |
117
+ | `dispose()` | `() => void` | 释放全部副作用 |
118
+
119
+ `RuntimeEvents`:
120
+
121
+ | 事件 | 回调 |
122
+ | --- | --- |
123
+ | `resize` | `(info: WindowInfo) => void` |
124
+ | `visibilitychange` | `(visible: boolean) => void` |
125
+ | `contextlost` | `() => void` |
126
+ | `dispose` | `() => void` |
127
+ | `error` | `(error: Error) => void` |
128
+
129
+ `RendererHints`:`{ canvas, antialias: false, alpha: false, powerPreference: 'high-performance', preserveDrawingBuffer: false, outputColorSpace: 'srgb' }`。
130
+
131
+ ---
132
+
133
+ ## 4.3 作用域
134
+
135
+ ```ts
136
+ function createScope(overrides?: Partial<MiniThreeScope>): MiniThreeScope;
137
+ function getActiveScope(): MiniThreeScope; // 未初始化时返回「可 typeof、取值即抛错」的占位
138
+ function setActiveScope(scope: MiniThreeScope | null): () => void;
139
+ function hasActiveScope(): boolean;
140
+ function installGlobals(scope, options?): () => void;
141
+ ```
142
+
143
+ `MiniThreeScope` 同时扮演 `window` / `self` / `globalThis`(三者指向自身),并包含:
144
+
145
+ - 领域对象:`document`、`navigator`、`screen`、`performance`、`getComputedStyle`、`matchMedia`;
146
+ - 尺寸:`innerWidth`、`innerHeight`、`outerWidth`、`outerHeight`、`devicePixelRatio`、`pageXOffset`、`pageYOffset`(均为 live getter);
147
+ - 事件:`Event`、`EventTarget`、`CustomEvent`、`PointerEvent`、`MouseEvent`、`TouchEvent`、`MessageEvent`、`ProgressEvent`、`KeyboardEvent`、`DOMException`;
148
+ - DOM:`HTMLElement`、`HTMLCanvasElement`、`HTMLImageElement`、`OffscreenCanvas`、`Image`、`ImageData`、`DOMRect`、`WebGLRenderingContext`、`WebGL2RenderingContext`、`AudioContext`;
149
+ - 网络/编码:`Blob`、`URL`、`TextEncoder`、`TextDecoder`、`fetch`、`XMLHttpRequest`、`AbortController`、`AbortSignal`、`atob`、`btoa`;
150
+ - 帧:`requestAnimationFrame`、`cancelAnimationFrame`;
151
+ - 明确不可用:`createImageBitmap`、`FileReader`、`WebSocket` 为 `undefined`(让 three 走降级分支)。
152
+
153
+ `installGlobals(scope, { target?, skipExisting?, extraKeys? })` 把上述键定义为 `globalThis` 上的 getter;返回的 disposer 会精确还原原有 descriptor。
154
+
155
+ ---
156
+
157
+ ## 4.4 core 子路径
158
+
159
+ | API | 签名 / 说明 |
160
+ | --- | --- |
161
+ | `patchElement(instance, options)` | 就地补 DOM 属性,返回 `{ element, updateRect, disposers }` |
162
+ | `createMockClass(name)` | 生成带 `Symbol.hasInstance` + `WeakSet` 的构造器 shim |
163
+ | `markAs(ctor, obj)` / `isMarked(ctor, obj)` | 注册 / 查询 instanceof 关系 |
164
+ | `*Shim` | `HTMLCanvasElementShim`、`HTMLImageElementShim`、`HTMLElementShim`、`OffscreenCanvasShim`、`ImageDataShim`、`WebGLRenderingContextShim`、`WebGL2RenderingContextShim`、`DOMRectShim` |
165
+ | `patchCanvas(raw, options)` | 返回 `{ canvas, contexts, updateRect, element, disposers }` |
166
+ | `createOffscreenCanvas(wx, w?, h?, options?)` | 直接创建并补丁离屏画布 |
167
+ | `createImageFactory(wx, diagnostics?)` | `{ Image, HTMLImageElement, ImageData, createImage, createImageData, createImageBitmap: undefined }` |
168
+ | `createDocument(options)` / `createScreen(w, h)` / `ShimDOMRect` | 伪 DOM 容器 |
169
+ | `PointerBridge` | `dispatch(event, opts?)`、`dispatchMouse(event)`、`setRect`、`refreshRect`、`setPointerCapture`、`releasePointerCapture`、`activePointerCount`、`dispose` |
170
+ | `createFrameScheduler(raf, caf, options)` | `request` / `cancel` / `loop(cb)` / `setFpsCap` / `fps` / `dispose` |
171
+ | `createWindowInfoStore(wx, options)` | `info` / `refresh()` / `onChange()` / `setPixelRatioCap()` / `dispose()` |
172
+ | `detectCapabilities(wx, platform, options)` / `versionAtLeast(a, b)` | 能力探测 |
173
+ | `createDiagnostics(level, reporter)` / `capabilityReport(caps)` | 日志与报告 |
174
+ | `currentScope()` | 返回当前作用域或 `null` |
175
+
176
+ ### `PlatformBinding`(新增平台时实现)
177
+
178
+ ```ts
179
+ interface PlatformBinding {
180
+ readonly kind: 'wechat-game' | 'wechat-miniprogram' | 'browser' | 'unknown';
181
+ readonly wx?: WxLike;
182
+ readonly rawCanvas: WxCanvas;
183
+ readonly capabilities: Capabilities;
184
+ readonly imageFactory: ImageFactory;
185
+ getCanvasRect(): Rect | Promise<Rect>;
186
+ createOffscreenCanvas(w: number, h: number, type: ContextType): WxCanvas;
187
+ watchTouch(handler: (e: TouchLikeEvent) => void): Disposer;
188
+ watchVisibility(handler: (visible: boolean) => void): Disposer;
189
+ requestAnimationFrame(cb: (time: number) => void): number;
190
+ cancelAnimationFrame(id: number): void;
191
+ now(): number;
192
+ dispose(): void;
193
+ }
194
+ ```
195
+
196
+ ---
197
+
198
+ ## 4.5 polyfills 子路径
199
+
200
+ | API | 说明 |
201
+ | --- | --- |
202
+ | `MiniEvent` / `MiniCustomEvent` / `MiniPointerEvent` / `MiniMouseEvent` / `MiniMessageEvent` / `MiniProgressEvent` / `MiniDOMException` | 事件对象 |
203
+ | `MiniEventTarget` / `patchEventTarget(obj)` | 事件目标;`patchEventTarget` 不改变对象身份 |
204
+ | `MiniBlob` | `bytes()`、`arrayBuffer()`、`text()`、`slice()`、`dataURL()`、`size`、`type` |
205
+ | `MiniURL` | `createObjectURL` / `revokeObjectURL` / `resolveObjectURL` / `clearObjectURLs`;构造器支持相对路径解析 |
206
+ | `MiniURLSearchParams` | `get` / `set` / `toString` |
207
+ | `bytesToBase64` / `base64ToBytes` / `resolveUrl` | 编码与 URL 工具 |
208
+ | `atob` / `btoa` / `MiniTextEncoder` / `MiniTextDecoder` | 编码 |
209
+ | `createFetch(wx)` / `MiniXMLHttpRequest` / `createXMLHttpRequestFactory(wx)` / `MiniAbortController` / `MiniAbortSignal` | 网络 |
210
+
211
+ > 注意:对象 URL 采用 `mini-three-blob:` 前缀并解析为 `data:` URI,而不是浏览器 `blob:` ——因为微信 image loader 只认 `data:` / 本地路径。
212
+
213
+ ---
214
+
215
+ ## 4.6 构建插件
216
+
217
+ ### Vite
218
+
219
+ ```ts
220
+ import miniThree from 'mini-three-adapter/vite';
221
+ plugins: [miniThree(options)];
222
+ ```
223
+
224
+ 插件额外提供 `config()`,设置 `optimizeDeps.exclude: ['three', 'three-stdlib', 'three/examples/jsm']`,确保 AST 重写见到原始 ESM 模块图。
225
+
226
+ ### Rollup
227
+
228
+ ```ts
229
+ import { miniThree } from 'mini-three-adapter/rollup';
230
+ plugins: [miniThree(options)];
231
+ ```
232
+
233
+ ### `MiniThreePluginOptions`
234
+
235
+ | 选项 | 类型 | 默认 | 说明 |
236
+ | --- | --- | --- | --- |
237
+ | `include` | `(id: string) => boolean` | 匹配 `three` / `three-stdlib` / `@react-three` / `@tresjs` / `.vite/deps/three*` | 需要重写的模块 |
238
+ | `exclude` | `(id: string) => boolean` | `() => false` | 排除 |
239
+ | `includeUserCode` | `boolean` | `false` | 是否也改写应用代码 |
240
+ | `rewrite` | `RewriteOptions` | — | 高级重写配置 |
241
+ | `webgpu` | `'warn' \| 'error' \| 'rewrite' \| 'ignore'` | `'warn'` | 遇到 `three/webgpu` 的策略 |
242
+ | `roots` | `string[]` | three jsm/libs、`three-stdlib`、`public`、`static` | 资源搜索目录 |
243
+ | `outputDir` | `string` | `'assets/three'` | 资源输出目录 |
244
+ | `brotli` | `boolean` | `true` | 同时拷贝 `.wasm.br` |
245
+ | `manifest` | `boolean` | `true` | 输出 `mini-three-assets.json` |
246
+ | `cwd` | `string` | `process.cwd()` | 解析 roots 的根目录 |
247
+ | `report` | `boolean` | `true` | 打印构建摘要 |
248
+ | `debug` | `boolean` | `false` | 逐模块日志 |
249
+
250
+ ### `RewriteOptions`
251
+
252
+ | 选项 | 默认 | 说明 |
253
+ | --- | --- | --- |
254
+ | `globals` | `DEFAULT_GLOBAL_NAMES` | 替换默认清单(而非追加) |
255
+ | `extraGlobals` | `[]` | 追加清单 |
256
+ | `forceUndef` | `['createImageBitmap']` | 强制走 `__m3().x`(作用域中恒为 `undefined`) |
257
+ | `accessor` | `'__m3'` | 注入的 `getActiveScope` 别名 |
258
+ | `scopeModule` | `'mini-three-adapter/scope'` | 注入的 import 路径 |
259
+
260
+ ### 高级导出(`mini-three-adapter/rollup`)
261
+
262
+ `rewriteGlobals(code, id, options)`、`DEFAULT_GLOBAL_NAMES`、`DEFAULT_FORCE_UNDEF`、`collectAssetReferences`、`collectAssets`、`copyAssets`、`miniThreePlugin`。
263
+
264
+ `plugin.api.report()` → `BuildReport`:`modulesScanned`、`modulesRewritten`、`rewrites`、`globalsSeen`、`assetReferences`、`missingAssets`、`webgpuWarnings`、`parseFailures`。
265
+
266
+ ---
267
+
268
+ ## 4.7 类型速查
269
+
270
+ ```ts
271
+ interface Capabilities {
272
+ platform: 'wechat-game' | 'wechat-miniprogram' | 'browser' | 'unknown';
273
+ webgl2: boolean; webgl1: boolean; offscreenCanvas: boolean;
274
+ worker: boolean; wasm: boolean; brotliWasm: boolean; nativeImage: boolean;
275
+ triggerGC: boolean; getWindowInfo: boolean; windowResizeEvent: boolean;
276
+ baseLibraryVersion: string;
277
+ }
278
+
279
+ interface WindowInfo {
280
+ width: number; height: number; pixelRatio: number; rawPixelRatio: number;
281
+ safeArea?: Rect;
282
+ }
283
+
284
+ interface Rect { top: number; left: number; width: number; height: number; right: number; bottom: number; }
285
+
286
+ interface TouchLikeEvent {
287
+ type: string; touches?: ArrayLike<TouchPoint>;
288
+ changedTouches?: ArrayLike<TouchPoint>; timeStamp?: number;
289
+ [key: string]: unknown;
290
+ }
291
+ ```