@octanejs/drei 0.0.1

package/src/core/GizmoHelper.three.tsrx

@@ -0,0 +1,115 @@
+/** @jsxImportSource @octanejs/three/intrinsics */
+import { type ThreeElements, useFrame, useThree } from '@octanejs/three';
+import { useCallback, useEffect, useMemo, useRef } from '@octanejs/three/renderer';
+import { createContext, type OctaneNode, useContext } from 'octane';
+import { Group, Matrix4, Object3D, OrthographicCamera as OrthographicCameraImpl, Quaternion, Vector3 } from 'three';
+import type { OrbitControls as OrbitControlsType } from 'three-stdlib';
+import { Hud } from './Hud.three.tsrx';
+import { OrthographicCamera } from './cameras.three.tsrx';
+
+type GizmoHelperContext = { tweenCamera: (direction: Vector3) => void };
+const GizmoContext = createContext<GizmoHelperContext>({} as GizmoHelperContext);
+
+export const useGizmoContext = () => useContext(GizmoContext);
+
+const turnRate = 2 * Math.PI;
+const dummy = new Object3D();
+const matrix = new Matrix4();
+const q1 = new Quaternion();
+const q2 = new Quaternion();
+const target = new Vector3();
+const targetPosition = new Vector3();
+
+type ControlsProto = {
+	update(delta?: number): void;
+	target: Vector3;
+	getTarget?(target: Vector3): Vector3;
+	setPosition?(x: number, y: number, z: number): void;
+};
+
+export type GizmoHelperProps = ThreeElements['group'] & {
+	alignment?: 'top-left' | 'top-right' | 'bottom-right' | 'bottom-left' | 'bottom-center' | 'center-right' | 'center-left' | 'center-center' | 'top-center';
+	margin?: [number, number];
+	renderPriority?: number;
+	autoClear?: boolean;
+	onUpdate?: () => void;
+	onTarget?: () => Vector3;
+	children?: OctaneNode;
+};
+
+function isOrbitControls(controls: ControlsProto | undefined): controls is ControlsProto & OrbitControlsType {
+	return Boolean(controls && 'minPolarAngle' in controls);
+}
+
+function isCameraControls(controls: ControlsProto | undefined): controls is ControlsProto & Required<Pick<ControlsProto, 'getTarget' | 'setPosition'>> {
+	return Boolean(controls && 'getTarget' in controls);
+}
+
+function getControlsTarget(controls: ControlsProto | undefined, destination: Vector3): Vector3 | undefined {
+	return controls?.getTarget ? controls.getTarget(destination) : controls?.target;
+}
+
+export function GizmoHelper({
+	alignment = 'bottom-right',
+	margin = [80, 80],
+	renderPriority = 1,
+	onUpdate,
+	onTarget,
+	children,
+}: GizmoHelperProps) @{
+	const size = useThree((state) => state.size);
+	const mainCamera = useThree((state) => state.camera);
+	const defaultControls = useThree((state) => state.controls as unknown as ControlsProto | undefined);
+	const invalidate = useThree((state) => state.invalidate);
+	const gizmo = useRef<Group | null>(null);
+	const virtualCamera = useRef<OrthographicCameraImpl | null>(null);
+	const animating = useRef(false);
+	const radius = useRef(0);
+	const focusPoint = useRef(new Vector3());
+	const defaultUp = useRef(new Vector3());
+	useEffect(() => {
+		defaultUp.current.copy(mainCamera.up);
+		dummy.up.copy(mainCamera.up);
+	}, [mainCamera]);
+	const tweenCamera = useCallback((direction: Vector3) => {
+		animating.current = true;
+		if (defaultControls || onTarget) {
+			focusPoint.current = onTarget?.() ?? getControlsTarget(defaultControls, focusPoint.current) ?? focusPoint.current;
+		}
+		radius.current = mainCamera.position.distanceTo(target);
+		q1.copy(mainCamera.quaternion);
+		targetPosition.copy(direction).multiplyScalar(radius.current).add(target);
+		dummy.lookAt(targetPosition);
+		q2.copy(dummy.quaternion);
+		invalidate();
+	}, [defaultControls, mainCamera, onTarget, invalidate]);
+	useFrame((_state, delta) => {
+		if (!virtualCamera.current || !gizmo.current) return;
+		if (animating.current) {
+			if (q1.angleTo(q2) < 0.01) {
+				animating.current = false;
+				if (isOrbitControls(defaultControls)) mainCamera.up.copy(defaultUp.current);
+			} else {
+				q1.rotateTowards(q2, delta * turnRate);
+				mainCamera.position.set(0, 0, 1).applyQuaternion(q1).multiplyScalar(radius.current).add(focusPoint.current);
+				mainCamera.up.set(0, 1, 0).applyQuaternion(q1).normalize();
+				mainCamera.quaternion.copy(q1);
+				if (isCameraControls(defaultControls)) defaultControls.setPosition(mainCamera.position.x, mainCamera.position.y, mainCamera.position.z);
+				if (onUpdate) onUpdate(); else defaultControls?.update(delta);
+				invalidate();
+			}
+		}
+		matrix.copy(mainCamera.matrix).invert();
+		gizmo.current.quaternion.setFromRotationMatrix(matrix);
+	});
+	const context = useMemo(() => ({ tweenCamera }), [tweenCamera]);
+	const [marginX, marginY] = margin;
+	const x = alignment.endsWith('-center') ? 0 : alignment.endsWith('-left') ? -size.width / 2 + marginX : size.width / 2 - marginX;
+	const y = alignment.startsWith('center-') ? 0 : alignment.startsWith('top-') ? size.height / 2 - marginY : -size.height / 2 + marginY;
+	<Hud renderPriority={renderPriority}>
+		<GizmoContext.Provider value={context}>
+			<OrthographicCamera makeDefault ref={virtualCamera} position={[0, 0, 200]} />
+			<group ref={gizmo} position={[x, y, 0]}>{children}</group>
+		</GizmoContext.Provider>
+	</Hud>
+}

package/src/core/GizmoViewcube.three.tsrx

@@ -0,0 +1,82 @@
+/** @jsxImportSource @octanejs/three/intrinsics */
+import { type ThreeEvent, useThree } from '@octanejs/three';
+import { useMemo, useState } from '@octanejs/three/renderer';
+import { CanvasTexture, Vector3 } from 'three';
+import { useGizmoContext } from './GizmoHelper.three.tsrx';
+
+type XYZ = [number, number, number];
+type GizmoViewcubeProps = {
+	font?: string;
+	opacity?: number;
+	color?: string;
+	hoverColor?: string;
+	textColor?: string;
+	strokeColor?: string;
+	onClick?: (event: ThreeEvent<MouseEvent>) => null;
+	faces?: string[];
+};
+type FaceMaterialProps = GizmoViewcubeProps & { hover: boolean; index: number };
+type EdgeCubeProps = GizmoViewcubeProps & { dimensions: XYZ; position: Vector3 };
+const colors = { bg: '#f0f0f0', hover: '#999', text: 'black', stroke: 'black' };
+const defaultFaces = ['Right', 'Left', 'Top', 'Bottom', 'Front', 'Back'];
+const makePositionVector = (xyz: number[]) => new Vector3(...(xyz as XYZ)).multiplyScalar(0.38);
+const corners = [[1,1,1],[1,1,-1],[1,-1,1],[1,-1,-1],[-1,1,1],[-1,1,-1],[-1,-1,1],[-1,-1,-1]].map(makePositionVector);
+const edges = [[1,1,0],[1,0,1],[1,0,-1],[1,-1,0],[0,1,1],[0,1,-1],[0,-1,1],[0,-1,-1],[-1,1,0],[-1,0,1],[-1,0,-1],[-1,-1,0]].map(makePositionVector);
+const cornerDimensions: XYZ = [0.25, 0.25, 0.25];
+const edgeDimensions = edges.map((edge) => edge.toArray().map((axis) => axis === 0 ? 0.5 : 0.25) as XYZ);
+
+function FaceMaterial({ hover, index, font = '20px Inter var, Arial, sans-serif', faces = defaultFaces, color = colors.bg, hoverColor = colors.hover, textColor = colors.text, strokeColor = colors.stroke, opacity = 1 }: FaceMaterialProps) @{
+	const gl = useThree((state) => state.gl);
+	const texture = useMemo(() => {
+		const canvas = document.createElement('canvas'); canvas.width = 128; canvas.height = 128;
+		const context = canvas.getContext('2d')!;
+		context.fillStyle = color; context.fillRect(0, 0, 128, 128); context.strokeStyle = strokeColor; context.strokeRect(0, 0, 128, 128);
+		context.font = font; context.textAlign = 'center'; context.fillStyle = textColor; context.fillText(faces[index]!.toUpperCase(), 64, 76);
+		return new CanvasTexture(canvas);
+	}, [index, faces, font, color, textColor, strokeColor]);
+	<meshBasicMaterial map={texture} map-anisotropy={gl.capabilities.getMaxAnisotropy() || 1} attach={`material-${index}`} color={hover ? hoverColor : 'white'} transparent opacity={opacity} />
+}
+
+function FaceCube(props: GizmoViewcubeProps) @{
+	const { tweenCamera } = useGizmoContext();
+	const [hover, setHover] = useState<number | null>(null);
+	<mesh
+		onPointerOut={(event) => { event.stopPropagation(); setHover(null); }}
+		onPointerMove={(event) => { event.stopPropagation(); setHover(Math.floor(event.faceIndex! / 2)); }}
+		onClick={props.onClick || ((event) => { event.stopPropagation(); tweenCamera(event.face!.normal); })}
+	>
+		<FaceMaterial index={0} hover={hover === 0} {...props} /><FaceMaterial index={1} hover={hover === 1} {...props} />
+		<FaceMaterial index={2} hover={hover === 2} {...props} /><FaceMaterial index={3} hover={hover === 3} {...props} />
+		<FaceMaterial index={4} hover={hover === 4} {...props} /><FaceMaterial index={5} hover={hover === 5} {...props} />
+		<boxGeometry />
+	</mesh>
+}
+
+function EdgeCube({ onClick, dimensions, position, hoverColor = colors.hover }: EdgeCubeProps) @{
+	const { tweenCamera } = useGizmoContext();
+	const [hover, setHover] = useState(false);
+	<mesh scale={1.01} position={position}
+		onPointerOver={(event) => { event.stopPropagation(); setHover(true); }}
+		onPointerOut={(event) => { event.stopPropagation(); setHover(false); }}
+		onClick={onClick || ((event) => { event.stopPropagation(); tweenCamera(position); })}
+	>
+		<meshBasicMaterial color={hover ? hoverColor : 'white'} transparent opacity={0.6} visible={hover} />
+		<boxGeometry args={dimensions} />
+	</mesh>
+}
+
+export function GizmoViewcube(props: GizmoViewcubeProps) @{
+	<group scale={[60, 60, 60]}>
+		<FaceCube {...props} />
+		<EdgeCube position={edges[0]!} dimensions={edgeDimensions[0]!} {...props} /><EdgeCube position={edges[1]!} dimensions={edgeDimensions[1]!} {...props} />
+		<EdgeCube position={edges[2]!} dimensions={edgeDimensions[2]!} {...props} /><EdgeCube position={edges[3]!} dimensions={edgeDimensions[3]!} {...props} />
+		<EdgeCube position={edges[4]!} dimensions={edgeDimensions[4]!} {...props} /><EdgeCube position={edges[5]!} dimensions={edgeDimensions[5]!} {...props} />
+		<EdgeCube position={edges[6]!} dimensions={edgeDimensions[6]!} {...props} /><EdgeCube position={edges[7]!} dimensions={edgeDimensions[7]!} {...props} />
+		<EdgeCube position={edges[8]!} dimensions={edgeDimensions[8]!} {...props} /><EdgeCube position={edges[9]!} dimensions={edgeDimensions[9]!} {...props} />
+		<EdgeCube position={edges[10]!} dimensions={edgeDimensions[10]!} {...props} /><EdgeCube position={edges[11]!} dimensions={edgeDimensions[11]!} {...props} />
+		<EdgeCube position={corners[0]!} dimensions={cornerDimensions} {...props} /><EdgeCube position={corners[1]!} dimensions={cornerDimensions} {...props} />
+		<EdgeCube position={corners[2]!} dimensions={cornerDimensions} {...props} /><EdgeCube position={corners[3]!} dimensions={cornerDimensions} {...props} />
+		<EdgeCube position={corners[4]!} dimensions={cornerDimensions} {...props} /><EdgeCube position={corners[5]!} dimensions={cornerDimensions} {...props} />
+		<EdgeCube position={corners[6]!} dimensions={cornerDimensions} {...props} /><EdgeCube position={corners[7]!} dimensions={cornerDimensions} {...props} />
+	</group>
+}

package/src/core/GizmoViewport.three.tsrx

@@ -0,0 +1,122 @@
+/** @jsxImportSource @octanejs/three/intrinsics */
+import { type ThreeElements, type ThreeEvent, useThree } from '@octanejs/three';
+import { useMemo, useState } from '@octanejs/three/renderer';
+import { CanvasTexture } from 'three';
+import { universalComponent } from 'octane/universal';
+import { useGizmoContext } from './GizmoHelper.three.tsrx';
+
+type AxisProps = { color: string; rotation: [number, number, number]; scale?: [number, number, number] };
+type AxisHeadProps = Omit<ThreeElements['sprite'], 'ref'> & {
+	arcStyle: string;
+	label?: string;
+	labelColor: string;
+	axisHeadScale?: number;
+	disabled?: boolean;
+	font: string;
+	onClick?: (event: ThreeEvent<MouseEvent>) => null;
+};
+
+type GizmoViewportProps = ThreeElements['group'] & {
+	axisColors?: [string, string, string];
+	axisScale?: [number, number, number];
+	labels?: [string, string, string];
+	axisHeadScale?: number;
+	labelColor?: string;
+	hideNegativeAxes?: boolean;
+	hideAxisHeads?: boolean;
+	disabled?: boolean;
+	font?: string;
+	onClick?: (event: ThreeEvent<MouseEvent>) => null;
+};
+
+function Axis({ scale = [0.8, 0.05, 0.05], color, rotation }: AxisProps) @{
+	<group rotation={rotation}>
+		<mesh position={[0.4, 0, 0]}>
+			<boxGeometry args={scale} />
+			<meshBasicMaterial color={color} toneMapped={false} />
+		</mesh>
+	</group>
+}
+
+function AxisHead({ onClick, font, disabled, arcStyle, label, labelColor, axisHeadScale = 1, ...props }: AxisHeadProps) @{
+	const gl = useThree((state) => state.gl);
+	const texture = useMemo(() => {
+		const canvas = document.createElement('canvas');
+		canvas.width = 64;
+		canvas.height = 64;
+		const context = canvas.getContext('2d')!;
+		context.beginPath();
+		context.arc(32, 32, 16, 0, 2 * Math.PI);
+		context.closePath();
+		context.fillStyle = arcStyle;
+		context.fill();
+		if (label) {
+			context.font = font;
+			context.textAlign = 'center';
+			context.fillStyle = labelColor;
+			context.fillText(label, 32, 41);
+		}
+		return new CanvasTexture(canvas);
+	}, [arcStyle, label, labelColor, font]);
+	const [active, setActive] = useState(false);
+	const scale = (label ? 1 : 0.75) * (active ? 1.2 : 1) * axisHeadScale;
+	<sprite
+		scale={scale}
+		onPointerOver={!disabled ? (event) => { event.stopPropagation(); setActive(true); } : undefined}
+		onPointerOut={!disabled ? onClick || ((event) => { event.stopPropagation(); setActive(false); }) : undefined}
+		{...props}
+	>
+		<spriteMaterial map={texture} map-anisotropy={gl.capabilities.getMaxAnisotropy() || 1} alphaTest={0.3} opacity={label ? 1 : 0.75} toneMapped={false} />
+	</sprite>
+}
+
+type HeadsProps = {
+	font: string; disabled?: boolean; labelColor: string; onClick?: (event: ThreeEvent<MouseEvent>) => null;
+	axisHeadScale: number; pointerDown?: (event: ThreeEvent<PointerEvent>) => void;
+	colors: [string, string, string]; labels: [string, string, string];
+};
+
+function PositiveHeads({ font, disabled, labelColor, onClick, axisHeadScale, pointerDown, colors, labels }: HeadsProps) @{
+	<>
+		<AxisHead font={font} disabled={disabled} labelColor={labelColor} onClick={onClick} axisHeadScale={axisHeadScale} onPointerDown={pointerDown} arcStyle={colors[0]} position={[1, 0, 0]} label={labels[0]} />
+		<AxisHead font={font} disabled={disabled} labelColor={labelColor} onClick={onClick} axisHeadScale={axisHeadScale} onPointerDown={pointerDown} arcStyle={colors[1]} position={[0, 1, 0]} label={labels[1]} />
+		<AxisHead font={font} disabled={disabled} labelColor={labelColor} onClick={onClick} axisHeadScale={axisHeadScale} onPointerDown={pointerDown} arcStyle={colors[2]} position={[0, 0, 1]} label={labels[2]} />
+	</>
+}
+
+function AllHeads(props: HeadsProps) @{
+	<>
+		<PositiveHeads {...props} />
+		<AxisHead font={props.font} disabled={props.disabled} labelColor={props.labelColor} onClick={props.onClick} axisHeadScale={props.axisHeadScale} onPointerDown={props.pointerDown} arcStyle={props.colors[0]} position={[-1, 0, 0]} />
+		<AxisHead font={props.font} disabled={props.disabled} labelColor={props.labelColor} onClick={props.onClick} axisHeadScale={props.axisHeadScale} onPointerDown={props.pointerDown} arcStyle={props.colors[1]} position={[0, -1, 0]} />
+		<AxisHead font={props.font} disabled={props.disabled} labelColor={props.labelColor} onClick={props.onClick} axisHeadScale={props.axisHeadScale} onPointerDown={props.pointerDown} arcStyle={props.colors[2]} position={[0, 0, -1]} />
+	</>
+}
+
+function NoHeads() @{}
+
+export function GizmoViewport({
+	hideNegativeAxes,
+	hideAxisHeads,
+	disabled,
+	font = '18px Inter var, Arial, sans-serif',
+	axisColors = ['#ff2060', '#20df80', '#2080ff'],
+	axisHeadScale = 1,
+	axisScale,
+	labels = ['X', 'Y', 'Z'],
+	labelColor = '#000',
+	onClick,
+	...props
+}: GizmoViewportProps) @{
+	const [colorX, colorY, colorZ] = axisColors;
+	const { tweenCamera } = useGizmoContext();
+	const pointerDown = !disabled ? (event: ThreeEvent<PointerEvent>) => { tweenCamera(event.object.position); event.stopPropagation(); } : undefined;
+	const headsComponent = hideAxisHeads ? NoHeads : hideNegativeAxes ? PositiveHeads : AllHeads;
+	const headsProps: HeadsProps = { font, disabled, labelColor, onClick, axisHeadScale, pointerDown, colors: axisColors, labels };
+	<group scale={40} {...props}>
+		<Axis color={colorX} rotation={[0, 0, 0]} scale={axisScale} />
+		<Axis color={colorY} rotation={[0, 0, Math.PI / 2]} scale={axisScale} />
+		<Axis color={colorZ} rotation={[0, -Math.PI / 2, 0]} scale={axisScale} />
+		{universalComponent('three', headsComponent as any, headsProps as unknown as Record<string, unknown>)}
+	</group>
+}

package/src/core/Gltf.three.tsrx

@@ -0,0 +1,62 @@
+/** @jsxImportSource @octanejs/three/intrinsics */
+import { type ObjectMap, useLoader, type ThreeRef } from '@octanejs/three';
+import type { Group } from 'three';
+import { GLTFLoader, type GLTF } from 'three-stdlib';
+import { Clone, type CloneProps } from './Clone.three.tsrx';
+import { slotDefault } from './compiler-slot.js';
+import {
+	type ExtendLoader,
+	gltfExtensions,
+	type Path,
+	setGltfDecoderPath,
+	type UseDraco,
+	type UseMeshopt,
+} from './gltf-loader.js';
+
+type GltfResult = GLTF & ObjectMap;
+
+export const useGLTF = Object.assign(
+	<T extends Path,>(
+		path: T,
+		useDraco?: UseDraco,
+		useMeshopt?: UseMeshopt,
+		extendLoader?: ExtendLoader,
+	): T extends any[] ? GltfResult[] : GltfResult => {
+		useDraco = slotDefault(useDraco, undefined);
+		useMeshopt = slotDefault(useMeshopt, undefined);
+		extendLoader = slotDefault(extendLoader, undefined);
+		return useLoader(
+			GLTFLoader,
+			path,
+			gltfExtensions(useDraco, useMeshopt, extendLoader) as any,
+		) as unknown as T extends any[] ? GltfResult[] : GltfResult;
+	},
+	{
+		preload(path: Path, useDraco?: UseDraco, useMeshopt?: UseMeshopt, extendLoader?: ExtendLoader) {
+			useLoader.preload(
+				GLTFLoader,
+				path,
+				gltfExtensions(useDraco, useMeshopt, extendLoader) as any,
+			);
+		},
+		clear(path: Path) {
+			useLoader.clear(GLTFLoader, path);
+		},
+		setDecoderPath: setGltfDecoderPath,
+	},
+);
+
+export type GltfProps =
+	Omit<CloneProps, 'object'> & {
+		src: string;
+		useDraco?: UseDraco;
+		useMeshOpt?: UseMeshopt;
+		extendLoader?: ExtendLoader;
+	};
+
+export function Gltf({ src, useDraco, useMeshOpt, extendLoader, ref, ...props }: GltfProps & {
+	ref?: ThreeRef<Group>;
+}) @{
+	const { scene } = useGLTF(src, useDraco, useMeshOpt, extendLoader);
+	<Clone ref={ref} {...props} object={scene as unknown as Group} />
+}

package/src/core/GradientTexture.three.tsrx

@@ -0,0 +1,66 @@
+/** @jsxImportSource @octanejs/three/intrinsics */
+import { type ThreeElements, useThree } from '@octanejs/three';
+import { useMemo } from '@octanejs/three/renderer';
+import * as THREE from 'three';
+import { GradientType } from './gradient-types.js';
+
+export { GradientType } from './gradient-types.js';
+
+export type GradientTextureProps =
+	{
+		stops: number[];
+		colors: THREE.ColorRepresentation[];
+		attach?: string;
+		size?: number;
+		width?: number;
+		type?: GradientType;
+		innerCircleRadius?: number;
+		outerCircleRadius?: string | number;
+	} & Omit<ThreeElements['texture'], 'args' | 'type'>;
+
+export function GradientTexture({
+	stops,
+	colors,
+	size = 1024,
+	width = 16,
+	type = GradientType.Linear,
+	innerCircleRadius = 0,
+	outerCircleRadius = 'auto',
+	...props
+}: GradientTextureProps) @{
+	const gl = useThree((state) => state.gl);
+	const canvas = useMemo(() => {
+		const value = document.createElement('canvas');
+		const context = value.getContext('2d')!;
+		value.width = width;
+		value.height = size;
+		let gradient: CanvasGradient;
+		if (type === GradientType.Linear) {
+			gradient = context.createLinearGradient(0, 0, 0, size);
+		} else {
+			const centerX = value.width / 2;
+			const centerY = value.height / 2;
+			const radius =
+				outerCircleRadius !== 'auto'
+					? Math.abs(Number(outerCircleRadius))
+					: Math.sqrt(centerX ** 2 + centerY ** 2);
+			gradient = context.createRadialGradient(
+				centerX,
+				centerY,
+				Math.abs(innerCircleRadius),
+				centerX,
+				centerY,
+				radius,
+			);
+		}
+		const color = new THREE.Color();
+		let index = stops.length;
+		while (index--) gradient.addColorStop(stops[index], color.set(colors[index]).getStyle());
+		context.save();
+		context.fillStyle = gradient;
+		context.fillRect(0, 0, width, size);
+		context.restore();
+		return value;
+	}, [stops]);
+	<canvasTexture colorSpace={gl.outputColorSpace} args={[canvas]} attach="map" {...props as any} />
+}

package/src/core/Grid.three.tsrx

@@ -0,0 +1,170 @@
+/** @jsxImportSource @octanejs/three/intrinsics */
+import { applyProps, type ThreeElements, type ThreeRef, useFrame } from '@octanejs/three';
+import { useMemo, useRef, useState } from '@octanejs/three/renderer';
+import * as THREE from 'three';
+import { shaderMaterial } from './shaderMaterial.js';
+
+export type GridMaterialType = {
+	cellSize?: number;
+	cellThickness?: number;
+	cellColor?: THREE.ColorRepresentation;
+	sectionSize?: number;
+	sectionThickness?: number;
+	sectionColor?: THREE.ColorRepresentation;
+	followCamera?: boolean;
+	infiniteGrid?: boolean;
+	fadeDistance?: number;
+	fadeStrength?: number;
+	fadeFrom?: number;
+	side?: THREE.Side;
+};
+
+export type GridProps =
+	Omit<ThreeElements['mesh'], 'ref' | 'args'> & GridMaterialType & {
+		args?: ConstructorParameters<typeof THREE.PlaneGeometry>;
+	};
+
+const GridMaterial = shaderMaterial(
+	{
+		cellSize: 0.5,
+		sectionSize: 1,
+		fadeDistance: 100,
+		fadeStrength: 1,
+		fadeFrom: 1,
+		cellThickness: 0.5,
+		sectionThickness: 1,
+		cellColor: new THREE.Color(),
+		sectionColor: new THREE.Color(),
+		infiniteGrid: false,
+		followCamera: false,
+		worldCamProjPosition: new THREE.Vector3(),
+		worldPlanePosition: new THREE.Vector3(),
+	},
+	`varying vec3 localPosition;
+    varying vec4 worldPosition;
+
+    uniform vec3 worldCamProjPosition;
+    uniform vec3 worldPlanePosition;
+    uniform float fadeDistance;
+    uniform bool infiniteGrid;
+    uniform bool followCamera;
+
+    void main() {
+      localPosition = position.xzy;
+      if (infiniteGrid) localPosition *= 1.0 + fadeDistance;
+      
+      worldPosition = modelMatrix * vec4(localPosition, 1.0);
+      if (followCamera) {
+        worldPosition.xyz += (worldCamProjPosition - worldPlanePosition);
+        localPosition = (inverse(modelMatrix) * worldPosition).xyz;
+      }
+
+      gl_Position = projectionMatrix * viewMatrix * worldPosition;
+    }`,
+	`varying vec3 localPosition;
+    varying vec4 worldPosition;
+
+    uniform vec3 worldCamProjPosition;
+    uniform float cellSize;
+    uniform float sectionSize;
+    uniform vec3 cellColor;
+    uniform vec3 sectionColor;
+    uniform float fadeDistance;
+    uniform float fadeStrength;
+    uniform float fadeFrom;
+    uniform float cellThickness;
+    uniform float sectionThickness;
+
+    float getGrid(float size, float thickness) {
+      vec2 r = localPosition.xz / size;
+      vec2 grid = abs(fract(r - 0.5) - 0.5) / fwidth(r);
+      float line = min(grid.x, grid.y) + 1.0 - thickness;
+      return 1.0 - min(line, 1.0);
+    }
+
+    void main() {
+      float g1 = getGrid(cellSize, cellThickness);
+      float g2 = getGrid(sectionSize, sectionThickness);
+
+      vec3 from = worldCamProjPosition*vec3(fadeFrom);
+      float dist = distance(from, worldPosition.xyz);
+      float d = 1.0 - min(dist / fadeDistance, 1.0);
+      vec3 color = mix(cellColor, sectionColor, min(1.0, sectionThickness * g2));
+
+      gl_FragColor = vec4(color, (g1 + g2) * pow(d, fadeStrength));
+      gl_FragColor.a = mix(0.75 * gl_FragColor.a, gl_FragColor.a, g2);
+      if (gl_FragColor.a <= 0.0) discard;
+
+      #include <tonemapping_fragment>
+      #include <colorspace_fragment>
+    }`,
+);
+
+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 function Grid({
+	args,
+	cellColor = '#000000',
+	sectionColor = '#2080ff',
+	cellSize = 0.5,
+	sectionSize = 1,
+	followCamera = false,
+	infiniteGrid = false,
+	fadeDistance = 100,
+	fadeStrength = 1,
+	fadeFrom = 1,
+	cellThickness = 0.5,
+	sectionThickness = 1,
+	side = THREE.BackSide,
+	ref,
+	...props
+}: GridProps & { ref?: ThreeRef<THREE.Mesh> }) @{
+	const localRef = useRef<THREE.Mesh | null>(null);
+	const mergedRef = useMemo(
+		() => (value: THREE.Mesh | null) => {
+			localRef.current = value;
+			assignRef(ref, value);
+		},
+		[ref],
+	);
+	const [material] = useState(() => new GridMaterial());
+	applyProps(material, {
+		cellSize,
+		sectionSize,
+		cellColor,
+		sectionColor,
+		cellThickness,
+		sectionThickness,
+		fadeDistance,
+		fadeStrength,
+		fadeFrom,
+		infiniteGrid,
+		followCamera,
+		side,
+		transparent: true,
+		extensions: { derivatives: true },
+	});
+	const plane = new THREE.Plane();
+	const upVector = new THREE.Vector3(0, 1, 0);
+	const zeroVector = new THREE.Vector3();
+	useFrame((state) => {
+		if (!localRef.current) return;
+		plane.setFromNormalAndCoplanarPoint(upVector, zeroVector).applyMatrix4(
+			localRef.current.matrixWorld,
+		);
+		const worldCamProjPosition = material.uniforms.worldCamProjPosition as THREE.Uniform<
+			THREE.Vector3
+		>;
+		const worldPlanePosition = material.uniforms.worldPlanePosition as THREE.Uniform<THREE.Vector3>;
+		plane.projectPoint(state.camera.position, worldCamProjPosition.value);
+		worldPlanePosition.value.set(0, 0, 0).applyMatrix4(localRef.current.matrixWorld);
+	});
+	<mesh ref={mergedRef} frustumCulled={false} {...props}>
+		<primitive object={material} attach="material" />
+		<planeGeometry args={args} />
+	</mesh>
+}

package/src/core/Helper.three.tsrx

@@ -0,0 +1,56 @@
+/** @jsxImportSource @octanejs/three/intrinsics */
+import { type RefObject, useFrame, useThree } from '@octanejs/three';
+import { useLayoutEffect, useRef } from '@octanejs/three/renderer';
+import { Object3D } from 'three';
+import { stripTrailingSlot } from './compiler-slot.js';
+
+type Falsey = false | null | undefined;
+type HelperType = Object3D & { update?: () => void; dispose?: () => void };
+type HelperConstructor = new (...args: any[]) => any;
+type HelperArgs<T> = T extends [infer _, ...infer Rest] ? Rest : never;
+
+export function useHelper<T extends HelperConstructor>(
+	object3D: RefObject<Object3D> | Falsey,
+	helperConstructor: T,
+	...args: HelperArgs<ConstructorParameters<T>>
+) {
+	args = stripTrailingSlot(args) as HelperArgs<ConstructorParameters<T>>;
+	const helper = useRef<HelperType | null | undefined>(null);
+	const scene = useThree((state) => state.scene);
+	useLayoutEffect(() => {
+		let currentHelper: HelperType | undefined;
+		if (object3D && object3D.current && helperConstructor) {
+			helper.current = currentHelper =
+				new helperConstructor(object3D.current, ...args) as HelperType;
+		}
+		if (currentHelper) {
+			currentHelper.traverse((child) => (child.raycast = () => null));
+			scene.add(currentHelper);
+			return () => {
+				helper.current = undefined;
+				scene.remove(currentHelper);
+				currentHelper.dispose?.();
+			};
+		}
+	}, [scene, helperConstructor, object3D, ...args]);
+	useFrame(() => void helper.current?.update?.());
+	return helper;
+}
+
+export type HelperProps<T extends HelperConstructor> = {
+	type: T;
+	args?: HelperArgs<ConstructorParameters<T>>;
+};
+
+export function Helper<T extends HelperConstructor>({
+	type: helperConstructor,
+	args = [] as never,
+}: HelperProps<T>) @{
+	const thisRef = useRef<Object3D | null>(null);
+	const parentRef = useRef<Object3D | null>(null);
+	useLayoutEffect(() => {
+		parentRef.current = thisRef.current?.parent ?? null;
+	});
+	useHelper(parentRef, helperConstructor, ...args);
+	<object3D ref={thisRef} />
+}