@react-three/tsl 10.0.0-canary.f81281f → 10.0.0-canary.fbc659b

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';
 
@@ -162,6 +162,10 @@ function extractTSLValue(value) {
   if (node.isConstNode) {
     return node.value;
   }
+  if (node.isVarNode && node.node) {
+    const inner = extractTSLValue(node.node);
+    return inner === node.node ? value : inner;
+  }
   if ("value" in node) {
     let extractedValue = node.value;
     if (typeof node.traverse === "function") {
@@ -297,33 +301,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 +445,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 +666,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)) {
@@ -491,8 +689,9 @@ function useUniforms(creatorOrScope, scope) {
     input: memoizedInput,
     create: () => {
       if (isReader) return {};
-      if (typeof processedInput.candidates !== "object" || processedInput.candidates === null)
+      if (typeof processedInput.candidates !== "object" || processedInput.candidates === null) {
         throw new Error("Invalid uniform input");
+      }
       return processedInput.candidates;
     },
     prepare: (name, candidate) => createUniform(name, candidate, scope),
@@ -550,18 +749,20 @@ function isSameThreeType(a, b) {
 const uniformOf = uniform;
 function useUniform(name, value) {
   const store = usePrimaryStore();
+  const memoizedInput = useCompareMemoize(value === void 0 ? name : { [name]: normalizeValue(value) });
   const registered = useScopedResource({
     store,
     kind: "uniforms",
     scope: void 0,
     isLeaf: isUniformNode,
-    input: name,
+    input: memoizedInput,
     create: () => value === void 0 ? {} : { [name]: value },
     prepare: createNamedUniform,
     reconcile: (existing2) => {
-      if (value !== void 0 && !isTSLNode(value) && !isUniformNode(value)) {
-        existing2.value = typeof value === "string" ? new Color(value) : value;
-      }
+      if (value === void 0 || isUniformNode(value)) return;
+      const next = normalizeValue(value);
+      if (isTSLNode(next)) return;
+      existing2.value = next;
     }
   });
   if (registered[name]) return registered[name];
@@ -571,6 +772,9 @@ function useUniform(name, value) {
     `[useUniform] Uniform "${name}" not found. Create it first with: useUniform('${name}', initialValue)`
   );
 }
+function normalizeValue(value) {
+  return typeof value === "string" ? new Color(value) : vectorize(value);
+}
 function createNamedUniform(name, value) {
   let node;
   if (isUniformNode(value)) {
@@ -611,7 +815,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 +844,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 +983,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 +1049,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.f81281f",
+  "version": "10.0.0-canary.fbc659b",
   "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.f81281f"
+    "@react-three/fiber": "10.0.0-canary.fbc659b"
   },
   "scripts": {
     "build": "unbuild",

package/readme.md

@@ -46,7 +46,7 @@ export const App = () => (
 | `useBuffers`, `useGPUStorage` | Buffers and storage textures for compute                                     |
 | `useRenderPipeline`           | Post-processing with three's `RenderPipeline` (scene pass, MRT, output node) |
 
-Resources belong to the renderer: a primary canvas, its secondary canvases (`renderer={{ primaryCanvas }}`) and every portal inside them share one set. They live on the primary canvas's `RootState` (`state.uniforms`, `state.nodes`, `state.buffers`, `state.gpuStorage`); secondaries hold the same objects and portals inherit them from their parent (a portal's scene and camera stay its own), so `state.uniforms` reads the same everywhere.
+Resources belong to the renderer: a `<Canvas primary>`, the canvases sharing its renderer (every other WebGPU canvas, or `share="id"`) and every portal inside them share one set. They live on the primary canvas's `RootState` (`state.uniforms`, `state.nodes`, `state.buffers`, `state.gpuStorage`); secondaries hold the same objects and portals inherit them from their parent (a portal's scene and camera stay its own), so `state.uniforms` reads the same everywhere.
 
 Works under any Canvas that runs the WebGPU renderer: `@react-three/fiber` with the `renderer` prop, or `@react-three/fiber/webgpu`. It reaches fiber only through the three-free `@react-three/fiber/extension` entry, so it adds no renderer and no second copy of fiber to your bundle.