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

package/dist/webgpu/index.d.mts

@@ -803,8 +803,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 */
@@ -2575,11 +2577,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;
 };
@@ -2603,15 +2610,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')
  * ```
@@ -2628,63 +2638,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()
+ * // Load + register once (anywhere in the tree) — registered by default
+ * useTexture({ map: '/diffuse.jpg', normalMap: '/normal.jpg' })
  *
- * // 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 })
- * }
- *
- * // 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.
@@ -4766,4 +4793,4 @@ interface WebGPURootState extends Omit<RootState, 'renderer' | 'gl' | 'internal'
 }
 
 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, clearNodeScope, clearRootNodes, clearRootUniforms, clearScope, context, createEvents, createPointerEvents, createPortal, createRoot, createScopedStore, createStore, createTextureOperations, 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, rebuildAllBuffers, rebuildAllNodes, rebuildAllStorage, rebuildAllUniforms, reconciler, registerPrimary, removeInteractivity, removeNodes, removeUniforms, resolve, unmountComponentAtNode, unregisterPrimary, updateCamera, updateFrustum, useBridge, useBuffers, useEnvironment, useFrame, useGPUStorage, useGraph, useInstanceHandle, useIsomorphicLayoutEffect, useLoader, useLocalNodes, useMutableCallback, useNodes, useRenderPipeline, useRenderTarget, useStore, useTexture, useTextures, useThree, useUniform, useUniforms, waitForPrimary };
-export type { Act, AddPhaseOptions, Args, ArgsProp, AttachFnType, AttachType, BackgroundConfig, BackgroundProp, BaseRendererProps, Bridge, BufferCreator, BufferLike, BufferRecord, BufferStore, BuffersWithUtils, Camera, CameraProps, CanvasProps, CanvasSchedulerConfig, Catalogue, ClearBuffersFn, ClearNodesFn, ClearStorageFn, ClearUniformsFn, Color, ColorManagementConfig, ComputeFunction, ConstructorRepresentation, CreatorState, DefaultGLProps, DefaultRendererProps, Disposable, DisposeBuffersFn, DisposeStorageFn, 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, WebGPUInternalState as InternalState, Intersection, IntersectionEvent, IsAllOptional, IsOptional, Layers, LegacyInternalState, LegacyRenderer, LegacyRootState, LoaderInstance, LoaderLike, LoaderResult, LocalNodeCreator, MappedTextureType, MathProps, MathRepresentation, MathType, MathTypes, Matrix3, Matrix4, Mutable, MutableOrReadonlyParameters, NodeCreator, NodeProps, NodeRecord, NodesWithUtils, NonFunctionKeys, ObjectMap, OffscreenCanvas$1 as OffscreenCanvas, Overwrite, Performance, PointerCaptureTarget, PointerState, PresetsType, PrimaryCanvasEntry, Properties, Quaternion, WebGPUR3FRenderer as R3FRenderer, RaycastableRepresentation, ReactProps, RebuildBuffersFn, RebuildNodesFn, RebuildStorageFn, RebuildUniformsFn, ReconcilerRoot, RemoveBuffersFn, RemoveNodesFn, RemoveStorageFn, RemoveUniformsFn, RenderCallback, RenderProps, RenderTargetOptions, Renderer, RendererConfigExtended, RendererFactory, RendererProps, Root, RootOptions, WebGPURootState as RootState, RootStore, SchedulerApi, ScopedStoreType, SetBlock, Size, StorageCreator, StorageLike, StorageRecord, StorageStore, StorageWithUtils, Subscription, TSLNode, TSLNodeInput, TextureEntry, TextureOperations, ThreeCamera, ThreeElement, ThreeElements, ThreeElementsImpl, ThreeEvent, ThreeExports, ThreeToJSXElements, UnblockProps, UniformCreator, UniformValue, UniformsWithUtils, UseFrameNextOptions, UseFrameOptions, UseTextureOptions, UseTexturesReturn, Vector2, Vector3, Vector4, VectorRepresentation, Viewport, VisibilityEntry, WebGLDefaultProps, WebGLProps, WebGLShadowConfig, WebGPUDefaultProps, WebGPUProps, WebGPUShadowConfig, XRManager, XRPointerConfig };
+export type { Act, AddPhaseOptions, Args, ArgsProp, AttachFnType, AttachType, BackgroundConfig, BackgroundProp, BaseRendererProps, Bridge, BufferCreator, BufferLike, BufferRecord, BufferStore, BuffersWithUtils, Camera, CameraProps, CanvasProps, CanvasSchedulerConfig, Catalogue, ClearBuffersFn, ClearNodesFn, ClearStorageFn, ClearUniformsFn, Color, ColorManagementConfig, ComputeFunction, ConstructorRepresentation, CreatorState, DefaultGLProps, DefaultRendererProps, Disposable, DisposeBuffersFn, DisposeOptions, DisposeStorageFn, 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, WebGPUInternalState as InternalState, Intersection, IntersectionEvent, IsAllOptional, IsOptional, Layers, LegacyInternalState, LegacyRenderer, LegacyRootState, LoaderInstance, LoaderLike, LoaderResult, LocalNodeCreator, MappedTextureType, MathProps, MathRepresentation, MathType, MathTypes, Matrix3, Matrix4, Mutable, MutableOrReadonlyParameters, NodeCreator, NodeProps, NodeRecord, NodesWithUtils, NonFunctionKeys, ObjectMap, OffscreenCanvas$1 as OffscreenCanvas, Overwrite, Performance, PointerCaptureTarget, PointerState, PresetsType, PrimaryCanvasEntry, Properties, Quaternion, WebGPUR3FRenderer as R3FRenderer, RaycastableRepresentation, ReactProps, RebuildBuffersFn, RebuildNodesFn, RebuildStorageFn, RebuildUniformsFn, ReconcilerRoot, RemoveBuffersFn, RemoveNodesFn, RemoveStorageFn, RemoveUniformsFn, RenderCallback, RenderProps, RenderTargetOptions, Renderer, RendererConfigExtended, RendererFactory, RendererProps, Root, RootOptions, WebGPURootState as RootState, RootStore, SchedulerApi, ScopedStoreType, SetBlock, Size, StorageCreator, StorageLike, StorageRecord, StorageStore, StorageWithUtils, Subscription, TSLNode, TSLNodeInput, TextureInput, TextureOperations, TextureResult, ThreeCamera, ThreeElement, ThreeElements, ThreeElementsImpl, ThreeEvent, ThreeExports, ThreeToJSXElements, UnblockProps, UniformCreator, UniformValue, UniformsWithUtils, UseFrameNextOptions, UseFrameOptions, UseTextureOptions, UseTexturesReturn, Vector2, Vector3, Vector4, VectorRepresentation, Viewport, VisibilityEntry, WebGLDefaultProps, WebGLProps, WebGLShadowConfig, WebGPUDefaultProps, WebGPUProps, WebGPUShadowConfig, XRManager, XRPointerConfig };

package/dist/webgpu/index.d.ts

@@ -803,8 +803,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 */
@@ -2575,11 +2577,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;
 };
@@ -2603,15 +2610,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')
  * ```
@@ -2628,63 +2638,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()
+ * // Load + register once (anywhere in the tree) — registered by default
+ * useTexture({ map: '/diffuse.jpg', normalMap: '/normal.jpg' })
  *
- * // 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 })
- * }
- *
- * // 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.
@@ -4766,4 +4793,4 @@ interface WebGPURootState extends Omit<RootState, 'renderer' | 'gl' | 'internal'
 }
 
 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, clearNodeScope, clearRootNodes, clearRootUniforms, clearScope, context, createEvents, createPointerEvents, createPortal, createRoot, createScopedStore, createStore, createTextureOperations, 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, rebuildAllBuffers, rebuildAllNodes, rebuildAllStorage, rebuildAllUniforms, reconciler, registerPrimary, removeInteractivity, removeNodes, removeUniforms, resolve, unmountComponentAtNode, unregisterPrimary, updateCamera, updateFrustum, useBridge, useBuffers, useEnvironment, useFrame, useGPUStorage, useGraph, useInstanceHandle, useIsomorphicLayoutEffect, useLoader, useLocalNodes, useMutableCallback, useNodes, useRenderPipeline, useRenderTarget, useStore, useTexture, useTextures, useThree, useUniform, useUniforms, waitForPrimary };
-export type { Act, AddPhaseOptions, Args, ArgsProp, AttachFnType, AttachType, BackgroundConfig, BackgroundProp, BaseRendererProps, Bridge, BufferCreator, BufferLike, BufferRecord, BufferStore, BuffersWithUtils, Camera, CameraProps, CanvasProps, CanvasSchedulerConfig, Catalogue, ClearBuffersFn, ClearNodesFn, ClearStorageFn, ClearUniformsFn, Color, ColorManagementConfig, ComputeFunction, ConstructorRepresentation, CreatorState, DefaultGLProps, DefaultRendererProps, Disposable, DisposeBuffersFn, DisposeStorageFn, 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, WebGPUInternalState as InternalState, Intersection, IntersectionEvent, IsAllOptional, IsOptional, Layers, LegacyInternalState, LegacyRenderer, LegacyRootState, LoaderInstance, LoaderLike, LoaderResult, LocalNodeCreator, MappedTextureType, MathProps, MathRepresentation, MathType, MathTypes, Matrix3, Matrix4, Mutable, MutableOrReadonlyParameters, NodeCreator, NodeProps, NodeRecord, NodesWithUtils, NonFunctionKeys, ObjectMap, OffscreenCanvas$1 as OffscreenCanvas, Overwrite, Performance, PointerCaptureTarget, PointerState, PresetsType, PrimaryCanvasEntry, Properties, Quaternion, WebGPUR3FRenderer as R3FRenderer, RaycastableRepresentation, ReactProps, RebuildBuffersFn, RebuildNodesFn, RebuildStorageFn, RebuildUniformsFn, ReconcilerRoot, RemoveBuffersFn, RemoveNodesFn, RemoveStorageFn, RemoveUniformsFn, RenderCallback, RenderProps, RenderTargetOptions, Renderer, RendererConfigExtended, RendererFactory, RendererProps, Root, RootOptions, WebGPURootState as RootState, RootStore, SchedulerApi, ScopedStoreType, SetBlock, Size, StorageCreator, StorageLike, StorageRecord, StorageStore, StorageWithUtils, Subscription, TSLNode, TSLNodeInput, TextureEntry, TextureOperations, ThreeCamera, ThreeElement, ThreeElements, ThreeElementsImpl, ThreeEvent, ThreeExports, ThreeToJSXElements, UnblockProps, UniformCreator, UniformValue, UniformsWithUtils, UseFrameNextOptions, UseFrameOptions, UseTextureOptions, UseTexturesReturn, Vector2, Vector3, Vector4, VectorRepresentation, Viewport, VisibilityEntry, WebGLDefaultProps, WebGLProps, WebGLShadowConfig, WebGPUDefaultProps, WebGPUProps, WebGPUShadowConfig, XRManager, XRPointerConfig };
+export type { Act, AddPhaseOptions, Args, ArgsProp, AttachFnType, AttachType, BackgroundConfig, BackgroundProp, BaseRendererProps, Bridge, BufferCreator, BufferLike, BufferRecord, BufferStore, BuffersWithUtils, Camera, CameraProps, CanvasProps, CanvasSchedulerConfig, Catalogue, ClearBuffersFn, ClearNodesFn, ClearStorageFn, ClearUniformsFn, Color, ColorManagementConfig, ComputeFunction, ConstructorRepresentation, CreatorState, DefaultGLProps, DefaultRendererProps, Disposable, DisposeBuffersFn, DisposeOptions, DisposeStorageFn, 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, WebGPUInternalState as InternalState, Intersection, IntersectionEvent, IsAllOptional, IsOptional, Layers, LegacyInternalState, LegacyRenderer, LegacyRootState, LoaderInstance, LoaderLike, LoaderResult, LocalNodeCreator, MappedTextureType, MathProps, MathRepresentation, MathType, MathTypes, Matrix3, Matrix4, Mutable, MutableOrReadonlyParameters, NodeCreator, NodeProps, NodeRecord, NodesWithUtils, NonFunctionKeys, ObjectMap, OffscreenCanvas$1 as OffscreenCanvas, Overwrite, Performance, PointerCaptureTarget, PointerState, PresetsType, PrimaryCanvasEntry, Properties, Quaternion, WebGPUR3FRenderer as R3FRenderer, RaycastableRepresentation, ReactProps, RebuildBuffersFn, RebuildNodesFn, RebuildStorageFn, RebuildUniformsFn, ReconcilerRoot, RemoveBuffersFn, RemoveNodesFn, RemoveStorageFn, RemoveUniformsFn, RenderCallback, RenderProps, RenderTargetOptions, Renderer, RendererConfigExtended, RendererFactory, RendererProps, Root, RootOptions, WebGPURootState as RootState, RootStore, SchedulerApi, ScopedStoreType, SetBlock, Size, StorageCreator, StorageLike, StorageRecord, StorageStore, StorageWithUtils, Subscription, TSLNode, TSLNodeInput, TextureInput, TextureOperations, TextureResult, ThreeCamera, ThreeElement, ThreeElements, ThreeElementsImpl, ThreeEvent, ThreeExports, ThreeToJSXElements, UnblockProps, UniformCreator, UniformValue, UniformsWithUtils, UseFrameNextOptions, UseFrameOptions, UseTextureOptions, UseTexturesReturn, Vector2, Vector3, Vector4, VectorRepresentation, Viewport, VisibilityEntry, WebGLDefaultProps, WebGLProps, WebGLShadowConfig, WebGPUDefaultProps, WebGPUProps, WebGPUShadowConfig, XRManager, XRPointerConfig };

package/dist/webgpu/index.mjs

@@ -2810,6 +2810,7 @@ const createStore = (invalidate, advance) => {
       buffers: {},
       gpuStorage: {},
       textures: /* @__PURE__ */ new Map(),
+      _textureRefs: /* @__PURE__ */ new Map(),
       renderPipeline: null,
       passes: {},
       _hmrVersion: 0,
@@ -3173,18 +3174,18 @@ function buildFromCache(input, textureCache) {
 function useTexture(input, optionsOrOnLoad) {
   const renderer = useThree((state) => state.internal.actualRenderer);
   const store = useStore();
-  const textureCache = useThree((state) => state.textures);
   const options = typeof optionsOrOnLoad === "function" ? { onLoad: optionsOrOnLoad } : optionsOrOnLoad ?? {};
-  const { onLoad, cache = false } = options;
+  const { onLoad, cache = true } = options;
   const onLoadRef = useRef(onLoad);
   onLoadRef.current = onLoad;
   const onLoadCalledForRef = useRef(null);
   const urls = useMemo(() => getUrls(input), [input]);
   const cachedResult = useMemo(() => {
     if (!cache) return null;
-    if (!allUrlsCached(urls, textureCache)) return null;
-    return buildFromCache(input, textureCache);
-  }, [cache, urls, textureCache, input]);
+    const textures = store.getState().textures;
+    if (!allUrlsCached(urls, textures)) return null;
+    return buildFromCache(input, textures);
+  }, [cache, urls, input, store]);
   const loadedTextures = useLoader(
     TextureLoader,
     IsObject(input) ? Object.values(input) : input
@@ -3228,8 +3229,6 @@ function useTexture(input, optionsOrOnLoad) {
   }, [input, loadedTextures, cachedResult]);
   useEffect(() => {
     if (!cache) return;
-    if (cachedResult) return;
-    const set = store.setState;
     const urlTextureMap = [];
     if (typeof input === "string") {
       urlTextureMap.push([input, mappedTextures]);
@@ -3243,18 +3242,32 @@ function useTexture(input, optionsOrOnLoad) {
         urlTextureMap.push([url, textureRecord[key]]);
       }
     }
-    set((state) => {
-      const newMap = new Map(state.textures);
-      let changed = false;
+    store.setState((state) => {
+      const refs = new Map(state._textureRefs);
+      let textures = state.textures;
+      let added = false;
       for (const [url, texture] of urlTextureMap) {
-        if (!newMap.has(url)) {
-          newMap.set(url, texture);
-          changed = true;
+        if (!textures.has(url)) {
+          if (!added) {
+            textures = new Map(textures);
+            added = true;
+          }
+          textures.set(url, texture);
         }
+        refs.set(url, (refs.get(url) ?? 0) + 1);
       }
-      return changed ? { textures: newMap } : state;
+      return added ? { textures, _textureRefs: refs } : { _textureRefs: refs };
     });
-  }, [cache, input, mappedTextures, store, cachedResult]);
+    return () => store.setState((state) => {
+      const refs = new Map(state._textureRefs);
+      for (const [url] of urlTextureMap) {
+        const next = (refs.get(url) ?? 0) - 1;
+        if (next <= 0) refs.delete(url);
+        else refs.set(url, next);
+      }
+      return { _textureRefs: refs };
+    });
+  }, [cache, input, mappedTextures, store]);
   return mappedTextures;
 }
 useTexture.preload = (url) => useLoader.preload(TextureLoader, url);
@@ -3270,96 +3283,63 @@ const Texture = ({
   return /* @__PURE__ */ jsx(Fragment, { children: children?.(ret) });
 };
 
-function getTextureValue(entry) {
-  if (entry instanceof Texture$1) return entry;
-  if (entry && typeof entry === "object" && "value" in entry && entry.value instanceof Texture$1) {
-    return entry.value;
-  }
-  return null;
-}
-function useTextures() {
+function useTextures(selector) {
   const store = useStore();
-  return useMemo(() => {
-    const set = store.setState;
+  const registry = useMemo(() => {
     const getState = store.getState;
-    const add = (key, value) => {
-      set((state) => {
-        const newMap = new Map(state.textures);
-        newMap.set(key, value);
-        return { textures: newMap };
-      });
-    };
-    const addMultiple = (items) => {
-      set((state) => {
-        const newMap = new Map(state.textures);
-        const entries = items instanceof Map ? items.entries() : Object.entries(items);
-        for (const [key, value] of entries) {
-          newMap.set(key, value);
-        }
-        return { textures: newMap };
-      });
-    };
-    const remove = (key) => {
-      set((state) => {
-        const newMap = new Map(state.textures);
-        newMap.delete(key);
-        return { textures: newMap };
-      });
-    };
-    const removeMultiple = (keys) => {
-      set((state) => {
-        const newMap = new Map(state.textures);
-        for (const key of keys) newMap.delete(key);
-        return { textures: newMap };
-      });
-    };
-    const dispose = (key) => {
-      const entry = getState().textures.get(key);
-      if (entry) {
-        const tex = getTextureValue(entry);
-        tex?.dispose();
-      }
-      remove(key);
-    };
-    const disposeMultiple = (keys) => {
-      const textures = getState().textures;
-      for (const key of keys) {
-        const entry = textures.get(key);
-        if (entry) {
-          const tex = getTextureValue(entry);
-          tex?.dispose();
-        }
-      }
-      removeMultiple(keys);
-    };
-    const disposeAll = () => {
-      const textures = getState().textures;
-      for (const entry of textures.values()) {
-        const tex = getTextureValue(entry);
-        tex?.dispose();
-      }
-      set({ textures: /* @__PURE__ */ new Map() });
-    };
+    const setState = store.setState;
+    const getOne = (key) => getState().textures.get(key);
     return {
-      // Getter for the textures Map (reactive via getState)
-      get textures() {
+      get all() {
         return getState().textures;
       },
-      // Read
-      get: (key) => getState().textures.get(key),
+      get(input) {
+        if (typeof input === "string") return getOne(input);
+        if (Array.isArray(input)) return input.map(getOne);
+        const out = {};
+        for (const name in input) out[name] = getOne(input[name]);
+        return out;
+      },
       has: (key) => getState().textures.has(key),
-      // Write
-      add,
-      addMultiple,
-      // Remove (cache only)
-      remove,
-      removeMultiple,
-      // Dispose (GPU + cache)
-      dispose,
-      disposeMultiple,
-      disposeAll
+      add(keyOrRecord, texture) {
+        setState((state) => {
+          const textures = new Map(state.textures);
+          if (typeof keyOrRecord === "string") {
+            textures.set(keyOrRecord, texture);
+          } else {
+            for (const key in keyOrRecord) textures.set(key, keyOrRecord[key]);
+          }
+          return { textures };
+        });
+      },
+      dispose(key, options) {
+        const state = getState();
+        const refs = state._textureRefs.get(key) ?? 0;
+        if (refs > 0 && !options?.force) {
+          console.warn(
+            `[useTextures] "${key}" still has ${refs} active reference(s); skipping dispose. Pass { force: true } to override.`
+          );
+          return false;
+        }
+        state.textures.get(key)?.dispose();
+        setState((s) => {
+          const textures = new Map(s.textures);
+          textures.delete(key);
+          const nextRefs = new Map(s._textureRefs);
+          nextRefs.delete(key);
+          return { textures, _textureRefs: nextRefs };
+        });
+        return true;
+      },
+      disposeAll() {
+        for (const texture of getState().textures.values()) texture.dispose();
+        setState({ textures: /* @__PURE__ */ new Map(), _textureRefs: /* @__PURE__ */ new Map() });
+      }
     };
   }, [store]);
+  const subscribe = selector ? () => selector(registry) : (state) => state.textures;
+  const selected = useThree(subscribe);
+  return selector ? selected : registry;
 }
 
 function useRenderTarget(widthOrOptions, heightOrOptions, options) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@react-three/fiber",
-  "version": "10.0.0-canary.c3fa45d",
+  "version": "10.0.0-canary.d6fdf72",
   "description": "A React renderer for Threejs",
   "keywords": [
     "react",