mini-three-adapter 0.1.2 → 0.1.4
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-CQPWOYLA.js → chunk-26BRT4GS.js} +21 -10
- package/dist/chunk-26BRT4GS.js.map +1 -0
- package/dist/{chunk-LRR4AEZM.js → chunk-2WNTAMJZ.js} +4 -4
- package/dist/{chunk-LRR4AEZM.js.map → chunk-2WNTAMJZ.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-WB6MOHR3.js → chunk-HJIO6AFC.js} +19 -7
- package/dist/chunk-HJIO6AFC.js.map +1 -0
- package/dist/{chunk-TMSB525P.js → chunk-LCJNTN6F.js} +7 -6
- package/dist/chunk-LCJNTN6F.js.map +1 -0
- package/dist/{chunk-V2IGFCZV.js → chunk-NC2FTUEU.js} +3 -3
- package/dist/{chunk-V2IGFCZV.js.map → chunk-NC2FTUEU.js.map} +1 -1
- package/dist/{chunk-MWGTYPGA.js → chunk-XUKHCVAV.js} +12 -4
- package/dist/chunk-XUKHCVAV.js.map +1 -0
- package/dist/core/index.js +3 -3
- package/dist/index.d.ts +1 -1
- package/dist/index.js +7 -7
- package/dist/platforms/browser.js +4 -4
- package/dist/platforms/wechat-game.js +5 -5
- package/dist/platforms/wechat-miniprogram.js +5 -5
- package/dist/polyfills/index.js +1 -1
- package/dist/scope.d.ts +8 -1
- package/dist/scope.js +1 -1
- 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 +6 -3
- package/docs/07-integration-guide.md +2 -1
- package/docs/09-testing-and-release.md +210 -208
- package/docs/10-ai-playbook.md +3 -1
- package/docs/11-compat-matrix.md +3 -2
- package/docs/adr/0007-capability-probe-fallback.md +11 -5
- 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 -1
- package/package.json +1 -1
- package/dist/chunk-34RWHAW4.js.map +0 -1
- package/dist/chunk-CQPWOYLA.js.map +0 -1
- package/dist/chunk-MWGTYPGA.js.map +0 -1
- package/dist/chunk-TMSB525P.js.map +0 -1
- package/dist/chunk-WB6MOHR3.js.map +0 -1
|
@@ -29,8 +29,8 @@ const { startScene } = await import('./scene.js'); // scene.js 里才 import thr
|
|
|
29
29
|
|
|
30
30
|
**兜底**:`createWeChatGameRuntime({ installGlobals: true })`,把 shim 显式挂到 `globalThis`(可逆),适合无法改导入结构的老项目。
|
|
31
31
|
|
|
32
|
-
|
|
33
|
-
`Scoped global "xxx" was read before a runtime was created
|
|
32
|
+
诊断:占位作用域里 `document` / `navigator` / `screen` / `location` / `history` 读作 `undefined`(`typeof` 永不抛错),其余键真正取值时会抛
|
|
33
|
+
`Scoped global "xxx" was read before a runtime was created`,直接提示上述两种解法。早读过的环境全局会被记录下来,`createRuntime()` 启动时 `warnOnce` 汇总一次,指向「three 求值过早」。
|
|
34
34
|
|
|
35
35
|
## 6.3 已知坑位与处理
|
|
36
36
|
|
|
@@ -48,6 +48,8 @@ const { startScene } = await import('./scene.js'); // scene.js 里才 import thr
|
|
|
48
48
|
| three 版本升级后控件失效 | r170+ 用 `three/addons/`,`outputColorSpace` 取代 `outputEncoding` | 示例与 `rendererHints` 使用新 API;插件 include 覆盖两种路径 |
|
|
49
49
|
| `img.onload` / `addEventListener('load')` 永不触发,纹理靠超时兜底 | 图片 shim 只建了「合成事件 → 用户回调」这条边,没有「原生 load → 合成事件」 | `createImageFactory` 在 patch 前抓原生 `onload`/`onerror` 描述符并挂转发器;宿主不可拦截时 `warnOnce` 告警(`image has no writable onload/onerror`) |
|
|
50
50
|
| `canvas.onpointerdown = fn` 之类行内处理器不触发 | 事件方法被绑定到内部对象,`this['on'+type]` 查找落空 | `patchEventTarget` 把宿主对象作为行内处理器宿主传入 |
|
|
51
|
+
| `texture.image` 是个没有 `src` 的空壳,贴图不显示 | 监听器里的 `this` 是内部 `MiniEventTarget`,three `ImageLoader` 把它当成 `<img>` 存进 `Texture.source.data` | `dispatchEvent` 把 `this`、`event.target`、`currentTarget` 全部转发到宿主元素;`event.target` 不再暴露内部监听表 |
|
|
52
|
+
| 预置 `GameGlobal.screencanvas` 的宿主偶发黑屏 | 探测回退拿到的正是上屏画布,`getContext` + `WEBGL_lose_context` 把它废掉 | 无 `createOffscreenCanvas` 时干脆不兜底;兜底时按 `reservedCanvases`(本次使用的画布 + 缓存画布 + `GameGlobal.screencanvas` + `globalThis.canvas`)逐个比对身份,命中任一即放弃并退回 `webgl2Source: 'inferred'`(ADR-0008) |
|
|
51
53
|
|
|
52
54
|
深度缓冲补丁(应用层显式启用):
|
|
53
55
|
|
|
@@ -93,7 +95,8 @@ mini-three-adapter capability report
|
|
|
93
95
|
```
|
|
94
96
|
|
|
95
97
|
- `probeContext()` 优先用 `wx.createOffscreenCanvas({type:'webgl2'})` 探测并主动 `WEBGL_lose_context` 释放,**不会**占用上屏画布。
|
|
96
|
-
-
|
|
98
|
+
- 只有离屏 API **存在**但答不出 WebGL2 时,小游戏绑定才会回退到第二次 `wx.createCanvas()` 实测;离屏 API 完全不存在时直接放弃兜底——因为那时无法判断「首次 `createCanvas()`」是否已被消耗,兜底等于掷硬币。小程序绑定从不回退:它的画布节点来自选择器查询,直接探测会用默认属性抢先创建真实上下文。决策见 [ADR-0007](./adr/0007-capability-probe-fallback.md)、[ADR-0008](./adr/0008-probe-fallback-boundary.md)。
|
|
99
|
+
- 回退有一道身份守卫:调用方传入 `reservedCanvases`(本次使用的画布、缓存的上屏画布、`GameGlobal.screencanvas`、`globalThis.canvas` 的并集),`createCanvas()` 返回其中**任一对象**就立刻放弃,既不 `getContext` 也不 `WEBGL_lose_context`。基准必须是「所有可能的上屏画布」而不是「本次使用的画布」:宿主既预置 `screencanvas` 又显式传 `canvas` 时,两者不是同一个对象。
|
|
97
100
|
- 两者都无法判定时返回 `undefined`,`webgl2` 按基础库版本推断,`webgl2Source` 标为 `'inferred'` 并告警一次。**「探测不到」不等于「不支持」**。
|
|
98
101
|
- 探测结果可用 `capabilities` 选项覆盖(用于测试或已知机型分级),此时 `webgl2Source` 为 `'override'`。
|
|
99
102
|
- 实测 `webgl2: false` 时会告警,但**不会静默降级到 WebGL1**——three ≥ r163 本来就要求 WebGL2,静默降级只会延后报错。
|
|
@@ -219,6 +219,7 @@ Page({
|
|
|
219
219
|
| `Uncaught TypeError: Class constructor xxx cannot be invoked without 'new'`,栈顶在 `GLTFLoader.js` 的 `new TextDecoder()` 处 | 构建期把 `new TextDecoder()` 改成了 `(new __m3()).TextDecoder()` | 升级适配层;临时规避见 [`docs/05` §5.7](./05-build-plugin.md#57-调试构建问题) |
|
|
220
220
|
| `SyntaxError: Unexpected token '.'`,产物里出现 `{ __m3().xxx }` | 对象简写属性被原地替换 | 同上 |
|
|
221
221
|
| 纹理永远加载不出来、`ImageLoader` 卡满超时;`img.onload` 与 `addEventListener('load')` 都不触发 | 图片 shim 没有把原生 `onload` 桥接到合成事件 | 升级适配层;日志里出现 `image has no writable onload/onerror` 说明宿主图片对象不可拦截 |
|
|
222
|
+
| 纹理"加载成功"但画面无变化、法线 / 环境贴图不生效;`texture.image` 没有 `src` 也没有宽高 | 监听器里的 `this` 是内部事件载体,`ImageLoader` 把它当成 `<img>` 存进了 `Texture.source.data` | 升级适配层(0.1.3+)。若业务里自己写过 `image.inlineHost` 取真图,可以删掉 |
|
|
222
223
|
| `capabilities.webgl2 === false`,但 `#version 300 es` 能正常渲染 | 能力探测用了离屏画布,离屏与上屏能力不同 | 看 `capabilities.webgl2Source`:`'inferred'` 表示未实测;需要以实测为准时显式传 `capabilities: { webgl2: true }` |
|
|
223
|
-
| `Scoped global "
|
|
224
|
+
| `Scoped global "xxx" was read before a runtime was created` | 在 `createXxxRuntime()` 之前求值了读 `xxx` 的模块(`document` / `navigator` / `screen` 等环境全局已改为读作 `undefined`,不再抛;能抛的是 `TextDecoder`、`HTMLCanvasElement` 这类真实 API) | 改为动态 `import()`;日志里出现 `Scoped globals were read before this runtime existed` 说明特性检测走了「非浏览器」分支,同样需要调整入口顺序 |
|
|
224
225
|
| 触摸事件收不到 | 小程序未转发 `bindtouch*`,或小游戏在 runtime 之后才注册监听 | 见 [`docs/06`](./06-platform-notes.md) 与 §7.5 |
|
|
@@ -1,208 +1,210 @@
|
|
|
1
|
-
# 09 · 测试、构建与发布
|
|
2
|
-
|
|
3
|
-
## 9.1 常用命令
|
|
4
|
-
|
|
5
|
-
```bash
|
|
6
|
-
npm install # 安装依赖
|
|
7
|
-
npm run typecheck # tsc --noEmit(strict)
|
|
8
|
-
npm test # vitest run(
|
|
9
|
-
npm test -- --watch # 观察模式
|
|
10
|
-
npm run build # tsup:dist/*.js + *.d.ts + sourcemap
|
|
11
|
-
npm run check # typecheck + test + build
|
|
12
|
-
```
|
|
13
|
-
|
|
14
|
-
Windows 说明:`vitest.config.ts` 使用**单 fork**(`pool: 'forks'`, `singleFork: true`, `fileParallelism: false`, `cache: false`),避免并行 worker 写入系统临时目录时的 `EPERM`。若仍遇到临时目录权限问题:
|
|
15
|
-
|
|
16
|
-
```bash
|
|
17
|
-
TMP="$PWD/.tmp/vitest" TEMP="$PWD/.tmp/vitest" npm test
|
|
18
|
-
```
|
|
19
|
-
|
|
20
|
-
## 9.2 测试结构
|
|
21
|
-
|
|
22
|
-
| 文件 | 覆盖 |
|
|
23
|
-
| --- | --- |
|
|
24
|
-
| `tests/scope-rewrite.test.ts` | AST 重写:自由变量、局部遮蔽、对象键、成员属性、`typeof`、import/export、自定义访问器 |
|
|
25
|
-
| `tests/polyfills.test.ts` | EventTarget/once/remove、PointerEvent、Blob/URL/base64、URL 解析、TextEncoder、fetch、AbortController |
|
|
26
|
-
| `tests/runtime.test.ts` | 画布补丁、scope 隔离、上下文缓存、触摸桥、多指、installGlobals 可逆、resize/dispose、能力报告 |
|
|
27
|
-
| `tests/plugin.test.ts` | 资产扫描、未解析资源、模块过滤、WebGPU 告警、manifest 输出 |
|
|
28
|
-
| `tests/image-events.test.ts` | 图片原生 `onload`/`onerror` → 合成事件桥接、`decode()` settle、宿主不可拦截时的 `warnOnce` 去重 |
|
|
29
|
-
| `tests/
|
|
30
|
-
| `tests/
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
|
41
|
-
|
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
- `
|
|
48
|
-
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
import {
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
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
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
- `
|
|
100
|
-
- `
|
|
101
|
-
- `
|
|
102
|
-
|
|
103
|
-
`
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
npm
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
import
|
|
142
|
-
import {
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
```
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
#
|
|
174
|
-
npm version
|
|
175
|
-
#
|
|
176
|
-
npm version
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
|
188
|
-
|
|
|
189
|
-
|
|
|
190
|
-
| `
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
- [ ]
|
|
205
|
-
- [ ]
|
|
206
|
-
- [ ]
|
|
207
|
-
- [ ]
|
|
208
|
-
- [ ]
|
|
1
|
+
# 09 · 测试、构建与发布
|
|
2
|
+
|
|
3
|
+
## 9.1 常用命令
|
|
4
|
+
|
|
5
|
+
```bash
|
|
6
|
+
npm install # 安装依赖
|
|
7
|
+
npm run typecheck # tsc --noEmit(strict)
|
|
8
|
+
npm test # vitest run(71 例)
|
|
9
|
+
npm test -- --watch # 观察模式
|
|
10
|
+
npm run build # tsup:dist/*.js + *.d.ts + sourcemap
|
|
11
|
+
npm run check # typecheck + test + build
|
|
12
|
+
```
|
|
13
|
+
|
|
14
|
+
Windows 说明:`vitest.config.ts` 使用**单 fork**(`pool: 'forks'`, `singleFork: true`, `fileParallelism: false`, `cache: false`),避免并行 worker 写入系统临时目录时的 `EPERM`。若仍遇到临时目录权限问题:
|
|
15
|
+
|
|
16
|
+
```bash
|
|
17
|
+
TMP="$PWD/.tmp/vitest" TEMP="$PWD/.tmp/vitest" npm test
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
## 9.2 测试结构
|
|
21
|
+
|
|
22
|
+
| 文件 | 覆盖 |
|
|
23
|
+
| --- | --- |
|
|
24
|
+
| `tests/scope-rewrite.test.ts` | AST 重写:自由变量、局部遮蔽、对象键、成员属性、`typeof`、import/export、自定义访问器 |
|
|
25
|
+
| `tests/polyfills.test.ts` | EventTarget/once/remove、PointerEvent、Blob/URL/base64、URL 解析、TextEncoder、fetch、AbortController |
|
|
26
|
+
| `tests/runtime.test.ts` | 画布补丁、scope 隔离、上下文缓存、触摸桥、多指、installGlobals 可逆、resize/dispose、能力报告 |
|
|
27
|
+
| `tests/plugin.test.ts` | 资产扫描、未解析资源、模块过滤、WebGPU 告警、manifest 输出 |
|
|
28
|
+
| `tests/image-events.test.ts` | 图片原生 `onload`/`onerror` → 合成事件桥接、`decode()` settle、宿主不可拦截时的 `warnOnce` 去重 |
|
|
29
|
+
| `tests/event-dispatch.test.ts` | 监听器 `this`、`event.target` / `currentTarget` 指向宿主元素(含 three `ImageLoader` 取图场景)、`event.target` 不暴露内部监听表 |
|
|
30
|
+
| `tests/capabilities.test.ts` | 离屏优先 / 无离屏 API 时不兜底 / 主画布回退 / 无法探测返回 `undefined`、`webgl2Source` 三态、回退拿到任一候选上屏画布时按身份放弃(含宿主显式传 `canvas` 的组合) |
|
|
31
|
+
| `tests/scope.test.ts` | 未初始化占位作用域:环境全局读作 `undefined`、`typeof window.document` 不抛、真实 API 仍抛可读错误、早读被 `createRuntime()` 点名一次 |
|
|
32
|
+
| `tests/helpers/mock-wx.ts` | 可注入的 `wx` 模拟器(`__setSize`、`__touch`、`__canvases`、`__images`) |
|
|
33
|
+
|
|
34
|
+
**新功能必须带测试**。写测试时优先用 `createMockWx()` 注入,不要在测试里依赖真实 `wx` 或浏览器 DOM。
|
|
35
|
+
|
|
36
|
+
## 9.3 构建产物
|
|
37
|
+
|
|
38
|
+
`tsup.config.ts` 有两套配置:
|
|
39
|
+
|
|
40
|
+
| 配置 | 目标 | 输出 |
|
|
41
|
+
| --- | --- | --- |
|
|
42
|
+
| runtime | `es2019` / `platform: 'neutral'` / splitting / dts | `dist/index.js`、`dist/core/index.js`、`dist/scope.js`、`dist/polyfills/index.js`、`dist/platforms/*.js` + 共享 chunk |
|
|
43
|
+
| build tooling | `node18` / `platform: 'node'` / 不 splitting / dts | `dist/build/vite.js`、`dist/build/rollup.js` |
|
|
44
|
+
|
|
45
|
+
要点:
|
|
46
|
+
|
|
47
|
+
- `es2019` 让 esbuild 降级可选链与空值合并,减少开发者工具的语法报错。
|
|
48
|
+
- `three` 被标记为 `external`,永远不会进适配层产物。
|
|
49
|
+
- `sideEffects` 只声明平台入口文件,保证 tree-shaking 不误删必要的初始化。
|
|
50
|
+
- `.d.ts` 由 tsup/dts 生成,`package.json` 的 `exports` 逐个子路径指向它们。
|
|
51
|
+
|
|
52
|
+
构建后冒烟:
|
|
53
|
+
|
|
54
|
+
```bash
|
|
55
|
+
node --input-type=module -e "
|
|
56
|
+
import { rewriteGlobals } from './dist/build/rollup.js';
|
|
57
|
+
import { miniThree } from './dist/build/vite.js';
|
|
58
|
+
import { createWeChatGameRuntime } from './dist/index.js';
|
|
59
|
+
console.log(typeof rewriteGlobals, typeof miniThree, typeof createWeChatGameRuntime);
|
|
60
|
+
"
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
## 9.4 建议的 CI 流程
|
|
64
|
+
|
|
65
|
+
```yaml
|
|
66
|
+
# .github/workflows/ci.yml(示意)
|
|
67
|
+
name: ci
|
|
68
|
+
on: [push, pull_request]
|
|
69
|
+
jobs:
|
|
70
|
+
check:
|
|
71
|
+
runs-on: ubuntu-latest
|
|
72
|
+
steps:
|
|
73
|
+
- uses: actions/checkout@v4
|
|
74
|
+
- uses: actions/setup-node@v4
|
|
75
|
+
with: { node-version: 20 }
|
|
76
|
+
- run: npm ci
|
|
77
|
+
- run: npm run check
|
|
78
|
+
- name: Verify examples typecheck
|
|
79
|
+
run: |
|
|
80
|
+
cd examples/wechat-minigame && npm ci && npx tsc --noEmit -p tsconfig.json
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
额外建议:
|
|
84
|
+
|
|
85
|
+
- 在 CI 中打印 `plugin.api.report()`,把 `parseFailures` / `missingAssets` 作为质量门禁(允许白名单)。
|
|
86
|
+
- 建立回归用例集:按 controls / loaders / postprocessing / 动画 / 物理分类,每个类别挑选若干 three 官方示例场景,用 `examples/` 的三种平台工程跑通,结果写进 `docs/11-compat-matrix.md`。
|
|
87
|
+
|
|
88
|
+
## 9.5 发布到 npm
|
|
89
|
+
|
|
90
|
+
### 9.5.1 发布前检查
|
|
91
|
+
|
|
92
|
+
```bash
|
|
93
|
+
npm run check # typecheck + 71 例测试 + tsup 构建
|
|
94
|
+
npm run release:check # npm pack --dry-run --json,看将要发布的文件清单
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
`package.json` 已配置 `prepublishOnly: "npm run clean && npm run check"`,`npm publish` 会自动清空 `dist/` 并跑一次完整构建与测试,既不会把未构建的产物发出去,也不会带入历史 hash chunk。发布前确认:
|
|
98
|
+
|
|
99
|
+
- `files` 白名单只包含 `dist/`、`README.md`、`AGENTS.md`、`llms.txt`、`docs/`(0.1.3 实测 74 个文件、解包 644 KB、tarball 182 KB)。体积主要是 `docs/` 的 Markdown 与 `dist/` 的 `.d.ts`,两者都压缩率极高,tarball 增量很小。
|
|
100
|
+
- `exports` 里每个子路径的 `.js` 与 `.d.ts` 都存在。
|
|
101
|
+
- `CHANGELOG.md` 已补上本次版本条目。
|
|
102
|
+
- `docs/04-api-reference.md` 与 `package.json exports` 一致;`docs/03-module-map.md` 与文件树一致。
|
|
103
|
+
- `docs/11-compat-matrix.md` 已登记验证过的 three / 基础库版本。
|
|
104
|
+
|
|
105
|
+
`package.json` 已配置 `repository` / `homepage` / `bugs`,npm 包页面会展示源码入口与 issue 链接。若仓库迁移,同步修改这三个字段后再发布。
|
|
106
|
+
|
|
107
|
+
### 9.5.2 准备 npm 账号
|
|
108
|
+
|
|
109
|
+
1. 在 [npmjs.com](https://www.npmjs.com/signup) 注册账号,并在 **Account → 2FA** 开启双因素认证。
|
|
110
|
+
2. 检查包名是否可用(发布前再查一次,避免被占用):
|
|
111
|
+
|
|
112
|
+
```bash
|
|
113
|
+
npm view mini-three-adapter version
|
|
114
|
+
# 404 Not Found = 可用
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
3. 登录:
|
|
118
|
+
|
|
119
|
+
```bash
|
|
120
|
+
npm login # 浏览器授权,最简单
|
|
121
|
+
npm whoami # 确认已登录
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
CI 或非交互环境用 granular access token(权限选 `Read and write`,并限定到该包):
|
|
125
|
+
|
|
126
|
+
```bash
|
|
127
|
+
# 不要把这个文件提交到仓库
|
|
128
|
+
echo "//registry.npmjs.org/:_authToken=${NPM_TOKEN}" > .npmrc
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
### 9.5.3 本地演练(推荐先做)
|
|
132
|
+
|
|
133
|
+
生成一个真实 tarball,在干净目录里装一次,确认子路径导入都能解析:
|
|
134
|
+
|
|
135
|
+
```bash
|
|
136
|
+
npm pack # 得到 mini-three-adapter-0.1.0.tgz
|
|
137
|
+
mkdir -p /tmp/m3-smoke && cd /tmp/m3-smoke
|
|
138
|
+
npm init -y && npm pkg set type=module
|
|
139
|
+
npm i /path/to/mini-three-adapter-0.1.0.tgz three
|
|
140
|
+
node --input-type=module -e "
|
|
141
|
+
import { createWeChatGameRuntime } from 'mini-three-adapter/wechat-game';
|
|
142
|
+
import { createWeChatMiniProgramRuntime } from 'mini-three-adapter/wechat-miniprogram';
|
|
143
|
+
import miniThree from 'mini-three-adapter/vite';
|
|
144
|
+
import { getActiveScope } from 'mini-three-adapter/scope';
|
|
145
|
+
console.log(typeof createWeChatGameRuntime, typeof createWeChatMiniProgramRuntime, typeof miniThree, typeof getActiveScope);
|
|
146
|
+
"
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
> 未登录也能执行这一步。`npm pack` 生成的文件记得从仓库目录删掉,或把它加进 `.gitignore`。
|
|
150
|
+
|
|
151
|
+
### 9.5.4 正式发布
|
|
152
|
+
|
|
153
|
+
```bash
|
|
154
|
+
npm publish --access public
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
`publishConfig.access` 已设为 `public`,`--access public` 可省略。执行后 `prepublishOnly` 会自动清空 `dist/` 并跑 `npm run check`。
|
|
158
|
+
|
|
159
|
+
**npm 的版本号不可覆盖**:同一个 `0.1.0` 只能发一次,之后每次改动都要先升版本再发。24 小时内可以 `npm unpublish <pkg>@<version>` 撤回,超过时间就不能删了;公开包一旦被他人依赖,撤回会影响别人,尽量不要依赖这个能力。
|
|
160
|
+
|
|
161
|
+
### 9.5.5 发布后验证
|
|
162
|
+
|
|
163
|
+
```bash
|
|
164
|
+
npm view mini-three-adapter version
|
|
165
|
+
npm view mini-three-adapter exports --json
|
|
166
|
+
```
|
|
167
|
+
|
|
168
|
+
在任意新项目里执行 `npm i mini-three-adapter three`,再跑一遍 9.5.3 的 import 冒烟。CDN 会在发布后自动可用(如 `https://unpkg.com/mini-three-adapter/`),但小游戏构建走本地 node_modules,不依赖 CDN。
|
|
169
|
+
|
|
170
|
+
### 9.5.6 后续版本
|
|
171
|
+
|
|
172
|
+
```bash
|
|
173
|
+
# 修 bug
|
|
174
|
+
npm version patch && npm publish
|
|
175
|
+
# 新增向后兼容能力
|
|
176
|
+
npm version minor && npm publish
|
|
177
|
+
# 破坏性变更(0.x 阶段也用 minor 时要写进 CHANGELOG)
|
|
178
|
+
npm version major && npm publish
|
|
179
|
+
```
|
|
180
|
+
|
|
181
|
+
`npm version` 会自动改 `package.json`、生成 git tag(若已 `git init`)。每次发布重复 9.5.1 的检查。
|
|
182
|
+
|
|
183
|
+
CI 自动发布(`.github/workflows/publish.yml`)要点:用 `actions/setup-node` 配置 `registry-url`,把 `NPM_TOKEN` 放在仓库 Secrets 里,在 `npm ci && npm run check` 之后执行 `npm publish --provenance --access public`。`--provenance` 会在 npm 页面生成来源证明,需要仓库为 public 且 workflow 具备 `id-token: write` 权限。
|
|
184
|
+
|
|
185
|
+
### 9.5.7 其他分发方式
|
|
186
|
+
|
|
187
|
+
| 方式 | 适用场景 |
|
|
188
|
+
| --- | --- |
|
|
189
|
+
| `npm pack` 把 `.tgz` 直接发给同事 | 还没决定公开,或需要在隔离环境试用;对方 `npm i ./xxx.tgz` |
|
|
190
|
+
| `"mini-three-adapter": "file:../.."` | 本机多个项目复用同一份源码 |
|
|
191
|
+
| 私有 registry(Verdaccio / GitHub Packages) | 只给团队内部使用,不想发到公共 npm |
|
|
192
|
+
| `npm link` | 开发期实时联调,改源码立刻生效 |
|
|
193
|
+
|
|
194
|
+
发布到公共 npm 之后,业务项目只需 `npm i mini-three-adapter three`,`examples/*/package.json` 里的 `workspace:*` 改成 `"^0.1.0"` 即可。
|
|
195
|
+
|
|
196
|
+
## 9.6 版本策略
|
|
197
|
+
|
|
198
|
+
- 遵循语义化版本;`0.x` 阶段 minor 可含破坏性变更,但必须在 CHANGELOG 与接入文档里写明。
|
|
199
|
+
- `three` 是 optional peer,`>=0.163.0`(WebGL2 门槛)。three 大版本升级时,重点回归 `DEFAULT_GLOBAL_NAMES` 与 `patchElement` 的属性集合。
|
|
200
|
+
- 微信基础库能力变化只影响 `capabilities.ts` / `wechat-common.ts` / `assets.ts`,不应扩散到 `core/`。
|
|
201
|
+
|
|
202
|
+
## 9.7 真机验收清单(发布前)
|
|
203
|
+
|
|
204
|
+
- [ ] iOS / Android 各一台,WebGL2 正常出图
|
|
205
|
+
- [ ] 多指缩放/旋转(OrbitControls)不卡死,`touchcancel` 后指针计数归零
|
|
206
|
+
- [ ] 横竖屏切换后 `resize` 生效,画面不变形
|
|
207
|
+
- [ ] 前后台切换后帧循环恢复
|
|
208
|
+
- [ ] DRACO / KTX2 资源加载(含分包预下载 Worker)
|
|
209
|
+
- [ ] `runtime.dispose()` 后无残留监听、无内存持续增长
|
|
210
|
+
- [ ] `runtime.report()` 无 WebGL2 告警
|
package/docs/10-ai-playbook.md
CHANGED
|
@@ -109,7 +109,9 @@
|
|
|
109
109
|
| 「在运行时把 `WebGLRenderer.render` 猴补丁一下清深度」 | 隐式、不可观测、与 three 版本强耦合 | 应用层显式 `renderer.clearDepth()`,写进文档 |
|
|
110
110
|
| 「把 three 一起打包进适配层省事」 | 体积、版本冲突、许可 | `three` 保持 optional peer + external |
|
|
111
111
|
| 「WebGPU 不支持就 `try/catch` 回退」 | 小游戏根本没有 WebGPU 且 NodeMaterial 无 WebGL 等价物 | 插件 `webgpu` 策略 + 使用 WebGL 构建目标 |
|
|
112
|
-
| 「能力探测时直接 `wx.createCanvas().getContext('webgl2')`」 | 偷走唯一上屏画布、且用默认属性抢先建上下文 | 用 `wx.createOffscreenCanvas()
|
|
112
|
+
| 「能力探测时直接 `wx.createCanvas().getContext('webgl2')`」 | 偷走唯一上屏画布、且用默认属性抢先建上下文 | 用 `wx.createOffscreenCanvas()`;按 ADR-0007 显式回退,传 `reservedCanvases` 做身份守卫,离屏 API 缺失时干脆不兜底(ADR-0008) |
|
|
113
|
+
| 「让占位作用域对所有键都返回 `undefined`,省得报错」 | 真实 API 误读会在几帧之后、无关的栈上炸开 | 只有 `document`/`navigator`/`screen`/`location`/`history` 返回 `undefined`,其余仍抛错(ADR-0009) |
|
|
114
|
+
| 「`patchEventTarget` 把方法绑到内部载体就够了」 | 监听器的 `this`、`event.target` 都变成载体,依赖「`this` 是元素」的库(three `ImageLoader`)会拿到没有像素的空壳 | `dispatchEvent` 统一转发到 `inlineHost`(宿主元素) |
|
|
113
115
|
|
|
114
116
|
## 10.6 机器可读的报告(给自动化 / CI 用)
|
|
115
117
|
|
package/docs/11-compat-matrix.md
CHANGED
|
@@ -28,8 +28,9 @@
|
|
|
28
28
|
| --- | --- | --- | --- |
|
|
29
29
|
| `wx.createCanvas` / `getContext('webgl2')` | — | ✅ | [渲染文档](https://developers.weixin.qq.com/minigame/dev/guide/base-ability/render.html) |
|
|
30
30
|
| 唯一上屏画布规则 | — | ✅ | `getScreenCanvas()` 单次缓存 |
|
|
31
|
-
| `wx.createOffscreenCanvas` | 2.7.0(小程序)/ 小游戏同期 | ✅ |
|
|
31
|
+
| `wx.createOffscreenCanvas` | 2.7.0(小程序)/ 小游戏同期 | ✅ | 离屏画布首选来源;**API 完全不存在时不做回退**,退回版本推断([ADR-0008](./adr/0008-probe-fallback-boundary.md)) |
|
|
32
32
|
| WebGL2 能力判定 | — | ✅ | 顺序:离屏实测 → 主画布实测 → 按基础库版本推断;`capabilities.webgl2Source` 标明来源,`'inferred'` 表示未实测 |
|
|
33
|
+
| 回退探测与上屏画布的身份冲突 | — | ✅ | `probeContext` 接收 `reservedCanvases`(本次画布 + 缓存画布 + `GameGlobal.screencanvas` + `globalThis.canvas`),`createCanvas()` 返回其中任一对象即放弃、不 `getContext`(含宿主显式传 `canvas` 的窄口子) |
|
|
33
34
|
| `wx.getWindowInfo` | 较新版本 | ✅ | 回退 `getSystemInfoSync` |
|
|
34
35
|
| `wx.onWindowResize` | — | 🟡 | 不可用时告警,需手动 `runtime.resize()` |
|
|
35
36
|
| `WXWebAssembly` | 2.13.0(Worker 内 2.15.0) | 🟡 | [官方文档](https://developers.weixin.qq.com/minigame/dev/guide/performance/perf-webassembly.html);插件按引用拷贝 wasm |
|
|
@@ -81,7 +82,7 @@
|
|
|
81
82
|
| `loader_*` | GLTF / DRACO / KTX2 / OBJ / FBX | ⬜ 未回归 | 需配置 decoder 路径与分包 |
|
|
82
83
|
| `postprocessing_*` | EffectComposer / bloom / SSAO | ⬜ 未回归 | 注意深度缓冲与 render target 尺寸 |
|
|
83
84
|
| `animation_*` / `physics_*` | 骨骼动画 / wasm 物理 | ⬜ 未回归 | 涉及 wasm 资源预下载 |
|
|
84
|
-
| 基础渲染 | `examples/wechat-minigame`、`wechat-miniprogram`、`h5` | ✅ 单元级 |
|
|
85
|
+
| 基础渲染 | `examples/wechat-minigame`、`wechat-miniprogram`、`h5` | ✅ 单元级 | 63 个 Vitest 用例覆盖画布、事件、作用域、插件 |
|
|
85
86
|
|
|
86
87
|
每回归一条,在本表追加:`场景 id | three 版本 | 基础库 | 设备 | 结果 | 失败原因 | 新增 polyfill`。
|
|
87
88
|
|
|
@@ -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,13 +18,15 @@
|
|
|
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
|
+
4. `detectCapabilities` 把 `undefined` 当作未知,退回基础库版本启发式(`>= 2.20.0`),并用新增的 `capabilities.webgl2Source`(`'probe' | 'inferred' | 'override'`)标明来源;此时 `warnOnce` 提示一次。
|
|
23
24
|
|
|
24
25
|
## 理由
|
|
25
26
|
|
|
26
27
|
- 第二次 `wx.createCanvas()` 在微信里**保证**得到离屏画布(上屏画布只有第一次调用才返回),这与 `createOffscreenCanvasRaw` 里已有的兜底是同一机制,不违反「只有一个上屏画布」的本意:本意是**不要抢走那块上屏画布**,而不是禁用该 API。
|
|
27
|
-
-
|
|
28
|
+
- 但「保证」有一个缺口:宿主若通过 `GameGlobal.screencanvas` 预置了上屏画布,`getScreenCanvas()` 会直接取用它、并没有消耗那次「首次调用」。此时回退的 `createCanvas()` 仍可能把同一块上屏画布交回来,`getContext('webgl2')` 会抢先建上下文,紧接着的 `WEBGL_lose_context.loseContext()` 把它废掉——表现为黑屏且不报错,极难排查。身份比对是唯一可靠的判据:不看版本、不看 API 是否存在,只看返回的是不是那块画布。
|
|
29
|
+
- 因此回退**必须**在上屏画布已经解析之后调用,并且由调用方显式 opt-in(`allowCanvasFallback`)。`wechat-game` 的 `getScreenCanvas()` 就在探测之前,所以传 `true` 并附带 `screenCanvas`;`wechat-miniprogram` 的画布节点来自选择器查询,不能这样探测,保持不传。
|
|
28
30
|
- `webgl2Source` 让「这份报告里的 `false` 到底是实测还是猜测」一眼可见,这是本次缺陷里最伤排查成本的部分。
|
|
29
31
|
|
|
30
32
|
## 后果
|
|
@@ -51,5 +53,9 @@
|
|
|
51
53
|
|
|
52
54
|
## 验证方式
|
|
53
55
|
|
|
54
|
-
- `tests/capabilities.test.ts`:离屏优先且不碰 `createCanvas
|
|
56
|
+
- `tests/capabilities.test.ts`:离屏优先且不碰 `createCanvas`、离屏答不出时回退、离屏返回 false 而主画布返回 true、完全无法探测时返回 `undefined`、回退拿到上屏画布时按身份放弃(`getContext` 零调用)、`webgl2Source` 三种取值,以及 `GameGlobal.screencanvas` 预置时 `createWeChatGameBinding` 不触碰屏画布。
|
|
55
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`:正常路径的能力报告不受影响。
|