@react-three/fiber 10.0.0-canary.aecbafb → 10.0.0-canary.b6c54f2

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/legacy.d.cts CHANGED
@@ -1,11 +1,13 @@
1
1
  import * as THREE$1 from 'three';
2
- import { WebGLRenderTarget, Color as Color$1, ColorRepresentation, Euler as Euler$1, Loader, RenderTargetOptions as RenderTargetOptions$1, Layers as Layers$1, Raycaster, Intersection as Intersection$1, BufferGeometry, Matrix4 as Matrix4$1, Quaternion as Quaternion$1, Node as Node$1, Vector2 as Vector2$1, Vector3 as Vector3$1, Vector4 as Vector4$1, Matrix3 as Matrix3$1, ColorSpace, Texture as Texture$1, CubeTexture, Scene, Object3D, Frustum, OrthographicCamera } from 'three';
2
+ import { WebGLCubeRenderTarget, WebGLRenderTarget, Color as Color$1, ColorRepresentation, Euler as Euler$1, Loader, RenderTargetOptions as RenderTargetOptions$1, Layers as Layers$1, Raycaster, Intersection as Intersection$1, BufferGeometry, Matrix4 as Matrix4$1, Quaternion as Quaternion$1, Node as Node$1, Vector2 as Vector2$1, Vector3 as Vector3$1, Vector4 as Vector4$1, Matrix3 as Matrix3$1, ColorSpace, Texture as Texture$1, CubeTexture, Scene, Object3D, Frustum, OrthographicCamera } from 'three';
3
3
  import * as React$1 from 'react';
4
4
  import { ReactNode, Component, RefObject, JSX } from 'react';
5
5
  import * as three_webgpu from 'three/webgpu';
6
6
  import { WebGPURenderer as WebGPURenderer$1, Node, StorageTexture, Data3DTexture, CanvasTarget, ShaderNodeObject } from 'three/webgpu';
7
7
  import { StoreApi } from 'zustand';
8
8
  import { UseBoundStoreWithEqualityFn } from 'zustand/traditional';
9
+ import { FrameTimingState, FrameCallback as FrameCallback$1, SchedulerApi, UseFrameNextOptions, FrameNextControls } from '@pmndrs/scheduler';
10
+ export { AddPhaseOptions, FrameControls, FrameNextControls, FrameTimingState, RootOptions, Scheduler, SchedulerApi, UseFrameNextOptions, UseFrameOptions, getScheduler } from '@pmndrs/scheduler';
9
11
  import { Options } from 'react-use-measure';
10
12
  import * as react_jsx_runtime from 'react/jsx-runtime';
11
13
  import { ThreeElement as ThreeElement$1, Euler as Euler$2 } from '@react-three/fiber';
@@ -46,8 +48,12 @@ declare const WebGPURenderer: {
46
48
 
47
49
  declare const RenderTarget: any;
48
50
 
51
+ declare const CubeRenderTarget: any;
52
+
49
53
  var THREE = /*#__PURE__*/_mergeNamespaces({
50
54
  __proto__: null,
55
+ CubeRenderTarget: CubeRenderTarget,
56
+ CubeRenderTargetCompat: WebGLCubeRenderTarget,
51
57
  Inspector: Inspector,
52
58
  R3F_BUILD_LEGACY: R3F_BUILD_LEGACY,
53
59
  R3F_BUILD_WEBGPU: R3F_BUILD_WEBGPU,
@@ -291,228 +297,33 @@ interface VisibilityEntry {
291
297
  }
292
298
 
293
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.
294
304
 
295
305
 
296
306
 
297
- // Public Options --------------------------------
298
-
299
- /**
300
- * Options for useFrame hook
301
- */
302
- interface UseFrameNextOptions {
303
- /** Optional stable id for the job. Auto-generated if not provided */
304
- id?: string
305
- /** Named phase to run in. Default: 'update' */
306
- phase?: string
307
- /** Run before this phase or job id */
308
- before?: string | string[]
309
- /** Run after this phase or job id */
310
- after?: string | string[]
311
- /** Priority within phase. Higher runs first. Default: 0 */
312
- priority?: number
313
- /** Max frames per second for this job */
314
- fps?: number
315
- /** If true, skip frames when behind. If false, try to catch up. Default: true */
316
- drop?: boolean
317
- /** Enable/disable without unregistering. Default: true */
318
- enabled?: boolean
319
- }
320
-
321
- /** Alias for UseFrameNextOptions */
322
- type UseFrameOptions = UseFrameNextOptions
323
-
324
- /**
325
- * Options for addPhase
326
- */
327
- interface AddPhaseOptions {
328
- /** Insert this phase before the specified phase */
329
- before?: string
330
- /** Insert this phase after the specified phase */
331
- after?: string
332
- }
333
-
334
- // Frame State --------------------------------
307
+ // Frame State (r3f-specific) --------------------------------
335
308
 
336
309
  /**
337
- * Timing-only state for independent/outside mode (no RootState)
338
- */
339
- interface FrameTimingState {
340
- /** High-resolution timestamp from RAF (ms) */
341
- time: number
342
- /** Time since last frame in seconds (for legacy compatibility with THREE.Clock) */
343
- delta: number
344
- /** Elapsed time since first frame in seconds (for legacy compatibility with THREE.Clock) */
345
- elapsed: number
346
- /** Incrementing frame counter */
347
- frame: number
348
- }
349
-
350
- /**
351
- * State passed to useFrame callbacks (extends RootState with timing)
310
+ * State passed to useFrame callbacks (extends RootState with timing).
352
311
  */
353
312
  interface FrameNextState extends RootState, FrameTimingState {}
354
313
 
355
314
  /** Alias for FrameNextState */
356
315
  type FrameState = FrameNextState
357
316
 
358
- // Root Options --------------------------------
317
+ // Callback Types (r3f-specific) --------------------------------
359
318
 
360
319
  /**
361
- * Options for registerRoot
320
+ * Callback function for useFrame. Receives the full r3f RootState plus timing.
362
321
  */
363
- interface RootOptions {
364
- /** State provider for callbacks. Optional in independent mode. */
365
- getState?: () => any
366
- /** Error handler for job errors. Falls back to console.error if not provided. */
367
- onError?: (error: Error) => void
368
- }
369
-
370
- // Callback Types --------------------------------
371
-
372
- /**
373
- * Callback function for useFrame
374
- */
375
- type FrameNextCallback = (state: FrameNextState, delta: number) => void
322
+ type FrameNextCallback = FrameCallback$1<RootState>
376
323
 
377
324
  /** Alias for FrameNextCallback */
378
325
  type FrameCallback = FrameNextCallback
379
326
 
380
- // Controls returned from useFrame --------------------------------
381
-
382
- /**
383
- * Controls object returned from useFrame hook
384
- */
385
- interface FrameNextControls {
386
- /** The job's unique ID */
387
- id: string
388
- /** Access to the global scheduler for frame loop control */
389
- scheduler: SchedulerApi
390
- /** Manually step this job only (bypasses FPS limiting) */
391
- step(timestamp?: number): void
392
- /** Manually step ALL jobs in the scheduler */
393
- stepAll(timestamp?: number): void
394
- /** Pause this job (set enabled=false) */
395
- pause(): void
396
- /** Resume this job (set enabled=true) */
397
- resume(): void
398
- /** Reactive paused state - automatically triggers re-render when changed */
399
- isPaused: boolean
400
- }
401
-
402
- /** Alias for FrameNextControls */
403
- type FrameControls = FrameNextControls
404
-
405
- // Scheduler Interface --------------------------------
406
-
407
- /**
408
- * Public interface for the global Scheduler
409
- */
410
- interface SchedulerApi {
411
- //* Phase Management --------------------------------
412
-
413
- /** Add a named phase to the scheduler */
414
- addPhase(name: string, options?: AddPhaseOptions): void
415
- /** Get the ordered list of phase names */
416
- readonly phases: string[]
417
- /** Check if a phase exists */
418
- hasPhase(name: string): boolean
419
-
420
- //* Root Management --------------------------------
421
-
422
- /** Register a root (Canvas) with the scheduler. Returns unsubscribe function. */
423
- registerRoot(id: string, options?: RootOptions): () => void
424
- /** Unregister a root */
425
- unregisterRoot(id: string): void
426
- /** Generate a unique root ID */
427
- generateRootId(): string
428
- /** Get the number of registered roots */
429
- getRootCount(): number
430
- /** Check if any root is registered and ready */
431
- readonly isReady: boolean
432
- /** Subscribe to root-ready event. Fires immediately if already ready. Returns unsubscribe. */
433
- onRootReady(callback: () => void): () => void
434
-
435
- //* Job Registration --------------------------------
436
-
437
- /** Register a job with the scheduler (returns unsubscribe function) */
438
- register(
439
- callback: FrameNextCallback,
440
- options?: {
441
- id?: string
442
- rootId?: string
443
- phase?: string
444
- before?: string | string[]
445
- after?: string | string[]
446
- priority?: number
447
- fps?: number
448
- drop?: boolean
449
- enabled?: boolean
450
- },
451
- ): () => void
452
- /** Update a job's options */
453
- updateJob(
454
- id: string,
455
- options: {
456
- priority?: number
457
- fps?: number
458
- drop?: boolean
459
- enabled?: boolean
460
- phase?: string
461
- before?: string | string[]
462
- after?: string | string[]
463
- },
464
- ): void
465
- /** Unregister a job by ID */
466
- unregister(id: string, rootId?: string): void
467
- /** Get the number of registered jobs */
468
- getJobCount(): number
469
- /** Get all job IDs */
470
- getJobIds(): string[]
471
-
472
- //* Global Jobs (for legacy addEffect/addAfterEffect) --------------------------------
473
-
474
- /** Register a global job (runs once per frame, not per-root). Returns unsubscribe function. */
475
- registerGlobal(phase: 'before' | 'after', id: string, callback: (timestamp: number) => void): () => void
476
-
477
- //* Idle Callbacks (for legacy addTail) --------------------------------
478
-
479
- /** Register an idle callback (fires when loop stops). Returns unsubscribe function. */
480
- onIdle(callback: (timestamp: number) => void): () => void
481
-
482
- //* Frame Loop Control --------------------------------
483
-
484
- /** Start the scheduler loop */
485
- start(): void
486
- /** Stop the scheduler loop */
487
- stop(): void
488
- /** Check if the scheduler is running */
489
- readonly isRunning: boolean
490
- /** Get/set the frameloop mode ('always', 'demand', 'never') */
491
- frameloop: Frameloop
492
- /** Independent mode - runs without Canvas, callbacks receive timing-only state */
493
- independent: boolean
494
-
495
- //* Manual Stepping --------------------------------
496
-
497
- /** Manually step all jobs once (for frameloop='never' or testing) */
498
- step(timestamp?: number): void
499
- /** Manually step a single job by ID */
500
- stepJob(id: string, timestamp?: number): void
501
- /** Request frame(s) to be rendered (for frameloop='demand') */
502
- invalidate(frames?: number): void
503
-
504
- //* Per-Job Control --------------------------------
505
-
506
- /** Check if a job is paused */
507
- isJobPaused(id: string): boolean
508
- /** Pause a job */
509
- pauseJob(id: string): void
510
- /** Resume a job */
511
- resumeJob(id: string): void
512
- /** Subscribe to job state changes (for reactive isPaused). Returns unsubscribe function. */
513
- subscribeJobState(id: string, listener: () => void): () => void
514
- }
515
-
516
327
  //* Buffer Types (useBuffers) ========================================
517
328
 
518
329
  /**
@@ -688,7 +499,7 @@ interface InternalState {
688
499
  canvasTarget?: CanvasTarget
689
500
  /**
690
501
  * Whether multi-canvas rendering is active.
691
- * True when any canvas uses `target` prop to share a renderer.
502
+ * True when any canvas uses `renderer={{ primaryCanvas: 'id' }}` to share a renderer.
692
503
  * When true, setCanvasTarget is called before each render.
693
504
  */
694
505
  isMultiCanvas?: boolean
@@ -786,8 +597,8 @@ interface RootState {
786
597
  setSize: (width?: number, height?: number, top?: number, left?: number) => void
787
598
  /** Shortcut to manual setting the pixel ratio */
788
599
  setDpr: (dpr: Dpr) => void
789
- /** Shortcut to setting frameloop flags */
790
- setFrameloop: (frameloop: Frameloop) => void
600
+ /** Shortcut to setting frameloop flags. No args resets to 'always'. */
601
+ setFrameloop: (frameloop?: Frameloop) => void
791
602
  /** Set error state to propagate to error boundary */
792
603
  setError: (error: Error | null) => void
793
604
  /** Current error state (null when no error) */
@@ -800,10 +611,12 @@ interface RootState {
800
611
  buffers: BufferStore
801
612
  /** Global GPU storage (textures, etc.) - root-level storage + scoped sub-objects. Use useGPUStorage() hook */
802
613
  gpuStorage: StorageStore
803
- /** Global TSL texture nodes - use useTextures() hook for operations */
804
- 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>
805
618
  /** WebGPU RenderPipeline instance - use useRenderPipeline() hook */
806
- renderPipeline: any | null // THREE.PostProcessing (will be THREE.RenderPipeline in future Three.js release)
619
+ renderPipeline: ThreeRenderPipeline | null
807
620
  /** Global TSL pass nodes for render pipeline - use useRenderPipeline() hook */
808
621
  passes: Record<string, any>
809
622
  /** Internal version counter for HMR - incremented by rebuildNodes/rebuildUniforms to bust memoization */
@@ -854,6 +667,20 @@ interface Renderer {
854
667
  render: (scene: THREE$1.Scene, camera: THREE$1.Camera) => any
855
668
  }
856
669
 
670
+ //* Color Management Config ==============================
671
+
672
+ /**
673
+ * Color management configuration shared by both WebGL and WebGPU renderers.
674
+ */
675
+ interface ColorManagementConfig {
676
+ /**
677
+ * Color space assigned to 8-bit input textures (color maps).
678
+ * Defaults to sRGB. Most textures are authored in sRGB.
679
+ * @default THREE.SRGBColorSpace
680
+ */
681
+ textureColorSpace?: THREE$1.ColorSpace
682
+ }
683
+
857
684
  //* WebGL Renderer Props ==============================
858
685
 
859
686
  type DefaultGLProps = Omit<THREE$1.WebGLRendererParameters, 'canvas'> & {
@@ -864,7 +691,7 @@ type GLProps =
864
691
  | Renderer
865
692
  | ((defaultProps: DefaultGLProps) => Renderer)
866
693
  | ((defaultProps: DefaultGLProps) => Promise<Renderer>)
867
- | Partial<Properties<THREE$1.WebGLRenderer> | THREE$1.WebGLRendererParameters>
694
+ | (Partial<Properties<THREE$1.WebGLRenderer> | THREE$1.WebGLRendererParameters> & ColorManagementConfig)
868
695
 
869
696
  //* WebGPU Renderer Props ==============================
870
697
 
@@ -890,9 +717,9 @@ interface CanvasSchedulerConfig {
890
717
  }
891
718
 
892
719
  /**
893
- * Extended renderer configuration for multi-canvas support.
720
+ * Extended renderer configuration for multi-canvas support and color management.
894
721
  */
895
- interface RendererConfigExtended {
722
+ interface RendererConfigExtended extends ColorManagementConfig {
896
723
  /** Share renderer from another canvas (WebGPU only) */
897
724
  primaryCanvas?: string
898
725
  /** Canvas-level scheduler options */
@@ -957,8 +784,6 @@ interface RenderProps<TCanvas extends HTMLCanvasElement | OffscreenCanvas$1> {
957
784
  * @see https://threejs.org/docs/#api/en/renderers/WebGLRenderer.shadowMap
958
785
  */
959
786
  shadows?: boolean | 'basic' | 'percentage' | 'soft' | 'variance' | Partial<THREE$1.WebGLShadowMap>
960
- /** Color space assigned to 8-bit input textures (color maps). Defaults to sRGB. Most textures are authored in sRGB. */
961
- textureColorSpace?: THREE$1.ColorSpace
962
787
  /** Creates an orthographic camera */
963
788
  orthographic?: boolean
964
789
  /**
@@ -1084,8 +909,6 @@ interface Instance<O = any> {
1084
909
  attach?: AttachType<O>
1085
910
  previousAttach?: any
1086
911
  isHidden: boolean
1087
- /** Deferred ref props to apply in commitMount */
1088
- deferredRefs?: Array<{ prop: string; ref: React$1.RefObject<any> }>
1089
912
  /** Set of props that have been applied via once() */
1090
913
  appliedOnce?: Set<string>
1091
914
  }
@@ -1211,7 +1034,7 @@ interface CanvasProps
1211
1034
  */
1212
1035
  resize?: Options
1213
1036
  /** The target where events are being subscribed to, default: the div that wraps canvas */
1214
- eventSource?: HTMLElement | React$1.RefObject<HTMLElement>
1037
+ eventSource?: HTMLElement | React$1.RefObject<HTMLElement | null>
1215
1038
  /** The event prefix that is cast into canvas pointer x/y events, default: "offset" */
1216
1039
  eventPrefix?: 'offset' | 'client' | 'page' | 'layer' | 'screen'
1217
1040
  /** Enable/disable automatic HMR refresh for TSL nodes and uniforms, default: true in dev */
@@ -1322,10 +1145,21 @@ type RenderTargetOptions = RenderTargetOptions$1
1322
1145
  //* Global Types ==============================
1323
1146
 
1324
1147
  declare global {
1325
- /** Uniform node type - a Node with a value property (matches Three.js UniformNode) */
1326
- interface UniformNode<T = unknown> extends Node {
1327
- value: T
1328
- }
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>
1329
1163
 
1330
1164
  /**
1331
1165
  * ShaderCallable - the return type of Fn()
@@ -1470,13 +1304,14 @@ declare module 'three/tsl' {
1470
1304
  ): ShaderCallable<R>
1471
1305
  }
1472
1306
 
1473
- /**
1474
- * RenderPipeline Types for useRenderPipeline hook (WebGPU only)
1475
- */
1476
-
1477
-
1478
-
1479
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
+
1480
1315
  /** Pass record - stores TSL pass nodes for render pipeline */
1481
1316
  type PassRecord = Record<string, any>
1482
1317
 
@@ -1491,7 +1326,7 @@ declare global {
1491
1326
  /** Current passes from state */
1492
1327
  passes: PassRecord
1493
1328
  /** RenderPipeline instance (null if not initialized) */
1494
- renderPipeline: any | null // THREE.PostProcessing (will be THREE.RenderPipeline in future Three.js release)
1329
+ renderPipeline: ThreeRenderPipeline | null
1495
1330
  /** Clear all passes from state */
1496
1331
  clearPasses: () => void
1497
1332
  /** Reset RenderPipeline entirely (clears PP + passes) */
@@ -1503,146 +1338,6 @@ declare global {
1503
1338
  }
1504
1339
  }
1505
1340
 
1506
- //* useFrameNext Types ==============================
1507
-
1508
-
1509
-
1510
- //* Global Type Declarations ==============================
1511
-
1512
- declare global {
1513
- // Job --------------------------------
1514
-
1515
- /**
1516
- * Internal job representation in the scheduler
1517
- */
1518
- interface Job {
1519
- /** Unique identifier */
1520
- id: string
1521
- /** The callback to execute */
1522
- callback: FrameNextCallback
1523
- /** Phase this job belongs to */
1524
- phase: string
1525
- /** Run before these phases/job ids */
1526
- before: Set<string>
1527
- /** Run after these phases/job ids */
1528
- after: Set<string>
1529
- /** Priority within phase (higher first) */
1530
- priority: number
1531
- /** Insertion order for deterministic tie-breaking */
1532
- index: number
1533
- /** Max FPS for this job (undefined = no limit) */
1534
- fps?: number
1535
- /** Drop frames when behind (true) or catch up (false) */
1536
- drop: boolean
1537
- /** Last run timestamp (ms) */
1538
- lastRun?: number
1539
- /** Whether job is enabled */
1540
- enabled: boolean
1541
- /** Internal flag: system jobs (like default render) don't block user render takeover */
1542
- system?: boolean
1543
- }
1544
-
1545
- // Phase Graph --------------------------------
1546
-
1547
- /**
1548
- * A node in the phase graph
1549
- */
1550
- interface PhaseNode {
1551
- /** Phase name */
1552
- name: string
1553
- /** Whether this was auto-generated from a before/after constraint */
1554
- isAutoGenerated: boolean
1555
- }
1556
-
1557
- /**
1558
- * Options for creating a job from hook options
1559
- */
1560
- interface JobOptions {
1561
- id?: string
1562
- phase?: string
1563
- before?: string | string[]
1564
- after?: string | string[]
1565
- priority?: number
1566
- fps?: number
1567
- drop?: boolean
1568
- enabled?: boolean
1569
- }
1570
-
1571
- // Frame Loop State --------------------------------
1572
-
1573
- /**
1574
- * Internal frame loop state
1575
- */
1576
- interface FrameLoopState {
1577
- /** Whether the loop is running */
1578
- running: boolean
1579
- /** Current RAF handle */
1580
- rafHandle: number | null
1581
- /** Last frame timestamp in ms (null = uninitialized) */
1582
- lastTime: number | null
1583
- /** Frame counter */
1584
- frameCount: number
1585
- /** Elapsed time since first frame in ms */
1586
- elapsedTime: number
1587
- /** createdAt timestamp in ms */
1588
- createdAt: number
1589
- }
1590
-
1591
- // Root Entry --------------------------------
1592
-
1593
- /**
1594
- * Internal representation of a registered root (Canvas).
1595
- * Tracks jobs and manages rebuild state for this root.
1596
- * @internal
1597
- */
1598
- interface RootEntry {
1599
- /** Unique identifier for this root */
1600
- id: string
1601
- /** Function to get the root's current state. Returns any to support independent mode. */
1602
- getState: () => any
1603
- /** Map of job IDs to Job objects */
1604
- jobs: Map<string, Job>
1605
- /** Cached sorted job list for execution order */
1606
- sortedJobs: Job[]
1607
- /** Whether sortedJobs needs rebuilding */
1608
- needsRebuild: boolean
1609
- }
1610
-
1611
- /**
1612
- * Internal representation of a global job (deprecated API).
1613
- * Global jobs run once per frame, not per-root.
1614
- * Used by legacy addEffect/addAfterEffect APIs.
1615
- * @internal
1616
- * @deprecated Use useFrame with phases instead
1617
- */
1618
- interface GlobalJob {
1619
- /** Unique identifier for this global job */
1620
- id: string
1621
- /** Callback invoked with RAF timestamp in ms */
1622
- callback: (timestamp: number) => void
1623
- }
1624
-
1625
- // HMR Support --------------------------------
1626
-
1627
- /**
1628
- * Hot Module Replacement data structure for preserving scheduler state
1629
- * @internal
1630
- */
1631
- interface HMRData {
1632
- /** Shared data object for storing values across reloads */
1633
- data: Record<string, any>
1634
- /** Optional function to accept HMR updates */
1635
- accept?: () => void
1636
- }
1637
-
1638
- // Default Phases --------------------------------
1639
-
1640
- /**
1641
- * Default phase names for the scheduler
1642
- */
1643
- type DefaultPhase = 'start' | 'input' | 'physics' | 'update' | 'render' | 'finish'
1644
- }
1645
-
1646
1341
  type MutableOrReadonlyParameters<T extends (...args: any) => any> = Parameters<T> | Readonly<Parameters<T>>
1647
1342
 
1648
1343
  interface MathRepresentation {
@@ -1812,7 +1507,7 @@ declare namespace three_d {
1812
1507
  * a single WebGPURenderer using Three.js CanvasTarget API.
1813
1508
  *
1814
1509
  * Primary canvas: Has `id` prop, creates its own renderer, registers here
1815
- * 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
1816
1511
  */
1817
1512
 
1818
1513
  interface PrimaryCanvasEntry {
@@ -1880,12 +1575,23 @@ type EnvironmentLoaderProps = {
1880
1575
  * const texture = useEnvironment({ preset: 'sunset' })
1881
1576
  * ```
1882
1577
  */
1883
- 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>;
1884
1579
  declare namespace useEnvironment {
1885
1580
  var preload: (preloadOptions?: EnvironmentLoaderPreloadOptions) => void;
1886
1581
  var clear: (clearOptions?: EnvironmentLoaderClearOptions) => void;
1887
1582
  }
1888
- 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'>;
1889
1595
  type EnvironmentLoaderClearOptions = Pick<EnvironmentLoaderProps, 'files' | 'preset'>;
1890
1596
 
1891
1597
  /**
@@ -2135,383 +1841,21 @@ declare function getLoader<L extends LoaderLike | ConstructorRepresentation<Load
2135
1841
  * Note: this hook's caller must be wrapped with `React.Suspense`
2136
1842
  * @see https://docs.pmnd.rs/react-three-fiber/api/hooks#useloader
2137
1843
  */
2138
- 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>;
2139
1845
  declare namespace useLoader {
2140
- var preload: <I extends InputLike, L extends LoaderLike | ConstructorRepresentation<LoaderLike>>(loader: L, input: I, extensions?: Extensions<L>, onProgress?: (event: ProgressEvent<EventTarget>) => void) => void;
2141
- 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;
2142
1848
  var loader: typeof getLoader;
2143
1849
  }
2144
1850
 
2145
- /**
2146
- * Global Singleton Scheduler - manages the frame loop and job execution for ALL R3F roots.
2147
- *
2148
- * Features:
2149
- * - Single RAF loop for entire application
2150
- * - Root registration (multiple Canvas support)
2151
- * - Global phases for addEffect/addAfterEffect (deprecated)
2152
- * - Per-root job management with phases, priorities, FPS throttling
2153
- * - onIdle callbacks for addTail (deprecated)
2154
- * - Demand mode support via invalidate()
2155
- */
2156
- declare class Scheduler {
2157
- private static readonly INSTANCE_KEY;
2158
- private static get instance();
2159
- private static set instance(value);
2160
- /**
2161
- * Get the global scheduler instance (creates if doesn't exist).
2162
- * Uses HMR data to preserve instance across hot reloads.
2163
- * @returns {Scheduler} The singleton scheduler instance
2164
- */
2165
- static get(): Scheduler;
2166
- /**
2167
- * Reset the singleton instance. Stops the loop and clears all state.
2168
- * Primarily used for testing to ensure clean state between tests.
2169
- * @returns {void}
2170
- */
2171
- static reset(): void;
2172
- private roots;
2173
- private phaseGraph;
2174
- private loopState;
2175
- private stoppedTime;
2176
- private nextRootIndex;
2177
- private globalBeforeJobs;
2178
- private globalAfterJobs;
2179
- private nextGlobalIndex;
2180
- private idleCallbacks;
2181
- private nextJobIndex;
2182
- private jobStateListeners;
2183
- private pendingFrames;
2184
- private _frameloop;
2185
- private _independent;
2186
- private errorHandler;
2187
- private rootReadyCallbacks;
2188
- get phases(): string[];
2189
- get frameloop(): Frameloop;
2190
- set frameloop(mode: Frameloop);
2191
- get isRunning(): boolean;
2192
- get isReady(): boolean;
2193
- get independent(): boolean;
2194
- set independent(value: boolean);
2195
- constructor();
2196
- /**
2197
- * Register a root (Canvas) with the scheduler.
2198
- * The first root to register starts the RAF loop (if frameloop='always').
2199
- * @param {string} id - Unique identifier for this root
2200
- * @param {RootOptions} [options] - Optional configuration with getState and onError callbacks
2201
- * @returns {() => void} Unsubscribe function to remove this root
2202
- */
2203
- registerRoot(id: string, options?: RootOptions): () => void;
2204
- /**
2205
- * Unregister a root from the scheduler.
2206
- * Cleans up all job state listeners for this root's jobs.
2207
- * The last root to unregister stops the RAF loop.
2208
- * @param {string} id - The root ID to unregister
2209
- * @returns {void}
2210
- */
2211
- unregisterRoot(id: string): void;
2212
- /**
2213
- * Subscribe to be notified when a root becomes available.
2214
- * Fires immediately if a root already exists.
2215
- * @param {() => void} callback - Function called when first root registers
2216
- * @returns {() => void} Unsubscribe function
2217
- */
2218
- onRootReady(callback: () => void): () => void;
2219
- /**
2220
- * Notify all registered root-ready callbacks.
2221
- * Called when the first root registers.
2222
- * @returns {void}
2223
- * @private
2224
- */
2225
- private notifyRootReady;
2226
- /**
2227
- * Ensure a default root exists for independent mode.
2228
- * Creates a minimal root with no state provider.
2229
- * @returns {void}
2230
- * @private
2231
- */
2232
- private ensureDefaultRoot;
2233
- /**
2234
- * Trigger error handling for job errors.
2235
- * Uses the bound error handler if available, otherwise logs to console.
2236
- * @param {Error} error - The error to handle
2237
- * @returns {void}
2238
- */
2239
- triggerError(error: Error): void;
2240
- /**
2241
- * Add a named phase to the scheduler's execution order.
2242
- * Marks all roots for rebuild to incorporate the new phase.
2243
- * @param {string} name - The phase name (e.g., 'physics', 'postprocess')
2244
- * @param {AddPhaseOptions} [options] - Positioning options (before/after other phases)
2245
- * @returns {void}
2246
- * @example
2247
- * scheduler.addPhase('physics', { before: 'update' });
2248
- * scheduler.addPhase('postprocess', { after: 'render' });
2249
- */
2250
- addPhase(name: string, options?: AddPhaseOptions): void;
2251
- /**
2252
- * Check if a phase exists in the scheduler.
2253
- * @param {string} name - The phase name to check
2254
- * @returns {boolean} True if the phase exists
2255
- */
2256
- hasPhase(name: string): boolean;
2257
- /**
2258
- * Register a global job that runs once per frame (not per-root).
2259
- * Used internally by deprecated addEffect/addAfterEffect APIs.
2260
- * @param {'before' | 'after'} phase - When to run: 'before' all roots or 'after' all roots
2261
- * @param {string} id - Unique identifier for this global job
2262
- * @param {(timestamp: number) => void} callback - Function called each frame with RAF timestamp
2263
- * @returns {() => void} Unsubscribe function to remove this global job
2264
- * @deprecated Use useFrame with phases instead
2265
- */
2266
- registerGlobal(phase: 'before' | 'after', id: string, callback: (timestamp: number) => void): () => void;
2267
- /**
2268
- * Register an idle callback that fires when the loop stops.
2269
- * Used internally by deprecated addTail API.
2270
- * @param {(timestamp: number) => void} callback - Function called when loop becomes idle
2271
- * @returns {() => void} Unsubscribe function to remove this idle callback
2272
- * @deprecated Use demand mode with invalidate() instead
2273
- */
2274
- onIdle(callback: (timestamp: number) => void): () => void;
2275
- /**
2276
- * Notify all registered idle callbacks.
2277
- * Called when the loop stops in demand mode.
2278
- * @param {number} timestamp - The RAF timestamp when idle occurred
2279
- * @returns {void}
2280
- * @private
2281
- */
2282
- private notifyIdle;
2283
- /**
2284
- * Register a job (frame callback) with a specific root.
2285
- * This is the core registration method used by useFrame internally.
2286
- * @param {FrameNextCallback} callback - The function to call each frame
2287
- * @param {JobOptions & { rootId?: string; system?: boolean }} [options] - Job configuration
2288
- * @param {string} [options.rootId] - Target root ID (defaults to first registered root)
2289
- * @param {string} [options.id] - Unique job ID (auto-generated if not provided)
2290
- * @param {string} [options.phase] - Execution phase (defaults to 'update')
2291
- * @param {number} [options.priority] - Priority within phase (higher = earlier, default 0)
2292
- * @param {number} [options.fps] - FPS throttle limit
2293
- * @param {boolean} [options.drop] - Drop frames when behind (default true)
2294
- * @param {boolean} [options.enabled] - Whether job is active (default true)
2295
- * @param {boolean} [options.system] - Internal flag for system jobs (not user-facing)
2296
- * @returns {() => void} Unsubscribe function to remove this job
2297
- */
2298
- register(callback: FrameNextCallback, options?: JobOptions & {
2299
- rootId?: string;
2300
- system?: boolean;
2301
- }): () => void;
2302
- /**
2303
- * Unregister a job by its ID.
2304
- * Searches all roots if rootId is not provided.
2305
- * @param {string} id - The job ID to unregister
2306
- * @param {string} [rootId] - Optional root ID to search (searches all if not provided)
2307
- * @returns {void}
2308
- */
2309
- unregister(id: string, rootId?: string): void;
2310
- /**
2311
- * Update a job's options dynamically.
2312
- * Searches all roots to find the job by ID.
2313
- * Phase/constraint changes trigger a rebuild of the sorted job list.
2314
- * @param {string} id - The job ID to update
2315
- * @param {Partial<JobOptions>} options - The options to update
2316
- * @returns {void}
2317
- */
2318
- updateJob(id: string, options: Partial<JobOptions>): void;
2319
- /**
2320
- * Check if a job is currently paused (disabled).
2321
- * @param {string} id - The job ID to check
2322
- * @returns {boolean} True if the job exists and is paused
2323
- */
2324
- isJobPaused(id: string): boolean;
2325
- /**
2326
- * Subscribe to state changes for a specific job.
2327
- * Listener is called when job is paused or resumed.
2328
- * @param {string} id - The job ID to subscribe to
2329
- * @param {() => void} listener - Callback invoked on state changes
2330
- * @returns {() => void} Unsubscribe function
2331
- */
2332
- subscribeJobState(id: string, listener: () => void): () => void;
2333
- /**
2334
- * Notify all listeners that a job's state has changed.
2335
- * @param {string} id - The job ID that changed
2336
- * @returns {void}
2337
- * @private
2338
- */
2339
- private notifyJobStateChange;
2340
- /**
2341
- * Pause a job by ID (sets enabled=false).
2342
- * Notifies any subscribed state listeners.
2343
- * @param {string} id - The job ID to pause
2344
- * @returns {void}
2345
- */
2346
- pauseJob(id: string): void;
2347
- /**
2348
- * Resume a paused job by ID (sets enabled=true).
2349
- * Resets job timing to prevent frame accumulation.
2350
- * Notifies any subscribed state listeners.
2351
- * @param {string} id - The job ID to resume
2352
- * @returns {void}
2353
- */
2354
- resumeJob(id: string): void;
2355
- /**
2356
- * Start the requestAnimationFrame loop.
2357
- * Resets timing state (elapsedTime, frameCount) on start.
2358
- * No-op if already running.
2359
- * @returns {void}
2360
- */
2361
- start(): void;
2362
- /**
2363
- * Stop the requestAnimationFrame loop.
2364
- * Cancels any pending RAF callback.
2365
- * No-op if not running.
2366
- * @returns {void}
2367
- */
2368
- stop(): void;
2369
- /**
2370
- * Request frames to be rendered in demand mode.
2371
- * Accumulates pending frames (capped at 60) and starts the loop if not running.
2372
- * No-op if frameloop is not 'demand'.
2373
- * @param {number} [frames=1] - Number of frames to request
2374
- * @param {boolean} [stackFrames=false] - Whether to add frames to existing pending count
2375
- * - `false` (default): Sets pending frames to the specified value (replaces existing count)
2376
- * - `true`: Adds frames to existing pending count (useful for accumulating invalidations)
2377
- * @returns {void}
2378
- * @example
2379
- * // Request a single frame render
2380
- * scheduler.invalidate();
2381
- *
2382
- * @example
2383
- * // Request 5 frames (e.g., for animations)
2384
- * scheduler.invalidate(5);
2385
- *
2386
- * @example
2387
- * // Set pending frames to exactly 3 (don't stack with existing)
2388
- * scheduler.invalidate(3, false);
2389
- *
2390
- * @example
2391
- * // Add 2 more frames to existing pending count
2392
- * scheduler.invalidate(2, true);
2393
- */
2394
- invalidate(frames?: number, stackFrames?: boolean): void;
2395
- /**
2396
- * Reset timing state for deterministic testing.
2397
- * Preserves jobs and roots but resets lastTime, frameCount, elapsedTime, etc.
2398
- * @returns {void}
2399
- */
2400
- resetTiming(): void;
2401
- /**
2402
- * Manually execute a single frame for all roots.
2403
- * Useful for frameloop='never' mode or testing scenarios.
2404
- * @param {number} [timestamp] - Optional timestamp (defaults to performance.now())
2405
- * @returns {void}
2406
- * @example
2407
- * // Manual control mode
2408
- * scheduler.frameloop = 'never';
2409
- * scheduler.step(); // Execute one frame
2410
- */
2411
- step(timestamp?: number): void;
2412
- /**
2413
- * Manually execute a single job by its ID.
2414
- * Useful for testing individual job callbacks in isolation.
2415
- * @param {string} id - The job ID to step
2416
- * @param {number} [timestamp] - Optional timestamp (defaults to performance.now())
2417
- * @returns {void}
2418
- */
2419
- stepJob(id: string, timestamp?: number): void;
2420
- /**
2421
- * Main RAF loop callback.
2422
- * Executes frame, handles demand mode, and schedules next frame.
2423
- * @param {number} timestamp - RAF timestamp in milliseconds
2424
- * @returns {void}
2425
- * @private
2426
- */
2427
- private loop;
2428
- /**
2429
- * Execute a single frame across all roots.
2430
- * Order: globalBefore → each root's jobs → globalAfter
2431
- * @param {number} timestamp - RAF timestamp in milliseconds
2432
- * @returns {void}
2433
- * @private
2434
- */
2435
- private executeFrame;
2436
- /**
2437
- * Run all global jobs from a job map.
2438
- * Catches and logs errors without stopping execution.
2439
- * @param {Map<string, GlobalJob>} jobs - The global jobs map to execute
2440
- * @param {number} timestamp - RAF timestamp in milliseconds
2441
- * @returns {void}
2442
- * @private
2443
- */
2444
- private runGlobalJobs;
2445
- /**
2446
- * Execute all jobs for a single root in sorted order.
2447
- * Rebuilds sorted job list if needed, then dispatches each job.
2448
- * Errors are caught and propagated via triggerError.
2449
- * @param {RootEntry} root - The root entry to tick
2450
- * @param {number} timestamp - RAF timestamp in milliseconds
2451
- * @param {number} delta - Time since last frame in seconds
2452
- * @returns {void}
2453
- * @private
2454
- */
2455
- private tickRoot;
2456
- /**
2457
- * Get the total number of registered jobs across all roots.
2458
- * Includes both per-root jobs and global before/after jobs.
2459
- * @returns {number} Total job count
2460
- */
2461
- getJobCount(): number;
2462
- /**
2463
- * Get all registered job IDs across all roots.
2464
- * Includes both per-root jobs and global before/after jobs.
2465
- * @returns {string[]} Array of all job IDs
2466
- */
2467
- getJobIds(): string[];
2468
- /**
2469
- * Get the number of registered roots (Canvas instances).
2470
- * @returns {number} Number of registered roots
2471
- */
2472
- getRootCount(): number;
2473
- /**
2474
- * Check if any user (non-system) jobs are registered in a specific phase.
2475
- * Used by the default render job to know if a user has taken over rendering.
2476
- *
2477
- * @param phase The phase to check
2478
- * @param rootId Optional root ID to check (checks all roots if not provided)
2479
- * @returns true if any user jobs exist in the phase
2480
- */
2481
- hasUserJobsInPhase(phase: string, rootId?: string): boolean;
2482
- /**
2483
- * Generate a unique root ID for automatic root registration.
2484
- * @returns {string} A unique root ID in the format 'root_N'
2485
- */
2486
- generateRootId(): string;
2487
- /**
2488
- * Generate a unique job ID.
2489
- * @returns {string} A unique job ID in the format 'job_N'
2490
- * @private
2491
- */
2492
- private generateJobId;
2493
- /**
2494
- * Normalize before/after constraints to a Set.
2495
- * Handles undefined, single string, or array inputs.
2496
- * @param {string | string[] | undefined} value - The constraint value(s)
2497
- * @returns {Set<string>} Normalized Set of constraint strings
2498
- * @private
2499
- */
2500
- private normalizeConstraints;
2501
- }
2502
- /**
2503
- * Get the global scheduler instance.
2504
- * Creates one if it doesn't exist.
2505
- */
2506
- declare const getScheduler: () => Scheduler;
2507
-
2508
1851
  /**
2509
1852
  * Frame hook with phase-based ordering, priority, and FPS throttling.
2510
1853
  *
2511
- * Works both inside and outside Canvas context:
2512
- * - Inside Canvas: Full RootState (gl, scene, camera, etc.)
2513
- * - Outside Canvas (waiting mode): Waits for Canvas to mount, then gets full state
2514
- * - 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.
2515
1859
  *
2516
1860
  * Returns a controls object for manual stepping, pausing, and resuming.
2517
1861
  *
@@ -2528,16 +1872,16 @@ declare const getScheduler: () => Scheduler;
2528
1872
  * useFrame((state, delta) => { ... }, { phase: 'physics' })
2529
1873
  *
2530
1874
  * @example
2531
- * // Outside Canvas - waits for Canvas to mount
1875
+ * // Outside Canvas - callback waits for a Canvas, then always has full state
2532
1876
  * function UI() {
2533
1877
  * useFrame((state, delta) => { syncUI(state.camera) });
2534
1878
  * return <button>...</button>;
2535
1879
  * }
2536
1880
  *
2537
1881
  * @example
2538
- * // Independent mode - no Canvas needed
2539
- * getScheduler().independent = true;
2540
- * 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) })
2541
1885
  *
2542
1886
  * @example
2543
1887
  * // Scheduler-only access (no callback)
@@ -2560,11 +1904,16 @@ type UseTextureOptions<Url extends string[] | string | Record<string, string>> =
2560
1904
  /** Callback when texture(s) finish loading */
2561
1905
  onLoad?: (texture: MappedTextureType<Url>) => void;
2562
1906
  /**
2563
- * Cache the texture in R3F's global state for access via useTextures().
2564
- * When true:
1907
+ * Register the texture(s) in R3F's global texture registry for access via useTextures().
1908
+ * When true (the default):
2565
1909
  * - Textures persist until explicitly disposed
2566
- * - Returns existing cached textures if available (preserving modifications like colorSpace)
2567
- * @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
2568
1917
  */
2569
1918
  cache?: boolean;
2570
1919
  };
@@ -2588,15 +1937,18 @@ type UseTextureOptions<Url extends string[] | string | Record<string, string>> =
2588
1937
  * normal: '/normal.png'
2589
1938
  * })
2590
1939
  *
2591
- * // With caching - returns same texture object across components
2592
- * // Modifications (colorSpace, wrapS, etc.) are preserved
2593
- * 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')
2594
1943
  * diffuse.colorSpace = THREE.SRGBColorSpace
2595
1944
  *
2596
1945
  * // Another component gets the SAME texture with colorSpace already set
2597
- * const sameDiffuse = useTexture('/diffuse.png', { cache: true })
1946
+ * const sameDiffuse = useTexture('/diffuse.png')
2598
1947
  *
2599
- * // Access cache directly
1948
+ * // Opt out of registry enrollment for a one-off texture
1949
+ * const scratch = useTexture('/scratch.png', { cache: false })
1950
+ *
1951
+ * // Access the registry directly
2600
1952
  * const { get } = useTextures()
2601
1953
  * const cached = get('/diffuse.png')
2602
1954
  * ```
@@ -2613,63 +1965,80 @@ declare const Texture: ({ children, input, onLoad, cache, }: {
2613
1965
  cache?: boolean;
2614
1966
  }) => react_jsx_runtime.JSX.Element;
2615
1967
 
2616
- type TextureEntry = Texture$1 | {
2617
- value: Texture$1;
2618
- [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;
2619
1973
  };
1974
+ /** Options for `dispose()`. */
1975
+ interface DisposeOptions {
1976
+ /** Dispose even if the texture still has active references (default false). */
1977
+ force?: boolean;
1978
+ }
2620
1979
  interface UseTexturesReturn {
2621
- /** Map of all textures currently in cache */
2622
- textures: Map<string, TextureEntry>;
2623
- /** Get a specific texture by key (usually URL) */
2624
- get: (key: string) => TextureEntry | undefined;
2625
- /** Check if a texture exists in cache */
2626
- has: (key: string) => boolean;
2627
- /** Add a texture to the cache */
2628
- add: (key: string, value: TextureEntry) => void;
2629
- /** Add multiple textures to the cache */
2630
- addMultiple: (items: Map<string, TextureEntry> | Record<string, TextureEntry>) => void;
2631
- /** Remove a texture from cache (does NOT dispose GPU resources) */
2632
- remove: (key: string) => void;
2633
- /** Remove multiple textures from cache */
2634
- removeMultiple: (keys: string[]) => void;
2635
- /** Dispose a texture's GPU resources and remove from cache */
2636
- dispose: (key: string) => void;
2637
- /** Dispose multiple textures */
2638
- disposeMultiple: (keys: string[]) => void;
2639
- /** Dispose ALL cached textures - use with caution */
2640
- 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;
2641
2002
  }
2642
2003
  /**
2643
- * 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.
2644
2009
  *
2645
- * Textures are stored in a Map with URL/path keys for efficient lookup.
2646
- * 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.
2647
2012
  *
2648
2013
  * @example
2649
2014
  * ```tsx
2650
- * const { textures, add, get, remove, has, dispose } = useTextures()
2651
- *
2652
- * // Check if texture is already cached
2653
- * if (!has('/textures/diffuse.png')) {
2654
- * // Load with useTexture and cache: true, or manually add
2655
- * const tex = useTexture('/textures/diffuse.png', { cache: true })
2656
- * }
2015
+ * // Load + register once (anywhere in the tree) — registered by default
2016
+ * useTexture({ map: '/diffuse.jpg', normalMap: '/normal.jpg' })
2657
2017
  *
2658
- * // Access cached texture from anywhere
2659
- * const diffuse = get('/textures/diffuse.png')
2660
- * 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} />
2661
2021
  *
2662
- * // Remove from cache only (texture still in GPU memory)
2663
- * remove('/textures/old.png')
2022
+ * // A set of heightmaps at once
2023
+ * const [a, b, c] = useTextures().get(['/h0.png', '/h1.png', '/h2.png'])
2664
2024
  *
2665
- * // Fully dispose (frees GPU memory + removes from cache)
2666
- * dispose('/textures/unused.png')
2025
+ * // Register a non-URL texture (render target / procedural)
2026
+ * useTextures().add('rt-main', renderTarget.texture)
2667
2027
  *
2668
- * // Nuclear option - dispose everything
2669
- * disposeAll()
2028
+ * // Deliberate GPU cleanup (refcount-aware; force to override)
2029
+ * useTextures().dispose('/diffuse.jpg')
2030
+ * useTextures().disposeAll() // scene teardown
2670
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`.
2671
2039
  */
2672
2040
  declare function useTextures(): UseTexturesReturn;
2041
+ declare function useTextures<T>(selector: (registry: UseTexturesReturn) => T): T;
2673
2042
 
2674
2043
  /**
2675
2044
  * Creates a render target compatible with the current renderer.
@@ -4365,5 +3734,5 @@ declare function isOnce(value: unknown): value is {
4365
3734
  */
4366
3735
  declare function Canvas(props: CanvasProps): react_jsx_runtime.JSX.Element;
4367
3736
 
4368
- 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 };
4369
- export type { Act, AddPhaseOptions, Args, ArgsProp, AttachFnType, AttachType, BackgroundConfig, BackgroundProp, BaseRendererProps, Bridge, BufferLike, BufferRecord, BufferStore, Camera, CameraProps, CanvasProps, CanvasSchedulerConfig, Catalogue, Color, ComputeFunction, ConstructorRepresentation, DefaultGLProps, DefaultRendererProps, Disposable, DomEvent, Dpr, ElementProps, EnvironmentLoaderProps, EnvironmentProps, EquConfig, Euler, EventHandlers, EventManager, EventProps, Events, Extensions, FiberRoot, FilterFunction, FrameCallback, FrameControls, FrameNextCallback, FrameNextControls, FrameNextState, FrameState, FrameTimingState, Frameloop, GLProps, GLTFLike, GeometryProps, GeometryTransformProps, GlobalEffectType, GlobalRenderCallback, HostConfig, InferLoadResult, InjectState, InputLike, Instance, InstanceProps, LegacyInternalState as InternalState, Intersection, IntersectionEvent, IsAllOptional, IsOptional, Layers, LegacyInternalState, LegacyRenderer, LegacyRootState, LoaderInstance, LoaderLike, LoaderResult, MappedTextureType, MathProps, MathRepresentation, MathType, MathTypes, Matrix3, Matrix4, Mutable, MutableOrReadonlyParameters, NodeProps, NonFunctionKeys, ObjectMap, OffscreenCanvas$1 as OffscreenCanvas, Overwrite, Performance, PointerCaptureTarget, PointerState, PresetsType, PrimaryCanvasEntry, Properties, Quaternion, LegacyRenderer as R3FRenderer, RaycastableRepresentation, ReactProps, ReconcilerRoot, RenderCallback, RenderProps, RenderTargetOptions, Renderer, RendererConfigExtended, RendererFactory, RendererProps, Root, RootOptions, LegacyRootState as RootState, RootStore, SchedulerApi, SetBlock, Size, StorageLike, StorageRecord, StorageStore, Subscription, TSLNodeInput, TextureEntry, ThreeCamera, ThreeElement, ThreeElements, ThreeElementsImpl, ThreeEvent, ThreeExports, ThreeToJSXElements, UnblockProps, UseFrameNextOptions, UseFrameOptions, UseTextureOptions, UseTexturesReturn, Vector2, Vector3, Vector4, VectorRepresentation, Viewport, VisibilityEntry, WebGLDefaultProps, WebGLProps, WebGLShadowConfig, XRManager, XRPointerConfig };
3737
+ 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, 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, 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 };
3738
+ 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, LegacyInternalState as InternalState, Intersection, IntersectionEvent, IsAllOptional, IsOptional, Layers, LegacyInternalState, LegacyRenderer, LegacyRootState, LoaderInstance, LoaderLike, LoaderResult, MappedTextureType, MathProps, MathRepresentation, MathType, MathTypes, Matrix3, Matrix4, Mutable, MutableOrReadonlyParameters, NodeProps, NonFunctionKeys, ObjectMap, OffscreenCanvas$1 as OffscreenCanvas, Overwrite, Performance, PointerCaptureTarget, PointerState, PresetsType, PrimaryCanvasEntry, Properties, Quaternion, LegacyRenderer as R3FRenderer, RaycastableRepresentation, ReactProps, ReconcilerRoot, RenderCallback, RenderProps, RenderTargetOptions, Renderer, RendererConfigExtended, RendererFactory, RendererProps, Root, LegacyRootState as 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 };