@react-three/fiber 9.8.0 → 9.8.1

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # @react-three/fiber
 
+## 9.8.1
+
+### Patch Changes
+
+- 2bcc153b52213535e2149d70f6c01d7dcaee58a2: fix: keep a Canvas root alive while `<Activity>` hides it.
+
+  React destroys a hidden `<Activity>` tree's effects but keeps its DOM. The Canvas unmounted its root in that effect cleanup, which lost the WebGL context and disposed the scene. When the tree was shown again, the Canvas still held the unmounted root and stayed blank.
+
+  Canvas now keeps its renderer and scene state while hidden. A Canvas removed while hidden still releases its renderer.
+
+- 138bfb0055a2534103686454c5e1f22bcdbf4537: Canvas and `root.configure()` now apply only the configuration props that changed. Runtime changes made through setters such as `setFrameloop`, or directly to `gl.shadowMap`, last through rerenders and resizes until their prop changes. The pixel ratio still follows `dpr` and the device pixel ratio on every render. Inline option objects compare by value. Changing `flat` or `linear` after creation now updates the renderer, unless `gl` sets `toneMapping` or `outputColorSpace` explicitly.
+
+  Configuration applies in call order, including calls made from a renderer factory or a store subscriber while another configuration is running.
+
+- e0e9c2dbb5b9f1567f43ffe97205d29a4094028a: Update its-fine to 2.1.1 and bridge ancestor Activity visibility into the Canvas scene on React 19.2 and later. Hiding an Activity disconnects scene effects and useFrame subscriptions; revealing it reconnects them without resetting scene state. Keep the existing context and StrictMode bridges, and fall back to their previous behavior on React 19.0 and 19.1.
+- 9ac75626b2191c65698d3bfb27c2e43d6e3c8891: fix: dispose the renderer R3F creates when its root unmounts.
+
+  Teardown only called `forceContextLoss()`, never `dispose()`. A `WebGPURenderer` built in a `gl` factory, which has no `forceContextLoss`, was never released at all: its GPU device and every allocation on it outlived the canvas. A `WebGLRenderer` lost its context while three's listener was still attached, which logged `THREE.WebGLRenderer: Context Lost.` on every unmount.
+
+  A renderer R3F builds, from its defaults, a props object or a factory, is now disposed, and then its context is lost. A renderer passed in as an instance keeps its previous teardown. Each teardown step now runs on its own, so one that throws no longer skips the rest.
+
+- 8965ba4f05eab91c605fe0dfaaa58453c1ede7c9: Preserve an object's visibility across Activity and Suspense hiding. Visibility prop changes made while hidden take effect when the object is shown.
+- 9ac75626b2191c65698d3bfb27c2e43d6e3c8891: Model root teardown with explicit open, closing, disposing, and disposed states. Allow pending unmounts to be cancelled, wait for React cleanups and queued configuration before disposing, and prevent disposed root handles from configuring or unmounting replacement roots. Complete teardown callbacks after asynchronous renderer disposal settles, and release the context even if renderer disposal fails.
+
 ## 9.8.0
 
 ### Minor Changes

package/dist/declarations/src/core/{renderer.d.ts → configuration.d.ts}

@@ -1,14 +1,10 @@
-import * as React from 'react';
 import * as THREE from 'three';
 import type { ThreeElement } from "../three-types.js";
-import { ComputeFunction, EventManager } from "./events.js";
-import { Root } from "./reconciler.js";
-import { Dpr, Frameloop, Performance, Renderer, RootState, RootStore, Size } from "./store.js";
-import { type Properties, Camera } from "./utils.js";
-import { TrackedPromise } from "./promise.js";
+import type { EventManager } from "./events.js";
+import { type Dpr, type Frameloop, type Performance, type Renderer, type RootState, type RootStore, type Size } from "./store.js";
+import { type Camera, type Properties } from "./utils.js";
 interface OffscreenCanvas extends EventTarget {
 }
-export declare const _roots: Map<HTMLCanvasElement | OffscreenCanvas, Root>;
 export type DefaultGLProps = Omit<THREE.WebGLRendererParameters, 'canvas'> & {
     canvas: HTMLCanvasElement | OffscreenCanvas;
 };
@@ -64,28 +60,25 @@ export interface RenderProps<TCanvas extends HTMLCanvasElement | OffscreenCanvas
     /** Response for pointer clicks that have missed any target */
     onPointerMissed?: (event: MouseEvent) => void;
 }
-export interface ReconcilerRoot<TCanvas extends HTMLCanvasElement | OffscreenCanvas> {
-    ready: TrackedPromise<unknown>;
-    configure: (config?: RenderProps<TCanvas>) => TrackedPromise<ReconcilerRoot<TCanvas>>;
-    render: (element: React.ReactNode) => RootStore;
-    unmount: () => void;
+type Canvas = DefaultGLProps['canvas'];
+export type Configuration = RenderProps<Canvas>;
+/** What a root has applied, so its next configuration applies only what changed */
+export interface AppliedConfiguration {
+    /** The last configuration applied in full */
+    previous?: Configuration;
+    /** The camera prop that set the current camera */
+    camera?: Configuration['camera'];
 }
-export declare function createRoot<TCanvas extends HTMLCanvasElement | OffscreenCanvas>(canvas: TCanvas): ReconcilerRoot<TCanvas>;
-export declare function unmountComponentAtNode<TCanvas extends HTMLCanvasElement | OffscreenCanvas>(canvas: TCanvas, callback?: (canvas: TCanvas) => void): void;
-export type InjectState = Partial<Omit<RootState, 'events'> & {
-    events?: {
-        enabled?: boolean;
-        priority?: number;
-        compute?: ComputeFunction;
-        connected?: any;
-    };
-}>;
-export declare function createPortal(children: React.ReactNode, container: THREE.Object3D, state?: InjectState): React.JSX.Element;
+/** The renderer to configure, or a promise for one from an async factory */
+export declare function createRenderer(canvas: Canvas, gl?: GLProps): Renderer | PromiseLike<Renderer>;
 /**
- * Force React to flush any updates inside the provided callback synchronously and immediately.
- * All the same caveats documented for react-dom's `flushSync` apply here (see https://react.dev/reference/react-dom/flushSync).
- * Nevertheless, sometimes one needs to render synchronously, for example to keep DOM and 3D changes in lock-step without
- * having to revert to a non-React solution. Note: this will only flush updates within the `Canvas` root.
+ * Applies the inputs that changed since the last configuration applied in full, to a root whose
+ * renderer is installed. A runtime change, such as setFrameloop or an edit to gl.shadowMap, lasts
+ * until its input changes. The pixel ratio instead follows the device on every call. Objects and
+ * arrays compare shallowly, so an equal inline value is unchanged.
  */
-export declare function flushSync<R>(fn: () => R): R;
+export declare function applyRootConfiguration({ store, configuration }: {
+    store: RootStore;
+    configuration: AppliedConfiguration;
+}, canvas: Canvas, props: Configuration): void;
 export {};

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

@@ -4,9 +4,12 @@ export * from "./hooks.js";
 export type { GlobalRenderCallback, GlobalEffectType } from "./loop.js";
 export { flushGlobalEffects, addEffect, addAfterEffect, addTail, invalidate, advance } from "./loop.js";
 export type { AttachFnType, AttachType, ConstructorRepresentation, Catalogue, Args, InstanceProps, Instance, } from "./reconciler.js";
-export { extend, reconciler } from "./reconciler.js";
-export type { ReconcilerRoot, GLProps, CameraProps, RenderProps, InjectState } from "./renderer.js";
-export { _roots, createRoot, unmountComponentAtNode, createPortal, flushSync } from "./renderer.js";
+export { extend, reconciler, flushSync } from "./reconciler.js";
+export type { GLProps, CameraProps, RenderProps } from "./configuration.js";
+export type { ReconcilerRoot } from "./root.js";
+export { _roots, createRoot, unmountComponentAtNode } from "./root.js";
+export type { InjectState } from "./portal.js";
+export { createPortal } from "./portal.js";
 export type { Subscription, Dpr, Size, Viewport, RenderCallback, Frameloop, Performance, Renderer, XRManager, RootState, RootStore, } from "./store.js";
 export { context } from "./store.js";
 export type { ObjectMap, Camera, Disposable, Act } from "./utils.js";

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

@@ -0,0 +1,13 @@
+import * as React from 'react';
+import * as THREE from 'three';
+import type { ComputeFunction } from "./events.js";
+import { type RootState } from "./store.js";
+export type InjectState = Partial<Omit<RootState, 'events'> & {
+    events?: {
+        enabled?: boolean;
+        priority?: number;
+        compute?: ComputeFunction;
+        connected?: any;
+    };
+}>;
+export declare function createPortal(children: React.ReactNode, container: THREE.Object3D, state?: InjectState): React.JSX.Element;

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

@@ -1,4 +1,4 @@
-export declare const isPromiseLike: (value: unknown) => value is PromiseLike<unknown>;
+export declare const isPromiseLike: <T>(value: T | PromiseLike<T>) => value is PromiseLike<T>;
 /** A promise tagged with its state, the protocol React's `use` reads */
 export type TrackedPromise<T> = Promise<T> & ({
     status: 'pending';
@@ -11,5 +11,9 @@ export type TrackedPromise<T> = Promise<T> & ({
 });
 export declare const fulfilled: <T>(value: T) => TrackedPromise<T>;
 export declare const rejected: <T>(reason: unknown) => TrackedPromise<T>;
-/** Tags `promise` in place once it settles. */
-export declare const tracked: <T>(promise: PromiseLike<T>) => TrackedPromise<T>;
+/** A pending promise, settled once from outside. Its `status` updates the moment it settles */
+export declare const deferred: <T>() => {
+    promise: TrackedPromise<T>;
+    resolve: (_value: T) => void;
+    reject: (_reason: unknown) => void;
+};

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

@@ -1,18 +1,10 @@
 import * as THREE from 'three';
 import * as React from 'react';
 import Reconciler from '../../react-reconciler/index.js';
-import type { TrackedPromise } from "./promise.js";
 import { IsAllOptional } from "./utils.js";
 import type { RootStore } from "./store.js";
 import { type EventHandlers } from "./events.js";
 import type { ThreeElement } from "../three-types.js";
-export interface Root {
-    fiber: Reconciler.FiberRoot;
-    store: RootStore;
-    unmountClaim: symbol | null;
-    /** Pending only while an async renderer is being created */
-    ready: TrackedPromise<unknown>;
-}
 export type AttachFnType<O = any> = (parent: any, self: O) => () => void;
 export type AttachType<O = any> = string | AttachFnType<O>;
 export type ConstructorRepresentation<T = any> = new (...args: any[]) => T;
@@ -46,9 +38,17 @@ export interface Instance<O = any> {
     handlers: Partial<EventHandlers>;
     attach?: AttachType<O>;
     previousAttach?: any;
+    previousVisible: boolean | undefined;
     isHidden: boolean;
 }
 export declare function extend<T extends ConstructorRepresentation>(objects: T): React.ExoticComponent<ThreeElement<T>>;
 export declare function extend<T extends Catalogue>(objects: T): void;
 export declare const reconciler: Reconciler.Reconciler<RootStore, Instance<any>, void, Instance<any>, never, any>;
+/**
+ * Force React to flush any updates inside the provided callback synchronously and immediately.
+ * All the same caveats documented for react-dom's `flushSync` apply here (see https://react.dev/reference/react-dom/flushSync).
+ * Nevertheless, sometimes one needs to render synchronously, for example to keep DOM and 3D changes in lock-step without
+ * having to revert to a non-React solution. Note: this will only flush updates within the `Canvas` root.
+ */
+export declare function flushSync<R>(fn: () => R): R;
 export {};

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

@@ -0,0 +1,35 @@
+import * as React from 'react';
+import type Reconciler from '../../react-reconciler/index.js';
+import { type AppliedConfiguration, type RenderProps } from "./configuration.js";
+import { type TrackedPromise } from "./promise.js";
+import { type RootStore } from "./store.js";
+interface OffscreenCanvas extends EventTarget {
+}
+export interface Root {
+    fiber: Reconciler.FiberRoot;
+    store: RootStore;
+    state: RootStateMachine;
+    /** Settles once all accepted configuration has been applied */
+    ready: TrackedPromise<unknown>;
+    configuration: AppliedConfiguration;
+    /** Whether R3F built `gl` (from defaults, props or a factory) and so disposes it on unmount */
+    ownsRenderer: boolean;
+}
+export declare const _roots: Map<HTMLCanvasElement | OffscreenCanvas, Root>;
+export type RootStateMachine = {
+    status: 'open';
+} | {
+    status: 'closing';
+    token: symbol;
+} | {
+    status: 'disposed';
+};
+export interface ReconcilerRoot<TCanvas extends HTMLCanvasElement | OffscreenCanvas> {
+    ready: TrackedPromise<unknown>;
+    configure: (config?: RenderProps<TCanvas>) => TrackedPromise<ReconcilerRoot<TCanvas>>;
+    render: (element: React.ReactNode) => RootStore;
+    unmount: () => void;
+}
+export declare function createRoot<TCanvas extends HTMLCanvasElement | OffscreenCanvas>(canvas: TCanvas): ReconcilerRoot<TCanvas>;
+export declare function unmountComponentAtNode<TCanvas extends HTMLCanvasElement | OffscreenCanvas>(canvas: TCanvas, callback?: (canvas: TCanvas) => void): void;
+export {};

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

@@ -46,7 +46,7 @@ export type Bridge = React.FC<{
     children?: React.ReactNode;
 }>;
 /**
- * Bridges renderer Context and StrictMode from a primary renderer.
+ * Bridges Context, StrictMode, and Activity visibility from a primary renderer.
  */
 export declare function useBridge(): Bridge;
 export type SetBlock = false | Promise<null> | null;