@react-three/drei 11.0.0-alpha.5 → 11.0.0-alpha.6

package/index.mjs

@@ -2,9 +2,8 @@ import * as React from 'react';
 import { forwardRef, useImperativeHandle, useMemo, useEffect, useCallback, useRef, useLayoutEffect, useState, Fragment, createContext, useContext, Suspense } from 'react';
 import { useThree, useFrame, extend, createPortal, applyProps, useInstanceHandle, context as context$9, useLoader, addEffect, addAfterEffect } from '@react-three/fiber';
 import * as THREE from 'three';
-import { REVISION, WebGLRenderTarget, Frustum, Matrix4, Vector3, Vector4, Vector2, Color, InstancedInterleavedBuffer, InterleavedBufferAttribute, Object3D, WebGLCubeRenderTarget, HalfFloatType, CubeCamera as CubeCamera$1, EventDispatcher, Euler, Quaternion, MathUtils, TextureLoader, Texture as Texture$1, MeshLambertMaterial, DynamicDrawUsage, CatmullRomCurve3, CubicBezierCurve3, QuadraticBezierCurve3, Shape as Shape$1, CanvasTexture, DoubleSide, PerspectiveCamera as PerspectiveCamera$1, OrthographicCamera as OrthographicCamera$1, AudioListener, AudioLoader, AnimationMixer, BufferAttribute, Box3, Sphere as Sphere$1, InstancedBufferAttribute, DepthTexture, DepthFormat, UnsignedShortType, CubeTextureLoader, DefaultLoadingManager, Ray, Raycaster, Camera, CubeReflectionMapping, EquirectangularReflectionMapping, Scene, RepeatWrapping, Mesh, Spherical } from 'three';
+import { REVISION, WebGLRenderTarget, Frustum, Matrix4, Vector3, Vector4, Vector2, Color, InstancedInterleavedBuffer, InterleavedBufferAttribute, Object3D, WebGLCubeRenderTarget, HalfFloatType, CubeCamera as CubeCamera$1, EventDispatcher, Euler, Quaternion, MathUtils, TextureLoader, Texture as Texture$1, MeshLambertMaterial, DynamicDrawUsage, CatmullRomCurve3, CubicBezierCurve3, QuadraticBezierCurve3, Shape as Shape$1, CanvasTexture, PerspectiveCamera as PerspectiveCamera$1, OrthographicCamera as OrthographicCamera$1, AudioListener, AudioLoader, AnimationMixer, BufferAttribute, Box3, Sphere as Sphere$1, InstancedBufferAttribute, DoubleSide, DepthTexture, DepthFormat, UnsignedShortType, CubeTextureLoader, DefaultLoadingManager, Ray, Raycaster, Camera, CubeReflectionMapping, EquirectangularReflectionMapping, Scene, RepeatWrapping, Mesh, Spherical } from 'three';
 import { ArcballControls as ArcballControls$1 } from 'three/examples/jsm/controls/ArcballControls.js';
-import { useGesture } from '@use-gesture/react';
 import { FirstPersonControls as FirstPersonControls$1 } from 'three/examples/jsm/controls/FirstPersonControls.js';
 import { FlyControls as FlyControls$1 } from 'three/examples/jsm/controls/FlyControls.js';
 import { create as create$1 } from 'zustand';
@@ -13,6 +12,7 @@ import { MapControls as MapControls$1 } from 'three/examples/jsm/controls/MapCon
 import { misc, easing } from 'maath';
 import { OrbitControls as OrbitControls$1 } from 'three/addons/controls/OrbitControls.js';
 import { PointerLockControls as PointerLockControls$1 } from 'three/examples/jsm/controls/PointerLockControls.js';
+import { useGesture } from '@use-gesture/react';
 import * as ReactDOM from 'react-dom/client';
 import { TrackballControls as TrackballControls$1 } from 'three/examples/jsm/controls/TrackballControls.js';
 import { SimplexNoise } from 'three/examples/jsm/math/SimplexNoise.js';
@@ -31,7 +31,6 @@ import { TransformControls as TransformControls$1 } from 'three/examples/jsm/con
 import * as SkeletonUtils from 'three/examples/jsm/utils/SkeletonUtils.js';
 import { MeshSurfaceSampler } from 'three/examples/jsm/math/MeshSurfaceSampler.js';
 import { SVGLoader } from 'three/examples/jsm/loaders/SVGLoader.js';
-import { Events } from 'hls.js';
 import { FBXLoader } from 'three/examples/jsm/loaders/FBXLoader.js';
 import { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader.js';
 import { DRACOLoader } from 'three/examples/jsm/loaders/DRACOLoader.js';
@@ -1444,11 +1443,11 @@ const DeviceOrientationControls = /* @__PURE__ */ React.forwardRef(
 );
 
 const initialModelPosition = /* @__PURE__ */ new THREE.Vector3();
-const mousePosition2D = /* @__PURE__ */ new THREE.Vector2();
 const mousePosition3D = /* @__PURE__ */ new THREE.Vector3();
 const dragOffset = /* @__PURE__ */ new THREE.Vector3();
 const dragPlaneNormal = /* @__PURE__ */ new THREE.Vector3();
 const dragPlane = /* @__PURE__ */ new THREE.Plane();
+const startPointerPos = /* @__PURE__ */ new THREE.Vector3();
 const DragControls = React.forwardRef(
   ({
     autoTransform = true,
@@ -1464,90 +1463,132 @@ const DragControls = React.forwardRef(
     ...props
   }, fRef) => {
     const defaultControls = useThree((state) => state.controls);
-    const { camera, size, raycaster, invalidate } = useThree();
+    const { camera, invalidate } = useThree();
     const ref = React.useRef(null);
-    const bind = useGesture(
-      {
-        onHover: ({ hovering }) => onHover && onHover(hovering ?? false),
-        onDragStart: ({ event }) => {
-          if (defaultControls) defaultControls.enabled = false;
-          const { point } = event;
-          ref.current.matrix.decompose(initialModelPosition, new THREE.Quaternion(), new THREE.Vector3());
-          mousePosition3D.copy(point);
-          dragOffset.copy(mousePosition3D).sub(initialModelPosition);
-          onDragStart && onDragStart(initialModelPosition);
-          invalidate();
-        },
-        onDrag: ({ xy: [dragX, dragY], intentional, event }) => {
-          if (!intentional) return;
-          if (dragConfig && dragConfig.preventOverlap) event.preventDefault();
-          const normalizedMouseX = (dragX - size.left) / size.width * 2 - 1;
-          const normalizedMouseY = -((dragY - size.top) / size.height) * 2 + 1;
-          mousePosition2D.set(normalizedMouseX, normalizedMouseY);
-          raycaster.setFromCamera(mousePosition2D, camera);
-          if (!axisLock) {
-            camera.getWorldDirection(dragPlaneNormal).negate();
-          } else {
-            switch (axisLock) {
-              case "x":
-                dragPlaneNormal.set(1, 0, 0);
-                break;
-              case "y":
-                dragPlaneNormal.set(0, 1, 0);
-                break;
-              case "z":
-                dragPlaneNormal.set(0, 0, 1);
-                break;
-            }
-          }
-          dragPlane.setFromNormalAndCoplanarPoint(dragPlaneNormal, mousePosition3D);
-          raycaster.ray.intersectPlane(dragPlane, mousePosition3D);
-          const previousLocalMatrix = ref.current.matrix.clone();
-          const previousWorldMatrix = ref.current.matrixWorld.clone();
-          const intendedNewPosition = new THREE.Vector3(
-            mousePosition3D.x - dragOffset.x,
-            mousePosition3D.y - dragOffset.y,
-            mousePosition3D.z - dragOffset.z
-          );
-          if (dragLimits) {
-            intendedNewPosition.x = dragLimits[0] ? Math.max(Math.min(intendedNewPosition.x, dragLimits[0][1]), dragLimits[0][0]) : intendedNewPosition.x;
-            intendedNewPosition.y = dragLimits[1] ? Math.max(Math.min(intendedNewPosition.y, dragLimits[1][1]), dragLimits[1][0]) : intendedNewPosition.y;
-            intendedNewPosition.z = dragLimits[2] ? Math.max(Math.min(intendedNewPosition.z, dragLimits[2][1]), dragLimits[2][0]) : intendedNewPosition.z;
-          }
-          if (autoTransform) {
-            ref.current.matrix.setPosition(intendedNewPosition);
-            const deltaLocalMatrix = ref.current.matrix.clone().multiply(previousLocalMatrix.invert());
-            const deltaWorldMatrix = ref.current.matrix.clone().multiply(previousWorldMatrix.invert());
-            onDrag && onDrag(ref.current.matrix, deltaLocalMatrix, ref.current.matrixWorld, deltaWorldMatrix);
-          } else {
-            const tempMatrix = new THREE.Matrix4().copy(ref.current.matrix);
-            tempMatrix.setPosition(intendedNewPosition);
-            const deltaLocalMatrix = tempMatrix.clone().multiply(previousLocalMatrix.invert());
-            const deltaWorldMatrix = tempMatrix.clone().multiply(previousWorldMatrix.invert());
-            onDrag && onDrag(tempMatrix, deltaLocalMatrix, ref.current.matrixWorld, deltaWorldMatrix);
+    const dragState = React.useRef({
+      active: false,
+      intentional: false,
+      // Has moved past threshold
+      pointerId: -1
+    });
+    const threshold = dragConfig?.threshold ?? 0;
+    const filterTaps = dragConfig?.filterTaps ?? true;
+    const handlePointerDown = React.useCallback(
+      (event) => {
+        event.stopPropagation();
+        event.target.setPointerCapture(event.pointerId);
+        dragState.current.active = true;
+        dragState.current.intentional = threshold === 0;
+        dragState.current.pointerId = event.pointerId;
+        if (defaultControls) defaultControls.enabled = false;
+        ref.current.matrix.decompose(initialModelPosition, new THREE.Quaternion(), new THREE.Vector3());
+        mousePosition3D.copy(event.point);
+        startPointerPos.copy(event.point);
+        dragOffset.copy(mousePosition3D).sub(initialModelPosition);
+        if (!axisLock) {
+          camera.getWorldDirection(dragPlaneNormal).negate();
+        } else {
+          switch (axisLock) {
+            case "x":
+              dragPlaneNormal.set(1, 0, 0);
+              break;
+            case "y":
+              dragPlaneNormal.set(0, 1, 0);
+              break;
+            case "z":
+              dragPlaneNormal.set(0, 0, 1);
+              break;
           }
-          invalidate();
-        },
-        onDragEnd: () => {
-          if (defaultControls) defaultControls.enabled = true;
-          onDragEnd && onDragEnd();
-          invalidate();
         }
+        dragPlane.setFromNormalAndCoplanarPoint(dragPlaneNormal, mousePosition3D);
+        if (dragState.current.intentional) {
+          onDragStart && onDragStart(initialModelPosition);
+        }
+        invalidate();
+      },
+      [defaultControls, camera, axisLock, threshold, onDragStart, invalidate]
+    );
+    const handlePointerMove = React.useCallback(
+      (event) => {
+        if (!dragState.current.active || event.pointerId !== dragState.current.pointerId) return;
+        const intersection = event.ray.intersectPlane(dragPlane, mousePosition3D);
+        if (!intersection) return;
+        if (!dragState.current.intentional) {
+          const distance = mousePosition3D.distanceTo(startPointerPos);
+          if (distance < threshold) return;
+          dragState.current.intentional = true;
+          onDragStart && onDragStart(initialModelPosition);
+        }
+        const previousLocalMatrix = ref.current.matrix.clone();
+        const previousWorldMatrix = ref.current.matrixWorld.clone();
+        const intendedNewPosition = new THREE.Vector3(
+          mousePosition3D.x - dragOffset.x,
+          mousePosition3D.y - dragOffset.y,
+          mousePosition3D.z - dragOffset.z
+        );
+        if (dragLimits) {
+          intendedNewPosition.x = dragLimits[0] ? Math.max(Math.min(intendedNewPosition.x, dragLimits[0][1]), dragLimits[0][0]) : intendedNewPosition.x;
+          intendedNewPosition.y = dragLimits[1] ? Math.max(Math.min(intendedNewPosition.y, dragLimits[1][1]), dragLimits[1][0]) : intendedNewPosition.y;
+          intendedNewPosition.z = dragLimits[2] ? Math.max(Math.min(intendedNewPosition.z, dragLimits[2][1]), dragLimits[2][0]) : intendedNewPosition.z;
+        }
+        if (autoTransform) {
+          ref.current.matrix.setPosition(intendedNewPosition);
+          const deltaLocalMatrix = ref.current.matrix.clone().multiply(previousLocalMatrix.invert());
+          const deltaWorldMatrix = ref.current.matrix.clone().multiply(previousWorldMatrix.invert());
+          onDrag && onDrag(ref.current.matrix, deltaLocalMatrix, ref.current.matrixWorld, deltaWorldMatrix);
+        } else {
+          const tempMatrix = new THREE.Matrix4().copy(ref.current.matrix);
+          tempMatrix.setPosition(intendedNewPosition);
+          const deltaLocalMatrix = tempMatrix.clone().multiply(previousLocalMatrix.invert());
+          const deltaWorldMatrix = tempMatrix.clone().multiply(previousWorldMatrix.invert());
+          onDrag && onDrag(tempMatrix, deltaLocalMatrix, ref.current.matrixWorld, deltaWorldMatrix);
+        }
+        invalidate();
       },
-      {
-        drag: {
-          filterTaps: true,
-          threshold: 1,
-          ...typeof dragConfig === "object" ? dragConfig : {}
+      [autoTransform, dragLimits, threshold, onDragStart, onDrag, invalidate]
+    );
+    const handlePointerUp = React.useCallback(
+      (event) => {
+        if (!dragState.current.active || event.pointerId !== dragState.current.pointerId) return;
+        event.target.releasePointerCapture(event.pointerId);
+        const wasIntentional = dragState.current.intentional;
+        dragState.current.active = false;
+        dragState.current.intentional = false;
+        dragState.current.pointerId = -1;
+        if (defaultControls) defaultControls.enabled = true;
+        if (wasIntentional || !filterTaps) {
+          onDragEnd && onDragEnd();
         }
-      }
+        invalidate();
+      },
+      [defaultControls, filterTaps, onDragEnd, invalidate]
     );
+    const handlePointerEnter = React.useCallback(() => {
+      onHover && onHover(true);
+    }, [onHover]);
+    const handlePointerLeave = React.useCallback(() => {
+      onHover && onHover(false);
+    }, [onHover]);
     React.useImperativeHandle(fRef, () => ref.current, []);
     React.useLayoutEffect(() => {
       if (!matrix) return;
       ref.current.matrix = matrix;
     }, [matrix]);
-    return /* @__PURE__ */ React.createElement("group", { ref, ...bind(), matrix, matrixAutoUpdate: false, ...props }, children);
+    return /* @__PURE__ */ React.createElement(
+      "group",
+      {
+        ref,
+        onPointerDown: handlePointerDown,
+        onPointerMove: handlePointerMove,
+        onPointerUp: handlePointerUp,
+        onPointerEnter: handlePointerEnter,
+        onPointerLeave: handlePointerLeave,
+        matrix,
+        matrixAutoUpdate: false,
+        ...props
+      },
+      children
+    );
   }
 );
 
@@ -1665,7 +1706,7 @@ function KeyboardControls({ map, children, onChange, domElement }) {
       source.removeEventListener("keyup", upHandler);
       window.removeEventListener("blur", blurHandler);
     };
-  }, [domElement, key]);
+  }, [domElement, key, onChange]);
   return /* @__PURE__ */ React.createElement(context$8.Provider, { value: api, children });
 }
 function useKeyboardControls(sel) {
@@ -1687,20 +1728,28 @@ const MapControls = /* @__PURE__ */ React.forwardRef((props = { enableDamping: t
   const controls = React.useMemo(() => new MapControls$1(explCamera), [explCamera]);
   React.useEffect(() => {
     controls.connect(explDomElement);
+    return () => void controls.dispose();
+  }, [explDomElement, controls]);
+  React.useEffect(() => {
     const callback = (e) => {
       invalidate();
       if (onChange) onChange(e);
     };
+    const onStartCb = (e) => {
+      if (onStart) onStart(e);
+    };
+    const onEndCb = (e) => {
+      if (onEnd) onEnd(e);
+    };
     controls.addEventListener("change", callback);
-    if (onStart) controls.addEventListener("start", onStart);
-    if (onEnd) controls.addEventListener("end", onEnd);
+    controls.addEventListener("start", onStartCb);
+    controls.addEventListener("end", onEndCb);
     return () => {
-      controls.dispose();
+      controls.removeEventListener("start", onStartCb);
+      controls.removeEventListener("end", onEndCb);
       controls.removeEventListener("change", callback);
-      if (onStart) controls.removeEventListener("start", onStart);
-      if (onEnd) controls.removeEventListener("end", onEnd);
     };
-  }, [onChange, onStart, onEnd, controls, invalidate, explDomElement]);
+  }, [onChange, onStart, onEnd, controls, invalidate]);
   React.useEffect(() => {
     if (makeDefault) {
       const old = get().controls;
@@ -1708,7 +1757,9 @@ const MapControls = /* @__PURE__ */ React.forwardRef((props = { enableDamping: t
       return () => set({ controls: old });
     }
   }, [makeDefault, controls]);
-  useFrame(() => controls.update(), -1);
+  useFrame(() => {
+    if (controls.enabled) controls.update();
+  }, -1);
   return /* @__PURE__ */ React.createElement("primitive", { ref, object: controls, enableDamping: true, ...rest });
 });
 
@@ -1834,20 +1885,16 @@ const OrbitControls = /* @__PURE__ */ React.forwardRef(
     onEnd,
     ...restProps
   }, ref) => {
-    const invalidate = useThree((state) => state.invalidate);
-    const defaultCamera = useThree((state) => state.camera);
-    const gl = useThree((state) => state.gl);
-    const events = useThree((state) => state.events);
-    const setEvents = useThree((state) => state.setEvents);
-    const set = useThree((state) => state.set);
-    const get = useThree((state) => state.get);
-    const performance = useThree((state) => state.performance);
+    const { invalidate, camera: defaultCamera, renderer, events, setEvents, set, get, performance } = useThree();
     const explCamera = camera || defaultCamera;
-    const explDomElement = domElement || events.connected || gl.domElement;
+    const explDomElement = domElement || events.connected || renderer.domElement;
     const controls = React.useMemo(() => new OrbitControls$1(explCamera), [explCamera]);
-    useFrame(() => {
-      if (controls.enabled) controls.update();
-    }, -1);
+    useFrame(
+      () => {
+        if (controls.enabled) controls.update();
+      },
+      { before: "update" }
+    );
     React.useEffect(() => {
       if (keyEvents) {
         controls.connect(keyEvents === true ? explDomElement : keyEvents);
@@ -1961,9 +2008,8 @@ function PresentationControls({
   azimuth = [-Infinity, Infinity],
   damping = 0.25
 }) {
-  const events = useThree((state) => state.events);
-  const gl = useThree((state) => state.gl);
-  const explDomElement = domElement || events.connected || gl.domElement;
+  const { events, renderer, invalidate } = useThree();
+  const explDomElement = domElement || events.connected || renderer.domElement;
   const { size } = useThree();
   const rPolar = React.useMemo(
     () => [rotation[0] + polar[0], rotation[0] + polar[1]],
@@ -1980,18 +2026,20 @@ function PresentationControls({
   React.useEffect(() => {
     if (global && cursor && enabled) {
       explDomElement.style.cursor = "grab";
-      gl.domElement.style.cursor = "";
+      renderer.domElement.style.cursor = "";
       return () => {
         explDomElement.style.cursor = "default";
-        gl.domElement.style.cursor = "default";
+        renderer.domElement.style.cursor = "default";
       };
     }
   }, [global, cursor, explDomElement, enabled]);
   const [animation] = React.useState({ scale: 1, rotation: rInitial, damping });
   const ref = React.useRef(null);
   useFrame((state, delta) => {
-    easing.damp3(ref.current.scale, animation.scale, animation.damping, delta);
-    easing.dampE(ref.current.rotation, animation.rotation, animation.damping, delta);
+    let changed = false;
+    changed ||= easing.damp3(ref.current.scale, animation.scale, animation.damping, delta);
+    changed ||= easing.dampE(ref.current.rotation, animation.rotation, animation.damping, delta);
+    if (changed) state.invalidate();
   });
   const bind = useGesture(
     {
@@ -1999,6 +2047,7 @@ function PresentationControls({
         if (cursor && !global && enabled) explDomElement.style.cursor = last ? "auto" : "grab";
       },
       onDrag: ({ down, delta: [x, y], memo: [oldY, oldX] = animation.rotation || rInitial }) => {
+        invalidate();
         if (!enabled) return [y, x];
         if (cursor) explDomElement.style.cursor = down ? "grabbing" : "grab";
         x = MathUtils.clamp(oldX + x / size.width * Math.PI * speed, ...rAzimuth);
@@ -2007,9 +2056,12 @@ function PresentationControls({
         animation.rotation = snap && !down ? rInitial : [y, x, 0];
         animation.damping = snap && !down && typeof snap !== "boolean" ? snap : damping;
         return [y, x];
+      },
+      onDragEnd: () => {
+        invalidate();
       }
     },
-    { target: global ? explDomElement : void 0 }
+    { target: global ? explDomElement : void 0, enabled }
   );
   return /* @__PURE__ */ React.createElement("group", { ref, ...bind?.() }, children);
 }
@@ -2018,6 +2070,10 @@ function roundToPixelRatio(value) {
   const ratio = window.devicePixelRatio || 1;
   return Math.round(value * ratio) / ratio;
 }
+function getMaxAnisotropy(renderer) {
+  const r = renderer;
+  return r?.getMaxAnisotropy?.() ?? r?.capabilities?.getMaxAnisotropy?.() ?? 1;
+}
 
 const context$7 = /* @__PURE__ */ React.createContext(null);
 const rootCache = /* @__PURE__ */ new WeakMap();
@@ -2044,6 +2100,7 @@ function ScrollControls({
   const [fixed] = React.useState(() => document.createElement("div"));
   const target = gl.domElement.parentNode;
   const scroll = React.useRef(0);
+  const disableScrollUpdate = React.useRef(false);
   const state = React.useMemo(() => {
     const state2 = {
       el,
@@ -2125,16 +2182,20 @@ function ScrollControls({
       const scrollLength = el[horizontal ? "scrollWidth" : "scrollHeight"];
       const scrollThreshold = scrollLength - containerLength;
       let current = 0;
-      let disableScroll = true;
+      let disableScroll = false;
       let firstRun = true;
       const onScroll = () => {
         if (!enabled || firstRun) return;
+        if (disableScrollUpdate.current) {
+          disableScrollUpdate.current = false;
+          return;
+        }
         invalidate();
         current = el[horizontal ? "scrollLeft" : "scrollTop"];
         scroll.current = current / scrollThreshold;
         if (infinite) {
           if (!disableScroll) {
-            if (current >= scrollThreshold) {
+            if (current >= scrollThreshold - 1) {
               const damp = 1 - state.offset;
               el[horizontal ? "scrollLeft" : "scrollTop"] = 1;
               scroll.current = state.offset = -damp;
@@ -2151,11 +2212,34 @@ function ScrollControls({
       };
       el.addEventListener("scroll", onScroll, { passive: true });
       requestAnimationFrame(() => firstRun = false);
-      const onWheel = (e) => el.scrollLeft += e.deltaY / 2;
-      if (horizontal) el.addEventListener("wheel", onWheel, { passive: true });
+      const onResize = () => {
+        if (!el) return;
+        const scrollLength2 = el[horizontal ? "scrollWidth" : "scrollHeight"];
+        const containerLength2 = el[horizontal ? "clientWidth" : "clientHeight"];
+        disableScrollUpdate.current = true;
+        el[horizontal ? "scrollLeft" : "scrollTop"] = state.offset * (scrollLength2 - containerLength2);
+      };
+      const onWheel = (e) => {
+        if (horizontal) {
+          const previous = el.scrollLeft;
+          el.scrollLeft += e.deltaY / 2;
+          if (infinite && previous === el.scrollLeft) {
+            onScroll();
+          }
+        } else if (infinite) {
+          if (el.scrollTop <= 1 && e.deltaY < 0) {
+            onScroll();
+          } else if (el.scrollTop >= el.scrollHeight - el.clientHeight - 1 && e.deltaY > 0) {
+            onScroll();
+          }
+        }
+      };
+      if (horizontal || infinite) el.addEventListener("wheel", onWheel, { passive: true });
+      if (horizontal) window.addEventListener("resize", onResize);
       return () => {
         el.removeEventListener("scroll", onScroll);
-        if (horizontal) el.removeEventListener("wheel", onWheel);
+        if (horizontal || infinite) el.removeEventListener("wheel", onWheel);
+        if (horizontal) window.removeEventListener("resize", onResize);
       };
     }
   }, [el, events, size, infinite, state, invalidate, horizontal, enabled]);
@@ -2572,10 +2656,10 @@ const CloudInstance = /* @__PURE__ */ React.forwardRef(
     return /* @__PURE__ */ React.createElement("group", { ref, ...props });
   }
 );
-const Cloud = /* @__PURE__ */ React.forwardRef((props, fref) => {
+const Cloud = /* @__PURE__ */ React.forwardRef(({ materialFactory, ...props }, fref) => {
   const parent = React.useContext(context$6);
   if (parent) return /* @__PURE__ */ React.createElement(CloudInstance, { ref: fref, ...props });
-  return /* @__PURE__ */ React.createElement(Clouds, null, /* @__PURE__ */ React.createElement(CloudInstance, { ref: fref, ...props }));
+  return /* @__PURE__ */ React.createElement(Clouds, { materialFactory }, /* @__PURE__ */ React.createElement(CloudInstance, { ref: fref, ...props }));
 });
 
 const CatmullRomLine = /* @__PURE__ */ React.forwardRef(function CatmullRomLine2({
@@ -3097,7 +3181,7 @@ const Text3D = /* @__PURE__ */ React.forwardRef(
       return {
         font,
         size,
-        height,
+        depth: height,
         bevelThickness,
         bevelSize,
         bevelEnabled,
@@ -3280,7 +3364,7 @@ const FaceMaterial = ({
     "meshBasicMaterial",
     {
       map: texture,
-      "map-anisotropy": renderer.getMaxAnisotropy() || 1,
+      "map-anisotropy": getMaxAnisotropy(renderer),
       attach: `material-${index}`,
       color: hover ? hoverColor : "white",
       transparent: true,
@@ -3391,7 +3475,7 @@ function AxisHead({
       "spriteMaterial",
       {
         map: texture,
-        "map-anisotropy": renderer.getMaxAnisotropy() || 1,
+        "map-anisotropy": getMaxAnisotropy(renderer),
         alphaTest: 0.3,
         opacity: label ? 1 : 0.75,
         toneMapped: false
@@ -3536,6 +3620,7 @@ const Html = /* @__PURE__ */ React.forwardRef(
   }, ref) => {
     const { gl, camera, scene, size, raycaster, events, viewport } = useThree();
     const forceEven = useThree((state) => state.internal.forceEven);
+    const { frustum } = useThree();
     const [el] = React.useState(() => document.createElement(as));
     const root = React.useRef(null);
     const group = React.useRef(null);
@@ -3565,22 +3650,18 @@ const Html = /* @__PURE__ */ React.forwardRef(
       if (group.current) {
         if (!root.current) {
           root.current = ReactDOM.createRoot(el);
-        }
-        scene.updateMatrixWorld();
-        if (transform) {
-          el.style.cssText = `position:absolute;top:0;left:0;pointer-events:none;overflow:hidden;`;
-        } else {
-          el.style.cssText = `position:absolute;top:0;left:0;transform:translate3d(0,-9999px,0);transform-origin:0 0;`;
+          scene.updateMatrixWorld();
+          if (transform) {
+            el.style.cssText = `position:absolute;top:0;left:0;pointer-events:none;overflow:hidden;`;
+          } else {
+            el.style.cssText = `position:absolute;top:0;left:0;transform:translate3d(0,-9999px,0);transform-origin:0 0;`;
+          }
         }
         if (target) {
           if (prepend) target.prepend(el);
           else target.appendChild(el);
         }
         return () => {
-          if (root.current) {
-            root.current.unmount();
-            root.current = null;
-          }
           if (target && target.contains(el)) {
             target.removeChild(el);
           }
@@ -3714,8 +3795,7 @@ const Html = /* @__PURE__ */ React.forwardRef(
           if (transformOuterRef.current) {
             const el2 = transformOuterRef.current.children[0];
             if (el2?.clientWidth && el2?.clientHeight) {
-              const { isOrthographicCamera } = camera;
-              if (isOrthographicCamera || geometry) {
+              if (geometry) {
                 if (props.scale) {
                   if (!Array.isArray(props.scale)) {
                     occlusionMeshRef.current.scale.setScalar(1 / props.scale);
@@ -3747,64 +3827,7 @@ const Html = /* @__PURE__ */ React.forwardRef(
         }
       }
     });
-    const shaders = React.useMemo(
-      () => ({
-        vertexShader: !transform ? (
-          /* glsl */
-          `
-          /*
-            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;
-          }
-      `
-        ) : void 0,
-        fragmentShader: (
-          /* glsl */
-          `
-        void main() {
-          gl_FragColor = vec4(0.0, 0.0, 0.0, 0.0);
-        }
-      `
-        )
-      }),
-      [transform]
-    );
-    return /* @__PURE__ */ React.createElement("group", { ...props, ref: group }, occlude && !isRayCastOcclusion && /* @__PURE__ */ React.createElement("mesh", { castShadow, receiveShadow, ref: occlusionMeshRef }, geometry || /* @__PURE__ */ React.createElement("planeGeometry", null), material || /* @__PURE__ */ React.createElement(
-      "shaderMaterial",
-      {
-        side: DoubleSide,
-        vertexShader: shaders.vertexShader,
-        fragmentShader: shaders.fragmentShader
-      }
-    )));
+    return /* @__PURE__ */ React.createElement("group", { ...props, ref: group }, occlude && !isRayCastOcclusion && /* @__PURE__ */ React.createElement("mesh", { castShadow, receiveShadow, ref: occlusionMeshRef }, geometry || /* @__PURE__ */ React.createElement("planeGeometry", null), material));
   }
 );
 
@@ -4657,6 +4680,7 @@ const mW = /* @__PURE__ */ new THREE.Matrix4();
 const mL = /* @__PURE__ */ new THREE.Matrix4();
 const mL0Inv = /* @__PURE__ */ new THREE.Matrix4();
 const mdL = /* @__PURE__ */ new THREE.Matrix4();
+const mdW = /* @__PURE__ */ new THREE.Matrix4();
 const mG = /* @__PURE__ */ new THREE.Matrix4();
 const bb = /* @__PURE__ */ new THREE.Box3();
 const bbObj = /* @__PURE__ */ new THREE.Box3();
@@ -4771,7 +4795,8 @@ const PivotControls = /* @__PURE__ */ React.forwardRef(
           onDragStart && onDragStart(props2);
           invalidate();
         },
-        onDrag: (mdW) => {
+        onDrag: (mdW_) => {
+          mdW.copy(mdW_);
           mP.copy(parentRef.current.matrixWorld);
           mPInv.copy(mP).invert();
           mW.copy(mW0).premultiply(mdW);
@@ -4783,12 +4808,12 @@ const PivotControls = /* @__PURE__ */ React.forwardRef(
           }
           const target = resolveObject(object);
           if (target) target.matrix.copy(mL);
-          onDrag && onDrag(mL, mdL, mW, mdW);
+          onDrag && onDrag({ local: mL, deltaLocal: mdL, world: mW, deltaWorld: mdW });
           invalidate();
         },
         onDragEnd: () => {
           dragState.current = null;
-          if (onDragEnd) onDragEnd();
+          if (onDragEnd) onDragEnd({ local: mL, deltaLocal: mdL, world: mW, deltaWorld: mdW });
           invalidate();
         },
         onHover: (props2) => {
@@ -4899,7 +4924,9 @@ const TransformControls = /* @__PURE__ */ React.forwardRef(
     const group = React.useRef(null);
     React.useLayoutEffect(() => {
       if (object) {
-        controls.attach(object instanceof THREE.Object3D ? object : object.current);
+        controls.attach(
+          object instanceof THREE.Object3D ? object : object.current
+        );
       } else if (group.current instanceof THREE.Object3D) {
         controls.attach(group.current);
       }
@@ -4995,7 +5022,7 @@ const PointMaterial = /* @__PURE__ */ React.forwardRef((props, ref) => {
   return /* @__PURE__ */ React.createElement("primitive", { ...props, object: material, ref, attach: "material" });
 });
 
-const PositionalAudio = /* @__PURE__ */ React.forwardRef(({ url, distance = 1, loop = true, autoplay, ...props }, ref) => {
+const PositionalAudio = /* @__PURE__ */ React.forwardRef(({ url, distance = 1, loop = false, autoplay, ...props }, ref) => {
   const sound = React.useRef(null);
   React.useImperativeHandle(ref, () => sound.current, []);
   const camera = useThree(({ camera: camera2 }) => camera2);
@@ -5007,7 +5034,9 @@ const PositionalAudio = /* @__PURE__ */ React.forwardRef(({ url, distance = 1, l
       _sound.setBuffer(Array.isArray(buffer) ? buffer[0] : buffer);
       _sound.setRefDistance(distance);
       _sound.setLoop(loop);
-      if (autoplay && !_sound.isPlaying) _sound.play();
+      if (autoplay && !_sound.isPlaying) {
+        _sound.play();
+      }
     }
   }, [buffer, camera, distance, loop]);
   React.useEffect(() => {
@@ -5076,7 +5105,6 @@ const tempMatrix = /* @__PURE__ */ new THREE.Matrix4();
 const translation = /* @__PURE__ */ new THREE.Vector3();
 const rotation = /* @__PURE__ */ new THREE.Quaternion();
 const scale = /* @__PURE__ */ new THREE.Vector3();
-const isInstancedBufferAttribute = (attr) => attr.isInstancedBufferAttribute;
 const Instance = /* @__PURE__ */ React.forwardRef(({ context, children, ...props }, ref) => {
   React.useMemo(() => extend({ PositionMesh }), []);
   const group = React.useRef(null);
@@ -5096,24 +5124,20 @@ const Instances = /* @__PURE__ */ React.forwardRef(({ context, children, range,
   const parentRef = React.useRef(null);
   React.useImperativeHandle(ref, () => parentRef.current, []);
   const [instances, setInstances] = React.useState([]);
+  const boundsDirty = React.useRef(true);
   const [[matrices, colors]] = React.useState(() => {
     const mArray = new Float32Array(limit * 16);
     for (let i = 0; i < limit; i++) tempMatrix.identity().toArray(mArray, i * 16);
     return [mArray, new Float32Array([...new Array(limit * 3)].map(() => 1))];
   });
   React.useEffect(() => {
-    parentRef.current.instanceMatrix.needsUpdate = true;
+    if (parentRef.current) parentRef.current.instanceMatrix.needsUpdate = true;
   });
   let iterations = 0;
   let count = 0;
-  const attributes = React.useRef([]);
-  React.useLayoutEffect(() => {
-    attributes.current = Object.entries(parentRef.current.geometry.attributes).filter(
-      ([_name, value]) => isInstancedBufferAttribute(value)
-    );
-  });
   useFrame(() => {
     if (frames === Infinity || iterations < frames) {
+      if (!parentRef.current) return;
       parentRef.current.updateMatrix();
       parentRef.current.updateMatrixWorld();
       parentMatrix.copy(parentRef.current.matrixWorld).invert();
@@ -5134,13 +5158,22 @@ const Instances = /* @__PURE__ */ React.forwardRef(({ context, children, range,
       }
       iterations++;
     }
+    if (boundsDirty.current && (frames === Infinity || iterations === frames)) {
+      boundsDirty.current = false;
+      if (parentRef.current.boundingBox) parentRef.current.computeBoundingBox();
+      if (parentRef.current.boundingSphere) parentRef.current.computeBoundingSphere();
+    }
   });
   const api = React.useMemo(
     () => ({
       getParent: () => parentRef,
       subscribe: (ref2) => {
         setInstances((instances2) => [...instances2, ref2]);
-        return () => setInstances((instances2) => instances2.filter((item) => item.current !== ref2.current));
+        boundsDirty.current = true;
+        return () => {
+          setInstances((instances2) => instances2.filter((item) => item.current !== ref2.current));
+          boundsDirty.current = true;
+        };
       }
     }),
     []
@@ -5165,10 +5198,23 @@ const Merged = /* @__PURE__ */ React.forwardRef(function Merged2({ meshes, child
   if (!isArray) {
     for (const key of Object.keys(meshes)) if (!meshes[key].isMesh) delete meshes[key];
   }
-  const render = (args) => isArray ? children(...args) : children(
-    Object.keys(meshes).filter((key) => meshes[key].isMesh).reduce((acc, key, i) => ({ ...acc, [key]: args[i] }), {})
-  );
-  const components = (isArray ? meshes : Object.values(meshes)).map(({ geometry, material }) => /* @__PURE__ */ React.createElement(Instances, { key: geometry.uuid, geometry, material, ...props }));
+  const render = (args) => {
+    if (isArray) {
+      return children(
+        ...args
+      );
+    }
+    const instanceMap = {};
+    const keys = Object.keys(meshes).filter((key) => meshes[key].isMesh);
+    keys.forEach((key, i) => {
+      instanceMap[key] = args[i];
+    });
+    return children(instanceMap);
+  };
+  const components = (isArray ? meshes : Object.values(meshes)).map((mesh) => {
+    const { geometry, material } = mesh;
+    return /* @__PURE__ */ React.createElement(Instances, { key: geometry.uuid, geometry, material, ...props });
+  });
   return /* @__PURE__ */ React.createElement("group", { ref }, renderRecursive(render, components));
 });
 function renderRecursive(render, components, results = []) {
@@ -6242,12 +6288,13 @@ function Sampler({ children, weight, transform, instances, mesh, count = 16, ...
   return /* @__PURE__ */ React.createElement("group", { ref: group, ...props }, children);
 }
 
+const pathStyle = (path) => path.userData?.style;
 const Svg = /* @__PURE__ */ forwardRef(
   function R3FSvg({ src, skipFill, skipStrokes, fillMaterial, strokeMaterial, fillMeshProps, strokeMeshProps, ...props }, ref) {
     const svg = useLoader(SVGLoader, !src.startsWith("<svg") ? src : `data:image/svg+xml;utf8,${src}`);
     const strokeGeometries = useMemo(
       () => skipStrokes ? [] : svg.paths.map(
-        (path) => path.userData?.style.stroke === void 0 || path.userData.style.stroke === "none" ? null : path.subPaths.map((subPath) => SVGLoader.pointsToStroke(subPath.getPoints(), path.userData.style))
+        (path) => pathStyle(path)?.stroke === void 0 || pathStyle(path).stroke === "none" ? null : path.subPaths.map((subPath) => SVGLoader.pointsToStroke(subPath.getPoints(), pathStyle(path)))
       ),
       [svg, skipStrokes]
     );
@@ -6255,21 +6302,21 @@ const Svg = /* @__PURE__ */ forwardRef(
       return () => strokeGeometries.forEach((group) => group && group.map((g) => g.dispose()));
     }, [strokeGeometries]);
     let renderOrder = 0;
-    return /* @__PURE__ */ React.createElement("object3D", { ref, ...props }, /* @__PURE__ */ React.createElement("object3D", { scale: [1, -1, 1] }, svg.paths.map((path, p) => /* @__PURE__ */ React.createElement(Fragment, { key: p }, !skipFill && path.userData?.style.fill !== void 0 && path.userData.style.fill !== "none" && SVGLoader.createShapes(path).map((shape, s) => /* @__PURE__ */ React.createElement("mesh", { key: s, ...fillMeshProps, renderOrder: renderOrder++ }, /* @__PURE__ */ React.createElement("shapeGeometry", { args: [shape] }), /* @__PURE__ */ React.createElement(
+    return /* @__PURE__ */ React.createElement("object3D", { ref, ...props }, /* @__PURE__ */ React.createElement("object3D", { scale: [1, -1, 1] }, svg.paths.map((path, p) => /* @__PURE__ */ React.createElement(Fragment, { key: p }, !skipFill && pathStyle(path)?.fill !== void 0 && pathStyle(path).fill !== "none" && SVGLoader.createShapes(path).map((shape, s) => /* @__PURE__ */ React.createElement("mesh", { key: s, ...fillMeshProps, renderOrder: renderOrder++ }, /* @__PURE__ */ React.createElement("shapeGeometry", { args: [shape] }), /* @__PURE__ */ React.createElement(
       "meshBasicMaterial",
       {
-        color: path.userData.style.fill,
-        opacity: path.userData.style.fillOpacity,
+        color: pathStyle(path).fill,
+        opacity: pathStyle(path).fillOpacity,
         transparent: true,
         side: DoubleSide,
         depthWrite: false,
         ...fillMaterial
       }
-    ))), !skipStrokes && path.userData?.style.stroke !== void 0 && path.userData.style.stroke !== "none" && path.subPaths.map((_subPath, s) => /* @__PURE__ */ React.createElement("mesh", { key: s, geometry: strokeGeometries[p][s], ...strokeMeshProps, renderOrder: renderOrder++ }, /* @__PURE__ */ React.createElement(
+    ))), !skipStrokes && pathStyle(path)?.stroke !== void 0 && pathStyle(path).stroke !== "none" && path.subPaths.map((_subPath, s) => /* @__PURE__ */ React.createElement("mesh", { key: s, geometry: strokeGeometries[p][s], ...strokeMeshProps, renderOrder: renderOrder++ }, /* @__PURE__ */ React.createElement(
       "meshBasicMaterial",
       {
-        color: path.userData.style.stroke,
-        opacity: path.userData.style.strokeOpacity,
+        color: pathStyle(path).stroke,
+        opacity: pathStyle(path).strokeOpacity,
         transparent: true,
         side: DoubleSide,
         depthWrite: false,
@@ -6492,8 +6539,8 @@ function useVideoTexture(srcOrSrcObject, {
       });
       if (src && IS_BROWSER && src.endsWith(".m3u8")) {
         const hls = hlsRef.current = await getHls(hlsConfig);
-        if (hls) {
-          hls.on(Events.MEDIA_ATTACHED, () => void hls.loadSource(src));
+        if (hls && _HLSModule) {
+          hls.on(_HLSModule.Events.MEDIA_ATTACHED, () => void hls.loadSource(src));
           hls.attachMedia(video2);
         }
       }
@@ -6713,9 +6760,125 @@ function Fbx({
   return /* @__PURE__ */ React.createElement(Clone, { ...props, object });
 }
 
+const SERVICE_KEY = "__drei_ktx2_service__";
+const DEFAULT_TRANSCODER_PATH = "https://cdn.jsdelivr.net/gh/pmndrs/drei-assets@master/basis/";
+class KTX2LoaderServiceImpl {
+  loader = null;
+  renderer = null;
+  _isReady = false;
+  transcoderPath = DEFAULT_TRANSCODER_PATH;
+  pendingCallbacks = [];
+  /**
+   * Get or create the singleton KTX2Loader instance.
+   * The loader is created lazily on first access.
+   */
+  getLoader() {
+    if (!this.loader) {
+      this.loader = new KTX2Loader();
+      this.loader.setTranscoderPath(this.transcoderPath);
+    }
+    return this.loader;
+  }
+  /**
+   * Register a renderer and call detectSupport.
+   * Should be called from within React context (useLayoutEffect).
+   * Flushes any queued callbacks.
+   */
+  registerRenderer(renderer) {
+    if (this._isReady && this.renderer === renderer) {
+      return;
+    }
+    this.renderer = renderer;
+    const loader = this.getLoader();
+    loader.detectSupport(renderer);
+    this._isReady = true;
+    this.flushPendingCallbacks();
+  }
+  /**
+   * Check if the service is ready (has renderer registered).
+   */
+  isReady() {
+    return this._isReady;
+  }
+  /**
+   * Get the registered renderer, if any.
+   */
+  getRenderer() {
+    return this.renderer;
+  }
+  /**
+   * Register a callback to run when renderer becomes available.
+   * If renderer is already available, runs immediately.
+   */
+  onReady(callback) {
+    if (this._isReady) {
+      callback();
+    } else {
+      this.pendingCallbacks.push(callback);
+    }
+  }
+  /**
+   * Process all pending callbacks.
+   */
+  flushPendingCallbacks() {
+    const callbacks = this.pendingCallbacks;
+    this.pendingCallbacks = [];
+    for (const callback of callbacks) {
+      try {
+        callback();
+      } catch (error) {
+        console.error("KTX2LoaderService: Error in pending callback:", error);
+      }
+    }
+  }
+  /**
+   * Set the transcoder path for basis/ktx2 decoding.
+   */
+  setTranscoderPath(path) {
+    this.transcoderPath = path;
+    if (this.loader) {
+      this.loader.setTranscoderPath(path);
+    }
+  }
+  /**
+   * Get the current transcoder path.
+   */
+  getTranscoderPath() {
+    return this.transcoderPath;
+  }
+  /**
+   * Dispose of the loader and reset state.
+   * Useful for testing or cleanup.
+   */
+  dispose() {
+    if (this.loader) {
+      this.loader.dispose();
+    }
+    const path = this.transcoderPath;
+    this.loader = null;
+    this.renderer = null;
+    this._isReady = false;
+    this.transcoderPath = path;
+    this.pendingCallbacks = [];
+  }
+}
+const KTX2LoaderService = globalThis[SERVICE_KEY] || (globalThis[SERVICE_KEY] = new KTX2LoaderServiceImpl());
+
 let dracoLoader = null;
 let decoderPath = "https://www.gstatic.com/draco/versioned/decoders/1.5.5/";
-function extensions(useDraco = true, useMeshopt = true, extendLoader) {
+let legacyApiWarned = false;
+function isOptionsObject(arg) {
+  return typeof arg === "object" && arg !== null && !Array.isArray(arg);
+}
+function warnLegacyApi() {
+  if (!legacyApiWarned) {
+    legacyApiWarned = true;
+    console.warn(
+      "useGLTF: Boolean arguments are deprecated. Use options object instead:\n  useGLTF(path, { draco: true, meshopt: true, ktx2: true })"
+    );
+  }
+}
+function extensions(useDraco = true, useMeshopt = true, useKTX2 = false, extendLoader, renderer) {
   return (loader) => {
     if (extendLoader) {
       extendLoader(loader);
@@ -6731,36 +6894,110 @@ function extensions(useDraco = true, useMeshopt = true, extendLoader) {
       const decoder = typeof MeshoptDecoder === "function" ? MeshoptDecoder() : MeshoptDecoder;
       loader.setMeshoptDecoder(decoder);
     }
+    if (useKTX2) {
+      const ktx2Loader = KTX2LoaderService.getLoader();
+      if (typeof useKTX2 === "string") {
+        ktx2Loader.setTranscoderPath(useKTX2);
+      }
+      if (renderer) {
+        ktx2Loader.detectSupport(renderer);
+      }
+      loader.setKTX2Loader(ktx2Loader);
+    }
   };
 }
-const useGLTF = (path, useDraco, useMeshopt, extendLoader) => useLoader(GLTFLoader, path, extensions(useDraco, useMeshopt, extendLoader));
-useGLTF.preload = (path, useDraco, useMeshopt, extendLoader) => useLoader.preload(GLTFLoader, path, extensions(useDraco, useMeshopt, extendLoader));
+function useGLTF(path, optionsOrDraco, useMeshoptArg, useKTX2Arg, extendLoaderArg) {
+  let draco = true;
+  let meshopt = true;
+  let ktx2 = false;
+  let extendLoader;
+  if (isOptionsObject(optionsOrDraco)) {
+    draco = optionsOrDraco.draco ?? true;
+    meshopt = optionsOrDraco.meshopt ?? true;
+    ktx2 = optionsOrDraco.ktx2 ?? false;
+    extendLoader = optionsOrDraco.extendLoader;
+  } else if (optionsOrDraco !== void 0) {
+    warnLegacyApi();
+    draco = optionsOrDraco;
+    meshopt = useMeshoptArg ?? true;
+    ktx2 = useKTX2Arg ?? false;
+    extendLoader = extendLoaderArg;
+  }
+  const renderer = useThree((state) => state.renderer);
+  useLayoutEffect(() => {
+    if (ktx2) {
+      KTX2LoaderService.registerRenderer(renderer);
+    }
+  }, [ktx2, renderer]);
+  return useLoader(GLTFLoader, path, extensions(draco, meshopt, ktx2, extendLoader, ktx2 ? renderer : void 0));
+}
+useGLTF.preload = (path, optionsOrDraco, useMeshoptArg, useKTX2Arg, extendLoaderArg) => {
+  let draco = true;
+  let meshopt = true;
+  let ktx2 = false;
+  let extendLoader;
+  if (isOptionsObject(optionsOrDraco)) {
+    draco = optionsOrDraco.draco ?? true;
+    meshopt = optionsOrDraco.meshopt ?? true;
+    ktx2 = optionsOrDraco.ktx2 ?? false;
+    extendLoader = optionsOrDraco.extendLoader;
+  } else if (optionsOrDraco !== void 0) {
+    warnLegacyApi();
+    draco = optionsOrDraco;
+    meshopt = useMeshoptArg ?? true;
+    ktx2 = useKTX2Arg ?? false;
+    extendLoader = extendLoaderArg;
+  }
+  if (ktx2) {
+    KTX2LoaderService.onReady(() => {
+      const renderer = KTX2LoaderService.getRenderer();
+      useLoader.preload(GLTFLoader, path, extensions(draco, meshopt, ktx2, extendLoader, renderer));
+    });
+  } else {
+    useLoader.preload(GLTFLoader, path, extensions(draco, meshopt, false, extendLoader));
+  }
+};
 useGLTF.clear = (path) => useLoader.clear(GLTFLoader, path);
 useGLTF.setDecoderPath = (path) => {
   decoderPath = path;
 };
+useGLTF.setKTX2TranscoderPath = (path) => {
+  KTX2LoaderService.setTranscoderPath(path);
+};
 const Gltf = /* @__PURE__ */ React.forwardRef(
-  ({ src, useDraco, useMeshOpt, extendLoader, ...props }, ref) => {
-    const { scene } = useGLTF(src, useDraco, useMeshOpt, extendLoader);
+  ({ src, useDraco, useMeshOpt, extendLoader, options, ...props }, ref) => {
+    const opts = options ?? {
+      draco: useDraco,
+      meshopt: useMeshOpt,
+      extendLoader
+    };
+    const { scene } = useGLTF(src, opts);
     return /* @__PURE__ */ React.createElement(Clone, { ref, ...props, object: scene });
   }
 );
 
-let transcoderPath = "https://cdn.jsdelivr.net/gh/pmndrs/drei-assets@master/basis/";
 function useKTX2(input, basisPath = true, extendLoader) {
   const renderer = useThree((state) => state.renderer);
+  useLayoutEffect(() => {
+    KTX2LoaderService.registerRenderer(renderer);
+  }, [renderer]);
   const textures = useLoader(KTX2Loader, IsObject(input) ? Object.values(input) : input, (loader) => {
     if (extendLoader) {
       extendLoader(loader);
     }
     if (basisPath) {
-      loader.setTranscoderPath(typeof basisPath === "string" ? basisPath : transcoderPath);
+      const path = typeof basisPath === "string" ? basisPath : KTX2LoaderService.getTranscoderPath();
+      loader.setTranscoderPath(path);
     }
     loader.detectSupport(renderer);
   });
   useEffect(() => {
     const array = Array.isArray(textures) ? textures : [textures];
-    array.forEach((texture) => renderer.initTexture(texture));
+    array.forEach((texture) => {
+      if ("initTexture" in renderer) {
+        renderer.initTexture(texture);
+      }
+    });
   }, [renderer, textures]);
   if (IsObject(input)) {
     const keys = Object.keys(input);
@@ -6771,23 +7008,81 @@ function useKTX2(input, basisPath = true, extendLoader) {
     return textures;
   }
 }
-useKTX2.preload = (url, basisPath = true, extendLoader) => useLoader.preload(KTX2Loader, url, (loader) => {
-  if (extendLoader) {
-    extendLoader(loader);
-  }
-  if (basisPath) {
-    loader.setTranscoderPath(typeof basisPath === "string" ? basisPath : transcoderPath);
-  }
-});
+useKTX2.preload = (url, basisPath = true, extendLoader) => {
+  KTX2LoaderService.onReady(() => {
+    const renderer = KTX2LoaderService.getRenderer();
+    useLoader.preload(KTX2Loader, url, (loader) => {
+      if (extendLoader) {
+        extendLoader(loader);
+      }
+      if (basisPath) {
+        const path = typeof basisPath === "string" ? basisPath : KTX2LoaderService.getTranscoderPath();
+        loader.setTranscoderPath(path);
+      }
+      if (renderer) {
+        loader.detectSupport(renderer);
+      }
+    });
+  });
+};
 useKTX2.clear = (input) => useLoader.clear(KTX2Loader, input);
 useKTX2.setTranscoderPath = (path) => {
-  transcoderPath = path;
+  KTX2LoaderService.setTranscoderPath(path);
 };
 const Ktx2 = ({ children, input, basisPath, extendLoader }) => {
   const texture = useKTX2(input, basisPath, extendLoader);
   return /* @__PURE__ */ React.createElement(React.Fragment, null, children?.(texture));
 };
 
+const useVariants = (model, inVariant) => {
+  const [activeVariant, setActiveVariant] = useState(null);
+  const [materials, setMaterials] = useState([]);
+  useEffect(() => {
+    model.parser.getDependencies("material").then((materials2) => {
+      setMaterials(materials2);
+    });
+  }, [model]);
+  const variants = useMemo(() => {
+    return model.userData.gltfExtensions?.KHR_materials_variants?.variants;
+  }, [model]);
+  const applyVariant = useCallback(
+    (variantIndex) => {
+      model.scene.traverse(async (object) => {
+        if (!("isMesh" in object) || !object.userData.gltfExtensions) return;
+        const meshObject = object;
+        const meshVariantDef = meshObject.userData.gltfExtensions.KHR_materials_variants;
+        if (!meshVariantDef) return;
+        if (!meshObject.userData.originalMaterial) meshObject.userData.originalMaterial = meshObject.material;
+        const mapping = meshVariantDef.mappings.find((mapping2) => mapping2.variants.includes(variantIndex));
+        if (mapping) {
+          meshObject.material = await model.parser.getDependency("material", mapping.material);
+          model.parser.assignFinalMaterial(meshObject);
+        } else meshObject.material = meshObject.userData.originalMaterial;
+        if (Array.isArray(meshObject.material)) for (const mat of meshObject.material) mat.needsUpdate = true;
+        else meshObject.material.needsUpdate = true;
+      });
+    },
+    [model]
+  );
+  const setVariant = useCallback(
+    (variantName) => {
+      if (!variants) return;
+      const newVariant = variantName && variants.some((v) => v.name === variantName) ? variantName : null;
+      setActiveVariant(newVariant);
+    },
+    [variants]
+  );
+  useEffect(() => {
+    if (!variants) return;
+    const variantIndex = variants.findIndex((v) => v.name === activeVariant);
+    applyVariant(variantIndex > -1 ? variantIndex : 0);
+  }, [variants, activeVariant, applyVariant]);
+  useEffect(() => {
+    setVariant(inVariant ?? null);
+  }, [inVariant, setVariant]);
+  return { variants, activeVariant, setVariant, materials };
+};
+
 const WebcamVideoTexture = /* @__PURE__ */ forwardRef(
   ({
     constraints = {
@@ -6975,6 +7270,7 @@ function useEffectfulState(fn, deps = [], cb) {
 }
 
 function Stats({ showPanel = 0, className, parent }) {
+  React.useEffect(() => void console.warn("drei: <Stats /> is deprecated, use <StatsGl /> instead."), []);
   const stats = useEffectfulState(() => new StatsImpl(), []);
   React.useEffect(() => {
     if (stats) {
@@ -7003,6 +7299,7 @@ const StatsGl = /* @__PURE__ */ React.forwardRef(
       const stats2 = new Stats$1({
         ...props
       });
+      stats2.init(renderer);
       return stats2;
     }, [renderer]);
     React.useImperativeHandle(fref, () => stats.domElement, [stats]);
@@ -7020,7 +7317,7 @@ const StatsGl = /* @__PURE__ */ React.forwardRef(
         return () => {
           if (classNames.length) stats.domElement.classList.remove(...classNames);
           node?.removeChild(stats.domElement);
-          stats.end();
+          stats.dispose();
         };
       }
     }, [parent, stats, className, id, clearStatsGlStyle]);
@@ -7028,7 +7325,7 @@ const StatsGl = /* @__PURE__ */ React.forwardRef(
       () => {
         stats.begin();
       },
-      { before: "render" }
+      { before: "update" }
     );
     useFrame(
       () => {
@@ -7078,11 +7375,11 @@ const RenderCubeTexture = /* @__PURE__ */ React.forwardRef(
         depthBuffer,
         generateMipmaps
       };
-      const fboA2 = new THREE.WebGLCubeRenderTarget(fboSize, settings);
+      const fboA2 = new WebGLCubeRenderTarget(fboSize, settings);
       fboA2.texture.isRenderTargetTexture = !flip;
       fboA2.texture.flipY = true;
       fboA2.texture.type = THREE.HalfFloatType;
-      const fboB2 = new THREE.WebGLCubeRenderTarget(fboSize, settings);
+      const fboB2 = new WebGLCubeRenderTarget(fboSize, settings);
       fboB2.texture.isRenderTargetTexture = !flip;
       fboB2.texture.flipY = true;
       fboB2.texture.type = THREE.HalfFloatType;
@@ -7411,8 +7708,9 @@ const TUNNEL_KEY = "__drei_view_tunnel__";
 const tracked = globalThis[TUNNEL_KEY] || (globalThis[TUNNEL_KEY] = tunnel());
 function computeContainerPosition(canvasSize, trackRect, forceEven) {
   const { right, top: trackTop, left: trackLeft, bottom: trackBottom, width, height } = trackRect;
-  const isOffscreen = trackRect.bottom < 0 || trackTop > canvasSize.height || right < 0 || trackRect.left > canvasSize.width;
   const canvasBottom = canvasSize.top + canvasSize.height;
+  const canvasRight = canvasSize.left + canvasSize.width;
+  const isOffscreen = trackBottom < canvasSize.top || trackTop > canvasBottom || right < canvasSize.left || trackLeft > canvasRight;
   const rawBottom = canvasBottom - trackBottom;
   const rawLeft = trackLeft - canvasSize.left;
   const rawTop = trackTop - canvasSize.top;
@@ -7972,12 +8270,12 @@ useEnvironment.preload = (preloadOptions) => {
     if (extensions) extensions(loader2);
   });
 };
-const clearDefaultOptins = {
+const clearDefaultOptions = {
   files: defaultFiles,
   preset: void 0
 };
 useEnvironment.clear = (clearOptions) => {
-  const options = { ...clearDefaultOptins, ...clearOptions };
+  const options = { ...clearDefaultOptions, ...clearOptions };
   let { files } = options;
   const { preset } = options;
   if (preset) {
@@ -8671,9 +8969,14 @@ function Select({
     const oldControlsEnabled = controls?.enabled;
     let isDown = false;
     function prepareRay(event, vec) {
-      const { offsetX, offsetY } = event;
+      const canvas = gl.domElement;
+      const rect = canvas.getBoundingClientRect();
+      const x = event.clientX - rect.left;
+      const y = event.clientY - rect.top;
       const { width, height } = size;
-      vec.set(offsetX / width * 2 - 1, -(offsetY / height) * 2 + 1);
+      const normalizedX = x / width * 2 - 1;
+      const normalizedY = -(y / height) * 2 + 1;
+      vec.set(normalizedX, normalizedY, -1);
     }
     function onSelectStart(event) {
       if (controls) controls.enabled = false;
@@ -12918,7 +13221,7 @@ const FacemeshDatas = {
 
 const FaceLandmarkerContext = /* @__PURE__ */ createContext({});
 const FaceLandmarkerDefaults = {
-  basePath: "https://cdn.jsdelivr.net/npm/@mediapipe/tasks-vision@0.10.17/wasm",
+  basePath: `https://cdn.jsdelivr.net/npm/@mediapipe/tasks-vision@${"0.10.17"}/wasm`,
   options: {
     baseOptions: {
       modelAssetPath: "https://storage.googleapis.com/mediapipe-models/face_landmarker/face_landmarker/float16/1/face_landmarker.task",
@@ -13666,4 +13969,4 @@ const MarchingPlane = /* @__PURE__ */ React.forwardRef(
   }
 );
 
-export { AdaptiveDpr, AdaptiveEvents, ArcballControls, BBAnchor, Backdrop, Billboard, Bounds, Box, Bvh, CameraControls, CameraShake, Capsule, CatmullRomLine, Center, Circle, Clone, Cloud, CloudInstance, Clouds, ComputedAttribute, Cone, CubeCamera, CubeTexture, CubicBezierLine, CurveModifier, CycleRaycast, Cylinder, Decal, Detailed, DetectGPU, DeviceOrientationControls, Dodecahedron, DragControls, Edges, Environment, EnvironmentCube, EnvironmentMap, EnvironmentPortal, Example, Extrude, FaceControls, FaceLandmarker, FaceLandmarkerDefaults, Facemesh, FacemeshDatas, FacemeshEye, FacemeshEyeDefaults, Fbo, Fbx, FirstPersonControls, Fisheye, Float, FlyControls, GizmoHelper, GizmoViewcube, GizmoViewport, Gltf, Helper, Html, Hud, Icosahedron, Instance, InstancedAttribute, Instances, IsObject, KeyboardControls, Ktx2, Lathe, Lightformer, Loader, MapControls, MarchingCube, MarchingCubes, MarchingPlane, Mask, MatcapTexture, Merged, MotionPathControls, NormalTexture, Octahedron, OrbitControls, OrthographicCamera, Outlines, PerformanceMonitor, PerspectiveCamera, PivotControls, Plane, Point, PointMaterial, PointMaterialImpl, PointerLockControls, Points, PointsBuffer, Polyhedron, PositionMesh, PositionPoint, PositionalAudio, Preload, PresentationControls, Progress, QuadraticBezierLine, RenderCubeTexture, RenderTexture, Resize, Ring, RoundedBox, RoundedBoxGeometry, Sampler, ScreenQuad, ScreenSizer, ScreenSpace, ScreenVideoTexture, Scroll, ScrollControls, Select, Shadow, Shape, Sky, Sphere, Splat, SpriteAnimator, Stage, Stats, StatsGl, Svg, Tetrahedron, Text3D, Texture, Torus, TorusKnot, TrackballControls, Trail, TrailTexture, TransformControls, Tube, VideoTexture, View, WebcamVideoTexture, calcPosFromAngles, checkIfFrameIsEmpty, createInstances, getFirstFrame, meshBounds, presetsObj, useAnimations, useAspect, useBVH, useBounds, useContextBridge, useCubeCamera, useCubeTexture, useCursor, useCustomRaycast, useDepthBuffer, useDetectGPU, useEnvironment, useFBO, useFBX, useFaceControls, useFaceLandmarker, useFont, useGLTF, useGizmoContext, useHelper, useIntersect, useKTX2, useKeyboardControls, useMask, useMatcapTexture, useMotion, useNormalTexture, usePerformanceMonitor, useProgress, useScroll, useSelect, useSpriteAnimator, useSpriteLoader, useSurfaceSampler, useTexture, useTrail, useTrailTexture, useVideoTexture };
+export { AdaptiveDpr, AdaptiveEvents, ArcballControls, BBAnchor, Backdrop, Billboard, Bounds, Box, Bvh, CameraControls, CameraShake, Capsule, CatmullRomLine, Center, Circle, Clone, Cloud, CloudInstance, Clouds, ComputedAttribute, Cone, CubeCamera, CubeTexture, CubicBezierLine, CurveModifier, CycleRaycast, Cylinder, Decal, Detailed, DetectGPU, DeviceOrientationControls, Dodecahedron, DragControls, Edges, Environment, EnvironmentCube, EnvironmentMap, EnvironmentPortal, Example, Extrude, FaceControls, FaceLandmarker, FaceLandmarkerDefaults, Facemesh, FacemeshDatas, FacemeshEye, FacemeshEyeDefaults, Fbo, Fbx, FirstPersonControls, Fisheye, Float, FlyControls, GizmoHelper, GizmoViewcube, GizmoViewport, Gltf, Helper, Html, Hud, Icosahedron, Instance, InstancedAttribute, Instances, IsObject, KeyboardControls, Ktx2, Lathe, Lightformer, Loader, MapControls, MarchingCube, MarchingCubes, MarchingPlane, Mask, MatcapTexture, Merged, MotionPathControls, NormalTexture, Octahedron, OrbitControls, OrthographicCamera, Outlines, PerformanceMonitor, PerspectiveCamera, PivotControls, Plane, Point, PointMaterial, PointMaterialImpl, PointerLockControls, Points, PointsBuffer, Polyhedron, PositionMesh, PositionPoint, PositionalAudio, Preload, PresentationControls, Progress, QuadraticBezierLine, RenderCubeTexture, RenderTexture, Resize, Ring, RoundedBox, RoundedBoxGeometry, Sampler, ScreenQuad, ScreenSizer, ScreenSpace, ScreenVideoTexture, Scroll, ScrollControls, Select, Shadow, Shape, Sky, Sphere, Splat, SpriteAnimator, Stage, Stats, StatsGl, Svg, Tetrahedron, Text3D, Texture, Torus, TorusKnot, TrackballControls, Trail, TrailTexture, TransformControls, Tube, VideoTexture, View, WebcamVideoTexture, calcPosFromAngles, checkIfFrameIsEmpty, createInstances, getFirstFrame, meshBounds, presetsObj, useAnimations, useAspect, useBVH, useBounds, useContextBridge, useCubeCamera, useCubeTexture, useCursor, useCustomRaycast, useDepthBuffer, useDetectGPU, useEnvironment, useFBO, useFBX, useFaceControls, useFaceLandmarker, useFont, useGLTF, useGizmoContext, useHelper, useIntersect, useKTX2, useKeyboardControls, useMask, useMatcapTexture, useMotion, useNormalTexture, usePerformanceMonitor, useProgress, useScroll, useSelect, useSpriteAnimator, useSpriteLoader, useSurfaceSampler, useTexture, useTrail, useTrailTexture, useVariants, useVideoTexture };