@react-three/fiber 9.7.0 → 9.8.1

package/CHANGELOG.md

@@ -1,5 +1,56 @@
 # @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
+
+- 4ae2f816543f21e72b38d3e1328a21fc312428c1: Support React 19.3. Transitions that touch a `<ViewTransition>` subtree inside the canvas now commit synchronously, mirroring react-dom in browsers without view transitions, instead of leaving the reconciler stuck mid-commit.
+- bc240cc56dbb0162737b2df0e99077c889d7cf2e: feat: configure and render roots synchronously; suspend on async renderers.
+
+  `root.configure()` now runs synchronously unless `gl` is an async factory (WebGPU), and the first `root.render()` mounts synchronously once the root is configured; later renders are batched as before. The returned promises carry a `status` field that React's `use` reads, and every root exposes `ready`, which is pending only while an async renderer is being created.
+
+  `<Canvas>` uses this to commit its scene inside its own layout effect, so `onCreated` runs while the wrapper is mounted and the events are connected before the browser paints. With an async renderer the canvas suspends on `root.ready` internally, without showing a parent fallback, and mounts once it resolves. Unmounting meanwhile never renders the scene. A renderer factory that fails now reaches the nearest error boundary instead of an unhandled rejection.
+
+  Configure calls made while another is in flight are applied after it, in order. The `flushSync` caveats apply to that first `root.render()` when it is called from inside another root's commit.
+
+### Patch Changes
+
+- f0f1cdf4336519a988faadae7f8607bc0cd8d7e2: fix: unmount roots deterministically instead of after a 500ms timer.
+
+  `unmountComponentAtNode` deferred disposal by 500ms. A `<StrictMode>` remount lands inside that window and reuses the same root, store, scene and GL context, so the deferred callback destroyed a live root. `forceContextLoss()` is permanent, which left the canvas blank for the rest of the session.
+
+  Unmounting now claims the root and runs the teardown through React once the unmounted tree's effect cleanups have flushed. Using the root again through `configure` or `render` before then cancels it. A root that is unmounted, remounted and unmounted again is torn down exactly once.
+
+- bc240cc56dbb0162737b2df0e99077c889d7cf2e: fix: don't resurrect a `<Canvas>` root that unmounts before its render settles.
+
+  `<Canvas>` configured its root asynchronously. When the canvas was unmounted between that effect and the microtasks it queued, for example by a spring reparenting it through a synchronous state update from a layout effect, the stale continuation still rendered into the torn-down root. Its Provider then mounted again and called `events.connect` with the unmounted wrapper `div`, throwing `Cannot read properties of null (reading 'addEventListener')`, and the resurrected root leaked a live WebGL context.
+
+  The scene now commits inside the canvas' own commit, a deferred render bails once the root is claimed for teardown, and `unmountComponentAtNode` waits for a configure still in flight so the renderer it creates is disposed rather than orphaned.
+
 ## 9.7.0
 
 ### Minor Changes

package/dist/declarations/react-reconciler/index.d.ts

@@ -610,7 +610,8 @@ declare namespace ReactReconciler {
     type LanePriority = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17;
 
     type Lanes = number;
-    type Lane = number;
+
+    type Lane = number & { __LaneBrand: any };
 
     type Flags = number;
 
@@ -941,7 +942,6 @@ declare namespace ReactReconciler {
             onCaughtError: (error: Error, info: BaseErrorInfo) => void,
             onRecoverableError: (error: Error, info: BaseErrorInfo) => void,
             onDefaultTransitionIndicator: () => void,
-            transitionCallbacks: null | TransitionTracingCallbacks,
         ): OpaqueRoot;
 
         createPortal(
@@ -951,8 +951,6 @@ declare namespace ReactReconciler {
             key?: string | null,
         ): ReactPortal;
 
-        registerMutableSourceForHydration(root: FiberRoot, mutableSource: MutableSource): void;
-
         createComponentSelector(component: React$AbstractComponent<never, unknown>): ComponentSelector;
 
         createHasPseudoClassSelector(selectors: Selector[]): HasPseudoClassSelector;
@@ -987,8 +985,12 @@ declare namespace ReactReconciler {
             isStrictMode: boolean,
             concurrentUpdatesByDefaultOverride: null | boolean,
             identifierPrefix: string,
-            onRecoverableError: (error: Error) => void,
+            onUncaughtError: (error: Error, info: BaseErrorInfo & { errorBoundary?: Component }) => void,
+            onCaughtError: (error: Error, info: BaseErrorInfo) => void,
+            onRecoverableError: (error: Error, info: BaseErrorInfo) => void,
+            onDefaultTransitionIndicator: () => void,
             transitionCallbacks: null | TransitionTracingCallbacks,
+            formState: unknown,
         ): OpaqueRoot;
 
         updateContainer(
@@ -998,17 +1000,27 @@ declare namespace ReactReconciler {
             callback?: (() => void) | null,
         ): Lane;
 
+        updateContainerSync(
+            element: ReactNode,
+            container: OpaqueRoot,
+            parentComponent?: Component<any, any> | null,
+            callback?: (() => void) | null,
+        ): Lane;
+
         batchedUpdates<A, R>(fn: (a: A) => R, a: A): R;
 
         deferredUpdates<A>(fn: () => A): A;
 
         discreteUpdates<A, B, C, D, R>(fn: (arg0: A, arg1: B, arg2: C, arg3: D) => R, a: A, b: B, c: C, d: D): R;
 
-        flushControlled(fn: () => any): void;
-
         flushSync(): void;
         flushSync<R>(fn: () => R): R;
 
+        flushSyncFromReconciler(): void;
+        flushSyncFromReconciler<R>(fn: () => R): R;
+
+        flushSyncWork(): boolean;
+
         isAlreadyRendering(): boolean;
 
         flushPassiveEffects(): boolean;
@@ -1017,16 +1029,10 @@ declare namespace ReactReconciler {
 
         attemptSynchronousHydration(fiber: Fiber): void;
 
-        attemptDiscreteHydration(fiber: Fiber): void;
-
         attemptContinuousHydration(fiber: Fiber): void;
 
         attemptHydrationAtCurrentPriority(fiber: Fiber): void;
 
-        getCurrentUpdatePriority(): LanePriority;
-
-        runWithPriority<T>(priority: LanePriority, fn: () => T): T;
-
         findHostInstance(component: any): PublicInstance | null;
 
         findHostInstanceWithWarning(component: any, methodName: string): PublicInstance | null;
@@ -1039,6 +1045,17 @@ declare namespace ReactReconciler {
 
         injectIntoDevTools(devToolsConfig: DevToolsConfig<Instance, TextInstance, any>): boolean;
     }
+
+    function defaultOnUncaughtError(error: Error): void;
+    function defaultOnCaughtError(error: Error): void;
+    function defaultOnRecoverableError(error: Error): void;
+
+    function startHostTransition(
+        formFiber: Fiber,
+        pendingState: unknown,
+        action: ((formData: FormData) => void) | null,
+        formData: FormData,
+    ): void;
 }
 
 export = ReactReconciler;

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

@@ -1,13 +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 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;
 };
@@ -29,7 +26,7 @@ export interface RenderProps<TCanvas extends HTMLCanvasElement | OffscreenCanvas
     shadows?: boolean | 'basic' | 'percentage' | 'soft' | 'variance' | Partial<THREE.WebGLShadowMap>;
     /**
      * Disables three r139 color management.
-     * @see https://threejs.org/docs/#manual/en/introduction/Color-management
+     * @see https://threejs.org/manual/#en/color-management
      */
     legacy?: boolean;
     /** Switch off automatic sRGB encoding and gamma correction */
@@ -63,27 +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> {
-    configure: (config?: RenderProps<TCanvas>) => Promise<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,10 +4,14 @@ 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";
 export { applyProps, getRootState, dispose, act, buildGraph } from "./utils.js";
+export type { TrackedPromise } from "./promise.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

@@ -0,0 +1,19 @@
+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';
+} | {
+    status: 'fulfilled';
+    value: T;
+} | {
+    status: 'rejected';
+    reason: unknown;
+});
+export declare const fulfilled: <T>(value: T) => TrackedPromise<T>;
+export declare const rejected: <T>(reason: unknown) => 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

@@ -5,10 +5,6 @@ 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;
-}
 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;
@@ -42,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

@@ -39,11 +39,14 @@ export declare const isColorRepresentation: (value: unknown) => value is THREE.C
  */
 export declare const useIsomorphicLayoutEffect: typeof React.useLayoutEffect;
 export declare function useMutableCallback<T>(fn: T): React.RefObject<T>;
+export declare const noop: () => void;
+/** Waits for a promise in a null subtree, re-rendering the caller once it settles either way. */
+export declare function useGate(): [gate: React.ReactNode, waitFor: (promise: PromiseLike<unknown>) => void];
 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;

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

@@ -10,4 +10,4 @@ export interface CanvasProps extends Omit<RenderProps<HTMLCanvasElement>, 'size'
  * A native canvas which accepts threejs elements as children.
  * @see https://docs.pmnd.rs/react-three-fiber/api/canvas
  */
-export declare function Canvas(props: CanvasProps): import("react/jsx-runtime").JSX.Element;
+export declare function Canvas(props: CanvasProps): React.JSX.Element;

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

@@ -12,7 +12,7 @@ export interface CanvasProps extends Omit<RenderProps<HTMLCanvasElement>, 'size'
      */
     resize?: ResizeOptions;
     /** The target where events are being subscribed to, default: the div that wraps canvas */
-    eventSource?: HTMLElement | React.RefObject<HTMLElement>;
+    eventSource?: HTMLElement | React.RefObject<HTMLElement | null>;
     /** The event prefix that is cast into canvas pointer x/y events, default: "offset" */
     eventPrefix?: 'offset' | 'client' | 'page' | 'layer' | 'screen';
 }
@@ -20,4 +20,4 @@ export interface CanvasProps extends Omit<RenderProps<HTMLCanvasElement>, 'size'
  * A DOM canvas which accepts threejs elements as children.
  * @see https://docs.pmnd.rs/react-three-fiber/api/canvas
  */
-export declare function Canvas(props: CanvasProps): import("react/jsx-runtime").JSX.Element;
+export declare function Canvas(props: CanvasProps): React.JSX.Element;