@react-three/fiber 10.0.0-canary.9b237a7 → 10.0.0-canary.a1c1d93

package/dist/shared/{fiber.Bw8YnGg5.d.mts → fiber.CLTHZhZp.d.mts}

@@ -1,7 +1,7 @@
 import { FrameTimingState, FrameCallback as FrameCallback$1, SchedulerApi } from '@pmndrs/scheduler';
-import * as React from 'react';
 import * as THREE from 'three';
-import { WebGLRenderer, WebGLRenderTarget } from 'three';
+import { WebGLRenderer, WebGLRenderTarget, Color, ColorRepresentation } from 'three';
+import * as React from 'react';
 import * as ThreeWebGPU from 'three/webgpu';
 import { WebGPURenderer, RenderTarget, CanvasTarget } from 'three/webgpu';
 import { StoreApi } from 'zustand';
@@ -477,6 +477,11 @@ interface InternalState {
    * Selected once, from the entry's provider, and copied into portals with the rest of `internal`.
    */
   support: R3FRendererSupport
+  /**
+   * Releases this root's lease on its renderer. The last release disposes a renderer R3F created;
+   * a renderer passed in as an instance is never disposed by R3F.
+   */
+  releaseRenderer?: () => void | Promise<void>
   /** Global scheduler reference (for useFrame hook) */
   scheduler: SchedulerApi | null
   /**
@@ -489,6 +494,8 @@ interface InternalState {
   rootId?: string
   /** Function to unregister this root from the global scheduler */
   unregisterRoot?: () => void
+  /** Function to stop following devicePixelRatio changes */
+  unwatchDpr?: () => void
   /** Container for child attachment (scene for root, original container for portals) */
   container?: THREE.Object3D
   /**
@@ -530,6 +537,12 @@ interface InternalState {
    * Only set when isSecondary is true.
    */
   targetId?: string
+  /**
+   * This secondary stopped sharing because the primary's renderer fell back to its
+   * WebGL2 backend (#3965): it owns the renderer it constructed, so it is not
+   * `isSecondary` (which marks a canvas borrowing another's renderer).
+   */
+  sharedRendererFallback?: boolean
   /**
    * Function to unregister this primary canvas from the registry.
    * Only set when this canvas has an `id` prop.
@@ -654,6 +667,91 @@ interface RootState {
 
 type RootStore = UseBoundStoreWithEqualityFn<StoreApi<RootState>>
 
+//* Reconciler Types ==============================
+
+// FiberRoot is an opaque internal React type - we define it locally
+// to avoid bundling @types/react-reconciler which causes absolute path issues
+type FiberRoot = any
+
+/** A promise tagged with its state, the protocol React's `use` reads */
+type TrackedPromise<T> = Promise<T> &
+  ({ status: 'pending' } | { status: 'fulfilled'; value: T } | { status: 'rejected'; reason: unknown })
+
+interface Root {
+  fiber: FiberRoot
+  store: RootStore
+  /** Set while a teardown waits on React. Configure and render clear it, which cancels the teardown */
+  unmountClaim: symbol | null
+  /** Pending only while a renderer is being created */
+  ready: TrackedPromise<unknown>
+}
+
+type AttachFnType<O = any> = (parent: any, self: O) => () => void
+type AttachType<O = any> = string | AttachFnType<O>
+
+type ConstructorRepresentation<T = any> = new (...args: any[]) => T
+
+interface Catalogue {
+  [name: string]: ConstructorRepresentation
+}
+
+// TODO: handle constructor overloads
+// https://github.com/pmndrs/react-three-fiber/pull/2931
+// https://github.com/microsoft/TypeScript/issues/37079
+type Args<T> = T extends ConstructorRepresentation
+  ? T extends typeof Color
+    ? [r: number, g: number, b: number] | [color: ColorRepresentation]
+    : ConstructorParameters<T>
+  : any[]
+
+type ArgsProp<P> = P extends ConstructorRepresentation
+  ? IsAllOptional<ConstructorParameters<P>> extends true
+    ? { args?: Args<P> }
+    : { args: Args<P> }
+  : { args: unknown[] }
+
+type InstanceProps<T = any, P = any> = ArgsProp<P> & {
+  object?: T
+  dispose?: null
+  attach?: AttachType<T>
+}
+
+interface Instance<O = any> {
+  root: RootStore
+  type: string
+  parent: Instance | null
+  children: Instance[]
+  props: InstanceProps<O> & Record<string, unknown>
+  object: O & { __r3f?: Instance<O> }
+  eventCount: number
+  handlers: Partial<EventHandlers>
+  attach?: AttachType<O>
+  previousAttach?: any
+  isHidden: boolean
+  /** Set of props that have been applied via once() */
+  appliedOnce?: Set<string>
+}
+
+interface HostConfig {
+  type: string
+  props: Instance['props']
+  container: RootStore
+  instance: Instance
+  textInstance: void
+  suspenseInstance: Instance
+  hydratableInstance: never
+  formInstance: never
+  publicInstance: Instance['object']
+  hostContext: {}
+  childSet: never
+  timeoutHandle: number | undefined
+  noTimeout: -1
+  TransitionStatus: null
+}
+declare global {
+  var IS_REACT_ACT_ENVIRONMENT: boolean | undefined
+}
+
 interface RootExtension {
     /** Unique name. Registering the same name again replaces the entry (HMR-safe); roots it already
      *  set up are not set up a second time, but get the new entry's dispose and hmr. */
@@ -695,7 +793,14 @@ declare function useStore(): RootStore;
  */
 declare function useThree<T = RootState>(selector?: (state: RootState) => T, equalityFn?: <T>(state: T, newState: T) => boolean): T;
 
+/**
+ * React context that carries the current root's {@link RootStore}. Each root provides its store and
+ * each portal provides its own scoped one; `useStore`, and every hook built on it, reads it.
+ *
+ * Stored on `globalThis` under `Symbol.for('@react-three/fiber.context')`, so every copy and entry
+ * of fiber shares a single context.
+ */
 declare const context: React.Context<RootStore>;
 
-export { useStore as a2, context as a3, useThree as a7, registerRootExtension as r, setRenderOverride as s };
-export type { ForRegisteredRenderer as $, Act as A, Bridge as B, Camera as C, Dpr as D, Events as E, Frameloop as F, FrameCallback as G, ThreeNamespace as H, Intersection as I, ThreeCore as J, OcclusionSupport as K, WebGPUSupport as L, Mutable as M, NonFunctionKeys as N, Overwrite as O, PointerState as P, RendererSupport as Q, RootExtension as R, Subscription as S, ThreeEvent as T, UnblockProps as U, Viewport as V, WebGLSupport as W, XRManager as X, RendererProvider as Y, Register as Z, RegisteredRenderer as _, Size as a, R3FRenderTarget as a0, R3FRendererSupport as a1, R3FRenderer as a4, InternalState as a5, RootState as a6, RenderCallback as b, Performance as c, RootStore as d, IntersectionEvent as e, DomEvent as f, EventHandlers as g, FilterFunction as h, ComputeFunction as i, XRPointerConfig as j, EventManager as k, PointerCaptureTarget as l, VisibilityEntry as m, Properties as n, IsOptional as o, IsAllOptional as p, ThreeCamera as q, SetBlock as t, ObjectMap as u, EquConfig as v, Disposable as w, FrameNextState as x, FrameState as y, FrameNextCallback as z };
+export { useStore as ah, useThree as ai, context as aj, registerRootExtension as r, setRenderOverride as s };
+export type { ObjectMap as $, AttachFnType as A, ArgsProp as B, ConstructorRepresentation as C, Dpr as D, Events as E, Frameloop as F, InstanceProps as G, Instance as H, InternalState as I, HostConfig as J, Properties as K, IsOptional as L, Mutable as M, NonFunctionKeys as N, Overwrite as O, PointerState as P, IsAllOptional as Q, R3FRenderTarget as R, Subscription as S, ThreeEvent as T, ThreeCamera as U, Viewport as V, Act as W, XRManager as X, Bridge as Y, SetBlock as Z, UnblockProps as _, RootExtension as a, EquConfig as a0, Disposable as a1, FrameNextState as a2, FrameState as a3, FrameNextCallback as a4, FrameCallback as a5, ThreeNamespace as a6, ThreeCore as a7, OcclusionSupport as a8, WebGLSupport as a9, WebGPUSupport as aa, RendererSupport as ab, RendererProvider as ac, Register as ad, RegisteredRenderer as ae, ForRegisteredRenderer as af, R3FRendererSupport as ag, R3FRenderer as b, Size as c, RenderCallback as d, Performance as e, RootState as f, RootStore as g, Intersection as h, Camera as i, IntersectionEvent as j, DomEvent as k, EventHandlers as l, FilterFunction as m, ComputeFunction as n, XRPointerConfig as o, EventManager as p, PointerCaptureTarget as q, VisibilityEntry as t, FiberRoot as u, TrackedPromise as v, Root as w, AttachType as x, Catalogue as y, Args as z };

package/dist/shared/{fiber.Bw8YnGg5.d.ts → fiber.CLTHZhZp.d.ts}

@@ -1,7 +1,7 @@
 import { FrameTimingState, FrameCallback as FrameCallback$1, SchedulerApi } from '@pmndrs/scheduler';
-import * as React from 'react';
 import * as THREE from 'three';
-import { WebGLRenderer, WebGLRenderTarget } from 'three';
+import { WebGLRenderer, WebGLRenderTarget, Color, ColorRepresentation } from 'three';
+import * as React from 'react';
 import * as ThreeWebGPU from 'three/webgpu';
 import { WebGPURenderer, RenderTarget, CanvasTarget } from 'three/webgpu';
 import { StoreApi } from 'zustand';
@@ -477,6 +477,11 @@ interface InternalState {
    * Selected once, from the entry's provider, and copied into portals with the rest of `internal`.
    */
   support: R3FRendererSupport
+  /**
+   * Releases this root's lease on its renderer. The last release disposes a renderer R3F created;
+   * a renderer passed in as an instance is never disposed by R3F.
+   */
+  releaseRenderer?: () => void | Promise<void>
   /** Global scheduler reference (for useFrame hook) */
   scheduler: SchedulerApi | null
   /**
@@ -489,6 +494,8 @@ interface InternalState {
   rootId?: string
   /** Function to unregister this root from the global scheduler */
   unregisterRoot?: () => void
+  /** Function to stop following devicePixelRatio changes */
+  unwatchDpr?: () => void
   /** Container for child attachment (scene for root, original container for portals) */
   container?: THREE.Object3D
   /**
@@ -530,6 +537,12 @@ interface InternalState {
    * Only set when isSecondary is true.
    */
   targetId?: string
+  /**
+   * This secondary stopped sharing because the primary's renderer fell back to its
+   * WebGL2 backend (#3965): it owns the renderer it constructed, so it is not
+   * `isSecondary` (which marks a canvas borrowing another's renderer).
+   */
+  sharedRendererFallback?: boolean
   /**
    * Function to unregister this primary canvas from the registry.
    * Only set when this canvas has an `id` prop.
@@ -654,6 +667,91 @@ interface RootState {
 
 type RootStore = UseBoundStoreWithEqualityFn<StoreApi<RootState>>
 
+//* Reconciler Types ==============================
+
+// FiberRoot is an opaque internal React type - we define it locally
+// to avoid bundling @types/react-reconciler which causes absolute path issues
+type FiberRoot = any
+
+/** A promise tagged with its state, the protocol React's `use` reads */
+type TrackedPromise<T> = Promise<T> &
+  ({ status: 'pending' } | { status: 'fulfilled'; value: T } | { status: 'rejected'; reason: unknown })
+
+interface Root {
+  fiber: FiberRoot
+  store: RootStore
+  /** Set while a teardown waits on React. Configure and render clear it, which cancels the teardown */
+  unmountClaim: symbol | null
+  /** Pending only while a renderer is being created */
+  ready: TrackedPromise<unknown>
+}
+
+type AttachFnType<O = any> = (parent: any, self: O) => () => void
+type AttachType<O = any> = string | AttachFnType<O>
+
+type ConstructorRepresentation<T = any> = new (...args: any[]) => T
+
+interface Catalogue {
+  [name: string]: ConstructorRepresentation
+}
+
+// TODO: handle constructor overloads
+// https://github.com/pmndrs/react-three-fiber/pull/2931
+// https://github.com/microsoft/TypeScript/issues/37079
+type Args<T> = T extends ConstructorRepresentation
+  ? T extends typeof Color
+    ? [r: number, g: number, b: number] | [color: ColorRepresentation]
+    : ConstructorParameters<T>
+  : any[]
+
+type ArgsProp<P> = P extends ConstructorRepresentation
+  ? IsAllOptional<ConstructorParameters<P>> extends true
+    ? { args?: Args<P> }
+    : { args: Args<P> }
+  : { args: unknown[] }
+
+type InstanceProps<T = any, P = any> = ArgsProp<P> & {
+  object?: T
+  dispose?: null
+  attach?: AttachType<T>
+}
+
+interface Instance<O = any> {
+  root: RootStore
+  type: string
+  parent: Instance | null
+  children: Instance[]
+  props: InstanceProps<O> & Record<string, unknown>
+  object: O & { __r3f?: Instance<O> }
+  eventCount: number
+  handlers: Partial<EventHandlers>
+  attach?: AttachType<O>
+  previousAttach?: any
+  isHidden: boolean
+  /** Set of props that have been applied via once() */
+  appliedOnce?: Set<string>
+}
+
+interface HostConfig {
+  type: string
+  props: Instance['props']
+  container: RootStore
+  instance: Instance
+  textInstance: void
+  suspenseInstance: Instance
+  hydratableInstance: never
+  formInstance: never
+  publicInstance: Instance['object']
+  hostContext: {}
+  childSet: never
+  timeoutHandle: number | undefined
+  noTimeout: -1
+  TransitionStatus: null
+}
+declare global {
+  var IS_REACT_ACT_ENVIRONMENT: boolean | undefined
+}
+
 interface RootExtension {
     /** Unique name. Registering the same name again replaces the entry (HMR-safe); roots it already
      *  set up are not set up a second time, but get the new entry's dispose and hmr. */
@@ -695,7 +793,14 @@ declare function useStore(): RootStore;
  */
 declare function useThree<T = RootState>(selector?: (state: RootState) => T, equalityFn?: <T>(state: T, newState: T) => boolean): T;
 
+/**
+ * React context that carries the current root's {@link RootStore}. Each root provides its store and
+ * each portal provides its own scoped one; `useStore`, and every hook built on it, reads it.
+ *
+ * Stored on `globalThis` under `Symbol.for('@react-three/fiber.context')`, so every copy and entry
+ * of fiber shares a single context.
+ */
 declare const context: React.Context<RootStore>;
 
-export { useStore as a2, context as a3, useThree as a7, registerRootExtension as r, setRenderOverride as s };
-export type { ForRegisteredRenderer as $, Act as A, Bridge as B, Camera as C, Dpr as D, Events as E, Frameloop as F, FrameCallback as G, ThreeNamespace as H, Intersection as I, ThreeCore as J, OcclusionSupport as K, WebGPUSupport as L, Mutable as M, NonFunctionKeys as N, Overwrite as O, PointerState as P, RendererSupport as Q, RootExtension as R, Subscription as S, ThreeEvent as T, UnblockProps as U, Viewport as V, WebGLSupport as W, XRManager as X, RendererProvider as Y, Register as Z, RegisteredRenderer as _, Size as a, R3FRenderTarget as a0, R3FRendererSupport as a1, R3FRenderer as a4, InternalState as a5, RootState as a6, RenderCallback as b, Performance as c, RootStore as d, IntersectionEvent as e, DomEvent as f, EventHandlers as g, FilterFunction as h, ComputeFunction as i, XRPointerConfig as j, EventManager as k, PointerCaptureTarget as l, VisibilityEntry as m, Properties as n, IsOptional as o, IsAllOptional as p, ThreeCamera as q, SetBlock as t, ObjectMap as u, EquConfig as v, Disposable as w, FrameNextState as x, FrameState as y, FrameNextCallback as z };
+export { useStore as ah, useThree as ai, context as aj, registerRootExtension as r, setRenderOverride as s };
+export type { ObjectMap as $, AttachFnType as A, ArgsProp as B, ConstructorRepresentation as C, Dpr as D, Events as E, Frameloop as F, InstanceProps as G, Instance as H, InternalState as I, HostConfig as J, Properties as K, IsOptional as L, Mutable as M, NonFunctionKeys as N, Overwrite as O, PointerState as P, IsAllOptional as Q, R3FRenderTarget as R, Subscription as S, ThreeEvent as T, ThreeCamera as U, Viewport as V, Act as W, XRManager as X, Bridge as Y, SetBlock as Z, UnblockProps as _, RootExtension as a, EquConfig as a0, Disposable as a1, FrameNextState as a2, FrameState as a3, FrameNextCallback as a4, FrameCallback as a5, ThreeNamespace as a6, ThreeCore as a7, OcclusionSupport as a8, WebGLSupport as a9, WebGPUSupport as aa, RendererSupport as ab, RendererProvider as ac, Register as ad, RegisteredRenderer as ae, ForRegisteredRenderer as af, R3FRendererSupport as ag, R3FRenderer as b, Size as c, RenderCallback as d, Performance as e, RootState as f, RootStore as g, Intersection as h, Camera as i, IntersectionEvent as j, DomEvent as k, EventHandlers as l, FilterFunction as m, ComputeFunction as n, XRPointerConfig as o, EventManager as p, PointerCaptureTarget as q, VisibilityEntry as t, FiberRoot as u, TrackedPromise as v, Root as w, AttachType as x, Catalogue as y, Args as z };

package/dist/shared/fiber.CTEAJNmg.d.ts

@@ -0,0 +1,48 @@
+import { a4 as FrameNextCallback } from './fiber.CLTHZhZp.js';
+import { UseFrameNextOptions, FrameNextControls } from '@pmndrs/scheduler';
+
+/**
+ * Frame hook with phase-based ordering, priority, and FPS throttling.
+ *
+ * Always delivers full RootState — works both inside and outside Canvas context:
+ * - Inside Canvas: Full RootState (renderer, scene, camera, etc.)
+ * - Outside Canvas: The job registers immediately but the callback is held until a
+ *   Canvas adopts it, then runs with full RootState. For hostless / standalone
+ *   frame loops with no Canvas, use `@pmndrs/scheduler` directly.
+ *
+ * Returns a controls object for manual stepping, pausing, and resuming.
+ *
+ * @param callback - Function called each frame with (state, delta). Optional if you only need scheduler access.
+ * @param priorityOrOptions - Either a priority number (backwards compat) or options object
+ * @returns Controls object with step(), stepAll(), invalidate(), pause(), resume(), isPaused, id, rootId, scheduler
+ *
+ * @example
+ * // Simple priority (backwards compat)
+ * useFrame((state, delta) => { ... }, 5)
+ *
+ * @example
+ * // With phase-based ordering
+ * useFrame((state, delta) => { ... }, { phase: 'physics' })
+ *
+ * @example
+ * // Outside Canvas - callback waits for a Canvas, then always has full state
+ * function UI() {
+ *   useFrame((state, delta) => { syncUI(state.camera) });
+ *   return <button>...</button>;
+ * }
+ *
+ * @example
+ * // Hostless / standalone loop (no Canvas) - use @pmndrs/scheduler directly
+ * import { getScheduler } from '@pmndrs/scheduler'
+ * getScheduler().register((state, delta) => { updateGame(delta) })
+ *
+ * @example
+ * // Scheduler-only access (no callback)
+ * const { scheduler } = useFrame()
+ * scheduler.pauseJob('some-job-id')
+ *
+ * @see https://docs.pmnd.rs/react-three-fiber/api/hooks#useframe
+ */
+declare function useFrame(callback?: FrameNextCallback, priorityOrOptions?: number | UseFrameNextOptions): FrameNextControls;
+
+export { useFrame as u };

package/dist/shared/{fiber.D9zziEOb.mjs → fiber.CUKAa7Rv.mjs}

@@ -284,6 +284,33 @@ function useFrame(callback, priorityOrOptions) {
   return controls;
 }
 
+const R3F_STAGED_TEXTURES = Symbol.for("@react-three/fiber.stagedTextures");
+const globalStaging = globalThis;
+const staging = globalStaging[R3F_STAGED_TEXTURES] ?? (globalStaging[R3F_STAGED_TEXTURES] = /* @__PURE__ */ new WeakMap());
+function stageTextures(store, entries) {
+  const registered = store.getState().textures;
+  let staged = staging.get(store);
+  for (const [url, texture] of entries) {
+    if (registered.has(url)) continue;
+    if (!staged) staging.set(store, staged = /* @__PURE__ */ new Map());
+    staged.set(url, texture);
+  }
+}
+function unstageTextures(store, urls) {
+  const staged = staging.get(store);
+  if (!staged) return;
+  for (const url of urls) staged.delete(url);
+  if (staged.size === 0) staging.delete(store);
+}
+function getTextureView(store) {
+  const registered = store.getState().textures;
+  const staged = staging.get(store);
+  if (!staged) return registered;
+  const view = new Map(registered);
+  for (const [url, texture] of staged) if (!view.has(url)) view.set(url, texture);
+  return view;
+}
+
 const R3F_EXTENSIONS = Symbol.for("@react-three/fiber.extensions");
 function getRegistry() {
   return globalThis[R3F_EXTENSIONS] ?? (globalThis[R3F_EXTENSIONS] = {
@@ -334,4 +361,4 @@ function notifyRootExtensionsHmr(store) {
   for (const setUpBy of applied.values()) current(registry, setUpBy).hmr?.(store);
 }
 
-export { Block as B, ErrorBoundary as E, useThree as a, useFrame as b, context as c, useIsomorphicLayoutEffect as d, useMutableCallback as e, useBridge as f, detachRootExtensions as g, attachRootExtensions as h, notifyAlpha as i, notifyRootExtensionsHmr as j, notifyDepreciated as n, registerRootExtension as r, setRenderOverride as s, useStore as u };
+export { Block as B, ErrorBoundary as E, useThree as a, useFrame as b, context as c, useIsomorphicLayoutEffect as d, useMutableCallback as e, useBridge as f, getTextureView as g, unstageTextures as h, stageTextures as i, attachRootExtensions as j, detachRootExtensions as k, notifyAlpha as l, notifyRootExtensionsHmr as m, notifyDepreciated as n, registerRootExtension as r, setRenderOverride as s, useStore as u };

package/dist/shared/fiber.CksZuiOV.d.mts

@@ -0,0 +1,48 @@
+import { a4 as FrameNextCallback } from './fiber.CLTHZhZp.mjs';
+import { UseFrameNextOptions, FrameNextControls } from '@pmndrs/scheduler';
+
+/**
+ * Frame hook with phase-based ordering, priority, and FPS throttling.
+ *
+ * Always delivers full RootState — works both inside and outside Canvas context:
+ * - Inside Canvas: Full RootState (renderer, scene, camera, etc.)
+ * - Outside Canvas: The job registers immediately but the callback is held until a
+ *   Canvas adopts it, then runs with full RootState. For hostless / standalone
+ *   frame loops with no Canvas, use `@pmndrs/scheduler` directly.
+ *
+ * Returns a controls object for manual stepping, pausing, and resuming.
+ *
+ * @param callback - Function called each frame with (state, delta). Optional if you only need scheduler access.
+ * @param priorityOrOptions - Either a priority number (backwards compat) or options object
+ * @returns Controls object with step(), stepAll(), invalidate(), pause(), resume(), isPaused, id, rootId, scheduler
+ *
+ * @example
+ * // Simple priority (backwards compat)
+ * useFrame((state, delta) => { ... }, 5)
+ *
+ * @example
+ * // With phase-based ordering
+ * useFrame((state, delta) => { ... }, { phase: 'physics' })
+ *
+ * @example
+ * // Outside Canvas - callback waits for a Canvas, then always has full state
+ * function UI() {
+ *   useFrame((state, delta) => { syncUI(state.camera) });
+ *   return <button>...</button>;
+ * }
+ *
+ * @example
+ * // Hostless / standalone loop (no Canvas) - use @pmndrs/scheduler directly
+ * import { getScheduler } from '@pmndrs/scheduler'
+ * getScheduler().register((state, delta) => { updateGame(delta) })
+ *
+ * @example
+ * // Scheduler-only access (no callback)
+ * const { scheduler } = useFrame()
+ * scheduler.pauseJob('some-job-id')
+ *
+ * @see https://docs.pmnd.rs/react-three-fiber/api/hooks#useframe
+ */
+declare function useFrame(callback?: FrameNextCallback, priorityOrOptions?: number | UseFrameNextOptions): FrameNextControls;
+
+export { useFrame as u };