@octanejs/three 0.1.0 → 0.1.3

package/README.md

@@ -4,7 +4,7 @@ An experimental React Three Fiber 9-compatible web renderer for Octane. Octane
 keeps ownership of component execution, hooks, context, Suspense, refs, and
 effects; this package supplies the Three-specific host layer.
 
-Milestones 0, 2, 3, 4, 5, and 6 are implemented on top of Octane's renderer SDK
+Milestones 0–10 are implemented across this package and Octane's renderer SDK
 foundation. The current technical preview includes:
 
 - the serializable compiler preset, renderer entry point, renderer-local Three
@@ -30,12 +30,28 @@ foundation. The current technical preview includes:
   client-side Three-to-DOM pending/error projection;
 - same-renderer `createPortal` placement into borrowed `Object3D` targets,
   R3F-shaped state/event enclaves, nested context retention, one shared frame
-  loop, physical Three event bubbling, and root-scoped target teardown; and
+  loop, physical Three event bubbling, and root-scoped target teardown;
+- client-only Canvas SSR that streams and hydrates the existing DOM shell and
+  native canvas fallback without executing Three scene setup, constructors, or
+  loaders on the server;
+- direct `HTMLCanvasElement` and `OffscreenCanvas` roots, public Octane
+  `act`/`flushSync` scheduling, callback-aware `unmountComponentAtNode`, and
+  demand-loop invalidation after WebGL context restoration;
+- controlled WebXR session-loop handoff and teardown, plus compatible HMR that
+  retains live objects and incompatible `args` edits that reconstruct without
+  stale refs, handlers, or resources;
+- the low-level `DOMRegion` Three-to-DOM boundary with an explicit target and
+  deterministic DOM ownership; and
 - public behavior, prepared-driver, and same-source compiled scene evidence
-  against R3F 9.6.1 with the exact Three r172 oracle.
-
-Full Canvas SSR/hydration adoption, XR, OffscreenCanvas lifecycle, and live HMR
-behavior follow in later milestones.
+  against R3F 9.6.1 with the exact Three r172 oracle;
+- a real asynchronous `MessageChannel` renderer proof with structured-cloned
+  batches and values, root-scoped resource/portal handles, listener IDs,
+  acknowledgement-gated refs/layout, rejection/fault semantics, teardown, and
+  native-event delivery; and
+- a checked public export/subpath type matrix, Three r156/current compatibility
+  lanes, a packed external consumer, real WebGL creation-failure and context-
+  recovery coverage, and semantic-checksummed renderer and shipped-size
+  benchmarks.
 
 Three deliberate correctness fixes differ from R3F 9.6.1:
 
@@ -66,13 +82,15 @@ export default defineConfig({
 ```
 
 The same serializable `threeRenderers` value can be supplied to the Rsbuild and
-low-level Rspack integrations. Vite and Rsbuild additionally own application
-SSR and hydration; the Rspack plugin owns compilation and HMR only.
+low-level Rspack integrations. Vite and Rsbuild own the production application
+SSR/hydration lifecycle; the Rspack plugin owns the equivalent client/server
+graph split, compilation, and HMR transforms rather than an application server.
 
 The preset selects `@octanejs/three/renderer`, keeps Three scene modules
 client-only on the server, ignores authored text inside scenes, exposes a
 renderer-local intrinsic catalogue without merging Three tags into DOM JSX,
-and declares `Canvas.children` as the DOM-to-Three renderer boundary.
+and declares both `Canvas.children` as the DOM-to-Three renderer boundary and
+`DOMRegion.children` as the explicit Three-to-DOM boundary.
 
 ## Canvas and scene modules
 
@@ -106,9 +124,9 @@ export function Scene() @{
 }
 ```
 
-The low-level API follows Octane's component-plus-props root convention. Both
-synchronous and asynchronous renderer factories settle before the component
-can execute:
+The low-level API follows Octane's component-plus-props root convention and
+accepts either an `HTMLCanvasElement` or an `OffscreenCanvas`. Both synchronous
+and asynchronous renderer factories settle before the component can execute:
 
 ```ts
 import { createRoot } from '@octanejs/three';
@@ -119,6 +137,13 @@ root.render(Scene, { color: 'hotpink' });
 root.store.getState().advance(1 / 60);
 ```
 
+Direct-root scheduling uses Octane's public `act` and `flushSync` semantics.
+Call `root.unmount()` directly, or use
+`unmountComponentAtNode(canvas, optionalCallback)` to remove the root registered
+for either canvas kind. The optional callback runs synchronously only after
+teardown completes successfully. Teardown disconnects events and XR, clears the
+animation loop, releases scene resources, and disposes the renderer.
+
 Tests can inject the WebGL-free deterministic harness from
 `@octanejs/three/testing`; it drives the same root, host commits, hooks, and
 public `advance()` loop as an application. Its awaitable `fireEvent()` helper
@@ -136,6 +161,50 @@ that call its own lexical hook slot; keep that compatibility form unconditional
 and in stable order. Prefer `useStore(selector, equality?)` or
 `useThree(selector, equality?)` when using Octane's conditional-hook semantics.
 
+## Root lifecycle, XR, and HMR
+
+When the configured renderer exposes Three's XR event surface, the root listens
+for `sessionstart` and `sessionend`. A presenting session uses
+`renderer.xr.setAnimationLoop`; `frameloop="never"` remains manual, and ending
+the session invalidates the configured non-XR loop. Unmount removes both
+listeners, clears the XR callback, and makes any retained callback inert.
+
+WebGL context loss is prevented while the root is live. Context restoration
+invalidates the root so an `always` or `demand` root renders again; teardown
+removes both context listeners before forcing renderer context loss.
+
+Universal HMR preserves component state and Three object identity for compatible
+edits. A constructor `args` change reconstructs the affected object, detaches
+and reattaches stable refs, retires old handlers, and disposes the old owned
+resource once. Vite and the Rspack/Rsbuild path emit the same universal HMR
+wrapper behavior.
+
+## DOM regions
+
+`DOMRegion` is a low-level reverse-renderer boundary for mounting ordinary
+Octane DOM content from a Three scene into an explicit DOM target:
+
+```tsx
+// Scene.three.tsrx
+import { DOMRegion } from '@octanejs/three';
+
+export function Scene(props) @{
+	<DOMRegion target={props.overlayTarget}>
+		<button onClick={props.onClick}>Inspect object</button>
+	</DOMRegion>
+}
+```
+
+Each region owns one child container and one DOM root. Updating or moving its
+target preserves that container, DOM state, and node identity; deleting the
+region removes its owned DOM deterministically. The target may be an
+`HTMLElement` or an object ref whose `current` value is an `HTMLElement` or
+`null`.
+
+`DOMRegion` is not Drei `Html` and is not the WebXR DOM Overlay API. It provides
+no positioning, occlusion, transforms, styling, or layout contract. Those
+policies belong to future higher-level packages.
+
 ## Portals
 
 `createPortal` keeps its children in the authored Octane owner/context tree but
@@ -201,15 +270,30 @@ useLoader.clear(GLTFLoader, '/model.glb');
 the resolved asset. Declarative Three resources remain owned by their mounted
 host tree, while objects passed through `primitive` remain caller-owned. A
 root-level Three suspension or render error is projected through `Canvas` to
-the nearest client DOM `@pending` or `@catch` arm. Streaming server fallback
-and Canvas hydration remain Milestone 7 work.
+the nearest client DOM `@pending` or `@catch` arm. On the server, `Canvas`
+streams its DOM shell and native `<canvas>` fallback without evaluating the
+client-only scene. Hydration adopts that shell before measurement creates one
+fresh Three root on the client.
 
 ## Compatibility target
 
 The compatibility baseline is `@react-three/fiber@9.6.1` at commit
 `2a528745e9aa7c9e6cca41e404b59d45cf0d0cc7`, with `three@0.172.0` as the exact
-behavioral oracle. React Native/Expo, R3F 10's WebGPU/TSL APIs, and Drei are
-separate follow-on efforts.
+behavioral and differential oracle. The published peer range is
+`three >=0.156.0`, guarded by minimum-r156 and current-release CI lanes; the
+r172 lane remains immutable so a moving current dependency cannot change the
+parity oracle. TypeScript consumers must install `@types/three` from the same
+Three release line explicitly; its patch revision may differ from the runtime.
+It is an optional peer so a package manager cannot silently auto-install current
+declarations beside an older supported runtime:
+
+```bash
+pnpm add three@0.156.0
+pnpm add -D @types/three@0.156.0
+```
+
+React Native/Expo, R3F 10's WebGPU/TSL APIs, and Drei are separate follow-on
+efforts.
 
 See [`docs/three-port-plan.md`](../../docs/three-port-plan.md) for the delivery
 phases and [`UPSTREAM.md`](./UPSTREAM.md) for source and license provenance.

package/UPSTREAM.md

@@ -8,9 +8,15 @@ This port targets the immutable React Three Fiber release `v9.6.1`:
 - exact Three behavior and type oracle: `three@0.172.0` and
   `@types/three@0.172.0`.
 
-The upstream package accepts `three >=0.156`, but this port initially supports
-only the pinned r172 lane. The broader peer range is gated on a real
-minimum-version validation lane.
+The port advertises the upstream `three >=0.156` range. Its immutable
+differential oracle stays on r172, while separate CI jobs typecheck and run the
+Octane-owned compatibility suite against the minimum r156 pair and the current
+registry release. This prevents either a moving latest dependency or the pinned
+oracle from standing in for the other compatibility claim. `@types/three` is an
+optional peer that TypeScript consumers install from the same Three release line;
+its patch revision may differ from the runtime. Making it optional prevents
+package-manager peer auto-install from silently pairing current declarations with
+an older supported runtime.
 
 ## Source boundary
 
@@ -51,6 +57,49 @@ events bubble through physical Three ancestry. Octane's universal portal range
 retains logical context, error, effect, and scheduling ownership without
 embedding React Reconciler or representing the target as a fake host child.
 
+Milestone 7 follows the pinned web `Canvas` contract: the server emits the
+ordinary DOM wrapper, canvas, and native fallback while omitting Three children.
+Hydration adopts those DOM nodes, then positive client measurement creates one
+fresh Three root. Scene setup, constructors, and loaders remain outside the
+server execution path; client Three suspension and errors project through the
+owning DOM boundary, and deleting the Canvas tears down the nested root.
+
+Milestone 8 follows the pinned direct-root, HMR, and XR lifecycle contracts while
+keeping scheduling under Octane. Direct roots accept `HTMLCanvasElement` and
+`OffscreenCanvas`, expose Octane's `act` and `flushSync`, and support
+callback-aware `unmountComponentAtNode`. Octane completes that teardown and
+callback synchronously instead of retaining R3F's 500-millisecond delay.
+Compatible universal HMR edits retain Three objects; constructor `args` edits
+reconstruct them with ref, handler, and owned-resource cleanup. A controlled WebXR session hands rendering to
+`setAnimationLoop`, respects manual `frameloop="never"`, restores the configured
+loop on session end, and disconnects without leaving a live callback. WebGL
+context restoration invalidates the live root before teardown removes its
+listeners.
+
+Milestone 9 validates the renderer vocabulary independently of an in-process
+Three host. A real asynchronous `MessageChannel` carries structured-cloned host
+batches to a separate object driver and returns versioned acknowledgement,
+completion, rejection, fault, and event messages. Logical topology, lifecycle,
+refs, layout effects, and teardown publish only after acknowledgement; pre-ack
+rejection remains retryable, while post-ack faults retain the accepted commit.
+The existing portal proof separately verifies that only a root-scoped portal
+handle, never the raw target, enters a cloned batch.
+
+Milestone 10 hardens the release claim with an existence-checked 90-export/
+157-test crosswalk, public export and package-subpath type matrices, r156 and
+current Three compatibility lanes, and an external packed consumer that builds
+and executes the published package without React. Chromium coverage exercises
+real WebGL construction failure and `WEBGL_lose_context` loss/restoration.
+Renderer lifecycle/event benchmarks and minimal/full-catalogue shipped-size
+benchmarks compare Octane Three, R3F 9.6.1, and direct Three behind semantic
+checksums and committed ratio guards.
+
+`DOMRegion` is an Octane-specific proof of the already-compiled Three-to-DOM
+renderer boundary, so it is not part of the pinned R3F public-export inventory.
+It mounts one DOM root under an explicit target and preserves that root while
+the target moves. It is not Drei `Html`, is not the WebXR DOM Overlay API, and
+defines no positioning, occlusion, styling, or layout behavior.
+
 ## License provenance
 
 React Three Fiber is MIT-licensed, Copyright 2019–2025 Poimandres. Adapted

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "@octanejs/three",
-  "version": "0.1.0",
+  "version": "0.1.3",
   "license": "MIT",
   "type": "module",
+  "sideEffects": false,
   "engines": {
     "node": ">=22"
   },
@@ -45,18 +46,24 @@
     "./intrinsics/jsx-runtime": "./src/intrinsics.ts"
   },
   "dependencies": {
-    "@types/three": "0.172.0",
     "zustand": "^5.0.0"
   },
   "peerDependencies": {
-    "three": ">=0.172.0 <0.173.0",
-    "octane": "0.1.7"
+    "@types/three": ">=0.156.0",
+    "three": ">=0.156.0",
+    "octane": "0.1.10"
+  },
+  "peerDependenciesMeta": {
+    "@types/three": {
+      "optional": true
+    }
   },
   "devDependencies": {
     "@react-three/fiber": "9.6.1",
     "@rsbuild/core": "^2.1.5",
     "@rspack/core": "^2.1.3",
     "@tsrx/react": "^0.2.37",
+    "@types/three": "0.172.0",
     "esbuild": "^0.28.1",
     "playwright": "^1.61.0",
     "react": "^19.2.0",
@@ -65,13 +72,14 @@
     "typescript": "^5.9.3",
     "vite": "^8.0.16",
     "vitest": "^4.1.9",
-    "@octanejs/rsbuild-plugin": "0.1.2",
-    "@octanejs/rspack-plugin": "0.1.2",
-    "octane": "0.1.7",
-    "@octanejs/vite-plugin": "0.1.7"
+    "@octanejs/rsbuild-plugin": "0.1.5",
+    "@octanejs/rspack-plugin": "0.1.5",
+    "@octanejs/vite-plugin": "0.1.10",
+    "octane": "0.1.10"
   },
   "scripts": {
     "test": "pnpm upstream:check && vitest run --root ../.. --project three",
+    "test:compat": "pnpm upstream:check && vitest run --root ../.. --project three --exclude 'packages/three/tests/**/*differential.test.ts' --exclude 'packages/three/tests/browser/**/*.test.ts'",
     "upstream:check": "node scripts/check-upstream-crosswalk.mjs"
   }
 }

package/src/config.ts

@@ -35,6 +35,11 @@ export const threeRendererBoundaries = {
 			prop: 'children',
 			server: 'omit-child',
 		},
+		DOMRegion: {
+			ownerRenderer: THREE_RENDERER_ID,
+			childRenderer: 'dom',
+			prop: 'children',
+		},
 	},
 } as const;
 

package/src/core/catalogue.ts

@@ -41,6 +41,10 @@ type ArgsProp<T extends ConstructorRepresentation> =
 export type ThreeAttachFunction<T = unknown> = (parent: unknown, self: T) => void | (() => void);
 
 export type Attach<T = unknown> = string | ThreeAttachFunction<T>;
+/** R3F-compatible name for a function attachment, adapted to Octane cleanup callbacks. */
+export type AttachFnType<T = unknown> = ThreeAttachFunction<T>;
+/** R3F-compatible name for the public attachment union. */
+export type AttachType<T = unknown> = Attach<T>;
 export type ThreeKey = string | number | symbol | bigint;
 
 export type ThreeRef<T> =
@@ -100,15 +104,40 @@ export type MathType<T extends MathTypes> = T extends THREE.Color
 		? T | MutableOrReadonlyParameters<T['set']> | number
 		: T | MutableOrReadonlyParameters<T['set']>;
 
-type MathProps<T> = {
+export type MathProps<T> = {
 	[K in keyof T as T[K] extends MathTypes ? K : never]: T[K] extends MathTypes
 		? MathType<T[K]>
 		: never;
 };
 
+export type Vector2 = MathType<THREE.Vector2>;
+export type Vector3 = MathType<THREE.Vector3>;
+export type Vector4 = MathType<THREE.Vector4>;
+export type Color = MathType<THREE.Color>;
+export type Layers = MathType<THREE.Layers>;
+export type Quaternion = MathType<THREE.Quaternion>;
+export type Euler = MathType<THREE.Euler>;
+export type Matrix3 = MathType<THREE.Matrix3>;
+export type Matrix4 = MathType<THREE.Matrix4>;
+
+/**
+ * R3F-compatible authored-node props with Octane refs and renderable children.
+ * The historical name is retained for source compatibility without importing
+ * React or exposing React ownership semantics.
+ */
+export interface ReactProps<T> {
+	children?: unknown;
+	ref?: ThreeRef<T>;
+	key?: ThreeKey;
+}
+
+export type ElementProps<T extends ConstructorRepresentation, P = InstanceType<T>> = Partial<
+	Overwrite<P, MathProps<P> & ReactProps<P> & EventProps<P>>
+>;
+
 export type ThreeElement<T extends ConstructorRepresentation> = Mutable<
 	Overwrite<
-		Partial<Overwrite<Properties<InstanceType<T>>, MathProps<InstanceType<T>>>>,
+		ElementProps<T, Properties<InstanceType<T>>>,
 		ArgsProp<T> & ThreeInstanceProps<InstanceType<T>> & EventProps<InstanceType<T>>
 	>
 >;