@react-three/fiber 10.0.0-canary.c3fa45d → 10.0.0-canary.d6fdf72

package/dist/legacy.d.cts

@@ -800,8 +800,10 @@ interface RootState {
   buffers: BufferStore
   /** Global GPU storage (textures, etc.) - root-level storage + scoped sub-objects. Use useGPUStorage() hook */
   gpuStorage: StorageStore
-  /** Global TSL texture nodes - use useTextures() hook for operations */
-  textures: Map<string, any>
+  /** Global Texture registry (key → Texture, usually keyed by URL) - use useTextures() hook for access + lifecycle */
+  textures: Map<string, THREE$1.Texture>
+  /** Internal: refcount per texture key, driven by mounted useTexture consumers (registry enrollment is on by default) */
+  _textureRefs: Map<string, number>
   /** WebGPU RenderPipeline instance - use useRenderPipeline() hook */
   renderPipeline: any | null // THREE.PostProcessing (will be THREE.RenderPipeline in future Three.js release)
   /** Global TSL pass nodes for render pipeline - use useRenderPipeline() hook */
@@ -2572,11 +2574,16 @@ type UseTextureOptions<Url extends string[] | string | Record<string, string>> =
     /** Callback when texture(s) finish loading */
     onLoad?: (texture: MappedTextureType<Url>) => void;
     /**
-     * Cache the texture in R3F's global state for access via useTextures().
-     * When true:
+     * Register the texture(s) in R3F's global texture registry for access via useTextures().
+     * When true (the default):
      * - Textures persist until explicitly disposed
-     * - Returns existing cached textures if available (preserving modifications like colorSpace)
-     * @default false
+     * - On mount, returns existing registered textures if available (preserving modifications like colorSpace)
+     *
+     * Reads are taken once at mount — a mounted `useTexture` does not re-render when the registry
+     * changes. To react to registry swaps, use `useTextures(s => s.get(key))` instead.
+     *
+     * Pass `false` to opt out of registry enrollment entirely.
+     * @default true
      */
     cache?: boolean;
 };
@@ -2600,15 +2607,18 @@ type UseTextureOptions<Url extends string[] | string | Record<string, string>> =
  *   normal: '/normal.png'
  * })
  *
- * // With caching - returns same texture object across components
- * // Modifications (colorSpace, wrapS, etc.) are preserved
- * const diffuse = useTexture('/diffuse.png', { cache: true })
+ * // Textures are registered in the global registry by default — the same texture
+ * // object is shared across components and modifications (colorSpace, wrapS, etc.) are preserved
+ * const diffuse = useTexture('/diffuse.png')
  * diffuse.colorSpace = THREE.SRGBColorSpace
  *
  * // Another component gets the SAME texture with colorSpace already set
- * const sameDiffuse = useTexture('/diffuse.png', { cache: true })
+ * const sameDiffuse = useTexture('/diffuse.png')
  *
- * // Access cache directly
+ * // Opt out of registry enrollment for a one-off texture
+ * const scratch = useTexture('/scratch.png', { cache: false })
+ *
+ * // Access the registry directly
  * const { get } = useTextures()
  * const cached = get('/diffuse.png')
  * ```
@@ -2625,63 +2635,80 @@ declare const Texture: ({ children, input, onLoad, cache, }: {
     cache?: boolean;
 }) => react_jsx_runtime.JSX.Element;
 
-type TextureEntry = Texture$1 | {
-    value: Texture$1;
-    [key: string]: any;
+/** Accepted shapes for a registry read: a single key, a list of keys, or a name→key map. */
+type TextureInput = string | string[] | Record<string, string>;
+/** Result of a `get()` read, mirroring the input shape. */
+type TextureResult<Input extends TextureInput> = Input extends string ? Texture$1 | undefined : Input extends string[] ? (Texture$1 | undefined)[] : {
+    [K in keyof Input]: Texture$1 | undefined;
 };
+/** Options for `dispose()`. */
+interface DisposeOptions {
+    /** Dispose even if the texture still has active references (default false). */
+    force?: boolean;
+}
 interface UseTexturesReturn {
-    /** Map of all textures currently in cache */
-    textures: Map<string, TextureEntry>;
-    /** Get a specific texture by key (usually URL) */
-    get: (key: string) => TextureEntry | undefined;
-    /** Check if a texture exists in cache */
-    has: (key: string) => boolean;
-    /** Add a texture to the cache */
-    add: (key: string, value: TextureEntry) => void;
-    /** Add multiple textures to the cache */
-    addMultiple: (items: Map<string, TextureEntry> | Record<string, TextureEntry>) => void;
-    /** Remove a texture from cache (does NOT dispose GPU resources) */
-    remove: (key: string) => void;
-    /** Remove multiple textures from cache */
-    removeMultiple: (keys: string[]) => void;
-    /** Dispose a texture's GPU resources and remove from cache */
-    dispose: (key: string) => void;
-    /** Dispose multiple textures */
-    disposeMultiple: (keys: string[]) => void;
-    /** Dispose ALL cached textures - use with caution */
-    disposeAll: () => void;
+    /** The live registry Map (key → Texture). Treat as read-only. */
+    readonly all: Map<string, Texture$1>;
+    /** Read one texture, an array of textures, or a name→texture record (mirrors the input shape). */
+    get<Input extends TextureInput>(input: Input): TextureResult<Input>;
+    /** Check whether a key exists in the registry. */
+    has(key: string): boolean;
+    /**
+     * Register a texture (or a record of textures) that has no URL — e.g. a render
+     * target or procedural texture. URL-loaded textures are registered automatically
+     * by `useTexture` (registry enrollment is on by default).
+     */
+    add(key: string, texture: Texture$1): void;
+    add(record: Record<string, Texture$1>): void;
+    /**
+     * Dispose a texture's GPU resources and remove it from the registry.
+     * Refcount-aware: if the key is still in use by a mounted `useTexture` consumer it is
+     * skipped (with a warning) unless `{ force: true }` is passed.
+     * @returns true if disposed, false if skipped.
+     */
+    dispose(key: string, options?: DisposeOptions): boolean;
+    /** Dispose every texture in the registry and clear it. Use on scene teardown. */
+    disposeAll(): void;
 }
 /**
- * Hook for managing the global texture cache in R3F state.
+ * Reactive Texture registry — load once with `useTexture`, reach the textures from anywhere.
+ *
+ * This is a registry of plain `Texture` objects (not TSL nodes), so the same texture can feed
+ * a material map, a heightmap sampler, or anything else. It does **not** load — pair it with
+ * `useTexture` for loading (registry enrollment is on by default); `useTextures` is for access and lifecycle.
  *
- * Textures are stored in a Map with URL/path keys for efficient lookup.
- * Useful for sharing texture references across materials and components.
+ * The returned handle is **reactive**: the calling component re-renders when the registry
+ * changes. Pass a selector to scope the subscription to a single read.
  *
  * @example
  * ```tsx
- * const { textures, add, get, remove, has, dispose } = useTextures()
- *
- * // Check if texture is already cached
- * if (!has('/textures/diffuse.png')) {
- *   // Load with useTexture and cache: true, or manually add
- *   const tex = useTexture('/textures/diffuse.png', { cache: true })
- * }
+ * // Load + register once (anywhere in the tree) — registered by default
+ * useTexture({ map: '/diffuse.jpg', normalMap: '/normal.jpg' })
  *
- * // Access cached texture from anywhere
- * const diffuse = get('/textures/diffuse.png')
- * if (diffuse) material.map = diffuse
+ * // Reach them from another component — record form lands straight into a material
+ * const { map, normalMap } = useTextures().get({ map: '/diffuse.jpg', normalMap: '/normal.jpg' })
+ * return <meshStandardMaterial map={map} normalMap={normalMap} />
  *
- * // Remove from cache only (texture still in GPU memory)
- * remove('/textures/old.png')
+ * // A set of heightmaps at once
+ * const [a, b, c] = useTextures().get(['/h0.png', '/h1.png', '/h2.png'])
  *
- * // Fully dispose (frees GPU memory + removes from cache)
- * dispose('/textures/unused.png')
+ * // Register a non-URL texture (render target / procedural)
+ * useTextures().add('rt-main', renderTarget.texture)
  *
- * // Nuclear option - dispose everything
- * disposeAll()
+ * // Deliberate GPU cleanup (refcount-aware; force to override)
+ * useTextures().dispose('/diffuse.jpg')
+ * useTextures().disposeAll() // scene teardown
  * ```
+ *
+ * @remarks
+ * **Future expansion:** an imperative async loader (e.g. `await useTextures().load('/x.jpg')`) is
+ * intentionally not included yet. It would let non-React code (loading screens, dynamic streaming)
+ * populate the registry without Suspense, at the cost of putting loading back into this hook. It
+ * will be added only if a concrete consumer needs imperative loading; for now, loading lives in
+ * `useTexture`.
  */
 declare function useTextures(): UseTexturesReturn;
+declare function useTextures<T>(selector: (registry: UseTexturesReturn) => T): T;
 
 /**
  * Creates a render target compatible with the current renderer.
@@ -4378,4 +4405,4 @@ declare function isOnce(value: unknown): value is {
 declare function Canvas(props: CanvasProps): react_jsx_runtime.JSX.Element;
 
 export { Block, Canvas, Environment, EnvironmentCube, EnvironmentMap, EnvironmentPortal, ErrorBoundary, FROM_REF, IsObject, ONCE, Portal, R3F_BUILD_LEGACY, R3F_BUILD_WEBGPU, REACT_INTERNAL_PROPS, RESERVED_PROPS, three_d as ReactThreeFiber, Scheduler, Texture, _roots, act, addAfterEffect, addEffect, addTail, advance, applyProps, attach, buildGraph, calculateDpr, context, createEvents, createPointerEvents, createPortal, createRoot, createStore, detach, diffProps, dispose, createPointerEvents as events, extend, findInitialRoot, flushSync, fromRef, getInstanceProps, getPrimary, getPrimaryIds, getRootState, getScheduler, getUuidPrefix, hasConstructor, hasPrimary, invalidate, invalidateInstance, is, isColorRepresentation, isCopyable, isFromRef, isObject3D, isOnce, isOrthographicCamera, isRef, isRenderer, isTexture, isVectorLike, once, prepare, presetsObj, reconciler, registerPrimary, removeInteractivity, resolve, unmountComponentAtNode, unregisterPrimary, updateCamera, updateFrustum, useBridge, useEnvironment, useFrame, useGraph, useInstanceHandle, useIsomorphicLayoutEffect, useLoader, useMutableCallback, useRenderTarget, useStore, useTexture, useTextures, useThree, waitForPrimary };
-export type { Act, AddPhaseOptions, Args, ArgsProp, AttachFnType, AttachType, BackgroundConfig, BackgroundProp, BaseRendererProps, Bridge, BufferLike, BufferRecord, BufferStore, Camera, CameraProps, CanvasProps, CanvasSchedulerConfig, Catalogue, Color, ColorManagementConfig, ComputeFunction, ConstructorRepresentation, DefaultGLProps, DefaultRendererProps, Disposable, DomEvent, Dpr, ElementProps, EnvironmentLoaderProps, EnvironmentProps, EquConfig, Euler, EventHandlers, EventManager, EventProps, Events, Extensions, FiberRoot, FilterFunction, FrameCallback, FrameControls, FrameNextCallback, FrameNextControls, FrameNextState, FrameState, FrameTimingState, Frameloop, GLProps, GLTFLike, GeometryProps, GeometryTransformProps, GlobalEffectType, GlobalRenderCallback, HostConfig, InferLoadResult, InjectState, InputLike, Instance, InstanceProps, LegacyInternalState as InternalState, Intersection, IntersectionEvent, IsAllOptional, IsOptional, Layers, LegacyInternalState, LegacyRenderer, LegacyRootState, LoaderInstance, LoaderLike, LoaderResult, MappedTextureType, MathProps, MathRepresentation, MathType, MathTypes, Matrix3, Matrix4, Mutable, MutableOrReadonlyParameters, NodeProps, NonFunctionKeys, ObjectMap, OffscreenCanvas$1 as OffscreenCanvas, Overwrite, Performance, PointerCaptureTarget, PointerState, PresetsType, PrimaryCanvasEntry, Properties, Quaternion, LegacyRenderer as R3FRenderer, RaycastableRepresentation, ReactProps, ReconcilerRoot, RenderCallback, RenderProps, RenderTargetOptions, Renderer, RendererConfigExtended, RendererFactory, RendererProps, Root, RootOptions, LegacyRootState as RootState, RootStore, SchedulerApi, SetBlock, Size, StorageLike, StorageRecord, StorageStore, Subscription, TSLNodeInput, TextureEntry, ThreeCamera, ThreeElement, ThreeElements, ThreeElementsImpl, ThreeEvent, ThreeExports, ThreeToJSXElements, UnblockProps, UseFrameNextOptions, UseFrameOptions, UseTextureOptions, UseTexturesReturn, Vector2, Vector3, Vector4, VectorRepresentation, Viewport, VisibilityEntry, WebGLDefaultProps, WebGLProps, WebGLShadowConfig, XRManager, XRPointerConfig };
+export type { Act, AddPhaseOptions, Args, ArgsProp, AttachFnType, AttachType, BackgroundConfig, BackgroundProp, BaseRendererProps, Bridge, BufferLike, BufferRecord, BufferStore, Camera, CameraProps, CanvasProps, CanvasSchedulerConfig, Catalogue, Color, ColorManagementConfig, ComputeFunction, ConstructorRepresentation, DefaultGLProps, DefaultRendererProps, Disposable, DisposeOptions, DomEvent, Dpr, ElementProps, EnvironmentLoaderProps, EnvironmentProps, EquConfig, Euler, EventHandlers, EventManager, EventProps, Events, Extensions, FiberRoot, FilterFunction, FrameCallback, FrameControls, FrameNextCallback, FrameNextControls, FrameNextState, FrameState, FrameTimingState, Frameloop, GLProps, GLTFLike, GeometryProps, GeometryTransformProps, GlobalEffectType, GlobalRenderCallback, HostConfig, InferLoadResult, InjectState, InputLike, Instance, InstanceProps, LegacyInternalState as InternalState, Intersection, IntersectionEvent, IsAllOptional, IsOptional, Layers, LegacyInternalState, LegacyRenderer, LegacyRootState, LoaderInstance, LoaderLike, LoaderResult, MappedTextureType, MathProps, MathRepresentation, MathType, MathTypes, Matrix3, Matrix4, Mutable, MutableOrReadonlyParameters, NodeProps, NonFunctionKeys, ObjectMap, OffscreenCanvas$1 as OffscreenCanvas, Overwrite, Performance, PointerCaptureTarget, PointerState, PresetsType, PrimaryCanvasEntry, Properties, Quaternion, LegacyRenderer as R3FRenderer, RaycastableRepresentation, ReactProps, ReconcilerRoot, RenderCallback, RenderProps, RenderTargetOptions, Renderer, RendererConfigExtended, RendererFactory, RendererProps, Root, RootOptions, LegacyRootState as RootState, RootStore, SchedulerApi, SetBlock, Size, StorageLike, StorageRecord, StorageStore, Subscription, TSLNodeInput, TextureInput, TextureResult, ThreeCamera, ThreeElement, ThreeElements, ThreeElementsImpl, ThreeEvent, ThreeExports, ThreeToJSXElements, UnblockProps, UseFrameNextOptions, UseFrameOptions, UseTextureOptions, UseTexturesReturn, Vector2, Vector3, Vector4, VectorRepresentation, Viewport, VisibilityEntry, WebGLDefaultProps, WebGLProps, WebGLShadowConfig, XRManager, XRPointerConfig };

package/dist/legacy.d.mts

@@ -800,8 +800,10 @@ interface RootState {
   buffers: BufferStore
   /** Global GPU storage (textures, etc.) - root-level storage + scoped sub-objects. Use useGPUStorage() hook */
   gpuStorage: StorageStore
-  /** Global TSL texture nodes - use useTextures() hook for operations */
-  textures: Map<string, any>
+  /** Global Texture registry (key → Texture, usually keyed by URL) - use useTextures() hook for access + lifecycle */
+  textures: Map<string, THREE$1.Texture>
+  /** Internal: refcount per texture key, driven by mounted useTexture consumers (registry enrollment is on by default) */
+  _textureRefs: Map<string, number>
   /** WebGPU RenderPipeline instance - use useRenderPipeline() hook */
   renderPipeline: any | null // THREE.PostProcessing (will be THREE.RenderPipeline in future Three.js release)
   /** Global TSL pass nodes for render pipeline - use useRenderPipeline() hook */
@@ -2572,11 +2574,16 @@ type UseTextureOptions<Url extends string[] | string | Record<string, string>> =
     /** Callback when texture(s) finish loading */
     onLoad?: (texture: MappedTextureType<Url>) => void;
     /**
-     * Cache the texture in R3F's global state for access via useTextures().
-     * When true:
+     * Register the texture(s) in R3F's global texture registry for access via useTextures().
+     * When true (the default):
      * - Textures persist until explicitly disposed
-     * - Returns existing cached textures if available (preserving modifications like colorSpace)
-     * @default false
+     * - On mount, returns existing registered textures if available (preserving modifications like colorSpace)
+     *
+     * Reads are taken once at mount — a mounted `useTexture` does not re-render when the registry
+     * changes. To react to registry swaps, use `useTextures(s => s.get(key))` instead.
+     *
+     * Pass `false` to opt out of registry enrollment entirely.
+     * @default true
      */
     cache?: boolean;
 };
@@ -2600,15 +2607,18 @@ type UseTextureOptions<Url extends string[] | string | Record<string, string>> =
  *   normal: '/normal.png'
  * })
  *
- * // With caching - returns same texture object across components
- * // Modifications (colorSpace, wrapS, etc.) are preserved
- * const diffuse = useTexture('/diffuse.png', { cache: true })
+ * // Textures are registered in the global registry by default — the same texture
+ * // object is shared across components and modifications (colorSpace, wrapS, etc.) are preserved
+ * const diffuse = useTexture('/diffuse.png')
  * diffuse.colorSpace = THREE.SRGBColorSpace
  *
  * // Another component gets the SAME texture with colorSpace already set
- * const sameDiffuse = useTexture('/diffuse.png', { cache: true })
+ * const sameDiffuse = useTexture('/diffuse.png')
  *
- * // Access cache directly
+ * // Opt out of registry enrollment for a one-off texture
+ * const scratch = useTexture('/scratch.png', { cache: false })
+ *
+ * // Access the registry directly
  * const { get } = useTextures()
  * const cached = get('/diffuse.png')
  * ```
@@ -2625,63 +2635,80 @@ declare const Texture: ({ children, input, onLoad, cache, }: {
     cache?: boolean;
 }) => react_jsx_runtime.JSX.Element;
 
-type TextureEntry = Texture$1 | {
-    value: Texture$1;
-    [key: string]: any;
+/** Accepted shapes for a registry read: a single key, a list of keys, or a name→key map. */
+type TextureInput = string | string[] | Record<string, string>;
+/** Result of a `get()` read, mirroring the input shape. */
+type TextureResult<Input extends TextureInput> = Input extends string ? Texture$1 | undefined : Input extends string[] ? (Texture$1 | undefined)[] : {
+    [K in keyof Input]: Texture$1 | undefined;
 };
+/** Options for `dispose()`. */
+interface DisposeOptions {
+    /** Dispose even if the texture still has active references (default false). */
+    force?: boolean;
+}
 interface UseTexturesReturn {
-    /** Map of all textures currently in cache */
-    textures: Map<string, TextureEntry>;
-    /** Get a specific texture by key (usually URL) */
-    get: (key: string) => TextureEntry | undefined;
-    /** Check if a texture exists in cache */
-    has: (key: string) => boolean;
-    /** Add a texture to the cache */
-    add: (key: string, value: TextureEntry) => void;
-    /** Add multiple textures to the cache */
-    addMultiple: (items: Map<string, TextureEntry> | Record<string, TextureEntry>) => void;
-    /** Remove a texture from cache (does NOT dispose GPU resources) */
-    remove: (key: string) => void;
-    /** Remove multiple textures from cache */
-    removeMultiple: (keys: string[]) => void;
-    /** Dispose a texture's GPU resources and remove from cache */
-    dispose: (key: string) => void;
-    /** Dispose multiple textures */
-    disposeMultiple: (keys: string[]) => void;
-    /** Dispose ALL cached textures - use with caution */
-    disposeAll: () => void;
+    /** The live registry Map (key → Texture). Treat as read-only. */
+    readonly all: Map<string, Texture$1>;
+    /** Read one texture, an array of textures, or a name→texture record (mirrors the input shape). */
+    get<Input extends TextureInput>(input: Input): TextureResult<Input>;
+    /** Check whether a key exists in the registry. */
+    has(key: string): boolean;
+    /**
+     * Register a texture (or a record of textures) that has no URL — e.g. a render
+     * target or procedural texture. URL-loaded textures are registered automatically
+     * by `useTexture` (registry enrollment is on by default).
+     */
+    add(key: string, texture: Texture$1): void;
+    add(record: Record<string, Texture$1>): void;
+    /**
+     * Dispose a texture's GPU resources and remove it from the registry.
+     * Refcount-aware: if the key is still in use by a mounted `useTexture` consumer it is
+     * skipped (with a warning) unless `{ force: true }` is passed.
+     * @returns true if disposed, false if skipped.
+     */
+    dispose(key: string, options?: DisposeOptions): boolean;
+    /** Dispose every texture in the registry and clear it. Use on scene teardown. */
+    disposeAll(): void;
 }
 /**
- * Hook for managing the global texture cache in R3F state.
+ * Reactive Texture registry — load once with `useTexture`, reach the textures from anywhere.
+ *
+ * This is a registry of plain `Texture` objects (not TSL nodes), so the same texture can feed
+ * a material map, a heightmap sampler, or anything else. It does **not** load — pair it with
+ * `useTexture` for loading (registry enrollment is on by default); `useTextures` is for access and lifecycle.
  *
- * Textures are stored in a Map with URL/path keys for efficient lookup.
- * Useful for sharing texture references across materials and components.
+ * The returned handle is **reactive**: the calling component re-renders when the registry
+ * changes. Pass a selector to scope the subscription to a single read.
  *
  * @example
  * ```tsx
- * const { textures, add, get, remove, has, dispose } = useTextures()
- *
- * // Check if texture is already cached
- * if (!has('/textures/diffuse.png')) {
- *   // Load with useTexture and cache: true, or manually add
- *   const tex = useTexture('/textures/diffuse.png', { cache: true })
- * }
+ * // Load + register once (anywhere in the tree) — registered by default
+ * useTexture({ map: '/diffuse.jpg', normalMap: '/normal.jpg' })
  *
- * // Access cached texture from anywhere
- * const diffuse = get('/textures/diffuse.png')
- * if (diffuse) material.map = diffuse
+ * // Reach them from another component — record form lands straight into a material
+ * const { map, normalMap } = useTextures().get({ map: '/diffuse.jpg', normalMap: '/normal.jpg' })
+ * return <meshStandardMaterial map={map} normalMap={normalMap} />
  *
- * // Remove from cache only (texture still in GPU memory)
- * remove('/textures/old.png')
+ * // A set of heightmaps at once
+ * const [a, b, c] = useTextures().get(['/h0.png', '/h1.png', '/h2.png'])
  *
- * // Fully dispose (frees GPU memory + removes from cache)
- * dispose('/textures/unused.png')
+ * // Register a non-URL texture (render target / procedural)
+ * useTextures().add('rt-main', renderTarget.texture)
  *
- * // Nuclear option - dispose everything
- * disposeAll()
+ * // Deliberate GPU cleanup (refcount-aware; force to override)
+ * useTextures().dispose('/diffuse.jpg')
+ * useTextures().disposeAll() // scene teardown
  * ```
+ *
+ * @remarks
+ * **Future expansion:** an imperative async loader (e.g. `await useTextures().load('/x.jpg')`) is
+ * intentionally not included yet. It would let non-React code (loading screens, dynamic streaming)
+ * populate the registry without Suspense, at the cost of putting loading back into this hook. It
+ * will be added only if a concrete consumer needs imperative loading; for now, loading lives in
+ * `useTexture`.
  */
 declare function useTextures(): UseTexturesReturn;
+declare function useTextures<T>(selector: (registry: UseTexturesReturn) => T): T;
 
 /**
  * Creates a render target compatible with the current renderer.
@@ -4378,4 +4405,4 @@ declare function isOnce(value: unknown): value is {
 declare function Canvas(props: CanvasProps): react_jsx_runtime.JSX.Element;
 
 export { Block, Canvas, Environment, EnvironmentCube, EnvironmentMap, EnvironmentPortal, ErrorBoundary, FROM_REF, IsObject, ONCE, Portal, R3F_BUILD_LEGACY, R3F_BUILD_WEBGPU, REACT_INTERNAL_PROPS, RESERVED_PROPS, three_d as ReactThreeFiber, Scheduler, Texture, _roots, act, addAfterEffect, addEffect, addTail, advance, applyProps, attach, buildGraph, calculateDpr, context, createEvents, createPointerEvents, createPortal, createRoot, createStore, detach, diffProps, dispose, createPointerEvents as events, extend, findInitialRoot, flushSync, fromRef, getInstanceProps, getPrimary, getPrimaryIds, getRootState, getScheduler, getUuidPrefix, hasConstructor, hasPrimary, invalidate, invalidateInstance, is, isColorRepresentation, isCopyable, isFromRef, isObject3D, isOnce, isOrthographicCamera, isRef, isRenderer, isTexture, isVectorLike, once, prepare, presetsObj, reconciler, registerPrimary, removeInteractivity, resolve, unmountComponentAtNode, unregisterPrimary, updateCamera, updateFrustum, useBridge, useEnvironment, useFrame, useGraph, useInstanceHandle, useIsomorphicLayoutEffect, useLoader, useMutableCallback, useRenderTarget, useStore, useTexture, useTextures, useThree, waitForPrimary };
-export type { Act, AddPhaseOptions, Args, ArgsProp, AttachFnType, AttachType, BackgroundConfig, BackgroundProp, BaseRendererProps, Bridge, BufferLike, BufferRecord, BufferStore, Camera, CameraProps, CanvasProps, CanvasSchedulerConfig, Catalogue, Color, ColorManagementConfig, ComputeFunction, ConstructorRepresentation, DefaultGLProps, DefaultRendererProps, Disposable, DomEvent, Dpr, ElementProps, EnvironmentLoaderProps, EnvironmentProps, EquConfig, Euler, EventHandlers, EventManager, EventProps, Events, Extensions, FiberRoot, FilterFunction, FrameCallback, FrameControls, FrameNextCallback, FrameNextControls, FrameNextState, FrameState, FrameTimingState, Frameloop, GLProps, GLTFLike, GeometryProps, GeometryTransformProps, GlobalEffectType, GlobalRenderCallback, HostConfig, InferLoadResult, InjectState, InputLike, Instance, InstanceProps, LegacyInternalState as InternalState, Intersection, IntersectionEvent, IsAllOptional, IsOptional, Layers, LegacyInternalState, LegacyRenderer, LegacyRootState, LoaderInstance, LoaderLike, LoaderResult, MappedTextureType, MathProps, MathRepresentation, MathType, MathTypes, Matrix3, Matrix4, Mutable, MutableOrReadonlyParameters, NodeProps, NonFunctionKeys, ObjectMap, OffscreenCanvas$1 as OffscreenCanvas, Overwrite, Performance, PointerCaptureTarget, PointerState, PresetsType, PrimaryCanvasEntry, Properties, Quaternion, LegacyRenderer as R3FRenderer, RaycastableRepresentation, ReactProps, ReconcilerRoot, RenderCallback, RenderProps, RenderTargetOptions, Renderer, RendererConfigExtended, RendererFactory, RendererProps, Root, RootOptions, LegacyRootState as RootState, RootStore, SchedulerApi, SetBlock, Size, StorageLike, StorageRecord, StorageStore, Subscription, TSLNodeInput, TextureEntry, ThreeCamera, ThreeElement, ThreeElements, ThreeElementsImpl, ThreeEvent, ThreeExports, ThreeToJSXElements, UnblockProps, UseFrameNextOptions, UseFrameOptions, UseTextureOptions, UseTexturesReturn, Vector2, Vector3, Vector4, VectorRepresentation, Viewport, VisibilityEntry, WebGLDefaultProps, WebGLProps, WebGLShadowConfig, XRManager, XRPointerConfig };
+export type { Act, AddPhaseOptions, Args, ArgsProp, AttachFnType, AttachType, BackgroundConfig, BackgroundProp, BaseRendererProps, Bridge, BufferLike, BufferRecord, BufferStore, Camera, CameraProps, CanvasProps, CanvasSchedulerConfig, Catalogue, Color, ColorManagementConfig, ComputeFunction, ConstructorRepresentation, DefaultGLProps, DefaultRendererProps, Disposable, DisposeOptions, DomEvent, Dpr, ElementProps, EnvironmentLoaderProps, EnvironmentProps, EquConfig, Euler, EventHandlers, EventManager, EventProps, Events, Extensions, FiberRoot, FilterFunction, FrameCallback, FrameControls, FrameNextCallback, FrameNextControls, FrameNextState, FrameState, FrameTimingState, Frameloop, GLProps, GLTFLike, GeometryProps, GeometryTransformProps, GlobalEffectType, GlobalRenderCallback, HostConfig, InferLoadResult, InjectState, InputLike, Instance, InstanceProps, LegacyInternalState as InternalState, Intersection, IntersectionEvent, IsAllOptional, IsOptional, Layers, LegacyInternalState, LegacyRenderer, LegacyRootState, LoaderInstance, LoaderLike, LoaderResult, MappedTextureType, MathProps, MathRepresentation, MathType, MathTypes, Matrix3, Matrix4, Mutable, MutableOrReadonlyParameters, NodeProps, NonFunctionKeys, ObjectMap, OffscreenCanvas$1 as OffscreenCanvas, Overwrite, Performance, PointerCaptureTarget, PointerState, PresetsType, PrimaryCanvasEntry, Properties, Quaternion, LegacyRenderer as R3FRenderer, RaycastableRepresentation, ReactProps, ReconcilerRoot, RenderCallback, RenderProps, RenderTargetOptions, Renderer, RendererConfigExtended, RendererFactory, RendererProps, Root, RootOptions, LegacyRootState as RootState, RootStore, SchedulerApi, SetBlock, Size, StorageLike, StorageRecord, StorageStore, Subscription, TSLNodeInput, TextureInput, TextureResult, ThreeCamera, ThreeElement, ThreeElements, ThreeElementsImpl, ThreeEvent, ThreeExports, ThreeToJSXElements, UnblockProps, UseFrameNextOptions, UseFrameOptions, UseTextureOptions, UseTexturesReturn, Vector2, Vector3, Vector4, VectorRepresentation, Viewport, VisibilityEntry, WebGLDefaultProps, WebGLProps, WebGLShadowConfig, XRManager, XRPointerConfig };

package/dist/legacy.d.ts

@@ -800,8 +800,10 @@ interface RootState {
   buffers: BufferStore
   /** Global GPU storage (textures, etc.) - root-level storage + scoped sub-objects. Use useGPUStorage() hook */
   gpuStorage: StorageStore
-  /** Global TSL texture nodes - use useTextures() hook for operations */
-  textures: Map<string, any>
+  /** Global Texture registry (key → Texture, usually keyed by URL) - use useTextures() hook for access + lifecycle */
+  textures: Map<string, THREE$1.Texture>
+  /** Internal: refcount per texture key, driven by mounted useTexture consumers (registry enrollment is on by default) */
+  _textureRefs: Map<string, number>
   /** WebGPU RenderPipeline instance - use useRenderPipeline() hook */
   renderPipeline: any | null // THREE.PostProcessing (will be THREE.RenderPipeline in future Three.js release)
   /** Global TSL pass nodes for render pipeline - use useRenderPipeline() hook */
@@ -2572,11 +2574,16 @@ type UseTextureOptions<Url extends string[] | string | Record<string, string>> =
     /** Callback when texture(s) finish loading */
     onLoad?: (texture: MappedTextureType<Url>) => void;
     /**
-     * Cache the texture in R3F's global state for access via useTextures().
-     * When true:
+     * Register the texture(s) in R3F's global texture registry for access via useTextures().
+     * When true (the default):
      * - Textures persist until explicitly disposed
-     * - Returns existing cached textures if available (preserving modifications like colorSpace)
-     * @default false
+     * - On mount, returns existing registered textures if available (preserving modifications like colorSpace)
+     *
+     * Reads are taken once at mount — a mounted `useTexture` does not re-render when the registry
+     * changes. To react to registry swaps, use `useTextures(s => s.get(key))` instead.
+     *
+     * Pass `false` to opt out of registry enrollment entirely.
+     * @default true
      */
     cache?: boolean;
 };
@@ -2600,15 +2607,18 @@ type UseTextureOptions<Url extends string[] | string | Record<string, string>> =
  *   normal: '/normal.png'
  * })
  *
- * // With caching - returns same texture object across components
- * // Modifications (colorSpace, wrapS, etc.) are preserved
- * const diffuse = useTexture('/diffuse.png', { cache: true })
+ * // Textures are registered in the global registry by default — the same texture
+ * // object is shared across components and modifications (colorSpace, wrapS, etc.) are preserved
+ * const diffuse = useTexture('/diffuse.png')
  * diffuse.colorSpace = THREE.SRGBColorSpace
  *
  * // Another component gets the SAME texture with colorSpace already set
- * const sameDiffuse = useTexture('/diffuse.png', { cache: true })
+ * const sameDiffuse = useTexture('/diffuse.png')
  *
- * // Access cache directly
+ * // Opt out of registry enrollment for a one-off texture
+ * const scratch = useTexture('/scratch.png', { cache: false })
+ *
+ * // Access the registry directly
  * const { get } = useTextures()
  * const cached = get('/diffuse.png')
  * ```
@@ -2625,63 +2635,80 @@ declare const Texture: ({ children, input, onLoad, cache, }: {
     cache?: boolean;
 }) => react_jsx_runtime.JSX.Element;
 
-type TextureEntry = Texture$1 | {
-    value: Texture$1;
-    [key: string]: any;
+/** Accepted shapes for a registry read: a single key, a list of keys, or a name→key map. */
+type TextureInput = string | string[] | Record<string, string>;
+/** Result of a `get()` read, mirroring the input shape. */
+type TextureResult<Input extends TextureInput> = Input extends string ? Texture$1 | undefined : Input extends string[] ? (Texture$1 | undefined)[] : {
+    [K in keyof Input]: Texture$1 | undefined;
 };
+/** Options for `dispose()`. */
+interface DisposeOptions {
+    /** Dispose even if the texture still has active references (default false). */
+    force?: boolean;
+}
 interface UseTexturesReturn {
-    /** Map of all textures currently in cache */
-    textures: Map<string, TextureEntry>;
-    /** Get a specific texture by key (usually URL) */
-    get: (key: string) => TextureEntry | undefined;
-    /** Check if a texture exists in cache */
-    has: (key: string) => boolean;
-    /** Add a texture to the cache */
-    add: (key: string, value: TextureEntry) => void;
-    /** Add multiple textures to the cache */
-    addMultiple: (items: Map<string, TextureEntry> | Record<string, TextureEntry>) => void;
-    /** Remove a texture from cache (does NOT dispose GPU resources) */
-    remove: (key: string) => void;
-    /** Remove multiple textures from cache */
-    removeMultiple: (keys: string[]) => void;
-    /** Dispose a texture's GPU resources and remove from cache */
-    dispose: (key: string) => void;
-    /** Dispose multiple textures */
-    disposeMultiple: (keys: string[]) => void;
-    /** Dispose ALL cached textures - use with caution */
-    disposeAll: () => void;
+    /** The live registry Map (key → Texture). Treat as read-only. */
+    readonly all: Map<string, Texture$1>;
+    /** Read one texture, an array of textures, or a name→texture record (mirrors the input shape). */
+    get<Input extends TextureInput>(input: Input): TextureResult<Input>;
+    /** Check whether a key exists in the registry. */
+    has(key: string): boolean;
+    /**
+     * Register a texture (or a record of textures) that has no URL — e.g. a render
+     * target or procedural texture. URL-loaded textures are registered automatically
+     * by `useTexture` (registry enrollment is on by default).
+     */
+    add(key: string, texture: Texture$1): void;
+    add(record: Record<string, Texture$1>): void;
+    /**
+     * Dispose a texture's GPU resources and remove it from the registry.
+     * Refcount-aware: if the key is still in use by a mounted `useTexture` consumer it is
+     * skipped (with a warning) unless `{ force: true }` is passed.
+     * @returns true if disposed, false if skipped.
+     */
+    dispose(key: string, options?: DisposeOptions): boolean;
+    /** Dispose every texture in the registry and clear it. Use on scene teardown. */
+    disposeAll(): void;
 }
 /**
- * Hook for managing the global texture cache in R3F state.
+ * Reactive Texture registry — load once with `useTexture`, reach the textures from anywhere.
+ *
+ * This is a registry of plain `Texture` objects (not TSL nodes), so the same texture can feed
+ * a material map, a heightmap sampler, or anything else. It does **not** load — pair it with
+ * `useTexture` for loading (registry enrollment is on by default); `useTextures` is for access and lifecycle.
  *
- * Textures are stored in a Map with URL/path keys for efficient lookup.
- * Useful for sharing texture references across materials and components.
+ * The returned handle is **reactive**: the calling component re-renders when the registry
+ * changes. Pass a selector to scope the subscription to a single read.
  *
  * @example
  * ```tsx
- * const { textures, add, get, remove, has, dispose } = useTextures()
- *
- * // Check if texture is already cached
- * if (!has('/textures/diffuse.png')) {
- *   // Load with useTexture and cache: true, or manually add
- *   const tex = useTexture('/textures/diffuse.png', { cache: true })
- * }
+ * // Load + register once (anywhere in the tree) — registered by default
+ * useTexture({ map: '/diffuse.jpg', normalMap: '/normal.jpg' })
  *
- * // Access cached texture from anywhere
- * const diffuse = get('/textures/diffuse.png')
- * if (diffuse) material.map = diffuse
+ * // Reach them from another component — record form lands straight into a material
+ * const { map, normalMap } = useTextures().get({ map: '/diffuse.jpg', normalMap: '/normal.jpg' })
+ * return <meshStandardMaterial map={map} normalMap={normalMap} />
  *
- * // Remove from cache only (texture still in GPU memory)
- * remove('/textures/old.png')
+ * // A set of heightmaps at once
+ * const [a, b, c] = useTextures().get(['/h0.png', '/h1.png', '/h2.png'])
  *
- * // Fully dispose (frees GPU memory + removes from cache)
- * dispose('/textures/unused.png')
+ * // Register a non-URL texture (render target / procedural)
+ * useTextures().add('rt-main', renderTarget.texture)
  *
- * // Nuclear option - dispose everything
- * disposeAll()
+ * // Deliberate GPU cleanup (refcount-aware; force to override)
+ * useTextures().dispose('/diffuse.jpg')
+ * useTextures().disposeAll() // scene teardown
  * ```
+ *
+ * @remarks
+ * **Future expansion:** an imperative async loader (e.g. `await useTextures().load('/x.jpg')`) is
+ * intentionally not included yet. It would let non-React code (loading screens, dynamic streaming)
+ * populate the registry without Suspense, at the cost of putting loading back into this hook. It
+ * will be added only if a concrete consumer needs imperative loading; for now, loading lives in
+ * `useTexture`.
  */
 declare function useTextures(): UseTexturesReturn;
+declare function useTextures<T>(selector: (registry: UseTexturesReturn) => T): T;
 
 /**
  * Creates a render target compatible with the current renderer.
@@ -4378,4 +4405,4 @@ declare function isOnce(value: unknown): value is {
 declare function Canvas(props: CanvasProps): react_jsx_runtime.JSX.Element;
 
 export { Block, Canvas, Environment, EnvironmentCube, EnvironmentMap, EnvironmentPortal, ErrorBoundary, FROM_REF, IsObject, ONCE, Portal, R3F_BUILD_LEGACY, R3F_BUILD_WEBGPU, REACT_INTERNAL_PROPS, RESERVED_PROPS, three_d as ReactThreeFiber, Scheduler, Texture, _roots, act, addAfterEffect, addEffect, addTail, advance, applyProps, attach, buildGraph, calculateDpr, context, createEvents, createPointerEvents, createPortal, createRoot, createStore, detach, diffProps, dispose, createPointerEvents as events, extend, findInitialRoot, flushSync, fromRef, getInstanceProps, getPrimary, getPrimaryIds, getRootState, getScheduler, getUuidPrefix, hasConstructor, hasPrimary, invalidate, invalidateInstance, is, isColorRepresentation, isCopyable, isFromRef, isObject3D, isOnce, isOrthographicCamera, isRef, isRenderer, isTexture, isVectorLike, once, prepare, presetsObj, reconciler, registerPrimary, removeInteractivity, resolve, unmountComponentAtNode, unregisterPrimary, updateCamera, updateFrustum, useBridge, useEnvironment, useFrame, useGraph, useInstanceHandle, useIsomorphicLayoutEffect, useLoader, useMutableCallback, useRenderTarget, useStore, useTexture, useTextures, useThree, waitForPrimary };
-export type { Act, AddPhaseOptions, Args, ArgsProp, AttachFnType, AttachType, BackgroundConfig, BackgroundProp, BaseRendererProps, Bridge, BufferLike, BufferRecord, BufferStore, Camera, CameraProps, CanvasProps, CanvasSchedulerConfig, Catalogue, Color, ColorManagementConfig, ComputeFunction, ConstructorRepresentation, DefaultGLProps, DefaultRendererProps, Disposable, DomEvent, Dpr, ElementProps, EnvironmentLoaderProps, EnvironmentProps, EquConfig, Euler, EventHandlers, EventManager, EventProps, Events, Extensions, FiberRoot, FilterFunction, FrameCallback, FrameControls, FrameNextCallback, FrameNextControls, FrameNextState, FrameState, FrameTimingState, Frameloop, GLProps, GLTFLike, GeometryProps, GeometryTransformProps, GlobalEffectType, GlobalRenderCallback, HostConfig, InferLoadResult, InjectState, InputLike, Instance, InstanceProps, LegacyInternalState as InternalState, Intersection, IntersectionEvent, IsAllOptional, IsOptional, Layers, LegacyInternalState, LegacyRenderer, LegacyRootState, LoaderInstance, LoaderLike, LoaderResult, MappedTextureType, MathProps, MathRepresentation, MathType, MathTypes, Matrix3, Matrix4, Mutable, MutableOrReadonlyParameters, NodeProps, NonFunctionKeys, ObjectMap, OffscreenCanvas$1 as OffscreenCanvas, Overwrite, Performance, PointerCaptureTarget, PointerState, PresetsType, PrimaryCanvasEntry, Properties, Quaternion, LegacyRenderer as R3FRenderer, RaycastableRepresentation, ReactProps, ReconcilerRoot, RenderCallback, RenderProps, RenderTargetOptions, Renderer, RendererConfigExtended, RendererFactory, RendererProps, Root, RootOptions, LegacyRootState as RootState, RootStore, SchedulerApi, SetBlock, Size, StorageLike, StorageRecord, StorageStore, Subscription, TSLNodeInput, TextureEntry, ThreeCamera, ThreeElement, ThreeElements, ThreeElementsImpl, ThreeEvent, ThreeExports, ThreeToJSXElements, UnblockProps, UseFrameNextOptions, UseFrameOptions, UseTextureOptions, UseTexturesReturn, Vector2, Vector3, Vector4, VectorRepresentation, Viewport, VisibilityEntry, WebGLDefaultProps, WebGLProps, WebGLShadowConfig, XRManager, XRPointerConfig };
+export type { Act, AddPhaseOptions, Args, ArgsProp, AttachFnType, AttachType, BackgroundConfig, BackgroundProp, BaseRendererProps, Bridge, BufferLike, BufferRecord, BufferStore, Camera, CameraProps, CanvasProps, CanvasSchedulerConfig, Catalogue, Color, ColorManagementConfig, ComputeFunction, ConstructorRepresentation, DefaultGLProps, DefaultRendererProps, Disposable, DisposeOptions, DomEvent, Dpr, ElementProps, EnvironmentLoaderProps, EnvironmentProps, EquConfig, Euler, EventHandlers, EventManager, EventProps, Events, Extensions, FiberRoot, FilterFunction, FrameCallback, FrameControls, FrameNextCallback, FrameNextControls, FrameNextState, FrameState, FrameTimingState, Frameloop, GLProps, GLTFLike, GeometryProps, GeometryTransformProps, GlobalEffectType, GlobalRenderCallback, HostConfig, InferLoadResult, InjectState, InputLike, Instance, InstanceProps, LegacyInternalState as InternalState, Intersection, IntersectionEvent, IsAllOptional, IsOptional, Layers, LegacyInternalState, LegacyRenderer, LegacyRootState, LoaderInstance, LoaderLike, LoaderResult, MappedTextureType, MathProps, MathRepresentation, MathType, MathTypes, Matrix3, Matrix4, Mutable, MutableOrReadonlyParameters, NodeProps, NonFunctionKeys, ObjectMap, OffscreenCanvas$1 as OffscreenCanvas, Overwrite, Performance, PointerCaptureTarget, PointerState, PresetsType, PrimaryCanvasEntry, Properties, Quaternion, LegacyRenderer as R3FRenderer, RaycastableRepresentation, ReactProps, ReconcilerRoot, RenderCallback, RenderProps, RenderTargetOptions, Renderer, RendererConfigExtended, RendererFactory, RendererProps, Root, RootOptions, LegacyRootState as RootState, RootStore, SchedulerApi, SetBlock, Size, StorageLike, StorageRecord, StorageStore, Subscription, TSLNodeInput, TextureInput, TextureResult, ThreeCamera, ThreeElement, ThreeElements, ThreeElementsImpl, ThreeEvent, ThreeExports, ThreeToJSXElements, UnblockProps, UseFrameNextOptions, UseFrameOptions, UseTextureOptions, UseTexturesReturn, Vector2, Vector3, Vector4, VectorRepresentation, Viewport, VisibilityEntry, WebGLDefaultProps, WebGLProps, WebGLShadowConfig, XRManager, XRPointerConfig };