@octanejs/three 0.1.0

package/src/core/hooks.ts

@@ -0,0 +1,203 @@
+/**
+ * Canvas-scoped hooks and graph helpers for the Octane Three renderer.
+ *
+ * These hooks live in a plain TypeScript module which is intentionally excluded
+ * from Octane's hook transform. Compiled callers pass their call-site symbol as
+ * the final argument, so every composed universal hook receives a stable,
+ * distinct sub-slot derived from that symbol.
+ */
+import * as THREE from 'three';
+import {
+	useContext,
+	useLayoutEffect,
+	useMemo,
+	useRef,
+	useSyncExternalStore,
+} from 'octane/universal';
+import { getThreeEventStore, getThreeInstance, type Instance } from './driver.js';
+import {
+	getRootObjectStore,
+	RootStoreContext,
+	useRootStoreSelector,
+	type RenderCallback,
+	type RootState,
+	type RootStore,
+} from './store.js';
+
+export interface ObjectMap {
+	nodes: Record<string, THREE.Object3D>;
+	materials: Record<string, THREE.Material>;
+	meshes: Record<string, THREE.Mesh>;
+}
+
+export interface RefObject<T> {
+	current: T | null;
+}
+
+type EqualityFn<T> = (previous: T, next: T) => boolean;
+type Selector<T> = (state: RootState) => T;
+
+const subSlotCache = new Map<symbol, Map<string, symbol>>();
+
+function subSlot(slot: symbol | undefined, tag: string): symbol | undefined {
+	// Universal hooks allocate an owner-local implicit slot when an uncompiled
+	// caller provides no symbol. Preserve that fallback; a shared tag-only symbol
+	// would make two direct calls to the same composed hook collide.
+	if (slot === undefined) return undefined;
+	let byTag = subSlotCache.get(slot);
+	if (byTag === undefined) {
+		byTag = new Map();
+		subSlotCache.set(slot, byTag);
+	}
+	let result = byTag.get(tag);
+	if (result === undefined) {
+		result = Symbol.for(`${slot.description ?? ''}:@octanejs/three:${tag}`);
+		byTag.set(tag, result);
+	}
+	return result;
+}
+
+function splitSlot(args: readonly unknown[]): [readonly unknown[], symbol | undefined] {
+	const tail = args.at(-1);
+	return typeof tail === 'symbol' ? [args.slice(0, -1), tail] : [args, undefined];
+}
+
+const identity = <T>(value: T): T => value;
+
+/** Returns the nearest store, or selects it through a compiler-visible hook call. */
+export function useStore(): RootStore;
+export function useStore<T>(selector: Selector<T>, equalityFn?: EqualityFn<T>): T;
+export function useStore<T = RootStore>(...args: unknown[]): T {
+	const [userArgs, slot] = splitSlot(args);
+	const store = useContext(RootStoreContext);
+	if (store === null) {
+		throw new Error('R3F: Hooks can only be used within the Canvas component!');
+	}
+	if (typeof userArgs[0] !== 'function') return store as T;
+	const selector = userArgs[0] as Selector<T>;
+	const equalityFn = (typeof userArgs[1] === 'function' ? userArgs[1] : Object.is) as EqualityFn<T>;
+	return useRootStoreSelector(store, selector, equalityFn, slot);
+}
+
+/** Selects reactive state from the nearest Three Canvas/root. */
+export function useThree<T = RootState>(selector?: Selector<T>, equalityFn?: EqualityFn<T>): T;
+export function useThree<T = RootState>(...args: unknown[]): T {
+	const [userArgs, slot] = splitSlot(args);
+	const selector = (typeof userArgs[0] === 'function' ? userArgs[0] : identity) as Selector<T>;
+	const equalityFn = (typeof userArgs[1] === 'function' ? userArgs[1] : Object.is) as EqualityFn<T>;
+	const store = useStore();
+	const cache = useRef<
+		| {
+				readonly state: RootState;
+				readonly selector: Selector<T>;
+				readonly selection: T;
+		  }
+		| undefined
+	>(undefined, subSlot(slot, 'useThree:cache'));
+
+	const getSnapshot = (): T => {
+		const state = store.getState();
+		const previous = cache.current;
+		if (
+			previous !== undefined &&
+			previous.selector === selector &&
+			Object.is(previous.state, state)
+		) {
+			return previous.selection;
+		}
+		const selection = selector(state);
+		if (previous !== undefined && equalityFn(previous.selection, selection)) {
+			cache.current = { state, selector, selection: previous.selection };
+			return previous.selection;
+		}
+		cache.current = { state, selector, selection };
+		return selection;
+	};
+
+	return useSyncExternalStore(
+		store.subscribe,
+		getSnapshot,
+		getSnapshot,
+		subSlot(slot, 'useThree:store'),
+	);
+}
+
+/** Runs a callback before a root renders a frame. */
+export function useFrame(callback: RenderCallback, renderPriority?: number): null;
+export function useFrame(callback: RenderCallback, ...args: unknown[]): null {
+	const [userArgs, slot] = splitSlot(args);
+	const renderPriority = typeof userArgs[0] === 'number' ? userArgs[0] : 0;
+	const store = useStore();
+	const callbackRef = useRef(callback, subSlot(slot, 'useFrame:callback'));
+
+	useLayoutEffect(
+		() => {
+			callbackRef.current = callback;
+		},
+		[callback],
+		subSlot(slot, 'useFrame:latest'),
+	);
+
+	const subscribe = store.getState().internal.subscribe;
+	useLayoutEffect(
+		() => subscribe(callbackRef, renderPriority, store),
+		[renderPriority, store, subscribe],
+		subSlot(slot, 'useFrame:subscribe'),
+	);
+	return null;
+}
+
+/** Collects named objects, meshes, and materials from a Three object graph. */
+export function buildGraph(object: THREE.Object3D): ObjectMap {
+	const graph: ObjectMap = { nodes: {}, materials: {}, meshes: {} };
+	object?.traverse((node) => {
+		if (node.name !== '') graph.nodes[node.name] = node;
+		const mesh = node as THREE.Mesh;
+		const material = mesh.material;
+		if (
+			material !== undefined &&
+			!Array.isArray(material) &&
+			material.name !== '' &&
+			graph.materials[material.name] === undefined
+		) {
+			graph.materials[material.name] = material;
+		}
+		if (mesh.isMesh === true && node.name !== '' && graph.meshes[node.name] === undefined) {
+			graph.meshes[node.name] = mesh;
+		}
+	});
+	return graph;
+}
+
+/** Memoizes the named graph for one Three object. */
+export function useGraph(object: THREE.Object3D): ObjectMap;
+export function useGraph(object: THREE.Object3D, slot?: symbol): ObjectMap {
+	return useMemo(() => buildGraph(object), [object], subSlot(slot, 'useGraph'));
+}
+
+/** Returns the root state which owns a managed Three object. */
+export function getRootState<T extends THREE.Object3D = THREE.Object3D>(
+	object: T,
+): RootState | undefined {
+	return (getThreeEventStore(object) ?? getRootObjectStore(object))?.getState();
+}
+
+/** Exposes the stable public instance descriptor behind a managed Three ref. */
+export function useInstanceHandle<T extends object>(ref: RefObject<T>): RefObject<Instance<T>>;
+export function useInstanceHandle<T extends object>(
+	ref: RefObject<T>,
+	slot?: symbol,
+): RefObject<Instance<T>> {
+	const handle = useRef<Instance<T> | null>(null, subSlot(slot, 'useInstanceHandle:ref'));
+	useLayoutEffect(
+		() => {
+			handle.current = ref.current === null ? null : getThreeInstance(ref.current);
+			return () => {
+				handle.current = null;
+			};
+		},
+		[ref],
+		subSlot(slot, 'useInstanceHandle:layout'),
+	);
+	return handle;
+}

package/src/core/index.ts

@@ -0,0 +1,86 @@
+export { extend } from './catalogue.js';
+export { applyProps } from './driver.js';
+export {
+	buildGraph,
+	getRootState,
+	useFrame,
+	useGraph,
+	useInstanceHandle,
+	useStore,
+	useThree,
+} from './hooks.js';
+export { useLoader } from './loader.js';
+export { createPortal } from './portal.js';
+export { dispose } from './props.js';
+export {
+	addAfterEffect,
+	addEffect,
+	addTail,
+	advance,
+	flushGlobalEffects,
+	invalidate,
+} from './loop.js';
+export { createRoot, unmountComponentAtNode } from './root.js';
+export { RootStoreContext as context, calculateDpr } from './store.js';
+export { createEvents } from './events.js';
+export type {
+	Args,
+	Attach,
+	Catalogue,
+	ConstructorRepresentation,
+	EventProps,
+	InstanceProps,
+	MathRepresentation,
+	MathType,
+	MathTypes,
+	PrimitiveProps,
+	RaycastableRepresentation,
+	ThreeElement,
+	ThreeElements,
+	ThreeInstanceProps,
+	ThreeKey,
+	ThreeRef,
+	ThreeToElements,
+	ThreeToJSXElements,
+	VectorRepresentation,
+} from './catalogue.js';
+export type {
+	ComputeFunction,
+	DomEvent,
+	EventHandlers,
+	EventManager,
+	Events,
+	FilterFunction,
+	Intersection,
+	IntersectionEvent,
+	PointerCaptureTarget,
+	ThreeEvent,
+} from './events.js';
+export type { Instance } from './driver.js';
+export type { ObjectMap, RefObject } from './hooks.js';
+export type { Extensions, LoaderResult } from './loader.js';
+export type { InjectState } from './portal.js';
+export type { GlobalEffectType, GlobalRenderCallback } from './loop.js';
+export type {
+	CameraProps,
+	CanvasLike,
+	DefaultGLProps,
+	GLProps,
+	RenderProps,
+	ThreeRoot,
+} from './root.js';
+export type {
+	Camera,
+	Dpr,
+	Frameloop,
+	InternalState,
+	Performance,
+	RenderCallback,
+	Renderer,
+	RootState,
+	RootStore,
+	Size,
+	Subscription,
+	Viewport,
+	XRManager,
+} from './store.js';

package/src/core/loader.ts

@@ -0,0 +1,210 @@
+/**
+ * Suspense-aware Three loader cache.
+ *
+ * The cache key deliberately mirrors React Three Fiber: the loader identity and
+ * each normalized input participate in the key, while extensions and progress
+ * callbacks configure only the first request for that key.
+ */
+import * as THREE from 'three';
+import { use } from 'octane/universal';
+import { buildGraph, type ObjectMap } from './hooks.js';
+
+type InputLike = string | string[] | string[][] | Readonly<string | string[] | string[][]>;
+type LoaderLike = THREE.Loader<any, InputLike>;
+type LoaderConstructor = new (...args: any[]) => LoaderLike;
+type LoaderSource = LoaderLike | LoaderConstructor;
+type LoaderInstance<T extends LoaderSource> = T extends LoaderConstructor ? InstanceType<T> : T;
+type GLTFLike = { scene: THREE.Object3D };
+
+/** The resolved value produced by a loader, augmented for GLTF-shaped results. */
+export type LoaderResult<T extends LoaderSource> =
+	Awaited<ReturnType<LoaderInstance<T>['loadAsync']>> extends infer Result
+		? Result extends GLTFLike
+			? Result & ObjectMap
+			: Result
+		: never;
+
+/** Configures the concrete loader instance used for a request. */
+export type Extensions<T extends LoaderSource> = (loader: LoaderInstance<T>) => void;
+
+type InputKey = string | readonly string[];
+
+interface TrackedLoaderPromise<T> extends Promise<T> {
+	status?: 'pending' | 'fulfilled' | 'rejected';
+	value?: T;
+	reason?: unknown;
+}
+
+interface LoaderCacheEntry {
+	readonly keys: readonly InputKey[];
+	readonly promise: TrackedLoaderPromise<unknown[]>;
+}
+
+const memoizedLoaders = new WeakMap<LoaderConstructor, LoaderLike>();
+const loaderCache = new WeakMap<LoaderSource, LoaderCacheEntry[]>();
+
+function isConstructor(value: LoaderSource): value is LoaderConstructor {
+	return typeof value === 'function' && value.prototype?.constructor === value;
+}
+
+function inputKeyEquals(previous: InputKey, next: InputKey): boolean {
+	if (previous === next) return true;
+	if (!Array.isArray(previous) || !Array.isArray(next) || previous.length !== next.length) {
+		return false;
+	}
+	return previous.every((value, index) => value === next[index]);
+}
+
+function keysEqual(previous: readonly InputKey[], next: readonly InputKey[]): boolean {
+	return (
+		previous.length === next.length &&
+		previous.every((value, index) => inputKeyEquals(value, next[index]))
+	);
+}
+
+function normalizeInput(input: InputLike): InputKey[] {
+	return (Array.isArray(input) ? input : [input]) as InputKey[];
+}
+
+function resolveLoader(source: LoaderSource): LoaderLike {
+	if (!isConstructor(source)) return source;
+	let loader = memoizedLoaders.get(source);
+	if (loader === undefined) {
+		loader = new source();
+		memoizedLoaders.set(source, loader);
+	}
+	return loader;
+}
+
+function trackPromise<T>(promise: Promise<T>): TrackedLoaderPromise<T> {
+	const tracked = promise as TrackedLoaderPromise<T>;
+	tracked.status = 'pending';
+	promise.then(
+		(value) => {
+			tracked.status = 'fulfilled';
+			tracked.value = value;
+		},
+		(reason) => {
+			tracked.status = 'rejected';
+			tracked.reason = reason;
+		},
+	);
+	return tracked;
+}
+
+function loadInputs<L extends LoaderSource>(
+	source: L,
+	keys: readonly InputKey[],
+	extensions?: Extensions<L>,
+	onProgress?: (event: ProgressEvent<EventTarget>) => void,
+): TrackedLoaderPromise<unknown[]> {
+	const loader = resolveLoader(source) as LoaderInstance<L>;
+	extensions?.(loader);
+
+	const promise = Promise.all(
+		keys.map(
+			(input) =>
+				new Promise<unknown>((resolve, reject) => {
+					loader.load(
+						input as InputLike,
+						(data) => {
+							const scene = (data as { scene?: unknown } | null)?.scene;
+							if ((scene as THREE.Object3D | undefined)?.isObject3D === true) {
+								Object.assign(data as object, buildGraph(scene as THREE.Object3D));
+							}
+							resolve(data);
+						},
+						onProgress,
+						(error) => {
+							const message = (error as { message?: unknown } | null)?.message;
+							reject(new Error(`Could not load ${input}: ${message}`));
+						},
+					);
+				}),
+		),
+	);
+	return trackPromise(promise);
+}
+
+function getEntry<L extends LoaderSource>(
+	source: L,
+	keys: readonly InputKey[],
+	extensions?: Extensions<L>,
+	onProgress?: (event: ProgressEvent<EventTarget>) => void,
+): LoaderCacheEntry {
+	let entries = loaderCache.get(source);
+	const cached = entries?.find((entry) => keysEqual(entry.keys, keys));
+	if (cached !== undefined) return cached;
+
+	const entry: LoaderCacheEntry = {
+		keys: [...keys],
+		promise: loadInputs(source, keys, extensions, onProgress),
+	};
+	if (entries === undefined) {
+		entries = [];
+		loaderCache.set(source, entries);
+	}
+	entries.push(entry);
+	return entry;
+}
+
+function splitHookArguments(
+	args: readonly unknown[],
+): readonly [
+	Extensions<LoaderSource> | undefined,
+	((event: ProgressEvent<EventTarget>) => void) | undefined,
+] {
+	const userArgs = typeof args.at(-1) === 'symbol' ? args.slice(0, -1) : args;
+	return [
+		typeof userArgs[0] === 'function' ? (userArgs[0] as Extensions<LoaderSource>) : undefined,
+		typeof userArgs[1] === 'function'
+			? (userArgs[1] as (event: ProgressEvent<EventTarget>) => void)
+			: undefined,
+	];
+}
+
+interface UseLoader {
+	<I extends InputLike, L extends LoaderSource>(
+		loader: L,
+		input: I,
+		extensions?: Extensions<L>,
+		onProgress?: (event: ProgressEvent<EventTarget>) => void,
+	): I extends any[] ? LoaderResult<L>[] : LoaderResult<L>;
+	preload<I extends InputLike, L extends LoaderSource>(
+		loader: L,
+		input: I,
+		extensions?: Extensions<L>,
+	): void;
+	clear<I extends InputLike, L extends LoaderSource>(loader: L, input: I): void;
+}
+
+function useLoaderImplementation<L extends LoaderSource>(
+	loader: L,
+	input: InputLike,
+	...args: unknown[]
+): unknown {
+	const [extensions, onProgress] = splitHookArguments(args);
+	const keys = normalizeInput(input);
+	const results = use(
+		getEntry(loader, keys, extensions as Extensions<L> | undefined, onProgress).promise,
+	);
+	return Array.isArray(input) ? results : results[0];
+}
+
+/**
+ * Synchronously reads and caches assets loaded by a Three loader.
+ * The owning component must provide a Suspense boundary.
+ */
+export const useLoader = Object.assign(useLoaderImplementation, {
+	preload<L extends LoaderSource>(loader: L, input: InputLike, extensions?: Extensions<L>): void {
+		getEntry(loader, normalizeInput(input), extensions);
+	},
+	clear(loader: LoaderSource, input: InputLike): void {
+		const entries = loaderCache.get(loader);
+		if (entries === undefined) return;
+		const keys = normalizeInput(input);
+		const index = entries.findIndex((entry) => keysEqual(entry.keys, keys));
+		if (index !== -1) entries.splice(index, 1);
+		if (entries.length === 0) loaderCache.delete(loader);
+	},
+}) as UseLoader;

package/src/core/loop.ts

@@ -0,0 +1,210 @@
+import type { RenderCallback, RootState, RootStore, Subscription } from './store.js';
+
+export type GlobalRenderCallback = (timestamp: number) => void;
+export type GlobalEffectType = 'before' | 'after' | 'tail';
+
+interface GlobalSubscription {
+	callback: GlobalRenderCallback;
+}
+
+interface FrameRenderer {
+	render?: (scene: RootState['scene'], camera: RootState['camera']) => void;
+	xr?: { isPresenting?: boolean };
+}
+
+const roots = new Set<RootStore>();
+const globalEffects = new Set<GlobalSubscription>();
+const globalAfterEffects = new Set<GlobalSubscription>();
+const globalTailEffects = new Set<GlobalSubscription>();
+
+let running = false;
+let useFrameInProgress = false;
+
+function subscribeGlobal(
+	callback: GlobalRenderCallback,
+	subscriptions: Set<GlobalSubscription>,
+): () => void {
+	const subscription = { callback };
+	subscriptions.add(subscription);
+	return () => {
+		subscriptions.delete(subscription);
+	};
+}
+
+function runGlobalSubscriptions(subscriptions: Set<GlobalSubscription>, timestamp: number): void {
+	for (const subscription of subscriptions) {
+		subscription.callback(timestamp);
+	}
+}
+
+function getRenderer(state: RootState): FrameRenderer | undefined {
+	const compatibleState = state as RootState & {
+		gl?: FrameRenderer;
+		renderer?: FrameRenderer;
+	};
+	return compatibleState.gl ?? compatibleState.renderer;
+}
+
+function requestFrame(callback: FrameRequestCallback): number | null {
+	if (typeof globalThis.requestAnimationFrame !== 'function') return null;
+	return globalThis.requestAnimationFrame(callback);
+}
+
+function cancelFrame(frame: number): void {
+	if (typeof globalThis.cancelAnimationFrame === 'function') {
+		globalThis.cancelAnimationFrame(frame);
+	}
+}
+
+function update(timestamp: number, state: RootState, frame?: XRFrame): number {
+	let delta = state.clock.getDelta();
+
+	if (state.frameloop === 'never') {
+		delta = timestamp - state.clock.elapsedTime;
+		state.clock.oldTime = state.clock.elapsedTime;
+		state.clock.elapsedTime = timestamp;
+	}
+
+	const subscribers = state.internal.subscribers;
+	for (let index = 0; index < subscribers.length; index++) {
+		const subscription: Subscription = subscribers[index];
+		const callback: RenderCallback = subscription.ref.current;
+		callback(subscription.store.getState(), delta, frame);
+	}
+
+	const renderer = getRenderer(state);
+	if (state.internal.priority === 0 && renderer?.render) {
+		renderer.render(state.scene, state.camera);
+	}
+
+	state.internal.frames = Math.max(0, state.internal.frames - 1);
+	return state.frameloop === 'always' ? 1 : state.internal.frames;
+}
+
+/**
+ * Registers a configured root with the shared frame scheduler.
+ *
+ * This is an integration hook for the root implementation, not a public
+ * application API. Registering the same store more than once is idempotent.
+ */
+export function registerRootStore(store: RootStore): () => void {
+	roots.add(store);
+	return () => unregisterRootStore(store);
+}
+
+/** Removes a root from the shared frame scheduler. */
+export function unregisterRootStore(store: RootStore): void {
+	roots.delete(store);
+}
+
+/** Adds a callback that runs before active roots render each frame. */
+export function addEffect(callback: GlobalRenderCallback): () => void {
+	return subscribeGlobal(callback, globalEffects);
+}
+
+/** Adds a callback that runs after active roots render each frame. */
+export function addAfterEffect(callback: GlobalRenderCallback): () => void {
+	return subscribeGlobal(callback, globalAfterEffects);
+}
+
+/** Adds a callback that runs when the shared frame loop becomes idle. */
+export function addTail(callback: GlobalRenderCallback): () => void {
+	return subscribeGlobal(callback, globalTailEffects);
+}
+
+/** Runs one phase of the registered global frame callbacks. */
+export function flushGlobalEffects(type: GlobalEffectType, timestamp: number): void {
+	switch (type) {
+		case 'before':
+			runGlobalSubscriptions(globalEffects, timestamp);
+			break;
+		case 'after':
+			runGlobalSubscriptions(globalAfterEffects, timestamp);
+			break;
+		case 'tail':
+			runGlobalSubscriptions(globalTailEffects, timestamp);
+			break;
+	}
+}
+
+/** Runs one scheduled frame for every active registered root. */
+export function loop(timestamp: number): void {
+	const nextFrame = requestFrame(loop);
+	running = nextFrame !== null;
+	let repeat = 0;
+
+	flushGlobalEffects('before', timestamp);
+
+	useFrameInProgress = true;
+	try {
+		for (const store of roots) {
+			const state = store.getState();
+			const renderer = getRenderer(state);
+			if (
+				state.internal.active &&
+				(state.frameloop === 'always' || state.internal.frames > 0) &&
+				!renderer?.xr?.isPresenting
+			) {
+				repeat += update(timestamp, state);
+			}
+		}
+	} finally {
+		useFrameInProgress = false;
+	}
+
+	flushGlobalEffects('after', timestamp);
+
+	if (repeat === 0) {
+		flushGlobalEffects('tail', timestamp);
+		running = false;
+		if (nextFrame !== null) cancelFrame(nextFrame);
+	}
+}
+
+/**
+ * Requests a render from one root, or every registered root when state is
+ * omitted. Demand-mode requests coalesce into one shared animation frame.
+ */
+export function invalidate(state?: RootState, frames = 1): void {
+	if (state === undefined) {
+		for (const store of roots) invalidate(store.getState(), frames);
+		return;
+	}
+
+	const renderer = getRenderer(state);
+	if (renderer?.xr?.isPresenting || !state.internal.active || state.frameloop === 'never') {
+		return;
+	}
+
+	if (frames > 1) {
+		state.internal.frames = Math.min(60, state.internal.frames + frames);
+	} else {
+		state.internal.frames = useFrameInProgress ? 2 : 1;
+	}
+
+	if (!running) {
+		const frame = requestFrame(loop);
+		running = frame !== null;
+	}
+}
+
+/**
+ * Advances one root, or every registered root, without scheduling a RAF.
+ * This is the deterministic rendering path for `frameloop="never"`.
+ */
+export function advance(
+	timestamp: number,
+	runGlobalEffects = true,
+	state?: RootState,
+	frame?: XRFrame,
+): void {
+	if (runGlobalEffects) flushGlobalEffects('before', timestamp);
+
+	if (state === undefined) {
+		for (const store of roots) update(timestamp, store.getState());
+	} else {
+		update(timestamp, state, frame);
+	}
+
+	if (runGlobalEffects) flushGlobalEffects('after', timestamp);
+}