@react-three/fiber 10.0.0-canary.c3fa45d → 10.0.0-canary.c5c1a94

package/dist/webgpu/index.mjs

@@ -1,5 +1,5 @@
 import * as webgpu from 'three/webgpu';
-import { RenderTarget, CubeReflectionMapping, EquirectangularReflectionMapping, CubeTextureLoader, Scene, WebGLCubeRenderTarget, HalfFloatType, Color, Frustum, Matrix4, Group, BoxGeometry, MeshBasicNodeMaterial, Mesh, Node, NodeUpdateType, Layers, SRGBColorSpace, RGBAFormat, UnsignedByteType, Vector3, Vector2, TextureLoader, Texture as Texture$1, CanvasTarget, Raycaster, OrthographicCamera, PerspectiveCamera, PCFShadowMap, VSMShadowMap, BasicShadowMap, ACESFilmicToneMapping, WebGPURenderer, Vector4, PostProcessing } from 'three/webgpu';
+import { CubeRenderTarget, RenderTarget, CubeReflectionMapping, EquirectangularReflectionMapping, CubeTextureLoader, Scene, HalfFloatType, Color, Frustum, Matrix4, Group, BoxGeometry, MeshBasicNodeMaterial, Mesh, Node, NodeUpdateType, Layers, ShaderMaterial, Uniform, SRGBColorSpace, RGBAFormat, UnsignedByteType, Vector3, Vector2, TextureLoader, Texture as Texture$1, CanvasTarget, Raycaster, OrthographicCamera, PerspectiveCamera, PCFShadowMap, VSMShadowMap, BasicShadowMap, ACESFilmicToneMapping, WebGPURenderer, Vector4, RenderPipeline } from 'three/webgpu';
 import { Inspector } from 'three/addons/inspector/Inspector.js';
 import { jsx, Fragment, jsxs } from 'react/jsx-runtime';
 import * as React from 'react';
@@ -12,8 +12,10 @@ import { HDRLoader } from 'three/examples/jsm/loaders/HDRLoader.js';
 import { EXRLoader } from 'three/examples/jsm/loaders/EXRLoader.js';
 import { UltraHDRLoader } from 'three/examples/jsm/loaders/UltraHDRLoader.js';
 import { GainMapLoader } from '@monogrid/gainmap-js';
-import Tb, { unstable_scheduleCallback, unstable_IdlePriority } from 'scheduler';
+import Tb, { unstable_getCurrentPriorityLevel, unstable_IdlePriority, unstable_LowPriority, unstable_NormalPriority, unstable_UserBlockingPriority, unstable_ImmediatePriority, unstable_scheduleCallback } from 'scheduler';
 import { createWithEqualityFn } from 'zustand/traditional';
+import { getScheduler } from '@pmndrs/scheduler';
+export { Scheduler, getScheduler } from '@pmndrs/scheduler';
 import { suspend, preload, clear } from 'suspend-react';
 import { dequal } from 'dequal/lite';
 import 'zustand/shallow';
@@ -41,13 +43,16 @@ const WebGLRenderer = class WebGLRenderer2 {
   }
 };
 const WebGLRenderTarget = null;
+const WebGLCubeRenderTarget = null;
 
 const THREE = /*#__PURE__*/_mergeNamespaces({
   __proto__: null,
+  CubeRenderTargetCompat: CubeRenderTarget,
   Inspector: Inspector,
   R3F_BUILD_LEGACY: R3F_BUILD_LEGACY,
   R3F_BUILD_WEBGPU: R3F_BUILD_WEBGPU,
   RenderTargetCompat: RenderTarget,
+  WebGLCubeRenderTarget: WebGLCubeRenderTarget,
   WebGLRenderTarget: WebGLRenderTarget,
   WebGLRenderer: WebGLRenderer
 }, [webgpu]);
@@ -321,15 +326,16 @@ function EnvironmentPortal({
   preset = void 0,
   extensions
 }) {
-  const gl = useThree$1((state) => state.gl);
+  const renderer = useThree$1((state) => state.renderer);
+  const isLegacy = useThree$1((state) => state.isLegacy);
   const defaultScene = useThree$1((state) => state.scene);
   const camera = React.useRef(null);
   const [virtualScene] = React.useState(() => new Scene());
   const fbo = React.useMemo(() => {
-    const fbo2 = new WebGLCubeRenderTarget(resolution);
+    const fbo2 = isLegacy ? new WebGLCubeRenderTarget(resolution) : new CubeRenderTarget(resolution);
     fbo2.texture.type = HalfFloatType;
     return fbo2;
-  }, [resolution]);
+  }, [resolution, isLegacy]);
   React.useEffect(() => {
     return () => {
       fbo.dispose();
@@ -337,10 +343,10 @@ function EnvironmentPortal({
   }, [fbo]);
   React.useLayoutEffect(() => {
     if (frames === 1) {
-      const autoClear = gl.autoClear;
-      gl.autoClear = true;
-      camera.current.update(gl, virtualScene);
-      gl.autoClear = autoClear;
+      const autoClear = renderer.autoClear;
+      renderer.autoClear = true;
+      camera.current.update(renderer, virtualScene);
+      renderer.autoClear = autoClear;
     }
     return setEnvProps(background, scene, defaultScene, fbo.texture, {
       backgroundBlurriness: blur ?? backgroundBlurriness,
@@ -357,7 +363,7 @@ function EnvironmentPortal({
     defaultScene,
     background,
     frames,
-    gl,
+    renderer,
     blur,
     backgroundBlurriness,
     backgroundIntensity,
@@ -368,10 +374,10 @@ function EnvironmentPortal({
   let count = 1;
   useFrame$1(() => {
     if (frames === Infinity || count < frames) {
-      const autoClear = gl.autoClear;
-      gl.autoClear = true;
-      camera.current.update(gl, virtualScene);
-      gl.autoClear = autoClear;
+      const autoClear = renderer.autoClear;
+      renderer.autoClear = true;
+      camera.current.update(renderer, virtualScene);
+      renderer.autoClear = autoClear;
       count++;
     }
   });
@@ -435,10 +441,9 @@ function Environment(props) {
   return props.ground ? /* @__PURE__ */ jsx(EnvironmentGround, { ...props }) : props.map ? /* @__PURE__ */ jsx(EnvironmentMap, { ...props }) : props.children ? /* @__PURE__ */ jsx(EnvironmentPortal, { ...props }) : /* @__PURE__ */ jsx(EnvironmentCube, { ...props });
 }
 
-var __defProp$3 = Object.defineProperty;
-var __defNormalProp$3 = (obj, key, value) => key in obj ? __defProp$3(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
-var __publicField$3 = (obj, key, value) => __defNormalProp$3(obj, typeof key !== "symbol" ? key + "" : key, value);
-const act = React["act"];
+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 useIsomorphicLayoutEffect = /* @__PURE__ */ (() => typeof window !== "undefined" && (window.document?.createElement || window.navigator?.product === "ReactNative"))() ? React.useLayoutEffect : React.useEffect;
 function useMutableCallback(fn) {
   const ref = React.useRef(fn);
@@ -469,7 +474,7 @@ const ErrorBoundary = /* @__PURE__ */ (() => {
   return _a = class extends React.Component {
     constructor() {
       super(...arguments);
-      __publicField$3(this, "state", { error: false });
+      __publicField$1(this, "state", { error: false });
     }
     componentDidCatch(err) {
       this.props.set(err);
@@ -477,7 +482,7 @@ const ErrorBoundary = /* @__PURE__ */ (() => {
     render() {
       return this.state.error ? null : this.props.children;
     }
-  }, __publicField$3(_a, "getDerivedStateFromError", () => ({ error: true })), _a;
+  }, __publicField$1(_a, "getDerivedStateFromError", () => ({ error: true })), _a;
 })();
 
 const is = {
@@ -614,8 +619,7 @@ function prepare(target, root, type, props) {
       object,
       eventCount: 0,
       handlers: {},
-      isHidden: false,
-      deferredRefs: []
+      isHidden: false
     };
     if (object) object.__r3f = instance;
   }
@@ -772,6 +776,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;
@@ -932,9 +947,9 @@ function diffProps(instance, newProps) {
     const { root, key } = resolve(instance.object, prop);
     if (root.constructor && root.constructor.length === 0) {
       const ctor = getMemoizedPrototype(root);
-      if (!is.und(ctor)) changedProps[key] = ctor[key];
+      if (!is.und(ctor)) changedProps[prop] = ctor[key];
     } else {
-      changedProps[key] = 0;
+      changedProps[prop] = 0;
     }
   }
   return changedProps;
@@ -959,10 +974,7 @@ function applyProps(object, props) {
       continue;
     }
     if (value === void 0) continue;
-    if (isFromRef(value)) {
-      instance?.deferredRefs?.push({ prop, ref: value[FROM_REF] });
-      continue;
-    }
+    if (isFromRef(value)) continue;
     if (isOnce(value)) {
       if (instance?.appliedOnce?.has(prop)) continue;
       if (instance) {
@@ -998,6 +1010,19 @@ 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 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 Uniform ? uniform.clone() : new Uniform(uniform.value);
+          uniforms[name] = nextUniform;
+        }
+      }
     } else {
       root[key] = value;
       if (key.endsWith("Node") && root.isMaterial) {
@@ -1016,6 +1041,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,
@@ -1023,7 +1051,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);
     }
@@ -1551,6 +1581,7 @@ 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);
@@ -1637,1229 +1668,206 @@ function notifyAlpha({ message, link }) {
   }
 }
 
-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 DEFAULT_PHASES = ["start", "input", "physics", "update", "render", "finish"];
-class PhaseGraph {
-  constructor() {
-    /** Ordered list of phase nodes */
-    __publicField$2(this, "phases", []);
-    /** Quick lookup by name */
-    __publicField$2(this, "phaseMap", /* @__PURE__ */ new Map());
-    /** Cached ordered names (invalidated on changes) */
-    __publicField$2(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;
-  }
+const INTERNAL_LIB_MARKERS = ["zustand", "setState", "Object.assign"];
+function isInternalRendererAccess(stack, callerDepth = 2) {
+  if (!stack) return false;
+  const caller = stack.split("\n")[callerDepth] ?? "";
+  return INTERNAL_LIB_MARKERS.some((m) => caller.includes(m));
 }
 
-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);
+const R3F_CONTEXT = Symbol.for("@react-three/fiber.context");
+const context = globalThis[R3F_CONTEXT] ?? (globalThis[R3F_CONTEXT] = React.createContext(null));
+const createStore = (invalidate, advance) => {
+  const rootStore = createWithEqualityFn((set, get) => {
+    const position = new Vector3();
+    const defaultTarget = new Vector3();
+    const tempTarget = new Vector3();
+    function getCurrentViewport(camera = get().camera, target = defaultTarget, size = get().size) {
+      const { width, height, top, left } = size;
+      const aspect = width / height;
+      if (target.isVector3) tempTarget.copy(target);
+      else tempTarget.set(...target);
+      const distance = camera.getWorldPosition(position).distanceTo(tempTarget);
+      if (isOrthographicCamera(camera)) {
+        return { width: width / camera.zoom, height: height / camera.zoom, top, left, factor: 1, distance, aspect };
+      } else {
+        const fov = camera.fov * Math.PI / 180;
+        const h = 2 * Math.tan(fov / 2) * distance;
+        const w = h * (width / height);
+        return { width: w, height: h, top, left, factor: width / w, distance, aspect };
       }
     }
-    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);
+    let performanceTimeout = void 0;
+    const setPerformanceCurrent = (current) => set((state2) => ({ performance: { ...state2.performance, current } }));
+    const pointer = new Vector2();
+    const rootState = {
+      set,
+      get,
+      // Mock objects that have to be configured
+      // primaryStore is set after store creation (self-reference for primary, primary's store for secondary)
+      primaryStore: null,
+      gl: null,
+      renderer: null,
+      camera: null,
+      frustum: new Frustum(),
+      autoUpdateFrustum: true,
+      raycaster: null,
+      events: {
+        priority: 1,
+        enabled: true,
+        connected: false,
+        frameTimedRaycasts: true,
+        alwaysFireOnScroll: true,
+        updateOnFrame: false
+      },
+      scene: null,
+      rootScene: null,
+      xr: null,
+      inspector: null,
+      invalidate: (frames = 1, stackFrames = false) => invalidate(get(), frames, stackFrames),
+      advance: (timestamp, runGlobalEffects) => advance(timestamp, runGlobalEffects, get()),
+      textureColorSpace: SRGBColorSpace,
+      isLegacy: false,
+      webGPUSupported: false,
+      isNative: false,
+      controls: null,
+      pointer,
+      mouse: pointer,
+      frameloop: "always",
+      onPointerMissed: void 0,
+      onDragOverMissed: void 0,
+      onDropMissed: void 0,
+      performance: {
+        current: 1,
+        min: 0.5,
+        max: 1,
+        debounce: 200,
+        regress: () => {
+          const state2 = get();
+          if (performanceTimeout) clearTimeout(performanceTimeout);
+          if (state2.performance.current !== state2.performance.min) setPerformanceCurrent(state2.performance.min);
+          performanceTimeout = setTimeout(
+            () => setPerformanceCurrent(get().performance.max),
+            state2.performance.debounce
+          );
+        }
+      },
+      size: { width: 0, height: 0, top: 0, left: 0 },
+      viewport: {
+        initialDpr: 0,
+        dpr: 0,
+        width: 0,
+        height: 0,
+        top: 0,
+        left: 0,
+        aspect: 0,
+        distance: 0,
+        factor: 0,
+        getCurrentViewport
+      },
+      setEvents: (events) => set((state2) => ({ ...state2, events: { ...state2.events, ...events } })),
+      setSize: (width, height, top, left) => {
+        const state2 = get();
+        if (width === void 0) {
+          set({ _sizeImperative: false });
+          if (state2._sizeProps) {
+            const { width: propW, height: propH } = state2._sizeProps;
+            if (propW !== void 0 || propH !== void 0) {
+              const currentSize = state2.size;
+              const newSize = {
+                width: propW ?? currentSize.width,
+                height: propH ?? currentSize.height,
+                top: currentSize.top,
+                left: currentSize.left
+              };
+              set((s) => ({
+                size: newSize,
+                viewport: { ...s.viewport, ...getCurrentViewport(state2.camera, defaultTarget, newSize) }
+              }));
+              getScheduler().invalidate();
+            }
+          }
+          return;
+        }
+        const w = width;
+        const h = height ?? width;
+        const t = top ?? state2.size.top;
+        const l = left ?? state2.size.left;
+        const size = { width: w, height: h, top: t, left: l };
+        set((s) => ({
+          size,
+          viewport: { ...s.viewport, ...getCurrentViewport(state2.camera, defaultTarget, size) },
+          _sizeImperative: true
+        }));
+        getScheduler().invalidate();
+      },
+      setDpr: (dpr) => set((state2) => {
+        const resolved = calculateDpr(dpr);
+        return { viewport: { ...state2.viewport, dpr: resolved, initialDpr: state2.viewport.initialDpr || resolved } };
+      }),
+      setFrameloop: (frameloop = "always") => {
+        set(() => ({ frameloop }));
+        getScheduler().frameloop = frameloop;
+      },
+      setError: (error) => set(() => ({ error })),
+      error: null,
+      //* TSL State (managed via hooks: useUniforms, useNodes, useBuffers, useGPUStorage, useTextures, useRenderPipeline) ==============================
+      uniforms: {},
+      nodes: {},
+      buffers: {},
+      gpuStorage: {},
+      textures: /* @__PURE__ */ new Map(),
+      _textureRefs: /* @__PURE__ */ new Map(),
+      renderPipeline: null,
+      passes: {},
+      _hmrVersion: 0,
+      _sizeImperative: false,
+      _sizeProps: null,
+      previousRoot: void 0,
+      internal: {
+        // Events
+        interaction: [],
+        subscribers: [],
+        // Per-pointer state (new unified structure)
+        pointerMap: /* @__PURE__ */ new Map(),
+        pointerDirty: /* @__PURE__ */ new Map(),
+        lastEvent: React.createRef(),
+        // Deprecated but kept for backwards compatibility
+        hovered: /* @__PURE__ */ new Map(),
+        initialClick: [0, 0],
+        initialHits: [],
+        capturedMap: /* @__PURE__ */ new Map(),
+        // Visibility tracking (onFramed, onOccluded, onVisible)
+        visibilityRegistry: /* @__PURE__ */ new Map(),
+        // Occlusion system (WebGPU only)
+        occlusionEnabled: false,
+        occlusionObserver: null,
+        occlusionCache: /* @__PURE__ */ new Map(),
+        helperGroup: null,
+        // Updates
+        active: false,
+        frames: 0,
+        priority: 0,
+        subscribe: (ref, priority, store) => {
+          const internal = get().internal;
+          internal.priority = internal.priority + (priority > 0 ? 1 : 0);
+          internal.subscribers.push({ ref, priority, store });
+          internal.subscribers = internal.subscribers.sort((a, b) => a.priority - b.priority);
+          return () => {
+            const internal2 = get().internal;
+            if (internal2?.subscribers) {
+              internal2.priority = internal2.priority - (priority > 0 ? 1 : 0);
+              internal2.subscribers = internal2.subscribers.filter((s) => s.ref !== ref);
+            }
+          };
+        },
+        // Renderer Storage (single source of truth)
+        actualRenderer: null,
+        // Scheduler for useFrameNext (initialized in renderer.tsx)
+        scheduler: null
       }
-    }
-  }
-  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 - 1) 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$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 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$1(this, "roots", /* @__PURE__ */ new Map());
-    __publicField$1(this, "phaseGraph");
-    __publicField$1(this, "loopState", {
-      running: false,
-      rafHandle: null,
-      lastTime: null,
-      // null = uninitialized, 0+ = valid timestamp
-      frameCount: 0,
-      elapsedTime: 0,
-      createdAt: performance.now()
-    });
-    __publicField$1(this, "stoppedTime", 0);
-    //* Private State ================================
-    __publicField$1(this, "nextRootIndex", 0);
-    __publicField$1(this, "globalBeforeJobs", /* @__PURE__ */ new Map());
-    __publicField$1(this, "globalAfterJobs", /* @__PURE__ */ new Map());
-    __publicField$1(this, "nextGlobalIndex", 0);
-    __publicField$1(this, "idleCallbacks", /* @__PURE__ */ new Set());
-    __publicField$1(this, "nextJobIndex", 0);
-    __publicField$1(this, "jobStateListeners", /* @__PURE__ */ new Map());
-    __publicField$1(this, "pendingFrames", 0);
-    __publicField$1(this, "_frameloop", "always");
-    //* Independent Mode & Error Handling State ================================
-    __publicField$1(this, "_independent", false);
-    __publicField$1(this, "errorHandler", null);
-    __publicField$1(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$1(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$1(_Scheduler, "INSTANCE_KEY", Symbol.for("@react-three/fiber.scheduler"));
-let Scheduler = _Scheduler;
-const getScheduler = () => Scheduler.get();
-if (hmrData) {
-  hmrData.accept?.();
-}
-
-const R3F_CONTEXT = Symbol.for("@react-three/fiber.context");
-const context = globalThis[R3F_CONTEXT] ?? (globalThis[R3F_CONTEXT] = React.createContext(null));
-const createStore = (invalidate, advance) => {
-  const rootStore = createWithEqualityFn((set, get) => {
-    const position = new Vector3();
-    const defaultTarget = new Vector3();
-    const tempTarget = new Vector3();
-    function getCurrentViewport(camera = get().camera, target = defaultTarget, size = get().size) {
-      const { width, height, top, left } = size;
-      const aspect = width / height;
-      if (target.isVector3) tempTarget.copy(target);
-      else tempTarget.set(...target);
-      const distance = camera.getWorldPosition(position).distanceTo(tempTarget);
-      if (isOrthographicCamera(camera)) {
-        return { width: width / camera.zoom, height: height / camera.zoom, top, left, factor: 1, distance, aspect };
-      } else {
-        const fov = camera.fov * Math.PI / 180;
-        const h = 2 * Math.tan(fov / 2) * distance;
-        const w = h * (width / height);
-        return { width: w, height: h, top, left, factor: width / w, distance, aspect };
-      }
-    }
-    let performanceTimeout = void 0;
-    const setPerformanceCurrent = (current) => set((state2) => ({ performance: { ...state2.performance, current } }));
-    const pointer = new Vector2();
-    const rootState = {
-      set,
-      get,
-      // Mock objects that have to be configured
-      // primaryStore is set after store creation (self-reference for primary, primary's store for secondary)
-      primaryStore: null,
-      gl: null,
-      renderer: null,
-      camera: null,
-      frustum: new Frustum(),
-      autoUpdateFrustum: true,
-      raycaster: null,
-      events: {
-        priority: 1,
-        enabled: true,
-        connected: false,
-        frameTimedRaycasts: true,
-        alwaysFireOnScroll: true,
-        updateOnFrame: false
-      },
-      scene: null,
-      rootScene: null,
-      xr: null,
-      inspector: null,
-      invalidate: (frames = 1, stackFrames = false) => invalidate(get(), frames, stackFrames),
-      advance: (timestamp, runGlobalEffects) => advance(timestamp, runGlobalEffects, get()),
-      textureColorSpace: SRGBColorSpace,
-      isLegacy: false,
-      webGPUSupported: false,
-      isNative: false,
-      controls: null,
-      pointer,
-      mouse: pointer,
-      frameloop: "always",
-      onPointerMissed: void 0,
-      onDragOverMissed: void 0,
-      onDropMissed: void 0,
-      performance: {
-        current: 1,
-        min: 0.5,
-        max: 1,
-        debounce: 200,
-        regress: () => {
-          const state2 = get();
-          if (performanceTimeout) clearTimeout(performanceTimeout);
-          if (state2.performance.current !== state2.performance.min) setPerformanceCurrent(state2.performance.min);
-          performanceTimeout = setTimeout(
-            () => setPerformanceCurrent(get().performance.max),
-            state2.performance.debounce
-          );
-        }
-      },
-      size: { width: 0, height: 0, top: 0, left: 0 },
-      viewport: {
-        initialDpr: 0,
-        dpr: 0,
-        width: 0,
-        height: 0,
-        top: 0,
-        left: 0,
-        aspect: 0,
-        distance: 0,
-        factor: 0,
-        getCurrentViewport
-      },
-      setEvents: (events) => set((state2) => ({ ...state2, events: { ...state2.events, ...events } })),
-      setSize: (width, height, top, left) => {
-        const state2 = get();
-        if (width === void 0) {
-          set({ _sizeImperative: false });
-          if (state2._sizeProps) {
-            const { width: propW, height: propH } = state2._sizeProps;
-            if (propW !== void 0 || propH !== void 0) {
-              const currentSize = state2.size;
-              const newSize = {
-                width: propW ?? currentSize.width,
-                height: propH ?? currentSize.height,
-                top: currentSize.top,
-                left: currentSize.left
-              };
-              set((s) => ({
-                size: newSize,
-                viewport: { ...s.viewport, ...getCurrentViewport(state2.camera, defaultTarget, newSize) }
-              }));
-              getScheduler().invalidate();
-            }
-          }
-          return;
-        }
-        const w = width;
-        const h = height ?? width;
-        const t = top ?? state2.size.top;
-        const l = left ?? state2.size.left;
-        const size = { width: w, height: h, top: t, left: l };
-        set((s) => ({
-          size,
-          viewport: { ...s.viewport, ...getCurrentViewport(state2.camera, defaultTarget, size) },
-          _sizeImperative: true
-        }));
-        getScheduler().invalidate();
-      },
-      setDpr: (dpr) => set((state2) => {
-        const resolved = calculateDpr(dpr);
-        return { viewport: { ...state2.viewport, dpr: resolved, initialDpr: state2.viewport.initialDpr || resolved } };
-      }),
-      setFrameloop: (frameloop = "always") => {
-        set(() => ({ frameloop }));
-      },
-      setError: (error) => set(() => ({ error })),
-      error: null,
-      //* TSL State (managed via hooks: useUniforms, useNodes, useBuffers, useGPUStorage, useTextures, useRenderPipeline) ==============================
-      uniforms: {},
-      nodes: {},
-      buffers: {},
-      gpuStorage: {},
-      textures: /* @__PURE__ */ new Map(),
-      renderPipeline: null,
-      passes: {},
-      _hmrVersion: 0,
-      _sizeImperative: false,
-      _sizeProps: null,
-      previousRoot: void 0,
-      internal: {
-        // Events
-        interaction: [],
-        subscribers: [],
-        // Per-pointer state (new unified structure)
-        pointerMap: /* @__PURE__ */ new Map(),
-        pointerDirty: /* @__PURE__ */ new Map(),
-        lastEvent: React.createRef(),
-        // Deprecated but kept for backwards compatibility
-        hovered: /* @__PURE__ */ new Map(),
-        initialClick: [0, 0],
-        initialHits: [],
-        capturedMap: /* @__PURE__ */ new Map(),
-        // Visibility tracking (onFramed, onOccluded, onVisible)
-        visibilityRegistry: /* @__PURE__ */ new Map(),
-        // Occlusion system (WebGPU only)
-        occlusionEnabled: false,
-        occlusionObserver: null,
-        occlusionCache: /* @__PURE__ */ new Map(),
-        helperGroup: null,
-        // Updates
-        active: false,
-        frames: 0,
-        priority: 0,
-        subscribe: (ref, priority, store) => {
-          const internal = get().internal;
-          internal.priority = internal.priority + (priority > 0 ? 1 : 0);
-          internal.subscribers.push({ ref, priority, store });
-          internal.subscribers = internal.subscribers.sort((a, b) => a.priority - b.priority);
-          return () => {
-            const internal2 = get().internal;
-            if (internal2?.subscribers) {
-              internal2.priority = internal2.priority - (priority > 0 ? 1 : 0);
-              internal2.subscribers = internal2.subscribers.filter((s) => s.ref !== ref);
-            }
-          };
-        },
-        // Renderer Storage (single source of truth)
-        actualRenderer: null,
-        // Scheduler for useFrameNext (initialized in renderer.tsx)
-        scheduler: null
-      }
-    };
-    return rootState;
+    };
+    return rootState;
   });
   const state = rootStore.getState();
   Object.defineProperty(state, "gl", {
@@ -2867,8 +1875,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",
@@ -2981,19 +1988,25 @@ 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) => suspend(fn, [loader, key], { equal: is.equ }));
+  const results = cacheKeys.map(
+    (key, index) => 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) => 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) => preload(() => loadingFn(extensions, onProgress)(loader, inputs[index]), [loader, key])
+  );
 };
-useLoader.clear = function(loader, input) {
-  const keys = Array.isArray(input) ? input : [input];
-  keys.forEach((key) => clear([loader, key]));
+useLoader.clear = function(loader, input, cacheKey) {
+  const cacheKeys = Array.isArray(cacheKey ?? input) ? cacheKey ?? input : [cacheKey ?? input];
+  cacheKeys.forEach((key) => clear([loader, key]));
 };
 useLoader.loader = getLoader;
 
@@ -3069,20 +2082,14 @@ 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.register(
+        (state, delta) => {
+          const frameState = state;
+          if (!frameState.renderer) return;
+          callbackRef.current?.(frameState, delta);
+        },
+        { id, ...options }
+      );
     }
   }, [store, scheduler, id, optionsKey, isLegacyPriority, isInsideCanvas]);
   const isPaused = React.useSyncExternalStore(
@@ -3173,18 +2180,18 @@ 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 = useRef(onLoad);
   onLoadRef.current = onLoad;
   const onLoadCalledForRef = useRef(null);
   const urls = useMemo(() => getUrls(input), [input]);
   const cachedResult = 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(
     TextureLoader,
     IsObject(input) ? Object.values(input) : input
@@ -3228,8 +2235,6 @@ function useTexture(input, optionsOrOnLoad) {
   }, [input, loadedTextures, cachedResult]);
   useEffect(() => {
     if (!cache) return;
-    if (cachedResult) return;
-    const set = store.setState;
     const urlTextureMap = [];
     if (typeof input === "string") {
       urlTextureMap.push([input, mappedTextures]);
@@ -3243,18 +2248,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 };
     });
-  }, [cache, input, mappedTextures, store, cachedResult]);
+    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]);
   return mappedTextures;
 }
 useTexture.preload = (url) => useLoader.preload(TextureLoader, url);
@@ -3270,96 +2289,63 @@ const Texture = ({
   return /* @__PURE__ */ jsx(Fragment, { children: children?.(ret) });
 };
 
-function getTextureValue(entry) {
-  if (entry instanceof Texture$1) return entry;
-  if (entry && typeof entry === "object" && "value" in entry && entry.value instanceof Texture$1) {
-    return entry.value;
-  }
-  return null;
-}
-function useTextures() {
+function useTextures(selector) {
   const store = useStore();
-  return useMemo(() => {
-    const set = store.setState;
+  const registry = 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(widthOrOptions, heightOrOptions, options) {
@@ -3440,7 +2426,7 @@ function advance(timestamp) {
   getScheduler().step(timestamp);
 }
 
-const version = "10.0.0-alpha.2";
+const version = "10.0.0-alpha.3";
 const packageData = {
 	version: version};
 
@@ -14696,7 +13682,7 @@ function n0() {
 var t0 = n0();
 const r0 = Xb(t0);
 
-const t = 1, o = 8, r = 32, e = 2;
+const t = 1, o = 8, r = 32, e = 2, i$1 = 268435456;
 
 function createReconciler(config) {
   const reconciler2 = r0(config);
@@ -14861,7 +13847,15 @@ function setFiberRef(fiber, publicInstance) {
   }
 }
 const reconstructed = [];
-function swapInstances() {
+function flushReconstructedInstances() {
+  if (reconstructed.length === 0) return;
+  try {
+    swapReconstructedInstances();
+  } finally {
+    reconstructed.length = 0;
+  }
+}
+function swapReconstructedInstances() {
   for (const [instance] of reconstructed) {
     const parent = instance.parent;
     if (parent) {
@@ -14879,6 +13873,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);
   }
@@ -14891,6 +13886,8 @@ function swapInstances() {
       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);
@@ -14907,14 +13904,114 @@ function swapInstances() {
       invalidateInstance(instance);
     }
   }
-  reconstructed.length = 0;
 }
 const handleTextInstance = () => {
 };
 const NO_CONTEXT = {};
 let currentUpdatePriority = NoEventPriority;
-const NoFlags = 0;
-const Update = 4;
+function getEventPriority(type) {
+  switch (type) {
+    case "beforetoggle":
+    case "cancel":
+    case "click":
+    case "close":
+    case "contextmenu":
+    case "copy":
+    case "cut":
+    case "auxclick":
+    case "dblclick":
+    case "dragend":
+    case "dragstart":
+    case "drop":
+    case "focusin":
+    case "focusout":
+    case "input":
+    case "invalid":
+    case "keydown":
+    case "keypress":
+    case "keyup":
+    case "mousedown":
+    case "mouseup":
+    case "paste":
+    case "pause":
+    case "play":
+    case "pointercancel":
+    case "pointerdown":
+    case "pointerup":
+    case "ratechange":
+    case "reset":
+    case "resize":
+    case "seeked":
+    case "submit":
+    case "touchcancel":
+    case "touchend":
+    case "touchstart":
+    case "volumechange":
+    case "change":
+    case "selectionchange":
+    case "compositionstart":
+    case "compositionend":
+    case "compositionupdate":
+    case "beforeinput":
+    case "blur":
+    case "fullscreenchange":
+    case "focus":
+    case "hashchange":
+    case "popstate":
+    case "select":
+    case "selectstart":
+      return e;
+    case "drag":
+    case "dragenter":
+    case "dragexit":
+    case "dragleave":
+    case "dragover":
+    case "mousemove":
+    case "mouseout":
+    case "mouseover":
+    case "pointermove":
+    case "pointerout":
+    case "pointerover":
+    case "scroll":
+    case "touchmove":
+    case "wheel":
+    case "mouseenter":
+    case "mouseleave":
+    case "pointerenter":
+    case "pointerleave":
+      return o;
+    case "message": {
+      switch (unstable_getCurrentPriorityLevel()) {
+        case unstable_ImmediatePriority:
+          return e;
+        case unstable_UserBlockingPriority:
+          return o;
+        case unstable_NormalPriority:
+        case unstable_LowPriority:
+          return r;
+        case unstable_IdlePriority:
+          return i$1;
+        default:
+          return r;
+      }
+    }
+    default:
+      return r;
+  }
+}
+function scheduleMicrotask(callback) {
+  if (typeof queueMicrotask === "function") {
+    queueMicrotask(callback);
+  } else if (typeof Promise !== "undefined") {
+    Promise.resolve().then(callback).catch((error) => {
+      setTimeout(() => {
+        throw error;
+      });
+    });
+  } else {
+    setTimeout(callback);
+  }
+}
 const reconciler = /* @__PURE__ */ createReconciler({
   isPrimaryRenderer: false,
   warnsIfNotActing: false,
@@ -14953,16 +14050,15 @@ const reconciler = /* @__PURE__ */ createReconciler({
     else if (newProps.args?.length !== oldProps.args?.length) reconstruct = true;
     else if (newProps.args?.some((value, index) => value !== oldProps.args?.[index])) reconstruct = true;
     if (reconstruct) {
-      reconstructed.push([instance, { ...newProps }, fiber]);
+      reconstructed.push([instance, getInstanceProps(newProps), fiber]);
     } else {
       const changedProps = diffProps(instance, newProps);
-      if (Object.keys(changedProps).length) {
-        Object.assign(instance.props, changedProps);
-        applyProps(instance.object, changedProps);
-      }
+      const attach2 = instance.props.attach;
+      instance.props = getInstanceProps(newProps);
+      if (attach2 !== void 0) instance.props.attach = attach2;
+      else delete instance.props.attach;
+      if (Object.keys(changedProps).length) applyProps(instance.object, changedProps);
     }
-    const isTailSibling = fiber.sibling === null || (fiber.flags & Update) === NoFlags;
-    if (isTailSibling) swapInstances();
   },
   finalizeInitialChildren: (instance) => {
     for (const prop in instance.props) {
@@ -14987,8 +14083,9 @@ const reconciler = /* @__PURE__ */ createReconciler({
     const target = container.getState().internal.container ?? container.getState().scene;
     return prepare(target, container, "", {});
   },
-  resetAfterCommit: () => {
-  },
+  // Reconstructed instances are swapped once all mutations are committed,
+  // before layout effects run so refs point to the new objects
+  resetAfterCommit: flushReconstructedInstances,
   shouldSetTextContent: () => false,
   clearContainer: () => false,
   hideInstance,
@@ -14996,6 +14093,9 @@ const reconciler = /* @__PURE__ */ createReconciler({
   createTextInstance: handleTextInstance,
   hideTextInstance: handleTextInstance,
   unhideTextInstance: handleTextInstance,
+  // Mirrors react-dom, which flushes discrete work in microtasks
+  supportsMicrotasks: true,
+  scheduleMicrotask,
   scheduleTimeout: typeof setTimeout === "function" ? setTimeout : void 0,
   cancelTimeout: typeof clearTimeout === "function" ? clearTimeout : void 0,
   noTimeout: -1,
@@ -15036,28 +14136,9 @@ const reconciler = /* @__PURE__ */ createReconciler({
   },
   resolveUpdatePriority() {
     if (currentUpdatePriority !== NoEventPriority) return currentUpdatePriority;
-    switch (typeof window !== "undefined" && window.event?.type) {
-      case "click":
-      case "contextmenu":
-      case "dblclick":
-      case "dragenter":
-      case "dragleave":
-      case "drop":
-      case "pointercancel":
-      case "pointerdown":
-      case "pointerup":
-        return e;
-      case "dragover":
-      case "pointermove":
-      case "pointerout":
-      case "pointerover":
-      case "pointerenter":
-      case "pointerleave":
-      case "wheel":
-        return o;
-      default:
-        return r;
-    }
+    const eventType = typeof window !== "undefined" ? window.event?.type : void 0;
+    if (eventType === void 0) return r;
+    return getEventPriority(eventType);
   },
   resetFormInstance() {
   },
@@ -15106,11 +14187,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,
@@ -15195,6 +14280,7 @@ function createRoot(canvas) {
   const lastConfiguredProps = {};
   let configured = false;
   let pending = null;
+  let rendererSetup = null;
   return {
     async configure(props = {}) {
       let resolve;
@@ -15225,7 +14311,7 @@ function createRoot(canvas) {
         forceEven
       } = props;
       const textureColorSpace = is.obj(glConfig) && !is.fun(glConfig) && !isRenderer(glConfig) && glConfig.textureColorSpace || is.obj(rendererConfig) && !is.fun(rendererConfig) && !isRenderer(rendererConfig) && rendererConfig.textureColorSpace || SRGBColorSpace;
-      const state = store.getState();
+      let state = store.getState();
       const defaultGPUProps = {
         canvas,
         antialias: true
@@ -15239,52 +14325,64 @@ function createRoot(canvas) {
         throw new Error("Cannot use both gl and renderer props at the same time");
       }
       let renderer = state.internal.actualRenderer;
-      if (primaryCanvas && !state.internal.actualRenderer) {
-        const primary = await waitForPrimary(primaryCanvas);
-        renderer = primary.renderer;
-        state.internal.actualRenderer = renderer;
-        const canvasTarget = new 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 (!state.internal.actualRenderer) {
-        renderer = await resolveRenderer(rendererConfig, defaultGPUProps, 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 CanvasTarget(canvas);
-          const unregisterPrimary = registerPrimary(canvasId, renderer, store);
-          state.set((prev) => ({
-            internal: {
-              ...prev.internal,
-              canvasTarget,
-              unregisterPrimary
+      if (!state.internal.actualRenderer) {
+        if (!rendererSetup) {
+          rendererSetup = (async () => {
+            if (primaryCanvas) {
+              const primary = await waitForPrimary(primaryCanvas);
+              renderer = primary.renderer;
+              state.internal.actualRenderer = renderer;
+              const canvasTarget = new 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 {
+              renderer = await resolveRenderer(rendererConfig, defaultGPUProps, 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 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 Raycaster() });
@@ -15509,7 +14607,7 @@ function createRoot(canvas) {
           {
             id: `${newRootId}_frustum`,
             rootId: newRootId,
-            phase: "preRender",
+            before: "render",
             system: true
           }
         );
@@ -15521,7 +14619,7 @@ function createRoot(canvas) {
           {
             id: `${newRootId}_visibility`,
             rootId: newRootId,
-            phase: "preRender",
+            before: "render",
             system: true,
             after: `${newRootId}_frustum`
           }
@@ -15634,7 +14732,8 @@ function unmountComponentAtNode(canvas, callback) {
             dispose(state.scene);
             _roots.delete(canvas);
             if (callback) callback(canvas);
-          } catch {
+          } catch (error) {
+            console.warn("[R3F] Error while unmounting root; teardown may be incomplete:", error);
           }
         }, 500);
       }
@@ -15697,6 +14796,7 @@ function PortalInner({ state = {}, children, container }) {
       viewport = rootState.viewport.getCurrentViewport(camera, new Vector3(), resolvedSize);
       if (camera !== rootState.camera) updateCamera(camera, resolvedSize);
     }
+    const set = injectState.set;
     return {
       // The intersect consists of the previous root state
       ...rootState,
@@ -15715,33 +14815,205 @@ function PortalInner({ state = {}, children, container }) {
       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 }
     };
   });
-  const usePortalStore = useMemo(() => {
-    const store = createWithEqualityFn((set, get) => ({ ...rest, set, get }));
-    const onMutate = (prev) => store.setState((state2) => inject.current(prev, state2));
-    onMutate(previousRoot.getState());
-    return store;
-  }, [previousRoot, container]);
-  useIsomorphicLayoutEffect(() => {
-    const onMutate = (prev) => usePortalStore.setState((state2) => inject.current(prev, state2));
-    const unsubscribe = previousRoot.subscribe(onMutate);
-    return unsubscribe;
-  }, [previousRoot, usePortalStore]);
-  return (
-    // @ts-ignore, reconciler types are not maintained
-    /* @__PURE__ */ jsx(Fragment, { children: reconciler.createPortal(
-      /* @__PURE__ */ jsx(context.Provider, { value: usePortalStore, children }),
-      usePortalStore,
-      null
-    ) })
-  );
+  const usePortalStore = useMemo(() => {
+    const store = createWithEqualityFn((set, get) => ({ ...rest, set, get }));
+    const onMutate = (prev) => store.setState((state2) => inject.current(prev, state2));
+    onMutate(previousRoot.getState());
+    return store;
+  }, [previousRoot, container]);
+  useIsomorphicLayoutEffect(() => {
+    const onMutate = (prev) => usePortalStore.setState((state2) => inject.current(prev, state2));
+    const unsubscribe = previousRoot.subscribe(onMutate);
+    return unsubscribe;
+  }, [previousRoot, usePortalStore]);
+  return (
+    // @ts-ignore, reconciler types are not maintained
+    /* @__PURE__ */ jsx(Fragment, { children: reconciler.createPortal(
+      /* @__PURE__ */ jsx(context.Provider, { value: usePortalStore, children }),
+      usePortalStore,
+      null
+    ) })
+  );
+}
+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 };
+}
+
+const RESOURCE_KINDS = ["nodes", "uniforms", "buffers", "gpuStorage"];
+const ROOT_SCOPE = "";
+const registries = /* @__PURE__ */ new WeakMap();
+function getKindRegistry(store, kind) {
+  let registry = registries.get(store);
+  if (!registry) {
+    registry = {
+      nodes: { valid: /* @__PURE__ */ new Set(), staged: /* @__PURE__ */ new Map() },
+      uniforms: { valid: /* @__PURE__ */ new Set(), staged: /* @__PURE__ */ new Map() },
+      buffers: { valid: /* @__PURE__ */ new Set(), staged: /* @__PURE__ */ new Map() },
+      gpuStorage: { valid: /* @__PURE__ */ new Set(), staged: /* @__PURE__ */ new Map() }
+    };
+    registries.set(store, registry);
+  }
+  return registry[kind];
+}
+function resolvePrimary$1(store) {
+  return store.getState().primaryStore ?? store;
+}
+function isScopeValid(store, kind, scopeKey) {
+  return getKindRegistry(store, kind).valid.has(scopeKey);
+}
+function peekStaged(store, kind, scopeKey) {
+  return getKindRegistry(store, kind).staged.get(scopeKey);
+}
+function stageEntries(store, kind, scopeKey, entries) {
+  const { staged } = getKindRegistry(store, kind);
+  const current = staged.get(scopeKey);
+  if (current) Object.assign(current, entries);
+  else staged.set(scopeKey, { ...entries });
+}
+function readCommittedScope(map, scopeKey, isLeaf) {
+  if (scopeKey === ROOT_SCOPE) {
+    const leaves = {};
+    for (const [key, value] of Object.entries(map)) if (isLeaf(value)) leaves[key] = value;
+    return leaves;
+  }
+  const scopeData = map[scopeKey];
+  if (scopeData && typeof scopeData === "object" && !isLeaf(scopeData)) return scopeData;
+  return {};
+}
+function withStagedOverlay(store, kind, committed) {
+  const { staged } = getKindRegistry(store, kind);
+  if (staged.size === 0) return committed;
+  const view = { ...committed };
+  for (const [scopeKey, entries] of staged) {
+    if (scopeKey === ROOT_SCOPE) Object.assign(view, entries);
+    else view[scopeKey] = { ...view[scopeKey], ...entries };
+  }
+  return view;
+}
+function flushStagedScope(store, kind, scopeKey, isLeaf) {
+  const registry = getKindRegistry(store, kind);
+  const staged = registry.staged.get(scopeKey);
+  if (!staged) return;
+  registry.staged.delete(scopeKey);
+  const replace = !registry.valid.has(scopeKey);
+  store.setState((state) => {
+    const map = state[kind];
+    if (scopeKey === ROOT_SCOPE) {
+      if (!replace) return { [kind]: { ...map, ...staged } };
+      const next = {};
+      for (const [key, value] of Object.entries(map)) if (!isLeaf(value)) next[key] = value;
+      return { [kind]: { ...next, ...staged } };
+    }
+    const current = replace ? {} : map[scopeKey] ?? {};
+    return { [kind]: { ...map, [scopeKey]: { ...current, ...staged } } };
+  });
+  registry.valid.add(scopeKey);
+}
+function invalidateResource(store, kind, scopeKey) {
+  const registry = getKindRegistry(store, kind);
+  if (scopeKey === void 0) {
+    registry.valid.clear();
+    registry.staged.clear();
+  } else {
+    registry.valid.delete(scopeKey);
+    registry.staged.delete(scopeKey);
+  }
+}
+function rebuildResource(store, kind, userScope) {
+  const primary = resolvePrimary$1(store);
+  invalidateResource(primary, kind, userScope === "root" ? ROOT_SCOPE : userScope);
+  primary.setState((state) => ({ _hmrVersion: state._hmrVersion + 1 }));
+}
+function invalidateAllResources(store) {
+  for (const kind of RESOURCE_KINDS) invalidateResource(store, kind);
+}
+function removeResourceEntries(store, kind, names, scope, isLeaf) {
+  const staged = peekStaged(store, kind, scope ?? ROOT_SCOPE);
+  if (staged) for (const name of names) delete staged[name];
+  store.setState((state) => {
+    const map = state[kind];
+    if (scope) {
+      const currentScope = { ...map[scope] };
+      for (const name of names) delete currentScope[name];
+      return { [kind]: { ...map, [scope]: currentScope } };
+    }
+    const next = { ...map };
+    for (const name of names) if (isLeaf(next[name])) delete next[name];
+    return { [kind]: next };
+  });
 }
-function flushSync(fn) {
-  return reconciler.flushSyncFromReconciler(fn);
+function clearResourceEntries(store, kind, scope, isLeaf) {
+  const registry = getKindRegistry(store, kind);
+  if (scope && scope !== "root") registry.staged.delete(scope);
+  else if (scope === "root") registry.staged.delete(ROOT_SCOPE);
+  else registry.staged.clear();
+  store.setState((state) => {
+    const map = state[kind];
+    if (scope && scope !== "root") {
+      const { [scope]: _, ...rest } = map;
+      return { [kind]: rest };
+    }
+    if (scope === "root") {
+      const next = {};
+      for (const [key, value] of Object.entries(map)) if (!isLeaf(value)) next[key] = value;
+      return { [kind]: next };
+    }
+    return { [kind]: {} };
+  });
+}
+
+function clearHmrCaches(store) {
+  const primary = store.getState().primaryStore ?? store;
+  invalidateAllResources(primary);
+  primary.setState((state) => ({ _hmrVersion: state._hmrVersion + 1 }));
 }
 
 function CanvasImpl({
@@ -15764,6 +15036,8 @@ function CanvasImpl({
   raycaster,
   camera,
   scene,
+  autoUpdateFrustum,
+  occlusion,
   onPointerMissed,
   onDragOverMissed,
   onDropMissed,
@@ -15775,49 +15049,10 @@ function CanvasImpl({
   forceEven,
   ...props
 }) {
-  const isRendererConfig = typeof rendererProp === "object" && rendererProp !== null && !("render" in rendererProp) && ("primaryCanvas" in rendererProp || "scheduler" in rendererProp);
-  let primaryCanvas;
-  let scheduler;
-  let renderer;
-  if (isRendererConfig) {
-    const { primaryCanvas: pc, scheduler: sc, ...rest } = rendererProp;
-    primaryCanvas = pc;
-    scheduler = sc;
-    renderer = Object.keys(rest).length > 0 ? rest : rendererProp;
-  } else {
-    renderer = rendererProp;
-  }
+  const { primaryCanvas, scheduler, renderer } = parseRendererConfig(rendererProp);
   React.useMemo(() => extend(THREE), []);
   const Bridge = useBridge();
-  const backgroundProps = React.useMemo(() => {
-    if (!background) return null;
-    if (typeof background === "object" && !background.isColor) {
-      const { backgroundMap, envMap, files, preset, ...rest } = background;
-      return {
-        ...rest,
-        preset,
-        files: envMap || files,
-        backgroundFiles: backgroundMap,
-        background: true
-      };
-    }
-    if (typeof background === "number") {
-      return { color: background, background: true };
-    }
-    if (typeof background === "string") {
-      if (background in presetsObj) {
-        return { preset: background, background: true };
-      }
-      if (/^(https?:\/\/|\/|\.\/|\.\.\/)|\\.(hdr|exr|jpg|jpeg|png|webp|gif)$/i.test(background)) {
-        return { files: background, background: true };
-      }
-      return { color: background, background: true };
-    }
-    if (background.isColor) {
-      return { color: background, background: true };
-    }
-    return null;
-  }, [background]);
+  const backgroundProps = React.useMemo(() => parseBackground(background), [background]);
   const hasInitialSizeRef = React.useRef(false);
   const measureConfig = React.useMemo(() => {
     if (!hasInitialSizeRef.current) {
@@ -15859,6 +15094,7 @@ function CanvasImpl({
   const handleDropMissed = useMutableCallback(onDropMissed);
   const [block, setBlock] = React.useState(false);
   const [error, setError] = React.useState(false);
+  const [fallbackVisible, setFallbackVisible] = React.useState(false);
   if (block) throw block;
   if (error) throw error;
   const root = React.useRef(null);
@@ -15866,6 +15102,7 @@ function CanvasImpl({
   const unsubscribeErrorRef = React.useRef(null);
   useIsomorphicLayoutEffect(() => {
     effectActiveRef.current = true;
+    if (fallbackVisible) return;
     const canvas = canvasRef.current;
     if (effectiveSize.width > 0 && effectiveSize.height > 0 && canvas) {
       if (!root.current) {
@@ -15886,7 +15123,7 @@ function CanvasImpl({
       }
       async function run() {
         if (!effectActiveRef.current || !root.current) return;
-        await root.current.configure({
+        const configured = await root.current.configure({
           id,
           primaryCanvas,
           scheduler,
@@ -15901,6 +15138,8 @@ function CanvasImpl({
           performance,
           raycaster,
           camera,
+          autoUpdateFrustum,
+          occlusion,
           size: effectiveSize,
           // Store size props for reset functionality
           _sizeProps: width !== void 0 || height !== void 0 ? { width, height } : null,
@@ -15925,8 +15164,20 @@ 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__ */ jsx(Bridge, { children: /* @__PURE__ */ jsx(ErrorBoundary, { set: setError, children: /* @__PURE__ */ jsxs(React.Suspense, { fallback: /* @__PURE__ */ jsx(Block, { set: setBlock }), children: [
             backgroundProps && /* @__PURE__ */ jsx(Environment, { ...backgroundProps }),
@@ -15960,14 +15211,7 @@ function CanvasImpl({
     const handleHMR = () => {
       queueMicrotask(() => {
         const rootEntry = _roots.get(canvas);
-        if (rootEntry?.store) {
-          console.log("[R3F] HMR detected \u2014 rebuilding nodes/uniforms");
-          rootEntry.store.setState((state) => ({
-            nodes: {},
-            uniforms: {},
-            _hmrVersion: state._hmrVersion + 1
-          }));
-        }
+        if (rootEntry?.store) clearHmrCaches(rootEntry.store);
       });
     };
     if (typeof import.meta !== "undefined" && import.meta.hot) {
@@ -15996,7 +15240,11 @@ function CanvasImpl({
         ...style
       },
       ...props,
-      children: /* @__PURE__ */ jsx("div", { ref: containerRef, className: "r3f-canvas-container", style: { width: "100%", height: "100%" }, children: /* @__PURE__ */ jsx(
+      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__ */ jsx("div", { ref: containerRef, className: "r3f-canvas-container", style: { width: "100%", height: "100%" }, children: /* @__PURE__ */ jsx(
         "canvas",
         {
           ref: canvasRef,
@@ -16078,35 +15326,50 @@ let ScopedStore = _ScopedStore;
 function createScopedStore(data) {
   return new ScopedStore(data);
 }
-function createLazyCreatorState(state) {
+function createLazyCreatorState(state, store) {
   let _uniforms = null;
   let _nodes = null;
   let _buffers = null;
   let _gpuStorage = null;
+  const view = (kind) => store ? withStagedOverlay(store, kind, state[kind]) : state[kind];
   return Object.create(state, {
     uniforms: {
       get() {
-        return _uniforms ?? (_uniforms = createScopedStore(state.uniforms));
+        return _uniforms ?? (_uniforms = createScopedStore(view("uniforms")));
       }
     },
     nodes: {
       get() {
-        return _nodes ?? (_nodes = createScopedStore(state.nodes));
+        return _nodes ?? (_nodes = createScopedStore(view("nodes")));
       }
     },
     buffers: {
       get() {
-        return _buffers ?? (_buffers = createScopedStore(state.buffers));
+        return _buffers ?? (_buffers = createScopedStore(view("buffers")));
       }
     },
     gpuStorage: {
       get() {
-        return _gpuStorage ?? (_gpuStorage = createScopedStore(state.gpuStorage));
+        return _gpuStorage ?? (_gpuStorage = createScopedStore(view("gpuStorage")));
       }
     }
   });
 }
 
+function resolvePrimary(local) {
+  return local.getState().primaryStore ?? local;
+}
+function usePrimaryStore() {
+  const local = useStore();
+  const primary = local.getState().primaryStore;
+  return useMemo(() => primary ?? local, [primary, local]);
+}
+function usePrimaryThree(selector = (state) => state, equalityFn) {
+  const local = useStore();
+  const primary = resolvePrimary(local);
+  return primary(selector, equalityFn);
+}
+
 function addTexture(set, key, value) {
   set((state) => {
     const newMap = new Map(state.textures);
@@ -16210,65 +15473,56 @@ function useCompareMemoize(value, deep) {
   return ref.current;
 }
 
+function useScopedResource(options) {
+  const { store, kind, scope, isLeaf, create, prepare, reconcile, input } = options;
+  const scopeKey = scope ?? ROOT_SCOPE;
+  const version = store((s) => s._hmrVersion);
+  const entries = useMemo(() => {
+    const staged = peekStaged(store, kind, scopeKey);
+    const reusable = isScopeValid(store, kind, scopeKey);
+    const map = store.getState()[kind];
+    const committed = reusable ? readCommittedScope(map, scopeKey, isLeaf) : void 0;
+    const result = {};
+    let fresh = null;
+    for (const [name, candidate] of Object.entries(create())) {
+      const existing = staged?.[name] ?? committed?.[name];
+      if (existing !== void 0) {
+        result[name] = existing;
+        reconcile?.(existing, candidate);
+      } else {
+        const value = prepare ? prepare(name, candidate) : candidate;
+        result[name] = value;
+        (fresh ?? (fresh = {}))[name] = value;
+      }
+    }
+    if (fresh) stageEntries(store, kind, scopeKey, fresh);
+    return result;
+  }, [store, kind, scopeKey, version, input]);
+  useIsomorphicLayoutEffect(() => {
+    flushStagedScope(store, kind, scopeKey, isLeaf);
+  });
+  return entries;
+}
+
 const isUniformNode$1 = (value) => value !== null && typeof value === "object" && "value" in value && "uuid" in value;
 function useUniforms(creatorOrScope, scope) {
-  const store = useStore();
+  const store = usePrimaryStore();
   const removeUniforms2 = useCallback(
-    (names, targetScope) => {
-      const nameArray = Array.isArray(names) ? names : [names];
-      store.setState((state) => {
-        if (targetScope) {
-          const currentScope = { ...state.uniforms[targetScope] };
-          for (const name of nameArray) delete currentScope[name];
-          return { uniforms: { ...state.uniforms, [targetScope]: currentScope } };
-        }
-        const uniforms2 = { ...state.uniforms };
-        for (const name of nameArray) if (isUniformNode$1(uniforms2[name])) delete uniforms2[name];
-        return { uniforms: uniforms2 };
-      });
-    },
+    (names, targetScope) => removeResourceEntries(store, "uniforms", Array.isArray(names) ? names : [names], targetScope, isUniformNode$1),
     [store]
   );
   const clearUniforms = useCallback(
-    (targetScope) => {
-      store.setState((state) => {
-        if (targetScope && targetScope !== "root") {
-          const { [targetScope]: _, ...rest } = state.uniforms;
-          return { uniforms: rest };
-        }
-        if (targetScope === "root") {
-          const uniforms2 = {};
-          for (const [key, value] of Object.entries(state.uniforms)) {
-            if (!isUniformNode$1(value)) uniforms2[key] = value;
-          }
-          return { uniforms: uniforms2 };
-        }
-        return { uniforms: {} };
-      });
-    },
+    (targetScope) => clearResourceEntries(store, "uniforms", targetScope, isUniformNode$1),
     [store]
   );
   const rebuildUniforms = useCallback(
-    (targetScope) => {
-      store.setState((state) => {
-        let newUniforms = {};
-        if (targetScope && targetScope !== "root") {
-          const { [targetScope]: _, ...rest } = state.uniforms;
-          newUniforms = rest;
-        } else if (targetScope === "root") {
-          for (const [key, value] of Object.entries(state.uniforms)) {
-            if (!isUniformNode$1(value)) newUniforms[key] = value;
-          }
-        }
-        return { uniforms: newUniforms, _hmrVersion: state._hmrVersion + 1 };
-      });
-    },
+    (targetScope) => rebuildResource(store, "uniforms", targetScope),
     [store]
   );
   const inputForMemoization = useMemo(() => {
     let raw = creatorOrScope;
     if (is.fun(creatorOrScope)) {
-      const wrappedState = createLazyCreatorState(store.getState());
+      const wrappedState = createLazyCreatorState(store.getState(), store);
       raw = creatorOrScope(wrappedState);
     }
     if (raw && typeof raw === "object" && !Array.isArray(raw)) {
@@ -16282,80 +15536,44 @@ function useUniforms(creatorOrScope, scope) {
   }, [creatorOrScope, store]);
   const memoizedInput = useCompareMemoize(inputForMemoization);
   const isReader = memoizedInput === void 0 || typeof memoizedInput === "string";
-  const storeUniforms = useThree((s) => s.uniforms);
-  const hmrVersion = useThree((s) => s._hmrVersion);
-  const readerDep = isReader ? storeUniforms : null;
-  const creatorDep = isReader ? null : hmrVersion;
-  const uniforms = useMemo(() => {
-    if (memoizedInput === void 0) {
-      return storeUniforms;
-    }
-    if (typeof memoizedInput === "string") {
-      const scopeData = storeUniforms[memoizedInput];
-      if (scopeData && !isUniformNode$1(scopeData)) return scopeData;
-      return {};
-    }
-    const state = store.getState();
-    const set = store.setState;
-    if (typeof memoizedInput !== "object" || memoizedInput === null) {
-      throw new Error("Invalid uniform input");
-    }
-    const created = memoizedInput;
-    const result = {};
-    let hasNewUniforms = false;
-    let targetRecord = state.uniforms;
-    if (scope) {
-      if (!state.uniforms[scope]) state.uniforms[scope] = {};
-      targetRecord = state.uniforms[scope];
-    }
-    for (const [name, node] of Object.entries(created)) {
-      if (targetRecord[name]) {
-        result[name] = targetRecord[name];
-        const existingVal = result[name].value;
-        const newVal = vectorize(node);
-        let equals = newVal === existingVal;
-        if (!equals && hasEqualsMethod(existingVal) && hasEqualsMethod(newVal)) {
-          if (isThreeVector(existingVal) && isThreeVector(newVal)) {
-            equals = vectorEquals(existingVal, newVal);
-          } else if (isSameThreeType(existingVal, newVal)) {
-            equals = existingVal.equals(newVal);
-          }
+  const storeUniforms = usePrimaryThree((s) => s.uniforms);
+  const created = useScopedResource({
+    store,
+    kind: "uniforms",
+    scope: isReader ? void 0 : scope,
+    isLeaf: isUniformNode$1,
+    input: memoizedInput,
+    create: () => {
+      if (isReader) return {};
+      if (typeof memoizedInput !== "object" || memoizedInput === null) throw new Error("Invalid uniform input");
+      return memoizedInput;
+    },
+    prepare: (name, candidate) => createUniform(name, candidate, scope),
+    reconcile: (existing, candidate) => {
+      const existingVal = existing.value;
+      const newVal = vectorize(candidate);
+      let equals = newVal === existingVal;
+      if (!equals && hasEqualsMethod(existingVal) && hasEqualsMethod(newVal)) {
+        if (isThreeVector(existingVal) && isThreeVector(newVal)) {
+          equals = vectorEquals(existingVal, newVal);
+        } else if (isSameThreeType(existingVal, newVal)) {
+          equals = existingVal.equals(newVal);
         }
-        if (!equals) result[name].value = newVal;
-      } else {
-        result[name] = createUniform(name, node, scope);
-        hasNewUniforms = true;
-      }
-    }
-    if (hasNewUniforms) {
-      if (scope) {
-        set((s) => ({
-          uniforms: {
-            ...s.uniforms,
-            [scope]: { ...s.uniforms[scope], ...result }
-          }
-        }));
-      } else {
-        set((s) => ({ uniforms: { ...s.uniforms, ...result } }));
       }
+      if (!equals) existing.value = newVal;
     }
-    return result;
-  }, [store, memoizedInput, scope, readerDep, creatorDep]);
+  });
+  let uniforms = created;
+  if (memoizedInput === void 0) {
+    uniforms = storeUniforms;
+  } else if (typeof memoizedInput === "string") {
+    const scopeData = storeUniforms[memoizedInput];
+    uniforms = scopeData && !isUniformNode$1(scopeData) ? scopeData : {};
+  }
   return { ...uniforms, removeUniforms: removeUniforms2, clearUniforms, rebuildUniforms };
 }
 function rebuildAllUniforms(store, scope) {
-  store.setState((state) => {
-    let newUniforms = {};
-    if (scope && scope !== "root") {
-      const { [scope]: _, ...rest } = state.uniforms;
-      newUniforms = rest;
-    } else if (scope === "root") {
-      for (const [key, value] of Object.entries(state.uniforms)) {
-        if (!isUniformNode$1(value)) newUniforms[key] = value;
-      }
-    }
-    return { uniforms: newUniforms, _hmrVersion: state._hmrVersion + 1 };
-  });
+  rebuildResource(store, "uniforms", scope);
 }
 function removeUniforms(set, names, scope) {
   set((state) => {
@@ -16419,191 +15637,91 @@ function isSameThreeType(a, b) {
   return obj_a.isColor && obj_b.isColor || obj_a.isMatrix3 && obj_b.isMatrix3 || obj_a.isMatrix4 && obj_b.isMatrix4 || obj_a.isEuler && obj_b.isEuler || obj_a.isQuaternion && obj_b.isQuaternion;
 }
 
+const uniformOf = uniform;
 const isUniformNode = (value) => value !== null && typeof value === "object" && "value" in value && "uuid" in value;
 const isTSLNode$1 = (value) => value !== null && typeof value === "object" && "uuid" in value && "nodeType" in value;
 function useUniform(name, value) {
   const store = useStore();
-  const hmrVersion = useThree((s) => s._hmrVersion);
-  return useMemo(() => {
-    const state = store.getState();
-    const set = store.setState;
-    const existing = state.uniforms[name];
-    if (existing && isUniformNode(existing)) {
+  const registered = useScopedResource({
+    store,
+    kind: "uniforms",
+    scope: void 0,
+    isLeaf: isUniformNode,
+    input: name,
+    create: () => value === void 0 ? {} : { [name]: value },
+    prepare: createNamedUniform,
+    reconcile: (existing2) => {
       if (value !== void 0 && !isTSLNode$1(value) && !isUniformNode(value)) {
-        existing.value = typeof value === "string" ? new Color(value) : value;
+        existing2.value = typeof value === "string" ? new Color(value) : value;
       }
-      return existing;
-    }
-    if (value === void 0) {
-      throw new Error(
-        `[useUniform] Uniform "${name}" not found. Create it first with: useUniform('${name}', initialValue)`
-      );
-    }
-    if (isUniformNode(value)) {
-      const node2 = value;
-      if (typeof node2.setName === "function") {
-        node2.setName(name);
-      }
-      set((s) => ({
-        uniforms: { ...s.uniforms, [name]: node2 }
-      }));
-      return node2;
-    }
-    let node;
-    if (isTSLNode$1(value)) {
-      node = uniform(value);
-    } else if (typeof value === "string") {
-      node = uniform(new Color(value));
-    } else {
-      node = uniform(value);
-    }
-    if (typeof node.setName === "function") {
-      node.setName(name);
     }
-    set((s) => ({
-      uniforms: {
-        ...s.uniforms,
-        [name]: node
-      }
-    }));
-    return node;
-  }, [store, name, hmrVersion]);
+  });
+  if (registered[name]) return registered[name];
+  const existing = peekStaged(store, "uniforms", ROOT_SCOPE)?.[name] ?? store.getState().uniforms[name];
+  if (existing && isUniformNode(existing)) return existing;
+  throw new Error(
+    `[useUniform] Uniform "${name}" not found. Create it first with: useUniform('${name}', initialValue)`
+  );
+}
+function createNamedUniform(name, value) {
+  let node;
+  if (isUniformNode(value)) {
+    node = value;
+  } else if (isTSLNode$1(value)) {
+    node = uniformOf(value);
+  } else if (typeof value === "string") {
+    node = uniform(new Color(value));
+  } else {
+    node = uniformOf(value);
+  }
+  if (typeof node.setName === "function") {
+    node.setName(name);
+  }
+  return node;
 }
 
 const isTSLNode = (value) => value !== null && typeof value === "object" && ("uuid" in value || "nodeType" in value);
 function useNodes(creatorOrScope, scope) {
-  const store = useStore();
+  const store = usePrimaryStore();
   const removeNodes2 = useCallback(
-    (names, targetScope) => {
-      const nameArray = Array.isArray(names) ? names : [names];
-      store.setState((state) => {
-        if (targetScope) {
-          const currentScope = { ...state.nodes[targetScope] };
-          for (const name of nameArray) delete currentScope[name];
-          return { nodes: { ...state.nodes, [targetScope]: currentScope } };
-        }
-        const nodes2 = { ...state.nodes };
-        for (const name of nameArray) if (isTSLNode(nodes2[name])) delete nodes2[name];
-        return { nodes: nodes2 };
-      });
-    },
+    (names, targetScope) => removeResourceEntries(store, "nodes", Array.isArray(names) ? names : [names], targetScope, isTSLNode),
     [store]
   );
   const clearNodes = useCallback(
-    (targetScope) => {
-      store.setState((state) => {
-        if (targetScope && targetScope !== "root") {
-          const { [targetScope]: _, ...rest } = state.nodes;
-          return { nodes: rest };
-        }
-        if (targetScope === "root") {
-          const nodes2 = {};
-          for (const [key, value] of Object.entries(state.nodes)) {
-            if (!isTSLNode(value)) nodes2[key] = value;
-          }
-          return { nodes: nodes2 };
-        }
-        return { nodes: {} };
-      });
-    },
+    (targetScope) => clearResourceEntries(store, "nodes", targetScope, isTSLNode),
     [store]
   );
   const rebuildNodes = useCallback(
-    (targetScope) => {
-      store.setState((state) => {
-        let newNodes = state.nodes;
-        if (targetScope && targetScope !== "root") {
-          const { [targetScope]: _, ...rest } = state.nodes;
-          newNodes = rest;
-        } else if (targetScope === "root") {
-          newNodes = {};
-          for (const [key, value] of Object.entries(state.nodes)) {
-            if (!isTSLNode(value)) newNodes[key] = value;
-          }
-        } else {
-          newNodes = {};
-        }
-        return { nodes: newNodes, _hmrVersion: state._hmrVersion + 1 };
-      });
-    },
+    (targetScope) => rebuildResource(store, "nodes", targetScope),
     [store]
   );
   const isReader = creatorOrScope === void 0 || typeof creatorOrScope === "string";
-  const storeNodes = useThree((s) => s.nodes);
-  const hmrVersion = useThree((s) => s._hmrVersion);
-  const scopeDep = typeof creatorOrScope === "string" ? creatorOrScope : scope;
-  const readerDep = isReader ? storeNodes : null;
-  const creatorDep = isReader ? null : hmrVersion;
-  const nodes = useMemo(() => {
-    if (creatorOrScope === void 0) {
-      return storeNodes;
-    }
-    if (typeof creatorOrScope === "string") {
-      const scopeData = storeNodes[creatorOrScope];
-      if (scopeData && !isTSLNode(scopeData)) return scopeData;
-      return {};
-    }
-    const state = store.getState();
-    const set = store.setState;
-    const creator = creatorOrScope;
-    const wrappedState = createLazyCreatorState(state);
-    const created = creator(wrappedState);
-    const result = {};
-    let hasNewNodes = false;
-    if (scope) {
-      const currentScope = state.nodes[scope] ?? {};
-      for (const [name, node] of Object.entries(created)) {
-        if (currentScope[name]) {
-          result[name] = currentScope[name];
-        } else {
-          node.setName?.(`${scope}.${name}`);
-          result[name] = node;
-          hasNewNodes = true;
-        }
-      }
-      if (hasNewNodes) {
-        set((s) => ({
-          nodes: {
-            ...s.nodes,
-            [scope]: { ...s.nodes[scope], ...result }
-          }
-        }));
-      }
-      return result;
-    }
-    for (const [name, node] of Object.entries(created)) {
-      const existing = state.nodes[name];
-      if (existing && isTSLNode(existing)) {
-        result[name] = existing;
-      } else {
-        node.setName?.(name);
-        result[name] = node;
-        hasNewNodes = true;
-      }
-    }
-    if (hasNewNodes) {
-      set((s) => ({ nodes: { ...s.nodes, ...result } }));
+  const storeNodes = usePrimaryThree((s) => s.nodes);
+  const created = useScopedResource({
+    store,
+    kind: "nodes",
+    scope: isReader ? void 0 : scope,
+    isLeaf: isTSLNode,
+    create: () => {
+      if (isReader) return {};
+      return creatorOrScope(createLazyCreatorState(store.getState(), store));
+    },
+    prepare: (name, node) => {
+      node.setName?.(scope ? `${scope}.${name}` : name);
+      return node;
     }
-    return result;
-  }, [store, scopeDep, readerDep, creatorDep]);
+  });
+  let nodes = created;
+  if (creatorOrScope === void 0) {
+    nodes = storeNodes;
+  } else if (typeof creatorOrScope === "string") {
+    const scopeData = storeNodes[creatorOrScope];
+    nodes = scopeData && !isTSLNode(scopeData) ? scopeData : {};
+  }
   return { ...nodes, removeNodes: removeNodes2, clearNodes, rebuildNodes };
 }
 function rebuildAllNodes(store, scope) {
-  store.setState((state) => {
-    let newNodes = state.nodes;
-    if (scope && scope !== "root") {
-      const { [scope]: _, ...rest } = state.nodes;
-      newNodes = rest;
-    } else if (scope === "root") {
-      newNodes = {};
-      for (const [key, value] of Object.entries(state.nodes)) {
-        if (!isTSLNode(value)) newNodes[key] = value;
-      }
-    } else {
-      newNodes = {};
-    }
-    return { nodes: newNodes, _hmrVersion: state._hmrVersion + 1 };
-  });
+  rebuildResource(store, "nodes", scope);
 }
 function removeNodes(set, names, scope) {
   set((state) => {
@@ -16633,13 +15751,13 @@ function clearRootNodes(set) {
   });
 }
 function useLocalNodes(creator) {
-  const store = useStore();
-  const uniforms = useThree((s) => s.uniforms);
-  const nodes = useThree((s) => s.nodes);
-  const textures = useThree((s) => s.textures);
-  const hmrVersion = useThree((s) => s._hmrVersion);
+  const store = usePrimaryStore();
+  const uniforms = usePrimaryThree((s) => s.uniforms);
+  const nodes = usePrimaryThree((s) => s.nodes);
+  const textures = usePrimaryThree((s) => s.textures);
+  const hmrVersion = usePrimaryThree((s) => s._hmrVersion);
   return useMemo(() => {
-    const wrappedState = createLazyCreatorState(store.getState());
+    const wrappedState = createLazyCreatorState(store.getState(), store);
     return creator(wrappedState);
   }, [store, creator, uniforms, nodes, textures, hmrVersion]);
 }
@@ -16658,60 +15776,17 @@ const disposeBuffer = (buffer) => {
   }
 };
 function useBuffers(creatorOrScope, scope) {
-  const store = useStore();
+  const store = usePrimaryStore();
   const removeBuffers = useCallback(
-    (names, targetScope) => {
-      const nameArray = Array.isArray(names) ? names : [names];
-      store.setState((state) => {
-        if (targetScope) {
-          const currentScope = { ...state.buffers[targetScope] };
-          for (const name of nameArray) delete currentScope[name];
-          return { buffers: { ...state.buffers, [targetScope]: currentScope } };
-        }
-        const buffers2 = { ...state.buffers };
-        for (const name of nameArray) if (isBufferLike(buffers2[name])) delete buffers2[name];
-        return { buffers: buffers2 };
-      });
-    },
+    (names, targetScope) => removeResourceEntries(store, "buffers", Array.isArray(names) ? names : [names], targetScope, isBufferLike),
     [store]
   );
   const clearBuffers = useCallback(
-    (targetScope) => {
-      store.setState((state) => {
-        if (targetScope && targetScope !== "root") {
-          const { [targetScope]: _, ...rest } = state.buffers;
-          return { buffers: rest };
-        }
-        if (targetScope === "root") {
-          const buffers2 = {};
-          for (const [key, value] of Object.entries(state.buffers)) {
-            if (!isBufferLike(value)) buffers2[key] = value;
-          }
-          return { buffers: buffers2 };
-        }
-        return { buffers: {} };
-      });
-    },
+    (targetScope) => clearResourceEntries(store, "buffers", targetScope, isBufferLike),
     [store]
   );
   const rebuildBuffers = useCallback(
-    (targetScope) => {
-      store.setState((state) => {
-        let newBuffers = state.buffers;
-        if (targetScope && targetScope !== "root") {
-          const { [targetScope]: _, ...rest } = state.buffers;
-          newBuffers = rest;
-        } else if (targetScope === "root") {
-          newBuffers = {};
-          for (const [key, value] of Object.entries(state.buffers)) {
-            if (!isBufferLike(value)) newBuffers[key] = value;
-          }
-        } else {
-          newBuffers = {};
-        }
-        return { buffers: newBuffers, _hmrVersion: state._hmrVersion + 1 };
-      });
-    },
+    (targetScope) => rebuildResource(store, "buffers", targetScope),
     [store]
   );
   const disposeBuffers = useCallback(
@@ -16729,85 +15804,34 @@ function useBuffers(creatorOrScope, scope) {
     [store, removeBuffers]
   );
   const isReader = creatorOrScope === void 0 || typeof creatorOrScope === "string";
-  const storeBuffers = useThree((s) => s.buffers);
-  const hmrVersion = useThree((s) => s._hmrVersion);
-  const scopeDep = typeof creatorOrScope === "string" ? creatorOrScope : scope;
-  const readerDep = isReader ? storeBuffers : null;
-  const creatorDep = isReader ? null : hmrVersion;
-  const buffers = useMemo(() => {
-    if (creatorOrScope === void 0) {
-      return storeBuffers;
-    }
-    if (typeof creatorOrScope === "string") {
-      const scopeData = storeBuffers[creatorOrScope];
-      if (scopeData && !isBufferLike(scopeData)) return scopeData;
-      return {};
-    }
-    const state = store.getState();
-    const set = store.setState;
-    const creator = creatorOrScope;
-    const wrappedState = createLazyCreatorState(state);
-    const created = creator(wrappedState);
-    const result = {};
-    let hasNewBuffers = false;
-    if (scope) {
-      const currentScope = state.buffers[scope] ?? {};
-      for (const [name, buffer] of Object.entries(created)) {
-        if (currentScope[name]) {
-          result[name] = currentScope[name];
-        } else {
-          if ("setName" in buffer && typeof buffer.setName === "function") {
-            buffer.setName(`${scope}.${name}`);
-          }
-          result[name] = buffer;
-          hasNewBuffers = true;
-        }
-      }
-      if (hasNewBuffers) {
-        set((s) => ({
-          buffers: {
-            ...s.buffers,
-            [scope]: { ...s.buffers[scope], ...result }
-          }
-        }));
-      }
-      return result;
-    }
-    for (const [name, buffer] of Object.entries(created)) {
-      const existing = state.buffers[name];
-      if (existing && isBufferLike(existing)) {
-        result[name] = existing;
-      } else {
-        if ("setName" in buffer && typeof buffer.setName === "function") {
-          buffer.setName(name);
-        }
-        result[name] = buffer;
-        hasNewBuffers = true;
+  const storeBuffers = usePrimaryThree((s) => s.buffers);
+  const created = useScopedResource({
+    store,
+    kind: "buffers",
+    scope: isReader ? void 0 : scope,
+    isLeaf: isBufferLike,
+    create: () => {
+      if (isReader) return {};
+      return creatorOrScope(createLazyCreatorState(store.getState(), store));
+    },
+    prepare: (name, buffer) => {
+      if ("setName" in buffer && typeof buffer.setName === "function") {
+        buffer.setName(scope ? `${scope}.${name}` : name);
       }
+      return buffer;
     }
-    if (hasNewBuffers) {
-      set((s) => ({ buffers: { ...s.buffers, ...result } }));
-    }
-    return result;
-  }, [store, scopeDep, readerDep, creatorDep]);
+  });
+  let buffers = created;
+  if (creatorOrScope === void 0) {
+    buffers = storeBuffers;
+  } else if (typeof creatorOrScope === "string") {
+    const scopeData = storeBuffers[creatorOrScope];
+    buffers = scopeData && !isBufferLike(scopeData) ? scopeData : {};
+  }
   return { ...buffers, removeBuffers, clearBuffers, rebuildBuffers, disposeBuffers };
 }
 function rebuildAllBuffers(store, scope) {
-  store.setState((state) => {
-    let newBuffers = state.buffers;
-    if (scope && scope !== "root") {
-      const { [scope]: _, ...rest } = state.buffers;
-      newBuffers = rest;
-    } else if (scope === "root") {
-      newBuffers = {};
-      for (const [key, value] of Object.entries(state.buffers)) {
-        if (!isBufferLike(value)) newBuffers[key] = value;
-      }
-    } else {
-      newBuffers = {};
-    }
-    return { buffers: newBuffers, _hmrVersion: state._hmrVersion + 1 };
-  });
+  rebuildResource(store, "buffers", scope);
 }
 
 const isStorageLike = (value) => {
@@ -16824,60 +15848,17 @@ const disposeStorage = (storage) => {
   }
 };
 function useGPUStorage(creatorOrScope, scope) {
-  const store = useStore();
+  const store = usePrimaryStore();
   const removeStorage = useCallback(
-    (names, targetScope) => {
-      const nameArray = Array.isArray(names) ? names : [names];
-      store.setState((state) => {
-        if (targetScope) {
-          const currentScope = { ...state.gpuStorage[targetScope] };
-          for (const name of nameArray) delete currentScope[name];
-          return { gpuStorage: { ...state.gpuStorage, [targetScope]: currentScope } };
-        }
-        const gpuStorage2 = { ...state.gpuStorage };
-        for (const name of nameArray) if (isStorageLike(gpuStorage2[name])) delete gpuStorage2[name];
-        return { gpuStorage: gpuStorage2 };
-      });
-    },
+    (names, targetScope) => removeResourceEntries(store, "gpuStorage", Array.isArray(names) ? names : [names], targetScope, isStorageLike),
     [store]
   );
   const clearStorage = useCallback(
-    (targetScope) => {
-      store.setState((state) => {
-        if (targetScope && targetScope !== "root") {
-          const { [targetScope]: _, ...rest } = state.gpuStorage;
-          return { gpuStorage: rest };
-        }
-        if (targetScope === "root") {
-          const gpuStorage2 = {};
-          for (const [key, value] of Object.entries(state.gpuStorage)) {
-            if (!isStorageLike(value)) gpuStorage2[key] = value;
-          }
-          return { gpuStorage: gpuStorage2 };
-        }
-        return { gpuStorage: {} };
-      });
-    },
+    (targetScope) => clearResourceEntries(store, "gpuStorage", targetScope, isStorageLike),
     [store]
   );
   const rebuildStorage = useCallback(
-    (targetScope) => {
-      store.setState((state) => {
-        let newStorage = state.gpuStorage;
-        if (targetScope && targetScope !== "root") {
-          const { [targetScope]: _, ...rest } = state.gpuStorage;
-          newStorage = rest;
-        } else if (targetScope === "root") {
-          newStorage = {};
-          for (const [key, value] of Object.entries(state.gpuStorage)) {
-            if (!isStorageLike(value)) newStorage[key] = value;
-          }
-        } else {
-          newStorage = {};
-        }
-        return { gpuStorage: newStorage, _hmrVersion: state._hmrVersion + 1 };
-      });
-    },
+    (targetScope) => rebuildResource(store, "gpuStorage", targetScope),
     [store]
   );
   const disposeStorageFn = useCallback(
@@ -16895,73 +15876,34 @@ function useGPUStorage(creatorOrScope, scope) {
     [store, removeStorage]
   );
   const isReader = creatorOrScope === void 0 || typeof creatorOrScope === "string";
-  const storeStorage = useThree((s) => s.gpuStorage);
-  const hmrVersion = useThree((s) => s._hmrVersion);
-  const scopeDep = typeof creatorOrScope === "string" ? creatorOrScope : scope;
-  const readerDep = isReader ? storeStorage : null;
-  const creatorDep = isReader ? null : hmrVersion;
-  const gpuStorage = useMemo(() => {
-    if (creatorOrScope === void 0) {
-      return storeStorage;
-    }
-    if (typeof creatorOrScope === "string") {
-      const scopeData = storeStorage[creatorOrScope];
-      if (scopeData && !isStorageLike(scopeData)) return scopeData;
-      return {};
-    }
-    const state = store.getState();
-    const set = store.setState;
-    const creator = creatorOrScope;
-    const wrappedState = createLazyCreatorState(state);
-    const created = creator(wrappedState);
-    const result = {};
-    let hasNewStorage = false;
-    if (scope) {
-      const currentScope = state.gpuStorage[scope] ?? {};
-      for (const [name, storage] of Object.entries(created)) {
-        if (currentScope[name]) {
-          result[name] = currentScope[name];
-        } else {
-          if ("setName" in storage && typeof storage.setName === "function") {
-            storage.setName(`${scope}.${name}`);
-          }
-          if ("name" in storage && typeof storage.name === "string") {
-            storage.name = `${scope}.${name}`;
-          }
-          result[name] = storage;
-          hasNewStorage = true;
-        }
-      }
-      if (hasNewStorage) {
-        set((s) => ({
-          gpuStorage: {
-            ...s.gpuStorage,
-            [scope]: { ...s.gpuStorage[scope], ...result }
-          }
-        }));
+  const storeStorage = usePrimaryThree((s) => s.gpuStorage);
+  const created = useScopedResource({
+    store,
+    kind: "gpuStorage",
+    scope: isReader ? void 0 : scope,
+    isLeaf: isStorageLike,
+    create: () => {
+      if (isReader) return {};
+      return creatorOrScope(createLazyCreatorState(store.getState(), store));
+    },
+    prepare: (name, storage) => {
+      const label = scope ? `${scope}.${name}` : name;
+      if ("setName" in storage && typeof storage.setName === "function") {
+        storage.setName(label);
       }
-      return result;
-    }
-    for (const [name, storage] of Object.entries(created)) {
-      const existing = state.gpuStorage[name];
-      if (existing && isStorageLike(existing)) {
-        result[name] = existing;
-      } else {
-        if ("setName" in storage && typeof storage.setName === "function") {
-          storage.setName(name);
-        }
-        if ("name" in storage && typeof storage.name === "string") {
-          storage.name = name;
-        }
-        result[name] = storage;
-        hasNewStorage = true;
+      if ("name" in storage && typeof storage.name === "string") {
+        storage.name = label;
       }
+      return storage;
     }
-    if (hasNewStorage) {
-      set((s) => ({ gpuStorage: { ...s.gpuStorage, ...result } }));
-    }
-    return result;
-  }, [store, scopeDep, readerDep, creatorDep]);
+  });
+  let gpuStorage = created;
+  if (creatorOrScope === void 0) {
+    gpuStorage = storeStorage;
+  } else if (typeof creatorOrScope === "string") {
+    const scopeData = storeStorage[creatorOrScope];
+    gpuStorage = scopeData && !isStorageLike(scopeData) ? scopeData : {};
+  }
   return {
     ...gpuStorage,
     removeStorage,
@@ -16971,21 +15913,7 @@ function useGPUStorage(creatorOrScope, scope) {
   };
 }
 function rebuildAllStorage(store, scope) {
-  store.setState((state) => {
-    let newStorage = state.gpuStorage;
-    if (scope && scope !== "root") {
-      const { [scope]: _, ...rest } = state.gpuStorage;
-      newStorage = rest;
-    } else if (scope === "root") {
-      newStorage = {};
-      for (const [key, value] of Object.entries(state.gpuStorage)) {
-        if (!isStorageLike(value)) newStorage[key] = value;
-      }
-    } else {
-      newStorage = {};
-    }
-    return { gpuStorage: newStorage, _hmrVersion: state._hmrVersion + 1 };
-  });
+  rebuildResource(store, "gpuStorage", scope);
 }
 
 function useRenderPipeline(mainCB, setupCB) {
@@ -17026,12 +15954,12 @@ function useRenderPipeline(mainCB, setupCB) {
     const state = store.getState();
     const set = store.setState;
     try {
-      let pp = state.renderPipeline;
+      let pipeline = state.renderPipeline;
       let currentPasses = { ...state.passes };
-      let justCreatedPP = false;
-      if (!pp) {
-        pp = new PostProcessing(renderer);
-        justCreatedPP = true;
+      let justCreatedPipeline = false;
+      if (!pipeline) {
+        pipeline = new RenderPipeline(renderer);
+        justCreatedPipeline = true;
       }
       const cacheValid = scenePassCacheRef.current && scenePassCacheRef.current.sceneUuid === scene.uuid && scenePassCacheRef.current.cameraUuid === camera.uuid;
       let scenePass;
@@ -17042,9 +15970,9 @@ function useRenderPipeline(mainCB, setupCB) {
         scenePassCacheRef.current = { sceneUuid: scene.uuid, cameraUuid: camera.uuid, scenePass };
       }
       currentPasses.scenePass = scenePass;
-      if (!pp.outputNode || justCreatedPP) pp.outputNode = scenePass;
-      set({ renderPipeline: pp, passes: currentPasses });
-      const shouldRunCallbacks = justCreatedPP || !callbacksRanRef.current || !cacheValid;
+      if (!pipeline.outputNode || justCreatedPipeline) pipeline.outputNode = scenePass;
+      set({ renderPipeline: pipeline, passes: currentPasses });
+      const shouldRunCallbacks = justCreatedPipeline || !callbacksRanRef.current || !cacheValid;
       if (shouldRunCallbacks) {
         if (setupCBRef.current) {
           const freshState = store.getState();
@@ -17065,7 +15993,7 @@ function useRenderPipeline(mainCB, setupCB) {
         callbacksRanRef.current = true;
       }
     } catch (error) {
-      console.error("[useRenderPipeline] Setup error:", error);
+      console.warn("[useRenderPipeline] Setup failed; the render pipeline was not configured:", error);
     }
   }, [store, renderer, scene, camera, isLegacy, rebuildVersion]);
   const passes = useThree((s) => s.passes);
@@ -17083,4 +16011,4 @@ function useRenderPipeline(mainCB, setupCB) {
 
 extend(THREE);
 
-export { Block, Canvas, Environment, EnvironmentCube, EnvironmentMap, EnvironmentPortal, ErrorBoundary, FROM_REF, IsObject, ONCE, Portal, R3F_BUILD_LEGACY, R3F_BUILD_WEBGPU, REACT_INTERNAL_PROPS, RESERVED_PROPS, Scheduler, Texture, _roots, act, addAfterEffect, addEffect, addTail, advance, applyProps, attach, buildGraph, calculateDpr, clearNodeScope, clearRootNodes, clearRootUniforms, clearScope, context, createEvents, createPointerEvents, createPortal, createRoot, createScopedStore, createStore, createTextureOperations, detach, diffProps, dispose, createPointerEvents as events, extend, findInitialRoot, flushSync, fromRef, getInstanceProps, getPrimary, getPrimaryIds, getRootState, getScheduler, getUuidPrefix, hasConstructor, hasPrimary, invalidate, invalidateInstance, is, isColorRepresentation, isCopyable, isFromRef, isObject3D, isOnce, isOrthographicCamera, isRef, isRenderer, isTexture, isVectorLike, once, prepare, presetsObj, rebuildAllBuffers, rebuildAllNodes, rebuildAllStorage, rebuildAllUniforms, reconciler, registerPrimary, removeInteractivity, removeNodes, removeUniforms, resolve, unmountComponentAtNode, unregisterPrimary, updateCamera, updateFrustum, useBridge, useBuffers, useEnvironment, useFrame, useGPUStorage, useGraph, useInstanceHandle, useIsomorphicLayoutEffect, useLoader, useLocalNodes, useMutableCallback, useNodes, useRenderPipeline, useRenderTarget, useStore, useTexture, useTextures, useThree, useUniform, useUniforms, waitForPrimary };
+export { Block, Canvas, Environment, EnvironmentCube, EnvironmentMap, EnvironmentPortal, ErrorBoundary, FROM_REF, IsObject, ONCE, Portal, R3F_BUILD_LEGACY, R3F_BUILD_WEBGPU, REACT_INTERNAL_PROPS, RESERVED_PROPS, Texture, _roots, addAfterEffect, addEffect, addTail, advance, applyProps, attach, buildGraph, calculateDpr, clearNodeScope, clearRootNodes, clearRootUniforms, clearScope, context, createEvents, createPointerEvents, createPortal, createRoot, createScopedStore, createStore, createTextureOperations, detach, diffProps, dispose, createPointerEvents as events, extend, findInitialRoot, flushSync, fromRef, getInstanceProps, getPrimary, getPrimaryIds, getRootState, getUuidPrefix, hasConstructor, hasPrimary, invalidate, invalidateInstance, is, isColorRepresentation, isCopyable, isFromRef, isObject3D, isOnce, isOrthographicCamera, isRef, isRenderer, isTexture, isVectorLike, once, prepare, presetsObj, rebuildAllBuffers, rebuildAllNodes, rebuildAllStorage, rebuildAllUniforms, reconciler, registerPrimary, removeInteractivity, removeNodes, removeUniforms, resolve, unmountComponentAtNode, unregisterPrimary, updateCamera, updateFrustum, useBridge, useBuffers, useEnvironment, useFrame, useGPUStorage, useGraph, useInstanceHandle, useIsomorphicLayoutEffect, useLoader, useLocalNodes, useMutableCallback, useNodes, useRenderPipeline, useRenderTarget, useStore, useTexture, useTextures, useThree, useUniform, useUniforms, waitForPrimary };