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.
- package/AGENTS.md +85 -85
- package/LICENSE +21 -21
- package/README.md +159 -159
- package/dist/build/rollup.d.ts +2 -2
- package/dist/build/rollup.js.map +1 -1
- package/dist/build/vite.d.ts +2 -2
- package/dist/build/vite.js.map +1 -1
- package/dist/{chunk-MSP7V7KM.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-LCJNTN6F.js → chunk-LAVHSWBU.js} +8 -5
- package/dist/chunk-LAVHSWBU.js.map +1 -0
- package/dist/{chunk-WYUHMKUM.js → chunk-RYWYBOYO.js} +43 -4
- package/dist/chunk-RYWYBOYO.js.map +1 -0
- package/dist/{chunk-6Y4MKIJL.js → chunk-SXQUZI22.js} +4 -4
- package/dist/chunk-SXQUZI22.js.map +1 -0
- package/dist/{chunk-TDVL2OAV.js → chunk-TPMMZFHW.js} +123 -58
- package/dist/chunk-TPMMZFHW.js.map +1 -0
- package/dist/{chunk-L4QZ5SP6.js → chunk-YPG3QUYK.js} +4 -4
- package/dist/chunk-YPG3QUYK.js.map +1 -0
- package/dist/core/index.d.ts +9 -3
- package/dist/core/index.js +3 -3
- package/dist/index.d.ts +2 -2
- package/dist/index.js +7 -7
- package/dist/platforms/browser.d.ts +2 -2
- package/dist/platforms/browser.js +4 -4
- package/dist/platforms/wechat-game.d.ts +2 -2
- package/dist/platforms/wechat-game.js +5 -5
- package/dist/platforms/wechat-miniprogram.d.ts +2 -2
- package/dist/platforms/wechat-miniprogram.js +5 -5
- package/dist/{plugin-core-BuqW9C-L.d.ts → plugin-core-CBOr1cyv.d.ts} +15 -4
- package/dist/polyfills/index.d.ts +1 -1
- package/dist/polyfills/index.js +1 -1
- package/dist/{runtime-BrHExTjl.d.ts → runtime-C8_xIlDM.d.ts} +29 -1
- package/dist/scope.d.ts +1 -1
- package/dist/scope.js +1 -1
- package/dist/{types-X_5SJh4y.d.ts → types-DOoJ7noL.d.ts} +13 -1
- package/docs/01-design-principles.md +105 -105
- package/docs/03-module-map.md +99 -99
- package/docs/04-api-reference.md +310 -304
- package/docs/05-build-plugin.md +176 -176
- package/docs/06-platform-notes.md +8 -4
- package/docs/07-integration-guide.md +226 -225
- package/docs/08-extension-guide.md +101 -101
- package/docs/09-testing-and-release.md +212 -211
- 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 -0
- package/docs/adr/0011-host-callback-slot-bridging.md +45 -0
- package/docs/adr/README.md +33 -31
- package/package.json +126 -125
- package/dist/chunk-35XVAVDB.js.map +0 -1
- package/dist/chunk-6Y4MKIJL.js.map +0 -1
- package/dist/chunk-L4QZ5SP6.js.map +0 -1
- package/dist/chunk-LCJNTN6F.js.map +0 -1
- package/dist/chunk-MSP7V7KM.js.map +0 -1
- package/dist/chunk-TDVL2OAV.js.map +0 -1
- package/dist/chunk-WYUHMKUM.js.map +0 -1
|
@@ -1,101 +1,101 @@
|
|
|
1
|
-
# 08 · 扩展指南
|
|
2
|
-
|
|
3
|
-
> 面向人和 AI:三种最常见的扩展(新平台 / 新 polyfill / 新资源规则)各自的最小改动集与验收标准。
|
|
4
|
-
|
|
5
|
-
## 8.1 新增一个平台
|
|
6
|
-
|
|
7
|
-
**原则**:平台差异只允许出现在 `src/platforms/`。`core/` 不认识任何平台。
|
|
8
|
-
|
|
9
|
-
1. 在 `src/platforms/<name>.ts` 实现 `PlatformBinding`(`src/core/platform.ts`)。
|
|
10
|
-
2. 复用 `wechat-common.ts` 里能复用的部分;若新平台 API 差异大,就在 `wx-types.ts` 里补结构化类型或新建 `<name>-types.ts`。
|
|
11
|
-
3. 导出 `create<Name>Binding()` 与 `create<Name>Runtime()`(后者调用 `createRuntime(() => binding, options)`)。
|
|
12
|
-
4. 在 `src/index.ts` 导出;在 `package.json` 的 `exports` 加子路径。
|
|
13
|
-
5. 在 `Capabilities['platform']`(`src/types.ts`)加字面量;在 `docs/11-compat-matrix.md` 登记。
|
|
14
|
-
6. 补 `tests/<name>.test.ts`,用 mock 宿主验证:画布补丁、scope、触摸、resize、dispose。
|
|
15
|
-
7. 加 `examples/<name>/` 最小可运行示例。
|
|
16
|
-
|
|
17
|
-
模板:
|
|
18
|
-
|
|
19
|
-
```ts
|
|
20
|
-
import type { PlatformBinding } from '../core/platform';
|
|
21
|
-
import { createRuntime, type MiniThreeRuntime, type RuntimeOptions } from '../core/runtime';
|
|
22
|
-
import { detectCapabilities } from '../core/capabilities';
|
|
23
|
-
|
|
24
|
-
export function createFooBinding(options: FooOptions): PlatformBinding {
|
|
25
|
-
const host = resolveFoo(options.host);
|
|
26
|
-
return {
|
|
27
|
-
kind: 'browser', // 或扩展 Capabilities['platform'] 字面量
|
|
28
|
-
wx: undefined,
|
|
29
|
-
rawCanvas: host.canvas,
|
|
30
|
-
capabilities: detectCapabilities(host.wxLike, 'browser'),
|
|
31
|
-
imageFactory: createImageFactory(host.wxLike),
|
|
32
|
-
getCanvasRect: () => host.rect(),
|
|
33
|
-
createOffscreenCanvas: (w, h, type) => host.offscreen(w, h, type),
|
|
34
|
-
watchTouch: (handler) => host.onTouch(handler),
|
|
35
|
-
watchVisibility: (handler) => host.onVisibility(handler),
|
|
36
|
-
requestAnimationFrame: (cb) => host.raf(cb),
|
|
37
|
-
cancelAnimationFrame: (id) => host.caf(id),
|
|
38
|
-
now: () => host.now(),
|
|
39
|
-
dispose: () => host.close(),
|
|
40
|
-
};
|
|
41
|
-
}
|
|
42
|
-
|
|
43
|
-
export function createFooRuntime(options: FooOptions & RuntimeOptions = {}): Promise<MiniThreeRuntime> {
|
|
44
|
-
return createRuntime(() => createFooBinding(options), options);
|
|
45
|
-
}
|
|
46
|
-
```
|
|
47
|
-
|
|
48
|
-
**验收**:`npm run check` 通过;`dispose()` 后所有监听被移除;`getCanvasRect()` 在尺寸变化后能通过 `runtime.resize()` 生效;不得调用 `wx.createCanvas()` 超过一次。
|
|
49
|
-
|
|
50
|
-
## 8.2 新增一个 polyfill / 全局 shim
|
|
51
|
-
|
|
52
|
-
three 报 `X is not defined` 或 `X is not a constructor` 时,按以下顺序改:
|
|
53
|
-
|
|
54
|
-
1. `src/polyfills/` 新建实现文件(自包含,不 import `core/*`)。
|
|
55
|
-
2. 在 `src/polyfills/index.ts` 导出。
|
|
56
|
-
3. 在 `src/scope.ts` 的 `MiniThreeScope` 接口里加字段,并加入 `GLOBAL_KEYS`(这样 `installGlobals()` 也会带上它)。
|
|
57
|
-
4. 在 `src/core/runtime.ts` 的 scope 组装区赋值(或按平台条件赋值)。
|
|
58
|
-
5. 在 `src/build/scope-rewrite.ts` 的 `DEFAULT_GLOBAL_NAMES` 加入标识符。
|
|
59
|
-
6. 补测试:`tests/polyfills.test.ts`(实现)+ `tests/scope-rewrite.test.ts`(改写)+ `tests/runtime.test.ts`(scope 中存在)。
|
|
60
|
-
7. 更新 `docs/04-api-reference.md` 与 `docs/03-module-map.md`。
|
|
61
|
-
|
|
62
|
-
> 若某个 API 在小程序里**不可用且必须让 three 走降级分支**,把值设为 `undefined` 并加入 `DEFAULT_FORCE_UNDEF`,不要伪造一个半实现(参考 `createImageBitmap`)。
|
|
63
|
-
|
|
64
|
-
## 8.3 新增 DOM 属性 / `instanceof` 支持
|
|
65
|
-
|
|
66
|
-
1. `src/core/element.ts` 的 `patchElement()`:加 `define(instance, key, descriptor)`。若需要响应式(随 rect 变化),用闭包 `rect` 的 getter。
|
|
67
|
-
2. canvas 专属属性放到 `src/core/canvas.ts` 的 `extra` 描述符里。
|
|
68
|
-
3. 若 three 用 `x instanceof SomeCtor` 判断,复用已有 `*Shim`,或 `createMockClass()` 新建一个并在补丁时加入 `instanceOf` 列表。
|
|
69
|
-
4. 若 three 用 `new SomeCtor()`,提供一个真正返回平台对象的构造器(参考 `createOffscreenCanvasCtor`)。
|
|
70
|
-
5. 补 `tests/runtime.test.ts` 断言。
|
|
71
|
-
|
|
72
|
-
**禁止**:`Object.setPrototypeOf`、Proxy 包装、返回克隆对象(会破坏微信内部 WeakMap 校验,见 ADR-0004)。
|
|
73
|
-
|
|
74
|
-
## 8.4 新增资源类型 / override 规则
|
|
75
|
-
|
|
76
|
-
1. `src/build/assets.ts`:
|
|
77
|
-
- `ASSET_PATTERN` 加入新扩展名;
|
|
78
|
-
- `DECODER_KEYWORDS` 加入新关键字;
|
|
79
|
-
- `defaultRoots()` 加入该库的资源目录;
|
|
80
|
-
- `classify()` 加入新 kind;
|
|
81
|
-
- `decoderPaths` 生成逻辑加入新 key。
|
|
82
|
-
2. 若某个 addon 需要替换 import 路径,在 `src/build/plugin-core.ts` 的 `transform` 里加一条**显式、可配置、可关闭**的映射规则,并写进 `docs/05`。不要做成隐式全局替换。
|
|
83
|
-
3. 在 `tests/plugin.test.ts` 加资产扫描用例。
|
|
84
|
-
4. 更新 `examples/*/vite.config.ts` 的 `roots` 示例与 `docs/05`。
|
|
85
|
-
|
|
86
|
-
## 8.5 新增构建期能力
|
|
87
|
-
|
|
88
|
-
- 新 hook 放在 `src/build/plugin-core.ts`;保持 Rollup/Vite 双兼容(只用 `transform` / `resolveId` / `generateBundle` / `config`)。
|
|
89
|
-
- 所有新行为都要有对应**开关**与默认值,且默认不得改变已有产物语义。
|
|
90
|
-
- 统计信息加入 `BuildReport`,方便 CI 与 AI 读取。
|
|
91
|
-
- 参考 ADR 流程:若改变架构不变量,先写 `docs/adr/NNNN-*.md`。
|
|
92
|
-
|
|
93
|
-
## 8.6 扩展的评审清单
|
|
94
|
-
|
|
95
|
-
- [ ] 是否违反 [架构不变量](./02-architecture.md#25-架构不变量ai-必读不得破坏)?
|
|
96
|
-
- [ ] `src/` 是否引入了 `three` 的运行时 import?
|
|
97
|
-
- [ ] 新订阅 / 定时器 / 全局写入是否都登记到 `disposers`?
|
|
98
|
-
- [ ] 是否新增了同步 `wx.createCanvas()` 调用?
|
|
99
|
-
- [ ] 类型是否 strict 通过(`noUncheckedIndexedAccess`)?
|
|
100
|
-
- [ ] 行为是否可被测试(能注入 mock 宿主)?
|
|
101
|
-
- [ ] `docs/03`、`docs/04`、`CHANGELOG.md` 是否同步?
|
|
1
|
+
# 08 · 扩展指南
|
|
2
|
+
|
|
3
|
+
> 面向人和 AI:三种最常见的扩展(新平台 / 新 polyfill / 新资源规则)各自的最小改动集与验收标准。
|
|
4
|
+
|
|
5
|
+
## 8.1 新增一个平台
|
|
6
|
+
|
|
7
|
+
**原则**:平台差异只允许出现在 `src/platforms/`。`core/` 不认识任何平台。
|
|
8
|
+
|
|
9
|
+
1. 在 `src/platforms/<name>.ts` 实现 `PlatformBinding`(`src/core/platform.ts`)。
|
|
10
|
+
2. 复用 `wechat-common.ts` 里能复用的部分;若新平台 API 差异大,就在 `wx-types.ts` 里补结构化类型或新建 `<name>-types.ts`。
|
|
11
|
+
3. 导出 `create<Name>Binding()` 与 `create<Name>Runtime()`(后者调用 `createRuntime(() => binding, options)`)。
|
|
12
|
+
4. 在 `src/index.ts` 导出;在 `package.json` 的 `exports` 加子路径。
|
|
13
|
+
5. 在 `Capabilities['platform']`(`src/types.ts`)加字面量;在 `docs/11-compat-matrix.md` 登记。
|
|
14
|
+
6. 补 `tests/<name>.test.ts`,用 mock 宿主验证:画布补丁、scope、触摸、resize、dispose。
|
|
15
|
+
7. 加 `examples/<name>/` 最小可运行示例。
|
|
16
|
+
|
|
17
|
+
模板:
|
|
18
|
+
|
|
19
|
+
```ts
|
|
20
|
+
import type { PlatformBinding } from '../core/platform';
|
|
21
|
+
import { createRuntime, type MiniThreeRuntime, type RuntimeOptions } from '../core/runtime';
|
|
22
|
+
import { detectCapabilities } from '../core/capabilities';
|
|
23
|
+
|
|
24
|
+
export function createFooBinding(options: FooOptions): PlatformBinding {
|
|
25
|
+
const host = resolveFoo(options.host);
|
|
26
|
+
return {
|
|
27
|
+
kind: 'browser', // 或扩展 Capabilities['platform'] 字面量
|
|
28
|
+
wx: undefined,
|
|
29
|
+
rawCanvas: host.canvas,
|
|
30
|
+
capabilities: detectCapabilities(host.wxLike, 'browser'),
|
|
31
|
+
imageFactory: createImageFactory(host.wxLike),
|
|
32
|
+
getCanvasRect: () => host.rect(),
|
|
33
|
+
createOffscreenCanvas: (w, h, type) => host.offscreen(w, h, type),
|
|
34
|
+
watchTouch: (handler) => host.onTouch(handler),
|
|
35
|
+
watchVisibility: (handler) => host.onVisibility(handler),
|
|
36
|
+
requestAnimationFrame: (cb) => host.raf(cb),
|
|
37
|
+
cancelAnimationFrame: (id) => host.caf(id),
|
|
38
|
+
now: () => host.now(),
|
|
39
|
+
dispose: () => host.close(),
|
|
40
|
+
};
|
|
41
|
+
}
|
|
42
|
+
|
|
43
|
+
export function createFooRuntime(options: FooOptions & RuntimeOptions = {}): Promise<MiniThreeRuntime> {
|
|
44
|
+
return createRuntime(() => createFooBinding(options), options);
|
|
45
|
+
}
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
**验收**:`npm run check` 通过;`dispose()` 后所有监听被移除;`getCanvasRect()` 在尺寸变化后能通过 `runtime.resize()` 生效;不得调用 `wx.createCanvas()` 超过一次。
|
|
49
|
+
|
|
50
|
+
## 8.2 新增一个 polyfill / 全局 shim
|
|
51
|
+
|
|
52
|
+
three 报 `X is not defined` 或 `X is not a constructor` 时,按以下顺序改:
|
|
53
|
+
|
|
54
|
+
1. `src/polyfills/` 新建实现文件(自包含,不 import `core/*`)。
|
|
55
|
+
2. 在 `src/polyfills/index.ts` 导出。
|
|
56
|
+
3. 在 `src/scope.ts` 的 `MiniThreeScope` 接口里加字段,并加入 `GLOBAL_KEYS`(这样 `installGlobals()` 也会带上它)。
|
|
57
|
+
4. 在 `src/core/runtime.ts` 的 scope 组装区赋值(或按平台条件赋值)。
|
|
58
|
+
5. 在 `src/build/scope-rewrite.ts` 的 `DEFAULT_GLOBAL_NAMES` 加入标识符。
|
|
59
|
+
6. 补测试:`tests/polyfills.test.ts`(实现)+ `tests/scope-rewrite.test.ts`(改写)+ `tests/runtime.test.ts`(scope 中存在)。
|
|
60
|
+
7. 更新 `docs/04-api-reference.md` 与 `docs/03-module-map.md`。
|
|
61
|
+
|
|
62
|
+
> 若某个 API 在小程序里**不可用且必须让 three 走降级分支**,把值设为 `undefined` 并加入 `DEFAULT_FORCE_UNDEF`,不要伪造一个半实现(参考 `createImageBitmap`)。
|
|
63
|
+
|
|
64
|
+
## 8.3 新增 DOM 属性 / `instanceof` 支持
|
|
65
|
+
|
|
66
|
+
1. `src/core/element.ts` 的 `patchElement()`:加 `define(instance, key, descriptor)`。若需要响应式(随 rect 变化),用闭包 `rect` 的 getter。
|
|
67
|
+
2. canvas 专属属性放到 `src/core/canvas.ts` 的 `extra` 描述符里。
|
|
68
|
+
3. 若 three 用 `x instanceof SomeCtor` 判断,复用已有 `*Shim`,或 `createMockClass()` 新建一个并在补丁时加入 `instanceOf` 列表。
|
|
69
|
+
4. 若 three 用 `new SomeCtor()`,提供一个真正返回平台对象的构造器(参考 `createOffscreenCanvasCtor`)。
|
|
70
|
+
5. 补 `tests/runtime.test.ts` 断言。
|
|
71
|
+
|
|
72
|
+
**禁止**:`Object.setPrototypeOf`、Proxy 包装、返回克隆对象(会破坏微信内部 WeakMap 校验,见 ADR-0004)。
|
|
73
|
+
|
|
74
|
+
## 8.4 新增资源类型 / override 规则
|
|
75
|
+
|
|
76
|
+
1. `src/build/assets.ts`:
|
|
77
|
+
- `ASSET_PATTERN` 加入新扩展名;
|
|
78
|
+
- `DECODER_KEYWORDS` 加入新关键字;
|
|
79
|
+
- `defaultRoots()` 加入该库的资源目录;
|
|
80
|
+
- `classify()` 加入新 kind;
|
|
81
|
+
- `decoderPaths` 生成逻辑加入新 key。
|
|
82
|
+
2. 若某个 addon 需要替换 import 路径,在 `src/build/plugin-core.ts` 的 `transform` 里加一条**显式、可配置、可关闭**的映射规则,并写进 `docs/05`。不要做成隐式全局替换。
|
|
83
|
+
3. 在 `tests/plugin.test.ts` 加资产扫描用例。
|
|
84
|
+
4. 更新 `examples/*/vite.config.ts` 的 `roots` 示例与 `docs/05`。
|
|
85
|
+
|
|
86
|
+
## 8.5 新增构建期能力
|
|
87
|
+
|
|
88
|
+
- 新 hook 放在 `src/build/plugin-core.ts`;保持 Rollup/Vite 双兼容(只用 `transform` / `resolveId` / `generateBundle` / `config`)。
|
|
89
|
+
- 所有新行为都要有对应**开关**与默认值,且默认不得改变已有产物语义。
|
|
90
|
+
- 统计信息加入 `BuildReport`,方便 CI 与 AI 读取。
|
|
91
|
+
- 参考 ADR 流程:若改变架构不变量,先写 `docs/adr/NNNN-*.md`。
|
|
92
|
+
|
|
93
|
+
## 8.6 扩展的评审清单
|
|
94
|
+
|
|
95
|
+
- [ ] 是否违反 [架构不变量](./02-architecture.md#25-架构不变量ai-必读不得破坏)?
|
|
96
|
+
- [ ] `src/` 是否引入了 `three` 的运行时 import?
|
|
97
|
+
- [ ] 新订阅 / 定时器 / 全局写入是否都登记到 `disposers`?
|
|
98
|
+
- [ ] 是否新增了同步 `wx.createCanvas()` 调用?
|
|
99
|
+
- [ ] 类型是否 strict 通过(`noUncheckedIndexedAccess`)?
|
|
100
|
+
- [ ] 行为是否可被测试(能注入 mock 宿主)?
|
|
101
|
+
- [ ] `docs/03`、`docs/04`、`CHANGELOG.md` 是否同步?
|