@react-three/fiber 10.0.0-canary.f81281f → 10.0.0-canary.fbc659b

package/dist/shared/{fiber.DAg-9ieU.d.ts → fiber.CtivZ3IY.d.ts}

@@ -1,316 +1,10 @@
 import * as React$1 from 'react';
 import { ReactNode, Component, RefObject, JSX } from 'react';
 import { Options } from 'react-use-measure';
+import { al as RenderProps, m as ConstructorRepresentation, aJ as ObjectMap, a8 as BaseRendererProps, a9 as RendererFactory, aA as Properties, I as InternalState, J as RootState, E as Euler$1, K as RootStore, a4 as EventManager, _ as DomEvent, aw as Instance, o as ThreeElement, as as Catalogue, ap as Root, am as InjectState, aR as ThreeCore, aG as Bridge, aI as UnblockProps, aL as Disposable, D as Dpr, aE as ThreeCamera, z as Size, aK as EquConfig } from './fiber.C_MFx7We.js';
 import * as THREE from 'three';
-import { Color as Color$1, ColorRepresentation, Euler as Euler$1, Loader, RenderTargetOptions as RenderTargetOptions$1, ColorSpace, Texture as Texture$1, CubeTexture, Scene, Object3D } from 'three';
-import { n as Properties, a as Size, F as Frameloop, c as Performance, D as Dpr, d as RootStore, k as EventManager, a6 as RootState, i as ComputeFunction, p as IsAllOptional, g as EventHandlers, u as ObjectMap, a5 as InternalState, M as Mutable, O as Overwrite, f as DomEvent, J as ThreeCore, B as Bridge, U as UnblockProps, w as Disposable, q as ThreeCamera, v as EquConfig } from './fiber.Bw8YnGg5.js';
-import { WebGPURenderer, WebGPURendererParameters } from 'three/webgpu';
-import * as react_jsx_runtime from 'react/jsx-runtime';
-
-//* Base Renderer Types =====================================
-
-// Shim for OffscreenCanvas since it was removed from DOM types
-interface OffscreenCanvas$1 extends EventTarget {}
-
-interface BaseRendererProps {
-  canvas: HTMLCanvasElement | OffscreenCanvas$1
-  powerPreference?: 'high-performance' | 'low-power' | 'default'
-  antialias?: boolean
-  alpha?: boolean
-}
-
-type RendererFactory<TRenderer, TParams> =
-  | TRenderer
-  | ((defaultProps: TParams) => TRenderer)
-  | ((defaultProps: TParams) => Promise<TRenderer>)
-
-interface Renderer {
-  render: (scene: THREE.Scene, camera: THREE.Camera) => any
-}
-
-//* Color Management Config ==============================
-
-/**
- * Color management configuration shared by both WebGL and WebGPU renderers.
- */
-interface ColorManagementConfig {
-  /**
-   * Color space assigned to 8-bit input textures (color maps).
-   * Defaults to sRGB. Most textures are authored in sRGB.
-   * @default THREE.SRGBColorSpace
-   */
-  textureColorSpace?: THREE.ColorSpace
-}
-
-//* WebGL Renderer Props ==============================
-
-type DefaultGLProps = Omit<THREE.WebGLRendererParameters, 'canvas'> & {
-  canvas: HTMLCanvasElement | OffscreenCanvas$1
-}
-
-type GLProps =
-  | Renderer
-  | ((defaultProps: DefaultGLProps) => Renderer)
-  | ((defaultProps: DefaultGLProps) => Promise<Renderer>)
-  | (Partial<Properties<THREE.WebGLRenderer> | THREE.WebGLRendererParameters> & ColorManagementConfig)
-
-//* WebGPU Renderer Props ==============================
-
-type DefaultRendererProps = {
-  canvas: HTMLCanvasElement | OffscreenCanvas$1
-  [key: string]: any
-}
-
-/**
- * Canvas-level scheduler configuration.
- * Controls render timing relative to other canvases.
- */
-interface CanvasSchedulerConfig {
-  /**
-   * Run this Canvas root before the referenced Canvas root id(s).
-   */
-  before?: string | string[]
-  /**
-   * Run this Canvas root after the referenced Canvas root id(s).
-   */
-  after?: string | string[]
-  /**
-   * Numeric root order. Lower values run first.
-   */
-  order?: number
-  /**
-   * Limit this Canvas's default render job (frames per second).
-   */
-  fps?: number
-}
-
-/**
- * Extended renderer configuration for multi-canvas support and color management.
- */
-interface RendererConfigExtended extends ColorManagementConfig {
-  /** Share renderer from another canvas (WebGPU only) */
-  primaryCanvas?: string
-  /** Canvas-level scheduler options */
-  scheduler?: CanvasSchedulerConfig
-}
-
-/**
- * The `renderer` prop: opt into three's WebGPU renderer.
- * - `true` (the `<Canvas renderer>` shorthand) or `{}`: a default `WebGPURenderer`
- * - a props bag: constructor parameters (`antialias`, `forceWebGL`, ...) and renderer properties
- *   (`toneMapping`, ...), plus `textureColorSpace`, `primaryCanvas` and `scheduler`
- * - a renderer instance, or a sync/async factory receiving the default props. Structural, like
- *   the `gl` prop: anything with `render()`, so a wrapped or mocked renderer is accepted.
- */
-type RendererProps =
-  | boolean
-  | Renderer
-  | ((defaultProps: DefaultRendererProps) => Renderer)
-  | ((defaultProps: DefaultRendererProps) => Promise<Renderer>)
-  | (Partial<Properties<WebGPURenderer> & WebGPURendererParameters> & RendererConfigExtended)
-
-//* Camera Props ==============================
-
-type CameraProps = (
-  | THREE.Camera
-  | Partial<
-      ThreeElement<typeof THREE.Camera> &
-        ThreeElement<typeof THREE.PerspectiveCamera> &
-        ThreeElement<typeof THREE.OrthographicCamera>
-    >
-) & {
-  /** Flags the camera as manual, putting projection into your own hands */
-  manual?: boolean
-}
-
-//* Render Props ==============================
-
-interface RenderProps<TCanvas extends HTMLCanvasElement | OffscreenCanvas$1> {
-  /**
-   * Unique identifier for multi-canvas renderer sharing.
-   * Makes this canvas targetable by other canvases using the `primaryCanvas` prop.
-   * Also sets the HTML `id` attribute on the canvas element.
-   * @example <Canvas id="main-viewer">...</Canvas>
-   */
-  id?: string
-  /**
-   * Share the renderer from another canvas instead of creating a new one.
-   * Pass the `id` of the primary canvas to share its WebGPURenderer.
-   * Only available with WebGPU (not legacy WebGL).
-   *
-   * Note: This is extracted from `renderer={{ primaryCanvas: "id" }}` by Canvas.
-   * @internal
-   */
-  primaryCanvas?: string
-  /**
-   * Canvas-level scheduler options. Controls render timing relative to other canvases.
-   *
-   * Note: This is extracted from `renderer={{ scheduler: {...} }}` by Canvas.
-   * @internal
-   */
-  scheduler?: CanvasSchedulerConfig
-  /** A threejs renderer instance or props that go into the default renderer */
-  gl?: GLProps
-  /** A WebGPU renderer instance or props that go into the default renderer */
-  renderer?: RendererProps
-  /** 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>
-  /** 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?: Frameloop
-  /**
-   * 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. `params` is merged into the raycaster's defaults,
-   * so a single threshold can be set: `raycaster={{ params: { Points: { threshold: 0.2 } } }}`.
-   */
-  raycaster?: Partial<Omit<THREE.Raycaster, 'params'>> & { params?: Partial<THREE.RaycasterParameters> }
-  /** A `THREE.Scene` instance or props that go into the default scene */
-  scene?: THREE.Scene | Partial<THREE.Scene>
-  /** A `THREE.Camera` instance or props that go into the default camera */
-  camera?: CameraProps
-  /** An R3F event manager to manage elements' pointer events */
-  events?: (store: RootStore) => EventManager<Element>
-  /** 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
-  /** Response for dragover events that have missed any target */
-  onDragOverMissed?: (event: DragEvent) => void
-  /** Response for drop events that have missed any target */
-  onDropMissed?: (event: DragEvent) => void
-  /** Whether to automatically update the frustum each frame (default: true) */
-  autoUpdateFrustum?: boolean
-  /**
-   * Enable WebGPU occlusion queries for onOccluded/onVisible events.
-   * Auto-enabled when any object uses onOccluded or onVisible handlers.
-   * Only works with WebGPU renderer - WebGL will log a warning.
-   */
-  occlusion?: boolean
-  /** Internal: stored size props from Canvas for reset functionality */
-  _sizeProps?: { width?: number; height?: number } | null
-  /** Force canvas dimensions to even numbers (fixes Safari rendering issues with odd/fractional sizes) */
-  forceEven?: boolean
-}
-
-//* Reconciler Root ==============================
-
-interface ReconcilerRoot<TCanvas extends HTMLCanvasElement | OffscreenCanvas$1> {
-  configure: (config?: RenderProps<TCanvas>) => Promise<ReconcilerRoot<TCanvas>>
-  render: (element: ReactNode) => RootStore
-  unmount: () => void
-}
-
-//* Inject State ==============================
-
-type InjectState = Partial<
-  Omit<RootState, 'events'> & {
-    events?: {
-      enabled?: boolean
-      priority?: number
-      compute?: ComputeFunction
-      connected?: any
-    }
-    /**
-     * When true (default), injects a THREE.Scene between container and children if container isn't already a Scene.
-     * This ensures state.scene is always a real THREE.Scene with proper properties (background, environment, fog).
-     * Set to false to use the container directly as scene (anti-pattern, but supported for edge cases).
-     */
-    injectScene?: boolean
-  }
->
-
-//* 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
-
-interface Root {
-  fiber: FiberRoot
-  store: RootStore
-}
-
-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$1
-    ? [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
-}
+import { ColorRepresentation, Euler, Loader, RenderTargetOptions as RenderTargetOptions$1, ColorSpace, Texture as Texture$1, CubeTexture, Scene, Object3D } from 'three';
+import { WebGPURenderer } from 'three/webgpu';
 
 //* Loop Types ==============================
 
@@ -341,16 +35,16 @@ type PresetsType = keyof typeof presetsObj;
 interface BackgroundConfig {
   /** HDRI preset name: 'apartment', 'city', 'dawn', 'forest', 'lobby', 'night', 'park', 'studio', 'sunset', 'warehouse' */
   preset?: PresetsType
-  /** Files for cube texture (6 faces) or single HDR/EXR */
+  /** Files for cube texture (6 faces) or a single equirect (.hdr, .exr, .jpg, .png, .webp, .avif, .gif) */
   files?: string | string[]
   /** Separate files for scene.background (visual backdrop) */
   backgroundMap?: string | string[]
-  backgroundRotation?: Euler$1 | [number, number, number]
+  backgroundRotation?: Euler | [number, number, number]
   backgroundBlurriness?: number
   backgroundIntensity?: number
   /** Separate files for scene.environment (PBR lighting/reflections) */
   envMap?: string | string[]
-  environmentRotation?: Euler$1 | [number, number, number]
+  environmentRotation?: Euler | [number, number, number]
   environmentIntensity?: number
   path?: string
   extensions?: (loader: Loader) => void
@@ -361,7 +55,7 @@ interface BackgroundConfig {
  *
  * String detection priority:
  * 1. Preset - exact match against known presets (apartment, city, dawn, forest, lobby, night, park, studio, sunset, warehouse)
- * 2. URL - starts with /, ./, ../, http://, https://, OR has image extension
+ * 2. URL - starts with /, ./, ../, http://, https://, data:, OR has an image extension (a query or hash may follow)
  * 3. Color - default fallback (CSS color names, hex values, rgb(), etc.)
  *
  * @example Color
@@ -400,9 +94,7 @@ type BackgroundProp =
 //* Canvas Types ==============================
 
 interface CanvasProps
-  extends
-    Omit<RenderProps<HTMLCanvasElement>, 'size' | 'primaryCanvas' | 'scheduler'>,
-    React$1.HTMLAttributes<HTMLDivElement> {
+  extends Omit<RenderProps<HTMLCanvasElement>, 'size' | '_primaryToken'>, React$1.HTMLAttributes<HTMLDivElement> {
   children?: React$1.ReactNode
   ref?: React$1.Ref<HTMLCanvasElement>
   /** Canvas fallback content, similar to img's alt prop */
@@ -521,205 +213,6 @@ interface LegacyRootState extends Omit<RootState, 'renderer' | 'internal'> {
 
 type RenderTargetOptions = RenderTargetOptions$1
 
-type MutableOrReadonlyParameters<T extends (...args: any) => any> = Parameters<T> | Readonly<Parameters<T>>
-
-interface MathRepresentation {
-  set(...args: number[]): any
-}
-interface VectorRepresentation extends MathRepresentation {
-  setScalar(value: number): any
-}
-type MathTypes = MathRepresentation | THREE.Euler | THREE.Color
-
-type MathType<T extends MathTypes> = T extends THREE.Color
-  ? Args<typeof THREE.Color> | THREE.ColorRepresentation
-  : T extends VectorRepresentation | THREE.Layers | THREE.Euler
-    ? T | MutableOrReadonlyParameters<T['set']> | number
-    : T | MutableOrReadonlyParameters<T['set']>
-
-type MathProps<P> = {
-  [K in keyof P as P[K] extends MathTypes ? K : never]: P[K] extends MathTypes ? MathType<P[K]> : never
-}
-
-type Vector2 = MathType<THREE.Vector2>
-type Vector3 = MathType<THREE.Vector3>
-type Vector4 = MathType<THREE.Vector4>
-type Color = MathType<THREE.Color>
-type Layers = MathType<THREE.Layers>
-type Quaternion = MathType<THREE.Quaternion>
-type Euler = MathType<THREE.Euler>
-type Matrix3 = MathType<THREE.Matrix3>
-type Matrix4 = MathType<THREE.Matrix4>
-
-interface RaycastableRepresentation {
-  raycast(raycaster: THREE.Raycaster, intersects: THREE.Intersection[]): void
-}
-type EventProps<P> = P extends RaycastableRepresentation ? Partial<EventHandlers> : {}
-
-/**
- * Props for geometry transform methods that can be called with `once()`.
- * These methods modify the geometry in-place and only make sense to call once on mount.
- *
- * @example
- * import { once } from '@react-three/fiber'
- *
- * <boxGeometry args={[1, 1, 1]} rotateX={once(Math.PI / 2)} />
- * <planeGeometry args={[10, 10]} translate={once(0, 0, 5)} />
- * <bufferGeometry applyMatrix4={once(matrix)} center={once()} />
- */
-interface GeometryTransformProps {
-  /** Rotate the geometry about the X axis (radians). Use with once(). */
-  rotateX?: number
-  /** Rotate the geometry about the Y axis (radians). Use with once(). */
-  rotateY?: number
-  /** Rotate the geometry about the Z axis (radians). Use with once(). */
-  rotateZ?: number
-  /** Translate the geometry (x, y, z). Use with once(). */
-  translate?: [x: number, y: number, z: number]
-  /** Scale the geometry (x, y, z). Use with once(). */
-  scale?: [x: number, y: number, z: number]
-  /** Center the geometry based on bounding box. Use with once(). */
-  center?: true
-  /** Apply a Matrix4 transformation. Use with once(). */
-  applyMatrix4?: THREE.Matrix4
-  /** Apply a Quaternion rotation. Use with once(). */
-  applyQuaternion?: THREE.Quaternion
-}
-
-type GeometryProps<P> = P extends THREE.BufferGeometry ? GeometryTransformProps : {}
-
-/**
- * Workaround for @types/three TSL node type issues.
- * The Node base class has properties that subclasses (OperatorNode, ConstNode, etc.) don't inherit.
- * This transforms `Node | null` properties to accept any object with node-like shape.
- */
-type TSLNodeInput = { nodeType?: string | null; uuid?: string } | null
-
-/**
- * For node material properties (colorNode, positionNode, etc.), accept broader types
- * since @types/three has broken inheritance for TSL node subclasses. NodeClass requires
- * `nodeType`, so this structural key test remains neutral to the selected Three entry.
- */
-type NodeProps<P> = {
-  [K in keyof P as NonNullable<P[K]> extends { nodeType: string | null } ? K : never]?: TSLNodeInput
-}
-
-interface ReactProps<P> {
-  children?: React.ReactNode
-  ref?: React.Ref<P>
-  key?: React.Key
-}
-
-type ElementProps<T extends ConstructorRepresentation, P = InstanceType<T>> = Partial<
-  Overwrite<P, MathProps<P> & ReactProps<P> & EventProps<P> & GeometryProps<P> & NodeProps<P>>
->
-
-type ThreeElement<T extends ConstructorRepresentation> = Mutable<
-  Overwrite<ElementProps<T>, Omit<InstanceProps<InstanceType<T>, T>, 'object'>>
->
-
-type ThreeToJSXElements<T extends Record<string, any>> = {
-  [K in keyof T & string as Uncapitalize<K>]: T[K] extends ConstructorRepresentation ? ThreeElement<T[K]> : never
-}
-
-/** Method names of Object3D, excluded from the `primitive` element's typed props. */
-type Object3DMethod = NonNullable<
-  {
-    [K in keyof THREE.Object3D]-?: THREE.Object3D[K] extends (...args: any[]) => any ? K : never
-  }[keyof THREE.Object3D]
->
-
-/** Look up a key present in a generic element map. */
-type ElementOf<E, K extends string> = E[Extract<keyof E, K>]
-
-/**
- * The JSX element map derived from an entry's Three.js exports. Each entry declares its own
- * `ThreeElements` from this (`src/index.tsx`, `src/legacy.tsx`, `src/webgpu/index.tsx`) and augments
- * react's `IntrinsicElements` with it, so `/legacy` never advertises node materials and `/webgpu`
- * never advertises a `<webGLRenderer>`.
- */
-type ThreeElementsOf<T extends Record<string, any>> = Omit<
-  ThreeToJSXElements<T>,
-  'audio' | 'source' | 'line' | 'path'
-> & {
-  /**
-   * `primitive` wraps a pre-existing object, so its props cannot be derived from one class.
-   * Events are typed from `EventHandlers` (`onClick={(e) => ...}` infers `e`), the ref is
-   * untyped, and any other prop is accepted and applied to the object by name. Object3D's own
-   * methods are left out of the typed surface: they return `this`, so a subclass element's
-   * props (`ThreeElements['group']`) could not be spread onto a primitive otherwise.
-   */
-  primitive: Omit<ThreeElement<typeof THREE.Object3D>, 'args' | 'object' | 'ref' | Object3DMethod> & {
-    object: object
-    ref?: React.Ref<any>
-    [prop: string]: unknown
-  }
-  // Conflicts with DOM types can be accessed through a three* prefix
-  threeAudio: ElementOf<ThreeToJSXElements<T>, 'audio'>
-  threeSource: ElementOf<ThreeToJSXElements<T>, 'source'>
-  threeLine: ElementOf<ThreeToJSXElements<T>, 'line'>
-  threePath: ElementOf<ThreeToJSXElements<T>, 'path'>
-}
-
-/**
- * @fileoverview Registry for primary canvases that can be targeted by secondary canvases
- *
- * Enables multi-canvas WebGPU rendering where multiple Canvas components share
- * a single WebGPURenderer using Three.js CanvasTarget API.
- *
- * Primary canvas: Has `id` prop, creates its own renderer, registers here
- * Secondary canvas: Has `renderer={{ primaryCanvas: 'id' }}`, shares primary's renderer via CanvasTarget
- */
-
-interface PrimaryCanvasEntry {
-    /** The WebGPURenderer instance owned by this primary canvas */
-    renderer: WebGPURenderer;
-    /** The zustand store for this canvas */
-    store: RootStore;
-}
-/**
- * Register a primary canvas that can be targeted by secondary canvases.
- *
- * @param id - Unique identifier for this primary canvas
- * @param renderer - The WebGPURenderer owned by this canvas
- * @param store - The zustand store for this canvas
- * @returns Cleanup function to unregister on unmount
- */
-declare function registerPrimary(id: string, renderer: WebGPURenderer, store: RootStore): () => void;
-/**
- * Get a registered primary canvas by id.
- *
- * @param id - The id of the primary canvas to look up
- * @returns The primary canvas entry or undefined if not found
- */
-declare function getPrimary(id: string): PrimaryCanvasEntry | undefined;
-/**
- * Wait for a primary canvas to be registered.
- * Returns immediately if already registered, otherwise waits.
- *
- * @param id - The id of the primary canvas to wait for
- * @param timeout - Optional timeout in ms (default: 5000)
- * @returns Promise that resolves with the primary canvas entry
- */
-declare function waitForPrimary(id: string, timeout?: number): Promise<PrimaryCanvasEntry>;
-/**
- * Check if a primary canvas with the given id exists.
- *
- * @param id - The id to check
- * @returns True if a primary canvas with this id is registered
- */
-declare function hasPrimary(id: string): boolean;
-/**
- * Unregister a primary canvas. Called on unmount.
- *
- * @param id - The id of the primary canvas to unregister
- */
-declare function unregisterPrimary(id: string): void;
-/**
- * Get all registered primary canvas ids. Useful for debugging.
- */
-declare function getPrimaryIds(): string[];
-
 type EnvironmentLoaderProps = {
     files?: string | string[];
     path?: string;
@@ -777,7 +270,7 @@ type EnvironmentLoaderClearOptions = Pick<EnvironmentLoaderProps, 'files' | 'pre
  *   - scale: Scale of backside projected sphere (default: 1000)
  *
  * Additional loader props:
- * @property files - File path(s) for environment. Supports .hdr, .exr, Ultra HDR .jpg, or array of 6 cube faces
+ * @property files - File path(s) for environment. Supports .hdr, .exr, .jpg (Ultra HDR or plain), an LDR .png/.webp/.avif/.gif, or array of 6 cube faces
  * @property path - Base path for file loading
  * @property extensions - Texture extensions override
  */
@@ -792,9 +285,9 @@ type EnvironmentProps = {
     blur?: number;
     backgroundBlurriness?: number;
     backgroundIntensity?: number;
-    backgroundRotation?: Euler;
+    backgroundRotation?: Euler$1;
     environmentIntensity?: number;
-    environmentRotation?: Euler;
+    environmentRotation?: Euler$1;
     map?: Texture$1;
     preset?: PresetsType;
     scene?: Scene | React$1.RefObject<Scene>;
@@ -820,8 +313,9 @@ type EnvironmentProps = {
 declare function EnvironmentMap({ scene, background, map, ...config }: EnvironmentProps): null;
 /**
  * Internal component that loads environment textures from files or presets.
- * Uses HDRLoader for .hdr, EXRLoader for .exr, UltraHDRLoader for .jpg/.jpeg Ultra HDR,
- * or CubeTextureLoader for arrays of images.
+ * Uses HDRLoader for .hdr, EXRLoader for .exr, UltraHDRLoader for .jpg/.jpeg (a JPEG without a gain
+ * map loads as a plain image), TextureLoader for an LDR .png/.webp/.avif/.gif, or CubeTextureLoader
+ * for arrays of images.
  *
  * @example With preset
  * ```jsx
@@ -875,14 +369,14 @@ declare function EnvironmentCube({ background, scene, blur, backgroundBlurriness
  * </EnvironmentPortal>
  * ```
  */
-declare function EnvironmentPortal({ children, near, far, resolution, frames, map, background, blur, backgroundBlurriness, backgroundIntensity, backgroundRotation, environmentIntensity, environmentRotation, scene, files, path, preset, extensions, }: EnvironmentProps): react_jsx_runtime.JSX.Element;
+declare function EnvironmentPortal({ children, near, far, resolution, frames, map, background, blur, backgroundBlurriness, backgroundIntensity, backgroundRotation, environmentIntensity, environmentRotation, scene, files, path, preset, extensions, }: EnvironmentProps): React$1.JSX.Element;
 /**
  * Sets up a global environment map for PBR materials and backgrounds.
  * Affects scene.environment and optionally scene.background unless a custom scene is passed.
  *
  * Supports multiple input methods:
  * - **Presets**: Selection of HDRI Haven assets (apartment, city, dawn, forest, lobby, night, park, studio, sunset, warehouse)
- * - **Files**: HDR (.hdr), EXR (.exr), Ultra HDR JPEG (.jpg), or cube faces (array of 6 images)
+ * - **Files**: HDR (.hdr), EXR (.exr), JPEG (.jpg, Ultra HDR when it carries a gain map), LDR image (.png, .webp, .avif, .gif), or cube faces (array of 6 images)
  * - **Texture**: Pre-existing cube texture via `map` prop
  * - **Custom Scene**: Render children into environment using portal and cube camera
  * - **Ground Projection**: Project environment onto ground plane
@@ -971,7 +465,7 @@ declare function EnvironmentPortal({ children, near, far, resolution, frames, ma
  * />
  * ```
  */
-declare function Environment(props: EnvironmentProps): react_jsx_runtime.JSX.Element;
+declare function Environment(props: EnvironmentProps): React$1.JSX.Element;
 
 /**
  * Moves every trace of interactivity from one object to its replacement, for reconstruction.
@@ -1089,7 +583,7 @@ declare const Texture: ({ children, input, onLoad, cache, }: {
     input: Parameters<typeof useTexture>[0];
     onLoad?: Parameters<typeof useTexture>[1];
     cache?: boolean;
-}) => react_jsx_runtime.JSX.Element;
+}) => React$1.JSX.Element;
 
 /** Accepted shapes for a registry read: a single key, a list of keys, or a name→key map. */
 type TextureInput = string | string[] | Record<string, string>;
@@ -1876,7 +1370,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;
 
@@ -2207,7 +1702,6 @@ declare namespace ReactReconciler {
             onCaughtError: (error: Error, info: BaseErrorInfo) => void,
             onRecoverableError: (error: Error, info: BaseErrorInfo) => void,
             onDefaultTransitionIndicator: () => void,
-            transitionCallbacks: null | TransitionTracingCallbacks,
         ): OpaqueRoot;
 
         createPortal(
@@ -2217,8 +1711,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;
@@ -2253,8 +1745,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(
@@ -2264,17 +1760,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;
@@ -2283,16 +1789,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;
@@ -2305,19 +1805,86 @@ 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;
 }
 
+/**
+ * Registers constructors so they can be rendered as JSX elements.
+ *
+ * - `extend({ OrbitControls })` makes each constructor available under its camelCased key
+ *   (`<orbitControls />`). Values that are not constructors are skipped, so a whole module
+ *   namespace can be passed.
+ * - `extend(MyClass)` registers one constructor and returns a component to render it with.
+ *
+ * Registrations are global, shared by every copy and entry of fiber, and are checked before the
+ * three namespace of a root's renderer when an element name is resolved.
+ *
+ * @example
+ * import { OrbitControls } from 'three/addons/controls/OrbitControls.js'
+ * extend({ OrbitControls })
+ * // <orbitControls args={[camera, gl.domElement]} />
+ *
+ * @example
+ * const Controls = extend(OrbitControls)
+ * // <Controls args={[camera, gl.domElement]} />
+ *
+ * @see https://docs.pmnd.rs/react-three-fiber/api/objects#using-3rd-party-objects-declaratively
+ */
 declare function extend<T extends ConstructorRepresentation>(objects: T): React$1.ExoticComponent<ThreeElement<T>>;
+/** Registers each constructor in `objects` under its key; see the first overload. */
 declare function extend<T extends Catalogue>(objects: T): void;
+/** Registers every constructor in a module namespace, skipping other exports; see the first overload. */
 declare function extend(objects: Record<string, unknown>): void;
 
+/**
+ * R3F's React reconciler: a mutation-mode host config that turns JSX elements into three.js objects.
+ * Each root's {@link RootStore} is its container, and children attach to `internal.container`
+ * (a portal's target) or else the root's `scene`.
+ *
+ * - **Element names** resolve through `extend()` registrations first, then the three namespace of
+ *   the root's renderer. A `three` prefix (`<threeLine>`) is stripped when no element by the
+ *   prefixed name exists. `<primitive object={...}>` wraps an existing object.
+ * - **Construction is deferred** until an instance is attached to a mounted parent, so a tree that
+ *   Suspense discards never creates three objects.
+ * - **Updates** apply only changed props. Changing `args` (or a primitive's `object`) reconstructs
+ *   the object instead; the swap happens in `resetAfterCommit`, before layout effects, so refs
+ *   already point to the new object.
+ * - **Removal** detaches the object and disposes it (at idle priority, or immediately in an `act`
+ *   test environment), unless it is a primitive, a `Scene`, or it or an ancestor has `dispose={null}`.
+ * - **Priority**: not the primary renderer, so it runs alongside react-dom, and update priority
+ *   follows react-dom's event priorities. View-transition commits are flushed synchronously, since
+ *   three has nothing to animate between commits.
+ *
+ * `createRoot`, `createPortal` and `flushSync` drive it; app code rarely needs it directly.
+ */
 declare const reconciler: ReactReconciler.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.
+ */
+declare function flushSync<R>(fn: () => R): R;
 
-declare const isRenderer: (def: any) => boolean;
-interface OffscreenCanvas extends EventTarget {
-}
 declare const _roots: Map<HTMLCanvasElement | OffscreenCanvas, Root>;
+/**
+ * Unmount the root on `canvas`. The teardown runs once React has committed the unmount, and waits
+ * for a renderer that is still being created. `callback` runs when the root is gone: after the
+ * teardown, and when it disposed a renderer R3F created whose `dispose()` is async (WebGPURenderer
+ * from three r186), after that dispose has settled.
+ */
 declare function unmountComponentAtNode<TCanvas extends HTMLCanvasElement | OffscreenCanvas>(canvas: TCanvas, callback?: (canvas: TCanvas) => void): void;
+
 declare function createPortal(children: ReactNode, container: THREE.Object3D | RefObject<THREE.Object3D | null> | RefObject<THREE.Object3D>, state?: InjectState): JSX.Element;
 interface PortalProps {
     children: ReactNode;
@@ -2325,14 +1892,89 @@ interface PortalProps {
     container: Object3D | RefObject<Object3D | null> | RefObject<Object3D>;
 }
 declare function Portal({ children, container, state }: PortalProps): JSX.Element;
+
+/** Renderer resources: creation, shared canvas lookup, and ownership through final release. */
+
+declare const isRenderer: (def: any) => boolean;
+interface PrimaryCanvasEntry {
+    /** The WebGPURenderer instance owned by this primary canvas */
+    renderer: WebGPURenderer;
+    /** The zustand store for this canvas */
+    store: RootStore;
+    /** The primary's scheduler root id; a sharing canvas renders after it by default */
+    rootId?: string;
+}
 /**
- * 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.
+ * Register a primary canvas that can be targeted by secondary canvases.
+ *
+ * @param id - Registry key: the canvas id, or DEFAULT_PRIMARY
+ * @param renderer - The WebGPURenderer owned by this canvas
+ * @param store - The zustand store for this canvas
+ * @param options - The owner token that announced it and its scheduler root id
+ * @returns Cleanup function to unregister on unmount
  */
-declare function flushSync<R>(fn: () => R): R;
+declare function registerPrimary(id: string, renderer: WebGPURenderer, store: RootStore, options?: {
+    token?: object;
+    rootId?: string;
+}): () => void;
+/**
+ * Get a registered primary canvas by id.
+ *
+ * @param id - The id of the primary canvas to look up
+ * @returns The primary canvas entry or undefined if not found
+ */
+declare function getPrimary(id: string): PrimaryCanvasEntry | undefined;
+/**
+ * Wait for a primary canvas to be registered (`share="id"`).
+ * Returns immediately if already registered, otherwise waits, even through a primary remounting.
+ *
+ * @param id - The id of the primary canvas to wait for
+ * @param timeout - Optional timeout in ms (default: 5000)
+ * @returns Promise that resolves with the primary canvas entry
+ */
+declare function waitForPrimary(id: string, timeout?: number): Promise<PrimaryCanvasEntry>;
+/**
+ * Check if a primary canvas with the given id exists.
+ *
+ * @param id - The id to check
+ * @returns True if a primary canvas with this id is registered
+ */
+declare function hasPrimary(id: string): boolean;
+/**
+ * Unregister a primary canvas. Called on unmount.
+ *
+ * @param id - The id of the primary canvas to unregister
+ */
+declare function unregisterPrimary(id: string): void;
+/**
+ * Get all registered primary canvas ids. Useful for debugging.
+ */
+declare function getPrimaryIds(): string[];
 
+/**
+ * Creates the Zustand store that holds one root's {@link RootState}.
+ *
+ * The store starts unconfigured: the renderer, `camera`, `scene`, `raycaster`, `frustum` and `pointer`
+ * are `null` placeholders until the root's renderer support has loaded and `configure()` in
+ * `configuration.ts` fills them in. Only core's part of `RootState` is created here; packages building on
+ * fiber add their own fields through root extensions.
+ *
+ * Besides the initial state, the store wires up:
+ * - `state.gl` and `state.renderer` as accessors over `internal.actualRenderer`. `gl` reports a
+ *   deprecation when user code reads it outside legacy mode.
+ * - `rootScene` following `scene` whenever `scene` is set to a real `THREE.Scene`.
+ * - On a size or DPR change: updating the camera and resizing the root's own canvas target (or the
+ *   renderer when there is none).
+ * - On a camera change: adding an unparented camera to `rootScene`, then refreshing the viewport and
+ *   (when `autoUpdateFrustum` is set) the frustum.
+ * - Calling `invalidate(state)` after every state change.
+ *
+ * `createRoot` calls this once per canvas.
+ *
+ * @param invalidate - Requests frames for a root. Bound into `state.invalidate` and called on every store change.
+ * @param advance - Steps a root manually. Bound into `state.advance`.
+ * @returns The root's store, which is also the reconciler container for that root.
+ */
 declare const createStore: (invalidate: (state?: RootState, frames?: number, stackFrames?: boolean) => void, advance: (timestamp: number, runGlobalEffects?: boolean, state?: RootState, frame?: XRFrame) => void) => RootStore;
 
 /** Whether any root has loaded a renderer yet. */
@@ -2365,7 +2007,7 @@ declare const useIsomorphicLayoutEffect: typeof React$1.useLayoutEffect;
  */
 declare function useMutableCallback<T>(fn: T): React$1.RefObject<T>;
 /**
- * Bridges renderer Context and StrictMode from a primary renderer.
+ * Bridges renderer Context, StrictMode, and Activity visibility from a primary renderer.
  * Used to maintain React context when rendering into portals or secondary canvases.
  *
  * @returns A Bridge component that wraps children with the parent renderer's context
@@ -2848,5 +2490,5 @@ declare function isOnce(value: unknown): value is {
     [ONCE]: any[] | true;
 };
 
-export { getThree as B, hasThree as D, whenThree as F, _roots as a$, swapInteractivity as aB, removeInteractivity as aC, createEvents as aD, useInstanceHandle as aE, useGraph as aF, useLoader as aG, IsObject as aH, useTexture as aK, Texture as aL, useTextures as aQ, useEnvironment as aS, addEffect as aT, addAfterEffect as aU, addTail as aV, invalidate as aW, advance as aX, extend as aY, reconciler as aZ, isRenderer as a_, registerPrimary as ao, getPrimary as ap, waitForPrimary as aq, hasPrimary as ar, unregisterPrimary as as, getPrimaryIds as at, EnvironmentMap as av, EnvironmentCube as aw, EnvironmentPortal as ax, Environment as ay, presetsObj as az, unmountComponentAtNode as b0, createPortal as b1, Portal as b2, flushSync as b3, createStore as b4, useIsomorphicLayoutEffect as b5, useMutableCallback as b6, useBridge as b7, Block as b8, ErrorBoundary as b9, isVectorLike as bA, isCopyable as bB, hasConstructor as bC, FROM_REF as bD, fromRef as bF, isFromRef as bG, ONCE as bH, once as bI, isOnce as bK, REACT_INTERNAL_PROPS as ba, findInitialRoot as bb, getRootState as bc, buildGraph as bd, dispose as be, getInstanceProps as bf, prepare as bg, invalidateInstance as bh, RESERVED_PROPS as bi, resolve as bj, attach as bk, detach as bl, diffProps as bm, applyProps as bn, calculateDpr as bo, getUuidPrefix as bp, updateCamera as bq, updateFrustum as br, is as bs, isOrthographicCamera as bt, isRef as bu, isColorRepresentation as bv, isObject3D as bw, isTexture as bx, isLayers as by, isUniform as bz, createPointerEvents as w };
-export type { CameraProps as $, WebGLShadowConfig as A, Color as C, Euler as E, GeometryTransformProps as G, OffscreenCanvas$1 as H, BaseRendererProps as I, RendererFactory as J, Renderer as K, Layers as L, MutableOrReadonlyParameters as M, NodeProps as N, Object3DMethod as O, ColorManagementConfig as P, Quaternion as Q, RaycastableRepresentation as R, DefaultGLProps as S, TSLNodeInput as T, GLProps as U, VectorRepresentation as V, WebGLProps as W, DefaultRendererProps as X, CanvasSchedulerConfig as Y, RendererConfigExtended as Z, RendererProps as _, MathRepresentation as a, RenderProps as a0, InjectState as a1, FiberRoot as a2, Root as a3, AttachFnType as a4, AttachType as a5, Catalogue as a6, Args as a7, ArgsProp as a8, InstanceProps as a9, PresetsType as aA, MappedTextureType as aI, UseTextureOptions as aJ, TextureInput as aM, TextureResult as aN, DisposeOptions as aO, UseTexturesReturn as aP, EnvironmentLoaderProps as aR, Instance as aa, HostConfig as ab, GlobalRenderCallback as ac, GlobalEffectType as ad, BackgroundConfig as ae, BackgroundProp as af, InputLike as ag, LoaderLike as ah, GLTFLike as ai, LoaderInstance as aj, InferLoadResult as ak, LoaderResult as al, Extensions as am, PrimaryCanvasEntry as an, EnvironmentProps as au, MathTypes as b, FromRefMarker as bE, OnceValue as bJ, MathType as c, MathProps as d, Vector2 as e, Vector3 as f, Vector4 as g, Matrix3 as h, Matrix4 as i, EventProps as j, GeometryProps as k, ReactProps as l, ConstructorRepresentation as m, ElementProps as n, ThreeElement as o, ThreeToJSXElements as p, ThreeElementsOf as q, ElementOf as r, CanvasProps as s, LegacyRootState as t, ReconcilerRoot as u, RenderTargetOptions as v, LegacyInternalState as x, LegacyRenderer as y, WebGLDefaultProps as z };
+export { useTexture as $, EnvironmentMap as H, EnvironmentCube as J, EnvironmentPortal as K, Environment as M, presetsObj as N, swapInteractivity as Q, removeInteractivity as S, createEvents as T, useInstanceHandle as U, useGraph as V, useLoader as X, IsObject as Y, addEffect as a, Texture as a0, useTextures as a5, useEnvironment as a7, extend as a8, reconciler as a9, diffProps as aA, applyProps as aB, is as aC, isOrthographicCamera as aD, isRef as aE, isColorRepresentation as aF, isObject3D as aG, isTexture as aH, isLayers as aI, isUniform as aJ, isVectorLike as aK, isCopyable as aL, hasConstructor as aM, FROM_REF as aN, fromRef as aP, isFromRef as aQ, ONCE as aR, once as aS, isOnce as aU, flushSync as aa, _roots as ab, unmountComponentAtNode as ac, createPortal as ad, Portal as ae, useIsomorphicLayoutEffect as af, useMutableCallback as ag, useBridge as ah, Block as ai, ErrorBoundary as aj, calculateDpr as ak, getUuidPrefix as al, updateCamera as am, updateFrustum as an, REACT_INTERNAL_PROPS as ao, findInitialRoot as ap, getRootState as aq, buildGraph as ar, dispose as as, getInstanceProps as at, prepare as au, invalidateInstance as av, RESERVED_PROPS as aw, resolve as ax, attach as ay, detach as az, addAfterEffect as b, createPointerEvents as c, addTail as d, advance as e, isRenderer as f, getPrimary as g, hasPrimary as h, invalidate as i, getPrimaryIds as j, createStore as k, getThree as l, hasThree as m, whenThree as n, registerPrimary as r, unregisterPrimary as u, waitForPrimary as w };
+export type { LegacyInternalState as A, BackgroundConfig as B, CanvasProps as C, LegacyRootState as D, Extensions as E, EnvironmentProps as F, GlobalRenderCallback as G, InputLike as I, LoaderLike as L, PresetsType as O, PrimaryCanvasEntry as P, RenderTargetOptions as R, WebGLDefaultProps as W, MappedTextureType as Z, UseTextureOptions as _, TextureInput as a1, TextureResult as a2, DisposeOptions as a3, UseTexturesReturn as a4, EnvironmentLoaderProps as a6, FromRefMarker as aO, OnceValue as aT, GlobalEffectType as o, BackgroundProp as p, GLTFLike as q, LoaderInstance as s, InferLoadResult as t, LoaderResult as v, WebGLProps as x, WebGLShadowConfig as y, LegacyRenderer as z };