@react-three/fiber 10.0.0-canary.ba354c7 → 10.0.0-canary.c385e9f

package/dist/legacy.cjs

@@ -50,11 +50,9 @@ const Tb__default = /*#__PURE__*/_interopDefaultCompat(Tb);
 
 const R3F_BUILD_LEGACY = true;
 const R3F_BUILD_WEBGPU = false;
-const Inspector = class Inspector2 {
-  constructor() {
-    throw new Error("Inspector is not available in legacy builds. Use @react-three/fiber/webgpu instead.");
-  }
-};
+async function loadInspector() {
+  throw new Error("Inspector is not available in legacy builds. Use @react-three/fiber/webgpu instead.");
+}
 const WebGPURenderer = class WebGPURenderer2 {
   constructor() {
     throw new Error("WebGPURenderer is not available in legacy builds. Use @react-three/fiber/webgpu instead.");
@@ -67,12 +65,12 @@ const THREE = /*#__PURE__*/_mergeNamespaces({
   __proto__: null,
   CubeRenderTarget: CubeRenderTarget,
   CubeRenderTargetCompat: three.WebGLCubeRenderTarget,
-  Inspector: Inspector,
   R3F_BUILD_LEGACY: R3F_BUILD_LEGACY,
   R3F_BUILD_WEBGPU: R3F_BUILD_WEBGPU,
   RenderTarget: RenderTarget,
   RenderTargetCompat: three.WebGLRenderTarget,
-  WebGPURenderer: WebGPURenderer
+  WebGPURenderer: WebGPURenderer,
+  loadInspector: loadInspector
 }, [three__namespace]);
 
 const primaryRegistry = /* @__PURE__ */ new Map();
@@ -931,7 +929,7 @@ const createStore = (invalidate, advance) => {
                 size: newSize,
                 viewport: { ...s.viewport, ...getCurrentViewport(state2.camera, defaultTarget, newSize) }
               }));
-              scheduler.getScheduler().invalidate();
+              get().invalidate();
             }
           }
           return;
@@ -946,15 +944,16 @@ const createStore = (invalidate, advance) => {
           viewport: { ...s.viewport, ...getCurrentViewport(state2.camera, defaultTarget, size) },
           _sizeImperative: true
         }));
-        scheduler.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) scheduler.getScheduler().setRootFrameloop(rootId, frameloop);
         set(() => ({ frameloop }));
-        scheduler.getScheduler().frameloop = frameloop;
       },
       setError: (error) => set(() => ({ error })),
       error: null,
@@ -1070,17 +1069,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;
@@ -1142,7 +1134,11 @@ function useLoader(loader, input, extensions, onProgress, cacheKey) {
   const results = cacheKeys.map(
     (key, index) => suspendReact.suspend(() => fn(loader, inputs[index]), [loader, key], { equal: is.equ })
   );
-  return Array.isArray(input) ? results : results[0];
+  const stableRef = React.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];
@@ -1262,6 +1258,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 scheduler.getScheduler().getJobRootId(id);
+      },
       /**
        * Manually step this job only.
        * Bypasses FPS limiting - always runs.
@@ -1278,6 +1281,14 @@ function useFrame(callback, priorityOrOptions) {
       stepAll: (timestamp) => {
         scheduler.getScheduler().step(timestamp);
       },
+      /**
+       * Request frames for this job's owning root without waking sibling roots.
+       */
+      invalidate: (frames, stackFrames) => {
+        const scheduler3 = scheduler.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.
@@ -1307,6 +1318,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));
 }
@@ -1332,18 +1348,19 @@ function useTexture(input, optionsOrOnLoad) {
   const onLoadRef = React.useRef(onLoad);
   onLoadRef.current = onLoad;
   const onLoadCalledForRef = React.useRef(null);
-  const urls = React.useMemo(() => getUrls(input), [input]);
+  const inputKey = React.useMemo(() => inputSignature(input), [input]);
+  const stableInput = React.useMemo(() => input, [inputKey]);
+  const urls = React.useMemo(() => getUrls(stableInput), [stableInput]);
   const cachedResult = React.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(
     three.TextureLoader,
-    IsObject(input) ? Object.values(input) : input
+    IsObject(stableInput) ? Object.values(stableInput) : stableInput
   );
-  const inputKey = urls.join("\0");
   React.useLayoutEffect(() => {
     if (cachedResult) return;
     if (onLoadCalledForRef.current === inputKey) return;
@@ -1370,28 +1387,28 @@ function useTexture(input, optionsOrOnLoad) {
   }, [renderer, loadedTextures, cachedResult]);
   const mappedTextures = React.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]);
   React.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]]);
       }
     }
@@ -1420,7 +1437,7 @@ function useTexture(input, optionsOrOnLoad) {
       }
       return { _textureRefs: refs };
     });
-  }, [cache, input, mappedTextures, store]);
+  }, [cache, stableInput, mappedTextures, store]);
   return mappedTextures;
 }
 useTexture.preload = (url) => useLoader.preload(three.TextureLoader, url);
@@ -1689,13 +1706,19 @@ function addTail(callback) {
   return scheduler.getScheduler().onIdle(callback);
 }
 function invalidate(state, frames = 1, stackFrames = false) {
-  scheduler.getScheduler().invalidate(frames, stackFrames);
+  const rootId = state?.internal?.rootId;
+  const scheduler$1 = scheduler.getScheduler();
+  if (rootId) scheduler$1.invalidateRoot(rootId, frames, stackFrames);
+  else scheduler$1.invalidate(frames, stackFrames);
 }
-function advance(timestamp) {
-  scheduler.getScheduler().step(timestamp);
+function advance(timestamp, runGlobalEffects, state) {
+  const rootId = state?.internal?.rootId;
+  const scheduler$1 = scheduler.getScheduler();
+  if (rootId) scheduler$1.stepRoot(rootId, timestamp);
+  else scheduler$1.step(timestamp);
 }
 
-const version = "10.0.0-alpha.3";
+const version = "10.0.0-alpha.4";
 const packageData = {
 	version: version};
 
@@ -14307,7 +14330,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 = () => {
@@ -14315,7 +14338,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() {
@@ -14397,7 +14420,11 @@ function createRoot(canvas) {
         const newRootId = canvasId || scheduler$1.generateRootId();
         const unregisterRoot = scheduler$1.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$1.register(
           () => {
@@ -14405,6 +14432,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?.();
+              }
             }
           },
           {
@@ -14473,8 +14504,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 }
           }
         );
@@ -14493,8 +14523,21 @@ function createRoot(canvas) {
             scheduler: scheduler$1
           }
         }));
+      } else {
+        const constraintsChanged = !is.equ(schedulerConfig?.before, lastConfiguredProps.schedulerBefore, shallowLoose) || !is.equ(schedulerConfig?.after, lastConfiguredProps.schedulerAfter, shallowLoose);
+        if (constraintsChanged) {
+          scheduler$1.setRootConstraints(rootId, {
+            before: schedulerConfig?.before,
+            after: schedulerConfig?.after
+          });
+        }
+        if (schedulerConfig?.order !== lastConfiguredProps.schedulerOrder) {
+          scheduler$1.setRootOrder(rootId, schedulerConfig?.order ?? 0);
+        }
       }
-      scheduler$1.frameloop = frameloop;
+      lastConfiguredProps.schedulerBefore = schedulerConfig?.before;
+      lastConfiguredProps.schedulerAfter = schedulerConfig?.after;
+      lastConfiguredProps.schedulerOrder = schedulerConfig?.order;
       onCreated = onCreatedCallback;
       configured = true;
       resolve();
@@ -14536,14 +14579,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;
@@ -14991,9 +15039,9 @@ function CanvasImpl({
   React__namespace.useMemo(() => extend(THREE), []);
   const Bridge = useBridge();
   const backgroundProps = React__namespace.useMemo(() => parseBackground(background), [background]);
-  const hasInitialSizeRef = React__namespace.useRef(false);
+  const [hasInitialSize, setHasInitialSize] = React__namespace.useState(false);
   const measureConfig = React__namespace.useMemo(() => {
-    if (!hasInitialSizeRef.current) {
+    if (!hasInitialSize) {
       return {
         ...resize,
         scroll: resize?.scroll ?? true,
@@ -15005,7 +15053,7 @@ function CanvasImpl({
       debounce: { scroll: 50, resize: 0 },
       ...resize
     };
-  }, [resize, hasInitialSizeRef.current]);
+  }, [hasInitialSize, resize]);
   const [containerRef, containerRect] = useMeasure__default(measureConfig);
   const effectiveSize = React__namespace.useMemo(() => {
     let w = width ?? containerRect.width;
@@ -15021,9 +15069,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__namespace.useRef(null);
   const divRef = React__namespace.useRef(null);
   React__namespace.useImperativeHandle(ref, () => canvasRef.current);
@@ -15137,6 +15183,7 @@ function CanvasImpl({
     const canvas = canvasRef.current;
     if (canvas) {
       return () => {
+        if (canvas.isConnected) return;
         unmountComponentAtNode(canvas);
         root.current = null;
       };

package/dist/legacy.d.cts

@@ -38,9 +38,9 @@ function _mergeNamespaces(n, m) {
 declare const R3F_BUILD_LEGACY = true;
 declare const R3F_BUILD_WEBGPU = false;
 
-declare const Inspector: {
-    new (): {};
-};
+type Inspector = never;
+/** Not available on the legacy (WebGL-only) entry. */
+declare function loadInspector(): Promise<never>;
 declare const WebGPURenderer: {
     new (): {};
 };
@@ -58,7 +58,8 @@ var THREE = /*#__PURE__*/_mergeNamespaces({
   R3F_BUILD_WEBGPU: R3F_BUILD_WEBGPU,
   RenderTarget: RenderTarget,
   RenderTargetCompat: WebGLRenderTarget,
-  WebGPURenderer: WebGPURenderer
+  WebGPURenderer: WebGPURenderer,
+  loadInspector: loadInspector
 }, [THREE$1]);
 
 //* Utility Types ==============================
@@ -358,6 +359,33 @@ type BufferRecord = Record<string, BufferLike>
  */
 type BufferStore = Record<string, BufferLike | BufferRecord>
 
+//* Node Types (useNodes) ========================================
+
+/**
+ * Structural shape of a TSL node as stored on `state.nodes`.
+ *
+ * Deliberately minimal rather than three's nominal `Node`: in @types/three several node classes
+ * TSL hands back (OperatorNode, ConstNode, ...) do not extend `Node` cleanly, so a `Node` bound
+ * would reject values `useNodes` creators legitimately return. This is the same shape
+ * `useNodes` already constrains creators to (`TSLNodeLike`).
+ */
+interface NodeLike {
+  uuid?: string
+  nodeType?: string | null
+  /** label method for chaining - sets the node's label and returns self */
+  label?: ((label: string) => NodeLike) | string
+  setName?: (name: string) => this
+}
+
+/** Flat record of TSL nodes (no nested scopes) */
+type NodeRecord = Record<string, NodeLike>
+
+/**
+ * Node store that can contain both root-level nodes and scoped node objects.
+ * Structure: { wobble: OperatorNode, fx: { blur: ShaderCallable } }
+ */
+type NodeStore = Record<string, NodeLike | NodeRecord>
+
 //* Storage Types (useGPUStorage) ========================================
 
 /**
@@ -496,6 +524,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.
@@ -605,7 +645,7 @@ interface RootState {
   /** Global TSL uniform nodes - root-level uniforms + scoped sub-objects. Use useUniforms() hook */
   uniforms: UniformStore
   /** Global TSL nodes - root-level nodes + scoped sub-objects. Use useNodes() hook */
-  nodes: Record<string, any>
+  nodes: NodeStore
   /** Global TSL buffer nodes - root-level buffers + scoped sub-objects. Use useBuffers() hook */
   buffers: BufferStore
   /** Global GPU storage (textures, etc.) - root-level storage + scoped sub-objects. Use useGPUStorage() hook */
@@ -617,7 +657,7 @@ interface RootState {
   /** WebGPU RenderPipeline instance - use useRenderPipeline() hook */
   renderPipeline: ThreeRenderPipeline | null
   /** Global TSL pass nodes for render pipeline - use useRenderPipeline() hook */
-  passes: Record<string, any>
+  passes: PassRecord
   /** Internal version counter for HMR - incremented by rebuildNodes/rebuildUniforms to bust memoization */
   _hmrVersion: number
   /** Internal: whether setSize() has taken ownership of canvas dimensions */
@@ -705,12 +745,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
 }
@@ -1158,7 +1205,33 @@ declare global {
    * ergonomics. The result is three's structural type, so members stay in sync with the
    * installed three instead of needing to be mirrored by hand.
    */
-  type UniformNode<T = unknown> = three_webgpu.UniformNode<unknown, T>
+  type UniformNode<T = unknown> = three_webgpu.UniformNode<UniformNodeTypeFor<T>, T>
+
+  /**
+   * three's node type name for a uniform value type, mirroring the `uniform()` overloads.
+   * A `UniformNode<number>` is a `Node<'float'>`, so TSL math (`.mul`, `.add`, ...) accepts it.
+   * Unknown or unlisted value types resolve to `unknown`, which TSL math rejects: narrow with
+   * `as UniformNode<number>` (or the matching value type) at the call site.
+   */
+  type UniformNodeTypeFor<T> = T extends number
+    ? 'float'
+    : T extends boolean
+      ? 'bool'
+      : T extends three_webgpu.Color
+        ? 'color'
+        : T extends three_webgpu.Vector2
+          ? 'vec2'
+          : T extends three_webgpu.Vector3
+            ? 'vec3'
+            : T extends three_webgpu.Vector4
+              ? 'vec4'
+              : T extends three_webgpu.Matrix2
+                ? 'mat2'
+                : T extends three_webgpu.Matrix3
+                  ? 'mat3'
+                  : T extends three_webgpu.Matrix4
+                    ? 'mat4'
+                    : unknown
 
   /**
    * ShaderCallable - the return type of Fn()
@@ -1311,30 +1384,97 @@ declare global {
    */
   type ThreeRenderPipeline = three_webgpu.RenderPipeline
 
-  /** Pass record - stores TSL pass nodes for render pipeline */
-  type PassRecord = Record<string, any>
+  /**
+   * The pass `useRenderPipeline` creates for you: three's own `PassNode`, as returned by
+   * `pass(scene, camera)` from `three/tsl`. Referenced from three so members like
+   * `getTextureNode`, `setMRT` and `dispose` track the installed version.
+   */
+  type ScenePassNode = three_webgpu.PassNode
+
+  /**
+   * Pass record - stores TSL pass nodes for render pipeline.
+   *
+   * `scenePass` is the only key the library owns. It is optional here because this is also the
+   * shape of `state.passes`, which is `{}` before the pipeline exists and again after `reset()`
+   * or `clearPasses()`. Inside the callbacks it is always present; see
+   * {@link RenderPipelineCallbackState}.
+   *
+   * Every other key is user-registered, via a callback's return value. Those are TSL nodes of
+   * any kind, not only passes: texture reads of an MRT attachment, effect nodes, extra
+   * `pass()` instances. `Node` is the common base, so that is the bound. Narrow at the call
+   * site when you need a member, e.g. `passes.velocity as TextureNode`.
+   */
+  interface PassRecord {
+    scenePass?: ScenePassNode
+    [key: string]: three_webgpu.Node
+  }
+
+  /**
+   * State passed to pipeline callbacks after the active pipeline has been created.
+   *
+   * `passes.scenePass` is required here: the hook installs the default scene pass before either
+   * callback runs, so callbacks can use it without a guard or a cast.
+   *
+   * `renderer` is narrowed to `WebGPURenderer` and `isLegacy` to `false`: the hook throws under
+   * the legacy renderer before either callback can run, so a callback never sees WebGL.
+   */
+  type RenderPipelineCallbackState = RootState & {
+    renderPipeline: ThreeRenderPipeline
+    passes: PassRecord & { scenePass: ScenePassNode }
+    renderer: three_webgpu.WebGPURenderer
+    isLegacy: false
+  }
+
+  /**
+   * What a callback may return to register entries into `state.passes`.
+   *
+   * `scenePass` is reserved. The hook owns that entry and its lifecycle: it caches the pass it
+   * created, and `rebuild()` / `reset()` dispose that cached pass. A callback overwriting the
+   * store entry would leave the store pointing at a node the hook never disposes, and the hook
+   * disposing a pass nothing references. So returning it is a type error.
+   */
+  type RegisteredPasses = Record<string, three_webgpu.Node> & { scenePass?: never }
 
   /** Setup callback - runs first to configure MRT, create additional passes */
-  type RenderPipelineSetupCallback = (state: RootState) => PassRecord | void
+  type RenderPipelineSetupCallback = (state: RenderPipelineCallbackState) => RegisteredPasses | void
 
   /** Main callback - runs second to configure outputNode, create effect passes */
-  type RenderPipelineMainCallback = (state: RootState) => PassRecord | void
+  type RenderPipelineMainCallback = (state: RenderPipelineCallbackState) => RegisteredPasses | void
 
-  /** Return type for useRenderPipeline hook */
-  interface UseRenderPipelineReturn {
+  /** The imperative half of useRenderPipeline's return value, present in every state */
+  interface UseRenderPipelineActions {
     /** Current passes from state */
     passes: PassRecord
-    /** RenderPipeline instance (null if not initialized) */
-    renderPipeline: ThreeRenderPipeline | null
     /** Clear all passes from state */
     clearPasses: () => void
     /** Reset RenderPipeline entirely (clears PP + passes) */
     reset: () => void
     /** Re-run setup/main callbacks with current closure values */
     rebuild: () => void
-    /** True when RenderPipeline is configured and ready */
-    isReady: boolean
   }
+
+  /**
+   * Return type for useRenderPipeline hook, discriminated on `isReady`.
+   *
+   * `if (isReady)` narrows `renderPipeline` to non-null, which is what the docs already tell
+   * callers to check. `passes.scenePass` deliberately stays optional in the ready branch:
+   * `clearPasses()` empties the record while leaving the pipeline in place.
+   */
+  type UseRenderPipelineReturn = UseRenderPipelineActions &
+    (
+      | {
+          /** True when RenderPipeline is configured and ready */
+          isReady: true
+          /** RenderPipeline instance */
+          renderPipeline: ThreeRenderPipeline
+        }
+      | {
+          /** False until the pipeline has been created */
+          isReady: false
+          /** Not initialized yet, or torn down by reset() */
+          renderPipeline: null
+        }
+    )
 }
 
 type MutableOrReadonlyParameters<T extends (...args: any) => any> = Parameters<T> | Readonly<Parameters<T>>
@@ -1878,7 +2018,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 +2314,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 +2328,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<
@@ -3747,4 +3892,4 @@ declare function isOnce(value: unknown): value is {
 declare function Canvas(props: CanvasProps): react_jsx_runtime.JSX.Element;
 
 export { Block, Canvas, Environment, EnvironmentCube, EnvironmentMap, EnvironmentPortal, ErrorBoundary, FROM_REF, IsObject, ONCE, Portal, R3F_BUILD_LEGACY, R3F_BUILD_WEBGPU, REACT_INTERNAL_PROPS, RESERVED_PROPS, three_d as ReactThreeFiber, Texture, _roots, addAfterEffect, addEffect, addTail, advance, applyProps, attach, buildGraph, calculateDpr, context, createEvents, createPointerEvents, createPortal, createRoot, createStore, detach, diffProps, dispose, createPointerEvents as events, extend, findInitialRoot, flushSync, fromRef, getInstanceProps, getPrimary, getPrimaryIds, getRootState, getUuidPrefix, hasConstructor, hasPrimary, invalidate, invalidateInstance, is, isColorRepresentation, isCopyable, isFromRef, isObject3D, isOnce, isOrthographicCamera, isRef, isRenderer, isTexture, isVectorLike, once, prepare, presetsObj, reconciler, registerPrimary, removeInteractivity, resolve, swapInteractivity, unmountComponentAtNode, unregisterPrimary, updateCamera, updateFrustum, useBridge, useEnvironment, useFrame, useGraph, useInstanceHandle, useIsomorphicLayoutEffect, useLoader, useMutableCallback, useRenderTarget, useStore, useTexture, useTextures, useThree, waitForPrimary };
-export type { Act, Args, ArgsProp, AttachFnType, AttachType, BackgroundConfig, BackgroundProp, BaseRendererProps, Bridge, BufferLike, BufferRecord, BufferStore, Camera, CameraProps, CanvasProps, CanvasSchedulerConfig, Catalogue, Color, ColorManagementConfig, ComputeFunction, ConstructorRepresentation, DefaultGLProps, DefaultRendererProps, Disposable, DisposeOptions, DomEvent, Dpr, ElementProps, EnvironmentLoaderProps, EnvironmentProps, EquConfig, Euler, EventHandlers, EventManager, EventProps, Events, Extensions, FiberRoot, FilterFunction, FrameCallback, FrameNextCallback, FrameNextState, FrameState, Frameloop, GLProps, GLTFLike, GeometryProps, GeometryTransformProps, GlobalEffectType, GlobalRenderCallback, HostConfig, InferLoadResult, InjectState, InputLike, Instance, InstanceProps, LegacyInternalState as InternalState, Intersection, IntersectionEvent, IsAllOptional, IsOptional, Layers, LegacyInternalState, LegacyRenderer, LegacyRootState, LoaderInstance, LoaderLike, LoaderResult, MappedTextureType, MathProps, MathRepresentation, MathType, MathTypes, Matrix3, Matrix4, Mutable, MutableOrReadonlyParameters, NodeProps, NonFunctionKeys, ObjectMap, OffscreenCanvas$1 as OffscreenCanvas, Overwrite, Performance, PointerCaptureTarget, PointerState, PresetsType, PrimaryCanvasEntry, Properties, Quaternion, LegacyRenderer as R3FRenderer, RaycastableRepresentation, ReactProps, ReconcilerRoot, RenderCallback, RenderProps, RenderTargetOptions, Renderer, RendererConfigExtended, RendererFactory, RendererProps, Root, LegacyRootState as RootState, RootStore, SetBlock, Size, StorageLike, StorageRecord, StorageStore, Subscription, TSLNodeInput, TextureInput, TextureResult, ThreeCamera, ThreeElement, ThreeElements, ThreeElementsImpl, ThreeEvent, ThreeExports, ThreeToJSXElements, UnblockProps, UseTextureOptions, UseTexturesReturn, Vector2, Vector3, Vector4, VectorRepresentation, Viewport, VisibilityEntry, WebGLDefaultProps, WebGLProps, WebGLShadowConfig, XRManager, XRPointerConfig };
+export type { Act, Args, ArgsProp, AttachFnType, AttachType, BackgroundConfig, BackgroundProp, BaseRendererProps, Bridge, BufferLike, BufferRecord, BufferStore, Camera, CameraProps, CanvasProps, CanvasSchedulerConfig, Catalogue, Color, ColorManagementConfig, ComputeFunction, ConstructorRepresentation, DefaultGLProps, DefaultRendererProps, Disposable, DisposeOptions, DomEvent, Dpr, ElementProps, EnvironmentLoaderProps, EnvironmentProps, EquConfig, Euler, EventHandlers, EventManager, EventProps, Events, Extensions, FiberRoot, FilterFunction, FrameCallback, FrameNextCallback, FrameNextState, FrameState, Frameloop, GLProps, GLTFLike, GeometryProps, GeometryTransformProps, GlobalEffectType, GlobalRenderCallback, HostConfig, InferLoadResult, InjectState, InputLike, Instance, InstanceProps, LegacyInternalState as InternalState, Intersection, IntersectionEvent, IsAllOptional, IsOptional, Layers, LegacyInternalState, LegacyRenderer, LegacyRootState, LoaderInstance, LoaderLike, LoaderResult, MappedTextureType, MathProps, MathRepresentation, MathType, MathTypes, Matrix3, Matrix4, Mutable, MutableOrReadonlyParameters, NodeLike, NodeProps, NodeRecord, NodeStore, NonFunctionKeys, ObjectMap, OffscreenCanvas$1 as OffscreenCanvas, Overwrite, Performance, PointerCaptureTarget, PointerState, PresetsType, PrimaryCanvasEntry, Properties, Quaternion, LegacyRenderer as R3FRenderer, RaycastableRepresentation, ReactProps, ReconcilerRoot, RenderCallback, RenderProps, RenderTargetOptions, Renderer, RendererConfigExtended, RendererFactory, RendererProps, Root, LegacyRootState as RootState, RootStore, SetBlock, Size, StorageLike, StorageRecord, StorageStore, Subscription, TSLNodeInput, TextureInput, TextureResult, ThreeCamera, ThreeElement, ThreeElements, ThreeElementsImpl, ThreeEvent, ThreeExports, ThreeToJSXElements, UnblockProps, UseTextureOptions, UseTexturesReturn, Vector2, Vector3, Vector4, VectorRepresentation, Viewport, VisibilityEntry, WebGLDefaultProps, WebGLProps, WebGLShadowConfig, XRManager, XRPointerConfig };