@react-three/tsl 10.0.0-canary.bf4b0be → 10.0.0-canary.d0fe0de

package/dist/index.d.ts

@@ -149,6 +149,16 @@ declare global {
   /** Node type accepted by broad dynamic node-store readers. */
   type TSLNodeType = three_webgpu.Node | CallableTSLNode
 
+  /**
+   * What TSL's constant constructors return: `int(1)`, `vec2(0, 1)`, `color('red')` and friends
+   * wrap a ConstNode in a VarNode. three's `uniform()` unwraps exactly this shape to
+   * `UniformNode<TNodeType, TValue>`, and so do the mappings below.
+   */
+  type TSLConstNode<TNodeType, TValue> = three_webgpu.VarNode<
+    TNodeType,
+    three_webgpu.ConstNode<TNodeType, TValue>
+  >
+
   /**
    * Derive Three's shader node type from an existing node or a supported raw input.
    * Existing InputNode generics take precedence over structural value normalization.
@@ -159,44 +169,48 @@ declare global {
     ? TNodeType
     : T extends three_webgpu.InputNode<infer TNodeType, infer _TValue>
       ? TNodeType
-      : T extends number
-        ? 'float'
-        : T extends boolean
-          ? 'bool'
-          : T extends string | three_webgpu.Color | { r: number; g: number; b: number }
-            ? 'color'
-            : T extends three_webgpu.Vector4 | { x: number; y: number; z: number; w: number }
-              ? 'vec4'
-              : T extends three_webgpu.Vector3 | { x: number; y: number; z: number }
-                ? 'vec3'
-                : T extends three_webgpu.Vector2 | { x: number; y: number }
-                  ? 'vec2'
-                  : T extends three_webgpu.Matrix4
-                    ? 'mat4'
-                    : T extends three_webgpu.Matrix3
-                      ? 'mat3'
-                      : T extends three_webgpu.Matrix2
-                        ? 'mat2'
-                        : unknown
+      : T extends TSLConstNode<infer TNodeType, infer _TValue>
+        ? TNodeType
+        : T extends number
+          ? 'float'
+          : T extends boolean
+            ? 'bool'
+            : T extends string | three_webgpu.Color | { r: number; g: number; b: number }
+              ? 'color'
+              : T extends three_webgpu.Vector4 | { x: number; y: number; z: number; w: number }
+                ? 'vec4'
+                : T extends three_webgpu.Vector3 | { x: number; y: number; z: number }
+                  ? 'vec3'
+                  : T extends three_webgpu.Vector2 | { x: number; y: number }
+                    ? 'vec2'
+                    : T extends three_webgpu.Matrix4
+                      ? 'mat4'
+                      : T extends three_webgpu.Matrix3
+                        ? 'mat3'
+                        : T extends three_webgpu.Matrix2
+                          ? 'mat2'
+                          : unknown
 
   /** Derive the normalized JavaScript value stored by a uniform node. */
   type UniformNodeValue<T> = T extends three_webgpu.UniformNode<infer _TNodeType, infer TValue>
     ? TValue
     : T extends three_webgpu.InputNode<infer _TNodeType, infer TValue>
       ? TValue
-      : T extends string | { r: number; g: number; b: number }
-        ? three_webgpu.Color
-        : T extends { x: number; y: number; z: number; w: number }
-          ? three_webgpu.Vector4
-          : T extends { x: number; y: number; z: number }
-            ? three_webgpu.Vector3
-            : T extends { x: number; y: number }
-              ? three_webgpu.Vector2
-              : T extends number
-                ? number
-                : T extends boolean
-                  ? boolean
-                  : T
+      : T extends TSLConstNode<infer _TNodeType, infer TValue>
+        ? TValue
+        : T extends string | { r: number; g: number; b: number }
+          ? three_webgpu.Color
+          : T extends { x: number; y: number; z: number; w: number }
+            ? three_webgpu.Vector4
+            : T extends { x: number; y: number; z: number }
+              ? three_webgpu.Vector3
+              : T extends { x: number; y: number }
+                ? three_webgpu.Vector2
+                : T extends number
+                  ? number
+                  : T extends boolean
+                    ? boolean
+                    : T
 
   /** Three's exact UniformNode with shader and value generics derived from an input. */
   type UniformNodeFor<T> = three_webgpu.UniformNode<UniformNodeType<T>, UniformNodeValue<T>>
@@ -381,10 +395,17 @@ type ResourceLeafGuard<T> = (value: unknown) => value is T;
  *
  * @example
  * ```tsx
+ * // With uniforms registered (see `Register` and the Typed Uniforms guide), reads are typed by name
  * useLocalNodes(({ uniforms }) => ({
- *   wobble: sin(uniforms.uTime.mul(2)),           // No cast needed!
- *   playerHealth: uniforms.scope('player').uHealth // Explicit scope access
- * }))
+ *   wobble: sin(uniforms.uTime.mul(2)),
+ *   playerHealth: uniforms.scope('player').uHealth, // or uniforms.player.uHealth
+ * }), [])
+ *
+ * // Without registration, give a scope its schema
+ * useLocalNodes(({ uniforms }) => {
+ *   const player = uniforms.scope<{ uHealth: UniformNode<'float', number> }>('player')
+ *   return { damage: player.uHealth.mul(2) }
+ * }, [])
  * ```
  */
 
@@ -619,32 +640,81 @@ declare function rebuildAllNodes(store: ReturnType<typeof useStore>, scope?: str
 /** Creator receives CreatorState with ScopedStore wrappers for type-safe access. Returns any record. */
 type LocalNodeCreator<T extends Record<string, unknown>> = (state: CreatorState) => T;
 /**
- * Creates local values that rebuild when uniforms, nodes, or textures change.
+ * The install step an install-form creator returns: it runs after commit (as a layout effect) and
+ * may return a cleanup, which runs before the next install and on unmount.
+ */
+type LocalNodeInstall = () => void | (() => void);
+/** A creator that builds during render and returns an install step instead of a record. */
+type LocalNodeInstaller = (state: CreatorState) => LocalNodeInstall;
+/**
+ * Creates component-local values from the rendering context and the shared TSL resources.
+ *
+ * Unlike `useNodes`, this does NOT register to the global store — nothing is published during
+ * render or commit. The creator runs in the render phase and is pure computation.
+ *
+ * **When the creator re-runs** is controlled by the optional `deps` array, mirroring `useMemo`:
  *
- * Unlike `useNodes`, this does NOT register to the global store.
- * Use for component-specific nodes/values that depend on shared resources.
+ * | Call                             | Ordinary component renders                                  |
+ * | -------------------------------- | ----------------------------------------------------------- |
+ * | `useLocalNodes(creator)`         | Re-evaluate every render, even with a `useCallback` creator |
+ * | `useLocalNodes(creator, [])`     | Reuse the result                                            |
+ * | `useLocalNodes(creator, [a, b])` | Reuse until a declared dependency changes by `Object.is`    |
+ *
+ * Independently of `deps`, three things re-run the creator: a change to a shared resource the
+ * creator READ (replaced, removed, or appearing where it read nothing), a change of the owning
+ * (primary) store, and an HMR / `rebuild*` invalidation. Registrations the creator did not read
+ * change nothing, and writing `.value` on a uniform it read is not a change. `[]` therefore means
+ * "no JavaScript construction inputs", not "never rebuild". Whenever it re-runs, the creator from
+ * the CURRENT render is used; creator identity itself is never a rebuild trigger once an array is
+ * supplied.
+ *
+ * Only reads the creator makes before it returns are tracked. Inside `Fn(() => …)` the body runs
+ * later, while three builds the shader, so read the resource in the creator and close over it.
+ *
+ * `[]` is the normal case. A value that changes (a color prop, a slider) belongs in a uniform: the
+ * graph references the `UniformNode`, so updating its `.value` needs no rebuild and must not be a
+ * dependency. Declare only inputs that decide the graph's structure and cannot be uniforms: which
+ * node to use, a loop count, whether a branch exists.
+ *
+ * **Install form.** To put a node onto a Three object (`scene.fogNode`, `scene.backgroundNode`),
+ * return a function instead of a record. The creator still builds during render; the returned
+ * function runs after commit and may return a cleanup, which runs before the next install and on
+ * unmount. Mutating a Three object inside the creator itself is unsafe: React can discard a
+ * render, and StrictMode renders twice. The hook returns nothing in this form.
+ *
+ * ```tsx
+ * useLocalNodes(({ scene, uniforms }) => {
+ *   const fogNode = fog(uniforms.fogColor, rangeFogFactor(uniforms.near, uniforms.far))
+ *   return () => {
+ *     scene.fogNode = fogNode
+ *     return () => { scene.fogNode = null }
+ *   }
+ * }, [])
+ * ```
  *
  * @example
  * ```tsx
- * // Destructure what you need from state
+ * // Resource-driven composition: no surrounding JS inputs. `uniforms.uTime` is typed when the
+ * // app registers its uniforms (see `Register`); otherwise give a scope its schema or cast.
  * const { wobble, uTime } = useLocalNodes(({ uniforms, nodes }) => ({
  *   wobble: sin(uniforms.uTime.mul(2)),
- *   uTime: uniforms.uTime,  // can return uniforms too
- * }))
+ *   uTime: uniforms.uTime, // can return uniforms too
+ * }), [])
  *
- * // Or access anything else from RootState
- * const { scaled } = useLocalNodes(({ camera, nodes }) => ({
- *   scaled: nodes.basePos.mul(camera.zoom),
- * }))
+ * // `pattern` picks which node the graph is built from: a structural input.
+ * const { result } = useLocalNodes(({ nodes }) => ({
+ *   result: pattern === 'noise' ? nodes.noise : nodes.stripes,
+ * }), [pattern])
  *
- * // Type-safe uniform access
+ * // An unregistered uniform, cast to its type
  * const { colorNode } = useLocalNodes(({ uniforms }) => {
- *   const uValue = uniforms.myUniform as UniformNode<number>
+ *   const uValue = uniforms.myUniform as UniformNode<'float', number>
  *   return { colorNode: mix(colorA, colorB, uValue) }
- * })
+ * }, [])
  * ```
  */
-declare function useLocalNodes<T extends Record<string, unknown>>(creator: LocalNodeCreator<T>): T;
+declare function useLocalNodes(creator: LocalNodeInstaller, deps?: React.DependencyList): void;
+declare function useLocalNodes<T extends Record<string, unknown>>(creator: LocalNodeCreator<T>, deps?: React.DependencyList): T;
 
 /**
  * A record of buffer-like values - allows mixed types (TypedArrays, BufferAttributes, TSL nodes)
@@ -774,4 +844,4 @@ declare function rebuildAllStorage(store: ReturnType<typeof useStore>, scope?: s
 declare function useRenderPipeline(mainCB?: RenderPipelineMainCallback, setupCB?: RenderPipelineSetupCallback): UseRenderPipelineReturn;
 
 export { configureTSL, createScopedStore, rebuildAllBuffers, rebuildAllNodes, rebuildAllStorage, rebuildAllUniforms, useBuffers, useGPUStorage, useLocalNodes, useNodes, useRenderPipeline, useUniform, useUniforms };
-export type { AppUniforms, BufferCreator, BufferLike, BufferRecord, BufferStore, BuffersWithUtils, ClearBuffersFn, ClearNodesFn, ClearStorageFn, ClearUniformsFn, CreatorState, DisposeBuffersFn, DisposeStorageFn, LocalNodeCreator, NodeCreator, NodeLike, NodeRecord, NodeStore, NodesWithUtils, RebuildBuffersFn, RebuildNodesFn, RebuildStorageFn, RebuildUniformsFn, Register, RegisteredScopeUniforms, RegisteredScopes, RegisteredUniform, RegisteredUniforms, RemoveBuffersFn, RemoveNodesFn, RemoveStorageFn, RemoveUniformsFn, RootUniformInput, ScopeUniformInput, ScopedStoreType, StorageCreator, StorageLike, StorageRecord, StorageStore, StorageWithUtils, TSLConfig, TSLNode, TSLNodeLike, TSLRootState, UniformCreator, UniformValue, UniformsWithUtils };
+export type { AppUniforms, BufferCreator, BufferLike, BufferRecord, BufferStore, BuffersWithUtils, ClearBuffersFn, ClearNodesFn, ClearStorageFn, ClearUniformsFn, CreatorState, DisposeBuffersFn, DisposeStorageFn, LocalNodeCreator, LocalNodeInstall, LocalNodeInstaller, NodeCreator, NodeLike, NodeRecord, NodeStore, NodesWithUtils, RebuildBuffersFn, RebuildNodesFn, RebuildStorageFn, RebuildUniformsFn, Register, RegisteredScopeUniforms, RegisteredScopes, RegisteredUniform, RegisteredUniforms, RemoveBuffersFn, RemoveNodesFn, RemoveStorageFn, RemoveUniformsFn, RootUniformInput, ScopeUniformInput, ScopedStoreType, StorageCreator, StorageLike, StorageRecord, StorageStore, StorageWithUtils, TSLConfig, TSLNode, TSLNodeLike, TSLRootState, UniformCreator, UniformValue, UniformsWithUtils };