@react-three/fiber 10.0.0-alpha.2 → 10.0.0-canary.0706a92

package/dist/index.cjs

@@ -7,8 +7,15 @@ const jsxRuntime = require('react/jsx-runtime');
 const React = require('react');
 const useMeasure = require('react-use-measure');
 const itsFine = require('its-fine');
+const fiber = require('@react-three/fiber');
+const GroundedSkybox_js = require('three/examples/jsm/objects/GroundedSkybox.js');
+const HDRLoader_js = require('three/examples/jsm/loaders/HDRLoader.js');
+const EXRLoader_js = require('three/examples/jsm/loaders/EXRLoader.js');
+const UltraHDRLoader_js = require('three/examples/jsm/loaders/UltraHDRLoader.js');
+const gainmapJs = require('@monogrid/gainmap-js');
 const Tb = require('scheduler');
 const traditional = require('zustand/traditional');
+const scheduler = require('@pmndrs/scheduler');
 const suspendReact = require('suspend-react');
 
 var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
@@ -57,9 +64,392 @@ const THREE = /*#__PURE__*/_mergeNamespaces({
   WebGLRenderer: three.WebGLRenderer
 }, [webgpu__namespace]);
 
-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);
+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 = fiber.useThree((state) => state.renderer);
+  React.useLayoutEffect(() => {
+    if (extension !== "webp" && extension !== "jpg" && extension !== "jpeg") return;
+    function clearGainmapTexture() {
+      fiber.useLoader.clear(loader, multiFile ? [files] : files);
+    }
+    renderer.domElement.addEventListener("webglcontextlost", clearGainmapTexture, { once: true });
+  }, [extension, files, loader, multiFile, renderer.domElement]);
+  const loaderResult = fiber.useLoader(
+    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 ? webgpu.CubeReflectionMapping : webgpu.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);
+  fiber.useLoader.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);
+  fiber.useLoader.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" ? webgpu.CubeTextureLoader : extension === "hdr" ? HDRLoader_js.HDRLoader : extension === "exr" ? EXRLoader_js.EXRLoader : extension === "jpg" || extension === "jpeg" ? UltraHDRLoader_js.UltraHDRLoader : extension === "webp" ? gainmapJs.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;
+  fiber.applyProps(target, sceneProps);
+  return () => {
+    if (background !== "only") target.environment = oldenv;
+    if (background) target.background = oldbg;
+    fiber.applyProps(target, oldSceneProps);
+  };
+}
+function EnvironmentMap({ scene, background = false, map, ...config }) {
+  const defaultScene = fiber.useThree((state) => state.scene);
+  React__namespace.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 = fiber.useThree((state) => state.scene);
+  React__namespace.useLayoutEffect(() => {
+    return setEnvProps(background, scene, defaultScene, texture, {
+      backgroundBlurriness: blur ?? backgroundBlurriness,
+      backgroundIntensity,
+      backgroundRotation,
+      environmentIntensity,
+      environmentRotation
+    });
+  });
+  React__namespace.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 = fiber.useThree((state) => state.gl);
+  const defaultScene = fiber.useThree((state) => state.scene);
+  const camera = React__namespace.useRef(null);
+  const [virtualScene] = React__namespace.useState(() => new webgpu.Scene());
+  const fbo = React__namespace.useMemo(() => {
+    const fbo2 = new webgpu.WebGLCubeRenderTarget(resolution);
+    fbo2.texture.type = webgpu.HalfFloatType;
+    return fbo2;
+  }, [resolution]);
+  React__namespace.useEffect(() => {
+    return () => {
+      fbo.dispose();
+    };
+  }, [fbo]);
+  React__namespace.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;
+  fiber.useFrame(() => {
+    if (frames === Infinity || count < frames) {
+      const autoClear = gl.autoClear;
+      gl.autoClear = true;
+      camera.current.update(gl, virtualScene);
+      gl.autoClear = autoClear;
+      count++;
+    }
+  });
+  return /* @__PURE__ */ jsxRuntime.jsx(jsxRuntime.Fragment, { children: fiber.createPortal(
+    /* @__PURE__ */ jsxRuntime.jsxs(jsxRuntime.Fragment, { children: [
+      children,
+      /* @__PURE__ */ jsxRuntime.jsx("cubeCamera", { ref: camera, args: [near, far, fbo] }),
+      files || preset ? /* @__PURE__ */ jsxRuntime.jsx(EnvironmentCube, { background: true, files, preset, path, extensions }) : map ? /* @__PURE__ */ jsxRuntime.jsx(EnvironmentMap, { background: true, map, extensions }) : null
+    ] }),
+    virtualScene
+  ) });
+}
+function EnvironmentGround(props) {
+  const textureDefault = useEnvironment(props);
+  const texture = props.map || textureDefault;
+  React__namespace.useMemo(() => fiber.extend({ GroundProjectedEnvImpl: GroundedSkybox_js.GroundedSkybox }), []);
+  React__namespace.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__namespace.useMemo(
+    () => [texture, height, radius],
+    [texture, height, radius]
+  );
+  return /* @__PURE__ */ jsxRuntime.jsxs(jsxRuntime.Fragment, { children: [
+    /* @__PURE__ */ jsxRuntime.jsx(EnvironmentMap, { ...props, map: texture }),
+    /* @__PURE__ */ jsxRuntime.jsx("groundProjectedEnvImpl", { args, scale })
+  ] });
+}
+function EnvironmentColor({ color, scene }) {
+  const defaultScene = fiber.useThree((state) => state.scene);
+  React__namespace.useLayoutEffect(() => {
+    if (color === void 0) return;
+    const target = resolveScene(scene || defaultScene);
+    const oldBg = target.background;
+    target.background = new webgpu.Color(color);
+    return () => {
+      target.background = oldBg;
+    };
+  });
+  return null;
+}
+function EnvironmentDualSource(props) {
+  const { backgroundFiles, ...envProps } = props;
+  return /* @__PURE__ */ jsxRuntime.jsxs(jsxRuntime.Fragment, { children: [
+    /* @__PURE__ */ jsxRuntime.jsx(EnvironmentCube, { ...envProps, background: false }),
+    /* @__PURE__ */ jsxRuntime.jsx(EnvironmentCube, { ...props, files: backgroundFiles, background: "only" })
+  ] });
+}
+function Environment(props) {
+  if (props.color && !props.files && !props.preset && !props.map) {
+    return /* @__PURE__ */ jsxRuntime.jsx(EnvironmentColor, { ...props });
+  }
+  if (props.backgroundFiles && props.backgroundFiles !== props.files) {
+    return /* @__PURE__ */ jsxRuntime.jsx(EnvironmentDualSource, { ...props });
+  }
+  return props.ground ? /* @__PURE__ */ jsxRuntime.jsx(EnvironmentGround, { ...props }) : props.map ? /* @__PURE__ */ jsxRuntime.jsx(EnvironmentMap, { ...props }) : props.children ? /* @__PURE__ */ jsxRuntime.jsx(EnvironmentPortal, { ...props }) : /* @__PURE__ */ jsxRuntime.jsx(EnvironmentCube, { ...props });
+}
+
+var __defProp = Object.defineProperty;
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
 const act = React__namespace["act"];
 const useIsomorphicLayoutEffect = /* @__PURE__ */ (() => typeof window !== "undefined" && (window.document?.createElement || window.navigator?.product === "ReactNative"))() ? React__namespace.useLayoutEffect : React__namespace.useEffect;
 function useMutableCallback(fn) {
@@ -91,7 +481,7 @@ const ErrorBoundary = /* @__PURE__ */ (() => {
   return _a = class extends React__namespace.Component {
     constructor() {
       super(...arguments);
-      __publicField$2(this, "state", { error: false });
+      __publicField(this, "state", { error: false });
     }
     componentDidCatch(err) {
       this.props.set(err);
@@ -99,7 +489,7 @@ const ErrorBoundary = /* @__PURE__ */ (() => {
     render() {
       return this.state.error ? null : this.props.children;
     }
-  }, __publicField$2(_a, "getDerivedStateFromError", () => ({ error: true })), _a;
+  }, __publicField(_a, "getDerivedStateFromError", () => ({ error: true })), _a;
 })();
 
 const is = {
@@ -285,7 +675,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) {
@@ -393,6 +783,17 @@ function unregisterVisibility(store, object) {
   internal.visibilityRegistry.delete(object.uuid);
   internal.occlusionCache.delete(object);
 }
+function updateVisibilityHandlers(store, object, handlers) {
+  const { internal } = store.getState();
+  const entry = internal.visibilityRegistry.get(object.uuid);
+  if (!entry) return false;
+  entry.handlers = handlers;
+  if ((handlers.onOccluded || handlers.onVisible) && !internal.occlusionEnabled) {
+    object.occlusionTest = true;
+    enableOcclusion(store);
+  }
+  return true;
+}
 function checkVisibility(state) {
   const { internal, camera } = state;
   const registry = internal.visibilityRegistry;
@@ -448,6 +849,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",
@@ -518,7 +935,7 @@ function getMemoizedPrototype(root) {
       ctor = new root.constructor();
       MEMOIZED_PROTOTYPES.set(root.constructor, ctor);
     }
-  } catch (e) {
+  } catch {
   }
   return ctor;
 }
@@ -564,6 +981,22 @@ function applyProps(object, props) {
       continue;
     }
     if (value === void 0) continue;
+    if (isFromRef(value)) 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}".`);
@@ -584,9 +1017,25 @@ function applyProps(object, props) {
     } else if (isVectorLike(target) && is.num(value)) {
       if ("setScalar" in target && typeof target.setScalar === "function") target.setScalar(value);
       else target.set(value);
+    } else if (root instanceof webgpu.ShaderMaterial && key === "uniforms" && is.obj(value)) {
+      if (!is.obj(root.uniforms)) root.uniforms = {};
+      const uniforms = root.uniforms;
+      const nextUniforms = value;
+      for (const name in nextUniforms) {
+        const uniform = nextUniforms[name];
+        const targetUniform = uniforms[name];
+        if (targetUniform) Object.assign(targetUniform, uniform);
+        else {
+          const nextUniform = uniform instanceof webgpu.Uniform ? uniform.clone() : new webgpu.Uniform(uniform.value);
+          uniforms[name] = nextUniform;
+        }
+      }
     } 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 === webgpu.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 === webgpu.RGBAFormat && root[key].type === webgpu.UnsignedByteType) {
         root[key].colorSpace = rootState.textureColorSpace;
       }
@@ -599,6 +1048,9 @@ function applyProps(object, props) {
     if (instance.eventCount && object2.raycast !== null) {
       rootState.internal.interaction.push(object2);
     }
+  }
+  if (instance?.parent && rootState?.internal && instance.object?.isObject3D) {
+    const object2 = instance.object;
     const root = findInitialRoot(instance);
     const visibilityHandlers = {
       onFramed: instance.handlers.onFramed,
@@ -606,7 +1058,9 @@ function applyProps(object, props) {
       onVisible: instance.handlers.onVisible
     };
     if (hasVisibilityHandlers(visibilityHandlers)) {
-      registerVisibility(root, object2, visibilityHandlers);
+      if (!updateVisibilityHandlers(root, object2, visibilityHandlers)) {
+        registerVisibility(root, object2, visibilityHandlers);
+      }
     } else {
       unregisterVisibility(root, object2);
     }
@@ -619,38 +1073,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) {
@@ -686,6 +1162,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;
@@ -707,9 +1192,13 @@ function createEvents(store) {
         eventObject = eventObject.parent;
       }
     }
-    if ("pointerId" in event && state.internal.capturedMap.has(event.pointerId)) {
-      for (const 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;
@@ -722,27 +1211,25 @@ function createEvents(store) {
         if (state) {
           const { raycaster, pointer, camera, internal } = state;
           const unprojectedPoint = new webgpu.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);
           };
           const extractEventProps = {};
           for (const prop in event) {
             const property = event[prop];
             if (typeof property !== "function") extractEventProps[prop] = property;
           }
+          const eventPointerId = "pointerId" in event ? event.pointerId : void 0;
           const raycastEvent = {
             ...hit,
             ...extractEventProps,
@@ -753,18 +1240,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);
                 }
               }
             },
@@ -780,15 +1268,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 };
@@ -817,41 +1308,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);
@@ -866,7 +1434,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;
@@ -875,9 +1445,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) {
@@ -887,9 +1458,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();
@@ -900,18 +1472,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))
               );
             }
           }
@@ -920,7 +1492,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],
@@ -939,11 +1519,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);
     },
@@ -952,11 +1537,33 @@ function createPointerEvents(store) {
       (acc, key) => ({ ...acc, [key]: handlePointer(key) }),
       {}
     ),
-    update: () => {
+    update: (pointerId) => {
       const { events, internal } = store.getState();
-      if (internal.lastEvent?.current && events.handlers) events.handlers.onPointerMove(internal.lastEvent.current);
+      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();
+      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 } }));
@@ -980,6 +1587,33 @@ function createPointerEvents(store) {
         }
         set((state) => ({ events: { ...state.events, connected: void 0 } }));
       }
+    },
+    // PREVIEW (A8): the XR pointer registration API may change before stable.
+    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);
     }
   };
 }
@@ -1041,6 +1675,14 @@ function notifyAlpha({ message, link }) {
   }
 }
 
+const INTERNAL_LIB_MARKERS = ["zustand", "setState", "Object.assign"];
+const INTERNAL_FIBER_MARKERS = ["packages/fiber/src", "packages/fiber/dist", "@react-three/fiber", "@react-three_fiber"];
+function isInternalRendererAccess(stack, callerDepth = 2) {
+  if (!stack) return false;
+  const caller = stack.split("\n")[callerDepth] ?? "";
+  return INTERNAL_LIB_MARKERS.some((m) => caller.includes(m)) || INTERNAL_FIBER_MARKERS.some((m) => caller.includes(m));
+}
+
 const R3F_CONTEXT = Symbol.for("@react-three/fiber.context");
 const context = globalThis[R3F_CONTEXT] ?? (globalThis[R3F_CONTEXT] = React__namespace.createContext(null));
 const createStore = (invalidate, advance) => {
@@ -1070,23 +1712,29 @@ const createStore = (invalidate, advance) => {
       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 webgpu.Frustum(),
       autoUpdateFrustum: true,
       raycaster: null,
-      events: { priority: 1, enabled: true, connected: false },
+      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()),
-      legacy: false,
-      linear: false,
-      flat: false,
-      textureColorSpace: "srgb",
+      textureColorSpace: webgpu.SRGBColorSpace,
       isLegacy: false,
       webGPUSupported: false,
       isNative: false,
@@ -1144,6 +1792,7 @@ const createStore = (invalidate, advance) => {
                 size: newSize,
                 viewport: { ...s.viewport, ...getCurrentViewport(state2.camera, defaultTarget, newSize) }
               }));
+              scheduler.getScheduler().invalidate();
             }
           }
           return;
@@ -1158,6 +1807,7 @@ const createStore = (invalidate, advance) => {
           viewport: { ...s.viewport, ...getCurrentViewport(state2.camera, defaultTarget, size) },
           _sizeImperative: true
         }));
+        scheduler.getScheduler().invalidate();
       },
       setDpr: (dpr) => set((state2) => {
         const resolved = calculateDpr(dpr);
@@ -1165,14 +1815,18 @@ const createStore = (invalidate, advance) => {
       }),
       setFrameloop: (frameloop = "always") => {
         set(() => ({ frameloop }));
+        scheduler.getScheduler().frameloop = frameloop;
       },
       setError: (error) => set(() => ({ error })),
       error: null,
-      //* TSL State (managed via hooks: useUniforms, useNodes, useTextures, usePostProcessing) ==============================
+      //* TSL State (managed via hooks: useUniforms, useNodes, useBuffers, useGPUStorage, useTextures, useRenderPipeline) ==============================
       uniforms: {},
       nodes: {},
+      buffers: {},
+      gpuStorage: {},
       textures: /* @__PURE__ */ new Map(),
-      postProcessing: null,
+      _textureRefs: /* @__PURE__ */ new Map(),
+      renderPipeline: null,
       passes: {},
       _hmrVersion: 0,
       _sizeImperative: false,
@@ -1181,12 +1835,16 @@ const createStore = (invalidate, advance) => {
       internal: {
         // Events
         interaction: [],
-        hovered: /* @__PURE__ */ new Map(),
         subscribers: [],
+        // Per-pointer state (new unified structure)
+        pointerMap: /* @__PURE__ */ new Map(),
+        pointerDirty: /* @__PURE__ */ new Map(),
+        lastEvent: React__namespace.createRef(),
+        // Deprecated but kept for backwards compatibility
+        hovered: /* @__PURE__ */ new Map(),
         initialClick: [0, 0],
         initialHits: [],
         capturedMap: /* @__PURE__ */ new Map(),
-        lastEvent: React__namespace.createRef(),
         // Visibility tracking (onFramed, onOccluded, onVisible)
         visibilityRegistry: /* @__PURE__ */ new Map(),
         // Occlusion system (WebGPU only)
@@ -1225,8 +1883,7 @@ const createStore = (invalidate, advance) => {
       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) {
+        if (!isInternalRendererAccess(stack)) {
           const cleanedStack = stack.split("\n").slice(2).join("\n") || "Stack trace unavailable";
           notifyDepreciated({
             heading: "Accessing state.gl in WebGPU mode",
@@ -1269,13 +1926,22 @@ const createStore = (invalidate, advance) => {
   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 (viewport.dpr > 0) actualRenderer.setPixelRatio(viewport.dpr);
-      const updateStyle = typeof HTMLCanvasElement !== "undefined" && actualRenderer.domElement instanceof HTMLCanvasElement;
-      actualRenderer.setSize(size.width, size.height, updateStyle);
+      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;
@@ -1330,1058 +1996,32 @@ function loadingFn(extensions, onProgress) {
     );
   };
 }
-function useLoader(loader, input, extensions, onProgress) {
-  const keys = Array.isArray(input) ? input : [input];
+function useLoader(loader, input, extensions, onProgress, cacheKey) {
+  const inputs = Array.isArray(input) ? input : [input];
+  const cacheKeys = Array.isArray(cacheKey ?? input) ? cacheKey ?? input : [cacheKey ?? input];
   const fn = loadingFn(extensions, onProgress);
-  const results = keys.map((key) => suspendReact.suspend(fn, [loader, key], { equal: is.equ }));
+  const results = cacheKeys.map(
+    (key, index) => suspendReact.suspend(() => fn(loader, inputs[index]), [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) => suspendReact.preload(loadingFn(extensions, onProgress), [loader, key]));
+useLoader.preload = function(loader, input, extensions, onProgress, cacheKey) {
+  const inputs = Array.isArray(input) ? input : [input];
+  const cacheKeys = Array.isArray(cacheKey ?? input) ? cacheKey ?? input : [cacheKey ?? input];
+  cacheKeys.forEach(
+    (key, index) => suspendReact.preload(() => loadingFn(extensions, onProgress)(loader, inputs[index]), [loader, key])
+  );
 };
-useLoader.clear = function(loader, input) {
-  const keys = Array.isArray(input) ? input : [input];
-  keys.forEach((key) => suspendReact.clear([loader, key]));
+useLoader.clear = function(loader, input, cacheKey) {
+  const cacheKeys = Array.isArray(cacheKey ?? input) ? cacheKey ?? input : [cacheKey ?? input];
+  cacheKeys.forEach((key) => suspendReact.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);
-    }
-    this.invalidateCache();
-  }
-  //* Public API --------------------------------
-  /**
-   * Add a named phase to the graph
-   * @param name - Phase name (must be unique)
-   * @param options - Position options (before or after another phase)
-   */
-  addPhase(name, options = {}) {
-    if (this.phaseMap.has(name)) {
-      console.warn(`[useFrame] Phase "${name}" already exists`);
-      return;
-    }
-    const { before, after } = options;
-    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 {
-      const constraintType = before ? "before" : "after";
-      console.warn(`[useFrame] Phase "${before ?? after}" not found for '${constraintType}' constraint`);
-    }
-    this.phases.splice(insertIndex, 0, node);
-    this.phaseMap.set(name, node);
-    this.invalidateCache();
-  }
-  /**
-   * Get ordered list of phase names
-   */
-  getOrderedPhases() {
-    if (this.orderedNamesCache === null) this.orderedNamesCache = this.phases.map((p) => p.name);
-    return this.orderedNamesCache;
-  }
-  /**
-   * Check if a phase exists
-   */
-  hasPhase(name) {
-    return this.phaseMap.has(name);
-  }
-  /**
-   * Get the index of a phase (-1 if not found)
-   */
-  getPhaseIndex(name) {
-    if (!name) return -1;
-    return this.phases.findIndex((p) => p.name === name);
-  }
-  /**
-   * Ensure a phase exists, creating an auto-generated one if needed.
-   * Used for resolving before/after constraints.
-   *
-   * @param name - The phase name to ensure exists
-   * @returns The phase name (may be auto-generated like 'before:render')
-   */
-  ensurePhase(name) {
-    if (this.phaseMap.has(name)) return name;
-    const node = { name, isAutoGenerated: true };
-    this.phases.push(node);
-    this.phaseMap.set(name, node);
-    this.invalidateCache();
-    return name;
-  }
-  /**
-   * Resolve where a job with before/after constraints should go.
-   * Creates auto-generated phases if needed.
-   *
-   * @param before - Phase(s) to run before
-   * @param after - Phase(s) to run after
-   * @returns The resolved phase name
-   */
-  resolveConstraintPhase(before, after) {
-    const beforeArr = before ? Array.isArray(before) ? before : [before] : [];
-    const afterArr = after ? Array.isArray(after) ? after : [after] : [];
-    if (beforeArr.length > 0) {
-      return this.ensureAutoPhase(beforeArr[0], "before", 0);
-    }
-    if (afterArr.length > 0) {
-      return this.ensureAutoPhase(afterArr[0], "after", 1);
-    }
-    return "update";
-  }
-  /**
-   * Ensure an auto-generated phase exists relative to a target phase.
-   * Creates the phase if it doesn't exist, inserting it at the correct position.
-   *
-   * @param target - The target phase name to position relative to
-   * @param prefix - Prefix for auto-generated phase name ('before' or 'after')
-   * @param offset - Insertion offset (0 for before, 1 for after)
-   * @returns The auto-generated phase name
-   */
-  ensureAutoPhase(target, prefix, offset) {
-    const autoName = `${prefix}:${target}`;
-    if (this.phaseMap.has(autoName)) return autoName;
-    const node = { name: autoName, isAutoGenerated: true };
-    const targetIndex = this.getPhaseIndex(target);
-    if (targetIndex !== -1) this.phases.splice(targetIndex + offset, 0, node);
-    else this.phases.push(node);
-    this.phaseMap.set(autoName, node);
-    this.invalidateCache();
-    return autoName;
-  }
-  // Internal --------------------------------
-  invalidateCache() {
-    this.orderedNamesCache = null;
-  }
-}
-
-function rebuildSortedJobs(jobs, phaseGraph) {
-  const orderedPhases = phaseGraph.getOrderedPhases();
-  const buckets = /* @__PURE__ */ new Map();
-  for (const phase of orderedPhases) {
-    buckets.set(phase, []);
-  }
-  for (const job of jobs.values()) {
-    if (!job.enabled) continue;
-    let bucket = buckets.get(job.phase);
-    if (!bucket) {
-      bucket = [];
-      buckets.set(job.phase, bucket);
-    }
-    bucket.push(job);
-  }
-  const sortedBuckets = [];
-  for (const phase of orderedPhases) {
-    const bucket = buckets.get(phase);
-    if (!bucket || bucket.length === 0) continue;
-    bucket.sort((a, b) => {
-      if (a.priority !== b.priority) return b.priority - a.priority;
-      return a.index - b.index;
-    });
-    sortedBuckets.push(hasCrossJobConstraints(bucket) ? topologicalSort(bucket) : bucket);
-  }
-  for (const [phase, bucket] of buckets) {
-    if (!orderedPhases.includes(phase) && bucket.length > 0) {
-      bucket.sort((a, b) => {
-        if (a.priority !== b.priority) return b.priority - a.priority;
-        return a.index - b.index;
-      });
-      sortedBuckets.push(bucket);
-    }
-  }
-  return sortedBuckets.flat();
-}
-function hasCrossJobConstraints(bucket) {
-  const jobIds = new Set(bucket.map((j) => j.id));
-  for (const job of bucket) {
-    for (const ref of job.before) {
-      if (jobIds.has(ref)) return true;
-    }
-    for (const ref of job.after) {
-      if (jobIds.has(ref)) return true;
-    }
-  }
-  return false;
-}
-function topologicalSort(jobs) {
-  const n = jobs.length;
-  if (n <= 1) return jobs;
-  const jobMap = /* @__PURE__ */ new Map();
-  const inDegree = /* @__PURE__ */ new Map();
-  const adjacency = /* @__PURE__ */ new Map();
-  for (const job of jobs) {
-    jobMap.set(job.id, job);
-    inDegree.set(job.id, 0);
-    adjacency.set(job.id, []);
-  }
-  for (const job of jobs) {
-    for (const ref of job.before) {
-      if (jobMap.has(ref)) {
-        adjacency.get(job.id).push(ref);
-        inDegree.set(ref, inDegree.get(ref) + 1);
-      }
-    }
-    for (const ref of job.after) {
-      if (jobMap.has(ref)) {
-        adjacency.get(ref).push(job.id);
-        inDegree.set(job.id, inDegree.get(job.id) + 1);
-      }
-    }
-  }
-  const queue = [];
-  for (const job of jobs) {
-    if (inDegree.get(job.id) === 0) {
-      queue.push(job);
-    }
-  }
-  queue.sort((a, b) => {
-    if (a.priority !== b.priority) return b.priority - a.priority;
-    return a.index - b.index;
-  });
-  const result = [];
-  while (queue.length > 0) {
-    const job = queue.shift();
-    result.push(job);
-    const neighbors = adjacency.get(job.id) || [];
-    for (const neighborId of neighbors) {
-      const newDegree = inDegree.get(neighborId) - 1;
-      inDegree.set(neighborId, newDegree);
-      if (newDegree === 0) {
-        const neighbor = jobMap.get(neighborId);
-        insertSorted(queue, neighbor);
-      }
-    }
-  }
-  if (result.length !== n) {
-    console.warn("[useFrame] Circular dependency detected in job constraints");
-    const resultIds = new Set(result.map((j) => j.id));
-    for (const job of jobs) {
-      if (!resultIds.has(job.id)) result.push(job);
-    }
-  }
-  return result;
-}
-function insertSorted(arr, job) {
-  let i = 0;
-  while (i < arr.length) {
-    const cmp = arr[i];
-    if (job.priority > cmp.priority || job.priority === cmp.priority && job.index < cmp.index) {
-      break;
-    }
-    i++;
-  }
-  arr.splice(i, 0, job);
-}
-
-function shouldRun(job, now) {
-  if (!job.enabled) return false;
-  if (!job.fps) return true;
-  const minInterval = 1e3 / job.fps;
-  const lastRun = job.lastRun ?? 0;
-  const elapsed = now - lastRun;
-  if (elapsed < minInterval) return false;
-  if (job.drop) {
-    job.lastRun = now;
-  } else {
-    const steps = Math.floor(elapsed / minInterval);
-    job.lastRun = lastRun + steps * minInterval;
-    if (job.lastRun < now - minInterval) {
-      job.lastRun = now;
-    }
-  }
-  return true;
-}
-function resetJobTiming(job) {
-  job.lastRun = void 0;
-}
-
-var __defProp = Object.defineProperty;
-var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
-var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
-const hmrData = (() => {
-  if (typeof process !== "undefined" && process.env.NODE_ENV === "test") return void 0;
-  if (typeof import_meta_hot !== "undefined") return import_meta_hot;
-  try {
-    return (0, eval)("import.meta.hot");
-  } catch {
-    return void 0;
-  }
-})();
-const _Scheduler = class _Scheduler {
-  //* Constructor ================================
-  constructor() {
-    //* Critical State ================================
-    __publicField(this, "roots", /* @__PURE__ */ new Map());
-    __publicField(this, "phaseGraph");
-    __publicField(this, "loopState", {
-      running: false,
-      rafHandle: null,
-      lastTime: null,
-      // null = uninitialized, 0+ = valid timestamp
-      frameCount: 0,
-      elapsedTime: 0,
-      createdAt: performance.now()
-    });
-    __publicField(this, "stoppedTime", 0);
-    //* Private State ================================
-    __publicField(this, "nextRootIndex", 0);
-    __publicField(this, "globalBeforeJobs", /* @__PURE__ */ new Map());
-    __publicField(this, "globalAfterJobs", /* @__PURE__ */ new Map());
-    __publicField(this, "nextGlobalIndex", 0);
-    __publicField(this, "idleCallbacks", /* @__PURE__ */ new Set());
-    __publicField(this, "nextJobIndex", 0);
-    __publicField(this, "jobStateListeners", /* @__PURE__ */ new Map());
-    __publicField(this, "pendingFrames", 0);
-    __publicField(this, "_frameloop", "always");
-    //* Independent Mode & Error Handling State ================================
-    __publicField(this, "_independent", false);
-    __publicField(this, "errorHandler", null);
-    __publicField(this, "rootReadyCallbacks", /* @__PURE__ */ new Set());
-    //* Core Loop Execution Methods ================================
-    /**
-     * Main RAF loop callback.
-     * Executes frame, handles demand mode, and schedules next frame.
-     * @param {number} timestamp - RAF timestamp in milliseconds
-     * @returns {void}
-     * @private
-     */
-    __publicField(this, "loop", (timestamp) => {
-      if (!this.loopState.running) return;
-      this.executeFrame(timestamp);
-      if (this._frameloop === "demand") {
-        this.pendingFrames = Math.max(0, this.pendingFrames - 1);
-        if (this.pendingFrames === 0) {
-          this.notifyIdle(timestamp);
-          return this.stop();
-        }
-      }
-      this.loopState.rafHandle = requestAnimationFrame(this.loop);
-    });
-    this.phaseGraph = new PhaseGraph();
-  }
-  static get instance() {
-    return globalThis[_Scheduler.INSTANCE_KEY] ?? null;
-  }
-  static set instance(value) {
-    globalThis[_Scheduler.INSTANCE_KEY] = value;
-  }
-  /**
-   * Get the global scheduler instance (creates if doesn't exist).
-   * Uses HMR data to preserve instance across hot reloads.
-   * @returns {Scheduler} The singleton scheduler instance
-   */
-  static get() {
-    if (!_Scheduler.instance && hmrData?.data?.scheduler) {
-      _Scheduler.instance = hmrData.data.scheduler;
-    }
-    if (!_Scheduler.instance) {
-      _Scheduler.instance = new _Scheduler();
-      if (hmrData?.data) {
-        hmrData.data.scheduler = _Scheduler.instance;
-      }
-    }
-    return _Scheduler.instance;
-  }
-  /**
-   * Reset the singleton instance. Stops the loop and clears all state.
-   * Primarily used for testing to ensure clean state between tests.
-   * @returns {void}
-   */
-  static reset() {
-    if (_Scheduler.instance) {
-      _Scheduler.instance.stop();
-      _Scheduler.instance = null;
-    }
-    if (hmrData?.data) {
-      hmrData.data.scheduler = null;
-    }
-  }
-  //* Getters & Setters ================================
-  get phases() {
-    return this.phaseGraph.getOrderedPhases();
-  }
-  get frameloop() {
-    return this._frameloop;
-  }
-  set frameloop(mode) {
-    if (this._frameloop === mode) return;
-    const wasAlways = this._frameloop === "always";
-    this._frameloop = mode;
-    if (mode === "always" && !this.loopState.running && this.roots.size > 0) this.start();
-    else if (mode !== "always" && wasAlways) this.stop();
-  }
-  get isRunning() {
-    return this.loopState.running;
-  }
-  get isReady() {
-    return this.roots.size > 0;
-  }
-  get independent() {
-    return this._independent;
-  }
-  set independent(value) {
-    this._independent = value;
-    if (value) this.ensureDefaultRoot();
-  }
-  //* Root Management Methods ================================
-  /**
-   * Register a root (Canvas) with the scheduler.
-   * The first root to register starts the RAF loop (if frameloop='always').
-   * @param {string} id - Unique identifier for this root
-   * @param {RootOptions} [options] - Optional configuration with getState and onError callbacks
-   * @returns {() => void} Unsubscribe function to remove this root
-   */
-  registerRoot(id, options = {}) {
-    if (this.roots.has(id)) {
-      console.warn(`[Scheduler] Root "${id}" already registered`);
-      return () => this.unregisterRoot(id);
-    }
-    const entry = {
-      id,
-      getState: options.getState ?? (() => ({})),
-      jobs: /* @__PURE__ */ new Map(),
-      sortedJobs: [],
-      needsRebuild: false
-    };
-    if (options.onError) {
-      this.errorHandler = options.onError;
-    }
-    this.roots.set(id, entry);
-    if (this.roots.size === 1) {
-      this.notifyRootReady();
-      if (this._frameloop === "always") this.start();
-    }
-    return () => this.unregisterRoot(id);
-  }
-  /**
-   * Unregister a root from the scheduler.
-   * Cleans up all job state listeners for this root's jobs.
-   * The last root to unregister stops the RAF loop.
-   * @param {string} id - The root ID to unregister
-   * @returns {void}
-   */
-  unregisterRoot(id) {
-    const root = this.roots.get(id);
-    if (!root) return;
-    for (const jobId of root.jobs.keys()) {
-      this.jobStateListeners.delete(jobId);
-    }
-    this.roots.delete(id);
-    if (this.roots.size === 0) {
-      this.stop();
-      this.errorHandler = null;
-    }
-  }
-  /**
-   * Subscribe to be notified when a root becomes available.
-   * Fires immediately if a root already exists.
-   * @param {() => void} callback - Function called when first root registers
-   * @returns {() => void} Unsubscribe function
-   */
-  onRootReady(callback) {
-    if (this.roots.size > 0) {
-      callback();
-      return () => {
-      };
-    }
-    this.rootReadyCallbacks.add(callback);
-    return () => this.rootReadyCallbacks.delete(callback);
-  }
-  /**
-   * Notify all registered root-ready callbacks.
-   * Called when the first root registers.
-   * @returns {void}
-   * @private
-   */
-  notifyRootReady() {
-    for (const cb of this.rootReadyCallbacks) {
-      try {
-        cb();
-      } catch (error) {
-        console.error("[Scheduler] Error in root-ready callback:", error);
-      }
-    }
-    this.rootReadyCallbacks.clear();
-  }
-  /**
-   * Ensure a default root exists for independent mode.
-   * Creates a minimal root with no state provider.
-   * @returns {void}
-   * @private
-   */
-  ensureDefaultRoot() {
-    if (!this.roots.has("__default__")) {
-      this.registerRoot("__default__");
-    }
-  }
-  /**
-   * Trigger error handling for job errors.
-   * Uses the bound error handler if available, otherwise logs to console.
-   * @param {Error} error - The error to handle
-   * @returns {void}
-   */
-  triggerError(error) {
-    if (this.errorHandler) this.errorHandler(error);
-    else console.error("[Scheduler]", error);
-  }
-  //* Phase Management Methods ================================
-  /**
-   * Add a named phase to the scheduler's execution order.
-   * Marks all roots for rebuild to incorporate the new phase.
-   * @param {string} name - The phase name (e.g., 'physics', 'postprocess')
-   * @param {AddPhaseOptions} [options] - Positioning options (before/after other phases)
-   * @returns {void}
-   * @example
-   * scheduler.addPhase('physics', { before: 'update' });
-   * scheduler.addPhase('postprocess', { after: 'render' });
-   */
-  addPhase(name, options) {
-    this.phaseGraph.addPhase(name, options);
-    for (const root of this.roots.values()) {
-      root.needsRebuild = true;
-    }
-  }
-  /**
-   * Check if a phase exists in the scheduler.
-   * @param {string} name - The phase name to check
-   * @returns {boolean} True if the phase exists
-   */
-  hasPhase(name) {
-    return this.phaseGraph.hasPhase(name);
-  }
-  //* Global Job Registration Methods (Deprecated APIs) ================================
-  /**
-   * Register a global job that runs once per frame (not per-root).
-   * Used internally by deprecated addEffect/addAfterEffect APIs.
-   * @param {'before' | 'after'} phase - When to run: 'before' all roots or 'after' all roots
-   * @param {string} id - Unique identifier for this global job
-   * @param {(timestamp: number) => void} callback - Function called each frame with RAF timestamp
-   * @returns {() => void} Unsubscribe function to remove this global job
-   * @deprecated Use useFrame with phases instead
-   */
-  registerGlobal(phase, id, callback) {
-    const job = { id, callback };
-    if (phase === "before") {
-      this.globalBeforeJobs.set(id, job);
-    } else {
-      this.globalAfterJobs.set(id, job);
-    }
-    return () => {
-      if (phase === "before") this.globalBeforeJobs.delete(id);
-      else this.globalAfterJobs.delete(id);
-    };
-  }
-  //* Idle Callback Methods (Deprecated API) ================================
-  /**
-   * Register an idle callback that fires when the loop stops.
-   * Used internally by deprecated addTail API.
-   * @param {(timestamp: number) => void} callback - Function called when loop becomes idle
-   * @returns {() => void} Unsubscribe function to remove this idle callback
-   * @deprecated Use demand mode with invalidate() instead
-   */
-  onIdle(callback) {
-    this.idleCallbacks.add(callback);
-    return () => this.idleCallbacks.delete(callback);
-  }
-  /**
-   * Notify all registered idle callbacks.
-   * Called when the loop stops in demand mode.
-   * @param {number} timestamp - The RAF timestamp when idle occurred
-   * @returns {void}
-   * @private
-   */
-  notifyIdle(timestamp) {
-    for (const cb of this.idleCallbacks) {
-      try {
-        cb(timestamp);
-      } catch (error) {
-        console.error("[Scheduler] Error in idle callback:", error);
-      }
-    }
-  }
-  //* Job Registration & Management Methods ================================
-  /**
-   * Register a job (frame callback) with a specific root.
-   * This is the core registration method used by useFrame internally.
-   * @param {FrameNextCallback} callback - The function to call each frame
-   * @param {JobOptions & { rootId?: string; system?: boolean }} [options] - Job configuration
-   * @param {string} [options.rootId] - Target root ID (defaults to first registered root)
-   * @param {string} [options.id] - Unique job ID (auto-generated if not provided)
-   * @param {string} [options.phase] - Execution phase (defaults to 'update')
-   * @param {number} [options.priority] - Priority within phase (higher = earlier, default 0)
-   * @param {number} [options.fps] - FPS throttle limit
-   * @param {boolean} [options.drop] - Drop frames when behind (default true)
-   * @param {boolean} [options.enabled] - Whether job is active (default true)
-   * @param {boolean} [options.system] - Internal flag for system jobs (not user-facing)
-   * @returns {() => void} Unsubscribe function to remove this job
-   */
-  register(callback, options = {}) {
-    const rootId = options.rootId;
-    const root = rootId ? this.roots.get(rootId) : this.roots.values().next().value;
-    if (!root) {
-      console.warn("[Scheduler] No root registered. Is this inside a Canvas?");
-      return () => {
-      };
-    }
-    const id = options.id ?? this.generateJobId();
-    let phase = options.phase ?? "update";
-    if (!options.phase && (options.before || options.after)) {
-      phase = this.phaseGraph.resolveConstraintPhase(options.before, options.after);
-    }
-    const before = this.normalizeConstraints(options.before);
-    const after = this.normalizeConstraints(options.after);
-    const job = {
-      id,
-      callback,
-      phase,
-      before,
-      after,
-      priority: options.priority ?? 0,
-      index: this.nextJobIndex++,
-      fps: options.fps,
-      drop: options.drop ?? true,
-      enabled: options.enabled ?? true,
-      system: options.system ?? false
-    };
-    if (root.jobs.has(id)) {
-      console.warn(`[useFrame] Job with id "${id}" already exists, replacing`);
-    }
-    root.jobs.set(id, job);
-    root.needsRebuild = true;
-    return () => this.unregister(id, root.id);
-  }
-  /**
-   * Unregister a job by its ID.
-   * Searches all roots if rootId is not provided.
-   * @param {string} id - The job ID to unregister
-   * @param {string} [rootId] - Optional root ID to search (searches all if not provided)
-   * @returns {void}
-   */
-  unregister(id, rootId) {
-    const root = rootId ? this.roots.get(rootId) : Array.from(this.roots.values()).find((r) => r.jobs.has(id));
-    if (root?.jobs.delete(id)) {
-      root.needsRebuild = true;
-      this.jobStateListeners.delete(id);
-    }
-  }
-  /**
-   * Update a job's options dynamically.
-   * Searches all roots to find the job by ID.
-   * Phase/constraint changes trigger a rebuild of the sorted job list.
-   * @param {string} id - The job ID to update
-   * @param {Partial<JobOptions>} options - The options to update
-   * @returns {void}
-   */
-  updateJob(id, options) {
-    let job;
-    let root;
-    for (const r of this.roots.values()) {
-      job = r.jobs.get(id);
-      if (job) {
-        root = r;
-        break;
-      }
-    }
-    if (!job || !root) return;
-    if (options.priority !== void 0) job.priority = options.priority;
-    if (options.fps !== void 0) job.fps = options.fps;
-    if (options.drop !== void 0) job.drop = options.drop;
-    if (options.enabled !== void 0) {
-      const wasEnabled = job.enabled;
-      job.enabled = options.enabled;
-      if (!wasEnabled && job.enabled) resetJobTiming(job);
-      if (wasEnabled !== job.enabled) root.needsRebuild = true;
-    }
-    if (options.phase !== void 0 || options.before !== void 0 || options.after !== void 0) {
-      if (options.phase) job.phase = options.phase;
-      if (options.before !== void 0) job.before = this.normalizeConstraints(options.before);
-      if (options.after !== void 0) job.after = this.normalizeConstraints(options.after);
-      root.needsRebuild = true;
-    }
-  }
-  //* Job State Management Methods ================================
-  /**
-   * Check if a job is currently paused (disabled).
-   * @param {string} id - The job ID to check
-   * @returns {boolean} True if the job exists and is paused
-   */
-  isJobPaused(id) {
-    for (const root of this.roots.values()) {
-      const job = root.jobs.get(id);
-      if (job) return !job.enabled;
-    }
-    return false;
-  }
-  /**
-   * Subscribe to state changes for a specific job.
-   * Listener is called when job is paused or resumed.
-   * @param {string} id - The job ID to subscribe to
-   * @param {() => void} listener - Callback invoked on state changes
-   * @returns {() => void} Unsubscribe function
-   */
-  subscribeJobState(id, listener) {
-    if (!this.jobStateListeners.has(id)) {
-      this.jobStateListeners.set(id, /* @__PURE__ */ new Set());
-    }
-    this.jobStateListeners.get(id).add(listener);
-    return () => {
-      this.jobStateListeners.get(id)?.delete(listener);
-      if (this.jobStateListeners.get(id)?.size === 0) {
-        this.jobStateListeners.delete(id);
-      }
-    };
-  }
-  /**
-   * Notify all listeners that a job's state has changed.
-   * @param {string} id - The job ID that changed
-   * @returns {void}
-   * @private
-   */
-  notifyJobStateChange(id) {
-    this.jobStateListeners.get(id)?.forEach((listener) => listener());
-  }
-  /**
-   * Pause a job by ID (sets enabled=false).
-   * Notifies any subscribed state listeners.
-   * @param {string} id - The job ID to pause
-   * @returns {void}
-   */
-  pauseJob(id) {
-    this.updateJob(id, { enabled: false });
-    this.notifyJobStateChange(id);
-  }
-  /**
-   * Resume a paused job by ID (sets enabled=true).
-   * Resets job timing to prevent frame accumulation.
-   * Notifies any subscribed state listeners.
-   * @param {string} id - The job ID to resume
-   * @returns {void}
-   */
-  resumeJob(id) {
-    this.updateJob(id, { enabled: true });
-    this.notifyJobStateChange(id);
-  }
-  //* Frame Loop Control Methods ================================
-  /**
-   * Start the requestAnimationFrame loop.
-   * Resets timing state (elapsedTime, frameCount) on start.
-   * No-op if already running.
-   * @returns {void}
-   */
-  start() {
-    if (this.loopState.running) return;
-    const { elapsedTime, createdAt } = this.loopState;
-    let adjustedCreated = 0;
-    if (this.stoppedTime > 0) {
-      adjustedCreated = createdAt - (performance.now() - this.stoppedTime);
-      this.stoppedTime = 0;
-    }
-    Object.assign(this.loopState, {
-      running: true,
-      elapsedTime: elapsedTime ?? 0,
-      lastTime: performance.now(),
-      createdAt: adjustedCreated > 0 ? adjustedCreated : performance.now(),
-      frameCount: 0,
-      rafHandle: requestAnimationFrame(this.loop)
-    });
-  }
-  /**
-   * Stop the requestAnimationFrame loop.
-   * Cancels any pending RAF callback.
-   * No-op if not running.
-   * @returns {void}
-   */
-  stop() {
-    if (!this.loopState.running) return;
-    this.loopState.running = false;
-    if (this.loopState.rafHandle !== null) {
-      cancelAnimationFrame(this.loopState.rafHandle);
-      this.loopState.rafHandle = null;
-    }
-    this.stoppedTime = performance.now();
-  }
-  /**
-   * Request frames to be rendered in demand mode.
-   * Accumulates pending frames (capped at 60) and starts the loop if not running.
-   * No-op if frameloop is not 'demand'.
-   * @param {number} [frames=1] - Number of frames to request
-   * @param {boolean} [stackFrames=false] - Whether to add frames to existing pending count
-   *   - `false` (default): Sets pending frames to the specified value (replaces existing count)
-   *   - `true`: Adds frames to existing pending count (useful for accumulating invalidations)
-   * @returns {void}
-   * @example
-   * // Request a single frame render
-   * scheduler.invalidate();
-   *
-   * @example
-   * // Request 5 frames (e.g., for animations)
-   * scheduler.invalidate(5);
-   *
-   * @example
-   * // Set pending frames to exactly 3 (don't stack with existing)
-   * scheduler.invalidate(3, false);
-   *
-   * @example
-   * // Add 2 more frames to existing pending count
-   * scheduler.invalidate(2, true);
-   */
-  invalidate(frames = 1, stackFrames = false) {
-    if (this._frameloop !== "demand") return;
-    const baseFrames = stackFrames ? this.pendingFrames : 0;
-    this.pendingFrames = Math.min(60, baseFrames + frames);
-    if (!this.loopState.running && this.pendingFrames > 0) this.start();
-  }
-  /**
-   * Reset timing state for deterministic testing.
-   * Preserves jobs and roots but resets lastTime, frameCount, elapsedTime, etc.
-   * @returns {void}
-   */
-  resetTiming() {
-    this.loopState.lastTime = null;
-    this.loopState.frameCount = 0;
-    this.loopState.elapsedTime = 0;
-    this.loopState.createdAt = performance.now();
-  }
-  //* Manual Stepping Methods ================================
-  /**
-   * Manually execute a single frame for all roots.
-   * Useful for frameloop='never' mode or testing scenarios.
-   * @param {number} [timestamp] - Optional timestamp (defaults to performance.now())
-   * @returns {void}
-   * @example
-   * // Manual control mode
-   * scheduler.frameloop = 'never';
-   * scheduler.step(); // Execute one frame
-   */
-  step(timestamp) {
-    const now = timestamp ?? performance.now();
-    this.executeFrame(now);
-  }
-  /**
-   * Manually execute a single job by its ID.
-   * Useful for testing individual job callbacks in isolation.
-   * @param {string} id - The job ID to step
-   * @param {number} [timestamp] - Optional timestamp (defaults to performance.now())
-   * @returns {void}
-   */
-  stepJob(id, timestamp) {
-    let job;
-    let root;
-    for (const r of this.roots.values()) {
-      job = r.jobs.get(id);
-      if (job) {
-        root = r;
-        break;
-      }
-    }
-    if (!job || !root) {
-      console.warn(`[Scheduler] Job "${id}" not found`);
-      return;
-    }
-    const now = timestamp ?? performance.now();
-    const deltaMs = this.loopState.lastTime !== null ? now - this.loopState.lastTime : 0;
-    const delta = deltaMs / 1e3;
-    const elapsed = now - this.loopState.createdAt;
-    const providedState = root.getState?.() ?? {};
-    const frameState = {
-      ...providedState,
-      time: now,
-      delta,
-      elapsed,
-      frame: this.loopState.frameCount
-    };
-    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)));
-    }
-  }
-  /**
-   * Execute a single frame across all roots.
-   * Order: globalBefore → each root's jobs → globalAfter
-   * @param {number} timestamp - RAF timestamp in milliseconds
-   * @returns {void}
-   * @private
-   */
-  executeFrame(timestamp) {
-    const deltaMs = this.loopState.lastTime !== null ? timestamp - this.loopState.lastTime : 0;
-    const delta = deltaMs / 1e3;
-    this.loopState.lastTime = timestamp;
-    this.loopState.frameCount++;
-    this.loopState.elapsedTime += deltaMs;
-    this.runGlobalJobs(this.globalBeforeJobs, timestamp);
-    for (const root of this.roots.values()) {
-      this.tickRoot(root, timestamp, delta);
-    }
-    this.runGlobalJobs(this.globalAfterJobs, timestamp);
-  }
-  /**
-   * Run all global jobs from a job map.
-   * Catches and logs errors without stopping execution.
-   * @param {Map<string, GlobalJob>} jobs - The global jobs map to execute
-   * @param {number} timestamp - RAF timestamp in milliseconds
-   * @returns {void}
-   * @private
-   */
-  runGlobalJobs(jobs, timestamp) {
-    for (const job of jobs.values()) {
-      try {
-        job.callback(timestamp);
-      } catch (error) {
-        console.error(`[Scheduler] Error in global job "${job.id}":`, error);
-      }
-    }
-  }
-  /**
-   * Execute all jobs for a single root in sorted order.
-   * Rebuilds sorted job list if needed, then dispatches each job.
-   * Errors are caught and propagated via triggerError.
-   * @param {RootEntry} root - The root entry to tick
-   * @param {number} timestamp - RAF timestamp in milliseconds
-   * @param {number} delta - Time since last frame in seconds
-   * @returns {void}
-   * @private
-   */
-  tickRoot(root, timestamp, delta) {
-    if (root.needsRebuild) {
-      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)));
-      }
-    }
-  }
-  //* 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?.();
-}
-
 function useFrame(callback, priorityOrOptions) {
   const store = React__namespace.useContext(context);
   const isInsideCanvas = store !== null;
-  const scheduler = getScheduler();
+  const scheduler$1 = scheduler.getScheduler();
   const optionsKey = typeof priorityOrOptions === "number" ? `p:${priorityOrOptions}` : priorityOrOptions ? JSON.stringify({
     id: priorityOrOptions.id,
     phase: priorityOrOptions.phase,
@@ -2429,7 +2069,7 @@ function useFrame(callback, priorityOrOptions) {
         };
         callbackRef.current?.(mergedState, delta);
       };
-      const unregister = scheduler.register(wrappedCallback, {
+      const unregister = scheduler$1.register(wrappedCallback, {
         id,
         rootId,
         ...options
@@ -2450,37 +2090,31 @@ function useFrame(callback, priorityOrOptions) {
         }
       };
     } else {
-      const registerOutside = () => {
-        return scheduler.register((state, delta) => callbackRef.current?.(state, delta), { id, ...options });
-      };
-      if (scheduler.independent || scheduler.isReady) {
-        return registerOutside();
-      }
-      let unregisterJob = null;
-      const unsubReady = scheduler.onRootReady(() => {
-        unregisterJob = registerOutside();
-      });
-      return () => {
-        unsubReady();
-        unregisterJob?.();
-      };
+      return scheduler$1.register(
+        (state, delta) => {
+          const frameState = state;
+          if (!frameState.renderer) return;
+          callbackRef.current?.(frameState, delta);
+        },
+        { id, ...options }
+      );
     }
-  }, [store, scheduler, id, optionsKey, isLegacyPriority, isInsideCanvas]);
+  }, [store, scheduler$1, id, optionsKey, isLegacyPriority, isInsideCanvas]);
   const isPaused = React__namespace.useSyncExternalStore(
     // Subscribe function
     React__namespace.useCallback(
       (onStoreChange) => {
-        return getScheduler().subscribeJobState(id, onStoreChange);
+        return scheduler.getScheduler().subscribeJobState(id, onStoreChange);
       },
       [id]
     ),
     // getSnapshot function
-    React__namespace.useCallback(() => getScheduler().isJobPaused(id), [id]),
+    React__namespace.useCallback(() => scheduler.getScheduler().isJobPaused(id), [id]),
     // getServerSnapshot function (SSR)
     React__namespace.useCallback(() => false, [])
   );
   const controls = React__namespace.useMemo(() => {
-    const scheduler2 = getScheduler();
+    const scheduler2 = scheduler.getScheduler();
     return {
       /** The job's unique ID */
       id,
@@ -2495,7 +2129,7 @@ function useFrame(callback, priorityOrOptions) {
        * @param timestamp Optional timestamp (defaults to performance.now())
        */
       step: (timestamp) => {
-        getScheduler().stepJob(id, timestamp);
+        scheduler.getScheduler().stepJob(id, timestamp);
       },
       /**
        * Manually step ALL jobs in the scheduler.
@@ -2503,20 +2137,20 @@ function useFrame(callback, priorityOrOptions) {
        * @param timestamp Optional timestamp (defaults to performance.now())
        */
       stepAll: (timestamp) => {
-        getScheduler().step(timestamp);
+        scheduler.getScheduler().step(timestamp);
       },
       /**
        * Pause this job (set enabled=false).
        * Job remains registered but won't run.
        */
       pause: () => {
-        getScheduler().pauseJob(id);
+        scheduler.getScheduler().pauseJob(id);
       },
       /**
        * Resume this job (set enabled=true).
        */
       resume: () => {
-        getScheduler().resumeJob(id);
+        scheduler.getScheduler().resumeJob(id);
       },
       /**
        * Reactive paused state - automatically updates when pause/resume is called.
@@ -2554,22 +2188,29 @@ function buildFromCache(input, textureCache) {
 function useTexture(input, optionsOrOnLoad) {
   const renderer = useThree((state) => state.internal.actualRenderer);
   const store = useStore();
-  const textureCache = useThree((state) => state.textures);
   const options = typeof optionsOrOnLoad === "function" ? { onLoad: optionsOrOnLoad } : optionsOrOnLoad ?? {};
-  const { onLoad, cache = false } = options;
+  const { onLoad, cache = true } = options;
+  const onLoadRef = React.useRef(onLoad);
+  onLoadRef.current = onLoad;
+  const onLoadCalledForRef = React.useRef(null);
   const urls = React.useMemo(() => getUrls(input), [input]);
   const cachedResult = React.useMemo(() => {
     if (!cache) return null;
-    if (!allUrlsCached(urls, textureCache)) return null;
-    return buildFromCache(input, textureCache);
-  }, [cache, urls, textureCache, input]);
+    const textures = store.getState().textures;
+    if (!allUrlsCached(urls, textures)) return null;
+    return buildFromCache(input, textures);
+  }, [cache, urls, input, store]);
   const loadedTextures = useLoader(
     webgpu.TextureLoader,
     IsObject(input) ? Object.values(input) : input
   );
+  const inputKey = urls.join("\0");
   React.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]);
   React.useEffect(() => {
     if (cachedResult) return;
     if ("initTexture" in renderer) {
@@ -2602,8 +2243,6 @@ function useTexture(input, optionsOrOnLoad) {
   }, [input, loadedTextures, cachedResult]);
   React.useEffect(() => {
     if (!cache) return;
-    if (cachedResult) return;
-    const set = store.setState;
     const urlTextureMap = [];
     if (typeof input === "string") {
       urlTextureMap.push([input, mappedTextures]);
@@ -2617,18 +2256,32 @@ function useTexture(input, optionsOrOnLoad) {
         urlTextureMap.push([url, textureRecord[key]]);
       }
     }
-    set((state) => {
-      const newMap = new Map(state.textures);
-      let changed = false;
+    store.setState((state) => {
+      const refs = new Map(state._textureRefs);
+      let textures = state.textures;
+      let added = false;
       for (const [url, texture] of urlTextureMap) {
-        if (!newMap.has(url)) {
-          newMap.set(url, texture);
-          changed = true;
+        if (!textures.has(url)) {
+          if (!added) {
+            textures = new Map(textures);
+            added = true;
+          }
+          textures.set(url, texture);
         }
+        refs.set(url, (refs.get(url) ?? 0) + 1);
       }
-      return changed ? { textures: newMap } : state;
+      return added ? { textures, _textureRefs: refs } : { _textureRefs: refs };
+    });
+    return () => store.setState((state) => {
+      const refs = new Map(state._textureRefs);
+      for (const [url] of urlTextureMap) {
+        const next = (refs.get(url) ?? 0) - 1;
+        if (next <= 0) refs.delete(url);
+        else refs.set(url, next);
+      }
+      return { _textureRefs: refs };
     });
-  }, [cache, input, mappedTextures, store, cachedResult]);
+  }, [cache, input, mappedTextures, store]);
   return mappedTextures;
 }
 useTexture.preload = (url) => useLoader.preload(webgpu.TextureLoader, url);
@@ -2644,108 +2297,92 @@ const Texture = ({
   return /* @__PURE__ */ jsxRuntime.jsx(jsxRuntime.Fragment, { children: children?.(ret) });
 };
 
-function getTextureValue(entry) {
-  if (entry instanceof webgpu.Texture) return entry;
-  if (entry && typeof entry === "object" && "value" in entry && entry.value instanceof webgpu.Texture) {
-    return entry.value;
-  }
-  return null;
-}
-function useTextures() {
+function useTextures(selector) {
   const store = useStore();
-  return React.useMemo(() => {
-    const set = store.setState;
+  const registry = React.useMemo(() => {
     const getState = store.getState;
-    const add = (key, value) => {
-      set((state) => {
-        const newMap = new Map(state.textures);
-        newMap.set(key, value);
-        return { textures: newMap };
-      });
-    };
-    const addMultiple = (items) => {
-      set((state) => {
-        const newMap = new Map(state.textures);
-        const entries = items instanceof Map ? items.entries() : Object.entries(items);
-        for (const [key, value] of entries) {
-          newMap.set(key, value);
-        }
-        return { textures: newMap };
-      });
-    };
-    const remove = (key) => {
-      set((state) => {
-        const newMap = new Map(state.textures);
-        newMap.delete(key);
-        return { textures: newMap };
-      });
-    };
-    const removeMultiple = (keys) => {
-      set((state) => {
-        const newMap = new Map(state.textures);
-        for (const key of keys) newMap.delete(key);
-        return { textures: newMap };
-      });
-    };
-    const dispose = (key) => {
-      const entry = getState().textures.get(key);
-      if (entry) {
-        const tex = getTextureValue(entry);
-        tex?.dispose();
-      }
-      remove(key);
-    };
-    const disposeMultiple = (keys) => {
-      const textures = getState().textures;
-      for (const key of keys) {
-        const entry = textures.get(key);
-        if (entry) {
-          const tex = getTextureValue(entry);
-          tex?.dispose();
-        }
-      }
-      removeMultiple(keys);
-    };
-    const disposeAll = () => {
-      const textures = getState().textures;
-      for (const entry of textures.values()) {
-        const tex = getTextureValue(entry);
-        tex?.dispose();
-      }
-      set({ textures: /* @__PURE__ */ new Map() });
-    };
+    const setState = store.setState;
+    const getOne = (key) => getState().textures.get(key);
     return {
-      // Getter for the textures Map (reactive via getState)
-      get textures() {
+      get all() {
         return getState().textures;
       },
-      // Read
-      get: (key) => getState().textures.get(key),
+      get(input) {
+        if (typeof input === "string") return getOne(input);
+        if (Array.isArray(input)) return input.map(getOne);
+        const out = {};
+        for (const name in input) out[name] = getOne(input[name]);
+        return out;
+      },
       has: (key) => getState().textures.has(key),
-      // Write
-      add,
-      addMultiple,
-      // Remove (cache only)
-      remove,
-      removeMultiple,
-      // Dispose (GPU + cache)
-      dispose,
-      disposeMultiple,
-      disposeAll
+      add(keyOrRecord, texture) {
+        setState((state) => {
+          const textures = new Map(state.textures);
+          if (typeof keyOrRecord === "string") {
+            textures.set(keyOrRecord, texture);
+          } else {
+            for (const key in keyOrRecord) textures.set(key, keyOrRecord[key]);
+          }
+          return { textures };
+        });
+      },
+      dispose(key, options) {
+        const state = getState();
+        const refs = state._textureRefs.get(key) ?? 0;
+        if (refs > 0 && !options?.force) {
+          console.warn(
+            `[useTextures] "${key}" still has ${refs} active reference(s); skipping dispose. Pass { force: true } to override.`
+          );
+          return false;
+        }
+        state.textures.get(key)?.dispose();
+        setState((s) => {
+          const textures = new Map(s.textures);
+          textures.delete(key);
+          const nextRefs = new Map(s._textureRefs);
+          nextRefs.delete(key);
+          return { textures, _textureRefs: nextRefs };
+        });
+        return true;
+      },
+      disposeAll() {
+        for (const texture of getState().textures.values()) texture.dispose();
+        setState({ textures: /* @__PURE__ */ new Map(), _textureRefs: /* @__PURE__ */ new Map() });
+      }
     };
   }, [store]);
+  const subscribe = selector ? () => selector(registry) : (state) => state.textures;
+  const selected = useThree(subscribe);
+  return selector ? selected : registry;
 }
 
-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 React.useMemo(() => {
     const w = width ?? size.width;
     const h = height ?? size.height;
     {
-      return isLegacy ? new three.WebGLRenderTarget(w, h, options) : new webgpu.RenderTarget(w, h, options);
+      return isLegacy ? new three.WebGLRenderTarget(w, h, opts) : new webgpu.RenderTarget(w, h, opts);
     }
-  }, [width, height, size.width, size.height, options, isLegacy]);
+  }, [width, height, size.width, size.height, opts, isLegacy]);
 }
 
 function useStore() {
@@ -2773,7 +2410,7 @@ function addEffect(callback) {
     link: "https://docs.pmnd.rs/react-three-fiber/api/hooks#useframe"
   });
   const id = `legacy_effect_${effectId++}`;
-  return getScheduler().registerGlobal("before", id, callback);
+  return scheduler.getScheduler().registerGlobal("before", id, callback);
 }
 function addAfterEffect(callback) {
   notifyDepreciated({
@@ -2782,7 +2419,7 @@ function addAfterEffect(callback) {
     link: "https://docs.pmnd.rs/react-three-fiber/api/hooks#useframe"
   });
   const id = `legacy_afterEffect_${effectId++}`;
-  return getScheduler().registerGlobal("after", id, callback);
+  return scheduler.getScheduler().registerGlobal("after", id, callback);
 }
 function addTail(callback) {
   notifyDepreciated({
@@ -2790,16 +2427,16 @@ function addTail(callback) {
     body: "Use scheduler.onIdle(callback) instead.\naddTail will be removed in a future version.",
     link: "https://docs.pmnd.rs/react-three-fiber/api/hooks#useframe"
   });
-  return getScheduler().onIdle(callback);
+  return scheduler.getScheduler().onIdle(callback);
 }
 function invalidate(state, frames = 1, stackFrames = false) {
-  getScheduler().invalidate(frames, stackFrames);
+  scheduler.getScheduler().invalidate(frames, stackFrames);
 }
-function advance(timestamp, runGlobalEffects = true, state, frame) {
-  getScheduler().step(timestamp);
+function advance(timestamp) {
+  scheduler.getScheduler().step(timestamp);
 }
 
-const version = "10.0.0-alpha.2";
+const version = "10.0.0-alpha.3";
 const packageData = {
 	version: version};
 
@@ -14238,6 +13875,7 @@ function swapInstances() {
       }
     }
     if (instance.isHidden) unhideInstance(instance);
+    if (isObject3D(instance.object)) removeInteractivity(findInitialRoot(instance), instance.object);
     if (instance.object.__r3f) delete instance.object.__r3f;
     if (instance.type !== "primitive") disposeOnIdle(instance.object);
   }
@@ -14249,6 +13887,9 @@ function swapInstances() {
       instance.object = instance.props.object ?? new target(...instance.props.args ?? []);
       instance.object.__r3f = instance;
       setFiberRef(fiber, instance.object);
+      delete instance.appliedOnce;
+      instance.eventCount = 0;
+      instance.handlers = {};
       applyProps(instance.object, instance.props);
       if (instance.props.attach) {
         attach(parent, instance);
@@ -14322,8 +13963,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,
@@ -14450,11 +14105,15 @@ const reconciler = /* @__PURE__ */ createReconciler({
   cloneMutableTextInstance(textInstance) {
     return textInstance;
   },
+  // React 19.2 added these for root-level view transitions. They only run for hosts that opt into
+  // view transitions by returning a container from cloneRootViewTransitionContainer; R3F renders
+  // into a WebGL/WebGPU canvas, where cloning the root has no meaning, so we never opt in and
+  // React never calls them. They stay as no-ops rather than throws: the host config is shared by
+  // every root, and a throw here would turn a React-internal probe into a hard crash for users.
+  // Guarded by a test asserting a full render + unmount never reaches them.
   cloneRootViewTransitionContainer(_rootContainer) {
-    throw new Error("Not implemented.");
   },
   removeRootViewTransitionClone(_rootContainer, _clone) {
-    throw new Error("Not implemented.");
   },
   // https://github.com/facebook/react/pull/32465
   createFragmentInstance: (_fiber) => null,
@@ -14539,11 +14198,15 @@ function createRoot(canvas) {
   const lastConfiguredProps = {};
   let configured = false;
   let pending = null;
+  let rendererSetup = null;
   return {
     async configure(props = {}) {
       let resolve;
       pending = new Promise((_resolve) => resolve = _resolve);
       const {
+        id: canvasId,
+        primaryCanvas,
+        scheduler: schedulerConfig,
         gl: glConfig,
         renderer: rendererConfig,
         size: propsSize,
@@ -14551,10 +14214,6 @@ function createRoot(canvas) {
         events,
         onCreated: onCreatedCallback,
         shadows = false,
-        linear = false,
-        flat = false,
-        textureColorSpace = webgpu.SRGBColorSpace,
-        legacy = false,
         orthographic = false,
         frameloop = "always",
         dpr = [1, 2],
@@ -14566,9 +14225,11 @@ function createRoot(canvas) {
         onDropMissed,
         autoUpdateFrustum = true,
         occlusion = false,
-        _sizeProps
+        _sizeProps,
+        forceEven
       } = props;
-      const 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 || webgpu.SRGBColorSpace;
+      let state = store.getState();
       const defaultGLProps = {
         canvas,
         powerPreference: "high-performance",
@@ -14576,7 +14237,8 @@ function createRoot(canvas) {
         alpha: true
       };
       const defaultGPUProps = {
-        canvas
+        canvas,
+        antialias: true
       };
       const wantsGL = (state.isLegacy || glConfig || !R3F_BUILD_WEBGPU || !rendererConfig);
       if (glConfig && rendererConfig) {
@@ -14590,19 +14252,73 @@ function createRoot(canvas) {
         });
       }
       let renderer = state.internal.actualRenderer;
-      if (wantsGL && !state.internal.actualRenderer) {
-        renderer = await resolveRenderer(glConfig, defaultGLProps, three.WebGLRenderer);
-        state.internal.actualRenderer = renderer;
-        state.set({ isLegacy: true, gl: renderer, renderer });
-      } else if (!wantsGL && !state.internal.actualRenderer) {
-        renderer = await resolveRenderer(rendererConfig, defaultGPUProps, webgpu.WebGPURenderer);
-        if (!renderer.hasInitialized?.()) {
-          await renderer.init();
-        }
-        const backend = renderer.backend;
-        const isWebGPUBackend = backend && "isWebGPUBackend" in backend;
-        state.internal.actualRenderer = renderer;
-        state.set({ webGPUSupported: isWebGPUBackend, renderer });
+      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) {
+        if (!rendererSetup) {
+          rendererSetup = (async () => {
+            if (wantsGL) {
+              renderer = await resolveRenderer(glConfig, defaultGLProps, three.WebGLRenderer);
+              state.internal.actualRenderer = renderer;
+              state.set({ isLegacy: true, gl: renderer, renderer, primaryStore: store });
+            } else if (!wantsGL && primaryCanvas) {
+              const primary = await waitForPrimary(primaryCanvas);
+              renderer = primary.renderer;
+              state.internal.actualRenderer = renderer;
+              const canvasTarget = new webgpu.CanvasTarget(canvas);
+              primary.store.setState((prev) => ({
+                internal: { ...prev.internal, isMultiCanvas: true }
+              }));
+              state.set((prev) => ({
+                webGPUSupported: primary.store.getState().webGPUSupported,
+                renderer,
+                primaryStore: primary.store,
+                internal: {
+                  ...prev.internal,
+                  canvasTarget,
+                  isMultiCanvas: true,
+                  isSecondary: true,
+                  targetId: primaryCanvas
+                }
+              }));
+            } else if (!wantsGL) {
+              renderer = await resolveRenderer(rendererConfig, defaultGPUProps, webgpu.WebGPURenderer);
+              if (!renderer.hasInitialized?.()) {
+                const size2 = computeInitialSize(canvas, propsSize);
+                if (size2.width > 0 && size2.height > 0) {
+                  const pixelRatio = calculateDpr(dpr);
+                  canvas.width = size2.width * pixelRatio;
+                  canvas.height = size2.height * pixelRatio;
+                }
+                await renderer.init();
+              }
+              const backend = renderer.backend;
+              const isWebGPUBackend = backend && "isWebGPUBackend" in backend;
+              state.internal.actualRenderer = renderer;
+              state.set({ webGPUSupported: isWebGPUBackend, renderer, primaryStore: store });
+              if (canvasId && !state.internal.isSecondary) {
+                const canvasTarget = new webgpu.CanvasTarget(canvas);
+                const unregisterPrimary = registerPrimary(canvasId, renderer, store);
+                state.set((prev) => ({
+                  internal: {
+                    ...prev.internal,
+                    canvasTarget,
+                    unregisterPrimary
+                  }
+                }));
+              }
+            }
+          })().catch((err) => {
+            rendererSetup = null;
+            throw err;
+          });
+        }
+        await rendererSetup;
+        state = store.getState();
+        renderer = state.internal.actualRenderer;
       }
       let raycaster = state.raycaster;
       if (!raycaster) state.set({ raycaster: raycaster = new webgpu.Raycaster() });
@@ -14611,6 +14327,7 @@ function createRoot(canvas) {
       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;
@@ -14630,6 +14347,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) {
@@ -14647,7 +14365,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) {
@@ -14664,6 +14382,9 @@ function createRoot(canvas) {
       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 (!state._sizeImperative && !is.equ(size, state.size, shallowLoose)) {
         const wasImperative = state._sizeImperative;
@@ -14690,10 +14411,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 = () => {
@@ -14705,16 +14426,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();
@@ -14726,15 +14447,22 @@ function createRoot(canvas) {
         const oldType = renderer.shadowMap.type;
         renderer.shadowMap.enabled = !!shadows;
         if (is.boo(shadows)) {
-          renderer.shadowMap.type = webgpu.PCFSoftShadowMap;
+          renderer.shadowMap.type = webgpu.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: webgpu.BasicShadowMap,
             percentage: webgpu.PCFShadowMap,
-            soft: webgpu.PCFSoftShadowMap,
+            soft: webgpu.PCFShadowMap,
             variance: webgpu.VSMShadowMap
           };
-          renderer.shadowMap.type = types[shadows] ?? webgpu.PCFSoftShadowMap;
+          renderer.shadowMap.type = types[shadows] ?? webgpu.PCFShadowMap;
         } else if (is.obj(shadows)) {
           Object.assign(renderer.shadowMap, shadows);
         }
@@ -14742,57 +14470,70 @@ function createRoot(canvas) {
           renderer.shadowMap.needsUpdate = true;
         }
       }
-      {
-        const legacyChanged = legacy !== lastConfiguredProps.legacy;
-        const linearChanged = linear !== lastConfiguredProps.linear;
-        const flatChanged = flat !== lastConfiguredProps.flat;
-        if (legacyChanged) {
-          if (legacy) {
-            notifyDepreciated({
-              heading: "Legacy Color Management",
-              body: "Legacy color management is deprecated and will be removed in a future version.",
-              link: "https://docs.pmnd.rs/react-three-fiber/api/hooks#useframe"
-            });
-          }
-        }
-        if (legacyChanged) {
-          webgpu.ColorManagement.enabled = !legacy;
-          lastConfiguredProps.legacy = legacy;
-        }
-        if (!configured || linearChanged) {
-          renderer.outputColorSpace = linear ? webgpu.LinearSRGBColorSpace : webgpu.SRGBColorSpace;
-          lastConfiguredProps.linear = linear;
-        }
-        if (!configured || flatChanged) {
-          renderer.toneMapping = flat ? webgpu.NoToneMapping : webgpu.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 = webgpu.SRGBColorSpace;
+        renderer.toneMapping = webgpu.ACESFilmicToneMapping;
       }
       if (textureColorSpace !== lastConfiguredProps.textureColorSpace) {
         if (state.textureColorSpace !== textureColorSpace) state.set(() => ({ textureColorSpace }));
         lastConfiguredProps.textureColorSpace = textureColorSpace;
       }
+      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)) {
-        applyProps(renderer, glConfig);
+        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 scheduler$1 = scheduler.getScheduler();
       const rootId = state.internal.rootId;
       if (!rootId) {
-        const newRootId = scheduler.generateRootId();
-        const unregisterRoot = scheduler.registerRoot(newRootId, {
+        const newRootId = canvasId || scheduler$1.generateRootId();
+        const unregisterRoot = scheduler$1.registerRoot(newRootId, {
           getState: () => store.getState(),
           onError: (err) => store.getState().setError(err)
         });
-        const unregisterFrustum = scheduler.register(
+        const unregisterCanvasTarget = scheduler$1.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$1.register(
+          () => {
+            const state2 = store.getState();
+            state2.events.flush?.();
+          },
+          {
+            id: `${newRootId}_events`,
+            rootId: newRootId,
+            phase: "input",
+            system: true
+          }
+        );
+        const unregisterFrustum = scheduler$1.register(
           () => {
             const state2 = store.getState();
             if (state2.autoUpdateFrustum && state2.camera) {
@@ -14802,11 +14543,11 @@ function createRoot(canvas) {
           {
             id: `${newRootId}_frustum`,
             rootId: newRootId,
-            phase: "preRender",
+            before: "render",
             system: true
           }
         );
-        const unregisterVisibility = scheduler.register(
+        const unregisterVisibility = scheduler$1.register(
           () => {
             const state2 = store.getState();
             checkVisibility(state2);
@@ -14814,30 +14555,34 @@ function createRoot(canvas) {
           {
             id: `${newRootId}_visibility`,
             rootId: newRootId,
-            phase: "preRender",
+            before: "render",
             system: true,
             after: `${newRootId}_frustum`
           }
         );
-        const unregisterRender = scheduler.register(
+        const unregisterRender = scheduler$1.register(
           () => {
             const state2 = store.getState();
             const renderer2 = state2.internal.actualRenderer;
-            const userHandlesRender = scheduler.hasUserJobsInPhase("render", newRootId);
+            const userHandlesRender = scheduler$1.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) => ({
@@ -14846,15 +14591,17 @@ function createRoot(canvas) {
             rootId: newRootId,
             unregisterRoot: () => {
               unregisterRoot();
+              unregisterCanvasTarget();
+              unregisterEventsFlush();
               unregisterFrustum();
               unregisterVisibility();
               unregisterRender();
             },
-            scheduler
+            scheduler: scheduler$1
           }
         }));
       }
-      scheduler.frameloop = frameloop;
+      scheduler$1.frameloop = frameloop;
       onCreated = onCreatedCallback;
       configured = true;
       resolve();
@@ -14904,15 +14651,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);
       }
@@ -14920,36 +14676,34 @@ function unmountComponentAtNode(canvas, callback) {
   }
 }
 function createPortal(children, container, state) {
-  return /* @__PURE__ */ jsxRuntime.jsx(PortalWrapper, { children, container, state });
+  return /* @__PURE__ */ jsxRuntime.jsx(Portal, { children, container, state });
 }
-function PortalWrapper({ children, container, state }) {
+function Portal({ children, container, state }) {
   const isRef = React.useCallback((obj) => obj && "current" in obj, []);
-  const [resolvedContainer, setResolvedContainer] = React.useState(() => {
+  const [resolvedContainer, _setResolvedContainer] = React.useState(() => {
     if (isRef(container)) return container.current ?? null;
     return container;
   });
+  const setResolvedContainer = React.useCallback(
+    (newContainer) => {
+      if (!newContainer || newContainer === resolvedContainer) return;
+      _setResolvedContainer(isRef(newContainer) ? newContainer.current : newContainer);
+    },
+    [resolvedContainer, _setResolvedContainer, isRef]
+  );
   React.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__ */ jsxRuntime.jsx(jsxRuntime.Fragment, {});
   const portalKey = resolvedContainer.uuid ?? `portal-${resolvedContainer.id ?? "unknown"}`;
-  return /* @__PURE__ */ jsxRuntime.jsx(Portal, { children, container: resolvedContainer, state }, portalKey);
+  return /* @__PURE__ */ jsxRuntime.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] = React.useState(() => new webgpu.Raycaster());
@@ -14970,12 +14724,14 @@ 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 webgpu.Vector3(), size);
-      if (camera !== rootState.camera) updateCamera(camera, size);
+      viewport = rootState.viewport.getCurrentViewport(camera, new webgpu.Vector3(), resolvedSize);
+      if (camera !== rootState.camera) updateCamera(camera, resolvedSize);
     }
+    const set = injectState.set;
     return {
       // The intersect consists of the previous root state
       ...rootState,
@@ -14991,10 +14747,10 @@ 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 } })),
+      setEvents: (events2) => set((state2) => ({ ...state2, events: { ...state2.events, ...events2 } })),
       // Container for child attachment - the portalScene (injected or container itself)
       internal: { ...rootState.internal, ...injectState.internal, container: portalScene }
     };
@@ -15003,9 +14759,13 @@ function Portal({ state = {}, children, container }) {
     const store = traditional.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__ */ jsxRuntime.jsx(jsxRuntime.Fragment, { children: reconciler.createPortal(
@@ -15019,21 +14779,72 @@ function flushSync(fn) {
   return reconciler.flushSyncFromReconciler(fn);
 }
 
+function parseBackground(background) {
+  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;
+}
+
+function parseRendererConfig(rendererProp) {
+  const isRendererConfig = typeof rendererProp === "object" && rendererProp !== null && !("render" in rendererProp) && ("primaryCanvas" in rendererProp || "scheduler" in rendererProp);
+  if (isRendererConfig) {
+    const { primaryCanvas: pc, scheduler: sc, ...rest } = rendererProp;
+    return {
+      primaryCanvas: pc,
+      scheduler: sc,
+      renderer: Object.keys(rest).length > 0 ? rest : rendererProp
+    };
+  }
+  return { primaryCanvas: void 0, scheduler: void 0, renderer: rendererProp };
+}
+
+function clearHmrCaches(store) {
+  store.setState((state) => ({
+    nodes: {},
+    uniforms: {},
+    buffers: {},
+    gpuStorage: {},
+    _hmrVersion: state._hmrVersion + 1
+  }));
+}
+
 function CanvasImpl({
   ref,
   children,
   fallback,
   resize,
   style,
+  id,
   gl,
-  renderer,
+  renderer: rendererProp,
   events = createPointerEvents,
   eventSource,
   eventPrefix,
   shadows,
-  linear,
-  flat,
-  legacy,
   orthographic,
   frameloop,
   dpr,
@@ -15041,6 +14852,8 @@ function CanvasImpl({
   raycaster,
   camera,
   scene,
+  autoUpdateFrustum,
+  occlusion,
   onPointerMissed,
   onDragOverMissed,
   onDropMissed,
@@ -15048,10 +14861,14 @@ function CanvasImpl({
   hmr,
   width,
   height,
+  background,
+  forceEven,
   ...props
 }) {
+  const { primaryCanvas, scheduler, renderer } = parseRendererConfig(rendererProp);
   React__namespace.useMemo(() => extend(THREE), []);
   const Bridge = useBridge();
+  const backgroundProps = React__namespace.useMemo(() => parseBackground(background), [background]);
   const hasInitialSizeRef = React__namespace.useRef(false);
   const measureConfig = React__namespace.useMemo(() => {
     if (!hasInitialSizeRef.current) {
@@ -15068,15 +14885,20 @@ function CanvasImpl({
     };
   }, [resize, hasInitialSizeRef.current]);
   const [containerRef, containerRect] = useMeasure__default(measureConfig);
-  const effectiveSize = React__namespace.useMemo(
-    () => ({
-      width: width ?? containerRect.width,
-      height: height ?? containerRect.height,
+  const effectiveSize = React__namespace.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]
-  );
+    };
+  }, [width, height, containerRect, forceEven]);
   if (!hasInitialSizeRef.current && effectiveSize.width > 0 && effectiveSize.height > 0) {
     hasInitialSizeRef.current = true;
   }
@@ -15088,6 +14910,7 @@ function CanvasImpl({
   const handleDropMissed = useMutableCallback(onDropMissed);
   const [block, setBlock] = React__namespace.useState(false);
   const [error, setError] = React__namespace.useState(false);
+  const [fallbackVisible, setFallbackVisible] = React__namespace.useState(false);
   if (block) throw block;
   if (error) throw error;
   const root = React__namespace.useRef(null);
@@ -15095,6 +14918,7 @@ function CanvasImpl({
   const unsubscribeErrorRef = React__namespace.useRef(null);
   useIsomorphicLayoutEffect(() => {
     effectActiveRef.current = true;
+    if (fallbackVisible) return;
     const canvas = canvasRef.current;
     if (effectiveSize.width > 0 && effectiveSize.height > 0 && canvas) {
       if (!root.current) {
@@ -15115,24 +14939,27 @@ function CanvasImpl({
       }
       async function run() {
         if (!effectActiveRef.current || !root.current) return;
-        await root.current.configure({
+        const configured = await root.current.configure({
+          id,
+          primaryCanvas,
+          scheduler,
           gl,
           renderer,
           scene,
           events,
           shadows,
-          linear,
-          flat,
-          legacy,
           orthographic,
           frameloop,
           dpr,
           performance,
           raycaster,
           camera,
+          autoUpdateFrustum,
+          occlusion,
           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),
@@ -15153,10 +14980,25 @@ function CanvasImpl({
             }
             onCreated?.(state);
           }
-        });
-        if (!effectActiveRef.current || !root.current) return;
+        }).then(
+          () => true,
+          // Renderer setup failed (e.g. no WebGL/WebGPU support). The `fallback` prop lives
+          // inside <canvas>, which browsers don't display, so surface it as visible DOM
+          // instead; with no fallback, rethrow to an external error boundary. (#3757)
+          (setupError) => {
+            if (effectActiveRef.current) {
+              if (fallback != null) setFallbackVisible(true);
+              else setError(setupError);
+            }
+            return false;
+          }
+        );
+        if (!configured || !effectActiveRef.current || !root.current) return;
         root.current.render(
-          /* @__PURE__ */ jsxRuntime.jsx(Bridge, { children: /* @__PURE__ */ jsxRuntime.jsx(ErrorBoundary, { set: setError, children: /* @__PURE__ */ jsxRuntime.jsx(React__namespace.Suspense, { fallback: /* @__PURE__ */ jsxRuntime.jsx(Block, { set: setBlock }), children: children ?? null }) }) })
+          /* @__PURE__ */ jsxRuntime.jsx(Bridge, { children: /* @__PURE__ */ jsxRuntime.jsx(ErrorBoundary, { set: setError, children: /* @__PURE__ */ jsxRuntime.jsxs(React__namespace.Suspense, { fallback: /* @__PURE__ */ jsxRuntime.jsx(Block, { set: setBlock }), children: [
+            backgroundProps && /* @__PURE__ */ jsxRuntime.jsx(Environment, { ...backgroundProps }),
+            children ?? null
+          ] }) }) })
         );
       }
       run();
@@ -15183,20 +15025,15 @@ function CanvasImpl({
     const canvas = canvasRef.current;
     if (!canvas) return;
     const handleHMR = () => {
-      const rootEntry = _roots.get(canvas);
-      if (rootEntry?.store) {
-        rootEntry.store.setState((state) => ({
-          nodes: {},
-          uniforms: {},
-          _hmrVersion: state._hmrVersion + 1
-        }));
-      }
+      queueMicrotask(() => {
+        const rootEntry = _roots.get(canvas);
+        if (rootEntry?.store) clearHmrCaches(rootEntry.store);
+      });
     };
     if (typeof ({ url: (typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('index.cjs', document.baseURI).href)) }) !== "undefined" && undefined) {
       const hot = undefined;
       hot.on("vite:afterUpdate", handleHMR);
-      return () => hot.dispose?.(() => {
-      });
+      return () => hot.off?.("vite:afterUpdate", handleHMR);
     }
     if (typeof module !== "undefined" && module.hot) {
       const hot = module.hot;
@@ -15219,7 +15056,20 @@ function CanvasImpl({
         ...style
       },
       ...props,
-      children: /* @__PURE__ */ jsxRuntime.jsx("div", { ref: containerRef, className: "r3f-canvas-container", style: { width: "100%", height: "100%" }, children: /* @__PURE__ */ jsxRuntime.jsx("canvas", { ref: canvasRef, className: "r3f-canvas", style: { display: "block" }, children: fallback }) })
+      children: fallbackVisible ? (
+        // Renderer setup failed: render the fallback as visible DOM. Inside <canvas> (below)
+        // it exists in the tree but browsers never paint it, which is the whole bug (#3757).
+        fallback
+      ) : /* @__PURE__ */ jsxRuntime.jsx("div", { ref: containerRef, className: "r3f-canvas-container", style: { width: "100%", height: "100%" }, children: /* @__PURE__ */ jsxRuntime.jsx(
+        "canvas",
+        {
+          ref: canvasRef,
+          id,
+          className: "r3f-canvas",
+          style: { display: "block", width: "100%", height: "100%" },
+          children: fallback
+        }
+      ) })
     }
   );
 }
@@ -15229,15 +15079,23 @@ function Canvas(props) {
 
 extend(THREE);
 
+exports.Scheduler = scheduler.Scheduler;
+exports.getScheduler = scheduler.getScheduler;
 exports.Block = Block;
 exports.Canvas = Canvas;
+exports.Environment = Environment;
+exports.EnvironmentCube = EnvironmentCube;
+exports.EnvironmentMap = EnvironmentMap;
+exports.EnvironmentPortal = EnvironmentPortal;
 exports.ErrorBoundary = ErrorBoundary;
+exports.FROM_REF = FROM_REF;
 exports.IsObject = IsObject;
+exports.ONCE = ONCE;
+exports.Portal = Portal;
 exports.R3F_BUILD_LEGACY = R3F_BUILD_LEGACY;
 exports.R3F_BUILD_WEBGPU = R3F_BUILD_WEBGPU;
 exports.REACT_INTERNAL_PROPS = REACT_INTERNAL_PROPS;
 exports.RESERVED_PROPS = RESERVED_PROPS;
-exports.Scheduler = Scheduler;
 exports.Texture = Texture;
 exports._roots = _roots;
 exports.act = act;
@@ -15262,30 +15120,40 @@ exports.events = createPointerEvents;
 exports.extend = extend;
 exports.findInitialRoot = findInitialRoot;
 exports.flushSync = flushSync;
+exports.fromRef = fromRef;
 exports.getInstanceProps = getInstanceProps;
+exports.getPrimary = getPrimary;
+exports.getPrimaryIds = getPrimaryIds;
 exports.getRootState = getRootState;
-exports.getScheduler = getScheduler;
 exports.getUuidPrefix = getUuidPrefix;
 exports.hasConstructor = hasConstructor;
+exports.hasPrimary = hasPrimary;
 exports.invalidate = invalidate;
 exports.invalidateInstance = invalidateInstance;
 exports.is = is;
 exports.isColorRepresentation = isColorRepresentation;
 exports.isCopyable = isCopyable;
+exports.isFromRef = isFromRef;
 exports.isObject3D = isObject3D;
+exports.isOnce = isOnce;
 exports.isOrthographicCamera = isOrthographicCamera;
 exports.isRef = isRef;
 exports.isRenderer = isRenderer;
 exports.isTexture = isTexture;
 exports.isVectorLike = isVectorLike;
+exports.once = once;
 exports.prepare = prepare;
+exports.presetsObj = presetsObj;
 exports.reconciler = reconciler;
+exports.registerPrimary = registerPrimary;
 exports.removeInteractivity = removeInteractivity;
 exports.resolve = resolve;
 exports.unmountComponentAtNode = unmountComponentAtNode;
+exports.unregisterPrimary = unregisterPrimary;
 exports.updateCamera = updateCamera;
 exports.updateFrustum = updateFrustum;
 exports.useBridge = useBridge;
+exports.useEnvironment = useEnvironment;
 exports.useFrame = useFrame;
 exports.useGraph = useGraph;
 exports.useInstanceHandle = useInstanceHandle;
@@ -15297,3 +15165,4 @@ exports.useStore = useStore;
 exports.useTexture = useTexture;
 exports.useTextures = useTextures;
 exports.useThree = useThree;
+exports.waitForPrimary = waitForPrimary;