@octanejs/three 0.1.0

package/src/index.ts

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

package/src/intrinsics.ts

@@ -0,0 +1,18 @@
+import type { ThreeElements as ThreeIntrinsicElements } from './core/catalogue.js';
+
+export type {
+	Args,
+	Attach,
+	ConstructorRepresentation,
+	PrimitiveProps,
+	ThreeElement,
+	ThreeElements,
+	ThreeKey,
+	ThreeRef,
+	ThreeToJSXElements,
+} from './core/catalogue.js';
+
+/** TypeScript resolves this namespace through the intrinsic jsx-runtime export. */
+export namespace JSX {
+	export interface IntrinsicElements extends ThreeIntrinsicElements {}
+}

package/src/renderer.ts

@@ -0,0 +1,12 @@
+/**
+ * Compiler-facing Three renderer ABI.
+ *
+ * Compiled `*.three.tsrx` modules import their host plans and hook helpers from
+ * this entry point. The Three driver remains package-owned while component
+ * execution, ownership, scheduling, refs, and effects stay in Octane.
+ */
+export * from 'octane/universal';
+export * from './core/index.js';
+// Resolve the deliberate name overlap with the capability-gated universal
+// primitive in favor of Three's R3F-shaped state-enclave adapter.
+export { createPortal } from './core/portal.js';

package/src/testing.ts

@@ -0,0 +1,259 @@
+/**
+ * Deterministic, WebGL-free scene harness for `@octanejs/three` components.
+ *
+ * The harness deliberately drives the same configured root and frame loop as
+ * an application. It only replaces the rendering object with a small recorder,
+ * so host commits, hooks, global effects, and `useFrame` subscriptions retain
+ * their production behavior.
+ */
+import type * as THREE from 'three';
+import type { UniversalComponent } from 'octane/universal';
+import {
+	dispatchThreeEvent,
+	getThreeEventListener,
+	getThreeEventStore,
+	runThreeEventScope,
+} from './core/driver.js';
+import { createRoot, type CanvasLike, type ThreeRoot } from './core/root.js';
+import type { Renderer, RootStore } from './core/store.js';
+
+const DEFAULT_WIDTH = 1280;
+const DEFAULT_HEIGHT = 800;
+
+export interface CreateThreeTestRendererOptions {
+	/** Logical canvas width. Defaults to 1280. */
+	readonly width?: number;
+	/** Logical canvas height. Defaults to 800. */
+	readonly height?: number;
+}
+
+/** Renderer recorder injected into a deterministic Three test root. */
+export interface TestingRenderer extends Renderer {
+	/** Number of frames delivered through the root's real render loop. */
+	readonly frameCount: number;
+	/** Last scene submitted for rendering, or `null` before the first frame. */
+	readonly lastScene: THREE.Scene | null;
+	/** Last camera submitted for rendering, or `null` before the first frame. */
+	readonly lastCamera: THREE.Camera | null;
+	/** Whether root teardown disposed the recorder. */
+	readonly disposed: boolean;
+}
+
+/** Additional values copied onto a directly-fired testing event. */
+export interface MockEventData {
+	[key: string]: unknown;
+}
+
+/** R3F test-renderer-compatible event payload produced by {@link fireEvent}. */
+export interface MockSyntheticEvent extends MockEventData {
+	camera: THREE.Camera;
+	stopPropagation(): void;
+	target: object;
+	currentTarget: object;
+	sourceEvent: MockEventData;
+}
+
+export type FireEvent = (object: object, name: string, data?: MockEventData) => Promise<unknown>;
+
+export interface ThreeTestRenderer {
+	readonly canvas: CanvasLike;
+	readonly scene: THREE.Scene;
+	readonly store: RootStore;
+	readonly root: ThreeRoot<CanvasLike>;
+	readonly renderer: TestingRenderer;
+	update<P>(component: UniversalComponent<P>, props: P): RootStore;
+	/** Directly invokes an event handler on a managed Three object. */
+	fireEvent: FireEvent;
+	/**
+	 * Advances the configured `frameloop="never"` root by explicit deltas.
+	 * A short delta array repeats its final value for the remaining frames.
+	 */
+	advanceFrames(frames: number, delta?: number | readonly number[]): void;
+	unmount(): void;
+}
+
+class FrameRecorder implements TestingRenderer {
+	readonly domElement: CanvasLike;
+	readonly renderLists = { dispose() {} };
+	#frameCount = 0;
+	#lastScene: THREE.Scene | null = null;
+	#lastCamera: THREE.Camera | null = null;
+	#disposed = false;
+
+	constructor(canvas: CanvasLike) {
+		this.domElement = canvas;
+	}
+
+	get frameCount(): number {
+		return this.#frameCount;
+	}
+
+	get lastScene(): THREE.Scene | null {
+		return this.#lastScene;
+	}
+
+	get lastCamera(): THREE.Camera | null {
+		return this.#lastCamera;
+	}
+
+	get disposed(): boolean {
+		return this.#disposed;
+	}
+
+	render(scene: THREE.Scene, camera: THREE.Camera): void {
+		this.#frameCount++;
+		this.#lastScene = scene;
+		this.#lastCamera = camera;
+	}
+
+	setPixelRatio(_dpr: number): void {}
+
+	setSize(_width: number, _height: number, _updateStyle?: boolean): void {}
+
+	forceContextLoss(): void {}
+
+	dispose(): void {
+		this.#disposed = true;
+	}
+}
+
+function createCanvas(width: number, height: number): CanvasLike {
+	if (typeof document !== 'undefined' && typeof document.createElement === 'function') {
+		const canvas = document.createElement('canvas');
+		canvas.width = width;
+		canvas.height = height;
+		return canvas;
+	}
+	return { width, height, parentElement: null };
+}
+
+function assertFrameCount(frames: number): void {
+	if (!Number.isSafeInteger(frames) || frames < 0) {
+		throw new RangeError('@octanejs/three/testing: frames must be a non-negative integer.');
+	}
+}
+
+function deltaForFrame(delta: number | readonly number[], index: number): number {
+	const value = typeof delta === 'number' ? delta : (delta[index] ?? delta.at(-1) ?? 1);
+	if (!Number.isFinite(value)) {
+		throw new RangeError('@octanejs/three/testing: frame deltas must be finite numbers.');
+	}
+	return value;
+}
+
+function toEventHandlerName(name: string): string {
+	return name.startsWith('on') ? name : `on${name.charAt(0).toUpperCase()}${name.slice(1)}`;
+}
+
+function warnMissingEventHandler(name: string): void {
+	console.warn(
+		`Handler for ${name} was not found. You must pass event names in camelCase or name of the handler https://github.com/pmndrs/react-three-fiber/blob/master/packages/test-renderer/markdown/rttr.md#create-fireevent`,
+	);
+}
+
+async function dispatchTestingEvent(
+	object: object,
+	name: string,
+	data: MockEventData = {},
+): Promise<unknown> {
+	const handlerName = toEventHandlerName(name);
+	const listener = getThreeEventListener(object, handlerName);
+	const store = getThreeEventStore(object);
+	if (listener === undefined || store === undefined) {
+		warnMissingEventHandler(name);
+		return undefined;
+	}
+
+	const event = {
+		camera: store.getState().camera,
+		stopPropagation() {},
+		target: object,
+		currentTarget: object,
+		sourceEvent: data,
+		...data,
+	} as MockSyntheticEvent;
+
+	const result = runThreeEventScope(store, listener.priority, () =>
+		dispatchThreeEvent(store, listener.id, event),
+	);
+	const resolved = await result;
+	// Continuous scopes schedule their commit in a microtask. Let that commit and
+	// any passive work it queues settle before the caller observes the scene.
+	await Promise.resolve();
+	return resolved;
+}
+
+/**
+ * Directly invoke the latest committed event listener for a managed Three object.
+ * Both `pointerDown` and `onPointerDown` naming forms are accepted.
+ */
+export const fireEvent: FireEvent = dispatchTestingEvent;
+
+/** Creates a configured, deterministic Three root without requesting WebGL. */
+export async function createThreeTestRenderer<P>(
+	component: UniversalComponent<P>,
+	props: P,
+	options: CreateThreeTestRendererOptions = {},
+): Promise<ThreeTestRenderer> {
+	const width = options.width ?? DEFAULT_WIDTH;
+	const height = options.height ?? DEFAULT_HEIGHT;
+	const canvas = createCanvas(width, height);
+	const renderer = new FrameRecorder(canvas);
+	const root: ThreeRoot<CanvasLike> = createRoot(canvas);
+	let unmounted = false;
+
+	try {
+		await root.configure({
+			gl: renderer,
+			size: { width, height, top: 0, left: 0 },
+			dpr: 1,
+			frameloop: 'never',
+		});
+		root.render(component, props);
+	} catch (error) {
+		root.unmount();
+		throw error;
+	}
+
+	const store = root.store;
+	const scene = store.getState().scene;
+	const assertMounted = () => {
+		if (unmounted) {
+			throw new Error('@octanejs/three/testing: The test root has already been unmounted.');
+		}
+	};
+
+	return {
+		canvas,
+		scene,
+		store,
+		root,
+		renderer,
+		update<NextProps>(nextComponent: UniversalComponent<NextProps>, nextProps: NextProps) {
+			assertMounted();
+			return root.render(nextComponent, nextProps);
+		},
+		fireEvent(object, name, data) {
+			assertMounted();
+			return dispatchTestingEvent(object, name, data);
+		},
+		advanceFrames(frames, delta = 1) {
+			assertMounted();
+			assertFrameCount(frames);
+			const state = store.getState();
+			for (let index = 0; index < frames; index++) {
+				state.advance(state.clock.elapsedTime + deltaForFrame(delta, index));
+			}
+		},
+		unmount() {
+			if (unmounted) return;
+			unmounted = true;
+			root.unmount();
+		},
+	};
+}
+
+/** R3F test-renderer-compatible short name for the component-plus-props API. */
+export const create = createThreeTestRenderer;
+
+export default { create, fireEvent };

package/src/web/Canvas.tsrx

@@ -0,0 +1,295 @@
+import { useInsertionEffect, useLayoutEffect, useRef, useState } from 'octane';
+import { createUniversalHostBoundary } from 'octane/universal';
+import type { RendererRegion } from 'octane/universal';
+import type { ComputeFunction, DomEvent } from '../core/events.js';
+import { createRoot, createThreeBoundaryMount } from '../core/root.js';
+import type { RenderProps, ThreeBoundaryMount, ThreeRoot } from '../core/root.js';
+import type { RootState, Size } from '../core/store.js';
+import { createPointerEvents } from './events.js';
+import { observeCanvasSize } from './measure.js';
+import type { ResizeOptions } from './measure.js';
+
+const ThreeBoundary = createUniversalHostBoundary('three');
+const DEFAULT_RESIZE_OPTIONS: ResizeOptions = Object.freeze({
+	scroll: true,
+	debounce: Object.freeze({ scroll: 50, resize: 0 }),
+});
+
+export type CanvasStyle = Readonly<Record<string, string | number | null | undefined>>;
+type EventPrefix = 'offset' | 'client' | 'page' | 'layer' | 'screen';
+export type CanvasRef =
+	| { current: HTMLCanvasElement | null }
+	| ((canvas: HTMLCanvasElement | null) => void | (() => void))
+	| readonly CanvasRef[]
+	| null;
+
+export interface CanvasProps extends Omit<RenderProps<HTMLCanvasElement>, 'size'>, Record<
+	string,
+	unknown
+> {
+	/** Compiler-owned Three renderer region. Application JSX is lowered into this payload. */
+	children?: RendererRegion;
+	/** Fallback content rendered as native canvas fallback DOM. */
+	fallback?: unknown;
+	/** DOM measurement options compatible with the R3F Canvas surface. */
+	resize?: ResizeOptions;
+	/** Event subscription target. Defaults to the outer Canvas wrapper. */
+	eventSource?: HTMLElement | { current: HTMLElement | null };
+	/** Coordinate prefix used to normalize pointer positions. Defaults to `offset`. */
+	eventPrefix?: EventPrefix;
+	ref?: CanvasRef;
+	style?: CanvasStyle;
+}
+
+function sameSize(previous: Size | null, next: Size): boolean {
+	return previous !== null && previous.width === next.width && previous.height === next.height &&
+		previous.top === next.top &&
+		previous.left === next.left;
+}
+
+function configurationError(error: unknown): Error {
+	return error instanceof Error
+		? error
+		: new Error(`@octanejs/three: Canvas configuration failed: ${String(error)}`);
+}
+
+interface CanvasEventBinding {
+	initialized: boolean;
+	restoreCompute?: ComputeFunction;
+	source?: CanvasProps['eventSource'];
+	target?: HTMLElement | null;
+	prefix?: EventPrefix;
+	prefixCompute?: ComputeFunction;
+}
+
+function resolveEventSource(
+	source: CanvasProps['eventSource'],
+	wrapper: HTMLDivElement | null,
+): HTMLElement | null {
+	if (source === undefined) return wrapper;
+	return 'current' in source ? source.current ?? wrapper : source;
+}
+
+function createPrefixCompute(prefix: EventPrefix): ComputeFunction {
+	return (event: DomEvent, state: RootState) => {
+		const x = event[`${prefix}X` as keyof DomEvent] as number;
+		const y = event[`${prefix}Y` as keyof DomEvent] as number;
+		state.pointer.set((x / state.size.width) * 2 - 1, -(y / state.size.height) * 2 + 1);
+		state.raycaster.setFromCamera(state.pointer, state.camera);
+	};
+}
+
+function bindCanvasEvents(
+	state: RootState,
+	source: CanvasProps['eventSource'],
+	wrapper: HTMLDivElement | null,
+	prefix: EventPrefix | undefined,
+	binding: CanvasEventBinding,
+): void {
+	let current = state.get();
+	const target = resolveEventSource(source, wrapper);
+	if (!binding.initialized || binding.source !== source || binding.target !== target) {
+		binding.source = source;
+		binding.target = target;
+		if (target === null) current.events.disconnect?.();
+		else if (current.events.connected !== target) current.events.connect?.(target);
+		current = state.get();
+	}
+
+	if (!binding.initialized) binding.initialized = true;
+	if (binding.prefix !== prefix) {
+		const previousPrefixCompute = binding.prefixCompute;
+		if (binding.prefix === undefined || current.events.compute !== previousPrefixCompute) {
+			binding.restoreCompute = current.events.compute;
+		}
+		binding.prefix = prefix;
+		if (prefix === undefined) {
+			binding.prefixCompute = undefined;
+			if (current.events.compute === previousPrefixCompute) {
+				current.setEvents({ compute: binding.restoreCompute });
+			}
+		} else {
+			const prefixCompute = createPrefixCompute(prefix);
+			binding.prefixCompute = prefixCompute;
+			current.setEvents({ compute: prefixCompute });
+		}
+	}
+}
+
+/** A measured DOM canvas whose authored children execute in the Three renderer. */
+export function Canvas({
+	ref,
+	children,
+	fallback,
+	resize,
+	style,
+	gl,
+	events = createPointerEvents,
+	eventSource,
+	eventPrefix,
+	shadows,
+	linear,
+	flat,
+	legacy,
+	orthographic,
+	frameloop,
+	dpr,
+	performance,
+	raycaster,
+	camera,
+	scene,
+	onPointerMissed,
+	onCreated,
+	...domProps
+}: CanvasProps) {
+	const wrapperRef = useRef<HTMLDivElement | null>(null);
+	const canvasRef = useRef<HTMLCanvasElement | null>(null);
+	const rootRef = useRef<ThreeRoot<HTMLCanvasElement> | null>(null);
+	const eventSourceRef = useRef<CanvasProps['eventSource']>(eventSource);
+	const eventPrefixRef = useRef<EventPrefix | undefined>(eventPrefix);
+	const onCreatedRef = useRef(onCreated);
+	const onPointerMissedRef = useRef(onPointerMissed);
+	const eventBindingRef = useRef<CanvasEventBinding>({ initialized: false });
+	const createdHandlerRef = useRef<((state: RootState) => void) | null>(null);
+	const pointerMissedHandlerRef = useRef<((event: MouseEvent) => void) | null>(null);
+	const [size, setSize] = useState<Size | null>(null);
+	const [boundaryMount, setBoundaryMount] = useState<ThreeBoundaryMount | null>(null);
+	const [error, setError] = useState<Error | null>(null);
+	const eventTarget = resolveEventSource(eventSource, wrapperRef.current);
+	eventSourceRef.current = eventSource;
+	eventPrefixRef.current = eventPrefix;
+	onCreatedRef.current = onCreated;
+	onPointerMissedRef.current = onPointerMissed;
+	if (createdHandlerRef.current === null) {
+		createdHandlerRef.current = (state) => {
+			bindCanvasEvents(
+				state,
+				eventSourceRef.current,
+				wrapperRef.current,
+				eventPrefixRef.current,
+				eventBindingRef.current,
+			);
+			onCreatedRef.current?.(state.get());
+		};
+	}
+	if (pointerMissedHandlerRef.current === null) {
+		pointerMissedHandlerRef.current = (event) => onPointerMissedRef.current?.(event);
+	}
+
+	if (error !== null) throw error;
+
+	useLayoutEffect(() => {
+		const wrapper = wrapperRef.current;
+		if (wrapper === null) return;
+		return observeCanvasSize(wrapper, resize ?? DEFAULT_RESIZE_OPTIONS, (next) => {
+			setSize((previous) => (sameSize(previous, next) ? previous : next));
+		});
+	}, [resize]);
+
+	// A DOM Suspense or Activity boundary disconnects layout effects while its
+	// content is hidden. Root ownership must survive that retained state and
+	// end only when the Canvas is actually deleted.
+	useInsertionEffect(() => {
+		return () => {
+			const root = rootRef.current;
+			rootRef.current = null;
+			root?.unmount();
+		};
+	}, []);
+
+	useLayoutEffect(() => {
+		const canvas = canvasRef.current;
+		if (canvas === null || size === null || size.width <= 0 || size.height <= 0) return;
+		let cancelled = false;
+		let root = rootRef.current;
+		if (root === null) {
+			root = createRoot(canvas);
+			rootRef.current = root;
+		}
+		void root.configure({
+			gl,
+			events,
+			shadows,
+			linear,
+			flat,
+			legacy,
+			orthographic,
+			frameloop,
+			dpr,
+			performance,
+			raycaster,
+			camera,
+			scene,
+			onPointerMissed: pointerMissedHandlerRef.current,
+			onCreated: createdHandlerRef.current,
+			size,
+		}).then(() => {
+			if (cancelled) return;
+			setBoundaryMount(createThreeBoundaryMount(root));
+		}).catch((reason) => {
+			if (!cancelled) setError(configurationError(reason));
+		});
+		return () => {
+			cancelled = true;
+		};
+	}, [
+		size,
+		gl,
+		events,
+		shadows,
+		linear,
+		flat,
+		legacy,
+		orthographic,
+		frameloop,
+		dpr,
+		performance,
+		raycaster,
+		camera,
+		scene,
+	]);
+
+	// A stable ref object can receive a new current target during commit. Recheck after every
+	// render; bindCanvasEvents avoids reconnecting when the resolved target is unchanged.
+	useLayoutEffect(() => {
+		const root = rootRef.current;
+		if (boundaryMount === null || root === null) return;
+		bindCanvasEvents(
+			root.store.getState(),
+			eventSource,
+			wrapperRef.current,
+			eventPrefix,
+			eventBindingRef.current,
+		);
+	}, null);
+
+	const renderedBoundaryMount: ThreeBoundaryMount | null =
+		boundaryMount === null
+			? null
+			: {
+					...boundaryMount,
+					props: { ...boundaryMount.props, region: children },
+				};
+
+	const wrapperStyle: CanvasStyle = {
+		position: 'relative',
+		width: '100%',
+		height: '100%',
+		overflow: 'hidden',
+		pointerEvents: eventTarget === wrapperRef.current ? 'auto' : 'none',
+		...style,
+	};
+
+	return <div ref={wrapperRef} style={wrapperStyle} {...domProps}>
+		<div style={{ width: '100%', height: '100%' }}>
+			<canvas ref={[canvasRef, ref]} style={{ display: 'block' }}>{fallback}</canvas>
+		</div>
+		{renderedBoundaryMount === null
+			? null
+			: <ThreeBoundary
+					root={renderedBoundaryMount.root}
+					component={renderedBoundaryMount.component}
+					props={renderedBoundaryMount.props}
+				/>}
+	</div>;
+}

package/src/web/Canvas.tsrx.d.ts

@@ -0,0 +1,23 @@
+import type { RendererRegion } from 'octane/universal';
+import type { RenderProps } from '../core/root.js';
+import type { ResizeOptions } from './measure.js';
+
+export type CanvasStyle = Readonly<Record<string, string | number | null | undefined>>;
+export type CanvasRef =
+	| { current: HTMLCanvasElement | null }
+	| ((canvas: HTMLCanvasElement | null) => void | (() => void))
+	| readonly CanvasRef[]
+	| null;
+
+export interface CanvasProps
+	extends Omit<RenderProps<HTMLCanvasElement>, 'size'>, Record<string, unknown> {
+	children?: RendererRegion;
+	fallback?: unknown;
+	resize?: ResizeOptions;
+	eventSource?: HTMLElement | { current: HTMLElement | null };
+	eventPrefix?: 'offset' | 'client' | 'page' | 'layer' | 'screen';
+	ref?: CanvasRef;
+	style?: CanvasStyle;
+}
+
+export declare function Canvas(props: CanvasProps): unknown;