@octanejs/drei 0.0.1

package/src/core/lines.three.tsrx

@@ -0,0 +1,329 @@
+/** @jsxImportSource @octanejs/three/intrinsics */
+import {
+	type ThreeElement,
+	type ThreeElements,
+	type ThreeRef,
+	type Vector2 as FiberVector2,
+	type Vector3 as FiberVector3,
+	useThree,
+} from '@octanejs/three';
+import {
+	useCallback,
+	useEffect,
+	useLayoutEffect,
+	useMemo,
+	useRef,
+	useState,
+} from '@octanejs/three/renderer';
+import {
+	CatmullRomCurve3,
+	Color,
+	type ColorRepresentation,
+	CubicBezierCurve3,
+	EdgesGeometry,
+	type BufferAttribute,
+	type BufferGeometry,
+	type Mesh,
+	QuadraticBezierCurve3,
+	Vector2,
+	Vector3,
+	Vector4,
+} from 'three';
+import {
+	Line2,
+	LineGeometry,
+	LineMaterial,
+	type LineMaterialParameters,
+	LineSegments2,
+	LineSegmentsGeometry,
+} from 'three-stdlib';
+
+function assignRef<T>(ref: ThreeRef<T> | undefined, value: T | null): void {
+	if (Array.isArray(ref)) for (const item of ref) assignRef(item, value);
+	else if (typeof ref === 'function') ref(value);
+	else if (ref && 'current' in ref) ref.current = value;
+}
+
+export type LineProps =
+	Omit<
+		{
+			points: ReadonlyArray<FiberVector2 | FiberVector3>;
+			vertexColors?: ReadonlyArray<
+				Color | [number, number, number] | [number, number, number, number]
+			>;
+			lineWidth?: number;
+			segments?: boolean;
+		} & Omit<LineMaterialParameters, 'vertexColors' | 'color'> & Omit<
+			ThreeElement<typeof Line2>,
+			'ref' | 'args'
+		> & Omit<ThreeElement<typeof LineMaterial>, 'ref' | 'color' | 'vertexColors' | 'args'> & {
+			color?: ColorRepresentation;
+		},
+		'ref'
+	>;
+
+export function Line({
+	points,
+	color = 0xffffff,
+	vertexColors,
+	linewidth,
+	lineWidth,
+	segments,
+	dashed,
+	ref,
+	...rest
+}: LineProps & { ref?: ThreeRef<Line2 | LineSegments2> }) @{
+	const size = useThree((state) => state.size);
+	const line = useMemo(() => (segments ? new LineSegments2() : new Line2()), [segments]);
+	const [material] = useState(() => new LineMaterial());
+	const itemSize =
+		(vertexColors?.[0] as number[] | undefined)?.length === 4 ? 4 : 3;
+	const geometry = useMemo(() => {
+		const value = segments ? new LineSegmentsGeometry() : new LineGeometry();
+		const positions = points.map((point) => {
+			const array = Array.isArray(point);
+			return point instanceof Vector3 || point instanceof Vector4
+				? [point.x, point.y, point.z]
+				: point instanceof Vector2
+					? [point.x, point.y, 0]
+					: array && point.length === 3
+						? [point[0], point[1], point[2]]
+						: array && point.length === 2
+							? [point[0], point[1], 0]
+							: point;
+		});
+		value.setPositions(positions.flat() as number[]);
+		if (vertexColors) {
+			color = 0xffffff;
+			const values = vertexColors.map((value) => value instanceof Color ? value.toArray() : value);
+			value.setColors(values.flat(), itemSize);
+		}
+		return value;
+	}, [points, segments, vertexColors, itemSize]);
+	const mergedRef = useMemo(() => (value: Line2 | LineSegments2 | null) => assignRef(ref, value), [
+		ref,
+	]);
+	useLayoutEffect(() => {
+		line.computeLineDistances();
+	}, [points, line]);
+	useLayoutEffect(() => {
+		if (dashed) material.defines.USE_DASH = '';
+		else delete material.defines.USE_DASH;
+		material.needsUpdate = true;
+	}, [dashed, material]);
+	useEffect(
+		() => () => {
+			geometry.dispose();
+			material.dispose();
+		},
+		[geometry],
+	);
+	<primitive object={line} ref={mergedRef as any} {...rest as any}>
+		<primitive object={geometry} attach="geometry" />
+		<primitive
+			object={material}
+			attach="material"
+			color={color}
+			vertexColors={Boolean(vertexColors)}
+			resolution={[size.width, size.height]}
+			linewidth={linewidth ?? lineWidth ?? 1}
+			dashed={dashed}
+			transparent={itemSize === 4}
+			{...rest as any}
+		/>
+	</primitive>
+}
+
+export type QuadraticBezierLineRef =
+	Line2 & {
+		setPoints(start: Vector3 | [number, number, number], end: | Vector3
+		| [number, number, number], mid: Vector3 | [number, number, number]): void;
+	};
+
+export type QuadraticBezierLineProps =
+	Omit<LineProps, 'points' | 'ref' | 'segments'> & {
+		start: Vector3 | [number, number, number];
+		end: Vector3 | [number, number, number];
+		mid?: Vector3 | [number, number, number];
+		segments?: number;
+	};
+
+const quadraticOffset = new Vector3();
+
+export function QuadraticBezierLine({
+	start = [0, 0, 0],
+	end = [0, 0, 0],
+	mid,
+	segments = 20,
+	ref,
+	...rest
+}: QuadraticBezierLineProps & { ref?: ThreeRef<QuadraticBezierLineRef> }) @{
+	const localRef = useRef<QuadraticBezierLineRef | null>(null);
+	const [curve] = useState(
+		() => new QuadraticBezierCurve3(undefined as any, undefined as any, undefined as any),
+	);
+	const getPoints = useCallback((
+		from: Vector3 | [number, number, number],
+		to: Vector3 | [number, number, number],
+		middle?: Vector3 | [number, number, number],
+		count = 20,
+	) => {
+		if (from instanceof Vector3) curve.v0.copy(from);
+		else curve.v0.set(...from);
+		if (to instanceof Vector3) curve.v2.copy(to);
+		else curve.v2.set(...to);
+		if (middle instanceof Vector3) curve.v1.copy(middle);
+		else if (Array.isArray(middle)) curve.v1.set(...middle);
+		else {
+			curve.v1.copy(
+				curve.v0.clone().add(curve.v2.clone().sub(curve.v0)).add(
+					quadraticOffset.set(0, curve.v0.y - curve.v2.y, 0),
+				),
+			);
+		}
+		return curve.getPoints(count);
+	}, []);
+	useLayoutEffect(() => {
+		if (!localRef.current) return;
+		localRef.current.setPoints = (from, to, middle) => {
+			const values = getPoints(from, to, middle);
+			localRef.current?.geometry?.setPositions(values.flatMap((point) => point.toArray()));
+		};
+	});
+	const points = useMemo(() => getPoints(start, end, mid, segments), [start, end, mid, segments]);
+	const mergedRef = useMemo(
+		() => (value: QuadraticBezierLineRef | null) => {
+			localRef.current = value;
+			assignRef(ref, value);
+		},
+		[ref],
+	);
+	<Line ref={mergedRef as any} points={points} {...rest as any} />
+}
+
+export type CubicBezierLineProps =
+	Omit<LineProps, 'points' | 'ref' | 'segments'> & {
+		start: Vector3 | [number, number, number];
+		end: Vector3 | [number, number, number];
+		midA: Vector3 | [number, number, number];
+		midB: Vector3 | [number, number, number];
+		segments?: number;
+	};
+
+export function CubicBezierLine({
+	start,
+	end,
+	midA,
+	midB,
+	segments = 20,
+	ref,
+	...rest
+}: CubicBezierLineProps & { ref?: ThreeRef<Line2> }) @{
+	const points = useMemo(() => {
+		const startVector =
+			start instanceof Vector3 ? start : new Vector3(...start);
+		const endVector =
+			end instanceof Vector3 ? end : new Vector3(...end);
+		const midAVector =
+			midA instanceof Vector3 ? midA : new Vector3(...midA);
+		const midBVector =
+			midB instanceof Vector3 ? midB : new Vector3(...midB);
+		return new CubicBezierCurve3(startVector, midAVector, midBVector, endVector).getPoints(
+			segments,
+		);
+	}, [start, end, midA, midB, segments]);
+	<Line ref={ref as any} points={points} {...rest as any} />
+}
+
+export type CatmullRomLineProps =
+	Omit<LineProps, 'ref' | 'segments'> & {
+		closed?: boolean;
+		curveType?: 'centripetal' | 'chordal' | 'catmullrom';
+		tension?: number;
+		segments?: number;
+	};
+
+export function CatmullRomLine({
+	points,
+	closed = false,
+	curveType = 'centripetal',
+	tension = 0.5,
+	segments = 20,
+	vertexColors,
+	ref,
+	...rest
+}: CatmullRomLineProps & { ref?: ThreeRef<Line2> }) @{
+	const curve = useMemo(() => {
+		const mapped = points.map(
+			(point) => point instanceof Vector3
+				? point
+				: new Vector3(...point as [number, number, number]),
+		);
+		return new CatmullRomCurve3(mapped, closed, curveType, tension);
+	}, [points, closed, curveType, tension]);
+	const segmentedPoints = useMemo(() => curve.getPoints(segments), [curve, segments]);
+	const interpolatedVertexColors = useMemo(() => {
+		if (!vertexColors || vertexColors.length < 2) return undefined;
+		if (vertexColors.length === segments + 1) return vertexColors;
+		const mapped = vertexColors.map(
+			(color) => color instanceof Color ? color : new Color(...color as [number, number, number]),
+		);
+		if (closed) mapped.push(mapped[0].clone());
+		const values: Color[] = [mapped[0]];
+		const divisions = segments / (mapped.length - 1);
+		for (let index = 1; index < segments; index++) {
+			const alpha = (index % divisions) / divisions;
+			const colorIndex = Math.floor(index / divisions);
+			values.push(mapped[colorIndex].clone().lerp(mapped[colorIndex + 1], alpha));
+		}
+		values.push(mapped[mapped.length - 1]);
+		return values;
+	}, [vertexColors, segments]);
+	<Line
+		ref={ref as any}
+		points={segmentedPoints}
+		vertexColors={interpolatedVertexColors}
+		{...rest as any}
+	/>
+}
+
+export type EdgesRef = Mesh<any, any>;
+export type EdgesProps =
+	Partial<ThreeElements['mesh']> & {
+		threshold?: number;
+		lineWidth?: number;
+		geometry?: BufferGeometry;
+		color?: ColorRepresentation;
+	} & Omit<LineMaterialParameters, 'vertexColors' | 'color'>;
+
+export function Edges({ threshold = 15, geometry: explicitGeometry, ref, ...props }: EdgesProps & {
+	ref?: ThreeRef<EdgesRef>;
+}) @{
+	const localRef = useRef<LineSegments2 | null>(null);
+	const points = useMemo(() => [0, 0, 0, 1, 0, 0], []);
+	const memoizedGeometry = useRef<BufferGeometry | null>(null);
+	const memoizedThreshold = useRef<number | null>(null);
+	const mergedRef = useMemo(
+		() => (value: LineSegments2 | null) => {
+			localRef.current = value;
+			assignRef(ref as ThreeRef<LineSegments2> | undefined, value);
+		},
+		[ref],
+	);
+	useLayoutEffect(() => {
+		if (!localRef.current) return;
+		const parent = localRef.current.parent as Mesh | null;
+		const geometry = explicitGeometry ?? parent?.geometry;
+		if (!geometry) return;
+		if (memoizedGeometry.current === geometry && memoizedThreshold.current === threshold) return;
+		memoizedGeometry.current = geometry;
+		memoizedThreshold.current = threshold;
+		const edgeGeometry = new EdgesGeometry(geometry, threshold);
+		const values = (edgeGeometry.attributes.position as BufferAttribute).array as Float32Array;
+		localRef.current.geometry.setPositions(values);
+		localRef.current.geometry.attributes.instanceStart.needsUpdate = true;
+		localRef.current.geometry.attributes.instanceEnd.needsUpdate = true;
+		localRef.current.computeLineDistances();
+	});
+	<Line segments points={points} ref={mergedRef as any} raycast={() => null} {...props as any} />
+}

package/src/core/meshBounds.ts

@@ -0,0 +1,26 @@
+import { type Intersection, Matrix4, type Mesh, Ray, type Raycaster, Sphere, Vector3 } from 'three';
+
+const _inverseMatrix = /* @__PURE__ */ new Matrix4();
+const _ray = /* @__PURE__ */ new Ray();
+const _sphere = /* @__PURE__ */ new Sphere();
+const _vA = /* @__PURE__ */ new Vector3();
+
+export function meshBounds(this: Mesh, raycaster: Raycaster, intersects: Intersection[]): void {
+	const geometry = this.geometry;
+	const material = this.material;
+	const matrixWorld = this.matrixWorld;
+	if (material === undefined) return;
+	if (geometry.boundingSphere === null) geometry.computeBoundingSphere();
+	_sphere.copy(geometry.boundingSphere!);
+	_sphere.applyMatrix4(matrixWorld);
+	if (raycaster.ray.intersectsSphere(_sphere) === false) return;
+	_inverseMatrix.copy(matrixWorld).invert();
+	_ray.copy(raycaster.ray).applyMatrix4(_inverseMatrix);
+	if (geometry.boundingBox !== null && _ray.intersectBox(geometry.boundingBox, _vA) === null)
+		return;
+	intersects.push({
+		distance: _vA.distanceTo(raycaster.ray.origin),
+		point: _vA.clone(),
+		object: this,
+	});
+}

package/src/core/motion-materials.three.tsrx

@@ -0,0 +1,93 @@
+/** @jsxImportSource @octanejs/three/intrinsics */
+import { type ThreeElements, type ThreeRef, useFrame } from '@octanejs/three';
+import { useMemo, useState } from '@octanejs/three/renderer';
+import * as THREE from 'three';
+
+const distortShader = '#define GLSLIFY 1\nvec3 mod289(vec3 x){return x-floor(x*(1.0/289.0))*289.0;}vec4 mod289(vec4 x){return x-floor(x*(1.0/289.0))*289.0;}vec4 permute(vec4 x){return mod289(((x*34.0)+1.0)*x);}vec4 taylorInvSqrt(vec4 r){return 1.79284291400159-0.85373472095314*r;}float snoise(vec3 v){const vec2 C=vec2(1.0/6.0,1.0/3.0);const vec4 D=vec4(0.0,0.5,1.0,2.0);vec3 i=floor(v+dot(v,C.yyy));vec3 x0=v-i+dot(i,C.xxx);vec3 g=step(x0.yzx,x0.xyz);vec3 l=1.0-g;vec3 i1=min(g.xyz,l.zxy);vec3 i2=max(g.xyz,l.zxy);vec3 x1=x0-i1+C.xxx;vec3 x2=x0-i2+C.yyy;vec3 x3=x0-D.yyy;i=mod289(i);vec4 p=permute(permute(permute(i.z+vec4(0.0,i1.z,i2.z,1.0))+i.y+vec4(0.0,i1.y,i2.y,1.0))+i.x+vec4(0.0,i1.x,i2.x,1.0));float n_=0.142857142857;vec3 ns=n_*D.wyz-D.xzx;vec4 j=p-49.0*floor(p*ns.z*ns.z);vec4 x_=floor(j*ns.z);vec4 y_=floor(j-7.0*x_);vec4 x=x_*ns.x+ns.yyyy;vec4 y=y_*ns.x+ns.yyyy;vec4 h=1.0-abs(x)-abs(y);vec4 b0=vec4(x.xy,y.xy);vec4 b1=vec4(x.zw,y.zw);vec4 s0=floor(b0)*2.0+1.0;vec4 s1=floor(b1)*2.0+1.0;vec4 sh=-step(h,vec4(0.0));vec4 a0=b0.xzyw+s0.xzyw*sh.xxyy;vec4 a1=b1.xzyw+s1.xzyw*sh.zzww;vec3 p0=vec3(a0.xy,h.x);vec3 p1=vec3(a0.zw,h.y);vec3 p2=vec3(a1.xy,h.z);vec3 p3=vec3(a1.zw,h.w);vec4 norm=taylorInvSqrt(vec4(dot(p0,p0),dot(p1,p1),dot(p2,p2),dot(p3,p3)));p0*=norm.x;p1*=norm.y;p2*=norm.z;p3*=norm.w;vec4 m=max(0.6-vec4(dot(x0,x0),dot(x1,x1),dot(x2,x2),dot(x3,x3)),0.0);m=m*m;return 42.0*dot(m*m,vec4(dot(p0,x0),dot(p1,x1),dot(p2,x2),dot(p3,x3)));}';
+
+type Uniform<T> = { value: T };
+
+export class DistortMaterialImpl extends THREE.MeshPhysicalMaterial {
+	_time: Uniform<number> = { value: 0 };
+	_distort: Uniform<number> = { value: 0.4 };
+	_radius: Uniform<number> = { value: 1 };
+
+	constructor(parameters: THREE.MeshPhysicalMaterialParameters = {}) {
+		super(parameters);
+		this.setValues(parameters);
+	}
+
+	override onBeforeCompile(shader: THREE.WebGLProgramParametersWithUniforms): void {
+		shader.uniforms.time = this._time;
+		shader.uniforms.radius = this._radius;
+		shader.uniforms.distort = this._distort;
+		shader.vertexShader = `uniform float time;\nuniform float radius;\nuniform float distort;\n${distortShader}\n${shader.vertexShader}`;
+		shader.vertexShader = shader.vertexShader.replace('#include <begin_vertex>', 'float updateTime = time / 50.0;\nfloat noise = snoise(vec3(position / 2.0 + updateTime * 5.0));\nvec3 transformed = vec3(position * (noise * pow(distort, 2.0) + radius));');
+	}
+
+	get time(): number { return this._time.value; }
+	set time(value: number) { this._time.value = value; }
+	get distort(): number { return this._distort.value; }
+	set distort(value: number) { this._distort.value = value; }
+	get radius(): number { return this._radius.value; }
+	set radius(value: number) { this._radius.value = value; }
+}
+
+export class WobbleMaterialImpl extends THREE.MeshStandardMaterial {
+	_time: Uniform<number> = { value: 0 };
+	_factor: Uniform<number> = { value: 1 };
+
+	constructor(parameters: THREE.MeshStandardMaterialParameters = {}) {
+		super(parameters);
+		this.setValues(parameters);
+	}
+
+	override onBeforeCompile(shader: THREE.WebGLProgramParametersWithUniforms): void {
+		shader.uniforms.time = this._time;
+		shader.uniforms.factor = this._factor;
+		shader.vertexShader = `uniform float time;\nuniform float factor;\n${shader.vertexShader}`;
+		shader.vertexShader = shader.vertexShader.replace('#include <begin_vertex>', 'float theta = sin( time + position.y ) / 2.0 * factor;\nfloat c = cos( theta );\nfloat s = sin( theta );\nmat3 m = mat3( c, 0, s, 0, 1, 0, -s, 0, c );\nvec3 transformed = vec3( position ) * m;\nvNormal = vNormal * m;');
+	}
+
+	get time(): number { return this._time.value; }
+	set time(value: number) { this._time.value = value; }
+	get factor(): number { return this._factor.value; }
+	set factor(value: number) { this._factor.value = value; }
+}
+
+export type MeshDistortMaterialProps = Omit<ThreeElements['meshPhysicalMaterial'], 'ref'> & {
+	time?: number;
+	distort?: number;
+	radius?: number;
+	speed?: number;
+	factor?: number;
+};
+
+export function MeshDistortMaterial({ speed = 1, ref, ...props }: MeshDistortMaterialProps & {
+	ref?: ThreeRef<DistortMaterialImpl>;
+}) @{
+	const [material] = useState(() => new DistortMaterialImpl());
+	const mergedRef = useMemo(() => (value: DistortMaterialImpl | null) => assignRef(ref, value), [ref]);
+	useFrame((state) => (material.time = state.clock.elapsedTime * speed));
+	<primitive object={material} ref={mergedRef} attach="material" {...props as any} />
+}
+
+export type WobbleMaterialProps = Omit<ThreeElements['meshStandardMaterial'], 'ref'> & {
+	speed?: number;
+	factor?: number;
+};
+
+export function MeshWobbleMaterial({ speed = 1, ref, ...props }: WobbleMaterialProps & {
+	ref?: ThreeRef<WobbleMaterialImpl>;
+}) @{
+	const [material] = useState(() => new WobbleMaterialImpl());
+	const mergedRef = useMemo(() => (value: WobbleMaterialImpl | null) => assignRef(ref, value), [ref]);
+	useFrame((state) => (material.time = state.clock.elapsedTime * speed));
+	<primitive object={material} ref={mergedRef} attach="material" {...props as any} />
+}
+
+function assignRef<T>(ref: ThreeRef<T> | undefined, value: T | null): void {
+	if (Array.isArray(ref)) for (const item of ref) assignRef(item, value);
+	else if (typeof ref === 'function') ref(value);
+	else if (ref && 'current' in ref) ref.current = value;
+}

package/src/core/octane-children.ts

@@ -0,0 +1,18 @@
+import { isChildrenBlock } from 'octane';
+import type { OctaneNode } from 'octane';
+
+// Compiler-generated TSRX children blocks are zero-argument functions and are
+// structurally assignable to this callback shape. Keep the public type focused
+// on the upstream render-prop contract so callback parameters remain contextual.
+export type RenderChildren<T> = (value: T) => OctaneNode;
+
+export function isRenderFunction(value: unknown): value is (...args: any[]) => unknown {
+	return typeof value === 'function' && !isChildrenBlock(value);
+}
+
+export function resolveRenderChildren<T>(
+	children: RenderChildren<T> | undefined,
+	value: T,
+): unknown {
+	return isRenderFunction(children) ? children(value) : children;
+}

package/src/core/octane-element.ts

@@ -0,0 +1,16 @@
+import { isChildrenBlock, isValidElement } from 'octane';
+
+/** Keeps renderer-neutral element detection outside universal compiler imports. */
+export const isOctaneElement: typeof isValidElement = isValidElement;
+
+/** Distinguishes compiled child blocks from user-authored render-prop functions. */
+export const isOctaneChildrenBlock: typeof isChildrenBlock = isChildrenBlock;
+
+/** Iterates universal child values, whose descriptors intentionally differ from DOM elements. */
+export function forEachOctaneChild(children: unknown, visit: (child: unknown) => void): void {
+	if (Array.isArray(children)) {
+		for (const child of children) forEachOctaneChild(child, visit);
+	} else if (children !== null && children !== undefined && typeof children !== 'boolean') {
+		visit(children);
+	}
+}

package/src/core/resource.ts

@@ -0,0 +1,29 @@
+type Key = readonly unknown[];
+
+interface ResourceEntry<T = unknown> {
+	readonly keys: Key;
+	readonly promise: Promise<T>;
+}
+
+const entries: ResourceEntry[] = [];
+
+function equalKeys(previous: Key, next: Key): boolean {
+	return previous.length === next.length && previous.every((value, index) => value === next[index]);
+}
+
+export function resourcePromise<T>(loader: (...keys: any[]) => Promise<T>, keys: Key): Promise<T> {
+	const cached = entries.find((entry) => equalKeys(entry.keys, keys));
+	if (cached !== undefined) return cached.promise as Promise<T>;
+	const entry: ResourceEntry<T> = { keys: [...keys], promise: loader(...keys) };
+	entries.push(entry);
+	return entry.promise;
+}
+
+export function preloadResource<T>(loader: (...keys: any[]) => Promise<T>, keys: Key): void {
+	void resourcePromise(loader, keys);
+}
+
+export function clearResource(keys: Key): void {
+	const index = entries.findIndex((entry) => equalKeys(entry.keys, keys));
+	if (index !== -1) entries.splice(index, 1);
+}

package/src/core/scene-motion.three.tsrx

@@ -0,0 +1,183 @@
+/** @jsxImportSource @octanejs/three/intrinsics */
+import { type ThreeElements, type ThreeRef, useFrame } from '@octanejs/three';
+import { useEffect, useLayoutEffect, useMemo, useRef } from '@octanejs/three/renderer';
+import * as THREE from 'three';
+
+function assignRef<T>(ref: ThreeRef<T> | undefined, value: T | null): void {
+	if (Array.isArray(ref)) {
+		for (const item of ref) assignRef(item, value);
+	} else if (typeof ref === 'function') ref(value);
+	else if (ref && 'current' in ref) ref.current = value;
+}
+
+export type BillboardProps =
+	Omit<ThreeElements['group'], 'ref'> & {
+		follow?: boolean;
+		lockX?: boolean;
+		lockY?: boolean;
+		lockZ?: boolean;
+	};
+
+export function Billboard({
+	children,
+	follow = true,
+	lockX = false,
+	lockY = false,
+	lockZ = false,
+	ref,
+	...props
+}: BillboardProps & { ref?: ThreeRef<THREE.Group> }) @{
+	const inner = useRef<THREE.Group | null>(null);
+	const localRef = useRef<THREE.Group | null>(null);
+	const quaternion = useMemo(() => new THREE.Quaternion(), []);
+	const mergedRef = useMemo(
+		() => (value: THREE.Group | null) => {
+			localRef.current = value;
+			assignRef(ref, value);
+		},
+		[ref],
+	);
+	useFrame(({ camera }) => {
+		if (!follow || !localRef.current || !inner.current) return;
+		const previousRotation = inner.current.rotation.clone();
+		localRef.current.updateMatrix();
+		localRef.current.updateWorldMatrix(false, false);
+		localRef.current.getWorldQuaternion(quaternion);
+		camera.getWorldQuaternion(inner.current.quaternion).premultiply(quaternion.invert());
+		if (lockX) inner.current.rotation.x = previousRotation.x;
+		if (lockY) inner.current.rotation.y = previousRotation.y;
+		if (lockZ) inner.current.rotation.z = previousRotation.z;
+	});
+	<group ref={mergedRef} {...props}>
+		<group ref={inner}>{children}</group>
+	</group>
+}
+
+export type FloatProps =
+	Omit<ThreeElements['group'], 'ref'> & {
+		enabled?: boolean;
+		speed?: number;
+		rotationIntensity?: number;
+		floatIntensity?: number;
+		floatingRange?: [number?, number?];
+		autoInvalidate?: boolean;
+	};
+
+export function Float({
+	children,
+	enabled = true,
+	speed = 1,
+	rotationIntensity = 1,
+	floatIntensity = 1,
+	floatingRange = [-0.1, 0.1],
+	autoInvalidate = false,
+	ref,
+	...props
+}: FloatProps & { ref?: ThreeRef<THREE.Group> }) @{
+	const inner = useRef<THREE.Group | null>(null);
+	const offset = useRef(Math.random() * 10000);
+	const mergedRef = useMemo(
+		() => (value: THREE.Group | null) => {
+			inner.current = value;
+			assignRef(ref, value);
+		},
+		[ref],
+	);
+	useFrame((state) => {
+		if (!enabled || speed === 0 || !inner.current) return;
+		if (autoInvalidate) state.invalidate();
+		const time = offset.current + state.clock.elapsedTime;
+		inner.current.rotation.x = (Math.cos((time / 4) * speed) / 8) * rotationIntensity;
+		inner.current.rotation.y = (Math.sin((time / 4) * speed) / 8) * rotationIntensity;
+		inner.current.rotation.z = (Math.sin((time / 4) * speed) / 20) * rotationIntensity;
+		const base = Math.sin((time / 4) * speed) / 10;
+		inner.current.position.y = THREE.MathUtils.mapLinear(
+			base,
+			-0.1,
+			0.1,
+			floatingRange[0] ?? -0.1,
+			floatingRange[1] ?? 0.1,
+		) *
+		floatIntensity;
+		inner.current.updateMatrix();
+	});
+	<group {...props}>
+		<group ref={mergedRef} matrixAutoUpdate={false}>{children}</group>
+	</group>
+}
+
+const easeInExpo = (value: number) => (value === 0 ? 0 : Math.pow(2, 10 * value - 10));
+
+export type BackdropProps =
+	ThreeElements['group'] & {
+		floor?: number;
+		segments?: number;
+		receiveShadow?: boolean;
+	};
+
+export function Backdrop({
+	children,
+	floor = 0.25,
+	segments = 20,
+	receiveShadow,
+	...props
+}: BackdropProps) @{
+	const geometry = useRef<THREE.PlaneGeometry | null>(null);
+	useLayoutEffect(() => {
+		if (!geometry.current) return;
+		let index = 0;
+		const offset = segments / segments / 2;
+		const position = geometry.current.attributes.position as THREE.BufferAttribute;
+		for (let x = 0; x < segments + 1; x++) {
+			for (let y = 0; y < segments + 1; y++) {
+				position.setXYZ(
+					index++,
+					x / segments - offset + (x === 0 ? -floor : 0),
+					y / segments - offset,
+					easeInExpo(x / segments),
+				);
+			}
+		}
+		position.needsUpdate = true;
+		geometry.current.computeVertexNormals();
+	}, [segments, floor]);
+	<group {...props}>
+		<mesh receiveShadow={receiveShadow} rotation={[-Math.PI / 2, 0, Math.PI / 2]}>
+			<planeGeometry ref={geometry} args={[1, 1, segments, segments]} />
+			{children}
+		</mesh>
+	</group>
+}
+
+const boundingBox = new THREE.Box3();
+const boundingBoxSize = new THREE.Vector3();
+
+export type BBAnchorProps =
+	ThreeElements['group'] & {
+		anchor: THREE.Vector3 | [number, number, number];
+	};
+
+export function BBAnchor({ anchor, ...props }: BBAnchorProps) @{
+	const ref = useRef<THREE.Group | null>(null);
+	const parentRef = useRef<THREE.Object3D | null>(null);
+	useEffect(() => {
+		if (ref.current?.parent?.parent) {
+			parentRef.current = ref.current.parent;
+			ref.current.parent.parent.add(ref.current);
+		}
+	}, []);
+	useFrame(() => {
+		if (!parentRef.current || !ref.current) return;
+		boundingBox.setFromObject(parentRef.current);
+		boundingBox.getSize(boundingBoxSize);
+		ref.current.position.set(
+			parentRef.current.position.x +
+				(boundingBoxSize.x * (Array.isArray(anchor) ? anchor[0] : anchor.x)) / 2,
+			parentRef.current.position.y +
+				(boundingBoxSize.y * (Array.isArray(anchor) ? anchor[1] : anchor.y)) / 2,
+			parentRef.current.position.z +
+				(boundingBoxSize.z * (Array.isArray(anchor) ? anchor[2] : anchor.z)) / 2,
+		);
+	});
+	<group ref={ref} {...props} />
+}