@octanejs/drei 0.0.1

package/src/core/Outlines.three.tsrx

@@ -0,0 +1,162 @@
+/** @jsxImportSource @octanejs/three/intrinsics */
+import { applyProps, type ThreeElements, useThree } from '@octanejs/three';
+import { useEffect, useLayoutEffect, useRef, useState } from '@octanejs/three/renderer';
+import * as THREE from 'three';
+import { toCreasedNormals } from 'three-stdlib';
+import { shaderMaterial } from './shaderMaterial.js';
+
+const OutlinesMaterial = shaderMaterial(
+	{
+		screenspace: false,
+		color: new THREE.Color('black'),
+		opacity: 1,
+		thickness: 0.05,
+		size: new THREE.Vector2(),
+	},
+	`#include <common>
+   #include <morphtarget_pars_vertex>
+   #include <skinning_pars_vertex>
+   #include <clipping_planes_pars_vertex>
+   uniform float thickness;
+   uniform bool screenspace;
+   uniform vec2 size;
+   void main() {
+     #if defined (USE_SKINNING)
+	     #include <beginnormal_vertex>
+       #include <morphnormal_vertex>
+       #include <skinbase_vertex>
+       #include <skinnormal_vertex>
+       #include <defaultnormal_vertex>
+     #endif
+     #include <begin_vertex>
+	   #include <morphtarget_vertex>
+	   #include <skinning_vertex>
+     #include <project_vertex>
+     #include <clipping_planes_vertex>
+     vec4 tNormal = vec4(normal, 0.0);
+     vec4 tPosition = vec4(transformed, 1.0);
+     #ifdef USE_INSTANCING
+       tNormal = instanceMatrix * tNormal;
+       tPosition = instanceMatrix * tPosition;
+     #endif
+     if (screenspace) {
+       vec3 newPosition = tPosition.xyz + tNormal.xyz * thickness;
+       gl_Position = projectionMatrix * modelViewMatrix * vec4(newPosition, 1.0);
+     } else {
+       vec4 clipPosition = projectionMatrix * modelViewMatrix * tPosition;
+       vec4 clipNormal = projectionMatrix * modelViewMatrix * tNormal;
+       vec2 offset = normalize(clipNormal.xy) * thickness / size * clipPosition.w * 2.0;
+       clipPosition.xy += offset;
+       gl_Position = clipPosition;
+     }
+   }`,
+	`uniform vec3 color;
+   uniform float opacity;
+   #include <clipping_planes_pars_fragment>
+   void main(){
+     #include <clipping_planes_fragment>
+     gl_FragColor = vec4(color, opacity);
+     #include <tonemapping_fragment>
+     #include <colorspace_fragment>
+   }`,
+);
+
+export type OutlinesProps = Omit<ThreeElements['group'], 'ref'> & {
+	color?: ThreeElements['meshBasicMaterial']['color'];
+	screenspace?: boolean;
+	opacity?: number;
+	transparent?: boolean;
+	thickness?: number;
+	angle?: number;
+	clippingPlanes?: THREE.Plane[];
+	toneMapped?: boolean;
+	polygonOffset?: boolean;
+	polygonOffsetFactor?: number;
+	renderOrder?: number;
+};
+
+export function Outlines({
+	color = 'black',
+	opacity = 1,
+	transparent = false,
+	screenspace = false,
+	toneMapped = true,
+	polygonOffset = false,
+	polygonOffsetFactor = 0,
+	renderOrder = 0,
+	thickness = 0.05,
+	angle = Math.PI,
+	clippingPlanes,
+	...props
+}: OutlinesProps) @{
+	const groupRef = useRef<THREE.Group | null>(null);
+	const [material] = useState(() => new OutlinesMaterial({ side: THREE.BackSide }));
+	const gl = useThree((state) => state.gl);
+	const size = useThree((state) => state.size);
+	const contextSize = typeof (gl as any).getDrawingBufferSize === 'function'
+		? (gl as any).getDrawingBufferSize(new THREE.Vector2())
+		: new THREE.Vector2(size.width, size.height);
+	const oldAngle = useRef(0);
+	const oldGeometry = useRef<THREE.BufferGeometry | null>(null);
+	useLayoutEffect(() => {
+		const group = groupRef.current;
+		if (!group) return;
+		const parent = group.parent as THREE.Mesh & THREE.SkinnedMesh & THREE.InstancedMesh;
+		if (!parent?.geometry || (oldAngle.current === angle && oldGeometry.current === parent.geometry)) return;
+		oldAngle.current = angle;
+		oldGeometry.current = parent.geometry;
+		let mesh = group.children[0] as any;
+		if (mesh) {
+			if (angle) mesh.geometry.dispose();
+			group.remove(mesh);
+		}
+		if (parent.skeleton) {
+			mesh = new THREE.SkinnedMesh();
+			mesh.material = material;
+			mesh.bind(parent.skeleton, parent.bindMatrix);
+		} else if (parent.isInstancedMesh) {
+			mesh = new THREE.InstancedMesh(parent.geometry, material, parent.count);
+			mesh.instanceMatrix = parent.instanceMatrix;
+		} else {
+			mesh = new THREE.Mesh();
+			mesh.material = material;
+		}
+		group.add(mesh);
+		mesh.geometry = angle ? toCreasedNormals(parent.geometry as any, angle) as any : parent.geometry;
+		mesh.morphTargetInfluences = parent.morphTargetInfluences;
+		mesh.morphTargetDictionary = parent.morphTargetDictionary;
+	});
+	useLayoutEffect(() => {
+		const group = groupRef.current;
+		const mesh = group?.children[0] as THREE.Mesh<THREE.BufferGeometry, THREE.Material> | undefined;
+		if (!group || !mesh) return;
+		mesh.renderOrder = renderOrder;
+		const parent = group.parent as THREE.Mesh;
+		applyProps(mesh as any, {
+			morphTargetInfluences: parent.morphTargetInfluences,
+			morphTargetDictionary: parent.morphTargetDictionary,
+		});
+		applyProps(mesh.material as any, {
+			transparent,
+			thickness,
+			color,
+			opacity,
+			size: contextSize,
+			screenspace,
+			toneMapped,
+			polygonOffset,
+			polygonOffsetFactor,
+			clippingPlanes,
+			clipping: Boolean(clippingPlanes?.length),
+		});
+	});
+	useEffect(() => () => {
+		const group = groupRef.current;
+		const mesh = group?.children[0] as THREE.Mesh | undefined;
+		if (group && mesh) {
+			if (angle) mesh.geometry.dispose();
+			group.remove(mesh);
+		}
+	}, []);
+	<group ref={groupRef} {...props} />
+}

package/src/core/PerformanceMonitor.three.tsrx

@@ -0,0 +1,144 @@
+/** @jsxImportSource @octanejs/three/intrinsics */
+import { useFrame } from '@octanejs/three';
+import {
+	createContext,
+	useContext,
+	useLayoutEffect,
+	useRef,
+	useState,
+} from '@octanejs/three/renderer';
+import type { OctaneNode } from 'octane';
+
+type PerformanceMonitorHookApi = {
+	onIncline: (api: PerformanceMonitorApi) => void;
+	onDecline: (api: PerformanceMonitorApi) => void;
+	onChange: (api: PerformanceMonitorApi) => void;
+	onFallback: (api: PerformanceMonitorApi) => void;
+};
+
+export type PerformanceMonitorApi = {
+	fps: number;
+	factor: number;
+	refreshrate: number;
+	frames: number[];
+	averages: number[];
+	index: number;
+	flipped: number;
+	fallback: boolean;
+	subscriptions: Map<symbol, Partial<PerformanceMonitorHookApi>>;
+	subscribe: (ref: { current: Partial<PerformanceMonitorHookApi> }) => () => void;
+};
+
+export type PerformanceMonitorProps = {
+	ms?: number;
+	iterations?: number;
+	threshold?: number;
+	bounds?: (refreshrate: number) => [lower: number, upper: number];
+	flipflops?: number;
+	factor?: number;
+	step?: number;
+	onIncline?: (api: PerformanceMonitorApi) => void;
+	onDecline?: (api: PerformanceMonitorApi) => void;
+	onChange?: (api: PerformanceMonitorApi) => void;
+	onFallback?: (api: PerformanceMonitorApi) => void;
+	children?: OctaneNode;
+};
+
+const context = createContext<PerformanceMonitorApi>(null!);
+
+export function PerformanceMonitor({
+	iterations = 10,
+	ms = 250,
+	threshold = 0.75,
+	step = 0.1,
+	factor: initialFactor = 0.5,
+	flipflops = Infinity,
+	bounds = (refreshrate) => (refreshrate > 100 ? [60, 100] : [40, 60]),
+	onIncline,
+	onDecline,
+	onChange,
+	onFallback,
+	children,
+}: PerformanceMonitorProps) @{
+	const decimalPlacesRatio = Math.pow(10, 0);
+	const [api] = useState<PerformanceMonitorApi>(() => ({
+		fps: 0,
+		index: 0,
+		factor: initialFactor,
+		flipped: 0,
+		refreshrate: 0,
+		fallback: false,
+		frames: [],
+		averages: [],
+		subscriptions: new Map(),
+		subscribe: (ref) => {
+			const key = Symbol();
+			api.subscriptions.set(key, ref.current);
+			return () => void api.subscriptions.delete(key);
+		},
+	}));
+
+	let lastFactor = 0;
+	useFrame(() => {
+		const { frames, averages } = api;
+		if (api.fallback) return;
+		if (averages.length < iterations) {
+			frames.push(performance.now());
+			const msPassed = frames[frames.length - 1] - frames[0];
+			if (msPassed >= ms) {
+				api.fps =
+					Math.round((frames.length / msPassed) * 1000 * decimalPlacesRatio) /
+					decimalPlacesRatio;
+				api.refreshrate = Math.max(api.refreshrate, api.fps);
+				averages[api.index++ % iterations] = api.fps;
+				if (averages.length === iterations) {
+					const [lower, upper] = bounds(api.refreshrate);
+					const upperBounds = averages.filter((value) => value >= upper);
+					const lowerBounds = averages.filter((value) => value < lower);
+					if (upperBounds.length > iterations * threshold) {
+						api.factor = Math.min(1, api.factor + step);
+						api.flipped++;
+						onIncline?.(api);
+						api.subscriptions.forEach((value) => value.onIncline?.(api));
+					}
+					if (lowerBounds.length > iterations * threshold) {
+						api.factor = Math.max(0, api.factor - step);
+						api.flipped++;
+						onDecline?.(api);
+						api.subscriptions.forEach((value) => value.onDecline?.(api));
+					}
+					if (lastFactor !== api.factor) {
+						lastFactor = api.factor;
+						onChange?.(api);
+						api.subscriptions.forEach((value) => value.onChange?.(api));
+					}
+					if (api.flipped > flipflops && !api.fallback) {
+						api.fallback = true;
+						onFallback?.(api);
+						api.subscriptions.forEach((value) => value.onFallback?.(api));
+					}
+					api.averages = [];
+				}
+				api.frames = [];
+			}
+		}
+	});
+	<context.Provider value={api}>{children}</context.Provider>
+}
+
+export function usePerformanceMonitor({
+	onIncline,
+	onDecline,
+	onChange,
+	onFallback,
+}: Partial<PerformanceMonitorHookApi>): void {
+	const api = useContext(context);
+	const ref = useRef({ onIncline, onDecline, onChange, onFallback });
+	useLayoutEffect(() => {
+		ref.current.onIncline = onIncline;
+		ref.current.onDecline = onDecline;
+		ref.current.onChange = onChange;
+		ref.current.onFallback = onFallback;
+	}, [onIncline, onDecline, onChange, onFallback]);
+	useLayoutEffect(() => api.subscribe(ref), [api]);
+}

package/src/core/PointerLockControls.three.tsrx

@@ -0,0 +1,84 @@
+/** @jsxImportSource @octanejs/three/intrinsics */
+import { type RootState, type ThreeElement, type ThreeRef, useThree } from '@octanejs/three';
+import { useEffect, useMemo } from '@octanejs/three/renderer';
+import type * as THREE from 'three';
+import { PointerLockControls as PointerLockControlsImpl } from 'three-stdlib';
+
+export type PointerLockControlsProps =
+	Omit<ThreeElement<typeof PointerLockControlsImpl>, 'ref' | 'args'> & {
+		domElement?: HTMLElement;
+		selector?: string;
+		enabled?: boolean;
+		camera?: THREE.Camera;
+		onChange?: (event?: THREE.Event) => void;
+		onLock?: (event?: THREE.Event) => void;
+		onUnlock?: (event?: THREE.Event) => void;
+		makeDefault?: boolean;
+	};
+
+export function PointerLockControls({
+	domElement,
+	selector,
+	onChange,
+	onLock,
+	onUnlock,
+	enabled = true,
+	makeDefault,
+	camera,
+	ref,
+	...props
+}: PointerLockControlsProps & { ref?: ThreeRef<PointerLockControlsImpl> }) @{
+	const state = useThree();
+	const explicitCamera = camera || state.camera;
+	const explicitElement = (domElement || state.events.connected ||
+		state.gl.domElement) as HTMLElement;
+	const controls = useMemo(() => new PointerLockControlsImpl(explicitCamera as any), [
+		explicitCamera,
+	]);
+	useEffect(() => {
+		if (!enabled) return;
+		controls.connect(explicitElement);
+		const oldCompute = state.get().events.compute;
+		state.setEvents({
+			compute(_event: unknown, rootState: RootState) {
+				const offsetX = rootState.size.width / 2;
+				const offsetY = rootState.size.height / 2;
+				rootState.pointer.set(
+					(offsetX / rootState.size.width) * 2 - 1,
+					-(offsetY / rootState.size.height) * 2 + 1,
+				);
+				rootState.raycaster.setFromCamera(rootState.pointer, rootState.camera);
+			},
+		});
+		return () => {
+			controls.disconnect();
+			state.setEvents({ compute: oldCompute });
+		};
+	}, [enabled, controls]);
+	useEffect(() => {
+		const change = (event: any) => {
+			state.invalidate();
+			onChange?.(event);
+		};
+		controls.addEventListener('change', change);
+		if (onLock) controls.addEventListener('lock', onLock as any);
+		if (onUnlock) controls.addEventListener('unlock', onUnlock as any);
+		const handler = () => controls.lock();
+		const elements =
+			selector ? Array.from(document.querySelectorAll(selector)) : [document];
+		for (const element of elements) element?.addEventListener('click', handler);
+		return () => {
+			controls.removeEventListener('change', change);
+			if (onLock) controls.removeEventListener('lock', onLock as any);
+			if (onUnlock) controls.removeEventListener('unlock', onUnlock as any);
+			for (const element of elements) element?.removeEventListener('click', handler);
+		};
+	}, [onChange, onLock, onUnlock, selector, controls, state.invalidate]);
+	useEffect(() => {
+		if (!makeDefault) return;
+		const old = state.get().controls;
+		state.set({ controls } as any);
+		return () => state.set({ controls: old } as any);
+	}, [makeDefault, controls]);
+	<primitive ref={ref as any} object={controls} {...props as any} />
+}

package/src/core/Points.three.tsrx

@@ -0,0 +1,242 @@
+/** @jsxImportSource @octanejs/three/intrinsics */
+import {
+	extend,
+	type ThreeElement,
+	type ThreeElements,
+	type ThreeRef,
+	useFrame,
+} from '@octanejs/three';
+import {
+	useEffect,
+	useLayoutEffect,
+	useMemo,
+	useRef,
+	useState,
+} from '@octanejs/three/renderer';
+import { createContext, type OctaneNode, useContext } from 'octane';
+import * as THREE from 'three';
+
+type PointRef = { current: PositionPoint | null };
+type PointsRef = { current: THREE.Points | null };
+
+type Api = {
+	getParent: () => PointsRef;
+	subscribe: (ref: PointRef) => () => void;
+};
+
+export type PointsInstancesProps = Omit<ThreeElements['points'], 'ref'> & {
+	range?: number;
+	limit?: number;
+	children?: OctaneNode;
+};
+
+const inverseMatrix = new THREE.Matrix4();
+const ray = new THREE.Ray();
+const sphere = new THREE.Sphere();
+const worldPosition = new THREE.Vector3();
+
+export class PositionPoint extends THREE.Group {
+	size = 0;
+	color = new THREE.Color('white');
+	instance: PointsRef = { current: null };
+	instanceKey: PointRef = { current: null };
+
+	get geometry(): THREE.BufferGeometry | undefined {
+		return this.instance.current?.geometry;
+	}
+
+	override raycast(raycaster: THREE.Raycaster, intersects: THREE.Intersection[]): void {
+		const parent = this.instance.current;
+		if (!parent?.geometry) return;
+		const instances = parent.userData.instances as PointRef[];
+		const instanceId = instances.indexOf(this.instanceKey);
+		if (instanceId === -1 || instanceId > parent.geometry.drawRange.count) return;
+
+		const threshold = raycaster.params.Points?.threshold ?? 1;
+		sphere.set(this.getWorldPosition(worldPosition), threshold);
+		if (!raycaster.ray.intersectsSphere(sphere)) return;
+
+		inverseMatrix.copy(parent.matrixWorld).invert();
+		ray.copy(raycaster.ray).applyMatrix4(inverseMatrix);
+
+		const localThreshold = threshold / ((this.scale.x + this.scale.y + this.scale.z) / 3);
+		const rayPointDistanceSq = ray.distanceSqToPoint(this.position);
+		if (rayPointDistanceSq < localThreshold * localThreshold) {
+			const intersectPoint = new THREE.Vector3();
+			ray.closestPointToPoint(this.position, intersectPoint);
+			intersectPoint.applyMatrix4(this.matrixWorld);
+			const distance = raycaster.ray.origin.distanceTo(intersectPoint);
+			if (distance < raycaster.near || distance > raycaster.far) return;
+			intersects.push({
+				distance,
+				distanceToRay: Math.sqrt(rayPointDistanceSq),
+				point: intersectPoint,
+				index: instanceId,
+				face: null,
+				object: this,
+			});
+		}
+	}
+}
+
+const PositionPointElement = extend(PositionPoint);
+const PointsContext = createContext<Api | null>(null);
+const parentMatrix = new THREE.Matrix4();
+const localPosition = new THREE.Vector3();
+
+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;
+}
+
+function PointsInstances({
+	children,
+	range,
+	limit = 1000,
+	ref,
+	...props
+}: PointsInstancesProps & { ref?: ThreeRef<THREE.Points> }) @{
+	const parentRef = useRef<THREE.Points | null>(null);
+	const [refs, setRefs] = useState<PointRef[]>([]);
+	const [[positions, colors, sizes]] = useState(() => [
+		new Float32Array(limit * 3),
+		Float32Array.from({ length: limit * 3 }, () => 1),
+		Float32Array.from({ length: limit }, () => 1),
+	]);
+	const mergedRef = useMemo(
+		() => (value: THREE.Points | null) => {
+			parentRef.current = value;
+			assignRef(ref, value);
+		},
+		[ref],
+	);
+	const api = useMemo<Api>(() => ({
+		getParent: () => parentRef,
+		subscribe(pointRef) {
+			setRefs((current) => [...current, pointRef]);
+			return () => setRefs((current) => current.filter((item) => item.current !== pointRef.current));
+		},
+	}), []);
+
+	useEffect(() => {
+		const position = parentRef.current?.geometry.attributes.position;
+		if (position) position.needsUpdate = true;
+	});
+	useFrame(() => {
+		const parent = parentRef.current;
+		if (!parent) return;
+		parent.updateMatrix();
+		parent.updateMatrixWorld();
+		parentMatrix.copy(parent.matrixWorld).invert();
+		parent.geometry.drawRange.count = Math.min(limit, range ?? limit, refs.length);
+		for (let index = 0; index < refs.length; index++) {
+			const point = refs[index]?.current;
+			if (!point) continue;
+			point.getWorldPosition(localPosition).applyMatrix4(parentMatrix);
+			localPosition.toArray(positions, index * 3);
+			parent.geometry.attributes.position!.needsUpdate = true;
+			point.matrixWorldNeedsUpdate = true;
+			point.color.toArray(colors, index * 3);
+			parent.geometry.attributes.color!.needsUpdate = true;
+			sizes.set([point.size], index);
+			parent.geometry.attributes.size!.needsUpdate = true;
+		}
+	});
+
+	<points
+		userData={{ instances: refs }}
+		matrixAutoUpdate={false}
+		ref={mergedRef}
+		raycast={() => null}
+		{...props as any}
+	>
+		<bufferGeometry>
+			<bufferAttribute attach="attributes-position" args={[positions, 3]} usage={THREE.DynamicDrawUsage} />
+			<bufferAttribute attach="attributes-color" args={[colors, 3]} usage={THREE.DynamicDrawUsage} />
+			<bufferAttribute attach="attributes-size" args={[sizes, 1]} usage={THREE.DynamicDrawUsage} />
+		</bufferGeometry>
+		<PointsContext.Provider value={api}>{children}</PointsContext.Provider>
+	</points>
+}
+
+type PointProps = ThreeElement<typeof PositionPoint>;
+
+export function Point({ children, ref, ...props }: PointProps & {
+	ref?: ThreeRef<PositionPoint>;
+}) @{
+	const group = useRef<PositionPoint | null>(null);
+	const api = useContext(PointsContext);
+	if (!api) throw new Error('Point must be used inside Points component.');
+	const mergedRef = useMemo(
+		() => (value: PositionPoint | null) => {
+			group.current = value;
+			assignRef(ref, value);
+		},
+		[ref],
+	);
+	useLayoutEffect(() => api.subscribe(group), [api]);
+	<PositionPointElement
+		instance={api.getParent()}
+		instanceKey={group}
+		ref={mergedRef}
+		{...props as any}
+	>
+		{children}
+	</PositionPointElement>
+}
+
+export type PointsBuffersProps = Omit<ThreeElements['points'], 'ref'> & {
+	positions: Float32Array;
+	colors?: Float32Array;
+	sizes?: Float32Array;
+	stride?: 2 | 3;
+};
+
+export function PointsBuffer({
+	children,
+	positions,
+	colors,
+	sizes,
+	stride = 3,
+	ref,
+	...props
+}: PointsBuffersProps & { ref?: ThreeRef<THREE.Points> }) @{
+	const pointsRef = useRef<THREE.Points | null>(null);
+	const mergedRef = useMemo(
+		() => (value: THREE.Points | null) => {
+			pointsRef.current = value;
+			assignRef(ref, value);
+		},
+		[ref],
+	);
+	useFrame(() => {
+		const attributes = pointsRef.current?.geometry.attributes;
+		if (!attributes) return;
+		attributes.position!.needsUpdate = true;
+		if (colors) attributes.color!.needsUpdate = true;
+		if (sizes) attributes.size!.needsUpdate = true;
+	});
+	<points ref={mergedRef} {...props as any}>
+		<bufferGeometry>
+			<bufferAttribute attach="attributes-position" args={[positions, stride]} usage={THREE.DynamicDrawUsage} />
+			@if (colors) {
+				<bufferAttribute attach="attributes-color" args={[colors, stride]} count={colors.length / stride} usage={THREE.DynamicDrawUsage} />
+			}
+			@if (sizes) {
+				<bufferAttribute attach="attributes-size" args={[sizes, 1]} count={sizes.length / stride} usage={THREE.DynamicDrawUsage} />
+			}
+		</bufferGeometry>
+		{children}
+	</points>
+}
+
+export function Points(props: (PointsBuffersProps | PointsInstancesProps) & {
+	ref?: ThreeRef<THREE.Points>;
+}) @{
+	@if ((props as PointsBuffersProps).positions instanceof Float32Array) {
+		<PointsBuffer {...props as PointsBuffersProps} />
+	} @else {
+		<PointsInstances {...props as PointsInstancesProps} />
+	}
+}

package/src/core/PositionalAudio.three.tsrx

@@ -0,0 +1,76 @@
+/** @jsxImportSource @octanejs/three/intrinsics */
+import { type ThreeElement, type ThreeRef, useLoader, useThree } from '@octanejs/three';
+import {
+	useEffect,
+	useMemo,
+	useRef,
+	useState,
+} from '@octanejs/three/renderer';
+import {
+	AudioListener,
+	AudioLoader,
+	PositionalAudio as PositionalAudioImpl,
+} 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 PositionalAudioProps = Omit<
+	ThreeElement<typeof PositionalAudioImpl>,
+	'ref' | 'args'
+> & {
+	url: string;
+	distance?: number;
+	loop?: boolean;
+	ref?: ThreeRef<PositionalAudioImpl>;
+};
+
+export function PositionalAudio({
+	url,
+	distance = 1,
+	loop = true,
+	autoplay,
+	ref,
+	...props
+}: PositionalAudioProps) @{
+	const sound = useRef<PositionalAudioImpl | null>(null);
+	const mergedRef = useMemo(
+		() => (value: PositionalAudioImpl | null) => {
+			sound.current = value;
+			assignRef(ref, value);
+		},
+		[ref],
+	);
+	const camera = useThree((state) => state.camera);
+	const [listener] = useState(() => new AudioListener());
+	const buffer = useLoader(AudioLoader, url);
+
+	useEffect(() => {
+		const current = sound.current;
+		if (current) {
+			current.setBuffer(buffer);
+			current.setRefDistance(distance);
+			current.setLoop(loop);
+			if (autoplay && !current.isPlaying) current.play();
+		}
+	}, [buffer, camera, distance, loop]);
+
+	useEffect(() => {
+		const current = sound.current;
+		camera.add(listener);
+		return () => {
+			camera.remove(listener);
+			if (current) {
+				if (current.isPlaying) current.stop();
+				if (current.source && (current.source as { _connected?: boolean })._connected) {
+					current.disconnect();
+				}
+			}
+		};
+	}, []);
+
+	<positionalAudio ref={mergedRef} args={[listener]} autoplay={autoplay} {...props as any} />
+}