@octanejs/three 0.1.0 → 0.1.3

package/src/core/portal.ts

@@ -25,10 +25,13 @@ import {
 import type { ComputeFunction, EventManager } from './events.js';
 import {
 	createPortalStore,
+	readRootStoreRenderSnapshot,
 	RootStoreContext,
+	RootStoreRenderSnapshotContext,
 	updateCamera,
 	type RootState,
 	type RootStore,
+	type RootStoreRenderSnapshot,
 	type Size,
 } from './store.js';
 
@@ -49,24 +52,56 @@ interface PortalProps {
 	readonly state?: InjectState;
 }
 
-interface PortalOptions {
-	readonly events: InjectState['events'];
-	readonly size: Partial<Size> | undefined;
+interface PortalPlan {
+	readonly parent: RootState;
+	readonly inject: InjectState;
+	readonly state: RootState;
+	readonly view: RootStoreRenderSnapshot;
+	readonly injectedKeys: ReadonlySet<string>;
+	readonly injectedEventKeys: ReadonlySet<string>;
 }
 
 interface PortalLayer {
 	readonly store: RootStore;
 	readonly target: ThreePortalTargetBinding;
-	readonly sync: (parent: RootState, options: PortalOptions) => void;
-	readonly commitCamera: (parent: RootState, options: PortalOptions) => void;
+	readonly stage: (parent: RootState, state: InjectState) => PortalPlan;
+	readonly commit: (plan: PortalPlan) => void;
 }
 
-const PORTAL_OPTIONS = Symbol('octane.three.portal.options');
-const PORTAL_OPTIONS_COMMIT = Symbol('octane.three.portal.options-commit');
+const EMPTY_INJECT_STATE = Object.freeze({}) as InjectState;
+const PORTAL_STATE = Symbol('octane.three.portal.state');
+const PORTAL_STATE_COMMIT = Symbol('octane.three.portal.state-commit');
 const PORTAL_LAYER = Symbol('octane.three.portal.layer');
-const PORTAL_CAMERA_COMMIT = Symbol('octane.three.portal.camera-commit');
 const PORTAL_SUBSCRIPTION = Symbol('octane.three.portal.subscription');
 
+function shallowEqual(left: object, right: object): boolean {
+	const leftKeys = Object.keys(left);
+	const rightKeys = Object.keys(right);
+	if (leftKeys.length !== rightKeys.length) return false;
+	return leftKeys.every(
+		(key) =>
+			Object.prototype.hasOwnProperty.call(right, key) &&
+			Object.is((left as Record<string, unknown>)[key], (right as Record<string, unknown>)[key]),
+	);
+}
+
+function reuseShallow<T extends object>(previous: T, next: T): T {
+	return shallowEqual(previous, next) ? previous : next;
+}
+
+function resetRemovedKeys(
+	target: Record<string, unknown>,
+	previousKeys: ReadonlySet<string>,
+	next: Readonly<Record<string, unknown>>,
+	fallback: Readonly<Record<string, unknown>>,
+): void {
+	for (const key of previousKeys) {
+		if (Object.prototype.hasOwnProperty.call(next, key)) continue;
+		if (Object.prototype.hasOwnProperty.call(fallback, key)) target[key] = fallback[key];
+		else delete target[key];
+	}
+}
+
 function getWorldMatrixSnapshot(object: THREE.Object3D): THREE.Matrix4 {
 	if (object.matrixWorldAutoUpdate === false) return object.matrixWorld.clone();
 	const local = object.matrixAutoUpdate
@@ -98,82 +133,154 @@ function snapshotCamera<T extends THREE.Camera>(camera: T): T {
 function createLayer(
 	previousRoot: RootStore,
 	container: THREE.Object3D,
+	parentState: RootState,
 	state: InjectState,
-	options: PortalOptions,
 ): PortalLayer {
-	const { events: _events, size: _size, ...rest } = state;
+	const { events: _events, size: _size, ...initialRest } = state;
 	const raycaster = new THREE.Raycaster();
 	const pointer = new THREE.Vector2();
 	const target = createThreePortalTargetBinding(container);
 	const store = createPortalStore({
-		...previousRoot.getState(),
-		...rest,
+		...parentState,
+		...initialRest,
 		// A managed portal target may be reconstructed without changing the
 		// authored target handle. The driver advances the shared binding to the
 		// accepted replacement, and subsequent parent-state mirrors retain it.
 		scene: target.current as THREE.Scene,
 	} as RootState);
-
-	const sync = (parent: RootState, currentOptions: PortalOptions) => {
+	let injectedKeys = new Set<string>();
+	let injectedEventKeys = new Set<string>();
+	let cameraCommit:
+		| {
+				readonly camera: RootState['camera'];
+				readonly width: number;
+				readonly height: number;
+				readonly manual: boolean | undefined;
+		  }
+		| undefined;
+	const setEvents = (events: Partial<EventManager<any>>) => {
 		store.setState((local) => {
-			let viewport: Partial<RootState['viewport']> | undefined;
-			if (local.camera != null && currentOptions.size !== undefined) {
-				const size = {
-					...parent.size,
-					...currentOptions.size,
-				} as Size;
-				viewport = parent.viewport.getCurrentViewport(
-					snapshotCamera(local.camera),
-					new THREE.Vector3(),
-					size,
-				);
-			}
-			return {
-				...parent,
-				...local,
-				scene: target.current as THREE.Scene,
-				raycaster,
-				pointer,
-				mouse: pointer,
-				previousRoot,
-				events: {
-					...parent.events,
-					...local.events,
-					...currentOptions.events,
-				} as EventManager<any>,
-				size: {
-					...parent.size,
-					...currentOptions.size,
-				},
-				viewport: {
-					...parent.viewport,
-					...viewport,
-				},
-				setEvents(events: Partial<EventManager<any>>) {
-					store.setState((value) => ({
-						events: { ...value.events, ...events },
-					}));
-				},
-			};
+			const next = { ...local.events, ...events } as EventManager<any>;
+			return shallowEqual(local.events, next) ? local : { events: next };
 		});
 	};
-	const commitCamera = (parent: RootState, currentOptions: PortalOptions) => {
+
+	const stage = (parent: RootState, currentState: InjectState): PortalPlan => {
+		const { events, size, ...rest } = currentState;
+		const nextInjectedKeys = new Set(Object.keys(rest));
+		const nextInjectedEventKeys = new Set(Object.keys(events ?? {}));
 		const local = store.getState();
+		const inherited = { ...parent, ...local } as RootState & Record<string, unknown>;
+		resetRemovedKeys(
+			inherited,
+			injectedKeys,
+			rest as Readonly<Record<string, unknown>>,
+			parent as unknown as Readonly<Record<string, unknown>>,
+		);
+		Object.assign(inherited, rest);
+
+		const localEvents = { ...local.events } as Record<string, unknown>;
+		resetRemovedKeys(
+			localEvents,
+			injectedEventKeys,
+			(events ?? {}) as Readonly<Record<string, unknown>>,
+			parent.events as unknown as Readonly<Record<string, unknown>>,
+		);
+		const nextEvents = reuseShallow(local.events, {
+			...parent.events,
+			...localEvents,
+			...events,
+		} as EventManager<any>);
+		const nextSize = reuseShallow(local.size, { ...parent.size, ...size } as Size);
+		let viewport: Partial<RootState['viewport']> | undefined;
+		if (inherited.camera != null && size !== undefined) {
+			viewport = parent.viewport.getCurrentViewport(
+				snapshotCamera(inherited.camera),
+				new THREE.Vector3(),
+				nextSize,
+			);
+		}
+		const nextViewport = reuseShallow(local.viewport, {
+			...parent.viewport,
+			...viewport,
+		});
+		const candidate = {
+			...inherited,
+			set: local.set,
+			get: local.get,
+			scene: target.current as THREE.Scene,
+			raycaster,
+			pointer,
+			mouse: pointer,
+			previousRoot,
+			events: nextEvents,
+			size: nextSize,
+			viewport: nextViewport,
+			setEvents,
+		} as RootState;
+		const next = shallowEqual(local, candidate) ? local : candidate;
+		return {
+			parent,
+			inject: currentState,
+			state: next,
+			view: { store, current: next },
+			injectedKeys: nextInjectedKeys,
+			injectedEventKeys: nextInjectedEventKeys,
+		};
+	};
+	const commitCamera = (plan: PortalPlan) => {
+		const camera = plan.state.camera;
+		if (camera == null || plan.inject.size === undefined || camera === plan.parent.camera) {
+			cameraCommit = undefined;
+			return;
+		}
+		const size = {
+			...plan.parent.size,
+			...plan.inject.size,
+		} as Size;
 		if (
-			local.camera == null ||
-			currentOptions.size === undefined ||
-			local.camera === parent.camera
+			cameraCommit?.camera === camera &&
+			cameraCommit.width === size.width &&
+			cameraCommit.height === size.height &&
+			cameraCommit.manual === camera.manual
 		) {
 			return;
 		}
-		updateCamera(local.camera, {
-			...parent.size,
-			...currentOptions.size,
-		} as Size);
+		updateCamera(camera, size);
+		cameraCommit = {
+			camera,
+			width: size.width,
+			height: size.height,
+			manual: camera.manual,
+		};
+	};
+	const commit = (plan: PortalPlan) => {
+		try {
+			// The driver advances the binding during the accepted host commit.
+			// The staged state is attempt-owned, so reasserting that target here
+			// cannot leak through a render that preparation rejects.
+			plan.state.scene = target.current as THREE.Scene;
+			commitCamera(plan);
+			if (store.getState() !== plan.state) store.setState(plan.state, true);
+			injectedKeys = new Set(plan.injectedKeys);
+			injectedEventKeys = new Set(plan.injectedEventKeys);
+		} finally {
+			plan.view.current = null;
+		}
 	};
 
-	sync(previousRoot.getState(), options);
-	return { store, target, sync, commitCamera };
+	// A new layer has no previously accepted state that can be exposed. Seed its
+	// private store during construction so imperative `useStore().getState()`
+	// reads are complete even before the first accepted insertion commit. Camera
+	// mutations remain deferred until acceptance.
+	const initialPlan = stage(parentState, state);
+	initialPlan.state.scene = target.current as THREE.Scene;
+	store.setState(initialPlan.state, true);
+	injectedKeys = new Set(initialPlan.injectedKeys);
+	injectedEventKeys = new Set(initialPlan.injectedEventKeys);
+	initialPlan.view.current = null;
+
+	return { store, target, stage, commit };
 }
 
 const Portal = defineUniversalComponent<PortalProps>('three', (props) => {
@@ -186,32 +293,28 @@ const Portal = defineUniversalComponent<PortalProps>('three', (props) => {
 	if (activeStore === null) {
 		throw new Error('R3F: createPortal can only be used within the Canvas component!');
 	}
-	const options = { events: props.state?.events, size: props.state?.size };
-	const optionsRef = useRef<PortalOptions>(options, PORTAL_OPTIONS);
-	useInsertionEffect(
-		() => {
-			optionsRef.current = options;
-		},
-		[options.events, options.size],
-		PORTAL_OPTIONS_COMMIT,
-	);
+	const parentView = useContext(RootStoreRenderSnapshotContext);
+	const parentState = readRootStoreRenderSnapshot(activeStore, parentView);
+	const state = props.state ?? EMPTY_INJECT_STATE;
+	const stateRef = useRef<InjectState>(state, PORTAL_STATE);
 	const layer = useMemo(
-		() => createLayer(activeStore, props.container, props.state ?? {}, options),
+		() => createLayer(activeStore, props.container, parentState, state),
 		[activeStore, props.container],
 		PORTAL_LAYER,
 	);
+	const plan = layer.stage(parentState, state);
 	useInsertionEffect(
 		() => {
-			layer.commitCamera(activeStore.getState(), optionsRef.current);
+			layer.commit(plan);
+			stateRef.current = state;
 		},
-		[activeStore, layer],
-		PORTAL_CAMERA_COMMIT,
+		null,
+		PORTAL_STATE_COMMIT,
 	);
 	useLayoutEffect(
 		() => {
-			return activeStore.subscribe((state) => {
-				layer.sync(state, optionsRef.current);
-				layer.commitCamera(state, optionsRef.current);
+			return activeStore.subscribe((parent) => {
+				layer.commit(layer.stage(parent, stateRef.current));
 			});
 		},
 		[activeStore, layer],
@@ -219,9 +322,11 @@ const Portal = defineUniversalComponent<PortalProps>('three', (props) => {
 	);
 
 	return universalContext(RootStoreContext, layer.store, () =>
-		createUniversalPortal(
-			props.children,
-			createThreePortalTarget(props.container, layer.store, layer.target),
+		universalContext(RootStoreRenderSnapshotContext, plan.view, () =>
+			createUniversalPortal(
+				props.children,
+				createThreePortalTarget(props.container, layer.store, layer.target),
+			),
 		),
 	);
 });

package/src/core/root.ts

@@ -38,6 +38,7 @@ import {
 	type RootState,
 	type RootStore,
 	type Size,
+	type XRManager,
 } from './store.js';
 import { createUniversalRoot } from 'octane/universal';
 
@@ -132,6 +133,10 @@ interface ThreeRootInternals<TCanvas extends CanvasLike> {
 	pendingRender: PendingRender | null;
 	lastConfiguredCamera?: CameraProps;
 	onCreated?: (state: RootState) => void;
+	contextLifecycleInitialized: boolean;
+	contextLifecycleCleanup: (() => void) | null;
+	xrInitialized: boolean;
+	xrManager: XRManager | null;
 }
 
 interface RootRecord<TCanvas extends CanvasLike = CanvasLike> {
@@ -204,6 +209,147 @@ function disposeRenderer(renderer: Renderer | null | undefined): void {
 	}
 }
 
+interface ContextLifecycleTarget {
+	addEventListener(type: string, listener: (event: Event) => void): void;
+	removeEventListener(type: string, listener: (event: Event) => void): void;
+}
+
+function isContextLifecycleTarget(value: unknown): value is ContextLifecycleTarget {
+	const target = value as Partial<ContextLifecycleTarget> | null;
+	return (
+		target !== null &&
+		typeof target === 'object' &&
+		typeof target.addEventListener === 'function' &&
+		typeof target.removeEventListener === 'function'
+	);
+}
+
+function initializeContextLifecycle(internals: ThreeRootInternals<any>, renderer: Renderer): void {
+	if (internals.contextLifecycleInitialized) return;
+	const target = isContextLifecycleTarget(renderer.domElement)
+		? renderer.domElement
+		: isContextLifecycleTarget(internals.canvas)
+			? internals.canvas
+			: null;
+	if (target === null) {
+		internals.contextLifecycleInitialized = true;
+		return;
+	}
+
+	const handleContextLoss = (event: Event) => {
+		event.preventDefault();
+	};
+	const handleContextRestore = () => {
+		if (!internals.disposed) internals.store.getState().invalidate();
+	};
+	target.addEventListener('webglcontextlost', handleContextLoss);
+	try {
+		target.addEventListener('webglcontextrestored', handleContextRestore);
+	} catch (error) {
+		target.removeEventListener('webglcontextlost', handleContextLoss);
+		throw error;
+	}
+	internals.contextLifecycleCleanup = () => {
+		try {
+			target.removeEventListener('webglcontextlost', handleContextLoss);
+		} finally {
+			target.removeEventListener('webglcontextrestored', handleContextRestore);
+		}
+	};
+	internals.contextLifecycleInitialized = true;
+}
+
+function createXRManager(internals: ThreeRootInternals<any>, renderer: Renderer): XRManager {
+	let connected = false;
+	let frameCallback: ((timestamp: number, frame?: XRFrame) => void) | null = null;
+
+	const handleSessionChange = () => {
+		if (!connected || internals.disposed) return;
+		const xr = renderer.xr;
+		if (xr === undefined) return;
+		const presenting = xr.isPresenting === true;
+		xr.enabled = presenting;
+		if (presenting) {
+			if (frameCallback === null) {
+				let currentFrame!: (timestamp: number, frame?: XRFrame) => void;
+				currentFrame = (timestamp, frame) => {
+					if (!connected || internals.disposed || frameCallback !== currentFrame) {
+						return;
+					}
+					const state = internals.store.getState();
+					if (state.frameloop !== 'never') advance(timestamp, true, state, frame);
+				};
+				frameCallback = currentFrame;
+			}
+			xr.setAnimationLoop?.(frameCallback);
+		} else {
+			frameCallback = null;
+			xr.setAnimationLoop?.(null);
+			internals.store.getState().invalidate();
+		}
+	};
+
+	return {
+		connect() {
+			if (connected || internals.disposed) return;
+			const xr = renderer.xr;
+			if (
+				xr === undefined ||
+				typeof xr.addEventListener !== 'function' ||
+				typeof xr.removeEventListener !== 'function'
+			) {
+				return;
+			}
+			xr.addEventListener('sessionstart', handleSessionChange);
+			try {
+				xr.addEventListener('sessionend', handleSessionChange);
+			} catch (error) {
+				xr.removeEventListener('sessionstart', handleSessionChange);
+				throw error;
+			}
+			connected = true;
+		},
+		disconnect() {
+			const xr = renderer.xr;
+			const wasConnected = connected;
+			connected = false;
+			frameCallback = null;
+			if (xr === undefined) return;
+			try {
+				if (wasConnected && typeof xr.removeEventListener === 'function') {
+					xr.removeEventListener('sessionstart', handleSessionChange);
+				}
+			} finally {
+				try {
+					if (wasConnected && typeof xr.removeEventListener === 'function') {
+						xr.removeEventListener('sessionend', handleSessionChange);
+					}
+				} finally {
+					try {
+						xr.setAnimationLoop?.(null);
+					} finally {
+						xr.enabled = false;
+					}
+				}
+			}
+		},
+	};
+}
+
+function initializeXR(internals: ThreeRootInternals<any>, renderer: Renderer): void {
+	if (internals.xrInitialized) return;
+	const xr = createXRManager(internals, renderer);
+	xr.connect();
+	try {
+		internals.store.setState({ xr });
+	} catch (error) {
+		xr.disconnect();
+		throw error;
+	}
+	internals.xrManager = xr;
+	internals.xrInitialized = true;
+}
+
 function computeInitialSize(canvas: CanvasLike, size?: RenderProps<any>['size']): Size {
 	if (size !== undefined) {
 		return { width: size.width, height: size.height, top: size.top ?? 0, left: size.left ?? 0 };
@@ -246,9 +392,12 @@ function applyRaycasterOptions(
 			...raycaster.params,
 			...params,
 			Mesh: { ...raycaster.params.Mesh, ...params.Mesh },
-			Line: { ...raycaster.params.Line, ...params.Line },
+			Line: { ...raycaster.params.Line, ...params.Line } as THREE.Raycaster['params']['Line'],
 			LOD: { ...raycaster.params.LOD, ...params.LOD },
-			Points: { ...raycaster.params.Points, ...params.Points },
+			Points: {
+				...raycaster.params.Points,
+				...params.Points,
+			} as THREE.Raycaster['params']['Points'],
 			Sprite: { ...raycaster.params.Sprite, ...params.Sprite },
 		};
 	}
@@ -402,6 +551,8 @@ async function applyConfiguration<TCanvas extends CanvasLike>(
 	} = props;
 	const renderer = await ensureRenderer(internals, glConfig, generation);
 	if (renderer === null || internals.disposed || internals.generation !== generation) return;
+	initializeContextLifecycle(internals, renderer);
+	initializeXR(internals, renderer);
 
 	let state = internals.store.getState();
 	if (state.raycaster == null) internals.store.setState({ raycaster: new THREE.Raycaster() });
@@ -579,14 +730,23 @@ export function createRoot<TCanvas extends CanvasLike>(canvas: TCanvas): ThreeRo
 				try {
 					internals.hostRoot?.unmount();
 				} finally {
-					internals.container?.flushDisposals();
 					try {
-						state.xr.disconnect();
+						internals.container?.flushDisposals();
 					} finally {
-						disposeRenderer(state.gl);
-						destroyRootStore(store);
-						roots.delete(canvas);
-						rootInternals.delete(controller);
+						try {
+							internals.contextLifecycleCleanup?.();
+						} finally {
+							internals.contextLifecycleCleanup = null;
+							try {
+								internals.xrManager?.disconnect();
+							} finally {
+								internals.xrManager = null;
+								disposeRenderer(state.gl);
+								destroyRootStore(store);
+								roots.delete(canvas);
+								rootInternals.delete(controller);
+							}
+						}
 					}
 				}
 			}
@@ -610,6 +770,10 @@ export function createRoot<TCanvas extends CanvasLike>(canvas: TCanvas): ThreeRo
 		generation: 0,
 		pendingRender: null,
 		lastConfiguredCamera: undefined,
+		contextLifecycleInitialized: false,
+		contextLifecycleCleanup: null,
+		xrInitialized: false,
+		xrManager: null,
 	};
 	rootInternals.set(controller, internals);
 	roots.set(canvas, { store, root: controller });
@@ -617,8 +781,14 @@ export function createRoot<TCanvas extends CanvasLike>(canvas: TCanvas): ThreeRo
 	return controller;
 }
 
-export function unmountComponentAtNode<TCanvas extends CanvasLike>(canvas: TCanvas): void {
-	roots.get(canvas)?.root.unmount();
+export function unmountComponentAtNode<TCanvas extends CanvasLike>(
+	canvas: TCanvas,
+	callback?: (canvas: TCanvas) => void,
+): void {
+	const record = roots.get(canvas);
+	if (record === undefined) return;
+	record.root.unmount();
+	callback?.(canvas);
 }
 
 export interface ThreeBoundaryMount {

package/src/core/store.ts

@@ -6,7 +6,13 @@
  * components. Zustand remains the framework-neutral storage primitive.
  */
 import * as THREE from 'three';
-import { createContext, useRef, useSyncExternalStore, withSlot } from 'octane/universal';
+import {
+	createContext,
+	useContext,
+	useRef,
+	useSyncExternalStore,
+	withSlot,
+} from 'octane/universal';
 import { createStore as createVanillaStore, type StoreApi } from 'zustand/vanilla';
 import type {
 	DomEvent,
@@ -453,6 +459,31 @@ interface SelectionCell<T> {
 	value: T;
 }
 
+/**
+ * Render-attempt-local state exposed by a portal without mutating its live
+ * store. An accepted portal commit clears `current`, after which consumers
+ * resume reading the store itself.
+ *
+ * This is package-private plumbing for the Three renderer. It is exported from
+ * this module so the portal and hook implementations can share it, but it is
+ * intentionally absent from the package's public barrel.
+ */
+export interface RootStoreRenderSnapshot {
+	readonly store: RootStore;
+	current: RootState | null;
+}
+
+export const RootStoreRenderSnapshotContext = createContext<RootStoreRenderSnapshot | null>(null);
+
+export function readRootStoreRenderSnapshot(
+	store: RootStore,
+	snapshot: RootStoreRenderSnapshot | null,
+): RootState {
+	return snapshot?.store === store && snapshot.current !== null
+		? snapshot.current
+		: store.getState();
+}
+
 /** Universal-hook selector used by the callable store and `useThree`. */
 export function useRootStoreSelector<T>(
 	store: RootStore,
@@ -460,12 +491,13 @@ export function useRootStoreSelector<T>(
 	equalityFn: (previous: T, next: T) => boolean = Object.is,
 	slot?: unknown,
 ): T {
+	const renderSnapshot = useContext(RootStoreRenderSnapshotContext);
 	const run = (nested: boolean): T => {
 		const cell = nested
 			? useRef<SelectionCell<T>>({ initialized: false, value: undefined as T }, 'selection')
 			: useRef<SelectionCell<T>>({ initialized: false, value: undefined as T });
 		const snapshot = () => {
-			const next = selector(store.getState());
+			const next = selector(readRootStoreRenderSnapshot(store, renderSnapshot));
 			if (!cell.current.initialized || !equalityFn(cell.current.value, next)) {
 				cell.current = { initialized: true, value: next };
 			}