@react-three/fiber 8.15.4 → 8.15.6

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @react-three/fiber
 
+## 8.15.6
+
+### Patch Changes
+
+- 7bb2950b: experiment: stable object sort
+
+## 8.15.5
+
+### Patch Changes
+
+- 0e44fd8b: fix(types): preserve deprecated JSX annotations
+
 ## 8.15.4
 
 ### Patch Changes

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

@@ -3,18 +3,29 @@ import type { UseBoundStore } from 'zustand';
 import type { RootState } from './store';
 import type { Properties } from '../three-types';
 export interface Intersection extends THREE.Intersection {
+    /** The event source (the object which registered the handler) */
     eventObject: THREE.Object3D;
 }
 export interface IntersectionEvent<TSourceEvent> extends Intersection {
+    /** The event source (the object which registered the handler) */
     eventObject: THREE.Object3D;
+    /** An array of intersections */
     intersections: Intersection[];
+    /** vec3.set(pointer.x, pointer.y, 0).unproject(camera) */
     unprojectedPoint: THREE.Vector3;
+    /** Normalized event coordinates */
     pointer: THREE.Vector2;
+    /** Delta between first click and this event */
     delta: number;
+    /** The ray that pierced it */
     ray: THREE.Ray;
+    /** The camera that was used by the raycaster */
     camera: Camera;
+    /** stopPropagation will stop underlying handlers from firing */
     stopPropagation: () => void;
+    /** The original host event */
     nativeEvent: TSourceEvent;
+    /** If the event was stopped by calling stopPropagation */
     stopped: boolean;
 }
 export declare type Camera = THREE.OrthographicCamera | THREE.PerspectiveCamera;
@@ -50,14 +61,25 @@ export declare type EventHandlers = {
 export declare type FilterFunction = (items: THREE.Intersection[], state: RootState) => THREE.Intersection[];
 export declare type ComputeFunction = (event: DomEvent, root: RootState, previous?: RootState) => void;
 export interface EventManager<TTarget> {
+    /** Determines if the event layer is active */
     enabled: boolean;
+    /** Event layer priority, higher prioritized layers come first and may stop(-propagate) lower layer  */
     priority: number;
+    /** The compute function needs to set up the raycaster and an xy- pointer  */
     compute?: ComputeFunction;
+    /** The filter can re-order or re-structure the intersections  */
     filter?: FilterFunction;
+    /** The target node the event layer is tied to */
     connected?: TTarget;
+    /** All the pointer event handlers through which the host forwards native events */
     handlers?: Events;
+    /** Allows re-connecting to another target */
     connect?: (target: TTarget) => void;
+    /** Removes all existing events handlers from the target */
     disconnect?: () => void;
+    /** Triggers a onPointerMove with the last known event. This can be useful to enable raycasting without
+     *  explicit user interaction, for instance when the camera moves a hoverable object underneath the cursor.
+     */
     update?: () => void;
 }
 export interface PointerCaptureTarget {

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

@@ -17,11 +17,36 @@ export declare type Extensions<T extends {
 }> = (loader: T['prototype']) => void;
 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>;
+/**
+ * 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.
+ */
 export declare function useInstanceHandle<O>(ref: React.MutableRefObject<O>): React.MutableRefObject<LocalState>;
 export declare function useStore(): import("zustand").UseBoundStore<RootState, import("zustand").StoreApi<RootState>>;
+/**
+ * Accesses R3F's internal state, containing renderer, canvas, scene, etc.
+ * @see https://docs.pmnd.rs/react-three-fiber/api/hooks#usethree
+ */
 export declare function useThree<T = RootState>(selector?: StateSelector<RootState, T>, equalityFn?: EqualityChecker<T>): T;
+/**
+ * Executes a callback before render in a shared frame loop.
+ * Can order effects with render priority or manually render with a positive priority.
+ * @see https://docs.pmnd.rs/react-three-fiber/api/hooks#useframe
+ */
 export declare function useFrame(callback: RenderCallback, renderPriority?: number): null;
+/**
+ * Returns a node graph of an object with named nodes & materials.
+ * @see https://docs.pmnd.rs/react-three-fiber/api/hooks#usegraph
+ */
 export declare function useGraph(object: THREE.Object3D): ObjectMap;
+/**
+ * Synchronously loads and caches assets with a three loader.
+ *
+ * Note: this hook's caller must be wrapped with `React.Suspense`
+ * @see https://docs.pmnd.rs/react-three-fiber/api/hooks#useloader
+ */
 export declare function useLoader<T, U extends string | string[], L extends LoaderProto<T>, R = LoaderReturnType<T, L>>(Proto: L, input: U, extensions?: Extensions<L>, onProgress?: (event: ProgressEvent<EventTarget>) => void): U extends any[] ? BranchingReturn<R, GLTF, GLTF & ObjectMap>[] : BranchingReturn<R, GLTF, GLTF & ObjectMap>;
 export declare namespace useLoader {
     var preload: <T, U extends string | string[], L extends LoaderProto<T>>(Proto: L, input: U, extensions?: Extensions<L> | undefined) => undefined;

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

@@ -15,23 +15,53 @@ declare const invalidate: (state?: RootState | undefined, frames?: number) => vo
 declare const reconciler: import("react-reconciler").Reconciler<UseBoundStore<RootState, import("zustand").StoreApi<RootState>>, import("./renderer").Instance, void, import("./renderer").Instance, import("./renderer").Instance>, applyProps: typeof import("./utils").applyProps;
 declare type GLProps = Renderer | ((canvas: Canvas) => Renderer) | Partial<Properties<THREE.WebGLRenderer> | THREE.WebGLRendererParameters> | undefined;
 export declare type RenderProps<TCanvas extends Canvas> = {
+    /** A threejs renderer instance or props that go into the default renderer */
     gl?: GLProps;
+    /** Dimensions to fit the renderer to. Will measure canvas dimensions if omitted */
     size?: Size;
+    /**
+     * Enables shadows (by default PCFsoft). Can accept `gl.shadowMap` options for fine-tuning,
+     * but also strings: 'basic' | 'percentage' | 'soft' | 'variance'.
+     * @see https://threejs.org/docs/#api/en/renderers/WebGLRenderer.shadowMap
+     */
     shadows?: boolean | 'basic' | 'percentage' | 'soft' | 'variance' | Partial<THREE.WebGLShadowMap>;
+    /**
+     * Disables three r139 color management.
+     * @see https://threejs.org/docs/#manual/en/introduction/Color-management
+     */
     legacy?: boolean;
+    /** Switch off automatic sRGB color space and gamma correction */
     linear?: boolean;
+    /** Use `THREE.NoToneMapping` instead of `THREE.ACESFilmicToneMapping` */
     flat?: boolean;
+    /** Creates an orthographic camera */
     orthographic?: boolean;
+    /**
+     * R3F's render mode. Set to `demand` to only render on state change or `never` to take control.
+     * @see https://docs.pmnd.rs/react-three-fiber/advanced/scaling-performance#on-demand-rendering
+     */
     frameloop?: 'always' | 'demand' | 'never';
+    /**
+     * R3F performance options for adaptive performance.
+     * @see https://docs.pmnd.rs/react-three-fiber/advanced/scaling-performance#movement-regression
+     */
     performance?: Partial<Omit<Performance, 'regress'>>;
+    /** Target pixel ratio. Can clamp between a range: `[min, max]` */
     dpr?: Dpr;
+    /** Props that go into the default raycaster */
     raycaster?: Partial<THREE.Raycaster>;
+    /** A `THREE.Scene` instance or props that go into the default scene */
     scene?: THREE.Scene | Partial<ReactThreeFiber.Object3DNode<THREE.Scene, typeof THREE.Scene>>;
+    /** A `THREE.Camera` instance or props that go into the default camera */
     camera?: (Camera | Partial<ReactThreeFiber.Object3DNode<THREE.Camera, typeof THREE.Camera> & ReactThreeFiber.Object3DNode<THREE.PerspectiveCamera, typeof THREE.PerspectiveCamera> & ReactThreeFiber.Object3DNode<THREE.OrthographicCamera, typeof THREE.OrthographicCamera>>) & {
+        /** Flags the camera as manual, putting projection into your own hands */
         manual?: boolean;
     };
+    /** An R3F event manager to manage elements' pointer events */
     events?: (store: UseBoundStore<RootState>) => EventManager<HTMLElement>;
+    /** Callback after the canvas has rendered (but not yet committed) */
     onCreated?: (state: RootState) => void;
+    /** Response for pointer clicks that have missed any target */
     onPointerMissed?: (event: MouseEvent) => void;
 };
 export declare type ReconcilerRoot<TCanvas extends Canvas> = {

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

@@ -1,13 +1,33 @@
 import { Root } from './renderer';
 import { RootState } from './store';
 export declare type GlobalRenderCallback = (timeStamp: number) => void;
+/**
+ * Adds a global render callback which is called each frame.
+ * @see https://docs.pmnd.rs/react-three-fiber/api/additional-exports#addEffect
+ */
 export declare const addEffect: (callback: GlobalRenderCallback) => () => void;
+/**
+ * Adds a global after-render callback which is called each frame.
+ * @see https://docs.pmnd.rs/react-three-fiber/api/additional-exports#addAfterEffect
+ */
 export declare const addAfterEffect: (callback: GlobalRenderCallback) => () => void;
+/**
+ * Adds a global callback which is called when rendering stops.
+ * @see https://docs.pmnd.rs/react-three-fiber/api/additional-exports#addTail
+ */
 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;
+    /**
+     * Invalidates the view, requesting a frame to be rendered. Will globally invalidate unless passed a root's state.
+     * @see https://docs.pmnd.rs/react-three-fiber/api/additional-exports#invalidate
+     */
     invalidate: (state?: RootState | undefined, frames?: number) => void;
+    /**
+     * Advances the frameloop and runs render effects, useful for when manually rendering via `frameloop="never"`.
+     * @see https://docs.pmnd.rs/react-three-fiber/api/additional-exports#advance
+     */
     advance: (timestamp: number, runGlobalEffects?: boolean, state?: RootState | undefined, frame?: import("three").XRFrame | undefined) => void;
 };

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

@@ -19,21 +19,32 @@ export declare type Size = {
     height: number;
     top: number;
     left: number;
+    /** @deprecated `updateStyle` is now disabled for OffscreenCanvas and will be removed in v9. */
     updateStyle?: boolean;
 };
 export declare type Viewport = Size & {
+    /** The initial pixel ratio */
     initialDpr: number;
+    /** Current pixel ratio */
     dpr: number;
+    /** size.width / viewport.width */
     factor: number;
+    /** Camera distance */
     distance: number;
+    /** Camera aspect ratio: width / height */
     aspect: number;
 };
 export declare type RenderCallback = (state: RootState, delta: number, frame?: _XRFrame) => void;
 export declare type Performance = {
+    /** Current performance normal, between min and max */
     current: number;
+    /** How low the performance can go, between 0 and max */
     min: number;
+    /** How high the performance can go, between min and max */
     max: number;
+    /** Time until current returns to max in ms */
     debounce: number;
+    /** Sets current to min, puts the system in regression */
     regress: () => void;
 };
 export declare type Renderer = {
@@ -54,40 +65,71 @@ export declare type InternalState = {
     subscribe: (callback: React.MutableRefObject<RenderCallback>, priority: number, store: UseBoundStore<RootState, StoreApi<RootState>>) => () => void;
 };
 export declare type RootState = {
+    /** Set current state */
     set: SetState<RootState>;
+    /** Get current state */
     get: GetState<RootState>;
+    /** The instance of the renderer */
     gl: THREE.WebGLRenderer;
+    /** Default camera */
     camera: Camera & {
         manual?: boolean;
     };
+    /** Default scene */
     scene: THREE.Scene;
+    /** Default raycaster */
     raycaster: THREE.Raycaster;
+    /** Default clock */
     clock: THREE.Clock;
+    /** Event layer interface, contains the event handler and the node they're connected to */
     events: EventManager<any>;
+    /** XR interface */
     xr: {
         connect: () => void;
         disconnect: () => void;
     };
+    /** Currently used controls */
     controls: THREE.EventDispatcher | null;
+    /** Normalized event coordinates */
     pointer: THREE.Vector2;
+    /** @deprecated Normalized event coordinates, use "pointer" instead! */
     mouse: THREE.Vector2;
     legacy: boolean;
+    /** Shortcut to gl.outputColorSpace = THREE.LinearSRGBColorSpace */
     linear: boolean;
+    /** Shortcut to gl.toneMapping = NoTonemapping */
     flat: boolean;
+    /** Render loop flags */
     frameloop: 'always' | 'demand' | 'never';
+    /** Adaptive performance interface */
     performance: Performance;
+    /** Reactive pixel-size of the canvas */
     size: Size;
+    /** Reactive size of the viewport in threejs units */
     viewport: Viewport & {
         getCurrentViewport: (camera?: Camera, target?: THREE.Vector3 | Parameters<THREE.Vector3['set']>, size?: Size) => Omit<Viewport, 'dpr' | 'initialDpr'>;
     };
+    /** Flags the canvas for render, but doesn't render in itself */
     invalidate: (frames?: number) => void;
+    /** Advance (render) one step */
     advance: (timestamp: number, runGlobalEffects?: boolean) => void;
+    /** Shortcut to setting the event layer */
     setEvents: (events: Partial<EventManager<any>>) => void;
-    setSize: (width: number, height: number, updateStyle?: boolean, top?: number, left?: number) => void;
+    /**
+     * Shortcut to manual sizing
+     */
+    setSize: (width: number, height: number, 
+    /** @deprecated `updateStyle` is now disabled for OffscreenCanvas and will be removed in v9. */
+    updateStyle?: boolean, top?: number, left?: number) => void;
+    /** Shortcut to manual setting the pixel ratio */
     setDpr: (dpr: Dpr) => void;
+    /** Shortcut to frameloop flags */
     setFrameloop: (frameloop?: 'always' | 'demand' | 'never') => void;
+    /** When the canvas was clicked but nothing was hit */
     onPointerMissed?: (event: MouseEvent) => void;
+    /** If this state model is layerd (via createPortal) then this contains the previous layer */
     previousRoot?: UseBoundStore<RootState, StoreApi<RootState>>;
+    /** Internals */
     internal: InternalState;
 };
 declare const context: React.Context<UseBoundStore<RootState, StoreApi<RootState>>>;

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

@@ -7,6 +7,9 @@ declare type _DeprecatedXRFrame = THREE.XRFrame;
 export declare type _XRFrame = THREE.WebGLRenderTargetOptions extends {
     samples?: number;
 } ? XRFrame : _DeprecatedXRFrame;
+/**
+ * Returns `true` with correct TS type inference if an object has a configurable color space (since r152).
+ */
 export declare const hasColorSpace: <T extends object | Renderer | THREE.Texture, P = T extends Renderer ? {
     outputColorSpace: string;
 } : {
@@ -17,10 +20,22 @@ export declare type ColorManagementRepresentation = {
 } | {
     legacyMode: boolean | never;
 };
+/**
+ * The current THREE.ColorManagement instance, if present.
+ */
 export declare const getColorManagement: () => ColorManagementRepresentation | null;
 export declare type Camera = THREE.OrthographicCamera | THREE.PerspectiveCamera;
 export declare const isOrthographicCamera: (def: Camera) => def is THREE.OrthographicCamera;
 export declare const isRef: (obj: any) => obj is React.MutableRefObject<unknown>;
+/**
+ * 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
+ */
 export declare const useIsomorphicLayoutEffect: typeof React.useLayoutEffect;
 export declare function useMutableCallback<T>(fn: T): React.MutableRefObject<T>;
 export declare type SetBlock = false | Promise<null> | null;
@@ -65,10 +80,16 @@ export declare type ObjectMap = {
     };
 };
 export declare function calculateDpr(dpr: Dpr): number;
+/**
+ * Returns instance root state
+ */
 export declare const getRootState: (obj: THREE.Object3D) => RootState | undefined;
 export declare type EquConfig = {
+    /** Compare arrays by reference equality a === b (default), or by shallow equality */
     arrays?: 'reference' | 'shallow';
+    /** Compare objects by reference equality a === b (default), or by shallow equality */
     objects?: 'reference' | 'shallow';
+    /** If true the keys in both a and b must match 1:1 (default), if false a's keys must intersect b's */
     strict?: boolean;
 };
 export declare const is: {
@@ -81,6 +102,9 @@ export declare const is: {
     arr: (a: any) => boolean;
     equ(a: any, b: any, { arrays, objects, strict }?: EquConfig): boolean;
 };
+/**
+ * Collects nodes and materials from a THREE.Object3D.
+ */
 export declare function buildGraph(object: THREE.Object3D): ObjectMap;
 export declare function dispose<TObj extends {
     dispose?: () => void;

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

@@ -7,4 +7,8 @@ export interface CanvasProps extends Omit<RenderProps<HTMLCanvasElement>, 'size'
 }
 export interface Props extends CanvasProps {
 }
+/**
+ * A native canvas which accepts threejs elements as children.
+ * @see https://docs.pmnd.rs/react-three-fiber/api/canvas
+ */
 export declare const Canvas: React.ForwardRefExoticComponent<Props & React.RefAttributes<View>>;

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

@@ -1,4 +1,5 @@
 import { UseBoundStore } from 'zustand';
 import { RootState } from '../core/store';
 import { EventManager } from '../core/events';
+/** Default R3F event manager for react-native */
 export declare function createTouchEvents(store: UseBoundStore<RootState>): EventManager<HTMLElement>;

package/dist/declarations/src/three-types.d.ts

@@ -8,9 +8,15 @@ export declare type NonFunctionKeys<T> = {
     [K in keyof T]-?: T[K] extends Function ? never : K;
 }[keyof T];
 export declare type Overwrite<T, O> = Omit<T, NonFunctionKeys<O>> & O;
+/**
+ * If **T** contains a constructor, @see ConstructorParameters must be used, otherwise **T**.
+ */
 declare type Args<T> = T extends new (...args: any) => any ? ConstructorParameters<T> : T;
 export declare type Euler = THREE.Euler | Parameters<THREE.Euler['set']>;
 export declare type Matrix4 = THREE.Matrix4 | Parameters<THREE.Matrix4['set']> | Readonly<THREE.Matrix4['set']>;
+/**
+ * Turn an implementation of THREE.Vector in to the type that an r3f component would accept as a prop.
+ */
 declare type VectorLike<VectorClass extends THREE.Vector> = VectorClass | Parameters<VectorClass['set']> | Readonly<Parameters<VectorClass['set']>> | Parameters<VectorClass['setScalar']>[0];
 export declare type Vector2 = VectorLike<THREE.Vector2>;
 export declare type Vector3 = VectorLike<THREE.Vector3>;
@@ -22,6 +28,7 @@ export declare type Quaternion = THREE.Quaternion | Parameters<THREE.Quaternion[
 export declare type AttachCallback = string | ((child: any, parentInstance: any) => void);
 export interface NodeProps<T, P> {
     attach?: AttachType;
+    /** Constructor arguments */
     args?: Args<P>;
     children?: React.ReactNode;
     ref?: React.Ref<T>;
@@ -67,23 +74,71 @@ export declare type CubeCameraProps = Object3DNode<THREE.CubeCamera, typeof THRE
 export declare type ArrayCameraProps = Object3DNode<THREE.ArrayCamera, typeof THREE.ArrayCamera>;
 export declare type InstancedBufferGeometryProps = BufferGeometryNode<THREE.InstancedBufferGeometry, typeof THREE.InstancedBufferGeometry>;
 export declare type BufferGeometryProps = BufferGeometryNode<THREE.BufferGeometry, typeof THREE.BufferGeometry>;
+/** @ts-ignore */
 export declare type BoxBufferGeometryProps = BufferGeometryNode<THREE.BoxBufferGeometry, typeof THREE.BoxBufferGeometry>;
-export declare type CircleBufferGeometryProps = BufferGeometryNode<THREE.CircleBufferGeometry, typeof THREE.CircleBufferGeometry>;
+export declare type CircleBufferGeometryProps = BufferGeometryNode<
+/** @ts-ignore */
+THREE.CircleBufferGeometry, 
+/** @ts-ignore */
+typeof THREE.CircleBufferGeometry>;
+/** @ts-ignore */
 export declare type ConeBufferGeometryProps = BufferGeometryNode<THREE.ConeBufferGeometry, typeof THREE.ConeBufferGeometry>;
-export declare type CylinderBufferGeometryProps = BufferGeometryNode<THREE.CylinderBufferGeometry, typeof THREE.CylinderBufferGeometry>;
-export declare type DodecahedronBufferGeometryProps = BufferGeometryNode<THREE.DodecahedronBufferGeometry, typeof THREE.DodecahedronBufferGeometry>;
-export declare type ExtrudeBufferGeometryProps = BufferGeometryNode<THREE.ExtrudeBufferGeometry, typeof THREE.ExtrudeBufferGeometry>;
-export declare type IcosahedronBufferGeometryProps = BufferGeometryNode<THREE.IcosahedronBufferGeometry, typeof THREE.IcosahedronBufferGeometry>;
+export declare type CylinderBufferGeometryProps = BufferGeometryNode<
+/** @ts-ignore */
+THREE.CylinderBufferGeometry, 
+/** @ts-ignore */
+typeof THREE.CylinderBufferGeometry>;
+export declare type DodecahedronBufferGeometryProps = BufferGeometryNode<
+/** @ts-ignore */
+THREE.DodecahedronBufferGeometry, 
+/** @ts-ignore */
+typeof THREE.DodecahedronBufferGeometry>;
+export declare type ExtrudeBufferGeometryProps = BufferGeometryNode<
+/** @ts-ignore */
+THREE.ExtrudeBufferGeometry, 
+/** @ts-ignore */
+typeof THREE.ExtrudeBufferGeometry>;
+export declare type IcosahedronBufferGeometryProps = BufferGeometryNode<
+/** @ts-ignore */
+THREE.IcosahedronBufferGeometry, 
+/** @ts-ignore */
+typeof THREE.IcosahedronBufferGeometry>;
+/** @ts-ignore */
 export declare type LatheBufferGeometryProps = BufferGeometryNode<THREE.LatheBufferGeometry, typeof THREE.LatheBufferGeometry>;
-export declare type OctahedronBufferGeometryProps = BufferGeometryNode<THREE.OctahedronBufferGeometry, typeof THREE.OctahedronBufferGeometry>;
+export declare type OctahedronBufferGeometryProps = BufferGeometryNode<
+/** @ts-ignore */
+THREE.OctahedronBufferGeometry, 
+/** @ts-ignore */
+typeof THREE.OctahedronBufferGeometry>;
+/** @ts-ignore */
 export declare type PlaneBufferGeometryProps = BufferGeometryNode<THREE.PlaneBufferGeometry, typeof THREE.PlaneBufferGeometry>;
-export declare type PolyhedronBufferGeometryProps = BufferGeometryNode<THREE.PolyhedronBufferGeometry, typeof THREE.PolyhedronBufferGeometry>;
+export declare type PolyhedronBufferGeometryProps = BufferGeometryNode<
+/** @ts-ignore */
+THREE.PolyhedronBufferGeometry, 
+/** @ts-ignore */
+typeof THREE.PolyhedronBufferGeometry>;
+/** @ts-ignore */
 export declare type RingBufferGeometryProps = BufferGeometryNode<THREE.RingBufferGeometry, typeof THREE.RingBufferGeometry>;
+/** @ts-ignore */
 export declare type ShapeBufferGeometryProps = BufferGeometryNode<THREE.ShapeBufferGeometry, typeof THREE.ShapeBufferGeometry>;
-export declare type SphereBufferGeometryProps = BufferGeometryNode<THREE.SphereBufferGeometry, typeof THREE.SphereBufferGeometry>;
-export declare type TetrahedronBufferGeometryProps = BufferGeometryNode<THREE.TetrahedronBufferGeometry, typeof THREE.TetrahedronBufferGeometry>;
+export declare type SphereBufferGeometryProps = BufferGeometryNode<
+/** @ts-ignore */
+THREE.SphereBufferGeometry, 
+/** @ts-ignore */
+typeof THREE.SphereBufferGeometry>;
+export declare type TetrahedronBufferGeometryProps = BufferGeometryNode<
+/** @ts-ignore */
+THREE.TetrahedronBufferGeometry, 
+/** @ts-ignore */
+typeof THREE.TetrahedronBufferGeometry>;
+/** @ts-ignore */
 export declare type TorusBufferGeometryProps = BufferGeometryNode<THREE.TorusBufferGeometry, typeof THREE.TorusBufferGeometry>;
-export declare type TorusKnotBufferGeometryProps = BufferGeometryNode<THREE.TorusKnotBufferGeometry, typeof THREE.TorusKnotBufferGeometry>;
+export declare type TorusKnotBufferGeometryProps = BufferGeometryNode<
+/** @ts-ignore */
+THREE.TorusKnotBufferGeometry, 
+/** @ts-ignore */
+typeof THREE.TorusKnotBufferGeometry>;
+/** @ts-ignore */
 export declare type TubeBufferGeometryProps = BufferGeometryNode<THREE.TubeBufferGeometry, typeof THREE.TubeBufferGeometry>;
 export declare type WireframeGeometryProps = BufferGeometryNode<THREE.WireframeGeometry, typeof THREE.WireframeGeometry>;
 export declare type TetrahedronGeometryProps = BufferGeometryNode<THREE.TetrahedronGeometry, typeof THREE.TetrahedronGeometry>;
@@ -139,7 +194,9 @@ export declare type DirectionalLightShadowProps = Node<THREE.DirectionalLightSha
 export declare type DirectionalLightProps = LightNode<THREE.DirectionalLight, typeof THREE.DirectionalLight>;
 export declare type AmbientLightProps = LightNode<THREE.AmbientLight, typeof THREE.AmbientLight>;
 export declare type LightShadowProps = Node<THREE.LightShadow, typeof THREE.LightShadow>;
+/** @ts-ignore */
 export declare type AmbientLightProbeProps = LightNode<THREE.AmbientLightProbe, typeof THREE.AmbientLightProbe>;
+/** @ts-ignore */
 export declare type HemisphereLightProbeProps = LightNode<THREE.HemisphereLightProbe, typeof THREE.HemisphereLightProbe>;
 export declare type LightProbeProps = LightNode<THREE.LightProbe, typeof THREE.LightProbe>;
 export declare type SpotLightHelperProps = Object3DNode<THREE.SpotLightHelper, typeof THREE.SpotLightHelper>;
@@ -158,6 +215,7 @@ export declare type AxesHelperProps = Object3DNode<THREE.AxesHelper, typeof THRE
 export declare type TextureProps = Node<THREE.Texture, typeof THREE.Texture>;
 export declare type VideoTextureProps = Node<THREE.VideoTexture, typeof THREE.VideoTexture>;
 export declare type DataTextureProps = Node<THREE.DataTexture, typeof THREE.DataTexture>;
+/** @ts-ignore */
 export declare type DataTexture3DProps = Node<THREE.DataTexture3D, typeof THREE.DataTexture3D>;
 export declare type CompressedTextureProps = Node<THREE.CompressedTexture, typeof THREE.CompressedTexture>;
 export declare type CubeTextureProps = Node<THREE.CubeTexture, typeof THREE.CubeTexture>;

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

@@ -3,11 +3,22 @@ import type { Options as ResizeOptions } from 'react-use-measure';
 import { RenderProps } from '../core';
 export interface CanvasProps extends Omit<RenderProps<HTMLCanvasElement>, 'size'>, React.HTMLAttributes<HTMLDivElement> {
     children: React.ReactNode;
+    /** Canvas fallback content, similar to img's alt prop */
     fallback?: React.ReactNode;
+    /**
+     * Options to pass to useMeasure.
+     * @see https://github.com/pmndrs/react-use-measure#api
+     */
     resize?: ResizeOptions;
+    /** The target where events are being subscribed to, default: the div that wraps canvas */
     eventSource?: HTMLElement | React.MutableRefObject<HTMLElement>;
+    /** The event prefix that is cast into canvas pointer x/y events, default: "offset" */
     eventPrefix?: 'offset' | 'client' | 'page' | 'layer' | 'screen';
 }
 export interface Props extends CanvasProps {
 }
+/**
+ * A DOM canvas which accepts threejs elements as children.
+ * @see https://docs.pmnd.rs/react-three-fiber/api/canvas
+ */
 export declare const Canvas: React.ForwardRefExoticComponent<Props & React.RefAttributes<HTMLCanvasElement>>;

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

@@ -1,4 +1,5 @@
 import { UseBoundStore } from 'zustand';
 import { RootState } from '../core/store';
 import { EventManager } from '../core/events';
+/** Default R3F event manager for web */
 export declare function createPointerEvents(store: UseBoundStore<RootState>): EventManager<HTMLElement>;

package/dist/{index-e6d64601.cjs.prod.js → index-66b6e976.cjs.prod.js}

@@ -127,7 +127,11 @@ function createRenderer(_roots, _getEventPriority) {
         parentInstance.children = [...restSiblings.slice(0, index), child, ...restSiblings.slice(index)];
         added = true;
       }
-      if (!added) (_parentInstance$__r3f2 = parentInstance.__r3f) == null ? void 0 : _parentInstance$__r3f2.objects.push(child);
+      const objects = (_parentInstance$__r3f2 = parentInstance.__r3f) == null ? void 0 : _parentInstance$__r3f2.objects;
+      if (!added && objects) {
+        const index = objects.indexOf(beforeChild);
+        if (index !== -1) objects.splice(index, 0, child);else objects.push(child);
+      }
       if (!child.__r3f) prepare(child, {});
       child.__r3f.parent = parentInstance;
       updateInstance(child);
@@ -143,7 +147,11 @@ function createRenderer(_roots, _getEventPriority) {
       // Clear the parent reference
       if (child.__r3f) child.__r3f.parent = null;
       // Remove child from the parents objects
-      if ((_parentInstance$__r3f3 = parentInstance.__r3f) != null && _parentInstance$__r3f3.objects) parentInstance.__r3f.objects = parentInstance.__r3f.objects.filter(x => x !== child);
+      const objects = (_parentInstance$__r3f3 = parentInstance.__r3f) == null ? void 0 : _parentInstance$__r3f3.objects;
+      if (objects) {
+        const index = objects.indexOf(child);
+        if (index !== -1) objects.splice(index, 1);
+      }
       // Remove attachment
       if ((_child$__r3f3 = child.__r3f) != null && _child$__r3f3.attach) {
         detach(parentInstance, child, child.__r3f.attach);
@@ -209,13 +217,14 @@ function createRenderer(_roots, _getEventPriority) {
     }
     instance.__r3f.objects.forEach(child => appendChild(newInstance, child));
     instance.__r3f.objects = [];
+    const autoRemovedBeforeAppend = !!newInstance.parent;
     if (!instance.__r3f.autoRemovedBeforeAppend) {
+      insertBefore(parent, newInstance, instance);
       removeChild(parent, instance);
+    } else {
+      appendChild(parent, newInstance);
     }
-    if (newInstance.parent) {
-      newInstance.__r3f.autoRemovedBeforeAppend = true;
-    }
-    appendChild(parent, newInstance);
+    newInstance.__r3f.autoRemovedBeforeAppend = autoRemovedBeforeAppend;
 
     // Re-bind event handlers
     if (newInstance.raycast && newInstance.__r3f.eventCount) {

package/dist/{index-d26c5c57.cjs.dev.js → index-9bf2e8aa.cjs.dev.js}

@@ -127,7 +127,11 @@ function createRenderer(_roots, _getEventPriority) {
         parentInstance.children = [...restSiblings.slice(0, index), child, ...restSiblings.slice(index)];
         added = true;
       }
-      if (!added) (_parentInstance$__r3f2 = parentInstance.__r3f) == null ? void 0 : _parentInstance$__r3f2.objects.push(child);
+      const objects = (_parentInstance$__r3f2 = parentInstance.__r3f) == null ? void 0 : _parentInstance$__r3f2.objects;
+      if (!added && objects) {
+        const index = objects.indexOf(beforeChild);
+        if (index !== -1) objects.splice(index, 0, child);else objects.push(child);
+      }
       if (!child.__r3f) prepare(child, {});
       child.__r3f.parent = parentInstance;
       updateInstance(child);
@@ -143,7 +147,11 @@ function createRenderer(_roots, _getEventPriority) {
       // Clear the parent reference
       if (child.__r3f) child.__r3f.parent = null;
       // Remove child from the parents objects
-      if ((_parentInstance$__r3f3 = parentInstance.__r3f) != null && _parentInstance$__r3f3.objects) parentInstance.__r3f.objects = parentInstance.__r3f.objects.filter(x => x !== child);
+      const objects = (_parentInstance$__r3f3 = parentInstance.__r3f) == null ? void 0 : _parentInstance$__r3f3.objects;
+      if (objects) {
+        const index = objects.indexOf(child);
+        if (index !== -1) objects.splice(index, 1);
+      }
       // Remove attachment
       if ((_child$__r3f3 = child.__r3f) != null && _child$__r3f3.attach) {
         detach(parentInstance, child, child.__r3f.attach);
@@ -209,13 +217,14 @@ function createRenderer(_roots, _getEventPriority) {
     }
     instance.__r3f.objects.forEach(child => appendChild(newInstance, child));
     instance.__r3f.objects = [];
+    const autoRemovedBeforeAppend = !!newInstance.parent;
     if (!instance.__r3f.autoRemovedBeforeAppend) {
+      insertBefore(parent, newInstance, instance);
       removeChild(parent, instance);
+    } else {
+      appendChild(parent, newInstance);
     }
-    if (newInstance.parent) {
-      newInstance.__r3f.autoRemovedBeforeAppend = true;
-    }
-    appendChild(parent, newInstance);
+    newInstance.__r3f.autoRemovedBeforeAppend = autoRemovedBeforeAppend;
 
     // Re-bind event handlers
     if (newInstance.raycast && newInstance.__r3f.eventCount) {

package/dist/{index-594193f5.esm.js → index-a2103d81.esm.js}

@@ -100,7 +100,11 @@ function createRenderer(_roots, _getEventPriority) {
         parentInstance.children = [...restSiblings.slice(0, index), child, ...restSiblings.slice(index)];
         added = true;
       }
-      if (!added) (_parentInstance$__r3f2 = parentInstance.__r3f) == null ? void 0 : _parentInstance$__r3f2.objects.push(child);
+      const objects = (_parentInstance$__r3f2 = parentInstance.__r3f) == null ? void 0 : _parentInstance$__r3f2.objects;
+      if (!added && objects) {
+        const index = objects.indexOf(beforeChild);
+        if (index !== -1) objects.splice(index, 0, child);else objects.push(child);
+      }
       if (!child.__r3f) prepare(child, {});
       child.__r3f.parent = parentInstance;
       updateInstance(child);
@@ -116,7 +120,11 @@ function createRenderer(_roots, _getEventPriority) {
       // Clear the parent reference
       if (child.__r3f) child.__r3f.parent = null;
       // Remove child from the parents objects
-      if ((_parentInstance$__r3f3 = parentInstance.__r3f) != null && _parentInstance$__r3f3.objects) parentInstance.__r3f.objects = parentInstance.__r3f.objects.filter(x => x !== child);
+      const objects = (_parentInstance$__r3f3 = parentInstance.__r3f) == null ? void 0 : _parentInstance$__r3f3.objects;
+      if (objects) {
+        const index = objects.indexOf(child);
+        if (index !== -1) objects.splice(index, 1);
+      }
       // Remove attachment
       if ((_child$__r3f3 = child.__r3f) != null && _child$__r3f3.attach) {
         detach(parentInstance, child, child.__r3f.attach);
@@ -182,13 +190,14 @@ function createRenderer(_roots, _getEventPriority) {
     }
     instance.__r3f.objects.forEach(child => appendChild(newInstance, child));
     instance.__r3f.objects = [];
+    const autoRemovedBeforeAppend = !!newInstance.parent;
     if (!instance.__r3f.autoRemovedBeforeAppend) {
+      insertBefore(parent, newInstance, instance);
       removeChild(parent, instance);
+    } else {
+      appendChild(parent, newInstance);
     }
-    if (newInstance.parent) {
-      newInstance.__r3f.autoRemovedBeforeAppend = true;
-    }
-    appendChild(parent, newInstance);
+    newInstance.__r3f.autoRemovedBeforeAppend = autoRemovedBeforeAppend;
 
     // Re-bind event handlers
     if (newInstance.raycast && newInstance.__r3f.eventCount) {

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

@@ -2,7 +2,7 @@
 
 Object.defineProperty(exports, '__esModule', { value: true });
 
-var index = require('./index-d26c5c57.cjs.dev.js');
+var index = require('./index-9bf2e8aa.cjs.dev.js');
 var _extends = require('@babel/runtime/helpers/extends');
 var React = require('react');
 var THREE = require('three');

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

@@ -2,7 +2,7 @@
 
 Object.defineProperty(exports, '__esModule', { value: true });
 
-var index = require('./index-e6d64601.cjs.prod.js');
+var index = require('./index-66b6e976.cjs.prod.js');
 var _extends = require('@babel/runtime/helpers/extends');
 var React = require('react');
 var THREE = require('three');

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

@@ -1,5 +1,5 @@
-import { c as createEvents, e as extend, u as useMutableCallback, a as useIsomorphicLayoutEffect, b as createRoot, i as isRef, E as ErrorBoundary, B as Block, d as unmountComponentAtNode } from './index-594193f5.esm.js';
-export { t as ReactThreeFiber, x as _roots, v as act, o as addAfterEffect, n as addEffect, p as addTail, m as advance, j as applyProps, w as buildGraph, f as context, c as createEvents, g as createPortal, b as createRoot, k as dispose, e as extend, q as flushGlobalEffects, s as getRootState, l as invalidate, h as reconciler, r as render, d as unmountComponentAtNode, C as useFrame, D as useGraph, y as useInstanceHandle, F as useLoader, z as useStore, A as useThree } from './index-594193f5.esm.js';
+import { c as createEvents, e as extend, u as useMutableCallback, a as useIsomorphicLayoutEffect, b as createRoot, i as isRef, E as ErrorBoundary, B as Block, d as unmountComponentAtNode } from './index-a2103d81.esm.js';
+export { t as ReactThreeFiber, x as _roots, v as act, o as addAfterEffect, n as addEffect, p as addTail, m as advance, j as applyProps, w as buildGraph, f as context, c as createEvents, g as createPortal, b as createRoot, k as dispose, e as extend, q as flushGlobalEffects, s as getRootState, l as invalidate, h as reconciler, r as render, d as unmountComponentAtNode, C as useFrame, D as useGraph, y as useInstanceHandle, F as useLoader, z as useStore, A as useThree } from './index-a2103d81.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-d26c5c57.cjs.dev.js');
+var index = require('../../dist/index-9bf2e8aa.cjs.dev.js');
 var _extends = require('@babel/runtime/helpers/extends');
 var React = require('react');
 var THREE = require('three');
@@ -345,7 +345,7 @@ async function getAsset(input) {
 }
 function polyfills() {
   // Patch Blob for ArrayBuffer and URL if unsupported
-  // https://github.com/pmndrs/react-three-fiber/pull/3059
+  // https://github.com/facebook/react-native/pull/39276
   // https://github.com/pmndrs/react-three-fiber/issues/3058
   if (reactNative.Platform.OS !== 'web') {
     try {

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-e6d64601.cjs.prod.js');
+var index = require('../../dist/index-66b6e976.cjs.prod.js');
 var _extends = require('@babel/runtime/helpers/extends');
 var React = require('react');
 var THREE = require('three');
@@ -345,7 +345,7 @@ async function getAsset(input) {
 }
 function polyfills() {
   // Patch Blob for ArrayBuffer and URL if unsupported
-  // https://github.com/pmndrs/react-three-fiber/pull/3059
+  // https://github.com/facebook/react-native/pull/39276
   // https://github.com/pmndrs/react-three-fiber/issues/3058
   if (reactNative.Platform.OS !== 'web') {
     try {

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

@@ -1,5 +1,5 @@
-import { c as createEvents, e as extend, u as useMutableCallback, b as createRoot, E as ErrorBoundary, B as Block, d as unmountComponentAtNode } from '../../dist/index-594193f5.esm.js';
-export { t as ReactThreeFiber, x as _roots, v as act, o as addAfterEffect, n as addEffect, p as addTail, m as advance, j as applyProps, w as buildGraph, f as context, c as createEvents, g as createPortal, b as createRoot, k as dispose, e as extend, q as flushGlobalEffects, s as getRootState, l as invalidate, h as reconciler, r as render, d as unmountComponentAtNode, C as useFrame, D as useGraph, y as useInstanceHandle, F as useLoader, z as useStore, A as useThree } from '../../dist/index-594193f5.esm.js';
+import { c as createEvents, e as extend, u as useMutableCallback, b as createRoot, E as ErrorBoundary, B as Block, d as unmountComponentAtNode } from '../../dist/index-a2103d81.esm.js';
+export { t as ReactThreeFiber, x as _roots, v as act, o as addAfterEffect, n as addEffect, p as addTail, m as advance, j as applyProps, w as buildGraph, f as context, c as createEvents, g as createPortal, b as createRoot, k as dispose, e as extend, q as flushGlobalEffects, s as getRootState, l as invalidate, h as reconciler, r as render, d as unmountComponentAtNode, C as useFrame, D as useGraph, y as useInstanceHandle, F as useLoader, z as useStore, A as useThree } from '../../dist/index-a2103d81.esm.js';
 import _extends from '@babel/runtime/helpers/esm/extends';
 import * as React from 'react';
 import * as THREE from 'three';
@@ -320,7 +320,7 @@ async function getAsset(input) {
 }
 function polyfills() {
   // Patch Blob for ArrayBuffer and URL if unsupported
-  // https://github.com/pmndrs/react-three-fiber/pull/3059
+  // https://github.com/facebook/react-native/pull/39276
   // https://github.com/pmndrs/react-three-fiber/issues/3058
   if (Platform.OS !== 'web') {
     try {

package/package.json

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