@react-three/fiber 8.6.2 → 8.7.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @react-three/fiber
 
+## 8.7.0
+
+### Minor Changes
+
+- f5db1b78: feat: useInstanceHandle, flushGlobalEffects
+
 ## 8.6.2
 
 ### Patch Changes

package/dist/declarations/src/core/hooks.d.ts

@@ -1,9 +1,11 @@
 import * as THREE from 'three';
+import * as React from 'react';
 import { StateSelector, EqualityChecker } from 'zustand';
 import { GLTF } from 'three/examples/jsm/loaders/GLTFLoader';
 import { RootState, RenderCallback } from './store';
 import { ObjectMap } from './utils';
 import { LoadingManager } from 'three';
+import { LocalState } from './renderer';
 export interface Loader<T> extends THREE.Loader {
     load(url: string, onLoad?: (result: T) => void, onProgress?: (event: ProgressEvent) => void, onError?: (event: ErrorEvent) => void): unknown;
 }
@@ -11,6 +13,7 @@ export declare type Extensions = (loader: THREE.Loader) => void;
 export declare type LoaderResult<T> = T extends any[] ? Loader<T[number]> : Loader<T>;
 export declare type ConditionalType<Child, Parent, Truthy, Falsy> = Child extends Parent ? Truthy : Falsy;
 export declare type BranchingReturn<T, Parent, Coerced> = ConditionalType<T, Parent, Coerced, T>;
+export declare function useInstanceHandle<O>(ref: React.MutableRefObject<O>): React.MutableRefObject<LocalState>;
 export declare function useStore(): import("zustand").UseBoundStore<RootState, import("zustand").StoreApi<RootState>>;
 export declare function useThree<T = RootState>(selector?: StateSelector<RootState, T>, equalityFn?: EqualityChecker<T>): T;
 export declare function useFrame(callback: RenderCallback, renderPriority?: number): null;

package/dist/declarations/src/core/loop.d.ts

@@ -5,6 +5,8 @@ declare type GlobalRenderCallback = (timeStamp: number) => void;
 export declare const addEffect: (callback: GlobalRenderCallback) => () => void;
 export declare const addAfterEffect: (callback: GlobalRenderCallback) => () => void;
 export declare const addTail: (callback: GlobalRenderCallback) => () => void;
+export declare type GlobalEffectType = 'before' | 'after' | 'tail';
+export declare function flushGlobalEffects(type: GlobalEffectType, timestamp: number): void;
 export declare function createLoop<TCanvas>(roots: Map<TCanvas, Root>): {
     loop: (timestamp: number) => void;
     invalidate: (state?: RootState | undefined, frames?: number) => void;

package/dist/{index-cecf55e8.esm.js → index-3b3bed95.esm.js}

@@ -1468,11 +1468,24 @@ const addAfterEffect = callback => createSubs(callback, globalAfterEffects);
 const addTail = callback => createSubs(callback, globalTailEffects);
 
 function run(effects, timestamp) {
+  if (!effects.size) return;
   effects.forEach(({
     callback
   }) => callback(timestamp));
 }
 
+function flushGlobalEffects(type, timestamp) {
+  switch (type) {
+    case 'before':
+      return run(globalEffects, timestamp);
+
+    case 'after':
+      return run(globalAfterEffects, timestamp);
+
+    case 'tail':
+      return run(globalTailEffects, timestamp);
+  }
+}
 let subscribers;
 let subscription;
 
@@ -1512,7 +1525,7 @@ function createLoop(roots) {
     running = true;
     repeat = 0; // Run effects
 
-    if (globalEffects.size) run(globalEffects, timestamp); // Render all roots
+    flushGlobalEffects('before', timestamp); // Render all roots
 
     roots.forEach(root => {
       var _state$gl$xr;
@@ -1524,11 +1537,11 @@ function createLoop(roots) {
       }
     }); // Run after-effects
 
-    if (globalAfterEffects.size) run(globalAfterEffects, timestamp); // Stop the loop if nothing invalidates it
+    flushGlobalEffects('after', timestamp); // Stop the loop if nothing invalidates it
 
     if (repeat === 0) {
       // Tail call effects, they are called when rendering stops
-      if (globalTailEffects.size) run(globalTailEffects, timestamp); // Flag end of operation
+      flushGlobalEffects('tail', timestamp); // Flag end of operation
 
       running = false;
       return cancelAnimationFrame(frame);
@@ -1550,9 +1563,9 @@ function createLoop(roots) {
   }
 
   function advance(timestamp, runGlobalEffects = true, state, frame) {
-    if (runGlobalEffects) run(globalEffects, timestamp);
+    if (runGlobalEffects) flushGlobalEffects('before', timestamp);
     if (!state) roots.forEach(root => render$1(timestamp, root.store.getState()));else render$1(timestamp, state, frame);
-    if (runGlobalEffects) run(globalAfterEffects, timestamp);
+    if (runGlobalEffects) flushGlobalEffects('after', timestamp);
   }
 
   return {
@@ -1572,6 +1585,17 @@ function createLoop(roots) {
   };
 }
 
+/**
+ * Exposes an object's {@link LocalState}.
+ * @see https://docs.pmnd.rs/react-three-fiber/api/additional-exports#useInstanceHandle
+ *
+ * **Note**: this is an escape hatch to react-internal fields. Expect this to change significantly between versions.
+ */
+function useInstanceHandle(ref) {
+  const instance = React.useRef(null);
+  useIsomorphicLayoutEffect(() => void (instance.current = ref.current.__r3f), [ref]);
+  return instance;
+}
 function useStore() {
   const store = React.useContext(context);
   if (!store) throw new Error('R3F: Hooks can only be used within the Canvas component!');
@@ -2105,4 +2129,4 @@ reconciler.injectIntoDevTools({
 });
 const act = React.unstable_act;
 
-export { Block as B, ErrorBoundary as E, createRoot as a, useIsomorphicLayoutEffect as b, createEvents as c, unmountComponentAtNode as d, extend as e, context as f, createPortal as g, reconciler as h, applyProps as i, dispose as j, invalidate as k, advance as l, addEffect as m, addAfterEffect as n, addTail as o, getRootState as p, act as q, render as r, roots as s, threeTypes as t, useMutableCallback as u, useStore as v, useThree as w, useFrame as x, useGraph as y, useLoader as z };
+export { useLoader as A, Block as B, ErrorBoundary as E, createRoot as a, useIsomorphicLayoutEffect as b, createEvents as c, unmountComponentAtNode as d, extend as e, context as f, createPortal as g, reconciler as h, applyProps as i, dispose as j, invalidate as k, advance as l, addEffect as m, addAfterEffect as n, addTail as o, getRootState as p, act as q, render as r, roots as s, threeTypes as t, useMutableCallback as u, useInstanceHandle as v, useStore as w, useThree as x, useFrame as y, useGraph as z };

package/dist/{index-f368ca4a.cjs.prod.js → index-846c69c6.cjs.prod.js}

@@ -1495,11 +1495,24 @@ const addAfterEffect = callback => createSubs(callback, globalAfterEffects);
 const addTail = callback => createSubs(callback, globalTailEffects);
 
 function run(effects, timestamp) {
+  if (!effects.size) return;
   effects.forEach(({
     callback
   }) => callback(timestamp));
 }
 
+function flushGlobalEffects(type, timestamp) {
+  switch (type) {
+    case 'before':
+      return run(globalEffects, timestamp);
+
+    case 'after':
+      return run(globalAfterEffects, timestamp);
+
+    case 'tail':
+      return run(globalTailEffects, timestamp);
+  }
+}
 let subscribers;
 let subscription;
 
@@ -1539,7 +1552,7 @@ function createLoop(roots) {
     running = true;
     repeat = 0; // Run effects
 
-    if (globalEffects.size) run(globalEffects, timestamp); // Render all roots
+    flushGlobalEffects('before', timestamp); // Render all roots
 
     roots.forEach(root => {
       var _state$gl$xr;
@@ -1551,11 +1564,11 @@ function createLoop(roots) {
       }
     }); // Run after-effects
 
-    if (globalAfterEffects.size) run(globalAfterEffects, timestamp); // Stop the loop if nothing invalidates it
+    flushGlobalEffects('after', timestamp); // Stop the loop if nothing invalidates it
 
     if (repeat === 0) {
       // Tail call effects, they are called when rendering stops
-      if (globalTailEffects.size) run(globalTailEffects, timestamp); // Flag end of operation
+      flushGlobalEffects('tail', timestamp); // Flag end of operation
 
       running = false;
       return cancelAnimationFrame(frame);
@@ -1577,9 +1590,9 @@ function createLoop(roots) {
   }
 
   function advance(timestamp, runGlobalEffects = true, state, frame) {
-    if (runGlobalEffects) run(globalEffects, timestamp);
+    if (runGlobalEffects) flushGlobalEffects('before', timestamp);
     if (!state) roots.forEach(root => render$1(timestamp, root.store.getState()));else render$1(timestamp, state, frame);
-    if (runGlobalEffects) run(globalAfterEffects, timestamp);
+    if (runGlobalEffects) flushGlobalEffects('after', timestamp);
   }
 
   return {
@@ -1599,6 +1612,17 @@ function createLoop(roots) {
   };
 }
 
+/**
+ * Exposes an object's {@link LocalState}.
+ * @see https://docs.pmnd.rs/react-three-fiber/api/additional-exports#useInstanceHandle
+ *
+ * **Note**: this is an escape hatch to react-internal fields. Expect this to change significantly between versions.
+ */
+function useInstanceHandle(ref) {
+  const instance = React__namespace.useRef(null);
+  useIsomorphicLayoutEffect(() => void (instance.current = ref.current.__r3f), [ref]);
+  return instance;
+}
 function useStore() {
   const store = React__namespace.useContext(context);
   if (!store) throw new Error('R3F: Hooks can only be used within the Canvas component!');
@@ -2155,6 +2179,7 @@ exports.threeTypes = threeTypes;
 exports.unmountComponentAtNode = unmountComponentAtNode;
 exports.useFrame = useFrame;
 exports.useGraph = useGraph;
+exports.useInstanceHandle = useInstanceHandle;
 exports.useIsomorphicLayoutEffect = useIsomorphicLayoutEffect;
 exports.useLoader = useLoader;
 exports.useMutableCallback = useMutableCallback;

package/dist/{index-9a338808.cjs.dev.js → index-b3d1f4d2.cjs.dev.js}

@@ -1495,11 +1495,24 @@ const addAfterEffect = callback => createSubs(callback, globalAfterEffects);
 const addTail = callback => createSubs(callback, globalTailEffects);
 
 function run(effects, timestamp) {
+  if (!effects.size) return;
   effects.forEach(({
     callback
   }) => callback(timestamp));
 }
 
+function flushGlobalEffects(type, timestamp) {
+  switch (type) {
+    case 'before':
+      return run(globalEffects, timestamp);
+
+    case 'after':
+      return run(globalAfterEffects, timestamp);
+
+    case 'tail':
+      return run(globalTailEffects, timestamp);
+  }
+}
 let subscribers;
 let subscription;
 
@@ -1539,7 +1552,7 @@ function createLoop(roots) {
     running = true;
     repeat = 0; // Run effects
 
-    if (globalEffects.size) run(globalEffects, timestamp); // Render all roots
+    flushGlobalEffects('before', timestamp); // Render all roots
 
     roots.forEach(root => {
       var _state$gl$xr;
@@ -1551,11 +1564,11 @@ function createLoop(roots) {
       }
     }); // Run after-effects
 
-    if (globalAfterEffects.size) run(globalAfterEffects, timestamp); // Stop the loop if nothing invalidates it
+    flushGlobalEffects('after', timestamp); // Stop the loop if nothing invalidates it
 
     if (repeat === 0) {
       // Tail call effects, they are called when rendering stops
-      if (globalTailEffects.size) run(globalTailEffects, timestamp); // Flag end of operation
+      flushGlobalEffects('tail', timestamp); // Flag end of operation
 
       running = false;
       return cancelAnimationFrame(frame);
@@ -1577,9 +1590,9 @@ function createLoop(roots) {
   }
 
   function advance(timestamp, runGlobalEffects = true, state, frame) {
-    if (runGlobalEffects) run(globalEffects, timestamp);
+    if (runGlobalEffects) flushGlobalEffects('before', timestamp);
     if (!state) roots.forEach(root => render$1(timestamp, root.store.getState()));else render$1(timestamp, state, frame);
-    if (runGlobalEffects) run(globalAfterEffects, timestamp);
+    if (runGlobalEffects) flushGlobalEffects('after', timestamp);
   }
 
   return {
@@ -1599,6 +1612,17 @@ function createLoop(roots) {
   };
 }
 
+/**
+ * Exposes an object's {@link LocalState}.
+ * @see https://docs.pmnd.rs/react-three-fiber/api/additional-exports#useInstanceHandle
+ *
+ * **Note**: this is an escape hatch to react-internal fields. Expect this to change significantly between versions.
+ */
+function useInstanceHandle(ref) {
+  const instance = React__namespace.useRef(null);
+  useIsomorphicLayoutEffect(() => void (instance.current = ref.current.__r3f), [ref]);
+  return instance;
+}
 function useStore() {
   const store = React__namespace.useContext(context);
   if (!store) throw new Error('R3F: Hooks can only be used within the Canvas component!');
@@ -2155,6 +2179,7 @@ exports.threeTypes = threeTypes;
 exports.unmountComponentAtNode = unmountComponentAtNode;
 exports.useFrame = useFrame;
 exports.useGraph = useGraph;
+exports.useInstanceHandle = useInstanceHandle;
 exports.useIsomorphicLayoutEffect = useIsomorphicLayoutEffect;
 exports.useLoader = useLoader;
 exports.useMutableCallback = useMutableCallback;

package/dist/react-three-fiber.cjs.dev.js

@@ -2,7 +2,7 @@
 
 Object.defineProperty(exports, '__esModule', { value: true });
 
-var index = require('./index-9a338808.cjs.dev.js');
+var index = require('./index-b3d1f4d2.cjs.dev.js');
 var _extends = require('@babel/runtime/helpers/extends');
 var React = require('react');
 var THREE = require('three');
@@ -263,6 +263,7 @@ exports.render = index.render;
 exports.unmountComponentAtNode = index.unmountComponentAtNode;
 exports.useFrame = index.useFrame;
 exports.useGraph = index.useGraph;
+exports.useInstanceHandle = index.useInstanceHandle;
 exports.useLoader = index.useLoader;
 exports.useStore = index.useStore;
 exports.useThree = index.useThree;

package/dist/react-three-fiber.cjs.prod.js

@@ -2,7 +2,7 @@
 
 Object.defineProperty(exports, '__esModule', { value: true });
 
-var index = require('./index-f368ca4a.cjs.prod.js');
+var index = require('./index-846c69c6.cjs.prod.js');
 var _extends = require('@babel/runtime/helpers/extends');
 var React = require('react');
 var THREE = require('three');
@@ -263,6 +263,7 @@ exports.render = index.render;
 exports.unmountComponentAtNode = index.unmountComponentAtNode;
 exports.useFrame = index.useFrame;
 exports.useGraph = index.useGraph;
+exports.useInstanceHandle = index.useInstanceHandle;
 exports.useLoader = index.useLoader;
 exports.useStore = index.useStore;
 exports.useThree = index.useThree;

package/dist/react-three-fiber.esm.js

@@ -1,5 +1,5 @@
-import { c as createEvents, e as extend, u as useMutableCallback, a as createRoot, E as ErrorBoundary, B as Block, b as useIsomorphicLayoutEffect, d as unmountComponentAtNode } from './index-cecf55e8.esm.js';
-export { t as ReactThreeFiber, s as _roots, q as act, n as addAfterEffect, m as addEffect, o as addTail, l as advance, i as applyProps, f as context, c as createEvents, g as createPortal, a as createRoot, j as dispose, e as extend, p as getRootState, k as invalidate, h as reconciler, r as render, d as unmountComponentAtNode, x as useFrame, y as useGraph, z as useLoader, v as useStore, w as useThree } from './index-cecf55e8.esm.js';
+import { c as createEvents, e as extend, u as useMutableCallback, a as createRoot, E as ErrorBoundary, B as Block, b as useIsomorphicLayoutEffect, d as unmountComponentAtNode } from './index-3b3bed95.esm.js';
+export { t as ReactThreeFiber, s as _roots, q as act, n as addAfterEffect, m as addEffect, o as addTail, l as advance, i as applyProps, f as context, c as createEvents, g as createPortal, a as createRoot, j as dispose, e as extend, p as getRootState, k as invalidate, h as reconciler, r as render, d as unmountComponentAtNode, y as useFrame, z as useGraph, v as useInstanceHandle, A as useLoader, w as useStore, x as useThree } from './index-3b3bed95.esm.js';
 import _extends from '@babel/runtime/helpers/esm/extends';
 import * as React from 'react';
 import * as THREE from 'three';

package/native/dist/react-three-fiber-native.cjs.dev.js

@@ -2,7 +2,7 @@
 
 Object.defineProperty(exports, '__esModule', { value: true });
 
-var index = require('../../dist/index-9a338808.cjs.dev.js');
+var index = require('../../dist/index-b3d1f4d2.cjs.dev.js');
 var _extends = require('@babel/runtime/helpers/extends');
 var React = require('react');
 var THREE = require('three');
@@ -401,6 +401,7 @@ exports.render = index.render;
 exports.unmountComponentAtNode = index.unmountComponentAtNode;
 exports.useFrame = index.useFrame;
 exports.useGraph = index.useGraph;
+exports.useInstanceHandle = index.useInstanceHandle;
 exports.useLoader = index.useLoader;
 exports.useStore = index.useStore;
 exports.useThree = index.useThree;

package/native/dist/react-three-fiber-native.cjs.prod.js

@@ -2,7 +2,7 @@
 
 Object.defineProperty(exports, '__esModule', { value: true });
 
-var index = require('../../dist/index-f368ca4a.cjs.prod.js');
+var index = require('../../dist/index-846c69c6.cjs.prod.js');
 var _extends = require('@babel/runtime/helpers/extends');
 var React = require('react');
 var THREE = require('three');
@@ -401,6 +401,7 @@ exports.render = index.render;
 exports.unmountComponentAtNode = index.unmountComponentAtNode;
 exports.useFrame = index.useFrame;
 exports.useGraph = index.useGraph;
+exports.useInstanceHandle = index.useInstanceHandle;
 exports.useLoader = index.useLoader;
 exports.useStore = index.useStore;
 exports.useThree = index.useThree;

package/native/dist/react-three-fiber-native.esm.js

@@ -1,5 +1,5 @@
-import { c as createEvents, e as extend, u as useMutableCallback, a as createRoot, E as ErrorBoundary, B as Block, d as unmountComponentAtNode } from '../../dist/index-cecf55e8.esm.js';
-export { t as ReactThreeFiber, s as _roots, q as act, n as addAfterEffect, m as addEffect, o as addTail, l as advance, i as applyProps, f as context, g as createPortal, a as createRoot, j as dispose, e as extend, p as getRootState, k as invalidate, h as reconciler, r as render, d as unmountComponentAtNode, x as useFrame, y as useGraph, z as useLoader, v as useStore, w as useThree } from '../../dist/index-cecf55e8.esm.js';
+import { c as createEvents, e as extend, u as useMutableCallback, a as createRoot, E as ErrorBoundary, B as Block, d as unmountComponentAtNode } from '../../dist/index-3b3bed95.esm.js';
+export { t as ReactThreeFiber, s as _roots, q as act, n as addAfterEffect, m as addEffect, o as addTail, l as advance, i as applyProps, f as context, g as createPortal, a as createRoot, j as dispose, e as extend, p as getRootState, k as invalidate, h as reconciler, r as render, d as unmountComponentAtNode, y as useFrame, z as useGraph, v as useInstanceHandle, A as useLoader, w as useStore, x as useThree } from '../../dist/index-3b3bed95.esm.js';
 import _extends from '@babel/runtime/helpers/esm/extends';
 import * as React from 'react';
 import * as THREE from 'three';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@react-three/fiber",
-  "version": "8.6.2",
+  "version": "8.7.0",
   "description": "A React renderer for Threejs",
   "keywords": [
     "react",