@octanejs/drei 0.0.1

package/src/core/useBoxProjectedEnv.three.tsrx

@@ -0,0 +1,113 @@
+import { applyProps, type Vector3 as Vector3Prop } from '@octanejs/three';
+import { useLayoutEffect, useMemo, useRef, useState } from '@octanejs/three/renderer';
+import * as THREE from 'three';
+import { slotDefault } from './compiler-slot.js';
+
+const worldposReplace = /* glsl */ `
+#if defined( USE_ENVMAP ) || defined( DISTANCE ) || defined ( USE_SHADOWMAP )
+  vec4 worldPosition = modelMatrix * vec4( transformed, 1.0 );
+  #ifdef BOX_PROJECTED_ENV_MAP
+    vWorldPosition = worldPosition.xyz;
+  #endif
+#endif
+`;
+
+const boxProjectDefinitions = /* glsl */ `
+#ifdef BOX_PROJECTED_ENV_MAP
+  uniform vec3 envMapSize;
+  uniform vec3 envMapPosition;
+  varying vec3 vWorldPosition;
+    
+  vec3 parallaxCorrectNormal( vec3 v, vec3 cubeSize, vec3 cubePos ) {
+    vec3 nDir = normalize( v );
+    vec3 rbmax = ( .5 * cubeSize + cubePos - vWorldPosition ) / nDir;
+    vec3 rbmin = ( -.5 * cubeSize + cubePos - vWorldPosition ) / nDir;
+    vec3 rbminmax;
+    rbminmax.x = ( nDir.x > 0. ) ? rbmax.x : rbmin.x;
+    rbminmax.y = ( nDir.y > 0. ) ? rbmax.y : rbmin.y;
+    rbminmax.z = ( nDir.z > 0. ) ? rbmax.z : rbmin.z;
+    float correction = min( min( rbminmax.x, rbminmax.y ), rbminmax.z );
+    vec3 boxIntersection = vWorldPosition + nDir * correction;    
+    return boxIntersection - cubePos;
+  }
+#endif
+`;
+
+const getIBLIrradiancePatch = /* glsl */ `
+#ifdef BOX_PROJECTED_ENV_MAP
+  worldNormal = parallaxCorrectNormal( worldNormal, envMapSize, envMapPosition );
+#endif
+`;
+
+const getIBLRadiancePatch = /* glsl */ `
+#ifdef BOX_PROJECTED_ENV_MAP
+  reflectVec = parallaxCorrectNormal( reflectVec, envMapSize, envMapPosition );
+#endif
+`;
+
+interface MaterialShader {
+	vertexShader: string;
+	fragmentShader: string;
+	defines: Record<string, string | number | boolean> | undefined;
+	uniforms: Record<string, THREE.IUniform>;
+}
+
+function boxProjectedEnvMap(
+	shader: MaterialShader,
+	envMapPosition: THREE.Vector3,
+	envMapSize: THREE.Vector3,
+) {
+	shader.defines!.BOX_PROJECTED_ENV_MAP = true;
+	shader.uniforms.envMapPosition = { value: envMapPosition };
+	shader.uniforms.envMapSize = { value: envMapSize };
+	shader.vertexShader = `
+  varying vec3 vWorldPosition;
+  ${shader.vertexShader.replace(
+		'#include <worldpos_vertex>',
+		worldposReplace,
+	)}`;
+	shader.fragmentShader = `
+    ${boxProjectDefinitions}
+    ${shader.fragmentShader.replace(
+		'#include <envmap_physical_pars_fragment>',
+		THREE.ShaderChunk.envmap_physical_pars_fragment,
+	).replace(
+		'vec3 worldNormal = inverseTransformDirection( normal, viewMatrix );',
+		`vec3 worldNormal = inverseTransformDirection( normal, viewMatrix );
+         ${getIBLIrradiancePatch}
+         `,
+	).replace(
+		'reflectVec = inverseTransformDirection( reflectVec, viewMatrix );',
+		`reflectVec = inverseTransformDirection( reflectVec, viewMatrix );
+         ${getIBLRadiancePatch}
+        `,
+	)}`;
+}
+
+export function useBoxProjectedEnv(
+	position: Vector3Prop = new THREE.Vector3(),
+	size: Vector3Prop = new THREE.Vector3(),
+) {
+	position = slotDefault(position, new THREE.Vector3());
+	size = slotDefault(size, new THREE.Vector3());
+	const [config] = useState(() => ({ position: new THREE.Vector3(), size: new THREE.Vector3() }));
+	applyProps(config as any, { position, size });
+	const ref = useRef<THREE.Material | null>(null);
+	const spread = useMemo(
+		() => ({
+			ref,
+			onBeforeCompile: (shader: MaterialShader) => boxProjectedEnvMap(
+				shader,
+				config.position,
+				config.size,
+			),
+			customProgramCacheKey: () =>
+				JSON.stringify(config.position.toArray()) + JSON.stringify(config.size.toArray()),
+		}),
+		[...config.position.toArray(), ...config.size.toArray()],
+	);
+	useLayoutEffect(() => {
+		if (ref.current) ref.current.needsUpdate = true;
+	}, [config]);
+	return spread;
+}

package/src/core/useCamera.three.tsrx

@@ -0,0 +1,26 @@
+import { applyProps, type RefObject, useThree } from '@octanejs/three';
+import { useState } from '@octanejs/three/renderer';
+import { Camera, type Intersection, Raycaster } from 'three';
+import { slotDefault } from './compiler-slot.js';
+
+export function useCamera(camera: Camera | RefObject<Camera>, props?: Partial<Raycaster>) {
+	props = slotDefault(props, undefined);
+	const pointer = useThree((state) => state.pointer);
+	const [raycast] = useState(() => {
+		const raycaster = new Raycaster();
+		if (props) applyProps(raycaster, props);
+		return function (
+			this: { constructor: { prototype: { raycast?: Function } } },
+			_: Raycaster,
+			intersects: Intersection[],
+		): void {
+			const activeCamera =
+				camera instanceof Camera ? camera : camera.current;
+			if (!activeCamera) return;
+			raycaster.setFromCamera(pointer, activeCamera);
+			const implementation = this.constructor.prototype.raycast?.bind(this);
+			implementation?.(raycaster, intersects);
+		};
+	});
+	return raycast;
+}

package/src/core/useContextBridge.three.tsrx

@@ -0,0 +1,25 @@
+/** @jsxImportSource @octanejs/three/intrinsics */
+import { type Context, type OctaneNode, useContext, useMemo, useRef } from 'octane';
+import { defineUniversalComponent, universalComponent, universalContext, type UniversalRenderable } from 'octane/universal';
+import { stripTrailingSlot } from './compiler-slot.js';
+
+type BridgeProps = { children?: OctaneNode };
+type BridgeRendererProps = BridgeProps & { contexts: Array<Context<any>>; values: { current: unknown[] } };
+
+function BridgeRenderer({ children, contexts, values }: BridgeRendererProps) @{
+	let result = children as UniversalRenderable;
+	for (let index = contexts.length - 1; index >= 0; index--) {
+		result = universalContext(contexts[index]!, values.current[index], result);
+	}
+	<>{result}</>
+}
+
+export function useContextBridge(...contexts: Array<Context<any>>) {
+	contexts = stripTrailingSlot(contexts);
+	const values = useRef<unknown[]>([]);
+	values.current = contexts.map((context) => useContext(context));
+	return useMemo(() => defineUniversalComponent<BridgeProps>(
+		'three',
+		(props) => universalComponent('three', BridgeRenderer as any, { ...props, contexts, values }),
+	), []);
+}

package/src/core/useDepthBuffer.three.tsrx

@@ -0,0 +1,35 @@
+import { useFrame, useThree } from '@octanejs/three';
+import { useMemo } from '@octanejs/three/renderer';
+import { DepthFormat, DepthTexture, UnsignedShortType } from 'three';
+import { slotDefault } from './compiler-slot.js';
+import { useFBO } from './Fbo.three.tsrx';
+
+type DepthBufferOptions = {
+		size?: number;
+		frames?: number;
+	};
+
+export function useDepthBuffer(options: DepthBufferOptions = {}) {
+	const { size = 256, frames = Infinity } = slotDefault(options, {});
+	const dpr = useThree((state) => state.viewport.dpr);
+	const { width, height } = useThree((state) => state.size);
+	const targetWidth = size || width * dpr;
+	const targetHeight = size || height * dpr;
+	const depthConfig = useMemo(() => {
+		const depthTexture = new DepthTexture(targetWidth, targetHeight);
+		depthTexture.format = DepthFormat;
+		depthTexture.type = UnsignedShortType;
+		return { depthTexture };
+	}, [targetWidth, targetHeight]);
+	let count = 0;
+	const depthFbo = useFBO(targetWidth, targetHeight, depthConfig);
+	useFrame((state) => {
+		if (frames === Infinity || count < frames) {
+			state.gl.setRenderTarget?.(depthFbo);
+			state.gl.render(state.scene, state.camera);
+			state.gl.setRenderTarget?.(null);
+			count++;
+		}
+	});
+	return depthFbo.depthTexture;
+}

package/src/core/useEnvironment.three.tsrx

@@ -0,0 +1,81 @@
+import { useLoader, useThree } from '@octanejs/three';
+import { useLayoutEffect } from '@octanejs/three/renderer';
+import {
+	CubeReflectionMapping,
+	EquirectangularReflectionMapping,
+	type CubeTexture,
+	type Loader,
+	type Texture,
+} from 'three';
+import {
+	defaultEnvironmentFiles,
+	environmentExtension,
+	environmentLoader,
+	type EnvironmentLoaderProps,
+	resolveEnvironmentOptions,
+} from './environment-loader.js';
+import { slotDefault } from './compiler-slot.js';
+
+export function useEnvironment(options: Partial<EnvironmentLoaderProps> = {}) {
+	options = slotDefault(options, {});
+	const { files, path, colorSpace, extensions } = resolveEnvironmentOptions(options);
+	const { extension, isCubemap, multiple } = environmentExtension(files);
+	const loader = environmentLoader(extension);
+	if (!loader) throw new Error(`useEnvironment: Unrecognized file extension: ${files}`);
+	const gl = useThree((state) => state.gl);
+
+	useLayoutEffect(() => {
+		if (extension !== 'webp' && extension !== 'jpg' && extension !== 'jpeg') return;
+		const clearGainmapTexture = () => useLoader.clear(
+			loader as any,
+			(multiple ? [files] : files) as any,
+		);
+		const canvas = gl.domElement as EventTarget;
+		canvas.addEventListener('webglcontextlost', clearGainmapTexture, { once: true });
+	}, [files, gl.domElement]);
+
+	const loaderResult = useLoader(loader as any, (multiple ? [files] : files) as any, (
+		concreteLoader: any,
+	) => {
+		if (extension === 'webp' || extension === 'jpg' || extension === 'jpeg') {
+			concreteLoader.setRenderer(gl);
+		}
+		concreteLoader.setPath?.(path);
+		extensions?.(concreteLoader as Loader);
+	}) as Texture | Texture[];
+	let texture: Texture | CubeTexture = multiple
+		? (loaderResult as Texture[])[0]
+		: loaderResult as Texture;
+	if (extension === 'jpg' || extension === 'jpeg' || extension === 'webp') {
+		texture = (texture as any).renderTarget?.texture;
+	}
+	texture.mapping = isCubemap ? CubeReflectionMapping : EquirectangularReflectionMapping;
+	texture.colorSpace = colorSpace ?? (isCubemap ? 'srgb' : 'srgb-linear');
+	return texture;
+}
+
+type PreloadOptions = Omit<EnvironmentLoaderProps, 'encoding'>;
+useEnvironment.preload = (preloadOptions?: PreloadOptions) => {
+	const { files, path, extensions } = resolveEnvironmentOptions({
+		files: defaultEnvironmentFiles,
+		...preloadOptions,
+	});
+	const { extension, multiple } = environmentExtension(files);
+	if (extension === 'webp' || extension === 'jpg' || extension === 'jpeg') {
+		throw new Error('useEnvironment: Preloading gainmaps is not supported');
+	}
+	const loader = environmentLoader(extension);
+	if (!loader) throw new Error(`useEnvironment: Unrecognized file extension: ${files}`);
+	useLoader.preload(loader as any, (multiple ? [files] : files) as any, (concreteLoader: any) => {
+		concreteLoader.setPath?.(path);
+		extensions?.(concreteLoader as Loader);
+	});
+};
+
+useEnvironment.clear = (clearOptions?: Pick<EnvironmentLoaderProps, 'files' | 'preset'>) => {
+	const { files } = resolveEnvironmentOptions({ files: defaultEnvironmentFiles, ...clearOptions });
+	const { extension, multiple } = environmentExtension(files);
+	const loader = environmentLoader(extension);
+	if (!loader) throw new Error(`useEnvironment: Unrecognized file extension: ${files}`);
+	useLoader.clear(loader as any, (multiple ? [files] : files) as any);
+};

package/src/core/useFont.three.tsrx

@@ -0,0 +1,12 @@
+import { use } from '@octanejs/three/renderer';
+import { loadFont, type FontInput } from './font-resource.js';
+import { clearResource, preloadResource, resourcePromise } from './resource.js';
+
+export type { FontData, Glyph } from './font-resource.js';
+
+export function useFont(font: FontInput) {
+	return use(resourcePromise(loadFont, [font]));
+}
+
+useFont.preload = (font: FontInput) => preloadResource(loadFont, [font]);
+useFont.clear = (font: FontInput) => clearResource([font]);

package/src/core/useIntersect.three.tsrx

@@ -0,0 +1,38 @@
+import { addAfterEffect, addEffect } from '@octanejs/three';
+import { useEffect, useLayoutEffect, useRef } from '@octanejs/three/renderer';
+import type { Object3D } from 'three';
+
+export function useIntersect<T extends Object3D>(onChange: (visible: boolean) => void) {
+	const ref = useRef<T | null>(null);
+	const check = useRef(false);
+	const previous = useRef(false);
+	const callback = useRef(onChange);
+	useLayoutEffect(() => {
+		callback.current = onChange;
+	}, [onChange]);
+	useEffect(() => {
+		const object = ref.current;
+		if (!object) return;
+		const removeBefore = addEffect(() => {
+			check.current = false;
+			return true;
+		});
+		const oldOnBeforeRender = object.onBeforeRender;
+		object.onBeforeRender = () => {
+			check.current = true;
+		};
+		const removeAfter = addAfterEffect(() => {
+			if (check.current !== previous.current) {
+				previous.current = check.current;
+				callback.current(previous.current);
+			}
+			return true;
+		});
+		return () => {
+			object.onBeforeRender = oldOnBeforeRender;
+			removeBefore();
+			removeAfter();
+		};
+	}, []);
+	return ref;
+}

package/src/core/useSpriteLoader.three.tsrx

@@ -0,0 +1,249 @@
+import { useLoader, useThree } from '@octanejs/three';
+import { useCallback, useLayoutEffect, useMemo, useRef, useState } from '@octanejs/three/renderer';
+import * as THREE from 'three';
+import { slotDefault } from './compiler-slot.js';
+
+export type Size = { w: number; h: number };
+
+export type FrameData = {
+	frame: { x: number; y: number; w: number; h: number };
+	scaleRatio?: number;
+	rotated: boolean;
+	trimmed: boolean;
+	spriteSourceSize: { x: number; y: number; w: number; h: number };
+	sourceSize: Size;
+};
+
+export type MetaData = {
+	version: string;
+	size: Size;
+	rows: number;
+	columns: number;
+	frameWidth: number;
+	frameHeight: number;
+	scale: string;
+};
+
+type Frames = Record<string, FrameData[]> | FrameData[];
+
+export type SpriteData = { frames: Frames; meta: MetaData };
+
+type SpriteMetaDimension = { row: number; col: number };
+
+type SourceFrame = FrameData & { filename?: string };
+
+export const getFirstFrame = (frames: SpriteData['frames'], frameName?: string): FrameData => {
+	if (Array.isArray(frames)) return frames[0];
+	const key = frameName ?? Object.keys(frames)[0];
+	return frames[key][0];
+};
+
+export const checkIfFrameIsEmpty = (frameData: Uint8ClampedArray): boolean => {
+	for (let index = 3; index < frameData.length; index += 4) {
+		if (frameData[index] !== 0) return false;
+	}
+	return true;
+};
+
+export function useSpriteLoader<Url extends string>(
+	input: Url | null,
+	json?: string | null,
+	animationNames?: string[] | null,
+	numberOfFrames?: number | null,
+	onLoad?: (texture: THREE.Texture, textureData?: SpriteData | null) => void,
+	canvasRenderingContext2DSettings?: CanvasRenderingContext2DSettings,
+) {
+	json = slotDefault(json, undefined);
+	animationNames = slotDefault(animationNames, undefined);
+	numberOfFrames = slotDefault(numberOfFrames, undefined);
+	onLoad = slotDefault(onLoad, undefined);
+	canvasRenderingContext2DSettings = slotDefault(canvasRenderingContext2DSettings, undefined);
+	const viewportRef = useRef(useThree((state) => state.viewport));
+	const spriteDataRef = useRef<SpriteData | null>(null);
+	const totalFrames = useRef(0);
+	const inputRef = useRef(input);
+	const jsonRef = useRef(json);
+	const animationFramesRef = useRef(animationNames);
+	const [spriteData, setSpriteData] = useState<SpriteData | null>(null);
+	const [spriteTexture, setSpriteTexture] = useState<THREE.Texture>(new THREE.Texture());
+	const textureLoader = useMemo(() => new THREE.TextureLoader(), []);
+	const [spriteObj, setSpriteObj] = useState<{
+		spriteTexture: THREE.Texture;
+		spriteData: SpriteData | null;
+		aspect: THREE.Vector3;
+	} | null>(null);
+
+	const calculateAspectRatio = useCallback((width: number, height: number, factor: number) => {
+		const viewport = viewportRef.current;
+		const adaptedHeight = height * (viewport.aspect > width / height ? viewport.width / width : viewport.height / height);
+		const adaptedWidth = width * (viewport.aspect > width / height ? viewport.width / width : viewport.height / height);
+		const scaleX = adaptedWidth * factor;
+		const scaleY = adaptedHeight * factor;
+		let finalMaxScaleW = Math.min(1, scaleX);
+		let finalMaxScaleH = Math.min(1, scaleY);
+		if (scaleX > 1) {
+			finalMaxScaleW = 1;
+			finalMaxScaleH = scaleY / scaleX;
+		}
+		return new THREE.Vector3(finalMaxScaleW, finalMaxScaleH, 1);
+	}, []);
+
+	const getRowsAndColumns = useCallback((texture: THREE.Texture, frames: number) => {
+		if (!texture.image) return { rows: 0, columns: 0, frameWidth: 0, frameHeight: 0, emptyFrames: [] as SpriteMetaDimension[] };
+		const canvas = document.createElement('canvas');
+		const context = canvas.getContext('2d', canvasRenderingContext2DSettings);
+		if (!context) throw new Error('Failed to get 2d context');
+		canvas.width = texture.image.width;
+		canvas.height = texture.image.height;
+		context.drawImage(texture.image, 0, 0);
+		const width = texture.image.width;
+		const height = texture.image.height;
+		const columns = Math.round(Math.sqrt(frames * (width / height)));
+		const rows = Math.round(frames / columns);
+		const frameWidth = width / columns;
+		const frameHeight = height / rows;
+		const emptyFrames: SpriteMetaDimension[] = [];
+		for (let row = 0; row < rows; row++) {
+			for (let column = 0; column < columns; column++) {
+				const frameIndex = row * columns + column;
+				if (frameIndex >= frames) {
+					emptyFrames.push({ row, col: column });
+					continue;
+				}
+				const data = context.getImageData(column * frameWidth, row * frameHeight, frameWidth, frameHeight).data;
+				if (checkIfFrameIsEmpty(data)) emptyFrames.push({ row, col: column });
+			}
+		}
+		return { rows, columns, frameWidth, frameHeight, emptyFrames };
+	}, [canvasRenderingContext2DSettings]);
+
+	const calculateScaleRatio = useCallback((frames: FrameData[] | Record<string, FrameData[]>) => {
+		const process = (values: FrameData[]) => {
+			let largest: { area: number } | null = null;
+			for (const value of values) {
+				const area = value.frame.w * value.frame.h;
+				if (!largest || area > largest.area) largest = { area };
+			}
+			return values.map((value) => {
+				const area = value.frame.w * value.frame.h;
+				return { ...value, scaleRatio: largest ? (area === largest.area ? 1 : Math.sqrt(area / largest.area)) : 1 };
+			});
+		};
+		if (Array.isArray(frames)) return process(frames);
+		const result: Record<string, FrameData[]> = {};
+		for (const key in frames) result[key] = process(frames[key]);
+		return result;
+	}, []);
+
+	const parseFrames = useCallback((): Frames => {
+		const sprites: Record<string, FrameData[]> = {};
+		const data = spriteDataRef.current;
+		const delimiters = animationFramesRef.current;
+		if (!data) return [];
+		if (delimiters && Array.isArray(data.frames)) {
+			for (const delimiter of delimiters) {
+				sprites[delimiter] = [];
+				for (const rawValue of data.frames) {
+					const value = rawValue as SourceFrame;
+					if (typeof value.filename === 'string' && value.filename.toLowerCase().includes(delimiter.toLowerCase())) {
+						sprites[delimiter].push({ ...value, frame: value.frame, sourceSize: { w: value.sourceSize.w, h: value.sourceSize.h } });
+					}
+				}
+			}
+			for (const key in sprites) sprites[key] = calculateScaleRatio(sprites[key]) as FrameData[];
+			return sprites;
+		}
+		if (delimiters && typeof data.frames === 'object') {
+			for (const delimiter of delimiters) {
+				sprites[delimiter] = [];
+				for (const innerKey in data.frames) {
+					const value = (data.frames as Record<string, FrameData[]>)[innerKey] as unknown as SourceFrame;
+					if (innerKey.toLowerCase().includes(delimiter.toLowerCase())) {
+						sprites[delimiter].push({ ...value, frame: value.frame, sourceSize: { w: value.sourceSize.w, h: value.sourceSize.h } });
+					}
+				}
+			}
+			for (const key in sprites) sprites[key] = calculateScaleRatio(sprites[key]) as FrameData[];
+			return sprites;
+		}
+		const values = (Array.isArray(data.frames) ? data.frames : Object.values(data.frames).flat()).map((value) => ({
+			...value,
+			x: value.frame.x,
+			y: value.frame.y,
+			w: value.frame.w,
+			h: value.frame.h,
+		}));
+		return calculateScaleRatio(values) as FrameData[];
+	}, [calculateScaleRatio, spriteDataRef]);
+
+	const parseSpriteData = useCallback((jsonData: SpriteData | null, texture: THREE.Texture) => {
+		let aspect = new THREE.Vector3(1, 1, 1);
+		if (jsonData === null) {
+			if (texture && numberOfFrames) {
+				const width = texture.image.width;
+				const height = texture.image.height;
+				totalFrames.current = numberOfFrames;
+				const { rows, columns, frameWidth, frameHeight, emptyFrames } = getRowsAndColumns(texture, numberOfFrames);
+				const generated: SpriteData = { frames: [], meta: { version: '1.0', size: { w: width, h: height }, rows, columns, frameWidth, frameHeight, scale: '1' } };
+				for (let row = 0; row < rows; row++) {
+					for (let column = 0; column < columns; column++) {
+						if (emptyFrames.some((coord) => coord.row === row && coord.col === column)) continue;
+						(generated.frames as FrameData[]).push({
+							frame: { x: column * frameWidth, y: row * frameHeight, w: frameWidth, h: frameHeight },
+							scaleRatio: 1,
+							rotated: false,
+							trimmed: false,
+							spriteSourceSize: { x: 0, y: 0, w: frameWidth, h: frameHeight },
+							sourceSize: { w: frameWidth, h: frameHeight },
+						});
+					}
+				}
+				aspect = calculateAspectRatio(frameWidth, frameHeight, 0.1);
+				spriteDataRef.current = generated;
+			}
+			if (spriteDataRef.current?.frames) spriteDataRef.current.frames = calculateScaleRatio(spriteDataRef.current.frames);
+		} else if (texture) {
+			spriteDataRef.current = jsonData;
+			spriteDataRef.current.frames = parseFrames();
+			totalFrames.current = Array.isArray(jsonData.frames) ? jsonData.frames.length : Object.keys(jsonData.frames).length;
+			const { w, h } = getFirstFrame(jsonData.frames).sourceSize;
+			aspect = calculateAspectRatio(w, h, 0.1);
+		}
+		setSpriteData(spriteDataRef.current);
+		if ('encoding' in texture) (texture as THREE.Texture & { encoding: number }).encoding = 3001;
+		else texture.colorSpace = THREE.SRGBColorSpace;
+		setSpriteTexture(texture);
+		setSpriteObj({ spriteTexture: texture, spriteData: spriteDataRef.current, aspect });
+	}, [getRowsAndColumns, numberOfFrames, parseFrames, calculateAspectRatio, calculateScaleRatio]);
+
+	const loadJsonAndTextureAndExecuteCallback = useCallback((jsonUrl: string, textureUrl: string, callback: (data: SpriteData, texture: THREE.Texture) => void): void => {
+		const jsonPromise = fetch(jsonUrl).then((response) => response.json() as Promise<SpriteData>);
+		const texturePromise = new Promise<THREE.Texture>((resolve) => textureLoader.load(textureUrl, resolve));
+		Promise.all([jsonPromise, texturePromise]).then(([data, texture]) => callback(data, texture));
+	}, [textureLoader]);
+
+	const loadStandaloneSprite = useCallback((textureUrl?: string) => {
+		if (!textureUrl && !inputRef.current) throw new Error('Either textureUrl or input must be provided');
+		const validUrl = textureUrl ?? inputRef.current;
+		if (!validUrl) throw new Error('A valid texture URL must be provided');
+		textureLoader.load(validUrl, (texture) => parseSpriteData(null, texture));
+	}, [textureLoader, parseSpriteData]);
+
+	const loadJsonAndTexture = useCallback((textureUrl: string, jsonUrl?: string) => {
+		if (jsonUrl && textureUrl) loadJsonAndTextureAndExecuteCallback(jsonUrl, textureUrl, parseSpriteData);
+		else loadStandaloneSprite(textureUrl);
+	}, [loadJsonAndTextureAndExecuteCallback, loadStandaloneSprite, parseSpriteData]);
+
+	useLayoutEffect(() => {
+		if (jsonRef.current && inputRef.current) loadJsonAndTextureAndExecuteCallback(jsonRef.current, inputRef.current, parseSpriteData);
+		else if (inputRef.current) loadStandaloneSprite();
+		const currentInput = inputRef.current;
+		return () => { if (currentInput) useLoader.clear(THREE.TextureLoader, currentInput); };
+	}, [loadJsonAndTextureAndExecuteCallback, loadStandaloneSprite, parseSpriteData]);
+
+	useLayoutEffect(() => onLoad?.(spriteTexture, spriteData ?? null), [spriteTexture, spriteData, onLoad]);
+	return { spriteObj, loadJsonAndTexture };
+}
+
+useSpriteLoader.preload = (url: string) => useLoader.preload(THREE.TextureLoader, url);
+useSpriteLoader.clear = (input: string) => useLoader.clear(THREE.TextureLoader, input);

package/src/core/video-texture-resource.ts

@@ -0,0 +1,14 @@
+import type Hls from 'hls.js';
+
+export const IS_BROWSER =
+	typeof window !== 'undefined' &&
+	typeof window.document?.createElement === 'function' &&
+	typeof window.navigator?.userAgent === 'string';
+
+let hlsModule: typeof import('hls.js') | null = null;
+
+export async function getHls(...args: ConstructorParameters<typeof Hls>): Promise<Hls | null> {
+	hlsModule ??= await import('hls.js');
+	const Ctor = hlsModule.default;
+	return Ctor.isSupported() ? new Ctor(...args) : null;
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export * from './web/index';
+export * from './core/index';