@react-three/tsl 10.0.0-canary.04087d8

package/dist/index.d.cts

@@ -0,0 +1,847 @@
+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';
+
+//* Buffer Types (useBuffers) ========================================
+
+/**
+ * Buffer-like types for GPU compute and storage operations.
+ * Includes raw CPU arrays, Three.js buffer attributes, and TSL buffer nodes.
+ *
+ * @example
+ * ```tsx
+ * const { positions, velocities } = useBuffers(() => ({
+ *   positions: instancedArray(count, 'vec3'),       // StorageBufferNode
+ *   velocities: new Float32Array(count * 3),        // TypedArray
+ * }), 'particles')
+ * ```
+ */
+type BufferLike =
+  | Float32Array
+  | Uint32Array
+  | Int32Array
+  | Float64Array
+  | Uint8Array
+  | Int8Array
+  | Uint16Array
+  | Int16Array
+  | three_webgpu.BufferAttribute // Base class for all buffer attributes
+  | three_webgpu.InterleavedBufferAttribute
+  | Node // TSL buffer nodes (instancedArray, storage)
+
+/** Flat record of buffer-like values (no nested scopes) */
+type BufferRecord = Record<string, BufferLike>
+
+/**
+ * Buffer store that can contain both root-level buffers and scoped buffer objects.
+ * Structure: { positions: Float32Array, particles: { vel: StorageBufferNode } }
+ */
+type BufferStore = Record<string, BufferLike | BufferRecord>
+
+//* Node Types (useNodes) ========================================
+
+/**
+ * Every node representation `useNodes` accepts and `state.nodes` holds: three's real `Node`,
+ * the callable proxy `Fn()` returns, and the legacy structural shape (`uuid`/`nodeType`) older
+ * code passes through. Creators are constrained to this same type, so the shape a creator returns
+ * and the shape the store holds are one type by construction.
+ */
+type NodeLike = TSLNodeType | LegacyTSLNodeLike
+
+/** Flat record of TSL nodes (no nested scopes) */
+type NodeRecord<T extends NodeLike = NodeLike> = Record<string, T>
+
+/**
+ * Node store that can contain both root-level nodes and scoped node objects.
+ * Structure: { wobble: OperatorNode, fx: { blur: ShaderCallable } }
+ */
+type NodeStore = Record<string, NodeLike | NodeRecord>
+
+//* Storage Types (useGPUStorage) ========================================
+
+/**
+ * GPU storage types for texture-based storage operations.
+ * Includes Three.js storage textures and TSL storage texture nodes.
+ *
+ * @example
+ * ```tsx
+ * const { heightMap } = useGPUStorage(() => ({
+ *   heightMap: new StorageTexture(512, 512),
+ * }), 'terrain')
+ * ```
+ */
+type StorageLike =
+  | StorageTexture // 2D GPU storage texture
+  | Storage3DTexture // 3D GPU storage texture (volumes, fluid grids)
+  | StorageArrayTexture // 2D-array GPU storage texture
+  | Data3DTexture // 3D texture (can be used as storage)
+  | Node // TSL storage texture nodes (storageTexture)
+
+/** Flat record of storage-like values (no nested scopes) */
+type StorageRecord = Record<string, StorageLike>
+
+/**
+ * Storage store that can contain both root-level storage and scoped storage objects.
+ * Structure: { heightMap: StorageTexture, terrain: { normal: StorageTextureNode } }
+ */
+type StorageStore = Record<string, StorageLike | StorageRecord>
+
+/**
+ * The fields @react-three/tsl adds to RootState. Its root extension sets them up on every canvas;
+ * a secondary canvas holds its primary's map objects, and portals inherit them from their parent. So
+ * `state.uniforms` reads the same in useFrame, useThree, creators and handlers, on any canvas.
+ */
+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.
+   */
+  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
+  /** 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. */
+  renderPipeline?: RenderPipeline | null
+  /** Pass nodes registered with useRenderPipeline */
+  passes?: PassRecord
+}
+
+// Every fiber entry shares one core, and so one RootState: augmenting it through the root entry
+// reaches /legacy, /webgpu and /extension as well.
+declare module '@react-three/fiber' {
+  interface RootState extends TSLRootState {}
+}
+
+// /webgpu exports WebGPURootState as RootState. Augmenting the base state it extends reaches both,
+// and also the stores (useStore(), get(), primaryStore) typed with the base.
+declare module '@react-three/fiber/webgpu' {
+  interface BaseRootState extends TSLRootState {}
+}
+
+declare module '@react-three/fiber/extension' {
+  interface RootState extends TSLRootState {}
+}
+
+//* Global TSL Types ==============================
+
+declare global {
+  /**
+   * Broad callable-node fallback for dynamic store readers.
+   * Creator hooks preserve the exact function signatures inferred from Three's `Fn`.
+   */
+  type CallableTSLNode = ((...params: never[]) => unknown) & {
+    readonly shaderNode: unknown
+    readonly id: number
+  }
+
+  /** Legacy structural node accepted when at least one historical marker exists. */
+  type LegacyTSLNodeLike = {
+    label?: ((label: string) => unknown) | string
+    setName?: (name: string) => unknown
+  } & ({ uuid: string | undefined; nodeType?: string | null } | { uuid?: string; nodeType: string | null | undefined })
+
+  /** 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.
+   * Both generics must be inferred because Three's UniformNode intersects an unknown-typed
+   * InputNode base with its concrete InputNode specialization.
+   */
+  type UniformNodeType<T> = T extends three_webgpu.UniformNode<infer TNodeType, infer _TValue>
+    ? TNodeType
+    : T extends three_webgpu.InputNode<infer TNodeType, infer _TValue>
+      ? TNodeType
+      : 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 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>>
+
+  /** Preserve every input key while mapping values to exact Three uniform nodes. */
+  type UniformNodesFor<T extends UniformInputRecord> = {
+    [K in keyof T]: UniformNodeFor<T[K]>
+  }
+
+  /** Backward-compatible single-parameter uniform alias. */
+  type UniformNode<T = unknown> = UniformNodeFor<T>
+
+  /** Flat record of uniform nodes (no nested scopes) */
+  type UniformRecord<T extends UniformNode = UniformNode> = Record<string, T>
+
+  /**
+   * Uniform store that can contain both root-level uniforms and scoped uniform objects
+   * Used by state.uniforms which has structure like:
+   * { uTime: UniformNode, player: { uHealth: UniformNode }, enemy: { uHealth: UniformNode } }
+   */
+  type UniformStore = Record<string, UniformNode | UniformRecord>
+
+  /**
+   * Helper to safely access a uniform node from the store.
+   * Use this when accessing state.uniforms to get proper typing.
+   * @example
+   * const uTime = uniforms.uTime as UniformNode<number>
+   * const uColor = uniforms.uColor as UniformNode<import('three/webgpu').Color>
+   */
+  type GetUniform<T = unknown> = UniformNode<T>
+
+  /**
+   * Acceptable input values for useUniforms - raw values that get converted to UniformNodes
+   * Supports:
+   * - Primitives: number, string (color), boolean
+   * - Three.js types: Color, Vector2/3/4, Matrix2/3/4
+   * - Plain objects: { x, y, z, w } converted to vectors
+   * - TSL nodes: color(), vec3(), float() for type casting
+   * - UniformNode: existing uniforms (reused as-is)
+   */
+  type UniformValue =
+    | number
+    | string
+    | boolean
+    | three_webgpu.Color
+    | three_webgpu.Vector2
+    | three_webgpu.Vector3
+    | three_webgpu.Vector4
+    | three_webgpu.Matrix2
+    | three_webgpu.Matrix3
+    | three_webgpu.Matrix4
+    | { x: number; y: number }
+    | { x: number; y: number; z: number }
+    | { x: number; y: number; z: number; w: number }
+    | { r: number; g: number; b: number; a?: number } // Plain objects converted to Color
+    | three_webgpu.Node // TSL nodes like color(), vec3(), float() for type casting
+    | UniformNode
+
+  /** Input record for useUniforms - accepts raw values or UniformNodes */
+  type UniformInputRecord = Record<string, UniformValue>
+}
+
+declare global {
+  /**
+   * three's own render pipeline type. Named here so the rest of R3F refers to three's shape
+   * rather than `any`. three r183 renamed `PostProcessing` to `RenderPipeline`; our peer floor
+   * is r185, so the new name is the only one.
+   */
+  type ThreeRenderPipeline = three_webgpu.RenderPipeline
+
+  /**
+   * The pass `useRenderPipeline` creates for you: three's own `PassNode`, as returned by
+   * `pass(scene, camera)` from `three/tsl`. Referenced from three so members like
+   * `getTextureNode`, `setMRT` and `dispose` track the installed version.
+   */
+  type ScenePassNode = three_webgpu.PassNode
+
+  /**
+   * Pass record - stores TSL pass nodes for render pipeline.
+   *
+   * `scenePass` is the only key the library owns. It is optional here because this is also the
+   * shape of `state.passes`, which is `{}` before the pipeline exists and again after `reset()`
+   * or `clearPasses()`. Inside the callbacks it is always present; see
+   * {@link RenderPipelineCallbackState}.
+   *
+   * Every other key is user-registered, via a callback's return value. Those are TSL nodes of
+   * any kind, not only passes: texture reads of an MRT attachment, effect nodes, extra
+   * `pass()` instances. `Node` is the common base, so that is the bound. Narrow at the call
+   * site when you need a member, e.g. `passes.velocity as TextureNode`.
+   *
+   * The index signature admits `undefined` because a key may simply not be registered, and
+   * because the optional `scenePass` must be assignable to it: under `skipLibCheck: false` an
+   * optional property whose type excludes `undefined` from the index signature is an error
+   * (TS2411) for every consumer compiling these declarations.
+   */
+  interface PassRecord {
+    scenePass?: ScenePassNode
+    [key: string]: three_webgpu.Node | undefined
+  }
+
+  /**
+   * State passed to pipeline callbacks after the active pipeline has been created.
+   *
+   * `passes.scenePass` is required here: the hook installs the default scene pass before either
+   * callback runs, so callbacks can use it without a guard or a cast.
+   *
+   * `renderer` is narrowed to `WebGPURenderer` and `isLegacy` to `false`: the hook throws under
+   * the legacy renderer before either callback can run, so a callback never sees WebGL.
+   */
+  type RenderPipelineCallbackState = RootState & {
+    renderPipeline: ThreeRenderPipeline
+    passes: PassRecord & { scenePass: ScenePassNode }
+    renderer: three_webgpu.WebGPURenderer
+    isLegacy: false
+  }
+
+  /**
+   * What a callback may return to register entries into `state.passes`.
+   *
+   * `scenePass` is reserved. The hook owns that entry and its lifecycle: it caches the pass it
+   * created, and `rebuild()` / `reset()` dispose that cached pass. A callback overwriting the
+   * store entry would leave the store pointing at a node the hook never disposes, and the hook
+   * disposing a pass nothing references. So returning it is a type error.
+   */
+  type RegisteredPasses = Record<string, three_webgpu.Node> & { scenePass?: never }
+
+  /** Setup callback - runs first to configure MRT, create additional passes */
+  type RenderPipelineSetupCallback = (state: RenderPipelineCallbackState) => RegisteredPasses | void
+
+  /** Main callback - runs second to configure outputNode, create effect passes */
+  type RenderPipelineMainCallback = (state: RenderPipelineCallbackState) => RegisteredPasses | void
+
+  /** The imperative half of useRenderPipeline's return value, present in every state */
+  interface UseRenderPipelineActions {
+    /** Current passes from state */
+    passes: PassRecord
+    /** Clear all passes from state */
+    clearPasses: () => void
+    /** Reset RenderPipeline entirely (clears PP + passes) */
+    reset: () => void
+    /** Re-run setup/main callbacks with current closure values */
+    rebuild: () => void
+  }
+
+  /**
+   * Return type for useRenderPipeline hook, discriminated on `isReady`.
+   *
+   * `if (isReady)` narrows `renderPipeline` to non-null, which is what the docs already tell
+   * callers to check. `passes.scenePass` deliberately stays optional in the ready branch:
+   * `clearPasses()` empties the record while leaving the pipeline in place.
+   */
+  type UseRenderPipelineReturn = UseRenderPipelineActions &
+    (
+      | {
+          /** True when RenderPipeline is configured and ready */
+          isReady: true
+          /** RenderPipeline instance */
+          renderPipeline: ThreeRenderPipeline
+        }
+      | {
+          /** False until the pipeline has been created */
+          isReady: false
+          /** Not initialized yet, or torn down by reset() */
+          renderPipeline: null
+        }
+    )
+}
+
+/** Distinguishes a resource leaf from a nested resource scope. */
+type ResourceLeafGuard<T> = (value: unknown) => value is T;
+
+/**
+ * ScopedStore - Type-safe wrapper for nested stores (uniforms, nodes)
+ *
+ * Provides TypeScript-friendly access to uniform/node stores where the runtime
+ * structure is `Record<string, T | Record<string, T>>` (leaf nodes or nested scopes).
+ *
+ * The wrapper uses a Proxy to:
+ * 1. Return `T` for property access (type assumption: assumes leaf node)
+ * 2. Provide `.scope(key)` method for explicit nested access
+ * 3. Support iteration methods: has(), keys(), Object.keys(), for...in
+ *
+ * @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)),
+ *   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) }
+ * }, [])
+ * ```
+ */
+
+/**
+ * Type-safe wrapper interface for accessing nested store data.
+ * Property access returns `T` (assumes leaf node).
+ * Use `.scope(key)` for nested object access.
+ *
+ */
+type ScopedStoreMethods<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>;
+    /** 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>;
+interface ScopedStoreData<TLeaf> {
+    [key: string]: TLeaf | ScopedStoreData<TLeaf>;
+}
+/**
+ * Create a type-safe ScopedStore wrapper around store data.
+ * @param data - The raw store data (uniforms or nodes from RootState)
+ * @returns A ScopedStoreType wrapper with type-safe access
+ */
+declare function createScopedStore<TLeaf>(data: ScopedStoreData<TLeaf>, isLeaf: ResourceLeafGuard<TLeaf>): ScopedStoreType<TLeaf>;
+/**
+ * State type passed to creator functions with ScopedStore wrappers.
+ * Provides type-safe access to uniforms, nodes, buffers, and gpuStorage without manual casting.
+ */
+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>;
+};
+
+/**
+ * @fileoverview Typed uniforms by registration (the TanStack Router `Register` pattern).
+ *
+ * Nothing registered: every type below falls back to the loose shapes the hooks have always had.
+ * Registered once, anywhere in the app:
+ *
+ * ```ts
+ * export const globalUniforms = { uTime: 0, uColor: new Color('hotpink') }
+ * export const playerUniforms = { uHealth: 1 }
+ *
+ * declare module '@react-three/tsl' {
+ *   interface Register {
+ *     uniforms: typeof globalUniforms
+ *     scopes: { player: typeof playerUniforms }
+ *     // strict: false  // unregistered root keys become loose instead of errors
+ *   }
+ * }
+ *
+ * configureTSL({ uniforms: globalUniforms, scopes: { player: playerUniforms } })
+ * ```
+ *
+ * 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.
+ */
+
+/**
+ * Augment this to type uniforms 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)
+ */
+interface Register {
+}
+/** The registered root-level uniform inputs, or `{}` when nothing is registered. */
+type RegisteredUniforms = Register extends {
+    uniforms: infer U extends UniformInputRecord;
+} ? U : {};
+/** The registered scopes and their inputs, or `{}` when nothing is registered. */
+type RegisteredScopes = Register extends {
+    scopes: infer S extends Record<string, UniformInputRecord>;
+} ? S : {};
+type IsRegistered = Register extends {
+    uniforms: any;
+} | {
+    scopes: any;
+} ? true : false;
+type IsStrict = Register extends {
+    strict: false;
+} ? false : true;
+type TypedUniforms = UniformNodesFor<RegisteredUniforms> & {
+    [K in keyof RegisteredScopes]: UniformNodesFor<RegisteredScopes[K]>;
+};
+/**
+ * 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.
+ */
+type AppUniforms = IsRegistered extends true ? IsStrict extends true ? TypedUniforms : TypedUniforms & UniformStore : UniformStore;
+/** 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. */
+type ScopeUniformInput<S extends string> = S extends keyof RegisteredScopes ? Partial<RegisteredScopes[S]> : unknown;
+/** A registered scope's uniform nodes. */
+type RegisteredScopeUniforms<S extends keyof RegisteredScopes> = UniformNodesFor<RegisteredScopes[S]>;
+/** 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
+ * 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>;
+
+/** Uniforms that exist on every primary canvas from the start. See configureTSL. */
+interface TSLConfig {
+    /** Root-level uniform inputs, e.g. the object you registered as `Register['uniforms']` */
+    uniforms?: UniformInputRecord;
+    /** Scoped uniform inputs, e.g. the object you registered as `Register['scopes']` */
+    scopes?: Record<string, UniformInputRecord>;
+}
+/**
+ * Create uniforms on every primary canvas up front -- the runtime half of `Register`. Pass the same
+ * objects you registered, so the registered types are true before the first frame:
+ *
+ * ```ts
+ * configureTSL({ uniforms: globalUniforms, scopes: { player: playerUniforms } })
+ * ```
+ *
+ * They land on the primary canvas's RootState, so `state.uniforms` has them on the primary, its
+ * secondaries and every portal. Applies to canvases already mounted and to every canvas mounted
+ * later. Calling it again adds to the configuration; uniforms that already exist are never
+ * replaced. Optional: without it, a uniform exists once some component creates it.
+ */
+declare function configureTSL(next: TSLConfig): void;
+
+/** Creator function that returns uniform inputs (can be raw values or UniformNodes) */
+type UniformCreator<T extends UniformInputRecord = UniformInputRecord> = (state: CreatorState) => T;
+/** Function signature for removeUniforms util */
+type RemoveUniformsFn = (names: string | string[], scope?: string) => void;
+/** Function signature for clearUniforms util */
+type ClearUniformsFn = (scope?: string) => void;
+/** Function signature for rebuildUniforms util */
+type RebuildUniformsFn = (scope?: string) => void;
+/** Return type with utils included */
+type UniformsWithUtils<T extends UniformRecord | UniformStore = UniformRecord> = T & {
+    removeUniforms: RemoveUniformsFn;
+    clearUniforms: ClearUniformsFn;
+    rebuildUniforms: RebuildUniformsFn;
+};
+declare function useUniforms<T extends RootUniformInput>(creator: UniformCreator<T>): UniformsWithUtils<UniformNodesFor<T>>;
+declare function useUniforms<T extends UniformInputRecord, S extends string>(creator: (state: CreatorState) => T & ScopeUniformInput<S>, scope: S): UniformsWithUtils<UniformNodesFor<T>>;
+declare function useUniforms<T extends RootUniformInput>(uniforms: T): UniformsWithUtils<UniformNodesFor<T>>;
+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>>;
+/**
+ * Global rebuildUniforms function for HMR integration.
+ * Invalidates cached uniforms and increments _hmrVersion to trigger re-creation.
+ * Call this when HMR is detected to refresh all uniform creators.
+ *
+ * Resolves to the primary store so shared TSL resources rebuild on the
+ * authoritative store.
+ *
+ * @param store - The R3F store (from useStore or context)
+ * @param scope - Optional scope to rebuild ('root' for root only, string for specific scope, undefined for all)
+ */
+declare function rebuildAllUniforms(store: ReturnType<typeof useStore>, scope?: string): void;
+
+/**
+ * Supported uniform value types:
+ * - Raw values: number, boolean, Vector2, Vector3, Vector4, Color, Matrix2, Matrix3, Matrix4
+ * - String colors: '#ff0000', 'red', 'rgb(255,0,0)' (auto-converted to Color)
+ * - TSL nodes: color(), vec3(), float(), etc. (for type casting)
+ * - UniformNode: existing uniforms (reused as-is)
+ */
+type UniformValue = number | boolean | string | Vector2 | Vector3 | Vector4 | Color | Matrix2 | Matrix3 | Matrix4 | Node | UniformNode;
+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>(name: string, value: T): UniformNodeFor<T>;
+
+/**
+ * Every node representation a creator may return. The definition lives with the store types as
+ * `NodeLike`, so the shape creators return and the shape `state.nodes` holds are one type by
+ * construction: three's real `Node`, the callable proxy `Fn()` returns, or the legacy structural
+ * `{ uuid, nodeType }` shape.
+ */
+type TSLNodeLike = NodeLike;
+
+/** Backward-compatible alias covering every accepted node representation. */
+type TSLNode = TSLNodeLike;
+/**
+ * Creator function that returns a record of nodes.
+ * Exact creator return inference is preserved within the compatible node constraint.
+ */
+type NodeCreator<T extends Record<string, TSLNodeLike>> = (state: CreatorState) => T;
+/** Function signature for removeNodes util */
+type RemoveNodesFn = (names: string | string[], scope?: string) => void;
+/** Function signature for clearNodes util */
+type ClearNodesFn = (scope?: string) => void;
+/** Function signature for rebuildNodes util */
+type RebuildNodesFn = (scope?: string) => void;
+/** Return type with utils included */
+type NodesWithUtils<T extends Record<string, unknown> = NodeRecord> = T & {
+    removeNodes: RemoveNodesFn;
+    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>>;
+/**
+ * Global rebuildNodes function for HMR integration.
+ * Invalidates cached nodes and increments _hmrVersion to trigger re-creation.
+ * Call this when HMR is detected to refresh all node creators.
+ *
+ * Resolves to the primary store so shared TSL resources rebuild on the
+ * authoritative store.
+ *
+ * @param store - The R3F store (from useStore or context)
+ * @param scope - Optional scope to rebuild ('root' for root only, string for specific scope, undefined for all)
+ */
+declare function rebuildAllNodes(store: ReturnType<typeof useStore>, scope?: string): void;
+
+/** Creator receives CreatorState with ScopedStore wrappers for type-safe access. Returns any record. */
+type LocalNodeCreator<T extends Record<string, unknown>> = (state: CreatorState) => T;
+/**
+ * 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`:
+ *
+ * | 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
+ * // 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
+ * }), [])
+ *
+ * // `pattern` picks which node the graph is built from: a structural input.
+ * const { result } = useLocalNodes(({ nodes }) => ({
+ *   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) }
+ * }, [])
+ * ```
+ */
+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)
+ */
+type BufferRecordType<T extends BufferLike = BufferLike> = Record<string, T>;
+/**
+ * Creator function that returns a record of buffers.
+ * Receives CreatorState with access to existing buffers, gpuStorage, uniforms, nodes, etc.
+ */
+type BufferCreator<T extends Record<string, BufferLike>> = (state: CreatorState) => T;
+/** Function signature for removeBuffers util */
+type RemoveBuffersFn = (names: string | string[], scope?: string) => void;
+/** Function signature for clearBuffers util */
+type ClearBuffersFn = (scope?: string) => void;
+/** Function signature for rebuildBuffers util */
+type RebuildBuffersFn = (scope?: string) => void;
+/** Function signature for disposeBuffers util - releases GPU resources */
+type DisposeBuffersFn = (names: string | string[], scope?: string) => void;
+/** Return type with utils included */
+type BuffersWithUtils<T extends BufferRecordType | BufferStore = BufferRecordType> = T & {
+    removeBuffers: RemoveBuffersFn;
+    clearBuffers: ClearBuffersFn;
+    rebuildBuffers: RebuildBuffersFn;
+    disposeBuffers: DisposeBuffersFn;
+};
+declare function useBuffers(): BuffersWithUtils<BufferStore>;
+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>;
+/**
+ * Global rebuildBuffers function for HMR integration.
+ * Invalidates cached buffers and increments _hmrVersion to trigger re-creation.
+ * Call this when HMR is detected to refresh all buffer creators.
+ *
+ * Resolves to the primary store so shared TSL resources rebuild on the
+ * authoritative store.
+ *
+ * @param store - The R3F store (from useStore or context)
+ * @param scope - Optional scope to rebuild ('root' for root only, string for specific scope, undefined for all)
+ */
+declare function rebuildAllBuffers(store: ReturnType<typeof useStore>, scope?: string): void;
+
+/**
+ * A record of storage-like values - allows mixed types (StorageTexture, Storage3DTexture, TSL nodes)
+ */
+type StorageRecordType<T extends StorageLike = StorageLike> = Record<string, T>;
+/**
+ * Creator function that returns a record of GPU storage objects.
+ * Receives CreatorState with access to existing buffers, gpuStorage, uniforms, nodes, etc.
+ */
+type StorageCreator<T extends Record<string, StorageLike>> = (state: CreatorState) => T;
+/** Function signature for removeStorage util */
+type RemoveStorageFn = (names: string | string[], scope?: string) => void;
+/** Function signature for clearStorage util */
+type ClearStorageFn = (scope?: string) => void;
+/** Function signature for rebuildStorage util */
+type RebuildStorageFn = (scope?: string) => void;
+/** Function signature for disposeStorage util - releases GPU resources */
+type DisposeStorageFn = (names: string | string[], scope?: string) => void;
+/** Return type with utils included */
+type StorageWithUtils<T extends StorageRecordType | StorageStore = StorageRecordType> = T & {
+    removeStorage: RemoveStorageFn;
+    clearStorage: ClearStorageFn;
+    rebuildStorage: RebuildStorageFn;
+    disposeStorage: DisposeStorageFn;
+};
+declare function useGPUStorage(): StorageWithUtils<StorageStore>;
+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>;
+/**
+ * Global rebuildStorage function for HMR integration.
+ * Invalidates cached storage and increments _hmrVersion to trigger re-creation.
+ * Call this when HMR is detected to refresh all storage creators.
+ *
+ * Resolves to the primary store so shared TSL resources rebuild on the
+ * authoritative store.
+ *
+ * @param store - The R3F store (from useStore or context)
+ * @param scope - Optional scope to rebuild ('root' for root only, string for specific scope, undefined for all)
+ */
+declare function rebuildAllStorage(store: ReturnType<typeof useStore>, scope?: string): void;
+
+/**
+ * Hook for managing WebGPU RenderPipeline with automatic scenePass setup.
+ *
+ * Features:
+ * - Creates RenderPipeline instance if not exists
+ * - Creates default scenePass (no MRT) automatically
+ * - Callbacks receive full RootState for flexibility
+ * - No auto-cleanup on unmount - use reset() for explicit cleanup
+ * - Scene/camera changes trigger scenePass recreation
+ * - A replaced scenePass is disposed once the new graph is installed, so rebuild() does not
+ *   strand its render target (and MRT attachments) on the GPU
+ * - Any run that changes the output node sets RenderPipeline.needsUpdate, so rebuild() actually
+ *   recompiles instead of silently keeping the first compiled graph
+ *
+ * @param mainCB - Main callback to configure outputNode and create effect passes
+ * @param setupCB - Optional setup callback to configure MRT on scenePass
+ * @returns { passes, renderPipeline, clearPasses, reset, rebuild }
+ *
+ * @example
+ * ```tsx
+ * // Simple effect
+ * useRenderPipeline(({ renderPipeline, passes }) => {
+ *   renderPipeline.outputNode = bloom(passes.scenePass.getTextureNode())
+ * })
+ *
+ * // With MRT setup
+ * useRenderPipeline(
+ *   ({ renderPipeline, passes }) => {
+ *     const beauty = passes.scenePass.getTextureNode().toInspector('Color')
+ *     const vel = passes.scenePass.getTextureNode('velocity')
+ *     renderPipeline.outputNode = motionBlur(beauty, vel)
+ *   },
+ *   ({ passes }) => {
+ *     passes.scenePass.setMRT(mrt({ output, velocity }))
+ *   }
+ * )
+ *
+ * // Read-only access
+ * const { renderPipeline, passes } = useRenderPipeline()
+ * ```
+ */
+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 };