@react-three/fiber 10.0.0-alpha.4 → 10.0.0-canary.04087d8

package/dist/shared/fiber.CB0XkHB0.d.cts

@@ -0,0 +1,812 @@
+import { FrameTimingState, FrameCallback as FrameCallback$1, SchedulerApi } from '@pmndrs/scheduler';
+import * as THREE from 'three';
+import { WebGLRenderer, WebGLRenderTarget, Color, ColorRepresentation } from 'three';
+import * as React from 'react';
+import * as ThreeWebGPU from 'three/webgpu';
+import { WebGPURenderer, RenderTarget, CanvasTarget } from 'three/webgpu';
+import { StoreApi } from 'zustand';
+import { UseBoundStoreWithEqualityFn } from 'zustand/traditional';
+import { uniform, nodeObject } from 'three/tsl';
+
+//* Utility Types ==============================
+
+type NonFunctionKeys<P> = { [K in keyof P]-?: P[K] extends Function ? never : K }[keyof P]
+type Overwrite<P, O> = Omit<P, NonFunctionKeys<O>> & O
+type Properties<T> = Pick<T, NonFunctionKeys<T>>
+type Mutable<P> = { -readonly [K in keyof P]: P[K] }
+type IsOptional<T> = undefined extends T ? true : false
+type IsAllOptional<T extends any[]> = T extends [infer First, ...infer Rest]
+  ? IsOptional<First> extends true
+    ? IsAllOptional<Rest>
+    : false
+  : true
+
+//* Camera Types ==============================
+
+type ThreeCamera = (THREE.OrthographicCamera | THREE.PerspectiveCamera) & { manual?: boolean }
+
+//* Act Type ==============================
+
+type Act = <T = any>(cb: () => Promise<T>) => Promise<T>
+
+//* Bridge & Block Types ==============================
+
+type Bridge = React.FC<{ children?: React.ReactNode }>
+
+type SetBlock = false | Promise<null> | null
+type UnblockProps = { set: React.Dispatch<React.SetStateAction<SetBlock>>; children: React.ReactNode }
+
+//* Object Map Type ==============================
+
+/* Original version
+export interface ObjectMap {
+  nodes: { [name: string]: THREE.Object3D }
+  materials: { [name: string]: THREE.Material }
+  meshes: { [name: string]: THREE.Mesh }
+}
+*/
+/* This version is an expansion found in a PR by itsdouges that seems abandoned but looks useful.
+It allows expansion but falls back to the original shape. (deleted due to stale, but If it doesnt conflict
+I will keep the use here)
+https://github.com/pmndrs/react-three-fiber/commits/generic-object-map/
+His description is:
+The object map type is now generic and can optionally declare the available properties for nodes, materials, and meshes.
+*/
+interface ObjectMap<
+  T extends { nodes?: string; materials?: string; meshes?: string } = {
+    nodes: string
+    materials: string
+    meshes: string
+  },
+> {
+  nodes: Record<T['nodes'] extends string ? T['nodes'] : string, THREE.Object3D>
+  materials: Record<T['materials'] extends string ? T['materials'] : string, THREE.Material>
+  meshes: Record<T['meshes'] extends string ? T['meshes'] : string, THREE.Mesh>
+}
+
+//* Equality Config ==============================
+
+interface EquConfig {
+  /** Compare arrays by reference equality a === b (default), or by shallow equality */
+  arrays?: 'reference' | 'shallow'
+  /** Compare objects by reference equality a === b (default), or by shallow equality */
+  objects?: 'reference' | 'shallow'
+  /** If true the keys in both a and b must match 1:1 (default), if false a's keys must intersect b's */
+  strict?: boolean
+}
+
+//* Disposable Type ==============================
+
+interface Disposable {
+  type?: string
+  dispose?: () => void
+}
+
+//* Event-related Types =====================================
+
+interface Intersection extends THREE.Intersection {
+  /** The event source (the object which registered the handler) */
+  eventObject: THREE.Object3D
+}
+
+type Camera = THREE.OrthographicCamera | THREE.PerspectiveCamera
+
+interface IntersectionEvent<TSourceEvent> extends Intersection {
+  /** The event source (the object which registered the handler) */
+  eventObject: THREE.Object3D
+  /** An array of intersections */
+  intersections: Intersection[]
+  /** vec3.set(pointer.x, pointer.y, 0).unproject(camera) */
+  unprojectedPoint: THREE.Vector3
+  /** Normalized event coordinates */
+  pointer: THREE.Vector2
+  /** pointerId of the original event for multiple pointer events */
+  pointerId: number
+  /** Delta between first click and this event */
+  delta: number
+  /** The ray that pierced it */
+  ray: THREE.Ray
+  /** The camera that was used by the raycaster */
+  camera: Camera
+  /** stopPropagation will stop underlying handlers from firing */
+  stopPropagation: () => void
+  /** The original host event */
+  nativeEvent: TSourceEvent
+  /** If the event was stopped by calling stopPropagation */
+  stopped: boolean
+}
+
+type ThreeEvent<TEvent> = IntersectionEvent<TEvent> & Properties<TEvent>
+type DomEvent = PointerEvent | MouseEvent | WheelEvent
+
+/** DOM event handlers registered on the canvas element */
+interface Events {
+  onClick: EventListener
+  onContextMenu: EventListener
+  onDoubleClick: EventListener
+  onWheel: EventListener
+  onPointerDown: EventListener
+  onPointerUp: EventListener
+  onPointerLeave: EventListener
+  onPointerMove: EventListener
+  onPointerCancel: EventListener
+  onLostPointerCapture: EventListener
+  onDragEnter: EventListener
+  onDragLeave: EventListener
+  onDragOver: EventListener
+  onDrop: EventListener
+}
+
+/** Event handlers that can be attached to R3F objects (meshes, groups, etc.) */
+interface EventHandlers {
+  onClick?: (event: ThreeEvent<MouseEvent>) => void
+  onContextMenu?: (event: ThreeEvent<MouseEvent>) => void
+  onDoubleClick?: (event: ThreeEvent<MouseEvent>) => void
+  /** Fires continuously while dragging over the object */
+  onDragOver?: (event: ThreeEvent<DragEvent>) => void
+  /** Fires once when drag enters the object */
+  onDragOverEnter?: (event: ThreeEvent<DragEvent>) => void
+  /** Fires once when drag leaves the object */
+  onDragOverLeave?: (event: ThreeEvent<DragEvent>) => void
+  /** Fires when drag misses this object (for objects that have drag handlers) */
+  onDragOverMissed?: (event: DragEvent) => void
+  /** Fires when a drop occurs on this object */
+  onDrop?: (event: ThreeEvent<DragEvent>) => void
+  /** Fires when a drop misses this object (for objects that have drop handlers) */
+  onDropMissed?: (event: DragEvent) => void
+  onPointerUp?: (event: ThreeEvent<PointerEvent>) => void
+  onPointerDown?: (event: ThreeEvent<PointerEvent>) => void
+  onPointerOver?: (event: ThreeEvent<PointerEvent>) => void
+  onPointerOut?: (event: ThreeEvent<PointerEvent>) => void
+  onPointerEnter?: (event: ThreeEvent<PointerEvent>) => void
+  onPointerLeave?: (event: ThreeEvent<PointerEvent>) => void
+  onPointerMove?: (event: ThreeEvent<PointerEvent>) => void
+  onPointerMissed?: (event: MouseEvent) => void
+  onPointerCancel?: (event: ThreeEvent<PointerEvent>) => void
+  onWheel?: (event: ThreeEvent<WheelEvent>) => void
+  onLostPointerCapture?: (event: ThreeEvent<PointerEvent>) => void
+
+  //* Visibility Events --------------------------------
+  /** Fires when object enters/exits camera frustum. Receives true when in view, false when out. */
+  onFramed?: (inView: boolean) => void
+  /** Fires when object occlusion state changes (WebGPU only, requires occlusionTest=true on object) */
+  onOccluded?: (occluded: boolean) => void
+  /** Fires when combined visibility changes (frustum + occlusion + visible prop) */
+  onVisible?: (visible: boolean) => void
+}
+
+type FilterFunction = (items: THREE.Intersection[], state: RootState) => THREE.Intersection[]
+type ComputeFunction = (event: DomEvent, root: RootState, previous?: RootState) => void
+
+/** Configuration for XR pointer registration (controllers/hands) */
+interface XRPointerConfig {
+  /** Ray origin (updated each frame by XR system) */
+  ray: THREE.Ray
+  /** Optional: custom compute function for this pointer */
+  compute?: (state: RootState) => void
+  /** Pointer type identifier */
+  type: 'controller' | 'hand' | 'gaze'
+  /** Which hand (for controller/hand types) */
+  handedness?: 'left' | 'right'
+}
+
+interface EventManager<TTarget> {
+  /** Determines if the event layer is active */
+  enabled: boolean
+  /** Event layer priority, higher prioritized layers come first and may stop(-propagate) lower layer  */
+  priority: number
+  /** The compute function needs to set up the raycaster and an xy- pointer  */
+  compute?: ComputeFunction
+  /** The filter can re-order or re-structure the intersections  */
+  filter?: FilterFunction
+  /** The target node the event layer is tied to */
+  connected?: TTarget
+  /** All the pointer event handlers through which the host forwards native events */
+  handlers?: Events
+  /** Allows re-connecting to another target */
+  connect?: (target: TTarget) => void
+  /** Removes all existing events handlers from the target */
+  disconnect?: () => void
+  /** Triggers a onPointerMove with the last known event. This can be useful to enable raycasting without
+   *  explicit user interaction, for instance when the camera moves a hoverable object underneath the cursor.
+   *  @param pointerId - Optional pointer ID to update specific pointer only
+   */
+  update?: (pointerId?: number) => void
+  /** Defer pointer move raycasting to frame start (default: true) */
+  frameTimedRaycasts?: boolean
+  /** Always fire raycaster immediately on scroll events (default: true) */
+  alwaysFireOnScroll?: boolean
+  /** Automatically re-raycast every frame to detect hover changes from moving objects/camera (default: false) */
+  updateOnFrame?: boolean
+  /** Flush deferred pointer raycasts. Called by scheduler at frame start (input phase). */
+  flush?: () => void
+  /** Register an XR pointer (controller/hand). Returns assigned pointerId */
+  registerPointer?: (config: XRPointerConfig) => number
+  /** Unregister an XR pointer */
+  unregisterPointer?: (pointerId: number) => void
+}
+
+interface PointerCaptureTarget {
+  intersection: Intersection
+  target: Element
+}
+
+//* Visibility System Types =====================================
+
+/** Entry in the visibility registry for tracking object visibility state */
+interface VisibilityEntry {
+  object: THREE.Object3D
+  handlers: Pick<EventHandlers, 'onFramed' | 'onOccluded' | 'onVisible'>
+  lastFramedState: boolean | null
+  lastOccludedState: boolean | null
+  lastVisibleState: boolean | null
+}
+
+//* Scheduler Types (useFrame) ==============================
+//
+// The generic, framework-agnostic scheduler types now live in @pmndrs/scheduler.
+// This file re-exports them and layers r3f's RootState-aware frame state on top,
+// so existing `#types` imports across the codebase keep resolving unchanged.
+
+
+
+// Frame State (r3f-specific) --------------------------------
+
+/**
+ * State passed to useFrame callbacks (extends RootState with timing).
+ */
+interface FrameNextState extends RootState, FrameTimingState {}
+
+/** Alias for FrameNextState */
+type FrameState = FrameNextState
+
+// Callback Types (r3f-specific) --------------------------------
+
+/**
+ * Callback function for useFrame. Receives the full r3f RootState plus timing.
+ */
+type FrameNextCallback = FrameCallback$1<RootState>
+
+/** Alias for FrameNextCallback */
+type FrameCallback = FrameNextCallback
+
+//* Renderer Support ==============================
+// Core has no static imports from `three` or `three/webgpu`. Both are separate bundles built on one
+// shared `three.core.js`, and there is no import that gives you the core alone -- so a core that
+// statically imported either one would put that renderer into every app's eager graph. Instead each
+// renderer is described by a *support* object, loaded when a root needs it, that carries the three
+// namespace of its flavour plus the handful of renderer-specific classes core touches by name.
+
+/** The Three.js namespace of either flavour. Classes in three's shared core are the same objects in both. */
+type ThreeNamespace = typeof THREE | typeof ThreeWebGPU
+
+/**
+ * Three's shared core: every export `three` and `three/webgpu` have in common (`Vector3`, `Scene`,
+ * `Mesh`, the constants, ...). This is what core code reads from `getThree()`. The renderer-specific
+ * exports are reached through the flavour's support object, never by name from here.
+ */
+type ThreeCore = Pick<typeof THREE, Extract<keyof typeof THREE, keyof typeof ThreeWebGPU>>
+
+/** Node classes and TSL functions the occlusion observer is built from (WebGPU only). */
+interface OcclusionSupport {
+  Node: typeof ThreeWebGPU.Node
+  NodeUpdateType: typeof ThreeWebGPU.NodeUpdateType
+  MeshBasicNodeMaterial: typeof ThreeWebGPU.MeshBasicNodeMaterial
+  uniform: typeof uniform
+  nodeObject: typeof nodeObject
+}
+
+/** WebGL renderer support: the `three` namespace and the classes only it exports. */
+interface WebGLSupport {
+  kind: 'webgl'
+  /** `import * as THREE from 'three'`: JSX constructors for roots on this renderer, and core's classes. */
+  three: typeof THREE
+  Renderer: typeof THREE.WebGLRenderer
+  /** Render target for `useRenderTarget`. */
+  RenderTarget: typeof THREE.WebGLRenderTarget
+  /** Cube render target for `<Environment>`. */
+  CubeRenderTarget: typeof THREE.WebGLCubeRenderTarget
+}
+
+/** WebGPU renderer support: the `three/webgpu` namespace and the classes only it exports. */
+interface WebGPUSupport {
+  kind: 'webgpu'
+  /** `import * as THREE from 'three/webgpu'`: JSX constructors (node materials included) and core's classes. */
+  three: typeof ThreeWebGPU
+  Renderer: typeof ThreeWebGPU.WebGPURenderer
+  /** Render target for `useRenderTarget`. */
+  RenderTarget: typeof ThreeWebGPU.RenderTarget
+  /** Cube render target for `<Environment>`. */
+  CubeRenderTarget: typeof ThreeWebGPU.CubeRenderTarget
+  /** Canvas target for secondary canvases sharing a primary's renderer. */
+  CanvasTarget: typeof ThreeWebGPU.CanvasTarget
+  occlusion: OcclusionSupport
+}
+
+/** Support for the renderer a root ended up with. Selected by `configure()`, kept on `state.internal.support`. */
+type RendererSupport = WebGLSupport | WebGPUSupport
+
+/**
+ * What an entry point hands to `createRoot`/`Canvas`: a loader per renderer it can construct.
+ *
+ * The root entry provides both as dynamic imports, so an app downloads only the renderer its
+ * Canvas asks for. `/legacy` and `/webgpu` provide one each, statically, for apps that would rather
+ * have no extra request than the choice.
+ */
+interface RendererProvider {
+  webgl?: () => WebGLSupport | Promise<WebGLSupport>
+  webgpu?: () => WebGPUSupport | Promise<WebGPUSupport>
+}
+
+//* Register ==============================
+// The root entry can construct either renderer, so by default `state.renderer` is the union of
+// both and a WebGPU-only member (`renderer.compute`, `renderer.backend`) needs a narrow. An app that
+// has decided on one renderer says so once, and every renderer-typed field follows -- `useThree`,
+// `useFrame`, `onCreated`, `useRenderTarget`, `state.internal.support`:
+//
+//   declare module '@react-three/fiber' {
+//     interface Register {
+//       renderer: 'webgpu'
+//     }
+//   }
+//
+// Same pattern as `Register` in @react-three/tsl (and TanStack Router). Nothing registered means
+// the union, unchanged. The `/legacy` and `/webgpu` entries are the same thing decided by import
+// path; this is for apps on `@react-three/fiber` that want the narrowed types without changing it.
+
+/**
+ * Augment this to type `RootState` for the renderer your app uses. Recognised keys:
+ * - `renderer`: `'webgpu'` or `'webgl'`
+ */
+interface Register {}
+
+/** The registered renderer, or `'any'` when nothing is registered. */
+type RegisteredRenderer = Register extends { renderer: infer R extends 'webgl' | 'webgpu' } ? R : 'any'
+
+/** Pick the type for the registered renderer: WebGPU, WebGL, or both when nothing is registered. */
+type ForRegisteredRenderer<WebGPU, WebGL, Either = WebGPU | WebGL> = RegisteredRenderer extends 'webgpu'
+  ? WebGPU
+  : RegisteredRenderer extends 'webgl'
+    ? WebGL
+    : Either
+
+/** The renderer type of `state.renderer`: a union of both unless one is registered. */
+type R3FRenderer = ForRegisteredRenderer<WebGPURenderer, WebGLRenderer>
+
+/** What `useRenderTarget` returns: a union of both target classes unless a renderer is registered. */
+type R3FRenderTarget = ForRegisteredRenderer<RenderTarget, WebGLRenderTarget>
+
+/** The renderer support on `state.internal.support`, narrowed to the registered renderer. */
+type R3FRendererSupport = ForRegisteredRenderer<WebGPUSupport, WebGLSupport, RendererSupport>
+
+//* Core Store Types ========================================
+
+type Subscription = {
+  ref: React.RefObject<RenderCallback>
+  priority: number
+  store: RootStore
+}
+
+/** Per-pointer state for multi-touch and XR support */
+type PointerState = {
+  /** Objects currently hovered by this pointer */
+  hovered: Map<string, ThreeEvent<DomEvent>>
+  /** Objects capturing this pointer */
+  captured: Map<THREE.Object3D, PointerCaptureTarget>
+  /** Initial click position [x, y] */
+  initialClick: [x: number, y: number]
+  /** Objects hit on initial click */
+  initialHits: THREE.Object3D[]
+}
+
+type Dpr = number | [min: number, max: number]
+
+interface Size {
+  width: number
+  height: number
+  top: number
+  left: number
+}
+
+type Frameloop = 'always' | 'demand' | 'never'
+
+interface Viewport extends Size {
+  /** The initial pixel ratio */
+  initialDpr: number
+  /** Current pixel ratio */
+  dpr: number
+  /** size.width / viewport.width */
+  factor: number
+  /** Camera distance */
+  distance: number
+  /** Camera aspect ratio: width / height */
+  aspect: number
+}
+
+type RenderCallback = (state: RootState, delta: number, frame?: XRFrame) => void
+
+interface Performance {
+  /** Current performance normal, between min and max */
+  current: number
+  /** How low the performance can go, between 0 and max */
+  min: number
+  /** How high the performance can go, between min and max */
+  max: number
+  /** Time until current returns to max in ms */
+  debounce: number
+  /** Sets current to min, puts the system in regression */
+  regress: () => void
+}
+
+interface InternalState {
+  interaction: THREE.Object3D[]
+  subscribers: Subscription[]
+  /** Per-pointer state (hover, capture, click tracking) - replaces hovered, capturedMap, initialClick, initialHits */
+  pointerMap: Map<number, PointerState>
+  /** Pointers needing raycast this frame (used with frameTimedRaycasts) */
+  pointerDirty: Map<number, DomEvent>
+  /** Last event received (for events.update() compatibility) */
+  lastEvent: React.RefObject<DomEvent | null>
+  /** @deprecated Use pointerMap.get(pointerId).hovered instead */
+  hovered: Map<string, ThreeEvent<DomEvent>>
+  /** @deprecated Use pointerMap.get(pointerId).captured instead */
+  capturedMap: Map<number, Map<THREE.Object3D, PointerCaptureTarget>>
+  /** @deprecated Use pointerMap.get(pointerId).initialClick instead */
+  initialClick: [x: number, y: number]
+  /** @deprecated Use pointerMap.get(pointerId).initialHits instead */
+  initialHits: THREE.Object3D[]
+  /** Visibility event registry (onFramed, onOccluded, onVisible) */
+  visibilityRegistry: Map<string, VisibilityEntry>
+  /** Whether occlusion queries are enabled (WebGPU only) */
+  occlusionEnabled: boolean
+  /** Reference to the invisible occlusion observer mesh */
+  occlusionObserver: THREE.Mesh | null
+  /** Cached occlusion results from render pass - keyed by Object3D */
+  occlusionCache: Map<THREE.Object3D, boolean | null>
+  /** Internal helper group for R3F system objects (occlusion observer, etc.) */
+  helperGroup: THREE.Group | null
+  active: boolean
+  priority: number
+  frames: number
+  subscribe: (callback: React.RefObject<RenderCallback>, priority: number, store: RootStore) => () => void
+  /** Internal renderer storage - use state.renderer or state.gl to access */
+  actualRenderer: R3FRenderer
+  /**
+   * The renderer support `configure()` loaded for this root: the three namespace of that flavour
+   * (JSX constructors, core's classes) and the renderer-specific classes core needs by name.
+   * Selected once, from the entry's provider, and copied into portals with the rest of `internal`.
+   */
+  support: R3FRendererSupport
+  /**
+   * Releases this root's lease on its renderer. The last release disposes a renderer R3F created;
+   * a renderer passed in as an instance is never disposed by R3F.
+   */
+  releaseRenderer?: () => void | Promise<void>
+  /** Global scheduler reference (for useFrame hook) */
+  scheduler: SchedulerApi | null
+  /**
+   * Replaces `renderer.render(scene, camera)` in the default render job when set. Set it with
+   * `setRenderOverride(store, fn)`; the job keeps its fps throttle, error handling and user
+   * render-phase takeover. Used by `useRenderPipeline`.
+   */
+  renderOverride?: (() => void) | null
+  /** This root's unique ID in the global scheduler */
+  rootId?: string
+  /** Function to unregister this root from the global scheduler */
+  unregisterRoot?: () => void
+  /** Function to stop following devicePixelRatio changes */
+  unwatchDpr?: () => void
+  /** Container for child attachment (scene for root, original container for portals) */
+  container?: THREE.Object3D
+  /**
+   * The CanvasTarget this root sizes and renders through.
+   *
+   * A primary (`<Canvas id>`) owns the renderer's default target -- the one three itself built
+   * around the canvas element -- so sizing it is sizing the renderer. A secondary owns a target
+   * R3F created for its own element. Either way there is exactly one target per canvas element,
+   * and the canvas-target job makes it the renderer's active one before this root renders.
+   * Absent on WebGL and on a WebGPU canvas that is neither a primary nor sharing, where the renderer
+   * is sized directly.
+   * @see https://threejs.org/docs/#api/en/renderers/common/CanvasTarget
+   */
+  canvasTarget?: CanvasTarget
+  /**
+   * Set when this root's canvas target has been resized and the backend's cached render pass
+   * descriptor (which holds a depth-stencil view built once per canvas) is therefore stale.
+   *
+   * Flushed by the canvas-target job in the `start` phase, which is the only place this root's
+   * target is guaranteed to be the renderer's active one — `backend.updateSize()` operates on
+   * whatever `getCanvasTarget()` returns, so calling it from the resize subscription would
+   * invalidate some other canvas's descriptor instead.
+   *
+   * @see https://github.com/pmndrs/react-three-fiber/issues/3847
+   */
+  canvasTargetSizeDirty?: boolean
+  /**
+   * Whether multi-canvas rendering is active.
+   * True on a `<Canvas primary>` once another canvas shares its renderer, and on that canvas.
+   * When true, setCanvasTarget is called before each render.
+   */
+  isMultiCanvas?: boolean
+  /**
+   * Whether this canvas is a secondary canvas sharing another's renderer: it found a
+   * `<Canvas primary>` (automatically, or through `share="id"`) and borrows its renderer.
+   */
+  isSecondary?: boolean
+  /**
+   * The id of the primary canvas this secondary canvas shares.
+   * Only set when isSecondary is true and the primary has an `id`.
+   */
+  targetId?: string
+  /**
+   * This secondary stopped sharing because the primary's renderer fell back to its
+   * WebGL2 backend (#3965): it owns the renderer it constructed, so it is not
+   * `isSecondary` (which marks a canvas borrowing another's renderer).
+   */
+  sharedRendererFallback?: boolean
+  /**
+   * Function to withdraw this primary canvas from the registry.
+   * Only set on a `<Canvas primary>`.
+   */
+  unregisterPrimary?: () => void
+  /**
+   * Function to stop tracking this canvas as one that built its own WebGPU renderer while no primary
+   * existed (for the late-primary warning).
+   */
+  untrackStandalone?: () => void
+  /** Whether canvas dimensions are forced to even numbers */
+  forceEven?: boolean
+}
+
+interface XRManager {
+  connect: () => void
+  disconnect: () => void
+}
+
+//* Root State Interface ====================================
+
+interface RootState {
+  /** Set current state */
+  set: StoreApi<RootState>['setState']
+  /** Get current state */
+  get: StoreApi<RootState>['getState']
+  /**
+   * The store of the canvas that owns this root's renderer.
+   * - For primary/independent canvases: points to its own store (self-reference)
+   * - For secondary canvases: points to the primary canvas's store
+   * - Portals copy it from their parent
+   *
+   * Anything shared per renderer rather than per canvas (e.g. @react-three/tsl's resources)
+   * resolves through it.
+   */
+  primaryStore: RootStore
+  /** @deprecated Use `renderer` instead. The instance of the renderer (typed as WebGLRenderer for backwards compat) */
+  gl: ForRegisteredRenderer<WebGPURenderer, THREE.WebGLRenderer, THREE.WebGLRenderer>
+  /**
+   * The renderer instance. Both renderers unless the app registered one
+   * (`declare module '@react-three/fiber' { interface Register { renderer: 'webgpu' } }`), or the
+   * entry decides it (`/webgpu`, `/legacy`).
+   */
+  renderer: R3FRenderer
+  /** Inspector of the webGPU Renderer. Init in the canvas */
+  inspector: any // Inspector type from three/webgpu
+
+  /** Default camera */
+  camera: ThreeCamera
+  /** Camera frustum for visibility checks - auto-updated each frame when autoUpdateFrustum is true */
+  frustum: THREE.Frustum
+  /** Whether to automatically update the frustum each frame (default: true) */
+  autoUpdateFrustum: boolean
+  /** Default scene (may be overridden in portals to point to the portal container) */
+  scene: THREE.Scene
+  /** The actual root THREE.Scene - always points to the true scene, even inside portals */
+  rootScene: THREE.Scene
+  /** Default raycaster */
+  raycaster: THREE.Raycaster
+  /** Event layer interface, contains the event handler and the node they're connected to */
+  events: EventManager<any>
+  /** XR interface */
+  xr: XRManager
+  /** Currently used controls */
+  controls: THREE.EventDispatcher | null
+  /** Normalized event coordinates */
+  pointer: THREE.Vector2
+  /** @deprecated Normalized event coordinates, use "pointer" instead! */
+  mouse: THREE.Vector2
+  /** Color space assigned to 8-bit input textures (color maps). Most textures are authored in sRGB. */
+  textureColorSpace: THREE.ColorSpace
+  /** Render loop flags */
+  frameloop: Frameloop
+  performance: Performance
+  /** Reactive pixel-size of the canvas */
+  size: Size
+  /** Reactive size of the viewport in threejs units */
+  viewport: Viewport & {
+    getCurrentViewport: (
+      camera?: ThreeCamera,
+      target?: THREE.Vector3 | Parameters<THREE.Vector3['set']>,
+      size?: Size,
+    ) => Omit<Viewport, 'dpr' | 'initialDpr'>
+  }
+  /** Flags the canvas for render, but doesn't render in itself */
+  invalidate: (frames?: number, stackFrames?: boolean) => void
+  /** Advance (render) one step */
+  advance: (timestamp: number, runGlobalEffects?: boolean) => void
+  /** Shortcut to setting the event layer */
+  setEvents: (events: Partial<EventManager<any>>) => void
+  /** Shortcut to manual sizing. No args resets to props/container. Single arg creates square. */
+  setSize: (width?: number, height?: number, top?: number, left?: number) => void
+  /** Shortcut to manual setting the pixel ratio */
+  setDpr: (dpr: Dpr) => void
+  /** Shortcut to setting frameloop flags. No args resets to 'always'. */
+  setFrameloop: (frameloop?: Frameloop) => void
+  /** Set error state to propagate to error boundary */
+  setError: (error: Error | null) => void
+  /** Current error state (null when no error) */
+  error: Error | null
+  /** Global Texture registry (key → Texture, usually keyed by URL) - use useTextures() hook for access + lifecycle */
+  textures: Map<string, THREE.Texture>
+  /** Internal: refcount per texture key, driven by mounted useTexture consumers (registry enrollment is on by default) */
+  _textureRefs: Map<string, number>
+  /** Internal: whether setSize() has taken ownership of canvas dimensions */
+  _sizeImperative: boolean
+  /** Internal: stored size props from Canvas for reset functionality */
+  _sizeProps: { width?: number; height?: number } | null
+  /** When the canvas was clicked but nothing was hit */
+  onPointerMissed?: (event: MouseEvent) => void
+  /** When a dragover event has missed any target */
+  onDragOverMissed?: (event: DragEvent) => void
+  /** When a drop event has missed any target */
+  onDropMissed?: (event: DragEvent) => void
+  /** If this state model is layered (via createPortal) then this contains the previous layer */
+  previousRoot?: RootStore
+  /** Internals */
+  internal: InternalState
+  // flags for triggers
+  // if we are using the webGl renderer, this will be true
+  isLegacy: ForRegisteredRenderer<false, true, boolean>
+  // regardless of renderer, if the system supports webGpu, this will be true
+  webGPUSupported: boolean
+  //if we are on native
+  isNative: boolean
+}
+
+type RootStore = UseBoundStoreWithEqualityFn<StoreApi<RootState>>
+
+//* Reconciler Types ==============================
+
+// FiberRoot is an opaque internal React type - we define it locally
+// to avoid bundling @types/react-reconciler which causes absolute path issues
+type FiberRoot = any
+
+/** A promise tagged with its state, the protocol React's `use` reads */
+type TrackedPromise<T> = Promise<T> &
+  ({ status: 'pending' } | { status: 'fulfilled'; value: T } | { status: 'rejected'; reason: unknown })
+
+interface Root {
+  fiber: FiberRoot
+  store: RootStore
+  /** Set while a teardown waits on React. Configure and render clear it, which cancels the teardown */
+  unmountClaim: symbol | null
+  /** Pending only while a renderer is being created */
+  ready: TrackedPromise<unknown>
+}
+
+type AttachFnType<O = any> = (parent: any, self: O) => () => void
+type AttachType<O = any> = string | AttachFnType<O>
+
+type ConstructorRepresentation<T = any> = new (...args: any[]) => T
+
+interface Catalogue {
+  [name: string]: ConstructorRepresentation
+}
+
+// TODO: handle constructor overloads
+// https://github.com/pmndrs/react-three-fiber/pull/2931
+// https://github.com/microsoft/TypeScript/issues/37079
+type Args<T> = T extends ConstructorRepresentation
+  ? T extends typeof Color
+    ? [r: number, g: number, b: number] | [color: ColorRepresentation]
+    : ConstructorParameters<T>
+  : any[]
+
+type ArgsProp<P> = P extends ConstructorRepresentation
+  ? IsAllOptional<ConstructorParameters<P>> extends true
+    ? { args?: Args<P> }
+    : { args: Args<P> }
+  : { args: unknown[] }
+
+type InstanceProps<T = any, P = any> = ArgsProp<P> & {
+  object?: T
+  dispose?: null
+  attach?: AttachType<T>
+}
+
+interface Instance<O = any> {
+  root: RootStore
+  type: string
+  parent: Instance | null
+  children: Instance[]
+  props: InstanceProps<O> & Record<string, unknown>
+  object: O & { __r3f?: Instance<O> }
+  eventCount: number
+  handlers: Partial<EventHandlers>
+  attach?: AttachType<O>
+  previousAttach?: any
+  isHidden: boolean
+  /** Set of props that have been applied via once() */
+  appliedOnce?: Set<string>
+}
+
+interface HostConfig {
+  type: string
+  props: Instance['props']
+  container: RootStore
+  instance: Instance
+  textInstance: void
+  suspenseInstance: Instance
+  hydratableInstance: never
+  formInstance: never
+  publicInstance: Instance['object']
+  hostContext: {}
+  childSet: never
+  timeoutHandle: number | undefined
+  noTimeout: -1
+  TransitionStatus: null
+}
+declare global {
+  var IS_REACT_ACT_ENVIRONMENT: boolean | undefined
+}
+
+interface RootExtension {
+    /** Unique name. Registering the same name again replaces the entry (HMR-safe); roots it already
+     *  set up are not set up a second time, but get the new entry's dispose and hmr. */
+    name: string;
+    /**
+     * Called once per root, after its renderer exists and before `onCreated` and the first frame.
+     * `isLegacy` and `primaryStore` are known by then, so an extension can skip WebGL roots or defer
+     * to the primary canvas. Return fields to merge into the root's state, or nothing.
+     */
+    setup?(store: RootStore): Partial<RootState> | void;
+    /** Called when a root this extension set up unmounts. */
+    dispose?(store: RootStore): void;
+    /** Called when `<Canvas>` detects hot module replacement (skipped with `hmr={false}`). */
+    hmr?(store: RootStore): void;
+}
+/**
+ * Register an extension. It is set up on every live root immediately, and on every root created
+ * afterwards. Returns a function that unregisters it: new roots are no longer set up, while roots
+ * it already set up keep its state and still get its dispose when they unmount.
+ */
+declare function registerRootExtension(extension: RootExtension): () => void;
+/**
+ * Point a root's default render job at a different render function, or back at
+ * `renderer.render(scene, camera)` with `null`.
+ *
+ * The default job keeps everything else: the Canvas `fps` throttle, error propagation to the error
+ * boundary, and backing off when a user `useFrame(..., { phase: 'render' })` job takes over.
+ */
+declare function setRenderOverride(store: RootStore, render: (() => void) | null): void;
+
+/**
+ * Returns the R3F Canvas' Zustand store. Useful for [transient updates](https://github.com/pmndrs/zustand#transient-updates-for-often-occurring-state-changes).
+ * @see https://docs.pmnd.rs/react-three-fiber/api/hooks#usestore
+ */
+declare function useStore(): RootStore;
+/**
+ * Accesses R3F's internal state, containing renderer, canvas, scene, etc.
+ * @see https://docs.pmnd.rs/react-three-fiber/api/hooks#usethree
+ */
+declare function useThree<T = RootState>(selector?: (state: RootState) => T, equalityFn?: <T>(state: T, newState: T) => boolean): T;
+
+/**
+ * React context that carries the current root's {@link RootStore}. Each root provides its store and
+ * each portal provides its own scoped one; `useStore`, and every hook built on it, reads it.
+ *
+ * Stored on `globalThis` under `Symbol.for('@react-three/fiber.context')`, so every copy and entry
+ * of fiber shares a single context.
+ */
+declare const context: React.Context<RootStore>;
+
+export { useStore as ah, useThree as ai, context as aj, registerRootExtension as r, setRenderOverride as s };
+export type { ObjectMap as $, AttachFnType as A, ArgsProp as B, ConstructorRepresentation as C, Dpr as D, Events as E, Frameloop as F, InstanceProps as G, Instance as H, InternalState as I, HostConfig as J, Properties as K, IsOptional as L, Mutable as M, NonFunctionKeys as N, Overwrite as O, PointerState as P, IsAllOptional as Q, R3FRenderTarget as R, Subscription as S, ThreeEvent as T, ThreeCamera as U, Viewport as V, Act as W, XRManager as X, Bridge as Y, SetBlock as Z, UnblockProps as _, RootExtension as a, EquConfig as a0, Disposable as a1, FrameNextState as a2, FrameState as a3, FrameNextCallback as a4, FrameCallback as a5, ThreeNamespace as a6, ThreeCore as a7, OcclusionSupport as a8, WebGLSupport as a9, WebGPUSupport as aa, RendererSupport as ab, RendererProvider as ac, Register as ad, RegisteredRenderer as ae, ForRegisteredRenderer as af, R3FRendererSupport as ag, R3FRenderer as b, Size as c, RenderCallback as d, Performance as e, RootState as f, RootStore as g, Intersection as h, Camera as i, IntersectionEvent as j, DomEvent as k, EventHandlers as l, FilterFunction as m, ComputeFunction as n, XRPointerConfig as o, EventManager as p, PointerCaptureTarget as q, VisibilityEntry as t, FiberRoot as u, TrackedPromise as v, Root as w, AttachType as x, Catalogue as y, Args as z };