@react-three/fiber 10.0.0-canary.20de6b2 → 10.0.0-canary.27df622

package/dist/index.d.cts

@@ -1,6 +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 } 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 } from 'three/webgpu';
 import * as THREE$1 from 'three';
 import { WebGLCubeRenderTarget, WebGLRenderTarget, WebGLRenderer, Color as Color$1, ColorRepresentation, Euler as Euler$1, Loader, RenderTargetOptions as RenderTargetOptions$1 } from 'three';
 import { WebGLRendererParameters } from 'three/src/renderers/WebGLRenderer.js';
@@ -352,6 +352,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) */
@@ -363,6 +364,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) ========================================
 
 /**
@@ -377,7 +397,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)
 
@@ -496,8 +518,13 @@ 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
@@ -622,7 +649,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 */
@@ -634,7 +661,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 */
@@ -722,12 +749,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).
    */
-  after?: string
+  before?: string | string[]
   /**
-   * Limit this canvas's render rate (frames per second).
+   * Run this Canvas root after the referenced Canvas root id(s).
+   */
+  after?: string | string[]
+  /**
+   * Numeric root order. Lower values run first.
+   */
+  order?: number
+  /**
+   * Limit this Canvas's default render job (frames per second).
    */
   fps?: number
 }
@@ -814,14 +848,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 */
@@ -1050,7 +1087,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 */
@@ -1158,81 +1195,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>
@@ -1257,7 +1299,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)
@@ -1270,88 +1312,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>>
@@ -1430,10 +1508,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> {
@@ -1454,11 +1533,30 @@ 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' | 'onUpdate' | Object3DMethod> & {
+    object: object
+    ref?: React.Ref<any>
+    onUpdate?: (self: any) => void
+    [prop: string]: unknown
+  }
   // Conflicts with DOM types can be accessed through a three* prefix
   threeAudio: ThreeElementsImpl['audio']
   threeSource: ThreeElementsImpl['source']
@@ -1499,6 +1597,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>;
@@ -1513,7 +1612,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 };
 }
 
 /**
@@ -1862,7 +1961,7 @@ 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>;
 
 /**
  * Gets or creates a memoized loader instance from a loader constructor or returns the loader if it's already an instance.
@@ -1895,7 +1994,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)
@@ -2191,7 +2290,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)
  *
@@ -2202,14 +2304,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<
@@ -3254,6 +3358,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;
@@ -3697,29 +3802,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.
@@ -3746,7 +3866,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.
  *
@@ -3764,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, 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, R3FRenderer, RaycastableRepresentation, ReactProps, ReconcilerRoot, RenderCallback, RenderProps, RenderTargetOptions, Renderer, RendererConfigExtended, RendererFactory, RendererProps, Root, 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, FromRefMarker, GLProps, GLTFLike, GeometryProps, GeometryTransformProps, GlobalEffectType, GlobalRenderCallback, HostConfig, InferLoadResult, InjectState, InputLike, Instance, InstanceProps, 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, Object3DMethod, ObjectMap, OffscreenCanvas$1 as OffscreenCanvas, OnceValue, Overwrite, Performance, PointerCaptureTarget, PointerState, PresetsType, PrimaryCanvasEntry, Properties, Quaternion, R3FRenderer, RaycastableRepresentation, ReactProps, ReconcilerRoot, RenderCallback, RenderProps, RenderTargetOptions, Renderer, RendererConfigExtended, RendererFactory, RendererProps, Root, 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 };