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

package/dist/legacy.mjs

@@ -1,5 +1,5 @@
 import * as three from 'three';
-import { Layers, RGBAFormat, UnsignedByteType, Vector3, Vector2, TextureLoader, Texture as Texture$1, SRGBColorSpace, Raycaster, OrthographicCamera, PerspectiveCamera, Scene, PCFSoftShadowMap, VSMShadowMap, PCFShadowMap, BasicShadowMap, ColorManagement, LinearSRGBColorSpace, NoToneMapping, ACESFilmicToneMapping, WebGLRenderer } from 'three';
+import { WebGLRenderTarget, Frustum, Matrix4, Group, BoxGeometry, MeshBasicNodeMaterial, Mesh, Node, NodeUpdateType, Layers, RGBAFormat, UnsignedByteType, Vector3, Vector2, TextureLoader, Texture as Texture$1, SRGBColorSpace, Raycaster, OrthographicCamera, PerspectiveCamera, Scene, PCFSoftShadowMap, VSMShadowMap, PCFShadowMap, BasicShadowMap, ColorManagement, LinearSRGBColorSpace, NoToneMapping, ACESFilmicToneMapping, WebGLRenderer } from 'three';
 import { jsx, Fragment } from 'react/jsx-runtime';
 import * as React from 'react';
 import React__default, { useMemo, useLayoutEffect, useEffect, useContext, useRef, useImperativeHandle, useCallback, useState } from 'react';
@@ -33,12 +33,15 @@ const WebGPURenderer = class WebGPURenderer2 {
     throw new Error("WebGPURenderer is not available in legacy builds. Use @react-three/fiber/webgpu instead.");
   }
 };
+const RenderTarget = null;
 
 const 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]);
 
@@ -147,6 +150,13 @@ function updateCamera(camera, size) {
   }
   camera.updateProjectionMatrix();
 }
+const frustumMatrix = new Matrix4();
+function updateFrustum(camera, frustum) {
+  const target = frustum ?? new Frustum();
+  frustumMatrix.multiplyMatrices(camera.projectionMatrix, camera.matrixWorldInverse);
+  target.setFromProjectionMatrix(frustumMatrix);
+  return target;
+}
 
 const REACT_INTERNAL_PROPS = ["children", "key", "ref"];
 function findInitialRoot(instance) {
@@ -227,6 +237,205 @@ function invalidateInstance(instance) {
   if (state && state.internal.frames === 0) state.invalidate();
 }
 
+const tempFrustum = new Frustum();
+let hasWarnedWebGL = false;
+let tslModule = null;
+async function loadTSL() {
+  if (tslModule) return tslModule;
+  try {
+    const tsl = await import('three/tsl');
+    tslModule = { uniform: tsl.uniform, nodeObject: tsl.nodeObject };
+    return tslModule;
+  } catch {
+    return null;
+  }
+}
+function createOcclusionObserverNode(store, uniform) {
+  const node = new Node("float");
+  node.updateType = NodeUpdateType.OBJECT;
+  node.update = function(frame) {
+    const { internal } = store.getState();
+    const registry = internal.visibilityRegistry;
+    const cache = internal.occlusionCache;
+    for (const entry of registry.values()) {
+      const { object, handlers } = entry;
+      if (handlers.onOccluded || handlers.onVisible) {
+        const isOccluded = frame.renderer.isOccluded(object);
+        cache.set(object, isOccluded);
+      }
+    }
+  };
+  node.setup = function() {
+    return uniform(0);
+  };
+  return node;
+}
+let occlusionSetupPromise = null;
+function enableOcclusion(store) {
+  const state = store.getState();
+  const { internal, renderer, rootScene } = state;
+  if (internal.occlusionEnabled || occlusionSetupPromise) return;
+  const hasOcclusionSupport = typeof renderer?.isOccluded === "function";
+  if (!hasOcclusionSupport) {
+    if (!hasWarnedWebGL) {
+      console.warn(
+        "[R3F] Warning: onOccluded/onVisible occlusion queries require WebGPU renderer. Occlusion events will not fire on WebGL."
+      );
+      hasWarnedWebGL = true;
+    }
+    return;
+  }
+  occlusionSetupPromise = setupOcclusion(store);
+}
+async function setupOcclusion(store) {
+  const state = store.getState();
+  const { internal, rootScene, set } = state;
+  const tsl = await loadTSL();
+  if (!tsl) {
+    console.warn("[R3F] Warning: TSL module not available. Occlusion queries disabled.");
+    occlusionSetupPromise = null;
+    return;
+  }
+  const { uniform, nodeObject } = tsl;
+  let helperGroup = internal.helperGroup;
+  if (!helperGroup) {
+    helperGroup = new Group();
+    helperGroup.name = "__r3fInternal";
+    helperGroup.__r3fInternal = true;
+    rootScene.add(helperGroup);
+  }
+  const geometry = new BoxGeometry(1, 1, 1);
+  const material = new MeshBasicNodeMaterial({
+    transparent: true,
+    opacity: 0
+  });
+  const observerNode = nodeObject(createOcclusionObserverNode(store, uniform));
+  material.colorNode = observerNode;
+  material.needsUpdate = true;
+  const mesh = new Mesh(geometry, material);
+  mesh.name = "__r3fOcclusionObserver";
+  mesh.scale.setScalar(1e-4);
+  mesh.frustumCulled = false;
+  mesh.__r3fInternal = true;
+  helperGroup.add(mesh);
+  set((state2) => ({
+    internal: {
+      ...state2.internal,
+      helperGroup,
+      occlusionObserver: mesh,
+      occlusionEnabled: true
+    }
+  }));
+  occlusionSetupPromise = null;
+}
+function disableOcclusion(store) {
+  const { internal, set } = store.getState();
+  if (!internal.occlusionEnabled) return;
+  if (internal.occlusionObserver) {
+    internal.occlusionObserver.removeFromParent();
+    internal.occlusionObserver.geometry.dispose();
+    internal.occlusionObserver.material.dispose();
+  }
+  internal.occlusionCache.clear();
+  set((state) => ({
+    internal: {
+      ...state.internal,
+      occlusionObserver: null,
+      occlusionEnabled: false
+    }
+  }));
+}
+function cleanupHelperGroup(store) {
+  const { internal, set } = store.getState();
+  disableOcclusion(store);
+  if (internal.helperGroup) {
+    internal.helperGroup.removeFromParent();
+    set((state) => ({
+      internal: {
+        ...state.internal,
+        helperGroup: null
+      }
+    }));
+  }
+}
+function registerVisibility(store, object, handlers) {
+  const { internal } = store.getState();
+  const registry = internal.visibilityRegistry;
+  const entry = {
+    object,
+    handlers,
+    lastFramedState: null,
+    lastOccludedState: null,
+    lastVisibleState: null
+  };
+  registry.set(object.uuid, entry);
+  if (handlers.onOccluded || handlers.onVisible) {
+    object.occlusionTest = true;
+    if (!internal.occlusionEnabled) {
+      enableOcclusion(store);
+    }
+  }
+}
+function unregisterVisibility(store, object) {
+  const { internal } = store.getState();
+  internal.visibilityRegistry.delete(object.uuid);
+  internal.occlusionCache.delete(object);
+}
+function checkVisibility(state) {
+  const { internal, camera } = state;
+  const registry = internal.visibilityRegistry;
+  if (registry.size === 0) return;
+  updateFrustum(camera, tempFrustum);
+  for (const entry of registry.values()) {
+    const { object, handlers, lastFramedState, lastOccludedState, lastVisibleState } = entry;
+    let inFrustum = null;
+    const computeFrustum = () => {
+      if (inFrustum === null) {
+        if (object.geometry?.boundingSphere === null) {
+          object.geometry?.computeBoundingSphere();
+        }
+        inFrustum = tempFrustum.intersectsObject(object);
+      }
+      return inFrustum;
+    };
+    if (handlers.onFramed) {
+      const currentInFrustum = computeFrustum();
+      if (currentInFrustum !== lastFramedState) {
+        entry.lastFramedState = currentInFrustum;
+        handlers.onFramed(currentInFrustum);
+      }
+    }
+    let currentOcclusion = null;
+    if (handlers.onOccluded && internal.occlusionEnabled) {
+      currentOcclusion = internal.occlusionCache.get(object) ?? null;
+      if (currentOcclusion !== null && currentOcclusion !== lastOccludedState) {
+        entry.lastOccludedState = currentOcclusion;
+        handlers.onOccluded(currentOcclusion);
+      }
+    }
+    if (handlers.onVisible) {
+      const currentInFrustum = computeFrustum();
+      if (!handlers.onFramed && currentInFrustum !== lastFramedState) {
+        entry.lastFramedState = currentInFrustum;
+      }
+      let isOccluded = currentOcclusion;
+      if (isOccluded === null && internal.occlusionEnabled) {
+        isOccluded = internal.occlusionCache.get(object) ?? null;
+      }
+      if (isOccluded === null) isOccluded = false;
+      const isVisible = currentInFrustum && !isOccluded && object.visible;
+      if (isVisible !== lastVisibleState) {
+        entry.lastVisibleState = isVisible;
+        handlers.onVisible(isVisible);
+      }
+    }
+  }
+}
+function hasVisibilityHandlers(handlers) {
+  if (!handlers) return false;
+  return !!(handlers.onFramed || handlers.onOccluded || handlers.onVisible);
+}
+
 const RESERVED_PROPS = [
   "children",
   "key",
@@ -241,6 +450,7 @@ const RESERVED_PROPS = [
   "dispose"
 ];
 const EVENT_REGEX = /^on(Pointer|Drag|Drop|Click|DoubleClick|ContextMenu|Wheel)/;
+const VISIBILITY_EVENT_REGEX = /^on(Framed|Occluded|Visible)$/;
 const INDEX_REGEX = /-\d+$/;
 const MEMOIZED_PROTOTYPES = /* @__PURE__ */ new Map();
 const colorMaps = ["map", "emissiveMap", "sheenColorMap", "specularColorMap", "envMap"];
@@ -335,6 +545,12 @@ function applyProps(object, props) {
       instance.eventCount = Object.keys(instance.handlers).length;
       continue;
     }
+    if (instance && VISIBILITY_EVENT_REGEX.test(prop)) {
+      if (typeof value === "function") instance.handlers[prop] = value;
+      else delete instance.handlers[prop];
+      instance.eventCount = Object.keys(instance.handlers).length;
+      continue;
+    }
     if (value === void 0) continue;
     let { root, key, target } = resolve(object, prop);
     if (target === void 0 && (typeof root !== "object" || root === null)) {
@@ -371,6 +587,17 @@ function applyProps(object, props) {
     if (instance.eventCount && object2.raycast !== null) {
       rootState.internal.interaction.push(object2);
     }
+    const root = findInitialRoot(instance);
+    const visibilityHandlers = {
+      onFramed: instance.handlers.onFramed,
+      onOccluded: instance.handlers.onOccluded,
+      onVisible: instance.handlers.onVisible
+    };
+    if (hasVisibilityHandlers(visibilityHandlers)) {
+      registerVisibility(root, object2, visibilityHandlers);
+    } else {
+      unregisterVisibility(root, object2);
+    }
   }
   if (instance && instance.props.attach === void 0) {
     if (instance.object.isBufferGeometry) instance.props.attach = "geometry";
@@ -405,6 +632,7 @@ function removeInteractivity(store, object) {
   internal.capturedMap.forEach((captures, pointerId) => {
     releaseInternalPointerCapture(internal.capturedMap, object, captures, pointerId);
   });
+  unregisterVisibility(store, object);
 }
 function createEvents(store) {
   function calculateDistance(event) {
@@ -787,8 +1015,21 @@ function formatLocation(url, line) {
   const file = clean.split("/").pop() ?? clean;
   return `${file}:${line}`;
 }
+function notifyAlpha({ message, link }) {
+  if (typeof process !== "undefined" && (process.env.NODE_ENV === "test" || process.env.JEST_WORKER_ID !== void 0) && process.env.R3F_SHOW_ALPHA_WARNINGS !== "true") {
+    return;
+  }
+  if (shownNotices.has(message)) return;
+  shownNotices.add(message);
+  const boxStyle = "background: #6366f1; color: #ffffff; padding: 6px 10px; border-radius: 4px; font-weight: 500;";
+  console.log(`%c\u{1F52C} ${message}`, boxStyle);
+  {
+    console.log(`%cMore info: ${link}`, "color: #6366f1; font-weight: normal;");
+  }
+}
 
-const context = /* @__PURE__ */ React.createContext(null);
+const R3F_CONTEXT = Symbol.for("@react-three/fiber.context");
+const context = globalThis[R3F_CONTEXT] ?? (globalThis[R3F_CONTEXT] = React.createContext(null));
 const createStore = (invalidate, advance) => {
   const rootStore = createWithEqualityFn((set, get) => {
     const position = new Vector3();
@@ -819,6 +1060,8 @@ const createStore = (invalidate, advance) => {
       gl: null,
       renderer: null,
       camera: null,
+      frustum: new Frustum(),
+      autoUpdateFrustum: true,
       raycaster: null,
       events: { priority: 1, enabled: true, connected: false },
       scene: null,
@@ -900,6 +1143,13 @@ const createStore = (invalidate, advance) => {
         initialHits: [],
         capturedMap: /* @__PURE__ */ new Map(),
         lastEvent: React.createRef(),
+        // Visibility tracking (onFramed, onOccluded, onVisible)
+        visibilityRegistry: /* @__PURE__ */ new Map(),
+        // Occlusion system (WebGPU only)
+        occlusionEnabled: false,
+        occlusionObserver: null,
+        occlusionCache: /* @__PURE__ */ new Map(),
+        helperGroup: null,
         // Updates
         active: false,
         frames: 0,
@@ -985,7 +1235,15 @@ const createStore = (invalidate, advance) => {
     }
     if (camera !== oldCamera) {
       oldCamera = camera;
+      const { rootScene } = rootStore.getState();
+      if (camera && rootScene && !camera.parent) {
+        rootScene.add(camera);
+      }
       set((state2) => ({ viewport: { ...state2.viewport, ...state2.viewport.getCurrentViewport(camera) } }));
+      const currentState = rootStore.getState();
+      if (currentState.autoUpdateFrustum && camera) {
+        updateFrustum(camera, currentState.frustum);
+      }
     }
   });
   rootStore.subscribe((state2) => invalidate(state2));
@@ -1349,6 +1607,10 @@ const _Scheduler = class _Scheduler {
     __publicField(this, "jobStateListeners", /* @__PURE__ */ new Map());
     __publicField(this, "pendingFrames", 0);
     __publicField(this, "_frameloop", "always");
+    //* Independent Mode & Error Handling State ================================
+    __publicField(this, "_independent", false);
+    __publicField(this, "errorHandler", null);
+    __publicField(this, "rootReadyCallbacks", /* @__PURE__ */ new Set());
     //* Core Loop Execution Methods ================================
     /**
      * Main RAF loop callback.
@@ -1371,6 +1633,12 @@ const _Scheduler = class _Scheduler {
     });
     this.phaseGraph = new PhaseGraph();
   }
+  static get instance() {
+    return globalThis[_Scheduler.INSTANCE_KEY] ?? null;
+  }
+  static set instance(value) {
+    globalThis[_Scheduler.INSTANCE_KEY] = value;
+  }
   /**
    * Get the global scheduler instance (creates if doesn't exist).
    * Uses HMR data to preserve instance across hot reloads.
@@ -1419,29 +1687,43 @@ const _Scheduler = class _Scheduler {
   get isRunning() {
     return this.loopState.running;
   }
+  get isReady() {
+    return this.roots.size > 0;
+  }
+  get independent() {
+    return this._independent;
+  }
+  set independent(value) {
+    this._independent = value;
+    if (value) this.ensureDefaultRoot();
+  }
   //* Root Management Methods ================================
   /**
    * 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, getState) {
+  registerRoot(id, options = {}) {
     if (this.roots.has(id)) {
       console.warn(`[Scheduler] Root "${id}" already registered`);
       return () => this.unregisterRoot(id);
     }
     const entry = {
       id,
-      getState,
+      getState: options.getState ?? (() => ({})),
       jobs: /* @__PURE__ */ new Map(),
       sortedJobs: [],
       needsRebuild: false
     };
+    if (options.onError) {
+      this.errorHandler = options.onError;
+    }
     this.roots.set(id, entry);
-    if (this.roots.size === 1 && this._frameloop === "always") {
-      this.start();
+    if (this.roots.size === 1) {
+      this.notifyRootReady();
+      if (this._frameloop === "always") this.start();
     }
     return () => this.unregisterRoot(id);
   }
@@ -1461,8 +1743,61 @@ const _Scheduler = class _Scheduler {
     this.roots.delete(id);
     if (this.roots.size === 0) {
       this.stop();
+      this.errorHandler = null;
     }
   }
+  /**
+   * 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) {
+    if (this.roots.size > 0) {
+      callback();
+      return () => {
+      };
+    }
+    this.rootReadyCallbacks.add(callback);
+    return () => this.rootReadyCallbacks.delete(callback);
+  }
+  /**
+   * Notify all registered root-ready callbacks.
+   * Called when the first root registers.
+   * @returns {void}
+   * @private
+   */
+  notifyRootReady() {
+    for (const cb of this.rootReadyCallbacks) {
+      try {
+        cb();
+      } catch (error) {
+        console.error("[Scheduler] Error in root-ready callback:", error);
+      }
+    }
+    this.rootReadyCallbacks.clear();
+  }
+  /**
+   * Ensure a default root exists for independent mode.
+   * Creates a minimal root with no state provider.
+   * @returns {void}
+   * @private
+   */
+  ensureDefaultRoot() {
+    if (!this.roots.has("__default__")) {
+      this.registerRoot("__default__");
+    }
+  }
+  /**
+   * 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) {
+    if (this.errorHandler) this.errorHandler(error);
+    else console.error("[Scheduler]", error);
+  }
   //* Phase Management Methods ================================
   /**
    * Add a named phase to the scheduler's execution order.
@@ -1821,9 +2156,9 @@ const _Scheduler = class _Scheduler {
     const deltaMs = this.loopState.lastTime !== null ? now - this.loopState.lastTime : 0;
     const delta = deltaMs / 1e3;
     const elapsed = now - this.loopState.createdAt;
-    const rootState = root.getState();
+    const providedState = root.getState?.() ?? {};
     const frameState = {
-      ...rootState,
+      ...providedState,
       time: now,
       delta,
       elapsed,
@@ -1833,6 +2168,7 @@ const _Scheduler = class _Scheduler {
       job.callback(frameState, delta);
     } catch (error) {
       console.error(`[Scheduler] Error in job "${job.id}":`, error);
+      this.triggerError(error instanceof Error ? error : new Error(String(error)));
     }
   }
   /**
@@ -1874,7 +2210,7 @@ const _Scheduler = 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
@@ -1886,10 +2222,9 @@ const _Scheduler = class _Scheduler {
       root.sortedJobs = rebuildSortedJobs(root.jobs, this.phaseGraph);
       root.needsRebuild = false;
     }
-    const rootState = root.getState();
-    if (!rootState) return;
+    const providedState = root.getState?.() ?? {};
     const frameState = {
-      ...rootState,
+      ...providedState,
       time: timestamp,
       delta,
       elapsed: this.loopState.elapsedTime / 1e3,
@@ -1902,7 +2237,7 @@ const _Scheduler = class _Scheduler {
         job.callback(frameState, delta);
       } catch (error) {
         console.error(`[Scheduler] Error in job "${job.id}":`, error);
-        rootState.setError(error instanceof Error ? error : new Error(String(error)));
+        this.triggerError(error instanceof Error ? error : new Error(String(error)));
       }
     }
   }
@@ -1987,8 +2322,11 @@ const _Scheduler = class _Scheduler {
     return /* @__PURE__ */ new Set([value]);
   }
 };
-//* Static State & Methods (Singlton Usage) ================================
-__publicField(_Scheduler, "instance", null);
+//* Static State & Methods (Singleton Usage) ================================
+//* Cross-Bundle Singleton Key ==============================
+// Use Symbol.for() to ensure scheduler is shared across bundle boundaries
+// This prevents issues when mixing imports from @react-three/fiber and @react-three/fiber/webgpu
+__publicField(_Scheduler, "INSTANCE_KEY", Symbol.for("@react-three/fiber.scheduler"));
 let Scheduler = _Scheduler;
 const getScheduler = () => Scheduler.get();
 if (hmrData) {
@@ -1996,11 +2334,9 @@ if (hmrData) {
 }
 
 function useFrame(callback, priorityOrOptions) {
-  const store = useStore();
-  const getRootId = React.useCallback(() => {
-    const state = store.getState();
-    return state.internal.rootId;
-  }, [store]);
+  const store = React.useContext(context);
+  const isInsideCanvas = store !== null;
+  const scheduler = getScheduler();
   const optionsKey = typeof priorityOrOptions === "number" ? `p:${priorityOrOptions}` : priorityOrOptions ? JSON.stringify({
     id: priorityOrOptions.id,
     phase: priorityOrOptions.phase,
@@ -2020,55 +2356,71 @@ function useFrame(callback, priorityOrOptions) {
   const isLegacyPriority = typeof priorityOrOptions === "number" && priorityOrOptions > 0;
   useIsomorphicLayoutEffect(() => {
     if (!callback) return;
-    const scheduler = getScheduler();
-    const rootId = getRootId();
-    const state = store.getState();
-    if (isLegacyPriority) {
-      state.internal.priority++;
-      let parentRoot = state.previousRoot;
-      while (parentRoot) {
-        const parentState = parentRoot.getState();
-        if (parentState?.internal) parentState.internal.priority++;
-        parentRoot = parentState?.previousRoot;
-      }
-      notifyDepreciated({
-        heading: "useFrame with numeric priority is deprecated",
-        body: 'Using useFrame(callback, number) to control render order is deprecated.\n\nFor custom rendering, use: useFrame(callback, { phase: "render" })\nFor execution order within update phase, use: useFrame(callback, { priority: number })',
-        link: "https://docs.pmnd.rs/react-three-fiber/api/hooks#useframe"
-      });
-    }
-    const wrappedCallback = (frameState, delta) => {
-      const localState = store.getState();
-      const mergedState = {
-        ...localState,
-        time: frameState.time,
-        delta: frameState.delta,
-        elapsed: frameState.elapsed,
-        frame: frameState.frame
-      };
-      callbackRef.current?.(mergedState, delta);
-    };
-    const unregister = scheduler.register(wrappedCallback, {
-      id,
-      rootId,
-      ...options
-    });
-    return () => {
-      unregister();
+    if (isInsideCanvas) {
+      const state = store.getState();
+      const rootId = state.internal.rootId;
       if (isLegacyPriority) {
-        const currentState = store.getState();
-        if (currentState.internal) {
-          currentState.internal.priority--;
-          let parentRoot = currentState.previousRoot;
-          while (parentRoot) {
-            const parentState = parentRoot.getState();
-            if (parentState?.internal) parentState.internal.priority--;
-            parentRoot = parentState?.previousRoot;
+        state.internal.priority++;
+        let parentRoot = state.previousRoot;
+        while (parentRoot) {
+          const parentState = parentRoot.getState();
+          if (parentState?.internal) parentState.internal.priority++;
+          parentRoot = parentState?.previousRoot;
+        }
+        notifyDepreciated({
+          heading: "useFrame with numeric priority is deprecated",
+          body: 'Using useFrame(callback, number) to control render order is deprecated.\n\nFor custom rendering, use: useFrame(callback, { phase: "render" })\nFor execution order within update phase, use: useFrame(callback, { priority: number })',
+          link: "https://docs.pmnd.rs/react-three-fiber/api/hooks#useframe"
+        });
+      }
+      const wrappedCallback = (frameState, delta) => {
+        const localState = store.getState();
+        const mergedState = {
+          ...localState,
+          time: frameState.time,
+          delta: frameState.delta,
+          elapsed: frameState.elapsed,
+          frame: frameState.frame
+        };
+        callbackRef.current?.(mergedState, delta);
+      };
+      const unregister = scheduler.register(wrappedCallback, {
+        id,
+        rootId,
+        ...options
+      });
+      return () => {
+        unregister();
+        if (isLegacyPriority) {
+          const currentState = store.getState();
+          if (currentState.internal) {
+            currentState.internal.priority--;
+            let parentRoot = currentState.previousRoot;
+            while (parentRoot) {
+              const parentState = parentRoot.getState();
+              if (parentState?.internal) parentState.internal.priority--;
+              parentRoot = parentState?.previousRoot;
+            }
           }
         }
+      };
+    } else {
+      const registerOutside = () => {
+        return scheduler.register((state, delta) => callbackRef.current?.(state, delta), { id, ...options });
+      };
+      if (scheduler.independent || scheduler.isReady) {
+        return registerOutside();
       }
-    };
-  }, [store, id, optionsKey, isLegacyPriority]);
+      let unregisterJob = null;
+      const unsubReady = scheduler.onRootReady(() => {
+        unregisterJob = registerOutside();
+      });
+      return () => {
+        unsubReady();
+        unregisterJob?.();
+      };
+    }
+  }, [store, scheduler, id, optionsKey, isLegacyPriority, isInsideCanvas]);
   const isPaused = React.useSyncExternalStore(
     // Subscribe function
     React.useCallback(
@@ -2083,7 +2435,7 @@ function useFrame(callback, priorityOrOptions) {
     React.useCallback(() => false, [])
   );
   const controls = React.useMemo(() => {
-    const scheduler = getScheduler();
+    const scheduler2 = getScheduler();
     return {
       /** The job's unique ID */
       id,
@@ -2091,7 +2443,7 @@ function useFrame(callback, priorityOrOptions) {
        * Access to the global scheduler for frame loop control.
        * Use for controlling the entire frame loop, adding phases, etc.
        */
-      scheduler,
+      scheduler: scheduler2,
       /**
        * Manually step this job only.
        * Bypasses FPS limiting - always runs.
@@ -2339,6 +2691,16 @@ function useTextures() {
   }, [store]);
 }
 
+function useRenderTarget(width, height, options) {
+  const isLegacy = useThree((s) => s.isLegacy);
+  const size = useThree((s) => s.size);
+  return useMemo(() => {
+    const w = width ?? size.width;
+    const h = height ?? size.height;
+    return new WebGLRenderTarget(w, h, options);
+  }, [width, height, size.width, size.height, options, isLegacy]);
+}
+
 function useStore() {
   const store = useContext(context);
   if (!store) throw new Error("R3F: Hooks can only be used within the Canvas component!");
@@ -2390,7 +2752,7 @@ function advance(timestamp, runGlobalEffects = true, state, frame) {
   getScheduler().step(timestamp);
 }
 
-const version = "10.0.0-alpha.0";
+const version = "10.0.0-alpha.1";
 const packageData = {
 	version: version};
 
@@ -13691,7 +14053,8 @@ function createReconciler(config) {
   return reconciler2;
 }
 const NoEventPriority = 0;
-const catalogue = {};
+const R3F_CATALOGUE = Symbol.for("@react-three/fiber.catalogue");
+const catalogue = globalThis[R3F_CATALOGUE] ?? (globalThis[R3F_CATALOGUE] = {});
 const PREFIX_REGEX = /^three(?=[A-Z])/;
 const toPascalCase = (type) => `${type[0].toUpperCase()}${type.slice(1)}`;
 let i = 0;
@@ -14189,7 +14552,9 @@ function createRoot(canvas) {
         camera: cameraOptions,
         onPointerMissed,
         onDragOverMissed,
-        onDropMissed
+        onDropMissed,
+        autoUpdateFrustum = true,
+        occlusion = false
       } = props;
       let state = store.getState();
       const defaultGLProps = {
@@ -14255,6 +14620,8 @@ function createRoot(canvas) {
           rootScene: scene,
           internal: { ...prev.internal, container: scene }
         }));
+        const camera = state.camera;
+        if (camera && !camera.parent) scene.add(camera);
       }
       if (events && !state.events.handlers) {
         state.set({ events: events(store) });
@@ -14282,6 +14649,10 @@ function createRoot(canvas) {
       if (!state.onPointerMissed) state.set({ onPointerMissed });
       if (!state.onDragOverMissed) state.set({ onDragOverMissed });
       if (!state.onDropMissed) state.set({ onDropMissed });
+      if (state.autoUpdateFrustum !== autoUpdateFrustum) state.set({ autoUpdateFrustum });
+      if (occlusion && !state.internal.occlusionEnabled) {
+        enableOcclusion(store);
+      }
       if (performance && !is.equ(performance, lastConfiguredProps.performance, shallowLoose)) {
         state.set((state2) => ({ performance: { ...state2.performance, ...performance } }));
         lastConfiguredProps.performance = performance;
@@ -14374,7 +14745,37 @@ function createRoot(canvas) {
       const rootId = state.internal.rootId;
       if (!rootId) {
         const newRootId = scheduler.generateRootId();
-        const unregisterRoot = scheduler.registerRoot(newRootId, () => store.getState());
+        const unregisterRoot = scheduler.registerRoot(newRootId, {
+          getState: () => store.getState(),
+          onError: (err) => store.getState().setError(err)
+        });
+        const unregisterFrustum = scheduler.register(
+          () => {
+            const state2 = store.getState();
+            if (state2.autoUpdateFrustum && state2.camera) {
+              updateFrustum(state2.camera, state2.frustum);
+            }
+          },
+          {
+            id: `${newRootId}_frustum`,
+            rootId: newRootId,
+            phase: "preRender",
+            system: true
+          }
+        );
+        const unregisterVisibility = scheduler.register(
+          () => {
+            const state2 = store.getState();
+            checkVisibility(state2);
+          },
+          {
+            id: `${newRootId}_visibility`,
+            rootId: newRootId,
+            phase: "preRender",
+            system: true,
+            after: `${newRootId}_frustum`
+          }
+        );
         const unregisterRender = scheduler.register(
           () => {
             const state2 = store.getState();
@@ -14402,6 +14803,8 @@ function createRoot(canvas) {
             rootId: newRootId,
             unregisterRoot: () => {
               unregisterRoot();
+              unregisterFrustum();
+              unregisterVisibility();
               unregisterRender();
             },
             scheduler
@@ -14459,6 +14862,7 @@ function unmountComponentAtNode(canvas, callback) {
             const unregisterRoot = state.internal.unregisterRoot;
             if (unregisterRoot) unregisterRoot();
             state.events.disconnect?.();
+            cleanupHelperGroup(root.store);
             renderer?.renderLists?.dispose?.();
             renderer?.forceContextLoss?.();
             if (renderer?.xr) state.xr.disconnect();
@@ -14638,7 +15042,22 @@ function CanvasImpl({
     effectActiveRef.current = true;
     const canvas = canvasRef.current;
     if (containerRect.width > 0 && containerRect.height > 0 && canvas) {
-      if (!root.current) root.current = createRoot(canvas);
+      if (!root.current) {
+        root.current = createRoot(canvas);
+        notifyAlpha({
+          message: "React Three Fiber v10 is in ALPHA - expect breaking changes",
+          link: "https://github.com/pmndrs/react-three-fiber/discussions"
+        });
+        const rootEntry = _roots.get(canvas);
+        if (rootEntry?.store) {
+          if (unsubscribeErrorRef.current) unsubscribeErrorRef.current();
+          unsubscribeErrorRef.current = rootEntry.store.subscribe((state) => {
+            if (state.error && effectActiveRef.current) {
+              setError(state.error);
+            }
+          });
+        }
+      }
       async function run() {
         if (!effectActiveRef.current || !root.current) return;
         await root.current.configure({
@@ -14679,15 +15098,9 @@ function CanvasImpl({
           }
         });
         if (!effectActiveRef.current || !root.current) return;
-        const store = root.current.render(
+        root.current.render(
           /* @__PURE__ */ jsx(Bridge, { children: /* @__PURE__ */ jsx(ErrorBoundary, { set: setError, children: /* @__PURE__ */ jsx(React.Suspense, { fallback: /* @__PURE__ */ jsx(Block, { set: setBlock }), children: children ?? null }) }) })
         );
-        if (unsubscribeErrorRef.current) unsubscribeErrorRef.current();
-        unsubscribeErrorRef.current = store.subscribe((state) => {
-          if (state.error && effectActiveRef.current) {
-            setError(state.error);
-          }
-        });
       }
       run();
     }
@@ -14732,4 +15145,4 @@ function Canvas(props) {
 
 extend(THREE);
 
-export { Block, Canvas, ErrorBoundary, IsObject, R3F_BUILD_LEGACY, R3F_BUILD_WEBGPU, REACT_INTERNAL_PROPS, RESERVED_PROPS, 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 { Block, Canvas, ErrorBoundary, IsObject, R3F_BUILD_LEGACY, R3F_BUILD_WEBGPU, REACT_INTERNAL_PROPS, RESERVED_PROPS, 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 };