@octanejs/drei 0.0.1

package/src/web/Html.three.tsrx

@@ -0,0 +1,390 @@
+/** @jsxImportSource @octanejs/three/intrinsics */
+import {
+	DOMRegion,
+	type RefObject,
+	type ThreeElements,
+	type ThreeRef,
+	useFrame,
+	useThree,
+} from '@octanejs/three';
+import {
+	useImperativeHandle,
+	useLayoutEffect,
+	useMemo,
+	useRef,
+	useState,
+} from '@octanejs/three/renderer';
+import type { OctaneNode } from 'octane';
+import type { RendererRegion } from 'octane/universal';
+import {
+	Camera,
+	DoubleSide,
+	Group,
+	Matrix4,
+	Mesh,
+	Object3D,
+	OrthographicCamera,
+	PerspectiveCamera,
+	Raycaster,
+	Vector2,
+	Vector3,
+	WebGLRenderer,
+} from 'three';
+
+const v1 = new Vector3();
+const v2 = new Vector3();
+const v3 = new Vector3();
+const v4 = new Vector2();
+
+export function defaultCalculatePosition(
+	el: Object3D,
+	camera: Camera,
+	size: { width: number; height: number },
+): [number, number] {
+	const objectPos = v1.setFromMatrixPosition(el.matrixWorld).project(camera);
+	return [
+		objectPos.x * (size.width / 2) + size.width / 2,
+		-objectPos.y * (size.height / 2) + size.height / 2,
+	];
+}
+
+export type CalculatePosition = typeof defaultCalculatePosition;
+export type PointerEventsProperties = CSSStyleDeclaration['pointerEvents'];
+
+export interface HtmlProps extends Omit<ThreeElements['group'], 'children' | 'ref'> {
+	children?: OctaneNode;
+	ref?: ThreeRef<HTMLDivElement>;
+	prepend?: boolean;
+	center?: boolean;
+	fullscreen?: boolean;
+	eps?: number;
+	portal?: RefObject<HTMLElement | null>;
+	distanceFactor?: number;
+	sprite?: boolean;
+	transform?: boolean;
+	zIndexRange?: [number, number] | number[];
+	calculatePosition?: CalculatePosition;
+	as?: keyof HTMLElementTagNameMap | string;
+	wrapperClass?: string;
+	className?: string;
+	style?: Partial<CSSStyleDeclaration> & Record<string, unknown>;
+	pointerEvents?: PointerEventsProperties;
+	occlude?: RefObject<Object3D | null>[] | boolean | 'raycast' | 'blending';
+	onOcclude?: (hidden: boolean) => void;
+	material?: OctaneNode;
+	geometry?: OctaneNode;
+	castShadow?: boolean;
+	receiveShadow?: boolean;
+}
+
+function isObjectBehindCamera(el: Object3D, camera: Camera): boolean {
+	const delta = v1
+		.setFromMatrixPosition(el.matrixWorld)
+		.sub(v2.setFromMatrixPosition(camera.matrixWorld));
+	return delta.angleTo(camera.getWorldDirection(v3)) > Math.PI / 2;
+}
+
+function isObjectVisible(
+	el: Object3D,
+	camera: Camera,
+	raycaster: Raycaster,
+	occlude: Object3D[],
+): boolean {
+	const position = v1.setFromMatrixPosition(el.matrixWorld);
+	const projected = position.clone().project(camera);
+	raycaster.setFromCamera(v4.set(projected.x, projected.y), camera);
+	const intersection = raycaster.intersectObjects(occlude, true)[0];
+	return !intersection || position.distanceTo(raycaster.ray.origin) < intersection.distance;
+}
+
+function objectScale(el: Object3D, camera: Camera): number {
+	if (camera instanceof OrthographicCamera) return camera.zoom;
+	if (!(camera instanceof PerspectiveCamera)) return 1;
+	const distance = v1
+		.setFromMatrixPosition(el.matrixWorld)
+		.distanceTo(v2.setFromMatrixPosition(camera.matrixWorld));
+	return 1 / (2 * Math.tan((camera.fov * Math.PI) / 360) * distance);
+}
+
+function objectZIndex(el: Object3D, camera: Camera, range: readonly number[]): number | undefined {
+	if (!(camera instanceof PerspectiveCamera || camera instanceof OrthographicCamera)) return undefined;
+	const distance = v1
+		.setFromMatrixPosition(el.matrixWorld)
+		.distanceTo(v2.setFromMatrixPosition(camera.matrixWorld));
+	const slope = (range[1] - range[0]) / (camera.far - camera.near);
+	return Math.round(slope * distance + range[1] - slope * camera.far);
+}
+
+const epsilon = (value: number) => (Math.abs(value) < 1e-10 ? 0 : value);
+
+function cssMatrix(matrix: Matrix4, multipliers: number[], prepend = ''): string {
+	return `${prepend}matrix3d(${matrix.elements
+		.map((value, index) => epsilon(value * multipliers[index]))
+		.join(',')})`;
+}
+
+const cameraMultipliers = [1, -1, 1, 1, 1, -1, 1, 1, 1, -1, 1, 1, 1, -1, 1, 1];
+const objectMultipliers = (factor: number) => [
+	1 / factor, 1 / factor, 1 / factor, 1,
+	-1 / factor, -1 / factor, -1 / factor, -1,
+	1 / factor, 1 / factor, 1 / factor, 1,
+	1, 1, 1, 1,
+];
+
+const NON_TRANSFORM_VERTEX_SHADER = `
+  /*
+    This shader is from the THREE's SpriteMaterial.
+    We need to turn the backing plane into a Sprite
+    (make it always face the camera) if "transfrom"
+    is false.
+  */
+  #include <common>
+
+  void main() {
+    vec2 center = vec2(0., 1.);
+    float rotation = 0.0;
+
+    // This is somewhat arbitrary, but it seems to work well
+    // Need to figure out how to derive this dynamically if it even matters
+    float size = 0.03;
+
+    vec4 mvPosition = modelViewMatrix * vec4( 0.0, 0.0, 0.0, 1.0 );
+    vec2 scale;
+    scale.x = length( vec3( modelMatrix[ 0 ].x, modelMatrix[ 0 ].y, modelMatrix[ 0 ].z ) );
+    scale.y = length( vec3( modelMatrix[ 1 ].x, modelMatrix[ 1 ].y, modelMatrix[ 1 ].z ) );
+
+    bool isPerspective = isPerspectiveMatrix( projectionMatrix );
+    if ( isPerspective ) scale *= - mvPosition.z;
+
+    vec2 alignedPosition = ( position.xy - ( center - vec2( 0.5 ) ) ) * scale * size;
+    vec2 rotatedPosition;
+    rotatedPosition.x = cos( rotation ) * alignedPosition.x - sin( rotation ) * alignedPosition.y;
+    rotatedPosition.y = sin( rotation ) * alignedPosition.x + cos( rotation ) * alignedPosition.y;
+    mvPosition.xy += rotatedPosition;
+
+    gl_Position = projectionMatrix * mvPosition;
+  }
+`;
+
+const TRANSPARENT_FRAGMENT_SHADER = `
+  void main() {
+    gl_FragColor = vec4(0.0, 0.0, 0.0, 0.0);
+  }
+`;
+
+function assignStyle(element: HTMLElement, style: HtmlProps['style']): void {
+	if (!style) return;
+	for (const [key, value] of Object.entries(style)) {
+		if (value !== undefined && value !== null) (element.style as any)[key] = value;
+	}
+}
+
+export function Html({
+	children,
+	ref: forwardedRef,
+	eps = 0.001,
+	style,
+	className,
+	prepend,
+	center,
+	fullscreen,
+	portal,
+	distanceFactor,
+	sprite = false,
+	transform = false,
+	occlude,
+	onOcclude,
+	castShadow,
+	receiveShadow,
+	material,
+	geometry,
+	zIndexRange = [16777271, 0],
+	calculatePosition = defaultCalculatePosition,
+	as = 'div',
+	wrapperClass,
+	pointerEvents = 'auto',
+	...props
+}: HtmlProps) @{
+	const state = useThree();
+	const [el] = useState(() => document.createElement(as));
+	const [transformOuter] = useState(() => document.createElement('div'));
+	const [transformInner] = useState(() => document.createElement('div'));
+	const group = useRef<Group | null>(null);
+	const content = useRef<HTMLDivElement | null>(null);
+	const mesh = useRef<Mesh | null>(null);
+	const visible = useRef(true);
+	const oldZoom = useRef(0);
+	const oldPosition = useRef<[number, number]>([0, 0]);
+	const meshSized = useRef(false);
+	const isRaycastOcclusion = useMemo(
+		() => Boolean(occlude && occlude !== 'blending'),
+		[occlude],
+	);
+	const canvas = (state.gl as unknown as WebGLRenderer).domElement;
+	const target = (portal?.current ?? state.events.connected ?? canvas.parentNode) as HTMLElement;
+	const regionTarget = transform ? transformInner : el;
+
+	useImperativeHandle(
+		(forwardedRef ?? null) as any,
+		() => content.current!,
+		[el],
+	);
+
+	useLayoutEffect(() => {
+		const canvas = (state.gl as unknown as WebGLRenderer).domElement as HTMLCanvasElement;
+		if (occlude === 'blending') {
+			canvas.style.zIndex = `${Math.floor(zIndexRange[0] / 2)}`;
+			canvas.style.position = 'absolute';
+			canvas.style.pointerEvents = 'none';
+		} else {
+			canvas.style.zIndex = '';
+			canvas.style.position = '';
+			canvas.style.pointerEvents = '';
+		}
+	}, [state.gl, occlude, zIndexRange]);
+
+	useLayoutEffect(() => {
+		state.scene.updateMatrixWorld();
+		if (transform) {
+			el.style.cssText = 'position:absolute;top:0;left:0;pointer-events:none;overflow:hidden;';
+			if (transformOuter.parentElement !== el) el.append(transformOuter);
+			if (transformInner.parentElement !== transformOuter) transformOuter.append(transformInner);
+		}
+		else {
+			transformOuter.remove();
+			const position = group.current
+				? calculatePosition(group.current, state.camera, state.size)
+				: [0, 0];
+			el.style.cssText = `position:absolute;top:0;left:0;transform:translate3d(${position[0]}px,${position[1]}px,0);transform-origin:0 0;`;
+		}
+		if (prepend) target.prepend(el);
+		else target.append(el);
+		return () => el.remove();
+	}, [target, transform, prepend, el, transformOuter, transformInner, state.scene, state.camera, state.size, calculatePosition]);
+
+	useLayoutEffect(() => {
+		if (wrapperClass) el.className = wrapperClass;
+		meshSized.current = false;
+		const node = content.current;
+		if (!node) return;
+		node.className = className ?? '';
+		if (transform) {
+			transformOuter.style.cssText = `position:absolute;top:0;left:0;width:${state.size.width}px;height:${state.size.height}px;transform-style:preserve-3d;pointer-events:none;`;
+			transformInner.style.cssText = `position:absolute;pointer-events:${pointerEvents};`;
+			node.style.cssText = '';
+		} else {
+			node.style.cssText = `position:absolute;transform:${center ? 'translate3d(-50%,-50%,0)' : 'none'};`;
+		}
+		if (!transform && fullscreen) {
+			node.style.top = `${-state.size.height / 2}px`;
+			node.style.left = `${-state.size.width / 2}px`;
+			node.style.width = `${state.size.width}px`;
+			node.style.height = `${state.size.height}px`;
+		}
+		assignStyle(node, style);
+	}, [el, transformOuter, transformInner, wrapperClass, className, style, center, fullscreen, transform, pointerEvents, state.size]);
+
+	useFrame(() => {
+		const object = group.current;
+		if (!object) return;
+		state.camera.updateMatrixWorld();
+		object.updateWorldMatrix(true, false);
+		const position = transform ? oldPosition.current : calculatePosition(object, state.camera, state.size);
+		if (
+			transform ||
+			Math.abs(oldZoom.current - state.camera.zoom) > eps ||
+			Math.abs(oldPosition.current[0] - position[0]) > eps ||
+			Math.abs(oldPosition.current[1] - position[1]) > eps
+		) {
+			let shown = !isObjectBehindCamera(object, state.camera);
+			if (shown && isRaycastOcclusion) {
+				const targets = Array.isArray(occlude)
+					? occlude.map((item) => item.current).filter((item): item is Object3D => item !== null)
+					: [state.scene];
+				shown = isObjectVisible(object, state.camera, state.raycaster, targets);
+			}
+			if (visible.current !== shown) {
+				visible.current = shown;
+				if (onOcclude) onOcclude(!shown);
+				else el.style.display = shown ? 'block' : 'none';
+			}
+			const half = Math.floor(zIndexRange[0] / 2);
+			const range = occlude
+				? isRaycastOcclusion ? [zIndexRange[0], half] : [half - 1, 0]
+				: zIndexRange;
+			el.style.zIndex = `${objectZIndex(object, state.camera, range)}`;
+			if (transform) {
+				const fov = state.camera.projectionMatrix.elements[5] * state.size.height / 2;
+				const camera = state.camera as OrthographicCamera;
+				const cameraTransform = camera.isOrthographicCamera
+					? `scale(${fov})translate(${epsilon(-(camera.right + camera.left) / 2)}px,${epsilon((camera.top + camera.bottom) / 2)}px)`
+					: `translateZ(${fov}px)`;
+				let matrix = object.matrixWorld;
+				if (sprite) {
+					matrix = state.camera.matrixWorldInverse.clone().transpose().copyPosition(matrix).scale(object.scale);
+					matrix.elements[3] = matrix.elements[7] = matrix.elements[11] = 0;
+					matrix.elements[15] = 1;
+				}
+				el.style.width = `${state.size.width}px`;
+				el.style.height = `${state.size.height}px`;
+				el.style.perspective = camera.isOrthographicCamera ? '' : `${fov}px`;
+				transformOuter.style.transform = `${cameraTransform}${cssMatrix(state.camera.matrixWorldInverse, cameraMultipliers)}translate(${state.size.width / 2}px,${state.size.height / 2}px)`;
+				transformInner.style.transform = cssMatrix(
+					matrix,
+					objectMultipliers(1 / ((distanceFactor || 10) / 400)),
+					'translate(-50%,-50%)',
+				);
+			} else {
+				const scale = distanceFactor === undefined ? 1 : objectScale(object, state.camera) * distanceFactor;
+				el.style.transform = `translate3d(${position[0]}px,${position[1]}px,0) scale(${scale})`;
+			}
+			oldPosition.current = position;
+			oldZoom.current = state.camera.zoom;
+		}
+
+		const plane = mesh.current;
+		const node = content.current;
+		if (!isRaycastOcclusion && plane && !meshSized.current) {
+			if (transform) {
+				const measured = transformOuter.children[0] as HTMLElement | undefined;
+				if (measured?.clientWidth && measured.clientHeight) {
+					const camera = state.camera as OrthographicCamera;
+					if (camera.isOrthographicCamera || geometry) {
+						if (props.scale) {
+							if (!Array.isArray(props.scale)) plane.scale.setScalar(1 / (props.scale as number));
+							else if (props.scale instanceof Vector3) plane.scale.copy(props.scale.clone().divideScalar(1));
+							else plane.scale.set(1 / props.scale[0], 1 / props.scale[1], 1 / props.scale[2]);
+						}
+					} else {
+						const ratio = (distanceFactor || 10) / 400;
+						plane.scale.set(measured.clientWidth * ratio, measured.clientHeight * ratio, 1);
+					}
+					meshSized.current = true;
+				}
+			} else {
+				if (node?.clientWidth && node.clientHeight) {
+					const ratio = 1 / state.viewport.factor;
+					plane.scale.set(node.clientWidth * ratio, node.clientHeight * ratio, 1);
+					meshSized.current = true;
+				}
+				plane.lookAt(state.camera.position);
+			}
+		}
+	});
+
+	<group {...props} ref={group}>
+		<DOMRegion target={regionTarget} region={children as RendererRegion} containerRef={content} />
+		@if (occlude && !isRaycastOcclusion) {
+			<mesh ref={mesh} castShadow={castShadow} receiveShadow={receiveShadow}>
+				@if (geometry) { {geometry} } @else { <planeGeometry /> }
+				@if (material) { {material} } @else {
+					<shaderMaterial
+						side={DoubleSide}
+						vertexShader={transform ? undefined : NON_TRANSFORM_VERTEX_SHADER}
+						fragmentShader={TRANSPARENT_FRAGMENT_SHADER}
+					/>
+				}
+			</mesh>
+		}
+	</group>
+}

package/src/web/KeyboardControls.three.tsrx

@@ -0,0 +1,98 @@
+import { create } from '@octanejs/zustand/universal';
+import { subscribeWithSelector } from '@octanejs/zustand/middleware';
+import { createContext, type OctaneNode, useContext, useEffect, useMemo } from 'octane';
+import type {
+	KeyboardControlsApi,
+	KeyboardControlsState,
+	UseKeyboardControls,
+} from './keyboard-controls-types.js';
+
+export type KeyboardControlsEntry<T extends string = string> = {
+	name: T;
+	keys: string[];
+	up?: boolean;
+};
+
+export type KeyboardControlsProps = {
+	map: KeyboardControlsEntry[];
+	children: OctaneNode;
+	onChange?: (name: string, pressed: boolean, state: KeyboardControlsState) => void;
+	domElement?: HTMLElement;
+};
+
+const KeyboardContext = createContext<KeyboardControlsApi>(null!);
+
+export function KeyboardControls({ map, children, onChange, domElement }: KeyboardControlsProps) @{
+	const key = map.map((item) => item.name + item.keys).join('-');
+	const useControls = useMemo(
+		() => create(
+			subscribeWithSelector(
+				() => map.reduce(
+					(previous, current) => ({ ...previous, [current.name]: false }),
+					{} as KeyboardControlsState,
+				),
+			),
+		),
+		[key],
+	);
+	const api = useMemo<KeyboardControlsApi>(
+		() => [useControls.subscribe, useControls.getState, useControls],
+		[key],
+	);
+	const set = useControls.setState;
+	useEffect(() => {
+		const config = map.map(
+			({ name, keys, up }) => ({
+				keys,
+				up,
+				fn: (value: boolean) => {
+					set({ [name]: value });
+					onChange?.(name, value, api[1]());
+				},
+			}),
+		);
+		const keyMap = config.reduce<
+			Record<string, { fn(value: boolean): void; pressed: boolean; up: boolean }>
+		>((output, { keys, fn, up = true }) => {
+			keys.forEach((value) => (output[value] = { fn, pressed: false, up }));
+			return output;
+		}, {});
+		const downHandler = ({ key: value, code }: KeyboardEvent) => {
+			const object = keyMap[value] || keyMap[code];
+			if (!object) return;
+			const { fn, pressed, up } = object;
+			object.pressed = true;
+			if (up || !pressed) fn(true);
+		};
+		const upHandler = ({ key: value, code }: KeyboardEvent) => {
+			const object = keyMap[value] || keyMap[code];
+			if (!object) return;
+			const { fn, up } = object;
+			object.pressed = false;
+			if (up) fn(false);
+		};
+		const source = domElement || window;
+		source.addEventListener('keydown', downHandler as EventListener, { passive: true });
+		source.addEventListener('keyup', upHandler as EventListener, { passive: true });
+		return () => {
+			source.removeEventListener('keydown', downHandler as EventListener);
+			source.removeEventListener('keyup', upHandler as EventListener);
+		};
+	}, [domElement, key]);
+	<KeyboardContext.Provider value={api}>{children}</KeyboardContext.Provider>
+}
+
+type Selector<T extends string = string> = (state: KeyboardControlsState<T>) => boolean;
+
+export const useKeyboardControls: UseKeyboardControls = (
+	...rest: [selector?: Selector | symbol, slot?: symbol]
+) => {
+	const [subscribe, get, store] = useContext(KeyboardContext);
+	const tail = rest.at(-1);
+	const slot =
+		typeof tail === 'symbol' ? tail : undefined;
+	const selector =
+		typeof rest[0] === 'function' ? rest[0] : undefined;
+	if (selector) return (store as any)(selector, slot);
+	return [subscribe, get];
+};

package/src/web/Loader.tsrx

@@ -0,0 +1,61 @@
+import { useCallback, useEffect, useRef, useState, useSyncExternalStore } from 'octane';
+import { useProgress } from '../core/Progress.three.tsrx';
+
+type Style = Record<string, string | number>;
+interface LoaderOptions {
+	containerStyles: Style;
+	innerStyles: Style;
+	barStyles: Style;
+	dataStyles: Style;
+	dataInterpolation: (progress: number) => string;
+	initialState: (active: boolean) => boolean;
+}
+
+const defaultDataInterpolation = (progress: number) => `Loading ${progress.toFixed(2)}%`;
+
+export function Loader({
+	containerStyles,
+	innerStyles,
+	barStyles,
+	dataStyles,
+	dataInterpolation = defaultDataInterpolation,
+	initialState = (active: boolean) => active,
+}: Partial<LoaderOptions>) {
+	const { active, progress } = useSyncExternalStore(useProgress.subscribe, useProgress.getState, useProgress.getInitialState);
+	const progressRef = useRef(0);
+	const rafRef = useRef(0);
+	const progressSpanRef = useRef<HTMLSpanElement | null>(null);
+	const [shown, setShown] = useState(initialState(active));
+	useEffect(() => {
+		let timeout: ReturnType<typeof setTimeout> | undefined;
+		if (active !== shown) timeout = setTimeout(() => setShown(active), 300);
+		return () => { if (timeout !== undefined) clearTimeout(timeout); };
+	}, [shown, active]);
+	const updateProgress = useCallback(() => {
+		if (!progressSpanRef.current) return;
+		progressRef.current += (progress - progressRef.current) / 2;
+		if (progressRef.current > 0.95 * progress || progress === 100) progressRef.current = progress;
+		progressSpanRef.current.innerText = dataInterpolation(progressRef.current);
+		if (progressRef.current < progress) rafRef.current = requestAnimationFrame(updateProgress);
+	}, [dataInterpolation, progress]);
+	useEffect(() => {
+		updateProgress();
+		return () => cancelAnimationFrame(rafRef.current);
+	}, [updateProgress]);
+	if (!shown) return null;
+	return <div style={{ ...styles.container, opacity: active ? 1 : 0, ...containerStyles }}>
+		<div>
+			<div style={{ ...styles.inner, ...innerStyles }}>
+				<div style={{ ...styles.bar, transform: `scaleX(${progress / 100})`, ...barStyles }} />
+				<span ref={progressSpanRef} style={{ ...styles.data, ...dataStyles }} />
+			</div>
+		</div>
+	</div>;
+}
+
+const styles: Record<string, Style> = {
+	container: { position: 'absolute', top: 0, left: 0, width: '100%', height: '100%', background: '#171717', display: 'flex', alignItems: 'center', justifyContent: 'center', transition: 'opacity 300ms ease', zIndex: 1000 },
+	inner: { width: 100, height: 3, background: '#272727', textAlign: 'center' },
+	bar: { height: 3, width: '100%', background: 'white', transition: 'transform 200ms', transformOrigin: 'left center' },
+	data: { display: 'inline-block', position: 'relative', fontVariantNumeric: 'tabular-nums', marginTop: '0.8em', color: '#f0f0f0', fontSize: '0.6em', fontFamily: '-apple-system, BlinkMacSystemFont, "Inter", "Segoe UI", "Helvetica Neue", Helvetica, Arial, Roboto, Ubuntu, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol"', whiteSpace: 'nowrap' },
+};

package/src/web/PresentationControls.three.tsrx

@@ -0,0 +1,63 @@
+/** @jsxImportSource @octanejs/three/intrinsics */
+import { useFrame, useThree } from '@octanejs/three';
+import { useEffect, useMemo, useRef, useState } from '@octanejs/three/renderer';
+import { easing } from 'maath';
+import type { OctaneNode } from 'octane';
+import { Group, MathUtils } from 'three';
+import { useGesture } from './useGesture.js';
+
+export type PresentationControlProps = {
+	snap?: Boolean | number;
+	global?: boolean;
+	cursor?: boolean;
+	speed?: number;
+	zoom?: number;
+	rotation?: [number, number, number];
+	polar?: [number, number];
+	azimuth?: [number, number];
+	damping?: number;
+	enabled?: boolean;
+	children?: OctaneNode;
+	domElement?: HTMLElement;
+};
+
+export function PresentationControls({
+	enabled = true, snap, global, domElement, cursor = true, children, speed = 1, rotation = [0, 0, 0], zoom = 1,
+	polar = [0, Math.PI / 2], azimuth = [-Infinity, Infinity], damping = 0.25,
+}: PresentationControlProps) @{
+	const events = useThree((state) => state.events);
+	const gl = useThree((state) => state.gl);
+	const canvas = gl.domElement as HTMLElement;
+	const size = useThree((state) => state.size);
+	const target = domElement || events.connected || canvas;
+	const rPolar = useMemo(() => [rotation[0] + polar[0], rotation[0] + polar[1]] as [number, number], [rotation[0], polar[0], polar[1]]);
+	const rAzimuth = useMemo(() => [rotation[1] + azimuth[0], rotation[1] + azimuth[1]] as [number, number], [rotation[1], azimuth[0], azimuth[1]]);
+	const rInitial = useMemo(() => [MathUtils.clamp(rotation[0], ...rPolar), MathUtils.clamp(rotation[1], ...rAzimuth), rotation[2]], [rotation[0], rotation[1], rotation[2], rPolar, rAzimuth]);
+	useEffect(() => {
+		if (global && cursor && enabled) {
+			target.style.cursor = 'grab'; canvas.style.cursor = '';
+			return () => { target.style.cursor = 'default'; canvas.style.cursor = 'default'; };
+		}
+	}, [global, cursor, target, enabled]);
+	const [animation] = useState({ scale: 1, rotation: rInitial, damping });
+	const ref = useRef<Group | null>(null);
+	useFrame((_state, delta) => {
+		if (!ref.current) return;
+		easing.damp3(ref.current.scale, animation.scale, animation.damping, delta);
+		easing.dampE(ref.current.rotation, animation.rotation as any, animation.damping, delta);
+	});
+	const bind = useGesture({
+		onHover: ({ last }: any) => { if (cursor && !global && enabled) target.style.cursor = last ? 'auto' : 'grab'; },
+		onDrag: ({ down, delta: [deltaX, deltaY], memo: [oldY, oldX] = animation.rotation || rInitial }: any) => {
+			if (!enabled) return [deltaY, deltaX];
+			if (cursor) target.style.cursor = down ? 'grabbing' : 'grab';
+			const x = MathUtils.clamp(oldX + (deltaX / size.width) * Math.PI * speed, ...rAzimuth);
+			const y = MathUtils.clamp(oldY + (deltaY / size.height) * Math.PI * speed, ...rPolar);
+			animation.scale = down && y > rPolar[1] / 2 ? zoom : 1;
+			animation.rotation = snap && !down ? rInitial : [y, x, 0];
+			animation.damping = snap && !down && typeof snap !== 'boolean' ? snap as number : damping;
+			return [y, x];
+		},
+	}, { target: global ? target : undefined });
+	<group ref={ref} {...((bind?.() ?? {}) as any)}>{children}</group>
+}