sibujs 4.6.0 → 4.8.0

package/dist/data.cjs

@@ -660,7 +660,7 @@ function forEachSubscriber(signal2, visit) {
 }
 
 // src/reactivity/track.ts
-var _runtimeVersion = true ? "4.6.0" : "dev";
+var _runtimeVersion = true ? "4.8.0" : "dev";
 var REGISTRY_KEY = /* @__PURE__ */ Symbol.for("sibujs.reactive.v1");
 function resolveReactiveApi() {
   const g = globalThis;
@@ -716,6 +716,14 @@ var getSubscriberCount2 = API.getSubscriberCount;
 var getSubscriberDeps2 = API.getSubscriberDeps;
 var forEachSubscriber2 = API.forEachSubscriber;
 
+// src/core/devtoolsHook.ts
+function emitDevtools(hook, event, payload) {
+  try {
+    hook.emit(event, payload);
+  } catch {
+  }
+}
+
 // src/core/signals/derived.ts
 function derived(getter, options) {
   devAssert(typeof getter === "function", "derived: argument must be a getter function.");
@@ -742,17 +750,17 @@ function derived(getter, options) {
     cs._d = false;
     cs._init = true;
   };
-  track2(() => {
-    let threw = true;
-    try {
+  try {
+    track2(() => {
       cs._v = getter();
       cs._d = false;
       cs._init = true;
-      threw = false;
-    } finally {
-      if (threw) cs._d = true;
-    }
-  }, markDirty);
+    }, markDirty);
+  } catch (err) {
+    disposed = true;
+    cleanup2(markDirty);
+    throw err;
+  }
   const hook = globalThis.__SIBU_DEVTOOLS_GLOBAL_HOOK__;
   const validate = () => {
     if (!cs._d || disposed || pendingError !== void 0) return;
@@ -771,7 +779,7 @@ function derived(getter, options) {
       if (disposed) cleanup2(markDirty);
     }
     if (hook && !disposed && !Object.is(oldValue, cs._v)) {
-      hook.emit("computed:update", { signal: cs, oldValue, newValue: cs._v });
+      emitDevtools(hook, "computed:update", { signal: cs, oldValue, newValue: cs._v });
     }
   };
   cs._validate = validate;
@@ -822,7 +830,7 @@ function derived(getter, options) {
       }
     }
   };
-  if (hook) hook.emit("computed:create", { signal: cs, name: debugName, getter: computedGetter });
+  if (hook) emitDevtools(hook, "computed:create", { signal: cs, name: debugName, getter: computedGetter });
   return computedGetter;
 }
 
@@ -991,12 +999,17 @@ function effect(effectFn, options) {
   try {
     retrack2(ctx.bodyFn, ctx.subscriber);
     if (ctx.rerunPending) drainReruns(ctx);
+  } catch (err) {
+    ctx.disposed = true;
+    if (ctx.userCleanups.length > 0) flushUserCleanups(ctx);
+    cleanup2(ctx.subscriber);
+    throw err;
   } finally {
     ctx.running = false;
     ctx.rerunPending = false;
   }
   const hook = _g.__SIBU_DEVTOOLS_GLOBAL_HOOK__;
-  if (hook) hook.emit("effect:create", { effectFn });
+  if (hook) emitDevtools(hook, "effect:create", { effectFn });
   return () => disposeEffect(ctx);
 }
 
@@ -1083,7 +1096,7 @@ function signal(initial, options) {
       state2.__v++;
       if (DEV) {
         const hook = _g2.__SIBU_DEVTOOLS_GLOBAL_HOOK__;
-        if (hook) hook.emit("signal:update", { signal: state2, name: debugName, oldValue: prev, newValue });
+        if (hook) emitDevtools(hook, "signal:update", { signal: state2, name: debugName, oldValue: prev, newValue });
       }
       if (!enqueueBatchedSignal(state2)) {
         notifySubscribers2(state2);
@@ -1097,7 +1110,7 @@ function signal(initial, options) {
       state2.value = newValue;
       state2.__v++;
       const hook = _g2.__SIBU_DEVTOOLS_GLOBAL_HOOK__;
-      if (hook) hook.emit("signal:update", { signal: state2, name: debugName, oldValue: prev, newValue });
+      if (hook) emitDevtools(hook, "signal:update", { signal: state2, name: debugName, oldValue: prev, newValue });
       if (!enqueueBatchedSignal(state2)) {
         notifySubscribers2(state2);
       }
@@ -1116,7 +1129,7 @@ function signal(initial, options) {
   }
   if (DEV) {
     const hook = _g2.__SIBU_DEVTOOLS_GLOBAL_HOOK__;
-    if (hook) hook.emit("signal:create", { signal: state2, name: debugName, getter: get, initial });
+    if (hook) emitDevtools(hook, "signal:create", { signal: state2, name: debugName, getter: get, initial });
   }
   return [get, set];
 }
@@ -1238,7 +1251,87 @@ function waitForRetryDelay(delay, signal2) {
   });
 }
 
+// src/data/structuralSharing.ts
+function isPlainObject(value) {
+  if (value === null || typeof value !== "object") return false;
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+}
+function isPlainArray(value) {
+  return Array.isArray(value) && Object.getPrototypeOf(value) === Array.prototype;
+}
+function reconcile(prev, next, depth, walk, newRoot) {
+  if (Object.is(prev, next)) return prev;
+  const arrays = isPlainArray(prev) && isPlainArray(next);
+  if (!arrays && !(isPlainObject(prev) && isPlainObject(next))) return next;
+  if (Object.getPrototypeOf(prev) !== Object.getPrototypeOf(next)) return next;
+  const nextObject = next;
+  const seenAt = walk.path.get(nextObject);
+  if (seenAt !== void 0) {
+    walk.cycleTo = Math.min(walk.cycleTo, seenAt);
+    return next;
+  }
+  const prevRecord = prev;
+  const nextRecord = next;
+  const nextKeys = arrays ? Array.from({ length: next.length }, (_, i) => i) : Object.keys(nextRecord);
+  const prevSize = arrays ? prev.length : Object.keys(prevRecord).length;
+  const copy = arrays ? new Array(nextKeys.length) : Object.create(Object.getPrototypeOf(next));
+  let allFromPrev = prevSize === nextKeys.length;
+  let allFromNext = true;
+  const outerCycleTo = walk.cycleTo;
+  walk.cycleTo = Number.POSITIVE_INFINITY;
+  walk.path.set(nextObject, depth);
+  for (const key of nextKeys) {
+    if (arrays && !Object.hasOwn(nextRecord, key)) {
+      if (Object.hasOwn(prevRecord, key)) allFromPrev = false;
+      continue;
+    }
+    const nextChild = nextRecord[key];
+    const hasPrev = Object.hasOwn(prevRecord, key);
+    const shared = hasPrev ? reconcile(prevRecord[key], nextChild, depth + 1, walk, false) : nextChild;
+    if (key === "__proto__") {
+      Object.defineProperty(copy, key, { value: shared, writable: true, enumerable: true, configurable: true });
+    } else {
+      copy[key] = shared;
+    }
+    if (!hasPrev || !Object.is(shared, prevRecord[key])) allFromPrev = false;
+    if (!Object.is(shared, nextChild)) allFromNext = false;
+  }
+  walk.path.delete(nextObject);
+  const reached = walk.cycleTo;
+  walk.cycleTo = Math.min(outerCycleTo, reached < depth ? reached : Number.POSITIVE_INFINITY);
+  if (reached <= depth) return next;
+  if (allFromPrev && !newRoot) return prev;
+  if (allFromNext) return next;
+  return copy;
+}
+function applyStructuralSharing(option, prev, next, explicit = false) {
+  if (option === false || prev === void 0) return next;
+  const forceNew = explicit && !Object.is(prev, next);
+  if (typeof option === "function") {
+    const shared = option(prev, next);
+    return forceNew && Object.is(shared, prev) ? next : shared;
+  }
+  return reconcile(prev, next, 0, { path: /* @__PURE__ */ new Map(), cycleTo: Number.POSITIVE_INFINITY }, forceNew);
+}
+
 // src/data/query.ts
+function shareSafely(option, prev, next, explicit) {
+  const shared = untracked2(
+    () => runSelect("query structuralSharing", () => applyStructuralSharing(option, prev, next, explicit))
+  );
+  return shared.ok ? shared.value : next;
+}
+function sharedView(entry) {
+  const raw = entry.data;
+  if (raw === void 0) return void 0;
+  if (entry.hasShared && Object.is(entry.sharedFrom, raw)) return entry.shared;
+  const value = shareSafely(true, entry.hasShared ? entry.shared : void 0, raw, entry.explicit);
+  entry.shared = value;
+  entry.sharedFrom = raw;
+  entry.hasShared = true;
+  return value;
+}
 var globalQueryCache = globalSingleton(/* @__PURE__ */ Symbol.for("sibujs.query.cache.v1"), () => /* @__PURE__ */ new Map());
 function getActiveQueryCache() {
   return getRequestScopedCache("query") ?? globalQueryCache;
@@ -1264,7 +1357,11 @@ function getOrCreateEntry(cache, key, initialData) {
       listeners: /* @__PURE__ */ new Set(),
       refetchers: /* @__PURE__ */ new Set(),
       controller: null,
-      generation: 0
+      generation: 0,
+      explicit: false,
+      shared: void 0,
+      sharedFrom: void 0,
+      hasShared: false
     };
     cache.set(key, entry);
   }
@@ -1283,13 +1380,24 @@ function query(key, fetcher, options = {}) {
     onSuccess,
     onError,
     onSettled,
-    select
+    select,
+    structuralSharing = true
   } = options;
   const resolveKey = typeof key === "function" ? key : () => key;
   const cache = getActiveQueryCache();
   const [data, setData] = signal(initialData);
   const [isFetching, setIsFetching] = signal(false);
   const [error, setError] = signal(void 0);
+  const [updatedAt, setUpdatedAt] = signal(0);
+  const [base, setBase] = signal(void 0);
+  let baseEntry = null;
+  let baseValue;
+  let baseExplicit = false;
+  let customEntry = null;
+  let customFrom;
+  let customValue;
+  let selectedEntry = null;
+  let selectedValue;
   let disposed = false;
   let currentKey = null;
   let attachedEntry = null;
@@ -1298,11 +1406,57 @@ function query(key, fetcher, options = {}) {
   const loading = derived(() => isFetching() && data() === void 0);
   const isStale = derived(() => {
     data();
+    updatedAt();
     if (!currentKey) return true;
     const entry = cache.get(currentKey);
     if (!entry || entry.dataUpdatedAt === 0) return true;
     return Date.now() - entry.dataUpdatedAt >= staleTime;
   });
+  function viewOf(entry) {
+    const raw = entry.data;
+    if (raw === void 0) return void 0;
+    if (structuralSharing === false) return raw;
+    if (typeof structuralSharing !== "function") return sharedView(entry);
+    const sameEntry = customEntry === entry;
+    if (sameEntry && Object.is(customFrom, raw)) return customValue;
+    const value = shareSafely(structuralSharing, sameEntry ? customValue : void 0, raw, entry.explicit);
+    customEntry = entry;
+    customFrom = raw;
+    customValue = value;
+    return value;
+  }
+  function commitBase(entry, value) {
+    const changed = !Object.is(value, baseValue);
+    baseEntry = entry;
+    baseValue = value;
+    if (!select) {
+      setData(value);
+      return;
+    }
+    if (!changed) return;
+    baseExplicit = entry?.explicit === true;
+    setBase(value);
+  }
+  const stopSelect = select ? effect(() => {
+    const raw = base();
+    const entry = baseEntry;
+    const explicit = baseExplicit;
+    baseExplicit = false;
+    if (entry === null && selectedEntry === null) return;
+    if (raw === void 0) {
+      selectedEntry = entry;
+      selectedValue = void 0;
+      setData(void 0);
+      return;
+    }
+    const selected = runSelect("query select", () => select(raw));
+    if (!selected.ok) return;
+    const prev = selectedEntry === entry ? selectedValue : void 0;
+    const value = shareSafely(structuralSharing, prev, selected.value, explicit);
+    selectedEntry = entry;
+    selectedValue = value;
+    setData(value);
+  }) : null;
   function detachFromEntry() {
     const entry = attachedEntry;
     const key2 = attachedKey;
@@ -1361,7 +1515,7 @@ function query(key, fetcher, options = {}) {
             const settledError = entry.error;
             runCallback("query onError", () => onError?.(settledError));
           } else if (entry.data !== void 0) {
-            const settledData = entry.data;
+            const settledData = viewOf(entry);
             runCallback("query onSuccess", () => onSuccess?.(settledData));
           }
           runCallback("query onSettled", () => onSettled?.());
@@ -1392,17 +1546,14 @@ function query(key, fetcher, options = {}) {
       entry.promise = null;
       entry.controller = null;
       entry.data = result;
+      entry.explicit = false;
       entry.dataUpdatedAt = Date.now();
       entry.error = void 0;
       notifyListeners(entry.listeners, "query cache listener");
       if (disposed || currentKey !== key2) return;
-      const selected = runSelect("query select", () => select ? select(result) : result);
-      batch(() => {
-        if (selected.ok) setData(selected.value);
-        setIsFetching(false);
-        setError(void 0);
-      });
-      runCallback("query onSuccess", () => onSuccess?.(result));
+      if (!entry.listeners.has(onCacheUpdate)) onCacheUpdate();
+      const committedResult = viewOf(entry);
+      runCallback("query onSuccess", () => onSuccess?.(committedResult));
     } catch (err) {
       if (entry.generation !== generation) return;
       entry.promise = null;
@@ -1432,18 +1583,19 @@ function query(key, fetcher, options = {}) {
     const entry = cache.get(currentKey);
     if (!entry) {
       batch(() => {
-        setData(void 0);
+        commitBase(null, void 0);
         setError(void 0);
         setIsFetching(false);
+        setUpdatedAt(0);
       });
       return;
     }
-    const raw = entry.data;
-    const selected = raw !== void 0 && select ? runSelect("query select", () => select(raw)) : { ok: true, value: raw };
+    const view = viewOf(entry);
     batch(() => {
-      if (selected.ok) setData(selected.value);
+      commitBase(entry, view);
       setError(entry.error);
       if (!entry.promise) setIsFetching(false);
+      setUpdatedAt(entry.dataUpdatedAt);
     });
   }
   const effectCleanup = effect(() => {
@@ -1453,11 +1605,11 @@ function query(key, fetcher, options = {}) {
     const entry = getOrCreateEntry(cache, key2, initialData);
     attachToEntry(entry, key2);
     if (entry.data !== void 0) {
-      const raw = entry.data;
-      const selected = runSelect("query select", () => select ? select(raw) : raw);
+      const view = viewOf(entry);
       batch(() => {
-        if (selected.ok) setData(selected.value);
+        commitBase(entry, view);
         setError(entry.error);
+        setUpdatedAt(entry.dataUpdatedAt);
       });
     }
     if (!keyChanged && currentKey === key2 && entry.data !== void 0) {
@@ -1495,6 +1647,7 @@ function query(key, fetcher, options = {}) {
     if (disposed) return;
     disposed = true;
     effectCleanup();
+    stopSelect?.();
     loading.dispose();
     isStale.dispose();
     if (intervalTimer) clearInterval(intervalTimer);
@@ -1526,13 +1679,15 @@ function invalidateQueries(keyOrPredicate) {
   }
 }
 function getQueryData(key) {
-  return getActiveQueryCache().get(key)?.data;
+  const entry = getActiveQueryCache().get(key);
+  return entry ? sharedView(entry) : void 0;
 }
 function setQueryData(key, data) {
   const entry = getActiveQueryCache().get(key);
   if (!entry) return;
-  const newData = typeof data === "function" ? data(entry.data) : data;
+  const newData = typeof data === "function" ? data(sharedView(entry)) : data;
   entry.data = newData;
+  entry.explicit = true;
   entry.dataUpdatedAt = Date.now();
   notifyListeners(entry.listeners, "query cache listener");
 }
@@ -1916,6 +2071,15 @@ function resource(sourceOrFetcher, fetcherOrOptions, maybeOptions) {
   const [loading, setLoading] = signal(false);
   const [error, setError] = signal(void 0);
   let currentData = options.initialValue;
+  function commitData(next, explicit) {
+    const sharing = options.structuralSharing ?? true;
+    const shared = untracked2(
+      () => runSelect("resource structuralSharing", () => applyStructuralSharing(sharing, currentData, next, explicit))
+    );
+    currentData = shared.ok ? shared.value : next;
+    setData(currentData);
+    return currentData;
+  }
   let abortController = null;
   let disposed = false;
   let effectCleanup = null;
@@ -1935,12 +2099,12 @@ function resource(sourceOrFetcher, fetcherOrOptions, maybeOptions) {
     try {
       const result = await withRetry(() => fetcher(sourceValue, { signal: signal2, prev }), options.retry, void 0, signal2);
       if (version !== fetchVersion || disposed) return;
-      currentData = result;
+      let committed = result;
       batch(() => {
-        setData(result);
+        committed = commitData(result, false);
         setLoading(false);
       });
-      runCallback("resource onSuccess", () => options.onSuccess?.(result));
+      runCallback("resource onSuccess", () => options.onSuccess?.(committed));
     } catch (err) {
       if (version !== fetchVersion || disposed) return;
       if (isAbortError(err)) {
@@ -1974,8 +2138,7 @@ function resource(sourceOrFetcher, fetcherOrOptions, maybeOptions) {
     refetch: () => doFetch(source ? source() : void 0),
     mutate: (value) => {
       const newValue = typeof value === "function" ? value(currentData) : value;
-      currentData = newValue;
-      setData(newValue);
+      commitData(newValue, true);
     },
     abort: () => abortController?.abort(),
     dispose: () => {
@@ -2501,6 +2664,9 @@ function sanitizeUrl(url) {
   const probe = stripControlChars(url).trim();
   if (!probe) return "";
   const output = url.replace(OUTER_TRIM, "");
+  if (probe.length >= 2 && (probe[0] === "\\" || probe[0] === "/") && (probe[1] === "\\" || probe[1] === "/") && (probe[0] === "\\" || probe[1] === "\\")) {
+    return "";
+  }
   const lower = probe.toLowerCase();
   let schemeEnd = -1;
   for (let i = 0; i < lower.length; i++) {

package/dist/data.d.cts

@@ -57,6 +57,43 @@ declare function calculateDelay(attempt: number, strategy: "exponential" | "line
  */
 declare function withRetry<T>(fn: () => Promise<T>, options?: RetryOptions, onRetry?: (error: unknown, attempt: number, delay: number) => void, signal?: AbortSignal): Promise<T>;
 
+/**
+ * Structural sharing for the data layer.
+ *
+ * A refetch almost always produces a brand-new object graph, even when the
+ * server sent back exactly what it sent last time. Committing that graph to a
+ * signal notifies every subscriber — signals compare with `Object.is` — so a
+ * background refresh that changed nothing still re-ran every binding reading
+ * the data, and a `when(() => q.data(), …)` or a `() => q.data() && Form()`
+ * child rebuilt its subtree and threw away whatever the user was typing.
+ *
+ * `replaceEqualDeep(prev, next)` reconciles the new graph against the old one:
+ *
+ * - deeply equal → returns `prev` itself, so the signal write is a no-op and
+ *   nothing is notified;
+ * - partially equal → returns a new container in which every unchanged
+ *   subtree is the OLD reference, so an `each()` keyed by reference, a
+ *   `derived` over one branch, or an `equals`-less signal holding a sub-object
+ *   stays stable while only the changed path gets fresh identities.
+ *
+ * Only plain objects (prototype `Object.prototype` or `null`) and arrays are
+ * reconciled. Everything else — Date, Map, Set, class instances — is opaque
+ * and compared by identity: its enumerable keys say nothing about its state,
+ * and rebuilding it as a plain object would change its type.
+ *
+ * Internal to the data layer; not re-exported from `data.ts`.
+ */
+/**
+ * The public knob shared by `query()` and `resource()`.
+ *
+ * - `true` (default) — reconcile with {@link replaceEqualDeep}.
+ * - `false` — commit every result as-is (a fresh reference notifies).
+ * - a function — custom reconciliation. It receives the previously committed
+ *   value and the new one and returns what to commit; returning `prev` means
+ *   "unchanged" and notifies nobody.
+ */
+type StructuralSharingOption<T> = boolean | ((prev: T, next: T) => T);
+
 /**
  * ## Callback semantics
  *
@@ -118,8 +155,52 @@ interface QueryOptions<T> {
     onError?: (error: Error) => void;
     /** Called on fetch settle (success or error) */
     onSettled?: () => void;
-    /** Transform fetched data before returning to consumers. Cache stores raw data. */
+    /**
+     * Transform fetched data before returning to consumers. Cache stores raw data.
+     *
+     * Runs in this observer's own reactive computation: it re-runs when the
+     * cached value changes, and when a signal it reads changes — without
+     * re-running the key effect, so such a signal never triggers a refetch. It
+     * runs once per fetch that changed the data, and its output is structurally
+     * shared against this observer's previous output for the same key, so an
+     * identical refetch notifies nobody.
+     */
     select?: (data: T) => T;
+    /**
+     * Keep data referentially stable across refetches. Default: `true`.
+     *
+     * Every refetch — `refetchInterval`, window focus, reconnect,
+     * `invalidateQueries` — produces a new object graph even when the server
+     * returned the same thing. With structural sharing on, the new result is
+     * reconciled against the previous value of the same key: if it is deeply
+     * equal the previous reference is kept and `data` subscribers are not
+     * notified at all; if only part of it changed, every unchanged nested object
+     * or array keeps its old reference, so `each()` rows and deriveds over
+     * untouched branches stay put. Only plain objects and arrays are compared —
+     * Date, Map, Set and class instances compare by identity. Cyclic data is
+     * safe: the containers on a cycle are taken as-is.
+     *
+     * Every observer of a key using the default holds the SAME reference.
+     *
+     * `setQueryData()` is an explicit write, not a fetch: when it hands over a
+     * new top-level reference, observers always receive a new top-level
+     * reference and are notified — even if every child is unchanged, as after
+     * `prev.items.push(x); return { ...prev }`. Unchanged nested subtrees are
+     * still reused beneath it.
+     *
+     * The option applies to this observer only; observers of one key may use
+     * different settings.
+     *
+     * - `false` commits every result as-is (each refetch notifies).
+     * - A function `(prev, next) => T` replaces the default reconciliation;
+     *   `prev` is this observer's previous value for the same key. Return `prev`
+     *   to report "unchanged" (ignored for an explicit write of a new
+     *   reference). It must not throw — if it does, the error is reported and
+     *   `next` is committed unshared.
+     *
+     * Also applied to this observer's `select` output.
+     */
+    structuralSharing?: StructuralSharingOption<T>;
 }
 interface QueryResult<T> {
     /** Reactive getter for the cached data */
@@ -143,9 +224,20 @@ declare function query<T>(key: string | (() => string), fetcher: (ctx: {
 }) => Promise<T>, options?: QueryOptions<T>): QueryResult<T>;
 /** Invalidate queries matching a key or predicate, triggering refetch for active subscribers */
 declare function invalidateQueries(keyOrPredicate: string | ((key: string) => boolean)): void;
-/** Get cached data for a query key */
+/**
+ * Get cached data for a query key — the same reference every observer using
+ * the default `structuralSharing` holds.
+ */
 declare function getQueryData<T>(key: string): T | undefined;
-/** Set cached data for a query key, notifying subscribers */
+/**
+ * Set cached data for a query key, notifying subscribers.
+ *
+ * An explicit write: a value (or updater result) that is a new top-level
+ * reference reaches every observer as a new top-level reference, even when it
+ * is deeply equal to the previous value — so `prev.items.push(x); return
+ * { ...prev }` is never dropped. Unchanged nested subtrees are still reused.
+ * Returning `prev` itself changes nothing.
+ */
 declare function setQueryData<T>(key: string, data: T | ((prev: T | undefined) => T)): void;
 /** Clear the entire query cache */
 declare function clearQueryCache(): void;
@@ -354,6 +446,30 @@ interface ResourceOptions<T> {
     onError?: (error: Error) => void;
     /** Called on fetch settle (success or error) */
     onSettled?: () => void;
+    /**
+     * Keep data referentially stable across refetches. Default: `true`.
+     *
+     * Each fetched result — from `refetch()` or a source change — is
+     * reconciled against the value already held: a deeply equal result keeps
+     * the previous reference and notifies nobody, and a partially changed one
+     * reuses every unchanged nested object or array. Only plain objects and
+     * arrays are compared; Date, Map, Set and class instances compare by
+     * identity. Cyclic data is safe: the containers on a cycle are taken as-is.
+     * Same contract as `QueryOptions.structuralSharing`.
+     *
+     * `mutate()` is an explicit write, not a fetch: when it hands over a new
+     * top-level reference, `data` always becomes a new top-level reference and
+     * notifies — even if every child is unchanged, as after
+     * `prev.items.push(x); return { ...prev }`. Unchanged nested subtrees are
+     * still reused beneath it.
+     *
+     * - `false` commits every result as-is.
+     * - A function `(prev, next) => T` replaces the default reconciliation;
+     *   return `prev` to report "unchanged" (ignored for a `mutate()` of a new
+     *   reference). If it throws, the error is reported and `next` is committed
+     *   unshared.
+     */
+    structuralSharing?: StructuralSharingOption<T>;
 }
 interface Resource<T> {
     /** Reactive getter for the fetched data */