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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.mts CHANGED
@@ -1,13 +1,15 @@
1
1
  import * as three_webgpu from 'three/webgpu';
2
- import { RenderTarget, WebGPURenderer, Node, StorageTexture, Data3DTexture, CanvasTarget, ShaderNodeObject, Euler as Euler$2, Color as Color$2, ColorRepresentation as ColorRepresentation$1, Layers as Layers$1, Raycaster, Intersection as Intersection$1, BufferGeometry, Matrix4 as Matrix4$1, Quaternion as Quaternion$1, Vector2 as Vector2$1, Vector3 as Vector3$1, Vector4 as Vector4$1, Matrix3 as Matrix3$1, Loader as Loader$1, ColorSpace, Texture as Texture$1, CubeTexture, Scene, Object3D, Frustum, OrthographicCamera } from 'three/webgpu';
2
+ import { CubeRenderTarget, RenderTarget, WebGPURenderer, Node, StorageTexture, Data3DTexture, CanvasTarget, ShaderNodeObject, Euler as Euler$2, Color as Color$2, ColorRepresentation as ColorRepresentation$1, Layers as Layers$1, Raycaster, Intersection as Intersection$1, BufferGeometry, Matrix4 as Matrix4$1, Quaternion as Quaternion$1, Vector2 as Vector2$1, Vector3 as Vector3$1, Vector4 as Vector4$1, Matrix3 as Matrix3$1, Loader as Loader$1, ColorSpace, Texture as Texture$1, CubeTexture, Scene, Object3D, Frustum, OrthographicCamera } from 'three/webgpu';
3
3
  import * as THREE$1 from 'three';
4
- import { WebGLRenderTarget, WebGLRenderer, Color as Color$1, ColorRepresentation, Euler as Euler$1, Loader, RenderTargetOptions as RenderTargetOptions$1 } from 'three';
4
+ import { WebGLCubeRenderTarget, WebGLRenderTarget, WebGLRenderer, Color as Color$1, ColorRepresentation, Euler as Euler$1, Loader, RenderTargetOptions as RenderTargetOptions$1 } from 'three';
5
5
  import { WebGLRendererParameters } from 'three/src/renderers/WebGLRenderer.js';
6
6
  import { Inspector } from 'three/addons/inspector/Inspector.js';
7
7
  import * as React$1 from 'react';
8
8
  import { ReactNode, Component, RefObject, JSX } from 'react';
9
9
  import { StoreApi } from 'zustand';
10
10
  import { UseBoundStoreWithEqualityFn } from 'zustand/traditional';
11
+ import { FrameTimingState, FrameCallback as FrameCallback$1, SchedulerApi, UseFrameNextOptions, FrameNextControls } from '@pmndrs/scheduler';
12
+ export { AddPhaseOptions, FrameControls, FrameNextControls, FrameTimingState, RootOptions, Scheduler, SchedulerApi, UseFrameNextOptions, UseFrameOptions, getScheduler } from '@pmndrs/scheduler';
11
13
  import { Options } from 'react-use-measure';
12
14
  import * as react_jsx_runtime from 'react/jsx-runtime';
13
15
  import { ThreeElement as ThreeElement$1, Euler as Euler$3 } from '@react-three/fiber';
@@ -48,10 +50,13 @@ declare const R3F_BUILD_WEBGPU = true;
48
50
 
49
51
  var THREE = /*#__PURE__*/_mergeNamespaces({
50
52
  __proto__: null,
53
+ CubeRenderTarget: CubeRenderTarget,
54
+ CubeRenderTargetCompat: CubeRenderTarget,
51
55
  Inspector: Inspector,
52
56
  R3F_BUILD_LEGACY: R3F_BUILD_LEGACY,
53
57
  R3F_BUILD_WEBGPU: R3F_BUILD_WEBGPU,
54
58
  RenderTargetCompat: RenderTarget,
59
+ WebGLCubeRenderTarget: WebGLCubeRenderTarget,
55
60
  WebGLRenderTarget: WebGLRenderTarget,
56
61
  WebGLRenderer: WebGLRenderer,
57
62
  WebGLRendererParameters: WebGLRendererParameters
@@ -292,228 +297,33 @@ interface VisibilityEntry {
292
297
  }
293
298
 
294
299
  //* Scheduler Types (useFrame) ==============================
300
+ //
301
+ // The generic, framework-agnostic scheduler types now live in @pmndrs/scheduler.
302
+ // This file re-exports them and layers r3f's RootState-aware frame state on top,
303
+ // so existing `#types` imports across the codebase keep resolving unchanged.
295
304
 
296
305
 
297
306
 
298
- // Public Options --------------------------------
307
+ // Frame State (r3f-specific) --------------------------------
299
308
 
300
309
  /**
301
- * Options for useFrame hook
302
- */
303
- interface UseFrameNextOptions {
304
- /** Optional stable id for the job. Auto-generated if not provided */
305
- id?: string
306
- /** Named phase to run in. Default: 'update' */
307
- phase?: string
308
- /** Run before this phase or job id */
309
- before?: string | string[]
310
- /** Run after this phase or job id */
311
- after?: string | string[]
312
- /** Priority within phase. Higher runs first. Default: 0 */
313
- priority?: number
314
- /** Max frames per second for this job */
315
- fps?: number
316
- /** If true, skip frames when behind. If false, try to catch up. Default: true */
317
- drop?: boolean
318
- /** Enable/disable without unregistering. Default: true */
319
- enabled?: boolean
320
- }
321
-
322
- /** Alias for UseFrameNextOptions */
323
- type UseFrameOptions = UseFrameNextOptions
324
-
325
- /**
326
- * Options for addPhase
327
- */
328
- interface AddPhaseOptions {
329
- /** Insert this phase before the specified phase */
330
- before?: string
331
- /** Insert this phase after the specified phase */
332
- after?: string
333
- }
334
-
335
- // Frame State --------------------------------
336
-
337
- /**
338
- * Timing-only state for independent/outside mode (no RootState)
339
- */
340
- interface FrameTimingState {
341
- /** High-resolution timestamp from RAF (ms) */
342
- time: number
343
- /** Time since last frame in seconds (for legacy compatibility with THREE.Clock) */
344
- delta: number
345
- /** Elapsed time since first frame in seconds (for legacy compatibility with THREE.Clock) */
346
- elapsed: number
347
- /** Incrementing frame counter */
348
- frame: number
349
- }
350
-
351
- /**
352
- * State passed to useFrame callbacks (extends RootState with timing)
310
+ * State passed to useFrame callbacks (extends RootState with timing).
353
311
  */
354
312
  interface FrameNextState extends RootState, FrameTimingState {}
355
313
 
356
314
  /** Alias for FrameNextState */
357
315
  type FrameState = FrameNextState
358
316
 
359
- // Root Options --------------------------------
317
+ // Callback Types (r3f-specific) --------------------------------
360
318
 
361
319
  /**
362
- * Options for registerRoot
320
+ * Callback function for useFrame. Receives the full r3f RootState plus timing.
363
321
  */
364
- interface RootOptions {
365
- /** State provider for callbacks. Optional in independent mode. */
366
- getState?: () => any
367
- /** Error handler for job errors. Falls back to console.error if not provided. */
368
- onError?: (error: Error) => void
369
- }
370
-
371
- // Callback Types --------------------------------
372
-
373
- /**
374
- * Callback function for useFrame
375
- */
376
- type FrameNextCallback = (state: FrameNextState, delta: number) => void
322
+ type FrameNextCallback = FrameCallback$1<RootState>
377
323
 
378
324
  /** Alias for FrameNextCallback */
379
325
  type FrameCallback = FrameNextCallback
380
326
 
381
- // Controls returned from useFrame --------------------------------
382
-
383
- /**
384
- * Controls object returned from useFrame hook
385
- */
386
- interface FrameNextControls {
387
- /** The job's unique ID */
388
- id: string
389
- /** Access to the global scheduler for frame loop control */
390
- scheduler: SchedulerApi
391
- /** Manually step this job only (bypasses FPS limiting) */
392
- step(timestamp?: number): void
393
- /** Manually step ALL jobs in the scheduler */
394
- stepAll(timestamp?: number): void
395
- /** Pause this job (set enabled=false) */
396
- pause(): void
397
- /** Resume this job (set enabled=true) */
398
- resume(): void
399
- /** Reactive paused state - automatically triggers re-render when changed */
400
- isPaused: boolean
401
- }
402
-
403
- /** Alias for FrameNextControls */
404
- type FrameControls = FrameNextControls
405
-
406
- // Scheduler Interface --------------------------------
407
-
408
- /**
409
- * Public interface for the global Scheduler
410
- */
411
- interface SchedulerApi {
412
- //* Phase Management --------------------------------
413
-
414
- /** Add a named phase to the scheduler */
415
- addPhase(name: string, options?: AddPhaseOptions): void
416
- /** Get the ordered list of phase names */
417
- readonly phases: string[]
418
- /** Check if a phase exists */
419
- hasPhase(name: string): boolean
420
-
421
- //* Root Management --------------------------------
422
-
423
- /** Register a root (Canvas) with the scheduler. Returns unsubscribe function. */
424
- registerRoot(id: string, options?: RootOptions): () => void
425
- /** Unregister a root */
426
- unregisterRoot(id: string): void
427
- /** Generate a unique root ID */
428
- generateRootId(): string
429
- /** Get the number of registered roots */
430
- getRootCount(): number
431
- /** Check if any root is registered and ready */
432
- readonly isReady: boolean
433
- /** Subscribe to root-ready event. Fires immediately if already ready. Returns unsubscribe. */
434
- onRootReady(callback: () => void): () => void
435
-
436
- //* Job Registration --------------------------------
437
-
438
- /** Register a job with the scheduler (returns unsubscribe function) */
439
- register(
440
- callback: FrameNextCallback,
441
- options?: {
442
- id?: string
443
- rootId?: string
444
- phase?: string
445
- before?: string | string[]
446
- after?: string | string[]
447
- priority?: number
448
- fps?: number
449
- drop?: boolean
450
- enabled?: boolean
451
- },
452
- ): () => void
453
- /** Update a job's options */
454
- updateJob(
455
- id: string,
456
- options: {
457
- priority?: number
458
- fps?: number
459
- drop?: boolean
460
- enabled?: boolean
461
- phase?: string
462
- before?: string | string[]
463
- after?: string | string[]
464
- },
465
- ): void
466
- /** Unregister a job by ID */
467
- unregister(id: string, rootId?: string): void
468
- /** Get the number of registered jobs */
469
- getJobCount(): number
470
- /** Get all job IDs */
471
- getJobIds(): string[]
472
-
473
- //* Global Jobs (for legacy addEffect/addAfterEffect) --------------------------------
474
-
475
- /** Register a global job (runs once per frame, not per-root). Returns unsubscribe function. */
476
- registerGlobal(phase: 'before' | 'after', id: string, callback: (timestamp: number) => void): () => void
477
-
478
- //* Idle Callbacks (for legacy addTail) --------------------------------
479
-
480
- /** Register an idle callback (fires when loop stops). Returns unsubscribe function. */
481
- onIdle(callback: (timestamp: number) => void): () => void
482
-
483
- //* Frame Loop Control --------------------------------
484
-
485
- /** Start the scheduler loop */
486
- start(): void
487
- /** Stop the scheduler loop */
488
- stop(): void
489
- /** Check if the scheduler is running */
490
- readonly isRunning: boolean
491
- /** Get/set the frameloop mode ('always', 'demand', 'never') */
492
- frameloop: Frameloop
493
- /** Independent mode - runs without Canvas, callbacks receive timing-only state */
494
- independent: boolean
495
-
496
- //* Manual Stepping --------------------------------
497
-
498
- /** Manually step all jobs once (for frameloop='never' or testing) */
499
- step(timestamp?: number): void
500
- /** Manually step a single job by ID */
501
- stepJob(id: string, timestamp?: number): void
502
- /** Request frame(s) to be rendered (for frameloop='demand') */
503
- invalidate(frames?: number): void
504
-
505
- //* Per-Job Control --------------------------------
506
-
507
- /** Check if a job is paused */
508
- isJobPaused(id: string): boolean
509
- /** Pause a job */
510
- pauseJob(id: string): void
511
- /** Resume a job */
512
- resumeJob(id: string): void
513
- /** Subscribe to job state changes (for reactive isPaused). Returns unsubscribe function. */
514
- subscribeJobState(id: string, listener: () => void): () => void
515
- }
516
-
517
327
  //* Buffer Types (useBuffers) ========================================
518
328
 
519
329
  /**
@@ -689,7 +499,7 @@ interface InternalState {
689
499
  canvasTarget?: CanvasTarget
690
500
  /**
691
501
  * Whether multi-canvas rendering is active.
692
- * True when any canvas uses `target` prop to share a renderer.
502
+ * True when any canvas uses `renderer={{ primaryCanvas: 'id' }}` to share a renderer.
693
503
  * When true, setCanvasTarget is called before each render.
694
504
  */
695
505
  isMultiCanvas?: boolean
@@ -787,8 +597,8 @@ interface RootState {
787
597
  setSize: (width?: number, height?: number, top?: number, left?: number) => void
788
598
  /** Shortcut to manual setting the pixel ratio */
789
599
  setDpr: (dpr: Dpr) => void
790
- /** Shortcut to setting frameloop flags */
791
- setFrameloop: (frameloop: Frameloop) => void
600
+ /** Shortcut to setting frameloop flags. No args resets to 'always'. */
601
+ setFrameloop: (frameloop?: Frameloop) => void
792
602
  /** Set error state to propagate to error boundary */
793
603
  setError: (error: Error | null) => void
794
604
  /** Current error state (null when no error) */
@@ -801,10 +611,12 @@ interface RootState {
801
611
  buffers: BufferStore
802
612
  /** Global GPU storage (textures, etc.) - root-level storage + scoped sub-objects. Use useGPUStorage() hook */
803
613
  gpuStorage: StorageStore
804
- /** Global TSL texture nodes - use useTextures() hook for operations */
805
- textures: Map<string, any>
614
+ /** Global Texture registry (key → Texture, usually keyed by URL) - use useTextures() hook for access + lifecycle */
615
+ textures: Map<string, THREE$1.Texture>
616
+ /** Internal: refcount per texture key, driven by mounted useTexture consumers (registry enrollment is on by default) */
617
+ _textureRefs: Map<string, number>
806
618
  /** WebGPU RenderPipeline instance - use useRenderPipeline() hook */
807
- renderPipeline: any | null // THREE.PostProcessing (will be THREE.RenderPipeline in future Three.js release)
619
+ renderPipeline: ThreeRenderPipeline | null
808
620
  /** Global TSL pass nodes for render pipeline - use useRenderPipeline() hook */
809
621
  passes: Record<string, any>
810
622
  /** Internal version counter for HMR - incremented by rebuildNodes/rebuildUniforms to bust memoization */
@@ -1097,8 +909,6 @@ interface Instance<O = any> {
1097
909
  attach?: AttachType<O>
1098
910
  previousAttach?: any
1099
911
  isHidden: boolean
1100
- /** Deferred ref props to apply in commitMount */
1101
- deferredRefs?: Array<{ prop: string; ref: React$1.RefObject<any> }>
1102
912
  /** Set of props that have been applied via once() */
1103
913
  appliedOnce?: Set<string>
1104
914
  }
@@ -1335,10 +1145,21 @@ type RenderTargetOptions = RenderTargetOptions$1
1335
1145
  //* Global Types ==============================
1336
1146
 
1337
1147
  declare global {
1338
- /** Uniform node type - a Node with a value property (matches Three.js UniformNode) */
1339
- interface UniformNode<T = unknown> extends Node {
1340
- value: T
1341
- }
1148
+ /**
1149
+ * Uniform node type.
1150
+ *
1151
+ * This is three's own `UniformNode`, not a re-declaration of it. It previously was a
1152
+ * hand-rolled `interface UniformNode<T> extends Node { value: T }`, which shadowed the real
1153
+ * exported type globally — so R3F's ~58 references resolved to an approximation that was
1154
+ * missing members three actually ships (`setName` among them) and had drifted to the wrong
1155
+ * arity when three made `UniformNode` two-parameter.
1156
+ *
1157
+ * three's signature is `UniformNode<TNodeType, TValue>`. R3F only ever varies the value type,
1158
+ * so the node type is fixed to `unknown` and the single parameter is kept for call-site
1159
+ * ergonomics. The result is three's structural type, so members stay in sync with the
1160
+ * installed three instead of needing to be mirrored by hand.
1161
+ */
1162
+ type UniformNode<T = unknown> = three_webgpu.UniformNode<unknown, T>
1342
1163
 
1343
1164
  /**
1344
1165
  * ShaderCallable - the return type of Fn()
@@ -1483,13 +1304,14 @@ declare module 'three/tsl' {
1483
1304
  ): ShaderCallable<R>
1484
1305
  }
1485
1306
 
1486
- /**
1487
- * RenderPipeline Types for useRenderPipeline hook (WebGPU only)
1488
- */
1489
-
1490
-
1491
-
1492
1307
  declare global {
1308
+ /**
1309
+ * three's own render pipeline type. Named here so the rest of R3F refers to three's shape
1310
+ * rather than `any`. three r183 renamed `PostProcessing` to `RenderPipeline`; our peer floor
1311
+ * is r185, so the new name is the only one.
1312
+ */
1313
+ type ThreeRenderPipeline = three_webgpu.RenderPipeline
1314
+
1493
1315
  /** Pass record - stores TSL pass nodes for render pipeline */
1494
1316
  type PassRecord = Record<string, any>
1495
1317
 
@@ -1504,7 +1326,7 @@ declare global {
1504
1326
  /** Current passes from state */
1505
1327
  passes: PassRecord
1506
1328
  /** RenderPipeline instance (null if not initialized) */
1507
- renderPipeline: any | null // THREE.PostProcessing (will be THREE.RenderPipeline in future Three.js release)
1329
+ renderPipeline: ThreeRenderPipeline | null
1508
1330
  /** Clear all passes from state */
1509
1331
  clearPasses: () => void
1510
1332
  /** Reset RenderPipeline entirely (clears PP + passes) */
@@ -1516,146 +1338,6 @@ declare global {
1516
1338
  }
1517
1339
  }
1518
1340
 
1519
- //* useFrameNext Types ==============================
1520
-
1521
-
1522
-
1523
- //* Global Type Declarations ==============================
1524
-
1525
- declare global {
1526
- // Job --------------------------------
1527
-
1528
- /**
1529
- * Internal job representation in the scheduler
1530
- */
1531
- interface Job {
1532
- /** Unique identifier */
1533
- id: string
1534
- /** The callback to execute */
1535
- callback: FrameNextCallback
1536
- /** Phase this job belongs to */
1537
- phase: string
1538
- /** Run before these phases/job ids */
1539
- before: Set<string>
1540
- /** Run after these phases/job ids */
1541
- after: Set<string>
1542
- /** Priority within phase (higher first) */
1543
- priority: number
1544
- /** Insertion order for deterministic tie-breaking */
1545
- index: number
1546
- /** Max FPS for this job (undefined = no limit) */
1547
- fps?: number
1548
- /** Drop frames when behind (true) or catch up (false) */
1549
- drop: boolean
1550
- /** Last run timestamp (ms) */
1551
- lastRun?: number
1552
- /** Whether job is enabled */
1553
- enabled: boolean
1554
- /** Internal flag: system jobs (like default render) don't block user render takeover */
1555
- system?: boolean
1556
- }
1557
-
1558
- // Phase Graph --------------------------------
1559
-
1560
- /**
1561
- * A node in the phase graph
1562
- */
1563
- interface PhaseNode {
1564
- /** Phase name */
1565
- name: string
1566
- /** Whether this was auto-generated from a before/after constraint */
1567
- isAutoGenerated: boolean
1568
- }
1569
-
1570
- /**
1571
- * Options for creating a job from hook options
1572
- */
1573
- interface JobOptions {
1574
- id?: string
1575
- phase?: string
1576
- before?: string | string[]
1577
- after?: string | string[]
1578
- priority?: number
1579
- fps?: number
1580
- drop?: boolean
1581
- enabled?: boolean
1582
- }
1583
-
1584
- // Frame Loop State --------------------------------
1585
-
1586
- /**
1587
- * Internal frame loop state
1588
- */
1589
- interface FrameLoopState {
1590
- /** Whether the loop is running */
1591
- running: boolean
1592
- /** Current RAF handle */
1593
- rafHandle: number | null
1594
- /** Last frame timestamp in ms (null = uninitialized) */
1595
- lastTime: number | null
1596
- /** Frame counter */
1597
- frameCount: number
1598
- /** Elapsed time since first frame in ms */
1599
- elapsedTime: number
1600
- /** createdAt timestamp in ms */
1601
- createdAt: number
1602
- }
1603
-
1604
- // Root Entry --------------------------------
1605
-
1606
- /**
1607
- * Internal representation of a registered root (Canvas).
1608
- * Tracks jobs and manages rebuild state for this root.
1609
- * @internal
1610
- */
1611
- interface RootEntry {
1612
- /** Unique identifier for this root */
1613
- id: string
1614
- /** Function to get the root's current state. Returns any to support independent mode. */
1615
- getState: () => any
1616
- /** Map of job IDs to Job objects */
1617
- jobs: Map<string, Job>
1618
- /** Cached sorted job list for execution order */
1619
- sortedJobs: Job[]
1620
- /** Whether sortedJobs needs rebuilding */
1621
- needsRebuild: boolean
1622
- }
1623
-
1624
- /**
1625
- * Internal representation of a global job (deprecated API).
1626
- * Global jobs run once per frame, not per-root.
1627
- * Used by legacy addEffect/addAfterEffect APIs.
1628
- * @internal
1629
- * @deprecated Use useFrame with phases instead
1630
- */
1631
- interface GlobalJob {
1632
- /** Unique identifier for this global job */
1633
- id: string
1634
- /** Callback invoked with RAF timestamp in ms */
1635
- callback: (timestamp: number) => void
1636
- }
1637
-
1638
- // HMR Support --------------------------------
1639
-
1640
- /**
1641
- * Hot Module Replacement data structure for preserving scheduler state
1642
- * @internal
1643
- */
1644
- interface HMRData {
1645
- /** Shared data object for storing values across reloads */
1646
- data: Record<string, any>
1647
- /** Optional function to accept HMR updates */
1648
- accept?: () => void
1649
- }
1650
-
1651
- // Default Phases --------------------------------
1652
-
1653
- /**
1654
- * Default phase names for the scheduler
1655
- */
1656
- type DefaultPhase = 'start' | 'input' | 'physics' | 'update' | 'render' | 'finish'
1657
- }
1658
-
1659
1341
  type MutableOrReadonlyParameters<T extends (...args: any) => any> = Parameters<T> | Readonly<Parameters<T>>
1660
1342
 
1661
1343
  interface MathRepresentation {
@@ -1825,7 +1507,7 @@ declare namespace three_d {
1825
1507
  * a single WebGPURenderer using Three.js CanvasTarget API.
1826
1508
  *
1827
1509
  * Primary canvas: Has `id` prop, creates its own renderer, registers here
1828
- * Secondary canvas: Has `target="id"` prop, shares primary's renderer via CanvasTarget
1510
+ * Secondary canvas: Has `renderer={{ primaryCanvas: 'id' }}`, shares primary's renderer via CanvasTarget
1829
1511
  */
1830
1512
 
1831
1513
  interface PrimaryCanvasEntry {
@@ -1893,12 +1575,23 @@ type EnvironmentLoaderProps = {
1893
1575
  * const texture = useEnvironment({ preset: 'sunset' })
1894
1576
  * ```
1895
1577
  */
1896
- declare function useEnvironment({ files, path, preset, colorSpace, extensions, }?: Partial<EnvironmentLoaderProps>): Texture$1<unknown> | CubeTexture;
1578
+ declare function useEnvironment({ files, path, preset, colorSpace, extensions, }?: Partial<EnvironmentLoaderProps>): Texture$1<unknown, THREE$1.TextureEventMap> | CubeTexture<unknown>;
1897
1579
  declare namespace useEnvironment {
1898
1580
  var preload: (preloadOptions?: EnvironmentLoaderPreloadOptions) => void;
1899
1581
  var clear: (clearOptions?: EnvironmentLoaderClearOptions) => void;
1900
1582
  }
1901
- type EnvironmentLoaderPreloadOptions = Omit<EnvironmentLoaderProps, 'encoding'>;
1583
+ /**
1584
+ * Options accepted by `useEnvironment.preload`.
1585
+ *
1586
+ * `colorSpace` is deliberately omitted: preload only warms the loader cache, and colorSpace is
1587
+ * applied to the texture by `useEnvironment()` at use time, per consumer. Accepting it here would
1588
+ * advertise an option this function silently ignores.
1589
+ *
1590
+ * This previously read `Omit<…, 'encoding'>` — omitting a key that does not exist on
1591
+ * `EnvironmentLoaderProps`, a leftover from three's pre-`colorSpace` `encoding` API. That made the
1592
+ * type equivalent to the full props, so `colorSpace` was accepted and then dropped on the floor.
1593
+ */
1594
+ type EnvironmentLoaderPreloadOptions = Omit<EnvironmentLoaderProps, 'colorSpace'>;
1902
1595
  type EnvironmentLoaderClearOptions = Pick<EnvironmentLoaderProps, 'files' | 'preset'>;
1903
1596
 
1904
1597
  /**
@@ -2148,383 +1841,21 @@ declare function getLoader<L extends LoaderLike | ConstructorRepresentation<Load
2148
1841
  * Note: this hook's caller must be wrapped with `React.Suspense`
2149
1842
  * @see https://docs.pmnd.rs/react-three-fiber/api/hooks#useloader
2150
1843
  */
2151
- declare function useLoader<I extends InputLike, L extends LoaderLike | ConstructorRepresentation<LoaderLike>>(loader: L, input: I, extensions?: Extensions<L>, onProgress?: (event: ProgressEvent<EventTarget>) => void): I extends any[] ? LoaderResult<L>[] : LoaderResult<L>;
1844
+ declare function useLoader<I extends InputLike, L extends LoaderLike | ConstructorRepresentation<LoaderLike>>(loader: L, input: I, extensions?: Extensions<L>, onProgress?: (event: ProgressEvent<EventTarget>) => void, cacheKey?: InputLike): I extends any[] ? LoaderResult<L>[] : LoaderResult<L>;
2152
1845
  declare namespace useLoader {
2153
- var preload: <I extends InputLike, L extends LoaderLike | ConstructorRepresentation<LoaderLike>>(loader: L, input: I, extensions?: Extensions<L>, onProgress?: (event: ProgressEvent<EventTarget>) => void) => void;
2154
- var clear: <I extends InputLike, L extends LoaderLike | ConstructorRepresentation<LoaderLike>>(loader: L, input: I) => void;
1846
+ var preload: <I extends InputLike, L extends LoaderLike | ConstructorRepresentation<LoaderLike>>(loader: L, input: I, extensions?: Extensions<L>, onProgress?: (event: ProgressEvent<EventTarget>) => void, cacheKey?: InputLike) => void;
1847
+ var clear: <I extends InputLike, L extends LoaderLike | ConstructorRepresentation<LoaderLike>>(loader: L, input: I, cacheKey?: InputLike) => void;
2155
1848
  var loader: typeof getLoader;
2156
1849
  }
2157
1850
 
2158
- /**
2159
- * Global Singleton Scheduler - manages the frame loop and job execution for ALL R3F roots.
2160
- *
2161
- * Features:
2162
- * - Single RAF loop for entire application
2163
- * - Root registration (multiple Canvas support)
2164
- * - Global phases for addEffect/addAfterEffect (deprecated)
2165
- * - Per-root job management with phases, priorities, FPS throttling
2166
- * - onIdle callbacks for addTail (deprecated)
2167
- * - Demand mode support via invalidate()
2168
- */
2169
- declare class Scheduler {
2170
- private static readonly INSTANCE_KEY;
2171
- private static get instance();
2172
- private static set instance(value);
2173
- /**
2174
- * Get the global scheduler instance (creates if doesn't exist).
2175
- * Uses HMR data to preserve instance across hot reloads.
2176
- * @returns {Scheduler} The singleton scheduler instance
2177
- */
2178
- static get(): Scheduler;
2179
- /**
2180
- * Reset the singleton instance. Stops the loop and clears all state.
2181
- * Primarily used for testing to ensure clean state between tests.
2182
- * @returns {void}
2183
- */
2184
- static reset(): void;
2185
- private roots;
2186
- private phaseGraph;
2187
- private loopState;
2188
- private stoppedTime;
2189
- private nextRootIndex;
2190
- private globalBeforeJobs;
2191
- private globalAfterJobs;
2192
- private nextGlobalIndex;
2193
- private idleCallbacks;
2194
- private nextJobIndex;
2195
- private jobStateListeners;
2196
- private pendingFrames;
2197
- private _frameloop;
2198
- private _independent;
2199
- private errorHandler;
2200
- private rootReadyCallbacks;
2201
- get phases(): string[];
2202
- get frameloop(): Frameloop;
2203
- set frameloop(mode: Frameloop);
2204
- get isRunning(): boolean;
2205
- get isReady(): boolean;
2206
- get independent(): boolean;
2207
- set independent(value: boolean);
2208
- constructor();
2209
- /**
2210
- * Register a root (Canvas) with the scheduler.
2211
- * The first root to register starts the RAF loop (if frameloop='always').
2212
- * @param {string} id - Unique identifier for this root
2213
- * @param {RootOptions} [options] - Optional configuration with getState and onError callbacks
2214
- * @returns {() => void} Unsubscribe function to remove this root
2215
- */
2216
- registerRoot(id: string, options?: RootOptions): () => void;
2217
- /**
2218
- * Unregister a root from the scheduler.
2219
- * Cleans up all job state listeners for this root's jobs.
2220
- * The last root to unregister stops the RAF loop.
2221
- * @param {string} id - The root ID to unregister
2222
- * @returns {void}
2223
- */
2224
- unregisterRoot(id: string): void;
2225
- /**
2226
- * Subscribe to be notified when a root becomes available.
2227
- * Fires immediately if a root already exists.
2228
- * @param {() => void} callback - Function called when first root registers
2229
- * @returns {() => void} Unsubscribe function
2230
- */
2231
- onRootReady(callback: () => void): () => void;
2232
- /**
2233
- * Notify all registered root-ready callbacks.
2234
- * Called when the first root registers.
2235
- * @returns {void}
2236
- * @private
2237
- */
2238
- private notifyRootReady;
2239
- /**
2240
- * Ensure a default root exists for independent mode.
2241
- * Creates a minimal root with no state provider.
2242
- * @returns {void}
2243
- * @private
2244
- */
2245
- private ensureDefaultRoot;
2246
- /**
2247
- * Trigger error handling for job errors.
2248
- * Uses the bound error handler if available, otherwise logs to console.
2249
- * @param {Error} error - The error to handle
2250
- * @returns {void}
2251
- */
2252
- triggerError(error: Error): void;
2253
- /**
2254
- * Add a named phase to the scheduler's execution order.
2255
- * Marks all roots for rebuild to incorporate the new phase.
2256
- * @param {string} name - The phase name (e.g., 'physics', 'postprocess')
2257
- * @param {AddPhaseOptions} [options] - Positioning options (before/after other phases)
2258
- * @returns {void}
2259
- * @example
2260
- * scheduler.addPhase('physics', { before: 'update' });
2261
- * scheduler.addPhase('postprocess', { after: 'render' });
2262
- */
2263
- addPhase(name: string, options?: AddPhaseOptions): void;
2264
- /**
2265
- * Check if a phase exists in the scheduler.
2266
- * @param {string} name - The phase name to check
2267
- * @returns {boolean} True if the phase exists
2268
- */
2269
- hasPhase(name: string): boolean;
2270
- /**
2271
- * Register a global job that runs once per frame (not per-root).
2272
- * Used internally by deprecated addEffect/addAfterEffect APIs.
2273
- * @param {'before' | 'after'} phase - When to run: 'before' all roots or 'after' all roots
2274
- * @param {string} id - Unique identifier for this global job
2275
- * @param {(timestamp: number) => void} callback - Function called each frame with RAF timestamp
2276
- * @returns {() => void} Unsubscribe function to remove this global job
2277
- * @deprecated Use useFrame with phases instead
2278
- */
2279
- registerGlobal(phase: 'before' | 'after', id: string, callback: (timestamp: number) => void): () => void;
2280
- /**
2281
- * Register an idle callback that fires when the loop stops.
2282
- * Used internally by deprecated addTail API.
2283
- * @param {(timestamp: number) => void} callback - Function called when loop becomes idle
2284
- * @returns {() => void} Unsubscribe function to remove this idle callback
2285
- * @deprecated Use demand mode with invalidate() instead
2286
- */
2287
- onIdle(callback: (timestamp: number) => void): () => void;
2288
- /**
2289
- * Notify all registered idle callbacks.
2290
- * Called when the loop stops in demand mode.
2291
- * @param {number} timestamp - The RAF timestamp when idle occurred
2292
- * @returns {void}
2293
- * @private
2294
- */
2295
- private notifyIdle;
2296
- /**
2297
- * Register a job (frame callback) with a specific root.
2298
- * This is the core registration method used by useFrame internally.
2299
- * @param {FrameNextCallback} callback - The function to call each frame
2300
- * @param {JobOptions & { rootId?: string; system?: boolean }} [options] - Job configuration
2301
- * @param {string} [options.rootId] - Target root ID (defaults to first registered root)
2302
- * @param {string} [options.id] - Unique job ID (auto-generated if not provided)
2303
- * @param {string} [options.phase] - Execution phase (defaults to 'update')
2304
- * @param {number} [options.priority] - Priority within phase (higher = earlier, default 0)
2305
- * @param {number} [options.fps] - FPS throttle limit
2306
- * @param {boolean} [options.drop] - Drop frames when behind (default true)
2307
- * @param {boolean} [options.enabled] - Whether job is active (default true)
2308
- * @param {boolean} [options.system] - Internal flag for system jobs (not user-facing)
2309
- * @returns {() => void} Unsubscribe function to remove this job
2310
- */
2311
- register(callback: FrameNextCallback, options?: JobOptions & {
2312
- rootId?: string;
2313
- system?: boolean;
2314
- }): () => void;
2315
- /**
2316
- * Unregister a job by its ID.
2317
- * Searches all roots if rootId is not provided.
2318
- * @param {string} id - The job ID to unregister
2319
- * @param {string} [rootId] - Optional root ID to search (searches all if not provided)
2320
- * @returns {void}
2321
- */
2322
- unregister(id: string, rootId?: string): void;
2323
- /**
2324
- * Update a job's options dynamically.
2325
- * Searches all roots to find the job by ID.
2326
- * Phase/constraint changes trigger a rebuild of the sorted job list.
2327
- * @param {string} id - The job ID to update
2328
- * @param {Partial<JobOptions>} options - The options to update
2329
- * @returns {void}
2330
- */
2331
- updateJob(id: string, options: Partial<JobOptions>): void;
2332
- /**
2333
- * Check if a job is currently paused (disabled).
2334
- * @param {string} id - The job ID to check
2335
- * @returns {boolean} True if the job exists and is paused
2336
- */
2337
- isJobPaused(id: string): boolean;
2338
- /**
2339
- * Subscribe to state changes for a specific job.
2340
- * Listener is called when job is paused or resumed.
2341
- * @param {string} id - The job ID to subscribe to
2342
- * @param {() => void} listener - Callback invoked on state changes
2343
- * @returns {() => void} Unsubscribe function
2344
- */
2345
- subscribeJobState(id: string, listener: () => void): () => void;
2346
- /**
2347
- * Notify all listeners that a job's state has changed.
2348
- * @param {string} id - The job ID that changed
2349
- * @returns {void}
2350
- * @private
2351
- */
2352
- private notifyJobStateChange;
2353
- /**
2354
- * Pause a job by ID (sets enabled=false).
2355
- * Notifies any subscribed state listeners.
2356
- * @param {string} id - The job ID to pause
2357
- * @returns {void}
2358
- */
2359
- pauseJob(id: string): void;
2360
- /**
2361
- * Resume a paused job by ID (sets enabled=true).
2362
- * Resets job timing to prevent frame accumulation.
2363
- * Notifies any subscribed state listeners.
2364
- * @param {string} id - The job ID to resume
2365
- * @returns {void}
2366
- */
2367
- resumeJob(id: string): void;
2368
- /**
2369
- * Start the requestAnimationFrame loop.
2370
- * Resets timing state (elapsedTime, frameCount) on start.
2371
- * No-op if already running.
2372
- * @returns {void}
2373
- */
2374
- start(): void;
2375
- /**
2376
- * Stop the requestAnimationFrame loop.
2377
- * Cancels any pending RAF callback.
2378
- * No-op if not running.
2379
- * @returns {void}
2380
- */
2381
- stop(): void;
2382
- /**
2383
- * Request frames to be rendered in demand mode.
2384
- * Accumulates pending frames (capped at 60) and starts the loop if not running.
2385
- * No-op if frameloop is not 'demand'.
2386
- * @param {number} [frames=1] - Number of frames to request
2387
- * @param {boolean} [stackFrames=false] - Whether to add frames to existing pending count
2388
- * - `false` (default): Sets pending frames to the specified value (replaces existing count)
2389
- * - `true`: Adds frames to existing pending count (useful for accumulating invalidations)
2390
- * @returns {void}
2391
- * @example
2392
- * // Request a single frame render
2393
- * scheduler.invalidate();
2394
- *
2395
- * @example
2396
- * // Request 5 frames (e.g., for animations)
2397
- * scheduler.invalidate(5);
2398
- *
2399
- * @example
2400
- * // Set pending frames to exactly 3 (don't stack with existing)
2401
- * scheduler.invalidate(3, false);
2402
- *
2403
- * @example
2404
- * // Add 2 more frames to existing pending count
2405
- * scheduler.invalidate(2, true);
2406
- */
2407
- invalidate(frames?: number, stackFrames?: boolean): void;
2408
- /**
2409
- * Reset timing state for deterministic testing.
2410
- * Preserves jobs and roots but resets lastTime, frameCount, elapsedTime, etc.
2411
- * @returns {void}
2412
- */
2413
- resetTiming(): void;
2414
- /**
2415
- * Manually execute a single frame for all roots.
2416
- * Useful for frameloop='never' mode or testing scenarios.
2417
- * @param {number} [timestamp] - Optional timestamp (defaults to performance.now())
2418
- * @returns {void}
2419
- * @example
2420
- * // Manual control mode
2421
- * scheduler.frameloop = 'never';
2422
- * scheduler.step(); // Execute one frame
2423
- */
2424
- step(timestamp?: number): void;
2425
- /**
2426
- * Manually execute a single job by its ID.
2427
- * Useful for testing individual job callbacks in isolation.
2428
- * @param {string} id - The job ID to step
2429
- * @param {number} [timestamp] - Optional timestamp (defaults to performance.now())
2430
- * @returns {void}
2431
- */
2432
- stepJob(id: string, timestamp?: number): void;
2433
- /**
2434
- * Main RAF loop callback.
2435
- * Executes frame, handles demand mode, and schedules next frame.
2436
- * @param {number} timestamp - RAF timestamp in milliseconds
2437
- * @returns {void}
2438
- * @private
2439
- */
2440
- private loop;
2441
- /**
2442
- * Execute a single frame across all roots.
2443
- * Order: globalBefore → each root's jobs → globalAfter
2444
- * @param {number} timestamp - RAF timestamp in milliseconds
2445
- * @returns {void}
2446
- * @private
2447
- */
2448
- private executeFrame;
2449
- /**
2450
- * Run all global jobs from a job map.
2451
- * Catches and logs errors without stopping execution.
2452
- * @param {Map<string, GlobalJob>} jobs - The global jobs map to execute
2453
- * @param {number} timestamp - RAF timestamp in milliseconds
2454
- * @returns {void}
2455
- * @private
2456
- */
2457
- private runGlobalJobs;
2458
- /**
2459
- * Execute all jobs for a single root in sorted order.
2460
- * Rebuilds sorted job list if needed, then dispatches each job.
2461
- * Errors are caught and propagated via triggerError.
2462
- * @param {RootEntry} root - The root entry to tick
2463
- * @param {number} timestamp - RAF timestamp in milliseconds
2464
- * @param {number} delta - Time since last frame in seconds
2465
- * @returns {void}
2466
- * @private
2467
- */
2468
- private tickRoot;
2469
- /**
2470
- * Get the total number of registered jobs across all roots.
2471
- * Includes both per-root jobs and global before/after jobs.
2472
- * @returns {number} Total job count
2473
- */
2474
- getJobCount(): number;
2475
- /**
2476
- * Get all registered job IDs across all roots.
2477
- * Includes both per-root jobs and global before/after jobs.
2478
- * @returns {string[]} Array of all job IDs
2479
- */
2480
- getJobIds(): string[];
2481
- /**
2482
- * Get the number of registered roots (Canvas instances).
2483
- * @returns {number} Number of registered roots
2484
- */
2485
- getRootCount(): number;
2486
- /**
2487
- * Check if any user (non-system) jobs are registered in a specific phase.
2488
- * Used by the default render job to know if a user has taken over rendering.
2489
- *
2490
- * @param phase The phase to check
2491
- * @param rootId Optional root ID to check (checks all roots if not provided)
2492
- * @returns true if any user jobs exist in the phase
2493
- */
2494
- hasUserJobsInPhase(phase: string, rootId?: string): boolean;
2495
- /**
2496
- * Generate a unique root ID for automatic root registration.
2497
- * @returns {string} A unique root ID in the format 'root_N'
2498
- */
2499
- generateRootId(): string;
2500
- /**
2501
- * Generate a unique job ID.
2502
- * @returns {string} A unique job ID in the format 'job_N'
2503
- * @private
2504
- */
2505
- private generateJobId;
2506
- /**
2507
- * Normalize before/after constraints to a Set.
2508
- * Handles undefined, single string, or array inputs.
2509
- * @param {string | string[] | undefined} value - The constraint value(s)
2510
- * @returns {Set<string>} Normalized Set of constraint strings
2511
- * @private
2512
- */
2513
- private normalizeConstraints;
2514
- }
2515
- /**
2516
- * Get the global scheduler instance.
2517
- * Creates one if it doesn't exist.
2518
- */
2519
- declare const getScheduler: () => Scheduler;
2520
-
2521
1851
  /**
2522
1852
  * Frame hook with phase-based ordering, priority, and FPS throttling.
2523
1853
  *
2524
- * Works both inside and outside Canvas context:
2525
- * - Inside Canvas: Full RootState (gl, scene, camera, etc.)
2526
- * - Outside Canvas (waiting mode): Waits for Canvas to mount, then gets full state
2527
- * - Outside Canvas (independent mode): Fires immediately with timing-only state
1854
+ * Always delivers full RootState — works both inside and outside Canvas context:
1855
+ * - Inside Canvas: Full RootState (renderer, scene, camera, etc.)
1856
+ * - Outside Canvas: The job registers immediately but the callback is held until a
1857
+ * Canvas adopts it, then runs with full RootState. For hostless / standalone
1858
+ * frame loops with no Canvas, use `@pmndrs/scheduler` directly.
2528
1859
  *
2529
1860
  * Returns a controls object for manual stepping, pausing, and resuming.
2530
1861
  *
@@ -2541,16 +1872,16 @@ declare const getScheduler: () => Scheduler;
2541
1872
  * useFrame((state, delta) => { ... }, { phase: 'physics' })
2542
1873
  *
2543
1874
  * @example
2544
- * // Outside Canvas - waits for Canvas to mount
1875
+ * // Outside Canvas - callback waits for a Canvas, then always has full state
2545
1876
  * function UI() {
2546
1877
  * useFrame((state, delta) => { syncUI(state.camera) });
2547
1878
  * return <button>...</button>;
2548
1879
  * }
2549
1880
  *
2550
1881
  * @example
2551
- * // Independent mode - no Canvas needed
2552
- * getScheduler().independent = true;
2553
- * useFrame((state, delta) => { updateGame(delta) });
1882
+ * // Hostless / standalone loop (no Canvas) - use @pmndrs/scheduler directly
1883
+ * import { getScheduler } from '@pmndrs/scheduler'
1884
+ * getScheduler().register((state, delta) => { updateGame(delta) })
2554
1885
  *
2555
1886
  * @example
2556
1887
  * // Scheduler-only access (no callback)
@@ -2573,11 +1904,16 @@ type UseTextureOptions<Url extends string[] | string | Record<string, string>> =
2573
1904
  /** Callback when texture(s) finish loading */
2574
1905
  onLoad?: (texture: MappedTextureType<Url>) => void;
2575
1906
  /**
2576
- * Cache the texture in R3F's global state for access via useTextures().
2577
- * When true:
1907
+ * Register the texture(s) in R3F's global texture registry for access via useTextures().
1908
+ * When true (the default):
2578
1909
  * - Textures persist until explicitly disposed
2579
- * - Returns existing cached textures if available (preserving modifications like colorSpace)
2580
- * @default false
1910
+ * - On mount, returns existing registered textures if available (preserving modifications like colorSpace)
1911
+ *
1912
+ * Reads are taken once at mount — a mounted `useTexture` does not re-render when the registry
1913
+ * changes. To react to registry swaps, use `useTextures(s => s.get(key))` instead.
1914
+ *
1915
+ * Pass `false` to opt out of registry enrollment entirely.
1916
+ * @default true
2581
1917
  */
2582
1918
  cache?: boolean;
2583
1919
  };
@@ -2601,15 +1937,18 @@ type UseTextureOptions<Url extends string[] | string | Record<string, string>> =
2601
1937
  * normal: '/normal.png'
2602
1938
  * })
2603
1939
  *
2604
- * // With caching - returns same texture object across components
2605
- * // Modifications (colorSpace, wrapS, etc.) are preserved
2606
- * const diffuse = useTexture('/diffuse.png', { cache: true })
1940
+ * // Textures are registered in the global registry by default — the same texture
1941
+ * // object is shared across components and modifications (colorSpace, wrapS, etc.) are preserved
1942
+ * const diffuse = useTexture('/diffuse.png')
2607
1943
  * diffuse.colorSpace = THREE.SRGBColorSpace
2608
1944
  *
2609
1945
  * // Another component gets the SAME texture with colorSpace already set
2610
- * const sameDiffuse = useTexture('/diffuse.png', { cache: true })
1946
+ * const sameDiffuse = useTexture('/diffuse.png')
1947
+ *
1948
+ * // Opt out of registry enrollment for a one-off texture
1949
+ * const scratch = useTexture('/scratch.png', { cache: false })
2611
1950
  *
2612
- * // Access cache directly
1951
+ * // Access the registry directly
2613
1952
  * const { get } = useTextures()
2614
1953
  * const cached = get('/diffuse.png')
2615
1954
  * ```
@@ -2626,63 +1965,80 @@ declare const Texture: ({ children, input, onLoad, cache, }: {
2626
1965
  cache?: boolean;
2627
1966
  }) => react_jsx_runtime.JSX.Element;
2628
1967
 
2629
- type TextureEntry = Texture$1 | {
2630
- value: Texture$1;
2631
- [key: string]: any;
1968
+ /** Accepted shapes for a registry read: a single key, a list of keys, or a name→key map. */
1969
+ type TextureInput = string | string[] | Record<string, string>;
1970
+ /** Result of a `get()` read, mirroring the input shape. */
1971
+ type TextureResult<Input extends TextureInput> = Input extends string ? Texture$1 | undefined : Input extends string[] ? (Texture$1 | undefined)[] : {
1972
+ [K in keyof Input]: Texture$1 | undefined;
2632
1973
  };
1974
+ /** Options for `dispose()`. */
1975
+ interface DisposeOptions {
1976
+ /** Dispose even if the texture still has active references (default false). */
1977
+ force?: boolean;
1978
+ }
2633
1979
  interface UseTexturesReturn {
2634
- /** Map of all textures currently in cache */
2635
- textures: Map<string, TextureEntry>;
2636
- /** Get a specific texture by key (usually URL) */
2637
- get: (key: string) => TextureEntry | undefined;
2638
- /** Check if a texture exists in cache */
2639
- has: (key: string) => boolean;
2640
- /** Add a texture to the cache */
2641
- add: (key: string, value: TextureEntry) => void;
2642
- /** Add multiple textures to the cache */
2643
- addMultiple: (items: Map<string, TextureEntry> | Record<string, TextureEntry>) => void;
2644
- /** Remove a texture from cache (does NOT dispose GPU resources) */
2645
- remove: (key: string) => void;
2646
- /** Remove multiple textures from cache */
2647
- removeMultiple: (keys: string[]) => void;
2648
- /** Dispose a texture's GPU resources and remove from cache */
2649
- dispose: (key: string) => void;
2650
- /** Dispose multiple textures */
2651
- disposeMultiple: (keys: string[]) => void;
2652
- /** Dispose ALL cached textures - use with caution */
2653
- disposeAll: () => void;
1980
+ /** The live registry Map (key → Texture). Treat as read-only. */
1981
+ readonly all: Map<string, Texture$1>;
1982
+ /** Read one texture, an array of textures, or a name→texture record (mirrors the input shape). */
1983
+ get<Input extends TextureInput>(input: Input): TextureResult<Input>;
1984
+ /** Check whether a key exists in the registry. */
1985
+ has(key: string): boolean;
1986
+ /**
1987
+ * Register a texture (or a record of textures) that has no URL — e.g. a render
1988
+ * target or procedural texture. URL-loaded textures are registered automatically
1989
+ * by `useTexture` (registry enrollment is on by default).
1990
+ */
1991
+ add(key: string, texture: Texture$1): void;
1992
+ add(record: Record<string, Texture$1>): void;
1993
+ /**
1994
+ * Dispose a texture's GPU resources and remove it from the registry.
1995
+ * Refcount-aware: if the key is still in use by a mounted `useTexture` consumer it is
1996
+ * skipped (with a warning) unless `{ force: true }` is passed.
1997
+ * @returns true if disposed, false if skipped.
1998
+ */
1999
+ dispose(key: string, options?: DisposeOptions): boolean;
2000
+ /** Dispose every texture in the registry and clear it. Use on scene teardown. */
2001
+ disposeAll(): void;
2654
2002
  }
2655
2003
  /**
2656
- * Hook for managing the global texture cache in R3F state.
2004
+ * Reactive Texture registry — load once with `useTexture`, reach the textures from anywhere.
2005
+ *
2006
+ * This is a registry of plain `Texture` objects (not TSL nodes), so the same texture can feed
2007
+ * a material map, a heightmap sampler, or anything else. It does **not** load — pair it with
2008
+ * `useTexture` for loading (registry enrollment is on by default); `useTextures` is for access and lifecycle.
2657
2009
  *
2658
- * Textures are stored in a Map with URL/path keys for efficient lookup.
2659
- * Useful for sharing texture references across materials and components.
2010
+ * The returned handle is **reactive**: the calling component re-renders when the registry
2011
+ * changes. Pass a selector to scope the subscription to a single read.
2660
2012
  *
2661
2013
  * @example
2662
2014
  * ```tsx
2663
- * const { textures, add, get, remove, has, dispose } = useTextures()
2015
+ * // Load + register once (anywhere in the tree) — registered by default
2016
+ * useTexture({ map: '/diffuse.jpg', normalMap: '/normal.jpg' })
2664
2017
  *
2665
- * // Check if texture is already cached
2666
- * if (!has('/textures/diffuse.png')) {
2667
- * // Load with useTexture and cache: true, or manually add
2668
- * const tex = useTexture('/textures/diffuse.png', { cache: true })
2669
- * }
2670
- *
2671
- * // Access cached texture from anywhere
2672
- * const diffuse = get('/textures/diffuse.png')
2673
- * if (diffuse) material.map = diffuse
2018
+ * // Reach them from another component — record form lands straight into a material
2019
+ * const { map, normalMap } = useTextures().get({ map: '/diffuse.jpg', normalMap: '/normal.jpg' })
2020
+ * return <meshStandardMaterial map={map} normalMap={normalMap} />
2674
2021
  *
2675
- * // Remove from cache only (texture still in GPU memory)
2676
- * remove('/textures/old.png')
2022
+ * // A set of heightmaps at once
2023
+ * const [a, b, c] = useTextures().get(['/h0.png', '/h1.png', '/h2.png'])
2677
2024
  *
2678
- * // Fully dispose (frees GPU memory + removes from cache)
2679
- * dispose('/textures/unused.png')
2025
+ * // Register a non-URL texture (render target / procedural)
2026
+ * useTextures().add('rt-main', renderTarget.texture)
2680
2027
  *
2681
- * // Nuclear option - dispose everything
2682
- * disposeAll()
2028
+ * // Deliberate GPU cleanup (refcount-aware; force to override)
2029
+ * useTextures().dispose('/diffuse.jpg')
2030
+ * useTextures().disposeAll() // scene teardown
2683
2031
  * ```
2032
+ *
2033
+ * @remarks
2034
+ * **Future expansion:** an imperative async loader (e.g. `await useTextures().load('/x.jpg')`) is
2035
+ * intentionally not included yet. It would let non-React code (loading screens, dynamic streaming)
2036
+ * populate the registry without Suspense, at the cost of putting loading back into this hook. It
2037
+ * will be added only if a concrete consumer needs imperative loading; for now, loading lives in
2038
+ * `useTexture`.
2684
2039
  */
2685
2040
  declare function useTextures(): UseTexturesReturn;
2041
+ declare function useTextures<T>(selector: (registry: UseTexturesReturn) => T): T;
2686
2042
 
2687
2043
  /**
2688
2044
  * Creates a render target compatible with the current renderer.
@@ -3890,11 +3246,6 @@ declare function flushSync<R>(fn: () => R): R;
3890
3246
  declare const context: React$1.Context<RootStore>;
3891
3247
  declare const createStore: (invalidate: (state?: RootState, frames?: number, stackFrames?: boolean) => void, advance: (timestamp: number, runGlobalEffects?: boolean, state?: RootState, frame?: XRFrame) => void) => RootStore;
3892
3248
 
3893
- /**
3894
- * Safely flush async effects when testing, simulating a legacy root.
3895
- * @deprecated Import from React instead. import { act } from 'react'
3896
- */
3897
- declare const act: typeof React$1.act;
3898
3249
  /**
3899
3250
  * An SSR-friendly useLayoutEffect.
3900
3251
  *
@@ -4378,5 +3729,5 @@ declare function isOnce(value: unknown): value is {
4378
3729
  */
4379
3730
  declare function Canvas(props: CanvasProps): react_jsx_runtime.JSX.Element;
4380
3731
 
4381
- 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 };
4382
- 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, 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, R3FRenderer, RaycastableRepresentation, ReactProps, ReconcilerRoot, RenderCallback, RenderProps, RenderTargetOptions, Renderer, RendererConfigExtended, RendererFactory, RendererProps, Root, RootOptions, 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 };
3732
+ 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, Texture, _roots, 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, 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 };
3733
+ export type { Act, 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, FrameNextCallback, FrameNextState, FrameState, Frameloop, GLProps, GLTFLike, GeometryProps, GeometryTransformProps, GlobalEffectType, GlobalRenderCallback, HostConfig, InferLoadResult, InjectState, InputLike, Instance, InstanceProps, 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, R3FRenderer, RaycastableRepresentation, ReactProps, ReconcilerRoot, RenderCallback, RenderProps, RenderTargetOptions, Renderer, RendererConfigExtended, RendererFactory, RendererProps, Root, RootState, RootStore, SetBlock, Size, StorageLike, StorageRecord, StorageStore, Subscription, TSLNodeInput, TextureInput, TextureResult, ThreeCamera, ThreeElement, ThreeElements, ThreeElementsImpl, ThreeEvent, ThreeExports, ThreeToJSXElements, UnblockProps, UseTextureOptions, UseTexturesReturn, Vector2, Vector3, Vector4, VectorRepresentation, Viewport, VisibilityEntry, WebGLDefaultProps, WebGLProps, WebGLShadowConfig, XRManager, XRPointerConfig };