mini-three-adapter 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (73) hide show
  1. package/AGENTS.md +85 -0
  2. package/LICENSE +21 -0
  3. package/README.md +158 -2
  4. package/dist/build/rollup.d.ts +8 -0
  5. package/dist/build/rollup.js +393 -0
  6. package/dist/build/rollup.js.map +1 -0
  7. package/dist/build/vite.d.ts +15 -0
  8. package/dist/build/vite.js +395 -0
  9. package/dist/build/vite.js.map +1 -0
  10. package/dist/chunk-34RWHAW4.js +128 -0
  11. package/dist/chunk-34RWHAW4.js.map +1 -0
  12. package/dist/chunk-3UGQWFH3.js +1246 -0
  13. package/dist/chunk-3UGQWFH3.js.map +1 -0
  14. package/dist/chunk-4UEBRAK6.js +711 -0
  15. package/dist/chunk-4UEBRAK6.js.map +1 -0
  16. package/dist/chunk-LB3WL24R.js +91 -0
  17. package/dist/chunk-LB3WL24R.js.map +1 -0
  18. package/dist/chunk-MTBMOFAL.js +132 -0
  19. package/dist/chunk-MTBMOFAL.js.map +1 -0
  20. package/dist/chunk-QYQQ5J6E.js +3 -0
  21. package/dist/chunk-QYQQ5J6E.js.map +1 -0
  22. package/dist/chunk-V6TY7KAL.js +7 -0
  23. package/dist/chunk-V6TY7KAL.js.map +1 -0
  24. package/dist/chunk-WLRQDTSZ.js +145 -0
  25. package/dist/chunk-WLRQDTSZ.js.map +1 -0
  26. package/dist/chunk-Z7AMDRN3.js +66 -0
  27. package/dist/chunk-Z7AMDRN3.js.map +1 -0
  28. package/dist/core/index.d.ts +101 -0
  29. package/dist/core/index.js +7 -0
  30. package/dist/core/index.js.map +1 -0
  31. package/dist/index.d.ts +8 -0
  32. package/dist/index.js +11 -0
  33. package/dist/index.js.map +1 -0
  34. package/dist/platforms/browser.d.ts +23 -0
  35. package/dist/platforms/browser.js +7 -0
  36. package/dist/platforms/browser.js.map +1 -0
  37. package/dist/platforms/wechat-game.d.ts +31 -0
  38. package/dist/platforms/wechat-game.js +8 -0
  39. package/dist/platforms/wechat-game.js.map +1 -0
  40. package/dist/platforms/wechat-miniprogram.d.ts +26 -0
  41. package/dist/platforms/wechat-miniprogram.js +8 -0
  42. package/dist/platforms/wechat-miniprogram.js.map +1 -0
  43. package/dist/plugin-core-BuqW9C-L.d.ts +127 -0
  44. package/dist/polyfills/index.d.ts +291 -0
  45. package/dist/polyfills/index.js +4 -0
  46. package/dist/polyfills/index.js.map +1 -0
  47. package/dist/runtime-7uUOoFhC.d.ts +263 -0
  48. package/dist/scope.d.ts +146 -0
  49. package/dist/scope.js +4 -0
  50. package/dist/scope.js.map +1 -0
  51. package/dist/types-BzK0LQMa.d.ts +153 -0
  52. package/dist/wx-types-NMNyrsWO.d.ts +150 -0
  53. package/docs/01-design-principles.md +105 -0
  54. package/docs/02-architecture.md +126 -0
  55. package/docs/03-module-map.md +99 -0
  56. package/docs/04-api-reference.md +291 -0
  57. package/docs/05-build-plugin.md +146 -0
  58. package/docs/06-platform-notes.md +108 -0
  59. package/docs/07-integration-guide.md +211 -0
  60. package/docs/08-extension-guide.md +101 -0
  61. package/docs/09-testing-and-release.md +206 -0
  62. package/docs/10-ai-playbook.md +140 -0
  63. package/docs/11-compat-matrix.md +94 -0
  64. package/docs/README.md +41 -0
  65. package/docs/adr/0001-scoped-globals.md +41 -0
  66. package/docs/adr/0002-unified-runtime-lifecycle.md +40 -0
  67. package/docs/adr/0003-ast-rewrite.md +51 -0
  68. package/docs/adr/0004-in-place-patching.md +42 -0
  69. package/docs/adr/0005-webgl2-only.md +44 -0
  70. package/docs/adr/0006-zero-three-dependency.md +43 -0
  71. package/docs/adr/README.md +28 -0
  72. package/llms.txt +65 -0
  73. package/package.json +117 -4
@@ -0,0 +1,146 @@
1
+ import { c as EventTargetLike, P as PatchedCanvas, C as CanvasStyleLike, R as Rect } from './types-BzK0LQMa.js';
2
+
3
+ /**
4
+ * Scoped globals: the central design decision of mini-three-adapter.
5
+ *
6
+ * The original adapter style (and WeChat's official `weapp-adapter`) writes
7
+ * `window`, `document`, `Image`, ... onto `globalThis`. That is convenient but
8
+ * irreversible: it breaks H5 dual-target builds, makes two three.js versions
9
+ * fight over the same canvas, and cannot be un-installed in tests.
10
+ *
11
+ * Here the shims live in one explicit `MiniThreeScope` object. Third-party
12
+ * modules (three, three/addons, three-stdlib, ...) are rewritten at build time
13
+ * by `mini-three-adapter/vite` so that their *free* references to browser
14
+ * globals resolve through `getActiveScope()`. Application code is untouched.
15
+ *
16
+ * `installGlobals()` remains available as an explicit, reversible escape hatch
17
+ * for libraries that cannot be transformed.
18
+ */
19
+
20
+ interface DocumentLike extends EventTargetLike {
21
+ createElement(tagName: string): PatchedCanvas | unknown;
22
+ createElementNS(namespaceURI: string | null, tagName: string): PatchedCanvas | unknown;
23
+ body: ElementLike;
24
+ documentElement: ElementLike;
25
+ defaultView: MiniThreeScope | null;
26
+ [key: string]: unknown;
27
+ }
28
+ interface ElementLike extends EventTargetLike {
29
+ style: CanvasStyleLike;
30
+ clientWidth: number;
31
+ clientHeight: number;
32
+ getBoundingClientRect(): Rect;
33
+ setAttribute(name: string, value: unknown): void;
34
+ removeAttribute(name: string): void;
35
+ [key: string]: unknown;
36
+ }
37
+ interface NavigatorLike {
38
+ userAgent: string;
39
+ platform: string;
40
+ hardwareConcurrency: number;
41
+ [key: string]: unknown;
42
+ }
43
+ /**
44
+ * The set of browser globals three.js (and its addons) may read. Members are
45
+ * typed where they matter and `unknown` in the index signature so the build
46
+ * plugin can add platform-specific extras without loosening the whole object.
47
+ */
48
+ interface MiniThreeScope extends EventTargetLike {
49
+ readonly window: MiniThreeScope;
50
+ readonly self: MiniThreeScope;
51
+ readonly globalThis: MiniThreeScope;
52
+ document: DocumentLike;
53
+ navigator: NavigatorLike;
54
+ screen: EventTargetLike & {
55
+ width: number;
56
+ height: number;
57
+ availWidth: number;
58
+ availHeight: number;
59
+ colorDepth: number;
60
+ pixelDepth: number;
61
+ };
62
+ innerWidth: number;
63
+ innerHeight: number;
64
+ outerWidth: number;
65
+ outerHeight: number;
66
+ devicePixelRatio: number;
67
+ pageXOffset: number;
68
+ pageYOffset: number;
69
+ performance: {
70
+ now(): number;
71
+ };
72
+ requestAnimationFrame(callback: (time: number) => void): number;
73
+ cancelAnimationFrame(id: number): void;
74
+ getComputedStyle(element: unknown): CanvasStyleLike;
75
+ matchMedia(query: string): {
76
+ matches: boolean;
77
+ media: string;
78
+ addListener(l: unknown): void;
79
+ removeListener(l: unknown): void;
80
+ };
81
+ atob(data: string): string;
82
+ btoa(data: string): string;
83
+ Event: unknown;
84
+ EventTarget: unknown;
85
+ CustomEvent: unknown;
86
+ PointerEvent: unknown;
87
+ MouseEvent: unknown;
88
+ TouchEvent: unknown;
89
+ MessageEvent: unknown;
90
+ ProgressEvent: unknown;
91
+ KeyboardEvent: unknown;
92
+ DOMException: unknown;
93
+ HTMLElement: unknown;
94
+ HTMLCanvasElement: unknown;
95
+ HTMLImageElement: unknown;
96
+ HTMLVideoElement: unknown;
97
+ OffscreenCanvas: unknown;
98
+ Image: unknown;
99
+ ImageData: unknown;
100
+ DOMRect: unknown;
101
+ WebGLRenderingContext: unknown;
102
+ WebGL2RenderingContext: unknown;
103
+ AudioContext: unknown;
104
+ Blob: unknown;
105
+ URL: unknown;
106
+ FileReader: unknown;
107
+ TextDecoder: unknown;
108
+ TextEncoder: unknown;
109
+ AbortController: unknown;
110
+ AbortSignal: unknown;
111
+ fetch: unknown;
112
+ XMLHttpRequest: unknown;
113
+ WebSocket: unknown;
114
+ createImageBitmap: unknown;
115
+ Worker: unknown;
116
+ WebAssembly: unknown;
117
+ ResizeObserver: unknown;
118
+ [key: string]: unknown;
119
+ }
120
+ /** Returns the currently installed scope (or the throwing placeholder). */
121
+ declare function getActiveScope(): MiniThreeScope;
122
+ /** Install / replace the active scope. Returns a disposer. */
123
+ declare function setActiveScope(scope: MiniThreeScope | null): () => void;
124
+ declare function hasActiveScope(): boolean;
125
+ /**
126
+ * Build a scope with a set of overrides. `window`, `self` and `globalThis`
127
+ * are wired to the scope itself so that `window.window === window`.
128
+ */
129
+ declare function createScope(overrides?: Partial<MiniThreeScope>): MiniThreeScope;
130
+ interface InstallGlobalsOptions {
131
+ /** Defaults to `globalThis`. */
132
+ target?: Record<string, unknown>;
133
+ /** Skip keys that already exist (useful in a browser / H5 build). */
134
+ skipExisting?: boolean;
135
+ /** Additional keys to copy from the scope. */
136
+ extraKeys?: string[];
137
+ }
138
+ /**
139
+ * Explicit opt-in global pollution for libraries that cannot be transformed.
140
+ * Returns a disposer that restores every overwritten descriptor exactly.
141
+ *
142
+ * This is intentionally NOT called automatically: the default path is scoped.
143
+ */
144
+ declare function installGlobals(scope: MiniThreeScope, options?: InstallGlobalsOptions): () => void;
145
+
146
+ export { type DocumentLike, type ElementLike, type InstallGlobalsOptions, type MiniThreeScope, type NavigatorLike, createScope, getActiveScope, hasActiveScope, installGlobals, setActiveScope };
package/dist/scope.js ADDED
@@ -0,0 +1,4 @@
1
+ export { createScope, getActiveScope, hasActiveScope, installGlobals, setActiveScope } from './chunk-34RWHAW4.js';
2
+ import './chunk-V6TY7KAL.js';
3
+ //# sourceMappingURL=scope.js.map
4
+ //# sourceMappingURL=scope.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"sources":[],"names":[],"mappings":"","file":"scope.js"}
@@ -0,0 +1,153 @@
1
+ /**
2
+ * Public type contracts for mini-three-adapter.
3
+ *
4
+ * Design note (AI context): everything in this file is **type-only**. The
5
+ * runtime never imports from `three` and never assumes a browser global. This
6
+ * keeps the adapter usable in Node (tests), in a WeChat mini game, in a WeChat
7
+ * mini program webview-less runtime, and in a browser for H5 dual builds.
8
+ */
9
+ interface Rect {
10
+ top: number;
11
+ left: number;
12
+ width: number;
13
+ height: number;
14
+ right: number;
15
+ bottom: number;
16
+ }
17
+ interface WindowInfo {
18
+ /** CSS pixel width of the drawable area. */
19
+ width: number;
20
+ /** CSS pixel height of the drawable area. */
21
+ height: number;
22
+ /** Physical device pixel ratio, already capped by configuration. */
23
+ pixelRatio: number;
24
+ /** Raw device pixel ratio (before capping). */
25
+ rawPixelRatio: number;
26
+ /** Safe area in CSS pixels, when the platform exposes it. */
27
+ safeArea?: Rect;
28
+ }
29
+ /** A single touch point, in either WeChat mini game or mini program shape. */
30
+ interface TouchPoint {
31
+ identifier?: number;
32
+ clientX?: number;
33
+ clientY?: number;
34
+ pageX?: number;
35
+ pageY?: number;
36
+ x?: number;
37
+ y?: number;
38
+ force?: number;
39
+ }
40
+ /** Platform touch event shape. `touches`/`changedTouches` may be arrays or array-likes. */
41
+ interface TouchLikeEvent {
42
+ type: string;
43
+ touches?: ArrayLike<TouchPoint>;
44
+ changedTouches?: ArrayLike<TouchPoint>;
45
+ timeStamp?: number;
46
+ [key: string]: unknown;
47
+ }
48
+ type TouchEventName = 'touchstart' | 'touchmove' | 'touchend' | 'touchcancel' | 'tap';
49
+ /** Minimal W3C-ish pointer event consumed by three.js controls. */
50
+ interface MiniPointerEvent {
51
+ type: string;
52
+ pointerId: number;
53
+ pointerType: 'touch' | 'mouse' | 'pen';
54
+ isPrimary: boolean;
55
+ clientX: number;
56
+ clientY: number;
57
+ pageX: number;
58
+ pageY: number;
59
+ offsetX: number;
60
+ offsetY: number;
61
+ button: number;
62
+ buttons: number;
63
+ ctrlKey: boolean;
64
+ shiftKey: boolean;
65
+ altKey: boolean;
66
+ metaKey: boolean;
67
+ timeStamp: number;
68
+ target: unknown;
69
+ currentTarget: unknown;
70
+ /** Non-standard, but three's OrbitControls reads it in some versions. */
71
+ pointerX?: number;
72
+ pointerY?: number;
73
+ preventDefault(): void;
74
+ stopPropagation(): void;
75
+ }
76
+ type EventListenerLike = (event: unknown) => void;
77
+ interface EventTargetLike {
78
+ addEventListener(type: string, listener: EventListenerLike, options?: unknown): void;
79
+ removeEventListener(type: string, listener: EventListenerLike, options?: unknown): void;
80
+ dispatchEvent(event: unknown): boolean;
81
+ }
82
+ /** A wx canvas patched to look like an HTMLCanvasElement for three.js. */
83
+ interface PatchedCanvas extends EventTargetLike {
84
+ width: number;
85
+ height: number;
86
+ clientWidth: number;
87
+ clientHeight: number;
88
+ style: CanvasStyleLike;
89
+ getContext(type: string, attrs?: Record<string, unknown>): unknown;
90
+ getBoundingClientRect(): Rect;
91
+ toDataURL(type?: string, quality?: number): string;
92
+ setAttribute(name: string, value: unknown): void;
93
+ removeAttribute(name: string): void;
94
+ focus(): void;
95
+ setPointerCapture(id: number): void;
96
+ releasePointerCapture(id: number): void;
97
+ requestPointerLock(): void;
98
+ exitPointerLock(): void;
99
+ ownerDocument: unknown;
100
+ [key: string]: unknown;
101
+ }
102
+ interface CanvasStyleLike {
103
+ width: string;
104
+ height: string;
105
+ display: string;
106
+ cursor?: string;
107
+ touchAction?: string;
108
+ [key: string]: unknown;
109
+ }
110
+ type ContextType = 'webgl2' | 'webgl' | '2d';
111
+ interface Capabilities {
112
+ platform: 'wechat-game' | 'wechat-miniprogram' | 'browser' | 'unknown';
113
+ /** `Canvas.getContext('webgl2')` is usable. three >= r163 requires WebGL2. */
114
+ webgl2: boolean;
115
+ webgl1: boolean;
116
+ offscreenCanvas: boolean;
117
+ worker: boolean;
118
+ wasm: boolean;
119
+ /** WXWebAssembly supports .wasm.br on some base libraries. */
120
+ brotliWasm: boolean;
121
+ /** wx.createImage / OffscreenCanvas.createImage availability. */
122
+ nativeImage: boolean;
123
+ /** wx.triggerGC is available (iOS high-performance mode hint). */
124
+ triggerGC: boolean;
125
+ /** wx.getWindowInfo available; otherwise we fall back to getSystemInfoSync. */
126
+ getWindowInfo: boolean;
127
+ /** wx.onWindowResize available. */
128
+ windowResizeEvent: boolean;
129
+ baseLibraryVersion: string;
130
+ }
131
+ interface RuntimeEvents {
132
+ resize: (info: WindowInfo) => void;
133
+ visibilitychange: (visible: boolean) => void;
134
+ contextlost: () => void;
135
+ dispose: () => void;
136
+ error: (error: Error) => void;
137
+ }
138
+ type Disposer = () => void;
139
+ interface FrameHandle {
140
+ cancel(): void;
141
+ }
142
+ interface FrameScheduler {
143
+ request(callback: (time: number) => void): number;
144
+ cancel(id: number): void;
145
+ /** Convenience loop with a delta-time argument and automatic cleanup. */
146
+ loop(callback: (deltaMs: number, time: number) => void): FrameHandle;
147
+ /** Cap the logical frame rate; 0 disables the cap. */
148
+ setFpsCap(fps: number): void;
149
+ readonly fps: number;
150
+ dispose(): void;
151
+ }
152
+
153
+ export type { CanvasStyleLike as C, Disposer as D, EventListenerLike as E, FrameHandle as F, MiniPointerEvent as M, PatchedCanvas as P, Rect as R, TouchEventName as T, WindowInfo as W, Capabilities as a, ContextType as b, EventTargetLike as c, FrameScheduler as d, RuntimeEvents as e, TouchLikeEvent as f, TouchPoint as g };
@@ -0,0 +1,150 @@
1
+ /**
2
+ * Hand-written, minimal structural types for the WeChat runtime.
3
+ *
4
+ * Why not `minigame-api-typings`? Because consuming the official typings forces
5
+ * a global `wx` declaration onto every consumer (including browser builds and
6
+ * Node tests) and couples us to a specific version. Structural interfaces let
7
+ * the adapter work with a real `wx`, a mock in tests, or a future platform.
8
+ */
9
+ interface WxCanvas {
10
+ width: number;
11
+ height: number;
12
+ getContext(type: string, attributes?: Record<string, unknown>): unknown;
13
+ toDataURL?(type?: string, quality?: number): string;
14
+ createImage?(): WxImage;
15
+ requestAnimationFrame?(callback: (time: number) => void): number;
16
+ cancelAnimationFrame?(id: number): void;
17
+ [key: string]: unknown;
18
+ }
19
+ interface WxImage {
20
+ width: number;
21
+ height: number;
22
+ src: string;
23
+ onload?: ((event?: unknown) => void) | null;
24
+ onerror?: ((error?: unknown) => void) | null;
25
+ complete?: boolean;
26
+ [key: string]: unknown;
27
+ }
28
+ interface WxRect {
29
+ top: number;
30
+ left: number;
31
+ width: number;
32
+ height: number;
33
+ right: number;
34
+ bottom: number;
35
+ }
36
+ interface WxWindowInfo {
37
+ windowWidth: number;
38
+ windowHeight: number;
39
+ pixelRatio: number;
40
+ screenWidth?: number;
41
+ screenHeight?: number;
42
+ safeArea?: WxRect;
43
+ }
44
+ interface WxTouchPoint {
45
+ identifier?: number;
46
+ clientX?: number;
47
+ clientY?: number;
48
+ pageX?: number;
49
+ pageY?: number;
50
+ x?: number;
51
+ y?: number;
52
+ force?: number;
53
+ }
54
+ interface WxTouchEvent {
55
+ type: string;
56
+ touches?: ArrayLike<WxTouchPoint>;
57
+ changedTouches?: ArrayLike<WxTouchPoint>;
58
+ timeStamp?: number;
59
+ }
60
+ interface WxRequestResult {
61
+ statusCode: number;
62
+ data: string | ArrayBuffer | Record<string, unknown>;
63
+ header?: Record<string, string>;
64
+ errMsg?: string;
65
+ }
66
+ interface WxRequestOptions {
67
+ url: string;
68
+ method?: string;
69
+ data?: unknown;
70
+ header?: Record<string, string>;
71
+ responseType?: 'text' | 'arraybuffer';
72
+ timeout?: number;
73
+ success?: (result: WxRequestResult) => void;
74
+ fail?: (error: {
75
+ errMsg?: string;
76
+ [key: string]: unknown;
77
+ }) => void;
78
+ }
79
+ interface WxSelectorQueryResult {
80
+ node?: WxCanvas;
81
+ width?: number;
82
+ height?: number;
83
+ top?: number;
84
+ left?: number;
85
+ right?: number;
86
+ bottom?: number;
87
+ }
88
+ interface WxSelectorQuery {
89
+ select(selector: string): WxSelectorQuery;
90
+ fields(fields: Record<string, boolean>): WxSelectorQuery;
91
+ exec(callback: (results: (WxSelectorQueryResult | null)[]) => void): void;
92
+ }
93
+ /** The subset of `wx` the adapter touches. All members are optional so the
94
+ * same interface can describe a mini game, a mini program or a test mock. */
95
+ interface WxLike {
96
+ createCanvas?(): WxCanvas;
97
+ createOffscreenCanvas?(options?: {
98
+ width?: number;
99
+ height?: number;
100
+ type?: '2d' | 'webgl' | 'webgl2';
101
+ }): WxCanvas;
102
+ createImage?(): WxImage;
103
+ createImageData?(width: number, height: number): unknown;
104
+ getWindowInfo?(): WxWindowInfo;
105
+ getSystemInfoSync?(): WxWindowInfo;
106
+ onWindowResize?(listener: (res: {
107
+ windowWidth: number;
108
+ windowHeight: number;
109
+ }) => void): void;
110
+ offWindowResize?(listener: (res: {
111
+ windowWidth: number;
112
+ windowHeight: number;
113
+ }) => void): void;
114
+ onTouchStart?(listener: (event: WxTouchEvent) => void): void;
115
+ onTouchMove?(listener: (event: WxTouchEvent) => void): void;
116
+ onTouchEnd?(listener: (event: WxTouchEvent) => void): void;
117
+ onTouchCancel?(listener: (event: WxTouchEvent) => void): void;
118
+ offTouchStart?(listener: (event: WxTouchEvent) => void): void;
119
+ offTouchMove?(listener: (event: WxTouchEvent) => void): void;
120
+ offTouchEnd?(listener: (event: WxTouchEvent) => void): void;
121
+ offTouchCancel?(listener: (event: WxTouchEvent) => void): void;
122
+ onShow?(listener: () => void): void;
123
+ onHide?(listener: () => void): void;
124
+ offShow?(listener: () => void): void;
125
+ offHide?(listener: () => void): void;
126
+ request?(options: WxRequestOptions): {
127
+ abort?(): void;
128
+ };
129
+ createSelectorQuery?(): WxSelectorQuery;
130
+ getPerformance?(): {
131
+ now(): number;
132
+ };
133
+ setPreferredFramesPerSecond?(fps: number): void;
134
+ triggerGC?(): void;
135
+ createWorker?(path: string, options?: unknown): unknown;
136
+ env?: {
137
+ USER_DATA_PATH?: string;
138
+ [key: string]: unknown;
139
+ };
140
+ getSystemInfo?(options: {
141
+ success?: (info: WxWindowInfo & {
142
+ SDKVersion?: string;
143
+ }) => void;
144
+ }): void;
145
+ [key: string]: unknown;
146
+ }
147
+ /** Resolve `wx` from an explicit injection or from the host global. */
148
+ declare function resolveWx(injected?: WxLike): WxLike;
149
+
150
+ export { type WxCanvas as W, type WxImage as a, type WxLike as b, type WxRect as c, type WxRequestOptions as d, type WxRequestResult as e, type WxSelectorQuery as f, type WxSelectorQueryResult as g, type WxTouchEvent as h, type WxTouchPoint as i, type WxWindowInfo as j, resolveWx as r };
@@ -0,0 +1,105 @@
1
+ # 01 · 设计目标与技术约束
2
+
3
+ > 本文档描述 `mini-three-adapter` 自身的设计目标、运行环境约束、技术选型与能力边界。它是阅读 [02 架构设计](./02-architecture.md) 之前的总纲。
4
+
5
+ ## 1.1 项目定位
6
+
7
+ `mini-three-adapter` 让 three.js 运行在微信小游戏 / 小程序的**非 WebView 原生渲染环境**中,目标是让业务侧的场景代码尽可能保持标准 three.js 写法:
8
+
9
+ - 用 `new THREE.WebGLRenderer({ canvas })` 创建渲染器,不改写 three 源码、不引入定制版 three。
10
+ - 用 `three/addons/*` 的控制器、加载器,交互行为与浏览器一致。
11
+ - 同一份场景代码可以在小游戏、小程序和 H5 双端运行。
12
+ - 适配层本身不参与渲染管线、不管理材质与资源生命周期,这些仍归 three 与业务代码。
13
+
14
+ ## 1.2 运行环境约束
15
+
16
+ 微信小游戏的 JavaScript 运行时在 iOS 是 JavaScriptCore、Android 是 V8,**没有 BOM 与 DOM**:不存在全局 `window`、`document`、`Image`、`URL`、`XMLHttpRequest`、`EventTarget`。基础库只提供 `wx.*` 平台 API 与 `setTimeout` / `requestAnimationFrame` 等基础方法;DOM 兼容层需要由应用自行引入。
17
+
18
+ 由此派生出几条硬约束:
19
+
20
+ | 约束 | 对实现的要求 |
21
+ | --- | --- |
22
+ | 只有一个上屏画布:首次 `wx.createCanvas()` 得到上屏画布,后续调用得到的都是离屏画布 | 必须把这一次调用收敛到单一位置并缓存;能力探测只能用 `wx.createOffscreenCanvas()` |
23
+ | 宿主内部按对象身份保存画布校验数据 | 画布补丁必须作用于原对象,不能包装、克隆或改原型 |
24
+ | `Canvas.getContext('webgl2')` 是可用的标准 WebGL2 上下文 | three ≥ r163 仅支持 WebGL2,适配层以 WebGL2 为唯一主线 |
25
+ | Worker 并发上限为 1,且配置只支持一个目录 | worker 与 wasm 必须输出到同一目录,分包 Worker 需先预下载 |
26
+ | 代码包有体积上限(主包 / 分包各 4MB、总包 8MB,以控制台额度为准) | three 本体、decoder、wasm 需要分包;`.wasm.br` 是有效的减包手段 |
27
+ | iOS 高性能模式内存限制更严,高性能+ 建议用于 WebGL2 场景 | 启动阶段就要能报告能力、避免不必要的大对象常驻 |
28
+
29
+ 小程序(非小游戏)额外约束:画布节点要通过 `createSelectorQuery().select(...).fields({ node, rect, size })` **异步**取得,触摸事件由 WXML 绑定下发,而不是 `wx.onTouch*`。
30
+
31
+ ## 1.3 Three.js 版本约束
32
+
33
+ | 版本 | 关系 |
34
+ | --- | --- |
35
+ | `>= 0.163.0`(r163+) | 目标区间。`WebGLRenderer` 要求 WebGL2 |
36
+ | `0.187.0` | 当前构建与单元测试所依据的版本 |
37
+ | `0.151.0 ~ 0.162.x` | 不保证:未针对 WebGL1 路径做专门适配 |
38
+ | `< 0.151.0` | 不提供保证 |
39
+ | `three/webgpu` + TSL / NodeMaterial | 小游戏环境没有 WebGPU,构建插件默认告警;复杂 WebGPU 项目需使用 WebGL 构建目标 |
40
+
41
+ 版本升级时需要复核:导入路径(`three/addons/*`)、`renderer.outputColorSpace`、`renderer.setAnimationLoop()`、以及 three 新增的浏览器全局与 DOM 属性清单。检查项固化在 [`docs/11-compat-matrix.md`](./11-compat-matrix.md)。
42
+
43
+ ## 1.4 设计目标
44
+
45
+ 1. **不 fork three**:构建期只重定向三方模块对浏览器全局的自由引用,不修改 three 的语义。适配层与 three 版本解耦。
46
+ 2. **零全局污染**:所有 shim 存放在显式的 `MiniThreeScope` 中,可被替换、可被卸载;写 `globalThis` 只发生在显式调用且可逆的路径上。
47
+ 3. **一套 API 覆盖三端**:`createRuntime()` 返回唯一的 `MiniThreeRuntime`,平台差异收敛在 `PlatformBinding` 内部。
48
+ 4. **单一生命周期**:所有订阅、定时器、全局注入统一登记,`dispose()` 之后不留副作用。
49
+ 5. **可测试**:平台宿主可注入,核心逻辑能在 Node + Vitest 中完整验证,无需真实设备。
50
+ 6. **可观测**:分级日志、一次性告警、能力报告与构建报告,让环境问题在启动/构建阶段就能定位。
51
+ 7. **可 tree-shake**:ESM + 子路径导出 + 显式 `sideEffects`,运行时不携带构建工具依赖。
52
+
53
+ ## 1.5 技术选型
54
+
55
+ | 领域 | 选型 | 理由 |
56
+ | --- | --- | --- |
57
+ | 语言与模块 | TypeScript strict + ESM | 完整 `.d.ts`,编译期捕获平台类型差异 |
58
+ | 运行时构建目标 | `es2019`(esbuild / tsup) | 降级可选链与空值合并,避免开发者工具语法报错 |
59
+ | 全局重定向 | `@babel/parser` + `@babel/traverse` + `magic-string` | 依赖真实作用域绑定信息,只改写自由变量,保留 sourcemap |
60
+ | 画布兼容 | `Object.defineProperty` + `Symbol.hasInstance` 注册表 | 保持对象身份,满足 three 的 `instanceof` 分支 |
61
+ | 平台抽象 | 结构化接口 `PlatformBinding` | 以组合方式表达平台差异,新增平台只需实现一组字段与方法 |
62
+ | 作用域 | `getActiveScope()` 惰性读取 | 支持运行时替换、多实例与测试注入 |
63
+ | 网络 | `wx.request` 桥接 `fetch` / `XMLHttpRequest` | three 的 FileLoader 与 addons 可直接工作 |
64
+ | 对象 URL | `mini-three-blob:` → `data:` URI | 宿主图片加载器可直接识别,无需拦截 `Image.src` |
65
+ | 构建工具集成 | Rollup 兼容插件核心 + Vite 薄封装 | 一套逻辑覆盖 Vite / Rollup,Node 依赖不进小游戏包 |
66
+
67
+ ## 1.6 能力边界
68
+
69
+ **做**:
70
+
71
+ - 补全 three 与主流生态(three-stdlib / @react-three / @tresjs)用到的浏览器全局、DOM 属性与构造器判定。
72
+ - 把平台 `touch` 事件转换为符合 three controls 预期的 `pointer*` / `mouse*` 事件。
73
+ - 统一窗口尺寸、DPR、resize、可见性、帧循环。
74
+ - 构建期收集 worker / wasm / decoder 资源并生成分包建议。
75
+ - 提供 H5 双端可运行的 `browser` 平台。
76
+
77
+ **不做**:
78
+
79
+ - 不提供完整 DOM / CSS 布局 / 事件冒泡树;DOM 密集型 UI 应使用 WebView 方案。
80
+ - 不模拟 WebGPU;`createImageBitmap`、`FileReader`、`WebSocket` 保持 `undefined`,让依赖它们的库走降级分支。
81
+ - 不在运行时改写 `WebGLRenderer` 的行为;平台差异补丁一律显式、可关闭、可观测。
82
+ - 不默认改写业务代码(插件只处理 `node_modules` 中的三方生态模块)。
83
+ - 不内置物理、动画、UI 等 3D 引擎能力。
84
+
85
+ ## 1.7 关键设计决策一览
86
+
87
+ | 决策 | 落地位置 | 详情 |
88
+ | --- | --- | --- |
89
+ | 显式可逆作用域 | `src/scope.ts` | [ADR-0001](./adr/0001-scoped-globals.md) |
90
+ | 单一运行生命周期 | `src/core/runtime.ts` | [ADR-0002](./adr/0002-unified-runtime-lifecycle.md) |
91
+ | AST 作用域重写 | `src/build/scope-rewrite.ts` | [ADR-0003](./adr/0003-ast-rewrite.md) |
92
+ | 就地画布补丁 | `src/core/element.ts` | [ADR-0004](./adr/0004-in-place-patching.md) |
93
+ | WebGL2 优先 | `src/core/capabilities.ts` | [ADR-0005](./adr/0005-webgl2-only.md) |
94
+ | 零 three 依赖、构建运行隔离 | `tsup.config.ts` | [ADR-0006](./adr/0006-zero-three-dependency.md) |
95
+
96
+ ## 1.8 规范链接
97
+
98
+ 平台与渲染引擎的权威规范,用于核对能力边界:
99
+
100
+ - [微信开放文档 · Adapter](https://developers.weixin.qq.com/minigame/dev/guide/runtime/adapter.html)
101
+ - [微信开放文档 · 渲染](https://developers.weixin.qq.com/minigame/dev/guide/base-ability/render.html)
102
+ - [微信开放文档 · 使用 WXWebAssembly](https://developers.weixin.qq.com/minigame/dev/guide/performance/perf-webassembly.html)
103
+ - [微信开放文档 · iOS 高性能与高性能+模式](https://developers.weixin.qq.com/minigame/dev/guide/game-engine/unity-webgl-transform/Design/iOSOptimization.html)
104
+ - 微信开放文档 · 小游戏配置(game.json 的 workers / subpackages / iOSHighPerformance 字段)
105
+ - [three.js Migration Guide](https://github.com/mrdoob/three.js/wiki/Migration-Guide)