@react-three/fiber 10.0.0-canary.98da52a → 10.0.0-canary.a1c1d93

package/dist/shared/{fiber.CT-cCVjA.mjs → fiber.Dl_2kSXg.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';
@@ -13997,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);
@@ -14016,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]) {
@@ -14765,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) {
@@ -14776,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) {
@@ -14794,6 +14861,47 @@ 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;
+}
+async function createOwnedWebGPURenderer(rendererConfig, defaultGPUProps, canvas, propsSize, dpr, support) {
+  const resolved = await resolveRenderer(rendererConfig, defaultGPUProps, support.Renderer);
+  const renderer = resolved.renderer;
+  if (!renderer.hasInitialized?.()) {
+    const size = computeInitialSize(canvas, propsSize);
+    if (size.width > 0 && size.height > 0) {
+      renderer.setPixelRatio(calculateDpr(dpr));
+      renderer.setSize(size.width, size.height, false);
+    }
+    await renderer.init();
+  }
+  return { renderer, owned: resolved.owned };
+}
 function createRoot(canvas, provider) {
   const prevRoot = _roots.get(canvas);
   const prevFiber = prevRoot?.fiber;
@@ -14830,15 +14938,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 {
@@ -14912,49 +15044,82 @@ 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;
-              const canvasTarget = new support.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, support.Renderer);
-              if (!renderer.hasInitialized?.()) {
-                const size2 = computeInitialSize(canvas, propsSize);
-                if (size2.width > 0 && size2.height > 0) {
-                  renderer.setPixelRatio(calculateDpr(dpr));
-                  renderer.setSize(size2.width, size2.height, false);
-                }
-                await renderer.init();
+              if (primary.store.getState().webGPUSupported) {
+                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 }
+                }));
+                state.set((prev) => ({
+                  webGPUSupported: primary.store.getState().webGPUSupported,
+                  renderer,
+                  primaryStore: primary.store,
+                  internal: {
+                    ...prev.internal,
+                    canvasTarget,
+                    isMultiCanvas: true,
+                    isSecondary: true,
+                    targetId: primaryCanvas
+                  }
+                }));
+              } else {
+                const isPlainConfig = is.obj(rendererConfig) && !is.fun(rendererConfig) && !isRenderer(rendererConfig);
+                const { primaryCanvas: _peeled, ...rendererOptions } = isPlainConfig ? rendererConfig : {};
+                const fallbackConfig = is.fun(rendererConfig) || isRenderer(rendererConfig) ? rendererConfig : { ...rendererOptions, forceWebGL: true };
+                const resolved = await createOwnedWebGPURenderer(
+                  fallbackConfig,
+                  defaultGPUProps,
+                  canvas,
+                  propsSize,
+                  dpr,
+                  support
+                );
+                renderer = resolved.renderer;
+                const backend = renderer.backend;
+                const isWebGPUBackend = backend && "isWebGPUBackend" in backend;
+                state.internal.actualRenderer = renderer;
+                state.internal.releaseRenderer = leaseRenderer(renderer, resolved.owned);
+                state.set((prev) => ({
+                  webGPUSupported: isWebGPUBackend,
+                  renderer,
+                  primaryStore: store,
+                  internal: {
+                    ...prev.internal,
+                    canvasTarget: renderer.getCanvasTarget?.(),
+                    sharedRendererFallback: true
+                  }
+                }));
               }
+            } else {
+              const resolved = await createOwnedWebGPURenderer(
+                rendererConfig,
+                defaultGPUProps,
+                canvas,
+                propsSize,
+                dpr,
+                support
+              );
+              renderer = resolved.renderer;
               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?.();
@@ -14968,16 +15133,15 @@ 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;
       }
       const three = getThree();
+      const borrowsRenderer = state.internal.isSecondary === true;
       let raycaster = state.raycaster;
       if (!raycaster) state.set({ raycaster: raycaster = new three.Raycaster() });
       const { params, ...options } = raycastOptions || {};
@@ -15052,6 +15216,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);
@@ -15080,7 +15250,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() {
@@ -15096,10 +15269,10 @@ function createRoot(canvas, provider) {
             xrManager.removeEventListener("sessionend", handleSessionChange);
           }
         };
-        if (typeof renderer.xr?.addEventListener === "function") xr.connect();
+        if (!borrowsRenderer && typeof renderer.xr?.addEventListener === "function") xr.connect();
         state.set({ xr });
       }
-      if (renderer.shadowMap && !is.equ(shadows, lastConfiguredProps.shadows, shallowLoose)) {
+      if (!borrowsRenderer && renderer.shadowMap && !is.equ(shadows, lastConfiguredProps.shadows, shallowLoose)) {
         lastConfiguredProps.shadows = shadows;
         const oldEnabled = renderer.shadowMap.enabled;
         const oldType = renderer.shadowMap.type;
@@ -15128,7 +15301,7 @@ function createRoot(canvas, provider) {
           renderer.shadowMap.needsUpdate = true;
         }
       }
-      if (!configured) {
+      if (!configured && !borrowsRenderer) {
         renderer.outputColorSpace = three.SRGBColorSpace;
         renderer.toneMapping = three.ACESFilmicToneMapping;
       }
@@ -15137,7 +15310,7 @@ function createRoot(canvas, provider) {
         if (state.textureColorSpace !== textureColorSpace) state.set(() => ({ textureColorSpace }));
         lastConfiguredProps.textureColorSpace = textureColorSpace;
       }
-      const r3fProps = ["textureColorSpace"];
+      const r3fProps = ["textureColorSpace", "primaryCanvas", "scheduler"];
       const constructorOnlyProps = ["samples", "antialias", "alpha", "canvas", "powerPreference"];
       const nonApplyProps = [...r3fProps, ...constructorOnlyProps];
       if (glConfig && !is.fun(glConfig) && !isRenderer(glConfig) && !is.equ(glConfig, renderer, shallowLoose)) {
@@ -15147,7 +15320,7 @@ function createRoot(canvas, provider) {
         }
         applyProps(renderer, glProps);
       }
-      if (rendererConfig && !is.fun(rendererConfig) && !isRenderer(rendererConfig) && state.renderer) {
+      if (rendererConfig && !is.fun(rendererConfig) && !isRenderer(rendererConfig) && state.renderer && !borrowsRenderer) {
         const currentRenderer = state.renderer;
         if (!is.equ(rendererConfig, currentRenderer, shallowLoose)) {
           const rendererProps = {};
@@ -15290,8 +15463,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,
@@ -15302,7 +15478,7 @@ function createRoot(canvas, provider) {
       return store;
     },
     unmount() {
-      unmountComponentAtNode(canvas);
+      if (_roots.get(canvas) === root) unmountComponentAtNode(canvas);
     }
   };
 }
@@ -15322,46 +15498,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) {
@@ -15906,13 +16088,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.11sXr8Eb.d.cts → fiber.NwhGYEh-.d.ts}

@@ -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.CLTHZhZp.js';
 import { WebGPURenderer, WebGPURendererParameters } from 'three/webgpu';
 
 //* Base Renderer Types =====================================
@@ -2255,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 {
@@ -2281,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. */