@react-three/fiber 10.0.0-canary.c6846c3 → 10.0.0-canary.ce4bd5f

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+import * as three_examples_jsm_inspector_Inspector_js from 'three/examples/jsm/inspector/Inspector.js';
 import * as three_webgpu from 'three/webgpu';
 import { CubeRenderTarget, RenderTarget, WebGPURenderer, Node, StorageTexture, Data3DTexture, CanvasTarget, ShaderNodeObject, Euler as Euler$2, Color as Color$2, ColorRepresentation as ColorRepresentation$1, Layers as Layers$1, Raycaster, Intersection as Intersection$1, BufferGeometry, Matrix4 as Matrix4$1, Quaternion as Quaternion$1, Vector2 as Vector2$1, Vector3 as Vector3$1, Vector4 as Vector4$1, Matrix3 as Matrix3$1, Loader as Loader$1, ColorSpace, Texture as Texture$1, CubeTexture, Scene, Object3D, Frustum, OrthographicCamera } from 'three/webgpu';
 import * as THREE$1 from 'three';
@@ -47,6 +48,9 @@ function _mergeNamespaces(n, m) {
 declare const R3F_BUILD_LEGACY = true;
 declare const R3F_BUILD_WEBGPU = true;
 
+/** Lazily load the three Inspector. Keeps it out of the eager module graph — see note above. */
+declare function loadInspector(): Promise<typeof three_examples_jsm_inspector_Inspector_js.Inspector>;
+
 var THREE = /*#__PURE__*/_mergeNamespaces({
   __proto__: null,
   CubeRenderTarget: CubeRenderTarget,
@@ -58,7 +62,8 @@ var THREE = /*#__PURE__*/_mergeNamespaces({
   WebGLCubeRenderTarget: WebGLCubeRenderTarget,
   WebGLRenderTarget: WebGLRenderTarget,
   WebGLRenderer: WebGLRenderer,
-  WebGLRendererParameters: WebGLRendererParameters
+  WebGLRendererParameters: WebGLRendererParameters,
+  loadInspector: loadInspector
 }, [three_webgpu]);
 
 //* Utility Types ==============================
@@ -496,6 +501,18 @@ interface InternalState {
    * @see https://threejs.org/docs/#api/en/renderers/common/CanvasTarget
    */
   canvasTarget?: CanvasTarget
+  /**
+   * Set when this root's canvas target has been resized and the backend's cached render pass
+   * descriptor (which holds a depth-stencil view built once per canvas) is therefore stale.
+   *
+   * Flushed by the canvas-target job in the `start` phase, which is the only place this root's
+   * target is guaranteed to be the renderer's active one — `backend.updateSize()` operates on
+   * whatever `getCanvasTarget()` returns, so calling it from the resize subscription would
+   * invalidate some other canvas's descriptor instead.
+   *
+   * @see https://github.com/pmndrs/react-three-fiber/issues/3847
+   */
+  canvasTargetSizeDirty?: boolean
   /**
    * Whether multi-canvas rendering is active.
    * True when any canvas uses `renderer={{ primaryCanvas: 'id' }}` to share a renderer.
@@ -705,12 +722,19 @@ type DefaultRendererProps = {
  */
 interface CanvasSchedulerConfig {
   /**
-   * Render this canvas after another canvas completes.
-   * Pass the `id` of another canvas.
+   * Run this Canvas root before the referenced Canvas root id(s).
+   */
+  before?: string | string[]
+  /**
+   * Run this Canvas root after the referenced Canvas root id(s).
    */
-  after?: string
+  after?: string | string[]
   /**
-   * Limit this canvas's render rate (frames per second).
+   * Numeric root order. Lower values run first.
+   */
+  order?: number
+  /**
+   * Limit this Canvas's default render job (frames per second).
    */
   fps?: number
 }
@@ -1314,11 +1338,16 @@ declare global {
   /** Pass record - stores TSL pass nodes for render pipeline */
   type PassRecord = Record<string, any>
 
+  /** State passed to pipeline callbacks after the active pipeline has been created */
+  type RenderPipelineCallbackState = RootState & {
+    renderPipeline: ThreeRenderPipeline
+  }
+
   /** Setup callback - runs first to configure MRT, create additional passes */
-  type RenderPipelineSetupCallback = (state: RootState) => PassRecord | void
+  type RenderPipelineSetupCallback = (state: RenderPipelineCallbackState) => PassRecord | void
 
   /** Main callback - runs second to configure outputNode, create effect passes */
-  type RenderPipelineMainCallback = (state: RootState) => PassRecord | void
+  type RenderPipelineMainCallback = (state: RenderPipelineCallbackState) => PassRecord | void
 
   /** Return type for useRenderPipeline hook */
   interface UseRenderPipelineReturn {
@@ -1878,7 +1907,7 @@ declare namespace useLoader {
  *
  * @param callback - Function called each frame with (state, delta). Optional if you only need scheduler access.
  * @param priorityOrOptions - Either a priority number (backwards compat) or options object
- * @returns Controls object with step(), stepAll(), pause(), resume(), isPaused, id, scheduler
+ * @returns Controls object with step(), stepAll(), invalidate(), pause(), resume(), isPaused, id, rootId, scheduler
  *
  * @example
  * // Simple priority (backwards compat)
@@ -2174,7 +2203,10 @@ declare function addTail(callback: GlobalRenderCallback): () => void;
  * Invalidates the view, requesting a frame to be rendered.
  * In demand mode, this triggers the scheduler to run frames.
  *
- * @param state - Optional root state (ignored in new scheduler, kept for backwards compat)
+ * With a state argument, only that root's jobs run on the requested frames; other
+ * roots on 'demand' stay idle. Without one, every registered root is invalidated.
+ *
+ * @param state - Optional root state; targets the invalidation at that root
  * @param frames - Number of frames to request (default: 1)
  * @param stackFrames - If false, sets pendingFrames to frames. If true, adds to existing pendingFrames (default: false)
  *
@@ -2185,14 +2217,16 @@ declare function invalidate(state?: RootState, frames?: number, stackFrames?: bo
  * Advances the frameloop and runs render effects.
  * Useful for when manually rendering via `frameloop="never"`.
  *
+ * With a state argument, only that root is stepped. Without one, every
+ * registered root is stepped for backwards compatibility.
+ *
  * @param timestamp - The timestamp to use for this frame
  * @param runGlobalEffects - Ignored (kept for backwards compat, global effects always run)
- * @param state - Ignored (kept for backwards compat)
- * @param frame - Ignored (kept for backwards compat)
+ * @param state - Optional root state; targets the manual step at that root
  *
  * @see https://docs.pmnd.rs/react-three-fiber/api/additional-exports#advance
  */
-declare function advance(timestamp: number): void;
+declare function advance(timestamp: number, runGlobalEffects?: boolean, state?: RootState): void;
 
 /* eslint-disable @definitelytyped/no-unnecessary-generics */
 declare function ReactReconciler<

package/dist/index.mjs

@@ -1,7 +1,6 @@
 import * as webgpu from 'three/webgpu';
 import { CubeRenderTarget, RenderTarget, Frustum, Matrix4, Group, BoxGeometry, MeshBasicNodeMaterial, Mesh, Node, NodeUpdateType, Layers, ShaderMaterial, Uniform, SRGBColorSpace, RGBAFormat, UnsignedByteType, Vector3, Vector2, TextureLoader, Texture as Texture$1, CubeReflectionMapping, EquirectangularReflectionMapping, CubeTextureLoader, CanvasTarget, Raycaster, OrthographicCamera, PerspectiveCamera, Scene, PCFShadowMap, VSMShadowMap, BasicShadowMap, ACESFilmicToneMapping, WebGPURenderer, HalfFloatType, Color } from 'three/webgpu';
 import { WebGLCubeRenderTarget, WebGLRenderTarget, WebGLRenderer } from 'three';
-import { Inspector } from 'three/addons/inspector/Inspector.js';
 import { jsx, Fragment, jsxs } from 'react/jsx-runtime';
 import * as React from 'react';
 import React__default, { useRef, useMemo, useLayoutEffect, useEffect, useContext, useImperativeHandle, useCallback, useState } from 'react';
@@ -32,18 +31,22 @@ function _mergeNamespaces(n, m) {
 
 const R3F_BUILD_LEGACY = true;
 const R3F_BUILD_WEBGPU = true;
+async function loadInspector() {
+  const { Inspector } = await import('three/addons/inspector/Inspector.js');
+  return Inspector;
+}
 
 const THREE = /*#__PURE__*/_mergeNamespaces({
   __proto__: null,
   CubeRenderTarget: CubeRenderTarget,
   CubeRenderTargetCompat: CubeRenderTarget,
-  Inspector: Inspector,
   R3F_BUILD_LEGACY: R3F_BUILD_LEGACY,
   R3F_BUILD_WEBGPU: R3F_BUILD_WEBGPU,
   RenderTargetCompat: RenderTarget,
   WebGLCubeRenderTarget: WebGLCubeRenderTarget,
   WebGLRenderTarget: WebGLRenderTarget,
-  WebGLRenderer: WebGLRenderer
+  WebGLRenderer: WebGLRenderer,
+  loadInspector: loadInspector
 }, [webgpu]);
 
 const primaryRegistry = /* @__PURE__ */ new Map();
@@ -902,7 +905,7 @@ const createStore = (invalidate, advance) => {
                 size: newSize,
                 viewport: { ...s.viewport, ...getCurrentViewport(state2.camera, defaultTarget, newSize) }
               }));
-              getScheduler().invalidate();
+              get().invalidate();
             }
           }
           return;
@@ -917,15 +920,16 @@ const createStore = (invalidate, advance) => {
           viewport: { ...s.viewport, ...getCurrentViewport(state2.camera, defaultTarget, size) },
           _sizeImperative: true
         }));
-        getScheduler().invalidate();
+        get().invalidate();
       },
       setDpr: (dpr) => set((state2) => {
         const resolved = calculateDpr(dpr);
         return { viewport: { ...state2.viewport, dpr: resolved, initialDpr: state2.viewport.initialDpr || resolved } };
       }),
       setFrameloop: (frameloop = "always") => {
+        const rootId = get().internal.rootId;
+        if (rootId) getScheduler().setRootFrameloop(rootId, frameloop);
         set(() => ({ frameloop }));
-        getScheduler().frameloop = frameloop;
       },
       setError: (error) => set(() => ({ error })),
       error: null,
@@ -1041,17 +1045,10 @@ const createStore = (invalidate, advance) => {
       oldSize = size;
       oldDpr = viewport.dpr;
       updateCamera(camera, size);
-      if (internal.isSecondary && canvasTarget) {
-        if (viewport.dpr > 0) canvasTarget.setPixelRatio(viewport.dpr);
-        canvasTarget.setSize(size.width, size.height, false);
-      } else {
-        if (viewport.dpr > 0) actualRenderer.setPixelRatio(viewport.dpr);
-        actualRenderer.setSize(size.width, size.height, false);
-        if (canvasTarget) {
-          if (viewport.dpr > 0) canvasTarget.setPixelRatio(viewport.dpr);
-          canvasTarget.setSize(size.width, size.height, false);
-        }
-      }
+      const resizeTarget = canvasTarget ?? actualRenderer;
+      if (viewport.dpr > 0) resizeTarget.setPixelRatio(viewport.dpr);
+      resizeTarget.setSize(size.width, size.height, false);
+      internal.canvasTargetSizeDirty = true;
     }
     if (camera !== oldCamera) {
       oldCamera = camera;
@@ -1113,7 +1110,11 @@ function useLoader(loader, input, extensions, onProgress, cacheKey) {
   const results = cacheKeys.map(
     (key, index) => suspend(() => fn(loader, inputs[index]), [loader, key], { equal: is.equ })
   );
-  return Array.isArray(input) ? results : results[0];
+  const stableRef = useRef(null);
+  const previous = stableRef.current;
+  const stable = previous !== null && previous.length === results.length && previous.every((value, i) => value === results[i]) ? previous : results;
+  stableRef.current = stable;
+  return Array.isArray(input) ? stable : stable[0];
 }
 useLoader.preload = function(loader, input, extensions, onProgress, cacheKey) {
   const inputs = Array.isArray(input) ? input : [input];
@@ -1233,6 +1234,13 @@ function useFrame(callback, priorityOrOptions) {
        * Use for controlling the entire frame loop, adding phases, etc.
        */
       scheduler: scheduler2,
+      /**
+       * The root that currently owns this job. Resolve on access because ambient
+       * jobs can be adopted by a Canvas after the controls object is created.
+       */
+      get rootId() {
+        return getScheduler().getJobRootId(id);
+      },
       /**
        * Manually step this job only.
        * Bypasses FPS limiting - always runs.
@@ -1249,6 +1257,14 @@ function useFrame(callback, priorityOrOptions) {
       stepAll: (timestamp) => {
         getScheduler().step(timestamp);
       },
+      /**
+       * Request frames for this job's owning root without waking sibling roots.
+       */
+      invalidate: (frames, stackFrames) => {
+        const scheduler3 = getScheduler();
+        const rootId = scheduler3.getJobRootId(id);
+        if (rootId) scheduler3.invalidateRoot(rootId, frames, stackFrames);
+      },
       /**
        * Pause this job (set enabled=false).
        * Job remains registered but won't run.
@@ -1278,6 +1294,11 @@ function getUrls(input) {
   if (Array.isArray(input)) return input;
   return Object.values(input);
 }
+function inputSignature(input) {
+  if (typeof input === "string") return input;
+  if (Array.isArray(input)) return input.join("\0");
+  return Object.keys(input).sort().map((key) => `${key}\0${input[key]}`).join("
");
+}
 function allUrlsCached(urls, textureCache) {
   return urls.every((url) => textureCache.has(url));
 }
@@ -1303,18 +1324,19 @@ function useTexture(input, optionsOrOnLoad) {
   const onLoadRef = useRef(onLoad);
   onLoadRef.current = onLoad;
   const onLoadCalledForRef = useRef(null);
-  const urls = useMemo(() => getUrls(input), [input]);
+  const inputKey = useMemo(() => inputSignature(input), [input]);
+  const stableInput = useMemo(() => input, [inputKey]);
+  const urls = useMemo(() => getUrls(stableInput), [stableInput]);
   const cachedResult = useMemo(() => {
     if (!cache) return null;
     const textures = store.getState().textures;
     if (!allUrlsCached(urls, textures)) return null;
-    return buildFromCache(input, textures);
-  }, [cache, urls, input, store]);
+    return buildFromCache(stableInput, textures);
+  }, [cache, urls, stableInput, store]);
   const loadedTextures = useLoader(
     TextureLoader,
-    IsObject(input) ? Object.values(input) : input
+    IsObject(stableInput) ? Object.values(stableInput) : stableInput
   );
-  const inputKey = urls.join("\0");
   useLayoutEffect(() => {
     if (cachedResult) return;
     if (onLoadCalledForRef.current === inputKey) return;
@@ -1341,28 +1363,28 @@ function useTexture(input, optionsOrOnLoad) {
   }, [renderer, loadedTextures, cachedResult]);
   const mappedTextures = useMemo(() => {
     if (cachedResult) return cachedResult;
-    if (IsObject(input)) {
+    if (IsObject(stableInput)) {
       const keyed = {};
       const textureArray = loadedTextures;
       let i = 0;
-      for (const key in input) keyed[key] = textureArray[i++];
+      for (const key in stableInput) keyed[key] = textureArray[i++];
       return keyed;
     } else {
       return loadedTextures;
     }
-  }, [input, loadedTextures, cachedResult]);
+  }, [stableInput, loadedTextures, cachedResult]);
   useEffect(() => {
     if (!cache) return;
     const urlTextureMap = [];
-    if (typeof input === "string") {
-      urlTextureMap.push([input, mappedTextures]);
-    } else if (Array.isArray(input)) {
+    if (typeof stableInput === "string") {
+      urlTextureMap.push([stableInput, mappedTextures]);
+    } else if (Array.isArray(stableInput)) {
       const textureArray = mappedTextures;
-      input.forEach((url, i) => urlTextureMap.push([url, textureArray[i]]));
-    } else if (IsObject(input)) {
+      stableInput.forEach((url, i) => urlTextureMap.push([url, textureArray[i]]));
+    } else if (IsObject(stableInput)) {
       const textureRecord = mappedTextures;
-      for (const key in input) {
-        const url = input[key];
+      for (const key in stableInput) {
+        const url = stableInput[key];
         urlTextureMap.push([url, textureRecord[key]]);
       }
     }
@@ -1391,7 +1413,7 @@ function useTexture(input, optionsOrOnLoad) {
       }
       return { _textureRefs: refs };
     });
-  }, [cache, input, mappedTextures, store]);
+  }, [cache, stableInput, mappedTextures, store]);
   return mappedTextures;
 }
 useTexture.preload = (url) => useLoader.preload(TextureLoader, url);
@@ -1662,13 +1684,19 @@ function addTail(callback) {
   return getScheduler().onIdle(callback);
 }
 function invalidate(state, frames = 1, stackFrames = false) {
-  getScheduler().invalidate(frames, stackFrames);
+  const rootId = state?.internal?.rootId;
+  const scheduler = getScheduler();
+  if (rootId) scheduler.invalidateRoot(rootId, frames, stackFrames);
+  else scheduler.invalidate(frames, stackFrames);
 }
-function advance(timestamp) {
-  getScheduler().step(timestamp);
+function advance(timestamp, runGlobalEffects, state) {
+  const rootId = state?.internal?.rootId;
+  const scheduler = getScheduler();
+  if (rootId) scheduler.stepRoot(rootId, timestamp);
+  else scheduler.step(timestamp);
 }
 
-const version = "10.0.0-alpha.3";
+const version = "10.0.0-alpha.4";
 const packageData = {
 	version: version};
 
@@ -14327,7 +14355,7 @@ function createRoot(canvas) {
         const handleXRFrame = (timestamp, _frame) => {
           const state2 = store.getState();
           if (state2.frameloop === "never") return;
-          advance(timestamp);
+          advance(timestamp, true, state2);
         };
         const actualRenderer = state.internal.actualRenderer;
         const handleSessionChange = () => {
@@ -14335,7 +14363,7 @@ function createRoot(canvas) {
           const renderer2 = state2.internal.actualRenderer;
           actualRenderer.xr.enabled = actualRenderer.xr.isPresenting;
           renderer2.xr.setAnimationLoop(renderer2.xr.isPresenting ? handleXRFrame : null);
-          if (!renderer2.xr.isPresenting) invalidate();
+          if (!renderer2.xr.isPresenting) invalidate(state2);
         };
         const xr = {
           connect() {
@@ -14417,7 +14445,11 @@ function createRoot(canvas) {
         const newRootId = canvasId || scheduler.generateRootId();
         const unregisterRoot = scheduler.registerRoot(newRootId, {
           getState: () => store.getState(),
-          onError: (err) => store.getState().setError(err)
+          onError: (err) => store.getState().setError(err),
+          frameloop: store.getState().frameloop,
+          before: schedulerConfig?.before,
+          after: schedulerConfig?.after,
+          order: schedulerConfig?.order
         });
         const unregisterCanvasTarget = scheduler.register(
           () => {
@@ -14425,6 +14457,10 @@ function createRoot(canvas) {
             if (state2.internal.isMultiCanvas && state2.internal.canvasTarget) {
               const renderer2 = state2.internal.actualRenderer;
               renderer2.setCanvasTarget(state2.internal.canvasTarget);
+              if (state2.internal.canvasTargetSizeDirty) {
+                state2.internal.canvasTargetSizeDirty = false;
+                renderer2.backend?.updateSize?.();
+              }
             }
           },
           {
@@ -14493,8 +14529,7 @@ function createRoot(canvas) {
             phase: "render",
             system: true,
             // Internal flag: this is a system job, not user-controlled
-            // Apply scheduler config for render ordering and rate limiting
-            ...schedulerConfig?.after && { after: schedulerConfig.after },
+            // FPS throttles only the default render job; Canvas ordering belongs to the root.
             ...schedulerConfig?.fps && { fps: schedulerConfig.fps }
           }
         );
@@ -14513,8 +14548,21 @@ function createRoot(canvas) {
             scheduler
           }
         }));
+      } else {
+        const constraintsChanged = !is.equ(schedulerConfig?.before, lastConfiguredProps.schedulerBefore, shallowLoose) || !is.equ(schedulerConfig?.after, lastConfiguredProps.schedulerAfter, shallowLoose);
+        if (constraintsChanged) {
+          scheduler.setRootConstraints(rootId, {
+            before: schedulerConfig?.before,
+            after: schedulerConfig?.after
+          });
+        }
+        if (schedulerConfig?.order !== lastConfiguredProps.schedulerOrder) {
+          scheduler.setRootOrder(rootId, schedulerConfig?.order ?? 0);
+        }
       }
-      scheduler.frameloop = frameloop;
+      lastConfiguredProps.schedulerBefore = schedulerConfig?.before;
+      lastConfiguredProps.schedulerAfter = schedulerConfig?.after;
+      lastConfiguredProps.schedulerOrder = schedulerConfig?.order;
       onCreated = onCreatedCallback;
       configured = true;
       resolve();
@@ -14556,14 +14604,19 @@ function unmountComponentAtNode(canvas, callback) {
   const fiber = root?.fiber;
   if (fiber) {
     const state = root?.store.getState();
-    if (state) state.internal.active = false;
+    if (state) {
+      state.internal.active = false;
+      const unregisterRoot = state.internal.unregisterRoot;
+      if (unregisterRoot) {
+        unregisterRoot();
+        state.internal.unregisterRoot = void 0;
+      }
+    }
     reconciler.updateContainer(null, fiber, null, () => {
       if (state) {
         setTimeout(() => {
           try {
             const renderer = state.internal.actualRenderer;
-            const unregisterRoot = state.internal.unregisterRoot;
-            if (unregisterRoot) unregisterRoot();
             const unregisterPrimary = state.internal.unregisterPrimary;
             if (unregisterPrimary) unregisterPrimary();
             const canvasTarget = state.internal.canvasTarget;
@@ -15011,9 +15064,9 @@ function CanvasImpl({
   React.useMemo(() => extend(THREE), []);
   const Bridge = useBridge();
   const backgroundProps = React.useMemo(() => parseBackground(background), [background]);
-  const hasInitialSizeRef = React.useRef(false);
+  const [hasInitialSize, setHasInitialSize] = React.useState(false);
   const measureConfig = React.useMemo(() => {
-    if (!hasInitialSizeRef.current) {
+    if (!hasInitialSize) {
       return {
         ...resize,
         scroll: resize?.scroll ?? true,
@@ -15025,7 +15078,7 @@ function CanvasImpl({
       debounce: { scroll: 50, resize: 0 },
       ...resize
     };
-  }, [resize, hasInitialSizeRef.current]);
+  }, [hasInitialSize, resize]);
   const [containerRef, containerRect] = useMeasure(measureConfig);
   const effectiveSize = React.useMemo(() => {
     let w = width ?? containerRect.width;
@@ -15041,9 +15094,7 @@ function CanvasImpl({
       left: containerRect.left
     };
   }, [width, height, containerRect, forceEven]);
-  if (!hasInitialSizeRef.current && effectiveSize.width > 0 && effectiveSize.height > 0) {
-    hasInitialSizeRef.current = true;
-  }
+  if (!hasInitialSize && effectiveSize.width > 0 && effectiveSize.height > 0) setHasInitialSize(true);
   const canvasRef = React.useRef(null);
   const divRef = React.useRef(null);
   React.useImperativeHandle(ref, () => canvasRef.current);
@@ -15157,6 +15208,7 @@ function CanvasImpl({
     const canvas = canvasRef.current;
     if (canvas) {
       return () => {
+        if (canvas.isConnected) return;
         unmountComponentAtNode(canvas);
         root.current = null;
       };