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

package/dist/index.cjs

@@ -51,6 +51,8 @@ const THREE = /*#__PURE__*/_mergeNamespaces({
   Inspector: Inspector_js.Inspector,
   R3F_BUILD_LEGACY: R3F_BUILD_LEGACY,
   R3F_BUILD_WEBGPU: R3F_BUILD_WEBGPU,
+  RenderTargetCompat: webgpu.RenderTarget,
+  WebGLRenderTarget: three.WebGLRenderTarget,
   WebGLRenderer: three.WebGLRenderer
 }, [webgpu__namespace]);
 
@@ -159,6 +161,13 @@ function updateCamera(camera, size) {
   }
   camera.updateProjectionMatrix();
 }
+const frustumMatrix = new webgpu.Matrix4();
+function updateFrustum(camera, frustum) {
+  const target = frustum ?? new webgpu.Frustum();
+  frustumMatrix.multiplyMatrices(camera.projectionMatrix, camera.matrixWorldInverse);
+  target.setFromProjectionMatrix(frustumMatrix);
+  return target;
+}
 
 const REACT_INTERNAL_PROPS = ["children", "key", "ref"];
 function findInitialRoot(instance) {
@@ -239,6 +248,205 @@ function invalidateInstance(instance) {
   if (state && state.internal.frames === 0) state.invalidate();
 }
 
+const tempFrustum = new webgpu.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 webgpu.Node("float");
+  node.updateType = webgpu.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 webgpu.Group();
+    helperGroup.name = "__r3fInternal";
+    helperGroup.__r3fInternal = true;
+    rootScene.add(helperGroup);
+  }
+  const geometry = new webgpu.BoxGeometry(1, 1, 1);
+  const material = new webgpu.MeshBasicNodeMaterial({
+    transparent: true,
+    opacity: 0
+  });
+  const observerNode = nodeObject(createOcclusionObserverNode(store, uniform));
+  material.colorNode = observerNode;
+  material.needsUpdate = true;
+  const mesh = new webgpu.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",
@@ -253,6 +461,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"];
@@ -347,6 +556,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)) {
@@ -383,6 +598,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";
@@ -417,6 +643,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) {
@@ -799,8 +1026,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__namespace.createContext(null);
+const R3F_CONTEXT = Symbol.for("@react-three/fiber.context");
+const context = globalThis[R3F_CONTEXT] ?? (globalThis[R3F_CONTEXT] = React__namespace.createContext(null));
 const createStore = (invalidate, advance) => {
   const rootStore = traditional.createWithEqualityFn((set, get) => {
     const position = new webgpu.Vector3();
@@ -831,6 +1071,8 @@ const createStore = (invalidate, advance) => {
       gl: null,
       renderer: null,
       camera: null,
+      frustum: new webgpu.Frustum(),
+      autoUpdateFrustum: true,
       raycaster: null,
       events: { priority: 1, enabled: true, connected: false },
       scene: null,
@@ -912,6 +1154,13 @@ const createStore = (invalidate, advance) => {
         initialHits: [],
         capturedMap: /* @__PURE__ */ new Map(),
         lastEvent: React__namespace.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,
@@ -997,7 +1246,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));
@@ -1361,6 +1618,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.
@@ -1383,6 +1644,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.
@@ -1431,29 +1698,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);
   }
@@ -1473,8 +1754,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.
@@ -1833,9 +2167,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,
@@ -1845,6 +2179,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)));
     }
   }
   /**
@@ -1886,7 +2221,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
@@ -1898,10 +2233,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,
@@ -1914,7 +2248,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)));
       }
     }
   }
@@ -1999,8 +2333,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) {
@@ -2008,11 +2345,9 @@ if (hmrData) {
 }
 
 function useFrame(callback, priorityOrOptions) {
-  const store = useStore();
-  const getRootId = React__namespace.useCallback(() => {
-    const state = store.getState();
-    return state.internal.rootId;
-  }, [store]);
+  const store = React__namespace.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,
@@ -2032,55 +2367,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__namespace.useSyncExternalStore(
     // Subscribe function
     React__namespace.useCallback(
@@ -2095,7 +2446,7 @@ function useFrame(callback, priorityOrOptions) {
     React__namespace.useCallback(() => false, [])
   );
   const controls = React__namespace.useMemo(() => {
-    const scheduler = getScheduler();
+    const scheduler2 = getScheduler();
     return {
       /** The job's unique ID */
       id,
@@ -2103,7 +2454,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.
@@ -2351,6 +2702,18 @@ function useTextures() {
   }, [store]);
 }
 
+function useRenderTarget(width, height, options) {
+  const isLegacy = useThree((s) => s.isLegacy);
+  const size = useThree((s) => s.size);
+  return React.useMemo(() => {
+    const w = width ?? size.width;
+    const h = height ?? size.height;
+    {
+      return isLegacy ? new three.WebGLRenderTarget(w, h, options) : new webgpu.RenderTarget(w, h, options);
+    }
+  }, [width, height, size.width, size.height, options, isLegacy]);
+}
+
 function useStore() {
   const store = React.useContext(context);
   if (!store) throw new Error("R3F: Hooks can only be used within the Canvas component!");
@@ -2402,7 +2765,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};
 
@@ -13703,7 +14066,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;
@@ -14201,7 +14565,9 @@ function createRoot(canvas) {
         camera: cameraOptions,
         onPointerMissed,
         onDragOverMissed,
-        onDropMissed
+        onDropMissed,
+        autoUpdateFrustum = true,
+        occlusion = false
       } = props;
       let state = store.getState();
       const defaultGLProps = {
@@ -14231,7 +14597,9 @@ function createRoot(canvas) {
         state.set({ isLegacy: true, gl: renderer, renderer });
       } else if (!wantsGL && !state.internal.actualRenderer) {
         renderer = await resolveRenderer(rendererConfig, defaultGPUProps, webgpu.WebGPURenderer);
-        await renderer.init();
+        if (!renderer.hasInitialized?.()) {
+          await renderer.init();
+        }
         const backend = renderer.backend;
         const isWebGPUBackend = backend && "isWebGPUBackend" in backend;
         state.internal.actualRenderer = renderer;
@@ -14279,6 +14647,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) });
@@ -14306,6 +14676,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;
@@ -14406,7 +14780,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();
@@ -14434,6 +14838,8 @@ function createRoot(canvas) {
             rootId: newRootId,
             unregisterRoot: () => {
               unregisterRoot();
+              unregisterFrustum();
+              unregisterVisibility();
               unregisterRender();
             },
             scheduler
@@ -14491,6 +14897,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();
@@ -14670,7 +15077,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({
@@ -14711,15 +15133,9 @@ function CanvasImpl({
           }
         });
         if (!effectActiveRef.current || !root.current) return;
-        const store = root.current.render(
+        root.current.render(
           /* @__PURE__ */ jsxRuntime.jsx(Bridge, { children: /* @__PURE__ */ jsxRuntime.jsx(ErrorBoundary, { set: setError, children: /* @__PURE__ */ jsxRuntime.jsx(React__namespace.Suspense, { fallback: /* @__PURE__ */ jsxRuntime.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();
     }
@@ -14819,6 +15235,7 @@ exports.removeInteractivity = removeInteractivity;
 exports.resolve = resolve;
 exports.unmountComponentAtNode = unmountComponentAtNode;
 exports.updateCamera = updateCamera;
+exports.updateFrustum = updateFrustum;
 exports.useBridge = useBridge;
 exports.useFrame = useFrame;
 exports.useGraph = useGraph;
@@ -14826,6 +15243,7 @@ exports.useInstanceHandle = useInstanceHandle;
 exports.useIsomorphicLayoutEffect = useIsomorphicLayoutEffect;
 exports.useLoader = useLoader;
 exports.useMutableCallback = useMutableCallback;
+exports.useRenderTarget = useRenderTarget;
 exports.useStore = useStore;
 exports.useTexture = useTexture;
 exports.useTextures = useTextures;