mini-three-adapter 0.1.3 → 0.1.5
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.
- package/AGENTS.md +85 -85
- package/README.md +159 -159
- package/dist/build/rollup.js.map +1 -1
- package/dist/build/vite.js.map +1 -1
- package/dist/{chunk-34RWHAW4.js → chunk-35XVAVDB.js} +23 -5
- package/dist/chunk-35XVAVDB.js.map +1 -0
- package/dist/{chunk-52IMRKOX.js → chunk-F7CSLEUI.js} +3 -3
- package/dist/{chunk-52IMRKOX.js.map → chunk-F7CSLEUI.js.map} +1 -1
- package/dist/{chunk-WZ2HKYC5.js → chunk-LE4FRYNG.js} +4 -4
- package/dist/{chunk-WZ2HKYC5.js.map → chunk-LE4FRYNG.js.map} +1 -1
- package/dist/{chunk-OL7NVZZJ.js → chunk-VA7SZFLN.js} +21 -12
- package/dist/chunk-VA7SZFLN.js.map +1 -0
- package/dist/{chunk-3QUEDYTT.js → chunk-ZB3AYNOS.js} +19 -11
- package/dist/chunk-ZB3AYNOS.js.map +1 -0
- package/dist/{chunk-J7VBWZRR.js → chunk-ZFJLEEF4.js} +188 -45
- package/dist/chunk-ZFJLEEF4.js.map +1 -0
- package/dist/core/index.d.ts +3 -3
- package/dist/core/index.js +2 -2
- package/dist/index.d.ts +3 -3
- package/dist/index.js +6 -6
- package/dist/platforms/browser.d.ts +2 -2
- package/dist/platforms/browser.js +3 -3
- package/dist/platforms/wechat-game.d.ts +2 -2
- package/dist/platforms/wechat-game.js +4 -4
- package/dist/platforms/wechat-miniprogram.d.ts +2 -2
- package/dist/platforms/wechat-miniprogram.js +4 -4
- package/dist/polyfills/index.d.ts +1 -1
- package/dist/{runtime-DnEkKZjo.d.ts → runtime-BrHExTjl.d.ts} +1 -1
- package/dist/scope.d.ts +8 -1
- package/dist/scope.js +1 -1
- package/dist/{wx-types-NMNyrsWO.d.ts → wx-types-BZTQ2jWG.d.ts} +17 -0
- package/docs/02-architecture.md +4 -4
- package/docs/03-module-map.md +99 -99
- package/docs/04-api-reference.md +304 -294
- package/docs/05-build-plugin.md +4 -2
- package/docs/06-platform-notes.md +44 -6
- package/docs/07-integration-guide.md +2 -2
- package/docs/09-testing-and-release.md +210 -209
- package/docs/10-ai-playbook.md +2 -1
- package/docs/11-compat-matrix.md +100 -96
- package/docs/adr/0007-capability-probe-fallback.md +8 -4
- package/docs/adr/0008-probe-fallback-boundary.md +56 -0
- package/docs/adr/0009-placeholder-scope-environment-globals.md +69 -0
- package/docs/adr/README.md +3 -1
- package/llms.txt +5 -2
- package/package.json +1 -1
- package/dist/chunk-34RWHAW4.js.map +0 -1
- package/dist/chunk-3QUEDYTT.js.map +0 -1
- package/dist/chunk-J7VBWZRR.js.map +0 -1
- package/dist/chunk-OL7NVZZJ.js.map +0 -1
package/docs/11-compat-matrix.md
CHANGED
|
@@ -1,96 +1,100 @@
|
|
|
1
|
-
# 11 · 兼容矩阵
|
|
2
|
-
|
|
3
|
-
> 状态说明:✅ 已验证 / 🟡 理论支持或单元测试覆盖,待真机 / ⚠️ 有限制 / ❌ 不支持。
|
|
4
|
-
> 每次发布前更新;真机验收清单见 [`docs/09`](./09-testing-and-release.md#97-真机验收清单发布前)。
|
|
5
|
-
|
|
6
|
-
## 11.1 three.js 版本
|
|
7
|
-
|
|
8
|
-
| three 版本 | 状态 | 说明 |
|
|
9
|
-
| --- | --- | --- |
|
|
10
|
-
| `>= 0.163.0`(r163+) | ✅ 目标区间 | r163 起 `WebGLRenderer` 要求 WebGL2,与本适配层默认一致 |
|
|
11
|
-
| `0.187.0` | 🟡 单元级 | 2026-11-08 npm 最新版;已按 Migration Guide 检查 `three/addons`、`outputColorSpace`、`setAnimationLoop`;待真机全量回归 |
|
|
12
|
-
| `0.151.0 ~ 0.162.x` | ⚠️ | 未针对 WebGL1 路径做专门适配,建议升级到 r163+ |
|
|
13
|
-
| `< 0.151.0` | ❌ | 不提供保证 |
|
|
14
|
-
| `three/webgpu` + TSL / NodeMaterial | ❌ | 小游戏无 WebGPU;插件默认告警,可选 `webgpu:'rewrite'` 仅适用于纯 WebGLRenderer 的简单场景 |
|
|
15
|
-
|
|
16
|
-
### 每次 three 升级需要复核的点
|
|
17
|
-
|
|
18
|
-
1. `DEFAULT_GLOBAL_NAMES`(`src/build/scope-rewrite.ts`)是否覆盖新增浏览器全局。
|
|
19
|
-
2. `patchElement` / `patchCanvas`(`src/core/element.ts`、`canvas.ts`)是否覆盖新增 DOM 属性。
|
|
20
|
-
3. import 路径:`three/addons/*` 与旧 `three/examples/jsm/*` 都要在插件 include 规则里。
|
|
21
|
-
4. `RGBELoader → HDRLoader`、`EffectComposer → PostProcessing` 等破坏性改名(r180+)。
|
|
22
|
-
5. `three/webgpu` 使用比例上升时,插件 `webgpu` 默认策略是否需要调整。
|
|
23
|
-
6. 用 `examples/` 的三个平台工程对 controls / loaders / postprocessing 类别做增量回归。
|
|
24
|
-
|
|
25
|
-
## 11.2 微信基础库 / 平台
|
|
26
|
-
|
|
27
|
-
| 能力 | 最低基础库 | 状态 | 依据 / 处理 |
|
|
28
|
-
| --- | --- | --- | --- |
|
|
29
|
-
| `wx.createCanvas` / `getContext('webgl2')` | — | ✅ | [渲染文档](https://developers.weixin.qq.com/minigame/dev/guide/base-ability/render.html) |
|
|
30
|
-
| 唯一上屏画布规则 | — | ✅ | `getScreenCanvas()` 单次缓存 |
|
|
31
|
-
| `wx.createOffscreenCanvas` | 2.7.0(小程序)/ 小游戏同期 | ✅ |
|
|
32
|
-
| WebGL2 能力判定 | — | ✅ | 顺序:离屏实测 → 主画布实测 → 按基础库版本推断;`capabilities.webgl2Source` 标明来源,`'inferred'` 表示未实测 |
|
|
33
|
-
| 回退探测与上屏画布的身份冲突 | — | ✅ | `probeContext` 接收 `
|
|
34
|
-
| `wx.getWindowInfo` | 较新版本 | ✅ | 回退 `getSystemInfoSync` |
|
|
35
|
-
| `wx.onWindowResize` | — | 🟡 | 不可用时告警,需手动 `runtime.resize()` |
|
|
36
|
-
| `WXWebAssembly` | 2.13.0(Worker 内 2.15.0) | 🟡 | [官方文档](https://developers.weixin.qq.com/minigame/dev/guide/performance/perf-webassembly.html);插件按引用拷贝 wasm |
|
|
37
|
-
| `.wasm.br` Brotli | — | 🟡 | `assets.brotli: true` |
|
|
38
|
-
| Worker(分包) | 2.0.10 | 🟡 | 需 `wx.preDownloadSubpackage({packageType:'workers'})`;并发上限 1 |
|
|
39
|
-
| 分包加载 | 2.1.0 | 🟡 | `game.json` 建议由 manifest 生成 |
|
|
40
|
-
| iOS 高性能 / 高性能+ | 需后台开通 | 🟡 | `game.json` 的 `iOSHighPerformance` / `iOSHighPerformance+`;官方建议 WebGL2 场景开启高性能+ |
|
|
41
|
-
| `wx.triggerGC` | — | ✅ | 影响 image 创建路径判定 |
|
|
42
|
-
|
|
43
|
-
## 11.3 平台支持
|
|
44
|
-
|
|
45
|
-
| 平台 | 入口 | 状态 | 备注 |
|
|
46
|
-
| --- | --- | --- | --- |
|
|
47
|
-
| 微信小游戏 | `mini-three-adapter/wechat-game` | ✅ 单元级 | 自动订阅 `wx.onTouch*`;完整示例 |
|
|
48
|
-
| 微信小程序(`<canvas type="webgl2">`) | `mini-three-adapter/wechat-miniprogram` | 🟡 | 需 WXML 转发 `bindtouch*`;`selectorCtx` 传组件实例 |
|
|
49
|
-
| 浏览器 / H5 双端 | `mini-three-adapter/browser` | ✅ 单元级 | 真实 DOM 不被覆盖;可跑 Node 测试 |
|
|
50
|
-
| 其他小程序 / 小游戏平台 | 自定义 `PlatformBinding` | 🟡 框架就绪 | 按 [`docs/08`](./08-extension-guide.md#81-新增一个平台) 实现 |
|
|
51
|
-
| WebView 套壳 | 不在范围内 | ❌ | 本方案用于非 WebView 原生渲染 |
|
|
52
|
-
|
|
53
|
-
## 11.4 Web / DOM API 覆盖
|
|
54
|
-
|
|
55
|
-
| API | 提供方式 | 状态 |
|
|
56
|
-
| --- | --- | --- |
|
|
57
|
-
| `window` / `self` / `globalThis`(作用域内) | `MiniThreeScope` 自引用 | ✅ |
|
|
58
|
-
| `document.createElement('canvas' \| 'img')` | `createDocument` | ✅ |
|
|
59
|
-
| `document.createElementNS` / `body` / `visibilityState` | `createDocument` | ✅ |
|
|
60
|
-
| `HTMLCanvasElement` / `HTMLImageElement` / `HTMLElement` / `OffscreenCanvas` / `ImageData` / `DOMRect` 的 `instanceof` | `Symbol.hasInstance` 注册表 | ✅ |
|
|
61
|
-
| `Event` / `EventTarget` / `CustomEvent` / `PointerEvent` / `MouseEvent` / `MessageEvent` / `ProgressEvent` | `polyfills/event.ts` | ✅ |
|
|
62
|
-
| `Blob` / `URL.createObjectURL` / `URL.revokeObjectURL` | `mini-three-blob:` → `data:` | ✅ |
|
|
63
|
-
| `URL` 构造 / 相对路径解析 | `MiniURL` | ✅ |
|
|
64
|
-
| `TextEncoder` / `TextDecoder` / `atob` / `btoa` | `polyfills/text-encoding.ts` | ✅ |
|
|
65
|
-
| `fetch` / `XMLHttpRequest` / `AbortController` | `wx.request` 桥接 | 🟡 单元级,真机网络待验证 |
|
|
66
|
-
| `requestAnimationFrame` / `cancelAnimationFrame` | `FrameScheduler` | ✅ |
|
|
67
|
-
| `performance.now` | `wx.getPerformance` → `Date.now` 回退 | ✅ |
|
|
68
|
-
| `getComputedStyle` / `matchMedia` / `screen` / `navigator` | 轻量模拟 | ⚠️ 仅够 three 使用,非完整实现 |
|
|
69
|
-
| `createImageBitmap` | **故意为 `undefined`** | ✅ 让 three 走降级分支 |
|
|
70
|
-
| `
|
|
71
|
-
|
|
|
72
|
-
| `
|
|
73
|
-
|
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
|
82
|
-
|
|
|
83
|
-
| `
|
|
84
|
-
| `
|
|
85
|
-
|
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
1
|
+
# 11 · 兼容矩阵
|
|
2
|
+
|
|
3
|
+
> 状态说明:✅ 已验证 / 🟡 理论支持或单元测试覆盖,待真机 / ⚠️ 有限制 / ❌ 不支持。
|
|
4
|
+
> 每次发布前更新;真机验收清单见 [`docs/09`](./09-testing-and-release.md#97-真机验收清单发布前)。
|
|
5
|
+
|
|
6
|
+
## 11.1 three.js 版本
|
|
7
|
+
|
|
8
|
+
| three 版本 | 状态 | 说明 |
|
|
9
|
+
| --- | --- | --- |
|
|
10
|
+
| `>= 0.163.0`(r163+) | ✅ 目标区间 | r163 起 `WebGLRenderer` 要求 WebGL2,与本适配层默认一致 |
|
|
11
|
+
| `0.187.0` | 🟡 单元级 | 2026-11-08 npm 最新版;已按 Migration Guide 检查 `three/addons`、`outputColorSpace`、`setAnimationLoop`;待真机全量回归 |
|
|
12
|
+
| `0.151.0 ~ 0.162.x` | ⚠️ | 未针对 WebGL1 路径做专门适配,建议升级到 r163+ |
|
|
13
|
+
| `< 0.151.0` | ❌ | 不提供保证 |
|
|
14
|
+
| `three/webgpu` + TSL / NodeMaterial | ❌ | 小游戏无 WebGPU;插件默认告警,可选 `webgpu:'rewrite'` 仅适用于纯 WebGLRenderer 的简单场景 |
|
|
15
|
+
|
|
16
|
+
### 每次 three 升级需要复核的点
|
|
17
|
+
|
|
18
|
+
1. `DEFAULT_GLOBAL_NAMES`(`src/build/scope-rewrite.ts`)是否覆盖新增浏览器全局。
|
|
19
|
+
2. `patchElement` / `patchCanvas`(`src/core/element.ts`、`canvas.ts`)是否覆盖新增 DOM 属性。
|
|
20
|
+
3. import 路径:`three/addons/*` 与旧 `three/examples/jsm/*` 都要在插件 include 规则里。
|
|
21
|
+
4. `RGBELoader → HDRLoader`、`EffectComposer → PostProcessing` 等破坏性改名(r180+)。
|
|
22
|
+
5. `three/webgpu` 使用比例上升时,插件 `webgpu` 默认策略是否需要调整。
|
|
23
|
+
6. 用 `examples/` 的三个平台工程对 controls / loaders / postprocessing 类别做增量回归。
|
|
24
|
+
|
|
25
|
+
## 11.2 微信基础库 / 平台
|
|
26
|
+
|
|
27
|
+
| 能力 | 最低基础库 | 状态 | 依据 / 处理 |
|
|
28
|
+
| --- | --- | --- | --- |
|
|
29
|
+
| `wx.createCanvas` / `getContext('webgl2')` | — | ✅ | [渲染文档](https://developers.weixin.qq.com/minigame/dev/guide/base-ability/render.html) |
|
|
30
|
+
| 唯一上屏画布规则 | — | ✅ | `getScreenCanvas()` 单次缓存 |
|
|
31
|
+
| `wx.createOffscreenCanvas` | 2.7.0(小程序)/ 小游戏同期 | ✅ | 离屏画布首选来源;**API 完全不存在时不做回退**,退回版本推断([ADR-0008](./adr/0008-probe-fallback-boundary.md)) |
|
|
32
|
+
| WebGL2 能力判定 | — | ✅ | 顺序:离屏实测 → 主画布实测 → 按基础库版本推断;`capabilities.webgl2Source` 标明来源,`'inferred'` 表示未实测 |
|
|
33
|
+
| 回退探测与上屏画布的身份冲突 | — | ✅ | `probeContext` 接收 `reservedCanvases`(本次画布 + 缓存画布 + `GameGlobal.screencanvas` + `globalThis.canvas`),`createCanvas()` 返回其中任一对象即放弃、不 `getContext`(含宿主显式传 `canvas` 的窄口子) |
|
|
34
|
+
| `wx.getWindowInfo` | 较新版本 | ✅ | 回退 `getSystemInfoSync` |
|
|
35
|
+
| `wx.onWindowResize` | — | 🟡 | 不可用时告警,需手动 `runtime.resize()` |
|
|
36
|
+
| `WXWebAssembly` | 2.13.0(Worker 内 2.15.0) | 🟡 | [官方文档](https://developers.weixin.qq.com/minigame/dev/guide/performance/perf-webassembly.html);插件按引用拷贝 wasm |
|
|
37
|
+
| `.wasm.br` Brotli | — | 🟡 | `assets.brotli: true` |
|
|
38
|
+
| Worker(分包) | 2.0.10 | 🟡 | 需 `wx.preDownloadSubpackage({packageType:'workers'})`;并发上限 1 |
|
|
39
|
+
| 分包加载 | 2.1.0 | 🟡 | `game.json` 建议由 manifest 生成 |
|
|
40
|
+
| iOS 高性能 / 高性能+ | 需后台开通 | 🟡 | `game.json` 的 `iOSHighPerformance` / `iOSHighPerformance+`;官方建议 WebGL2 场景开启高性能+ |
|
|
41
|
+
| `wx.triggerGC` | — | ✅ | 影响 image 创建路径判定 |
|
|
42
|
+
|
|
43
|
+
## 11.3 平台支持
|
|
44
|
+
|
|
45
|
+
| 平台 | 入口 | 状态 | 备注 |
|
|
46
|
+
| --- | --- | --- | --- |
|
|
47
|
+
| 微信小游戏 | `mini-three-adapter/wechat-game` | ✅ 单元级 | 自动订阅 `wx.onTouch*`;完整示例 |
|
|
48
|
+
| 微信小程序(`<canvas type="webgl2">`) | `mini-three-adapter/wechat-miniprogram` | 🟡 | 需 WXML 转发 `bindtouch*`;`selectorCtx` 传组件实例 |
|
|
49
|
+
| 浏览器 / H5 双端 | `mini-three-adapter/browser` | ✅ 单元级 | 真实 DOM 不被覆盖;可跑 Node 测试 |
|
|
50
|
+
| 其他小程序 / 小游戏平台 | 自定义 `PlatformBinding` | 🟡 框架就绪 | 按 [`docs/08`](./08-extension-guide.md#81-新增一个平台) 实现 |
|
|
51
|
+
| WebView 套壳 | 不在范围内 | ❌ | 本方案用于非 WebView 原生渲染 |
|
|
52
|
+
|
|
53
|
+
## 11.4 Web / DOM API 覆盖
|
|
54
|
+
|
|
55
|
+
| API | 提供方式 | 状态 |
|
|
56
|
+
| --- | --- | --- |
|
|
57
|
+
| `window` / `self` / `globalThis`(作用域内) | `MiniThreeScope` 自引用 | ✅ |
|
|
58
|
+
| `document.createElement('canvas' \| 'img')` | `createDocument` | ✅ |
|
|
59
|
+
| `document.createElementNS` / `body` / `visibilityState` | `createDocument` | ✅ |
|
|
60
|
+
| `HTMLCanvasElement` / `HTMLImageElement` / `HTMLElement` / `OffscreenCanvas` / `ImageData` / `DOMRect` 的 `instanceof` | `Symbol.hasInstance` 注册表 | ✅ |
|
|
61
|
+
| `Event` / `EventTarget` / `CustomEvent` / `PointerEvent` / `MouseEvent` / `MessageEvent` / `ProgressEvent` | `polyfills/event.ts` | ✅ |
|
|
62
|
+
| `Blob` / `URL.createObjectURL` / `URL.revokeObjectURL` | `mini-three-blob:` → `data:` | ✅ |
|
|
63
|
+
| `URL` 构造 / 相对路径解析 | `MiniURL` | ✅ |
|
|
64
|
+
| `TextEncoder` / `TextDecoder` / `atob` / `btoa` | `polyfills/text-encoding.ts` | ✅ |
|
|
65
|
+
| `fetch` / `XMLHttpRequest` / `AbortController` | `wx.request` 桥接 | 🟡 单元级,真机网络待验证 |
|
|
66
|
+
| `requestAnimationFrame` / `cancelAnimationFrame` | `FrameScheduler` | ✅ |
|
|
67
|
+
| `performance.now` | `wx.getPerformance` → `Date.now` 回退 | ✅ |
|
|
68
|
+
| `getComputedStyle` / `matchMedia` / `screen` / `navigator` | 轻量模拟 | ⚠️ 仅够 three 使用,非完整实现 |
|
|
69
|
+
| `createImageBitmap` | **故意为 `undefined`** | ✅ 让 three 走降级分支 |
|
|
70
|
+
| 图片原生事件(`img.onload` / `addEventListener('load')` / `decode()`) | 三级桥接:原生 `addEventListener` → `onload` 赋值 → `wx.getImageInfo` 诊断 | 🟡 模拟器与单元测试通过;真机宿主形态差异大,见 `docs/06` §6.3 |
|
|
71
|
+
| 纹理格式 | PNG / JPEG | ✅ WebP 在部分真机解码失败,见 §11.6 |
|
|
72
|
+
| `FileReader` / `WebSocket` / `AudioContext` | 缺省或透传 | ⚠️ 业务需要时按 `docs/08` 扩展 |
|
|
73
|
+
| `Worker` / `WebAssembly` | 透传宿主全局(`WXWebAssembly`) | 🟡 |
|
|
74
|
+
| `ResizeObserver` | no-op | ⚠️ |
|
|
75
|
+
| 完整 DOM(布局、CSS、事件冒泡树) | 不提供 | ❌ 超出范围 |
|
|
76
|
+
|
|
77
|
+
## 11.5 场景回归记录
|
|
78
|
+
|
|
79
|
+
以 three 官方示例场景为主体建立回归集,用 `examples/` 的三个平台工程逐一接入验证。
|
|
80
|
+
|
|
81
|
+
| 类别 | 覆盖目标 | 状态 | 备注 |
|
|
82
|
+
| --- | --- | --- | --- |
|
|
83
|
+
| `controls_*` | OrbitControls / TrackballControls / TransformControls 的多指交互 | ⬜ 未回归 | 优先验证 pointerId、capture、`pointercancel` |
|
|
84
|
+
| `loader_*` | GLTF / DRACO / KTX2 / OBJ / FBX | ⬜ 未回归 | 需配置 decoder 路径与分包 |
|
|
85
|
+
| `postprocessing_*` | EffectComposer / bloom / SSAO | ⬜ 未回归 | 注意深度缓冲与 render target 尺寸 |
|
|
86
|
+
| `animation_*` / `physics_*` | 骨骼动画 / wasm 物理 | ⬜ 未回归 | 涉及 wasm 资源预下载 |
|
|
87
|
+
| 基础渲染 | `examples/wechat-minigame`、`wechat-miniprogram`、`h5` | ✅ 单元级 | 79 个 Vitest 用例覆盖画布、事件、作用域、插件 |
|
|
88
|
+
|
|
89
|
+
每回归一条,在本表追加:`场景 id | three 版本 | 基础库 | 设备 | 结果 | 失败原因 | 新增 polyfill`。
|
|
90
|
+
|
|
91
|
+
## 11.6 已知限制汇总
|
|
92
|
+
|
|
93
|
+
1. 不模拟 WebGPU;`three/webgpu` 项目需改用 WebGL 构建目标。
|
|
94
|
+
2. `createImageBitmap` 恒为 `undefined`,依赖该 API 的库需自带降级。
|
|
95
|
+
3. 不提供完整 DOM;DOM 密集型 UI 库应走 WebView 方案。
|
|
96
|
+
4. 插件默认只改写 `node_modules` 中的三方生态代码;应用代码里直接写 `window` 不会自动改写(可开 `includeUserCode`)。
|
|
97
|
+
5. 对象 URL 是 `mini-three-blob:` + `data:`,不是浏览器 `blob:`;若有库硬编码 `blob:` 前缀判断,需要适配。
|
|
98
|
+
6. Worker 分包、`.wasm.br`、iOS 高性能+ 需业务按 `mini-three-assets.json` 的 `gameJsonSuggestion` 自行配置,插件不直接改 `game.json`。
|
|
99
|
+
7. 纹理请使用 PNG / JPEG。**WebP 在部分真机上无法解码**(`wx.createImage` 直接触发 `error`),这与适配层无关;`mini-three-adapter` 只会在 `wx.getImageInfo` 失败时给出指向格式的告警。
|
|
100
|
+
8. 图片事件桥接需要宿主提供至少一个入口(原生 `addEventListener`、可写的 `onload`/`onerror`,或 `wx.getImageInfo`)。三者都不存在的宿主只能快速失败:2s 内派发 `error`,无法出图。
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# ADR-0007 · 能力探测允许「主画布回退」与「无法探测」语义
|
|
2
2
|
|
|
3
|
-
- 状态:Accepted
|
|
3
|
+
- 状态:Accepted,其中「回退触发条件」与「身份比对基准」两条被 [ADR-0008](./0008-probe-fallback-boundary.md) 收紧
|
|
4
4
|
- 日期:2026-11-10
|
|
5
5
|
- 影响模块:`src/core/capabilities.ts`、`src/platforms/wechat-common.ts`、`src/platforms/wechat-game.ts`、`src/platforms/wechat-miniprogram.ts`、`src/types.ts`
|
|
6
6
|
|
|
@@ -18,8 +18,8 @@
|
|
|
18
18
|
1. `probeContext` 返回 `boolean | undefined`:
|
|
19
19
|
- `true` / `false` 表示**实测结果**;
|
|
20
20
|
- `undefined` 表示**无法探测**。
|
|
21
|
-
2. 探测顺序:离屏实测 →
|
|
22
|
-
3.
|
|
21
|
+
2. 探测顺序:离屏实测 → (仅当离屏 API 存在、上屏画布已解析且调用方显式允许时)第二次 `wx.createCanvas()` 实测 → 仍无法判定则返回 `undefined`。
|
|
22
|
+
3. 回退带**身份守卫**:调用方把候选上屏画布集合传给 `probeContext`(`reservedCanvases`),若 `createCanvas()` 返回的正是其中任一对象,立即返回 `undefined`,既不 `getContext` 也不 `WEBGL_lose_context`。
|
|
23
23
|
4. `detectCapabilities` 把 `undefined` 当作未知,退回基础库版本启发式(`>= 2.20.0`),并用新增的 `capabilities.webgl2Source`(`'probe' | 'inferred' | 'override'`)标明来源;此时 `warnOnce` 提示一次。
|
|
24
24
|
|
|
25
25
|
## 理由
|
|
@@ -53,5 +53,9 @@
|
|
|
53
53
|
|
|
54
54
|
## 验证方式
|
|
55
55
|
|
|
56
|
-
- `tests/capabilities.test.ts`:离屏优先且不碰 `createCanvas
|
|
56
|
+
- `tests/capabilities.test.ts`:离屏优先且不碰 `createCanvas`、离屏答不出时回退、离屏返回 false 而主画布返回 true、完全无法探测时返回 `undefined`、回退拿到上屏画布时按身份放弃(`getContext` 零调用)、`webgl2Source` 三种取值,以及 `GameGlobal.screencanvas` 预置时 `createWeChatGameBinding` 不触碰屏画布。
|
|
57
57
|
- `tests/runtime.test.ts`:小游戏运行时能力报告仍包含 `wechat-game` 与 `WebGL2`。
|
|
58
|
+
|
|
59
|
+
## 修订记录
|
|
60
|
+
|
|
61
|
+
- 2026-11-10(0.1.4):[ADR-0008](./0008-probe-fallback-boundary.md) 把第 2 条收窄为「无 `createOffscreenCanvas` 时完全不回退」,把第 3 条的身份基准从单个 `screenCanvas` 扩为候选全集 `reservedCanvases`。原因是宿主显式传 `canvas` 时,「本次使用的画布」与「设备的上屏画布」不是同一个对象,比对会落空。
|
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
# ADR-0008 · 能力探测兜底的边界:无离屏 API 不兜底,身份基准取候选全集
|
|
2
|
+
|
|
3
|
+
- 状态:Accepted(收紧 [ADR-0007](./0007-capability-probe-fallback.md) 的两条判据)
|
|
4
|
+
- 日期:2026-11-10
|
|
5
|
+
- 影响模块:`src/platforms/wechat-common.ts`、`src/platforms/wechat-game.ts`
|
|
6
|
+
|
|
7
|
+
## 背景
|
|
8
|
+
|
|
9
|
+
[ADR-0007](./0007-capability-probe-fallback.md) 允许在离屏探测答不出时回退到第二次 `wx.createCanvas()`,并用「上屏画布引用 + 身份比对」挡住最危险的一种返回。上线后复核发现两道口子:
|
|
10
|
+
|
|
11
|
+
1. **缺 `createOffscreenCanvas` 时仍然兜底。** 这条路径拿到的是「第几次 `createCanvas()`」的猜测:宿主若预置了 `GameGlobal.screencanvas`,首次调用根本没有被消耗,回退拿到的就是上屏画布本身。兜底换来的只是一个能力布尔值,代价却是可能被 `getContext` + `WEBGL_lose_context` 一起废掉的上屏上下文——症状是黑屏且不报错。
|
|
12
|
+
2. **身份比对基准选错了对象。** 原实现比的是「本次实际使用的画布」(`rawCanvas`)。宿主如果既预置了 `GameGlobal.screencanvas`、又调 `createWeChatGameBinding({ canvas })` 传了自己的画布,`getScreenCanvas` 走 `supplied` 分支、不写缓存,`rawCanvas` 与预置画布不是同一个对象,比对必然落空,探测照样摸到上屏画布。
|
|
13
|
+
|
|
14
|
+
## 决策
|
|
15
|
+
|
|
16
|
+
1. **没有 `createOffscreenCanvas` 就完全不兜底**。`allowCanvasFallback` 只在离屏 API 存在时生效;API 缺失直接返回 `undefined`,由 `detectCapabilities` 按基础库版本推断并标记 `webgl2Source: 'inferred'`。
|
|
17
|
+
2. **身份比对基准从「一个画布」改为「候选全集」**:`ProbeContextOptions.screenCanvas` 改为 `reservedCanvases`,小游戏绑定传入 `getScreenCanvas` 期间全部可能成为上屏画布的对象——显式传入的画布、缓存的上屏画布、`GameGlobal.screencanvas`、`globalThis.canvas`。命中任一即放弃探测。
|
|
18
|
+
3. 兜底仍然要求「上屏画布已解析」且显式 opt-in,这两条不变。
|
|
19
|
+
|
|
20
|
+
## 理由
|
|
21
|
+
|
|
22
|
+
- 兜底的价值是「一个更准的能力布尔值」,风险是「整块上屏画布」。ADR-0007 的收益判断在离屏 API 存在时成立(此时至少知道探测目标是第二次调用),在 API 缺失时不成立:那时连"这是第几次调用"都无法确定,等同掷硬币。**用「探测不到」换「确定不炸」是划算的**,何况不确定性已经通过 `webgl2Source: 'inferred'` 显式暴露给调用方,宿主可以自己覆盖。
|
|
23
|
+
- 身份比对是唯一可靠的判据,而"判据对不对"取决于基准集合是否完整。把一个引用扩成候选全集,成本是一次四元素的数组构造,收益是关掉一个入口分支上的重后果漏洞。
|
|
24
|
+
- 采纳「候选全集」而不是"禁止 `supplied` 与 `screencanvas` 同时出现",是因为后者会让宿主为了探测安全而改变合法的初始化写法。
|
|
25
|
+
|
|
26
|
+
## 后果
|
|
27
|
+
|
|
28
|
+
正面:
|
|
29
|
+
|
|
30
|
+
- 老基础库(无 `createOffscreenCanvas`)上不再有「探测废掉上屏画布」的路径;
|
|
31
|
+
- 显式传 `canvas` 的宿主也受身份守卫保护,`GameGlobal.screencanvas` 预置 + 自定义画布的组合不再漏;
|
|
32
|
+
- 回退分支少创建一块 1×1 画布,省一次画布额度。
|
|
33
|
+
|
|
34
|
+
负面 / 风险:
|
|
35
|
+
|
|
36
|
+
- 无离屏 API 的设备上不再有实测值,`webgl2` 完全依赖基础库版本推断(`>= 2.20.0`)。报告里 `webgl2Source: 'inferred'` 与一次 `warnOnce` 会说明这一点;
|
|
37
|
+
- 候选全集仍不是数学意义上的全集:如果某个宿主的上屏画布既不在 `GameGlobal.screencanvas`、也不在 `globalThis.canvas`、也没有显式传入,而 `createCanvas()` 又把它交回来,身份守卫仍会漏。这种宿主无法从适配层可见的信息中识别,属于残余风险;缓解手段是开发者工具 / 真机回归(`docs/11`)。
|
|
38
|
+
|
|
39
|
+
## 被否决的备选方案
|
|
40
|
+
|
|
41
|
+
| 方案 | 否决理由 |
|
|
42
|
+
| --- | --- |
|
|
43
|
+
| 保留无离屏 API 时的兜底,只做身份比对 | 正是本次要关掉的口子:那时连基准集合都不可靠 |
|
|
44
|
+
| 干脆彻底删掉回退探测 | 会丢掉 ADR-0007 的核心收益(开发者工具 / 部分机型离屏不支持 WebGL2,主画布支持),能力报告退回纯版本推断 |
|
|
45
|
+
| 禁止同时传 `canvas` 与预置 `screencanvas` | 用 API 限制去补实现漏洞,宿主合法写法被迫改变 |
|
|
46
|
+
| 用 `instanceof` / 宽高特征识别上屏画布 | 不是可靠判据(离屏画布同样有宽高),误判代价同样是黑屏 |
|
|
47
|
+
|
|
48
|
+
## 验证方式
|
|
49
|
+
|
|
50
|
+
- `tests/capabilities.test.ts`:
|
|
51
|
+
- 无 `createOffscreenCanvas` 时 `createCanvas()` 零调用、返回 `undefined`;
|
|
52
|
+
- 离屏存在但答不出 WebGL2 时仍回退,且回退返回非候选画布时正常得到 `true`;
|
|
53
|
+
- 回退返回候选画布时不 `getContext`;
|
|
54
|
+
- `GameGlobal.screencanvas` 预置 + 显式 `canvas` 时上屏画布零触碰、`webgl2Source === 'inferred'`;
|
|
55
|
+
- 离屏存在、回退拿到预置的上屏画布时同样零触碰。
|
|
56
|
+
- `tests/runtime.test.ts`:正常路径的能力报告不受影响。
|
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
# ADR-0009 · 占位作用域的「环境全局」读作 `undefined`
|
|
2
|
+
|
|
3
|
+
- 状态:Accepted(修订 [ADR-0001](./0001-scoped-globals.md) 的第 5 条)
|
|
4
|
+
- 日期:2026-11-10
|
|
5
|
+
- 影响模块:`src/scope.ts`、`src/core/runtime.ts`、`src/build/scope-rewrite.ts`(注释与语义边界)
|
|
6
|
+
|
|
7
|
+
## 背景
|
|
8
|
+
|
|
9
|
+
ADR-0001 决定:runtime 未创建时 `getActiveScope()` 返回占位对象,`typeof window` 仍是 `'object'`,其余键一读就抛带指引的错误。这个设计在「真的用错了」时很好用,但它把一个**探测**动作也变成了故障点。
|
|
10
|
+
|
|
11
|
+
复核时确认:
|
|
12
|
+
|
|
13
|
+
```text
|
|
14
|
+
getActiveScope().document
|
|
15
|
+
→ Error: [mini-three-adapter] Scoped global "document" was read before a runtime was created.
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
两条路径会撞上它:
|
|
19
|
+
|
|
20
|
+
1. `typeof document` —— 构建期插件只守卫 `typeof X` 这种**直接操作数**(改写成 `typeof (__m3Has() ? __m3().document : undefined)`)。`typeof window.document` 的操作数是成员表达式,插件只能替换 `window`,第二次取值仍落到占位对象上,`typeof` 立刻抛错。而 `typeof a.b` 在 JavaScript 里本来就允许抛:`typeof` 只对未声明的**标识符**免抛。
|
|
21
|
+
2. 任何库在模块顶层写的 `const hasDom = typeof document !== 'undefined'`,只要该模块不是被插件改写的目标(应用层代码默认不改写),又恰好通过 `installGlobals` 暴露到 `globalThis` 上,同样会抛。
|
|
22
|
+
|
|
23
|
+
「这个宿主有没有 DOM」是所有图形库第一个要问的问题,适配层在这上面抛错,等于把初始化顺序问题伪装成适配层内部故障。
|
|
24
|
+
|
|
25
|
+
## 决策
|
|
26
|
+
|
|
27
|
+
1. 占位对象对**环境探测型**全局返回 `undefined`:`document`、`navigator`、`screen`、`location`、`history`。语义上等于「这个宿主没有 DOM」,与 Worker / Node 一致,`typeof` 与真值判断都能正常工作。
|
|
28
|
+
2. 其余键(`HTMLCanvasElement`、`TextDecoder`、`Blob`、`fetch` …)**保持抛错**。读它们不是探测而是真实使用,静默 `undefined` 只会把错误推迟到几帧之后、在无关的栈上炸开。
|
|
29
|
+
3. 这些早读被记录到模块级集合,`createRuntime()` 启动时 `warnOnce` 汇总一次(`Scoped globals were read before this runtime existed: document`),随后清空。诊断价值从「抛出异常」改为「启动时点名」,不再阻断执行。
|
|
30
|
+
4. 占位对象对未知 `Symbol` 键返回 `undefined`,避免 `console.log` / `util.inspect` 之类仅做展示的动作抛错。
|
|
31
|
+
|
|
32
|
+
## 理由
|
|
33
|
+
|
|
34
|
+
- `typeof` 是约定俗成的「永不抛错」运算符,第三方库(含 three 的 `WebGL.js`、`ImageLoader`、worker 分支判断)大量依赖这一点。适配层不能成为这个约定的例外。
|
|
35
|
+
- 只放开环境探测型的五个键,而不是全部放开:真实 API 的误读仍然在**发生的那一行**报错,这是 ADR-0001 想要保留的性质。两类键的边界清楚可讲:「描述宿主形态的」vs「提供具体能力的」。
|
|
36
|
+
- 「启动时点名」比「就地抛错」更适合本项目的失败形态:three 求值过早不会破坏 runtime 本身,只是让某段特性检测走了非浏览器分支,跑起来通常是正常的。用一次告警指出可疑点,比让一整个应用起不来更符合实际后果。
|
|
37
|
+
|
|
38
|
+
## 后果
|
|
39
|
+
|
|
40
|
+
正面:
|
|
41
|
+
|
|
42
|
+
- `typeof document`、`typeof window.document`、`typeof navigator` 在任何时机都不再抛错;
|
|
43
|
+
- 早读仍有可发现的痕迹:`getEarlyScopeReads()` 可查,`createRuntime()` 会告警一次,`docs/06` / `docs/07` 的报错对照表给出处理方式;
|
|
44
|
+
- 构建期插件的 `typeof` 守卫从「唯一防线」退化为「对真实 API 的补强」,两处逻辑不再互相依赖。
|
|
45
|
+
|
|
46
|
+
负面 / 风险:
|
|
47
|
+
|
|
48
|
+
- 依赖「错误立即抛出」来发现初始化顺序问题的用户,现在看到的是告警而不是异常。这是有意的取舍:异常的代价(整个应用起不来、报错指向适配层)高于收益;
|
|
49
|
+
- 早读记录是模块级状态,多 runtime 场景下第一次 `createRuntime()` 就会消费并清空它。测试里需要显式 `clearEarlyScopeReads()`;
|
|
50
|
+
- 占位对象的行为不再对称(五个键返回 `undefined`,其余抛错),必须靠文档与 ADR 说明,否则后来者容易误以为漏了分支。
|
|
51
|
+
|
|
52
|
+
## 被否决的备选方案
|
|
53
|
+
|
|
54
|
+
| 方案 | 否决理由 |
|
|
55
|
+
| --- | --- |
|
|
56
|
+
| 全部键都返回 `undefined`,彻底不抛 | 真实使用会在离现场几帧的地方以无关形式失败,比 ADR-0001 之前更难排查 |
|
|
57
|
+
| 保持现状,靠构建期给 `typeof X.Y` 加守卫 | 需要识别成员链上的每个根,且应用层代码默认不改写,守卫无法覆盖 |
|
|
58
|
+
| 让占位对象在第一次 `typeof` 时打 `console.warn` | 只能拿到字符串 `prop`,无法区分探测与使用;且 `Diagnostics` 尚不存在(`src/scope.ts` 不能反向依赖 `core/`) |
|
|
59
|
+
| 在 `createRuntime()` 里直接 `throw` | 把「求值过早」升级成硬失败,与本次「不阻断」的取向相反 |
|
|
60
|
+
|
|
61
|
+
## 验证方式
|
|
62
|
+
|
|
63
|
+
- 新增 `tests/scope.test.ts`:
|
|
64
|
+
- 环境全局读作 `undefined`,`typeof` 不抛;
|
|
65
|
+
- `typeof window.document` 这种嵌套形态不抛(构建期无法守卫的缺口);
|
|
66
|
+
- `HTMLCanvasElement` / `TextDecoder` 仍然抛出含指引文案的错误;
|
|
67
|
+
- 早读被记录、`createRuntime()` 告警一次后清空;
|
|
68
|
+
- 没有任何早读时不告警。
|
|
69
|
+
- `tests/runtime.test.ts` 与 `tests/scope-rewrite.test.ts` 全部保持通过(改写产物形态未变)。
|
package/docs/adr/README.md
CHANGED
|
@@ -10,7 +10,9 @@
|
|
|
10
10
|
| [0004](./0004-in-place-patching.md) | 就地 patch 画布,不改原型、不用 Proxy | Accepted |
|
|
11
11
|
| [0005](./0005-webgl2-only.md) | WebGL2 优先,不静默降级到 WebGL1 | Accepted |
|
|
12
12
|
| [0006](./0006-zero-three-dependency.md) | 运行时零 `three` 依赖,构建/运行严格隔离 | Accepted |
|
|
13
|
-
| [0007](./0007-capability-probe-fallback.md) | 能力探测允许主画布回退,`undefined` 表示「无法探测」 | Accepted |
|
|
13
|
+
| [0007](./0007-capability-probe-fallback.md) | 能力探测允许主画布回退,`undefined` 表示「无法探测」 | Accepted(部分被 0008 收紧) |
|
|
14
|
+
| [0008](./0008-probe-fallback-boundary.md) | 无离屏 API 不兜底;身份基准取候选上屏画布全集 | Accepted |
|
|
15
|
+
| [0009](./0009-placeholder-scope-environment-globals.md) | 占位作用域的环境全局读作 `undefined`,早读改为启动时点名 | Accepted |
|
|
14
16
|
|
|
15
17
|
模板(新增 ADR 时复制):
|
|
16
18
|
|
package/llms.txt
CHANGED
|
@@ -32,6 +32,8 @@
|
|
|
32
32
|
- [ADR-0005 WebGL2 only](./docs/adr/0005-webgl2-only.md)
|
|
33
33
|
- [ADR-0006 zero three dependency](./docs/adr/0006-zero-three-dependency.md)
|
|
34
34
|
- [ADR-0007 capability probe fallback](./docs/adr/0007-capability-probe-fallback.md)
|
|
35
|
+
- [ADR-0008 probe fallback boundary](./docs/adr/0008-probe-fallback-boundary.md)
|
|
36
|
+
- [ADR-0009 placeholder scope environment globals](./docs/adr/0009-placeholder-scope-environment-globals.md)
|
|
35
37
|
|
|
36
38
|
## Source entry points
|
|
37
39
|
|
|
@@ -57,9 +59,10 @@
|
|
|
57
59
|
- [tests/scope-rewrite.test.ts](./tests/scope-rewrite.test.ts): AST correctness.
|
|
58
60
|
- [tests/polyfills.test.ts](./tests/polyfills.test.ts): event/blob/url/network.
|
|
59
61
|
- [tests/plugin.test.ts](./tests/plugin.test.ts): plugin and assets.
|
|
60
|
-
- [tests/image-events.test.ts](./tests/image-events.test.ts):
|
|
62
|
+
- [tests/image-events.test.ts](./tests/image-events.test.ts): host matrix for the image event bridge (native addEventListener / assignable onload / getImageInfo-only / watchdog), complete + decode semantics.
|
|
61
63
|
- [tests/event-dispatch.test.ts](./tests/event-dispatch.test.ts): listener `this` / event.target / currentTarget resolve to the host element.
|
|
62
|
-
- [tests/capabilities.test.ts](./tests/capabilities.test.ts): context probing fallback, screen-canvas identity guard, webgl2Source.
|
|
64
|
+
- [tests/capabilities.test.ts](./tests/capabilities.test.ts): context probing fallback, screen-canvas identity guard (candidate set), webgl2Source.
|
|
65
|
+
- [tests/scope.test.ts](./tests/scope.test.ts): placeholder scope before a runtime (environment globals read as undefined, early-read reporting).
|
|
63
66
|
- [tests/helpers/mock-wx.ts](./tests/helpers/mock-wx.ts): injectable wx simulator.
|
|
64
67
|
- [examples/README.md](./examples/README.md): three runnable targets (mini game / mini program / H5).
|
|
65
68
|
|
package/package.json
CHANGED
|
@@ -1 +0,0 @@
|
|
|
1
|
-
{"version":3,"sources":["../src/scope.ts"],"names":[],"mappings":"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","file":"chunk-34RWHAW4.js","sourcesContent":["/**\n * Scoped globals: the central design decision of mini-three-adapter.\n *\n * The original adapter style (and WeChat's official `weapp-adapter`) writes\n * `window`, `document`, `Image`, ... onto `globalThis`. That is convenient but\n * irreversible: it breaks H5 dual-target builds, makes two three.js versions\n * fight over the same canvas, and cannot be un-installed in tests.\n *\n * Here the shims live in one explicit `MiniThreeScope` object. Third-party\n * modules (three, three/addons, three-stdlib, ...) are rewritten at build time\n * by `mini-three-adapter/vite` so that their *free* references to browser\n * globals resolve through `getActiveScope()`. Application code is untouched.\n *\n * `installGlobals()` remains available as an explicit, reversible escape hatch\n * for libraries that cannot be transformed.\n */\nimport type {\n CanvasStyleLike,\n EventTargetLike,\n PatchedCanvas,\n Rect,\n} from './types';\n\nexport interface DocumentLike extends EventTargetLike {\n createElement(tagName: string): PatchedCanvas | unknown;\n createElementNS(namespaceURI: string | null, tagName: string): PatchedCanvas | unknown;\n body: ElementLike;\n documentElement: ElementLike;\n defaultView: MiniThreeScope | null;\n [key: string]: unknown;\n}\n\nexport interface ElementLike extends EventTargetLike {\n style: CanvasStyleLike;\n clientWidth: number;\n clientHeight: number;\n getBoundingClientRect(): Rect;\n setAttribute(name: string, value: unknown): void;\n removeAttribute(name: string): void;\n [key: string]: unknown;\n}\n\nexport interface NavigatorLike {\n userAgent: string;\n platform: string;\n hardwareConcurrency: number;\n [key: string]: unknown;\n}\n\n/**\n * The set of browser globals three.js (and its addons) may read. Members are\n * typed where they matter and `unknown` in the index signature so the build\n * plugin can add platform-specific extras without loosening the whole object.\n */\nexport interface MiniThreeScope extends EventTargetLike {\n readonly window: MiniThreeScope;\n readonly self: MiniThreeScope;\n readonly globalThis: MiniThreeScope;\n document: DocumentLike;\n navigator: NavigatorLike;\n screen: EventTargetLike & {\n width: number;\n height: number;\n availWidth: number;\n availHeight: number;\n colorDepth: number;\n pixelDepth: number;\n };\n innerWidth: number;\n innerHeight: number;\n outerWidth: number;\n outerHeight: number;\n devicePixelRatio: number;\n pageXOffset: number;\n pageYOffset: number;\n performance: { now(): number };\n requestAnimationFrame(callback: (time: number) => void): number;\n cancelAnimationFrame(id: number): void;\n getComputedStyle(element: unknown): CanvasStyleLike;\n matchMedia(query: string): { matches: boolean; media: string; addListener(l: unknown): void; removeListener(l: unknown): void };\n atob(data: string): string;\n btoa(data: string): string;\n\n Event: unknown;\n EventTarget: unknown;\n CustomEvent: unknown;\n PointerEvent: unknown;\n MouseEvent: unknown;\n TouchEvent: unknown;\n MessageEvent: unknown;\n ProgressEvent: unknown;\n KeyboardEvent: unknown;\n DOMException: unknown;\n\n HTMLElement: unknown;\n HTMLCanvasElement: unknown;\n HTMLImageElement: unknown;\n HTMLVideoElement: unknown;\n OffscreenCanvas: unknown;\n Image: unknown;\n ImageData: unknown;\n DOMRect: unknown;\n WebGLRenderingContext: unknown;\n WebGL2RenderingContext: unknown;\n AudioContext: unknown;\n\n Blob: unknown;\n URL: unknown;\n FileReader: unknown;\n TextDecoder: unknown;\n TextEncoder: unknown;\n AbortController: unknown;\n AbortSignal: unknown;\n fetch: unknown;\n XMLHttpRequest: unknown;\n WebSocket: unknown;\n createImageBitmap: unknown;\n Worker: unknown;\n WebAssembly: unknown;\n ResizeObserver: unknown;\n\n [key: string]: unknown;\n}\n\nlet active: MiniThreeScope | null = null;\n\nfunction notInitialized(name: string): never {\n throw new Error(\n `[mini-three-adapter] Scoped global \"${name}\" was read before a runtime was created. ` +\n `Import 'mini-three-adapter/wechat-game' and await createWeChatGameRuntime() before importing three.js, ` +\n `or call installGlobals(scope) explicitly.`,\n );\n}\n\n/**\n * A stable placeholder returned when no runtime exists yet. `typeof scope.window`\n * still yields \"object\" (which is what three.js feature-detection expects), but\n * any real access throws an actionable error instead of silently returning\n * `undefined` three frames later.\n */\nconst emptyScope: MiniThreeScope = new Proxy(\n { window: null, self: null, globalThis: null } as unknown as MiniThreeScope,\n {\n get(target, prop) {\n if (prop === 'window' || prop === 'self' || prop === 'globalThis') return emptyScope;\n if (prop === 'document') return notInitialized('document');\n if (prop === Symbol.toStringTag) return 'MiniThreeScope';\n return notInitialized(String(prop));\n },\n has() {\n return false;\n },\n },\n);\n\n/** Returns the currently installed scope (or the throwing placeholder). */\nexport function getActiveScope(): MiniThreeScope {\n return active ?? emptyScope;\n}\n\n/** Install / replace the active scope. Returns a disposer. */\nexport function setActiveScope(scope: MiniThreeScope | null): () => void {\n const previous = active;\n active = scope;\n return () => {\n if (active === scope) active = previous;\n };\n}\n\nexport function hasActiveScope(): boolean {\n return active !== null;\n}\n\n/**\n * Build a scope with a set of overrides. `window`, `self` and `globalThis`\n * are wired to the scope itself so that `window.window === window`.\n */\nexport function createScope(overrides: Partial<MiniThreeScope> = {}): MiniThreeScope {\n const scope = {\n ...overrides,\n } as MiniThreeScope;\n Object.defineProperties(scope, {\n window: { get: () => scope, enumerable: true, configurable: true },\n self: { get: () => scope, enumerable: true, configurable: true },\n globalThis: { get: () => scope, enumerable: true, configurable: true },\n });\n return scope;\n}\n\n/** Keys written by `installGlobals`. Kept explicit so restoration is exact. */\nconst GLOBAL_KEYS = [\n 'window', 'self', 'document', 'navigator', 'screen',\n 'innerWidth', 'innerHeight', 'outerWidth', 'outerHeight', 'devicePixelRatio',\n 'pageXOffset', 'pageYOffset', 'performance',\n 'requestAnimationFrame', 'cancelAnimationFrame', 'getComputedStyle', 'matchMedia',\n 'atob', 'btoa',\n 'Event', 'EventTarget', 'CustomEvent', 'PointerEvent', 'MouseEvent', 'TouchEvent',\n 'MessageEvent', 'ProgressEvent', 'KeyboardEvent', 'DOMException',\n 'HTMLElement', 'HTMLCanvasElement', 'HTMLImageElement', 'HTMLVideoElement',\n 'OffscreenCanvas', 'Image', 'ImageData', 'DOMRect',\n 'WebGLRenderingContext', 'WebGL2RenderingContext', 'AudioContext',\n 'Blob', 'URL', 'FileReader', 'TextDecoder', 'TextEncoder',\n 'AbortController', 'AbortSignal', 'fetch', 'XMLHttpRequest', 'WebSocket',\n 'createImageBitmap', 'Worker', 'WebAssembly', 'ResizeObserver',\n] as const;\n\nexport interface InstallGlobalsOptions {\n /** Defaults to `globalThis`. */\n target?: Record<string, unknown>;\n /** Skip keys that already exist (useful in a browser / H5 build). */\n skipExisting?: boolean;\n /** Additional keys to copy from the scope. */\n extraKeys?: string[];\n}\n\n/**\n * Explicit opt-in global pollution for libraries that cannot be transformed.\n * Returns a disposer that restores every overwritten descriptor exactly.\n *\n * This is intentionally NOT called automatically: the default path is scoped.\n */\nexport function installGlobals(\n scope: MiniThreeScope,\n options: InstallGlobalsOptions = {},\n): () => void {\n const target = options.target ?? (globalThis as unknown as Record<string, unknown>);\n const keys: string[] = [...GLOBAL_KEYS, ...(options.extraKeys ?? [])];\n const saved = new Map<string, PropertyDescriptor | undefined>();\n\n for (const key of keys) {\n const existing = Object.getOwnPropertyDescriptor(target, key);\n if (options.skipExisting && existing) continue;\n if (!(key in scope)) continue;\n saved.set(key, existing);\n Object.defineProperty(target, key, {\n get: () => (scope as Record<string, unknown>)[key],\n configurable: true,\n enumerable: true,\n });\n }\n\n return () => {\n for (const [key, descriptor] of saved) {\n if (descriptor) Object.defineProperty(target, key, descriptor);\n else delete target[key];\n }\n };\n}\n"]}
|
|
@@ -1 +0,0 @@
|
|
|
1
|
-
{"version":3,"sources":["../src/platforms/wechat-game.ts"],"names":[],"mappings":"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","file":"chunk-3QUEDYTT.js","sourcesContent":["/** WeChat Mini Game (小游戏) platform binding. */\nimport type { Capabilities, ContextType, Disposer, Rect, TouchLikeEvent } from '../types';\nimport type { PlatformBinding } from '../core/platform';\nimport { createRuntime, type MiniThreeRuntime, type RuntimeOptions } from '../core/runtime';\nimport { detectCapabilities } from '../core/capabilities';\nimport { createDiagnostics, type Diagnostics } from '../core/diagnostics';\nimport {\n createNow,\n createOffscreenCanvasRaw,\n createRafPair,\n createWechatImageFactory,\n probeContext,\n rectFromWindowInfo,\n watchWxTouch,\n watchWxVisibility,\n} from './wechat-common';\nimport { resolveWx, type WxCanvas, type WxLike } from './wx-types';\n\nexport interface WeChatGameOptions {\n /** Inject a `wx` mock (tests / non-WeChat hosts). */\n wx?: WxLike;\n /**\n * Reuse an existing on-screen canvas. If omitted, the adapter checks\n * `GameGlobal.screencanvas`, `globalThis.canvas` (weapp-adapter) and finally\n * calls `wx.createCanvas()` exactly once.\n */\n canvas?: WxCanvas;\n capabilities?: Partial<Capabilities>;\n diagnostics?: Diagnostics;\n /** Call wx.setPreferredFramesPerSecond(fps) when supported. */\n preferredFps?: number;\n}\n\nlet cachedScreenCanvas: WxCanvas | null = null;\n\n/** Resolve (and memoize) the single on-screen canvas. */\nexport function getScreenCanvas(wx: WxLike, supplied?: WxCanvas): WxCanvas {\n if (supplied) return supplied;\n if (cachedScreenCanvas) return cachedScreenCanvas;\n const host = globalThis as unknown as Record<string, unknown>;\n const gameGlobal = host.GameGlobal as Record<string, unknown> | undefined;\n const existing = (gameGlobal?.screencanvas ?? host.canvas) as WxCanvas | undefined;\n if (existing && typeof existing.getContext === 'function') {\n cachedScreenCanvas = existing;\n return existing;\n }\n if (typeof wx.createCanvas !== 'function') {\n throw new Error('[mini-three-adapter] wx.createCanvas is missing: this is not a WeChat Mini Game runtime');\n }\n cachedScreenCanvas = wx.createCanvas();\n return cachedScreenCanvas;\n}\n\n/** Only for tests: forget the memoized screen canvas. */\nexport function resetScreenCanvasCache(): void {\n cachedScreenCanvas = null;\n}\n\nexport function createWeChatGameBinding(options: WeChatGameOptions = {}): PlatformBinding {\n const wx = resolveWx(options.wx);\n const diagnostics = options.diagnostics ?? createDiagnostics('warn');\n const rawCanvas = getScreenCanvas(wx, options.canvas);\n const capabilities = detectCapabilities(wx, 'wechat-game', {\n overrides: options.capabilities,\n diagnostics,\n // The on-screen canvas is already resolved above, so a second\n // createCanvas() is guaranteed to be off-screen and safe to probe — except\n // when the host seeded `GameGlobal.screencanvas`: then the first call was\n // never consumed and can still hand the screen canvas back. Passing it in\n // lets `probeContext` refuse that object by identity instead of creating\n // and immediately losing its context.\n probeContext: (type) =>\n probeContext(wx, type, { allowCanvasFallback: true, screenCanvas: rawCanvas }),\n });\n const imageFactory = createWechatImageFactory(wx, diagnostics);\n const raf = createRafPair(wx, rawCanvas);\n const now = createNow(wx);\n\n if (options.preferredFps && typeof wx.setPreferredFramesPerSecond === 'function') {\n wx.setPreferredFramesPerSecond(options.preferredFps);\n }\n\n const getCanvasRect = (): Rect => rectFromWindowInfo(wx);\n\n return {\n kind: 'wechat-game',\n wx,\n rawCanvas,\n capabilities,\n imageFactory,\n getCanvasRect,\n createOffscreenCanvas: (width: number, height: number, type: ContextType) =>\n createOffscreenCanvasRaw(wx, width, height, type, diagnostics),\n watchTouch: (handler: (event: TouchLikeEvent) => void): Disposer => watchWxTouch(wx, handler),\n watchVisibility: (handler) => watchWxVisibility(wx, handler),\n requestAnimationFrame: raf.request,\n cancelAnimationFrame: raf.cancel,\n now,\n dispose: () => {\n // The on-screen canvas belongs to the game; never destroy it here.\n diagnostics.debug('wechat-game binding disposed');\n },\n };\n}\n\nexport type WeChatGameRuntimeOptions = WeChatGameOptions & RuntimeOptions;\n\n/** One-line bootstrap for mini games. */\nexport function createWeChatGameRuntime(\n options: WeChatGameRuntimeOptions = {},\n): Promise<MiniThreeRuntime> {\n return createRuntime(() => createWeChatGameBinding(options), options);\n}\n"]}
|