@react-three/fiber 10.0.0-canary.4a21acb → 10.0.0-canary.4bf885a

package/dist/webgpu/index.d.mts

@@ -1,5 +1,6 @@
+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, WebGPURendererParameters } from 'three/webgpu';
+import { CubeRenderTarget, RenderTarget, WebGPURenderer, Node, StorageTexture, Storage3DTexture, StorageArrayTexture, Data3DTexture, CanvasTarget, 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, Object3D, 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, Frustum, OrthographicCamera, Matrix2, WebGPURendererParameters } from 'three/webgpu';
 import { Inspector } from 'three/addons/inspector/Inspector.js';
 import * as THREE$1 from 'three';
 import { Color as Color$1, ColorRepresentation, Euler as Euler$1, Loader, RenderTargetOptions as RenderTargetOptions$1 } from 'three';
@@ -11,7 +12,6 @@ import { FrameTimingState, FrameCallback as FrameCallback$1, SchedulerApi, UseFr
 export { AddPhaseOptions, FrameControls, FrameNextControls, FrameTimingState, RootOptions, Scheduler, SchedulerApi, UseFrameNextOptions, UseFrameOptions, getScheduler } from '@pmndrs/scheduler';
 import { Options } from 'react-use-measure';
 import * as react_jsx_runtime from 'react/jsx-runtime';
-import { ThreeElement as ThreeElement$1, Euler as Euler$3 } from '@react-three/fiber';
 import { GroundedSkybox } from 'three/examples/jsm/objects/GroundedSkybox.js';
 
 function _mergeNamespaces(n, m) {
@@ -41,6 +41,8 @@ function _mergeNamespaces(n, m) {
 declare const R3F_BUILD_LEGACY = false;
 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>;
 declare const WebGLRenderer: {
     new (): {};
 };
@@ -62,7 +64,8 @@ var THREE = /*#__PURE__*/_mergeNamespaces({
   WebGLRenderTarget: WebGLRenderTarget,
   WebGLRenderer: WebGLRenderer,
   WebGLRendererParameters: WebGLRendererParameters,
-  WebGLShadowMap: WebGLShadowMap
+  WebGLShadowMap: WebGLShadowMap,
+  loadInspector: loadInspector
 }, [three_webgpu]);
 
 //* Utility Types ==============================
@@ -351,6 +354,7 @@ type BufferLike =
   | Uint16Array
   | Int16Array
   | THREE$1.BufferAttribute // Base class for all buffer attributes
+  | THREE$1.InterleavedBufferAttribute
   | Node // TSL buffer nodes (instancedArray, storage)
 
 /** Flat record of buffer-like values (no nested scopes) */
@@ -362,6 +366,25 @@ type BufferRecord = Record<string, BufferLike>
  */
 type BufferStore = Record<string, BufferLike | BufferRecord>
 
+//* Node Types (useNodes) ========================================
+
+/**
+ * Every node representation `useNodes` accepts and `state.nodes` holds: three's real `Node`,
+ * the callable proxy `Fn()` returns, and the legacy structural shape (`uuid`/`nodeType`) older
+ * code passes through. Creators are constrained to this same type, so the shape a creator returns
+ * and the shape the store holds are one type by construction.
+ */
+type NodeLike = TSLNodeType | LegacyTSLNodeLike
+
+/** Flat record of TSL nodes (no nested scopes) */
+type NodeRecord<T extends NodeLike = NodeLike> = Record<string, T>
+
+/**
+ * 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) ========================================
 
 /**
@@ -376,7 +399,9 @@ type BufferStore = Record<string, BufferLike | BufferRecord>
  * ```
  */
 type StorageLike =
-  | StorageTexture // GPU storage texture
+  | StorageTexture // 2D GPU storage texture
+  | Storage3DTexture // 3D GPU storage texture (volumes, fluid grids)
+  | StorageArrayTexture // 2D-array GPU storage texture
   | Data3DTexture // 3D texture (can be used as storage)
   | Node // TSL storage texture nodes (storageTexture)
 
@@ -488,6 +513,12 @@ interface InternalState {
   actualRenderer: R3FRenderer
   /** Global scheduler reference (for useFrame hook) */
   scheduler: SchedulerApi | null
+  /**
+   * Replaces `renderer.render(scene, camera)` in the default render job when set. Set it with
+   * `setRenderOverride(store, fn)`; the job keeps its fps throttle, error handling and user
+   * render-phase takeover. Used by `useRenderPipeline`.
+   */
+  renderOverride?: (() => void) | null
   /** This root's unique ID in the global scheduler */
   rootId?: string
   /** Function to unregister this root from the global scheduler */
@@ -495,11 +526,28 @@ interface InternalState {
   /** Container for child attachment (scene for root, original container for portals) */
   container?: THREE$1.Object3D
   /**
-   * CanvasTarget for multi-canvas WebGPU rendering.
-   * Created for all WebGPU canvases to support renderer sharing.
+   * The CanvasTarget this root sizes and renders through.
+   *
+   * A primary (`<Canvas id>`) owns the renderer's default target -- the one three itself built
+   * around the canvas element -- so sizing it is sizing the renderer. A secondary owns a target
+   * R3F created for its own element. Either way there is exactly one target per canvas element,
+   * and the canvas-target job makes it the renderer's active one before this root renders.
+   * Absent on WebGL and on an id-less WebGPU canvas, where the renderer is sized directly.
    * @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.
@@ -609,7 +657,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 */
@@ -621,7 +669,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 */
@@ -709,12 +757,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 | string[]
+  /**
+   * Numeric root order. Lower values run first.
    */
-  after?: string
+  order?: number
   /**
-   * Limit this canvas's render rate (frames per second).
+   * Limit this Canvas's default render job (frames per second).
    */
   fps?: number
 }
@@ -801,14 +856,17 @@ interface RenderProps<TCanvas extends HTMLCanvasElement | OffscreenCanvas$1> {
   performance?: Partial<Omit<Performance, 'regress'>>
   /** Target pixel ratio. Can clamp between a range: `[min, max]` */
   dpr?: Dpr
-  /** Props that go into the default raycaster */
-  raycaster?: Partial<THREE$1.Raycaster>
+  /**
+   * Props that go into the default raycaster. `params` is merged into the raycaster's defaults,
+   * so a single threshold can be set: `raycaster={{ params: { Points: { threshold: 0.2 } } }}`.
+   */
+  raycaster?: Partial<Omit<THREE$1.Raycaster, 'params'>> & { params?: Partial<THREE$1.RaycasterParameters> }
   /** A `THREE.Scene` instance or props that go into the default scene */
   scene?: THREE$1.Scene | Partial<THREE$1.Scene>
   /** A `THREE.Camera` instance or props that go into the default camera */
   camera?: CameraProps
   /** An R3F event manager to manage elements' pointer events */
-  events?: (store: RootStore) => EventManager<HTMLElement>
+  events?: (store: RootStore) => EventManager<Element>
   /** Callback after the canvas has rendered (but not yet committed) */
   onCreated?: (state: RootState) => void
   /** Response for pointer clicks that have missed any target */
@@ -897,7 +955,6 @@ type InstanceProps<T = any, P = any> = ArgsProp<P> & {
   object?: T
   dispose?: null
   attach?: AttachType<T>
-  onUpdate?: (self: T) => void
 }
 
 interface Instance<O = any> {
@@ -1037,7 +1094,7 @@ interface CanvasProps
    */
   resize?: Options
   /** The target where events are being subscribed to, default: the div that wraps canvas */
-  eventSource?: HTMLElement | React$1.RefObject<HTMLElement | null>
+  eventSource?: Element | React$1.RefObject<Element | null>
   /** The event prefix that is cast into canvas pointer x/y events, default: "offset" */
   eventPrefix?: 'offset' | 'client' | 'page' | 'layer' | 'screen'
   /** Enable/disable automatic HMR refresh for TSL nodes and uniforms, default: true in dev */
@@ -1145,81 +1202,86 @@ interface LegacyRootState extends Omit<RootState, 'renderer' | 'internal'> {
 
 type RenderTargetOptions = RenderTargetOptions$1
 
-//* Global Types ==============================
+//* Global TSL Types ==============================
 
 declare global {
   /**
-   * Uniform node type.
-   *
-   * This is three's own `UniformNode`, not a re-declaration of it. It previously was a
-   * hand-rolled `interface UniformNode<T> extends Node { value: T }`, which shadowed the real
-   * exported type globally — so R3F's ~58 references resolved to an approximation that was
-   * missing members three actually ships (`setName` among them) and had drifted to the wrong
-   * arity when three made `UniformNode` two-parameter.
-   *
-   * three's signature is `UniformNode<TNodeType, TValue>`. R3F only ever varies the value type,
-   * so the node type is fixed to `unknown` and the single parameter is kept for call-site
-   * 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.
+   * Broad callable-node fallback for dynamic store readers.
+   * Creator hooks preserve the exact function signatures inferred from Three's `Fn`.
    */
-  type UniformNode<T = unknown> = three_webgpu.UniformNode<unknown, T>
+  type CallableTSLNode = ((...params: never[]) => unknown) & {
+    readonly shaderNode: unknown
+    readonly id: number
+  }
 
-  /**
-   * ShaderCallable - the return type of Fn()
-   * A callable shader function node that can be invoked with parameters.
-   * The function returns a ShaderNodeObject when called.
-   *
-   * @example
-   * ```tsx
-   * // Define a shader function
-   * const blendColorFn = Fn(([color1, color2, factor]) => {
-   *   return mix(color1, color2, factor)
-   * })
-   *
-   * // Type when retrieving from nodes store
-   * const { blendColorFn } = nodes as { blendColorFn: ShaderCallable }
-   *
-   * // Or with specific return type
-   * const { myFn } = nodes as { myFn: ShaderCallable<THREE.Node> }
-   * ```
-   */
-  type ShaderCallable<R extends Node = Node> = ((...params: unknown[]) => ShaderNodeObject<R>) & Node
+  /** Legacy structural node accepted when at least one historical marker exists. */
+  type LegacyTSLNodeLike = {
+    label?: ((label: string) => unknown) | string
+    setName?: (name: string) => unknown
+  } & ({ uuid: string | undefined; nodeType?: string | null } | { uuid?: string; nodeType: string | null | undefined })
 
-  /**
-   * ShaderNodeRef - a ShaderNodeObject wrapper around a Node
-   * This is the common return type for TSL operations (add, mul, sin, etc.)
-   *
-   * @example
-   * ```tsx
-   * const { wobble } = nodes as { wobble: ShaderNodeRef }
-   * ```
-   */
-  type ShaderNodeRef<T extends Node = Node> = ShaderNodeObject<T>
+  /** Node type accepted by broad dynamic node-store readers. */
+  type TSLNodeType = three_webgpu.Node | CallableTSLNode
 
   /**
-   * TSLNodeType - Union of all common TSL node types
-   * Used by ScopedStore to properly type node access from the store.
-   *
-   * Includes:
-   * - Node: base Three.js node type
-   * - ShaderCallable: function nodes created with Fn()
-   * - ShaderNodeObject: wrapped nodes from TSL operations (sin, mul, mix, etc.)
-   *
-   * @example
-   * ```tsx
-   * // In useLocalNodes, nodes are typed as TSLNodeType
-   * const { positionNode, blendColorFn } = useLocalNodes(({ nodes }) => ({
-   *   positionNode: nodes.myPosition,      // Works - Node is in union
-   *   blendColorFn: nodes.myFn,            // Works - ShaderCallable is in union
-   * }))
-   *
-   * // Can narrow with type guard or assertion when needed
-   * if (typeof blendColorFn === 'function') {
-   *   blendColorFn(someColor, 0.5)
-   * }
-   * ```
+   * Derive Three's shader node type from an existing node or a supported raw input.
+   * Existing InputNode generics take precedence over structural value normalization.
+   * Both generics must be inferred because Three's UniformNode intersects an unknown-typed
+   * InputNode base with its concrete InputNode specialization.
    */
-  type TSLNodeType = Node | ShaderCallable<Node> | ShaderNodeObject<Node>
+  type UniformNodeType<T> = T extends three_webgpu.UniformNode<infer TNodeType, infer _TValue>
+    ? TNodeType
+    : T extends three_webgpu.InputNode<infer TNodeType, infer _TValue>
+      ? TNodeType
+      : T extends number
+        ? 'float'
+        : T extends boolean
+          ? 'bool'
+          : T extends string | three_webgpu.Color | { r: number; g: number; b: number }
+            ? 'color'
+            : T extends three_webgpu.Vector4 | { x: number; y: number; z: number; w: number }
+              ? 'vec4'
+              : T extends three_webgpu.Vector3 | { x: number; y: number; z: number }
+                ? 'vec3'
+                : T extends three_webgpu.Vector2 | { x: number; y: number }
+                  ? 'vec2'
+                  : T extends three_webgpu.Matrix4
+                    ? 'mat4'
+                    : T extends three_webgpu.Matrix3
+                      ? 'mat3'
+                      : T extends three_webgpu.Matrix2
+                        ? 'mat2'
+                        : unknown
+
+  /** Derive the normalized JavaScript value stored by a uniform node. */
+  type UniformNodeValue<T> = T extends three_webgpu.UniformNode<infer _TNodeType, infer TValue>
+    ? TValue
+    : T extends three_webgpu.InputNode<infer _TNodeType, infer TValue>
+      ? TValue
+      : T extends string | { r: number; g: number; b: number }
+        ? three_webgpu.Color
+        : T extends { x: number; y: number; z: number; w: number }
+          ? three_webgpu.Vector4
+          : T extends { x: number; y: number; z: number }
+            ? three_webgpu.Vector3
+            : T extends { x: number; y: number }
+              ? three_webgpu.Vector2
+              : T extends number
+                ? number
+                : T extends boolean
+                  ? boolean
+                  : T
+
+  /** Three's exact UniformNode with shader and value generics derived from an input. */
+  type UniformNodeFor<T> = three_webgpu.UniformNode<UniformNodeType<T>, UniformNodeValue<T>>
+
+  /** Preserve every input key while mapping values to exact Three uniform nodes. */
+  type UniformNodesFor<T extends UniformInputRecord> = {
+    [K in keyof T]: UniformNodeFor<T[K]>
+  }
+
+  /** Backward-compatible single-parameter uniform alias. */
+  type UniformNode<T = unknown> = UniformNodeFor<T>
 
   /** Flat record of uniform nodes (no nested scopes) */
   type UniformRecord<T extends UniformNode = UniformNode> = Record<string, T>
@@ -1244,7 +1306,7 @@ declare global {
    * Acceptable input values for useUniforms - raw values that get converted to UniformNodes
    * Supports:
    * - Primitives: number, string (color), boolean
-   * - Three.js types: Color, Vector2/3/4, Matrix3/4, Euler, Quaternion
+   * - Three.js types: Color, Vector2/3/4, Matrix2/3/4
    * - Plain objects: { x, y, z, w } converted to vectors
    * - TSL nodes: color(), vec3(), float() for type casting
    * - UniformNode: existing uniforms (reused as-is)
@@ -1257,88 +1319,124 @@ declare global {
     | three_webgpu.Vector2
     | three_webgpu.Vector3
     | three_webgpu.Vector4
+    | three_webgpu.Matrix2
     | three_webgpu.Matrix3
     | three_webgpu.Matrix4
-    | three_webgpu.Euler
-    | three_webgpu.Quaternion
-    | { x: number; y?: number; z?: number; w?: number } // Plain objects converted to vectors
+    | { x: number; y: number }
+    | { x: number; y: number; z: number }
+    | { x: number; y: number; z: number; w: number }
     | { r: number; g: number; b: number; a?: number } // Plain objects converted to Color
-    | Node // TSL nodes like color(), vec3(), float() for type casting
+    | three_webgpu.Node // TSL nodes like color(), vec3(), float() for type casting
     | UniformNode
 
   /** Input record for useUniforms - accepts raw values or UniformNodes */
   type UniformInputRecord = Record<string, UniformValue>
 }
 
-//* Module Augmentation ==============================
-
-declare module 'three/tsl' {
+declare global {
   /**
-   * Fn with array parameter destructuring
-   * @example Fn(([uv, skew]) => { ... })
+   * three's own render pipeline type. Named here so the rest of R3F refers to three's shape
+   * rather than `any`. three r183 renamed `PostProcessing` to `RenderPipeline`; our peer floor
+   * is r185, so the new name is the only one.
    */
-  export function Fn<R extends Node = Node>(
-    jsFunc: (inputs: ShaderNodeObject<Node>[]) => ShaderNodeObject<R>,
-  ): ShaderCallable<R>
+  type ThreeRenderPipeline = three_webgpu.RenderPipeline
 
   /**
-   * Fn with object parameter destructuring
-   * @example Fn(({ color, intensity }) => { ... })
+   * 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.
    */
-  export function Fn<T extends Record<string, unknown>, R extends Node = Node>(
-    jsFunc: (inputs: T) => ShaderNodeObject<R>,
-  ): ShaderCallable<R>
+  type ScenePassNode = three_webgpu.PassNode
 
   /**
-   * Fn with array params + layout
-   * @example Fn(([a, b]) => { ... }, { layout: [...] })
+   * 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`.
+   *
+   * The index signature admits `undefined` because a key may simply not be registered, and
+   * because the optional `scenePass` must be assignable to it: under `skipLibCheck: false` an
+   * optional property whose type excludes `undefined` from the index signature is an error
+   * (TS2411) for every consumer compiling these declarations.
    */
-  export function Fn<R extends Node = Node>(
-    jsFunc: (inputs: ShaderNodeObject<Node>[]) => ShaderNodeObject<R>,
-    layout: { layout?: unknown },
-  ): ShaderCallable<R>
+  interface PassRecord {
+    scenePass?: ScenePassNode
+    [key: string]: three_webgpu.Node | undefined
+  }
 
   /**
-   * Fn with object params + layout
+   * 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.
    */
-  export function Fn<T extends Record<string, unknown>, R extends Node = Node>(
-    jsFunc: (inputs: T) => ShaderNodeObject<R>,
-    layout: { layout?: unknown },
-  ): ShaderCallable<R>
-}
+  type RenderPipelineCallbackState = RootState & {
+    renderPipeline: ThreeRenderPipeline
+    passes: PassRecord & { scenePass: ScenePassNode }
+    renderer: three_webgpu.WebGPURenderer
+    isLegacy: false
+  }
 
-declare global {
   /**
-   * three's own render pipeline type. Named here so the rest of R3F refers to three's shape
-   * rather than `any`. three r183 renamed `PostProcessing` to `RenderPipeline`; our peer floor
-   * is r185, so the new name is the only one.
+   * 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 ThreeRenderPipeline = three_webgpu.RenderPipeline
-
-  /** Pass record - stores TSL pass nodes for render pipeline */
-  type PassRecord = Record<string, any>
+  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>>
@@ -1417,10 +1515,11 @@ type TSLNodeInput = { nodeType?: string | null; uuid?: string } | null
 
 /**
  * For node material properties (colorNode, positionNode, etc.), accept broader types
- * since @types/three has broken inheritance for TSL node subclasses.
+ * since @types/three has broken inheritance for TSL node subclasses. NodeClass requires
+ * `nodeType`, so this structural key test remains neutral to the selected Three entry.
  */
 type NodeProps<P> = {
-  [K in keyof P as P[K] extends Node | null ? K : never]?: TSLNodeInput
+  [K in keyof P as NonNullable<P[K]> extends { nodeType: string | null } ? K : never]?: TSLNodeInput
 }
 
 interface ReactProps<P> {
@@ -1441,11 +1540,29 @@ type ThreeToJSXElements<T extends Record<string, any>> = {
   [K in keyof T & string as Uncapitalize<K>]: T[K] extends ConstructorRepresentation ? ThreeElement<T[K]> : never
 }
 
+/** Method names of Object3D, excluded from the `primitive` element's typed props. */
+type Object3DMethod = NonNullable<
+  {
+    [K in keyof Object3D]-?: Object3D[K] extends (...args: any[]) => any ? K : never
+  }[keyof Object3D]
+>
+
 type ThreeExports = typeof THREE
 type ThreeElementsImpl = ThreeToJSXElements<ThreeExports>
 
 interface ThreeElements extends Omit<ThreeElementsImpl, 'audio' | 'source' | 'line' | 'path'> {
-  primitive: Omit<ThreeElement<any>, 'args'> & { object: object }
+  /**
+   * `primitive` wraps a pre-existing object, so its props cannot be derived from one class.
+   * Events are typed from `EventHandlers` (`onClick={(e) => ...}` infers `e`), the ref is
+   * untyped, and any other prop is accepted and applied to the object by name. Object3D's own
+   * methods are left out of the typed surface: they return `this`, so a subclass element's
+   * props (`ThreeElements['group']`) could not be spread onto a primitive otherwise.
+   */
+  primitive: Omit<ThreeElement<typeof Object3D>, 'args' | 'object' | 'ref' | Object3DMethod> & {
+    object: object
+    ref?: React.Ref<any>
+    [prop: string]: unknown
+  }
   // Conflicts with DOM types can be accessed through a three* prefix
   threeAudio: ThreeElementsImpl['audio']
   threeSource: ThreeElementsImpl['source']
@@ -1486,6 +1603,7 @@ type three_d_Matrix3 = Matrix3;
 type three_d_Matrix4 = Matrix4;
 type three_d_MutableOrReadonlyParameters<T extends (...args: any) => any> = MutableOrReadonlyParameters<T>;
 type three_d_NodeProps<P> = NodeProps<P>;
+type three_d_Object3DMethod = Object3DMethod;
 type three_d_Quaternion = Quaternion;
 type three_d_RaycastableRepresentation = RaycastableRepresentation;
 type three_d_ReactProps<P> = ReactProps<P>;
@@ -1500,7 +1618,7 @@ type three_d_Vector3 = Vector3;
 type three_d_Vector4 = Vector4;
 type three_d_VectorRepresentation = VectorRepresentation;
 declare namespace three_d {
-  export type { three_d_Color as Color, three_d_ElementProps as ElementProps, three_d_Euler as Euler, three_d_EventProps as EventProps, three_d_GeometryProps as GeometryProps, three_d_GeometryTransformProps as GeometryTransformProps, three_d_Layers as Layers, three_d_MathProps as MathProps, three_d_MathRepresentation as MathRepresentation, three_d_MathType as MathType, three_d_MathTypes as MathTypes, three_d_Matrix3 as Matrix3, three_d_Matrix4 as Matrix4, three_d_MutableOrReadonlyParameters as MutableOrReadonlyParameters, three_d_NodeProps as NodeProps, three_d_Quaternion as Quaternion, three_d_RaycastableRepresentation as RaycastableRepresentation, three_d_ReactProps as ReactProps, three_d_TSLNodeInput as TSLNodeInput, three_d_ThreeElement as ThreeElement, three_d_ThreeElements as ThreeElements, three_d_ThreeElementsImpl as ThreeElementsImpl, three_d_ThreeExports as ThreeExports, three_d_ThreeToJSXElements as ThreeToJSXElements, three_d_Vector2 as Vector2, three_d_Vector3 as Vector3, three_d_Vector4 as Vector4, three_d_VectorRepresentation as VectorRepresentation };
+  export type { three_d_Color as Color, three_d_ElementProps as ElementProps, three_d_Euler as Euler, three_d_EventProps as EventProps, three_d_GeometryProps as GeometryProps, three_d_GeometryTransformProps as GeometryTransformProps, three_d_Layers as Layers, three_d_MathProps as MathProps, three_d_MathRepresentation as MathRepresentation, three_d_MathType as MathType, three_d_MathTypes as MathTypes, three_d_Matrix3 as Matrix3, three_d_Matrix4 as Matrix4, three_d_MutableOrReadonlyParameters as MutableOrReadonlyParameters, three_d_NodeProps as NodeProps, three_d_Object3DMethod as Object3DMethod, three_d_Quaternion as Quaternion, three_d_RaycastableRepresentation as RaycastableRepresentation, three_d_ReactProps as ReactProps, three_d_TSLNodeInput as TSLNodeInput, three_d_ThreeElement as ThreeElement, three_d_ThreeElements as ThreeElements, three_d_ThreeElementsImpl as ThreeElementsImpl, three_d_ThreeExports as ThreeExports, three_d_ThreeToJSXElements as ThreeToJSXElements, three_d_Vector2 as Vector2, three_d_Vector3 as Vector3, three_d_Vector4 as Vector4, three_d_VectorRepresentation as VectorRepresentation };
 }
 
 /**
@@ -1638,9 +1756,9 @@ type EnvironmentProps = {
     blur?: number;
     backgroundBlurriness?: number;
     backgroundIntensity?: number;
-    backgroundRotation?: Euler$3;
+    backgroundRotation?: Euler;
     environmentIntensity?: number;
-    environmentRotation?: Euler$3;
+    environmentRotation?: Euler;
     map?: Texture$1;
     preset?: PresetsType;
     scene?: Scene | React$1.RefObject<Scene>;
@@ -1724,7 +1842,7 @@ declare function EnvironmentCube({ background, scene, blur, backgroundBlurriness
 declare function EnvironmentPortal({ children, near, far, resolution, frames, map, background, blur, backgroundBlurriness, backgroundIntensity, backgroundRotation, environmentIntensity, environmentRotation, scene, files, path, preset, extensions, }: EnvironmentProps): react_jsx_runtime.JSX.Element;
 declare module '@react-three/fiber' {
     interface ThreeElements {
-        groundProjectedEnvImpl: ThreeElement$1<typeof GroundedSkybox>;
+        groundProjectedEnvImpl: ThreeElement<typeof GroundedSkybox>;
     }
 }
 /**
@@ -1824,6 +1942,24 @@ declare module '@react-three/fiber' {
  */
 declare function Environment(props: EnvironmentProps): react_jsx_runtime.JSX.Element;
 
+/**
+ * Moves every trace of interactivity from one object to its replacement, for reconstruction.
+ *
+ * When `args` or a `primitive`'s `object` changes, R3F builds a new three object and keeps the same
+ * instance. Removing the old object from the interaction state and registering the new one from
+ * scratch makes events *work* again (#3778), but it forgets what was in flight: a pointer resting on
+ * the object fires a second `onPointerEnter` without ever having left, and an active pointer capture
+ * is dropped mid-drag. Rewriting the references instead keeps the interaction continuous across a
+ * swap the user never asked to see (#3744).
+ *
+ * Captures are re-keyed rather than released, so the DOM-level capture on `captureData.target` is
+ * left alone — releasing and re-acquiring it is precisely the glitch being avoided.
+ *
+ * Visibility handlers are deliberately not transferred: that registry is keyed by `object.uuid`, so
+ * the replacement re-registers itself through `applyProps`. The old entry is dropped here so it
+ * cannot outlive the object it described.
+ */
+declare function swapInteractivity(store: RootStore, object: Object3D, newObject: Object3D): void;
 declare function removeInteractivity(store: RootStore, object: Object3D): void;
 declare function createEvents(store: RootStore): {
     handlePointer: (name: string) => (event: DomEvent) => void;
@@ -1831,7 +1967,43 @@ declare function createEvents(store: RootStore): {
     processDeferredPointer: (event: DomEvent, pointerId: number) => void;
 };
 /** Default R3F event manager for web */
-declare function createPointerEvents(store: RootStore): EventManager<HTMLElement>;
+declare function createPointerEvents(store: RootStore): EventManager<Element>;
+
+interface RootExtension {
+    /** Unique name. Registering the same name again replaces the entry (HMR-safe); roots it already
+     *  set up are not set up a second time, but get the new entry's dispose and hmr. */
+    name: string;
+    /**
+     * Called once per root, after its renderer exists and before `onCreated` and the first frame.
+     * `isLegacy` and `primaryStore` are known by then, so an extension can skip WebGL roots or defer
+     * to the primary canvas. Return fields to merge into the root's state, or nothing.
+     */
+    setup?(store: RootStore): Partial<RootState> | void;
+    /** Called when a root this extension set up unmounts. */
+    dispose?(store: RootStore): void;
+    /** Called when `<Canvas>` detects hot module replacement (skipped with `hmr={false}`). */
+    hmr?(store: RootStore): void;
+}
+/**
+ * Register an extension. It is set up on every live root immediately, and on every root created
+ * afterwards. Returns a function that unregisters it: new roots are no longer set up, while roots
+ * it already set up keep its state and still get its dispose when they unmount.
+ */
+declare function registerRootExtension(extension: RootExtension): () => void;
+/**
+ * Point a root's default render job at a different render function, or back at
+ * `renderer.render(scene, camera)` with `null`.
+ *
+ * The default job keeps everything else: the Canvas `fps` throttle, error propagation to the error
+ * boundary, and backing off when a user `useFrame(..., { phase: 'render' })` job takes over.
+ */
+declare function setRenderOverride(store: RootStore, render: (() => void) | null): void;
+
+/**
+ * Returns the R3F Canvas' Zustand store. Useful for [transient updates](https://github.com/pmndrs/zustand#transient-updates-for-often-occurring-state-changes).
+ * @see https://docs.pmnd.rs/react-three-fiber/api/hooks#usestore
+ */
+declare function useStore(): RootStore;
 
 /**
  * Gets or creates a memoized loader instance from a loader constructor or returns the loader if it's already an instance.
@@ -1851,50 +2023,6 @@ declare namespace useLoader {
     var loader: typeof getLoader;
 }
 
-/**
- * Frame hook with phase-based ordering, priority, and FPS throttling.
- *
- * Always delivers full RootState — works both inside and outside Canvas context:
- * - Inside Canvas: Full RootState (renderer, scene, camera, etc.)
- * - Outside Canvas: The job registers immediately but the callback is held until a
- *   Canvas adopts it, then runs with full RootState. For hostless / standalone
- *   frame loops with no Canvas, use `@pmndrs/scheduler` directly.
- *
- * Returns a controls object for manual stepping, pausing, and resuming.
- *
- * @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
- *
- * @example
- * // Simple priority (backwards compat)
- * useFrame((state, delta) => { ... }, 5)
- *
- * @example
- * // With phase-based ordering
- * useFrame((state, delta) => { ... }, { phase: 'physics' })
- *
- * @example
- * // Outside Canvas - callback waits for a Canvas, then always has full state
- * function UI() {
- *   useFrame((state, delta) => { syncUI(state.camera) });
- *   return <button>...</button>;
- * }
- *
- * @example
- * // Hostless / standalone loop (no Canvas) - use @pmndrs/scheduler directly
- * import { getScheduler } from '@pmndrs/scheduler'
- * getScheduler().register((state, delta) => { updateGame(delta) })
- *
- * @example
- * // Scheduler-only access (no callback)
- * const { scheduler } = useFrame()
- * scheduler.pauseJob('some-job-id')
- *
- * @see https://docs.pmnd.rs/react-three-fiber/api/hooks#useframe
- */
-declare function useFrame(callback?: FrameNextCallback, priorityOrOptions?: number | UseFrameNextOptions): FrameNextControls;
-
 declare const IsObject: (url: unknown) => url is Record<string, string>;
 type TextureArray<T> = T extends string[] ? Texture$1[] : never;
 type TextureRecord<T> = T extends Record<string, string> ? {
@@ -2075,16 +2203,6 @@ declare function useRenderTarget(options?: RenderTargetOptions): RenderTarget;
 declare function useRenderTarget(size: number, options?: RenderTargetOptions): RenderTarget;
 declare function useRenderTarget(width: number, height: number, options?: RenderTargetOptions): RenderTarget;
 
-/**
- * Returns the R3F Canvas' Zustand store. Useful for [transient updates](https://github.com/pmndrs/zustand#transient-updates-for-often-occurring-state-changes).
- * @see https://docs.pmnd.rs/react-three-fiber/api/hooks#usestore
- */
-declare function useStore(): RootStore;
-/**
- * Accesses R3F's internal state, containing renderer, canvas, scene, etc.
- * @see https://docs.pmnd.rs/react-three-fiber/api/hooks#usethree
- */
-declare function useThree<T = RootState>(selector?: (state: RootState) => T, equalityFn?: <T>(state: T, newState: T) => boolean): T;
 /**
  * Exposes an object's {@link Instance}.
  * @see https://docs.pmnd.rs/react-three-fiber/api/additional-exports#useInstanceHandle
@@ -2160,7 +2278,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)
  *
@@ -2171,14 +2292,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<
@@ -3223,6 +3346,7 @@ declare namespace ReactReconciler {
 
 declare function extend<T extends ConstructorRepresentation>(objects: T): React$1.ExoticComponent<ThreeElement<T>>;
 declare function extend<T extends Catalogue>(objects: T): void;
+declare function extend(objects: Record<string, unknown>): void;
 declare const reconciler: ReactReconciler.Reconciler<RootStore, Instance<any>, void, Instance<any>, never, any>;
 
 declare const isRenderer: (def: any) => boolean;
@@ -3247,13 +3371,9 @@ declare function Portal({ children, container, state }: PortalProps): JSX.Elemen
 declare function flushSync<R>(fn: () => R): R;
 
 declare const context: React$1.Context<RootStore>;
+
 declare const createStore: (invalidate: (state?: RootState, frames?: number, stackFrames?: boolean) => void, advance: (timestamp: number, runGlobalEffects?: boolean, state?: RootState, frame?: XRFrame) => void) => RootStore;
 
-/**
- * Safely flush async effects when testing, simulating a legacy root.
- * @deprecated Import from React instead. import { act } from 'react'
- */
-declare const act: typeof React$1.act;
 /**
  * An SSR-friendly useLayoutEffect.
  *
@@ -3505,7 +3625,7 @@ declare function getInstanceProps<T = any>(pendingProps: Record<string, unknown>
 declare function prepare<T = any>(target: T, root: RootStore, type: string, props: Instance<T>['props']): Instance<T>;
 /**
  * Triggers an update for an instance.
- * Calls onUpdate callback and invalidates the frame if necessary.
+ * Invalidates the frame if the root is in demand mode.
  *
  * @param instance - Instance to invalidate
  */
@@ -3671,29 +3791,44 @@ declare const hasConstructor: (object: unknown) => object is {
  * Used to identify values that should be resolved from refs after mount.
  */
 declare const FROM_REF: unique symbol;
+/** The marker `fromRef()` returns; resolved by the reconciler in `commitMount`. */
+interface FromRefMarker<T = unknown, R = T> {
+    [FROM_REF]: React$1.RefObject<T | null>;
+    /** Optional transform applied to the resolved ref before assignment. */
+    transform?: (value: T) => R;
+}
 /**
  * Defers prop application until the referenced object is available.
  * Useful for props like `target` that need sibling refs to be populated.
  *
+ * Only top-level props on a three element are resolved: a marker nested inside another value
+ * (an array, an options object) is never seen. When the prop needs the sibling *wrapped* rather
+ * than assigned as-is, pass a `transform`; it runs once the ref is populated and its result is
+ * what gets assigned.
+ *
  * @param ref - React ref object to resolve at mount time
- * @returns A marker value that applyProps will resolve after mount
+ * @param transform - Optional mapping from the resolved object to the value the prop expects
+ * @returns A marker value that the reconciler resolves after mount
  *
  * @example
  * const targetRef = useRef<THREE.Object3D>(null)
  *
  * <group ref={targetRef} position={[-3, -2, -15]} />
  * <spotLight target={fromRef(targetRef)} intensity={100} />
+ *
+ * @example
+ * // Wrap the sibling: a node material's lightsNode needs a LightsNode, not the light itself
+ * <meshPhongNodeMaterial lightsNode={fromRef(lightRef, (light) => lights([light]))} />
  */
 declare function fromRef<T>(ref: React$1.RefObject<T | null>): T;
+declare function fromRef<T, R>(ref: React$1.RefObject<T | null>, transform: (value: T) => R): R;
 /**
  * Type guard to check if a value is a fromRef marker.
  *
  * @param value - Value to check
  * @returns True if value is a fromRef marker
  */
-declare function isFromRef(value: unknown): value is {
-    [FROM_REF]: React$1.RefObject<any>;
-};
+declare function isFromRef(value: unknown): value is FromRefMarker<any, unknown>;
 
 /**
  * Symbol marker for mount-only method calls.
@@ -3720,7 +3855,15 @@ declare const ONCE: unique symbol;
  * // No arguments
  * <geometry center={once()} />
  */
-declare function once<T>(...args: T[]): T;
+declare function once<A extends unknown[]>(...args: A): OnceValue<A>;
+/**
+ * What `once(...args)` is typed as, so the marker is assignable to the prop it targets:
+ * the single argument itself (`rotateX={once(angle)}`), the argument tuple for multi-argument
+ * methods (`translate={once(x, y, z)}`), or `true` for a bare call (`center={once()}`).
+ *
+ * The runtime value is always the marker object; only the declared type follows the prop.
+ */
+type OnceValue<A extends unknown[]> = A extends [] ? true : A extends [infer Single] ? Single : A;
 /**
  * Type guard to check if a value is a once marker.
  *
@@ -3731,11 +3874,8 @@ declare function isOnce(value: unknown): value is {
     [ONCE]: any[] | true;
 };
 
-/**
- * A DOM canvas which accepts threejs elements as children.
- * @see https://docs.pmnd.rs/react-three-fiber/api/canvas
- */
-declare function Canvas(props: CanvasProps): react_jsx_runtime.JSX.Element;
+/** Distinguishes a resource leaf from a nested resource scope. */
+type ResourceLeafGuard<T> = (value: unknown) => value is T;
 
 /**
  * ScopedStore - Type-safe wrapper for nested stores (uniforms, nodes)
@@ -3757,33 +3897,30 @@ declare function Canvas(props: CanvasProps): react_jsx_runtime.JSX.Element;
  * ```
  */
 
-/** Keys reserved for methods (excluded from index signature) */
-type MethodKeys = 'scope' | 'has' | 'keys';
 /**
  * Type-safe wrapper interface for accessing nested store data.
  * Property access returns `T` (assumes leaf node).
  * Use `.scope(key)` for nested object access.
  *
- * Uses mapped type with key filtering to exclude method names from index signature,
- * allowing methods to have their correct return types.
  */
-type ScopedStoreType<T> = {
-    /** Direct property access returns the leaf type T (method keys excluded) */
-    readonly [K in string as K extends MethodKeys ? never : K]: T;
-} & {
+type ScopedStoreMethods<TLeaf> = {
     /** Access a nested scope by key. Returns empty wrapper if scope doesn't exist. */
-    scope(key: string): ScopedStoreType<T>;
+    scope<TScope extends Record<string, TLeaf> = Record<string, TLeaf>>(key: string): ScopedStoreType<TLeaf, TScope>;
     /** Check if a key exists in the store */
     has(key: string): boolean;
     /** Get all keys in the store */
     keys(): string[];
 };
+type ScopedStoreType<TLeaf, TEntries extends Record<string, TLeaf> = Record<string, TLeaf>> = Readonly<TEntries> & ScopedStoreMethods<TLeaf>;
+interface ScopedStoreData<TLeaf> {
+    [key: string]: TLeaf | ScopedStoreData<TLeaf>;
+}
 /**
  * Create a type-safe ScopedStore wrapper around store data.
  * @param data - The raw store data (uniforms or nodes from RootState)
  * @returns A ScopedStoreType wrapper with type-safe access
  */
-declare function createScopedStore<T>(data: Record<string, any>): ScopedStoreType<T>;
+declare function createScopedStore<TLeaf>(data: ScopedStoreData<TLeaf>, isLeaf: ResourceLeafGuard<TLeaf>): ScopedStoreType<TLeaf>;
 /**
  * State type passed to creator functions with ScopedStore wrappers.
  * Provides type-safe access to uniforms, nodes, buffers, and gpuStorage without manual casting.
@@ -3791,8 +3928,8 @@ declare function createScopedStore<T>(data: Record<string, any>): ScopedStoreTyp
 type CreatorState = Omit<RootState, 'uniforms' | 'nodes' | 'buffers' | 'gpuStorage'> & {
     /** Type-safe uniform access - property access returns UniformNode */
     uniforms: ScopedStoreType<UniformNode>;
-    /** Type-safe node access - property access returns TSLNodeType (Node | ShaderCallable | ShaderNodeObject) */
-    nodes: ScopedStoreType<TSLNodeType>;
+    /** Type-safe node access for real, callable, and legacy structural nodes */
+    nodes: ScopedStoreType<NodeLike>;
     /** Type-safe buffer access - property access returns BufferLike (TypedArrays, BufferAttributes, TSL nodes) */
     buffers: ScopedStoreType<BufferLike>;
     /** Type-safe GPU storage access - property access returns StorageLike (StorageTexture, TSL nodes) */
@@ -3808,17 +3945,18 @@ type ClearUniformsFn = (scope?: string) => void;
 /** Function signature for rebuildUniforms util */
 type RebuildUniformsFn = (scope?: string) => void;
 /** Return type with utils included */
-type UniformsWithUtils<T extends UniformRecord = UniformRecord> = T & {
+type UniformsWithUtils<T extends UniformRecord | UniformStore = UniformRecord> = T & {
     removeUniforms: RemoveUniformsFn;
     clearUniforms: ClearUniformsFn;
     rebuildUniforms: RebuildUniformsFn;
 };
-declare function useUniforms(): UniformsWithUtils<UniformRecord & Record<string, UniformRecord>>;
+declare function useUniforms<T extends UniformInputRecord>(creator: UniformCreator<T>): UniformsWithUtils<UniformNodesFor<T>>;
+declare function useUniforms<T extends UniformInputRecord>(creator: UniformCreator<T>, scope: string): UniformsWithUtils<UniformNodesFor<T>>;
+declare function useUniforms<T extends UniformInputRecord>(uniforms: T): UniformsWithUtils<UniformNodesFor<T>>;
+declare function useUniforms<T extends UniformInputRecord>(uniforms: T, scope: string): UniformsWithUtils<UniformNodesFor<T>>;
+declare function useUniforms(): UniformsWithUtils<UniformStore>;
 declare function useUniforms(scope: string): UniformsWithUtils;
-declare function useUniforms<T extends UniformInputRecord>(creator: UniformCreator<T>): UniformsWithUtils<UniformRecord<UniformNode>>;
-declare function useUniforms<T extends UniformInputRecord>(creator: UniformCreator<T>, scope: string): UniformsWithUtils<UniformRecord<UniformNode>>;
-declare function useUniforms<T extends UniformInputRecord>(uniforms: T): UniformsWithUtils<UniformRecord<UniformNode>>;
-declare function useUniforms<T extends UniformInputRecord>(uniforms: T, scope: string): UniformsWithUtils<UniformRecord<UniformNode>>;
+declare function useUniforms<T extends UniformInputRecord>(scope?: string): UniformsWithUtils<UniformNodesFor<T>>;
 /**
  * Global rebuildUniforms function for HMR integration.
  * Invalidates cached uniforms and increments _hmrVersion to trigger re-creation.
@@ -3849,47 +3987,28 @@ declare function clearRootUniforms(set: ReturnType<typeof useStore>['setState'])
 
 /**
  * Supported uniform value types:
- * - Raw values: number, boolean, Vector2, Vector3, Vector4, Color, Matrix3, Matrix4
+ * - Raw values: number, boolean, Vector2, Vector3, Vector4, Color, Matrix2, Matrix3, Matrix4
  * - String colors: '#ff0000', 'red', 'rgb(255,0,0)' (auto-converted to Color)
  * - TSL nodes: color(), vec3(), float(), etc. (for type casting)
  * - UniformNode: existing uniforms (reused as-is)
  */
-type UniformValue = number | boolean | string | Vector2$1 | Vector3$1 | Vector4$1 | Color$2 | Matrix3$1 | Matrix4$1 | Node | UniformNode;
-/**
- * Widen literal types to their base types:
- * - 0 → number
- * - true → boolean
- * - '#ff0000' → Color (string colors are converted to Color objects)
- * - Node → Node (TSL nodes passed through for uniform type casting)
- */
-type Widen<T> = T extends number ? number : T extends boolean ? boolean : T extends string ? Color$2 : T;
-declare function useUniform<T extends UniformValue>(name: string): UniformNode<T>;
-declare function useUniform<T extends UniformValue>(name: string, value: T): UniformNode<Widen<T>>;
+type UniformValue = number | boolean | string | Vector2$1 | Vector3$1 | Vector4$1 | Color$2 | Matrix2 | Matrix3$1 | Matrix4$1 | Node | UniformNode;
+declare function useUniform<T extends UniformValue = UniformValue>(name: string): UniformNodeFor<T>;
+declare function useUniform<T extends UniformValue>(name: string, value: T): UniformNodeFor<T>;
 
 /**
- * Minimal interface for TSL nodes.
- * Used instead of Three.js's Node type because the @types/three definitions
- * have inconsistencies where OperatorNode, ConstNode, etc. don't properly
- * extend Node with all required properties.
+ * Every node representation a creator may return. The definition lives with the store types as
+ * `NodeLike`, so the shape creators return and the shape `state.nodes` holds are one type by
+ * construction: three's real `Node`, the callable proxy `Fn()` returns, or the legacy structural
+ * `{ uuid, nodeType }` shape.
  */
-interface TSLNodeLike {
-    uuid?: string;
-    nodeType?: string | null;
-    /** label method for chaining - sets the node's label and returns self */
-    label?: ((label: string) => TSLNodeLike) | string;
-    setName?: (name: string) => this;
-}
-/** TSL node type - alias for compatibility */
+type TSLNodeLike = NodeLike;
+
+/** Backward-compatible alias covering every accepted node representation. */
 type TSLNode = TSLNodeLike;
-/**
- * A record of TSL nodes - allows mixed node types (OperatorNode, ConstNode, etc.)
- * Uses TSLNodeLike for broader compatibility with Three.js's TSL type definitions.
- */
-type NodeRecord<T extends TSLNodeLike = TSLNodeLike> = Record<string, T>;
 /**
  * Creator function that returns a record of nodes.
- * Uses TSLNodeLike constraint to allow mixed node types
- * (e.g., { n: OperatorNode; color: ConstNode<Color> }) to pass type checking.
+ * Exact creator return inference is preserved within the compatible node constraint.
  */
 type NodeCreator<T extends Record<string, TSLNodeLike>> = (state: CreatorState) => T;
 /** Function signature for removeNodes util */
@@ -3899,15 +4018,17 @@ type ClearNodesFn = (scope?: string) => void;
 /** Function signature for rebuildNodes util */
 type RebuildNodesFn = (scope?: string) => void;
 /** Return type with utils included */
-type NodesWithUtils<T extends Record<string, TSLNodeLike> = Record<string, TSLNodeLike>> = T & {
+type NodesWithUtils<T extends Record<string, unknown> = NodeRecord> = T & {
     removeNodes: RemoveNodesFn;
     clearNodes: ClearNodesFn;
     rebuildNodes: RebuildNodesFn;
 };
-declare function useNodes(): NodesWithUtils<Record<string, TSLNodeLike> & Record<string, Record<string, TSLNodeLike>>>;
-declare function useNodes(scope: string): NodesWithUtils<Record<string, TSLNodeLike>>;
-declare function useNodes<T extends Record<string, TSLNodeLike>>(creator: NodeCreator<T>): NodesWithUtils<T>;
-declare function useNodes<T extends Record<string, TSLNodeLike>>(creator: NodeCreator<T>, scope: string): NodesWithUtils<T>;
+declare function useNodes(): NodesWithUtils<NodeStore>;
+declare function useNodes(scope: string): NodesWithUtils<NodeRecord>;
+declare function useNodes<T extends NodeRecord>(scope?: string): NodesWithUtils<T>;
+declare function useNodes<T extends NodeRecord>(creator: NodeCreator<T>): NodesWithUtils<T>;
+declare function useNodes<T extends NodeRecord>(creator: NodeCreator<T>, scope: string): NodesWithUtils<T>;
+declare function useNodes(creatorOrScope?: NodeCreator<NodeRecord> | string, scope?: string): NodesWithUtils<Record<string, unknown>>;
 /**
  * Global rebuildNodes function for HMR integration.
  * Invalidates cached nodes and increments _hmrVersion to trigger re-creation.
@@ -3966,6 +4087,10 @@ type LocalNodeCreator<T extends Record<string, unknown>> = (state: CreatorState)
  */
 declare function useLocalNodes<T extends Record<string, unknown>>(creator: LocalNodeCreator<T>): T;
 
+/**
+ * A record of buffer-like values - allows mixed types (TypedArrays, BufferAttributes, TSL nodes)
+ */
+type BufferRecordType<T extends BufferLike = BufferLike> = Record<string, T>;
 /**
  * Creator function that returns a record of buffers.
  * Receives CreatorState with access to existing buffers, gpuStorage, uniforms, nodes, etc.
@@ -3980,14 +4105,15 @@ type RebuildBuffersFn = (scope?: string) => void;
 /** Function signature for disposeBuffers util - releases GPU resources */
 type DisposeBuffersFn = (names: string | string[], scope?: string) => void;
 /** Return type with utils included */
-type BuffersWithUtils<T extends Record<string, BufferLike> = Record<string, BufferLike>> = T & {
+type BuffersWithUtils<T extends BufferRecordType | BufferStore = BufferRecordType> = T & {
     removeBuffers: RemoveBuffersFn;
     clearBuffers: ClearBuffersFn;
     rebuildBuffers: RebuildBuffersFn;
     disposeBuffers: DisposeBuffersFn;
 };
-declare function useBuffers(): BuffersWithUtils<Record<string, BufferLike> & Record<string, Record<string, BufferLike>>>;
+declare function useBuffers(): BuffersWithUtils<BufferStore>;
 declare function useBuffers(scope: string): BuffersWithUtils<Record<string, BufferLike>>;
+declare function useBuffers<T extends Record<string, BufferLike>>(scope?: string): BuffersWithUtils<T>;
 declare function useBuffers<T extends Record<string, BufferLike>>(creator: BufferCreator<T>): BuffersWithUtils<T>;
 declare function useBuffers<T extends Record<string, BufferLike>>(creator: BufferCreator<T>, scope: string): BuffersWithUtils<T>;
 /**
@@ -4003,6 +4129,10 @@ declare function useBuffers<T extends Record<string, BufferLike>>(creator: Buffe
  */
 declare function rebuildAllBuffers(store: ReturnType<typeof useStore>, scope?: string): void;
 
+/**
+ * A record of storage-like values - allows mixed types (StorageTexture, Storage3DTexture, TSL nodes)
+ */
+type StorageRecordType<T extends StorageLike = StorageLike> = Record<string, T>;
 /**
  * Creator function that returns a record of GPU storage objects.
  * Receives CreatorState with access to existing buffers, gpuStorage, uniforms, nodes, etc.
@@ -4017,14 +4147,15 @@ type RebuildStorageFn = (scope?: string) => void;
 /** Function signature for disposeStorage util - releases GPU resources */
 type DisposeStorageFn = (names: string | string[], scope?: string) => void;
 /** Return type with utils included */
-type StorageWithUtils<T extends Record<string, StorageLike> = Record<string, StorageLike>> = T & {
+type StorageWithUtils<T extends StorageRecordType | StorageStore = StorageRecordType> = T & {
     removeStorage: RemoveStorageFn;
     clearStorage: ClearStorageFn;
     rebuildStorage: RebuildStorageFn;
     disposeStorage: DisposeStorageFn;
 };
-declare function useGPUStorage(): StorageWithUtils<Record<string, StorageLike> & Record<string, Record<string, StorageLike>>>;
+declare function useGPUStorage(): StorageWithUtils<StorageStore>;
 declare function useGPUStorage(scope: string): StorageWithUtils<Record<string, StorageLike>>;
+declare function useGPUStorage<T extends Record<string, StorageLike>>(scope?: string): StorageWithUtils<T>;
 declare function useGPUStorage<T extends Record<string, StorageLike>>(creator: StorageCreator<T>): StorageWithUtils<T>;
 declare function useGPUStorage<T extends Record<string, StorageLike>>(creator: StorageCreator<T>, scope: string): StorageWithUtils<T>;
 /**
@@ -4074,6 +4205,10 @@ declare function createTextureOperations(set: StoreApi<RootState>['setState']):
  * - Callbacks receive full RootState for flexibility
  * - No auto-cleanup on unmount - use reset() for explicit cleanup
  * - Scene/camera changes trigger scenePass recreation
+ * - A replaced scenePass is disposed once the new graph is installed, so rebuild() does not
+ *   strand its render target (and MRT attachments) on the GPU
+ * - Any run that changes the output node sets RenderPipeline.needsUpdate, so rebuild() actually
+ *   recompiles instead of silently keeping the first compiled graph
  *
  * @param mainCB - Main callback to configure outputNode and create effect passes
  * @param setupCB - Optional setup callback to configure MRT on scenePass
@@ -4151,5 +4286,32 @@ interface WebGPURootState extends Omit<RootState, 'renderer' | 'gl' | 'internal'
   internal: WebGPUInternalState
 }
 
-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, act, addAfterEffect, addEffect, addTail, advance, applyProps, attach, buildGraph, calculateDpr, clearNodeScope, clearRootNodes, clearRootUniforms, clearScope, context, createEvents, createPointerEvents, createPortal, createRoot, createScopedStore, createStore, createTextureOperations, 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, rebuildAllBuffers, rebuildAllNodes, rebuildAllStorage, rebuildAllUniforms, reconciler, registerPrimary, removeInteractivity, removeNodes, removeUniforms, resolve, unmountComponentAtNode, unregisterPrimary, updateCamera, updateFrustum, useBridge, useBuffers, useEnvironment, useFrame, useGPUStorage, useGraph, useInstanceHandle, useIsomorphicLayoutEffect, useLoader, useLocalNodes, useMutableCallback, useNodes, useRenderPipeline, useRenderTarget, useStore, useTexture, useTextures, useThree, useUniform, useUniforms, waitForPrimary };
-export type { Act, Args, ArgsProp, AttachFnType, AttachType, BackgroundConfig, BackgroundProp, BaseRendererProps, Bridge, BufferCreator, BufferLike, BufferRecord, BufferStore, BuffersWithUtils, Camera, CameraProps, CanvasProps, CanvasSchedulerConfig, Catalogue, ClearBuffersFn, ClearNodesFn, ClearStorageFn, ClearUniformsFn, Color, ColorManagementConfig, ComputeFunction, ConstructorRepresentation, CreatorState, DefaultGLProps, DefaultRendererProps, Disposable, DisposeBuffersFn, DisposeOptions, DisposeStorageFn, 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, WebGPUInternalState as InternalState, Intersection, IntersectionEvent, IsAllOptional, IsOptional, Layers, LegacyInternalState, LegacyRenderer, LegacyRootState, LoaderInstance, LoaderLike, LoaderResult, LocalNodeCreator, MappedTextureType, MathProps, MathRepresentation, MathType, MathTypes, Matrix3, Matrix4, Mutable, MutableOrReadonlyParameters, NodeCreator, NodeProps, NodeRecord, NodesWithUtils, NonFunctionKeys, ObjectMap, OffscreenCanvas$1 as OffscreenCanvas, Overwrite, Performance, PointerCaptureTarget, PointerState, PresetsType, PrimaryCanvasEntry, Properties, Quaternion, WebGPUR3FRenderer as R3FRenderer, RaycastableRepresentation, ReactProps, RebuildBuffersFn, RebuildNodesFn, RebuildStorageFn, RebuildUniformsFn, ReconcilerRoot, RemoveBuffersFn, RemoveNodesFn, RemoveStorageFn, RemoveUniformsFn, RenderCallback, RenderProps, RenderTargetOptions, Renderer, RendererConfigExtended, RendererFactory, RendererProps, Root, WebGPURootState as RootState, RootStore, ScopedStoreType, SetBlock, Size, StorageCreator, StorageLike, StorageRecord, StorageStore, StorageWithUtils, Subscription, TSLNode, TSLNodeInput, TextureEntry, TextureInput, TextureNode, TextureOperations, TextureResult, ThreeCamera, ThreeElement, ThreeElements, ThreeElementsImpl, ThreeEvent, ThreeExports, ThreeToJSXElements, UnblockProps, UniformCreator, UniformValue, UniformsWithUtils, UseTextureOptions, UseTexturesReturn, Vector2, Vector3, Vector4, VectorRepresentation, Viewport, VisibilityEntry, WebGLDefaultProps, WebGLProps, WebGLShadowConfig, WebGPUDefaultProps, WebGPUProps, WebGPUShadowConfig, XRManager, XRPointerConfig };
+/**
+ * @fileoverview WebGPU entry point - WebGPU only, no legacy WebGL
+ *
+ * This entry point is for apps that want to use ONLY WebGPURenderer.
+ * Includes WebGPU-specific hooks (useUniforms, useNodes, useTextures).
+ * Auto-extends THREE with WebGPU node materials (MeshBasicNodeMaterial, etc.)
+ *
+ * Usage:
+ *   import { Canvas, useFrame, useUniforms } from '@react-three/fiber/webgpu'
+ */
+
+/** `useThree` narrowed to WebGPU state — `state.renderer` is a `WebGPURenderer`. */
+type UseThreeWebGPU = <T = WebGPURootState>(selector?: (state: WebGPURootState) => T, equalityFn?: <U>(state: U, newState: U) => boolean) => T;
+/** `useFrame` narrowed to WebGPU state — the callback's `state.renderer` is a `WebGPURenderer`. */
+type UseFrameWebGPU = (callback?: FrameCallback$1<WebGPURootState>, priorityOrOptions?: number | UseFrameNextOptions) => FrameNextControls;
+declare const useThree: UseThreeWebGPU;
+declare const useFrame: UseFrameWebGPU;
+
+/** Canvas props on the WebGPU entry: `onCreated` receives `WebGPURootState`. */
+type WebGPUCanvasProps = Omit<CanvasProps, 'onCreated'> & {
+    /** Callback after the canvas has rendered (but not yet committed); `state.renderer` is a `WebGPURenderer` */
+    onCreated?: (state: WebGPURootState) => void;
+};
+
+/** `Canvas` narrowed to WebGPU state — the same component, `onCreated` typed against `WebGPURootState`. */
+declare const Canvas: (props: WebGPUCanvasProps) => 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, clearNodeScope, clearRootNodes, clearRootUniforms, clearScope, context, createEvents, createPointerEvents, createPortal, createRoot, createScopedStore, createStore, createTextureOperations, 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, rebuildAllBuffers, rebuildAllNodes, rebuildAllStorage, rebuildAllUniforms, reconciler, registerPrimary, registerRootExtension, removeInteractivity, removeNodes, removeUniforms, resolve, setRenderOverride, swapInteractivity, unmountComponentAtNode, unregisterPrimary, updateCamera, updateFrustum, useBridge, useBuffers, useEnvironment, useFrame, useGPUStorage, useGraph, useInstanceHandle, useIsomorphicLayoutEffect, useLoader, useLocalNodes, useMutableCallback, useNodes, useRenderPipeline, useRenderTarget, useStore, useTexture, useTextures, useThree, useUniform, useUniforms, waitForPrimary };
+export type { Act, Args, ArgsProp, AttachFnType, AttachType, BackgroundConfig, BackgroundProp, BaseRendererProps, Bridge, BufferCreator, BufferLike, BufferRecord, BufferStore, BuffersWithUtils, Camera, CameraProps, WebGPUCanvasProps as CanvasProps, CanvasSchedulerConfig, Catalogue, ClearBuffersFn, ClearNodesFn, ClearStorageFn, ClearUniformsFn, Color, ColorManagementConfig, ComputeFunction, ConstructorRepresentation, CreatorState, DefaultGLProps, DefaultRendererProps, Disposable, DisposeBuffersFn, DisposeOptions, DisposeStorageFn, DomEvent, Dpr, ElementProps, EnvironmentLoaderProps, EnvironmentProps, EquConfig, Euler, EventHandlers, EventManager, EventProps, Events, Extensions, FiberRoot, FilterFunction, FrameCallback, FrameNextCallback, FrameNextState, FrameState, Frameloop, FromRefMarker, GLProps, GLTFLike, GeometryProps, GeometryTransformProps, GlobalEffectType, GlobalRenderCallback, HostConfig, InferLoadResult, InjectState, InputLike, Instance, InstanceProps, WebGPUInternalState as InternalState, Intersection, IntersectionEvent, IsAllOptional, IsOptional, Layers, LegacyInternalState, LegacyRenderer, LegacyRootState, LoaderInstance, LoaderLike, LoaderResult, LocalNodeCreator, MappedTextureType, MathProps, MathRepresentation, MathType, MathTypes, Matrix3, Matrix4, Mutable, MutableOrReadonlyParameters, NodeCreator, NodeLike, NodeProps, NodeRecord, NodeStore, NodesWithUtils, NonFunctionKeys, Object3DMethod, ObjectMap, OffscreenCanvas$1 as OffscreenCanvas, OnceValue, Overwrite, Performance, PointerCaptureTarget, PointerState, PresetsType, PrimaryCanvasEntry, Properties, Quaternion, WebGPUR3FRenderer as R3FRenderer, RaycastableRepresentation, ReactProps, RebuildBuffersFn, RebuildNodesFn, RebuildStorageFn, RebuildUniformsFn, ReconcilerRoot, RemoveBuffersFn, RemoveNodesFn, RemoveStorageFn, RemoveUniformsFn, RenderCallback, RenderProps, RenderTargetOptions, Renderer, RendererConfigExtended, RendererFactory, RendererProps, Root, RootExtension, WebGPURootState as RootState, RootStore, ScopedStoreType, SetBlock, Size, StorageCreator, StorageLike, StorageRecord, StorageStore, StorageWithUtils, Subscription, TSLNode, TSLNodeInput, TSLNodeLike, TextureEntry, TextureInput, TextureNode, TextureOperations, TextureResult, ThreeCamera, ThreeElement, ThreeElements, ThreeElementsImpl, ThreeEvent, ThreeExports, ThreeToJSXElements, UnblockProps, UniformCreator, UniformValue, UniformsWithUtils, UseFrameWebGPU, UseTextureOptions, UseTexturesReturn, UseThreeWebGPU, Vector2, Vector3, Vector4, VectorRepresentation, Viewport, VisibilityEntry, WebGLDefaultProps, WebGLProps, WebGLShadowConfig, WebGPUCanvasProps, WebGPUDefaultProps, WebGPUProps, WebGPUShadowConfig, XRManager, XRPointerConfig };