mini-three-adapter 0.1.3 → 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-OL7NVZZJ.js → chunk-26BRT4GS.js} +21 -12
- package/dist/chunk-26BRT4GS.js.map +1 -0
- package/dist/{chunk-WZ2HKYC5.js → chunk-2WNTAMJZ.js} +4 -4
- package/dist/{chunk-WZ2HKYC5.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-3QUEDYTT.js → chunk-HJIO6AFC.js} +19 -11
- package/dist/chunk-HJIO6AFC.js.map +1 -0
- package/dist/{chunk-52IMRKOX.js → chunk-NC2FTUEU.js} +3 -3
- package/dist/{chunk-52IMRKOX.js.map → chunk-NC2FTUEU.js.map} +1 -1
- package/dist/{chunk-J7VBWZRR.js → chunk-XUKHCVAV.js} +11 -3
- package/dist/chunk-XUKHCVAV.js.map +1 -0
- package/dist/core/index.js +2 -2
- package/dist/index.d.ts +1 -1
- package/dist/index.js +6 -6
- package/dist/platforms/browser.js +3 -3
- package/dist/platforms/wechat-game.js +4 -4
- package/dist/platforms/wechat-miniprogram.js +4 -4
- 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 +5 -5
- package/docs/07-integration-guide.md +1 -1
- package/docs/09-testing-and-release.md +210 -209
- package/docs/10-ai-playbook.md +2 -1
- package/docs/11-compat-matrix.md +2 -2
- package/docs/adr/0007-capability-probe-fallback.md +8 -4
- package/docs/adr/0008-probe-fallback-boundary.md +56 -0
- package/docs/adr/0009-placeholder-scope-environment-globals.md +69 -0
- package/docs/adr/README.md +3 -1
- package/llms.txt +4 -1
- package/package.json +1 -1
- package/dist/chunk-34RWHAW4.js.map +0 -1
- package/dist/chunk-3QUEDYTT.js.map +0 -1
- package/dist/chunk-J7VBWZRR.js.map +0 -1
- package/dist/chunk-OL7NVZZJ.js.map +0 -1
|
@@ -1,7 +1,7 @@
|
|
|
1
|
-
export { createWeChatGameBinding, createWeChatGameRuntime, getScreenCanvas, resetScreenCanvasCache } from '../chunk-
|
|
2
|
-
import '../chunk-
|
|
3
|
-
import '../chunk-
|
|
4
|
-
import '../chunk-
|
|
1
|
+
export { createWeChatGameBinding, createWeChatGameRuntime, getScreenCanvas, resetScreenCanvasCache } from '../chunk-HJIO6AFC.js';
|
|
2
|
+
import '../chunk-26BRT4GS.js';
|
|
3
|
+
import '../chunk-XUKHCVAV.js';
|
|
4
|
+
import '../chunk-35XVAVDB.js';
|
|
5
5
|
import '../chunk-LCJNTN6F.js';
|
|
6
6
|
import '../chunk-V6TY7KAL.js';
|
|
7
7
|
//# sourceMappingURL=wechat-game.js.map
|
|
@@ -1,7 +1,7 @@
|
|
|
1
|
-
export { createWeChatMiniProgramBinding, createWeChatMiniProgramRuntime } from '../chunk-
|
|
2
|
-
import '../chunk-
|
|
3
|
-
import '../chunk-
|
|
4
|
-
import '../chunk-
|
|
1
|
+
export { createWeChatMiniProgramBinding, createWeChatMiniProgramRuntime } from '../chunk-2WNTAMJZ.js';
|
|
2
|
+
import '../chunk-26BRT4GS.js';
|
|
3
|
+
import '../chunk-XUKHCVAV.js';
|
|
4
|
+
import '../chunk-35XVAVDB.js';
|
|
5
5
|
import '../chunk-LCJNTN6F.js';
|
|
6
6
|
import '../chunk-V6TY7KAL.js';
|
|
7
7
|
//# sourceMappingURL=wechat-miniprogram.js.map
|
package/dist/scope.d.ts
CHANGED
|
@@ -117,6 +117,13 @@ interface MiniThreeScope extends EventTargetLike {
|
|
|
117
117
|
ResizeObserver: unknown;
|
|
118
118
|
[key: string]: unknown;
|
|
119
119
|
}
|
|
120
|
+
/**
|
|
121
|
+
* Names read from the placeholder scope before any runtime existed. Reported
|
|
122
|
+
* once by `createRuntime()`: it means some module was evaluated too early.
|
|
123
|
+
*/
|
|
124
|
+
declare function getEarlyScopeReads(): readonly string[];
|
|
125
|
+
/** Clear the recorded early reads (called by `createRuntime()` after reporting). */
|
|
126
|
+
declare function clearEarlyScopeReads(): void;
|
|
120
127
|
/** Returns the currently installed scope (or the throwing placeholder). */
|
|
121
128
|
declare function getActiveScope(): MiniThreeScope;
|
|
122
129
|
/** Install / replace the active scope. Returns a disposer. */
|
|
@@ -143,4 +150,4 @@ interface InstallGlobalsOptions {
|
|
|
143
150
|
*/
|
|
144
151
|
declare function installGlobals(scope: MiniThreeScope, options?: InstallGlobalsOptions): () => void;
|
|
145
152
|
|
|
146
|
-
export { type DocumentLike, type ElementLike, type InstallGlobalsOptions, type MiniThreeScope, type NavigatorLike, createScope, getActiveScope, hasActiveScope, installGlobals, setActiveScope };
|
|
153
|
+
export { type DocumentLike, type ElementLike, type InstallGlobalsOptions, type MiniThreeScope, type NavigatorLike, clearEarlyScopeReads, createScope, getActiveScope, getEarlyScopeReads, hasActiveScope, installGlobals, setActiveScope };
|
package/dist/scope.js
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
export { createScope, getActiveScope, hasActiveScope, installGlobals, setActiveScope } from './chunk-
|
|
1
|
+
export { clearEarlyScopeReads, createScope, getActiveScope, getEarlyScopeReads, hasActiveScope, installGlobals, setActiveScope } from './chunk-35XVAVDB.js';
|
|
2
2
|
import './chunk-V6TY7KAL.js';
|
|
3
3
|
//# sourceMappingURL=scope.js.map
|
|
4
4
|
//# sourceMappingURL=scope.js.map
|
package/docs/02-architecture.md
CHANGED
|
@@ -54,7 +54,7 @@ src/index.ts 汇总导出
|
|
|
54
54
|
|
|
55
55
|
1. `createWeChatGameRuntime(options)` → `createWeChatGameBinding()`。
|
|
56
56
|
2. `getScreenCanvas(wx)` 按 `options.canvas` → `GameGlobal.screencanvas` → `globalThis.canvas` → `wx.createCanvas()` 的顺序取**唯一**上屏画布,并做模块级缓存。
|
|
57
|
-
3. `detectCapabilities()` 优先用 `wx.createOffscreenCanvas()` 探测 WebGL2
|
|
57
|
+
3. `detectCapabilities()` 优先用 `wx.createOffscreenCanvas()` 探测 WebGL2;上屏画布已解析且离屏 API 存在时,允许显式回退到第二次 `wx.createCanvas()`,并对候选上屏画布集合做身份拒绝([ADR-0007](./adr/0007-capability-probe-fallback.md)、[ADR-0008](./adr/0008-probe-fallback-boundary.md))。探测不到时返回 `undefined`,按基础库版本推断并在 `webgl2Source` 标明,**绝不把「探测不到」当成 `false`**。
|
|
58
58
|
4. `createDocument()` 建出 `document` / `body` / `screen` 等容器;`createElement('canvas')` 走 `webgl2` 离屏画布,失败降级 `2d` 并告警。
|
|
59
59
|
5. `patchCanvas()` 在原对象上定义 `style` / `clientWidth` / `getBoundingClientRect` / `getContext` / EventTarget 方法,并注册到 `HTMLCanvasElementShim` 的 `WeakSet`。
|
|
60
60
|
6. 组装 `MiniThreeScope`(polyfill 构造器 + 领域对象 + live getter),`setActiveScope(scope)` 让 `__m3()` 生效。
|
|
@@ -98,7 +98,7 @@ sequenceDiagram
|
|
|
98
98
|
|
|
99
99
|
## 2.5 架构不变量(AI 必读,不得破坏)
|
|
100
100
|
|
|
101
|
-
1. **只有一个上屏画布**:`wx.createCanvas()` 只在 `getScreenCanvas()`
|
|
101
|
+
1. **只有一个上屏画布**:`wx.createCanvas()` 只在 `getScreenCanvas()` 中调用一次并被缓存;能力探测只能走 `wx.createOffscreenCanvas()`,唯一的例外是「离屏 API 存在、上屏画布已解析、且调用方显式 opt-in」时的回退探测,且回退对象必须与**候选上屏画布集合**逐个比对身份(ADR-0007、ADR-0008)。
|
|
102
102
|
2. **对象身份不变**:canvas / image 永远是 `wx` 返回的那个对象;禁止 `new Proxy` 包装、禁止 `Object.setPrototypeOf`、禁止返回克隆体。
|
|
103
103
|
3. **默认零全局污染**:只有 `installGlobals()` 会写 `globalThis`,且必须可逆;`getActiveScope()` 是三方代码访问 shim 的唯一通道。
|
|
104
104
|
4. **`three` 零运行时依赖**:`src/` 不 import `three`,`package.json` 中它只是 optional peer。
|
|
@@ -114,10 +114,10 @@ sequenceDiagram
|
|
|
114
114
|
| 情况 | 行为 |
|
|
115
115
|
| --- | --- |
|
|
116
116
|
| 没有 `wx`(Node/浏览器) | `createWeChatGameRuntime({ wx })` 可注入;`browser` 平台用真实 DOM |
|
|
117
|
-
| `createOffscreenCanvas` 不可用 |
|
|
117
|
+
| `createOffscreenCanvas` 不可用 | 直接放弃兜底,标记 `webgl2Source: 'inferred'`(按基础库版本推断);`createCanvas()` 抛明确错误;文档提示升级基础库。**不**回退到 `createCanvas()`,因为无法判断首次调用是否已被消耗(ADR-0008) |
|
|
118
118
|
| WebGL2 不可用 | `diagnostics.warn` + 能力报告;不静默降级到 WebGL1(three ≥ r163 也无法工作) |
|
|
119
119
|
| `wx.createImage` 缺失 | 回退 `OffscreenCanvas.createImage()`,再失败抛可操作错误 |
|
|
120
|
-
| `typeof window` 在 runtime 之前被读取 | `emptyScope` 让 `typeof` 返回 `'object'
|
|
120
|
+
| `typeof window` / `typeof document` 在 runtime 之前被读取 | `emptyScope` 让 `typeof window` 返回 `'object'`;`document` / `navigator` / `screen` / `location` / `history` 返回 `undefined`(等价于「没有 DOM 的宿主」),其余键真正取值时抛带指引的错误;早读会被记录,`createRuntime()` 启动时 `warnOnce` 汇总一次([ADR-0009](./adr/0009-placeholder-scope-environment-globals.md)) |
|
|
121
121
|
| AST 解析失败 | 插件记录 `parseFailures`、告警并跳过该模块,绝不产出半改写代码 |
|
|
122
122
|
| 找不到 wasm/worker | 记录 `missingAssets` 并告警,不中断构建 |
|
|
123
123
|
|
package/docs/03-module-map.md
CHANGED
|
@@ -1,99 +1,99 @@
|
|
|
1
|
-
# 03 · 模块地图(AI 修改入口索引)
|
|
2
|
-
|
|
3
|
-
> **给 AI 用**:动手前先在这张表里定位目标文件;「改这里」列给出常见需求的最小改动面,「会影响」列给出必须同步检查的下游。
|
|
4
|
-
> 依赖层级:`types → scope / polyfills → core → platforms`;`build` 是独立分支。
|
|
5
|
-
|
|
6
|
-
## 3.1 根与协议层
|
|
7
|
-
|
|
8
|
-
| 文件 | 职责 | 关键导出 | 改这里 | 会影响 |
|
|
9
|
-
| --- | --- | --- | --- | --- |
|
|
10
|
-
| `src/types.ts` | 全部公开类型,纯 type-only | `Rect`、`WindowInfo`、`Capabilities`、`PatchedCanvas`、`TouchLikeEvent`、`FrameScheduler`、`RuntimeEvents` 等 | 新增平台能力字段、事件名称 | `core/*`、`platforms/*`、`dist/*.d.ts`、`docs/04` |
|
|
11
|
-
| `src/scope.ts` | 作用域协议:`MiniThreeScope
|
|
12
|
-
| `src/index.ts` | 汇总导出 | 全部公开 API | 新增公共入口 | `package.json` `exports`、`docs/04` |
|
|
13
|
-
| `src/core/index.ts` | core 子路径导出 | core API | 同上 | `docs/04` |
|
|
14
|
-
| `src/polyfills/index.ts` | polyfills 子路径导出 | polyfill API | 同上 | `docs/04` |
|
|
15
|
-
|
|
16
|
-
## 3.2 polyfills(自包含,无平台知识)
|
|
17
|
-
|
|
18
|
-
| 文件 | 职责 | 关键导出 | 改这里 | 会影响 / 测试 |
|
|
19
|
-
| --- | --- | --- | --- | --- |
|
|
20
|
-
| `src/polyfills/event.ts` | W3C 事件系统,`patchEventTarget` 把方法绑到内部载体但把 `this` / `event.target` / `currentTarget` 转发给宿主元素 | `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 相对解析 | `MiniBlob`、`MiniURL`、`bytesToBase64`、`resolveUrl` | `createObjectURL` 的目标格式、URL 解析边界 | `image.ts` 的 `src` 解析;`tests/polyfills.test.ts` |
|
|
22
|
-
| `src/polyfills/text-encoding.ts` | `atob`/`btoa`/`TextEncoder`/`TextDecoder` | 同名 | 编码边界、BOM、utf-16 | `network.ts`、`blob-url.ts`;`tests/polyfills.test.ts` |
|
|
23
|
-
| `src/polyfills/network.ts` | `fetch`、`XMLHttpRequest`、`AbortController` | `createFetch`、`createXMLHttpRequestFactory`、`MiniAbortController` | `wx.request` 返回结构差异、进度事件 | `runtime.ts` 的 scope 组装;`tests/polyfills.test.ts` |
|
|
24
|
-
|
|
25
|
-
> 约束:polyfills 不得 import `core/*`,不得读取 `globalThis.wx`。
|
|
26
|
-
|
|
27
|
-
## 3.3 core(平台无关运行时)
|
|
28
|
-
|
|
29
|
-
| 文件 | 职责 | 关键导出 | 改这里 | 会影响 / 测试 |
|
|
30
|
-
| --- | --- | --- | --- | --- |
|
|
31
|
-
| `src/core/platform.ts` | **平台契约**(结构化接口,替代抽象基类) | `PlatformBinding`、`PlatformFactory` | 平台要新增能力时**先改这里** | 所有 `platforms/*`、`runtime.ts` |
|
|
32
|
-
| `src/core/runtime.ts` | **总装配**:画布补丁、scope 组装、订阅、生命周期 | `createRuntime`、`MiniThreeRuntime`、`RuntimeOptions`、`RendererHints` | 新增 runtime API、新增/移除全局项、调整启动顺序 | 几乎所有模块;`tests/runtime.test.ts` |
|
|
33
|
-
| `src/core/element.ts` | 就地 DOM 属性补丁 + `Symbol.hasInstance` 注册表 | `patchElement`、`createMockClass`、`*Shim`、`normalizeRect` | three 报「DOM 属性缺失」、`instanceof` 失败 | `canvas.ts`、`image.ts`、`dom.ts` |
|
|
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 工厂,blob URL → data URL,**原生 `onload`/`onerror` → 合成事件桥接** | `createImageFactory`、`ShimImageData` | 图片加载、crossOrigin、decode、事件不触发 | `platforms/*`、`dom.ts`;`tests/image-events.test.ts` |
|
|
36
|
-
| `src/core/dom.ts` | `document` / `body` / `screen` / `DOMRect` / `OffscreenCanvas` 构造器 | `createDocument`、`createScreen`、`ShimDOMRect`、`createOffscreenCanvasCtor` | `document.createElement` 新标签、`visibilityState` | `runtime.ts` |
|
|
37
|
-
| `src/core/pointer.ts` | **touch → pointer/mouse 状态机** | `PointerBridge` | 多指、capture、`tap` 无 touches、坐标换算 | `runtime.ts`、`examples/*`;`tests/runtime.test.ts` |
|
|
38
|
-
| `src/core/frames.ts` | rAF 包装、delta、fpsCap、FPS 测量 | `createFrameScheduler` | 帧率限制、慢帧告警 | `runtime.ts` |
|
|
39
|
-
| `src/core/window-info.ts` | 窗口信息 + DPR 封顶 + resize 广播 | `createWindowInfoStore`、`readWindowInfo` | 新 API 替代 `getWindowInfo`、安全区 | `runtime.ts`;`tests/runtime.test.ts` |
|
|
40
|
-
| `src/core/capabilities.ts` | 能力探测(离屏优先,主画布回退;**不消费上屏画布**) | `detectCapabilities`、`versionAtLeast`、`webgl2Source` | 新增探测项、「探测不到」的语义 | 所有 `platforms/*`、`runtime.report()`;`tests/capabilities.test.ts` |
|
|
41
|
-
| `src/core/diagnostics.ts` | 分级日志、`warnOnce`、能力报告 | `createDiagnostics`、`capabilityReport` | 日志格式、报告字段 | 全局;`tests/runtime.test.ts` |
|
|
42
|
-
|
|
43
|
-
> 约束:`core/*` 不得 import `platforms/*`,不得 import `three`,不得直接写 `globalThis`。
|
|
44
|
-
|
|
45
|
-
## 3.4 platforms(平台差异收敛点)
|
|
46
|
-
|
|
47
|
-
| 文件 | 职责 | 关键导出 | 改这里 | 会影响 |
|
|
48
|
-
| --- | --- | --- | --- | --- |
|
|
49
|
-
| `src/platforms/wx-types.ts` | 手写最小 `wx` 结构化类型(不依赖官方 typings) | `WxLike`、`WxCanvas`、`WxTouchEvent`、`resolveWx` | 用到新的 `wx.*` API 时补类型 | 所有平台;`docs/04` |
|
|
50
|
-
| `src/platforms/wechat-common.ts` | rAF / now / touch / visibility / 离屏画布 / 能力探测共用实现 | `watchWxTouch`、`createRafPair`、`probeContext`(返回 `boolean \| undefined
|
|
51
|
-
| `src/platforms/wechat-game.ts` | 小游戏绑定 + 入口 | `createWeChatGameRuntime`、`createWeChatGameBinding`、`getScreenCanvas` | **上屏画布获取顺序**、锁帧 | `examples/wechat-minigame` |
|
|
52
|
-
| `src/platforms/wechat-miniprogram.ts` | 小程序绑定(`createSelectorQuery`) | `createWeChatMiniProgramRuntime` | 选择器查询、组件作用域 `selectorCtx` | `examples/wechat-miniprogram` |
|
|
53
|
-
| `src/platforms/browser.ts` | 浏览器 / Node 测试平台 | `createBrowserRuntime`、`createBrowserBinding` | H5 双端能力 | `examples/h5` |
|
|
54
|
-
|
|
55
|
-
## 3.5 build(Node 侧,不进小游戏 bundle)
|
|
56
|
-
|
|
57
|
-
| 文件 | 职责 | 关键导出 | 改这里 | 会影响 / 测试 |
|
|
58
|
-
| --- | --- | --- | --- | --- |
|
|
59
|
-
| `src/build/scope-rewrite.ts` | **AST 全局重写**,`@babel/parser` + `path.scope.hasBinding` | `rewriteGlobals`、`DEFAULT_GLOBAL_NAMES`、`DEFAULT_FORCE_UNDEF` | 需要改写的全局清单、访问器名、注入的 import | 所有三方模块;`tests/scope-rewrite.test.ts`、[ADR-0003](./adr/0003-ast-rewrite.md) |
|
|
60
|
-
| `src/build/assets.ts` | worker/wasm 引用扫描、解析、拷贝、manifest | `collectAssetReferences`、`collectAssets`、`copyAssets`、`AssetManifest` | 新 decoder 类型、输出目录、`game.json` 建议 | `plugin-core.ts`;`tests/plugin.test.ts` |
|
|
61
|
-
| `src/build/plugin-core.ts` | Rollup/Vite 兼容插件核心 | `miniThreePlugin`、`BuildReport` | include 规则、WebGPU 策略、构建报告 | `vite.ts`、`rollup.ts`;`tests/plugin.test.ts` |
|
|
62
|
-
| `src/build/vite.ts` | Vite 入口 + `optimizeDeps.exclude` 配置 | `miniThree`(default) | Vite 版本兼容 | `examples/*/vite.config.ts` |
|
|
63
|
-
| `src/build/rollup.ts` | Rollup 入口 + 高级 API 再导出 | `miniThree`、`rewriteGlobals` 等 | Rollup 集成 | `docs/05` |
|
|
64
|
-
|
|
65
|
-
> 约束:`build/*` 不得 import `core/*` / `platforms/*`;`node:fs` 只允许出现在这里。
|
|
66
|
-
|
|
67
|
-
## 3.6 配置与示例
|
|
68
|
-
|
|
69
|
-
| 文件 | 作用 |
|
|
70
|
-
| --- | --- |
|
|
71
|
-
| `package.json` | `exports` 子路径、`sideEffects`、peer(`three`/`vite`/`rollup` 均 optional) |
|
|
72
|
-
| `tsconfig.json` | strict + `noUncheckedIndexedAccess` + `verbatimModuleSyntax`;`include` 覆盖 `src/tests/config` |
|
|
73
|
-
| `tsup.config.ts` | 两套构建:runtime(es2019 / neutral / dts / splitting)与 build tooling(node18 / 无 splitting) |
|
|
74
|
-
| `vitest.config.ts` | 单 fork 执行(规避 Windows 临时目录权限),`cache: false` |
|
|
75
|
-
| `tests/helpers/mock-wx.ts` | 可注入的 wx 模拟器;`__setSize` 触发 resize,`__touch` 触发触摸 |
|
|
76
|
-
| `examples/wechat-minigame/` | 小游戏完整工程(vite + game.json + project.config.json + postbuild) |
|
|
77
|
-
| `examples/wechat-miniprogram/` | 小程序页面(WXML 事件转发) |
|
|
78
|
-
| `examples/h5/` | H5 双端 |
|
|
79
|
-
|
|
80
|
-
## 3.7 常见任务 → 文件清单(AI 速查)
|
|
81
|
-
|
|
82
|
-
| 需求 | 最小改动面 |
|
|
83
|
-
| --- | --- |
|
|
84
|
-
| three 报 `xxx is not defined` | `src/build/scope-rewrite.ts` 的 `DEFAULT_GLOBAL_NAMES` → `src/scope.ts` 的 `MiniThreeScope` → `src/core/runtime.ts` 组装 |
|
|
85
|
-
| 新 three 版本用了新的 DOM 属性 | `src/core/element.ts` `patchElement`(+ canvas 的 `extra`)→ 补 `tests/runtime.test.ts` |
|
|
86
|
-
| 触摸在小程序里不生效 | `src/core/pointer.ts`(`tap`/无 touches)→ `examples/wechat-miniprogram/pages/index/index.ts` 转发 |
|
|
87
|
-
| 新增一个平台(如抖音小游戏) | 新建 `src/platforms/xxx.ts` 实现 `PlatformBinding` → `src/index.ts` 导出 → `package.json` exports → `docs/08` |
|
|
88
|
-
| 新增 decoder 资源 | `src/build/assets.ts` 的 `DECODER_KEYWORDS` / `defaultRoots` → `examples/*/vite.config.ts` 的 `roots` |
|
|
89
|
-
| WebGPU 相关代码报错 | `src/build/plugin-core.ts` `webgpu` 策略 → `docs/06` |
|
|
90
|
-
| resize 后画面变形 | `src/core/window-info.ts`、`src/core/runtime.ts` 的 `resize()`、`docs/06` |
|
|
91
|
-
| 包体过大 | `docs/06`(分包 / Brotli / manualChunks)+ `src/build/assets.ts` |
|
|
92
|
-
| 发布新版本 | `docs/09-testing-and-release.md` + `CHANGELOG.md` + `package.json` |
|
|
93
|
-
|
|
94
|
-
## 3.8 修改后必做
|
|
95
|
-
|
|
96
|
-
1. `npm run check`(typecheck +
|
|
97
|
-
2. 更新本表(若职责变化)、`docs/04-api-reference.md`(若导出变化)、`CHANGELOG.md`。
|
|
98
|
-
3. 若触及架构不变量,新增或修订 `docs/adr/*.md`。
|
|
99
|
-
4. 若新增了平台能力,更新 `docs/11-compat-matrix.md`。
|
|
1
|
+
# 03 · 模块地图(AI 修改入口索引)
|
|
2
|
+
|
|
3
|
+
> **给 AI 用**:动手前先在这张表里定位目标文件;「改这里」列给出常见需求的最小改动面,「会影响」列给出必须同步检查的下游。
|
|
4
|
+
> 依赖层级:`types → scope / polyfills → core → platforms`;`build` 是独立分支。
|
|
5
|
+
|
|
6
|
+
## 3.1 根与协议层
|
|
7
|
+
|
|
8
|
+
| 文件 | 职责 | 关键导出 | 改这里 | 会影响 |
|
|
9
|
+
| --- | --- | --- | --- | --- |
|
|
10
|
+
| `src/types.ts` | 全部公开类型,纯 type-only | `Rect`、`WindowInfo`、`Capabilities`、`PatchedCanvas`、`TouchLikeEvent`、`FrameScheduler`、`RuntimeEvents` 等 | 新增平台能力字段、事件名称 | `core/*`、`platforms/*`、`dist/*.d.ts`、`docs/04` |
|
|
11
|
+
| `src/scope.ts` | 作用域协议:`MiniThreeScope`、活动作用域单例、显式全局注入、未初始化占位对象 | `createScope`、`getActiveScope`、`setActiveScope`、`hasActiveScope`、`installGlobals`、`getEarlyScopeReads`、`clearEarlyScopeReads` | 新增三方代码可能访问的浏览器全局;`UNDEFINED_BEFORE_RUNTIME` 里「探测型全局」的取舍 | **构建插件注入的 import**、[ADR-0001](./adr/0001-scoped-globals.md)、`docs/04`、`tests/scope.test.ts` |
|
|
12
|
+
| `src/index.ts` | 汇总导出 | 全部公开 API | 新增公共入口 | `package.json` `exports`、`docs/04` |
|
|
13
|
+
| `src/core/index.ts` | core 子路径导出 | core API | 同上 | `docs/04` |
|
|
14
|
+
| `src/polyfills/index.ts` | polyfills 子路径导出 | polyfill API | 同上 | `docs/04` |
|
|
15
|
+
|
|
16
|
+
## 3.2 polyfills(自包含,无平台知识)
|
|
17
|
+
|
|
18
|
+
| 文件 | 职责 | 关键导出 | 改这里 | 会影响 / 测试 |
|
|
19
|
+
| --- | --- | --- | --- | --- |
|
|
20
|
+
| `src/polyfills/event.ts` | W3C 事件系统,`patchEventTarget` 把方法绑到内部载体但把 `this` / `event.target` / `currentTarget` 转发给宿主元素 | `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 相对解析 | `MiniBlob`、`MiniURL`、`bytesToBase64`、`resolveUrl` | `createObjectURL` 的目标格式、URL 解析边界 | `image.ts` 的 `src` 解析;`tests/polyfills.test.ts` |
|
|
22
|
+
| `src/polyfills/text-encoding.ts` | `atob`/`btoa`/`TextEncoder`/`TextDecoder` | 同名 | 编码边界、BOM、utf-16 | `network.ts`、`blob-url.ts`;`tests/polyfills.test.ts` |
|
|
23
|
+
| `src/polyfills/network.ts` | `fetch`、`XMLHttpRequest`、`AbortController` | `createFetch`、`createXMLHttpRequestFactory`、`MiniAbortController` | `wx.request` 返回结构差异、进度事件 | `runtime.ts` 的 scope 组装;`tests/polyfills.test.ts` |
|
|
24
|
+
|
|
25
|
+
> 约束:polyfills 不得 import `core/*`,不得读取 `globalThis.wx`。
|
|
26
|
+
|
|
27
|
+
## 3.3 core(平台无关运行时)
|
|
28
|
+
|
|
29
|
+
| 文件 | 职责 | 关键导出 | 改这里 | 会影响 / 测试 |
|
|
30
|
+
| --- | --- | --- | --- | --- |
|
|
31
|
+
| `src/core/platform.ts` | **平台契约**(结构化接口,替代抽象基类) | `PlatformBinding`、`PlatformFactory` | 平台要新增能力时**先改这里** | 所有 `platforms/*`、`runtime.ts` |
|
|
32
|
+
| `src/core/runtime.ts` | **总装配**:画布补丁、scope 组装、订阅、生命周期 | `createRuntime`、`MiniThreeRuntime`、`RuntimeOptions`、`RendererHints` | 新增 runtime API、新增/移除全局项、调整启动顺序 | 几乎所有模块;`tests/runtime.test.ts` |
|
|
33
|
+
| `src/core/element.ts` | 就地 DOM 属性补丁 + `Symbol.hasInstance` 注册表 | `patchElement`、`createMockClass`、`*Shim`、`normalizeRect` | three 报「DOM 属性缺失」、`instanceof` 失败 | `canvas.ts`、`image.ts`、`dom.ts` |
|
|
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 工厂,blob URL → data URL,**原生 `onload`/`onerror` → 合成事件桥接** | `createImageFactory`、`ShimImageData` | 图片加载、crossOrigin、decode、事件不触发 | `platforms/*`、`dom.ts`;`tests/image-events.test.ts` |
|
|
36
|
+
| `src/core/dom.ts` | `document` / `body` / `screen` / `DOMRect` / `OffscreenCanvas` 构造器 | `createDocument`、`createScreen`、`ShimDOMRect`、`createOffscreenCanvasCtor` | `document.createElement` 新标签、`visibilityState` | `runtime.ts` |
|
|
37
|
+
| `src/core/pointer.ts` | **touch → pointer/mouse 状态机** | `PointerBridge` | 多指、capture、`tap` 无 touches、坐标换算 | `runtime.ts`、`examples/*`;`tests/runtime.test.ts` |
|
|
38
|
+
| `src/core/frames.ts` | rAF 包装、delta、fpsCap、FPS 测量 | `createFrameScheduler` | 帧率限制、慢帧告警 | `runtime.ts` |
|
|
39
|
+
| `src/core/window-info.ts` | 窗口信息 + DPR 封顶 + resize 广播 | `createWindowInfoStore`、`readWindowInfo` | 新 API 替代 `getWindowInfo`、安全区 | `runtime.ts`;`tests/runtime.test.ts` |
|
|
40
|
+
| `src/core/capabilities.ts` | 能力探测(离屏优先,主画布回退;**不消费上屏画布**) | `detectCapabilities`、`versionAtLeast`、`webgl2Source` | 新增探测项、「探测不到」的语义 | 所有 `platforms/*`、`runtime.report()`;`tests/capabilities.test.ts` |
|
|
41
|
+
| `src/core/diagnostics.ts` | 分级日志、`warnOnce`、能力报告 | `createDiagnostics`、`capabilityReport` | 日志格式、报告字段 | 全局;`tests/runtime.test.ts` |
|
|
42
|
+
|
|
43
|
+
> 约束:`core/*` 不得 import `platforms/*`,不得 import `three`,不得直接写 `globalThis`。
|
|
44
|
+
|
|
45
|
+
## 3.4 platforms(平台差异收敛点)
|
|
46
|
+
|
|
47
|
+
| 文件 | 职责 | 关键导出 | 改这里 | 会影响 |
|
|
48
|
+
| --- | --- | --- | --- | --- |
|
|
49
|
+
| `src/platforms/wx-types.ts` | 手写最小 `wx` 结构化类型(不依赖官方 typings) | `WxLike`、`WxCanvas`、`WxTouchEvent`、`resolveWx` | 用到新的 `wx.*` API 时补类型 | 所有平台;`docs/04` |
|
|
50
|
+
| `src/platforms/wechat-common.ts` | rAF / now / touch / visibility / 离屏画布 / 能力探测共用实现 | `watchWxTouch`、`createRafPair`、`probeContext`(返回 `boolean \| undefined`;无 `createOffscreenCanvas` 时不兜底,兜底时按 `reservedCanvases` 身份拒绝探测任何候选上屏画布)等 | 微信 API 变更、探测回退策略(ADR-0007、ADR-0008) | `wechat-game.ts`、`wechat-miniprogram.ts` |
|
|
51
|
+
| `src/platforms/wechat-game.ts` | 小游戏绑定 + 入口 | `createWeChatGameRuntime`、`createWeChatGameBinding`、`getScreenCanvas` | **上屏画布获取顺序**、锁帧 | `examples/wechat-minigame` |
|
|
52
|
+
| `src/platforms/wechat-miniprogram.ts` | 小程序绑定(`createSelectorQuery`) | `createWeChatMiniProgramRuntime` | 选择器查询、组件作用域 `selectorCtx` | `examples/wechat-miniprogram` |
|
|
53
|
+
| `src/platforms/browser.ts` | 浏览器 / Node 测试平台 | `createBrowserRuntime`、`createBrowserBinding` | H5 双端能力 | `examples/h5` |
|
|
54
|
+
|
|
55
|
+
## 3.5 build(Node 侧,不进小游戏 bundle)
|
|
56
|
+
|
|
57
|
+
| 文件 | 职责 | 关键导出 | 改这里 | 会影响 / 测试 |
|
|
58
|
+
| --- | --- | --- | --- | --- |
|
|
59
|
+
| `src/build/scope-rewrite.ts` | **AST 全局重写**,`@babel/parser` + `path.scope.hasBinding` | `rewriteGlobals`、`DEFAULT_GLOBAL_NAMES`、`DEFAULT_FORCE_UNDEF` | 需要改写的全局清单、访问器名、注入的 import | 所有三方模块;`tests/scope-rewrite.test.ts`、[ADR-0003](./adr/0003-ast-rewrite.md) |
|
|
60
|
+
| `src/build/assets.ts` | worker/wasm 引用扫描、解析、拷贝、manifest | `collectAssetReferences`、`collectAssets`、`copyAssets`、`AssetManifest` | 新 decoder 类型、输出目录、`game.json` 建议 | `plugin-core.ts`;`tests/plugin.test.ts` |
|
|
61
|
+
| `src/build/plugin-core.ts` | Rollup/Vite 兼容插件核心 | `miniThreePlugin`、`BuildReport` | include 规则、WebGPU 策略、构建报告 | `vite.ts`、`rollup.ts`;`tests/plugin.test.ts` |
|
|
62
|
+
| `src/build/vite.ts` | Vite 入口 + `optimizeDeps.exclude` 配置 | `miniThree`(default) | Vite 版本兼容 | `examples/*/vite.config.ts` |
|
|
63
|
+
| `src/build/rollup.ts` | Rollup 入口 + 高级 API 再导出 | `miniThree`、`rewriteGlobals` 等 | Rollup 集成 | `docs/05` |
|
|
64
|
+
|
|
65
|
+
> 约束:`build/*` 不得 import `core/*` / `platforms/*`;`node:fs` 只允许出现在这里。
|
|
66
|
+
|
|
67
|
+
## 3.6 配置与示例
|
|
68
|
+
|
|
69
|
+
| 文件 | 作用 |
|
|
70
|
+
| --- | --- |
|
|
71
|
+
| `package.json` | `exports` 子路径、`sideEffects`、peer(`three`/`vite`/`rollup` 均 optional) |
|
|
72
|
+
| `tsconfig.json` | strict + `noUncheckedIndexedAccess` + `verbatimModuleSyntax`;`include` 覆盖 `src/tests/config` |
|
|
73
|
+
| `tsup.config.ts` | 两套构建:runtime(es2019 / neutral / dts / splitting)与 build tooling(node18 / 无 splitting) |
|
|
74
|
+
| `vitest.config.ts` | 单 fork 执行(规避 Windows 临时目录权限),`cache: false` |
|
|
75
|
+
| `tests/helpers/mock-wx.ts` | 可注入的 wx 模拟器;`__setSize` 触发 resize,`__touch` 触发触摸 |
|
|
76
|
+
| `examples/wechat-minigame/` | 小游戏完整工程(vite + game.json + project.config.json + postbuild) |
|
|
77
|
+
| `examples/wechat-miniprogram/` | 小程序页面(WXML 事件转发) |
|
|
78
|
+
| `examples/h5/` | H5 双端 |
|
|
79
|
+
|
|
80
|
+
## 3.7 常见任务 → 文件清单(AI 速查)
|
|
81
|
+
|
|
82
|
+
| 需求 | 最小改动面 |
|
|
83
|
+
| --- | --- |
|
|
84
|
+
| three 报 `xxx is not defined` | `src/build/scope-rewrite.ts` 的 `DEFAULT_GLOBAL_NAMES` → `src/scope.ts` 的 `MiniThreeScope` → `src/core/runtime.ts` 组装 |
|
|
85
|
+
| 新 three 版本用了新的 DOM 属性 | `src/core/element.ts` `patchElement`(+ canvas 的 `extra`)→ 补 `tests/runtime.test.ts` |
|
|
86
|
+
| 触摸在小程序里不生效 | `src/core/pointer.ts`(`tap`/无 touches)→ `examples/wechat-miniprogram/pages/index/index.ts` 转发 |
|
|
87
|
+
| 新增一个平台(如抖音小游戏) | 新建 `src/platforms/xxx.ts` 实现 `PlatformBinding` → `src/index.ts` 导出 → `package.json` exports → `docs/08` |
|
|
88
|
+
| 新增 decoder 资源 | `src/build/assets.ts` 的 `DECODER_KEYWORDS` / `defaultRoots` → `examples/*/vite.config.ts` 的 `roots` |
|
|
89
|
+
| WebGPU 相关代码报错 | `src/build/plugin-core.ts` `webgpu` 策略 → `docs/06` |
|
|
90
|
+
| resize 后画面变形 | `src/core/window-info.ts`、`src/core/runtime.ts` 的 `resize()`、`docs/06` |
|
|
91
|
+
| 包体过大 | `docs/06`(分包 / Brotli / manualChunks)+ `src/build/assets.ts` |
|
|
92
|
+
| 发布新版本 | `docs/09-testing-and-release.md` + `CHANGELOG.md` + `package.json` |
|
|
93
|
+
|
|
94
|
+
## 3.8 修改后必做
|
|
95
|
+
|
|
96
|
+
1. `npm run check`(typecheck + 71 例单测 + tsup 构建)。
|
|
97
|
+
2. 更新本表(若职责变化)、`docs/04-api-reference.md`(若导出变化)、`CHANGELOG.md`。
|
|
98
|
+
3. 若触及架构不变量,新增或修订 `docs/adr/*.md`。
|
|
99
|
+
4. 若新增了平台能力,更新 `docs/11-compat-matrix.md`。
|