@octanejs/three 0.1.25 → 0.1.27

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/README.md CHANGED
@@ -137,6 +137,19 @@ root.render(Scene, { color: 'hotpink' });
137
137
  root.store.getState().advance(1 / 60);
138
138
  ```
139
139
 
140
+ Compiled Three scene modules import and register only the built-in constructors
141
+ used by their authored intrinsic tags, so direct roots do not retain the entire
142
+ Three namespace. Both extension forms remain selective: `extend({ CustomMesh })`
143
+ registers the named constructor, while `extend(CustomMesh)` returns a stable
144
+ callable component without registering unrelated built-ins. An explicit
145
+ extension always takes precedence over a compiler-registered constructor.
146
+
147
+ `Canvas` registers the complete Three namespace when it first renders, retaining
148
+ the familiar R3F-compatible catalogue for dynamic or otherwise uncompiled scene
149
+ content. Code that constructs low-level universal host plans by hand instead
150
+ of compiling a `.three.tsrx` scene must register each constructor itself before
151
+ rendering, for example `extend({ Mesh })` for a manually authored `mesh` plan.
152
+
140
153
  Direct-root scheduling uses Octane's public `act` and `flushSync` semantics.
141
154
  Call `root.unmount()` directly, or use
142
155
  `unmountComponentAtNode(canvas, optionalCallback)` to remove the root registered
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@octanejs/three",
3
- "version": "0.1.25",
3
+ "version": "0.1.27",
4
4
  "license": "MIT",
5
5
  "type": "module",
6
6
  "sideEffects": false,
@@ -51,7 +51,7 @@
51
51
  "peerDependencies": {
52
52
  "@types/three": ">=0.156.0",
53
53
  "three": ">=0.156.0",
54
- "octane": "0.1.32"
54
+ "octane": "0.1.34"
55
55
  },
56
56
  "peerDependenciesMeta": {
57
57
  "@types/three": {
@@ -72,10 +72,10 @@
72
72
  "typescript": "^5.9.3",
73
73
  "vite": "^8.1.5",
74
74
  "vitest": "^4.1.10",
75
- "@octanejs/rsbuild-plugin": "0.1.27",
76
- "@octanejs/rspack-plugin": "0.1.27",
77
- "@octanejs/vite-plugin": "0.1.32",
78
- "octane": "0.1.32"
75
+ "@octanejs/rsbuild-plugin": "0.1.29",
76
+ "@octanejs/rspack-plugin": "0.1.29",
77
+ "@octanejs/vite-plugin": "0.1.34",
78
+ "octane": "0.1.34"
79
79
  },
80
80
  "scripts": {
81
81
  "test": "pnpm upstream:check && vitest run --root ../.. --project three",
@@ -14,6 +14,7 @@ import {
14
14
  universalValue,
15
15
  } from 'octane/universal';
16
16
  import type { EventHandlers } from './events.js';
17
+ import { registerTrustedThreeConstructor } from './constructors.js';
17
18
 
18
19
  export const THREE_RENDERER_ID = 'three';
19
20
 
@@ -182,11 +183,23 @@ function toPascalCase(type: string): string {
182
183
  return type.length === 0 ? type : `${type[0].toUpperCase()}${type.slice(1)}`;
183
184
  }
184
185
 
185
- /** Register the built-in Three namespace once, at driver creation time. */
186
+ /** Register one compiler-selected built-in without replacing an authored extension. */
187
+ export function registerThreeIntrinsic(name: string, Constructor: ConstructorRepresentation): void {
188
+ registerTrustedThreeConstructor(Constructor);
189
+ if (!Object.hasOwn(catalogue, name)) catalogue[name] = Constructor;
190
+ }
191
+
192
+ /** Register the complete Three namespace only for Canvas's compatibility surface. */
186
193
  export function registerThreeNamespace(): void {
187
194
  if (namespaceRegistered) return;
188
195
  namespaceRegistered = true;
189
- Object.assign(catalogue, THREE);
196
+ for (const name of Object.keys(THREE)) {
197
+ const Constructor = (THREE as unknown as Catalogue)[name];
198
+ registerTrustedThreeConstructor(Constructor);
199
+ if (!Object.hasOwn(catalogue, name)) {
200
+ catalogue[name] = Constructor;
201
+ }
202
+ }
190
203
  }
191
204
 
192
205
  /** Resolve conflicting `threeLine`-style host names without shadowing explicit extensions. */
@@ -242,9 +255,6 @@ export function extend<T extends Catalogue>(objects: T): void;
242
255
  export function extend<T extends Catalogue | ConstructorRepresentation>(
243
256
  objects: T,
244
257
  ): UniversalComponent<any> | void {
245
- // Seed built-ins before user entries so an explicit extension can override a
246
- // catalogue name deterministically, independent of driver creation order.
247
- registerThreeNamespace();
248
258
  if (typeof objects !== 'function') {
249
259
  Object.assign(catalogue, objects);
250
260
  return;
@@ -0,0 +1,36 @@
1
+ import {
2
+ Color,
3
+ Euler,
4
+ Layers,
5
+ Matrix3,
6
+ Matrix4,
7
+ Quaternion,
8
+ Vector2,
9
+ Vector3,
10
+ Vector4,
11
+ } from 'three';
12
+
13
+ // These value classes occur on ordinary Three objects even when they are not
14
+ // authored as scene intrinsics. Keep their identities explicit so bundlers can
15
+ // discard the rest of the Three namespace and custom subclasses stay untrusted.
16
+ const TRUSTED_THREE_CONSTRUCTORS = new WeakSet<Function>([
17
+ Color,
18
+ Euler,
19
+ Layers,
20
+ Matrix3,
21
+ Matrix4,
22
+ Quaternion,
23
+ Vector2,
24
+ Vector3,
25
+ Vector4,
26
+ ]);
27
+
28
+ /** Accept constructors obtained from compiler-owned or full Three namespace registration. */
29
+ export function registerTrustedThreeConstructor(value: unknown): void {
30
+ if (typeof value === 'function') TRUSTED_THREE_CONSTRUCTORS.add(value);
31
+ }
32
+
33
+ /** Only an exact Three constructor, never a derived custom class, is trusted. */
34
+ export function isTrustedThreeConstructor(value: unknown): boolean {
35
+ return typeof value === 'function' && TRUSTED_THREE_CONSTRUCTORS.has(value);
36
+ }
@@ -26,7 +26,6 @@ import {
26
26
  } from './store.js';
27
27
  import {
28
28
  createThreeObject,
29
- registerThreeNamespace,
30
29
  resolveThreeConstructor,
31
30
  THREE_RENDERER_ID,
32
31
  type ConstructorRepresentation,
@@ -1858,7 +1857,6 @@ export function applyProps<T extends object>(
1858
1857
  export function createThreeDriver(
1859
1858
  renderer = THREE_RENDERER_ID,
1860
1859
  ): UniversalHostDriver<ThreeHostContainer, object> {
1861
- registerThreeNamespace();
1862
1860
  return {
1863
1861
  id: renderer,
1864
1862
  capabilities: {
package/src/core/props.ts CHANGED
@@ -12,6 +12,7 @@
12
12
  * properties only; renderer-reserved callbacks never become object fields.
13
13
  */
14
14
  import * as THREE from 'three';
15
+ import { isTrustedThreeConstructor } from './constructors.js';
15
16
 
16
17
  export type ThreePropBag = Readonly<Record<string, unknown>>;
17
18
 
@@ -53,11 +54,6 @@ export const THREE_RESERVED_PROPS = Object.freeze([
53
54
  const EVENT_PROP = /^on(Pointer|Click|DoubleClick|ContextMenu|Wheel)/;
54
55
  const COLOR_MAPS = new Set(['map', 'emissiveMap', 'sheenColorMap', 'specularColorMap', 'envMap']);
55
56
  const MEMOIZED_PROTOTYPES = new Map<Function, any>();
56
- const THREE_CONSTRUCTORS = new Set<Function>(
57
- Object.values(THREE as unknown as Record<string, unknown>).filter(
58
- (value) => typeof value === 'function',
59
- ) as Function[],
60
- );
61
57
  const UNKNOWN_SHAPE = Symbol('unknown Three property shape');
62
58
 
63
59
  function isObject(value: unknown): value is Record<string, any> {
@@ -373,7 +369,7 @@ function resolveShadowProperty(state: ShadowState, key: string): ResolvedShadowP
373
369
 
374
370
  function isKnownThreeValue(value: unknown): boolean {
375
371
  const Constructor = (value as { constructor?: unknown } | null)?.constructor;
376
- return typeof Constructor === 'function' && THREE_CONSTRUCTORS.has(Constructor);
372
+ return isTrustedThreeConstructor(Constructor);
377
373
  }
378
374
 
379
375
  function isCanonicalThreeMethod(value: unknown, key: string, method: unknown): boolean {
package/src/core/store.ts CHANGED
@@ -6,13 +6,8 @@
6
6
  * components. Zustand remains the framework-neutral storage primitive.
7
7
  */
8
8
  import * as THREE from 'three';
9
- import {
10
- createContext,
11
- useContext,
12
- useRef,
13
- useSyncExternalStore,
14
- withSlot,
15
- } from 'octane/universal';
9
+ import { useContext, useRef, useSyncExternalStore, withSlot } from 'octane/universal';
10
+ import { createContext } from 'octane/universal/native';
16
11
  import { createStore as createVanillaStore, type StoreApi } from 'zustand/vanilla';
17
12
  import type {
18
13
  DomEvent,
package/src/renderer.ts CHANGED
@@ -7,6 +7,7 @@
7
7
  */
8
8
  export * from 'octane/universal';
9
9
  export * from './core/index.js';
10
+ export { registerThreeIntrinsic } from './core/catalogue.js';
10
11
  // Resolve the deliberate name overlap with the capability-gated universal
11
12
  // primitive in favor of Three's R3F-shaped state-enclave adapter.
12
13
  export { createPortal } from './core/portal.js';
package/src/scheduling.ts CHANGED
@@ -1,6 +1,10 @@
1
1
  import * as Octane from 'octane';
2
- import { flushSync as clientFlushSync } from 'octane';
3
- import { flushUniversalAct, flushUniversalSync, type UniversalSyncFlusher } from 'octane/universal';
2
+ import {
3
+ flushUniversalAct,
4
+ flushUniversalSync,
5
+ getUniversalHostFlusher,
6
+ type UniversalSyncFlusher,
7
+ } from 'octane/universal';
4
8
 
5
9
  export type Act = typeof import('octane').act;
6
10
  type FlushSync = typeof import('octane').flushSync;
@@ -67,7 +71,7 @@ function runClientAct<T>(callback: () => T | Promise<T>, clientAct: Act): Promis
67
71
 
68
72
  /** Flushes both the DOM scheduler and mounted universal Three roots. */
69
73
  export const flushSync: FlushSync = (callback) => {
70
- return flushUniversalSync(callback, clientFlushSync);
74
+ return flushUniversalSync(callback, getUniversalHostFlusher());
71
75
  };
72
76
 
73
77
  /** R3F-compatible test helper backed by Octane's client scheduler when available. */
@@ -78,7 +82,7 @@ export const act: Act = (callback) => {
78
82
  const clientAct = Reflect.get(Octane, 'act') as Act | undefined;
79
83
  if (typeof clientAct === 'function') return runClientAct(callback, clientAct);
80
84
  try {
81
- return Promise.resolve(runActCallback(callback, clientFlushSync));
85
+ return Promise.resolve(runActCallback(callback, getUniversalHostFlusher()));
82
86
  } catch (error) {
83
87
  return Promise.reject(error);
84
88
  }
@@ -2,6 +2,7 @@ import { useInsertionEffect, useLayoutEffect, useRef, useState } from 'octane';
2
2
  import type { OctaneNode } from 'octane';
3
3
  import { createUniversalHostBoundary } from 'octane/universal';
4
4
  import type { RendererRegion } from 'octane/universal';
5
+ import { registerThreeNamespace } from '../core/catalogue.js';
5
6
  import type { ComputeFunction, DomEvent } from '../core/events.js';
6
7
  import { createRoot, createThreeBoundaryMount } from '../core/root.js';
7
8
  import type { RenderProps, ThreeBoundaryMount, ThreeRoot } from '../core/root.js';
@@ -208,6 +209,7 @@ export function Canvas({
208
209
  let cancelled = false;
209
210
  let root = rootRef.current;
210
211
  if (root === null) {
212
+ registerThreeNamespace();
211
213
  root = createRoot(canvas);
212
214
  rootRef.current = root;
213
215
  }
@@ -1,6 +1,10 @@
1
1
  import * as Octane from 'octane';
2
2
  import type { ComponentBody, Root } from 'octane';
3
- import { isRendererRegion, type RendererRegion } from 'octane/universal';
3
+ import {
4
+ isRendererRegion,
5
+ registerUniversalHostBridge,
6
+ type RendererRegion,
7
+ } from 'octane/universal';
4
8
 
5
9
  export type DOMRegionTarget = HTMLElement | { current: HTMLElement | null };
6
10
 
@@ -28,6 +32,7 @@ export interface DOMRegionBinding {
28
32
  }
29
33
 
30
34
  export function createDOMRegionBinding(): DOMRegionBinding {
35
+ registerUniversalHostBridge();
31
36
  const createRoot = Reflect.get(Octane, 'createRoot') as
32
37
  typeof import('octane').createRoot | undefined;
33
38
  if (typeof createRoot !== 'function' || typeof document === 'undefined') {