mini-three-adapter 0.1.6 → 0.1.8

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 (68) hide show
  1. package/AGENTS.md +85 -85
  2. package/LICENSE +21 -21
  3. package/README.md +159 -159
  4. package/dist/build/rollup.d.ts +2 -2
  5. package/dist/build/rollup.js.map +1 -1
  6. package/dist/build/vite.d.ts +2 -2
  7. package/dist/build/vite.js.map +1 -1
  8. package/dist/{chunk-MSP7V7KM.js → chunk-DQH3YRGN.js} +3 -3
  9. package/dist/chunk-DQH3YRGN.js.map +1 -0
  10. package/dist/{chunk-35XVAVDB.js → chunk-J34MD3IL.js} +2 -2
  11. package/dist/chunk-J34MD3IL.js.map +1 -0
  12. package/dist/{chunk-LCJNTN6F.js → chunk-LAVHSWBU.js} +8 -5
  13. package/dist/chunk-LAVHSWBU.js.map +1 -0
  14. package/dist/{chunk-WYUHMKUM.js → chunk-RYWYBOYO.js} +43 -4
  15. package/dist/chunk-RYWYBOYO.js.map +1 -0
  16. package/dist/{chunk-6Y4MKIJL.js → chunk-SXQUZI22.js} +4 -4
  17. package/dist/chunk-SXQUZI22.js.map +1 -0
  18. package/dist/{chunk-TDVL2OAV.js → chunk-TPMMZFHW.js} +123 -58
  19. package/dist/chunk-TPMMZFHW.js.map +1 -0
  20. package/dist/{chunk-L4QZ5SP6.js → chunk-YPG3QUYK.js} +4 -4
  21. package/dist/chunk-YPG3QUYK.js.map +1 -0
  22. package/dist/core/index.d.ts +9 -3
  23. package/dist/core/index.js +3 -3
  24. package/dist/index.d.ts +2 -2
  25. package/dist/index.js +7 -7
  26. package/dist/platforms/browser.d.ts +2 -2
  27. package/dist/platforms/browser.js +4 -4
  28. package/dist/platforms/wechat-game.d.ts +2 -2
  29. package/dist/platforms/wechat-game.js +5 -5
  30. package/dist/platforms/wechat-miniprogram.d.ts +2 -2
  31. package/dist/platforms/wechat-miniprogram.js +5 -5
  32. package/dist/{plugin-core-BuqW9C-L.d.ts → plugin-core-CBOr1cyv.d.ts} +15 -4
  33. package/dist/polyfills/index.d.ts +1 -1
  34. package/dist/polyfills/index.js +1 -1
  35. package/dist/{runtime-BrHExTjl.d.ts → runtime-C8_xIlDM.d.ts} +29 -1
  36. package/dist/scope.d.ts +1 -1
  37. package/dist/scope.js +1 -1
  38. package/dist/{types-X_5SJh4y.d.ts → types-DOoJ7noL.d.ts} +13 -1
  39. package/docs/01-design-principles.md +105 -105
  40. package/docs/03-module-map.md +99 -99
  41. package/docs/04-api-reference.md +310 -304
  42. package/docs/05-build-plugin.md +176 -176
  43. package/docs/06-platform-notes.md +8 -4
  44. package/docs/07-integration-guide.md +226 -225
  45. package/docs/08-extension-guide.md +101 -101
  46. package/docs/09-testing-and-release.md +212 -211
  47. package/docs/11-compat-matrix.md +100 -100
  48. package/docs/README.md +41 -41
  49. package/docs/adr/0001-scoped-globals.md +41 -41
  50. package/docs/adr/0002-unified-runtime-lifecycle.md +40 -40
  51. package/docs/adr/0003-ast-rewrite.md +51 -51
  52. package/docs/adr/0004-in-place-patching.md +42 -42
  53. package/docs/adr/0005-webgl2-only.md +44 -44
  54. package/docs/adr/0006-zero-three-dependency.md +43 -43
  55. package/docs/adr/0007-capability-probe-fallback.md +61 -61
  56. package/docs/adr/0008-probe-fallback-boundary.md +56 -56
  57. package/docs/adr/0009-placeholder-scope-environment-globals.md +69 -69
  58. package/docs/adr/0010-native-event-target-boundary.md +82 -0
  59. package/docs/adr/0011-host-callback-slot-bridging.md +45 -0
  60. package/docs/adr/README.md +33 -31
  61. package/package.json +126 -125
  62. package/dist/chunk-35XVAVDB.js.map +0 -1
  63. package/dist/chunk-6Y4MKIJL.js.map +0 -1
  64. package/dist/chunk-L4QZ5SP6.js.map +0 -1
  65. package/dist/chunk-LCJNTN6F.js.map +0 -1
  66. package/dist/chunk-MSP7V7KM.js.map +0 -1
  67. package/dist/chunk-TDVL2OAV.js.map +0 -1
  68. package/dist/chunk-WYUHMKUM.js.map +0 -1
@@ -1,42 +1,42 @@
1
- # ADR-0004 · 就地 patch 画布,不改原型、不用 Proxy
2
-
3
- - 状态:Accepted
4
- - 日期:2026-11-08
5
- - 影响模块:`src/core/element.ts`、`src/core/canvas.ts`、`src/core/image.ts`、`src/core/dom.ts`
6
-
7
- ## 背景
8
-
9
- 宿主内部按对象身份保存画布与图片的校验数据,任何「新建一个类实例包装」「用 Proxy 拦截」「克隆对象」的做法都会让这些校验失效。因此 three 需要的 DOM 属性与方法必须直接补到宿主返回的那个对象上。
10
-
11
- 同时,three 与 addons 会用 `instanceof HTMLCanvasElement` 之类的判定选择代码分支,补丁还需要让这些判定成立。修改对象原型虽然能达到目的,但在 JSC/V8 上是明确的去优化操作,且会与其他库对原型的修改互相覆盖。
12
-
13
- ## 决策
14
-
15
- 1. **保持对象身份**:所有补丁都是对 `wx` 返回的那个对象执行 `Object.defineProperty`。
16
- 2. **禁止** `new Proxy(...)` 包装、禁止克隆对象、禁止 `Object.setPrototypeOf`。
17
- 3. `instanceof` 用 `createMockClass()` 生成的 `Symbol.hasInstance` + `WeakSet` 注册表实现,补丁时把对象注册进对应的 shim。
18
- 4. 需要 `new SomeCtor()` 的场景(如 `OffscreenCanvas`)提供真正返回平台对象的构造器函数。
19
- 5. `style.width/height`、`clientWidth/Height`、`getBoundingClientRect()` 用闭包 `rect` 的响应式 getter,`updateRect()` 一处更新全处生效。
20
-
21
- ## 理由
22
-
23
- - 宿主校验依赖对象身份;任何包装都会破坏它。
24
- - `Object.setPrototypeOf` 是去优化操作,而且会与其他补丁冲突。
25
- - `Symbol.hasInstance` 是标准机制,精确且零副作用;`WeakSet` 不阻止 GC。
26
-
27
- ## 后果
28
-
29
- - 正面:兼容宿主校验、性能更好、可与其他补丁共存;身份不变也让缓存/Map 键稳定。
30
- - 负面:每个新 DOM 属性都要显式补;three 升级时可能发现新的属性缺失(这是 `docs/11` 升级检查项)。
31
- - 负面:`instanceof` 只对注册过的对象成立;业务自己 `new` 出来的假对象不会被识别(可接受)。
32
- - 风险:`defineProperty` 可能遇到宿主不可配置属性 → `normalizeContext()` 里对 `ctx.canvas` 的赋值用 try/catch 保护。
33
-
34
- ## 被否决的备选方案
35
-
36
- - 继承/代理包装:破坏身份,否决。
37
- - 改原型:去优化 + 冲突风险,否决。
38
- - 只靠 `Object.defineProperty` 不做 `instanceof`:three 与 addons 会用 `instanceof HTMLCanvasElement` 分支,否决。
39
-
40
- ## 验证方式
41
-
42
- `tests/runtime.test.ts`:「patches the canvas in place」「caches WebGL2 context identity and satisfies instanceof」断言 `runtime.canvas === wx.__canvases[0]` 且 `instanceof` 成立。
1
+ # ADR-0004 · 就地 patch 画布,不改原型、不用 Proxy
2
+
3
+ - 状态:Accepted
4
+ - 日期:2026-11-08
5
+ - 影响模块:`src/core/element.ts`、`src/core/canvas.ts`、`src/core/image.ts`、`src/core/dom.ts`
6
+
7
+ ## 背景
8
+
9
+ 宿主内部按对象身份保存画布与图片的校验数据,任何「新建一个类实例包装」「用 Proxy 拦截」「克隆对象」的做法都会让这些校验失效。因此 three 需要的 DOM 属性与方法必须直接补到宿主返回的那个对象上。
10
+
11
+ 同时,three 与 addons 会用 `instanceof HTMLCanvasElement` 之类的判定选择代码分支,补丁还需要让这些判定成立。修改对象原型虽然能达到目的,但在 JSC/V8 上是明确的去优化操作,且会与其他库对原型的修改互相覆盖。
12
+
13
+ ## 决策
14
+
15
+ 1. **保持对象身份**:所有补丁都是对 `wx` 返回的那个对象执行 `Object.defineProperty`。
16
+ 2. **禁止** `new Proxy(...)` 包装、禁止克隆对象、禁止 `Object.setPrototypeOf`。
17
+ 3. `instanceof` 用 `createMockClass()` 生成的 `Symbol.hasInstance` + `WeakSet` 注册表实现,补丁时把对象注册进对应的 shim。
18
+ 4. 需要 `new SomeCtor()` 的场景(如 `OffscreenCanvas`)提供真正返回平台对象的构造器函数。
19
+ 5. `style.width/height`、`clientWidth/Height`、`getBoundingClientRect()` 用闭包 `rect` 的响应式 getter,`updateRect()` 一处更新全处生效。
20
+
21
+ ## 理由
22
+
23
+ - 宿主校验依赖对象身份;任何包装都会破坏它。
24
+ - `Object.setPrototypeOf` 是去优化操作,而且会与其他补丁冲突。
25
+ - `Symbol.hasInstance` 是标准机制,精确且零副作用;`WeakSet` 不阻止 GC。
26
+
27
+ ## 后果
28
+
29
+ - 正面:兼容宿主校验、性能更好、可与其他补丁共存;身份不变也让缓存/Map 键稳定。
30
+ - 负面:每个新 DOM 属性都要显式补;three 升级时可能发现新的属性缺失(这是 `docs/11` 升级检查项)。
31
+ - 负面:`instanceof` 只对注册过的对象成立;业务自己 `new` 出来的假对象不会被识别(可接受)。
32
+ - 风险:`defineProperty` 可能遇到宿主不可配置属性 → `normalizeContext()` 里对 `ctx.canvas` 的赋值用 try/catch 保护。
33
+
34
+ ## 被否决的备选方案
35
+
36
+ - 继承/代理包装:破坏身份,否决。
37
+ - 改原型:去优化 + 冲突风险,否决。
38
+ - 只靠 `Object.defineProperty` 不做 `instanceof`:three 与 addons 会用 `instanceof HTMLCanvasElement` 分支,否决。
39
+
40
+ ## 验证方式
41
+
42
+ `tests/runtime.test.ts`:「patches the canvas in place」「caches WebGL2 context identity and satisfies instanceof」断言 `runtime.canvas === wx.__canvases[0]` 且 `instanceof` 成立。
@@ -1,44 +1,44 @@
1
- # ADR-0005 · WebGL2 优先,不静默降级到 WebGL1
2
-
3
- - 状态:Accepted
4
- - 日期:2026-11-08
5
- - 影响模块:`src/core/capabilities.ts`、`src/core/canvas.ts`、`src/core/dom.ts`、`src/platforms/wechat-common.ts`、`src/build/plugin-core.ts`
6
-
7
- ## 背景
8
-
9
- - three.js r163 起 `WebGLRenderer` 不再支持 WebGL1(见 [Migration Guide](https://github.com/mrdoob/three.js/wiki/Migration-Guide))。
10
- - 微信官方文档在 iOS 高性能+ 模式里明确「建议使用 WebGL2、内存压力大的游戏开启」([iOS 高性能模式](https://developers.weixin.qq.com/minigame/dev/guide/game-engine/unity-webgl-transform/Design/iOSOptimization.html))。
11
- - 三方库里存在 `new WebGLRenderer()` 不传 canvas 的写法,此时 `document.createElement('canvas')` 产出的默认上下文类型直接决定渲染器能否创建。
12
- - 宿主规定首次 `wx.createCanvas()` 是唯一上屏画布,能力探测不能碰它。
13
- - 小游戏环境没有 WebGPU,而 three 的 `three/webgpu` 入口依赖 NodeMaterial / TSL,无法用重命名的方式退回 WebGL。
14
-
15
- ## 决策
16
-
17
- 1. `defaultContextType` 默认 `'webgl2'`;`document.createElement('canvas')` 优先 `wx.createOffscreenCanvas({ type: 'webgl2' })`,失败降级 2d **并告警**。
18
- 2. `probeContext()` 只用 `wx.createOffscreenCanvas()` 探测 WebGL2,探测后主动 `WEBGL_lose_context` 释放;绝不调用 `wx.createCanvas()`。
19
- 3. `capabilities.webgl2 === false` 时发出明确告警 + 能力报告,**不静默切到 WebGL1**。
20
- 4. WebGPU:插件对 `from 'three/webgpu'` 默认告警,`webgpu: 'rewrite'` 是有损的显式 opt-in。
21
- 5. 已知宿主 WebGL 差异(`getExtension` 返回数字、`drawingBufferWidth`)由 `normalizeWebGL: true` 显式修复,可关闭。
22
-
23
- ## 理由
24
-
25
- - three 要求 WebGL2,静默降级只会把错误推迟到渲染阶段,不如在启动时给出可操作信息。
26
- - 探测不占用上屏画布是硬性约束(ADR 不变量 #1)。
27
- - 把「平台差异补丁」做成可开关、可观测,而不是在运行时改写渲染器行为。
28
-
29
- ## 后果
30
-
31
- - 正面:启动即可诊断环境问题;与 three r163+ / 官方高性能+ 建议一致。
32
- - 负面:极老设备 / 极旧基础库无法运行(明确不支持,见 `docs/11`)。
33
- - 负面:WebGPU 生态项目必须改用 WebGL 构建目标(写进 `docs/05` / `docs/11`)。
34
- - 风险:`createOffscreenCanvas({type:'webgl2'})` 在个别基础库上抛错 → `createOffscreenCanvasRaw()` 已带 catch 与降级日志。
35
-
36
- ## 被否决的备选方案
37
-
38
- - 运行时自动检测 WebGL2 → 回退 WebGL1:three 不支持,否决。
39
- - 用 `wx.createCanvas().getContext('webgl2')` 探测:会占用上屏画布,否决。
40
- - 打包定制版 three 内核:违反「零 three 依赖 / 不 fork」边界,否决。
41
-
42
- ## 验证方式
43
-
44
- `tests/runtime.test.ts` 覆盖 `getContext('webgl2')` 缓存与 `instanceof`;`docs/09` 真机清单要求 iOS/Android 各一台验证 WebGL2 出图。
1
+ # ADR-0005 · WebGL2 优先,不静默降级到 WebGL1
2
+
3
+ - 状态:Accepted
4
+ - 日期:2026-11-08
5
+ - 影响模块:`src/core/capabilities.ts`、`src/core/canvas.ts`、`src/core/dom.ts`、`src/platforms/wechat-common.ts`、`src/build/plugin-core.ts`
6
+
7
+ ## 背景
8
+
9
+ - three.js r163 起 `WebGLRenderer` 不再支持 WebGL1(见 [Migration Guide](https://github.com/mrdoob/three.js/wiki/Migration-Guide))。
10
+ - 微信官方文档在 iOS 高性能+ 模式里明确「建议使用 WebGL2、内存压力大的游戏开启」([iOS 高性能模式](https://developers.weixin.qq.com/minigame/dev/guide/game-engine/unity-webgl-transform/Design/iOSOptimization.html))。
11
+ - 三方库里存在 `new WebGLRenderer()` 不传 canvas 的写法,此时 `document.createElement('canvas')` 产出的默认上下文类型直接决定渲染器能否创建。
12
+ - 宿主规定首次 `wx.createCanvas()` 是唯一上屏画布,能力探测不能碰它。
13
+ - 小游戏环境没有 WebGPU,而 three 的 `three/webgpu` 入口依赖 NodeMaterial / TSL,无法用重命名的方式退回 WebGL。
14
+
15
+ ## 决策
16
+
17
+ 1. `defaultContextType` 默认 `'webgl2'`;`document.createElement('canvas')` 优先 `wx.createOffscreenCanvas({ type: 'webgl2' })`,失败降级 2d **并告警**。
18
+ 2. `probeContext()` 只用 `wx.createOffscreenCanvas()` 探测 WebGL2,探测后主动 `WEBGL_lose_context` 释放;绝不调用 `wx.createCanvas()`。
19
+ 3. `capabilities.webgl2 === false` 时发出明确告警 + 能力报告,**不静默切到 WebGL1**。
20
+ 4. WebGPU:插件对 `from 'three/webgpu'` 默认告警,`webgpu: 'rewrite'` 是有损的显式 opt-in。
21
+ 5. 已知宿主 WebGL 差异(`getExtension` 返回数字、`drawingBufferWidth`)由 `normalizeWebGL: true` 显式修复,可关闭。
22
+
23
+ ## 理由
24
+
25
+ - three 要求 WebGL2,静默降级只会把错误推迟到渲染阶段,不如在启动时给出可操作信息。
26
+ - 探测不占用上屏画布是硬性约束(ADR 不变量 #1)。
27
+ - 把「平台差异补丁」做成可开关、可观测,而不是在运行时改写渲染器行为。
28
+
29
+ ## 后果
30
+
31
+ - 正面:启动即可诊断环境问题;与 three r163+ / 官方高性能+ 建议一致。
32
+ - 负面:极老设备 / 极旧基础库无法运行(明确不支持,见 `docs/11`)。
33
+ - 负面:WebGPU 生态项目必须改用 WebGL 构建目标(写进 `docs/05` / `docs/11`)。
34
+ - 风险:`createOffscreenCanvas({type:'webgl2'})` 在个别基础库上抛错 → `createOffscreenCanvasRaw()` 已带 catch 与降级日志。
35
+
36
+ ## 被否决的备选方案
37
+
38
+ - 运行时自动检测 WebGL2 → 回退 WebGL1:three 不支持,否决。
39
+ - 用 `wx.createCanvas().getContext('webgl2')` 探测:会占用上屏画布,否决。
40
+ - 打包定制版 three 内核:违反「零 three 依赖 / 不 fork」边界,否决。
41
+
42
+ ## 验证方式
43
+
44
+ `tests/runtime.test.ts` 覆盖 `getContext('webgl2')` 缓存与 `instanceof`;`docs/09` 真机清单要求 iOS/Android 各一台验证 WebGL2 出图。
@@ -1,43 +1,43 @@
1
- # ADR-0006 · 运行时零 `three` 依赖,构建 / 运行严格隔离
2
-
3
- - 状态:Accepted
4
- - 日期:2026-11-08
5
- - 影响模块:`package.json`、`tsup.config.ts`、`src/**`、`docs/03-module-map.md`
6
-
7
- ## 背景
8
-
9
- 适配层如果与某个具体的 three 版本绑定(打包内置 three、替换 three 内部模块、改写渲染器方法),three 升级就必须同步发布适配层,行为也变得难以预测。
10
-
11
- 另一方面,构建插件运行在 Node,运行时代码运行在 JS 引擎。两者若混在同一个 bundle 里,`node:fs` 之类的依赖会被带进小游戏代码包,既增大体积又破坏可移植性。
12
-
13
- ## 决策
14
-
15
- 1. `src/**` **不得 import `three`**;`three` 只是 `optional peerDependency`,且被 tsup 标为 `external`。
16
- 2. 运行时只实现「浏览器环境 shim」,不关心 three 的类、材质、渲染流程。
17
- 3. 所有 three 相关的构建期行为集中在 `src/build/**`,且只做三件事:AST 全局重写、WebGPU 策略、worker/wasm 资产收集;**不改写 three 源码语义**。
18
- 4. 依赖方向固定:`types → scope/polyfills → core → platforms`;`build` 是独立分支,不得 import `core`/`platforms`;`node:fs` 只允许出现在 `build/`。
19
- 5. tsup 两套构建:runtime = `es2019` / `platform: neutral` / splitting / dts;build tooling = `node18` / `platform: node` / 不 splitting。
20
- 6. `es2019` 目标让 esbuild 降级 `?.` / `??`,减少微信开发者工具语法报错。
21
-
22
- ## 理由
23
-
24
- - 适配层与 three 解耦后,three 从 r163 到 r18x 的升级不需要改适配层内核,只需按 `docs/11` 补全局清单 / DOM 属性。
25
- - 构建/运行隔离保证产物体积与可移植性;也便于在 Node 里跑单元测试。
26
- - 不做语义改写 → 行为可预测、可调试,不会在 three 升级后突然失效。
27
-
28
- ## 后果
29
-
30
- - 正面:包体小、版本兼容面宽、可测试、可 tree-shake。
31
- - 负面:某些 loader 的 worker/wasm 需要业务自行 `setDecoderPath()`;插件只负责把资源放进包并生成 manifest。
32
- - 负面:不提供「自动替换 addons 模块」的便利,接入时按 `docs/07` 配置 decoder 路径即可。
33
- - 风险:未来 three 引入依赖原生 Web API 的新模块时,需要按 `docs/08` 补 polyfill(这是常规迭代,不是架构变更)。
34
-
35
- ## 被否决的备选方案
36
-
37
- - fork / 打包 three:体积、版本、许可都不可接受,否决。
38
- - 运行时 monkey-patch `WebGLRenderer`:隐式、脆弱、不可观测,否决。
39
- - 把插件与运行时打成一个包入口:`node:fs` 会进小游戏 bundle,否决。
40
-
41
- ## 验证方式
42
-
43
- `npx tsc --noEmit` + `npx tsup` 产物检查(`dist/index.js` 不含 `node:` 导入);`tests/*` 全程在 Node 中用 mock `wx` 运行,不加载真实 three。
1
+ # ADR-0006 · 运行时零 `three` 依赖,构建 / 运行严格隔离
2
+
3
+ - 状态:Accepted
4
+ - 日期:2026-11-08
5
+ - 影响模块:`package.json`、`tsup.config.ts`、`src/**`、`docs/03-module-map.md`
6
+
7
+ ## 背景
8
+
9
+ 适配层如果与某个具体的 three 版本绑定(打包内置 three、替换 three 内部模块、改写渲染器方法),three 升级就必须同步发布适配层,行为也变得难以预测。
10
+
11
+ 另一方面,构建插件运行在 Node,运行时代码运行在 JS 引擎。两者若混在同一个 bundle 里,`node:fs` 之类的依赖会被带进小游戏代码包,既增大体积又破坏可移植性。
12
+
13
+ ## 决策
14
+
15
+ 1. `src/**` **不得 import `three`**;`three` 只是 `optional peerDependency`,且被 tsup 标为 `external`。
16
+ 2. 运行时只实现「浏览器环境 shim」,不关心 three 的类、材质、渲染流程。
17
+ 3. 所有 three 相关的构建期行为集中在 `src/build/**`,且只做三件事:AST 全局重写、WebGPU 策略、worker/wasm 资产收集;**不改写 three 源码语义**。
18
+ 4. 依赖方向固定:`types → scope/polyfills → core → platforms`;`build` 是独立分支,不得 import `core`/`platforms`;`node:fs` 只允许出现在 `build/`。
19
+ 5. tsup 两套构建:runtime = `es2019` / `platform: neutral` / splitting / dts;build tooling = `node18` / `platform: node` / 不 splitting。
20
+ 6. `es2019` 目标让 esbuild 降级 `?.` / `??`,减少微信开发者工具语法报错。
21
+
22
+ ## 理由
23
+
24
+ - 适配层与 three 解耦后,three 从 r163 到 r18x 的升级不需要改适配层内核,只需按 `docs/11` 补全局清单 / DOM 属性。
25
+ - 构建/运行隔离保证产物体积与可移植性;也便于在 Node 里跑单元测试。
26
+ - 不做语义改写 → 行为可预测、可调试,不会在 three 升级后突然失效。
27
+
28
+ ## 后果
29
+
30
+ - 正面:包体小、版本兼容面宽、可测试、可 tree-shake。
31
+ - 负面:某些 loader 的 worker/wasm 需要业务自行 `setDecoderPath()`;插件只负责把资源放进包并生成 manifest。
32
+ - 负面:不提供「自动替换 addons 模块」的便利,接入时按 `docs/07` 配置 decoder 路径即可。
33
+ - 风险:未来 three 引入依赖原生 Web API 的新模块时,需要按 `docs/08` 补 polyfill(这是常规迭代,不是架构变更)。
34
+
35
+ ## 被否决的备选方案
36
+
37
+ - fork / 打包 three:体积、版本、许可都不可接受,否决。
38
+ - 运行时 monkey-patch `WebGLRenderer`:隐式、脆弱、不可观测,否决。
39
+ - 把插件与运行时打成一个包入口:`node:fs` 会进小游戏 bundle,否决。
40
+
41
+ ## 验证方式
42
+
43
+ `npx tsc --noEmit` + `npx tsup` 产物检查(`dist/index.js` 不含 `node:` 导入);`tests/*` 全程在 Node 中用 mock `wx` 运行,不加载真实 three。
@@ -1,61 +1,61 @@
1
- # ADR-0007 · 能力探测允许「主画布回退」与「无法探测」语义
2
-
3
- - 状态:Accepted,其中「回退触发条件」与「身份比对基准」两条被 [ADR-0008](./0008-probe-fallback-boundary.md) 收紧
4
- - 日期:2026-11-10
5
- - 影响模块:`src/core/capabilities.ts`、`src/platforms/wechat-common.ts`、`src/platforms/wechat-game.ts`、`src/platforms/wechat-miniprogram.ts`、`src/types.ts`
6
-
7
- ## 背景
8
-
9
- 架构不变量之一是「只有一个上屏画布」,能力探测因此被限定为**只能**用 `wx.createOffscreenCanvas()`,绝不调用 `wx.createCanvas()`。
10
-
11
- 实际开发中暴露了两个问题:
12
-
13
- 1. **被探测对象 ≠ 被使用对象。** 上屏画布支持 WebGL2,离屏画布不支持(或 `createOffscreenCanvas` 根本不存在),是微信各基础库 / 机型的常态。微信开发者工具 3.18.0 模拟器就是这种情况:`capabilities.webgl2 === false`,但 three 的 `WebGLRenderer` 用 `#version 300 es` 正常渲染。
14
- 2. **「探测不到」被当成了「不支持」。** `probeContext` 第一个分支直接 `return false`,于是「这个宿主没提供探测手段」被写成了「这个宿主没有 WebGL2」。宿主若据此降级后端或画质,就会在支持 WebGL2 的设备上错误降级,排查色彩 / 精度问题时也会被带偏。
15
-
16
- ## 决策
17
-
18
- 1. `probeContext` 返回 `boolean | undefined`:
19
- - `true` / `false` 表示**实测结果**;
20
- - `undefined` 表示**无法探测**。
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` 提示一次。
24
-
25
- ## 理由
26
-
27
- - 第二次 `wx.createCanvas()` 在微信里**保证**得到离屏画布(上屏画布只有第一次调用才返回),这与 `createOffscreenCanvasRaw` 里已有的兜底是同一机制,不违反「只有一个上屏画布」的本意:本意是**不要抢走那块上屏画布**,而不是禁用该 API。
28
- - 但「保证」有一个缺口:宿主若通过 `GameGlobal.screencanvas` 预置了上屏画布,`getScreenCanvas()` 会直接取用它、并没有消耗那次「首次调用」。此时回退的 `createCanvas()` 仍可能把同一块上屏画布交回来,`getContext('webgl2')` 会抢先建上下文,紧接着的 `WEBGL_lose_context.loseContext()` 把它废掉——表现为黑屏且不报错,极难排查。身份比对是唯一可靠的判据:不看版本、不看 API 是否存在,只看返回的是不是那块画布。
29
- - 因此回退**必须**在上屏画布已经解析之后调用,并且由调用方显式 opt-in(`allowCanvasFallback`)。`wechat-game` 的 `getScreenCanvas()` 就在探测之前,所以传 `true` 并附带 `screenCanvas`;`wechat-miniprogram` 的画布节点来自选择器查询,不能这样探测,保持不传。
30
- - `webgl2Source` 让「这份报告里的 `false` 到底是实测还是猜测」一眼可见,这是本次缺陷里最伤排查成本的部分。
31
-
32
- ## 后果
33
-
34
- 正面:
35
-
36
- - 模拟器 / 老基础库上不再把支持 WebGL2 的主画布误判为不支持;
37
- - 能力报告自带来源,宿主可以据此选择「信任」或「自己覆盖」。
38
-
39
- 负面 / 风险:
40
-
41
- - 回退分支会多创建一个 1×1 画布(仅在离屏探测失败时发生),计入画布数量;
42
- - `'inferred'` 仍然是猜测。若宿主真的不支持 WebGL2 而基础库版本又较新,报告会偏乐观——但 three r163+ 自身会在创建上下文时明确失败,比静默降级更容易发现;
43
- - `probeContext` 的返回类型从 `boolean` 放宽为 `boolean | undefined`,属于**类型放宽**:既有 `(type) => boolean` 的实现仍然可赋值。
44
-
45
- ## 被否决的备选方案
46
-
47
- | 方案 | 否决理由 |
48
- | --- | --- |
49
- | 继续只用离屏探测 | 就是本次缺陷本身 |
50
- | 直接探测上屏画布 `getContext('webgl2')` | 会用默认属性抢先创建真实 GL 上下文,three 之后再带 `antialias` 等属性请求会拿到同一个上下文,渲染属性被静默改变 |
51
- | 把 `webgl2` 改成 `boolean \| null` | 破坏公开字段语义,所有读取处都要改;用 `webgl2Source` 附加信息可达到同样诊断效果 |
52
- | 探测不到就一律当 `false` | 会把未知伪装成结论,正是要修的问题 |
53
-
54
- ## 验证方式
55
-
56
- - `tests/capabilities.test.ts`:离屏优先且不碰 `createCanvas`、离屏答不出时回退、离屏返回 false 而主画布返回 true、完全无法探测时返回 `undefined`、回退拿到上屏画布时按身份放弃(`getContext` 零调用)、`webgl2Source` 三种取值,以及 `GameGlobal.screencanvas` 预置时 `createWeChatGameBinding` 不触碰屏画布。
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` 时,「本次使用的画布」与「设备的上屏画布」不是同一个对象,比对会落空。
1
+ # ADR-0007 · 能力探测允许「主画布回退」与「无法探测」语义
2
+
3
+ - 状态:Accepted,其中「回退触发条件」与「身份比对基准」两条被 [ADR-0008](./0008-probe-fallback-boundary.md) 收紧
4
+ - 日期:2026-11-10
5
+ - 影响模块:`src/core/capabilities.ts`、`src/platforms/wechat-common.ts`、`src/platforms/wechat-game.ts`、`src/platforms/wechat-miniprogram.ts`、`src/types.ts`
6
+
7
+ ## 背景
8
+
9
+ 架构不变量之一是「只有一个上屏画布」,能力探测因此被限定为**只能**用 `wx.createOffscreenCanvas()`,绝不调用 `wx.createCanvas()`。
10
+
11
+ 实际开发中暴露了两个问题:
12
+
13
+ 1. **被探测对象 ≠ 被使用对象。** 上屏画布支持 WebGL2,离屏画布不支持(或 `createOffscreenCanvas` 根本不存在),是微信各基础库 / 机型的常态。微信开发者工具 3.18.0 模拟器就是这种情况:`capabilities.webgl2 === false`,但 three 的 `WebGLRenderer` 用 `#version 300 es` 正常渲染。
14
+ 2. **「探测不到」被当成了「不支持」。** `probeContext` 第一个分支直接 `return false`,于是「这个宿主没提供探测手段」被写成了「这个宿主没有 WebGL2」。宿主若据此降级后端或画质,就会在支持 WebGL2 的设备上错误降级,排查色彩 / 精度问题时也会被带偏。
15
+
16
+ ## 决策
17
+
18
+ 1. `probeContext` 返回 `boolean | undefined`:
19
+ - `true` / `false` 表示**实测结果**;
20
+ - `undefined` 表示**无法探测**。
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` 提示一次。
24
+
25
+ ## 理由
26
+
27
+ - 第二次 `wx.createCanvas()` 在微信里**保证**得到离屏画布(上屏画布只有第一次调用才返回),这与 `createOffscreenCanvasRaw` 里已有的兜底是同一机制,不违反「只有一个上屏画布」的本意:本意是**不要抢走那块上屏画布**,而不是禁用该 API。
28
+ - 但「保证」有一个缺口:宿主若通过 `GameGlobal.screencanvas` 预置了上屏画布,`getScreenCanvas()` 会直接取用它、并没有消耗那次「首次调用」。此时回退的 `createCanvas()` 仍可能把同一块上屏画布交回来,`getContext('webgl2')` 会抢先建上下文,紧接着的 `WEBGL_lose_context.loseContext()` 把它废掉——表现为黑屏且不报错,极难排查。身份比对是唯一可靠的判据:不看版本、不看 API 是否存在,只看返回的是不是那块画布。
29
+ - 因此回退**必须**在上屏画布已经解析之后调用,并且由调用方显式 opt-in(`allowCanvasFallback`)。`wechat-game` 的 `getScreenCanvas()` 就在探测之前,所以传 `true` 并附带 `screenCanvas`;`wechat-miniprogram` 的画布节点来自选择器查询,不能这样探测,保持不传。
30
+ - `webgl2Source` 让「这份报告里的 `false` 到底是实测还是猜测」一眼可见,这是本次缺陷里最伤排查成本的部分。
31
+
32
+ ## 后果
33
+
34
+ 正面:
35
+
36
+ - 模拟器 / 老基础库上不再把支持 WebGL2 的主画布误判为不支持;
37
+ - 能力报告自带来源,宿主可以据此选择「信任」或「自己覆盖」。
38
+
39
+ 负面 / 风险:
40
+
41
+ - 回退分支会多创建一个 1×1 画布(仅在离屏探测失败时发生),计入画布数量;
42
+ - `'inferred'` 仍然是猜测。若宿主真的不支持 WebGL2 而基础库版本又较新,报告会偏乐观——但 three r163+ 自身会在创建上下文时明确失败,比静默降级更容易发现;
43
+ - `probeContext` 的返回类型从 `boolean` 放宽为 `boolean | undefined`,属于**类型放宽**:既有 `(type) => boolean` 的实现仍然可赋值。
44
+
45
+ ## 被否决的备选方案
46
+
47
+ | 方案 | 否决理由 |
48
+ | --- | --- |
49
+ | 继续只用离屏探测 | 就是本次缺陷本身 |
50
+ | 直接探测上屏画布 `getContext('webgl2')` | 会用默认属性抢先创建真实 GL 上下文,three 之后再带 `antialias` 等属性请求会拿到同一个上下文,渲染属性被静默改变 |
51
+ | 把 `webgl2` 改成 `boolean \| null` | 破坏公开字段语义,所有读取处都要改;用 `webgl2Source` 附加信息可达到同样诊断效果 |
52
+ | 探测不到就一律当 `false` | 会把未知伪装成结论,正是要修的问题 |
53
+
54
+ ## 验证方式
55
+
56
+ - `tests/capabilities.test.ts`:离屏优先且不碰 `createCanvas`、离屏答不出时回退、离屏返回 false 而主画布返回 true、完全无法探测时返回 `undefined`、回退拿到上屏画布时按身份放弃(`getContext` 零调用)、`webgl2Source` 三种取值,以及 `GameGlobal.screencanvas` 预置时 `createWeChatGameBinding` 不触碰屏画布。
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` 时,「本次使用的画布」与「设备的上屏画布」不是同一个对象,比对会落空。
@@ -1,56 +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`:正常路径的能力报告不受影响。
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`:正常路径的能力报告不受影响。