mini-three-adapter 0.1.7 → 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.
- package/AGENTS.md +85 -85
- package/LICENSE +21 -21
- package/README.md +159 -159
- package/dist/build/rollup.js.map +1 -1
- package/dist/build/vite.js.map +1 -1
- package/dist/{chunk-HKT54DDM.js → chunk-DQH3YRGN.js} +3 -3
- package/dist/chunk-DQH3YRGN.js.map +1 -0
- package/dist/{chunk-35XVAVDB.js → chunk-J34MD3IL.js} +2 -2
- package/dist/chunk-J34MD3IL.js.map +1 -0
- package/dist/{chunk-U3P3XHA3.js → chunk-LAVHSWBU.js} +2 -2
- package/dist/{chunk-U3P3XHA3.js.map → chunk-LAVHSWBU.js.map} +1 -1
- package/dist/{chunk-7XOHQFZ6.js → chunk-RYWYBOYO.js} +4 -4
- package/dist/chunk-RYWYBOYO.js.map +1 -0
- package/dist/{chunk-DDCQIBWW.js → chunk-SXQUZI22.js} +4 -4
- package/dist/chunk-SXQUZI22.js.map +1 -0
- package/dist/{chunk-V64V4HIZ.js → chunk-TPMMZFHW.js} +22 -6
- package/dist/chunk-TPMMZFHW.js.map +1 -0
- package/dist/{chunk-FQ2GOIOE.js → chunk-YPG3QUYK.js} +4 -4
- package/dist/chunk-YPG3QUYK.js.map +1 -0
- package/dist/core/index.js +3 -3
- 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.js +1 -1
- package/docs/01-design-principles.md +105 -105
- package/docs/03-module-map.md +99 -99
- package/docs/04-api-reference.md +310 -310
- package/docs/05-build-plugin.md +176 -176
- package/docs/06-platform-notes.md +6 -3
- package/docs/07-integration-guide.md +226 -226
- package/docs/08-extension-guide.md +101 -101
- package/docs/09-testing-and-release.md +212 -212
- package/docs/11-compat-matrix.md +100 -100
- package/docs/README.md +41 -41
- package/docs/adr/0001-scoped-globals.md +41 -41
- package/docs/adr/0002-unified-runtime-lifecycle.md +40 -40
- package/docs/adr/0003-ast-rewrite.md +51 -51
- package/docs/adr/0004-in-place-patching.md +42 -42
- package/docs/adr/0005-webgl2-only.md +44 -44
- package/docs/adr/0006-zero-three-dependency.md +43 -43
- package/docs/adr/0007-capability-probe-fallback.md +61 -61
- package/docs/adr/0008-probe-fallback-boundary.md +56 -56
- package/docs/adr/0009-placeholder-scope-environment-globals.md +69 -69
- package/docs/adr/0010-native-event-target-boundary.md +82 -82
- package/docs/adr/0011-host-callback-slot-bridging.md +45 -0
- package/docs/adr/README.md +33 -32
- package/package.json +126 -126
- package/dist/chunk-35XVAVDB.js.map +0 -1
- package/dist/chunk-7XOHQFZ6.js.map +0 -1
- package/dist/chunk-DDCQIBWW.js.map +0 -1
- package/dist/chunk-FQ2GOIOE.js.map +0 -1
- package/dist/chunk-HKT54DDM.js.map +0 -1
- package/dist/chunk-V64V4HIZ.js.map +0 -1
|
@@ -1,69 +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` 全部保持通过(改写产物形态未变)。
|
|
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` 全部保持通过(改写产物形态未变)。
|
|
@@ -1,82 +1,82 @@
|
|
|
1
|
-
# ADR-0010 · 原生事件目标不做 EventTarget 替换(H5 canvas 边界)
|
|
2
|
-
|
|
3
|
-
- 状态:Accepted(限定 [ADR-0004](./0004-in-place-patching.md) 的适用范围)
|
|
4
|
-
- 实现状态:已实现,`tests/native-events.test.ts` 13 例覆盖
|
|
5
|
-
- 日期:2026-11-13
|
|
6
|
-
- 影响模块:`src/core/platform.ts`、`src/core/element.ts`、`src/core/canvas.ts`、`src/core/runtime.ts`、`src/core/pointer.ts`、`src/platforms/browser.ts`、`src/polyfills/event.ts`
|
|
7
|
-
|
|
8
|
-
## 背景
|
|
9
|
-
|
|
10
|
-
[ADR-0004](./0004-in-place-patching.md) 决定「就地 patch」:不包装、不改原型,用 `Object.defineProperty` 把 three 需要的 DOM 成员补到宿主返回的那个对象上。其中一条是 `patchEventTarget()`——给对象补 `addEventListener` / `removeEventListener` / `dispatchEvent`。
|
|
11
|
-
|
|
12
|
-
这条决策的**前提**是:`wx` 返回的 canvas / image 是裸对象,没有 DOM 事件系统,事件方法必须由适配层提供。
|
|
13
|
-
|
|
14
|
-
H5 双端目标打破了这个前提。`createBrowserRuntime({ canvas })` 传入的是真实 `HTMLCanvasElement`,它本来就有完整事件系统;而 `src/core/runtime.ts` 对 `binding.rawCanvas` 无条件 `patchCanvas()`,于是:
|
|
15
|
-
|
|
16
|
-
1. `patchElement()` 调用 `patchEventTarget(instance)`,用 `Object.defineProperty` 把三个事件方法写到 canvas **实例自身**,遮蔽了 `EventTarget.prototype` 上的原生实现。
|
|
17
|
-
2. 浏览器派发真实事件走宿主内部实现,不经过被覆盖的实例方法;而 `addEventListener` 已被替换,三方库与应用注册的监听器进了 `MiniEventTarget` 的私有 `Map`。结果是**真实输入(pointer / touch / wheel / contextlost)不触发任何监听器**。
|
|
18
|
-
3. `MiniEventTarget.dispatchEvent()` 无条件写 `ev.target` 与 `ev.currentTarget`。真实 `Event` 上这两个字段是**只有 getter、没有 setter** 的访问器,ESM 严格模式下赋值直接抛 `TypeError: Cannot set property target of #<Event> which has only a getter`。因此 `canvas.dispatchEvent(realEvent)` 这类事件转发写法在 H5 上一条都送不到,异常抛在入口。
|
|
19
|
-
4. `browser` 绑定的 `watchTouch()` 在 patch **之后**才调用 `element.addEventListener`,拿到的是 shim,真实 `touchstart` 也进不了 `PointerBridge`;桌面端鼠标与滚轮更彻底——`browser` 根本没有对应的监听源。
|
|
20
|
-
5. 同一路径还覆盖了 `style`、`getBoundingClientRect`、`setAttribute`、`setPointerCapture` 等成员。`canvas.style` 被换成纯 JS 假对象后,写入能读回但不进真实 `CSSStyleDeclaration`;`getBoundingClientRect()` 变成启动时的静态快照。
|
|
21
|
-
|
|
22
|
-
补充事实:`docs/06-platform-notes.md` §6.3.1 已写明「`patchElement` 会覆盖 `addEventListener`,任何用原生事件的方案都必须在它之前保存引用」。`src/core/image.ts` 照此办理(patch 之前抓四类原生入口),**canvas 这条路径没有做同样的防御**,因为在微信侧它并不需要。
|
|
23
|
-
|
|
24
|
-
## 决策
|
|
25
|
-
|
|
26
|
-
1. **能力位下沉到绑定**:`PlatformBinding` 增加 `nativeEventTarget?: boolean` 与 `createEvent?: (type: string, init: NativeEventInit) => unknown`。`browser` 绑定置 `true` 并提供真实构造器(`PointerEvent` / `MouseEvent` / `Event`;构造器缺失时退化为 `new Event()` 后逐字段 `defineProperty` 补齐)。微信两平台不设置,缺省 `false`,行为一字不变。
|
|
27
|
-
2. **不替换原生事件目标**:`nativeEventTarget` 为真时,`patchElement()` 跳过 `patchEventTarget()`,`addEventListener` / `removeEventListener` / `dispatchEvent` 保持原生。`clearEventListeners` 也不安装,`runtime.dispose()` 里的 `clearable.clearEventListeners?.()` 已是可选调用。
|
|
28
|
-
3. **补缺不覆盖**:同一路径下 `patchElement()` 只补元素上**不存在**的成员(`if (!(key in instance))`)。真实 canvas 已提供的 `style`、`getBoundingClientRect`、`clientWidth`、`setAttribute`、`setPointerCapture`、`nodeType` 一律不动。`patchCanvas()` 仍接管 `getContext()`(上下文缓存与 WebGL 归一化是适配层的价值,原生 `getContext` 身份本就稳定),`toDataURL` 同样只在缺失时补。
|
|
29
|
-
4. **派发真实事件**:`PointerBridge` 增加 `createEvent` 选项。设置时 `pointerdown` / `pointermove` / `pointerup` / `pointercancel` / `pointerover` / `pointerenter` / `pointerout` / `pointerleave` / `click` / `mousedown` / `mousemove` / `mouseup` / `wheel` 一律通过平台构造器生成**真实 DOM 事件**再派发;未设置时沿用 `MiniPointerEvent` / `MiniMouseEvent`。
|
|
30
|
-
5. **`target` 只由宿主写**:`MiniEventTarget.dispatchEvent()` 不再对非 `MiniEvent` 实例写入 `target` / `currentTarget`。判定条件用 `event instanceof MiniEvent`,而不是 `try/catch` 吞掉异常——后者会把「事件对象形态不对」这个信息一起吞掉。
|
|
31
|
-
6. **原生模式下不做 document/window 冒泡**:`PointerBridge.fanout()` 在原生目标上只派发到 `element` 与 `captured`,跳过 `document` / `window` 两个 shim。真实事件从 canvas 派发后由浏览器自己完成冒泡与捕获,适配层没有资格再往假对象上转一份;往假 `MiniEventTarget` 上派发真实事件本身也会触发第 5 条描述的问题。
|
|
32
|
-
7. **不重复投递原生输入**:浏览器 canvas 自己就会把可信的 `pointer*` / `wheel` 投递给挂在 `domElement` 上的监听器(`OrbitControls` 正是这样工作),适配层再合成一份会让每次手势触发两次。因此 `browser` 的 `watchTouch()` 在宿主支持 `PointerEvent` 时返回 no-op;只有没有 `PointerEvent` 的旧内核才退回 `touch*` 兜底,并由 `createEvent()` 转成真实事件派发。滚轮完全交给浏览器,`bridge.dispatchMouse({ type: 'wheel' })` 保留给需要手动注入的场景。
|
|
33
|
-
8. **不做的事**:`runtime.document` 在 H5 上仍是 scoped shim,不指向真实 `document`。真实 DOM 不被适配层接管,宿主需要的事件监听请直接挂在真实 `document` / `window` 上。`document.createElement('img')` 在 H5 上仍由图片桥接(`createImageFactory` 的四级兜底)接管,不随本次切换——它依赖 shim 分发来保证 `onload` / watchdog 的终态语义,切换需要单独设计。
|
|
34
|
-
|
|
35
|
-
## 理由
|
|
36
|
-
|
|
37
|
-
- ADR-0004 的目的是**弥补宿主缺失**,不是**接管宿主已有的能力**。对裸 wx 对象补事件方法是必要的;对真实 DOM 元素补事件方法只会制造一个平行的、互不连通的事件系统。决策的适用边界应当由「目标对象是否自带可用事件系统」来划定。
|
|
38
|
-
- ADR-0004 已经写了「就地 patch 保持身份」的原则,本决策不改身份,只改**写入策略**(覆盖 → 补缺)。这与 ADR-0004 兼容,不需要推翻它。
|
|
39
|
-
- 「补缺不覆盖」比「按成员白名单跳过」更稳:白名单会随 three 升级与浏览器新增 API 过期,`in` 判断跟随宿主实际形态,且天然覆盖 `style` / `getBoundingClientRect` 这类原生实现更好的成员。
|
|
40
|
-
- 用 `instanceof MiniEvent` 判定「谁可以写 target」比 `try/catch` 更好:真实事件与 Mini 事件的差异是**结构性的**,应当在赋值前分支,而不是在异常后补救。小程序侧全部是 `MiniEvent`,行为零变化。
|
|
41
|
-
- 原生模式跳过 document/window 冒泡不是功能削减:浏览器已经做了这件事,而且做得更完整(捕获、冒泡、`composedPath`、passive)。再转一份只会重复派发。
|
|
42
|
-
|
|
43
|
-
## 后果
|
|
44
|
-
|
|
45
|
-
正面:
|
|
46
|
-
|
|
47
|
-
- H5 上真实 `pointer` / `touch` / `wheel` / `webglcontextlost` 恢复送达,`OrbitControls` 这类把监听器挂在 `domElement` 上的三方控件可直接工作;
|
|
48
|
-
- `canvas.dispatchEvent(realEvent)` 不再抛 `TypeError`,事件转发类写法可用;
|
|
49
|
-
- `canvas.style` / `getBoundingClientRect()` / `setPointerCapture()` 回归原生语义,页面布局与 CSS 生效;
|
|
50
|
-
- 小程序侧行为不变:`nativeEventTarget` 缺省 `false`,`patchEventTarget` 照旧。
|
|
51
|
-
|
|
52
|
-
负面 / 风险:
|
|
53
|
-
|
|
54
|
-
- **双形态**:事件对象可能是 `MiniPointerEvent`,也可能是原生 `PointerEvent`。依赖 `ev instanceof MiniPointerEvent` 判断事件来源的代码需要改用 `ev instanceof scope.PointerEvent`,或只看字段。`docs/04` 需要写清。
|
|
55
|
-
- `patchElement()` 的「补缺」分支不看 `rect`,真实元素的 `style.width` 不再随 `updateRect()` 变化——这是**正确行为**(真实元素以布局为准),但会让「改了 rect 却没生效」看起来像 bug。`runtime.resize()` 对真实 canvas 只更新 `bridge` 的 rect 缓存。
|
|
56
|
-
- `browser` 绑定不再注册自己的输入源,H5 上的输入完全由浏览器派发;这意味着 `runtime.bridge.activePointerCount` 在 H5 上恒为 0,需要指针计数的应用应直接读原生事件。
|
|
57
|
-
- Node 测试环境没有 `PointerEvent`,`createEvent` 会退化到 `Event` + 补字段。测试只能断言「是真实 `Event` 实例且字段齐全」,不能断言 `instanceof PointerEvent`。
|
|
58
|
-
|
|
59
|
-
## 被否决的备选方案
|
|
60
|
-
|
|
61
|
-
| 方案 | 否决理由 |
|
|
62
|
-
| --- | --- |
|
|
63
|
-
| H5 用独立 runtime,不复用 `createRuntime()` | 双端代码分叉,违反 [ADR-0002](./0002-unified-runtime-lifecycle.md) 的单一生命周期;且 `document` / `scope` / 帧调度都要再写一份 |
|
|
64
|
-
| 保留覆盖,shim 内部保存原生方法并转调(代理式 shim) | 要同时维护两套监听表,还要自己实现 `once` / `capture` / `passive` / `signal` 语义;关键问题是它**解决不了根因**——浏览器内部派发不会调用被覆盖的 JS 方法,原生监听器仍然收不到 |
|
|
65
|
-
| 保留覆盖,只在 `dispatchEvent` 里 `try/catch` 包住 `target` 赋值 | 能消除异常,但真实事件依旧进不来,只是把 P0 变成静默失效;且 `try/catch` 会掩盖事件对象形态错误 |
|
|
66
|
-
| 按成员白名单跳过(只跳过 `style` / `getBoundingClientRect`) | 白名单随 three 与浏览器演进过期,漏掉一个就是同类问题复发;`in` 判断跟随宿主形态 |
|
|
67
|
-
| 让 `runtime.document` 指向真实 `document` | 会牵连 `installGlobals()` 的可逆性与零全局污染([ADR-0001](./0001-scoped-globals.md)),超出本次边界;宿主自行监听真实 `document` 即可 |
|
|
68
|
-
| 在浏览器里跳过 `patchCanvas()`,完全不碰 canvas | `getContext()` 的缓存与 WebGL 归一化仍有价值(部分内核 `getExtension` 返回数字),且 `instanceof HTMLCanvasElement` 的注册对跨 realm 场景有意义 |
|
|
69
|
-
|
|
70
|
-
## 验证方式
|
|
71
|
-
|
|
72
|
-
- 新增 `tests/native-events.test.ts`(原生事件目标,13 例):
|
|
73
|
-
- `createBrowserRuntime()` 之后 `addEventListener` / `dispatchEvent` 与 patch 前同引用(未被覆盖);
|
|
74
|
-
- `canvas.style` 与 `getBoundingClientRect()` 未被替换;
|
|
75
|
-
- 原生派发 `webglcontextlost` → `runtime.on('contextlost')` 命中;
|
|
76
|
-
- `canvas.dispatchEvent(new Event(...))` 不抛且送达原生监听器;
|
|
77
|
-
- `runtime.handleTouch()` 派发的是真实 `Event` 实例、原生监听器命中、字段(`clientX` / `clientY` / `pointerId`)齐全;
|
|
78
|
-
- 不向 scoped `document` / `window` 转派;
|
|
79
|
-
- `dispatchMouse({ type: 'wheel' })` 产出 `wheel` 事件且带 `deltaY`;
|
|
80
|
-
- `runtime.createCanvas()` 的离屏画布仍带事件方法(Node 无 `document` 时的 mock 兜底);
|
|
81
|
-
- 微信小游戏 runtime 的 canvas 仍是 shim(`hasOwnProperty('addEventListener')`、`dispatchEvent({ type })` 可用),防止回退。
|
|
82
|
-
- `tests/runtime.test.ts`、`tests/event-dispatch.test.ts`、`tests/image-events.test.ts`、`tests/polyfills.test.ts` 保持通过。
|
|
1
|
+
# ADR-0010 · 原生事件目标不做 EventTarget 替换(H5 canvas 边界)
|
|
2
|
+
|
|
3
|
+
- 状态:Accepted(限定 [ADR-0004](./0004-in-place-patching.md) 的适用范围)
|
|
4
|
+
- 实现状态:已实现,`tests/native-events.test.ts` 13 例覆盖
|
|
5
|
+
- 日期:2026-11-13
|
|
6
|
+
- 影响模块:`src/core/platform.ts`、`src/core/element.ts`、`src/core/canvas.ts`、`src/core/runtime.ts`、`src/core/pointer.ts`、`src/platforms/browser.ts`、`src/polyfills/event.ts`
|
|
7
|
+
|
|
8
|
+
## 背景
|
|
9
|
+
|
|
10
|
+
[ADR-0004](./0004-in-place-patching.md) 决定「就地 patch」:不包装、不改原型,用 `Object.defineProperty` 把 three 需要的 DOM 成员补到宿主返回的那个对象上。其中一条是 `patchEventTarget()`——给对象补 `addEventListener` / `removeEventListener` / `dispatchEvent`。
|
|
11
|
+
|
|
12
|
+
这条决策的**前提**是:`wx` 返回的 canvas / image 是裸对象,没有 DOM 事件系统,事件方法必须由适配层提供。
|
|
13
|
+
|
|
14
|
+
H5 双端目标打破了这个前提。`createBrowserRuntime({ canvas })` 传入的是真实 `HTMLCanvasElement`,它本来就有完整事件系统;而 `src/core/runtime.ts` 对 `binding.rawCanvas` 无条件 `patchCanvas()`,于是:
|
|
15
|
+
|
|
16
|
+
1. `patchElement()` 调用 `patchEventTarget(instance)`,用 `Object.defineProperty` 把三个事件方法写到 canvas **实例自身**,遮蔽了 `EventTarget.prototype` 上的原生实现。
|
|
17
|
+
2. 浏览器派发真实事件走宿主内部实现,不经过被覆盖的实例方法;而 `addEventListener` 已被替换,三方库与应用注册的监听器进了 `MiniEventTarget` 的私有 `Map`。结果是**真实输入(pointer / touch / wheel / contextlost)不触发任何监听器**。
|
|
18
|
+
3. `MiniEventTarget.dispatchEvent()` 无条件写 `ev.target` 与 `ev.currentTarget`。真实 `Event` 上这两个字段是**只有 getter、没有 setter** 的访问器,ESM 严格模式下赋值直接抛 `TypeError: Cannot set property target of #<Event> which has only a getter`。因此 `canvas.dispatchEvent(realEvent)` 这类事件转发写法在 H5 上一条都送不到,异常抛在入口。
|
|
19
|
+
4. `browser` 绑定的 `watchTouch()` 在 patch **之后**才调用 `element.addEventListener`,拿到的是 shim,真实 `touchstart` 也进不了 `PointerBridge`;桌面端鼠标与滚轮更彻底——`browser` 根本没有对应的监听源。
|
|
20
|
+
5. 同一路径还覆盖了 `style`、`getBoundingClientRect`、`setAttribute`、`setPointerCapture` 等成员。`canvas.style` 被换成纯 JS 假对象后,写入能读回但不进真实 `CSSStyleDeclaration`;`getBoundingClientRect()` 变成启动时的静态快照。
|
|
21
|
+
|
|
22
|
+
补充事实:`docs/06-platform-notes.md` §6.3.1 已写明「`patchElement` 会覆盖 `addEventListener`,任何用原生事件的方案都必须在它之前保存引用」。`src/core/image.ts` 照此办理(patch 之前抓四类原生入口),**canvas 这条路径没有做同样的防御**,因为在微信侧它并不需要。
|
|
23
|
+
|
|
24
|
+
## 决策
|
|
25
|
+
|
|
26
|
+
1. **能力位下沉到绑定**:`PlatformBinding` 增加 `nativeEventTarget?: boolean` 与 `createEvent?: (type: string, init: NativeEventInit) => unknown`。`browser` 绑定置 `true` 并提供真实构造器(`PointerEvent` / `MouseEvent` / `Event`;构造器缺失时退化为 `new Event()` 后逐字段 `defineProperty` 补齐)。微信两平台不设置,缺省 `false`,行为一字不变。
|
|
27
|
+
2. **不替换原生事件目标**:`nativeEventTarget` 为真时,`patchElement()` 跳过 `patchEventTarget()`,`addEventListener` / `removeEventListener` / `dispatchEvent` 保持原生。`clearEventListeners` 也不安装,`runtime.dispose()` 里的 `clearable.clearEventListeners?.()` 已是可选调用。
|
|
28
|
+
3. **补缺不覆盖**:同一路径下 `patchElement()` 只补元素上**不存在**的成员(`if (!(key in instance))`)。真实 canvas 已提供的 `style`、`getBoundingClientRect`、`clientWidth`、`setAttribute`、`setPointerCapture`、`nodeType` 一律不动。`patchCanvas()` 仍接管 `getContext()`(上下文缓存与 WebGL 归一化是适配层的价值,原生 `getContext` 身份本就稳定),`toDataURL` 同样只在缺失时补。
|
|
29
|
+
4. **派发真实事件**:`PointerBridge` 增加 `createEvent` 选项。设置时 `pointerdown` / `pointermove` / `pointerup` / `pointercancel` / `pointerover` / `pointerenter` / `pointerout` / `pointerleave` / `click` / `mousedown` / `mousemove` / `mouseup` / `wheel` 一律通过平台构造器生成**真实 DOM 事件**再派发;未设置时沿用 `MiniPointerEvent` / `MiniMouseEvent`。
|
|
30
|
+
5. **`target` 只由宿主写**:`MiniEventTarget.dispatchEvent()` 不再对非 `MiniEvent` 实例写入 `target` / `currentTarget`。判定条件用 `event instanceof MiniEvent`,而不是 `try/catch` 吞掉异常——后者会把「事件对象形态不对」这个信息一起吞掉。
|
|
31
|
+
6. **原生模式下不做 document/window 冒泡**:`PointerBridge.fanout()` 在原生目标上只派发到 `element` 与 `captured`,跳过 `document` / `window` 两个 shim。真实事件从 canvas 派发后由浏览器自己完成冒泡与捕获,适配层没有资格再往假对象上转一份;往假 `MiniEventTarget` 上派发真实事件本身也会触发第 5 条描述的问题。
|
|
32
|
+
7. **不重复投递原生输入**:浏览器 canvas 自己就会把可信的 `pointer*` / `wheel` 投递给挂在 `domElement` 上的监听器(`OrbitControls` 正是这样工作),适配层再合成一份会让每次手势触发两次。因此 `browser` 的 `watchTouch()` 在宿主支持 `PointerEvent` 时返回 no-op;只有没有 `PointerEvent` 的旧内核才退回 `touch*` 兜底,并由 `createEvent()` 转成真实事件派发。滚轮完全交给浏览器,`bridge.dispatchMouse({ type: 'wheel' })` 保留给需要手动注入的场景。
|
|
33
|
+
8. **不做的事**:`runtime.document` 在 H5 上仍是 scoped shim,不指向真实 `document`。真实 DOM 不被适配层接管,宿主需要的事件监听请直接挂在真实 `document` / `window` 上。`document.createElement('img')` 在 H5 上仍由图片桥接(`createImageFactory` 的四级兜底)接管,不随本次切换——它依赖 shim 分发来保证 `onload` / watchdog 的终态语义,切换需要单独设计。
|
|
34
|
+
|
|
35
|
+
## 理由
|
|
36
|
+
|
|
37
|
+
- ADR-0004 的目的是**弥补宿主缺失**,不是**接管宿主已有的能力**。对裸 wx 对象补事件方法是必要的;对真实 DOM 元素补事件方法只会制造一个平行的、互不连通的事件系统。决策的适用边界应当由「目标对象是否自带可用事件系统」来划定。
|
|
38
|
+
- ADR-0004 已经写了「就地 patch 保持身份」的原则,本决策不改身份,只改**写入策略**(覆盖 → 补缺)。这与 ADR-0004 兼容,不需要推翻它。
|
|
39
|
+
- 「补缺不覆盖」比「按成员白名单跳过」更稳:白名单会随 three 升级与浏览器新增 API 过期,`in` 判断跟随宿主实际形态,且天然覆盖 `style` / `getBoundingClientRect` 这类原生实现更好的成员。
|
|
40
|
+
- 用 `instanceof MiniEvent` 判定「谁可以写 target」比 `try/catch` 更好:真实事件与 Mini 事件的差异是**结构性的**,应当在赋值前分支,而不是在异常后补救。小程序侧全部是 `MiniEvent`,行为零变化。
|
|
41
|
+
- 原生模式跳过 document/window 冒泡不是功能削减:浏览器已经做了这件事,而且做得更完整(捕获、冒泡、`composedPath`、passive)。再转一份只会重复派发。
|
|
42
|
+
|
|
43
|
+
## 后果
|
|
44
|
+
|
|
45
|
+
正面:
|
|
46
|
+
|
|
47
|
+
- H5 上真实 `pointer` / `touch` / `wheel` / `webglcontextlost` 恢复送达,`OrbitControls` 这类把监听器挂在 `domElement` 上的三方控件可直接工作;
|
|
48
|
+
- `canvas.dispatchEvent(realEvent)` 不再抛 `TypeError`,事件转发类写法可用;
|
|
49
|
+
- `canvas.style` / `getBoundingClientRect()` / `setPointerCapture()` 回归原生语义,页面布局与 CSS 生效;
|
|
50
|
+
- 小程序侧行为不变:`nativeEventTarget` 缺省 `false`,`patchEventTarget` 照旧。
|
|
51
|
+
|
|
52
|
+
负面 / 风险:
|
|
53
|
+
|
|
54
|
+
- **双形态**:事件对象可能是 `MiniPointerEvent`,也可能是原生 `PointerEvent`。依赖 `ev instanceof MiniPointerEvent` 判断事件来源的代码需要改用 `ev instanceof scope.PointerEvent`,或只看字段。`docs/04` 需要写清。
|
|
55
|
+
- `patchElement()` 的「补缺」分支不看 `rect`,真实元素的 `style.width` 不再随 `updateRect()` 变化——这是**正确行为**(真实元素以布局为准),但会让「改了 rect 却没生效」看起来像 bug。`runtime.resize()` 对真实 canvas 只更新 `bridge` 的 rect 缓存。
|
|
56
|
+
- `browser` 绑定不再注册自己的输入源,H5 上的输入完全由浏览器派发;这意味着 `runtime.bridge.activePointerCount` 在 H5 上恒为 0,需要指针计数的应用应直接读原生事件。
|
|
57
|
+
- Node 测试环境没有 `PointerEvent`,`createEvent` 会退化到 `Event` + 补字段。测试只能断言「是真实 `Event` 实例且字段齐全」,不能断言 `instanceof PointerEvent`。
|
|
58
|
+
|
|
59
|
+
## 被否决的备选方案
|
|
60
|
+
|
|
61
|
+
| 方案 | 否决理由 |
|
|
62
|
+
| --- | --- |
|
|
63
|
+
| H5 用独立 runtime,不复用 `createRuntime()` | 双端代码分叉,违反 [ADR-0002](./0002-unified-runtime-lifecycle.md) 的单一生命周期;且 `document` / `scope` / 帧调度都要再写一份 |
|
|
64
|
+
| 保留覆盖,shim 内部保存原生方法并转调(代理式 shim) | 要同时维护两套监听表,还要自己实现 `once` / `capture` / `passive` / `signal` 语义;关键问题是它**解决不了根因**——浏览器内部派发不会调用被覆盖的 JS 方法,原生监听器仍然收不到 |
|
|
65
|
+
| 保留覆盖,只在 `dispatchEvent` 里 `try/catch` 包住 `target` 赋值 | 能消除异常,但真实事件依旧进不来,只是把 P0 变成静默失效;且 `try/catch` 会掩盖事件对象形态错误 |
|
|
66
|
+
| 按成员白名单跳过(只跳过 `style` / `getBoundingClientRect`) | 白名单随 three 与浏览器演进过期,漏掉一个就是同类问题复发;`in` 判断跟随宿主形态 |
|
|
67
|
+
| 让 `runtime.document` 指向真实 `document` | 会牵连 `installGlobals()` 的可逆性与零全局污染([ADR-0001](./0001-scoped-globals.md)),超出本次边界;宿主自行监听真实 `document` 即可 |
|
|
68
|
+
| 在浏览器里跳过 `patchCanvas()`,完全不碰 canvas | `getContext()` 的缓存与 WebGL 归一化仍有价值(部分内核 `getExtension` 返回数字),且 `instanceof HTMLCanvasElement` 的注册对跨 realm 场景有意义 |
|
|
69
|
+
|
|
70
|
+
## 验证方式
|
|
71
|
+
|
|
72
|
+
- 新增 `tests/native-events.test.ts`(原生事件目标,13 例):
|
|
73
|
+
- `createBrowserRuntime()` 之后 `addEventListener` / `dispatchEvent` 与 patch 前同引用(未被覆盖);
|
|
74
|
+
- `canvas.style` 与 `getBoundingClientRect()` 未被替换;
|
|
75
|
+
- 原生派发 `webglcontextlost` → `runtime.on('contextlost')` 命中;
|
|
76
|
+
- `canvas.dispatchEvent(new Event(...))` 不抛且送达原生监听器;
|
|
77
|
+
- `runtime.handleTouch()` 派发的是真实 `Event` 实例、原生监听器命中、字段(`clientX` / `clientY` / `pointerId`)齐全;
|
|
78
|
+
- 不向 scoped `document` / `window` 转派;
|
|
79
|
+
- `dispatchMouse({ type: 'wheel' })` 产出 `wheel` 事件且带 `deltaY`;
|
|
80
|
+
- `runtime.createCanvas()` 的离屏画布仍带事件方法(Node 无 `document` 时的 mock 兜底);
|
|
81
|
+
- 微信小游戏 runtime 的 canvas 仍是 shim(`hasOwnProperty('addEventListener')`、`dispatchEvent({ type })` 可用),防止回退。
|
|
82
|
+
- `tests/runtime.test.ts`、`tests/event-dispatch.test.ts`、`tests/image-events.test.ts`、`tests/polyfills.test.ts` 保持通过。
|
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
# ADR-0011 · 宿主回调槽位的访问器不得遮蔽桥接
|
|
2
|
+
|
|
3
|
+
- 状态:Accepted
|
|
4
|
+
- 日期:2026-11-21
|
|
5
|
+
- 影响模块:`src/core/image.ts`(`createImageFactory`);受约束于 `src/polyfills/event.ts`(`MiniEventTarget.dispatchEvent` 的行内派发)
|
|
6
|
+
|
|
7
|
+
## 背景
|
|
8
|
+
|
|
9
|
+
0.1.5 起图片事件桥接采用四级兜底:转发器 `forwardLoad` / `forwardError` 在 shim 访问器安装**之前**写入宿主的原生 `onload` / `onerror` 槽位;随后安装的用户访问器把同一属性覆盖成登记表——getter 返回 `handlers[eventName]`,只有消费者显式 `img.onload = fn` 才有值。
|
|
10
|
+
|
|
11
|
+
2026-11-21 业务侧真机对照报告(消消乐小游戏 `docs/adapter-image-events.md`)证实:真机宿主**不消费赋值时存下的回调**,而是在图片完成那一刻**读 `image.onload` 属性并调用读到的值**。three 的 `ImageLoader` 只用 `addEventListener('load')`、从不赋 `onload`,宿主读到 `undefined` → 桥接永不执行 → 2s 看门狗判 `image-events-timeout` → 所有 `TextureLoader` 纹理 reject(启动页插图 / UI 位图全部空白,且无报错)。模拟器的 `wx.createImage()` 在**赋值那一刻**把回调存进宿主内部、事件时直接调用存值,不读属性——同一份产物模拟器正常,缺陷被掩盖两个版本。
|
|
12
|
+
|
|
13
|
+
## 决策
|
|
14
|
+
|
|
15
|
+
安装在宿主回调槽位(`onload` / `onerror`)上的访问器遵循四条硬规则:
|
|
16
|
+
|
|
17
|
+
1. **非派发期间,getter 永远返回可调用的桥接函数**(`forwardLoad` / `forwardError`),不返回登记表。宿主「读属性再调用」的形态因此总能触发 `finish`;`finish` 幂等(终态只派发一次),宿主「既存又读」也不会双发。
|
|
18
|
+
2. **派发期间(`dispatchDepth > 0`),getter 返回登记的用户回调**。`MiniEventTarget.dispatchEvent` 的行内派发读 `host['on' + type]`:此时必须回用户函数,否则行内派发会递归回桥接而不是调用业务回调。
|
|
19
|
+
3. 登记照旧只进 `handlers`;setter **不**向宿主原生槽位写入用户函数——宿主若直接调存值就绕过了 `finish`,终态不落、看门狗 2s 后会迟到误判。
|
|
20
|
+
4. 转发器写入原生槽位必须发生在访问器安装**之前**(现有顺序:Tier-2 裸赋值 → 访问器)。这条依赖 `patchElement` 不碰 `on*` 成员;若未来 `patchElement` 开始定义 `on*`,本桥必须改为用 `patchElement` 之前抓到的描述符写值。
|
|
21
|
+
|
|
22
|
+
## 理由
|
|
23
|
+
|
|
24
|
+
- 对象身份不变(ADR-0004):继续 `Object.defineProperty` 就地补丁,不 Proxy、不改原型。
|
|
25
|
+
- 单一派发路径:用户回调只经 `dispatchEvent` 的行内派发送达,桥接只负责终态与监听器派发;双路触发收敛到一次。
|
|
26
|
+
- 业务报告的「组合 getter」(`user ? (ev) => { bridge(ev); user(ev) } : bridge`)会双发:`finish` 的行内派发再次读到组合函数并再次调用 user。`dispatchDepth` 区分两种读者,比组合更简单且各只送达一次。
|
|
27
|
+
|
|
28
|
+
## 后果
|
|
29
|
+
|
|
30
|
+
- 正面:真机「读属性」宿主出图;看门狗超时补 `warnOnce('image-events-timeout', …, { path, src })`,真机排查不再「无报错」。
|
|
31
|
+
- 负面:`img.onload === fn` 的身份比较不再成立(getter 回桥接而非用户函数)——浏览器语义在此让位于可交付性,已知代价;仓库内与 three 均无此类消费方。
|
|
32
|
+
- 负面:第三方若**读** `img.onload` 并自行调用,会触发一次完整派发(终态 + 监听器 + 用户回调),而非仅用户回调——语义上等价于「宿主触发了事件」。
|
|
33
|
+
- 风险:若未来有代码在派发进行中从外部读 `img.onload`,会读到用户回调而非桥接;当前无此读者。
|
|
34
|
+
|
|
35
|
+
## 被否决的备选方案
|
|
36
|
+
|
|
37
|
+
- **组合 getter(报告方案 A 草稿)**:行内派发再次读到组合函数,用户回调双发。
|
|
38
|
+
- **getter 恒回登记表(0.1.7 现状)**:真机读到 `undefined`,P0。
|
|
39
|
+
- **getter 恒回用户回调**:宿主直调用户函数、绕过 `finish`,看门狗 2s 后迟到报 error,`decode()` 永不 settle。
|
|
40
|
+
- **报告方案 B(统一事件源)/ C(`canvas.createImage()` 优先)**:与遮蔽缺陷正交,留待后续;本 ADR 只锁「访问器语义」这一层。
|
|
41
|
+
|
|
42
|
+
## 验证方式
|
|
43
|
+
|
|
44
|
+
- `tests/image-events.test.ts`:「触发时读属性」宿主 ×3(桥接可达 `addEventListener` 消费者 / 槽位始终可调用 / 业务 `img.onload = fn` 恰好一次)、「既存又读」宿主只收敛一次、看门狗超时告警恰好一条(带 `path` / `src`)。
|
|
45
|
+
- 真机复测路径:业务仓库切 `e59bf80` 构建对照(修复前模拟器正常 ↔ 真机空白;修复后均正常),见报告「五分钟确诊」。
|
package/docs/adr/README.md
CHANGED
|
@@ -1,32 +1,33 @@
|
|
|
1
|
-
# 架构决策记录(ADR)
|
|
2
|
-
|
|
3
|
-
每条 ADR 记录一个**难以从代码本身看出原因**的决策。新增或推翻决策时不要删除旧文件,把状态改为 `Superseded by ADR-XXXX` 并写明原因——这是给后续 AI 迭代保留「为什么」的关键。
|
|
4
|
-
|
|
5
|
-
| 编号 | 决策 | 状态 |
|
|
6
|
-
| --- | --- | --- |
|
|
7
|
-
| [0001](./0001-scoped-globals.md) | 作用域化的浏览器环境 shim | Accepted |
|
|
8
|
-
| [0002](./0002-unified-runtime-lifecycle.md) | 单一 `createRuntime()` / `MiniThreeRuntime` 生命周期 | Accepted |
|
|
9
|
-
| [0003](./0003-ast-rewrite.md) | 用 Babel AST 作用域分析重写三方模块全局引用 | Accepted |
|
|
10
|
-
| [0004](./0004-in-place-patching.md) | 就地 patch 画布,不改原型、不用 Proxy | Accepted |
|
|
11
|
-
| [0005](./0005-webgl2-only.md) | WebGL2 优先,不静默降级到 WebGL1 | Accepted |
|
|
12
|
-
| [0006](./0006-zero-three-dependency.md) | 运行时零 `three` 依赖,构建/运行严格隔离 | 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 |
|
|
16
|
-
| [0010](./0010-native-event-target-boundary.md) | 原生事件目标不做 EventTarget 替换,`patchElement` 改为补缺不覆盖 | Accepted |
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
-
|
|
23
|
-
-
|
|
24
|
-
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
##
|
|
28
|
-
##
|
|
29
|
-
##
|
|
30
|
-
##
|
|
31
|
-
##
|
|
32
|
-
|
|
1
|
+
# 架构决策记录(ADR)
|
|
2
|
+
|
|
3
|
+
每条 ADR 记录一个**难以从代码本身看出原因**的决策。新增或推翻决策时不要删除旧文件,把状态改为 `Superseded by ADR-XXXX` 并写明原因——这是给后续 AI 迭代保留「为什么」的关键。
|
|
4
|
+
|
|
5
|
+
| 编号 | 决策 | 状态 |
|
|
6
|
+
| --- | --- | --- |
|
|
7
|
+
| [0001](./0001-scoped-globals.md) | 作用域化的浏览器环境 shim | Accepted |
|
|
8
|
+
| [0002](./0002-unified-runtime-lifecycle.md) | 单一 `createRuntime()` / `MiniThreeRuntime` 生命周期 | Accepted |
|
|
9
|
+
| [0003](./0003-ast-rewrite.md) | 用 Babel AST 作用域分析重写三方模块全局引用 | Accepted |
|
|
10
|
+
| [0004](./0004-in-place-patching.md) | 就地 patch 画布,不改原型、不用 Proxy | Accepted |
|
|
11
|
+
| [0005](./0005-webgl2-only.md) | WebGL2 优先,不静默降级到 WebGL1 | Accepted |
|
|
12
|
+
| [0006](./0006-zero-three-dependency.md) | 运行时零 `three` 依赖,构建/运行严格隔离 | 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 |
|
|
16
|
+
| [0010](./0010-native-event-target-boundary.md) | 原生事件目标不做 EventTarget 替换,`patchElement` 改为补缺不覆盖 | Accepted |
|
|
17
|
+
| [0011](./0011-host-callback-slot-bridging.md) | 宿主回调槽位的访问器不得遮蔽桥接:getter 非派发期间恒回桥接函数 | Accepted |
|
|
18
|
+
|
|
19
|
+
模板(新增 ADR 时复制):
|
|
20
|
+
|
|
21
|
+
```markdown
|
|
22
|
+
# ADR-NNNN · 标题
|
|
23
|
+
- 状态:Proposed | Accepted | Deprecated | Superseded by ADR-XXXX
|
|
24
|
+
- 日期:YYYY-MM-DD
|
|
25
|
+
- 影响模块:...
|
|
26
|
+
|
|
27
|
+
## 背景
|
|
28
|
+
## 决策
|
|
29
|
+
## 理由
|
|
30
|
+
## 后果(正面 / 负面 / 风险)
|
|
31
|
+
## 被否决的备选方案
|
|
32
|
+
## 验证方式
|
|
33
|
+
```
|