@react-three/tsl 10.0.0-canary.975e1e7 → 10.0.0-canary.a9bd42a

package/dist/index.cjs

@@ -312,33 +312,129 @@ function ensureTSLExtension() {
   });
 }
 
+const SCOPE = Symbol("readTracking.scope");
+const LEAF_GUARDS = {
+  uniforms: isUniformNode,
+  nodes: isTSLNode,
+  buffers: isBufferLike,
+  gpuStorage: isStorageLike
+};
+function isScope(kind, value) {
+  return !!value && typeof value === "object" && !LEAF_GUARDS[kind](value);
+}
+function classify(kind, value) {
+  return kind !== "textures" && isScope(kind, value) ? SCOPE : value;
+}
+function resolveContainer(kind, root, scopePath) {
+  let container = root;
+  for (const key of scopePath) {
+    const next = container?.[key];
+    container = isScope(kind, next) ? next : void 0;
+  }
+  return container;
+}
+function observeNow(read, view) {
+  if (read.kind === "textures") {
+    const map = view("textures");
+    if (read.op === "keys") return [...map.keys()];
+    return read.op === "has" ? map.has(read.path[0]) : map.get(read.path[0]);
+  }
+  const root = view(read.kind);
+  if (read.op === "keys") return Object.keys(resolveContainer(read.kind, root, read.path) ?? {});
+  const container = resolveContainer(read.kind, root, read.path.slice(0, -1));
+  const key = read.path[read.path.length - 1];
+  if (read.op === "has") return !!container && key in container;
+  return classify(read.kind, container?.[key]);
+}
+function sameKeys(a, b) {
+  return a.length === b.length && a.every((key, i) => key === b[i]);
+}
+function hasChanged(read, view) {
+  const now = observeNow(read, view);
+  return read.op === "keys" ? !sameKeys(read.seen, now) : !Object.is(read.seen, now);
+}
+const warned = /* @__PURE__ */ new Set();
+function warnOnce(message) {
+  if (typeof process !== "undefined" && process.env.NODE_ENV === "production") return;
+  if (warned.has(message)) return;
+  warned.add(message);
+  console.warn(message);
+}
+function describeRead(kind, path) {
+  if (kind === "textures") return `textures.get('${path[0]}')`;
+  const scopes = path.slice(0, -1).map((key) => `.scope('${key}')`);
+  return `${kind}${scopes.join("")}.${path[path.length - 1] ?? ""}`;
+}
+function createReadTracker(hookName) {
+  const tracker = {
+    reads: [],
+    closed: false,
+    stale: false,
+    observe: (read) => {
+      if (tracker.closed) {
+        warnOnce(
+          `[${hookName}] ${describeRead(read.kind, read.path)} was read after the creator returned, probably inside Fn(). That read is not tracked, so replacing the resource will not rebuild this graph. Read the resource in the creator and close over it in Fn.`
+        );
+        return;
+      }
+      tracker.reads.push(read);
+    }
+  };
+  return tracker;
+}
+function isTrackerStale(tracker, view) {
+  if (!tracker.stale) tracker.stale = tracker.reads.some((read) => hasChanged(read, view));
+  return tracker.stale;
+}
+function warnMissingReads(hookName) {
+  return {
+    nested: false,
+    observe: (read) => {
+      if (read.op !== "get" || read.seen !== void 0) return;
+      warnOnce(
+        `[${hookName}] The creator read ${describeRead(read.kind, read.path)}, which does not exist yet. ${hookName} creators run once per generation, so this one will not re-run when it appears. Register it earlier (above this hook, or higher in the tree), or call rebuild* once it exists. To probe on purpose, use .has().`
+      );
+    }
+  };
+}
+
 var __defProp = Object.defineProperty;
 var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
 var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
-var _a, _b;
+var _a, _b, _c, _d;
 const INTERNAL_DATA = Symbol("ScopedStore.data");
 const INTERNAL_IS_LEAF = Symbol("ScopedStore.isLeaf");
-_b = INTERNAL_DATA, _a = INTERNAL_IS_LEAF;
+const INTERNAL_READS = Symbol("ScopedStore.reads");
+const INTERNAL_CHILDREN = Symbol("ScopedStore.children");
+_d = INTERNAL_DATA, _c = INTERNAL_IS_LEAF, _b = INTERNAL_READS, _a = INTERNAL_CHILDREN;
 const _ScopedStore = class _ScopedStore {
-  constructor(data, isLeaf) {
+  constructor(data, isLeaf, reads) {
+    /** @internal */
+    __publicField(this, _d);
+    /** @internal */
+    __publicField(this, _c);
+    /** @internal */
     __publicField(this, _b);
+    /** @internal */
     __publicField(this, _a);
     this[INTERNAL_DATA] = data;
     this[INTERNAL_IS_LEAF] = isLeaf;
+    this[INTERNAL_READS] = reads;
     return new Proxy(this, {
       get(target, prop, receiver) {
         if (typeof prop === "string") {
           if (prop === "scope" || prop === "has" || prop === "keys") {
             return Reflect.get(target, prop, receiver);
           }
-          return target[INTERNAL_DATA][prop];
+          return readEntry(target, prop);
         }
         return Reflect.get(target, prop, receiver);
       },
       has(target, prop) {
-        return typeof prop === "string" ? prop in target[INTERNAL_DATA] : Reflect.has(target, prop);
+        return typeof prop === "string" ? target.has(prop) : Reflect.has(target, prop);
       },
       ownKeys(target) {
+        observeKeys(target);
         return Reflect.ownKeys(target[INTERNAL_DATA]);
       },
       getOwnPropertyDescriptor(target, prop) {
@@ -360,54 +456,152 @@ const _ScopedStore = class _ScopedStore {
   scope(key) {
     const value = this[INTERNAL_DATA][key];
     const isLeaf = this[INTERNAL_IS_LEAF];
+    const reads = this[INTERNAL_READS];
     const scope = value && typeof value === "object" && !isLeaf(value) ? value : {};
-    return new _ScopedStore(scope, isLeaf);
+    const child = reads ? { ...reads, path: [...reads.path, key] } : void 0;
+    return new _ScopedStore(scope, isLeaf, child);
   }
   /**
    * Check if a key exists in the store.
    */
   has(key) {
-    return key in this[INTERNAL_DATA];
+    const found = key in this[INTERNAL_DATA];
+    const reads = this[INTERNAL_READS];
+    reads?.observe({ kind: reads.kind, op: "has", path: [...reads.path, key], seen: found });
+    return found;
   }
   /**
    * Get all keys in the store.
    */
   keys() {
+    observeKeys(this);
     return Object.keys(this[INTERNAL_DATA]);
   }
 };
 let ScopedStore = _ScopedStore;
+function readEntry(target, key) {
+  const value = target[INTERNAL_DATA][key];
+  const reads = target[INTERNAL_READS];
+  if (!reads) return value;
+  const isLeaf = target[INTERNAL_IS_LEAF];
+  const isScope = !!value && typeof value === "object" && !isLeaf(value);
+  const path = [...reads.path, key];
+  reads.observe({ kind: reads.kind, op: "get", path, seen: isScope ? SCOPE : value });
+  if (!isScope || !reads.nested) return value;
+  const children = target[INTERNAL_CHILDREN] ?? (target[INTERNAL_CHILDREN] = /* @__PURE__ */ new Map());
+  let child = children.get(key);
+  if (!child) {
+    child = new ScopedStore(value, isLeaf, { ...reads, path });
+    children.set(key, child);
+  }
+  return child;
+}
+function observeKeys(target) {
+  const reads = target[INTERNAL_READS];
+  reads?.observe({ kind: reads.kind, op: "keys", path: reads.path, seen: Object.keys(target[INTERNAL_DATA]) });
+}
 function createScopedStore(data, isLeaf) {
   return new ScopedStore(data, isLeaf);
 }
-function createLazyCreatorState(state, store) {
+function observeTextures(map, observe) {
+  const observeKeys2 = () => observe({ kind: "textures", op: "keys", path: [], seen: [...map.keys()] });
+  const observeAll = () => {
+    observeKeys2();
+    for (const [url, texture] of map) observe({ kind: "textures", op: "get", path: [url], seen: texture });
+  };
+  return new Proxy(map, {
+    get(target, prop) {
+      switch (prop) {
+        case "get":
+          return (url) => {
+            const texture = target.get(url);
+            observe({ kind: "textures", op: "get", path: [url], seen: texture });
+            return texture;
+          };
+        case "has":
+          return (url) => {
+            const found = target.has(url);
+            observe({ kind: "textures", op: "has", path: [url], seen: found });
+            return found;
+          };
+        case "size":
+          observeKeys2();
+          return target.size;
+        case "keys":
+          return () => {
+            observeKeys2();
+            return target.keys();
+          };
+        case "values":
+          return () => {
+            observeAll();
+            return target.values();
+          };
+        case "entries":
+        case Symbol.iterator:
+          return () => {
+            observeAll();
+            return target.entries();
+          };
+        case "forEach":
+          return (callback, thisArg) => {
+            observeAll();
+            target.forEach(callback, thisArg);
+          };
+      }
+      const value = Reflect.get(target, prop, target);
+      return typeof value === "function" ? value.bind(target) : value;
+    }
+  });
+}
+function createResourceView(primary, local = primary) {
+  return ((kind) => kind === "textures" ? extension.getTextureView(local) : withStagedOverlay(primary, kind, primary.getState()[kind]));
+}
+function createLazyCreatorState(state, store, options = {}) {
+  const { reads } = options;
+  const view = options.view ?? (store ? createResourceView(store) : void 0);
   let _uniforms = null;
   let _nodes = null;
   let _buffers = null;
   let _gpuStorage = null;
-  const view = (kind) => store ? withStagedOverlay(store, kind, state[kind]) : state[kind];
-  return Object.create(state, {
+  let _textures = null;
+  const read = (kind) => view ? view(kind) : state[kind];
+  const wrap = (kind, isLeaf) => new ScopedStore(
+    read(kind),
+    isLeaf,
+    reads && { ...reads, kind, path: [] }
+  );
+  const properties = {
     uniforms: {
       get() {
-        return _uniforms ?? (_uniforms = createScopedStore(view("uniforms"), isUniformNode));
+        return _uniforms ?? (_uniforms = wrap("uniforms", isUniformNode));
       }
     },
     nodes: {
       get() {
-        return _nodes ?? (_nodes = createScopedStore(view("nodes"), isTSLNode));
+        return _nodes ?? (_nodes = wrap("nodes", isTSLNode));
       }
     },
     buffers: {
       get() {
-        return _buffers ?? (_buffers = createScopedStore(view("buffers"), isBufferLike));
+        return _buffers ?? (_buffers = wrap("buffers", isBufferLike));
       }
     },
     gpuStorage: {
       get() {
-        return _gpuStorage ?? (_gpuStorage = createScopedStore(view("gpuStorage"), isStorageLike));
+        return _gpuStorage ?? (_gpuStorage = wrap("gpuStorage", isStorageLike));
       }
     }
-  });
+  };
+  if (options.view) {
+    properties.textures = {
+      get() {
+        const textures = options.view("textures");
+        return _textures ?? (_textures = reads ? observeTextures(textures, reads.observe) : textures);
+      }
+    };
+  }
+  return Object.create(state, properties);
 }
 
 function resolvePrimary(local) {
@@ -483,7 +677,7 @@ function useUniforms(creatorOrScope, scope) {
   const processedInput = React.useMemo(() => {
     let raw = creatorOrScope;
     if (typeof creatorOrScope === "function") {
-      const wrappedState = createLazyCreatorState(store.getState(), store);
+      const wrappedState = createLazyCreatorState(store.getState(), store, { reads: warnMissingReads("useUniforms") });
       raw = creatorOrScope(wrappedState);
     }
     if (raw && typeof raw === "object" && !Array.isArray(raw)) {
@@ -626,7 +820,16 @@ function useNodes(creatorOrScope, scope) {
     isLeaf: isTSLNode,
     create: () => {
       if (isReader) return {};
-      return creatorOrScope(createLazyCreatorState(store.getState(), store));
+      const nodes2 = creatorOrScope(
+        createLazyCreatorState(store.getState(), store, { reads: warnMissingReads("useNodes") })
+      );
+      if (nodes2 == null) {
+        warnOnce(
+          "[useNodes] The creator returned nothing, so nothing was registered. useNodes registers the nodes its creator returns. To put a node onto a Three object (scene.fogNode = ...), use useLocalNodes and return a function that assigns it: it runs after commit and may return a cleanup."
+        );
+        return {};
+      }
+      return nodes2;
     },
     prepare: (name, node) => {
       const setName = Reflect.get(node, "setName");
@@ -646,16 +849,100 @@ function useNodes(creatorOrScope, scope) {
 function rebuildAllNodes(store, scope) {
   rebuildResource(store, "nodes", scope);
 }
-function useLocalNodes(creator) {
+function areDepsEqual(next, prev) {
+  if (next.length !== prev.length) return false;
+  for (let i = 0; i < next.length; i++) if (!Object.is(next[i], prev[i])) return false;
+  return true;
+}
+function useDependencyToken(deps) {
+  const previous = React.useRef(null);
+  const record = previous.current;
+  if (typeof process !== "undefined" && process.env.NODE_ENV !== "production" && record) {
+    const hadDeps = record.deps !== void 0;
+    const hasDeps = deps !== void 0;
+    if (hadDeps !== hasDeps) {
+      console.warn(
+        `[useLocalNodes] The dependency array was ${hasDeps ? "added" : "omitted"} between renders. Pass an array on every render or on none; the mode must not change for a mounted component.`
+      );
+    } else if (hasDeps && record.deps.length !== deps.length) {
+      console.warn(
+        `[useLocalNodes] The dependency array length changed between renders (${record.deps.length} \u2192 ${deps.length}). Declare a fixed-length list; conditional dependencies belong inside the array as values.`
+      );
+    }
+  }
+  if (deps === void 0) {
+    previous.current = { deps: void 0, token: {} };
+  } else if (!record || record.deps === void 0 || !areDepsEqual(deps, record.deps)) {
+    previous.current = { deps, token: {} };
+  } else if (record.deps !== deps) {
+    previous.current = { deps, token: record.token };
+  }
+  return previous.current.token;
+}
+function useLocalNodes(creator, deps) {
+  const local = extension.useStore();
   const store = usePrimaryStore();
-  const uniforms = usePrimaryThree((s) => s.uniforms);
-  const nodes = usePrimaryThree((s) => s.nodes);
-  const textures = usePrimaryThree((s) => s.textures);
+  const view = React.useMemo(() => createResourceView(store, local), [store, local]);
   const hmrVersion = usePrimaryThree((s) => s._hmrVersion);
-  return React.useMemo(() => {
-    const wrappedState = createLazyCreatorState(store.getState(), store);
-    return creator(wrappedState);
-  }, [store, creator, uniforms, nodes, textures, hmrVersion]);
+  const depsToken = useDependencyToken(deps);
+  const committedReads = React.useRef(null);
+  const readsVersion = React.useRef(0);
+  const getReadsVersion = () => {
+    const tracker2 = committedReads.current;
+    if (tracker2 && !tracker2.stale && isTrackerStale(tracker2, view)) readsVersion.current++;
+    return readsVersion.current;
+  };
+  const subscribe = React.useCallback(
+    (onChange) => {
+      const unsubscribe = store.subscribe(onChange);
+      if (local === store) return unsubscribe;
+      const unsubscribeLocal = local.subscribe(onChange);
+      return () => {
+        unsubscribe();
+        unsubscribeLocal();
+      };
+    },
+    [store, local]
+  );
+  const resourceVersion = React.useSyncExternalStore(subscribe, getReadsVersion, getReadsVersion);
+  const evaluation = React.useMemo(() => {
+    const tracker2 = createReadTracker("useLocalNodes");
+    const reads = { observe: tracker2.observe, nested: true };
+    const value2 = creator(createLazyCreatorState(local.getState(), store, { reads, view }));
+    tracker2.closed = true;
+    return { value: value2, tracker: tracker2 };
+  }, [view, hmrVersion, depsToken, resourceVersion]);
+  const { value, tracker } = evaluation;
+  const installing = typeof value === "function";
+  useModeDiagnostics(value, installing);
+  useIsomorphicLayoutEffect(() => {
+    committedReads.current = tracker;
+    if (!installing) return;
+    tracker.closed = false;
+    let cleanup;
+    try {
+      cleanup = value();
+    } finally {
+      tracker.closed = true;
+    }
+    return typeof cleanup === "function" ? cleanup : void 0;
+  }, [evaluation]);
+  return installing ? void 0 : value;
+}
+function useModeDiagnostics(value, installing) {
+  const previous = React.useRef(null);
+  if (typeof process !== "undefined" && process.env.NODE_ENV === "production") return;
+  if (value === void 0 || value === null) {
+    warnOnce(
+      "[useLocalNodes] The creator returned nothing. To put a node onto a Three object (scene.fogNode = ...), build it in the creator and return a function that assigns it: that function runs after commit and may return a cleanup. Assigning inside the creator runs during render, which React may discard or repeat."
+    );
+  }
+  if (previous.current !== null && previous.current !== installing) {
+    warnOnce(
+      "[useLocalNodes] The creator switched between returning a record and returning an install function. Keep one form for a mounted component."
+    );
+  }
+  previous.current = installing;
 }
 
 const disposeBuffer = (buffer) => {
@@ -701,7 +988,9 @@ function useBuffers(creatorOrScope, scope) {
     isLeaf: isBufferLike,
     create: () => {
       if (isReader) return {};
-      return creatorOrScope(createLazyCreatorState(store.getState(), store));
+      return creatorOrScope(
+        createLazyCreatorState(store.getState(), store, { reads: warnMissingReads("useBuffers") })
+      );
     },
     prepare: (name, buffer) => {
       const setName = Reflect.get(buffer, "setName");
@@ -765,7 +1054,9 @@ function useGPUStorage(creatorOrScope, scope) {
     isLeaf: isStorageLike,
     create: () => {
       if (isReader) return {};
-      return creatorOrScope(createLazyCreatorState(store.getState(), store));
+      return creatorOrScope(
+        createLazyCreatorState(store.getState(), store, { reads: warnMissingReads("useGPUStorage") })
+      );
     },
     prepare: (name, storage) => {
       const label = scopedNodeName(scope, name);

package/dist/index.d.cts

@@ -381,10 +381,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 +626,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`:
+ *
+ * | 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.
  *
- * Unlike `useNodes`, this does NOT register to the global store.
- * Use for component-specific nodes/values that depend on shared resources.
+ * 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 +830,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 };

package/dist/index.d.mts

@@ -381,10 +381,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 +626,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`:
+ *
+ * | 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.
  *
- * Unlike `useNodes`, this does NOT register to the global store.
- * Use for component-specific nodes/values that depend on shared resources.
+ * 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 +830,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 };

package/dist/index.d.ts

@@ -381,10 +381,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 +626,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`:
+ *
+ * | 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.
  *
- * Unlike `useNodes`, this does NOT register to the global store.
- * Use for component-specific nodes/values that depend on shared resources.
+ * 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 +830,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 };

package/dist/index.mjs

@@ -1,9 +1,9 @@
-import { registerRootExtension, useStore, useThree, setRenderOverride } from '@react-three/fiber/extension';
+import { registerRootExtension, getTextureView, useStore, useThree, setRenderOverride } from '@react-three/fiber/extension';
 import { uniform, pass } from 'three/tsl';
 import * as THREE from 'three/webgpu';
 import { Color } from 'three/webgpu';
 import * as React from 'react';
-import { useMemo, useRef, useCallback, useState, useEffect, useLayoutEffect } from 'react';
+import { useMemo, useRef, useCallback, useSyncExternalStore, useState, useEffect, useLayoutEffect } from 'react';
 import { dequal } from 'dequal/lite';
 import 'zustand/shallow';
 
@@ -297,33 +297,129 @@ function ensureTSLExtension() {
   });
 }
 
+const SCOPE = Symbol("readTracking.scope");
+const LEAF_GUARDS = {
+  uniforms: isUniformNode,
+  nodes: isTSLNode,
+  buffers: isBufferLike,
+  gpuStorage: isStorageLike
+};
+function isScope(kind, value) {
+  return !!value && typeof value === "object" && !LEAF_GUARDS[kind](value);
+}
+function classify(kind, value) {
+  return kind !== "textures" && isScope(kind, value) ? SCOPE : value;
+}
+function resolveContainer(kind, root, scopePath) {
+  let container = root;
+  for (const key of scopePath) {
+    const next = container?.[key];
+    container = isScope(kind, next) ? next : void 0;
+  }
+  return container;
+}
+function observeNow(read, view) {
+  if (read.kind === "textures") {
+    const map = view("textures");
+    if (read.op === "keys") return [...map.keys()];
+    return read.op === "has" ? map.has(read.path[0]) : map.get(read.path[0]);
+  }
+  const root = view(read.kind);
+  if (read.op === "keys") return Object.keys(resolveContainer(read.kind, root, read.path) ?? {});
+  const container = resolveContainer(read.kind, root, read.path.slice(0, -1));
+  const key = read.path[read.path.length - 1];
+  if (read.op === "has") return !!container && key in container;
+  return classify(read.kind, container?.[key]);
+}
+function sameKeys(a, b) {
+  return a.length === b.length && a.every((key, i) => key === b[i]);
+}
+function hasChanged(read, view) {
+  const now = observeNow(read, view);
+  return read.op === "keys" ? !sameKeys(read.seen, now) : !Object.is(read.seen, now);
+}
+const warned = /* @__PURE__ */ new Set();
+function warnOnce(message) {
+  if (typeof process !== "undefined" && process.env.NODE_ENV === "production") return;
+  if (warned.has(message)) return;
+  warned.add(message);
+  console.warn(message);
+}
+function describeRead(kind, path) {
+  if (kind === "textures") return `textures.get('${path[0]}')`;
+  const scopes = path.slice(0, -1).map((key) => `.scope('${key}')`);
+  return `${kind}${scopes.join("")}.${path[path.length - 1] ?? ""}`;
+}
+function createReadTracker(hookName) {
+  const tracker = {
+    reads: [],
+    closed: false,
+    stale: false,
+    observe: (read) => {
+      if (tracker.closed) {
+        warnOnce(
+          `[${hookName}] ${describeRead(read.kind, read.path)} was read after the creator returned, probably inside Fn(). That read is not tracked, so replacing the resource will not rebuild this graph. Read the resource in the creator and close over it in Fn.`
+        );
+        return;
+      }
+      tracker.reads.push(read);
+    }
+  };
+  return tracker;
+}
+function isTrackerStale(tracker, view) {
+  if (!tracker.stale) tracker.stale = tracker.reads.some((read) => hasChanged(read, view));
+  return tracker.stale;
+}
+function warnMissingReads(hookName) {
+  return {
+    nested: false,
+    observe: (read) => {
+      if (read.op !== "get" || read.seen !== void 0) return;
+      warnOnce(
+        `[${hookName}] The creator read ${describeRead(read.kind, read.path)}, which does not exist yet. ${hookName} creators run once per generation, so this one will not re-run when it appears. Register it earlier (above this hook, or higher in the tree), or call rebuild* once it exists. To probe on purpose, use .has().`
+      );
+    }
+  };
+}
+
 var __defProp = Object.defineProperty;
 var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
 var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
-var _a, _b;
+var _a, _b, _c, _d;
 const INTERNAL_DATA = Symbol("ScopedStore.data");
 const INTERNAL_IS_LEAF = Symbol("ScopedStore.isLeaf");
-_b = INTERNAL_DATA, _a = INTERNAL_IS_LEAF;
+const INTERNAL_READS = Symbol("ScopedStore.reads");
+const INTERNAL_CHILDREN = Symbol("ScopedStore.children");
+_d = INTERNAL_DATA, _c = INTERNAL_IS_LEAF, _b = INTERNAL_READS, _a = INTERNAL_CHILDREN;
 const _ScopedStore = class _ScopedStore {
-  constructor(data, isLeaf) {
+  constructor(data, isLeaf, reads) {
+    /** @internal */
+    __publicField(this, _d);
+    /** @internal */
+    __publicField(this, _c);
+    /** @internal */
     __publicField(this, _b);
+    /** @internal */
     __publicField(this, _a);
     this[INTERNAL_DATA] = data;
     this[INTERNAL_IS_LEAF] = isLeaf;
+    this[INTERNAL_READS] = reads;
     return new Proxy(this, {
       get(target, prop, receiver) {
         if (typeof prop === "string") {
           if (prop === "scope" || prop === "has" || prop === "keys") {
             return Reflect.get(target, prop, receiver);
           }
-          return target[INTERNAL_DATA][prop];
+          return readEntry(target, prop);
         }
         return Reflect.get(target, prop, receiver);
       },
       has(target, prop) {
-        return typeof prop === "string" ? prop in target[INTERNAL_DATA] : Reflect.has(target, prop);
+        return typeof prop === "string" ? target.has(prop) : Reflect.has(target, prop);
       },
       ownKeys(target) {
+        observeKeys(target);
         return Reflect.ownKeys(target[INTERNAL_DATA]);
       },
       getOwnPropertyDescriptor(target, prop) {
@@ -345,54 +441,152 @@ const _ScopedStore = class _ScopedStore {
   scope(key) {
     const value = this[INTERNAL_DATA][key];
     const isLeaf = this[INTERNAL_IS_LEAF];
+    const reads = this[INTERNAL_READS];
     const scope = value && typeof value === "object" && !isLeaf(value) ? value : {};
-    return new _ScopedStore(scope, isLeaf);
+    const child = reads ? { ...reads, path: [...reads.path, key] } : void 0;
+    return new _ScopedStore(scope, isLeaf, child);
   }
   /**
    * Check if a key exists in the store.
    */
   has(key) {
-    return key in this[INTERNAL_DATA];
+    const found = key in this[INTERNAL_DATA];
+    const reads = this[INTERNAL_READS];
+    reads?.observe({ kind: reads.kind, op: "has", path: [...reads.path, key], seen: found });
+    return found;
   }
   /**
    * Get all keys in the store.
    */
   keys() {
+    observeKeys(this);
     return Object.keys(this[INTERNAL_DATA]);
   }
 };
 let ScopedStore = _ScopedStore;
+function readEntry(target, key) {
+  const value = target[INTERNAL_DATA][key];
+  const reads = target[INTERNAL_READS];
+  if (!reads) return value;
+  const isLeaf = target[INTERNAL_IS_LEAF];
+  const isScope = !!value && typeof value === "object" && !isLeaf(value);
+  const path = [...reads.path, key];
+  reads.observe({ kind: reads.kind, op: "get", path, seen: isScope ? SCOPE : value });
+  if (!isScope || !reads.nested) return value;
+  const children = target[INTERNAL_CHILDREN] ?? (target[INTERNAL_CHILDREN] = /* @__PURE__ */ new Map());
+  let child = children.get(key);
+  if (!child) {
+    child = new ScopedStore(value, isLeaf, { ...reads, path });
+    children.set(key, child);
+  }
+  return child;
+}
+function observeKeys(target) {
+  const reads = target[INTERNAL_READS];
+  reads?.observe({ kind: reads.kind, op: "keys", path: reads.path, seen: Object.keys(target[INTERNAL_DATA]) });
+}
 function createScopedStore(data, isLeaf) {
   return new ScopedStore(data, isLeaf);
 }
-function createLazyCreatorState(state, store) {
+function observeTextures(map, observe) {
+  const observeKeys2 = () => observe({ kind: "textures", op: "keys", path: [], seen: [...map.keys()] });
+  const observeAll = () => {
+    observeKeys2();
+    for (const [url, texture] of map) observe({ kind: "textures", op: "get", path: [url], seen: texture });
+  };
+  return new Proxy(map, {
+    get(target, prop) {
+      switch (prop) {
+        case "get":
+          return (url) => {
+            const texture = target.get(url);
+            observe({ kind: "textures", op: "get", path: [url], seen: texture });
+            return texture;
+          };
+        case "has":
+          return (url) => {
+            const found = target.has(url);
+            observe({ kind: "textures", op: "has", path: [url], seen: found });
+            return found;
+          };
+        case "size":
+          observeKeys2();
+          return target.size;
+        case "keys":
+          return () => {
+            observeKeys2();
+            return target.keys();
+          };
+        case "values":
+          return () => {
+            observeAll();
+            return target.values();
+          };
+        case "entries":
+        case Symbol.iterator:
+          return () => {
+            observeAll();
+            return target.entries();
+          };
+        case "forEach":
+          return (callback, thisArg) => {
+            observeAll();
+            target.forEach(callback, thisArg);
+          };
+      }
+      const value = Reflect.get(target, prop, target);
+      return typeof value === "function" ? value.bind(target) : value;
+    }
+  });
+}
+function createResourceView(primary, local = primary) {
+  return ((kind) => kind === "textures" ? getTextureView(local) : withStagedOverlay(primary, kind, primary.getState()[kind]));
+}
+function createLazyCreatorState(state, store, options = {}) {
+  const { reads } = options;
+  const view = options.view ?? (store ? createResourceView(store) : void 0);
   let _uniforms = null;
   let _nodes = null;
   let _buffers = null;
   let _gpuStorage = null;
-  const view = (kind) => store ? withStagedOverlay(store, kind, state[kind]) : state[kind];
-  return Object.create(state, {
+  let _textures = null;
+  const read = (kind) => view ? view(kind) : state[kind];
+  const wrap = (kind, isLeaf) => new ScopedStore(
+    read(kind),
+    isLeaf,
+    reads && { ...reads, kind, path: [] }
+  );
+  const properties = {
     uniforms: {
       get() {
-        return _uniforms ?? (_uniforms = createScopedStore(view("uniforms"), isUniformNode));
+        return _uniforms ?? (_uniforms = wrap("uniforms", isUniformNode));
       }
     },
     nodes: {
       get() {
-        return _nodes ?? (_nodes = createScopedStore(view("nodes"), isTSLNode));
+        return _nodes ?? (_nodes = wrap("nodes", isTSLNode));
       }
     },
     buffers: {
       get() {
-        return _buffers ?? (_buffers = createScopedStore(view("buffers"), isBufferLike));
+        return _buffers ?? (_buffers = wrap("buffers", isBufferLike));
       }
     },
     gpuStorage: {
       get() {
-        return _gpuStorage ?? (_gpuStorage = createScopedStore(view("gpuStorage"), isStorageLike));
+        return _gpuStorage ?? (_gpuStorage = wrap("gpuStorage", isStorageLike));
       }
     }
-  });
+  };
+  if (options.view) {
+    properties.textures = {
+      get() {
+        const textures = options.view("textures");
+        return _textures ?? (_textures = reads ? observeTextures(textures, reads.observe) : textures);
+      }
+    };
+  }
+  return Object.create(state, properties);
 }
 
 function resolvePrimary(local) {
@@ -468,7 +662,7 @@ function useUniforms(creatorOrScope, scope) {
   const processedInput = useMemo(() => {
     let raw = creatorOrScope;
     if (typeof creatorOrScope === "function") {
-      const wrappedState = createLazyCreatorState(store.getState(), store);
+      const wrappedState = createLazyCreatorState(store.getState(), store, { reads: warnMissingReads("useUniforms") });
       raw = creatorOrScope(wrappedState);
     }
     if (raw && typeof raw === "object" && !Array.isArray(raw)) {
@@ -611,7 +805,16 @@ function useNodes(creatorOrScope, scope) {
     isLeaf: isTSLNode,
     create: () => {
       if (isReader) return {};
-      return creatorOrScope(createLazyCreatorState(store.getState(), store));
+      const nodes2 = creatorOrScope(
+        createLazyCreatorState(store.getState(), store, { reads: warnMissingReads("useNodes") })
+      );
+      if (nodes2 == null) {
+        warnOnce(
+          "[useNodes] The creator returned nothing, so nothing was registered. useNodes registers the nodes its creator returns. To put a node onto a Three object (scene.fogNode = ...), use useLocalNodes and return a function that assigns it: it runs after commit and may return a cleanup."
+        );
+        return {};
+      }
+      return nodes2;
     },
     prepare: (name, node) => {
       const setName = Reflect.get(node, "setName");
@@ -631,16 +834,100 @@ function useNodes(creatorOrScope, scope) {
 function rebuildAllNodes(store, scope) {
   rebuildResource(store, "nodes", scope);
 }
-function useLocalNodes(creator) {
+function areDepsEqual(next, prev) {
+  if (next.length !== prev.length) return false;
+  for (let i = 0; i < next.length; i++) if (!Object.is(next[i], prev[i])) return false;
+  return true;
+}
+function useDependencyToken(deps) {
+  const previous = useRef(null);
+  const record = previous.current;
+  if (typeof process !== "undefined" && process.env.NODE_ENV !== "production" && record) {
+    const hadDeps = record.deps !== void 0;
+    const hasDeps = deps !== void 0;
+    if (hadDeps !== hasDeps) {
+      console.warn(
+        `[useLocalNodes] The dependency array was ${hasDeps ? "added" : "omitted"} between renders. Pass an array on every render or on none; the mode must not change for a mounted component.`
+      );
+    } else if (hasDeps && record.deps.length !== deps.length) {
+      console.warn(
+        `[useLocalNodes] The dependency array length changed between renders (${record.deps.length} \u2192 ${deps.length}). Declare a fixed-length list; conditional dependencies belong inside the array as values.`
+      );
+    }
+  }
+  if (deps === void 0) {
+    previous.current = { deps: void 0, token: {} };
+  } else if (!record || record.deps === void 0 || !areDepsEqual(deps, record.deps)) {
+    previous.current = { deps, token: {} };
+  } else if (record.deps !== deps) {
+    previous.current = { deps, token: record.token };
+  }
+  return previous.current.token;
+}
+function useLocalNodes(creator, deps) {
+  const local = useStore();
   const store = usePrimaryStore();
-  const uniforms = usePrimaryThree((s) => s.uniforms);
-  const nodes = usePrimaryThree((s) => s.nodes);
-  const textures = usePrimaryThree((s) => s.textures);
+  const view = useMemo(() => createResourceView(store, local), [store, local]);
   const hmrVersion = usePrimaryThree((s) => s._hmrVersion);
-  return useMemo(() => {
-    const wrappedState = createLazyCreatorState(store.getState(), store);
-    return creator(wrappedState);
-  }, [store, creator, uniforms, nodes, textures, hmrVersion]);
+  const depsToken = useDependencyToken(deps);
+  const committedReads = useRef(null);
+  const readsVersion = useRef(0);
+  const getReadsVersion = () => {
+    const tracker2 = committedReads.current;
+    if (tracker2 && !tracker2.stale && isTrackerStale(tracker2, view)) readsVersion.current++;
+    return readsVersion.current;
+  };
+  const subscribe = useCallback(
+    (onChange) => {
+      const unsubscribe = store.subscribe(onChange);
+      if (local === store) return unsubscribe;
+      const unsubscribeLocal = local.subscribe(onChange);
+      return () => {
+        unsubscribe();
+        unsubscribeLocal();
+      };
+    },
+    [store, local]
+  );
+  const resourceVersion = useSyncExternalStore(subscribe, getReadsVersion, getReadsVersion);
+  const evaluation = useMemo(() => {
+    const tracker2 = createReadTracker("useLocalNodes");
+    const reads = { observe: tracker2.observe, nested: true };
+    const value2 = creator(createLazyCreatorState(local.getState(), store, { reads, view }));
+    tracker2.closed = true;
+    return { value: value2, tracker: tracker2 };
+  }, [view, hmrVersion, depsToken, resourceVersion]);
+  const { value, tracker } = evaluation;
+  const installing = typeof value === "function";
+  useModeDiagnostics(value, installing);
+  useIsomorphicLayoutEffect(() => {
+    committedReads.current = tracker;
+    if (!installing) return;
+    tracker.closed = false;
+    let cleanup;
+    try {
+      cleanup = value();
+    } finally {
+      tracker.closed = true;
+    }
+    return typeof cleanup === "function" ? cleanup : void 0;
+  }, [evaluation]);
+  return installing ? void 0 : value;
+}
+function useModeDiagnostics(value, installing) {
+  const previous = useRef(null);
+  if (typeof process !== "undefined" && process.env.NODE_ENV === "production") return;
+  if (value === void 0 || value === null) {
+    warnOnce(
+      "[useLocalNodes] The creator returned nothing. To put a node onto a Three object (scene.fogNode = ...), build it in the creator and return a function that assigns it: that function runs after commit and may return a cleanup. Assigning inside the creator runs during render, which React may discard or repeat."
+    );
+  }
+  if (previous.current !== null && previous.current !== installing) {
+    warnOnce(
+      "[useLocalNodes] The creator switched between returning a record and returning an install function. Keep one form for a mounted component."
+    );
+  }
+  previous.current = installing;
 }
 
 const disposeBuffer = (buffer) => {
@@ -686,7 +973,9 @@ function useBuffers(creatorOrScope, scope) {
     isLeaf: isBufferLike,
     create: () => {
       if (isReader) return {};
-      return creatorOrScope(createLazyCreatorState(store.getState(), store));
+      return creatorOrScope(
+        createLazyCreatorState(store.getState(), store, { reads: warnMissingReads("useBuffers") })
+      );
     },
     prepare: (name, buffer) => {
       const setName = Reflect.get(buffer, "setName");
@@ -750,7 +1039,9 @@ function useGPUStorage(creatorOrScope, scope) {
     isLeaf: isStorageLike,
     create: () => {
       if (isReader) return {};
-      return creatorOrScope(createLazyCreatorState(store.getState(), store));
+      return creatorOrScope(
+        createLazyCreatorState(store.getState(), store, { reads: warnMissingReads("useGPUStorage") })
+      );
     },
     prepare: (name, storage) => {
       const label = scopedNodeName(scope, name);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@react-three/tsl",
-  "version": "10.0.0-canary.975e1e7",
+  "version": "10.0.0-canary.a9bd42a",
   "description": "TSL resource hooks for react-three-fiber: uniforms, nodes, buffers, GPU storage and render pipelines on WebGPU",
   "keywords": [
     "react",
@@ -49,14 +49,14 @@
   },
   "peerDependencies": {
     "@react-three/fiber": "^10.0.0-alpha.6",
-    "react": ">=19.0 <19.3",
+    "react": ">=19.0 <19.4",
     "three": ">=0.185.0"
   },
   "devDependencies": {
     "@types/three": "^0.185.0",
     "@webgpu/types": "^0.1.64",
     "three": ">=0.185.0",
-    "@react-three/fiber": "10.0.0-canary.975e1e7"
+    "@react-three/fiber": "10.0.0-canary.a9bd42a"
   },
   "scripts": {
     "build": "unbuild",