@react-three/fiber 10.0.0-canary.164c7be → 10.0.0-canary.1be335a

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,7 +12,7 @@ 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';
@@ -43,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]);
@@ -323,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();
@@ -339,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,
@@ -359,7 +363,7 @@ function EnvironmentPortal({
     defaultScene,
     background,
     frames,
-    gl,
+    renderer,
     blur,
     backgroundBlurriness,
     backgroundIntensity,
@@ -370,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++;
     }
   });
@@ -616,8 +620,7 @@ function prepare(target, root, type, props) {
       object,
       eventCount: 0,
       handlers: {},
-      isHidden: false,
-      deferredRefs: []
+      isHidden: false
     };
     if (object) object.__r3f = instance;
   }
@@ -774,6 +777,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;
@@ -934,9 +948,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;
@@ -961,10 +975,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) {
@@ -1000,6 +1011,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) {
@@ -1018,6 +1042,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,
@@ -1025,7 +1052,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);
     }
@@ -1553,6 +1582,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);
@@ -1639,6 +1669,13 @@ function notifyAlpha({ message, link }) {
   }
 }
 
+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));
+}
+
 const R3F_CONTEXT = Symbol.for("@react-three/fiber.context");
 const context = globalThis[R3F_CONTEXT] ?? (globalThis[R3F_CONTEXT] = React.createContext(null));
 const createStore = (invalidate, advance) => {
@@ -1771,6 +1808,7 @@ const createStore = (invalidate, advance) => {
       }),
       setFrameloop: (frameloop = "always") => {
         set(() => ({ frameloop }));
+        getScheduler().frameloop = frameloop;
       },
       setError: (error) => set(() => ({ error })),
       error: null,
@@ -1838,8 +1876,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",
@@ -1952,19 +1989,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;
 
@@ -2384,7 +2427,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};
 
@@ -13640,7 +13683,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);
@@ -13805,7 +13848,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) {
@@ -13823,6 +13874,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);
   }
@@ -13835,6 +13887,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);
@@ -13851,14 +13905,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,
@@ -13897,16 +14051,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) {
@@ -13931,8 +14084,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,
@@ -13940,6 +14094,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,
@@ -13980,28 +14137,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() {
   },
@@ -14050,11 +14188,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,
@@ -14139,6 +14281,7 @@ function createRoot(canvas) {
   const lastConfiguredProps = {};
   let configured = false;
   let pending = null;
+  let rendererSetup = null;
   return {
     async configure(props = {}) {
       let resolve;
@@ -14169,7 +14312,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
@@ -14183,52 +14326,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() });
@@ -14578,7 +14733,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);
       }
@@ -14641,6 +14797,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,
@@ -14659,7 +14816,7 @@ 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 }
     };
@@ -14718,14 +14875,146 @@ function parseBackground(background) {
   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 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) {
-  store.setState((state) => ({
-    nodes: {},
-    uniforms: {},
-    buffers: {},
-    gpuStorage: {},
-    _hmrVersion: state._hmrVersion + 1
-  }));
+  const primary = store.getState().primaryStore ?? store;
+  invalidateAllResources(primary);
+  primary.setState((state) => ({ _hmrVersion: state._hmrVersion + 1 }));
 }
 
 function CanvasImpl({
@@ -14761,18 +15050,7 @@ 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(() => parseBackground(background), [background]);
@@ -14817,6 +15095,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);
@@ -14824,6 +15103,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) {
@@ -14844,7 +15124,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,
@@ -14885,8 +15165,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 }),
@@ -14949,7 +15241,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,
@@ -15031,30 +15327,31 @@ 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")));
       }
     }
   });
@@ -15177,65 +15474,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 = 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)) {
@@ -15250,80 +15538,43 @@ function useUniforms(creatorOrScope, scope) {
   const memoizedInput = useCompareMemoize(inputForMemoization);
   const isReader = memoizedInput === void 0 || typeof memoizedInput === "string";
   const storeUniforms = usePrimaryThree((s) => s.uniforms);
-  const hmrVersion = usePrimaryThree((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);
-          }
-        }
-        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 } }));
-      }
+  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) 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 = store.getState().primaryStore ?? store;
-  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) => {
@@ -15387,192 +15638,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 = 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 = usePrimaryThree((s) => s.nodes);
-  const hmrVersion = usePrimaryThree((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 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 = store.getState().primaryStore ?? store;
-  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) => {
@@ -15608,7 +15758,7 @@ function useLocalNodes(creator) {
   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]);
 }
@@ -15629,58 +15779,15 @@ const disposeBuffer = (buffer) => {
 function useBuffers(creatorOrScope, scope) {
   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(
@@ -15699,85 +15806,33 @@ function useBuffers(creatorOrScope, scope) {
   );
   const isReader = creatorOrScope === void 0 || typeof creatorOrScope === "string";
   const storeBuffers = usePrimaryThree((s) => s.buffers);
-  const hmrVersion = usePrimaryThree((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 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 = store.getState().primaryStore ?? store;
-  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) => {
@@ -15796,58 +15851,15 @@ const disposeStorage = (storage) => {
 function useGPUStorage(creatorOrScope, scope) {
   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(
@@ -15866,72 +15878,33 @@ function useGPUStorage(creatorOrScope, scope) {
   );
   const isReader = creatorOrScope === void 0 || typeof creatorOrScope === "string";
   const storeStorage = usePrimaryThree((s) => s.gpuStorage);
-  const hmrVersion = usePrimaryThree((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 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,
@@ -15941,22 +15914,7 @@ function useGPUStorage(creatorOrScope, scope) {
   };
 }
 function rebuildAllStorage(store, scope) {
-  store = store.getState().primaryStore ?? store;
-  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) {
@@ -15997,12 +15955,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;
@@ -16013,9 +15971,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();
@@ -16036,7 +15994,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);