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

package/dist/legacy.d.mts

@@ -1,5 +1,5 @@
 import * as THREE$1 from 'three';
-import { Color as Color$1, ColorRepresentation, Euler as Euler$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';
+import { WebGLRenderTarget, Color as Color$1, ColorRepresentation, RenderTargetOptions as RenderTargetOptions$1, Euler as Euler$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';
 import * as React$1 from 'react';
 import { ReactNode, Component, RefObject, JSX } from 'react';
 import { StoreApi } from 'zustand';
@@ -43,11 +43,15 @@ declare const WebGPURenderer: {
     new (): {};
 };
 
+declare const RenderTarget: any;
+
 var THREE = /*#__PURE__*/_mergeNamespaces({
   __proto__: null,
   Inspector: Inspector,
   R3F_BUILD_LEGACY: R3F_BUILD_LEGACY,
   R3F_BUILD_WEBGPU: R3F_BUILD_WEBGPU,
+  RenderTarget: RenderTarget,
+  RenderTargetCompat: WebGLRenderTarget,
   WebGPURenderer: WebGPURenderer
 }, [THREE$1]);
 
@@ -186,6 +190,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[]
@@ -217,6 +229,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) ==============================
@@ -263,9 +286,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) */
@@ -276,9 +299,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 --------------------------------
 
 /**
@@ -332,13 +372,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 --------------------------------
 
@@ -397,6 +441,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 --------------------------------
 
@@ -474,6 +520,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
@@ -511,6 +567,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 */
@@ -712,6 +772,14 @@ 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
 }
 
 //* Reconciler Root ==============================
@@ -894,6 +962,11 @@ interface WebGLShadowConfig {
   shadows?: boolean | 'basic' | 'percentage' | 'soft' | 'variance' | Partial<THREE$1.WebGLShadowMap>
 }
 
+//* RenderTarget Types ==============================
+
+
+type RenderTargetOptions = RenderTargetOptions$1
+
 //* Global Types ==============================
 
 declare global {
@@ -912,6 +985,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
@@ -1010,6 +1092,10 @@ declare global {
   }
 }
 
+//* useFrameNext Types ==============================
+
+
+
 //* Global Type Declarations ==============================
 
 declare global {
@@ -1101,8 +1187,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 */
@@ -1294,7 +1380,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.
@@ -1320,19 +1408,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.
@@ -1341,6 +1435,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.
@@ -1549,7 +1671,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
@@ -1612,6 +1734,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.
@@ -1627,18 +1754,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)
@@ -1772,6 +1897,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
@@ -3306,6 +3464,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;
@@ -3343,5 +3521,5 @@ declare const hasConstructor: (object: unknown) => object is {
  */
 declare function Canvas(props: CanvasProps): react_jsx_runtime.JSX.Element;
 
-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, context, createEvents, createPointerEvents, createPortal, createRoot, createStore, 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, resolve, unmountComponentAtNode, updateCamera, useBridge, useFrame, useGraph, useInstanceHandle, useIsomorphicLayoutEffect, useLoader, useMutableCallback, useStore, useTexture, useTextures, useThree };
-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, MappedTextureType, MathProps, MathRepresentation, MathType, MathTypes, Matrix3, Matrix4, Mutable, MutableOrReadonlyParameters, 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, TextureEntry, ThreeCamera, ThreeElement, ThreeElements, ThreeElementsImpl, ThreeEvent, ThreeExports, ThreeToJSXElements, UnblockProps, 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, context, createEvents, createPointerEvents, createPortal, createRoot, createStore, 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, resolve, unmountComponentAtNode, updateCamera, updateFrustum, useBridge, useFrame, useGraph, useInstanceHandle, useIsomorphicLayoutEffect, useLoader, useMutableCallback, useRenderTarget, useStore, useTexture, useTextures, useThree };
+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, FrameTimingState, Frameloop, GLProps, GLTFLike, GlobalEffectType, GlobalRenderCallback, HostConfig, InferLoadResult, InjectState, InputLike, Instance, InstanceProps, InternalState, Intersection, IntersectionEvent, IsAllOptional, IsOptional, Layers, LoaderInstance, LoaderLike, LoaderResult, MappedTextureType, MathProps, MathRepresentation, MathType, MathTypes, Matrix3, Matrix4, Mutable, MutableOrReadonlyParameters, NonFunctionKeys, ObjectMap, OffscreenCanvas$1 as OffscreenCanvas, Overwrite, Performance, PointerCaptureTarget, Properties, Quaternion, RaycastableRepresentation, ReactProps, ReconcilerRoot, RenderCallback, RenderProps, RenderTargetOptions, Renderer, RendererFactory, RendererProps, Root, RootOptions, RootState, RootStore, SchedulerApi, SetBlock, Size, Subscription, TextureEntry, ThreeCamera, ThreeElement, ThreeElements, ThreeElementsImpl, ThreeEvent, ThreeExports, ThreeToJSXElements, UnblockProps, UseFrameNextOptions, UseFrameOptions, UseTextureOptions, UseTexturesReturn, Vector2, Vector3, Vector4, VectorRepresentation, Viewport, VisibilityEntry, WebGLDefaultProps, WebGLProps, WebGLShadowConfig, XRManager };