@octanejs/three 0.1.0 → 0.1.2

package/src/index.ts

@@ -26,22 +26,39 @@ export {
 export type {
 	Args,
 	Attach,
+	AttachFnType,
+	AttachType,
 	Catalogue,
+	Color,
 	ConstructorRepresentation,
+	Disposable,
+	ElementProps,
+	Euler,
 	EventProps,
 	Instance,
 	InstanceProps,
+	Layers,
 	MathRepresentation,
+	MathProps,
 	MathType,
 	MathTypes,
+	Matrix3,
+	Matrix4,
 	PrimitiveProps,
+	Quaternion,
 	RaycastableRepresentation,
+	ReactProps,
+	ReconcilerRoot,
 	ThreeElement,
 	ThreeElements,
 	ThreeInstanceProps,
 	ThreeKey,
 	ThreeRef,
 	ThreeToJSXElements,
+	Vector2,
+	Vector3,
+	Vector4,
+	VectorRepresentation,
 } from './core/index.js';
 export type {
 	Camera,
@@ -81,6 +98,14 @@ export type {
 	Viewport,
 	XRManager,
 } from './core/index.js';
+export { act, flushSync } from './scheduling.js';
+export type { Act } from './scheduling.js';
 export { Canvas } from './web/Canvas.tsrx';
 export type { CanvasProps, CanvasRef, CanvasStyle } from './web/Canvas.tsrx';
+export { DOMRegion } from './web/DOMRegion.js';
+export type { DOMRegionProps, DOMRegionTarget } from './web/DOMRegion.js';
 export { createPointerEvents as events } from './web/events.js';
+/** Canonical namespace for renderer-local Three element and math types. */
+export * as OctaneThree from './intrinsics.js';
+/** R3F's historical namespace name retained for source compatibility. */
+export * as ReactThreeFiber from './intrinsics.js';

package/src/intrinsics.ts

@@ -3,13 +3,33 @@ import type { ThreeElements as ThreeIntrinsicElements } from './core/catalogue.j
 export type {
 	Args,
 	Attach,
+	AttachFnType,
+	AttachType,
+	Color,
 	ConstructorRepresentation,
+	ElementProps,
+	Euler,
+	EventProps,
+	Layers,
+	MathProps,
+	MathRepresentation,
+	MathType,
+	MathTypes,
+	Matrix3,
+	Matrix4,
 	PrimitiveProps,
+	Quaternion,
+	RaycastableRepresentation,
+	ReactProps,
 	ThreeElement,
 	ThreeElements,
 	ThreeKey,
 	ThreeRef,
 	ThreeToJSXElements,
+	Vector2,
+	Vector3,
+	Vector4,
+	VectorRepresentation,
 } from './core/catalogue.js';
 
 /** TypeScript resolves this namespace through the intrinsic jsx-runtime export. */

package/src/scheduling.ts

@@ -0,0 +1,83 @@
+import * as Octane from 'octane';
+import { flushUniversalAct, flushUniversalSync, type UniversalSyncFlusher } from 'octane/universal';
+
+export type Act = typeof import('octane').act;
+type FlushSync = typeof import('octane').flushSync;
+const NO_ACT_ERROR = Symbol('octane.three.no-act-error');
+
+function isThenable<T>(value: T | Promise<T>): value is Promise<T> {
+	return (
+		value !== null &&
+		(typeof value === 'object' || typeof value === 'function') &&
+		typeof (value as PromiseLike<T>).then === 'function'
+	);
+}
+
+function runActCallback<T>(
+	callback: () => T | Promise<T>,
+	flushOwner?: UniversalSyncFlusher,
+): T | Promise<T> {
+	const result = flushUniversalAct(callback, flushOwner);
+	if (!isThenable(result)) return result;
+	return Promise.resolve(result).then((value) => flushUniversalAct(() => value, flushOwner));
+}
+
+function runClientAct<T>(callback: () => T | Promise<T>, clientAct: Act): Promise<T> {
+	const completions: Promise<unknown>[] = [];
+	const flushOwner: UniversalSyncFlusher = <Value>(run: () => Value): Value => {
+		let value!: Value;
+		let error: unknown = NO_ACT_ERROR;
+		const completion = clientAct(() => {
+			try {
+				value = run();
+			} catch (caught) {
+				error = caught;
+			}
+		});
+		completions.push(completion);
+		if (error !== NO_ACT_ERROR) throw error;
+		return value;
+	};
+
+	let result: T | Promise<T>;
+	try {
+		// Each universal wave executes inside a full DOM act phase, including DOM
+		// passive effects. This closes DOMRegion cascades in both directions.
+		result = flushUniversalAct(callback, flushOwner);
+	} catch (error) {
+		return Promise.allSettled(completions.splice(0)).then(() => {
+			throw error;
+		});
+	}
+
+	return (async () => {
+		try {
+			const value = await result;
+			await Promise.all(completions.splice(0));
+			const settled = flushUniversalAct(() => value, flushOwner);
+			await Promise.all(completions.splice(0));
+			return settled;
+		} catch (error) {
+			await Promise.allSettled(completions.splice(0));
+			throw error;
+		}
+	})();
+}
+
+/** Flushes both the DOM scheduler and mounted universal Three roots. */
+export const flushSync: FlushSync = (callback) => {
+	const clientFlushSync = Reflect.get(Octane, 'flushSync') as FlushSync | undefined;
+	return flushUniversalSync(callback, clientFlushSync);
+};
+
+/** R3F-compatible test helper backed by Octane's client scheduler when available. */
+export const act: Act = (callback) => {
+	const clientAct = Reflect.get(Octane, 'act') as Act | undefined;
+	const clientFlushSync = Reflect.get(Octane, 'flushSync') as FlushSync | undefined;
+	if (typeof clientAct === 'function') return runClientAct(callback, clientAct);
+	try {
+		return Promise.resolve(runActCallback(callback, clientFlushSync));
+	} catch (error) {
+		return Promise.reject(error);
+	}
+};

package/src/web/DOMRegion.ts

@@ -0,0 +1,58 @@
+import {
+	defineUniversalComponent,
+	universalPlan,
+	universalProps,
+	universalValue,
+	useLayoutEffect,
+	useMemo,
+	type RendererRegion,
+} from 'octane/universal';
+import { Object3D } from 'three';
+import { createDOMRegionBinding, type DOMRegionTarget } from './dom-region.js';
+
+export type { DOMRegionTarget } from './dom-region.js';
+
+export interface DOMRegionProps {
+	/** Explicit DOM parent for the region's one owned child container. */
+	target: DOMRegionTarget;
+	/** Compiler-owned DOM renderer region. Application JSX is lowered into this payload. */
+	children?: RendererRegion;
+}
+
+class DOMRegionSentinel extends Object3D {
+	declare region?: RendererRegion;
+}
+
+const DOM_REGION_PLAN = universalPlan('three', {
+	kind: 'host',
+	type: 'primitive',
+	propsSlot: 0,
+});
+const DOM_REGION_BINDING = Symbol('octane.three.dom-region.binding');
+const DOM_REGION_SENTINEL = Symbol('octane.three.dom-region.sentinel');
+const DOM_REGION_LIFETIME = Symbol('octane.three.dom-region.lifetime');
+const DOM_REGION_COMMIT = Symbol('octane.three.dom-region.commit');
+
+/**
+ * Low-level Three-to-DOM renderer boundary.
+ *
+ * DOMRegion deliberately provides no positioning, transforms, occlusion, or styling.
+ */
+export const DOMRegion = defineUniversalComponent<DOMRegionProps>('three', (props) => {
+	const binding = useMemo(() => createDOMRegionBinding(), [], DOM_REGION_BINDING);
+	const sentinel = useMemo(() => new DOMRegionSentinel(), [], DOM_REGION_SENTINEL);
+	useLayoutEffect(() => binding.attach(), [binding], DOM_REGION_LIFETIME);
+	useLayoutEffect(
+		() => binding.commit(props.target, props.children),
+		[binding, props.target, props.children],
+		DOM_REGION_COMMIT,
+	);
+
+	return universalValue(DOM_REGION_PLAN, [
+		universalProps([
+			['set', 'object', sentinel],
+			['set', 'dispose', null],
+			['set', 'region', props.children],
+		]),
+	]);
+});

package/src/web/dom-region.ts

@@ -0,0 +1,104 @@
+import * as Octane from 'octane';
+import type { ComponentBody, Root } from 'octane';
+import { isRendererRegion, type RendererRegion } from 'octane/universal';
+
+export type DOMRegionTarget = HTMLElement | { current: HTMLElement | null };
+
+function isHTMLElement(value: unknown): value is HTMLElement {
+	if (value === null || typeof value !== 'object') return false;
+	const view = (value as Node).ownerDocument?.defaultView;
+	return view !== null && view !== undefined && value instanceof view.HTMLElement;
+}
+
+function resolveTarget(target: DOMRegionTarget): HTMLElement | null {
+	if (target === null || typeof target !== 'object') {
+		throw new TypeError('@octanejs/three: DOMRegion target must be an HTMLElement or ref.');
+	}
+	const resolved = 'current' in target ? target.current : target;
+	if (resolved !== null && !isHTMLElement(resolved)) {
+		throw new TypeError('@octanejs/three: DOMRegion target ref must contain an HTMLElement.');
+	}
+	return resolved;
+}
+
+/** Package-private owner for the one DOM root materialized by a DOMRegion. */
+export interface DOMRegionBinding {
+	attach(): () => void;
+	commit(target: DOMRegionTarget, region: RendererRegion | undefined): void;
+}
+
+export function createDOMRegionBinding(): DOMRegionBinding {
+	const createRoot = Reflect.get(Octane, 'createRoot') as
+		| typeof import('octane').createRoot
+		| undefined;
+	if (typeof createRoot !== 'function' || typeof document === 'undefined') {
+		throw new Error('@octanejs/three: DOMRegion is client-only and requires a DOM root.');
+	}
+	const host = document.createElement('div');
+	let attached = false;
+	let root: Root | null = null;
+
+	const unmount = () => {
+		const current = root;
+		try {
+			if (current !== null) current.unmount();
+		} finally {
+			host.remove();
+		}
+	};
+
+	const createTrackedRoot = (): Root => {
+		const next = createRoot(host);
+		const rootUnmount = next.unmount.bind(next);
+		let live = true;
+		// The reverse-owner bridge may unmount this root before the Three sentinel
+		// itself is deleted. Track that public teardown so the next accepted commit
+		// can create a fresh root instead of updating an already-unmounted one.
+		next.unmount = () => {
+			if (!live) return;
+			live = false;
+			const wasCurrent = root === next;
+			if (wasCurrent) root = null;
+			try {
+				rootUnmount();
+			} finally {
+				if (wasCurrent) host.remove();
+			}
+		};
+		return next;
+	};
+
+	return {
+		attach() {
+			attached = true;
+			let active = true;
+			return () => {
+				if (!active) return;
+				active = false;
+				attached = false;
+				unmount();
+			};
+		},
+		commit(target, region) {
+			if (!attached) return;
+			const resolvedTarget = resolveTarget(target);
+			if (resolvedTarget === null || region === undefined) {
+				unmount();
+				return;
+			}
+			if (
+				!isRendererRegion(region) ||
+				region.ownerRenderer !== 'three' ||
+				region.childRenderer !== 'dom'
+			) {
+				throw new TypeError(
+					'@octanejs/three: DOMRegion children must be a compiler-owned Three-to-DOM region.',
+				);
+			}
+
+			if (root === null) root = createTrackedRoot();
+			if (host.parentElement !== resolvedTarget) resolvedTarget.append(host);
+			root.render(region.component as ComponentBody, region.props);
+		},
+	};
+}