@react-three/fiber 10.0.0-canary.b86abaa → 10.0.0-canary.b9d5979

package/dist/shared/{fiber.oKEFddXj.cjs → fiber.BegWBc5_.cjs}

@@ -417,6 +417,15 @@ function isOnce(value) {
   return value !== null && typeof value === "object" && ONCE in value;
 }
 
+function assertNodeMaterialSupported(state, value) {
+  if (!state?.isLegacy) return;
+  const material = (Array.isArray(value) ? value : [value]).find((m) => m?.isNodeMaterial);
+  if (!material) return;
+  throw new Error(
+    `R3F: ${material.type ?? "Node material"} requires WebGPURenderer (it falls back to WebGL2 automatically). Pass \`renderer\` to <Canvas> from @react-three/fiber, or import from @react-three/fiber/webgpu.`
+  );
+}
+
 const RESERVED_PROPS = [
   "children",
   "key",
@@ -587,6 +596,7 @@ function applyProps(object, props) {
         }
       }
     } else {
+      if (key === "material") assertNodeMaterialSupported(rootState, value);
       root[key] = value;
       if (key.endsWith("Node") && root.isMaterial) {
         root.needsUpdate = true;
@@ -13900,11 +13910,16 @@ function validateInstance(type, props, root) {
   const name = toPascalCase(type);
   const target = resolveConstructor(name, root);
   if (type !== "primitive" && !target) {
+    if (name.endsWith("NodeMaterial")) {
+      assertNodeMaterialSupported(root.getState(), { isNodeMaterial: true, type: name });
+    }
     throw new Error(
       `R3F: ${name} is not part of the THREE namespace! Did you forget to extend? See: https://docs.pmnd.rs/react-three-fiber/api/objects#using-3rd-party-objects-declaratively`
     );
   }
   if (type === "primitive" && !props.object) throw new Error(`R3F: Primitives without 'object' are invalid!`);
+  assertNodeMaterialSupported(root.getState(), props.object);
+  assertNodeMaterialSupported(root.getState(), props.material);
   if (props.args !== void 0 && !Array.isArray(props.args)) throw new Error("R3F: The args prop must be an array!");
 }
 function createInstance(type, props, root) {
@@ -14003,6 +14018,7 @@ function disposeOnIdle(object) {
 }
 function removeChild(parent, child, dispose) {
   if (!child) return;
+  const wasLinked = !!child.parent;
   child.parent = null;
   const childIndex = parent.children.indexOf(child);
   if (childIndex !== -1) parent.children.splice(childIndex, 1);
@@ -14022,7 +14038,10 @@ function removeChild(parent, child, dispose) {
   if (shouldDispose && child.type !== "primitive" && child.object.type !== "Scene") {
     disposeOnIdle(child.object);
   }
-  if (dispose === void 0) invalidateInstance(child);
+  if (dispose === void 0 && wasLinked) {
+    const state = findInitialRoot(child).getState();
+    if (state.internal.active && state.internal.frames === 0) state.invalidate();
+  }
 }
 function setFiberRef(fiber, publicInstance) {
   for (const _fiber of [fiber, fiber.alternate]) {
@@ -14771,6 +14790,69 @@ function getPrimaryIds() {
   return Array.from(primaryRegistry.keys());
 }
 
+const fulfilled = (value) => Object.assign(Promise.resolve(value), { status: "fulfilled", value });
+const tracked = (promise) => {
+  const result = Promise.resolve(promise);
+  result.status = "pending";
+  result.then(
+    (value) => {
+      Object.assign(result, { status: "fulfilled", value });
+    },
+    (reason) => {
+      Object.assign(result, { status: "rejected", reason });
+    }
+  );
+  return result;
+};
+
+const records = /* @__PURE__ */ new WeakMap();
+function take(renderer, record) {
+  record.leases++;
+  let released = false;
+  return () => {
+    if (released) return;
+    released = true;
+    if (--record.leases > 0) return;
+    records.delete(renderer);
+    if (record.owned) return disposeRenderer(renderer);
+  };
+}
+function leaseRenderer(renderer, owned) {
+  let record = records.get(renderer);
+  if (!record) records.set(renderer, record = { owned, leases: 0 });
+  return take(renderer, record);
+}
+function borrowRenderer(renderer) {
+  const record = records.get(renderer);
+  if (!record) throw new Error("R3F: cannot share a renderer whose canvas has already unmounted");
+  return take(renderer, record);
+}
+function disposeRenderer(renderer) {
+  if (renderer.hasInitialized?.() === false) return;
+  const warn = (error) => console.warn("[R3F] Error disposing renderer", error);
+  const loseContext = () => {
+    try {
+      ;
+      renderer.forceContextLoss?.();
+    } catch (error) {
+      warn(error);
+    }
+  };
+  let disposed;
+  try {
+    disposed = renderer.dispose();
+  } catch (error) {
+    warn(error);
+  }
+  if (typeof disposed?.then === "function") {
+    return Promise.resolve(disposed).then(loseContext, (error) => {
+      warn(error);
+      loseContext();
+    });
+  }
+  loseContext();
+}
+
 const isRenderer = (def) => !!def?.render;
 const _roots = /* @__PURE__ */ new Map();
 function ensureStoreThreeObjects(store) {
@@ -14782,9 +14864,9 @@ function ensureStoreThreeObjects(store) {
 }
 const shallowLoose = { objects: "shallow", strict: false };
 async function resolveRenderer(config, defaultProps, RendererClass) {
-  if (typeof config === "function") return await config(defaultProps);
-  if (isRenderer(config)) return config;
-  return new RendererClass({ ...defaultProps, ...config });
+  if (typeof config === "function") return { renderer: await config(defaultProps), owned: true };
+  if (isRenderer(config)) return { renderer: config, owned: false };
+  return { renderer: new RendererClass({ ...defaultProps, ...config }), owned: true };
 }
 function computeInitialSize(canvas, size) {
   if (!size && typeof HTMLCanvasElement !== "undefined" && canvas instanceof HTMLCanvasElement && canvas.parentElement) {
@@ -14800,6 +14882,34 @@ function computeInitialSize(canvas, size) {
   }
   return { width: 0, height: 0, top: 0, left: 0, ...size };
 }
+function watchDpr(onChange) {
+  if (typeof window === "undefined" || typeof window.matchMedia !== "function" || !window.devicePixelRatio) {
+    return () => {
+    };
+  }
+  let query;
+  const listen = () => {
+    try {
+      query = window.matchMedia(`(resolution: ${window.devicePixelRatio}dppx)`);
+      if (typeof query?.addEventListener === "function") query.addEventListener("change", handleChange);
+      else query?.addListener?.(handleChange);
+    } catch {
+      query = void 0;
+    }
+  };
+  const unlisten = () => {
+    if (typeof query?.removeEventListener === "function") query.removeEventListener("change", handleChange);
+    else query?.removeListener?.(handleChange);
+    query = void 0;
+  };
+  const handleChange = () => {
+    unlisten();
+    listen();
+    onChange();
+  };
+  listen();
+  return unlisten;
+}
 function createRoot(canvas, provider) {
   const prevRoot = _roots.get(canvas);
   const prevFiber = prevRoot?.fiber;
@@ -14836,15 +14946,39 @@ function createRoot(canvas, provider) {
     null
     // transitionCallbacks
   );
-  if (!prevRoot) _roots.set(canvas, { fiber, store });
+  const root = prevRoot || { fiber, store, unmountClaim: null, ready: fulfilled(void 0) };
+  if (!prevRoot) _roots.set(canvas, root);
   let onCreated;
   let lastCamera;
   const lastConfiguredProps = {};
+  let resolvedDpr = 0;
+  let dprChangedInXR = false;
+  let unwatchDpr;
+  const resolveDpr = () => {
+    if (_roots.get(canvas)?.store !== store) return unwatchDpr?.();
+    const state = store.getState();
+    const xr = state.internal.actualRenderer?.xr;
+    if (xr?.isPresenting || xr?.getSession?.()) {
+      dprChangedInXR = true;
+      return;
+    }
+    dprChangedInXR = false;
+    const dpr = lastConfiguredProps.dpr;
+    if (dpr === void 0 || state.viewport.dpr !== resolvedDpr || calculateDpr(dpr) === resolvedDpr) return;
+    state.setDpr(dpr);
+    resolvedDpr = store.getState().viewport.dpr;
+  };
   let configured = false;
   let pending = null;
-  let rendererSetup = null;
+  const cancelUnmount = () => {
+    if (!root.unmountClaim) return;
+    root.unmountClaim = null;
+    store.getState().internal.active = true;
+  };
   return {
     async configure(props = {}) {
+      if (_roots.get(canvas) !== root) throw new Error("R3F: cannot configure a root after it has unmounted");
+      cancelUnmount();
       let resolve;
       pending = new Promise((_resolve) => resolve = _resolve);
       const {
@@ -14918,20 +15052,23 @@ function createRoot(canvas, provider) {
         );
       }
       if (!state.internal.actualRenderer) {
-        if (!rendererSetup) {
-          rendererSetup = (async () => {
+        if (root.ready.status !== "pending") {
+          const setup = (async () => {
             const support = wantsGL ? await webgl() : await webgpu();
             registerThree(support.three);
             state.internal.support = support;
             ensureStoreThreeObjects(store);
             if (support.kind === "webgl") {
-              renderer = await resolveRenderer(glConfig, defaultGLProps, support.Renderer);
+              const resolved = await resolveRenderer(glConfig, defaultGLProps, support.Renderer);
+              renderer = resolved.renderer;
               state.internal.actualRenderer = renderer;
+              state.internal.releaseRenderer = leaseRenderer(renderer, resolved.owned);
               state.set({ isLegacy: true, gl: renderer, renderer, primaryStore: store });
             } else if (primaryCanvas) {
               const primary = await waitForPrimary(primaryCanvas);
               renderer = primary.renderer;
               state.internal.actualRenderer = renderer;
+              state.internal.releaseRenderer = borrowRenderer(renderer);
               const canvasTarget = new support.CanvasTarget(canvas);
               primary.store.setState((prev) => ({
                 internal: { ...prev.internal, isMultiCanvas: true }
@@ -14949,7 +15086,8 @@ function createRoot(canvas, provider) {
                 }
               }));
             } else {
-              renderer = await resolveRenderer(rendererConfig, defaultGPUProps, support.Renderer);
+              const resolved = await resolveRenderer(rendererConfig, defaultGPUProps, support.Renderer);
+              renderer = resolved.renderer;
               if (!renderer.hasInitialized?.()) {
                 const size2 = computeInitialSize(canvas, propsSize);
                 if (size2.width > 0 && size2.height > 0) {
@@ -14961,6 +15099,7 @@ function createRoot(canvas, provider) {
               const backend = renderer.backend;
               const isWebGPUBackend = backend && "isWebGPUBackend" in backend;
               state.internal.actualRenderer = renderer;
+              state.internal.releaseRenderer = leaseRenderer(renderer, resolved.owned);
               state.set({ webGPUSupported: isWebGPUBackend, renderer, primaryStore: store });
               if (canvasId && !state.internal.isSecondary) {
                 const canvasTarget = renderer.getCanvasTarget?.();
@@ -14974,12 +15113,10 @@ function createRoot(canvas, provider) {
                 }));
               }
             }
-          })().catch((err) => {
-            rendererSetup = null;
-            throw err;
-          });
+          })();
+          root.ready = tracked(setup);
         }
-        await rendererSetup;
+        await root.ready;
         state = store.getState();
         renderer = state.internal.actualRenderer;
       }
@@ -15058,6 +15195,12 @@ function createRoot(canvas, provider) {
       if (dpr !== void 0 && !is.equ(dpr, lastConfiguredProps.dpr, shallowLoose)) {
         state.setDpr(dpr);
         lastConfiguredProps.dpr = dpr;
+        resolvedDpr = store.getState().viewport.dpr;
+      }
+      const internal = store.getState().internal;
+      if (Array.isArray(dpr) && (!unwatchDpr || internal.unwatchDpr !== unwatchDpr)) {
+        internal.unwatchDpr?.();
+        internal.unwatchDpr = unwatchDpr = watchDpr(resolveDpr);
       }
       if (frameloop !== void 0 && frameloop !== lastConfiguredProps.frameloop) {
         state.setFrameloop(frameloop);
@@ -15086,7 +15229,10 @@ function createRoot(canvas, provider) {
           const renderer2 = state2.internal.actualRenderer;
           actualRenderer.xr.enabled = actualRenderer.xr.isPresenting;
           renderer2.xr.setAnimationLoop(renderer2.xr.isPresenting ? handleXRFrame : null);
-          if (!renderer2.xr.isPresenting) invalidate(state2);
+          if (!renderer2.xr.isPresenting) {
+            if (dprChangedInXR) resolveDpr();
+            invalidate(state2);
+          }
         };
         const xr = {
           connect() {
@@ -15296,8 +15442,11 @@ function createRoot(canvas, provider) {
       return this;
     },
     render(children) {
+      if (_roots.get(canvas) !== root) return store;
+      cancelUnmount();
       if (!configured && !pending) this.configure();
       pending.then(() => {
+        if (_roots.get(canvas) !== root || root.unmountClaim) return;
         reconciler.updateContainer(
           /* @__PURE__ */ jsxRuntime.jsx(Provider, { store, children, onCreated, rootElement: canvas }),
           fiber,
@@ -15308,7 +15457,7 @@ function createRoot(canvas, provider) {
       return store;
     },
     unmount() {
-      unmountComponentAtNode(canvas);
+      if (_roots.get(canvas) === root) unmountComponentAtNode(canvas);
     }
   };
 }
@@ -15328,46 +15477,52 @@ function Provider({
 }
 function unmountComponentAtNode(canvas, callback) {
   const root = _roots.get(canvas);
-  const fiber = root?.fiber;
-  if (fiber) {
-    const state = root?.store.getState();
-    if (state) {
-      state.internal.active = false;
-      const unregisterRoot = state.internal.unregisterRoot;
-      if (unregisterRoot) {
-        unregisterRoot();
-        state.internal.unregisterRoot = void 0;
+  if (!root) return;
+  const claim = root.unmountClaim = Symbol("unmount");
+  root.store.getState().internal.active = false;
+  reconciler.updateContainer(null, root.fiber, null, () => {
+    if (root.unmountClaim !== claim) return;
+    reconciler.updateContainer(null, root.fiber, null, () => {
+      if (root.unmountClaim !== claim) return;
+      if (root.ready.status === "pending") root.ready.then(teardown, teardown);
+      else teardown();
+    });
+  });
+  function teardown() {
+    if (root.unmountClaim !== claim) return;
+    root.unmountClaim = null;
+    _roots.delete(canvas);
+    const state = root.store.getState();
+    const internal = state.internal;
+    internal.active = false;
+    const attempt = (step) => {
+      try {
+        return step();
+      } catch (error) {
+        console.warn("[R3F] Error while unmounting root; teardown may be incomplete:", error);
       }
-    }
-    reconciler.updateContainer(null, fiber, null, () => {
-      if (root?.store) extensions.detachRootExtensions(root.store);
-      if (state) {
-        setTimeout(() => {
-          try {
-            const renderer = state.internal.actualRenderer;
-            const unregisterPrimary = state.internal.unregisterPrimary;
-            if (unregisterPrimary) unregisterPrimary();
-            const canvasTarget = state.internal.canvasTarget;
-            if (state.internal.isSecondary && canvasTarget?.dispose) canvasTarget.dispose();
-            state.events.disconnect?.();
-            cleanupHelperGroup(root.store);
-            if (state.isLegacy && renderer) {
-              ;
-              renderer.renderLists?.dispose?.();
-              renderer.forceContextLoss?.();
-            }
-            if (!state.internal.isSecondary) {
-              if (renderer?.xr) state.xr.disconnect();
-            }
-            dispose(state.scene);
-            _roots.delete(canvas);
-            if (callback) callback(canvas);
-          } catch (error) {
-            console.warn("[R3F] Error while unmounting root; teardown may be incomplete:", error);
-          }
-        }, 500);
+    };
+    attempt(() => internal.unwatchDpr?.());
+    internal.unwatchDpr = void 0;
+    attempt(() => internal.unregisterRoot?.());
+    internal.unregisterRoot = void 0;
+    attempt(() => extensions.detachRootExtensions(root.store));
+    attempt(() => internal.unregisterPrimary?.());
+    attempt(() => state.events.disconnect?.());
+    if (!internal.isSecondary && internal.actualRenderer?.xr && state.xr) attempt(() => state.xr.disconnect());
+    attempt(() => cleanupHelperGroup(root.store));
+    if (state.scene) attempt(() => dispose(state.scene));
+    const canvasTarget = internal.canvasTarget;
+    if (internal.isSecondary && canvasTarget?.dispose) attempt(() => canvasTarget.dispose());
+    const released = attempt(() => internal.releaseRenderer?.());
+    internal.releaseRenderer = void 0;
+    if (callback) {
+      if (released) {
+        released.then(() => callback(canvas)).catch((error) => console.warn("[R3F] Error in unmount callback", error));
+      } else {
+        callback(canvas);
       }
-    });
+    }
   }
 }
 function createPortal(children, container, state) {
@@ -15912,13 +16067,27 @@ function CanvasImpl({
       }
     };
   });
+  const insertionMounted = React__namespace.useRef(false);
+  React__namespace.useInsertionEffect(() => {
+    insertionMounted.current = true;
+    return () => {
+      insertionMounted.current = false;
+      queueMicrotask(() => {
+        if (insertionMounted.current) return;
+        const current = root.current;
+        root.current = null;
+        current?.unmount();
+      });
+    };
+  }, []);
   React__namespace.useEffect(() => {
     const canvas = canvasRef.current;
     if (canvas) {
       return () => {
         if (canvas.isConnected) return;
-        unmountComponentAtNode(canvas);
+        const current = root.current;
         root.current = null;
+        current?.unmount();
       };
     }
   }, []);
@@ -15932,7 +16101,7 @@ function CanvasImpl({
         if (rootEntry?.store) extensions.notifyRootExtensionsHmr(rootEntry.store);
       });
     };
-    if (typeof ({ url: (typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('shared/fiber.oKEFddXj.cjs', document.baseURI).href)) }) !== "undefined" && undefined) {
+    if (typeof ({ url: (typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('shared/fiber.BegWBc5_.cjs', document.baseURI).href)) }) !== "undefined" && undefined) {
       const hot = undefined;
       hot.on("vite:afterUpdate", handleHMR);
       return () => hot.off?.("vite:afterUpdate", handleHMR);

package/dist/shared/{fiber.BY6Yf1h-.d.cts → fiber.CQDCACCJ.d.mts}

@@ -3,7 +3,7 @@ import { ReactNode, Component, RefObject, JSX } from 'react';
 import { Options } from 'react-use-measure';
 import * as THREE from 'three';
 import { ColorRepresentation, Euler as Euler$1, Loader, RenderTargetOptions as RenderTargetOptions$1, ColorSpace, Texture as Texture$1, CubeTexture, Scene, Object3D } from 'three';
-import { J as Properties, c as Size, F as Frameloop, e as Performance, D as Dpr, g as RootStore, p as EventManager, f as RootState, n as ComputeFunction, C as ConstructorRepresentation, _ as ObjectMap, I as InternalState, M as Mutable, O as Overwrite, y as Args, l as EventHandlers, B as InstanceProps, k as DomEvent, G as Instance, x as Catalogue, v as Root, a6 as ThreeCore, W as Bridge, Z as UnblockProps, a0 as Disposable, Q as ThreeCamera, $ as EquConfig } from './fiber.I5Q4dVvl.cjs';
+import { K as Properties, c as Size, F as Frameloop, e as Performance, D as Dpr, g as RootStore, p as EventManager, f as RootState, n as ComputeFunction, C as ConstructorRepresentation, $ as ObjectMap, I as InternalState, M as Mutable, O as Overwrite, z as Args, l as EventHandlers, G as InstanceProps, k as DomEvent, H as Instance, y as Catalogue, w as Root, a7 as ThreeCore, Y as Bridge, _ as UnblockProps, a1 as Disposable, U as ThreeCamera, a0 as EquConfig } from './fiber.CZLeHcML.mjs';
 import { WebGPURenderer, WebGPURendererParameters } from 'three/webgpu';
 
 //* Base Renderer Types =====================================
@@ -155,8 +155,11 @@ interface RenderProps<TCanvas extends HTMLCanvasElement | OffscreenCanvas$1> {
   /** Dimensions to fit the renderer to. Will measure canvas dimensions if omitted */
   size?: Size
   /**
-   * Enables shadows (by default PCFsoft). Can accept `gl.shadowMap` options for fine-tuning,
-   * but also strings: 'basic' | 'percentage' | 'soft' | 'variance'.
+   * Enables shadows (`true` uses `THREE.PCFShadowMap`). Can accept `renderer.shadowMap` options for
+   * fine-tuning, but also strings: 'basic' | 'percentage' | 'soft' | 'variance'.
+   *
+   * `'soft'` is a deprecated alias of `'percentage'`: both map to `THREE.PCFShadowMap`, because three.js
+   * deprecated `PCFSoftShadowMap` and made `PCFShadowMap` soft. Using `'soft'` logs a deprecation notice.
    * @see https://threejs.org/docs/#api/en/renderers/WebGLRenderer.shadowMap
    */
   shadows?: boolean | 'basic' | 'percentage' | 'soft' | 'variance' | Partial<THREE.WebGLShadowMap>
@@ -540,8 +543,14 @@ type ThreeElement<T extends ConstructorRepresentation> = Mutable<
   Overwrite<ElementProps<T>, Omit<InstanceProps<InstanceType<T>, T>, 'object'>>
 >
 
+/**
+ * Every constructor export of a three namespace as an uncapitalized JSX element. Non-constructor
+ * exports (constants, functions, nested namespaces) are dropped from the keys rather than mapped
+ * to `never`: a single `never`-valued key in `JSX.IntrinsicElements` collapses the props of any
+ * tag typed `React.ElementType` (#3898).
+ */
 type ThreeToJSXElements<T extends Record<string, any>> = {
-  [K in keyof T & string as Uncapitalize<K>]: T[K] extends ConstructorRepresentation ? ThreeElement<T[K]> : never
+  [K in keyof T & string as T[K] extends ConstructorRepresentation ? Uncapitalize<K> : never]: ThreeElement<T[K]>
 }
 
 /** Method names of Object3D, excluded from the `primitive` element's typed props. */
@@ -2246,16 +2255,67 @@ declare namespace ReactReconciler {
     ): void;
 }
 
+/**
+ * Registers constructors so they can be rendered as JSX elements.
+ *
+ * - `extend({ OrbitControls })` makes each constructor available under its camelCased key
+ *   (`<orbitControls />`). Values that are not constructors are skipped, so a whole module
+ *   namespace can be passed.
+ * - `extend(MyClass)` registers one constructor and returns a component to render it with.
+ *
+ * Registrations are global, shared by every copy and entry of fiber, and are checked before the
+ * three namespace of a root's renderer when an element name is resolved.
+ *
+ * @example
+ * import { OrbitControls } from 'three/addons/controls/OrbitControls.js'
+ * extend({ OrbitControls })
+ * // <orbitControls args={[camera, gl.domElement]} />
+ *
+ * @example
+ * const Controls = extend(OrbitControls)
+ * // <Controls args={[camera, gl.domElement]} />
+ *
+ * @see https://docs.pmnd.rs/react-three-fiber/api/objects#using-3rd-party-objects-declaratively
+ */
 declare function extend<T extends ConstructorRepresentation>(objects: T): React$1.ExoticComponent<ThreeElement<T>>;
+/** Registers each constructor in `objects` under its key; see the first overload. */
 declare function extend<T extends Catalogue>(objects: T): void;
+/** Registers every constructor in a module namespace, skipping other exports; see the first overload. */
 declare function extend(objects: Record<string, unknown>): void;
 
+/**
+ * R3F's React reconciler: a mutation-mode host config that turns JSX elements into three.js objects.
+ * Each root's {@link RootStore} is its container, and children attach to `internal.container`
+ * (a portal's target) or else the root's `scene`.
+ *
+ * - **Element names** resolve through `extend()` registrations first, then the three namespace of
+ *   the root's renderer. A `three` prefix (`<threeLine>`) is stripped when no element by the
+ *   prefixed name exists. `<primitive object={...}>` wraps an existing object.
+ * - **Construction is deferred** until an instance is attached to a mounted parent, so a tree that
+ *   Suspense discards never creates three objects.
+ * - **Updates** apply only changed props. Changing `args` (or a primitive's `object`) reconstructs
+ *   the object instead; the swap happens in `resetAfterCommit`, before layout effects, so refs
+ *   already point to the new object.
+ * - **Removal** detaches the object and disposes it (at idle priority, or immediately in an `act`
+ *   test environment), unless it is a primitive, a `Scene`, or it or an ancestor has `dispose={null}`.
+ * - **Priority**: not the primary renderer, so it runs alongside react-dom, and update priority
+ *   follows react-dom's event priorities. View-transition commits are flushed synchronously, since
+ *   three has nothing to animate between commits.
+ *
+ * `createRoot`, `createPortal` and `flushSync` drive it; app code rarely needs it directly.
+ */
 declare const reconciler: ReactReconciler.Reconciler<RootStore, Instance<any>, void, Instance<any>, never, any>;
 
 declare const isRenderer: (def: any) => boolean;
 interface OffscreenCanvas extends EventTarget {
 }
 declare const _roots: Map<HTMLCanvasElement | OffscreenCanvas, Root>;
+/**
+ * Unmount the root on `canvas`. The teardown runs once React has committed the unmount, and waits
+ * for a renderer that is still being created. `callback` runs when the root is gone: after the
+ * teardown, and when it disposed a renderer R3F created whose `dispose()` is async (WebGPURenderer
+ * from three r186), after that dispose has settled.
+ */
 declare function unmountComponentAtNode<TCanvas extends HTMLCanvasElement | OffscreenCanvas>(canvas: TCanvas, callback?: (canvas: TCanvas) => void): void;
 declare function createPortal(children: ReactNode, container: THREE.Object3D | RefObject<THREE.Object3D | null> | RefObject<THREE.Object3D>, state?: InjectState): JSX.Element;
 interface PortalProps {
@@ -2272,6 +2332,30 @@ declare function Portal({ children, container, state }: PortalProps): JSX.Elemen
  */
 declare function flushSync<R>(fn: () => R): R;
 
+/**
+ * Creates the Zustand store that holds one root's {@link RootState}.
+ *
+ * The store starts unconfigured: the renderer, `camera`, `scene`, `raycaster`, `frustum` and `pointer`
+ * are `null` placeholders until the root's renderer support has loaded and `configure()` in
+ * `renderer.tsx` fills them in. Only core's part of `RootState` is created here; packages building on
+ * fiber add their own fields through root extensions.
+ *
+ * Besides the initial state, the store wires up:
+ * - `state.gl` and `state.renderer` as accessors over `internal.actualRenderer`. `gl` reports a
+ *   deprecation when user code reads it outside legacy mode.
+ * - `rootScene` following `scene` whenever `scene` is set to a real `THREE.Scene`.
+ * - On a size or DPR change: updating the camera and resizing the root's own canvas target (or the
+ *   renderer when there is none).
+ * - On a camera change: adding an unparented camera to `rootScene`, then refreshing the viewport and
+ *   (when `autoUpdateFrustum` is set) the frustum.
+ * - Calling `invalidate(state)` after every state change.
+ *
+ * `createRoot` calls this once per canvas.
+ *
+ * @param invalidate - Requests frames for a root. Bound into `state.invalidate` and called on every store change.
+ * @param advance - Steps a root manually. Bound into `state.advance`.
+ * @returns The root's store, which is also the reconciler container for that root.
+ */
 declare const createStore: (invalidate: (state?: RootState, frames?: number, stackFrames?: boolean) => void, advance: (timestamp: number, runGlobalEffects?: boolean, state?: RootState, frame?: XRFrame) => void) => RootStore;
 
 /** Whether any root has loaded a renderer yet. */

package/dist/shared/{fiber.B0oukOFO.mjs → fiber.CUKAa7Rv.mjs}

@@ -361,4 +361,4 @@ function notifyRootExtensionsHmr(store) {
   for (const setUpBy of applied.values()) current(registry, setUpBy).hmr?.(store);
 }
 
-export { Block as B, ErrorBoundary as E, useThree as a, useFrame as b, context as c, useIsomorphicLayoutEffect as d, useMutableCallback as e, useBridge as f, getTextureView as g, unstageTextures as h, stageTextures as i, detachRootExtensions as j, attachRootExtensions as k, notifyAlpha as l, notifyRootExtensionsHmr as m, notifyDepreciated as n, registerRootExtension as r, setRenderOverride as s, useStore as u };
+export { Block as B, ErrorBoundary as E, useThree as a, useFrame as b, context as c, useIsomorphicLayoutEffect as d, useMutableCallback as e, useBridge as f, getTextureView as g, unstageTextures as h, stageTextures as i, attachRootExtensions as j, detachRootExtensions as k, notifyAlpha as l, notifyRootExtensionsHmr as m, notifyDepreciated as n, registerRootExtension as r, setRenderOverride as s, useStore as u };

package/dist/shared/{fiber.I5Q4dVvl.d.cts → fiber.CZLeHcML.d.cts}

@@ -477,6 +477,11 @@ interface InternalState {
    * Selected once, from the entry's provider, and copied into portals with the rest of `internal`.
    */
   support: R3FRendererSupport
+  /**
+   * Releases this root's lease on its renderer. The last release disposes a renderer R3F created;
+   * a renderer passed in as an instance is never disposed by R3F.
+   */
+  releaseRenderer?: () => void | Promise<void>
   /** Global scheduler reference (for useFrame hook) */
   scheduler: SchedulerApi | null
   /**
@@ -489,6 +494,8 @@ interface InternalState {
   rootId?: string
   /** Function to unregister this root from the global scheduler */
   unregisterRoot?: () => void
+  /** Function to stop following devicePixelRatio changes */
+  unwatchDpr?: () => void
   /** Container for child attachment (scene for root, original container for portals) */
   container?: THREE.Object3D
   /**
@@ -660,9 +667,17 @@ type RootStore = UseBoundStoreWithEqualityFn<StoreApi<RootState>>
 // to avoid bundling @types/react-reconciler which causes absolute path issues
 type FiberRoot = any
 
+/** A promise tagged with its state, the protocol React's `use` reads */
+type TrackedPromise<T> = Promise<T> &
+  ({ status: 'pending' } | { status: 'fulfilled'; value: T } | { status: 'rejected'; reason: unknown })
+
 interface Root {
   fiber: FiberRoot
   store: RootStore
+  /** Set while a teardown waits on React. Configure and render clear it, which cancels the teardown */
+  unmountClaim: symbol | null
+  /** Pending only while a renderer is being created */
+  ready: TrackedPromise<unknown>
 }
 
 type AttachFnType<O = any> = (parent: any, self: O) => () => void
@@ -772,7 +787,14 @@ declare function useStore(): RootStore;
  */
 declare function useThree<T = RootState>(selector?: (state: RootState) => T, equalityFn?: <T>(state: T, newState: T) => boolean): T;
 
+/**
+ * React context that carries the current root's {@link RootStore}. Each root provides its store and
+ * each portal provides its own scoped one; `useStore`, and every hook built on it, reads it.
+ *
+ * Stored on `globalThis` under `Symbol.for('@react-three/fiber.context')`, so every copy and entry
+ * of fiber shares a single context.
+ */
 declare const context: React.Context<RootStore>;
 
-export { useStore as ag, useThree as ah, context as ai, registerRootExtension as r, setRenderOverride as s };
-export type { EquConfig as $, AttachFnType as A, InstanceProps as B, ConstructorRepresentation as C, Dpr as D, Events as E, Frameloop as F, Instance as G, HostConfig as H, InternalState as I, Properties as J, IsOptional as K, IsAllOptional as L, Mutable as M, NonFunctionKeys as N, Overwrite as O, PointerState as P, ThreeCamera as Q, R3FRenderTarget as R, Subscription as S, ThreeEvent as T, Act as U, Viewport as V, Bridge as W, XRManager as X, SetBlock as Y, UnblockProps as Z, ObjectMap as _, RootExtension as a, Disposable as a0, FrameNextState as a1, FrameState as a2, FrameNextCallback as a3, FrameCallback as a4, ThreeNamespace as a5, ThreeCore as a6, OcclusionSupport as a7, WebGLSupport as a8, WebGPUSupport as a9, RendererSupport as aa, RendererProvider as ab, Register as ac, RegisteredRenderer as ad, ForRegisteredRenderer as ae, R3FRendererSupport as af, R3FRenderer as b, Size as c, RenderCallback as d, Performance as e, RootState as f, RootStore as g, Intersection as h, Camera as i, IntersectionEvent as j, DomEvent as k, EventHandlers as l, FilterFunction as m, ComputeFunction as n, XRPointerConfig as o, EventManager as p, PointerCaptureTarget as q, VisibilityEntry as t, FiberRoot as u, Root as v, AttachType as w, Catalogue as x, Args as y, ArgsProp as z };
+export { useStore as ah, useThree as ai, context as aj, registerRootExtension as r, setRenderOverride as s };
+export type { ObjectMap as $, AttachFnType as A, ArgsProp as B, ConstructorRepresentation as C, Dpr as D, Events as E, Frameloop as F, InstanceProps as G, Instance as H, InternalState as I, HostConfig as J, Properties as K, IsOptional as L, Mutable as M, NonFunctionKeys as N, Overwrite as O, PointerState as P, IsAllOptional as Q, R3FRenderTarget as R, Subscription as S, ThreeEvent as T, ThreeCamera as U, Viewport as V, Act as W, XRManager as X, Bridge as Y, SetBlock as Z, UnblockProps as _, RootExtension as a, EquConfig as a0, Disposable as a1, FrameNextState as a2, FrameState as a3, FrameNextCallback as a4, FrameCallback as a5, ThreeNamespace as a6, ThreeCore as a7, OcclusionSupport as a8, WebGLSupport as a9, WebGPUSupport as aa, RendererSupport as ab, RendererProvider as ac, Register as ad, RegisteredRenderer as ae, ForRegisteredRenderer as af, R3FRendererSupport as ag, R3FRenderer as b, Size as c, RenderCallback as d, Performance as e, RootState as f, RootStore as g, Intersection as h, Camera as i, IntersectionEvent as j, DomEvent as k, EventHandlers as l, FilterFunction as m, ComputeFunction as n, XRPointerConfig as o, EventManager as p, PointerCaptureTarget as q, VisibilityEntry as t, FiberRoot as u, TrackedPromise as v, Root as w, AttachType as x, Catalogue as y, Args as z };