@react-three/fiber 10.0.0-canary.4f316e6 → 10.0.0-canary.4f9f64c

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) */
@@ -366,23 +367,15 @@ type BufferStore = Record<string, BufferLike | BufferRecord>
 //* Node Types (useNodes) ========================================
 
 /**
- * Structural shape of a TSL node as stored on `state.nodes`.
- *
- * Deliberately minimal rather than three's nominal `Node`: in @types/three several node classes
- * TSL hands back (OperatorNode, ConstNode, ...) do not extend `Node` cleanly, so a `Node` bound
- * would reject values `useNodes` creators legitimately return. This is the same shape
- * `useNodes` already constrains creators to (`TSLNodeLike`).
+ * 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.
  */
-interface NodeLike {
-  uuid?: string
-  nodeType?: string | null
-  /** label method for chaining - sets the node's label and returns self */
-  label?: ((label: string) => NodeLike) | string
-  setName?: (name: string) => this
-}
+type NodeLike = TSLNodeType | LegacyTSLNodeLike
 
 /** Flat record of TSL nodes (no nested scopes) */
-type NodeRecord = Record<string, NodeLike>
+type NodeRecord<T extends NodeLike = NodeLike> = Record<string, T>
 
 /**
  * Node store that can contain both root-level nodes and scoped node objects.
@@ -404,7 +397,9 @@ type NodeStore = Record<string, NodeLike | NodeRecord>
  * ```
  */
 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)
 
@@ -853,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 */
@@ -1089,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 */
@@ -1197,107 +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<UniformNodeTypeFor<T>, T>
+  type CallableTSLNode = ((...params: never[]) => unknown) & {
+    readonly shaderNode: unknown
+    readonly id: number
+  }
+
+  /** 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 })
+
+  /** Node type accepted by broad dynamic node-store readers. */
+  type TSLNodeType = three_webgpu.Node | CallableTSLNode
 
   /**
-   * three's node type name for a uniform value type, mirroring the `uniform()` overloads.
-   * A `UniformNode<number>` is a `Node<'float'>`, so TSL math (`.mul`, `.add`, ...) accepts it.
-   * Unknown or unlisted value types resolve to `unknown`, which TSL math rejects: narrow with
-   * `as UniformNode<number>` (or the matching value type) at the call site.
+   * 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 UniformNodeTypeFor<T> = T extends number
-    ? 'float'
-    : T extends boolean
-      ? 'bool'
-      : T extends three_webgpu.Color
-        ? 'color'
-        : T extends three_webgpu.Vector2
-          ? 'vec2'
-          : T extends three_webgpu.Vector3
-            ? 'vec3'
-            : T extends three_webgpu.Vector4
+  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.Matrix2
-                ? 'mat2'
-                : T extends three_webgpu.Matrix3
-                  ? 'mat3'
+              : 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'
-                    : unknown
-
-  /**
-   * 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
-
-  /**
-   * 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>
+                    : 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]>
+  }
 
-  /**
-   * 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)
-   * }
-   * ```
-   */
-  type TSLNodeType = Node | ShaderCallable<Node> | ShaderNodeObject<Node>
+  /** 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>
@@ -1322,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)
@@ -1335,56 +1312,20 @@ 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' {
-  /**
-   * Fn with array parameter destructuring
-   * @example Fn(([uv, skew]) => { ... })
-   */
-  export function Fn<R extends Node = Node>(
-    jsFunc: (inputs: ShaderNodeObject<Node>[]) => ShaderNodeObject<R>,
-  ): ShaderCallable<R>
-
-  /**
-   * Fn with object parameter destructuring
-   * @example Fn(({ color, intensity }) => { ... })
-   */
-  export function Fn<T extends Record<string, unknown>, R extends Node = Node>(
-    jsFunc: (inputs: T) => ShaderNodeObject<R>,
-  ): ShaderCallable<R>
-
-  /**
-   * Fn with array params + layout
-   * @example Fn(([a, b]) => { ... }, { layout: [...] })
-   */
-  export function Fn<R extends Node = Node>(
-    jsFunc: (inputs: ShaderNodeObject<Node>[]) => ShaderNodeObject<R>,
-    layout: { layout?: unknown },
-  ): ShaderCallable<R>
-
-  /**
-   * Fn with object params + layout
-   */
-  export function Fn<T extends Record<string, unknown>, R extends Node = Node>(
-    jsFunc: (inputs: T) => ShaderNodeObject<R>,
-    layout: { layout?: unknown },
-  ): ShaderCallable<R>
-}
-
 declare global {
   /**
    * three's own render pipeline type. Named here so the rest of R3F refers to three's shape
@@ -1412,10 +1353,15 @@ declare global {
    * 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.
    */
   interface PassRecord {
     scenePass?: ScenePassNode
-    [key: string]: three_webgpu.Node
+    [key: string]: three_webgpu.Node | undefined
   }
 
   /**
@@ -1562,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> {
@@ -1586,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']
@@ -1631,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>;
@@ -1645,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 };
 }
 
 /**
@@ -1994,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.
@@ -3391,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;
@@ -3834,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.
@@ -3883,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.
  *
@@ -3901,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, NodeLike, NodeProps, NodeRecord, NodeStore, 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 };