@react-three/fiber 10.0.0-canary.d202062 → 10.0.0-canary.d46ab63

package/dist/shared/{fiber.Cu2hX1IM.d.mts → fiber.CjMAAsJy.d.ts}

@@ -1,238 +1,10 @@
 import * as React$1 from 'react';
 import { ReactNode, Component, RefObject, JSX } from 'react';
 import { Options } from 'react-use-measure';
+import { ak as RenderProps, m as ConstructorRepresentation, aI as ObjectMap, a7 as BaseRendererProps, a8 as RendererFactory, az as Properties, I as InternalState, H as RootState, E as Euler$1, J as RootStore, a3 as EventManager, Z as DomEvent, av as Instance, o as ThreeElement, ar as Catalogue, ao as Root, al as InjectState, aQ as ThreeCore, aF as Bridge, aH as UnblockProps, aK as Disposable, D as Dpr, aD as ThreeCamera, y as Size, aJ as EquConfig } from './fiber.DQTSZ24m.js';
 import * as THREE from 'three';
-import { ColorRepresentation, Euler as Euler$1, Loader, RenderTargetOptions as RenderTargetOptions$1, ColorSpace, Texture as Texture$1, CubeTexture, Scene, Object3D } from 'three';
-import { J as Properties, c as Size, F as Frameloop, e as Performance, D as Dpr, g as RootStore, p as EventManager, f as RootState, n as ComputeFunction, C as ConstructorRepresentation, _ as ObjectMap, I as InternalState, M as Mutable, O as Overwrite, y as Args, l as EventHandlers, B as InstanceProps, k as DomEvent, G as Instance, x as Catalogue, v as Root, a6 as ThreeCore, W as Bridge, Z as UnblockProps, a0 as Disposable, Q as ThreeCamera, $ as EquConfig } from './fiber.I5Q4dVvl.mjs';
-import { WebGPURenderer, WebGPURendererParameters } from 'three/webgpu';
-
-//* 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
-  }
->
+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 ==============================
 
@@ -263,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
@@ -283,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
@@ -322,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 */
@@ -443,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;
@@ -699,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
  */
@@ -714,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>;
@@ -742,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
@@ -804,7 +376,7 @@ declare function EnvironmentPortal({ children, near, far, resolution, frames, ma
  *
  * 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
@@ -2246,17 +1818,73 @@ declare namespace ReactReconciler {
     ): 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;
@@ -2264,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. */
@@ -2304,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
@@ -2787,5 +2490,5 @@ declare function isOnce(value: unknown): value is {
     [ONCE]: any[] | true;
 };
 
-export { REACT_INTERNAL_PROPS as a$, Texture as aA, useTextures as aF, useEnvironment as aH, addEffect as aI, addAfterEffect as aJ, addTail as aK, invalidate as aL, advance as aM, extend as aN, reconciler as aO, isRenderer as aP, _roots as aQ, unmountComponentAtNode as aR, createPortal as aS, Portal as aT, flushSync as aU, createStore as aV, useIsomorphicLayoutEffect as aW, useMutableCallback as aX, useBridge as aY, Block as aZ, ErrorBoundary as a_, registerPrimary as ad, getPrimary as ae, waitForPrimary as af, hasPrimary as ag, unregisterPrimary as ah, getPrimaryIds as ai, EnvironmentMap as ak, EnvironmentCube as al, EnvironmentPortal as am, Environment as an, presetsObj as ao, swapInteractivity as aq, removeInteractivity as ar, createEvents as as, useInstanceHandle as at, useGraph as au, useLoader as av, IsObject as aw, useTexture as az, findInitialRoot as b0, getRootState as b1, buildGraph as b2, dispose as b3, getInstanceProps as b4, prepare as b5, invalidateInstance as b6, RESERVED_PROPS as b7, resolve as b8, attach as b9, detach as ba, diffProps as bb, applyProps as bc, calculateDpr as bd, getUuidPrefix as be, updateCamera as bf, updateFrustum as bg, is as bh, isOrthographicCamera as bi, isRef as bj, isColorRepresentation as bk, isObject3D as bl, isTexture as bm, isLayers as bn, isUniform as bo, isVectorLike as bp, isCopyable as bq, hasConstructor as br, FROM_REF as bs, fromRef as bu, isFromRef as bv, ONCE as bw, once as bx, isOnce as bz, createPointerEvents as u, getThree as v, hasThree as w, whenThree as x };
-export type { InputLike as $, Renderer as A, BaseRendererProps as B, Color as C, ColorManagementConfig as D, Euler as E, DefaultGLProps as F, GeometryTransformProps as G, GLProps as H, DefaultRendererProps as I, CanvasSchedulerConfig as J, RendererConfigExtended as K, Layers as L, MutableOrReadonlyParameters as M, NodeProps as N, Object3DMethod as O, RendererProps as P, Quaternion as Q, RaycastableRepresentation as R, CameraProps as S, TSLNodeInput as T, RenderProps as U, VectorRepresentation as V, InjectState as W, GlobalRenderCallback as X, GlobalEffectType as Y, BackgroundConfig as Z, BackgroundProp as _, MathRepresentation as a, LoaderLike as a0, GLTFLike as a1, LoaderInstance as a2, InferLoadResult as a3, LoaderResult as a4, Extensions as a5, WebGLDefaultProps as a6, WebGLProps as a7, WebGLShadowConfig as a8, LegacyRenderer as a9, TextureInput as aB, TextureResult as aC, DisposeOptions as aD, UseTexturesReturn as aE, EnvironmentLoaderProps as aG, LegacyInternalState as aa, LegacyRootState as ab, PrimaryCanvasEntry as ac, EnvironmentProps as aj, PresetsType as ap, MappedTextureType as ax, UseTextureOptions as ay, MathTypes as b, FromRefMarker as bt, OnceValue as by, 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, ElementProps as m, ThreeElement as n, ThreeToJSXElements as o, ThreeElementsOf as p, ElementOf as q, RenderTargetOptions as r, ReconcilerRoot as s, CanvasProps as t, OffscreenCanvas$1 as y, RendererFactory as z };
+export { Texture as $, EnvironmentMap as F, EnvironmentCube as H, EnvironmentPortal as J, Environment as K, presetsObj as M, swapInteractivity as O, removeInteractivity as Q, createEvents as S, useInstanceHandle as T, useGraph as U, useLoader as V, IsObject as X, useTexture as _, addEffect as a, useTextures as a4, useEnvironment as a6, extend as a7, reconciler as a8, flushSync as a9, applyProps as aA, is as aB, isOrthographicCamera as aC, isRef as aD, isColorRepresentation as aE, isObject3D as aF, isTexture as aG, isLayers as aH, isUniform as aI, isVectorLike as aJ, isCopyable as aK, hasConstructor as aL, FROM_REF as aM, fromRef as aO, isFromRef as aP, ONCE as aQ, once as aR, isOnce as aT, _roots as aa, unmountComponentAtNode as ab, createPortal as ac, Portal as ad, useIsomorphicLayoutEffect as ae, useMutableCallback as af, useBridge as ag, Block as ah, ErrorBoundary as ai, calculateDpr as aj, getUuidPrefix as ak, updateCamera as al, updateFrustum as am, REACT_INTERNAL_PROPS as an, findInitialRoot as ao, getRootState as ap, buildGraph as aq, dispose as ar, getInstanceProps as as, prepare as at, invalidateInstance as au, RESERVED_PROPS as av, resolve as aw, attach as ax, detach as ay, diffProps 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, LegacyRootState as C, EnvironmentProps as D, Extensions as E, GlobalRenderCallback as G, InputLike as I, LoaderLike as L, PresetsType as N, PrimaryCanvasEntry as P, RenderTargetOptions as R, WebGLDefaultProps as W, MappedTextureType as Y, UseTextureOptions as Z, TextureInput as a0, TextureResult as a1, DisposeOptions as a2, UseTexturesReturn as a3, EnvironmentLoaderProps as a5, FromRefMarker as aN, OnceValue as aS, CanvasProps as aU, 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 };