@react-three/fiber 8.2.0 → 9.0.0-alpha.0

package/dist/declarations/src/web/Canvas.d.ts

@@ -1,9 +1,9 @@
-import * as React from 'react';
-import type { Options as ResizeOptions } from 'react-use-measure';
-import { RenderProps } from '../core';
-export interface Props extends Omit<RenderProps<HTMLCanvasElement>, 'size'>, React.HTMLAttributes<HTMLDivElement> {
-    children: React.ReactNode;
-    fallback?: React.ReactNode;
-    resize?: ResizeOptions;
-}
-export declare const Canvas: React.ForwardRefExoticComponent<Props & React.RefAttributes<HTMLCanvasElement>>;
+import * as React from 'react';
+import type { Options as ResizeOptions } from 'react-use-measure';
+import { RenderProps } from '../core';
+export interface Props extends Omit<RenderProps<HTMLCanvasElement>, 'size'>, React.HTMLAttributes<HTMLDivElement> {
+    children: React.ReactNode;
+    fallback?: React.ReactNode;
+    resize?: ResizeOptions;
+}
+export declare const Canvas: React.ForwardRefExoticComponent<Props & React.RefAttributes<HTMLCanvasElement>>;

package/dist/declarations/src/web/events.d.ts

@@ -1,4 +1,4 @@
-import { UseBoundStore } from 'zustand';
-import { RootState } from '../core/store';
-import { EventManager } from '../core/events';
-export declare function createPointerEvents(store: UseBoundStore<RootState>): EventManager<HTMLElement>;
+import { UseBoundStore } from 'zustand';
+import { RootState } from '../core/store';
+import { EventManager } from '../core/events';
+export declare function createPointerEvents(store: UseBoundStore<RootState>): EventManager<HTMLElement>;

package/dist/{index-ca47b633.cjs.prod.js → index-b12f488b.cjs.prod.js}

@@ -37,12 +37,19 @@ var threeTypes = /*#__PURE__*/Object.freeze({
   __proto__: null
 });
 
-const isOrthographicCamera = def => def && def.isOrthographicCamera; // React currently throws a warning when using useLayoutEffect on the server.
-// To get around it, we can conditionally useEffect on the server (no-op) and
-// useLayoutEffect on the client.
+var _window$document, _window$navigator;
+const isOrthographicCamera = def => def && def.isOrthographicCamera;
+/**
+ * An SSR-friendly useLayoutEffect.
+ *
+ * React currently throws a warning when using useLayoutEffect on the server.
+ * To get around it, we can conditionally useEffect on the server (no-op) and
+ * useLayoutEffect elsewhere.
+ *
+ * @see https://github.com/facebook/react/issues/14927
+ */
 
-const isSSR = typeof window === 'undefined' || !window.navigator || /ServerSideRendering|^Deno\//.test(window.navigator.userAgent);
-const useIsomorphicLayoutEffect = isSSR ? React__namespace.useEffect : React__namespace.useLayoutEffect;
+const useIsomorphicLayoutEffect = typeof window !== 'undefined' && ((_window$document = window.document) != null && _window$document.createElement || ((_window$navigator = window.navigator) == null ? void 0 : _window$navigator.product) === 'ReactNative') ? React__namespace.useLayoutEffect : React__namespace.useEffect;
 function useMutableCallback(fn) {
   const ref = React__namespace.useRef(fn);
   useIsomorphicLayoutEffect(() => void (ref.current = fn), [fn]);
@@ -358,12 +365,7 @@ function applyProps$1(instance, data) {
 
         if (!isColor && targetProp.setScalar) targetProp.setScalar(value); // Layers have no copy function, we must therefore copy the mask property
         else if (targetProp instanceof THREE__namespace.Layers && value instanceof THREE__namespace.Layers) targetProp.mask = value.mask; // Otherwise just set ...
-        else targetProp.set(value); // For versions of three which don't support THREE.ColorManagement,
-        // Auto-convert sRGB colors
-        // https://github.com/pmndrs/react-three-fiber/issues/344
-
-        const supportsColorManagement = ('ColorManagement' in THREE__namespace);
-        if (!supportsColorManagement && !rootState.linear && isColor) targetProp.convertSRGBToLinear();
+        else targetProp.set(value);
       } // Else, just overwrite the value
 
     } else {
@@ -418,15 +420,6 @@ function updateCamera(camera, size) {
     camera.updateMatrixWorld();
   }
 }
-/**
- * Safely sets a deeply-nested value on an object.
- */
-
-function setDeep(obj, value, keys) {
-  const key = keys.pop();
-  const target = keys.reduce((acc, key) => acc[key], obj);
-  return target[key] = value;
-}
 
 function makeId(event) {
   return (event.eventObject || event.object).uuid + '/' + event.index + event.instanceId;
@@ -1063,7 +1056,10 @@ function createRenderer(_roots, _getEventPriority) {
         }
       }
     });
-  }
+  } // Don't handle text instances, warn on undefined behavior
+
+
+  const handleTextInstance = () => console.warn('Text is not allowed in the R3F tree! This could be stray whitespace or characters.');
 
   const reconciler = Reconciler__default["default"]({
     createInstance,
@@ -1077,13 +1073,20 @@ function createRenderer(_roots, _getEventPriority) {
     supportsHydration: false,
     noTimeout: -1,
     appendChildToContainer: (container, child) => {
+      if (!child) return;
       const scene = container.getState().scene; // Link current root to the default scene
 
       scene.__r3f.root = container;
       appendChild(scene, child);
     },
-    removeChildFromContainer: (container, child) => removeChild(container.getState().scene, child),
-    insertInContainerBefore: (container, child, beforeChild) => insertBefore(container.getState().scene, child, beforeChild),
+    removeChildFromContainer: (container, child) => {
+      if (!child) return;
+      removeChild(container.getState().scene, child);
+    },
+    insertInContainerBefore: (container, child, beforeChild) => {
+      if (!child || !beforeChild) return;
+      insertBefore(container.getState().scene, child, beforeChild);
+    },
     getRootHostContext: () => null,
     getChildHostContext: parentHostContext => parentHostContext,
 
@@ -1175,13 +1178,9 @@ function createRenderer(_roots, _getEventPriority) {
       invalidateInstance(instance);
     },
 
-    createTextInstance: () => {
-      throw new Error('Text is not allowed in the R3F tree.');
-    },
-    hideTextInstance: () => {
-      throw new Error('Text is not allowed in the R3F tree.');
-    },
-    unhideTextInstance: () => {},
+    createTextInstance: handleTextInstance,
+    hideTextInstance: handleTextInstance,
+    unhideTextInstance: handleTextInstance,
     // https://github.com/pmndrs/react-three-fiber/pull/2360#discussion_r916356874
     // @ts-ignore
     getCurrentEventPriority: () => _getEventPriority ? _getEventPriority() : constants.DefaultEventPriority,
@@ -1199,6 +1198,7 @@ function createRenderer(_roots, _getEventPriority) {
   };
 }
 
+// Keys that shouldn't be copied between R3F stores
 const privateKeys = ['set', 'get', 'setSize', 'setFrameloop', 'setDpr', 'events', 'invalidate', 'advance', 'size', 'viewport'];
 const isRenderer = def => !!(def != null && def.render);
 const context = /*#__PURE__*/React__namespace.createContext(null);
@@ -1346,8 +1346,14 @@ const createStore = (invalidate, advance) => {
           }
         };
       }),
-      setFrameloop: (frameloop = 'always') => {
-        const clock = get().clock; // if frameloop === "never" clock.elapsedTime is updated using advance(timestamp)
+      setFrameloop: frameloop => {
+        var _frameloop$mode, _frameloop$render, _frameloop$maxDelta;
+
+        const state = get();
+        const mode = typeof frameloop === 'string' ? frameloop : (frameloop == null ? void 0 : frameloop.mode) === 'auto' ? 'always' : (_frameloop$mode = frameloop == null ? void 0 : frameloop.mode) != null ? _frameloop$mode : state.frameloop;
+        const render = typeof frameloop === 'string' ? state.internal.render : (_frameloop$render = frameloop == null ? void 0 : frameloop.render) != null ? _frameloop$render : state.internal.render;
+        const maxDelta = typeof frameloop === 'string' ? state.internal.maxDelta : (_frameloop$maxDelta = frameloop == null ? void 0 : frameloop.maxDelta) != null ? _frameloop$maxDelta : state.internal.maxDelta;
+        const clock = state.clock; // if frameloop === "never" clock.elapsedTime is updated using advance(timestamp)
 
         clock.stop();
         clock.elapsedTime = 0;
@@ -1358,28 +1364,44 @@ const createStore = (invalidate, advance) => {
         }
 
         set(() => ({
-          frameloop
+          frameloop: mode,
+          internal: { ...state.internal,
+            render,
+            maxDelta
+          }
         }));
       },
       previousRoot: undefined,
       internal: {
-        active: false,
-        priority: 0,
-        frames: 0,
-        lastEvent: /*#__PURE__*/React__namespace.createRef(),
+        // Events
         interaction: [],
         hovered: new Map(),
         subscribers: [],
         initialClick: [0, 0],
         initialHits: [],
         capturedMap: new Map(),
+        lastEvent: /*#__PURE__*/React__namespace.createRef(),
+        // Updates
+        active: false,
+        frames: 0,
+        stages: [],
+        render: 'auto',
+        maxDelta: 1 / 10,
+        priority: 0,
         subscribe: (ref, priority, store) => {
-          const internal = get().internal; // If this subscription was given a priority, it takes rendering into its own hands
+          const state = get();
+          const internal = state.internal; // If this subscription was given a priority, it takes rendering into its own hands
           // For that reason we switch off automatic rendering and increase the manual flag
           // As long as this flag is positive there can be no internal rendering at all
           // because there could be multiple render subscriptions
 
-          internal.priority = internal.priority + (priority > 0 ? 1 : 0);
+          internal.priority = internal.priority + (priority > 0 ? 1 : 0); // We use the render flag and deprecate priority
+
+          if (internal.priority && state.internal.render === 'auto') set(() => ({
+            internal: { ...state.internal,
+              render: 'manual'
+            }
+          }));
           internal.subscribers.push({
             ref,
             priority,
@@ -1389,11 +1411,18 @@ const createStore = (invalidate, advance) => {
 
           internal.subscribers = internal.subscribers.sort((a, b) => a.priority - b.priority);
           return () => {
-            const internal = get().internal;
+            const state = get();
+            const internal = state.internal;
 
             if (internal != null && internal.subscribers) {
               // Decrease manual flag if this subscription had a priority
-              internal.priority = internal.priority - (priority > 0 ? 1 : 0); // Remove subscriber from list
+              internal.priority = internal.priority - (priority > 0 ? 1 : 0); // We use the render flag and deprecate priority
+
+              if (!internal.priority && state.internal.render === 'manual') set(() => ({
+                internal: { ...state.internal,
+                  render: 'auto'
+                }
+              })); // Remove subscriber from list
 
               internal.subscribers = internal.subscribers.filter(s => s.ref !== ref);
             }
@@ -1449,8 +1478,6 @@ function createSubs(callback, subs) {
   subs.add(sub);
   return () => void subs.delete(sub);
 }
-
-let i;
 let globalEffects = new Set();
 let globalAfterEffects = new Set();
 let globalTailEffects = new Set();
@@ -1479,10 +1506,7 @@ function run(effects, timestamp) {
   }) => callback(timestamp));
 }
 
-let subscribers;
-let subscription;
-
-function render$1(timestamp, state, frame) {
+function update(timestamp, state, frame) {
   // Run local effects
   let delta = state.clock.getDelta(); // In frameloop='never' mode, clock times are updated using the provided timestamp
 
@@ -1490,18 +1514,14 @@ function render$1(timestamp, state, frame) {
     delta = timestamp - state.clock.elapsedTime;
     state.clock.oldTime = state.clock.elapsedTime;
     state.clock.elapsedTime = timestamp;
-  } // Call subscribers (useFrame)
-
-
-  subscribers = state.internal.subscribers;
+  } else {
+    delta = Math.max(Math.min(delta, state.internal.maxDelta), 0);
+  } // Call subscribers (useUpdate)
 
-  for (i = 0; i < subscribers.length; i++) {
-    subscription = subscribers[i];
-    subscription.ref.current(subscription.store.getState(), delta, frame);
-  } // Render content
 
-
-  if (!state.internal.priority && state.gl.render) state.gl.render(state.scene, state.camera); // Decrease frame count
+  for (const stage of state.internal.stages) {
+    stage.frame(delta, frame);
+  }
 
   state.internal.frames = Math.max(0, state.internal.frames - 1);
   return state.frameloop === 'always' ? 1 : state.internal.frames;
@@ -1526,7 +1546,7 @@ function createLoop(roots) {
       state = root.store.getState(); // If the frameloop is invalidated, do not run another frame
 
       if (state.internal.active && (state.frameloop === 'always' || state.internal.frames > 0) && !((_state$gl$xr = state.gl.xr) != null && _state$gl$xr.isPresenting)) {
-        repeat += render$1(timestamp, state);
+        repeat += update(timestamp, state);
       }
     }); // Run after-effects
 
@@ -1557,7 +1577,7 @@ function createLoop(roots) {
 
   function advance(timestamp, runGlobalEffects = true, state, frame) {
     if (runGlobalEffects) run(globalEffects, timestamp);
-    if (!state) roots.forEach(root => render$1(timestamp, root.store.getState()));else render$1(timestamp, state, frame);
+    if (!state) roots.forEach(root => update(timestamp, root.store.getState()));else update(timestamp, state, frame);
     if (runGlobalEffects) run(globalAfterEffects, timestamp);
   }
 
@@ -1578,6 +1598,154 @@ function createLoop(roots) {
   };
 }
 
+/**
+ * Class representing a stage that updates every frame.
+ * Stages are used to build a lifecycle of effects for an app's frameloop.
+ */
+class Stage {
+  constructor() {
+    this.subscribers = [];
+    this._frameTime = 0;
+  }
+  /**
+   * Executes all callback subscriptions on the stage.
+   * @param delta - Delta time between frame calls.
+   * @param [frame] - The XR frame if it exists.
+   */
+
+
+  frame(delta, frame) {
+    const subs = this.subscribers;
+    const initialTime = performance.now();
+
+    for (let i = 0; i < subs.length; i++) {
+      subs[i].ref.current(subs[i].store.getState(), delta, frame);
+    }
+
+    this._frameTime = performance.now() - initialTime;
+  }
+  /**
+   * Adds a callback subscriber to the stage.
+   * @param ref - The mutable callback reference.
+   * @param store - The store to be used with the callback execution.
+   * @returns A function to remove the subscription.
+   */
+
+
+  add(ref, store) {
+    this.subscribers.push({
+      ref,
+      store
+    });
+    return () => {
+      this.subscribers = this.subscribers.filter(sub => {
+        return sub.ref !== ref;
+      });
+    };
+  }
+
+  get frameTime() {
+    return this._frameTime;
+  }
+
+} // Using Unity's fixedStep default.
+
+const FPS_50 = 1 / 50;
+/**
+ * Class representing a stage that updates every frame at a fixed rate.
+ * @param name - Name of the stage.
+ * @param [fixedStep] - Fixed step rate.
+ * @param [maxSubsteps] - Maximum number of substeps.
+ */
+
+class FixedStage extends Stage {
+  constructor(fixedStep, maxSubSteps) {
+    super();
+    this._fixedStep = fixedStep != null ? fixedStep : FPS_50;
+    this._maxSubsteps = maxSubSteps != null ? maxSubSteps : 6;
+    this._accumulator = 0;
+    this._alpha = 0;
+    this._fixedFrameTime = 0;
+    this._substepTimes = [];
+  }
+  /**
+   * Executes all callback subscriptions on the stage.
+   * @param delta - Delta time between frame calls.
+   * @param [frame] - The XR frame if it exists.
+   */
+
+
+  frame(delta, frame) {
+    const initialTime = performance.now();
+    let substeps = 0;
+    this._substepTimes = [];
+    this._accumulator += delta;
+
+    while (this._accumulator >= this._fixedStep && substeps < this._maxSubsteps) {
+      this._accumulator -= this._fixedStep;
+      substeps++;
+      super.frame(this._fixedStep, frame);
+
+      this._substepTimes.push(super.frameTime);
+    }
+
+    this._fixedFrameTime = performance.now() - initialTime; // The accumulator will only be larger than the fixed step if we had to
+    // bail early due to hitting the max substep limit or execution time lagging.
+    // In that case, we want to shave off the excess so we don't fall behind next frame.
+
+    this._accumulator = this._accumulator % this._fixedStep;
+    this._alpha = this._accumulator / this._fixedStep;
+  }
+
+  get frameTime() {
+    return this._fixedFrameTime;
+  }
+
+  get substepTimes() {
+    return this._substepTimes;
+  }
+
+  get fixedStep() {
+    return this._fixedStep;
+  }
+
+  set fixedStep(fixedStep) {
+    this._fixedStep = fixedStep;
+  }
+
+  get maxSubsteps() {
+    return this._maxSubsteps;
+  }
+
+  set maxSubsteps(maxSubsteps) {
+    this._maxSubsteps = maxSubsteps;
+  }
+
+  get accumulator() {
+    return this._accumulator;
+  }
+
+  get alpha() {
+    return this._alpha;
+  }
+
+}
+const Early = new Stage();
+const Fixed = new FixedStage();
+const Update = new Stage();
+const Late = new Stage();
+const Render = new Stage();
+const After = new Stage();
+const Stages = {
+  Early,
+  Fixed,
+  Update,
+  Late,
+  Render,
+  After
+};
+const Lifecycle = [Early, Fixed, Update, Late, Render, After];
+
 function useStore() {
   const store = React__namespace.useContext(context);
   if (!store) throw `R3F hooks can only be used within the Canvas component!`;
@@ -1606,6 +1774,21 @@ function useFrame(callback, renderPriority = 0) {
   useIsomorphicLayoutEffect(() => subscribe(ref, renderPriority, store), [renderPriority, subscribe, store]);
   return null;
 }
+/**
+ * Executes a callback in a given update stage.
+ * Uses the stage instance to indetify which stage to target in the lifecycle.
+ */
+
+function useUpdate(callback, stage = Stages.Update) {
+  const store = useStore();
+  const stages = store.getState().internal.stages; // Memoize ref
+
+  const ref = useMutableCallback(callback); // Throw an error if a stage does not exist in the lifecycle
+
+  if (!stages.includes(stage)) throw new Error(`An invoked stage does not exist in the lifecycle.`); // Subscribe on mount, unsubscribe on unmount
+
+  useIsomorphicLayoutEffect(() => stage.add(ref, store), [stage]);
+}
 /**
  * Returns a node graph of an object with named nodes & materials.
  * @see https://docs.pmnd.rs/react-three-fiber/api/hooks#usegraph
@@ -1687,6 +1870,43 @@ const createRendererInstance = (gl, canvas) => {
   });
 };
 
+const createStages = (stages, store) => {
+  var _stages;
+
+  const state = store.getState();
+  let subscribers;
+  let subscription;
+  stages = (_stages = stages) != null ? _stages : Lifecycle;
+  if (!stages.includes(Stages.Update)) throw 'The Stages.Update stage is required for R3F.';
+  if (!stages.includes(Stages.Render)) throw 'The Stages.Render stage is required for R3F.';
+  state.set(({
+    internal
+  }) => ({
+    internal: { ...internal,
+      stages: stages
+    }
+  })); // Add useFrame loop to update stage
+
+  const frameCallback = {
+    current: (state, delta, frame) => {
+      subscribers = state.internal.subscribers;
+
+      for (let i = 0; i < subscribers.length; i++) {
+        subscription = subscribers[i];
+        subscription.ref.current(subscription.store.getState(), delta, frame);
+      }
+    }
+  };
+  Stages.Update.add(frameCallback, store); // Add render callback to render stage
+
+  const renderCallback = {
+    current: state => {
+      if (state.internal.render === 'auto' && state.gl.render) state.gl.render(state.scene, state.camera);
+    }
+  };
+  Stages.Render.add(renderCallback, store);
+};
+
 function createRoot(canvas) {
   // Check against mistaken use of createRoot
   let prevRoot = roots.get(canvas);
@@ -1728,7 +1948,8 @@ function createRoot(canvas) {
         performance,
         raycaster: raycastOptions,
         camera: cameraOptions,
-        onPointerMissed
+        onPointerMissed,
+        stages
       } = props;
       let state = store.getState(); // Set up renderer (one time only!)
 
@@ -1819,14 +2040,8 @@ function createRoot(canvas) {
           if (!isBoolean) Object.assign(gl.shadowMap, shadows);else gl.shadowMap.type = THREE__namespace.PCFSoftShadowMap;
           if (old !== gl.shadowMap.enabled) gl.shadowMap.needsUpdate = true;
         }
-      } // Safely set color management if available.
-      // Avoid accessing THREE.ColorManagement to play nice with older versions
-
-
-      if ('ColorManagement' in THREE__namespace) {
-        setDeep(THREE__namespace, legacy, ['ColorManagement', 'legacyMode']);
-      }
-
+      } // Set color management
+      THREE__namespace.ColorManagement.legacyMode = legacy;
       const outputEncoding = linear ? THREE__namespace.LinearEncoding : THREE__namespace.sRGBEncoding;
       const toneMapping = flat ? THREE__namespace.NoToneMapping : THREE__namespace.ACESFilmicToneMapping;
       if (gl.outputEncoding !== outputEncoding) gl.outputEncoding = outputEncoding;
@@ -1877,7 +2092,9 @@ function createRoot(canvas) {
         performance: { ...state.performance,
           ...performance
         }
-      })); // Set locals
+      })); // Create update stages.
+
+      if (stages !== state.internal.stages) createStages(stages, store); // Set locals
 
       onCreated = onCreatedCallback;
       configured = true;
@@ -2091,6 +2308,9 @@ const act = React__namespace.unstable_act;
 
 exports.Block = Block;
 exports.ErrorBoundary = ErrorBoundary;
+exports.FixedStage = FixedStage;
+exports.Stage = Stage;
+exports.Stages = Stages;
 exports.act = act;
 exports.addAfterEffect = addAfterEffect;
 exports.addEffect = addEffect;
@@ -2117,3 +2337,4 @@ exports.useLoader = useLoader;
 exports.useMutableCallback = useMutableCallback;
 exports.useStore = useStore;
 exports.useThree = useThree;
+exports.useUpdate = useUpdate;