@react-three/fiber 10.0.0-alpha.1 → 10.0.0-canary.1b98c17

package/dist/legacy.mjs

@@ -1,10 +1,16 @@
 import * as three from 'three';
-import { WebGLRenderTarget, Frustum, Matrix4, Group, BoxGeometry, MeshBasicNodeMaterial, Mesh, Node, NodeUpdateType, Layers, RGBAFormat, UnsignedByteType, Vector3, Vector2, TextureLoader, Texture as Texture$1, SRGBColorSpace, Raycaster, OrthographicCamera, PerspectiveCamera, Scene, PCFSoftShadowMap, VSMShadowMap, PCFShadowMap, BasicShadowMap, ColorManagement, LinearSRGBColorSpace, NoToneMapping, ACESFilmicToneMapping, WebGLRenderer } from 'three';
-import { jsx, Fragment } from 'react/jsx-runtime';
+import { WebGLRenderTarget, CubeReflectionMapping, EquirectangularReflectionMapping, CubeTextureLoader, Scene, WebGLCubeRenderTarget, HalfFloatType, Color, Frustum, Matrix4, Group, BoxGeometry, MeshBasicNodeMaterial, Mesh, Node, NodeUpdateType, Layers, SRGBColorSpace, RGBAFormat, UnsignedByteType, Vector3, Vector2, TextureLoader, Texture as Texture$1, Raycaster, OrthographicCamera, PerspectiveCamera, PCFShadowMap, VSMShadowMap, BasicShadowMap, ACESFilmicToneMapping, WebGLRenderer } from 'three';
+import { jsx, Fragment, jsxs } from 'react/jsx-runtime';
 import * as React from 'react';
-import React__default, { useMemo, useLayoutEffect, useEffect, useContext, useRef, useImperativeHandle, useCallback, useState } from 'react';
+import React__default, { useLayoutEffect, useRef, useMemo, useEffect, useContext, useImperativeHandle, useCallback, useState } from 'react';
 import useMeasure from 'react-use-measure';
 import { useFiber, useContextBridge, traverseFiber, FiberProvider } from 'its-fine';
+import { useThree as useThree$1, useLoader as useLoader$1, useFrame as useFrame$1, createPortal as createPortal$1, applyProps as applyProps$1, extend as extend$1 } from '@react-three/fiber';
+import { GroundedSkybox } from 'three/examples/jsm/objects/GroundedSkybox.js';
+import { HDRLoader } from 'three/examples/jsm/loaders/HDRLoader.js';
+import { EXRLoader } from 'three/examples/jsm/loaders/EXRLoader.js';
+import { UltraHDRLoader } from 'three/examples/jsm/loaders/UltraHDRLoader.js';
+import { GainMapLoader } from '@monogrid/gainmap-js';
 import Tb, { unstable_scheduleCallback, unstable_IdlePriority } from 'scheduler';
 import { createWithEqualityFn } from 'zustand/traditional';
 import { suspend, preload, clear } from 'suspend-react';
@@ -45,6 +51,389 @@ const THREE = /*#__PURE__*/_mergeNamespaces({
   WebGPURenderer: WebGPURenderer
 }, [three]);
 
+const primaryRegistry = /* @__PURE__ */ new Map();
+const pendingSubscribers = /* @__PURE__ */ new Map();
+function registerPrimary(id, renderer, store) {
+  if (primaryRegistry.has(id)) {
+    console.warn(`Canvas with id="${id}" already registered. Overwriting.`);
+  }
+  const entry = { renderer, store };
+  primaryRegistry.set(id, entry);
+  const subscribers = pendingSubscribers.get(id);
+  if (subscribers) {
+    subscribers.forEach((callback) => callback(entry));
+    pendingSubscribers.delete(id);
+  }
+  return () => {
+    const currentEntry = primaryRegistry.get(id);
+    if (currentEntry?.renderer === renderer) {
+      primaryRegistry.delete(id);
+    }
+  };
+}
+function getPrimary(id) {
+  return primaryRegistry.get(id);
+}
+function waitForPrimary(id, timeout = 5e3) {
+  const existing = primaryRegistry.get(id);
+  if (existing) {
+    return Promise.resolve(existing);
+  }
+  return new Promise((resolve, reject) => {
+    const timeoutId = setTimeout(() => {
+      const subscribers = pendingSubscribers.get(id);
+      if (subscribers) {
+        const index = subscribers.indexOf(callback);
+        if (index !== -1) subscribers.splice(index, 1);
+        if (subscribers.length === 0) pendingSubscribers.delete(id);
+      }
+      reject(new Error(`Timeout waiting for canvas with id="${id}". Make sure a <Canvas id="${id}"> is mounted.`));
+    }, timeout);
+    const callback = (entry) => {
+      clearTimeout(timeoutId);
+      resolve(entry);
+    };
+    if (!pendingSubscribers.has(id)) {
+      pendingSubscribers.set(id, []);
+    }
+    pendingSubscribers.get(id).push(callback);
+  });
+}
+function hasPrimary(id) {
+  return primaryRegistry.has(id);
+}
+function unregisterPrimary(id) {
+  primaryRegistry.delete(id);
+}
+function getPrimaryIds() {
+  return Array.from(primaryRegistry.keys());
+}
+
+const presetsObj = {
+  apartment: "lebombo_1k.hdr",
+  city: "potsdamer_platz_1k.hdr",
+  dawn: "kiara_1_dawn_1k.hdr",
+  forest: "forest_slope_1k.hdr",
+  lobby: "st_fagans_interior_1k.hdr",
+  night: "dikhololo_night_1k.hdr",
+  park: "rooitou_park_1k.hdr",
+  studio: "studio_small_03_1k.hdr",
+  sunset: "venice_sunset_1k.hdr",
+  warehouse: "empty_warehouse_01_1k.hdr"
+};
+
+const CUBEMAP_ROOT = "https://raw.githack.com/pmndrs/drei-assets/456060a26bbeb8fdf79326f224b6d99b8bcce736/hdri/";
+const isArray = (arr) => Array.isArray(arr);
+const defaultFiles = ["/px.png", "/nx.png", "/py.png", "/ny.png", "/pz.png", "/nz.png"];
+function useEnvironment({
+  files = defaultFiles,
+  path = "",
+  preset = void 0,
+  colorSpace = void 0,
+  extensions
+} = {}) {
+  if (preset) {
+    validatePreset(preset);
+    files = presetsObj[preset];
+    path = CUBEMAP_ROOT;
+  }
+  const multiFile = isArray(files);
+  const { extension, isCubemap } = getExtension(files);
+  const loader = getLoader$1(extension);
+  if (!loader) throw new Error("useEnvironment: Unrecognized file extension: " + files);
+  const renderer = useThree$1((state) => state.renderer);
+  useLayoutEffect(() => {
+    if (extension !== "webp" && extension !== "jpg" && extension !== "jpeg") return;
+    function clearGainmapTexture() {
+      useLoader$1.clear(loader, multiFile ? [files] : files);
+    }
+    renderer.domElement.addEventListener("webglcontextlost", clearGainmapTexture, { once: true });
+  }, [extension, files, loader, multiFile, renderer.domElement]);
+  const loaderResult = useLoader$1(
+    loader,
+    multiFile ? [files] : files,
+    (loader2) => {
+      if (extension === "webp" || extension === "jpg" || extension === "jpeg") {
+        loader2.setRenderer?.(renderer);
+      }
+      loader2.setPath?.(path);
+      if (extensions) extensions(loader2);
+    }
+  );
+  let texture = multiFile ? (
+    // @ts-ignore
+    loaderResult[0]
+  ) : loaderResult;
+  if (extension === "jpg" || extension === "jpeg" || extension === "webp") {
+    texture = texture.renderTarget?.texture;
+  }
+  texture.mapping = isCubemap ? CubeReflectionMapping : EquirectangularReflectionMapping;
+  texture.colorSpace = colorSpace ?? (isCubemap ? "srgb" : "srgb-linear");
+  return texture;
+}
+const preloadDefaultOptions = {
+  files: defaultFiles,
+  path: "",
+  preset: void 0,
+  extensions: void 0
+};
+useEnvironment.preload = (preloadOptions) => {
+  const options = { ...preloadDefaultOptions, ...preloadOptions };
+  let { files, path = "" } = options;
+  const { preset, extensions } = options;
+  if (preset) {
+    validatePreset(preset);
+    files = presetsObj[preset];
+    path = CUBEMAP_ROOT;
+  }
+  const { extension } = getExtension(files);
+  if (extension === "webp" || extension === "jpg" || extension === "jpeg") {
+    throw new Error("useEnvironment: Preloading gainmaps is not supported");
+  }
+  const loader = getLoader$1(extension);
+  if (!loader) throw new Error("useEnvironment: Unrecognized file extension: " + files);
+  useLoader$1.preload(loader, isArray(files) ? [files] : files, (loader2) => {
+    loader2.setPath?.(path);
+    if (extensions) extensions(loader2);
+  });
+};
+const clearDefaultOptins = {
+  files: defaultFiles,
+  preset: void 0
+};
+useEnvironment.clear = (clearOptions) => {
+  const options = { ...clearDefaultOptins, ...clearOptions };
+  let { files } = options;
+  const { preset } = options;
+  if (preset) {
+    validatePreset(preset);
+    files = presetsObj[preset];
+  }
+  const { extension } = getExtension(files);
+  const loader = getLoader$1(extension);
+  if (!loader) throw new Error("useEnvironment: Unrecognized file extension: " + files);
+  useLoader$1.clear(loader, isArray(files) ? [files] : files);
+};
+function validatePreset(preset) {
+  if (!(preset in presetsObj)) throw new Error("Preset must be one of: " + Object.keys(presetsObj).join(", "));
+}
+function getExtension(files) {
+  const isCubemap = isArray(files) && files.length === 6;
+  const isGainmap = isArray(files) && files.length === 3 && files.some((file) => file.endsWith("json"));
+  const firstEntry = isArray(files) ? files[0] : files;
+  const extension = isCubemap ? "cube" : isGainmap ? "webp" : firstEntry.startsWith("data:application/exr") ? "exr" : firstEntry.startsWith("data:application/hdr") ? "hdr" : firstEntry.startsWith("data:image/jpeg") ? "jpg" : firstEntry.split(".").pop()?.split("?")?.shift()?.toLowerCase();
+  return { extension, isCubemap, isGainmap };
+}
+function getLoader$1(extension) {
+  const loader = extension === "cube" ? CubeTextureLoader : extension === "hdr" ? HDRLoader : extension === "exr" ? EXRLoader : extension === "jpg" || extension === "jpeg" ? UltraHDRLoader : extension === "webp" ? GainMapLoader : null;
+  return loader;
+}
+
+const isRef$1 = (obj) => obj.current && obj.current.isScene;
+const resolveScene = (scene) => isRef$1(scene) ? scene.current : scene;
+function setEnvProps(background, scene, defaultScene, texture, sceneProps = {}) {
+  sceneProps = {
+    backgroundBlurriness: 0,
+    backgroundIntensity: 1,
+    backgroundRotation: [0, 0, 0],
+    environmentIntensity: 1,
+    environmentRotation: [0, 0, 0],
+    ...sceneProps
+  };
+  const target = resolveScene(scene || defaultScene);
+  const oldbg = target.background;
+  const oldenv = target.environment;
+  const oldSceneProps = {
+    // @ts-ignore
+    backgroundBlurriness: target.backgroundBlurriness,
+    // @ts-ignore
+    backgroundIntensity: target.backgroundIntensity,
+    // @ts-ignore
+    backgroundRotation: target.backgroundRotation?.clone?.() ?? [0, 0, 0],
+    // @ts-ignore
+    environmentIntensity: target.environmentIntensity,
+    // @ts-ignore
+    environmentRotation: target.environmentRotation?.clone?.() ?? [0, 0, 0]
+  };
+  if (background !== "only") target.environment = texture;
+  if (background) target.background = texture;
+  applyProps$1(target, sceneProps);
+  return () => {
+    if (background !== "only") target.environment = oldenv;
+    if (background) target.background = oldbg;
+    applyProps$1(target, oldSceneProps);
+  };
+}
+function EnvironmentMap({ scene, background = false, map, ...config }) {
+  const defaultScene = useThree$1((state) => state.scene);
+  React.useLayoutEffect(() => {
+    if (map) return setEnvProps(background, scene, defaultScene, map, config);
+  });
+  return null;
+}
+function EnvironmentCube({
+  background = false,
+  scene,
+  blur,
+  backgroundBlurriness,
+  backgroundIntensity,
+  backgroundRotation,
+  environmentIntensity,
+  environmentRotation,
+  ...rest
+}) {
+  const texture = useEnvironment(rest);
+  const defaultScene = useThree$1((state) => state.scene);
+  React.useLayoutEffect(() => {
+    return setEnvProps(background, scene, defaultScene, texture, {
+      backgroundBlurriness: blur ?? backgroundBlurriness,
+      backgroundIntensity,
+      backgroundRotation,
+      environmentIntensity,
+      environmentRotation
+    });
+  });
+  React.useEffect(() => {
+    return () => {
+      texture.dispose();
+    };
+  }, [texture]);
+  return null;
+}
+function EnvironmentPortal({
+  children,
+  near = 0.1,
+  far = 1e3,
+  resolution = 256,
+  frames = 1,
+  map,
+  background = false,
+  blur,
+  backgroundBlurriness,
+  backgroundIntensity,
+  backgroundRotation,
+  environmentIntensity,
+  environmentRotation,
+  scene,
+  files,
+  path,
+  preset = void 0,
+  extensions
+}) {
+  const gl = useThree$1((state) => state.gl);
+  const defaultScene = useThree$1((state) => state.scene);
+  const camera = React.useRef(null);
+  const [virtualScene] = React.useState(() => new Scene());
+  const fbo = React.useMemo(() => {
+    const fbo2 = new WebGLCubeRenderTarget(resolution);
+    fbo2.texture.type = HalfFloatType;
+    return fbo2;
+  }, [resolution]);
+  React.useEffect(() => {
+    return () => {
+      fbo.dispose();
+    };
+  }, [fbo]);
+  React.useLayoutEffect(() => {
+    if (frames === 1) {
+      const autoClear = gl.autoClear;
+      gl.autoClear = true;
+      camera.current.update(gl, virtualScene);
+      gl.autoClear = autoClear;
+    }
+    return setEnvProps(background, scene, defaultScene, fbo.texture, {
+      backgroundBlurriness: blur ?? backgroundBlurriness,
+      backgroundIntensity,
+      backgroundRotation,
+      environmentIntensity,
+      environmentRotation
+    });
+  }, [
+    children,
+    virtualScene,
+    fbo.texture,
+    scene,
+    defaultScene,
+    background,
+    frames,
+    gl,
+    blur,
+    backgroundBlurriness,
+    backgroundIntensity,
+    backgroundRotation,
+    environmentIntensity,
+    environmentRotation
+  ]);
+  let count = 1;
+  useFrame$1(() => {
+    if (frames === Infinity || count < frames) {
+      const autoClear = gl.autoClear;
+      gl.autoClear = true;
+      camera.current.update(gl, virtualScene);
+      gl.autoClear = autoClear;
+      count++;
+    }
+  });
+  return /* @__PURE__ */ jsx(Fragment, { children: createPortal$1(
+    /* @__PURE__ */ jsxs(Fragment, { children: [
+      children,
+      /* @__PURE__ */ jsx("cubeCamera", { ref: camera, args: [near, far, fbo] }),
+      files || preset ? /* @__PURE__ */ jsx(EnvironmentCube, { background: true, files, preset, path, extensions }) : map ? /* @__PURE__ */ jsx(EnvironmentMap, { background: true, map, extensions }) : null
+    ] }),
+    virtualScene
+  ) });
+}
+function EnvironmentGround(props) {
+  const textureDefault = useEnvironment(props);
+  const texture = props.map || textureDefault;
+  React.useMemo(() => extend$1({ GroundProjectedEnvImpl: GroundedSkybox }), []);
+  React.useEffect(() => {
+    return () => {
+      textureDefault.dispose();
+    };
+  }, [textureDefault]);
+  const height = props.ground?.height ?? 15;
+  const radius = props.ground?.radius ?? 60;
+  const scale = props.ground?.scale ?? 1e3;
+  const args = React.useMemo(
+    () => [texture, height, radius],
+    [texture, height, radius]
+  );
+  return /* @__PURE__ */ jsxs(Fragment, { children: [
+    /* @__PURE__ */ jsx(EnvironmentMap, { ...props, map: texture }),
+    /* @__PURE__ */ jsx("groundProjectedEnvImpl", { args, scale })
+  ] });
+}
+function EnvironmentColor({ color, scene }) {
+  const defaultScene = useThree$1((state) => state.scene);
+  React.useLayoutEffect(() => {
+    if (color === void 0) return;
+    const target = resolveScene(scene || defaultScene);
+    const oldBg = target.background;
+    target.background = new Color(color);
+    return () => {
+      target.background = oldBg;
+    };
+  });
+  return null;
+}
+function EnvironmentDualSource(props) {
+  const { backgroundFiles, ...envProps } = props;
+  return /* @__PURE__ */ jsxs(Fragment, { children: [
+    /* @__PURE__ */ jsx(EnvironmentCube, { ...envProps, background: false }),
+    /* @__PURE__ */ jsx(EnvironmentCube, { ...props, files: backgroundFiles, background: "only" })
+  ] });
+}
+function Environment(props) {
+  if (props.color && !props.files && !props.preset && !props.map) {
+    return /* @__PURE__ */ jsx(EnvironmentColor, { ...props });
+  }
+  if (props.backgroundFiles && props.backgroundFiles !== props.files) {
+    return /* @__PURE__ */ jsx(EnvironmentDualSource, { ...props });
+  }
+  return props.ground ? /* @__PURE__ */ jsx(EnvironmentGround, { ...props }) : props.map ? /* @__PURE__ */ jsx(EnvironmentMap, { ...props }) : props.children ? /* @__PURE__ */ jsx(EnvironmentPortal, { ...props }) : /* @__PURE__ */ jsx(EnvironmentCube, { ...props });
+}
+
 var __defProp$2 = Object.defineProperty;
 var __defNormalProp$2 = (obj, key, value) => key in obj ? __defProp$2(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
 var __publicField$2 = (obj, key, value) => __defNormalProp$2(obj, typeof key !== "symbol" ? key + "" : key, value);
@@ -224,7 +613,8 @@ function prepare(target, root, type, props) {
       object,
       eventCount: 0,
       handlers: {},
-      isHidden: false
+      isHidden: false,
+      deferredRefs: []
     };
     if (object) object.__r3f = instance;
   }
@@ -273,7 +663,7 @@ function createOcclusionObserverNode(store, uniform) {
 let occlusionSetupPromise = null;
 function enableOcclusion(store) {
   const state = store.getState();
-  const { internal, renderer, rootScene } = state;
+  const { internal, renderer } = state;
   if (internal.occlusionEnabled || occlusionSetupPromise) return;
   const hasOcclusionSupport = typeof renderer?.isOccluded === "function";
   if (!hasOcclusionSupport) {
@@ -436,6 +826,22 @@ function hasVisibilityHandlers(handlers) {
   return !!(handlers.onFramed || handlers.onOccluded || handlers.onVisible);
 }
 
+const FROM_REF = Symbol.for("@react-three/fiber.fromRef");
+function fromRef(ref) {
+  return { [FROM_REF]: ref };
+}
+function isFromRef(value) {
+  return value !== null && typeof value === "object" && FROM_REF in value;
+}
+
+const ONCE = Symbol.for("@react-three/fiber.once");
+function once(...args) {
+  return { [ONCE]: args.length ? args : true };
+}
+function isOnce(value) {
+  return value !== null && typeof value === "object" && ONCE in value;
+}
+
 const RESERVED_PROPS = [
   "children",
   "key",
@@ -506,7 +912,7 @@ function getMemoizedPrototype(root) {
       ctor = new root.constructor();
       MEMOIZED_PROTOTYPES.set(root.constructor, ctor);
     }
-  } catch (e) {
+  } catch {
   }
   return ctor;
 }
@@ -537,7 +943,7 @@ function applyProps(object, props) {
   const rootState = instance && findInitialRoot(instance).getState();
   const prevHandlers = instance?.eventCount;
   for (const prop in props) {
-    let value = props[prop];
+    const value = props[prop];
     if (RESERVED_PROPS.includes(prop)) continue;
     if (instance && EVENT_REGEX.test(prop)) {
       if (typeof value === "function") instance.handlers[prop] = value;
@@ -552,6 +958,25 @@ function applyProps(object, props) {
       continue;
     }
     if (value === void 0) continue;
+    if (isFromRef(value)) {
+      instance?.deferredRefs?.push({ prop, ref: value[FROM_REF] });
+      continue;
+    }
+    if (isOnce(value)) {
+      if (instance?.appliedOnce?.has(prop)) continue;
+      if (instance) {
+        instance.appliedOnce ?? (instance.appliedOnce = /* @__PURE__ */ new Set());
+        instance.appliedOnce.add(prop);
+      }
+      const { root: targetRoot, key: targetKey } = resolve(object, prop);
+      const args = value[ONCE];
+      if (typeof targetRoot[targetKey] === "function") {
+        targetRoot[targetKey](...args === true ? [] : args);
+      } else if (args !== true && args.length > 0) {
+        targetRoot[targetKey] = args[0];
+      }
+      continue;
+    }
     let { root, key, target } = resolve(object, prop);
     if (target === void 0 && (typeof root !== "object" || root === null)) {
       throw Error(`R3F: Cannot set "${prop}". Ensure it is an object before setting "${key}".`);
@@ -574,7 +999,10 @@ function applyProps(object, props) {
       else target.set(value);
     } else {
       root[key] = value;
-      if (rootState && !rootState.linear && colorMaps.includes(key) && isTexture(value) && root[key]?.isTexture && // sRGB textures must be RGBA8 since r137 https://github.com/mrdoob/three.js/pull/23129
+      if (key.endsWith("Node") && root.isMaterial) {
+        root.needsUpdate = true;
+      }
+      if (rootState && rootState.renderer?.outputColorSpace === SRGBColorSpace && colorMaps.includes(key) && isTexture(value) && root[key]?.isTexture && // sRGB textures must be RGBA8 since r137 https://github.com/mrdoob/three.js/pull/23129
       root[key].format === RGBAFormat && root[key].type === UnsignedByteType) {
         root[key].colorSpace = rootState.textureColorSpace;
       }
@@ -607,38 +1035,60 @@ function applyProps(object, props) {
   return object;
 }
 
+const DEFAULT_POINTER_ID = 0;
+const XR_POINTER_ID_START = 1e3;
+function getPointerState(internal, pointerId) {
+  let state = internal.pointerMap.get(pointerId);
+  if (!state) {
+    state = {
+      hovered: /* @__PURE__ */ new Map(),
+      captured: /* @__PURE__ */ new Map(),
+      initialClick: [0, 0],
+      initialHits: []
+    };
+    internal.pointerMap.set(pointerId, state);
+  }
+  return state;
+}
+function getPointerId(event) {
+  return "pointerId" in event ? event.pointerId : DEFAULT_POINTER_ID;
+}
 function makeId(event) {
   return (event.eventObject || event.object).uuid + "/" + event.index + event.instanceId;
 }
-function releaseInternalPointerCapture(capturedMap, obj, captures, pointerId) {
-  const captureData = captures.get(obj);
+function releaseInternalPointerCapture(internal, obj, pointerId) {
+  const pointerState = internal.pointerMap.get(pointerId);
+  if (!pointerState) return;
+  const captureData = pointerState.captured.get(obj);
   if (captureData) {
-    captures.delete(obj);
-    if (captures.size === 0) {
-      capturedMap.delete(pointerId);
-      captureData.target.releasePointerCapture(pointerId);
-    }
+    pointerState.captured.delete(obj);
+    captureData.target.releasePointerCapture(pointerId);
   }
 }
 function removeInteractivity(store, object) {
   const { internal } = store.getState();
   internal.interaction = internal.interaction.filter((o) => o !== object);
-  internal.initialHits = internal.initialHits.filter((o) => o !== object);
-  internal.hovered.forEach((value, key) => {
-    if (value.eventObject === object || value.object === object) {
-      internal.hovered.delete(key);
+  for (const [pointerId, pointerState] of internal.pointerMap) {
+    pointerState.initialHits = pointerState.initialHits.filter((o) => o !== object);
+    pointerState.hovered.forEach((value, key) => {
+      if (value.eventObject === object || value.object === object) {
+        pointerState.hovered.delete(key);
+      }
+    });
+    if (pointerState.captured.has(object)) {
+      releaseInternalPointerCapture(internal, object, pointerId);
     }
-  });
-  internal.capturedMap.forEach((captures, pointerId) => {
-    releaseInternalPointerCapture(internal.capturedMap, object, captures, pointerId);
-  });
+  }
   unregisterVisibility(store, object);
 }
 function createEvents(store) {
-  function calculateDistance(event) {
+  function calculateDistance(event, pointerId) {
     const { internal } = store.getState();
-    const dx = event.offsetX - internal.initialClick[0];
-    const dy = event.offsetY - internal.initialClick[1];
+    const pointerState = internal.pointerMap.get(pointerId);
+    if (!pointerState) return 0;
+    const [initialX, initialY] = pointerState.initialClick;
+    const dx = event.offsetX - initialX;
+    const dy = event.offsetY - initialY;
     return Math.round(Math.sqrt(dx * dx + dy * dy));
   }
   function filterPointerEvents(objects) {
@@ -674,6 +1124,15 @@ function createEvents(store) {
       return state2.raycaster.camera ? state2.raycaster.intersectObject(obj, true) : [];
     }
     let hits = eventsObjects.flatMap(handleRaycast).sort((a, b) => {
+      const aInteractivePriority = a.object.userData?.interactivePriority;
+      const bInteractivePriority = b.object.userData?.interactivePriority;
+      if (aInteractivePriority !== void 0 || bInteractivePriority !== void 0) {
+        if (aInteractivePriority !== void 0 && bInteractivePriority === void 0) return -1;
+        if (bInteractivePriority !== void 0 && aInteractivePriority === void 0) return 1;
+        if (aInteractivePriority !== bInteractivePriority) {
+          return (bInteractivePriority ?? 0) - (aInteractivePriority ?? 0);
+        }
+      }
       const aState = getRootState(a.object);
       const bState = getRootState(b.object);
       const aPriority = aState?.events?.priority ?? 1;
@@ -689,14 +1148,19 @@ function createEvents(store) {
     for (const hit of hits) {
       let eventObject = hit.object;
       while (eventObject) {
-        if (eventObject.__r3f?.eventCount)
+        if (eventObject.__r3f?.eventCount) {
           intersections.push({ ...hit, eventObject });
+        }
         eventObject = eventObject.parent;
       }
     }
-    if ("pointerId" in event && state.internal.capturedMap.has(event.pointerId)) {
-      for (let captureData of state.internal.capturedMap.get(event.pointerId).values()) {
-        if (!duplicates.has(makeId(captureData.intersection))) intersections.push(captureData.intersection);
+    if ("pointerId" in event) {
+      const pointerId = event.pointerId;
+      const pointerState = state.internal.pointerMap.get(pointerId);
+      if (pointerState?.captured.size) {
+        for (const captureData of pointerState.captured.values()) {
+          if (!duplicates.has(makeId(captureData.intersection))) intersections.push(captureData.intersection);
+        }
       }
     }
     return intersections;
@@ -709,28 +1173,26 @@ function createEvents(store) {
         if (state) {
           const { raycaster, pointer, camera, internal } = state;
           const unprojectedPoint = new Vector3(pointer.x, pointer.y, 0).unproject(camera);
-          const hasPointerCapture = (id) => internal.capturedMap.get(id)?.has(hit.eventObject) ?? false;
+          const hasPointerCapture = (id) => {
+            const pointerState = internal.pointerMap.get(id);
+            return pointerState?.captured.has(hit.eventObject) ?? false;
+          };
           const setPointerCapture = (id) => {
             const captureData = { intersection: hit, target: event.target };
-            if (internal.capturedMap.has(id)) {
-              internal.capturedMap.get(id).set(hit.eventObject, captureData);
-            } else {
-              internal.capturedMap.set(id, /* @__PURE__ */ new Map([[hit.eventObject, captureData]]));
-            }
+            const pointerState = getPointerState(internal, id);
+            pointerState.captured.set(hit.eventObject, captureData);
             event.target.setPointerCapture(id);
           };
           const releasePointerCapture = (id) => {
-            const captures = internal.capturedMap.get(id);
-            if (captures) {
-              releaseInternalPointerCapture(internal.capturedMap, hit.eventObject, captures, id);
-            }
+            releaseInternalPointerCapture(internal, hit.eventObject, id);
           };
-          let extractEventProps = {};
-          for (let prop in event) {
-            let property = event[prop];
+          const extractEventProps = {};
+          for (const prop in event) {
+            const property = event[prop];
             if (typeof property !== "function") extractEventProps[prop] = property;
           }
-          let raycastEvent = {
+          const eventPointerId = "pointerId" in event ? event.pointerId : void 0;
+          const raycastEvent = {
             ...hit,
             ...extractEventProps,
             pointer,
@@ -740,18 +1202,19 @@ function createEvents(store) {
             unprojectedPoint,
             ray: raycaster.ray,
             camera,
+            pointerId: eventPointerId,
             // Hijack stopPropagation, which just sets a flag
             stopPropagation() {
-              const capturesForPointer = "pointerId" in event && internal.capturedMap.get(event.pointerId);
+              const pointerState = eventPointerId !== void 0 ? internal.pointerMap.get(eventPointerId) : void 0;
               if (
                 // ...if this pointer hasn't been captured
-                !capturesForPointer || // ... or if the hit object is capturing the pointer
-                capturesForPointer.has(hit.eventObject)
+                !pointerState?.captured.size || // ... or if the hit object is capturing the pointer
+                pointerState.captured.has(hit.eventObject)
               ) {
                 raycastEvent.stopped = localState.stopped = true;
-                if (internal.hovered.size && Array.from(internal.hovered.values()).find((i) => i.eventObject === hit.eventObject)) {
+                if (pointerState?.hovered.size && Array.from(pointerState.hovered.values()).find((i) => i.eventObject === hit.eventObject)) {
                   const higher = intersections.slice(0, intersections.indexOf(hit));
-                  cancelPointer([...higher, hit]);
+                  cancelPointer([...higher, hit], eventPointerId);
                 }
               }
             },
@@ -767,15 +1230,18 @@ function createEvents(store) {
     }
     return intersections;
   }
-  function cancelPointer(intersections) {
+  function cancelPointer(intersections, pointerId) {
     const { internal } = store.getState();
-    for (const hoveredObj of internal.hovered.values()) {
+    const pid = pointerId ?? DEFAULT_POINTER_ID;
+    const pointerState = internal.pointerMap.get(pid);
+    if (!pointerState) return;
+    for (const [hoveredId, hoveredObj] of pointerState.hovered) {
       if (!intersections.length || !intersections.find(
         (hit) => hit.object === hoveredObj.object && hit.index === hoveredObj.index && hit.instanceId === hoveredObj.instanceId
       )) {
         const eventObject = hoveredObj.eventObject;
         const instance = eventObject.__r3f;
-        internal.hovered.delete(makeId(hoveredObj));
+        pointerState.hovered.delete(hoveredId);
         if (instance?.eventCount) {
           const handlers = instance.handlers;
           const data = { ...hoveredObj, intersections };
@@ -804,41 +1270,118 @@ function createEvents(store) {
       instance?.handlers.onDropMissed?.(event);
     }
   }
+  function cleanupPointer(pointerId) {
+    const { internal } = store.getState();
+    const pointerState = internal.pointerMap.get(pointerId);
+    if (pointerState) {
+      for (const [, hoveredObj] of pointerState.hovered) {
+        const eventObject = hoveredObj.eventObject;
+        const instance = eventObject.__r3f;
+        if (instance?.eventCount) {
+          const handlers = instance.handlers;
+          const data = { ...hoveredObj, intersections: [] };
+          handlers.onPointerOut?.(data);
+          handlers.onPointerLeave?.(data);
+        }
+      }
+      internal.pointerMap.delete(pointerId);
+    }
+    internal.pointerDirty.delete(pointerId);
+  }
+  function processDeferredPointer(event, pointerId) {
+    const state = store.getState();
+    const { internal } = state;
+    if (!state.events.enabled) return;
+    const filter = filterPointerEvents;
+    const hits = intersect(event, filter);
+    cancelPointer(hits, pointerId);
+    function onIntersect(data) {
+      const eventObject = data.eventObject;
+      const instance = eventObject.__r3f;
+      if (!instance?.eventCount) return;
+      const handlers = instance.handlers;
+      if (handlers.onPointerOver || handlers.onPointerEnter || handlers.onPointerOut || handlers.onPointerLeave) {
+        const id = makeId(data);
+        const pointerState = getPointerState(internal, pointerId);
+        const hoveredItem = pointerState.hovered.get(id);
+        if (!hoveredItem) {
+          pointerState.hovered.set(id, data);
+          handlers.onPointerOver?.(data);
+          handlers.onPointerEnter?.(data);
+        } else if (hoveredItem.stopped) {
+          data.stopPropagation();
+        }
+      }
+      handlers.onPointerMove?.(data);
+    }
+    handleIntersects(hits, event, 0, onIntersect);
+  }
   function handlePointer(name) {
     switch (name) {
       case "onPointerLeave":
-      case "onPointerCancel":
       case "onDragLeave":
         return () => cancelPointer([]);
+      // Global cancel of these events
+      case "onPointerCancel":
+        return (event) => {
+          const pointerId = getPointerId(event);
+          cleanupPointer(pointerId);
+        };
       case "onLostPointerCapture":
         return (event) => {
           const { internal } = store.getState();
-          if ("pointerId" in event && internal.capturedMap.has(event.pointerId)) {
+          const pointerId = getPointerId(event);
+          const pointerState = internal.pointerMap.get(pointerId);
+          if (pointerState?.captured.size) {
             requestAnimationFrame(() => {
-              if (internal.capturedMap.has(event.pointerId)) {
-                internal.capturedMap.delete(event.pointerId);
-                cancelPointer([]);
+              const pointerState2 = internal.pointerMap.get(pointerId);
+              if (pointerState2?.captured.size) {
+                pointerState2.captured.clear();
               }
+              cancelPointer([], pointerId);
             });
           }
         };
     }
     return function handleEvent(event) {
       const state = store.getState();
-      const { onPointerMissed, onDragOverMissed, onDropMissed, internal } = state;
+      const { onPointerMissed, onDragOverMissed, onDropMissed, internal, events } = state;
+      const pointerId = getPointerId(event);
       internal.lastEvent.current = event;
-      if (!state.events.enabled) return;
+      if (!events.enabled) return;
       const isPointerMove = name === "onPointerMove";
       const isDragOver = name === "onDragOver";
       const isDrop = name === "onDrop";
       const isClickEvent = name === "onClick" || name === "onContextMenu" || name === "onDoubleClick";
+      const isPointerDown = name === "onPointerDown";
+      const isPointerUp = name === "onPointerUp";
+      const isWheel = name === "onWheel";
+      const canDeferRaycasts = events.frameTimedRaycasts && state.frameloop === "always";
+      if (isPointerMove && canDeferRaycasts) {
+        events.compute?.(event, state);
+        internal.pointerDirty.set(pointerId, event);
+        return;
+      }
+      if (isWheel && canDeferRaycasts && !events.alwaysFireOnScroll) {
+        events.compute?.(event, state);
+        internal.pointerDirty.set(pointerId, event);
+        return;
+      }
+      if ((isClickEvent || isPointerDown || isPointerUp) && internal.pointerDirty.has(pointerId)) {
+        const deferredEvent = internal.pointerDirty.get(pointerId);
+        internal.pointerDirty.delete(pointerId);
+        processDeferredPointer(deferredEvent, pointerId);
+      }
       const filter = isPointerMove || isDragOver || isDrop ? filterPointerEvents : void 0;
       const hits = intersect(event, filter);
-      const delta = isClickEvent ? calculateDistance(event) : 0;
-      if (name === "onPointerDown") {
-        internal.initialClick = [event.offsetX, event.offsetY];
-        internal.initialHits = hits.map((hit) => hit.eventObject);
-      }
+      const delta = isClickEvent ? calculateDistance(event, pointerId) : 0;
+      if (isPointerDown) {
+        const pointerState2 = getPointerState(internal, pointerId);
+        pointerState2.initialClick = [event.offsetX, event.offsetY];
+        pointerState2.initialHits = hits.map((hit) => hit.eventObject);
+      }
+      const pointerState = internal.pointerMap.get(pointerId);
+      const initialHits = pointerState?.initialHits ?? [];
       if (isClickEvent && !hits.length) {
         if (delta <= 2) {
           pointerMissed(event, internal.interaction);
@@ -853,7 +1396,9 @@ function createEvents(store) {
         dropMissed(event, internal.interaction);
         if (onDropMissed) onDropMissed(event);
       }
-      if (isPointerMove || isDragOver) cancelPointer(hits);
+      if (isPointerMove || isDragOver) {
+        cancelPointer(hits, pointerId);
+      }
       function onIntersect(data) {
         const eventObject = data.eventObject;
         const instance = eventObject.__r3f;
@@ -862,9 +1407,10 @@ function createEvents(store) {
         if (isPointerMove) {
           if (handlers.onPointerOver || handlers.onPointerEnter || handlers.onPointerOut || handlers.onPointerLeave) {
             const id = makeId(data);
-            const hoveredItem = internal.hovered.get(id);
+            const pointerState2 = getPointerState(internal, pointerId);
+            const hoveredItem = pointerState2.hovered.get(id);
             if (!hoveredItem) {
-              internal.hovered.set(id, data);
+              pointerState2.hovered.set(id, data);
               handlers.onPointerOver?.(data);
               handlers.onPointerEnter?.(data);
             } else if (hoveredItem.stopped) {
@@ -874,9 +1420,10 @@ function createEvents(store) {
           handlers.onPointerMove?.(data);
         } else if (isDragOver) {
           const id = makeId(data);
-          const hoveredItem = internal.hovered.get(id);
+          const pointerState2 = getPointerState(internal, pointerId);
+          const hoveredItem = pointerState2.hovered.get(id);
           if (!hoveredItem) {
-            internal.hovered.set(id, data);
+            pointerState2.hovered.set(id, data);
             handlers.onDragOverEnter?.(data);
           } else if (hoveredItem.stopped) {
             data.stopPropagation();
@@ -887,18 +1434,18 @@ function createEvents(store) {
         } else {
           const handler = handlers[name];
           if (handler) {
-            if (!isClickEvent || internal.initialHits.includes(eventObject)) {
+            if (!isClickEvent || initialHits.includes(eventObject)) {
               pointerMissed(
                 event,
-                internal.interaction.filter((object) => !internal.initialHits.includes(object))
+                internal.interaction.filter((object) => !initialHits.includes(object))
               );
               handler(data);
             }
           } else {
-            if (isClickEvent && internal.initialHits.includes(eventObject)) {
+            if (isClickEvent && initialHits.includes(eventObject)) {
               pointerMissed(
                 event,
-                internal.interaction.filter((object) => !internal.initialHits.includes(object))
+                internal.interaction.filter((object) => !initialHits.includes(object))
               );
             }
           }
@@ -907,7 +1454,15 @@ function createEvents(store) {
       handleIntersects(hits, event, delta, onIntersect);
     };
   }
-  return { handlePointer };
+  function flushDeferredPointers() {
+    const { internal, events } = store.getState();
+    if (!events.frameTimedRaycasts) return;
+    for (const [pointerId, event] of internal.pointerDirty) {
+      processDeferredPointer(event, pointerId);
+    }
+    internal.pointerDirty.clear();
+  }
+  return { handlePointer, flushDeferredPointers, processDeferredPointer };
 }
 const DOM_EVENTS = {
   onClick: ["click", false],
@@ -926,11 +1481,16 @@ const DOM_EVENTS = {
   onLostPointerCapture: ["lostpointercapture", true]
 };
 function createPointerEvents(store) {
-  const { handlePointer } = createEvents(store);
+  const { handlePointer, flushDeferredPointers, processDeferredPointer } = createEvents(store);
+  let nextXRPointerId = XR_POINTER_ID_START;
+  const xrPointers = /* @__PURE__ */ new Map();
   return {
     priority: 1,
     enabled: true,
-    compute(event, state, previous) {
+    frameTimedRaycasts: true,
+    alwaysFireOnScroll: true,
+    updateOnFrame: false,
+    compute(event, state) {
       state.pointer.set(event.offsetX / state.size.width * 2 - 1, -(event.offsetY / state.size.height) * 2 + 1);
       state.raycaster.setFromCamera(state.pointer, state.camera);
     },
@@ -939,11 +1499,33 @@ function createPointerEvents(store) {
       (acc, key) => ({ ...acc, [key]: handlePointer(key) }),
       {}
     ),
-    update: () => {
+    update: (pointerId) => {
+      const { events, internal } = store.getState();
+      if (!events.handlers) return;
+      if (pointerId !== void 0) {
+        const event = internal.pointerDirty.get(pointerId);
+        if (event) {
+          internal.pointerDirty.delete(pointerId);
+          processDeferredPointer(event, pointerId);
+        } else if (internal.lastEvent?.current) {
+          processDeferredPointer(internal.lastEvent.current, pointerId);
+        }
+      } else {
+        flushDeferredPointers();
+        if (internal.lastEvent?.current) {
+          events.handlers.onPointerMove(internal.lastEvent.current);
+        }
+      }
+    },
+    flush: () => {
       const { events, internal } = store.getState();
-      if (internal.lastEvent?.current && events.handlers) events.handlers.onPointerMove(internal.lastEvent.current);
+      flushDeferredPointers();
+      if (events.updateOnFrame && internal.lastEvent?.current && events.handlers) {
+        events.handlers.onPointerMove(internal.lastEvent.current);
+      }
     },
     connect: (target) => {
+      if (!target) return;
       const { set, events } = store.getState();
       events.disconnect?.();
       set((state) => ({ events: { ...state.events, connected: target } }));
@@ -967,6 +1549,32 @@ function createPointerEvents(store) {
         }
         set((state) => ({ events: { ...state.events, connected: void 0 } }));
       }
+    },
+    registerPointer: (config) => {
+      const pointerId = nextXRPointerId++;
+      xrPointers.set(pointerId, config);
+      const { internal } = store.getState();
+      getPointerState(internal, pointerId);
+      return pointerId;
+    },
+    unregisterPointer: (pointerId) => {
+      xrPointers.delete(pointerId);
+      const { internal } = store.getState();
+      const pointerState = internal.pointerMap.get(pointerId);
+      if (pointerState) {
+        for (const [, hoveredObj] of pointerState.hovered) {
+          const eventObject = hoveredObj.eventObject;
+          const instance = eventObject.__r3f;
+          if (instance?.eventCount) {
+            const handlers = instance.handlers;
+            const data = { ...hoveredObj, intersections: [] };
+            handlers.onPointerOut?.(data);
+            handlers.onPointerLeave?.(data);
+          }
+        }
+        internal.pointerMap.delete(pointerId);
+      }
+      internal.pointerDirty.delete(pointerId);
     }
   };
 }
@@ -1028,300 +1636,26 @@ function notifyAlpha({ message, link }) {
   }
 }
 
-const R3F_CONTEXT = Symbol.for("@react-three/fiber.context");
-const context = globalThis[R3F_CONTEXT] ?? (globalThis[R3F_CONTEXT] = React.createContext(null));
-const createStore = (invalidate, advance) => {
-  const rootStore = createWithEqualityFn((set, get) => {
-    const position = new Vector3();
-    const defaultTarget = new Vector3();
-    const tempTarget = new Vector3();
-    function getCurrentViewport(camera = get().camera, target = defaultTarget, size = get().size) {
-      const { width, height, top, left } = size;
-      const aspect = width / height;
-      if (target.isVector3) tempTarget.copy(target);
-      else tempTarget.set(...target);
-      const distance = camera.getWorldPosition(position).distanceTo(tempTarget);
-      if (isOrthographicCamera(camera)) {
-        return { width: width / camera.zoom, height: height / camera.zoom, top, left, factor: 1, distance, aspect };
-      } else {
-        const fov = camera.fov * Math.PI / 180;
-        const h = 2 * Math.tan(fov / 2) * distance;
-        const w = h * (width / height);
-        return { width: w, height: h, top, left, factor: width / w, distance, aspect };
-      }
-    }
-    let performanceTimeout = void 0;
-    const setPerformanceCurrent = (current) => set((state2) => ({ performance: { ...state2.performance, current } }));
-    const pointer = new Vector2();
-    const rootState = {
-      set,
-      get,
-      // Mock objects that have to be configured
-      gl: null,
-      renderer: null,
-      camera: null,
-      frustum: new Frustum(),
-      autoUpdateFrustum: true,
-      raycaster: null,
-      events: { priority: 1, enabled: true, connected: false },
-      scene: null,
-      rootScene: null,
-      xr: null,
-      inspector: null,
-      invalidate: (frames = 1, stackFrames = false) => invalidate(get(), frames, stackFrames),
-      advance: (timestamp, runGlobalEffects) => advance(timestamp, runGlobalEffects, get()),
-      legacy: false,
-      linear: false,
-      flat: false,
-      textureColorSpace: "srgb",
-      isLegacy: false,
-      webGPUSupported: false,
-      isNative: false,
-      controls: null,
-      pointer,
-      mouse: pointer,
-      frameloop: "always",
-      onPointerMissed: void 0,
-      onDragOverMissed: void 0,
-      onDropMissed: void 0,
-      performance: {
-        current: 1,
-        min: 0.5,
-        max: 1,
-        debounce: 200,
-        regress: () => {
-          const state2 = get();
-          if (performanceTimeout) clearTimeout(performanceTimeout);
-          if (state2.performance.current !== state2.performance.min) setPerformanceCurrent(state2.performance.min);
-          performanceTimeout = setTimeout(
-            () => setPerformanceCurrent(get().performance.max),
-            state2.performance.debounce
-          );
-        }
-      },
-      size: { width: 0, height: 0, top: 0, left: 0 },
-      viewport: {
-        initialDpr: 0,
-        dpr: 0,
-        width: 0,
-        height: 0,
-        top: 0,
-        left: 0,
-        aspect: 0,
-        distance: 0,
-        factor: 0,
-        getCurrentViewport
-      },
-      setEvents: (events) => set((state2) => ({ ...state2, events: { ...state2.events, ...events } })),
-      setSize: (width, height, top = 0, left = 0) => {
-        const camera = get().camera;
-        const size = { width, height, top, left };
-        set((state2) => ({ size, viewport: { ...state2.viewport, ...getCurrentViewport(camera, defaultTarget, size) } }));
-      },
-      setDpr: (dpr) => set((state2) => {
-        const resolved = calculateDpr(dpr);
-        return { viewport: { ...state2.viewport, dpr: resolved, initialDpr: state2.viewport.initialDpr || resolved } };
-      }),
-      setFrameloop: (frameloop = "always") => {
-        set(() => ({ frameloop }));
-      },
-      setError: (error) => set(() => ({ error })),
-      error: null,
-      //* TSL State (managed via hooks: useUniforms, useNodes, useTextures, usePostProcessing) ==============================
-      uniforms: {},
-      nodes: {},
-      textures: /* @__PURE__ */ new Map(),
-      postProcessing: null,
-      passes: {},
-      previousRoot: void 0,
-      internal: {
-        // Events
-        interaction: [],
-        hovered: /* @__PURE__ */ new Map(),
-        subscribers: [],
-        initialClick: [0, 0],
-        initialHits: [],
-        capturedMap: /* @__PURE__ */ new Map(),
-        lastEvent: React.createRef(),
-        // Visibility tracking (onFramed, onOccluded, onVisible)
-        visibilityRegistry: /* @__PURE__ */ new Map(),
-        // Occlusion system (WebGPU only)
-        occlusionEnabled: false,
-        occlusionObserver: null,
-        occlusionCache: /* @__PURE__ */ new Map(),
-        helperGroup: null,
-        // Updates
-        active: false,
-        frames: 0,
-        priority: 0,
-        subscribe: (ref, priority, store) => {
-          const internal = get().internal;
-          internal.priority = internal.priority + (priority > 0 ? 1 : 0);
-          internal.subscribers.push({ ref, priority, store });
-          internal.subscribers = internal.subscribers.sort((a, b) => a.priority - b.priority);
-          return () => {
-            const internal2 = get().internal;
-            if (internal2?.subscribers) {
-              internal2.priority = internal2.priority - (priority > 0 ? 1 : 0);
-              internal2.subscribers = internal2.subscribers.filter((s) => s.ref !== ref);
-            }
-          };
-        },
-        // Renderer Storage (single source of truth)
-        actualRenderer: null,
-        // Scheduler for useFrameNext (initialized in renderer.tsx)
-        scheduler: null
-      }
-    };
-    return rootState;
-  });
-  const state = rootStore.getState();
-  Object.defineProperty(state, "gl", {
-    get() {
-      const currentState = rootStore.getState();
-      if (!currentState.isLegacy && currentState.internal.actualRenderer) {
-        const stack = new Error().stack || "";
-        const isInternalAccess = stack.includes("zustand") || stack.includes("setState") || stack.includes("Object.assign") || stack.includes("react-three-fiber/packages/fiber/src/core");
-        if (!isInternalAccess) {
-          const cleanedStack = stack.split("\n").slice(2).join("\n") || "Stack trace unavailable";
-          notifyDepreciated({
-            heading: "Accessing state.gl in WebGPU mode",
-            body: "Please use state.renderer instead. state.gl is deprecated and will be removed in future versions.\n\nFor backwards compatibility, state.gl currently maps to state.renderer, but this may cause issues with libraries expecting WebGLRenderer.\n\nAccessed from:\n" + cleanedStack
-          });
-        }
-      }
-      return currentState.internal.actualRenderer;
-    },
-    set(value) {
-      rootStore.getState().internal.actualRenderer = value;
-    },
-    enumerable: true,
-    configurable: true
-  });
-  Object.defineProperty(state, "renderer", {
-    get() {
-      return rootStore.getState().internal.actualRenderer;
-    },
-    set(value) {
-      rootStore.getState().internal.actualRenderer = value;
-    },
-    enumerable: true,
-    configurable: true
-  });
-  let oldScene = state.scene;
-  rootStore.subscribe(() => {
-    const currentState = rootStore.getState();
-    const { scene, rootScene, set } = currentState;
-    if (scene !== oldScene) {
-      oldScene = scene;
-      if (scene?.isScene && scene !== rootScene) {
-        set({ rootScene: scene });
-      }
-    }
-  });
-  let oldSize = state.size;
-  let oldDpr = state.viewport.dpr;
-  let oldCamera = state.camera;
-  rootStore.subscribe(() => {
-    const { camera, size, viewport, set, internal } = rootStore.getState();
-    const actualRenderer = internal.actualRenderer;
-    if (size.width !== oldSize.width || size.height !== oldSize.height || viewport.dpr !== oldDpr) {
-      oldSize = size;
-      oldDpr = viewport.dpr;
-      updateCamera(camera, size);
-      if (viewport.dpr > 0) actualRenderer.setPixelRatio(viewport.dpr);
-      const updateStyle = typeof HTMLCanvasElement !== "undefined" && actualRenderer.domElement instanceof HTMLCanvasElement;
-      actualRenderer.setSize(size.width, size.height, updateStyle);
-    }
-    if (camera !== oldCamera) {
-      oldCamera = camera;
-      const { rootScene } = rootStore.getState();
-      if (camera && rootScene && !camera.parent) {
-        rootScene.add(camera);
-      }
-      set((state2) => ({ viewport: { ...state2.viewport, ...state2.viewport.getCurrentViewport(camera) } }));
-      const currentState = rootStore.getState();
-      if (currentState.autoUpdateFrustum && camera) {
-        updateFrustum(camera, currentState.frustum);
-      }
-    }
-  });
-  rootStore.subscribe((state2) => invalidate(state2));
-  return rootStore;
-};
-
-const memoizedLoaders = /* @__PURE__ */ new WeakMap();
-const isConstructor$1 = (value) => typeof value === "function" && value?.prototype?.constructor === value;
-function getLoader(Proto) {
-  if (isConstructor$1(Proto)) {
-    let loader = memoizedLoaders.get(Proto);
-    if (!loader) {
-      loader = new Proto();
-      memoizedLoaders.set(Proto, loader);
-    }
-    return loader;
-  }
-  return Proto;
-}
-function loadingFn(extensions, onProgress) {
-  return function(Proto, input) {
-    const loader = getLoader(Proto);
-    if (extensions) extensions(loader);
-    if ("loadAsync" in loader && typeof loader.loadAsync === "function") {
-      return loader.loadAsync(input, onProgress).then((data) => {
-        if (isObject3D(data?.scene)) Object.assign(data, buildGraph(data.scene));
-        return data;
-      });
-    }
-    return new Promise(
-      (res, reject) => loader.load(
-        input,
-        (data) => {
-          if (isObject3D(data?.scene)) Object.assign(data, buildGraph(data.scene));
-          res(data);
-        },
-        onProgress,
-        (error) => reject(new Error(`Could not load ${input}: ${error?.message}`))
-      )
-    );
-  };
-}
-function useLoader(loader, input, extensions, onProgress) {
-  const keys = Array.isArray(input) ? input : [input];
-  const fn = loadingFn(extensions, onProgress);
-  const results = keys.map((key) => suspend(fn, [loader, key], { equal: is.equ }));
-  return Array.isArray(input) ? results : results[0];
-}
-useLoader.preload = function(loader, input, extensions, onProgress) {
-  const keys = Array.isArray(input) ? input : [input];
-  keys.forEach((key) => preload(loadingFn(extensions, onProgress), [loader, key]));
-};
-useLoader.clear = function(loader, input) {
-  const keys = Array.isArray(input) ? input : [input];
-  keys.forEach((key) => clear([loader, key]));
-};
-useLoader.loader = getLoader;
-
-var __defProp$1 = Object.defineProperty;
-var __defNormalProp$1 = (obj, key, value) => key in obj ? __defProp$1(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
-var __publicField$1 = (obj, key, value) => __defNormalProp$1(obj, typeof key !== "symbol" ? key + "" : key, value);
-const DEFAULT_PHASES = ["start", "input", "physics", "update", "render", "finish"];
-class PhaseGraph {
-  constructor() {
-    /** Ordered list of phase nodes */
-    __publicField$1(this, "phases", []);
-    /** Quick lookup by name */
-    __publicField$1(this, "phaseMap", /* @__PURE__ */ new Map());
-    /** Cached ordered names (invalidated on changes) */
-    __publicField$1(this, "orderedNamesCache", null);
-    this.initializeDefaultPhases();
-  }
-  //* Initialization --------------------------------
-  initializeDefaultPhases() {
-    for (const name of DEFAULT_PHASES) {
-      const node = { name, isAutoGenerated: false };
-      this.phases.push(node);
-      this.phaseMap.set(name, node);
+var __defProp$1 = Object.defineProperty;
+var __defNormalProp$1 = (obj, key, value) => key in obj ? __defProp$1(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __publicField$1 = (obj, key, value) => __defNormalProp$1(obj, typeof key !== "symbol" ? key + "" : key, value);
+const DEFAULT_PHASES = ["start", "input", "physics", "update", "render", "finish"];
+class PhaseGraph {
+  constructor() {
+    /** Ordered list of phase nodes */
+    __publicField$1(this, "phases", []);
+    /** Quick lookup by name */
+    __publicField$1(this, "phaseMap", /* @__PURE__ */ new Map());
+    /** Cached ordered names (invalidated on changes) */
+    __publicField$1(this, "orderedNamesCache", null);
+    this.initializeDefaultPhases();
+  }
+  //* Initialization --------------------------------
+  initializeDefaultPhases() {
+    for (const name of DEFAULT_PHASES) {
+      const node = { name, isAutoGenerated: false };
+      this.phases.push(node);
+      this.phaseMap.set(name, node);
     }
     this.invalidateCache();
   }
@@ -1340,8 +1674,9 @@ class PhaseGraph {
     const node = { name, isAutoGenerated: false };
     let insertIndex = this.phases.length;
     const targetIndex = this.getPhaseIndex(before ?? after);
-    if (targetIndex !== -1) insertIndex = before ? targetIndex : targetIndex + 1;
-    else {
+    if (targetIndex !== -1) {
+      insertIndex = before ? targetIndex : targetIndex + 1;
+    } else {
       const constraintType = before ? "before" : "after";
       console.warn(`[useFrame] Phase "${before ?? after}" not found for '${constraintType}' constraint`);
     }
@@ -1553,7 +1888,7 @@ function shouldRun(job, now) {
   const minInterval = 1e3 / job.fps;
   const lastRun = job.lastRun ?? 0;
   const elapsed = now - lastRun;
-  if (elapsed < minInterval) return false;
+  if (elapsed < minInterval - 1) return false;
   if (job.drop) {
     job.lastRun = now;
   } else {
@@ -2222,116 +2557,444 @@ const _Scheduler = class _Scheduler {
       root.sortedJobs = rebuildSortedJobs(root.jobs, this.phaseGraph);
       root.needsRebuild = false;
     }
-    const providedState = root.getState?.() ?? {};
-    const frameState = {
-      ...providedState,
-      time: timestamp,
-      delta,
-      elapsed: this.loopState.elapsedTime / 1e3,
-      // Convert ms to seconds
-      frame: this.loopState.frameCount
-    };
-    for (const job of root.sortedJobs) {
-      if (!shouldRun(job, timestamp)) continue;
-      try {
-        job.callback(frameState, delta);
-      } catch (error) {
-        console.error(`[Scheduler] Error in job "${job.id}":`, error);
-        this.triggerError(error instanceof Error ? error : new Error(String(error)));
+    const providedState = root.getState?.() ?? {};
+    const frameState = {
+      ...providedState,
+      time: timestamp,
+      delta,
+      elapsed: this.loopState.elapsedTime / 1e3,
+      // Convert ms to seconds
+      frame: this.loopState.frameCount
+    };
+    for (const job of root.sortedJobs) {
+      if (!shouldRun(job, timestamp)) continue;
+      try {
+        job.callback(frameState, delta);
+      } catch (error) {
+        console.error(`[Scheduler] Error in job "${job.id}":`, error);
+        this.triggerError(error instanceof Error ? error : new Error(String(error)));
+      }
+    }
+  }
+  //* Debug & Inspection Methods ================================
+  /**
+   * Get the total number of registered jobs across all roots.
+   * Includes both per-root jobs and global before/after jobs.
+   * @returns {number} Total job count
+   */
+  getJobCount() {
+    let count = 0;
+    for (const root of this.roots.values()) {
+      count += root.jobs.size;
+    }
+    return count + this.globalBeforeJobs.size + this.globalAfterJobs.size;
+  }
+  /**
+   * Get all registered job IDs across all roots.
+   * Includes both per-root jobs and global before/after jobs.
+   * @returns {string[]} Array of all job IDs
+   */
+  getJobIds() {
+    const ids = [];
+    for (const root of this.roots.values()) {
+      ids.push(...root.jobs.keys());
+    }
+    ids.push(...this.globalBeforeJobs.keys());
+    ids.push(...this.globalAfterJobs.keys());
+    return ids;
+  }
+  /**
+   * Get the number of registered roots (Canvas instances).
+   * @returns {number} Number of registered roots
+   */
+  getRootCount() {
+    return this.roots.size;
+  }
+  /**
+   * Check if any user (non-system) jobs are registered in a specific phase.
+   * Used by the default render job to know if a user has taken over rendering.
+   *
+   * @param phase The phase to check
+   * @param rootId Optional root ID to check (checks all roots if not provided)
+   * @returns true if any user jobs exist in the phase
+   */
+  hasUserJobsInPhase(phase, rootId) {
+    const rootsToCheck = rootId ? [this.roots.get(rootId)].filter(Boolean) : Array.from(this.roots.values());
+    return rootsToCheck.some((root) => {
+      if (!root) return false;
+      for (const job of root.jobs.values()) {
+        if (job.phase === phase && !job.system && job.enabled) return true;
+      }
+      return false;
+    });
+  }
+  //* Utility Methods ================================
+  /**
+   * Generate a unique root ID for automatic root registration.
+   * @returns {string} A unique root ID in the format 'root_N'
+   */
+  generateRootId() {
+    return `root_${this.nextRootIndex++}`;
+  }
+  /**
+   * Generate a unique job ID.
+   * @returns {string} A unique job ID in the format 'job_N'
+   * @private
+   */
+  generateJobId() {
+    return `job_${this.nextJobIndex}`;
+  }
+  /**
+   * Normalize before/after constraints to a Set.
+   * Handles undefined, single string, or array inputs.
+   * @param {string | string[] | undefined} value - The constraint value(s)
+   * @returns {Set<string>} Normalized Set of constraint strings
+   * @private
+   */
+  normalizeConstraints(value) {
+    if (!value) return /* @__PURE__ */ new Set();
+    if (Array.isArray(value)) return new Set(value);
+    return /* @__PURE__ */ new Set([value]);
+  }
+};
+//* Static State & Methods (Singleton Usage) ================================
+//* Cross-Bundle Singleton Key ==============================
+// Use Symbol.for() to ensure scheduler is shared across bundle boundaries
+// This prevents issues when mixing imports from @react-three/fiber and @react-three/fiber/webgpu
+__publicField(_Scheduler, "INSTANCE_KEY", Symbol.for("@react-three/fiber.scheduler"));
+let Scheduler = _Scheduler;
+const getScheduler = () => Scheduler.get();
+if (hmrData) {
+  hmrData.accept?.();
+}
+
+const R3F_CONTEXT = Symbol.for("@react-three/fiber.context");
+const context = globalThis[R3F_CONTEXT] ?? (globalThis[R3F_CONTEXT] = React.createContext(null));
+const createStore = (invalidate, advance) => {
+  const rootStore = createWithEqualityFn((set, get) => {
+    const position = new Vector3();
+    const defaultTarget = new Vector3();
+    const tempTarget = new Vector3();
+    function getCurrentViewport(camera = get().camera, target = defaultTarget, size = get().size) {
+      const { width, height, top, left } = size;
+      const aspect = width / height;
+      if (target.isVector3) tempTarget.copy(target);
+      else tempTarget.set(...target);
+      const distance = camera.getWorldPosition(position).distanceTo(tempTarget);
+      if (isOrthographicCamera(camera)) {
+        return { width: width / camera.zoom, height: height / camera.zoom, top, left, factor: 1, distance, aspect };
+      } else {
+        const fov = camera.fov * Math.PI / 180;
+        const h = 2 * Math.tan(fov / 2) * distance;
+        const w = h * (width / height);
+        return { width: w, height: h, top, left, factor: width / w, distance, aspect };
+      }
+    }
+    let performanceTimeout = void 0;
+    const setPerformanceCurrent = (current) => set((state2) => ({ performance: { ...state2.performance, current } }));
+    const pointer = new Vector2();
+    const rootState = {
+      set,
+      get,
+      // Mock objects that have to be configured
+      // primaryStore is set after store creation (self-reference for primary, primary's store for secondary)
+      primaryStore: null,
+      gl: null,
+      renderer: null,
+      camera: null,
+      frustum: new Frustum(),
+      autoUpdateFrustum: true,
+      raycaster: null,
+      events: {
+        priority: 1,
+        enabled: true,
+        connected: false,
+        frameTimedRaycasts: true,
+        alwaysFireOnScroll: true,
+        updateOnFrame: false
+      },
+      scene: null,
+      rootScene: null,
+      xr: null,
+      inspector: null,
+      invalidate: (frames = 1, stackFrames = false) => invalidate(get(), frames, stackFrames),
+      advance: (timestamp, runGlobalEffects) => advance(timestamp, runGlobalEffects, get()),
+      textureColorSpace: SRGBColorSpace,
+      isLegacy: false,
+      webGPUSupported: false,
+      isNative: false,
+      controls: null,
+      pointer,
+      mouse: pointer,
+      frameloop: "always",
+      onPointerMissed: void 0,
+      onDragOverMissed: void 0,
+      onDropMissed: void 0,
+      performance: {
+        current: 1,
+        min: 0.5,
+        max: 1,
+        debounce: 200,
+        regress: () => {
+          const state2 = get();
+          if (performanceTimeout) clearTimeout(performanceTimeout);
+          if (state2.performance.current !== state2.performance.min) setPerformanceCurrent(state2.performance.min);
+          performanceTimeout = setTimeout(
+            () => setPerformanceCurrent(get().performance.max),
+            state2.performance.debounce
+          );
+        }
+      },
+      size: { width: 0, height: 0, top: 0, left: 0 },
+      viewport: {
+        initialDpr: 0,
+        dpr: 0,
+        width: 0,
+        height: 0,
+        top: 0,
+        left: 0,
+        aspect: 0,
+        distance: 0,
+        factor: 0,
+        getCurrentViewport
+      },
+      setEvents: (events) => set((state2) => ({ ...state2, events: { ...state2.events, ...events } })),
+      setSize: (width, height, top, left) => {
+        const state2 = get();
+        if (width === void 0) {
+          set({ _sizeImperative: false });
+          if (state2._sizeProps) {
+            const { width: propW, height: propH } = state2._sizeProps;
+            if (propW !== void 0 || propH !== void 0) {
+              const currentSize = state2.size;
+              const newSize = {
+                width: propW ?? currentSize.width,
+                height: propH ?? currentSize.height,
+                top: currentSize.top,
+                left: currentSize.left
+              };
+              set((s) => ({
+                size: newSize,
+                viewport: { ...s.viewport, ...getCurrentViewport(state2.camera, defaultTarget, newSize) }
+              }));
+              getScheduler().invalidate();
+            }
+          }
+          return;
+        }
+        const w = width;
+        const h = height ?? width;
+        const t = top ?? state2.size.top;
+        const l = left ?? state2.size.left;
+        const size = { width: w, height: h, top: t, left: l };
+        set((s) => ({
+          size,
+          viewport: { ...s.viewport, ...getCurrentViewport(state2.camera, defaultTarget, size) },
+          _sizeImperative: true
+        }));
+        getScheduler().invalidate();
+      },
+      setDpr: (dpr) => set((state2) => {
+        const resolved = calculateDpr(dpr);
+        return { viewport: { ...state2.viewport, dpr: resolved, initialDpr: state2.viewport.initialDpr || resolved } };
+      }),
+      setFrameloop: (frameloop = "always") => {
+        set(() => ({ frameloop }));
+      },
+      setError: (error) => set(() => ({ error })),
+      error: null,
+      //* TSL State (managed via hooks: useUniforms, useNodes, useBuffers, useGPUStorage, useTextures, useRenderPipeline) ==============================
+      uniforms: {},
+      nodes: {},
+      buffers: {},
+      gpuStorage: {},
+      textures: /* @__PURE__ */ new Map(),
+      renderPipeline: null,
+      passes: {},
+      _hmrVersion: 0,
+      _sizeImperative: false,
+      _sizeProps: null,
+      previousRoot: void 0,
+      internal: {
+        // Events
+        interaction: [],
+        subscribers: [],
+        // Per-pointer state (new unified structure)
+        pointerMap: /* @__PURE__ */ new Map(),
+        pointerDirty: /* @__PURE__ */ new Map(),
+        lastEvent: React.createRef(),
+        // Deprecated but kept for backwards compatibility
+        hovered: /* @__PURE__ */ new Map(),
+        initialClick: [0, 0],
+        initialHits: [],
+        capturedMap: /* @__PURE__ */ new Map(),
+        // Visibility tracking (onFramed, onOccluded, onVisible)
+        visibilityRegistry: /* @__PURE__ */ new Map(),
+        // Occlusion system (WebGPU only)
+        occlusionEnabled: false,
+        occlusionObserver: null,
+        occlusionCache: /* @__PURE__ */ new Map(),
+        helperGroup: null,
+        // Updates
+        active: false,
+        frames: 0,
+        priority: 0,
+        subscribe: (ref, priority, store) => {
+          const internal = get().internal;
+          internal.priority = internal.priority + (priority > 0 ? 1 : 0);
+          internal.subscribers.push({ ref, priority, store });
+          internal.subscribers = internal.subscribers.sort((a, b) => a.priority - b.priority);
+          return () => {
+            const internal2 = get().internal;
+            if (internal2?.subscribers) {
+              internal2.priority = internal2.priority - (priority > 0 ? 1 : 0);
+              internal2.subscribers = internal2.subscribers.filter((s) => s.ref !== ref);
+            }
+          };
+        },
+        // Renderer Storage (single source of truth)
+        actualRenderer: null,
+        // Scheduler for useFrameNext (initialized in renderer.tsx)
+        scheduler: null
+      }
+    };
+    return rootState;
+  });
+  const state = rootStore.getState();
+  Object.defineProperty(state, "gl", {
+    get() {
+      const currentState = rootStore.getState();
+      if (!currentState.isLegacy && currentState.internal.actualRenderer) {
+        const stack = new Error().stack || "";
+        const isInternalAccess = stack.includes("zustand") || stack.includes("setState") || stack.includes("Object.assign") || stack.includes("react-three-fiber/packages/fiber/src/core");
+        if (!isInternalAccess) {
+          const cleanedStack = stack.split("\n").slice(2).join("\n") || "Stack trace unavailable";
+          notifyDepreciated({
+            heading: "Accessing state.gl in WebGPU mode",
+            body: "Please use state.renderer instead. state.gl is deprecated and will be removed in future versions.\n\nFor backwards compatibility, state.gl currently maps to state.renderer, but this may cause issues with libraries expecting WebGLRenderer.\n\nAccessed from:\n" + cleanedStack
+          });
+        }
+      }
+      return currentState.internal.actualRenderer;
+    },
+    set(value) {
+      rootStore.getState().internal.actualRenderer = value;
+    },
+    enumerable: true,
+    configurable: true
+  });
+  Object.defineProperty(state, "renderer", {
+    get() {
+      return rootStore.getState().internal.actualRenderer;
+    },
+    set(value) {
+      rootStore.getState().internal.actualRenderer = value;
+    },
+    enumerable: true,
+    configurable: true
+  });
+  let oldScene = state.scene;
+  rootStore.subscribe(() => {
+    const currentState = rootStore.getState();
+    const { scene, rootScene, set } = currentState;
+    if (scene !== oldScene) {
+      oldScene = scene;
+      if (scene?.isScene && scene !== rootScene) {
+        set({ rootScene: scene });
+      }
+    }
+  });
+  let oldSize = state.size;
+  let oldDpr = state.viewport.dpr;
+  let oldCamera = state.camera;
+  rootStore.subscribe(() => {
+    const { camera, size, viewport, set, internal } = rootStore.getState();
+    const actualRenderer = internal.actualRenderer;
+    const canvasTarget = internal.canvasTarget;
+    if (size.width !== oldSize.width || size.height !== oldSize.height || viewport.dpr !== oldDpr) {
+      oldSize = size;
+      oldDpr = viewport.dpr;
+      updateCamera(camera, size);
+      if (internal.isSecondary && canvasTarget) {
+        if (viewport.dpr > 0) canvasTarget.setPixelRatio(viewport.dpr);
+        canvasTarget.setSize(size.width, size.height, false);
+      } else {
+        if (viewport.dpr > 0) actualRenderer.setPixelRatio(viewport.dpr);
+        actualRenderer.setSize(size.width, size.height, false);
+        if (canvasTarget) {
+          if (viewport.dpr > 0) canvasTarget.setPixelRatio(viewport.dpr);
+          canvasTarget.setSize(size.width, size.height, false);
+        }
+      }
+    }
+    if (camera !== oldCamera) {
+      oldCamera = camera;
+      const { rootScene } = rootStore.getState();
+      if (camera && rootScene && !camera.parent) {
+        rootScene.add(camera);
+      }
+      set((state2) => ({ viewport: { ...state2.viewport, ...state2.viewport.getCurrentViewport(camera) } }));
+      const currentState = rootStore.getState();
+      if (currentState.autoUpdateFrustum && camera) {
+        updateFrustum(camera, currentState.frustum);
       }
     }
-  }
-  //* Debug & Inspection Methods ================================
-  /**
-   * Get the total number of registered jobs across all roots.
-   * Includes both per-root jobs and global before/after jobs.
-   * @returns {number} Total job count
-   */
-  getJobCount() {
-    let count = 0;
-    for (const root of this.roots.values()) {
-      count += root.jobs.size;
+  });
+  rootStore.subscribe((state2) => invalidate(state2));
+  return rootStore;
+};
+
+const memoizedLoaders = /* @__PURE__ */ new WeakMap();
+const isConstructor$1 = (value) => typeof value === "function" && value?.prototype?.constructor === value;
+function getLoader(Proto) {
+  if (isConstructor$1(Proto)) {
+    let loader = memoizedLoaders.get(Proto);
+    if (!loader) {
+      loader = new Proto();
+      memoizedLoaders.set(Proto, loader);
     }
-    return count + this.globalBeforeJobs.size + this.globalAfterJobs.size;
+    return loader;
   }
-  /**
-   * Get all registered job IDs across all roots.
-   * Includes both per-root jobs and global before/after jobs.
-   * @returns {string[]} Array of all job IDs
-   */
-  getJobIds() {
-    const ids = [];
-    for (const root of this.roots.values()) {
-      ids.push(...root.jobs.keys());
+  return Proto;
+}
+function loadingFn(extensions, onProgress) {
+  return function(Proto, input) {
+    const loader = getLoader(Proto);
+    if (extensions) extensions(loader);
+    if ("loadAsync" in loader && typeof loader.loadAsync === "function") {
+      return loader.loadAsync(input, onProgress).then((data) => {
+        if (isObject3D(data?.scene)) Object.assign(data, buildGraph(data.scene));
+        return data;
+      });
     }
-    ids.push(...this.globalBeforeJobs.keys());
-    ids.push(...this.globalAfterJobs.keys());
-    return ids;
-  }
-  /**
-   * Get the number of registered roots (Canvas instances).
-   * @returns {number} Number of registered roots
-   */
-  getRootCount() {
-    return this.roots.size;
-  }
-  /**
-   * Check if any user (non-system) jobs are registered in a specific phase.
-   * Used by the default render job to know if a user has taken over rendering.
-   *
-   * @param phase The phase to check
-   * @param rootId Optional root ID to check (checks all roots if not provided)
-   * @returns true if any user jobs exist in the phase
-   */
-  hasUserJobsInPhase(phase, rootId) {
-    const rootsToCheck = rootId ? [this.roots.get(rootId)].filter(Boolean) : Array.from(this.roots.values());
-    return rootsToCheck.some((root) => {
-      if (!root) return false;
-      for (const job of root.jobs.values()) {
-        if (job.phase === phase && !job.system && job.enabled) return true;
-      }
-      return false;
-    });
-  }
-  //* Utility Methods ================================
-  /**
-   * Generate a unique root ID for automatic root registration.
-   * @returns {string} A unique root ID in the format 'root_N'
-   */
-  generateRootId() {
-    return `root_${this.nextRootIndex++}`;
-  }
-  /**
-   * Generate a unique job ID.
-   * @returns {string} A unique job ID in the format 'job_N'
-   * @private
-   */
-  generateJobId() {
-    return `job_${this.nextJobIndex}`;
-  }
-  /**
-   * Normalize before/after constraints to a Set.
-   * Handles undefined, single string, or array inputs.
-   * @param {string | string[] | undefined} value - The constraint value(s)
-   * @returns {Set<string>} Normalized Set of constraint strings
-   * @private
-   */
-  normalizeConstraints(value) {
-    if (!value) return /* @__PURE__ */ new Set();
-    if (Array.isArray(value)) return new Set(value);
-    return /* @__PURE__ */ new Set([value]);
-  }
-};
-//* Static State & Methods (Singleton Usage) ================================
-//* Cross-Bundle Singleton Key ==============================
-// Use Symbol.for() to ensure scheduler is shared across bundle boundaries
-// This prevents issues when mixing imports from @react-three/fiber and @react-three/fiber/webgpu
-__publicField(_Scheduler, "INSTANCE_KEY", Symbol.for("@react-three/fiber.scheduler"));
-let Scheduler = _Scheduler;
-const getScheduler = () => Scheduler.get();
-if (hmrData) {
-  hmrData.accept?.();
+    return new Promise(
+      (res, reject) => loader.load(
+        input,
+        (data) => {
+          if (isObject3D(data?.scene)) Object.assign(data, buildGraph(data.scene));
+          res(data);
+        },
+        onProgress,
+        (error) => reject(new Error(`Could not load ${input}: ${error?.message}`))
+      )
+    );
+  };
+}
+function useLoader(loader, input, extensions, onProgress) {
+  const keys = Array.isArray(input) ? input : [input];
+  const fn = loadingFn(extensions, onProgress);
+  const results = keys.map((key) => suspend(fn, [loader, key], { equal: is.equ }));
+  return Array.isArray(input) ? results : results[0];
 }
+useLoader.preload = function(loader, input, extensions, onProgress) {
+  const keys = Array.isArray(input) ? input : [input];
+  keys.forEach((key) => preload(loadingFn(extensions, onProgress), [loader, key]));
+};
+useLoader.clear = function(loader, input) {
+  const keys = Array.isArray(input) ? input : [input];
+  keys.forEach((key) => clear([loader, key]));
+};
+useLoader.loader = getLoader;
 
 function useFrame(callback, priorityOrOptions) {
   const store = React.useContext(context);
@@ -2512,6 +3175,9 @@ function useTexture(input, optionsOrOnLoad) {
   const textureCache = useThree((state) => state.textures);
   const options = typeof optionsOrOnLoad === "function" ? { onLoad: optionsOrOnLoad } : optionsOrOnLoad ?? {};
   const { onLoad, cache = false } = options;
+  const onLoadRef = useRef(onLoad);
+  onLoadRef.current = onLoad;
+  const onLoadCalledForRef = useRef(null);
   const urls = useMemo(() => getUrls(input), [input]);
   const cachedResult = useMemo(() => {
     if (!cache) return null;
@@ -2522,9 +3188,13 @@ function useTexture(input, optionsOrOnLoad) {
     TextureLoader,
     IsObject(input) ? Object.values(input) : input
   );
+  const inputKey = urls.join("\0");
   useLayoutEffect(() => {
-    if (!cachedResult) onLoad?.(loadedTextures);
-  }, [onLoad, cachedResult, loadedTextures]);
+    if (cachedResult) return;
+    if (onLoadCalledForRef.current === inputKey) return;
+    onLoadCalledForRef.current = inputKey;
+    onLoadRef.current?.(loadedTextures);
+  }, [cachedResult, loadedTextures, inputKey]);
   useEffect(() => {
     if (cachedResult) return;
     if ("initTexture" in renderer) {
@@ -2691,14 +3361,31 @@ function useTextures() {
   }, [store]);
 }
 
-function useRenderTarget(width, height, options) {
+function useRenderTarget(widthOrOptions, heightOrOptions, options) {
   const isLegacy = useThree((s) => s.isLegacy);
   const size = useThree((s) => s.size);
+  let width;
+  let height;
+  let opts;
+  if (typeof widthOrOptions === "object") {
+    opts = widthOrOptions;
+  } else if (typeof widthOrOptions === "number") {
+    width = widthOrOptions;
+    if (typeof heightOrOptions === "object") {
+      height = widthOrOptions;
+      opts = heightOrOptions;
+    } else if (typeof heightOrOptions === "number") {
+      height = heightOrOptions;
+      opts = options;
+    } else {
+      height = widthOrOptions;
+    }
+  }
   return useMemo(() => {
     const w = width ?? size.width;
     const h = height ?? size.height;
-    return new WebGLRenderTarget(w, h, options);
-  }, [width, height, size.width, size.height, options, isLegacy]);
+    return new WebGLRenderTarget(w, h, opts);
+  }, [width, height, size.width, size.height, opts, isLegacy]);
 }
 
 function useStore() {
@@ -2748,28 +3435,18 @@ function addTail(callback) {
 function invalidate(state, frames = 1, stackFrames = false) {
   getScheduler().invalidate(frames, stackFrames);
 }
-function advance(timestamp, runGlobalEffects = true, state, frame) {
+function advance(timestamp) {
   getScheduler().step(timestamp);
 }
 
-const version = "10.0.0-alpha.1";
+const version = "10.0.0-alpha.2";
 const packageData = {
 	version: version};
 
 function Xb(Tt) {
   return Tt && Tt.__esModule && Object.prototype.hasOwnProperty.call(Tt, "default") ? Tt.default : Tt;
 }
-var Rm = { exports: {} }, Og = { exports: {} };
-/**
-* @license React
-* react-reconciler.production.js
-*
-* Copyright (c) Meta Platforms, Inc. and affiliates.
-*
-* This source code is licensed under the MIT license found in the
-* LICENSE file in the root directory of this source tree.
-*/
-var _b;
+var Rm = { exports: {} }, Og = { exports: {} }, _b;
 function Kb() {
   return _b || (_b = 1, (function(Tt) {
     Tt.exports = function(m) {
@@ -3841,7 +4518,6 @@ Error generating stack: ` + l.message + `
             if (J === cl || J === jc) throw J;
             var Ge = Yn(29, J, null, P.mode);
             return Ge.lanes = H, Ge.return = P, Ge;
-          } finally {
           }
         };
       }
@@ -4495,7 +5171,6 @@ Error generating stack: ` + l.message + `
             var h = r.lastRenderedState, y = d(h, a);
             if (c.hasEagerState = true, c.eagerState = y, jn(y, h)) return go(t, r, c, 0), Ne === null && Bn(), false;
           } catch {
-          } finally {
           }
           if (a = yo(t, r, c, l), a !== null) return nt(a, t, l), ns(a, r, l), true;
         }
@@ -6916,10 +7591,7 @@ Error generating stack: ` + l.message + `
       function vr(t, r) {
         Sf(t, r), (t = t.alternate) && Sf(t, r);
       }
-      var ie = {}, Fm = React__default, tt = Tb, Lt = Object.assign, hc = Symbol.for("react.element"), zs = Symbol.for("react.transitional.element"), sa = Symbol.for("react.portal"), $a = Symbol.for("react.fragment"), kf = Symbol.for("react.strict_mode"), Cs = Symbol.for("react.profiler"), mc = Symbol.for("react.consumer"), Io = Symbol.for("react.context"), Zi = Symbol.for("react.forward_ref"), Va = Symbol.for("react.suspense"), Te = Symbol.for("react.suspense_list"), wf = Symbol.for("react.memo"), ua = Symbol.for("react.lazy");
-      var gc = Symbol.for("react.activity");
-      var $r = Symbol.for("react.memo_cache_sentinel");
-      var Pf = Symbol.iterator, xf = Symbol.for("react.client.reference"), ca = Array.isArray, M = Fm.__CLIENT_INTERNALS_DO_NOT_USE_OR_WARN_USERS_THEY_CANNOT_UPGRADE, Yp = m.rendererVersion, zf = m.rendererPackageName, Cf = m.extraDevToolsConfig, Ts = m.getPublicInstance, Hm = m.getRootHostContext, Xp = m.getChildHostContext, Am = m.prepareForCommit, _s = m.resetAfterCommit, Vr = m.createInstance;
+      var ie = {}, Fm = React__default, tt = Tb, Lt = Object.assign, hc = Symbol.for("react.element"), zs = Symbol.for("react.transitional.element"), sa = Symbol.for("react.portal"), $a = Symbol.for("react.fragment"), kf = Symbol.for("react.strict_mode"), Cs = Symbol.for("react.profiler"), mc = Symbol.for("react.consumer"), Io = Symbol.for("react.context"), Zi = Symbol.for("react.forward_ref"), Va = Symbol.for("react.suspense"), Te = Symbol.for("react.suspense_list"), wf = Symbol.for("react.memo"), ua = Symbol.for("react.lazy"), gc = Symbol.for("react.activity"), $r = Symbol.for("react.memo_cache_sentinel"), Pf = Symbol.iterator, xf = Symbol.for("react.client.reference"), ca = Array.isArray, M = Fm.__CLIENT_INTERNALS_DO_NOT_USE_OR_WARN_USERS_THEY_CANNOT_UPGRADE, Yp = m.rendererVersion, zf = m.rendererPackageName, Cf = m.extraDevToolsConfig, Ts = m.getPublicInstance, Hm = m.getRootHostContext, Xp = m.getChildHostContext, Am = m.prepareForCommit, _s = m.resetAfterCommit, Vr = m.createInstance;
       m.cloneMutableInstance;
       var yc = m.appendInitialChild, Kp = m.finalizeInitialChildren, Rs = m.shouldSetTextContent, bc = m.createTextInstance;
       m.cloneMutableTextInstance;
@@ -7288,17 +7960,7 @@ No matching component was found for:
     }, Tt.exports.default = Tt.exports, Object.defineProperty(Tt.exports, "__esModule", { value: true });
   })(Og)), Og.exports;
 }
-var Mg = { exports: {} };
-/**
-* @license React
-* react-reconciler.development.js
-*
-* Copyright (c) Meta Platforms, Inc. and affiliates.
-*
-* This source code is licensed under the MIT license found in the
-* LICENSE file in the root directory of this source tree.
-*/
-var Rb;
+var Mg = { exports: {} }, Rb;
 function e0() {
   return Rb || (Rb = 1, (function(Tt) {
     process.env.NODE_ENV !== "production" && (Tt.exports = function(m) {
@@ -13065,10 +13727,7 @@ Check the render method of %s.`, G(di) || "Unknown")), i = zo(n), i.payload = {
       function Ic() {
         return di;
       }
-      var le = {}, qm = React__default, St = Tb, ze = Object.assign, Uh = Symbol.for("react.element"), Ho = Symbol.for("react.transitional.element"), Ao = Symbol.for("react.portal"), ol = Symbol.for("react.fragment"), Lc = Symbol.for("react.strict_mode"), Uf = Symbol.for("react.profiler"), ei = Symbol.for("react.consumer"), on = Symbol.for("react.context"), jn = Symbol.for("react.forward_ref"), Nc = Symbol.for("react.suspense"), Bf = Symbol.for("react.suspense_list"), al = Symbol.for("react.memo"), kt = Symbol.for("react.lazy");
-      var Ds = Symbol.for("react.activity");
-      var Bh = Symbol.for("react.memo_cache_sentinel");
-      var ni = Symbol.iterator, il = Symbol.for("react.client.reference"), fn = Array.isArray, x = qm.__CLIENT_INTERNALS_DO_NOT_USE_OR_WARN_USERS_THEY_CANNOT_UPGRADE, Jt = m.rendererVersion, Zt = m.rendererPackageName, jo = m.extraDevToolsConfig, ot = m.getPublicInstance, Zr = m.getRootHostContext, Dn = m.getChildHostContext, Ws = m.prepareForCommit, pa = m.resetAfterCommit, Fc = m.createInstance;
+      var le = {}, qm = React__default, St = Tb, ze = Object.assign, Uh = Symbol.for("react.element"), Ho = Symbol.for("react.transitional.element"), Ao = Symbol.for("react.portal"), ol = Symbol.for("react.fragment"), Lc = Symbol.for("react.strict_mode"), Uf = Symbol.for("react.profiler"), ei = Symbol.for("react.consumer"), on = Symbol.for("react.context"), jn = Symbol.for("react.forward_ref"), Nc = Symbol.for("react.suspense"), Bf = Symbol.for("react.suspense_list"), al = Symbol.for("react.memo"), kt = Symbol.for("react.lazy"), Ds = Symbol.for("react.activity"), Bh = Symbol.for("react.memo_cache_sentinel"), ni = Symbol.iterator, il = Symbol.for("react.client.reference"), fn = Array.isArray, x = qm.__CLIENT_INTERNALS_DO_NOT_USE_OR_WARN_USERS_THEY_CANNOT_UPGRADE, Jt = m.rendererVersion, Zt = m.rendererPackageName, jo = m.extraDevToolsConfig, ot = m.getPublicInstance, Zr = m.getRootHostContext, Dn = m.getChildHostContext, Ws = m.prepareForCommit, pa = m.resetAfterCommit, Fc = m.createInstance;
       m.cloneMutableInstance;
       var bn = m.appendInitialChild, Ue = m.finalizeInitialChildren, ue = m.shouldSetTextContent, Do = m.createTextInstance;
       m.cloneMutableTextInstance;
@@ -14036,15 +14695,6 @@ function n0() {
 var t0 = n0();
 const r0 = Xb(t0);
 
-/**
- * @license React
- * react-reconciler-constants.production.js
- *
- * Copyright (c) Meta Platforms, Inc. and affiliates.
- *
- * This source code is licensed under the MIT license found in the
- * LICENSE file in the root directory of this source tree.
- */
 const t = 1, o = 8, r = 32, e = 2;
 
 function createReconciler(config) {
@@ -14071,10 +14721,11 @@ function extend(objects) {
 function validateInstance(type, props) {
   const name = toPascalCase(type);
   const target = catalogue[name];
-  if (type !== "primitive" && !target)
+  if (type !== "primitive" && !target) {
     throw new Error(
       `R3F: ${name} is not part of the THREE namespace! Did you forget to extend? See: https://docs.pmnd.rs/react-three-fiber/api/objects#using-3rd-party-objects-declaratively`
     );
+  }
   if (type === "primitive" && !props.object) throw new Error(`R3F: Primitives without 'object' are invalid!`);
   if (props.args !== void 0 && !Array.isArray(props.args)) throw new Error("R3F: The args prop must be an array!");
 }
@@ -14238,6 +14889,7 @@ function swapInstances() {
       instance.object = instance.props.object ?? new target(...instance.props.args ?? []);
       instance.object.__r3f = instance;
       setFiberRef(fiber, instance.object);
+      delete instance.appliedOnce;
       applyProps(instance.object, instance.props);
       if (instance.props.attach) {
         attach(parent, instance);
@@ -14311,8 +14963,22 @@ const reconciler = /* @__PURE__ */ createReconciler({
     const isTailSibling = fiber.sibling === null || (fiber.flags & Update) === NoFlags;
     if (isTailSibling) swapInstances();
   },
-  finalizeInitialChildren: () => false,
-  commitMount() {
+  finalizeInitialChildren: (instance) => {
+    for (const prop in instance.props) {
+      if (isFromRef(instance.props[prop])) return true;
+    }
+    return false;
+  },
+  commitMount(instance) {
+    const resolved = {};
+    for (const prop in instance.props) {
+      const value = instance.props[prop];
+      if (isFromRef(value)) {
+        const ref = value[FROM_REF];
+        if (ref.current != null) resolved[prop] = ref.current;
+      }
+    }
+    if (Object.keys(resolved).length) applyProps(instance.object, resolved);
   },
   getPublicInstance: (instance) => instance?.object,
   prepareForCommit: () => null,
@@ -14525,14 +15191,17 @@ function createRoot(canvas) {
   if (!prevRoot) _roots.set(canvas, { fiber, store });
   let onCreated;
   let lastCamera;
-  let lastConfiguredProps = {};
+  const lastConfiguredProps = {};
   let configured = false;
   let pending = null;
   return {
     async configure(props = {}) {
       let resolve;
       pending = new Promise((_resolve) => resolve = _resolve);
-      let {
+      const {
+        id: canvasId,
+        primaryCanvas,
+        scheduler: schedulerConfig,
         gl: glConfig,
         renderer: rendererConfig,
         size: propsSize,
@@ -14540,10 +15209,6 @@ function createRoot(canvas) {
         events,
         onCreated: onCreatedCallback,
         shadows = false,
-        linear = false,
-        flat = false,
-        textureColorSpace = SRGBColorSpace,
-        legacy = false,
         orthographic = false,
         frameloop = "always",
         dpr = [1, 2],
@@ -14554,9 +15219,12 @@ function createRoot(canvas) {
         onDragOverMissed,
         onDropMissed,
         autoUpdateFrustum = true,
-        occlusion = false
+        occlusion = false,
+        _sizeProps,
+        forceEven
       } = props;
-      let state = store.getState();
+      const textureColorSpace = is.obj(glConfig) && !is.fun(glConfig) && !isRenderer(glConfig) && glConfig.textureColorSpace || is.obj(rendererConfig) && !is.fun(rendererConfig) && !isRenderer(rendererConfig) && rendererConfig.textureColorSpace || SRGBColorSpace;
+      const state = store.getState();
       const defaultGLProps = {
         canvas,
         powerPreference: "high-performance",
@@ -14568,22 +15236,34 @@ function createRoot(canvas) {
           "WebGPURenderer (renderer prop) is not available in this build. Use @react-three/fiber or @react-three/fiber/webgpu instead."
         );
       }
-      (state.isLegacy || glConfig || !R3F_BUILD_WEBGPU);
+      const wantsGL = (state.isLegacy || glConfig || !R3F_BUILD_WEBGPU);
       if (glConfig && rendererConfig) {
         throw new Error("Cannot use both gl and renderer props at the same time");
       }
       let renderer = state.internal.actualRenderer;
+      if (primaryCanvas && !R3F_BUILD_WEBGPU) {
+        throw new Error(
+          "The `primaryCanvas` prop for multi-canvas rendering is only available with WebGPU. Use @react-three/fiber/webgpu instead."
+        );
+      }
+      if (primaryCanvas && wantsGL) {
+        throw new Error(
+          "The `primaryCanvas` prop for multi-canvas rendering cannot be used with WebGL. Remove the `gl` prop or use WebGPU."
+        );
+      }
       if (!state.internal.actualRenderer) {
         renderer = await resolveRenderer(glConfig, defaultGLProps, WebGLRenderer);
         state.internal.actualRenderer = renderer;
-        state.set({ isLegacy: true, gl: renderer, renderer });
+        state.set({ isLegacy: true, gl: renderer, renderer, primaryStore: store });
       }
       let raycaster = state.raycaster;
       if (!raycaster) state.set({ raycaster: raycaster = new Raycaster() });
       const { params, ...options } = raycastOptions || {};
       if (!is.equ(options, raycaster, shallowLoose)) applyProps(raycaster, { ...options });
-      if (!is.equ(params, raycaster.params, shallowLoose))
+      if (!is.equ(params, raycaster.params, shallowLoose)) {
         applyProps(raycaster, { params: { ...raycaster.params, ...params } });
+      }
+      let tempCamera = state.camera;
       if (!state.camera || state.camera === lastCamera && !is.equ(lastCamera, cameraOptions, shallowLoose)) {
         lastCamera = cameraOptions;
         const isCamera = cameraOptions?.isCamera;
@@ -14603,6 +15283,7 @@ function createRoot(canvas) {
           if (!state.camera && !cameraOptions?.rotation) camera.lookAt(0, 0, 0);
         }
         state.set({ camera });
+        tempCamera = camera;
         raycaster.camera = camera;
       }
       if (!state.scene) {
@@ -14620,7 +15301,7 @@ function createRoot(canvas) {
           rootScene: scene,
           internal: { ...prev.internal, container: scene }
         }));
-        const camera = state.camera;
+        const camera = tempCamera;
         if (camera && !camera.parent) scene.add(camera);
       }
       if (events && !state.events.handlers) {
@@ -14634,9 +15315,17 @@ function createRoot(canvas) {
           wasEnabled = enabled;
         });
       }
+      if (_sizeProps !== void 0) {
+        state.set({ _sizeProps });
+      }
+      if (forceEven !== void 0 && state.internal.forceEven !== forceEven) {
+        state.set((prev) => ({ internal: { ...prev.internal, forceEven } }));
+      }
       const size = computeInitialSize(canvas, propsSize);
-      if (!is.equ(size, state.size, shallowLoose)) {
+      if (!state._sizeImperative && !is.equ(size, state.size, shallowLoose)) {
+        const wasImperative = state._sizeImperative;
         state.setSize(size.width, size.height, size.top, size.left);
+        if (!wasImperative) state.set({ _sizeImperative: false });
       }
       if (dpr !== void 0 && !is.equ(dpr, lastConfiguredProps.dpr, shallowLoose)) {
         state.setDpr(dpr);
@@ -14658,10 +15347,10 @@ function createRoot(canvas) {
         lastConfiguredProps.performance = performance;
       }
       if (!state.xr) {
-        const handleXRFrame = (timestamp, frame) => {
+        const handleXRFrame = (timestamp, _frame) => {
           const state2 = store.getState();
           if (state2.frameloop === "never") return;
-          advance(timestamp, true);
+          advance(timestamp);
         };
         const actualRenderer = state.internal.actualRenderer;
         const handleSessionChange = () => {
@@ -14673,16 +15362,16 @@ function createRoot(canvas) {
         };
         const xr = {
           connect() {
-            const { gl, renderer: renderer2, isLegacy } = store.getState();
-            const actualRenderer2 = renderer2 || gl;
-            actualRenderer2.xr.addEventListener("sessionstart", handleSessionChange);
-            actualRenderer2.xr.addEventListener("sessionend", handleSessionChange);
+            const { gl, renderer: renderer2 } = store.getState();
+            const xrManager = (renderer2 || gl).xr;
+            xrManager.addEventListener("sessionstart", handleSessionChange);
+            xrManager.addEventListener("sessionend", handleSessionChange);
           },
           disconnect() {
-            const { gl, renderer: renderer2, isLegacy } = store.getState();
-            const actualRenderer2 = renderer2 || gl;
-            actualRenderer2.xr.removeEventListener("sessionstart", handleSessionChange);
-            actualRenderer2.xr.removeEventListener("sessionend", handleSessionChange);
+            const { gl, renderer: renderer2 } = store.getState();
+            const xrManager = (renderer2 || gl).xr;
+            xrManager.removeEventListener("sessionstart", handleSessionChange);
+            xrManager.removeEventListener("sessionend", handleSessionChange);
           }
         };
         if (typeof renderer.xr?.addEventListener === "function") xr.connect();
@@ -14694,61 +15383,92 @@ function createRoot(canvas) {
         const oldType = renderer.shadowMap.type;
         renderer.shadowMap.enabled = !!shadows;
         if (is.boo(shadows)) {
-          renderer.shadowMap.type = PCFSoftShadowMap;
+          renderer.shadowMap.type = PCFShadowMap;
         } else if (is.str(shadows)) {
+          if (shadows === "soft") {
+            notifyDepreciated({
+              heading: 'shadows="soft" is deprecated',
+              body: "Three has depreciated soft and improved basic PCFShadows, we converted for you.",
+              link: "https://github.com/mrdoob/three.js/wiki/Migration-Guide?utm_source=chatgpt.com#181--182"
+            });
+          }
           const types = {
             basic: BasicShadowMap,
             percentage: PCFShadowMap,
-            soft: PCFSoftShadowMap,
+            soft: PCFShadowMap,
             variance: VSMShadowMap
           };
-          renderer.shadowMap.type = types[shadows] ?? PCFSoftShadowMap;
+          renderer.shadowMap.type = types[shadows] ?? PCFShadowMap;
         } else if (is.obj(shadows)) {
           Object.assign(renderer.shadowMap, shadows);
         }
-        if (oldEnabled !== renderer.shadowMap.enabled || oldType !== renderer.shadowMap.type)
+        if (oldEnabled !== renderer.shadowMap.enabled || oldType !== renderer.shadowMap.type) {
           renderer.shadowMap.needsUpdate = true;
-      }
-      {
-        const legacyChanged = legacy !== lastConfiguredProps.legacy;
-        const linearChanged = linear !== lastConfiguredProps.linear;
-        const flatChanged = flat !== lastConfiguredProps.flat;
-        if (legacyChanged) {
-          ColorManagement.enabled = !legacy;
-          lastConfiguredProps.legacy = legacy;
         }
-        if (!configured || linearChanged) {
-          renderer.outputColorSpace = linear ? LinearSRGBColorSpace : SRGBColorSpace;
-          lastConfiguredProps.linear = linear;
-        }
-        if (!configured || flatChanged) {
-          renderer.toneMapping = flat ? NoToneMapping : ACESFilmicToneMapping;
-          lastConfiguredProps.flat = flat;
-        }
-        if (legacyChanged && state.legacy !== legacy) state.set(() => ({ legacy }));
-        if (linearChanged && state.linear !== linear) state.set(() => ({ linear }));
-        if (flatChanged && state.flat !== flat) state.set(() => ({ flat }));
+      }
+      if (!configured) {
+        renderer.outputColorSpace = SRGBColorSpace;
+        renderer.toneMapping = ACESFilmicToneMapping;
       }
       if (textureColorSpace !== lastConfiguredProps.textureColorSpace) {
         if (state.textureColorSpace !== textureColorSpace) state.set(() => ({ textureColorSpace }));
         lastConfiguredProps.textureColorSpace = textureColorSpace;
       }
-      if (glConfig && !is.fun(glConfig) && !isRenderer(glConfig) && !is.equ(glConfig, renderer, shallowLoose))
-        applyProps(renderer, glConfig);
+      const r3fProps = ["textureColorSpace"];
+      const constructorOnlyProps = ["samples", "antialias", "alpha", "canvas", "powerPreference"];
+      const nonApplyProps = [...r3fProps, ...constructorOnlyProps];
+      if (glConfig && !is.fun(glConfig) && !isRenderer(glConfig) && !is.equ(glConfig, renderer, shallowLoose)) {
+        const glProps = {};
+        for (const key in glConfig) {
+          if (!nonApplyProps.includes(key)) glProps[key] = glConfig[key];
+        }
+        applyProps(renderer, glProps);
+      }
       if (rendererConfig && !is.fun(rendererConfig) && !isRenderer(rendererConfig) && state.renderer) {
         const currentRenderer = state.renderer;
         if (!is.equ(rendererConfig, currentRenderer, shallowLoose)) {
-          applyProps(currentRenderer, rendererConfig);
+          const rendererProps = {};
+          for (const key in rendererConfig) {
+            if (!nonApplyProps.includes(key)) rendererProps[key] = rendererConfig[key];
+          }
+          applyProps(currentRenderer, rendererProps);
         }
       }
       const scheduler = getScheduler();
       const rootId = state.internal.rootId;
       if (!rootId) {
-        const newRootId = scheduler.generateRootId();
+        const newRootId = canvasId || scheduler.generateRootId();
         const unregisterRoot = scheduler.registerRoot(newRootId, {
           getState: () => store.getState(),
           onError: (err) => store.getState().setError(err)
         });
+        const unregisterCanvasTarget = scheduler.register(
+          () => {
+            const state2 = store.getState();
+            if (state2.internal.isMultiCanvas && state2.internal.canvasTarget) {
+              const renderer2 = state2.internal.actualRenderer;
+              renderer2.setCanvasTarget(state2.internal.canvasTarget);
+            }
+          },
+          {
+            id: `${newRootId}_canvasTarget`,
+            rootId: newRootId,
+            phase: "start",
+            system: true
+          }
+        );
+        const unregisterEventsFlush = scheduler.register(
+          () => {
+            const state2 = store.getState();
+            state2.events.flush?.();
+          },
+          {
+            id: `${newRootId}_events`,
+            rootId: newRootId,
+            phase: "input",
+            system: true
+          }
+        );
         const unregisterFrustum = scheduler.register(
           () => {
             const state2 = store.getState();
@@ -14783,18 +15503,22 @@ function createRoot(canvas) {
             const userHandlesRender = scheduler.hasUserJobsInPhase("render", newRootId);
             if (userHandlesRender || state2.internal.priority) return;
             try {
-              if (state2.postProcessing?.render) state2.postProcessing.render();
+              if (state2.renderPipeline?.render) state2.renderPipeline.render();
               else if (renderer2?.render) renderer2.render(state2.scene, state2.camera);
             } catch (error) {
               state2.setError(error instanceof Error ? error : new Error(String(error)));
             }
           },
           {
-            id: `${newRootId}_render`,
+            // Use canvas ID directly as job ID if available, otherwise use generated rootId
+            id: canvasId || `${newRootId}_render`,
             rootId: newRootId,
             phase: "render",
-            system: true
+            system: true,
             // Internal flag: this is a system job, not user-controlled
+            // Apply scheduler config for render ordering and rate limiting
+            ...schedulerConfig?.after && { after: schedulerConfig.after },
+            ...schedulerConfig?.fps && { fps: schedulerConfig.fps }
           }
         );
         state.set((state2) => ({
@@ -14803,6 +15527,8 @@ function createRoot(canvas) {
             rootId: newRootId,
             unregisterRoot: () => {
               unregisterRoot();
+              unregisterCanvasTarget();
+              unregisterEventsFlush();
               unregisterFrustum();
               unregisterVisibility();
               unregisterRender();
@@ -14861,15 +15587,24 @@ function unmountComponentAtNode(canvas, callback) {
             const renderer = state.internal.actualRenderer;
             const unregisterRoot = state.internal.unregisterRoot;
             if (unregisterRoot) unregisterRoot();
+            const unregisterPrimary = state.internal.unregisterPrimary;
+            if (unregisterPrimary) unregisterPrimary();
+            const canvasTarget = state.internal.canvasTarget;
+            if (canvasTarget?.dispose) canvasTarget.dispose();
             state.events.disconnect?.();
             cleanupHelperGroup(root.store);
-            renderer?.renderLists?.dispose?.();
-            renderer?.forceContextLoss?.();
-            if (renderer?.xr) state.xr.disconnect();
+            if (state.isLegacy && renderer) {
+              ;
+              renderer.renderLists?.dispose?.();
+              renderer.forceContextLoss?.();
+            }
+            if (!state.internal.isSecondary) {
+              if (renderer?.xr) state.xr.disconnect();
+            }
             dispose(state.scene);
             _roots.delete(canvas);
             if (callback) callback(canvas);
-          } catch (e) {
+          } catch {
           }
         }, 500);
       }
@@ -14877,36 +15612,34 @@ function unmountComponentAtNode(canvas, callback) {
   }
 }
 function createPortal(children, container, state) {
-  return /* @__PURE__ */ jsx(PortalWrapper, { children, container, state });
+  return /* @__PURE__ */ jsx(Portal, { children, container, state });
 }
-function PortalWrapper({ children, container, state }) {
+function Portal({ children, container, state }) {
   const isRef = useCallback((obj) => obj && "current" in obj, []);
-  const [resolvedContainer, setResolvedContainer] = useState(() => {
+  const [resolvedContainer, _setResolvedContainer] = useState(() => {
     if (isRef(container)) return container.current ?? null;
     return container;
   });
+  const setResolvedContainer = useCallback(
+    (newContainer) => {
+      if (!newContainer || newContainer === resolvedContainer) return;
+      _setResolvedContainer(isRef(newContainer) ? newContainer.current : newContainer);
+    },
+    [resolvedContainer, _setResolvedContainer, isRef]
+  );
   useMemo(() => {
-    if (isRef(container)) {
-      const current = container.current;
-      if (!current) {
-        queueMicrotask(() => {
-          const updated = container.current;
-          if (updated && updated !== resolvedContainer) {
-            setResolvedContainer(updated);
-          }
-        });
-      } else if (current !== resolvedContainer) {
-        setResolvedContainer(current);
-      }
-    } else if (container !== resolvedContainer) {
-      setResolvedContainer(container);
+    if (isRef(container) && !container.current) {
+      return queueMicrotask(() => {
+        setResolvedContainer(container.current);
+      });
     }
-  }, [container, resolvedContainer, isRef]);
+    setResolvedContainer(container);
+  }, [container, isRef, setResolvedContainer]);
   if (!resolvedContainer) return /* @__PURE__ */ jsx(Fragment, {});
   const portalKey = resolvedContainer.uuid ?? `portal-${resolvedContainer.id ?? "unknown"}`;
-  return /* @__PURE__ */ jsx(Portal, { children, container: resolvedContainer, state }, portalKey);
+  return /* @__PURE__ */ jsx(PortalInner, { children, container: resolvedContainer, state }, portalKey);
 }
-function Portal({ state = {}, children, container }) {
+function PortalInner({ state = {}, children, container }) {
   const { events, size, injectScene = true, ...rest } = state;
   const previousRoot = useStore();
   const [raycaster] = useState(() => new Raycaster());
@@ -14927,11 +15660,12 @@ function Portal({ state = {}, children, container }) {
     };
   }, [portalScene, container, injectScene]);
   const inject = useMutableCallback((rootState, injectState) => {
+    const resolvedSize = { ...rootState.size, ...injectState.size, ...size };
     let viewport = void 0;
-    if (injectState.camera && size) {
+    if (injectState.camera && (size || injectState.size)) {
       const camera = injectState.camera;
-      viewport = rootState.viewport.getCurrentViewport(camera, new Vector3(), size);
-      if (camera !== rootState.camera) updateCamera(camera, size);
+      viewport = rootState.viewport.getCurrentViewport(camera, new Vector3(), resolvedSize);
+      if (camera !== rootState.camera) updateCamera(camera, resolvedSize);
     }
     return {
       // The intersect consists of the previous root state
@@ -14948,7 +15682,7 @@ function Portal({ state = {}, children, container }) {
       previousRoot,
       // Events, size and viewport can be overridden by the inject layer
       events: { ...rootState.events, ...injectState.events, ...events },
-      size: { ...rootState.size, ...size },
+      size: resolvedSize,
       viewport: { ...rootState.viewport, ...viewport },
       // Layers are allowed to override events
       setEvents: (events2) => injectState.set((state2) => ({ ...state2, events: { ...state2.events, ...events2 } })),
@@ -14960,9 +15694,13 @@ function Portal({ state = {}, children, container }) {
     const store = createWithEqualityFn((set, get) => ({ ...rest, set, get }));
     const onMutate = (prev) => store.setState((state2) => inject.current(prev, state2));
     onMutate(previousRoot.getState());
-    previousRoot.subscribe(onMutate);
     return store;
   }, [previousRoot, container]);
+  useIsomorphicLayoutEffect(() => {
+    const onMutate = (prev) => usePortalStore.setState((state2) => inject.current(prev, state2));
+    const unsubscribe = previousRoot.subscribe(onMutate);
+    return unsubscribe;
+  }, [previousRoot, usePortalStore]);
   return (
     // @ts-ignore, reconciler types are not maintained
     /* @__PURE__ */ jsx(Fragment, { children: reconciler.createPortal(
@@ -14982,15 +15720,13 @@ function CanvasImpl({
   fallback,
   resize,
   style,
+  id,
   gl,
-  renderer,
+  renderer: rendererProp,
   events = createPointerEvents,
   eventSource,
   eventPrefix,
   shadows,
-  linear,
-  flat,
-  legacy,
   orthographic,
   frameloop,
   dpr,
@@ -15002,10 +15738,56 @@ function CanvasImpl({
   onDragOverMissed,
   onDropMissed,
   onCreated,
+  hmr,
+  width,
+  height,
+  background,
+  forceEven,
   ...props
 }) {
+  const isRendererConfig = typeof rendererProp === "object" && rendererProp !== null && !("render" in rendererProp) && ("primaryCanvas" in rendererProp || "scheduler" in rendererProp);
+  let primaryCanvas;
+  let scheduler;
+  let renderer;
+  if (isRendererConfig) {
+    const { primaryCanvas: pc, scheduler: sc, ...rest } = rendererProp;
+    primaryCanvas = pc;
+    scheduler = sc;
+    renderer = Object.keys(rest).length > 0 ? rest : rendererProp;
+  } else {
+    renderer = rendererProp;
+  }
   React.useMemo(() => extend(THREE), []);
   const Bridge = useBridge();
+  const backgroundProps = React.useMemo(() => {
+    if (!background) return null;
+    if (typeof background === "object" && !background.isColor) {
+      const { backgroundMap, envMap, files, preset, ...rest } = background;
+      return {
+        ...rest,
+        preset,
+        files: envMap || files,
+        backgroundFiles: backgroundMap,
+        background: true
+      };
+    }
+    if (typeof background === "number") {
+      return { color: background, background: true };
+    }
+    if (typeof background === "string") {
+      if (background in presetsObj) {
+        return { preset: background, background: true };
+      }
+      if (/^(https?:\/\/|\/|\.\/|\.\.\/)|\\.(hdr|exr|jpg|jpeg|png|webp|gif)$/i.test(background)) {
+        return { files: background, background: true };
+      }
+      return { color: background, background: true };
+    }
+    if (background.isColor) {
+      return { color: background, background: true };
+    }
+    return null;
+  }, [background]);
   const hasInitialSizeRef = React.useRef(false);
   const measureConfig = React.useMemo(() => {
     if (!hasInitialSizeRef.current) {
@@ -15022,7 +15804,21 @@ function CanvasImpl({
     };
   }, [resize, hasInitialSizeRef.current]);
   const [containerRef, containerRect] = useMeasure(measureConfig);
-  if (!hasInitialSizeRef.current && containerRect.width > 0 && containerRect.height > 0) {
+  const effectiveSize = React.useMemo(() => {
+    let w = width ?? containerRect.width;
+    let h = height ?? containerRect.height;
+    if (forceEven) {
+      w = Math.ceil(w / 2) * 2;
+      h = Math.ceil(h / 2) * 2;
+    }
+    return {
+      width: w,
+      height: h,
+      top: containerRect.top,
+      left: containerRect.left
+    };
+  }, [width, height, containerRect, forceEven]);
+  if (!hasInitialSizeRef.current && effectiveSize.width > 0 && effectiveSize.height > 0) {
     hasInitialSizeRef.current = true;
   }
   const canvasRef = React.useRef(null);
@@ -15041,7 +15837,7 @@ function CanvasImpl({
   useIsomorphicLayoutEffect(() => {
     effectActiveRef.current = true;
     const canvas = canvasRef.current;
-    if (containerRect.width > 0 && containerRect.height > 0 && canvas) {
+    if (effectiveSize.width > 0 && effectiveSize.height > 0 && canvas) {
       if (!root.current) {
         root.current = createRoot(canvas);
         notifyAlpha({
@@ -15061,21 +15857,24 @@ function CanvasImpl({
       async function run() {
         if (!effectActiveRef.current || !root.current) return;
         await root.current.configure({
+          id,
+          primaryCanvas,
+          scheduler,
           gl,
           renderer,
           scene,
           events,
           shadows,
-          linear,
-          flat,
-          legacy,
           orthographic,
           frameloop,
           dpr,
           performance,
           raycaster,
           camera,
-          size: containerRect,
+          size: effectiveSize,
+          // Store size props for reset functionality
+          _sizeProps: width !== void 0 || height !== void 0 ? { width, height } : null,
+          forceEven,
           // Pass mutable reference to onPointerMissed so it's free to update
           onPointerMissed: (...args) => handlePointerMissed.current?.(...args),
           onDragOverMissed: (...args) => handleDragOverMissed.current?.(...args),
@@ -15099,7 +15898,10 @@ function CanvasImpl({
         });
         if (!effectActiveRef.current || !root.current) return;
         root.current.render(
-          /* @__PURE__ */ jsx(Bridge, { children: /* @__PURE__ */ jsx(ErrorBoundary, { set: setError, children: /* @__PURE__ */ jsx(React.Suspense, { fallback: /* @__PURE__ */ jsx(Block, { set: setBlock }), children: children ?? null }) }) })
+          /* @__PURE__ */ jsx(Bridge, { children: /* @__PURE__ */ jsx(ErrorBoundary, { set: setError, children: /* @__PURE__ */ jsxs(React.Suspense, { fallback: /* @__PURE__ */ jsx(Block, { set: setBlock }), children: [
+            backgroundProps && /* @__PURE__ */ jsx(Environment, { ...backgroundProps }),
+            children ?? null
+          ] }) }) })
         );
       }
       run();
@@ -15121,6 +15923,35 @@ function CanvasImpl({
       };
     }
   }, []);
+  React.useEffect(() => {
+    if (hmr === false) return;
+    const canvas = canvasRef.current;
+    if (!canvas) return;
+    const handleHMR = () => {
+      queueMicrotask(() => {
+        const rootEntry = _roots.get(canvas);
+        if (rootEntry?.store) {
+          console.log("[R3F] HMR detected \u2014 rebuilding nodes/uniforms");
+          rootEntry.store.setState((state) => ({
+            nodes: {},
+            uniforms: {},
+            _hmrVersion: state._hmrVersion + 1
+          }));
+        }
+      });
+    };
+    if (typeof import.meta !== "undefined" && import.meta.hot) {
+      const hot = import.meta.hot;
+      hot.on("vite:afterUpdate", handleHMR);
+      return () => hot.off?.("vite:afterUpdate", handleHMR);
+    }
+    if (typeof module !== "undefined" && module.hot) {
+      const hot = module.hot;
+      hot.addStatusHandler((status) => {
+        if (status === "idle") handleHMR();
+      });
+    }
+  }, [hmr]);
   const pointerEvents = eventSource ? "none" : "auto";
   return /* @__PURE__ */ jsx(
     "div",
@@ -15135,7 +15966,16 @@ function CanvasImpl({
         ...style
       },
       ...props,
-      children: /* @__PURE__ */ jsx("div", { ref: containerRef, className: "r3f-canvas-container", style: { width: "100%", height: "100%" }, children: /* @__PURE__ */ jsx("canvas", { ref: canvasRef, className: "r3f-canvas", style: { display: "block" }, children: fallback }) })
+      children: /* @__PURE__ */ jsx("div", { ref: containerRef, className: "r3f-canvas-container", style: { width: "100%", height: "100%" }, children: /* @__PURE__ */ jsx(
+        "canvas",
+        {
+          ref: canvasRef,
+          id,
+          className: "r3f-canvas",
+          style: { display: "block", width: "100%", height: "100%" },
+          children: fallback
+        }
+      ) })
     }
   );
 }
@@ -15145,4 +15985,4 @@ function Canvas(props) {
 
 extend(THREE);
 
-export { Block, Canvas, ErrorBoundary, IsObject, R3F_BUILD_LEGACY, R3F_BUILD_WEBGPU, REACT_INTERNAL_PROPS, RESERVED_PROPS, Scheduler, Texture, _roots, act, addAfterEffect, addEffect, addTail, advance, applyProps, attach, buildGraph, calculateDpr, context, createEvents, createPointerEvents, createPortal, createRoot, createStore, detach, diffProps, dispose, createPointerEvents as events, extend, findInitialRoot, flushSync, getInstanceProps, getRootState, getScheduler, getUuidPrefix, hasConstructor, invalidate, invalidateInstance, is, isColorRepresentation, isCopyable, isObject3D, isOrthographicCamera, isRef, isRenderer, isTexture, isVectorLike, prepare, reconciler, removeInteractivity, resolve, unmountComponentAtNode, updateCamera, updateFrustum, useBridge, useFrame, useGraph, useInstanceHandle, useIsomorphicLayoutEffect, useLoader, useMutableCallback, useRenderTarget, useStore, useTexture, useTextures, useThree };
+export { Block, Canvas, Environment, EnvironmentCube, EnvironmentMap, EnvironmentPortal, ErrorBoundary, FROM_REF, IsObject, ONCE, Portal, R3F_BUILD_LEGACY, R3F_BUILD_WEBGPU, REACT_INTERNAL_PROPS, RESERVED_PROPS, Scheduler, Texture, _roots, act, addAfterEffect, addEffect, addTail, advance, applyProps, attach, buildGraph, calculateDpr, context, createEvents, createPointerEvents, createPortal, createRoot, createStore, detach, diffProps, dispose, createPointerEvents as events, extend, findInitialRoot, flushSync, fromRef, getInstanceProps, getPrimary, getPrimaryIds, getRootState, getScheduler, getUuidPrefix, hasConstructor, hasPrimary, invalidate, invalidateInstance, is, isColorRepresentation, isCopyable, isFromRef, isObject3D, isOnce, isOrthographicCamera, isRef, isRenderer, isTexture, isVectorLike, once, prepare, presetsObj, reconciler, registerPrimary, removeInteractivity, resolve, unmountComponentAtNode, unregisterPrimary, updateCamera, updateFrustum, useBridge, useEnvironment, useFrame, useGraph, useInstanceHandle, useIsomorphicLayoutEffect, useLoader, useMutableCallback, useRenderTarget, useStore, useTexture, useTextures, useThree, waitForPrimary };