@react-three/fiber 10.0.0-canary.ac30da2 → 10.0.0-canary.af75fd4

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.cjs CHANGED
@@ -925,7 +925,7 @@ const createStore = (invalidate, advance) => {
925
925
  size: newSize,
926
926
  viewport: { ...s.viewport, ...getCurrentViewport(state2.camera, defaultTarget, newSize) }
927
927
  }));
928
- scheduler.getScheduler().invalidate();
928
+ get().invalidate();
929
929
  }
930
930
  }
931
931
  return;
@@ -940,15 +940,16 @@ const createStore = (invalidate, advance) => {
940
940
  viewport: { ...s.viewport, ...getCurrentViewport(state2.camera, defaultTarget, size) },
941
941
  _sizeImperative: true
942
942
  }));
943
- scheduler.getScheduler().invalidate();
943
+ get().invalidate();
944
944
  },
945
945
  setDpr: (dpr) => set((state2) => {
946
946
  const resolved = calculateDpr(dpr);
947
947
  return { viewport: { ...state2.viewport, dpr: resolved, initialDpr: state2.viewport.initialDpr || resolved } };
948
948
  }),
949
949
  setFrameloop: (frameloop = "always") => {
950
+ const rootId = get().internal.rootId;
951
+ if (rootId) scheduler.getScheduler().setRootFrameloop(rootId, frameloop);
950
952
  set(() => ({ frameloop }));
951
- scheduler.getScheduler().frameloop = frameloop;
952
953
  },
953
954
  setError: (error) => set(() => ({ error })),
954
955
  error: null,
@@ -1067,7 +1068,8 @@ const createStore = (invalidate, advance) => {
1067
1068
  const resizeTarget = canvasTarget ?? actualRenderer;
1068
1069
  if (viewport.dpr > 0) resizeTarget.setPixelRatio(viewport.dpr);
1069
1070
  resizeTarget.setSize(size.width, size.height, false);
1070
- internal.canvasTargetSizeDirty = true;
1071
+ const activeTarget = actualRenderer.getCanvasTarget?.();
1072
+ if (!canvasTarget || activeTarget !== canvasTarget) internal.canvasTargetSizeDirty = true;
1071
1073
  }
1072
1074
  if (camera !== oldCamera) {
1073
1075
  oldCamera = camera;
@@ -1253,6 +1255,13 @@ function useFrame(callback, priorityOrOptions) {
1253
1255
  * Use for controlling the entire frame loop, adding phases, etc.
1254
1256
  */
1255
1257
  scheduler: scheduler2,
1258
+ /**
1259
+ * The root that currently owns this job. Resolve on access because ambient
1260
+ * jobs can be adopted by a Canvas after the controls object is created.
1261
+ */
1262
+ get rootId() {
1263
+ return scheduler.getScheduler().getJobRootId(id);
1264
+ },
1256
1265
  /**
1257
1266
  * Manually step this job only.
1258
1267
  * Bypasses FPS limiting - always runs.
@@ -1269,6 +1278,14 @@ function useFrame(callback, priorityOrOptions) {
1269
1278
  stepAll: (timestamp) => {
1270
1279
  scheduler.getScheduler().step(timestamp);
1271
1280
  },
1281
+ /**
1282
+ * Request frames for this job's owning root without waking sibling roots.
1283
+ */
1284
+ invalidate: (frames, stackFrames) => {
1285
+ const scheduler3 = scheduler.getScheduler();
1286
+ const rootId = scheduler3.getJobRootId(id);
1287
+ if (rootId) scheduler3.invalidateRoot(rootId, frames, stackFrames);
1288
+ },
1272
1289
  /**
1273
1290
  * Pause this job (set enabled=false).
1274
1291
  * Job remains registered but won't run.
@@ -1688,13 +1705,19 @@ function addTail(callback) {
1688
1705
  return scheduler.getScheduler().onIdle(callback);
1689
1706
  }
1690
1707
  function invalidate(state, frames = 1, stackFrames = false) {
1691
- scheduler.getScheduler().invalidate(frames, stackFrames);
1708
+ const rootId = state?.internal?.rootId;
1709
+ const scheduler$1 = scheduler.getScheduler();
1710
+ if (rootId) scheduler$1.invalidateRoot(rootId, frames, stackFrames);
1711
+ else scheduler$1.invalidate(frames, stackFrames);
1692
1712
  }
1693
- function advance(timestamp) {
1694
- scheduler.getScheduler().step(timestamp);
1713
+ function advance(timestamp, runGlobalEffects, state) {
1714
+ const rootId = state?.internal?.rootId;
1715
+ const scheduler$1 = scheduler.getScheduler();
1716
+ if (rootId) scheduler$1.stepRoot(rootId, timestamp);
1717
+ else scheduler$1.step(timestamp);
1695
1718
  }
1696
1719
 
1697
- const version = "10.0.0-alpha.3";
1720
+ const version = "10.0.0-alpha.4";
1698
1721
  const packageData = {
1699
1722
  version: version};
1700
1723
 
@@ -14228,9 +14251,8 @@ function createRoot(canvas) {
14228
14251
  if (!renderer.hasInitialized?.()) {
14229
14252
  const size2 = computeInitialSize(canvas, propsSize);
14230
14253
  if (size2.width > 0 && size2.height > 0) {
14231
- const pixelRatio = calculateDpr(dpr);
14232
- canvas.width = size2.width * pixelRatio;
14233
- canvas.height = size2.height * pixelRatio;
14254
+ renderer.setPixelRatio(calculateDpr(dpr));
14255
+ renderer.setSize(size2.width, size2.height, false);
14234
14256
  }
14235
14257
  await renderer.init();
14236
14258
  }
@@ -14239,7 +14261,7 @@ function createRoot(canvas) {
14239
14261
  state.internal.actualRenderer = renderer;
14240
14262
  state.set({ webGPUSupported: isWebGPUBackend, renderer, primaryStore: store });
14241
14263
  if (canvasId && !state.internal.isSecondary) {
14242
- const canvasTarget = new webgpu.CanvasTarget(canvas);
14264
+ const canvasTarget = renderer.getCanvasTarget?.();
14243
14265
  const unregisterPrimary = registerPrimary(canvasId, renderer, store);
14244
14266
  state.set((prev) => ({
14245
14267
  internal: {
@@ -14353,7 +14375,7 @@ function createRoot(canvas) {
14353
14375
  const handleXRFrame = (timestamp, _frame) => {
14354
14376
  const state2 = store.getState();
14355
14377
  if (state2.frameloop === "never") return;
14356
- advance(timestamp);
14378
+ advance(timestamp, true, state2);
14357
14379
  };
14358
14380
  const actualRenderer = state.internal.actualRenderer;
14359
14381
  const handleSessionChange = () => {
@@ -14361,7 +14383,7 @@ function createRoot(canvas) {
14361
14383
  const renderer2 = state2.internal.actualRenderer;
14362
14384
  actualRenderer.xr.enabled = actualRenderer.xr.isPresenting;
14363
14385
  renderer2.xr.setAnimationLoop(renderer2.xr.isPresenting ? handleXRFrame : null);
14364
- if (!renderer2.xr.isPresenting) invalidate();
14386
+ if (!renderer2.xr.isPresenting) invalidate(state2);
14365
14387
  };
14366
14388
  const xr = {
14367
14389
  connect() {
@@ -14443,14 +14465,19 @@ function createRoot(canvas) {
14443
14465
  const newRootId = canvasId || scheduler$1.generateRootId();
14444
14466
  const unregisterRoot = scheduler$1.registerRoot(newRootId, {
14445
14467
  getState: () => store.getState(),
14446
- onError: (err) => store.getState().setError(err)
14468
+ onError: (err) => store.getState().setError(err),
14469
+ frameloop: store.getState().frameloop,
14470
+ before: schedulerConfig?.before,
14471
+ after: schedulerConfig?.after,
14472
+ order: schedulerConfig?.order
14447
14473
  });
14448
14474
  const unregisterCanvasTarget = scheduler$1.register(
14449
14475
  () => {
14450
14476
  const state2 = store.getState();
14451
- if (state2.internal.isMultiCanvas && state2.internal.canvasTarget) {
14477
+ const canvasTarget = state2.internal.canvasTarget;
14478
+ if (canvasTarget) {
14452
14479
  const renderer2 = state2.internal.actualRenderer;
14453
- renderer2.setCanvasTarget(state2.internal.canvasTarget);
14480
+ if (renderer2.getCanvasTarget() !== canvasTarget) renderer2.setCanvasTarget(canvasTarget);
14454
14481
  if (state2.internal.canvasTargetSizeDirty) {
14455
14482
  state2.internal.canvasTargetSizeDirty = false;
14456
14483
  renderer2.backend?.updateSize?.();
@@ -14523,8 +14550,7 @@ function createRoot(canvas) {
14523
14550
  phase: "render",
14524
14551
  system: true,
14525
14552
  // Internal flag: this is a system job, not user-controlled
14526
- // Apply scheduler config for render ordering and rate limiting
14527
- ...schedulerConfig?.after && { after: schedulerConfig.after },
14553
+ // FPS throttles only the default render job; Canvas ordering belongs to the root.
14528
14554
  ...schedulerConfig?.fps && { fps: schedulerConfig.fps }
14529
14555
  }
14530
14556
  );
@@ -14543,8 +14569,21 @@ function createRoot(canvas) {
14543
14569
  scheduler: scheduler$1
14544
14570
  }
14545
14571
  }));
14572
+ } else {
14573
+ const constraintsChanged = !is.equ(schedulerConfig?.before, lastConfiguredProps.schedulerBefore, shallowLoose) || !is.equ(schedulerConfig?.after, lastConfiguredProps.schedulerAfter, shallowLoose);
14574
+ if (constraintsChanged) {
14575
+ scheduler$1.setRootConstraints(rootId, {
14576
+ before: schedulerConfig?.before,
14577
+ after: schedulerConfig?.after
14578
+ });
14579
+ }
14580
+ if (schedulerConfig?.order !== lastConfiguredProps.schedulerOrder) {
14581
+ scheduler$1.setRootOrder(rootId, schedulerConfig?.order ?? 0);
14582
+ }
14546
14583
  }
14547
- scheduler$1.frameloop = frameloop;
14584
+ lastConfiguredProps.schedulerBefore = schedulerConfig?.before;
14585
+ lastConfiguredProps.schedulerAfter = schedulerConfig?.after;
14586
+ lastConfiguredProps.schedulerOrder = schedulerConfig?.order;
14548
14587
  onCreated = onCreatedCallback;
14549
14588
  configured = true;
14550
14589
  resolve();
@@ -14586,18 +14625,23 @@ function unmountComponentAtNode(canvas, callback) {
14586
14625
  const fiber = root?.fiber;
14587
14626
  if (fiber) {
14588
14627
  const state = root?.store.getState();
14589
- if (state) state.internal.active = false;
14628
+ if (state) {
14629
+ state.internal.active = false;
14630
+ const unregisterRoot = state.internal.unregisterRoot;
14631
+ if (unregisterRoot) {
14632
+ unregisterRoot();
14633
+ state.internal.unregisterRoot = void 0;
14634
+ }
14635
+ }
14590
14636
  reconciler.updateContainer(null, fiber, null, () => {
14591
14637
  if (state) {
14592
14638
  setTimeout(() => {
14593
14639
  try {
14594
14640
  const renderer = state.internal.actualRenderer;
14595
- const unregisterRoot = state.internal.unregisterRoot;
14596
- if (unregisterRoot) unregisterRoot();
14597
14641
  const unregisterPrimary = state.internal.unregisterPrimary;
14598
14642
  if (unregisterPrimary) unregisterPrimary();
14599
14643
  const canvasTarget = state.internal.canvasTarget;
14600
- if (canvasTarget?.dispose) canvasTarget.dispose();
14644
+ if (state.internal.isSecondary && canvasTarget?.dispose) canvasTarget.dispose();
14601
14645
  state.events.disconnect?.();
14602
14646
  cleanupHelperGroup(root.store);
14603
14647
  if (state.isLegacy && renderer) {
@@ -15041,9 +15085,9 @@ function CanvasImpl({
15041
15085
  React__namespace.useMemo(() => extend(THREE), []);
15042
15086
  const Bridge = useBridge();
15043
15087
  const backgroundProps = React__namespace.useMemo(() => parseBackground(background), [background]);
15044
- const hasInitialSizeRef = React__namespace.useRef(false);
15088
+ const [hasInitialSize, setHasInitialSize] = React__namespace.useState(false);
15045
15089
  const measureConfig = React__namespace.useMemo(() => {
15046
- if (!hasInitialSizeRef.current) {
15090
+ if (!hasInitialSize) {
15047
15091
  return {
15048
15092
  ...resize,
15049
15093
  scroll: resize?.scroll ?? true,
@@ -15055,7 +15099,7 @@ function CanvasImpl({
15055
15099
  debounce: { scroll: 50, resize: 0 },
15056
15100
  ...resize
15057
15101
  };
15058
- }, [resize, hasInitialSizeRef.current]);
15102
+ }, [hasInitialSize, resize]);
15059
15103
  const [containerRef, containerRect] = useMeasure__default(measureConfig);
15060
15104
  const effectiveSize = React__namespace.useMemo(() => {
15061
15105
  let w = width ?? containerRect.width;
@@ -15071,9 +15115,7 @@ function CanvasImpl({
15071
15115
  left: containerRect.left
15072
15116
  };
15073
15117
  }, [width, height, containerRect, forceEven]);
15074
- if (!hasInitialSizeRef.current && effectiveSize.width > 0 && effectiveSize.height > 0) {
15075
- hasInitialSizeRef.current = true;
15076
- }
15118
+ if (!hasInitialSize && effectiveSize.width > 0 && effectiveSize.height > 0) setHasInitialSize(true);
15077
15119
  const canvasRef = React__namespace.useRef(null);
15078
15120
  const divRef = React__namespace.useRef(null);
15079
15121
  React__namespace.useImperativeHandle(ref, () => canvasRef.current);
package/dist/index.d.cts CHANGED
@@ -363,6 +363,33 @@ type BufferRecord = Record<string, BufferLike>
363
363
  */
364
364
  type BufferStore = Record<string, BufferLike | BufferRecord>
365
365
 
366
+ //* Node Types (useNodes) ========================================
367
+
368
+ /**
369
+ * Structural shape of a TSL node as stored on `state.nodes`.
370
+ *
371
+ * Deliberately minimal rather than three's nominal `Node`: in @types/three several node classes
372
+ * TSL hands back (OperatorNode, ConstNode, ...) do not extend `Node` cleanly, so a `Node` bound
373
+ * would reject values `useNodes` creators legitimately return. This is the same shape
374
+ * `useNodes` already constrains creators to (`TSLNodeLike`).
375
+ */
376
+ interface NodeLike {
377
+ uuid?: string
378
+ nodeType?: string | null
379
+ /** label method for chaining - sets the node's label and returns self */
380
+ label?: ((label: string) => NodeLike) | string
381
+ setName?: (name: string) => this
382
+ }
383
+
384
+ /** Flat record of TSL nodes (no nested scopes) */
385
+ type NodeRecord = Record<string, NodeLike>
386
+
387
+ /**
388
+ * Node store that can contain both root-level nodes and scoped node objects.
389
+ * Structure: { wobble: OperatorNode, fx: { blur: ShaderCallable } }
390
+ */
391
+ type NodeStore = Record<string, NodeLike | NodeRecord>
392
+
366
393
  //* Storage Types (useGPUStorage) ========================================
367
394
 
368
395
  /**
@@ -496,8 +523,13 @@ interface InternalState {
496
523
  /** Container for child attachment (scene for root, original container for portals) */
497
524
  container?: THREE$1.Object3D
498
525
  /**
499
- * CanvasTarget for multi-canvas WebGPU rendering.
500
- * Created for all WebGPU canvases to support renderer sharing.
526
+ * The CanvasTarget this root sizes and renders through.
527
+ *
528
+ * A primary (`<Canvas id>`) owns the renderer's default target -- the one three itself built
529
+ * around the canvas element -- so sizing it is sizing the renderer. A secondary owns a target
530
+ * R3F created for its own element. Either way there is exactly one target per canvas element,
531
+ * and the canvas-target job makes it the renderer's active one before this root renders.
532
+ * Absent on WebGL and on an id-less WebGPU canvas, where the renderer is sized directly.
501
533
  * @see https://threejs.org/docs/#api/en/renderers/common/CanvasTarget
502
534
  */
503
535
  canvasTarget?: CanvasTarget
@@ -622,7 +654,7 @@ interface RootState {
622
654
  /** Global TSL uniform nodes - root-level uniforms + scoped sub-objects. Use useUniforms() hook */
623
655
  uniforms: UniformStore
624
656
  /** Global TSL nodes - root-level nodes + scoped sub-objects. Use useNodes() hook */
625
- nodes: Record<string, any>
657
+ nodes: NodeStore
626
658
  /** Global TSL buffer nodes - root-level buffers + scoped sub-objects. Use useBuffers() hook */
627
659
  buffers: BufferStore
628
660
  /** Global GPU storage (textures, etc.) - root-level storage + scoped sub-objects. Use useGPUStorage() hook */
@@ -634,7 +666,7 @@ interface RootState {
634
666
  /** WebGPU RenderPipeline instance - use useRenderPipeline() hook */
635
667
  renderPipeline: ThreeRenderPipeline | null
636
668
  /** Global TSL pass nodes for render pipeline - use useRenderPipeline() hook */
637
- passes: Record<string, any>
669
+ passes: PassRecord
638
670
  /** Internal version counter for HMR - incremented by rebuildNodes/rebuildUniforms to bust memoization */
639
671
  _hmrVersion: number
640
672
  /** Internal: whether setSize() has taken ownership of canvas dimensions */
@@ -722,12 +754,19 @@ type DefaultRendererProps = {
722
754
  */
723
755
  interface CanvasSchedulerConfig {
724
756
  /**
725
- * Render this canvas after another canvas completes.
726
- * Pass the `id` of another canvas.
757
+ * Run this Canvas root before the referenced Canvas root id(s).
727
758
  */
728
- after?: string
759
+ before?: string | string[]
729
760
  /**
730
- * Limit this canvas's render rate (frames per second).
761
+ * Run this Canvas root after the referenced Canvas root id(s).
762
+ */
763
+ after?: string | string[]
764
+ /**
765
+ * Numeric root order. Lower values run first.
766
+ */
767
+ order?: number
768
+ /**
769
+ * Limit this Canvas's default render job (frames per second).
731
770
  */
732
771
  fps?: number
733
772
  }
@@ -1175,7 +1214,33 @@ declare global {
1175
1214
  * ergonomics. The result is three's structural type, so members stay in sync with the
1176
1215
  * installed three instead of needing to be mirrored by hand.
1177
1216
  */
1178
- type UniformNode<T = unknown> = three_webgpu.UniformNode<unknown, T>
1217
+ type UniformNode<T = unknown> = three_webgpu.UniformNode<UniformNodeTypeFor<T>, T>
1218
+
1219
+ /**
1220
+ * three's node type name for a uniform value type, mirroring the `uniform()` overloads.
1221
+ * A `UniformNode<number>` is a `Node<'float'>`, so TSL math (`.mul`, `.add`, ...) accepts it.
1222
+ * Unknown or unlisted value types resolve to `unknown`, which TSL math rejects: narrow with
1223
+ * `as UniformNode<number>` (or the matching value type) at the call site.
1224
+ */
1225
+ type UniformNodeTypeFor<T> = T extends number
1226
+ ? 'float'
1227
+ : T extends boolean
1228
+ ? 'bool'
1229
+ : T extends three_webgpu.Color
1230
+ ? 'color'
1231
+ : T extends three_webgpu.Vector2
1232
+ ? 'vec2'
1233
+ : T extends three_webgpu.Vector3
1234
+ ? 'vec3'
1235
+ : T extends three_webgpu.Vector4
1236
+ ? 'vec4'
1237
+ : T extends three_webgpu.Matrix2
1238
+ ? 'mat2'
1239
+ : T extends three_webgpu.Matrix3
1240
+ ? 'mat3'
1241
+ : T extends three_webgpu.Matrix4
1242
+ ? 'mat4'
1243
+ : unknown
1179
1244
 
1180
1245
  /**
1181
1246
  * ShaderCallable - the return type of Fn()
@@ -1328,30 +1393,97 @@ declare global {
1328
1393
  */
1329
1394
  type ThreeRenderPipeline = three_webgpu.RenderPipeline
1330
1395
 
1331
- /** Pass record - stores TSL pass nodes for render pipeline */
1332
- type PassRecord = Record<string, any>
1396
+ /**
1397
+ * The pass `useRenderPipeline` creates for you: three's own `PassNode`, as returned by
1398
+ * `pass(scene, camera)` from `three/tsl`. Referenced from three so members like
1399
+ * `getTextureNode`, `setMRT` and `dispose` track the installed version.
1400
+ */
1401
+ type ScenePassNode = three_webgpu.PassNode
1402
+
1403
+ /**
1404
+ * Pass record - stores TSL pass nodes for render pipeline.
1405
+ *
1406
+ * `scenePass` is the only key the library owns. It is optional here because this is also the
1407
+ * shape of `state.passes`, which is `{}` before the pipeline exists and again after `reset()`
1408
+ * or `clearPasses()`. Inside the callbacks it is always present; see
1409
+ * {@link RenderPipelineCallbackState}.
1410
+ *
1411
+ * Every other key is user-registered, via a callback's return value. Those are TSL nodes of
1412
+ * any kind, not only passes: texture reads of an MRT attachment, effect nodes, extra
1413
+ * `pass()` instances. `Node` is the common base, so that is the bound. Narrow at the call
1414
+ * site when you need a member, e.g. `passes.velocity as TextureNode`.
1415
+ */
1416
+ interface PassRecord {
1417
+ scenePass?: ScenePassNode
1418
+ [key: string]: three_webgpu.Node
1419
+ }
1420
+
1421
+ /**
1422
+ * State passed to pipeline callbacks after the active pipeline has been created.
1423
+ *
1424
+ * `passes.scenePass` is required here: the hook installs the default scene pass before either
1425
+ * callback runs, so callbacks can use it without a guard or a cast.
1426
+ *
1427
+ * `renderer` is narrowed to `WebGPURenderer` and `isLegacy` to `false`: the hook throws under
1428
+ * the legacy renderer before either callback can run, so a callback never sees WebGL.
1429
+ */
1430
+ type RenderPipelineCallbackState = RootState & {
1431
+ renderPipeline: ThreeRenderPipeline
1432
+ passes: PassRecord & { scenePass: ScenePassNode }
1433
+ renderer: three_webgpu.WebGPURenderer
1434
+ isLegacy: false
1435
+ }
1436
+
1437
+ /**
1438
+ * What a callback may return to register entries into `state.passes`.
1439
+ *
1440
+ * `scenePass` is reserved. The hook owns that entry and its lifecycle: it caches the pass it
1441
+ * created, and `rebuild()` / `reset()` dispose that cached pass. A callback overwriting the
1442
+ * store entry would leave the store pointing at a node the hook never disposes, and the hook
1443
+ * disposing a pass nothing references. So returning it is a type error.
1444
+ */
1445
+ type RegisteredPasses = Record<string, three_webgpu.Node> & { scenePass?: never }
1333
1446
 
1334
1447
  /** Setup callback - runs first to configure MRT, create additional passes */
1335
- type RenderPipelineSetupCallback = (state: RootState) => PassRecord | void
1448
+ type RenderPipelineSetupCallback = (state: RenderPipelineCallbackState) => RegisteredPasses | void
1336
1449
 
1337
1450
  /** Main callback - runs second to configure outputNode, create effect passes */
1338
- type RenderPipelineMainCallback = (state: RootState) => PassRecord | void
1451
+ type RenderPipelineMainCallback = (state: RenderPipelineCallbackState) => RegisteredPasses | void
1339
1452
 
1340
- /** Return type for useRenderPipeline hook */
1341
- interface UseRenderPipelineReturn {
1453
+ /** The imperative half of useRenderPipeline's return value, present in every state */
1454
+ interface UseRenderPipelineActions {
1342
1455
  /** Current passes from state */
1343
1456
  passes: PassRecord
1344
- /** RenderPipeline instance (null if not initialized) */
1345
- renderPipeline: ThreeRenderPipeline | null
1346
1457
  /** Clear all passes from state */
1347
1458
  clearPasses: () => void
1348
1459
  /** Reset RenderPipeline entirely (clears PP + passes) */
1349
1460
  reset: () => void
1350
1461
  /** Re-run setup/main callbacks with current closure values */
1351
1462
  rebuild: () => void
1352
- /** True when RenderPipeline is configured and ready */
1353
- isReady: boolean
1354
1463
  }
1464
+
1465
+ /**
1466
+ * Return type for useRenderPipeline hook, discriminated on `isReady`.
1467
+ *
1468
+ * `if (isReady)` narrows `renderPipeline` to non-null, which is what the docs already tell
1469
+ * callers to check. `passes.scenePass` deliberately stays optional in the ready branch:
1470
+ * `clearPasses()` empties the record while leaving the pipeline in place.
1471
+ */
1472
+ type UseRenderPipelineReturn = UseRenderPipelineActions &
1473
+ (
1474
+ | {
1475
+ /** True when RenderPipeline is configured and ready */
1476
+ isReady: true
1477
+ /** RenderPipeline instance */
1478
+ renderPipeline: ThreeRenderPipeline
1479
+ }
1480
+ | {
1481
+ /** False until the pipeline has been created */
1482
+ isReady: false
1483
+ /** Not initialized yet, or torn down by reset() */
1484
+ renderPipeline: null
1485
+ }
1486
+ )
1355
1487
  }
1356
1488
 
1357
1489
  type MutableOrReadonlyParameters<T extends (...args: any) => any> = Parameters<T> | Readonly<Parameters<T>>
@@ -1895,7 +2027,7 @@ declare namespace useLoader {
1895
2027
  *
1896
2028
  * @param callback - Function called each frame with (state, delta). Optional if you only need scheduler access.
1897
2029
  * @param priorityOrOptions - Either a priority number (backwards compat) or options object
1898
- * @returns Controls object with step(), stepAll(), pause(), resume(), isPaused, id, scheduler
2030
+ * @returns Controls object with step(), stepAll(), invalidate(), pause(), resume(), isPaused, id, rootId, scheduler
1899
2031
  *
1900
2032
  * @example
1901
2033
  * // Simple priority (backwards compat)
@@ -2191,7 +2323,10 @@ declare function addTail(callback: GlobalRenderCallback): () => void;
2191
2323
  * Invalidates the view, requesting a frame to be rendered.
2192
2324
  * In demand mode, this triggers the scheduler to run frames.
2193
2325
  *
2194
- * @param state - Optional root state (ignored in new scheduler, kept for backwards compat)
2326
+ * With a state argument, only that root's jobs run on the requested frames; other
2327
+ * roots on 'demand' stay idle. Without one, every registered root is invalidated.
2328
+ *
2329
+ * @param state - Optional root state; targets the invalidation at that root
2195
2330
  * @param frames - Number of frames to request (default: 1)
2196
2331
  * @param stackFrames - If false, sets pendingFrames to frames. If true, adds to existing pendingFrames (default: false)
2197
2332
  *
@@ -2202,14 +2337,16 @@ declare function invalidate(state?: RootState, frames?: number, stackFrames?: bo
2202
2337
  * Advances the frameloop and runs render effects.
2203
2338
  * Useful for when manually rendering via `frameloop="never"`.
2204
2339
  *
2340
+ * With a state argument, only that root is stepped. Without one, every
2341
+ * registered root is stepped for backwards compatibility.
2342
+ *
2205
2343
  * @param timestamp - The timestamp to use for this frame
2206
2344
  * @param runGlobalEffects - Ignored (kept for backwards compat, global effects always run)
2207
- * @param state - Ignored (kept for backwards compat)
2208
- * @param frame - Ignored (kept for backwards compat)
2345
+ * @param state - Optional root state; targets the manual step at that root
2209
2346
  *
2210
2347
  * @see https://docs.pmnd.rs/react-three-fiber/api/additional-exports#advance
2211
2348
  */
2212
- declare function advance(timestamp: number): void;
2349
+ declare function advance(timestamp: number, runGlobalEffects?: boolean, state?: RootState): void;
2213
2350
 
2214
2351
  /* eslint-disable @definitelytyped/no-unnecessary-generics */
2215
2352
  declare function ReactReconciler<
@@ -3764,4 +3901,4 @@ declare function isOnce(value: unknown): value is {
3764
3901
  declare function Canvas(props: CanvasProps): react_jsx_runtime.JSX.Element;
3765
3902
 
3766
3903
  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, swapInteractivity, unmountComponentAtNode, unregisterPrimary, updateCamera, updateFrustum, useBridge, useEnvironment, useFrame, useGraph, useInstanceHandle, useIsomorphicLayoutEffect, useLoader, useMutableCallback, useRenderTarget, useStore, useTexture, useTextures, useThree, waitForPrimary };
3767
- 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 };
3904
+ 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, NodeLike, NodeProps, NodeRecord, NodeStore, 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 };