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

package/dist/shared/{fiber.I5Q4dVvl.d.cts → fiber.DQTSZ24m.d.cts}

@@ -1,9 +1,10 @@
 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 { WebGLRenderer, WebGLRenderTarget, Color as Color$1, ColorRepresentation } from 'three';
 import * as ThreeWebGPU from 'three/webgpu';
-import { WebGPURenderer, RenderTarget, CanvasTarget } from 'three/webgpu';
+import { WebGPURenderer, RenderTarget, CanvasTarget, WebGPURendererParameters } from 'three/webgpu';
+import * as React$1 from 'react';
+import { ReactNode } from 'react';
 import { StoreApi } from 'zustand';
 import { UseBoundStoreWithEqualityFn } from 'zustand/traditional';
 import { uniform, nodeObject } from 'three/tsl';
@@ -31,10 +32,10 @@ type Act = <T = any>(cb: () => Promise<T>) => Promise<T>
 
 //* Bridge & Block Types ==============================
 
-type Bridge = React.FC<{ children?: React.ReactNode }>
+type Bridge = React$1.FC<{ children?: React$1.ReactNode }>
 
 type SetBlock = false | Promise<null> | null
-type UnblockProps = { set: React.Dispatch<React.SetStateAction<SetBlock>>; children: React.ReactNode }
+type UnblockProps = { set: React$1.Dispatch<React$1.SetStateAction<SetBlock>>; children: React$1.ReactNode }
 
 //* Object Map Type ==============================
 
@@ -339,10 +340,14 @@ interface RendererProvider {
 }
 
 //* 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`:
+// The base RootState is typed for both renderers, so by default `state.renderer` is the union and a
+// WebGPU-only member (`renderer.compute`, `renderer.backend`) needs a narrow. That base is what
+// `@react-three/fiber/extension` (the entry for libraries) and the `RootState` type expose, so a
+// library compiles for apps on either renderer.
+//
+// Apps rarely need this: each entry's hooks are already typed for the renderer it renders with
+// (`@react-three/fiber` WebGPU, `/legacy` WebGL). Registering narrows the base types too, for code
+// that goes through them (`/extension` hooks in an app, `RootState` annotations):
 //
 //   declare module '@react-three/fiber' {
 //     interface Register {
@@ -351,8 +356,7 @@ interface RendererProvider {
 //   }
 //
 // 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.
+// the union, unchanged.
 
 /**
  * Augment this to type `RootState` for the renderer your app uses. Recognised keys:
@@ -382,7 +386,7 @@ type R3FRendererSupport = ForRegisteredRenderer<WebGPUSupport, WebGLSupport, Ren
 //* Core Store Types ========================================
 
 type Subscription = {
-  ref: React.RefObject<RenderCallback>
+  ref: React$1.RefObject<RenderCallback>
   priority: number
   store: RootStore
 }
@@ -446,7 +450,7 @@ interface InternalState {
   /** Pointers needing raycast this frame (used with frameTimedRaycasts) */
   pointerDirty: Map<number, DomEvent>
   /** Last event received (for events.update() compatibility) */
-  lastEvent: React.RefObject<DomEvent | null>
+  lastEvent: React$1.RefObject<DomEvent | null>
   /** @deprecated Use pointerMap.get(pointerId).hovered instead */
   hovered: Map<string, ThreeEvent<DomEvent>>
   /** @deprecated Use pointerMap.get(pointerId).captured instead */
@@ -468,7 +472,7 @@ interface InternalState {
   active: boolean
   priority: number
   frames: number
-  subscribe: (callback: React.RefObject<RenderCallback>, priority: number, store: RootStore) => () => void
+  subscribe: (callback: React$1.RefObject<RenderCallback>, priority: number, store: RootStore) => () => void
   /** Internal renderer storage - use state.renderer or state.gl to access */
   actualRenderer: R3FRenderer
   /**
@@ -477,6 +481,11 @@ interface InternalState {
    * Selected once, from the entry's provider, and copied into portals with the rest of `internal`.
    */
   support: R3FRendererSupport
+  /**
+   * Releases this root's lease on its renderer. The last release disposes a renderer R3F created;
+   * a renderer passed in as an instance is never disposed by R3F.
+   */
+  releaseRenderer?: () => void | Promise<void>
   /** Global scheduler reference (for useFrame hook) */
   scheduler: SchedulerApi | null
   /**
@@ -487,8 +496,14 @@ interface InternalState {
   renderOverride?: (() => void) | null
   /** This root's unique ID in the global scheduler */
   rootId?: string
+  /** Scheduler id reserved when a primary publishes its renderer, before root jobs are installed. */
+  pendingRootId?: string
+  /** Default scheduler predecessor when borrowing a primary renderer. */
+  sharedAfter?: 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
   /**
@@ -498,7 +513,8 @@ interface InternalState {
    * 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 an id-less WebGPU canvas, where the renderer is sized directly.
+   * 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
@@ -516,25 +532,36 @@ interface InternalState {
   canvasTargetSizeDirty?: boolean
   /**
    * Whether multi-canvas rendering is active.
-   * True when any canvas uses `renderer={{ primaryCanvas: 'id' }}` to share a renderer.
+   * 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.
-   * True when `target` prop is used.
+   * 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 targets.
-   * Only set when isSecondary is true.
+   * The id of the primary canvas this secondary canvas shares.
+   * Only set when isSecondary is true and the primary has an `id`.
    */
   targetId?: string
   /**
-   * Function to unregister this primary canvas from the registry.
-   * Only set when this canvas has an `id` prop.
+   * 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
 }
@@ -660,9 +687,23 @@ type RootStore = UseBoundStoreWithEqualityFn<StoreApi<RootState>>
 // 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
+  state:
+    | { status: 'open' }
+    | { status: 'closing'; token: symbol; settled: Promise<void>; settle: () => void }
+    | { status: 'disposed' }
+  configuration: {
+    previous?: RenderProps<HTMLCanvasElement | OffscreenCanvas>
+    apply: (props: RenderProps<HTMLCanvasElement | OffscreenCanvas>) => void
+  }
+  /** Settles once all accepted configuration has been applied */
+  ready: TrackedPromise<unknown>
 }
 
 type AttachFnType<O = any> = (parent: any, self: O) => () => void
@@ -678,7 +719,7 @@ interface Catalogue {
 // 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
+  ? T extends typeof Color$1
     ? [r: number, g: number, b: number] | [color: ColorRepresentation]
     : ConstructorParameters<T>
   : any[]
@@ -706,6 +747,7 @@ interface Instance<O = any> {
   handlers: Partial<EventHandlers>
   attach?: AttachType<O>
   previousAttach?: any
+  previousVisible: boolean | undefined
   isHidden: boolean
   /** Set of props that have been applied via once() */
   appliedOnce?: Set<string>
@@ -731,6 +773,419 @@ declare global {
   var IS_REACT_ACT_ENVIRONMENT: boolean | undefined
 }
 
+//* 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
+}
+
+//* Renderer Settings ==============================
+
+/**
+ * Shadow map setting: `true` uses `THREE.PCFShadowMap`, a string picks a type, an object is assigned
+ * to `renderer.shadowMap`.
+ *
+ * `'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
+ */
+type ShadowsConfig = boolean | 'basic' | 'percentage' | 'soft' | 'variance' | Partial<THREE.WebGLShadowMap>
+
+/**
+ * Renderer-wide settings R3F reads from the `renderer` / `gl` props bag. They are not renderer
+ * properties: R3F applies them itself, and only on the canvas that owns its renderer.
+ */
+interface RendererSettingsConfig extends ColorManagementConfig {
+  /**
+   * Enables shadows. Only on a renderer R3F builds from a props bag: a renderer instance or factory
+   * keeps the `shadowMap` you give it.
+   * @example <Canvas renderer={{ shadows: 'variance' }} />
+   */
+  shadows?: ShadowsConfig
+}
+
+//* 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> & RendererSettingsConfig)
+
+//* 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
+}
+
+/**
+ * The config keys the `renderer` props bag accepts besides the renderer's own parameters and
+ * properties. Multi-canvas and scheduling are Canvas props (`primary`, `share`, `scheduler`).
+ */
+type RendererConfigExtended = RendererSettingsConfig
+
+/**
+ * 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 `shadows` and `textureColorSpace`
+ * - 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.
+ *
+ * Everything here configures a renderer this canvas owns. A canvas sharing a primary's renderer
+ * ignores a props bag (with a dev warning): renderer-wide settings come from the `<Canvas primary>`.
+ */
+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> {
+  /**
+   * Canvas id. Sets the HTML `id` attribute on the canvas element and the canvas's scheduler root
+   * id (so `scheduler={{ after: 'main' }}` can order against it). On a `<Canvas primary>` it is the
+   * name other canvases pass to `share="id"`.
+   * @example <Canvas id="main-viewer">...</Canvas>
+   */
+  id?: string
+  /**
+   * Make this canvas the owner of a WebGPU renderer that other canvases share. Every other WebGPU
+   * canvas mounted with or after it borrows its renderer (drawing into its own element through a
+   * `CanvasTarget`) unless it passes `share={false}` or its own renderer instance/factory.
+   * Renderer-wide settings (`renderer={{ shadows, toneMapping, ... }}`) belong on the primary.
+   *
+   * WebGPU only: on the root entry `primary` selects WebGPU like the `renderer` prop does. Several
+   * primaries need distinct `id`s, and the other canvases then pick one with `share="id"`.
+   * Read when the renderer is created; changing it later needs a remount.
+   * @example <Canvas primary renderer={{ shadows: true }}>...</Canvas>
+   */
+  primary?: boolean
+  /**
+   * Renderer sharing for a non-primary canvas (WebGPU only).
+   * - omitted: share the primary's renderer when exactly one `<Canvas primary>` is mounted, else
+   *   own a renderer as usual
+   * - `"id"`: share the renderer of `<Canvas id="id" primary>`, waiting for it to mount
+   * - `false`: always own a renderer, even while a primary exists
+   *
+   * Read when the renderer is created; changing it later needs a remount.
+   * @example <Canvas share="main">...</Canvas>
+   */
+  share?: string | false
+  /**
+   * Canvas-level scheduler options: this canvas's order relative to other canvases, and an fps cap
+   * for its default render. A canvas sharing a primary's renderer runs after the primary unless
+   * `before`/`after` are given here.
+   * @example <Canvas scheduler={{ after: 'main', fps: 30 }}>...</Canvas>
+   */
+  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
+  /** 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
+  /**
+   * Internal: the token a Canvas announced `primary` with before this root existed, so configure
+   * continues that announcement instead of starting a second one.
+   * @internal
+   */
+  _primaryToken?: object
+  /** 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> {
+  ready: TrackedPromise<unknown>
+  configure: (config?: RenderProps<TCanvas>) => TrackedPromise<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
+  }
+>
+
+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'>
+}
+
 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. */
@@ -772,7 +1227,14 @@ declare function useStore(): RootStore;
  */
 declare function useThree<T = RootState>(selector?: (state: RootState) => T, equalityFn?: <T>(state: T, newState: T) => boolean): T;
 
-declare const context: React.Context<RootStore>;
+/**
+ * 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$1.Context<RootStore>;
 
-export { useStore as ag, useThree as ah, context as ai, registerRootExtension as r, setRenderOverride as s };
-export type { EquConfig as $, AttachFnType as A, InstanceProps as B, ConstructorRepresentation as C, Dpr as D, Events as E, Frameloop as F, Instance as G, HostConfig as H, InternalState as I, Properties as J, IsOptional as K, IsAllOptional as L, Mutable as M, NonFunctionKeys as N, Overwrite as O, PointerState as P, ThreeCamera as Q, R3FRenderTarget as R, Subscription as S, ThreeEvent as T, Act as U, Viewport as V, Bridge as W, XRManager as X, SetBlock as Y, UnblockProps as Z, ObjectMap as _, RootExtension as a, Disposable as a0, FrameNextState as a1, FrameState as a2, FrameNextCallback as a3, FrameCallback as a4, ThreeNamespace as a5, ThreeCore as a6, OcclusionSupport as a7, WebGLSupport as a8, WebGPUSupport as a9, RendererSupport as aa, RendererProvider as ab, Register as ac, RegisteredRenderer as ad, ForRegisteredRenderer as ae, R3FRendererSupport as af, 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, Root as v, AttachType as w, Catalogue as x, Args as y, ArgsProp as z };
+export { useStore as a$, useThree as b0, registerRootExtension as t, setRenderOverride as u, context as w };
+export type { EventHandlers as $, RenderCallback as A, Performance as B, Color as C, Dpr as D, Euler as E, Frameloop as F, GeometryTransformProps as G, RootState as H, InternalState as I, RootStore as J, Intersection as K, Layers as L, MutableOrReadonlyParameters as M, NodeProps as N, Object3DMethod as O, PointerState as P, Quaternion as Q, RaycastableRepresentation as R, Subscription as S, TSLNodeInput as T, Camera as U, VectorRepresentation as V, IntersectionEvent as W, XRManager as X, ThreeEvent as Y, DomEvent as Z, Events as _, MathRepresentation as a, FilterFunction as a0, ComputeFunction as a1, XRPointerConfig as a2, EventManager as a3, PointerCaptureTarget as a4, VisibilityEntry as a5, OffscreenCanvas$1 as a6, BaseRendererProps as a7, RendererFactory as a8, Renderer as a9, Mutable as aA, IsOptional as aB, IsAllOptional as aC, ThreeCamera as aD, Act as aE, Bridge as aF, SetBlock as aG, UnblockProps as aH, ObjectMap as aI, EquConfig as aJ, Disposable as aK, FrameNextState as aL, FrameState as aM, FrameNextCallback as aN, FrameCallback as aO, ThreeNamespace as aP, ThreeCore as aQ, OcclusionSupport as aR, WebGLSupport as aS, WebGPUSupport as aT, RendererSupport as aU, RendererProvider as aV, Register as aW, RegisteredRenderer as aX, ForRegisteredRenderer as aY, R3FRenderTarget as aZ, R3FRendererSupport as a_, ColorManagementConfig as aa, ShadowsConfig as ab, RendererSettingsConfig as ac, DefaultGLProps as ad, GLProps as ae, DefaultRendererProps as af, CanvasSchedulerConfig as ag, RendererConfigExtended as ah, RendererProps as ai, CameraProps as aj, RenderProps as ak, InjectState as al, FiberRoot as am, TrackedPromise as an, Root as ao, AttachFnType as ap, AttachType as aq, Catalogue as ar, Args as as, ArgsProp as at, InstanceProps as au, Instance as av, HostConfig as aw, NonFunctionKeys as ax, Overwrite as ay, Properties as az, MathTypes as b, MathType as c, MathProps as d, Vector2 as e, Vector3 as f, Vector4 as g, Matrix3 as h, Matrix4 as i, EventProps as j, GeometryProps as k, ReactProps as l, ConstructorRepresentation as m, ElementProps as n, ThreeElement as o, ThreeToJSXElements as p, ThreeElementsOf as q, ElementOf as r, ReconcilerRoot as s, RootExtension as v, R3FRenderer as x, Size as y, Viewport as z };