@react-three/tsl 10.0.0-canary.777b94d → 10.0.0-canary.88b1ca7

package/dist/index.cjs

@@ -73,6 +73,13 @@ function withStagedOverlay(store, kind, committed) {
   }
   return view;
 }
+function readWithStaged(store, kind, committed, scope, isLeaf) {
+  if (scope === void 0) return withStagedOverlay(store, kind, committed);
+  const scopeData = committed[scope];
+  const current = scopeData && typeof scopeData === "object" && !isLeaf(scopeData) ? scopeData : {};
+  const staged = scope === ROOT_SCOPE ? void 0 : peekStaged(store, kind, scope);
+  return staged ? { ...current, ...staged } : current;
+}
 function flushStagedScope(store, kind, scopeKey, isLeaf) {
   const registry = getKindRegistry(store, kind);
   const staged = registry.staged.get(scopeKey);
@@ -177,6 +184,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") {
@@ -267,6 +278,103 @@ function configureTSL(next) {
   for (const store of primaries) applyConfig(store, config);
 }
 
+const owners = /* @__PURE__ */ new WeakMap();
+const warned$1 = /* @__PURE__ */ new WeakSet();
+const sweeps = /* @__PURE__ */ new WeakMap();
+function createOwner(store, rebuild) {
+  return { store, pipeline: null, scenePass: null, passes: {}, mounted: false, releaseTimer: null, rebuild };
+}
+function disposeOwnerResources(owner) {
+  owner.scenePass?.node.dispose();
+  owner.pipeline?.dispose();
+  owner.scenePass = null;
+  owner.pipeline = null;
+  owner.passes = {};
+}
+function activeOwner(store) {
+  return owners.get(store)?.at(-1);
+}
+function renderThroughPipeline(store) {
+  return () => {
+    const pipeline = store.getState().renderPipeline;
+    if (pipeline?.render) pipeline.render();
+  };
+}
+function claimOwnership(owner) {
+  if (owner.releaseTimer !== null) clearTimeout(owner.releaseTimer);
+  owner.releaseTimer = null;
+  owner.mounted = true;
+  let list = owners.get(owner.store);
+  if (!list) owners.set(owner.store, list = []);
+  if (list.includes(owner)) return;
+  if (list.some((other) => other.mounted) && !warned$1.has(owner.store)) {
+    warned$1.add(owner.store);
+    if (typeof process === "undefined" || process.env.NODE_ENV !== "production") {
+      console.warn(
+        "[useRenderPipeline] More than one mounted component configures this canvas's render pipeline. The most recently mounted one renders; the others take over again when it unmounts."
+      );
+    }
+  }
+  list.push(owner);
+  scheduleSweep(owner.store);
+}
+function scheduleSweep(store) {
+  if (sweeps.has(store)) return;
+  sweeps.set(
+    store,
+    setTimeout(() => {
+      sweeps.delete(store);
+      const active = activeOwner(store);
+      for (const owner of [...owners.get(store) ?? []]) {
+        if (owner !== active && !owner.mounted && owner.releaseTimer === null) releaseOwner(owner);
+      }
+    })
+  );
+}
+function publishOwner(owner) {
+  if (activeOwner(owner.store) !== owner || !owner.pipeline) return;
+  owner.store.setState({ renderPipeline: owner.pipeline, passes: owner.passes });
+  extension.setRenderOverride(owner.store, renderThroughPipeline(owner.store));
+}
+function scheduleRelease(owner) {
+  owner.mounted = false;
+  if (owner.releaseTimer !== null) return;
+  owner.releaseTimer = setTimeout(() => releaseOwner(owner));
+}
+function releaseOwner(owner) {
+  if (owner.releaseTimer !== null) clearTimeout(owner.releaseTimer);
+  owner.releaseTimer = null;
+  const { store } = owner;
+  const list = owners.get(store);
+  const index = list?.indexOf(owner) ?? -1;
+  if (list && index !== -1) {
+    const wasActive = index === list.length - 1;
+    list.splice(index, 1);
+    if (wasActive) {
+      const next = activeOwner(store);
+      if (next) {
+        publishOwner(next);
+      } else {
+        store.setState({ renderPipeline: null, passes: {} });
+        extension.setRenderOverride(store, null);
+      }
+    }
+  }
+  disposeOwnerResources(owner);
+}
+function releaseAllOwners(store) {
+  clearTimeout(sweeps.get(store));
+  sweeps.delete(store);
+  const list = owners.get(store);
+  if (!list) return;
+  owners.delete(store);
+  for (const owner of list) {
+    if (owner.releaseTimer !== null) clearTimeout(owner.releaseTimer);
+    owner.releaseTimer = null;
+    disposeOwnerResources(owner);
+  }
+}
+
 const SHARED_KEYS = ["uniforms", "nodes", "buffers", "gpuStorage", "_hmrVersion"];
 const following = /* @__PURE__ */ new WeakMap();
 function createResourceState() {
@@ -295,6 +403,7 @@ function followPrimary(store, primary) {
   following.set(store, primary.subscribe(sync));
 }
 function dispose(store) {
+  releaseAllOwners(store);
   untrackPrimary(store);
   following.get(store)?.();
   following.delete(store);
@@ -312,33 +421,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 +565,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 +786,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)) {
@@ -506,8 +809,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),
@@ -525,13 +829,7 @@ function useUniforms(creatorOrScope, scope) {
       if (!equals) existing.value = newVal;
     }
   });
-  let uniforms = created;
-  if (memoizedInput === void 0) {
-    uniforms = storeUniforms;
-  } else if (typeof memoizedInput === "string") {
-    const scopeData = storeUniforms[memoizedInput];
-    uniforms = scopeData && !isUniformNode(scopeData) ? scopeData : {};
-  }
+  const uniforms = isReader ? readWithStaged(store, "uniforms", storeUniforms, memoizedInput, isUniformNode) : created;
   return { ...uniforms, removeUniforms, clearUniforms, rebuildUniforms };
 }
 function rebuildAllUniforms(store, scope) {
@@ -565,18 +863,20 @@ function isSameThreeType(a, b) {
 const uniformOf = tsl.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 THREE.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];
@@ -586,6 +886,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 THREE.Color(value) : vectorize(value);
+}
 function createNamedUniform(name, value) {
   let node;
   if (isUniformNode(value)) {
@@ -626,7 +929,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");
@@ -634,28 +946,106 @@ function useNodes(creatorOrScope, scope) {
       return node;
     }
   });
-  let nodes = created;
-  if (creatorOrScope === void 0) {
-    nodes = storeNodes;
-  } else if (typeof creatorOrScope === "string") {
-    const scopeData = storeNodes[creatorOrScope];
-    nodes = scopeData && !isTSLNode(scopeData) ? scopeData : {};
-  }
+  const nodes = isReader ? readWithStaged(store, "nodes", storeNodes, creatorOrScope, isTSLNode) : created;
   return { ...nodes, removeNodes, clearNodes, rebuildNodes };
 }
 function rebuildAllNodes(store, scope) {
   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 +1091,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");
@@ -709,13 +1101,7 @@ function useBuffers(creatorOrScope, scope) {
       return buffer;
     }
   });
-  let buffers = created;
-  if (creatorOrScope === void 0) {
-    buffers = storeBuffers;
-  } else if (typeof creatorOrScope === "string") {
-    const scopeData = storeBuffers[creatorOrScope];
-    buffers = scopeData && !isBufferLike(scopeData) ? scopeData : {};
-  }
+  const buffers = isReader ? readWithStaged(store, "buffers", storeBuffers, creatorOrScope, isBufferLike) : created;
   return { ...buffers, removeBuffers, clearBuffers, rebuildBuffers, disposeBuffers };
 }
 function rebuildAllBuffers(store, scope) {
@@ -765,7 +1151,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);
@@ -777,13 +1165,7 @@ function useGPUStorage(creatorOrScope, scope) {
       return storage;
     }
   });
-  let gpuStorage = created;
-  if (creatorOrScope === void 0) {
-    gpuStorage = storeStorage;
-  } else if (typeof creatorOrScope === "string") {
-    const scopeData = storeStorage[creatorOrScope];
-    gpuStorage = scopeData && !isStorageLike(scopeData) ? scopeData : {};
-  }
+  const gpuStorage = isReader ? readWithStaged(store, "gpuStorage", storeStorage, creatorOrScope, isStorageLike) : created;
   return {
     ...gpuStorage,
     removeStorage,
@@ -797,120 +1179,164 @@ function rebuildAllStorage(store, scope) {
 }
 
 const NO_PASSES = Object.freeze({});
-function renderThroughPipeline(store) {
-  return () => {
-    const pipeline = store.getState().renderPipeline;
-    if (pipeline?.render) pipeline.render();
-  };
-}
-function useRenderPipeline(mainCB, setupCB) {
+function useRenderPipeline(mainCB, setupCB, options) {
   const store = extension.useStore();
+  const primary = usePrimaryStore();
+  const view = React.useMemo(() => createResourceView(primary, store), [primary, store]);
   const { scene, camera, renderer, isLegacy } = extension.useThree();
+  const hmrVersion = usePrimaryThree((s) => s._hmrVersion);
+  const isOwner = mainCB !== void 0 || setupCB !== void 0;
   const callbacksRanRef = React.useRef(false);
-  const scenePassCacheRef = React.useRef(null);
   const forceScenePassRebuildRef = React.useRef(false);
   const mainCBRef = React.useRef(mainCB);
   const setupCBRef = React.useRef(setupCB);
+  const persistRef = React.useRef(options?.persist ?? false);
   mainCBRef.current = mainCB;
   setupCBRef.current = setupCB;
+  persistRef.current = options?.persist ?? false;
   const [rebuildVersion, setRebuildVersion] = React.useState(0);
-  React.useEffect(() => {
+  const rerun = React.useCallback((freshScenePass) => {
     callbacksRanRef.current = false;
-    forceScenePassRebuildRef.current = true;
+    if (freshScenePass) forceScenePassRebuildRef.current = true;
+    setRebuildVersion((v) => v + 1);
   }, []);
+  const ownerRef = React.useRef(null);
+  const target = React.useCallback(() => (isOwner ? ownerRef.current : activeOwner(store)) ?? null, [isOwner, store]);
   const clearPasses = React.useCallback(() => {
-    store.setState({ passes: {} });
-  }, [store]);
+    const owner = target();
+    if (!owner) return;
+    owner.passes = {};
+    if (activeOwner(store) === owner) store.setState({ passes: {} });
+  }, [store, target]);
   const reset = React.useCallback(() => {
-    store.setState({
-      renderPipeline: null,
-      passes: {}
-    });
-    extension.setRenderOverride(store, null);
-    scenePassCacheRef.current?.scenePass.dispose();
-    callbacksRanRef.current = false;
-    scenePassCacheRef.current = null;
-    forceScenePassRebuildRef.current = false;
-  }, [store]);
+    const owner = target();
+    if (!owner) return;
+    releaseOwner(owner);
+    if (owner === ownerRef.current) committedReads.current = null;
+  }, [target]);
   const rebuild = React.useCallback(() => {
-    callbacksRanRef.current = false;
-    forceScenePassRebuildRef.current = true;
-    setRebuildVersion((v) => v + 1);
-  }, []);
+    if (isOwner) rerun(true);
+    else activeOwner(store)?.rebuild();
+  }, [isOwner, rerun, store]);
+  const hmrVersionRef = React.useRef(hmrVersion);
+  React.useEffect(() => {
+    if (hmrVersionRef.current === hmrVersion) return;
+    hmrVersionRef.current = hmrVersion;
+    if (isOwner) rerun(false);
+  }, [hmrVersion, isOwner, rerun]);
+  const committedReads = React.useRef(null);
+  const readsVersion = React.useRef(0);
+  const getReadsVersion = () => {
+    const tracker = committedReads.current;
+    if (tracker && !tracker.stale && isTrackerStale(tracker, view)) readsVersion.current++;
+    return readsVersion.current;
+  };
+  const subscribe = React.useCallback(
+    (onChange) => {
+      const unsubscribe = primary.subscribe(onChange);
+      if (store === primary) return unsubscribe;
+      const unsubscribeLocal = store.subscribe(onChange);
+      return () => {
+        unsubscribe();
+        unsubscribeLocal();
+      };
+    },
+    [primary, store]
+  );
+  const resourceVersion = React.useSyncExternalStore(subscribe, getReadsVersion, getReadsVersion);
+  const lastResourceVersion = React.useRef(resourceVersion);
   React.useLayoutEffect(() => {
     if (isLegacy) {
-      throw new Error("useRenderPipeline is only available with WebGPU renderer. Set renderer prop on Canvas.");
+      throw new Error(
+        "useRenderPipeline needs WebGPU: import Canvas from @react-three/fiber, not @react-three/fiber/legacy."
+      );
     }
+    if (!isOwner) return;
     if (!renderer || !scene || !camera) return;
     if (!("isWebGPURenderer" in renderer)) {
       throw new Error("useRenderPipeline: renderer is not a WebGPURenderer but isLegacy is false.");
     }
-    const state = store.getState();
-    const set = store.setState;
+    let owner = ownerRef.current;
+    if (owner && owner.store !== store) {
+      releaseOwner(owner);
+      owner = null;
+    }
+    if (!owner) owner = ownerRef.current = createOwner(store, () => rerun(true));
+    claimOwnership(owner);
+    const currentOwner = owner;
     try {
-      let pipeline = state.renderPipeline ?? null;
-      let currentPasses = { ...state.passes };
       let justCreatedPipeline = false;
-      if (!pipeline) {
-        pipeline = new THREE__namespace.RenderPipeline(renderer);
+      if (!owner.pipeline || owner.pipeline.renderer !== renderer) {
+        disposeOwnerResources(owner);
+        owner.pipeline = new THREE__namespace.RenderPipeline(renderer);
         justCreatedPipeline = true;
       }
-      const cacheValid = !forceScenePassRebuildRef.current && scenePassCacheRef.current && scenePassCacheRef.current.sceneUuid === scene.uuid && scenePassCacheRef.current.cameraUuid === camera.uuid;
+      const pipeline = owner.pipeline;
+      const cached = owner.scenePass;
+      const cacheValid = !forceScenePassRebuildRef.current && cached !== null && cached.sceneUuid === scene.uuid && cached.cameraUuid === camera.uuid;
       let outgoingScenePass = null;
       let scenePass;
-      if (cacheValid) {
-        scenePass = scenePassCacheRef.current.scenePass;
+      if (cacheValid && cached) {
+        scenePass = cached.node;
       } else {
-        outgoingScenePass = scenePassCacheRef.current?.scenePass ?? null;
+        outgoingScenePass = cached?.node ?? null;
         scenePass = tsl.pass(scene, camera);
-        scenePassCacheRef.current = { sceneUuid: scene.uuid, cameraUuid: camera.uuid, scenePass };
+        owner.scenePass = { sceneUuid: scene.uuid, cameraUuid: camera.uuid, node: scenePass };
         forceScenePassRebuildRef.current = false;
       }
-      currentPasses.scenePass = scenePass;
       let outputNodeChanged = false;
       if (!pipeline.outputNode || justCreatedPipeline || pipeline.outputNode === outgoingScenePass) {
         pipeline.outputNode = scenePass;
         outputNodeChanged = true;
       }
-      set({ renderPipeline: pipeline, passes: currentPasses });
-      extension.setRenderOverride(store, renderThroughPipeline(store));
-      const shouldRunCallbacks = justCreatedPipeline || !callbacksRanRef.current || !cacheValid;
+      const readsChanged = lastResourceVersion.current !== resourceVersion;
+      lastResourceVersion.current = resourceVersion;
+      const shouldRunCallbacks = justCreatedPipeline || !callbacksRanRef.current || !cacheValid || readsChanged;
       if (shouldRunCallbacks) {
-        if (setupCBRef.current) {
-          const freshState = Object.assign({}, store.getState(), {
-            renderPipeline: pipeline,
-            passes: { ...currentPasses, scenePass },
-            renderer,
-            isLegacy: false
-          });
-          const setupResult = setupCBRef.current(freshState);
-          if (setupResult && typeof setupResult === "object") {
-            currentPasses = { ...currentPasses, ...setupResult };
-            set({ passes: currentPasses });
+        let currentPasses = { scenePass };
+        owner.passes = currentPasses;
+        const tracker = createReadTracker("useRenderPipeline");
+        const callbackState = () => Object.assign(
+          createLazyCreatorState(store.getState(), primary, {
+            reads: { observe: tracker.observe, nested: true },
+            view
+          }),
+          { renderPipeline: pipeline, passes: { ...currentPasses, scenePass }, renderer, isLegacy: false }
+        );
+        try {
+          if (setupCBRef.current) {
+            const setupResult = setupCBRef.current(callbackState());
+            if (setupResult && typeof setupResult === "object") {
+              currentPasses = { ...currentPasses, ...setupResult };
+              owner.passes = currentPasses;
+            }
           }
-        }
-        if (mainCBRef.current) {
-          const freshState = Object.assign({}, store.getState(), {
-            renderPipeline: pipeline,
-            passes: { ...currentPasses, scenePass },
-            renderer,
-            isLegacy: false
-          });
-          const mainResult = mainCBRef.current(freshState);
-          if (mainResult && typeof mainResult === "object") {
-            currentPasses = { ...currentPasses, ...mainResult };
-            set({ passes: currentPasses });
+          if (mainCBRef.current) {
+            const mainResult = mainCBRef.current(callbackState());
+            if (mainResult && typeof mainResult === "object") {
+              currentPasses = { ...currentPasses, ...mainResult };
+              owner.passes = currentPasses;
+            }
           }
+        } finally {
+          tracker.closed = true;
+          committedReads.current = tracker;
         }
         outputNodeChanged = true;
         callbacksRanRef.current = true;
       }
       if (outputNodeChanged) pipeline.needsUpdate = true;
+      publishOwner(owner);
       if (outgoingScenePass && outgoingScenePass !== scenePass) outgoingScenePass.dispose();
     } catch (error) {
+      publishOwner(owner);
       console.warn("[useRenderPipeline] Setup failed; the render pipeline was not configured:", error);
     }
-  }, [store, renderer, scene, camera, isLegacy, rebuildVersion]);
+    return () => {
+      if (persistRef.current) currentOwner.mounted = false;
+      else scheduleRelease(currentOwner);
+    };
+  }, [store, primary, view, renderer, scene, camera, isLegacy, isOwner, rebuildVersion, resourceVersion, rerun]);
   const passes = extension.useThree((s) => s.passes) ?? NO_PASSES;
   const renderPipeline = extension.useThree((s) => s.renderPipeline) ?? null;
   const actions = { passes, clearPasses, reset, rebuild };