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

package/dist/shared/{fiber.AN9kOS0N.d.mts → fiber.VTTQNnlj.d.cts}

@@ -1,241 +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.cjs';
 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.Dh8K6RJr.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 (`true` uses `THREE.PCFShadowMap`). Can accept `renderer.shadowMap` options for
-   * fine-tuning, but also strings: 'basic' | 'percentage' | 'soft' | 'variance'.
-   *
-   * `'soft'` is a deprecated alias of `'percentage'`: both map to `THREE.PCFShadowMap`, because three.js
-   * deprecated `PCFSoftShadowMap` and made `PCFShadowMap` soft. Using `'soft'` logs a deprecation notice.
-   * @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 ==============================
 
@@ -266,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
@@ -286,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
@@ -325,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 */
@@ -446,211 +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'>>
->
-
-/**
- * Every constructor export of a three namespace as an uncapitalized JSX element. Non-constructor
- * exports (constants, functions, nested namespaces) are dropped from the keys rather than mapped
- * to `never`: a single `never`-valued key in `JSX.IntrinsicElements` collapses the props of any
- * tag typed `React.ElementType` (#3898).
- */
-type ThreeToJSXElements<T extends Record<string, any>> = {
-  [K in keyof T & string as T[K] extends ConstructorRepresentation ? Uncapitalize<K> : never]: ThreeElement<T[K]>
-}
-
-/** 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;
@@ -708,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
  */
@@ -723,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>;
@@ -751,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
@@ -813,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
@@ -2305,12 +1868,23 @@ declare function extend(objects: Record<string, unknown>): void;
  * `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;
@@ -2318,20 +1892,71 @@ 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
- * `renderer.tsx` fills them in. Only core's part of `RootState` is created here; packages building on
+ * `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:
@@ -2382,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
@@ -2865,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 { 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 };