@react-three/tsl 10.0.0-canary.87166dc → 10.0.0-canary.908b65b

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 import { RootState, useStore } from '@react-three/fiber/extension';
 import * as three_webgpu from 'three/webgpu';
 import { Node, StorageTexture, Storage3DTexture, StorageArrayTexture, Data3DTexture, RenderPipeline, Vector2, Vector3, Vector4, Color, Matrix2, Matrix3, Matrix4 } from 'three/webgpu';
+import { Fn } from 'three/tsl';
 
 //* Buffer Types (useBuffers) ========================================
 
@@ -57,6 +58,40 @@ type NodeRecord<T extends NodeLike = NodeLike> = Record<string, T>
  */
 type NodeStore = Record<string, NodeLike | NodeRecord>
 
+/** What `Fn()` returns (its members are what matters here, not its signature). */
+type FnNodeLike = ReturnType<typeof Fn>
+
+/**
+ * What an unregistered node read is: `useNodes().wobble`, `useNodes('fx').blur`, a creator's
+ * `nodes.wobble`, `state.nodes.wobble` in `useFrame`.
+ *
+ * Why it is loose: the read goes through a string name, and TypeScript cannot know what the entry
+ * under that name holds: a float, a vec3, a texture sample, or an `Fn()` to call. three's types
+ * only give operator methods to a node whose node type is known, and only an `Fn()` can be called,
+ * so the broad `NodeLike` allowed neither and every read needed a cast.
+ *
+ * So this has every member that any of three's nodes or an `Fn()` has, each typed `any`, and can
+ * be called. `nodes.wobble.mul(2)`, `material.colorNode = nodes.wobble` and `nodes.rimLightFn()`
+ * compile, and a misspelt member is still an error. It is a deliberate simplification: results of
+ * its own methods and calls are `any`.
+ *
+ * A single `as` gives it an exact type: `nodes.wobble as Node<'vec3'>`, `nodes.fn as typeof fn`.
+ * For exact types without casts, register the nodes (`nodes` / `nodeScopes` in `Register`) or pass
+ * a schema to the reader: `useNodes<{ blur: Node<'vec4'> }>('fx')`, `nodes.scope<Schema>('fx')`.
+ */
+interface LooseNode extends TSLLooseMembers<Node<TSLNodeTypeName> | FnNodeLike> {
+  (...args: any[]): any
+}
+
+/**
+ * A root entry of an unregistered node map: a node (its members) or a scope of nodes (any other
+ * name), since the type cannot tell which a name holds.
+ */
+type LooseNodeEntry = LooseNode & { readonly [name: string]: LooseNode }
+
+/** An unregistered node map read: `state.nodes`, `useNodes()`. */
+type LooseNodeStore = Record<string, LooseNodeEntry>
+
 //* Storage Types (useGPUStorage) ========================================
 
 /**
@@ -93,17 +128,23 @@ type StorageStore = Record<string, StorageLike | StorageRecord>
  */
 interface TSLRootState {
   /**
-   * TSL uniform nodes - root-level uniforms + scoped sub-objects. Use useUniforms(). Typed by name
-   * once you register them (see `Register`), so `useFrame(({ uniforms }) => uniforms.uTime.value)`
-   * needs no cast.
+   * TSL uniform nodes - root-level uniforms + scoped sub-objects. Use useUniforms(). Each read is a
+   * `LooseUniformNode`, usable without casts, or typed by name once you register them (see
+   * `Register`), so `useFrame(({ uniforms }) => uniforms.uTime.value)` needs no cast either way.
    */
   uniforms: AppUniforms
-  /** TSL nodes - root-level nodes + scoped sub-objects. Use useNodes() */
-  nodes: NodeStore
-  /** Buffers - root-level buffers + scoped sub-objects. Use useBuffers() */
-  buffers: BufferStore
-  /** GPU storage (textures, etc.) - root-level storage + scoped sub-objects. Use useGPUStorage() */
-  gpuStorage: StorageStore
+  /**
+   * TSL nodes - root-level nodes + scoped sub-objects. Use useNodes(). Each read is a `LooseNode`,
+   * usable without casts, or typed by name once you register your nodes (see `Register`).
+   */
+  nodes: AppNodes
+  /** Buffers - root-level buffers + scoped sub-objects. Use useBuffers(). Typed by name once registered */
+  buffers: AppBuffers
+  /**
+   * GPU storage (textures, etc.) - root-level storage + scoped sub-objects. Use useGPUStorage().
+   * Typed by name once registered
+   */
+  gpuStorage: AppGPUStorage
   /** Internal: bumped by hot reloads and rebuilds to re-run creators */
   _hmrVersion: number
   /** The canvas's RenderPipeline, once useRenderPipeline created one. Per canvas, not shared. */
@@ -233,6 +274,69 @@ declare global {
    */
   type UniformStore = Record<string, UniformNode | UniformRecord>
 
+  //* Loose reads ==============================
+
+  /** Every shader node type three's TSL declarations type separately. */
+  type TSLNodeTypeName =
+    | 'float'
+    | 'int'
+    | 'uint'
+    | 'bool'
+    | 'vec2'
+    | 'vec3'
+    | 'vec4'
+    | 'ivec2'
+    | 'ivec3'
+    | 'ivec4'
+    | 'uvec2'
+    | 'uvec3'
+    | 'uvec4'
+    | 'bvec2'
+    | 'bvec3'
+    | 'bvec4'
+    | 'color'
+    | 'mat2'
+    | 'mat3'
+    | 'mat4'
+
+  /** Every member of every constituent of `T`, each typed `any`. */
+  type TSLLooseMembers<T> = { [K in T extends unknown ? keyof T : never]: any }
+
+  /**
+   * What an unregistered uniform read is: `useUniforms().uTime`, `useUniforms('fx').blur`,
+   * `useUniform('uTime')`, a creator's `uniforms.uTime`, `state.uniforms.uTime` in `useFrame`.
+   *
+   * Why it is loose: the read goes through a string name, and TypeScript cannot know what a
+   * runtime entry under that name holds. three's types only give the operator methods (`.mul`,
+   * `.add`, swizzles, `.toVar()`, ...) to a node whose node type is known, so `UniformNode<unknown>`
+   * had none of them and every read needed a cast.
+   *
+   * So this has every member that any of three's uniform nodes has (float, vec3, color, mat4, ...),
+   * each typed `any`. Every operator, TSL function and material slot accepts it, and a misspelt member
+   * (`.valeu`) is still an error. It is a deliberate simplification: results of its own methods are
+   * `any`, and nothing checks that `cross()` gets a vec3.
+   *
+   * It converts to an exact type with a single `as`, since every member is `any`:
+   * `uniforms.uColor as UniformNode<'color', Color>`, or `as Node<'vec3'>`. A node typed as a float
+   * uniform would cover the operators with exact result types, but three's node types are not
+   * comparable to one another, so it could only be cast through `unknown`.
+   *
+   * Exact types without casts: register the uniforms (`Register` in `@react-three/tsl`, which also
+   * catches typos in the name), or pass a schema to the reader (`useUniforms<{ blur: number }>('fx')`,
+   * `useUniform<Color>('uColor')`, `uniforms.scope<{ uHealth: UniformNode<'float', number> }>('player')`).
+   */
+  interface LooseUniformNode extends TSLLooseMembers<three_webgpu.UniformNode<TSLNodeTypeName, any>> {}
+
+  /**
+   * A root entry of an unregistered uniform map: a uniform (its members) or a scope of uniforms (any
+   * other name), since the type cannot tell which a name holds. `uniforms.uTime.mul(2)` and
+   * `uniforms.player.uHealth` both read.
+   */
+  type LooseUniformEntry = LooseUniformNode & { readonly [name: string]: LooseUniformNode }
+
+  /** An unregistered uniform map read: `state.uniforms`, `useUniforms()`. */
+  type LooseUniformStore = Record<string, LooseUniformEntry>
+
   /**
    * Helper to safely access a uniform node from the store.
    * Use this when accessing state.uniforms to get proper typing.
@@ -395,13 +499,14 @@ 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
+ * // With uniforms registered (see `Register` and the Typed Resources guide), reads are typed by name
  * useLocalNodes(({ uniforms }) => ({
  *   wobble: sin(uniforms.uTime.mul(2)),
  *   playerHealth: uniforms.scope('player').uHealth, // or uniforms.player.uHealth
  * }), [])
  *
- * // Without registration, give a scope its schema
+ * // Without registration a read is loose: TSL takes it as is. A scope schema makes it exact.
+ * useLocalNodes(({ uniforms }) => ({ wobble: sin(uniforms.uTime.mul(2)) }), [])
  * useLocalNodes(({ uniforms }) => {
  *   const player = uniforms.scope<{ uHealth: UniformNode<'float', number> }>('player')
  *   return { damage: player.uHealth.mul(2) }
@@ -414,16 +519,19 @@ type ResourceLeafGuard<T> = (value: unknown) => value is T;
  * Property access returns `T` (assumes leaf node).
  * Use `.scope(key)` for nested object access.
  *
+ * `TLeaf` is what a scope schema must hold (`scope<{ uHealth: UniformNode<'float', number> }>()`),
+ * `TRead` what a leaf reads as without one. They differ for uniforms and nodes, whose unregistered
+ * reads are the loose `LooseUniformNode` / `LooseNode` (see those types for why).
  */
-type ScopedStoreMethods<TLeaf> = {
+type ScopedStoreMethods<TLeaf, TRead extends TLeaf = TLeaf> = {
     /** Access a nested scope by key. Returns empty wrapper if scope doesn't exist. */
-    scope<TScope extends Record<string, TLeaf> = Record<string, TLeaf>>(key: string): ScopedStoreType<TLeaf, TScope>;
+    scope<TScope extends Record<string, TLeaf> = Record<string, TRead>>(key: string): ScopedStoreType<TLeaf, TScope, TRead>;
     /** Check if a key exists in the store */
     has(key: string): boolean;
     /** Get all keys in the store */
     keys(): string[];
 };
-type ScopedStoreType<TLeaf, TEntries extends Record<string, TLeaf> = Record<string, TLeaf>> = Readonly<TEntries> & ScopedStoreMethods<TLeaf>;
+type ScopedStoreType<TLeaf, TEntries extends Record<string, TLeaf> = Record<string, TLeaf>, TRead extends TLeaf = TLeaf> = Readonly<TEntries> & ScopedStoreMethods<TLeaf, TRead>;
 interface ScopedStoreData<TLeaf> {
     [key: string]: TLeaf | ScopedStoreData<TLeaf>;
 }
@@ -440,18 +548,18 @@ declare function createScopedStore<TLeaf>(data: ScopedStoreData<TLeaf>, isLeaf:
 type CreatorState = Omit<RootState, 'uniforms' | 'nodes' | 'buffers' | 'gpuStorage'> & {
     /** Type-safe uniform access - property access returns UniformNode, typed by name when registered */
     uniforms: CreatorUniforms;
-    /** Type-safe node access for real, callable, and legacy structural nodes */
-    nodes: ScopedStoreType<NodeLike>;
-    /** Type-safe buffer access - property access returns BufferLike (TypedArrays, BufferAttributes, TSL nodes) */
-    buffers: ScopedStoreType<BufferLike>;
-    /** Type-safe GPU storage access - property access returns StorageLike (StorageTexture, TSL nodes) */
-    gpuStorage: ScopedStoreType<StorageLike>;
+    /** Node access: each read a `LooseNode` (callable, every operator), typed by name when registered */
+    nodes: CreatorNodes;
+    /** Buffer access: typed by name when registered, BufferLike (typed arrays, attributes, nodes) otherwise */
+    buffers: CreatorBuffers;
+    /** GPU storage access: typed by name when registered, StorageLike (storage textures, nodes) otherwise */
+    gpuStorage: CreatorGPUStorage;
 };
 
 /**
- * @fileoverview Typed uniforms by registration (the TanStack Router `Register` pattern).
+ * @fileoverview Typed TSL resources by registration (the TanStack Router `Register` pattern).
  *
- * Nothing registered: every type below falls back to the loose shapes the hooks have always had.
+ * Nothing registered: every type below falls back to loose reads (`LooseUniformNode`, `LooseNode`).
  * Registered once, anywhere in the app:
  *
  * ```ts
@@ -471,14 +579,25 @@ type CreatorState = Omit<RootState, 'uniforms' | 'nodes' | 'buffers' | 'gpuStora
  *
  * then `useUniforms().uTime`, `useUniforms('player').uHealth`, `useUniform('uTime')`,
  * `useFrame(({ uniforms }) => uniforms.uTime)`, `useThree((s) => s.uniforms.uTime)` and a creator's
- * `({ uniforms }) => uniforms.uTime` are typed by name, with no generics.
+ * `({ uniforms }) => uniforms.uTime` are typed by name, with no generics. Nodes register the same
+ * way, by their node types: `nodes: { wobble: Node<'float'>; rimLight: typeof rimLightFn }` and
+ * `nodeScopes: { fx: { blur: Node<'vec4'> } }`, and so do buffers (`buffers` / `bufferScopes`) and
+ * GPU storage (`gpuStorage` / `gpuStorageScopes`). Docs: docs/webgpu/typed-resources.mdx.
+ *
+ * Unregistered reads are loose: `LooseUniformNode` / `LooseNode`, which every operator accepts and
+ * a single `as` makes exact (see those types for why).
  */
 
 /**
- * Augment this to type uniforms by name. Recognised keys:
+ * Augment this to type TSL resources by name. Recognised keys:
  * - `uniforms`: the root-level uniform inputs (e.g. `typeof globalUniforms`)
- * - `scopes`: named scopes and their inputs (e.g. `{ player: typeof playerUniforms }`)
- * - `strict`: `false` makes unregistered root keys loose instead of errors (default: strict)
+ * - `scopes`: named uniform scopes and their inputs (e.g. `{ player: typeof playerUniforms }`)
+ * - `nodes`: the root-level nodes by node type (e.g. `{ wobble: Node<'float'>; rim: typeof rimFn }`)
+ * - `nodeScopes`: named node scopes and their nodes (e.g. `{ fx: { blur: Node<'vec4'> } }`)
+ * - `buffers` / `bufferScopes`: buffers by name (e.g. `{ positions: StorageBufferNode<'vec3'> }`)
+ * - `gpuStorage` / `gpuStorageScopes`: GPU storage by name (e.g. `{ heightMap: StorageTexture }`)
+ * - `strict`: `false` makes unregistered root keys loose instead of errors (default: strict), for
+ *   every resource family alike
  */
 interface Register {
 }
@@ -503,9 +622,11 @@ type TypedUniforms = UniformNodesFor<RegisteredUniforms> & {
 };
 /**
  * What `state.uniforms` and `useUniforms()` are: the registered shape (strict by default, so a typo
- * is an error), or today's loose `UniformStore` when nothing is registered.
+ * is an error), or the loose `LooseUniformStore` when nothing is registered. With `strict: false`
+ * an unregistered root key reads loose too. A loose read is a `LooseUniformNode`: every operator and
+ * material slot accepts it, and a single `as` gives it an exact type (see that type for why).
  */
-type AppUniforms = IsRegistered extends true ? IsStrict extends true ? TypedUniforms : TypedUniforms & UniformStore : UniformStore;
+type AppUniforms = IsRegistered extends true ? IsStrict extends true ? TypedUniforms : TypedUniforms & LooseUniformStore : LooseUniformStore;
 /** Creator input at root level: new keys are free, registered keys must keep their registered type. */
 type RootUniformInput = Partial<RegisteredUniforms> & UniformInputRecord;
 /** Creator input for scope `S`: checked against the registered scope, free for any other scope. */
@@ -515,13 +636,101 @@ type RegisteredScopeUniforms<S extends keyof RegisteredScopes> = UniformNodesFor
 /** A registered root uniform's node. */
 type RegisteredUniform<K extends keyof RegisteredUniforms> = UniformNodesFor<RegisteredUniforms>[K];
 /**
- * `uniforms` in a creator (`useNodes(({ uniforms }) => ...)`). Unregistered: any name is a
- * `UniformNode`, as before. Registered: typed by name like `state.uniforms`, and `.scope(name)` is
+ * `uniforms` in a creator (`useNodes(({ uniforms }) => ...)`). Unregistered: any name reads as a
+ * `LooseUniformNode` (or, by dot access, a scope of them), and `.scope(name)` as a record of them
+ * unless given a schema. Registered: typed by name like `state.uniforms`, and `.scope(name)` is
  * typed for registered scopes.
  */
 type CreatorUniforms = IsRegistered extends true ? {
-    scope<S extends keyof RegisteredScopes & string>(key: S): ScopedStoreType<UniformNode, RegisteredScopeUniforms<S>>;
-} & Readonly<AppUniforms> & ScopedStoreMethods<UniformNode> : ScopedStoreType<UniformNode>;
+    scope<S extends keyof RegisteredScopes & string>(key: S): ScopedStoreType<UniformNode, RegisteredScopeUniforms<S>, LooseUniformNode>;
+} & Readonly<AppUniforms> & ScopedStoreMethods<UniformNode, LooseUniformNode> : ScopedStoreType<UniformNode, LooseUniformStore, LooseUniformNode>;
+/** The registered root-level nodes, or `{}` when none are registered. */
+type RegisteredNodes = Register extends {
+    nodes: infer N extends NodeRecord;
+} ? N : {};
+/** The registered node scopes and their nodes, or `{}` when none are registered. */
+type RegisteredNodeScopes = Register extends {
+    nodeScopes: infer S extends Record<string, NodeRecord>;
+} ? S : {};
+type IsNodesRegistered = Register extends {
+    nodes: any;
+} | {
+    nodeScopes: any;
+} ? true : false;
+type TypedNodes = RegisteredNodes & RegisteredNodeScopes;
+/**
+ * What `state.nodes` and `useNodes()` are: the registered shape (strict by default, so a typo is an
+ * error), or the loose `LooseNodeStore` when no nodes are registered. With `strict: false` an
+ * unregistered root key reads loose too.
+ */
+type AppNodes = IsNodesRegistered extends true ? IsStrict extends true ? TypedNodes : TypedNodes & LooseNodeStore : LooseNodeStore;
+/** Creator output at root level: new keys are free, registered keys must keep their registered type. */
+type RootNodeInput = Partial<RegisteredNodes> & NodeRecord;
+/** Creator output for scope `S`: checked against the registered scope, free for any other scope. */
+type ScopeNodeInput<S extends string> = S extends keyof RegisteredNodeScopes ? Partial<RegisteredNodeScopes[S]> : unknown;
+/**
+ * `nodes` in a creator. Unregistered: any name reads as a `LooseNode` (or, by dot access, a scope of
+ * them). Registered: typed by name like `state.nodes`, and `.scope(name)` is typed for registered
+ * scopes.
+ */
+type CreatorNodes = IsNodesRegistered extends true ? {
+    scope<S extends keyof RegisteredNodeScopes & string>(key: S): ScopedStoreType<NodeLike, RegisteredNodeScopes[S], LooseNode>;
+} & Readonly<AppNodes> & ScopedStoreMethods<NodeLike, LooseNode> : ScopedStoreType<NodeLike, LooseNodeStore, LooseNode>;
+/** A node reader's result for an explicit schema `T`, or loose nodes when none was given. */
+type ReadNodes<T extends NodeRecord> = NodeRecord extends T ? Record<string, LooseNode> : T;
+/** The registered root-level buffers, or `{}` when none are registered. */
+type RegisteredBuffers = Register extends {
+    buffers: infer B extends BufferRecord;
+} ? B : {};
+/** The registered buffer scopes and their buffers, or `{}` when none are registered. */
+type RegisteredBufferScopes = Register extends {
+    bufferScopes: infer S extends Record<string, BufferRecord>;
+} ? S : {};
+type IsBuffersRegistered = Register extends {
+    buffers: any;
+} | {
+    bufferScopes: any;
+} ? true : false;
+type TypedBuffers = RegisteredBuffers & RegisteredBufferScopes;
+/** What `state.buffers` and `useBuffers()` are: the registered shape, or `BufferStore` when none are. */
+type AppBuffers = IsBuffersRegistered extends true ? IsStrict extends true ? TypedBuffers : TypedBuffers & BufferStore : BufferStore;
+/** Creator output at root level: new keys are free, registered keys must keep their registered type. */
+type RootBufferInput = Partial<RegisteredBuffers> & BufferRecord;
+/** Creator output for scope `S`: checked against the registered scope, free for any other scope. */
+type ScopeBufferInput<S extends string> = S extends keyof RegisteredBufferScopes ? Partial<RegisteredBufferScopes[S]> : unknown;
+/** `buffers` in a creator: typed by name when registered, `BufferLike` reads otherwise. */
+type CreatorBuffers = IsBuffersRegistered extends true ? {
+    scope<S extends keyof RegisteredBufferScopes & string>(key: S): ScopedStoreType<BufferLike, RegisteredBufferScopes[S]>;
+} & Readonly<AppBuffers> & ScopedStoreMethods<BufferLike> : ScopedStoreType<BufferLike>;
+/** The registered root-level GPU storage, or `{}` when none is registered. */
+type RegisteredGPUStorage = Register extends {
+    gpuStorage: infer G extends StorageRecord;
+} ? G : {};
+/** The registered GPU storage scopes and their entries, or `{}` when none are registered. */
+type RegisteredGPUStorageScopes = Register extends {
+    gpuStorageScopes: infer S extends Record<string, StorageRecord>;
+} ? S : {};
+type IsGPUStorageRegistered = Register extends {
+    gpuStorage: any;
+} | {
+    gpuStorageScopes: any;
+} ? true : false;
+type TypedGPUStorage = RegisteredGPUStorage & RegisteredGPUStorageScopes;
+/** What `state.gpuStorage` and `useGPUStorage()` are: the registered shape, or `StorageStore`. */
+type AppGPUStorage = IsGPUStorageRegistered extends true ? IsStrict extends true ? TypedGPUStorage : TypedGPUStorage & StorageStore : StorageStore;
+/** Creator output at root level: new keys are free, registered keys must keep their registered type. */
+type RootGPUStorageInput = Partial<RegisteredGPUStorage> & StorageRecord;
+/** Creator output for scope `S`: checked against the registered scope, free for any other scope. */
+type ScopeGPUStorageInput<S extends string> = S extends keyof RegisteredGPUStorageScopes ? Partial<RegisteredGPUStorageScopes[S]> : unknown;
+/** `gpuStorage` in a creator: typed by name when registered, `StorageLike` reads otherwise. */
+type CreatorGPUStorage = IsGPUStorageRegistered extends true ? {
+    scope<S extends keyof RegisteredGPUStorageScopes & string>(key: S): ScopedStoreType<StorageLike, RegisteredGPUStorageScopes[S]>;
+} & Readonly<AppGPUStorage> & ScopedStoreMethods<StorageLike> : ScopedStoreType<StorageLike>;
+/**
+ * A reader's result for an explicit schema `T`, or loose uniforms when none was given (`T` is then
+ * its constraint, `UniformInputRecord`): `useUniforms<{ blur: number }>('fx')` vs `useUniforms('fx')`.
+ */
+type ReadUniforms<T extends UniformInputRecord> = UniformInputRecord extends T ? Record<string, LooseUniformNode> : UniformNodesFor<T>;
 
 /** Uniforms that exist on every primary canvas from the start. See configureTSL. */
 interface TSLConfig {
@@ -565,7 +774,7 @@ declare function useUniforms<T extends RootUniformInput>(uniforms: T): UniformsW
 declare function useUniforms<T extends UniformInputRecord, S extends string>(uniforms: T & ScopeUniformInput<S>, scope: S): UniformsWithUtils<UniformNodesFor<T>>;
 declare function useUniforms(): UniformsWithUtils<AppUniforms>;
 declare function useUniforms<S extends keyof RegisteredScopes & string>(scope: S): UniformsWithUtils<RegisteredScopeUniforms<S>>;
-declare function useUniforms<T extends UniformInputRecord>(scope?: string): UniformsWithUtils<UniformNodesFor<T>>;
+declare function useUniforms<T extends UniformInputRecord>(scope?: string): UniformsWithUtils<ReadUniforms<T>>;
 /**
  * Global rebuildUniforms function for HMR integration.
  * Invalidates cached uniforms and increments _hmrVersion to trigger re-creation.
@@ -587,8 +796,10 @@ declare function rebuildAllUniforms(store: ReturnType<typeof useStore>, scope?:
  * - UniformNode: existing uniforms (reused as-is)
  */
 type UniformValue = number | boolean | string | Vector2 | Vector3 | Vector4 | Color | Matrix2 | Matrix3 | Matrix4 | Node | UniformNode;
+/** `useUniform<T>(name)`'s result: exact for an explicit `T`, a `LooseUniformNode` without one. */
+type ReadUniform<T extends UniformValue> = UniformValue extends T ? LooseUniformNode : UniformNodeFor<T>;
 declare function useUniform<K extends keyof RegisteredUniforms & string>(name: K): RegisteredUniform<K>;
-declare function useUniform<T extends UniformValue = UniformValue>(name: string): UniformNodeFor<T>;
+declare function useUniform<T extends UniformValue = UniformValue>(name: string): ReadUniform<T>;
 declare function useUniform<T extends UniformValue>(name: string, value: T): UniformNodeFor<T>;
 
 /**
@@ -618,12 +829,12 @@ type NodesWithUtils<T extends Record<string, unknown> = NodeRecord> = T & {
     clearNodes: ClearNodesFn;
     rebuildNodes: RebuildNodesFn;
 };
-declare function useNodes(): NodesWithUtils<NodeStore>;
-declare function useNodes(scope: string): NodesWithUtils<NodeRecord>;
-declare function useNodes<T extends NodeRecord>(scope?: string): NodesWithUtils<T>;
-declare function useNodes<T extends NodeRecord>(creator: NodeCreator<T>): NodesWithUtils<T>;
-declare function useNodes<T extends NodeRecord>(creator: NodeCreator<T>, scope: string): NodesWithUtils<T>;
-declare function useNodes(creatorOrScope?: NodeCreator<NodeRecord> | string, scope?: string): NodesWithUtils<Record<string, unknown>>;
+declare function useNodes(): NodesWithUtils<AppNodes>;
+declare function useNodes<S extends keyof RegisteredNodeScopes & string>(scope: S): NodesWithUtils<RegisteredNodeScopes[S]>;
+declare function useNodes<T extends NodeRecord>(scope?: string): NodesWithUtils<ReadNodes<T>>;
+declare function useNodes<T extends RootNodeInput>(creator: NodeCreator<T>): NodesWithUtils<T>;
+declare function useNodes<T extends NodeRecord, S extends string>(creator: (state: CreatorState) => T & ScopeNodeInput<S>, scope: S): NodesWithUtils<T>;
+declare function useNodes<S extends string | undefined>(creatorOrScope: NodeCreator<NodeRecord> | string | undefined, scope: S & (string extends S ? unknown : never)): NodesWithUtils<Record<string, unknown>>;
 /**
  * Global rebuildNodes function for HMR integration.
  * Invalidates cached nodes and increments _hmrVersion to trigger re-creation.
@@ -694,8 +905,8 @@ type LocalNodeInstaller = (state: CreatorState) => LocalNodeInstall;
  *
  * @example
  * ```tsx
- * // 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.
+ * // Resource-driven composition: no surrounding JS inputs. `uniforms.uTime` is typed by name when
+ * // the app registers its uniforms (see `Register`), and a loose node TSL accepts as is otherwise.
  * const { wobble, uTime } = useLocalNodes(({ uniforms, nodes }) => ({
  *   wobble: sin(uniforms.uTime.mul(2)),
  *   uTime: uniforms.uTime, // can return uniforms too
@@ -706,10 +917,10 @@ type LocalNodeInstaller = (state: CreatorState) => LocalNodeInstall;
  *   result: pattern === 'noise' ? nodes.noise : nodes.stripes,
  * }), [pattern])
  *
- * // An unregistered uniform, cast to its type
- * const { colorNode } = useLocalNodes(({ uniforms }) => {
- *   const uValue = uniforms.myUniform as UniformNode<'float', number>
- *   return { colorNode: mix(colorA, colorB, uValue) }
+ * // An unregistered uniform works as is; one `as` gives its exact type where that matters
+ * const { colorNode, facing } = useLocalNodes(({ uniforms }) => {
+ *   const uDir = uniforms.uDir as UniformNode<'vec3', Vector3> // cross() wants a vec3
+ *   return { colorNode: mix(colorA, colorB, uniforms.myUniform), facing: cross(uDir, normalView) }
  * }, [])
  * ```
  */
@@ -740,11 +951,13 @@ type BuffersWithUtils<T extends BufferRecordType | BufferStore = BufferRecordTyp
     rebuildBuffers: RebuildBuffersFn;
     disposeBuffers: DisposeBuffersFn;
 };
-declare function useBuffers(): BuffersWithUtils<BufferStore>;
+declare function useBuffers(): BuffersWithUtils<AppBuffers>;
+declare function useBuffers<S extends keyof RegisteredBufferScopes & string>(scope: S): BuffersWithUtils<RegisteredBufferScopes[S]>;
 declare function useBuffers(scope: string): BuffersWithUtils<Record<string, BufferLike>>;
 declare function useBuffers<T extends Record<string, BufferLike>>(scope?: string): BuffersWithUtils<T>;
-declare function useBuffers<T extends Record<string, BufferLike>>(creator: BufferCreator<T>): BuffersWithUtils<T>;
-declare function useBuffers<T extends Record<string, BufferLike>>(creator: BufferCreator<T>, scope: string): BuffersWithUtils<T>;
+declare function useBuffers<T extends RootBufferInput>(creator: BufferCreator<T>): BuffersWithUtils<T>;
+declare function useBuffers<T extends Record<string, BufferLike>, S extends string>(creator: (state: CreatorState) => T & ScopeBufferInput<S>, scope: S): BuffersWithUtils<T>;
+declare function useBuffers<S extends string | undefined>(creator: BufferCreator<BufferRecord>, scope: S & (string extends S ? unknown : never)): BuffersWithUtils<BufferRecord>;
 /**
  * Global rebuildBuffers function for HMR integration.
  * Invalidates cached buffers and increments _hmrVersion to trigger re-creation.
@@ -782,11 +995,13 @@ type StorageWithUtils<T extends StorageRecordType | StorageStore = StorageRecord
     rebuildStorage: RebuildStorageFn;
     disposeStorage: DisposeStorageFn;
 };
-declare function useGPUStorage(): StorageWithUtils<StorageStore>;
+declare function useGPUStorage(): StorageWithUtils<AppGPUStorage>;
+declare function useGPUStorage<S extends keyof RegisteredGPUStorageScopes & string>(scope: S): StorageWithUtils<RegisteredGPUStorageScopes[S]>;
 declare function useGPUStorage(scope: string): StorageWithUtils<Record<string, StorageLike>>;
 declare function useGPUStorage<T extends Record<string, StorageLike>>(scope?: string): StorageWithUtils<T>;
-declare function useGPUStorage<T extends Record<string, StorageLike>>(creator: StorageCreator<T>): StorageWithUtils<T>;
-declare function useGPUStorage<T extends Record<string, StorageLike>>(creator: StorageCreator<T>, scope: string): StorageWithUtils<T>;
+declare function useGPUStorage<T extends RootGPUStorageInput>(creator: StorageCreator<T>): StorageWithUtils<T>;
+declare function useGPUStorage<T extends Record<string, StorageLike>, S extends string>(creator: (state: CreatorState) => T & ScopeGPUStorageInput<S>, scope: S): StorageWithUtils<T>;
+declare function useGPUStorage<S extends string | undefined>(creator: StorageCreator<StorageRecord>, scope: S & (string extends S ? unknown : never)): StorageWithUtils<StorageRecord>;
 /**
  * Global rebuildStorage function for HMR integration.
  * Invalidates cached storage and increments _hmrVersion to trigger re-creation.
@@ -844,4 +1059,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, 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 };
+export type { AppBuffers, AppGPUStorage, AppNodes, AppUniforms, BufferCreator, BufferLike, BufferRecord, BufferStore, BuffersWithUtils, ClearBuffersFn, ClearNodesFn, ClearStorageFn, ClearUniformsFn, CreatorState, DisposeBuffersFn, DisposeStorageFn, FnNodeLike, LocalNodeCreator, LocalNodeInstall, LocalNodeInstaller, LooseNode, LooseNodeEntry, LooseNodeStore, NodeCreator, NodeLike, NodeRecord, NodeStore, NodesWithUtils, RebuildBuffersFn, RebuildNodesFn, RebuildStorageFn, RebuildUniformsFn, Register, RegisteredBufferScopes, RegisteredBuffers, RegisteredGPUStorage, RegisteredGPUStorageScopes, RegisteredNodeScopes, RegisteredNodes, RegisteredScopeUniforms, RegisteredScopes, RegisteredUniform, RegisteredUniforms, RemoveBuffersFn, RemoveNodesFn, RemoveStorageFn, RemoveUniformsFn, RootBufferInput, RootGPUStorageInput, RootNodeInput, RootUniformInput, ScopeBufferInput, ScopeGPUStorageInput, ScopeNodeInput, ScopeUniformInput, ScopedStoreType, StorageCreator, StorageLike, StorageRecord, StorageStore, StorageWithUtils, TSLConfig, TSLNode, TSLNodeLike, TSLRootState, UniformCreator, UniformValue, UniformsWithUtils };

package/dist/index.mjs

@@ -58,6 +58,13 @@ function withStagedOverlay(store, kind, committed) {
   }
   return view;
 }
+function readWithStaged(store, kind, committed, scope, isLeaf) {
+  if (scope === void 0) return withStagedOverlay(store, kind, committed);
+  const scopeData = committed[scope];
+  const current = scopeData && typeof scopeData === "object" && !isLeaf(scopeData) ? scopeData : {};
+  const staged = scope === ROOT_SCOPE ? void 0 : peekStaged(store, kind, scope);
+  return staged ? { ...current, ...staged } : current;
+}
 function flushStagedScope(store, kind, scopeKey, isLeaf) {
   const registry = getKindRegistry(store, kind);
   const staged = registry.staged.get(scopeKey);
@@ -689,8 +696,9 @@ function useUniforms(creatorOrScope, scope) {
     input: memoizedInput,
     create: () => {
       if (isReader) return {};
-      if (typeof processedInput.candidates !== "object" || processedInput.candidates === null)
+      if (typeof processedInput.candidates !== "object" || processedInput.candidates === null) {
         throw new Error("Invalid uniform input");
+      }
       return processedInput.candidates;
     },
     prepare: (name, candidate) => createUniform(name, candidate, scope),
@@ -708,13 +716,7 @@ function useUniforms(creatorOrScope, scope) {
       if (!equals) existing.value = newVal;
     }
   });
-  let uniforms = created;
-  if (memoizedInput === void 0) {
-    uniforms = storeUniforms;
-  } else if (typeof memoizedInput === "string") {
-    const scopeData = storeUniforms[memoizedInput];
-    uniforms = scopeData && !isUniformNode(scopeData) ? scopeData : {};
-  }
+  const uniforms = isReader ? readWithStaged(store, "uniforms", storeUniforms, memoizedInput, isUniformNode) : created;
   return { ...uniforms, removeUniforms, clearUniforms, rebuildUniforms };
 }
 function rebuildAllUniforms(store, scope) {
@@ -831,13 +833,7 @@ function useNodes(creatorOrScope, scope) {
       return node;
     }
   });
-  let nodes = created;
-  if (creatorOrScope === void 0) {
-    nodes = storeNodes;
-  } else if (typeof creatorOrScope === "string") {
-    const scopeData = storeNodes[creatorOrScope];
-    nodes = scopeData && !isTSLNode(scopeData) ? scopeData : {};
-  }
+  const nodes = isReader ? readWithStaged(store, "nodes", storeNodes, creatorOrScope, isTSLNode) : created;
   return { ...nodes, removeNodes, clearNodes, rebuildNodes };
 }
 function rebuildAllNodes(store, scope) {
@@ -992,13 +988,7 @@ function useBuffers(creatorOrScope, scope) {
       return buffer;
     }
   });
-  let buffers = created;
-  if (creatorOrScope === void 0) {
-    buffers = storeBuffers;
-  } else if (typeof creatorOrScope === "string") {
-    const scopeData = storeBuffers[creatorOrScope];
-    buffers = scopeData && !isBufferLike(scopeData) ? scopeData : {};
-  }
+  const buffers = isReader ? readWithStaged(store, "buffers", storeBuffers, creatorOrScope, isBufferLike) : created;
   return { ...buffers, removeBuffers, clearBuffers, rebuildBuffers, disposeBuffers };
 }
 function rebuildAllBuffers(store, scope) {
@@ -1062,13 +1052,7 @@ function useGPUStorage(creatorOrScope, scope) {
       return storage;
     }
   });
-  let gpuStorage = created;
-  if (creatorOrScope === void 0) {
-    gpuStorage = storeStorage;
-  } else if (typeof creatorOrScope === "string") {
-    const scopeData = storeStorage[creatorOrScope];
-    gpuStorage = scopeData && !isStorageLike(scopeData) ? scopeData : {};
-  }
+  const gpuStorage = isReader ? readWithStaged(store, "gpuStorage", storeStorage, creatorOrScope, isStorageLike) : created;
   return {
     ...gpuStorage,
     removeStorage,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@react-three/tsl",
-  "version": "10.0.0-canary.87166dc",
+  "version": "10.0.0-canary.908b65b",
   "description": "TSL resource hooks for react-three-fiber: uniforms, nodes, buffers, GPU storage and render pipelines on WebGPU",
   "keywords": [
     "react",
@@ -56,7 +56,7 @@
     "@types/three": "^0.185.0",
     "@webgpu/types": "^0.1.64",
     "three": ">=0.185.0",
-    "@react-three/fiber": "10.0.0-canary.87166dc"
+    "@react-three/fiber": "10.0.0-canary.908b65b"
   },
   "scripts": {
     "build": "unbuild",