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

package/dist/shared/{fiber.tsM9NKZ9.mjs → fiber.5Q8N6Hhq.mjs}

@@ -1,5 +1,5 @@
 import { jsx, Fragment, jsxs } from 'react/jsx-runtime';
-import { n as notifyDepreciated, a as useThree, u as useStore, h as unstageTextures, i as stageTextures, j as detachRootExtensions, k as attachRootExtensions, d as useIsomorphicLayoutEffect, e as useMutableCallback, c as context, b as useFrame, f as useBridge, l as notifyAlpha, E as ErrorBoundary, B as Block, m as notifyRootExtensionsHmr } from './fiber.B0oukOFO.mjs';
+import { n as notifyDepreciated, a as useThree, u as useStore, h as unstageTextures, i as stageTextures, j as attachRootExtensions, k as detachRootExtensions, d as useIsomorphicLayoutEffect, e as useMutableCallback, c as context, b as useFrame, f as useBridge, l as notifyAlpha, E as ErrorBoundary, B as Block, m as notifyRootExtensionsHmr } from './fiber.CUKAa7Rv.mjs';
 import * as React from 'react';
 import React__default, { useRef, useMemo, useLayoutEffect, useEffect, useImperativeHandle, useCallback, useState } from 'react';
 import useMeasure from 'react-use-measure';
@@ -396,6 +396,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",
@@ -566,6 +575,7 @@ function applyProps(object, props) {
         }
       }
     } else {
+      if (key === "material") assertNodeMaterialSupported(rootState, value);
       root[key] = value;
       if (key.endsWith("Node") && root.isMaterial) {
         root.needsUpdate = true;
@@ -13879,11 +13889,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) {
@@ -13982,6 +13997,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);
@@ -14001,7 +14017,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]) {
@@ -14750,6 +14769,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) {
@@ -14761,9 +14843,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) {
@@ -14779,6 +14861,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;
@@ -14815,15 +14925,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 {
@@ -14897,20 +15031,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 }
@@ -14928,7 +15065,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) {
@@ -14940,6 +15078,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?.();
@@ -14953,12 +15092,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;
       }
@@ -15037,6 +15174,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);
@@ -15065,7 +15208,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() {
@@ -15275,8 +15421,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__ */ jsx(Provider, { store, children, onCreated, rootElement: canvas }),
           fiber,
@@ -15287,7 +15436,7 @@ function createRoot(canvas, provider) {
       return store;
     },
     unmount() {
-      unmountComponentAtNode(canvas);
+      if (_roots.get(canvas) === root) unmountComponentAtNode(canvas);
     }
   };
 }
@@ -15307,46 +15456,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) 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(() => 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) {
@@ -15891,13 +16046,27 @@ function CanvasImpl({
       }
     };
   });
+  const insertionMounted = React.useRef(false);
+  React.useInsertionEffect(() => {
+    insertionMounted.current = true;
+    return () => {
+      insertionMounted.current = false;
+      queueMicrotask(() => {
+        if (insertionMounted.current) return;
+        const current = root.current;
+        root.current = null;
+        current?.unmount();
+      });
+    };
+  }, []);
   React.useEffect(() => {
     const canvas = canvasRef.current;
     if (canvas) {
       return () => {
         if (canvas.isConnected) return;
-        unmountComponentAtNode(canvas);
+        const current = root.current;
         root.current = null;
+        current?.unmount();
       };
     }
   }, []);

package/dist/shared/{fiber.Cx-UAmMb.d.ts → fiber.B_GGVI86.d.ts}

@@ -1,4 +1,4 @@
-import { a3 as FrameNextCallback } from './fiber.I5Q4dVvl.js';
+import { a4 as FrameNextCallback } from './fiber.CZLeHcML.js';
 import { UseFrameNextOptions, FrameNextControls } from '@pmndrs/scheduler';
 
 /**

package/dist/shared/{fiber.DXw-SLsH.d.ts → fiber.BcNm6NAg.d.cts}

@@ -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.js';
+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.cjs';
 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. */