mini-three-adapter 0.1.9 → 0.1.11
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 +1 -1
- package/dist/{chunk-LAVHSWBU.js → chunk-K43RAGDJ.js} +11 -14
- package/dist/chunk-K43RAGDJ.js.map +1 -0
- package/dist/{chunk-VOARPBLN.js → chunk-MZCXLR3W.js} +4 -4
- package/dist/{chunk-VOARPBLN.js.map → chunk-MZCXLR3W.js.map} +1 -1
- package/dist/{chunk-ACBSKQB7.js → chunk-RRXFXPVA.js} +5 -5
- package/dist/chunk-RRXFXPVA.js.map +1 -0
- package/dist/{chunk-IC2HZWDX.js → chunk-TDUSUSPD.js} +5 -5
- package/dist/chunk-TDUSUSPD.js.map +1 -0
- package/dist/{chunk-F4PKFV7T.js → chunk-XTQOIGN7.js} +5 -5
- package/dist/chunk-XTQOIGN7.js.map +1 -0
- package/dist/{chunk-3TZPKAS3.js → chunk-ZRI64HFV.js} +10 -18
- package/dist/chunk-ZRI64HFV.js.map +1 -0
- package/dist/core/index.d.ts +2 -2
- package/dist/core/index.js +2 -2
- package/dist/index.d.ts +1 -1
- package/dist/index.js +6 -6
- package/dist/platforms/browser.d.ts +1 -1
- package/dist/platforms/browser.js +3 -3
- package/dist/platforms/wechat-game.d.ts +10 -2
- package/dist/platforms/wechat-game.js +4 -4
- package/dist/platforms/wechat-miniprogram.d.ts +7 -2
- package/dist/platforms/wechat-miniprogram.js +4 -4
- package/dist/polyfills/index.d.ts +14 -6
- package/dist/polyfills/index.js +1 -1
- package/dist/{runtime-C8_xIlDM.d.ts → runtime-BJVrWHmH.d.ts} +12 -2
- package/docs/01-design-principles.md +1 -1
- package/docs/03-module-map.md +3 -3
- package/docs/04-api-reference.md +4 -2
- package/docs/06-platform-notes.md +1 -1
- package/docs/08-extension-guide.md +2 -0
- package/docs/09-testing-and-release.md +3 -3
- package/docs/11-compat-matrix.md +5 -5
- package/docs/adr/0012-host-data-property-boundary.md +3 -3
- package/docs/adr/0013-object-url-data-uri.md +48 -0
- package/docs/adr/README.md +1 -0
- package/package.json +1 -1
- package/dist/chunk-3TZPKAS3.js.map +0 -1
- package/dist/chunk-ACBSKQB7.js.map +0 -1
- package/dist/chunk-F4PKFV7T.js.map +0 -1
- package/dist/chunk-IC2HZWDX.js.map +0 -1
- package/dist/chunk-LAVHSWBU.js.map +0 -1
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
import { a as Capabilities, R as Rect, D as Disposer, N as NativeEventInit, b as ContextType, f as TouchLikeEvent, d as FrameScheduler, W as WindowInfo, e as RuntimeEvents } from './types-DOoJ7noL.js';
|
|
2
2
|
import { MiniThreeScope, DocumentLike } from './scope.js';
|
|
3
|
-
import { b as WxLike, W as WxCanvas } from './wx-types-BZTQ2jWG.js';
|
|
3
|
+
import { b as WxLike, a as WxImage, W as WxCanvas } from './wx-types-BZTQ2jWG.js';
|
|
4
4
|
|
|
5
5
|
/** Structured, level-filtered diagnostics. No console spam in production. */
|
|
6
6
|
|
|
@@ -107,7 +107,17 @@ interface ImageFactory {
|
|
|
107
107
|
* non-createImageBitmap branch. The build plugin can force this to `void 0`. */
|
|
108
108
|
createImageBitmap: undefined;
|
|
109
109
|
}
|
|
110
|
-
|
|
110
|
+
interface ImageFactoryOptions {
|
|
111
|
+
/**
|
|
112
|
+
* Replace how the raw host image object is acquired. Default:
|
|
113
|
+
* `wx.createImage()` → `OffscreenCanvas.createImage()`. Whatever this returns
|
|
114
|
+
* is bridged in place (event slots, `src` handling, fallbacks), so it must be
|
|
115
|
+
* the host's own image object — no wrappers, clones or proxies (ADR-0004 /
|
|
116
|
+
* ADR-0012). Errors thrown here are not swallowed.
|
|
117
|
+
*/
|
|
118
|
+
createImage?: () => WxImage;
|
|
119
|
+
}
|
|
120
|
+
declare function createImageFactory(wx: WxLike, diagnostics?: Diagnostics, options?: ImageFactoryOptions): ImageFactory;
|
|
111
121
|
|
|
112
122
|
/** Platform binding contract: everything the runtime needs from a host. */
|
|
113
123
|
|
|
@@ -61,7 +61,7 @@
|
|
|
61
61
|
| 平台抽象 | 结构化接口 `PlatformBinding` | 以组合方式表达平台差异,新增平台只需实现一组字段与方法 |
|
|
62
62
|
| 作用域 | `getActiveScope()` 惰性读取 | 支持运行时替换、多实例与测试注入 |
|
|
63
63
|
| 网络 | `wx.request` 桥接 `fetch` / `XMLHttpRequest` | three 的 FileLoader 与 addons 可直接工作 |
|
|
64
|
-
| 对象 URL | `
|
|
64
|
+
| 对象 URL | `createObjectURL` 直接返回 `data:` URI | 宿主图片加载器可直接识别,无需拦截 `Image.src`,也没有注册表或临时文件(真机 Android 3.18.0 验证 1.77 MB URI);见 [ADR-0013](./adr/0013-object-url-data-uri.md) |
|
|
65
65
|
| 构建工具集成 | Rollup 兼容插件核心 + Vite 薄封装 | 一套逻辑覆盖 Vite / Rollup,Node 依赖不进小游戏包 |
|
|
66
66
|
|
|
67
67
|
## 1.6 能力边界
|
package/docs/03-module-map.md
CHANGED
|
@@ -18,7 +18,7 @@
|
|
|
18
18
|
| 文件 | 职责 | 关键导出 | 改这里 | 会影响 / 测试 |
|
|
19
19
|
| --- | --- | --- | --- | --- |
|
|
20
20
|
| `src/polyfills/event.ts` | W3C 事件系统,`patchEventTarget` 把方法绑到内部载体但把 `this` / `event.target` / `currentTarget` 转发给宿主元素;`dispatchEvent` 只对 `MiniEvent` 写 `target`(真实 DOM 事件只读,ADR-0010) | `MiniEvent`、`MiniPointerEvent`、`MiniMouseEvent`、`MiniEventTarget`、`patchEventTarget`、`MiniDOMException` | 事件字段缺失(如 controls 读 `movementX`)、`onxxx` 内联处理器、监听器拿不到事件目标 | `pointer.ts`、`dom.ts`;`tests/polyfills.test.ts`、`tests/event-dispatch.test.ts` |
|
|
21
|
-
| `src/polyfills/blob-url.ts` | Blob / URL / base64 / URL
|
|
21
|
+
| `src/polyfills/blob-url.ts` | Blob / URL / base64 / URL 相对解析;`createObjectURL` 直接返回 `data:` URI([ADR-0013](./adr/0013-object-url-data-uri.md)) | `MiniBlob`、`MiniURL`、`bytesToBase64`、`resolveUrl` | `createObjectURL` 的返回格式(`data:` 直返)、URL 解析边界 | `image.ts`(不再消费对象 URL)、`tests/polyfills.test.ts` |
|
|
22
22
|
| `src/polyfills/text-encoding.ts` | `atob`/`btoa`/`TextEncoder`/`TextDecoder` | 同名 | 编码边界、BOM、utf-16 | `network.ts`、`blob-url.ts`;`tests/polyfills.test.ts` |
|
|
23
23
|
| `src/polyfills/network.ts` | `fetch`、`XMLHttpRequest`、`AbortController` | `createFetch`、`createXMLHttpRequestFactory`、`MiniAbortController` | `wx.request` 返回结构差异、进度事件 | `runtime.ts` 的 scope 组装;`tests/polyfills.test.ts` |
|
|
24
24
|
|
|
@@ -32,7 +32,7 @@
|
|
|
32
32
|
| `src/core/runtime.ts` | **总装配**:画布补丁、scope 组装、订阅、生命周期 | `createRuntime`、`MiniThreeRuntime`、`RuntimeOptions`、`RendererHints` | 新增 runtime API、新增/移除全局项、调整启动顺序 | 几乎所有模块;`tests/runtime.test.ts`、`tests/native-events.test.ts` |
|
|
33
33
|
| `src/core/element.ts` | 就地 DOM 属性补丁 + `Symbol.hasInstance` 注册表。原生事件目标上**只补缺失成员**,不覆盖宿主的 `style` / `getBoundingClientRect` / 事件方法 | `patchElement`、`createMockClass`、`*Shim`、`normalizeRect` | three 报「DOM 属性缺失」、`instanceof` 失败、H5 上原生成员被覆盖 | `canvas.ts`、`image.ts`、`dom.ts`;`tests/native-events.test.ts` |
|
|
34
34
|
| `src/core/canvas.ts` | canvas 补丁:getContext 缓存、WebGL 归一化、离屏画布 | `patchCanvas`、`createOffscreenCanvas` | 上下文丢失、扩展返回值异常、`canvas.canvas` 指向 | `dom.ts`、`runtime.ts`;`tests/runtime.test.ts` |
|
|
35
|
-
| `src/core/image.ts` | Image / ImageData
|
|
35
|
+
| `src/core/image.ts` | Image / ImageData 工厂,对象 URL 直返 `data:`(ADR-0013),**原生事件 → 合成事件桥接(四级兜底)**;`onload`/`onerror` 访问器不遮蔽原生槽位(非派发期间 getter 恒回桥接,ADR-0011);`addEventListener` 与槽位并行接线、`src` 按描述符分流(数据属性直通 + 有界轮询兜底,ADR-0012) | `createImageFactory`、`ImageFactoryOptions`、`ShimImageData` | 图片加载、crossOrigin、`complete` / `decode`、事件不触发、WebP 解码失败、`createImage` 取图入口注入 | `platforms/*`、`dom.ts`;`tests/image-events.test.ts` |
|
|
36
36
|
| `src/core/dom.ts` | `document` / `body` / `screen` / `DOMRect` / `OffscreenCanvas` 构造器 | `createDocument`、`createScreen`、`ShimDOMRect`、`createOffscreenCanvasCtor` | `document.createElement` 新标签、`visibilityState` | `runtime.ts` |
|
|
37
37
|
| `src/core/pointer.ts` | **touch → pointer/mouse 状态机**;`createEvent` 存在时派发真实 DOM 事件,`nativeEventTarget` 为真时不向 scoped `document` / `window` 转派 | `PointerBridge` | 多指、capture、`tap` 无 touches、坐标换算、H5 事件对象形态 | `runtime.ts`、`examples/*`;`tests/runtime.test.ts`、`tests/native-events.test.ts` |
|
|
38
38
|
| `src/core/frames.ts` | rAF 包装、delta、fpsCap、FPS 测量 | `createFrameScheduler` | 帧率限制、慢帧告警 | `runtime.ts` |
|
|
@@ -93,7 +93,7 @@
|
|
|
93
93
|
|
|
94
94
|
## 3.8 修改后必做
|
|
95
95
|
|
|
96
|
-
1. `npm run check`(typecheck +
|
|
96
|
+
1. `npm run check`(typecheck + 107 例单测 + tsup 构建)。
|
|
97
97
|
2. 更新本表(若职责变化)、`docs/04-api-reference.md`(若导出变化)、`CHANGELOG.md`。
|
|
98
98
|
3. 若触及架构不变量,新增或修订 `docs/adr/*.md`。
|
|
99
99
|
4. 若新增了平台能力,更新 `docs/11-compat-matrix.md`。
|
package/docs/04-api-reference.md
CHANGED
|
@@ -43,6 +43,7 @@ interface WeChatGameOptions {
|
|
|
43
43
|
capabilities?: Partial<Capabilities>;
|
|
44
44
|
diagnostics?: Diagnostics;
|
|
45
45
|
preferredFps?: number; // wx.setPreferredFramesPerSecond
|
|
46
|
+
createImage?: () => WxImage; // 替换原始取图(默认 wx.createImage → OffscreenCanvas.createImage)
|
|
46
47
|
}
|
|
47
48
|
type WeChatGameRuntimeOptions = WeChatGameOptions & RuntimeOptions;
|
|
48
49
|
```
|
|
@@ -59,6 +60,7 @@ interface WeChatMiniProgramOptions {
|
|
|
59
60
|
queryDelay?: number; // 等待布局的毫秒数
|
|
60
61
|
capabilities?: Partial<Capabilities>;
|
|
61
62
|
diagnostics?: Diagnostics;
|
|
63
|
+
createImage?: () => WxImage; // 同 WeChatGameOptions
|
|
62
64
|
}
|
|
63
65
|
```
|
|
64
66
|
|
|
@@ -174,7 +176,7 @@ function clearEarlyScopeReads(): void;
|
|
|
174
176
|
| `*Shim` | `HTMLCanvasElementShim`、`HTMLImageElementShim`、`HTMLElementShim`、`OffscreenCanvasShim`、`ImageDataShim`、`WebGLRenderingContextShim`、`WebGL2RenderingContextShim`、`DOMRectShim` |
|
|
175
177
|
| `patchCanvas(raw, options)` | 返回 `{ canvas, contexts, updateRect, element, disposers }`。`nativeEventTarget` 透传给 `patchElement`;无论哪种模式都接管 `getContext`(上下文缓存 + WebGL 归一化) |
|
|
176
178
|
| `createOffscreenCanvas(wx, w?, h?, options?)` | 直接创建并补丁离屏画布 |
|
|
177
|
-
| `createImageFactory(wx, diagnostics?)` | `{ Image, HTMLImageElement, ImageData, createImage, createImageData, createImageBitmap: undefined }
|
|
179
|
+
| `createImageFactory(wx, diagnostics?, options?)` | `{ Image, HTMLImageElement, ImageData, createImage, createImageData, createImageBitmap: undefined }`。`options.createImage?: () => WxImage` 只替换**原始取图**(默认 `wx.createImage()` → `OffscreenCanvas.createImage()`),事件桥接、`src` 分流与兜底照常就地补丁——用于宿主取图语义不同的场景(ADR-0004 / ADR-0012)。工厂按「原生 `addEventListener` → `onload`/`onerror` 赋值 → `wx.getImageInfo` → 2s watchdog」四级兜底把宿主事件桥接成合成事件:`img.onload = fn` 与 `addEventListener('load', fn)` 都能收到通知,`complete` 在成功/失败后都为 `true`,`decode()` 据此 resolve/reject。宿主两种消费时序都覆盖:**赋值即存**(模拟器)与**事件触发时读属性**(真机)——`onload`/`onerror` 访问器在非派发期间永远返回可调用的桥接函数,只有 `dispatchEvent` 行内派发期间返回登记的用户回调,见 [ADR-0011](./adr/0011-host-callback-slot-bridging.md)。`addEventListener` 与回调槽位**并行接线**(真机的 `addEventListener` 可能是空壳),watchdog 超时 `path` 报组合值(如 `addEventListener+onload`)。`src` 按描述符分流:accessor 宿主安装拦截(对象 URL 已直返 `data:`,见 [ADR-0013](./adr/0013-object-url-data-uri.md),拦截只用于兜底触发点);**数据属性宿主完全直通**、绝不 `defineProperty`,兜底由有界轮询(100ms × ≤120)触发,见 [ADR-0012](./adr/0012-host-data-property-boundary.md)。watchdog 对所有宿主无条件生效:`src` 后 2s 内没有真实事件时,`complete` 为真则派发 `load`,否则派发带 `reason` 的 `error` 并 `warnOnce('image-events-timeout', …, { path, src })`,不会无限 pending 也不会无告警 |
|
|
178
180
|
| `createDocument(options)` / `createScreen(w, h)` / `ShimDOMRect` | 伪 DOM 容器 |
|
|
179
181
|
| `PointerBridge` | `dispatch(event, opts?)`、`dispatchMouse(event)`、`setRect`、`refreshRect`、`setPointerCapture`、`releasePointerCapture`、`activePointerCount`、`dispose`。构造选项 `createEvent(type, init)` 存在时派发**真实 DOM 事件**而不是 `MiniEvent`;`nativeEventTarget: true` 时不再向 `document` / `window` 转派(浏览器自己冒泡),见 [ADR-0010](./adr/0010-native-event-target-boundary.md) |
|
|
180
182
|
| `createFrameScheduler(raf, caf, options)` | `request` / `cancel` / `loop(cb)` / `setFpsCap` / `fps` / `dispose` |
|
|
@@ -224,7 +226,7 @@ interface PlatformBinding {
|
|
|
224
226
|
| `atob` / `btoa` / `MiniTextEncoder` / `MiniTextDecoder` | 编码 |
|
|
225
227
|
| `createFetch(wx)` / `MiniXMLHttpRequest` / `createXMLHttpRequestFactory(wx)` / `MiniAbortController` / `MiniAbortSignal` | 网络 |
|
|
226
228
|
|
|
227
|
-
>
|
|
229
|
+
> 注意:`URL.createObjectURL` 直接返回 `data:` URI(同步、无注册表、`revokeObjectURL` 为 no-op),而不是浏览器 `blob:`——微信 image loader 原生可读 `data:`(真机 Android / 基础库 3.18.0 验证至 1.77 MB URI),见 [ADR-0013](./adr/0013-object-url-data-uri.md)。
|
|
228
230
|
|
|
229
231
|
---
|
|
230
232
|
|
|
@@ -98,7 +98,7 @@ renderer.setAnimationLoop(() => {
|
|
|
98
98
|
- 描述符不是唯一入口:有的宿主 `Object.getOwnPropertyDescriptor(img, 'onload')` 返回 `undefined`,但 `img.onload = fn` 仍然有效并能触发。
|
|
99
99
|
- 「能赋值」也分两种**消费时序**:模拟器在赋值那一刻把回调存进宿主内部、事件时直接调用存值;真机在事件触发时读 `image.onload` 属性并调用读到的值。shim 的 `onload` / `onerror` getter 因此在非派发期间**永远返回桥接函数**,只有 `dispatchEvent` 行内派发期间返回登记的用户回调——前者保证真机读到的不是 `undefined`(0.1.7 真机空白根因),后者防止行内派发递归回桥接、用户回调双发([ADR-0011](./adr/0011-host-callback-slot-bridging.md))。
|
|
100
100
|
- **`addEventListener` 与槽位并行接线**(0.1.9):真机的 `addEventListener` 可能是只注册不派发的空壳,不能因为它「挂上了」就跳过 `onload`/`onerror`;`finish` 幂等,双通道也只收敛一次。
|
|
101
|
-
- **`src` 同样要按形态分流**:accessor 宿主(模拟器 / H5)才安装拦截访问器;读取为**数据属性**的宿主(真机)写入经 interceptor 触发加载,`defineProperty` 接管——包括「还原捕获的描述符再写一次」——会把原生加载钩子换成死的普通属性,图片从未开始加载。数据属性宿主完全直通,兜底由有界轮询触发([ADR-0012](./adr/0012-host-data-property-boundary.md)
|
|
101
|
+
- **`src` 同样要按形态分流**:accessor 宿主(模拟器 / H5)才安装拦截访问器;读取为**数据属性**的宿主(真机)写入经 interceptor 触发加载,`defineProperty` 接管——包括「还原捕获的描述符再写一次」——会把原生加载钩子换成死的普通属性,图片从未开始加载。数据属性宿主完全直通,兜底由有界轮询触发([ADR-0012](./adr/0012-host-data-property-boundary.md))。对象 URL 已改为 `createObjectURL` 直接返回 `data:`(0.1.10,[ADR-0013](./adr/0013-object-url-data-uri.md)),这类宿主无需任何拦截即可加载。
|
|
102
102
|
- 「能赋值」还不等于「会触发」:这是 0.1.6 修的边界;不要用 `typeof img.onload === 'function'` 判断宿主是否健康。
|
|
103
103
|
- `patchElement` 在**没有原生事件系统**的宿主上会覆盖 `addEventListener`(小程序 / 小游戏),任何「用原生事件」的方案都必须在它之前保存引用,否则拿到的是 shim。浏览器 canvas 例外:`nativeEventTarget: true` 时事件方法与 DOM 成员一律不动([ADR-0010](./adr/0010-native-event-target-boundary.md))。
|
|
104
104
|
- `src` 同样可能只是可写数据属性。这种情况下 shim 访问器会吞掉写入,`image.ts` 会临时还原宿主属性写一次再装回访问器。
|
|
@@ -29,6 +29,8 @@ export function createFooBinding(options: FooOptions): PlatformBinding {
|
|
|
29
29
|
rawCanvas: host.canvas,
|
|
30
30
|
capabilities: detectCapabilities(host.wxLike, 'browser'),
|
|
31
31
|
imageFactory: createImageFactory(host.wxLike),
|
|
32
|
+
// 取图语义与宿主不同时:createImageFactory(host.wxLike, diagnostics, { createImage: () => host.createImage() })
|
|
33
|
+
// ——只替换原始取图,事件桥接 / src 分流 / 兜底照常就地补丁(ADR-0004)。
|
|
32
34
|
getCanvasRect: () => host.rect(),
|
|
33
35
|
createOffscreenCanvas: (w, h, type) => host.offscreen(w, h, type),
|
|
34
36
|
watchTouch: (handler) => host.onTouch(handler),
|
|
@@ -5,7 +5,7 @@
|
|
|
5
5
|
```bash
|
|
6
6
|
npm install # 安装依赖
|
|
7
7
|
npm run typecheck # tsc --noEmit(strict)
|
|
8
|
-
npm test # vitest run(
|
|
8
|
+
npm test # vitest run(107 例)
|
|
9
9
|
npm test -- --watch # 观察模式
|
|
10
10
|
npm run build # tsup:dist/*.js + *.d.ts + sourcemap
|
|
11
11
|
npm run check # typecheck + test + build
|
|
@@ -91,13 +91,13 @@ jobs:
|
|
|
91
91
|
### 9.5.1 发布前检查
|
|
92
92
|
|
|
93
93
|
```bash
|
|
94
|
-
npm run check # typecheck +
|
|
94
|
+
npm run check # typecheck + 107 例测试 + tsup 构建
|
|
95
95
|
npm run release:check # npm pack --dry-run --json,看将要发布的文件清单
|
|
96
96
|
```
|
|
97
97
|
|
|
98
98
|
`package.json` 已配置 `prepublishOnly: "npm run clean && npm run check"`,`npm publish` 会自动清空 `dist/` 并跑一次完整构建与测试,既不会把未构建的产物发出去,也不会带入历史 hash chunk。发布前确认:
|
|
99
99
|
|
|
100
|
-
- `files` 白名单只包含 `dist/`、`README.md`、`AGENTS.md`、`llms.txt`、`docs/`(0.1.
|
|
100
|
+
- `files` 白名单只包含 `dist/`、`README.md`、`AGENTS.md`、`llms.txt`、`docs/`(0.1.11 实测 80 个文件、解包 768 KB、tarball 219 KB)。体积主要是 `docs/` 的 Markdown 与 `dist/` 的 `.d.ts`,两者都压缩率极高,tarball 增量很小。
|
|
101
101
|
- 测体积前必须先 `npm run clean`(`release:check` 已包含),否则 `dist/` 里上一轮构建残留的 hash chunk 会被一起算进去,实测值会虚高。
|
|
102
102
|
- `exports` 里每个子路径的 `.js` 与 `.d.ts` 都存在。
|
|
103
103
|
- `CHANGELOG.md` 已补上本次版本条目。
|
package/docs/11-compat-matrix.md
CHANGED
|
@@ -59,7 +59,7 @@
|
|
|
59
59
|
| `document.createElementNS` / `body` / `visibilityState` | `createDocument` | ✅ |
|
|
60
60
|
| `HTMLCanvasElement` / `HTMLImageElement` / `HTMLElement` / `OffscreenCanvas` / `ImageData` / `DOMRect` 的 `instanceof` | `Symbol.hasInstance` 注册表 | ✅ |
|
|
61
61
|
| `Event` / `EventTarget` / `CustomEvent` / `PointerEvent` / `MouseEvent` / `MessageEvent` / `ProgressEvent` | `polyfills/event.ts` | ✅ |
|
|
62
|
-
| `Blob` / `URL.createObjectURL` / `URL.revokeObjectURL` |
|
|
62
|
+
| `Blob` / `URL.createObjectURL` / `URL.revokeObjectURL` | 直接返回 `data:` URI(无注册表,`revoke` 为 no-op) | ✅ 真机验证(Android / 基础库 3.18.0,1.77 MB URI) |
|
|
63
63
|
| `URL` 构造 / 相对路径解析 | `MiniURL` | ✅ |
|
|
64
64
|
| `TextEncoder` / `TextDecoder` / `atob` / `btoa` | `polyfills/text-encoding.ts` | ✅ |
|
|
65
65
|
| `fetch` / `XMLHttpRequest` / `AbortController` | `wx.request` 桥接 | 🟡 单元级,真机网络待验证 |
|
|
@@ -67,7 +67,7 @@
|
|
|
67
67
|
| `performance.now` | `wx.getPerformance` → `Date.now` 回退 | ✅ |
|
|
68
68
|
| `getComputedStyle` / `matchMedia` / `screen` / `navigator` | 轻量模拟 | ⚠️ 仅够 three 使用,非完整实现 |
|
|
69
69
|
| `createImageBitmap` | **故意为 `undefined`** | ✅ 让 three 走降级分支 |
|
|
70
|
-
| 图片原生事件(`img.onload` / `addEventListener('load')` / `decode()`) | 四级桥接:原生 `addEventListener` 与 `onload`/`onerror` 槽位**并行**接线 → `wx.getImageInfo` 诊断 → 2s watchdog;`onload` getter 非派发期间恒回桥接(ADR-0011);`src` 为数据属性的真机宿主完全直通 + 有界轮询兜底(ADR-0012) |
|
|
70
|
+
| 图片原生事件(`img.onload` / `addEventListener('load')` / `decode()`) | 四级桥接:原生 `addEventListener` 与 `onload`/`onerror` 槽位**并行**接线 → `wx.getImageInfo` 诊断 → 2s watchdog;`onload` getter 非派发期间恒回桥接(ADR-0011);`src` 为数据属性的真机宿主完全直通 + 有界轮询兜底(ADR-0012) | ✅ 单测 26 例覆盖「赋值即存 / 触发时读属性 / src 为 accessor 或数据属性 / 空壳 addEventListener」全部宿主形态;**真机复测通过**(0.1.9,业务侧 2026-11-22,`e59bf80` 构建对照出图) |
|
|
71
71
|
| 纹理格式 | PNG / JPEG | ✅ WebP 在部分真机解码失败,见 §11.6 |
|
|
72
72
|
| `FileReader` / `WebSocket` / `AudioContext` | 缺省或透传 | ⚠️ 业务需要时按 `docs/08` 扩展 |
|
|
73
73
|
| `Worker` / `WebAssembly` | 透传宿主全局(`WXWebAssembly`) | 🟡 |
|
|
@@ -84,7 +84,7 @@
|
|
|
84
84
|
| `loader_*` | GLTF / DRACO / KTX2 / OBJ / FBX | ⬜ 未回归 | 需配置 decoder 路径与分包 |
|
|
85
85
|
| `postprocessing_*` | EffectComposer / bloom / SSAO | ⬜ 未回归 | 注意深度缓冲与 render target 尺寸 |
|
|
86
86
|
| `animation_*` / `physics_*` | 骨骼动画 / wasm 物理 | ⬜ 未回归 | 涉及 wasm 资源预下载 |
|
|
87
|
-
| 基础渲染 | `examples/wechat-minigame`、`wechat-miniprogram`、`h5` | ✅ 单元级 |
|
|
87
|
+
| 基础渲染 | `examples/wechat-minigame`、`wechat-miniprogram`、`h5` | ✅ 单元级 | 105 个 Vitest 用例覆盖画布、事件、作用域、插件 |
|
|
88
88
|
|
|
89
89
|
每回归一条,在本表追加:`场景 id | three 版本 | 基础库 | 设备 | 结果 | 失败原因 | 新增 polyfill`。
|
|
90
90
|
|
|
@@ -94,7 +94,7 @@
|
|
|
94
94
|
2. `createImageBitmap` 恒为 `undefined`,依赖该 API 的库需自带降级。
|
|
95
95
|
3. 不提供完整 DOM;DOM 密集型 UI 库应走 WebView 方案。
|
|
96
96
|
4. 插件默认只改写 `node_modules` 中的三方生态代码;应用代码里直接写 `window` 不会自动改写(可开 `includeUserCode`)。
|
|
97
|
-
5. 对象 URL
|
|
97
|
+
5. 对象 URL 直接返回 `data:` URI,不是浏览器 `blob:`;若有库硬编码 `blob:` 前缀或期望可 `fetch` 的 URL,需要适配。
|
|
98
98
|
6. Worker 分包、`.wasm.br`、iOS 高性能+ 需业务按 `mini-three-assets.json` 的 `gameJsonSuggestion` 自行配置,插件不直接改 `game.json`。
|
|
99
99
|
7. 纹理请使用 PNG / JPEG。**WebP 在部分真机上无法解码**(`wx.createImage` 直接触发 `error`),这与适配层无关;`mini-three-adapter` 只会在 `wx.getImageInfo` 失败时给出指向格式的告警。
|
|
100
|
-
8. 图片事件桥接依赖宿主投递事件。真正的 `load`/`error` 拿不到时(宿主三种入口全无,或接受了 `onload` 却永不调用),一律在 **2s** 内由 watchdog 给出终态:`complete` 为真则派发 `load`,否则派发 `error` 并 `warnOnce('image-events-timeout', …, { path, src })`。这意味着 >2s 才能解码完的网络大图会被判失败,包内纹理不受影响。宿主「触发时读属性」(ADR-0011)与「`src` 为数据属性」(ADR-0012
|
|
100
|
+
8. 图片事件桥接依赖宿主投递事件。真正的 `load`/`error` 拿不到时(宿主三种入口全无,或接受了 `onload` 却永不调用),一律在 **2s** 内由 watchdog 给出终态:`complete` 为真则派发 `load`,否则派发 `error` 并 `warnOnce('image-events-timeout', …, { path, src })`。这意味着 >2s 才能解码完的网络大图会被判失败,包内纹理不受影响。宿主「触发时读属性」(ADR-0011)与「`src` 为数据属性」(ADR-0012)的形态由访问器恒回桥接与完全直通分别保证。对象 URL 现为 `data:` URI,数据属性宿主可直接加载(0.1.10 真机验证)。
|
|
@@ -18,7 +18,7 @@
|
|
|
18
18
|
2. **禁止对宿主数据属性做 `defineProperty` 接管**——不只 `src`:任何「读取为数据属性、但写入/读取带原生语义」的宿主属性(`onprogress` / `ontimeupdate` / `onended` 等)同理。判断依据是描述符里的 `writable && !set`;「还原捕获的描述符」不是恢复原生的手段。
|
|
19
19
|
3. **事件通道并行接线**:`addEventListener` 与 `onload`/`onerror` 槽位都挂,不 else-if。`finish` 幂等(终态一次)保证双通道只收敛一次;watchdog 超时 `path` 报组合值(如 `addEventListener+onload`),超时能指认全部已挂通道。
|
|
20
20
|
4. **数据属性宿主的兜底由有界轮询驱动**:100ms 一次、120 次封顶(12s)侦测首次 `src` 写入后触发 `startFallback`(看门狗 / `wx.getImageInfo`);终态(`finish`)或封顶自动停表。创建后从未赋值的图片不保留任何定时器。
|
|
21
|
-
5.
|
|
21
|
+
5. (0.1.10 修订,[ADR-0013](./0013-object-url-data-uri.md))对象 URL 改为 `createObjectURL` 直接返回 `data:` URI,数据属性宿主无需改写即可加载;本决策原先的 `image-src-object-url` 告警与文件桥待办一并取消。
|
|
22
22
|
|
|
23
23
|
## 理由
|
|
24
24
|
|
|
@@ -29,7 +29,7 @@
|
|
|
29
29
|
## 后果
|
|
30
30
|
|
|
31
31
|
- 正面:真机(数据属性 `src` + 空壳 `addEventListener` + 读属性槽位)出图;两层根因各有独立的单元宿主形态钉住。
|
|
32
|
-
-
|
|
32
|
+
- 负面(0.1.9 时):数据属性宿主上的对象 URL 无法加载(既有缺口显性化 + `image-src-object-url` 告警);0.1.10 起由 [ADR-0013](./0013-object-url-data-uri.md) 解决——对象 URL 直接是 `data:`,直通宿主同样可加载。
|
|
33
33
|
- 负面:轮询为每张图片保留一个 100ms 定时器直至首次写入或 12s 封顶;three 的 `ImageLoader` 在创建当帧赋值,实际开销 1–2 tick。
|
|
34
34
|
- 风险:若未来宿主在 `src` 上同时暴露 setter 描述符与 interceptor 语义,分流会走 accessor 分支——`writeNativeSrc` 用捕获的原生 setter 直写,仍然成立。
|
|
35
35
|
|
|
@@ -43,4 +43,4 @@
|
|
|
43
43
|
## 验证方式
|
|
44
44
|
|
|
45
45
|
- `tests/image-events.test.ts`:Proxy 宿主(数据描述符 + 写入副作用 + `defineProperty` 计数 + 空壳 `addEventListener` + 读属性槽位)端到端出图、`src` 永不被 defineProperty、轮询 + 组合 path 超时、双通道单次收敛、getImageInfo 经轮询、对象 URL 告警。
|
|
46
|
-
-
|
|
46
|
+
- 真机复测:✅ 2026-11-22 业务侧升级 0.1.9 实测通过(`e59bf80` 构建对照,启动页位图经标准 `TextureLoader` 出图,console 无 `image-events-timeout` / `image-src-object-url`)。
|
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
# ADR-0013 · 对象 URL 直接返回 data: URI
|
|
2
|
+
|
|
3
|
+
- 状态:Accepted
|
|
4
|
+
- 日期:2026-11-22
|
|
5
|
+
- 影响模块:`src/polyfills/blob-url.ts`、`src/core/image.ts`
|
|
6
|
+
|
|
7
|
+
## 背景
|
|
8
|
+
|
|
9
|
+
0.1.9 把「`src` 为原生数据属性」的真机宿主改为完全直通(ADR-0012)后,对象 URL 成为该类宿主唯一读不了的东西:旧的 `mini-three-blob:<id>` 注册表依赖「写入 `img.src` 时改写为 `data:`」,而直通宿主没有改写点,原生 loader 收到 `mini-three-blob:...` 直接失败。P2 待办最初拟定的方案是「`createObjectURL` 落盘 `wx.env.USER_DATA_PATH` 返回文件路径」。
|
|
10
|
+
|
|
11
|
+
重估后发现该方案与 web 契约冲突:`URL.createObjectURL` 必须**同步**返回字符串,而 `writeFile` 是异步的——GLTFLoader 拿到返回值后立即赋给 `img.src`,文件未写完就加载,属于同一类「模拟器正常、真机间歇失败」的缺陷;还要额外承担临时文件清理、配额、扩展名嗅探与 polyfill 边界(polyfills 不得读 `globalThis.wx`)。
|
|
12
|
+
|
|
13
|
+
关键事实:项目最初的设计表述就是「对象 URL → `data:` URI,宿主图片加载器可直接识别,无需拦截 `Image.src`」([docs/01](../01-design-principles.md)),只是实现后来演化成了注册表 + 写入时改写。
|
|
14
|
+
|
|
15
|
+
## 决策
|
|
16
|
+
|
|
17
|
+
1. `MiniURL.createObjectURL(blob)` **同步返回 `blob.dataURL()`**,即 `data:<mime>;base64,...`;不再产生 `mini-three-blob:` 句柄,不再维护注册表。
|
|
18
|
+
2. `revokeObjectURL` 为 no-op(API 兼容保留);`resolveObjectURL` 恒返回 `null`;`clearObjectURLs` 为 no-op;`OBJECT_URL_PREFIX` 保留导出并标记 deprecated。
|
|
19
|
+
3. `image.ts` 删除 `resolveSrc` 与对 `MiniURL` 的依赖;0.1.9 的 `image-src-object-url` 告警与相关分支删除。
|
|
20
|
+
4. watchdog 告警 payload 的 `src` 对长 `data:` URI 截断描述(`data:image/png;base64,…(1772874 chars)`)。
|
|
21
|
+
5. 不做尺寸阈值/混合落盘:真机探针覆盖到 1.77 MB URI,未出现解码失败;超大内嵌贴图的生产建议仍是「外部化纹理」。
|
|
22
|
+
|
|
23
|
+
## 理由
|
|
24
|
+
|
|
25
|
+
- **同步契约**:`data:` 在 `createObjectURL` 返回的同一 tick 就可用,与浏览器 `blob:` 的同步语义一致;文件落盘做不到。
|
|
26
|
+
- **零生命周期**:没有临时文件、没有清理、没有配额、没有注册表;顺带消除「未被 revoke 的 `MiniBlob` 常驻」的既有泄漏。
|
|
27
|
+
- **统一宿主**:`data:` 是字符串本身,accessor 宿主与数据属性宿主走出完全相同的路径,`src` 拦截不再是对象 URL 的前提。
|
|
28
|
+
- **真机证据**(Android / 基础库 3.18.0):1×1 PNG 169ms、1080×1912 JPEG(142 KB URI)164ms、256×256 PNG(198 KB URI)149ms、768×768 PNG(**1.77 MB URI**)174ms,全部 `onload` 成功。
|
|
29
|
+
|
|
30
|
+
## 后果
|
|
31
|
+
|
|
32
|
+
- 正面:数据属性宿主可加载 GLTF 内嵌贴图;`createObjectURL` 与 docs/01 的原始设计重新一致;对象 URL 相关的代码与时序分支更少。
|
|
33
|
+
- 负面:`data:` 在 `createObjectURL` 那一刻就 eager 编码(base64 是同步 CPU + 字符串内存)。three 的 loaders 都是 create→load 紧邻,等价于旧的「写入时编码」;但持有对象 URL 一段时间再用的代码会提前付出内存。
|
|
34
|
+
- 负面:`revokeObjectURL` 不再使 URL 失效(浏览器语义差异)。实践中没有依赖者(three 的 loaders 亦不保证 revoke)。
|
|
35
|
+
- 风险:超大内嵌贴图(数十 MB)会生成超大字符串,内存峰值取决于设备;生产建议外部化纹理,并可在业务侧预压缩。
|
|
36
|
+
|
|
37
|
+
## 被否决的备选方案
|
|
38
|
+
|
|
39
|
+
- **注册表 + 写入 `src` 时改写(0.1.4–0.1.9)**:依赖 `src` 拦截,直通宿主没有改写点。
|
|
40
|
+
- **`createObjectURL` 落盘文件(原 P2 待办)**:异步写违反同步契约(竞态)、生命周期与配额成本、跨 polyfill 边界。
|
|
41
|
+
- **阈值混合(小图 `data:`、大图落盘)**:真机探针未发现尺寸失败,先不引入两套语义;需要时再作为增补。
|
|
42
|
+
- **轮询检测到 `mini-three-blob:` 再改写 src**:会与原生首次失败事件竞争,可能先派发 error 终态。
|
|
43
|
+
|
|
44
|
+
## 验证方式
|
|
45
|
+
|
|
46
|
+
- `tests/polyfills.test.ts`:`createObjectURL` 返回可加载的 `data:`;`resolveObjectURL` 恒 `null`;revoke no-op。
|
|
47
|
+
- `tests/image-events.test.ts`:「对象 URL 是 `data:`,数据属性宿主直通加载」。
|
|
48
|
+
- 真机探针记录:Android / 基础库 3.18.0,四个尺寸全部出图(见上)。
|
package/docs/adr/README.md
CHANGED
|
@@ -16,6 +16,7 @@
|
|
|
16
16
|
| [0010](./0010-native-event-target-boundary.md) | 原生事件目标不做 EventTarget 替换,`patchElement` 改为补缺不覆盖 | Accepted |
|
|
17
17
|
| [0011](./0011-host-callback-slot-bridging.md) | 宿主回调槽位的访问器不得遮蔽桥接:getter 非派发期间恒回桥接函数 | Accepted |
|
|
18
18
|
| [0012](./0012-host-data-property-boundary.md) | 宿主数据属性不得用 defineProperty 接管:src 按描述符分流 + 事件并行接线 + 有界轮询兜底 | Accepted |
|
|
19
|
+
| [0013](./0013-object-url-data-uri.md) | 对象 URL 直接返回 `data:` URI:同步、无注册表、无落盘 | Accepted |
|
|
19
20
|
|
|
20
21
|
模板(新增 ADR 时复制):
|
|
21
22
|
|
package/package.json
CHANGED