@react-three/fiber 10.0.0-alpha.0 → 10.0.0-alpha.2

package/dist/webgpu/index.d.cts

@@ -1,13 +1,12 @@
 import * as three_webgpu from 'three/webgpu';
-import { Node, ShaderNodeObject, Euler as Euler$1, Color as Color$2, ColorRepresentation as ColorRepresentation$1, Layers as Layers$1, Raycaster, Intersection as Intersection$1, Vector2 as Vector2$1, Vector3 as Vector3$1, Vector4 as Vector4$1, Quaternion as Quaternion$1, Matrix3 as Matrix3$1, Matrix4 as Matrix4$1, Object3D, Texture as Texture$1, OrthographicCamera } from 'three/webgpu';
+import { RenderTarget, Node, ShaderNodeObject, Euler as Euler$1, Color as Color$2, ColorRepresentation as ColorRepresentation$1, Layers as Layers$1, Raycaster, Intersection as Intersection$1, Vector2 as Vector2$1, Vector3 as Vector3$1, Vector4 as Vector4$1, Quaternion as Quaternion$1, Matrix3 as Matrix3$1, Matrix4 as Matrix4$1, Object3D, Texture as Texture$1, Frustum, OrthographicCamera } from 'three/webgpu';
 import { Inspector } from 'three/addons/inspector/Inspector.js';
 import * as THREE$1 from 'three';
-import { Color as Color$1, ColorRepresentation } from 'three';
+import { Color as Color$1, ColorRepresentation, RenderTargetOptions as RenderTargetOptions$1 } from 'three';
 import * as React$1 from 'react';
 import { ReactNode, Component, RefObject, JSX } from 'react';
 import { StoreApi } from 'zustand';
 import { UseBoundStoreWithEqualityFn } from 'zustand/traditional';
-import * as react_reconciler from 'C:\\dev\\react-three-fiber\\node_modules\\.pnpm\\@types+react-reconciler@0.32.3_@types+react@19.2.7\\node_modules\\@types\\react-reconciler\\index.d.ts';
 import { Options } from 'react-use-measure';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 
@@ -44,11 +43,15 @@ declare const WebGLRenderer: {
 type WebGLRendererParameters = never;
 type WebGLShadowMap = never;
 
+declare const WebGLRenderTarget: any;
+
 var THREE = /*#__PURE__*/_mergeNamespaces({
   __proto__: null,
   Inspector: Inspector,
   R3F_BUILD_LEGACY: R3F_BUILD_LEGACY,
   R3F_BUILD_WEBGPU: R3F_BUILD_WEBGPU,
+  RenderTargetCompat: RenderTarget,
+  WebGLRenderTarget: WebGLRenderTarget,
   WebGLRenderer: WebGLRenderer,
   WebGLRendererParameters: WebGLRendererParameters,
   WebGLShadowMap: WebGLShadowMap
@@ -189,6 +192,14 @@ interface EventHandlers {
   onPointerCancel?: (event: ThreeEvent<PointerEvent>) => void
   onWheel?: (event: ThreeEvent<WheelEvent>) => void
   onLostPointerCapture?: (event: ThreeEvent<PointerEvent>) => void
+
+  //* Visibility Events --------------------------------
+  /** Fires when object enters/exits camera frustum. Receives true when in view, false when out. */
+  onFramed?: (inView: boolean) => void
+  /** Fires when object occlusion state changes (WebGPU only, requires occlusionTest=true on object) */
+  onOccluded?: (occluded: boolean) => void
+  /** Fires when combined visibility changes (frustum + occlusion + visible prop) */
+  onVisible?: (visible: boolean) => void
 }
 
 type FilterFunction = (items: THREE$1.Intersection[], state: RootState) => THREE$1.Intersection[]
@@ -220,6 +231,17 @@ interface EventManager<TTarget> {
 interface PointerCaptureTarget {
   intersection: Intersection
   target: Element
+}
+
+//* Visibility System Types =====================================
+
+/** Entry in the visibility registry for tracking object visibility state */
+interface VisibilityEntry {
+  object: THREE$1.Object3D
+  handlers: Pick<EventHandlers, 'onFramed' | 'onOccluded' | 'onVisible'>
+  lastFramedState: boolean | null
+  lastOccludedState: boolean | null
+  lastVisibleState: boolean | null
 }
 
 //* Scheduler Types (useFrame) ==============================
@@ -266,9 +288,9 @@ interface AddPhaseOptions {
 // Frame State --------------------------------
 
 /**
- * State passed to useFrame callbacks
+ * Timing-only state for independent/outside mode (no RootState)
  */
-interface FrameNextState extends RootState {
+interface FrameTimingState {
   /** High-resolution timestamp from RAF (ms) */
   time: number
   /** Time since last frame in seconds (for legacy compatibility with THREE.Clock) */
@@ -279,9 +301,26 @@ interface FrameNextState extends RootState {
   frame: number
 }
 
+/**
+ * State passed to useFrame callbacks (extends RootState with timing)
+ */
+interface FrameNextState extends RootState, FrameTimingState {}
+
 /** Alias for FrameNextState */
 type FrameState = FrameNextState
 
+// Root Options --------------------------------
+
+/**
+ * Options for registerRoot
+ */
+interface RootOptions {
+  /** State provider for callbacks. Optional in independent mode. */
+  getState?: () => any
+  /** Error handler for job errors. Falls back to console.error if not provided. */
+  onError?: (error: Error) => void
+}
+
 // Callback Types --------------------------------
 
 /**
@@ -335,13 +374,17 @@ interface SchedulerApi {
   //* Root Management --------------------------------
 
   /** Register a root (Canvas) with the scheduler. Returns unsubscribe function. */
-  registerRoot(id: string, getState: () => RootState): () => void
+  registerRoot(id: string, options?: RootOptions): () => void
   /** Unregister a root */
   unregisterRoot(id: string): void
   /** Generate a unique root ID */
   generateRootId(): string
   /** Get the number of registered roots */
   getRootCount(): number
+  /** Check if any root is registered and ready */
+  readonly isReady: boolean
+  /** Subscribe to root-ready event. Fires immediately if already ready. Returns unsubscribe. */
+  onRootReady(callback: () => void): () => void
 
   //* Job Registration --------------------------------
 
@@ -400,6 +443,8 @@ interface SchedulerApi {
   readonly isRunning: boolean
   /** Get/set the frameloop mode ('always', 'demand', 'never') */
   frameloop: Frameloop
+  /** Independent mode - runs without Canvas, callbacks receive timing-only state */
+  independent: boolean
 
   //* Manual Stepping --------------------------------
 
@@ -477,6 +522,16 @@ interface InternalState {
   initialClick: [x: number, y: number]
   initialHits: THREE$1.Object3D[]
   lastEvent: React$1.RefObject<DomEvent | null>
+  /** Visibility event registry (onFramed, onOccluded, onVisible) */
+  visibilityRegistry: Map<string, VisibilityEntry>
+  /** Whether occlusion queries are enabled (WebGPU only) */
+  occlusionEnabled: boolean
+  /** Reference to the invisible occlusion observer mesh */
+  occlusionObserver: THREE$1.Mesh | null
+  /** Cached occlusion results from render pass - keyed by Object3D */
+  occlusionCache: Map<THREE$1.Object3D, boolean | null>
+  /** Internal helper group for R3F system objects (occlusion observer, etc.) */
+  helperGroup: THREE$1.Group | null
   active: boolean
   priority: number
   frames: number
@@ -514,6 +569,10 @@ interface RootState {
 
   /** Default camera */
   camera: ThreeCamera
+  /** Camera frustum for visibility checks - auto-updated each frame when autoUpdateFrustum is true */
+  frustum: THREE$1.Frustum
+  /** Whether to automatically update the frustum each frame (default: true) */
+  autoUpdateFrustum: boolean
   /** Default scene (may be overridden in portals to point to the portal container) */
   scene: THREE$1.Scene
   /** The actual root THREE.Scene - always points to the true scene, even inside portals */
@@ -557,8 +616,8 @@ interface RootState {
   advance: (timestamp: number, runGlobalEffects?: boolean) => void
   /** Shortcut to setting the event layer */
   setEvents: (events: Partial<EventManager<any>>) => void
-  /** Shortcut to manual sizing */
-  setSize: (width: number, height: number, top?: number, left?: number) => void
+  /** Shortcut to manual sizing. No args resets to props/container. Single arg creates square. */
+  setSize: (width?: number, height?: number, top?: number, left?: number) => void
   /** Shortcut to manual setting the pixel ratio */
   setDpr: (dpr: Dpr) => void
   /** Shortcut to setting frameloop flags */
@@ -577,6 +636,12 @@ interface RootState {
   postProcessing: any | null // THREE.PostProcessing when available
   /** Global TSL pass nodes for post-processing - use usePostProcessing() hook */
   passes: Record<string, any>
+  /** Internal version counter for HMR - incremented by rebuildNodes/rebuildUniforms to bust memoization */
+  _hmrVersion: number
+  /** Internal: whether setSize() has taken ownership of canvas dimensions */
+  _sizeImperative: boolean
+  /** Internal: stored size props from Canvas for reset functionality */
+  _sizeProps: { width?: number; height?: number } | null
   /** When the canvas was clicked but nothing was hit */
   onPointerMissed?: (event: MouseEvent) => void
   /** When a dragover event has missed any target */
@@ -715,6 +780,16 @@ interface RenderProps<TCanvas extends HTMLCanvasElement | OffscreenCanvas$1> {
   onDragOverMissed?: (event: DragEvent) => void
   /** Response for drop events that have missed any target */
   onDropMissed?: (event: DragEvent) => void
+  /** Whether to automatically update the frustum each frame (default: true) */
+  autoUpdateFrustum?: boolean
+  /**
+   * Enable WebGPU occlusion queries for onOccluded/onVisible events.
+   * Auto-enabled when any object uses onOccluded or onVisible handlers.
+   * Only works with WebGPU renderer - WebGL will log a warning.
+   */
+  occlusion?: boolean
+  /** Internal: stored size props from Canvas for reset functionality */
+  _sizeProps?: { width?: number; height?: number } | null
 }
 
 //* Reconciler Root ==============================
@@ -746,8 +821,12 @@ type InjectState = Partial<
 
 //* Reconciler Types ==============================
 
+// FiberRoot is an opaque internal React type - we define it locally
+// to avoid bundling @types/react-reconciler which causes absolute path issues
+type FiberRoot = any
+
 interface Root {
-  fiber: react_reconciler.FiberRoot
+  fiber: FiberRoot
   store: RootStore
 }
 
@@ -825,8 +904,7 @@ type GlobalEffectType = 'before' | 'after' | 'tail'
 //* Canvas Types ==============================
 
 interface CanvasProps
-  extends Omit<RenderProps<HTMLCanvasElement>, 'size'>,
-    React$1.HTMLAttributes<HTMLDivElement> {
+  extends Omit<RenderProps<HTMLCanvasElement>, 'size'>, React$1.HTMLAttributes<HTMLDivElement> {
   children?: React$1.ReactNode
   ref?: React$1.Ref<HTMLCanvasElement>
   /** Canvas fallback content, similar to img's alt prop */
@@ -840,6 +918,12 @@ interface CanvasProps
   eventSource?: HTMLElement | React$1.RefObject<HTMLElement>
   /** 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 */
+  hmr?: boolean
+  /** Canvas resolution width in pixels. If omitted, uses container width. */
+  width?: number
+  /** Canvas resolution height in pixels. If omitted, uses container height. */
+  height?: number
 }
 
 //* Loader Types ==============================
@@ -868,20 +952,15 @@ type InferLoadResult<T> = T extends {
 }
   ? R
   : T extends ConstructorRepresentation<any>
-  ? InstanceType<T> extends {
-      load(url: any, onLoad?: (result: infer R) => void, ...args: any[]): any
-    }
-    ? R
+    ? InstanceType<T> extends {
+        load(url: any, onLoad?: (result: infer R) => void, ...args: any[]): any
+      }
+      ? R
+      : any
     : any
-  : any
 
-type LoaderResult<T extends LoaderLike | ConstructorRepresentation<LoaderLike>> = InferLoadResult<
-  LoaderInstance<T>
-> extends infer R
-  ? R extends GLTFLike
-    ? R & ObjectMap
-    : R
-  : never
+type LoaderResult<T extends LoaderLike | ConstructorRepresentation<LoaderLike>> =
+  InferLoadResult<LoaderInstance<T>> extends infer R ? (R extends GLTFLike ? R & ObjectMap : R) : never
 
 type Extensions<T extends LoaderLike | ConstructorRepresentation<LoaderLike>> = (
   loader: LoaderInstance<T>,
@@ -897,6 +976,11 @@ interface WebGLShadowConfig {
   shadows?: boolean | 'basic' | 'percentage' | 'soft' | 'variance' | Partial<THREE$1.WebGLShadowMap>
 }
 
+//* RenderTarget Types ==============================
+
+
+type RenderTargetOptions = RenderTargetOptions$1
+
 //* Global Types ==============================
 
 declare global {
@@ -915,6 +999,15 @@ declare global {
    */
   type UniformStore = Record<string, UniformNode | UniformRecord>
 
+  /**
+   * Helper to safely access a uniform node from the store.
+   * Use this when accessing state.uniforms to get proper typing.
+   * @example
+   * const uTime = uniforms.uTime as UniformNode<number>
+   * const uColor = uniforms.uColor as UniformNode<import('three/webgpu').Color>
+   */
+  type GetUniform<T = unknown> = UniformNode<T>
+
   /**
    * Acceptable input values for useUniforms - raw values that get converted to UniformNodes
    * Supports: primitives, Three.js types, plain objects (converted to vectors), and UniformNodes
@@ -1013,6 +1106,10 @@ declare global {
   }
 }
 
+//* useFrameNext Types ==============================
+
+
+
 //* Global Type Declarations ==============================
 
 declare global {
@@ -1104,8 +1201,8 @@ declare global {
   interface RootEntry {
     /** Unique identifier for this root */
     id: string
-    /** Function to get the root's current state */
-    getState: () => RootState
+    /** Function to get the root's current state. Returns any to support independent mode. */
+    getState: () => any
     /** Map of job IDs to Job objects */
     jobs: Map<string, Job>
     /** Cached sorted job list for execution order */
@@ -1162,8 +1259,8 @@ type MathTypes = MathRepresentation | Euler$1 | Color$2
 type MathType<T extends MathTypes> = T extends Color$2
   ? Args<typeof Color$2> | ColorRepresentation$1
   : T extends VectorRepresentation | Layers$1 | Euler$1
-  ? T | MutableOrReadonlyParameters<T['set']> | number
-  : T | MutableOrReadonlyParameters<T['set']>
+    ? T | MutableOrReadonlyParameters<T['set']> | number
+    : T | MutableOrReadonlyParameters<T['set']>
 
 type MathProps<P> = {
   [K in keyof P as P[K] extends MathTypes ? K : never]: P[K] extends MathTypes ? MathType<P[K]> : never
@@ -1297,7 +1394,9 @@ declare namespace useLoader {
  * - Demand mode support via invalidate()
  */
 declare class Scheduler {
-    private static instance;
+    private static readonly INSTANCE_KEY;
+    private static get instance();
+    private static set instance(value);
     /**
      * Get the global scheduler instance (creates if doesn't exist).
      * Uses HMR data to preserve instance across hot reloads.
@@ -1323,19 +1422,25 @@ declare class Scheduler {
     private jobStateListeners;
     private pendingFrames;
     private _frameloop;
+    private _independent;
+    private errorHandler;
+    private rootReadyCallbacks;
     get phases(): string[];
     get frameloop(): Frameloop;
     set frameloop(mode: Frameloop);
     get isRunning(): boolean;
+    get isReady(): boolean;
+    get independent(): boolean;
+    set independent(value: boolean);
     constructor();
     /**
      * Register a root (Canvas) with the scheduler.
      * The first root to register starts the RAF loop (if frameloop='always').
      * @param {string} id - Unique identifier for this root
-     * @param {() => RootState} getState - Function to get the root's current state
+     * @param {RootOptions} [options] - Optional configuration with getState and onError callbacks
      * @returns {() => void} Unsubscribe function to remove this root
      */
-    registerRoot(id: string, getState: () => RootState): () => void;
+    registerRoot(id: string, options?: RootOptions): () => void;
     /**
      * Unregister a root from the scheduler.
      * Cleans up all job state listeners for this root's jobs.
@@ -1344,6 +1449,34 @@ declare class Scheduler {
      * @returns {void}
      */
     unregisterRoot(id: string): void;
+    /**
+     * Subscribe to be notified when a root becomes available.
+     * Fires immediately if a root already exists.
+     * @param {() => void} callback - Function called when first root registers
+     * @returns {() => void} Unsubscribe function
+     */
+    onRootReady(callback: () => void): () => void;
+    /**
+     * Notify all registered root-ready callbacks.
+     * Called when the first root registers.
+     * @returns {void}
+     * @private
+     */
+    private notifyRootReady;
+    /**
+     * Ensure a default root exists for independent mode.
+     * Creates a minimal root with no state provider.
+     * @returns {void}
+     * @private
+     */
+    private ensureDefaultRoot;
+    /**
+     * Trigger error handling for job errors.
+     * Uses the bound error handler if available, otherwise logs to console.
+     * @param {Error} error - The error to handle
+     * @returns {void}
+     */
+    triggerError(error: Error): void;
     /**
      * Add a named phase to the scheduler's execution order.
      * Marks all roots for rebuild to incorporate the new phase.
@@ -1552,7 +1685,7 @@ declare class Scheduler {
     /**
      * Execute all jobs for a single root in sorted order.
      * Rebuilds sorted job list if needed, then dispatches each job.
-     * Errors are caught and propagated to the root's error boundary.
+     * Errors are caught and propagated via triggerError.
      * @param {RootEntry} root - The root entry to tick
      * @param {number} timestamp - RAF timestamp in milliseconds
      * @param {number} delta - Time since last frame in seconds
@@ -1615,6 +1748,11 @@ declare const getScheduler: () => Scheduler;
 /**
  * Frame hook with phase-based ordering, priority, and FPS throttling.
  *
+ * Works both inside and outside Canvas context:
+ * - Inside Canvas: Full RootState (gl, scene, camera, etc.)
+ * - Outside Canvas (waiting mode): Waits for Canvas to mount, then gets full state
+ * - Outside Canvas (independent mode): Fires immediately with timing-only state
+ *
  * 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.
@@ -1630,18 +1768,16 @@ declare const getScheduler: () => Scheduler;
  * useFrame((state, delta) => { ... }, { phase: 'physics' })
  *
  * @example
- * // With controls
- * const controls = useFrame(cb, { phase: 'physics', id: 'my-physics' })
- * controls.step()      // Step this job only
- * controls.stepAll()   // Step all jobs
- * controls.pause()     // Pause this job
- * controls.resume()    // Resume this job
+ * // Outside Canvas - waits for Canvas to mount
+ * function UI() {
+ *   useFrame((state, delta) => { syncUI(state.camera) });
+ *   return <button>...</button>;
+ * }
  *
  * @example
- * // Manual mode (frameloop='never')
- * const { stepAll } = useFrame(cb)
- * // In your animation controller:
- * stepAll()  // Advance all useFrame jobs
+ * // Independent mode - no Canvas needed
+ * getScheduler().independent = true;
+ * useFrame((state, delta) => { updateGame(delta) });
  *
  * @example
  * // Scheduler-only access (no callback)
@@ -1775,6 +1911,39 @@ interface UseTexturesReturn {
  */
 declare function useTextures(): UseTexturesReturn;
 
+/**
+ * Creates a render target compatible with the current renderer.
+ *
+ * - Legacy build: Returns WebGLRenderTarget
+ * - WebGPU build: Returns RenderTarget
+ * - Default build: Returns whichever matches the active renderer
+ *
+ * @param width - Target width (defaults to canvas width)
+ * @param height - Target height (defaults to canvas height)
+ * @param options - Three.js RenderTarget options
+ *
+ * @example
+ * ```tsx
+ * function PortalScene() {
+ *   const fbo = useRenderTarget(512, 512, { depthBuffer: true })
+ *
+ *   useFrame(({ renderer, scene, camera }) => {
+ *     renderer.setRenderTarget(fbo)
+ *     renderer.render(scene, camera)
+ *     renderer.setRenderTarget(null)
+ *   })
+ *
+ *   return (
+ *     <mesh>
+ *       <planeGeometry />
+ *       <meshBasicMaterial map={fbo.texture} />
+ *     </mesh>
+ *   )
+ * }
+ * ```
+ */
+declare function useRenderTarget(width?: number, height?: number, options?: RenderTargetOptions): RenderTarget<THREE$1.Texture<unknown>>;
+
 /**
  * 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
@@ -3309,6 +3478,26 @@ declare function getUuidPrefix(uuid: string): string;
  * @param size - Current viewport size
  */
 declare function updateCamera(camera: ThreeCamera, size: Size): void;
+/**
+ * Updates a frustum from a camera's projection and world matrices.
+ * If no target frustum is provided, creates and returns a new one.
+ *
+ * @param camera - Camera to extract frustum from
+ * @param frustum - Optional existing frustum to update (creates new if not provided)
+ * @returns The updated or newly created frustum
+ *
+ * @example
+ * // Create new frustum
+ * const frustum = updateFrustum(camera)
+ *
+ * // Update existing frustum (no allocation)
+ * updateFrustum(camera, existingFrustum)
+ *
+ * // Use for visibility checks
+ * if (frustum.containsPoint(point)) { ... }
+ * if (frustum.intersectsObject(mesh)) { ... }
+ */
+declare function updateFrustum(camera: ThreeCamera, frustum?: Frustum): Frustum;
 
 declare const is: {
     obj: (a: any) => boolean;
@@ -3346,57 +3535,163 @@ declare const hasConstructor: (object: unknown) => object is {
  */
 declare function Canvas(props: CanvasProps): react_jsx_runtime.JSX.Element;
 
+/**
+ * ScopedStore - Type-safe wrapper for nested stores (uniforms, nodes)
+ *
+ * Provides TypeScript-friendly access to uniform/node stores where the runtime
+ * structure is `Record<string, T | Record<string, T>>` (leaf nodes or nested scopes).
+ *
+ * The wrapper uses a Proxy to:
+ * 1. Return `T` for property access (type assumption: assumes leaf node)
+ * 2. Provide `.scope(key)` method for explicit nested access
+ * 3. Support iteration methods: has(), keys(), Object.keys(), for...in
+ *
+ * @example
+ * ```tsx
+ * useLocalNodes(({ uniforms }) => ({
+ *   wobble: sin(uniforms.uTime.mul(2)),           // No cast needed!
+ *   playerHealth: uniforms.scope('player').uHealth // Explicit scope access
+ * }))
+ * ```
+ */
+
+/** 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;
+} & {
+    /** Access a nested scope by key. Returns empty wrapper if scope doesn't exist. */
+    scope(key: string): ScopedStoreType<T>;
+    /** Check if a key exists in the store */
+    has(key: string): boolean;
+    /** Get all keys in the store */
+    keys(): string[];
+};
+/**
+ * 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>;
+/**
+ * State type passed to creator functions with ScopedStore wrappers.
+ * Provides type-safe access to uniforms and nodes without manual casting.
+ */
+type CreatorState = Omit<RootState, 'uniforms' | 'nodes'> & {
+    /** Type-safe uniform access - property access returns UniformNode */
+    uniforms: ScopedStoreType<UniformNode>;
+    /** Type-safe node access - property access returns Node */
+    nodes: ScopedStoreType<Node>;
+};
+
 /** Creator function that returns uniform inputs (can be raw values or UniformNodes) */
-type UniformCreator<T extends UniformInputRecord = UniformInputRecord> = (state: RootState) => T;
-declare function useUniforms(): UniformRecord;
-declare function useUniforms(scope: string): UniformRecord;
-declare function useUniforms<T extends UniformInputRecord>(creator: UniformCreator<T>): UniformRecord<UniformNode>;
-declare function useUniforms<T extends UniformInputRecord>(creator: UniformCreator<T>, scope: string): UniformRecord<UniformNode>;
-declare function useUniforms<T extends UniformInputRecord>(uniforms: T): UniformRecord<UniformNode>;
-declare function useUniforms<T extends UniformInputRecord>(uniforms: T, scope: string): UniformRecord<UniformNode>;
+type UniformCreator<T extends UniformInputRecord = UniformInputRecord> = (state: CreatorState) => T;
+/** Function signature for removeUniforms util */
+type RemoveUniformsFn = (names: string | string[], scope?: string) => void;
+/** Function signature for clearUniforms util */
+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 & {
+    removeUniforms: RemoveUniformsFn;
+    clearUniforms: ClearUniformsFn;
+    rebuildUniforms: RebuildUniformsFn;
+};
+declare function useUniforms(): UniformsWithUtils<UniformRecord & Record<string, UniformRecord>>;
+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>>;
+/**
+ * Global rebuildUniforms function for HMR integration.
+ * Clears cached uniforms and increments _hmrVersion to trigger re-creation.
+ * Call this when HMR is detected to refresh all uniform creators.
+ *
+ * @param store - The R3F store (from useStore or context)
+ * @param scope - Optional scope to rebuild ('root' for root only, string for specific scope, undefined for all)
+ */
+declare function rebuildAllUniforms(store: ReturnType<typeof useStore>, scope?: string): void;
 /**
  * Remove uniforms by name from root level or a scope
- * @param scope - If provided, removes from that scope. Otherwise removes from root.
+ * @deprecated Use `const { removeUniforms } = useUniforms()` instead
  */
 declare function removeUniforms(set: ReturnType<typeof useStore>['setState'], names: string[], scope?: string): void;
 /**
  * Clear all uniforms from a scope (removes the entire scope object)
+ * @deprecated Use `const { clearUniforms } = useUniforms()` instead
  */
 declare function clearScope(set: ReturnType<typeof useStore>['setState'], scope: string): void;
 /**
  * Clear all root-level uniforms (preserves scopes)
+ * @deprecated Use `const { clearUniforms } = useUniforms()` with `clearUniforms('root')` instead
  */
 declare function clearRootUniforms(set: ReturnType<typeof useStore>['setState']): void;
 
 /** Supported uniform value types */
 type UniformValue = number | boolean | Vector2$1 | Vector3$1 | Vector4$1 | Color$2 | Matrix3$1 | Matrix4$1;
+/** Widen literal types to their base types (0 → number, true → boolean) */
+type Widen<T> = T extends number ? number : T extends boolean ? boolean : T;
 declare function useUniform<T extends UniformValue>(name: string): UniformNode<T>;
-declare function useUniform<T extends UniformValue>(name: string, value: T): UniformNode<T>;
+declare function useUniform<T extends UniformValue>(name: string, value: T): UniformNode<Widen<T>>;
 
 /** TSL node type - extends Three.js Node for material compatibility */
 type TSLNode = Node;
 type NodeRecord<T extends Node = Node> = Record<string, T>;
-type NodeCreator<T extends NodeRecord> = (state: RootState) => T;
-declare function useNodes(): NodeRecord;
-declare function useNodes(scope: string): NodeRecord;
-declare function useNodes<T extends NodeRecord>(creator: NodeCreator<T>): T;
-declare function useNodes<T extends NodeRecord>(creator: NodeCreator<T>, scope: string): T;
+type NodeCreator<T extends NodeRecord> = (state: CreatorState) => T;
+/** Function signature for removeNodes util */
+type RemoveNodesFn = (names: string | string[], scope?: string) => void;
+/** Function signature for clearNodes util */
+type ClearNodesFn = (scope?: string) => void;
+/** Function signature for rebuildNodes util */
+type RebuildNodesFn = (scope?: string) => void;
+/** Return type with utils included */
+type NodesWithUtils<T extends NodeRecord = NodeRecord> = T & {
+    removeNodes: RemoveNodesFn;
+    clearNodes: ClearNodesFn;
+    rebuildNodes: RebuildNodesFn;
+};
+declare function useNodes(): NodesWithUtils<NodeRecord & Record<string, NodeRecord>>;
+declare function useNodes(scope: string): NodesWithUtils;
+declare function useNodes<T extends NodeRecord>(creator: NodeCreator<T>): NodesWithUtils<T>;
+declare function useNodes<T extends NodeRecord>(creator: NodeCreator<T>, scope: string): NodesWithUtils<T>;
+/**
+ * Global rebuildNodes function for HMR integration.
+ * Clears cached nodes and increments _hmrVersion to trigger re-creation.
+ * Call this when HMR is detected to refresh all node creators.
+ *
+ * @param store - The R3F store (from useStore or context)
+ * @param scope - Optional scope to rebuild ('root' for root only, string for specific scope, undefined for all)
+ */
+declare function rebuildAllNodes(store: ReturnType<typeof useStore>, scope?: string): void;
 /**
  * Remove nodes by name from root level or a scope
- * @param scope - If provided, removes from that scope. Otherwise removes from root.
+ * @deprecated Use `const { removeNodes } = useNodes()` instead
  */
 declare function removeNodes(set: ReturnType<typeof useStore>['setState'], names: string[], scope?: string): void;
 /**
  * Clear all nodes from a scope (removes the entire scope object)
+ * @deprecated Use `const { clearNodes } = useNodes()` instead
  */
 declare function clearNodeScope(set: ReturnType<typeof useStore>['setState'], scope: string): void;
 /**
  * Clear all root-level nodes (preserves scopes)
+ * @deprecated Use `const { clearNodes } = useNodes()` with `clearNodes('root')` instead
  */
 declare function clearRootNodes(set: ReturnType<typeof useStore>['setState']): void;
 
-/** Creator receives RootState - destructure what you need. Returns any record. */
-type LocalNodeCreator<T extends Record<string, unknown>> = (state: RootState) => T;
+/** Creator receives CreatorState with ScopedStore wrappers for type-safe access. Returns any record. */
+type LocalNodeCreator<T extends Record<string, unknown>> = (state: CreatorState) => T;
 /**
  * Creates local values that rebuild when uniforms, nodes, or textures change.
  *
@@ -3415,6 +3710,12 @@ type LocalNodeCreator<T extends Record<string, unknown>> = (state: RootState) =>
  * const { scaled } = useLocalNodes(({ camera, nodes }) => ({
  *   scaled: nodes.basePos.mul(camera.zoom),
  * }))
+ *
+ * // Type-safe uniform access
+ * const { colorNode } = useLocalNodes(({ uniforms }) => {
+ *   const uValue = uniforms.myUniform as UniformNode<number>
+ *   return { colorNode: mix(colorA, colorB, uValue) }
+ * })
  * ```
  */
 declare function useLocalNodes<T extends Record<string, unknown>>(creator: LocalNodeCreator<T>): T;
@@ -3466,5 +3767,5 @@ declare function createTextureOperations(set: StoreApi<RootState>['setState']):
  */
 declare function usePostProcessing(mainCB?: PostProcessingMainCallback, setupCB?: PostProcessingSetupCallback): UsePostProcessingReturn;
 
-export { Block, Canvas, ErrorBoundary, IsObject, R3F_BUILD_LEGACY, R3F_BUILD_WEBGPU, REACT_INTERNAL_PROPS, RESERVED_PROPS, three_d as ReactThreeFiber, Scheduler, Texture, _roots, act, addAfterEffect, addEffect, addTail, advance, applyProps, attach, buildGraph, calculateDpr, clearNodeScope, clearRootNodes, clearRootUniforms, clearScope, context, createEvents, createPointerEvents, createPortal, createRoot, createStore, createTextureOperations, detach, diffProps, dispose, createPointerEvents as events, extend, findInitialRoot, flushSync, getInstanceProps, getRootState, getScheduler, getUuidPrefix, hasConstructor, invalidate, invalidateInstance, is, isColorRepresentation, isCopyable, isObject3D, isOrthographicCamera, isRef, isRenderer, isTexture, isVectorLike, prepare, reconciler, removeInteractivity, removeNodes, removeUniforms, resolve, unmountComponentAtNode, updateCamera, useBridge, useFrame, useGraph, useInstanceHandle, useIsomorphicLayoutEffect, useLoader, useLocalNodes, useMutableCallback, useNodes, usePostProcessing, useStore, useTexture, useTextures, useThree, useUniform, useUniforms };
-export type { Act, AddPhaseOptions, Args, ArgsProp, AttachFnType, AttachType, BaseRendererProps, Bridge, Camera, CameraProps, CanvasProps, Catalogue, Color, ComputeFunction, ConstructorRepresentation, DefaultGLProps, DefaultRendererProps, Disposable, DomEvent, Dpr, ElementProps, EquConfig, Euler, EventHandlers, EventManager, EventProps, Events, Extensions, FilterFunction, FrameCallback, FrameControls, FrameNextCallback, FrameNextControls, FrameNextState, FrameState, Frameloop, GLProps, GLTFLike, GlobalEffectType, GlobalRenderCallback, HostConfig, InferLoadResult, InjectState, InputLike, Instance, InstanceProps, InternalState, Intersection, IntersectionEvent, IsAllOptional, IsOptional, Layers, LoaderInstance, LoaderLike, LoaderResult, LocalNodeCreator, MappedTextureType, MathProps, MathRepresentation, MathType, MathTypes, Matrix3, Matrix4, Mutable, MutableOrReadonlyParameters, NodeCreator, NodeRecord, NonFunctionKeys, ObjectMap, OffscreenCanvas$1 as OffscreenCanvas, Overwrite, Performance, PointerCaptureTarget, Properties, Quaternion, RaycastableRepresentation, ReactProps, ReconcilerRoot, RenderCallback, RenderProps, Renderer, RendererFactory, RendererProps, Root, RootState, RootStore, SchedulerApi, SetBlock, Size, Subscription, TSLNode, TextureEntry, TextureOperations, ThreeCamera, ThreeElement, ThreeElements, ThreeElementsImpl, ThreeEvent, ThreeExports, ThreeToJSXElements, UnblockProps, UniformCreator, UniformValue, UseFrameNextOptions, UseFrameOptions, UseTextureOptions, UseTexturesReturn, Vector2, Vector3, Vector4, VectorRepresentation, Viewport, WebGLDefaultProps, WebGLProps, WebGLShadowConfig, XRManager };
+export { Block, Canvas, ErrorBoundary, IsObject, R3F_BUILD_LEGACY, R3F_BUILD_WEBGPU, REACT_INTERNAL_PROPS, RESERVED_PROPS, three_d as ReactThreeFiber, Scheduler, 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, getInstanceProps, getRootState, getScheduler, getUuidPrefix, hasConstructor, invalidate, invalidateInstance, is, isColorRepresentation, isCopyable, isObject3D, isOrthographicCamera, isRef, isRenderer, isTexture, isVectorLike, prepare, rebuildAllNodes, rebuildAllUniforms, reconciler, removeInteractivity, removeNodes, removeUniforms, resolve, unmountComponentAtNode, updateCamera, updateFrustum, useBridge, useFrame, useGraph, useInstanceHandle, useIsomorphicLayoutEffect, useLoader, useLocalNodes, useMutableCallback, useNodes, usePostProcessing, useRenderTarget, useStore, useTexture, useTextures, useThree, useUniform, useUniforms };
+export type { Act, AddPhaseOptions, Args, ArgsProp, AttachFnType, AttachType, BaseRendererProps, Bridge, Camera, CameraProps, CanvasProps, Catalogue, ClearNodesFn, ClearUniformsFn, Color, ComputeFunction, ConstructorRepresentation, CreatorState, DefaultGLProps, DefaultRendererProps, Disposable, DomEvent, Dpr, ElementProps, EquConfig, Euler, EventHandlers, EventManager, EventProps, Events, Extensions, FiberRoot, FilterFunction, FrameCallback, FrameControls, FrameNextCallback, FrameNextControls, FrameNextState, FrameState, FrameTimingState, Frameloop, GLProps, GLTFLike, GlobalEffectType, GlobalRenderCallback, HostConfig, InferLoadResult, InjectState, InputLike, Instance, InstanceProps, InternalState, Intersection, IntersectionEvent, IsAllOptional, IsOptional, Layers, LoaderInstance, LoaderLike, LoaderResult, LocalNodeCreator, MappedTextureType, MathProps, MathRepresentation, MathType, MathTypes, Matrix3, Matrix4, Mutable, MutableOrReadonlyParameters, NodeCreator, NodeRecord, NodesWithUtils, NonFunctionKeys, ObjectMap, OffscreenCanvas$1 as OffscreenCanvas, Overwrite, Performance, PointerCaptureTarget, Properties, Quaternion, RaycastableRepresentation, ReactProps, RebuildNodesFn, RebuildUniformsFn, ReconcilerRoot, RemoveNodesFn, RemoveUniformsFn, RenderCallback, RenderProps, RenderTargetOptions, Renderer, RendererFactory, RendererProps, Root, RootOptions, RootState, RootStore, SchedulerApi, ScopedStoreType, SetBlock, Size, Subscription, TSLNode, TextureEntry, TextureOperations, ThreeCamera, ThreeElement, ThreeElements, ThreeElementsImpl, ThreeEvent, ThreeExports, ThreeToJSXElements, UnblockProps, UniformCreator, UniformValue, UniformsWithUtils, UseFrameNextOptions, UseFrameOptions, UseTextureOptions, UseTexturesReturn, Vector2, Vector3, Vector4, VectorRepresentation, Viewport, VisibilityEntry, WebGLDefaultProps, WebGLProps, WebGLShadowConfig, XRManager };