@buoy-gg/react-query 7.0.17 → 7.0.18

package/lib/commonjs/react-query/sync/dehydrate.js

@@ -3,13 +3,131 @@
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
+exports.UNSERIALIZABLE_DATA = exports.SNAPSHOT_DATA_INLINE_LIMIT = exports.MAX_QUERY_DETAIL_BYTES = exports.DATA_ON_DEVICE = void 0;
+exports.capQueryDetail = capQueryDetail;
 exports.dehydrateQueryClient = dehydrateQueryClient;
+exports.isDataOnDeviceMarker = isDataOnDeviceMarker;
+exports.isUnserializableMarker = isUnserializableMarker;
+exports.isWireDataMarker = isWireDataMarker;
+exports.jsonLongerThan = jsonLongerThan;
+exports.toWireData = toWireData;
+exports.toWireError = toWireError;
 /**
  * Dehydration for external sync — ported from buoy-desktop's
  * react-query-external-sync/hydration.ts so the desktop dashboard can
  * hydrate an identical mirror of the device's QueryClient.
  */
 
+/**
+ * Sentinel used in WIRE-FORM snapshots in place of oversized query/mutation
+ * data. Same hazard as redux/zustand: a single cached payload can exceed the
+ * 2MB emit budget (dashboard goes stale) or freeze JSON.stringify. Dashboards
+ * fetch the real value via `getQueryData`.
+ */
+const DATA_ON_DEVICE = exports.DATA_ON_DEVICE = Object.freeze({
+  __buoyDataOnDevice: true,
+  note: "Query data stays on the device — fetched on demand via getQueryData."
+});
+
+/** Sentinel when JSON.stringify throws (circular refs, bigint, …). */
+const UNSERIALIZABLE_DATA = exports.UNSERIALIZABLE_DATA = Object.freeze({
+  __buoyUnserializable: true,
+  note: "Query data is not JSON-serializable (circular or bigint) and stayed on the device."
+});
+
+/** Keep small payloads inline; strip anything over this (same as network bodies). */
+const SNAPSHOT_DATA_INLINE_LIMIT = exports.SNAPSHOT_DATA_INLINE_LIMIT = 16 * 1024;
+const MAX_QUERY_DETAIL_BYTES = exports.MAX_QUERY_DETAIL_BYTES = 8 * 1024 * 1024;
+function jsonLongerThan(value, limit) {
+  let bytes = 0;
+  const stack = [value];
+  const seen = new Set();
+  while (stack.length > 0) {
+    if (bytes > limit) return true;
+    const v = stack.pop();
+    if (v === null || v === undefined) bytes += 4;else if (typeof v === "string") bytes += v.length + 2;else if (typeof v === "number") bytes += 8;else if (typeof v === "boolean") bytes += 5;else if (typeof v === "object") {
+      if (seen.has(v)) continue;
+      seen.add(v);
+      if (Array.isArray(v)) {
+        bytes += 2 + v.length;
+        for (let i = 0; i < v.length; i++) stack.push(v[i]);
+      } else {
+        bytes += 2;
+        for (const k in v) {
+          bytes += k.length + 4;
+          stack.push(v[k]);
+        }
+      }
+    } else bytes += 4;
+  }
+  return bytes > limit;
+}
+function isDataOnDeviceMarker(value) {
+  return !!value && typeof value === "object" && value.__buoyDataOnDevice === true;
+}
+function isUnserializableMarker(value) {
+  return !!value && typeof value === "object" && value.__buoyUnserializable === true;
+}
+function isWireDataMarker(value) {
+  return isDataOnDeviceMarker(value) || isUnserializableMarker(value);
+}
+
+/** Replace unserializable / oversized values with a wire marker. */
+function toWireData(value) {
+  if (value === undefined) return undefined;
+  try {
+    JSON.stringify(value);
+  } catch {
+    return UNSERIALIZABLE_DATA;
+  }
+  if (jsonLongerThan(value, SNAPSHOT_DATA_INLINE_LIMIT)) {
+    return DATA_ON_DEVICE;
+  }
+  return value;
+}
+
+/**
+ * Query/mutation `error` (and `fetchFailureReason` / `failureReason`) often
+ * hold the live Axios/fetch error: `request` points at XHR (cyclic),
+ * `response.data` is the same fat body we already stripped from `state.data`.
+ * Spreading `query.state` left that copy on the wire after capping data.
+ * The dashboard only reads `error.message`.
+ */
+function toWireError(value) {
+  if (value == null) return value;
+  if (typeof value === "object") {
+    const err = value;
+    const name = typeof err.name === "string" ? err.name : undefined;
+    const message = typeof err.message === "string" ? err.message : undefined;
+    if (name !== undefined || message !== undefined) {
+      return toWireData({
+        ...(name !== undefined ? {
+          name
+        } : {}),
+        ...(message !== undefined ? {
+          message
+        } : {})
+      });
+    }
+  }
+  return toWireData(value);
+}
+
+/** Cap an on-demand detail payload (action result, not the per-tick snapshot). */
+function capQueryDetail(value) {
+  try {
+    JSON.stringify(value);
+  } catch {
+    return UNSERIALIZABLE_DATA;
+  }
+  if (jsonLongerThan(value, MAX_QUERY_DETAIL_BYTES)) {
+    return {
+      __buoyTruncated: true,
+      note: `Exceeds the ${MAX_QUERY_DETAIL_BYTES / (1024 * 1024)}MB detail limit — inspect it on-device.`
+    };
+  }
+  return value;
+}
 function dehydrateQueryClient(client) {
   const mutations = client.getMutationCache().getAll().map(mutation => dehydrateMutation(mutation));
   const queries = client.getQueryCache().getAll().map(query => dehydrateQuery(query));
@@ -19,39 +137,64 @@ function dehydrateQueryClient(client) {
   };
 }
 function dehydrateMutation(mutation) {
+  const state = mutation.state;
   return {
     mutationId: mutation.mutationId,
     mutationKey: mutation.options.mutationKey,
-    state: mutation.state,
+    state: {
+      ...state,
+      data: toWireData(state.data),
+      variables: toWireData(state.variables),
+      error: toWireError(state.error),
+      failureReason: toWireError(state.failureReason)
+    },
     ...(mutation.options.scope && {
       scope: mutation.options.scope
     }),
     ...(mutation.meta && {
-      meta: mutation.meta
+      meta: toWireData(mutation.meta)
     })
   };
 }
+function toWireObserverOptions(options) {
+  // queryFn / select / persister are functions. initialData and
+  // placeholderData are often the SAME fat tree as state.data (apps seed
+  // the cache with it). Capping state.data still left those copies on the
+  // wire and dropped the Query panel.
+  const {
+    queryFn: _queryFn,
+    select: _select,
+    persister: _persister,
+    initialData: _initialData,
+    placeholderData: _placeholderData,
+    ...light
+  } = options;
+  return {
+    ...light,
+    queryFn: undefined,
+    ...(options.meta ? {
+      meta: toWireData(options.meta)
+    } : {})
+  };
+}
 function dehydrateQuery(query) {
   const observerStates = query.observers.map(observer => ({
     queryHash: query.queryHash,
-    // Remove queryFn from observer options so the dashboard can't accidentally
-    // run device fetch functions (they aren't serializable anyway)
-    options: {
-      ...observer.options,
-      queryFn: undefined
-    }
+    options: toWireObserverOptions(observer.options)
   }));
   return {
     state: {
       ...query.state,
       ...(query.state.data !== undefined && {
-        data: query.state.data
-      })
+        data: toWireData(query.state.data)
+      }),
+      error: toWireError(query.state.error),
+      fetchFailureReason: toWireError(query.state.fetchFailureReason)
     },
     queryKey: query.queryKey,
     queryHash: query.queryHash,
     ...(query.meta && {
-      meta: query.meta
+      meta: toWireData(query.meta)
     }),
     observers: observerStates
   };

package/lib/commonjs/react-query/sync/reactQuerySyncAdapter.js

@@ -16,6 +16,9 @@ var _getQueryStatusLabel = require("../utils/getQueryStatusLabel");
  * (useSyncQueries.ts) so the dashboard keeps identical behavior, including
  * the trigger/restore loading and error simulations used by the TanStack
  * devtools UI.
+ *
+ * v2: oversized / unserializable query (and mutation) data is replaced with
+ * on-device markers. Dashboards fetch real data via `getQueryData`.
  */
 
 function createReactQuerySyncAdapter(queryClient) {
@@ -30,7 +33,7 @@ function createReactQuerySyncAdapter(queryClient) {
     return query;
   };
   return {
-    version: 1,
+    version: 2,
     getSnapshot: () => ({
       dehydratedState: (0, _dehydrate.dehydrateQueryClient)(queryClient),
       isOnlineManagerOnline: _reactQuery.onlineManager.isOnline()
@@ -46,6 +49,30 @@ function createReactQuerySyncAdapter(queryClient) {
       };
     },
     actions: {
+      /**
+       * On-demand detail: one query's real cached `data`. Wire-form snapshots
+       * replace oversized / unserializable data with markers; this is the
+       * explicit, size-guarded channel for the detail pane.
+       */
+      getQueryData: params => {
+        const {
+          queryHash
+        } = params ?? {};
+        if (!queryHash) return {
+          found: false,
+          reason: "missing queryHash"
+        };
+        const query = queryClient.getQueryCache().get(queryHash);
+        if (!query) return {
+          found: false,
+          reason: "unknown queryHash"
+        };
+        return {
+          found: true,
+          queryHash,
+          data: (0, _dehydrate.capQueryDetail)(query.state.data)
+        };
+      },
       /**
        * Compact, token-bounded cache reader for a remote driver (MCP/LLM):
        * projects each live query to light fields (hash, key, status label,

package/lib/commonjs/react-query/sync/snapshotProvider.js

@@ -6,6 +6,7 @@ Object.defineProperty(exports, "__esModule", {
 exports.createQuerySnapshotProvider = createQuerySnapshotProvider;
 exports.registerQuerySnapshotProvider = registerQuerySnapshotProvider;
 var _sharedUi = require("@buoy-gg/shared-ui");
+var _dataViewer = require("@buoy-gg/shared-ui/dataViewer");
 var _dehydrate = require("./dehydrate");
 /**
  * Time Machine snapshot provider for React Query.
@@ -32,6 +33,28 @@ function normalizeState(state) {
     fetchMeta: null
   };
 }
+
+/**
+ * The comparable projection of a query for previews: status/error/data ONLY.
+ * Timestamps (dataUpdatedAt etc.) are excluded — including them makes every
+ * query read as "changed" the moment anything refetches.
+ */
+function comparableQuery(q) {
+  return {
+    status: q.state.status,
+    error: q.state.error ?? null,
+    data: q.state.data
+  };
+}
+function queryLabel(queryKey, queryHash) {
+  try {
+    const s = JSON.stringify(queryKey);
+    return s.length > 60 ? `${s.slice(0, 57)}…` : s;
+  } catch {
+    return queryHash;
+  }
+}
+const ITEM_RENDER_BYTE_LIMIT = 256 * 1024;
 function createQuerySnapshotProvider(queryClient) {
   return {
     id: "query",
@@ -62,8 +85,12 @@ function createQuerySnapshotProvider(queryClient) {
         warnings
       };
     },
-    async restore(data) {
+    async restore(data, options) {
       const snapshot = data;
+      const excludedSet = new Set(options?.excludeKeys ?? []);
+      const includedSet = options?.includeKeys ? new Set(options.includeKeys) : null;
+      const touch = key => !excludedSet.has(key) && (!includedSet || includedSet.has(key));
+      let excludedHits = 0;
       const result = {
         ok: true,
         applied: 0,
@@ -81,6 +108,10 @@ function createQuerySnapshotProvider(queryClient) {
       const cache = queryClient.getQueryCache();
       const snapHashes = new Set(snapshot.queries.map(q => q.queryHash));
       for (const snap of snapshot.queries) {
+        if (!touch(snap.queryHash)) {
+          excludedHits += 1;
+          continue;
+        }
         try {
           const state = normalizeState(snap.state);
           const existing = cache.get(snap.queryHash);
@@ -110,6 +141,10 @@ function createQuerySnapshotProvider(queryClient) {
       // Cache entries the snapshot doesn't know about get removed; a mounted
       // observer will rebuild + refetch its query on next interaction.
       for (const query of cache.getAll().slice()) {
+        if (!touch(query.queryHash)) {
+          excludedHits += 1;
+          continue;
+        }
         if (!snapHashes.has(query.queryHash)) {
           try {
             cache.remove(query);
@@ -127,7 +162,80 @@ function createQuerySnapshotProvider(queryClient) {
         queryClient.getMutationCache().clear();
         result.warnings.push(`mutation cache cleared (${mutationCount} mutation(s))`);
       }
+      if (excludedHits > 0) {
+        result.warnings.push(`${excludedHits} quer(y/ies) excluded by you`);
+      }
       return result;
+    },
+    /** Per-query restore preview. `base` omitted = compare against live cache. */
+    async previewItems(target, base) {
+      const targetQueries = target?.queries ?? [];
+      const liveMode = base === undefined;
+      const baseQueries = liveMode ? (0, _dehydrate.dehydrateQueryClient)(queryClient).queries.map(({
+        observers: _o,
+        ...q
+      }) => q) : base?.queries ?? [];
+      const baseByHash = new Map(baseQueries.map(q => [q.queryHash, q]));
+      const targetByHash = new Map(targetQueries.map(q => [q.queryHash, q]));
+      const items = [];
+      const notes = [];
+      for (const q of targetQueries) {
+        const label = queryLabel(q.queryKey, q.queryHash);
+        const baseQ = baseByHash.get(q.queryHash);
+        if (!baseQ) {
+          items.push({
+            key: q.queryHash,
+            label,
+            verdict: "added",
+            newValue: comparableQuery(q)
+          });
+          continue;
+        }
+        const oldVal = comparableQuery(baseQ);
+        const newVal = comparableQuery(q);
+        if ((0, _dataViewer.boundedDeepEqual)(oldVal, newVal)) {
+          items.push({
+            key: q.queryHash,
+            label,
+            verdict: "unchanged"
+          });
+        } else if ((0, _dataViewer.jsonLikelyLargerThan)(oldVal, ITEM_RENDER_BYTE_LIMIT) || (0, _dataViewer.jsonLikelyLargerThan)(newVal, ITEM_RENDER_BYTE_LIMIT)) {
+          items.push({
+            key: q.queryHash,
+            label,
+            verdict: "too-large",
+            reason: "query data too large to render a diff — restore still applies it"
+          });
+        } else {
+          items.push({
+            key: q.queryHash,
+            label,
+            verdict: "changed",
+            oldValue: oldVal,
+            newValue: newVal
+          });
+        }
+      }
+      for (const q of baseQueries) {
+        if (!targetByHash.has(q.queryHash)) {
+          items.push({
+            key: q.queryHash,
+            label: queryLabel(q.queryKey, q.queryHash),
+            verdict: "removed",
+            oldValue: comparableQuery(q)
+          });
+        }
+      }
+      if (liveMode) {
+        const mutationCount = queryClient.getMutationCache().getAll().length;
+        if (mutationCount > 0) {
+          notes.push(`${mutationCount} in-memory mutation record(s) will be cleared`);
+        }
+      }
+      return {
+        items,
+        notes
+      };
     }
   };
 }

package/lib/module/react-query/sync/dehydrate.js

@@ -6,6 +6,116 @@
  * hydrate an identical mirror of the device's QueryClient.
  */
 
+/**
+ * Sentinel used in WIRE-FORM snapshots in place of oversized query/mutation
+ * data. Same hazard as redux/zustand: a single cached payload can exceed the
+ * 2MB emit budget (dashboard goes stale) or freeze JSON.stringify. Dashboards
+ * fetch the real value via `getQueryData`.
+ */
+export const DATA_ON_DEVICE = Object.freeze({
+  __buoyDataOnDevice: true,
+  note: "Query data stays on the device — fetched on demand via getQueryData."
+});
+
+/** Sentinel when JSON.stringify throws (circular refs, bigint, …). */
+export const UNSERIALIZABLE_DATA = Object.freeze({
+  __buoyUnserializable: true,
+  note: "Query data is not JSON-serializable (circular or bigint) and stayed on the device."
+});
+
+/** Keep small payloads inline; strip anything over this (same as network bodies). */
+export const SNAPSHOT_DATA_INLINE_LIMIT = 16 * 1024;
+export const MAX_QUERY_DETAIL_BYTES = 8 * 1024 * 1024;
+export function jsonLongerThan(value, limit) {
+  let bytes = 0;
+  const stack = [value];
+  const seen = new Set();
+  while (stack.length > 0) {
+    if (bytes > limit) return true;
+    const v = stack.pop();
+    if (v === null || v === undefined) bytes += 4;else if (typeof v === "string") bytes += v.length + 2;else if (typeof v === "number") bytes += 8;else if (typeof v === "boolean") bytes += 5;else if (typeof v === "object") {
+      if (seen.has(v)) continue;
+      seen.add(v);
+      if (Array.isArray(v)) {
+        bytes += 2 + v.length;
+        for (let i = 0; i < v.length; i++) stack.push(v[i]);
+      } else {
+        bytes += 2;
+        for (const k in v) {
+          bytes += k.length + 4;
+          stack.push(v[k]);
+        }
+      }
+    } else bytes += 4;
+  }
+  return bytes > limit;
+}
+export function isDataOnDeviceMarker(value) {
+  return !!value && typeof value === "object" && value.__buoyDataOnDevice === true;
+}
+export function isUnserializableMarker(value) {
+  return !!value && typeof value === "object" && value.__buoyUnserializable === true;
+}
+export function isWireDataMarker(value) {
+  return isDataOnDeviceMarker(value) || isUnserializableMarker(value);
+}
+
+/** Replace unserializable / oversized values with a wire marker. */
+export function toWireData(value) {
+  if (value === undefined) return undefined;
+  try {
+    JSON.stringify(value);
+  } catch {
+    return UNSERIALIZABLE_DATA;
+  }
+  if (jsonLongerThan(value, SNAPSHOT_DATA_INLINE_LIMIT)) {
+    return DATA_ON_DEVICE;
+  }
+  return value;
+}
+
+/**
+ * Query/mutation `error` (and `fetchFailureReason` / `failureReason`) often
+ * hold the live Axios/fetch error: `request` points at XHR (cyclic),
+ * `response.data` is the same fat body we already stripped from `state.data`.
+ * Spreading `query.state` left that copy on the wire after capping data.
+ * The dashboard only reads `error.message`.
+ */
+export function toWireError(value) {
+  if (value == null) return value;
+  if (typeof value === "object") {
+    const err = value;
+    const name = typeof err.name === "string" ? err.name : undefined;
+    const message = typeof err.message === "string" ? err.message : undefined;
+    if (name !== undefined || message !== undefined) {
+      return toWireData({
+        ...(name !== undefined ? {
+          name
+        } : {}),
+        ...(message !== undefined ? {
+          message
+        } : {})
+      });
+    }
+  }
+  return toWireData(value);
+}
+
+/** Cap an on-demand detail payload (action result, not the per-tick snapshot). */
+export function capQueryDetail(value) {
+  try {
+    JSON.stringify(value);
+  } catch {
+    return UNSERIALIZABLE_DATA;
+  }
+  if (jsonLongerThan(value, MAX_QUERY_DETAIL_BYTES)) {
+    return {
+      __buoyTruncated: true,
+      note: `Exceeds the ${MAX_QUERY_DETAIL_BYTES / (1024 * 1024)}MB detail limit — inspect it on-device.`
+    };
+  }
+  return value;
+}
 export function dehydrateQueryClient(client) {
   const mutations = client.getMutationCache().getAll().map(mutation => dehydrateMutation(mutation));
   const queries = client.getQueryCache().getAll().map(query => dehydrateQuery(query));
@@ -15,39 +125,64 @@ export function dehydrateQueryClient(client) {
   };
 }
 function dehydrateMutation(mutation) {
+  const state = mutation.state;
   return {
     mutationId: mutation.mutationId,
     mutationKey: mutation.options.mutationKey,
-    state: mutation.state,
+    state: {
+      ...state,
+      data: toWireData(state.data),
+      variables: toWireData(state.variables),
+      error: toWireError(state.error),
+      failureReason: toWireError(state.failureReason)
+    },
     ...(mutation.options.scope && {
       scope: mutation.options.scope
     }),
     ...(mutation.meta && {
-      meta: mutation.meta
+      meta: toWireData(mutation.meta)
     })
   };
 }
+function toWireObserverOptions(options) {
+  // queryFn / select / persister are functions. initialData and
+  // placeholderData are often the SAME fat tree as state.data (apps seed
+  // the cache with it). Capping state.data still left those copies on the
+  // wire and dropped the Query panel.
+  const {
+    queryFn: _queryFn,
+    select: _select,
+    persister: _persister,
+    initialData: _initialData,
+    placeholderData: _placeholderData,
+    ...light
+  } = options;
+  return {
+    ...light,
+    queryFn: undefined,
+    ...(options.meta ? {
+      meta: toWireData(options.meta)
+    } : {})
+  };
+}
 function dehydrateQuery(query) {
   const observerStates = query.observers.map(observer => ({
     queryHash: query.queryHash,
-    // Remove queryFn from observer options so the dashboard can't accidentally
-    // run device fetch functions (they aren't serializable anyway)
-    options: {
-      ...observer.options,
-      queryFn: undefined
-    }
+    options: toWireObserverOptions(observer.options)
   }));
   return {
     state: {
       ...query.state,
       ...(query.state.data !== undefined && {
-        data: query.state.data
-      })
+        data: toWireData(query.state.data)
+      }),
+      error: toWireError(query.state.error),
+      fetchFailureReason: toWireError(query.state.fetchFailureReason)
     },
     queryKey: query.queryKey,
     queryHash: query.queryHash,
     ...(query.meta && {
-      meta: query.meta
+      meta: toWireData(query.meta)
     }),
     observers: observerStates
   };

package/lib/module/react-query/sync/reactQuerySyncAdapter.js

@@ -9,9 +9,12 @@
  * (useSyncQueries.ts) so the dashboard keeps identical behavior, including
  * the trigger/restore loading and error simulations used by the TanStack
  * devtools UI.
+ *
+ * v2: oversized / unserializable query (and mutation) data is replaced with
+ * on-device markers. Dashboards fetch real data via `getQueryData`.
  */
 import { onlineManager } from "@tanstack/react-query";
-import { dehydrateQueryClient } from "./dehydrate";
+import { capQueryDetail, dehydrateQueryClient } from "./dehydrate";
 import { getQueryStatusLabel } from "../utils/getQueryStatusLabel";
 export function createReactQuerySyncAdapter(queryClient) {
   const getQuery = params => {
@@ -25,7 +28,7 @@ export function createReactQuerySyncAdapter(queryClient) {
     return query;
   };
   return {
-    version: 1,
+    version: 2,
     getSnapshot: () => ({
       dehydratedState: dehydrateQueryClient(queryClient),
       isOnlineManagerOnline: onlineManager.isOnline()
@@ -41,6 +44,30 @@ export function createReactQuerySyncAdapter(queryClient) {
       };
     },
     actions: {
+      /**
+       * On-demand detail: one query's real cached `data`. Wire-form snapshots
+       * replace oversized / unserializable data with markers; this is the
+       * explicit, size-guarded channel for the detail pane.
+       */
+      getQueryData: params => {
+        const {
+          queryHash
+        } = params ?? {};
+        if (!queryHash) return {
+          found: false,
+          reason: "missing queryHash"
+        };
+        const query = queryClient.getQueryCache().get(queryHash);
+        if (!query) return {
+          found: false,
+          reason: "unknown queryHash"
+        };
+        return {
+          found: true,
+          queryHash,
+          data: capQueryDetail(query.state.data)
+        };
+      },
       /**
        * Compact, token-bounded cache reader for a remote driver (MCP/LLM):
        * projects each live query to light fields (hash, key, status label,

package/lib/module/react-query/sync/snapshotProvider.js

@@ -18,6 +18,7 @@
  */
 
 import { registerStateSnapshotProvider } from "@buoy-gg/shared-ui";
+import { boundedDeepEqual, jsonLikelyLargerThan } from "@buoy-gg/shared-ui/dataViewer";
 import { dehydrateQueryClient } from "./dehydrate";
 /** A restored query must never claim an in-flight fetch it doesn't have. */
 function normalizeState(state) {
@@ -27,6 +28,28 @@ function normalizeState(state) {
     fetchMeta: null
   };
 }
+
+/**
+ * The comparable projection of a query for previews: status/error/data ONLY.
+ * Timestamps (dataUpdatedAt etc.) are excluded — including them makes every
+ * query read as "changed" the moment anything refetches.
+ */
+function comparableQuery(q) {
+  return {
+    status: q.state.status,
+    error: q.state.error ?? null,
+    data: q.state.data
+  };
+}
+function queryLabel(queryKey, queryHash) {
+  try {
+    const s = JSON.stringify(queryKey);
+    return s.length > 60 ? `${s.slice(0, 57)}…` : s;
+  } catch {
+    return queryHash;
+  }
+}
+const ITEM_RENDER_BYTE_LIMIT = 256 * 1024;
 export function createQuerySnapshotProvider(queryClient) {
   return {
     id: "query",
@@ -57,8 +80,12 @@ export function createQuerySnapshotProvider(queryClient) {
         warnings
       };
     },
-    async restore(data) {
+    async restore(data, options) {
       const snapshot = data;
+      const excludedSet = new Set(options?.excludeKeys ?? []);
+      const includedSet = options?.includeKeys ? new Set(options.includeKeys) : null;
+      const touch = key => !excludedSet.has(key) && (!includedSet || includedSet.has(key));
+      let excludedHits = 0;
       const result = {
         ok: true,
         applied: 0,
@@ -76,6 +103,10 @@ export function createQuerySnapshotProvider(queryClient) {
       const cache = queryClient.getQueryCache();
       const snapHashes = new Set(snapshot.queries.map(q => q.queryHash));
       for (const snap of snapshot.queries) {
+        if (!touch(snap.queryHash)) {
+          excludedHits += 1;
+          continue;
+        }
         try {
           const state = normalizeState(snap.state);
           const existing = cache.get(snap.queryHash);
@@ -105,6 +136,10 @@ export function createQuerySnapshotProvider(queryClient) {
       // Cache entries the snapshot doesn't know about get removed; a mounted
       // observer will rebuild + refetch its query on next interaction.
       for (const query of cache.getAll().slice()) {
+        if (!touch(query.queryHash)) {
+          excludedHits += 1;
+          continue;
+        }
         if (!snapHashes.has(query.queryHash)) {
           try {
             cache.remove(query);
@@ -122,7 +157,80 @@ export function createQuerySnapshotProvider(queryClient) {
         queryClient.getMutationCache().clear();
         result.warnings.push(`mutation cache cleared (${mutationCount} mutation(s))`);
       }
+      if (excludedHits > 0) {
+        result.warnings.push(`${excludedHits} quer(y/ies) excluded by you`);
+      }
       return result;
+    },
+    /** Per-query restore preview. `base` omitted = compare against live cache. */
+    async previewItems(target, base) {
+      const targetQueries = target?.queries ?? [];
+      const liveMode = base === undefined;
+      const baseQueries = liveMode ? dehydrateQueryClient(queryClient).queries.map(({
+        observers: _o,
+        ...q
+      }) => q) : base?.queries ?? [];
+      const baseByHash = new Map(baseQueries.map(q => [q.queryHash, q]));
+      const targetByHash = new Map(targetQueries.map(q => [q.queryHash, q]));
+      const items = [];
+      const notes = [];
+      for (const q of targetQueries) {
+        const label = queryLabel(q.queryKey, q.queryHash);
+        const baseQ = baseByHash.get(q.queryHash);
+        if (!baseQ) {
+          items.push({
+            key: q.queryHash,
+            label,
+            verdict: "added",
+            newValue: comparableQuery(q)
+          });
+          continue;
+        }
+        const oldVal = comparableQuery(baseQ);
+        const newVal = comparableQuery(q);
+        if (boundedDeepEqual(oldVal, newVal)) {
+          items.push({
+            key: q.queryHash,
+            label,
+            verdict: "unchanged"
+          });
+        } else if (jsonLikelyLargerThan(oldVal, ITEM_RENDER_BYTE_LIMIT) || jsonLikelyLargerThan(newVal, ITEM_RENDER_BYTE_LIMIT)) {
+          items.push({
+            key: q.queryHash,
+            label,
+            verdict: "too-large",
+            reason: "query data too large to render a diff — restore still applies it"
+          });
+        } else {
+          items.push({
+            key: q.queryHash,
+            label,
+            verdict: "changed",
+            oldValue: oldVal,
+            newValue: newVal
+          });
+        }
+      }
+      for (const q of baseQueries) {
+        if (!targetByHash.has(q.queryHash)) {
+          items.push({
+            key: q.queryHash,
+            label: queryLabel(q.queryKey, q.queryHash),
+            verdict: "removed",
+            oldValue: comparableQuery(q)
+          });
+        }
+      }
+      if (liveMode) {
+        const mutationCount = queryClient.getMutationCache().getAll().length;
+        if (mutationCount > 0) {
+          notes.push(`${mutationCount} in-memory mutation record(s) will be cleared`);
+        }
+      }
+      return {
+        items,
+        notes
+      };
     }
   };
 }

package/lib/typescript/react-query/sync/dehydrate.d.ts

@@ -4,6 +4,40 @@
  * hydrate an identical mirror of the device's QueryClient.
  */
 import type { DefaultError, MutationKey, MutationMeta, MutationScope, MutationState, QueryClient, QueryKey, QueryMeta, QueryObserverOptions, QueryState } from "@tanstack/react-query";
+/**
+ * Sentinel used in WIRE-FORM snapshots in place of oversized query/mutation
+ * data. Same hazard as redux/zustand: a single cached payload can exceed the
+ * 2MB emit budget (dashboard goes stale) or freeze JSON.stringify. Dashboards
+ * fetch the real value via `getQueryData`.
+ */
+export declare const DATA_ON_DEVICE: Readonly<{
+    __buoyDataOnDevice: true;
+    note: "Query data stays on the device — fetched on demand via getQueryData.";
+}>;
+/** Sentinel when JSON.stringify throws (circular refs, bigint, …). */
+export declare const UNSERIALIZABLE_DATA: Readonly<{
+    __buoyUnserializable: true;
+    note: "Query data is not JSON-serializable (circular or bigint) and stayed on the device.";
+}>;
+/** Keep small payloads inline; strip anything over this (same as network bodies). */
+export declare const SNAPSHOT_DATA_INLINE_LIMIT: number;
+export declare const MAX_QUERY_DETAIL_BYTES: number;
+export declare function jsonLongerThan(value: unknown, limit: number): boolean;
+export declare function isDataOnDeviceMarker(value: unknown): boolean;
+export declare function isUnserializableMarker(value: unknown): boolean;
+export declare function isWireDataMarker(value: unknown): boolean;
+/** Replace unserializable / oversized values with a wire marker. */
+export declare function toWireData(value: unknown): unknown;
+/**
+ * Query/mutation `error` (and `fetchFailureReason` / `failureReason`) often
+ * hold the live Axios/fetch error: `request` points at XHR (cyclic),
+ * `response.data` is the same fat body we already stripped from `state.data`.
+ * Spreading `query.state` left that copy on the wire after capping data.
+ * The dashboard only reads `error.message`.
+ */
+export declare function toWireError(value: unknown): unknown;
+/** Cap an on-demand detail payload (action result, not the per-tick snapshot). */
+export declare function capQueryDetail(value: unknown): unknown;
 export interface DehydratedState {
     mutations: DehydratedMutation[];
     queries: DehydratedQuery[];

package/lib/typescript/react-query/sync/dehydrate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dehydrate.d.ts","sourceRoot":"","sources":["../../../../src/react-query/sync/dehydrate.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EACV,YAAY,EAEZ,WAAW,EACX,YAAY,EACZ,aAAa,EACb,aAAa,EAEb,WAAW,EAEX,QAAQ,EACR,SAAS,EACT,oBAAoB,EACpB,UAAU,EACX,MAAM,uBAAuB,CAAC;AAE/B,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,kBAAkB,EAAE,CAAC;IAChC,OAAO,EAAE,eAAe,EAAE,CAAC;CAC5B;AAED,MAAM,WAAW,kBAAkB;IACjC,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,KAAK,EAAE,aAAa,CAAC;IACrB,IAAI,CAAC,EAAE,YAAY,CAAC;IACpB,KAAK,CAAC,EAAE,aAAa,CAAC;CACvB;AAED,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,QAAQ,CAAC;IACnB,KAAK,EAAE,UAAU,CAAC;IAClB,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB,SAAS,EAAE,aAAa,EAAE,CAAC;CAC5B;AAED,MAAM,WAAW,aAAa,CAC5B,YAAY,GAAG,OAAO,EACtB,MAAM,GAAG,YAAY,EACrB,KAAK,GAAG,YAAY,EACpB,UAAU,GAAG,YAAY,EACzB,SAAS,SAAS,QAAQ,GAAG,QAAQ;IAErC,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,oBAAoB,CAC3B,YAAY,EACZ,MAAM,EACN,KAAK,EACL,UAAU,EACV,SAAS,CACV,CAAC;CACH;AAED,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,WAAW,GAAG,eAAe,CAYzE"}
+{"version":3,"file":"dehydrate.d.ts","sourceRoot":"","sources":["../../../../src/react-query/sync/dehydrate.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EACV,YAAY,EAEZ,WAAW,EACX,YAAY,EACZ,aAAa,EACb,aAAa,EAEb,WAAW,EAEX,QAAQ,EACR,SAAS,EACT,oBAAoB,EACpB,UAAU,EACX,MAAM,uBAAuB,CAAC;AAE/B;;;;;GAKG;AACH,eAAO,MAAM,cAAc;;;EAGzB,CAAC;AAEH,sEAAsE;AACtE,eAAO,MAAM,mBAAmB;;;EAG9B,CAAC;AAEH,qFAAqF;AACrF,eAAO,MAAM,0BAA0B,QAAY,CAAC;AAEpD,eAAO,MAAM,sBAAsB,QAAkB,CAAC;AAEtD,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CA2BrE;AAED,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAM5D;AAED,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAM9D;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAExD;AAED,oEAAoE;AACpE,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAWlD;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAcnD;AAED,kFAAkF;AAClF,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAatD;AAED,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,kBAAkB,EAAE,CAAC;IAChC,OAAO,EAAE,eAAe,EAAE,CAAC;CAC5B;AAED,MAAM,WAAW,kBAAkB;IACjC,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,KAAK,EAAE,aAAa,CAAC;IACrB,IAAI,CAAC,EAAE,YAAY,CAAC;IACpB,KAAK,CAAC,EAAE,aAAa,CAAC;CACvB;AAED,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,QAAQ,CAAC;IACnB,KAAK,EAAE,UAAU,CAAC;IAClB,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB,SAAS,EAAE,aAAa,EAAE,CAAC;CAC5B;AAED,MAAM,WAAW,aAAa,CAC5B,YAAY,GAAG,OAAO,EACtB,MAAM,GAAG,YAAY,EACrB,KAAK,GAAG,YAAY,EACpB,UAAU,GAAG,YAAY,EACzB,SAAS,SAAS,QAAQ,GAAG,QAAQ;IAErC,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,oBAAoB,CAC3B,YAAY,EACZ,MAAM,EACN,KAAK,EACL,UAAU,EACV,SAAS,CACV,CAAC;CACH;AAED,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,WAAW,GAAG,eAAe,CAYzE"}

package/lib/typescript/react-query/sync/reactQuerySyncAdapter.d.ts

@@ -7,6 +7,9 @@
  * (useSyncQueries.ts) so the dashboard keeps identical behavior, including
  * the trigger/restore loading and error simulations used by the TanStack
  * devtools UI.
+ *
+ * v2: oversized / unserializable query (and mutation) data is replaced with
+ * on-device markers. Dashboards fetch real data via `getQueryData`.
  */
 import { type QueryClient } from "@tanstack/react-query";
 export declare function createReactQuerySyncAdapter(queryClient: QueryClient): {
@@ -17,6 +20,22 @@ export declare function createReactQuerySyncAdapter(queryClient: QueryClient): {
     };
     subscribe: (onChange: () => void) => () => void;
     actions: {
+        /**
+         * On-demand detail: one query's real cached `data`. Wire-form snapshots
+         * replace oversized / unserializable data with markers; this is the
+         * explicit, size-guarded channel for the detail pane.
+         */
+        getQueryData: (params: unknown) => {
+            found: false;
+            reason: string;
+            queryHash?: undefined;
+            data?: undefined;
+        } | {
+            found: true;
+            queryHash: string;
+            data: unknown;
+            reason?: undefined;
+        };
         /**
          * Compact, token-bounded cache reader for a remote driver (MCP/LLM):
          * projects each live query to light fields (hash, key, status label,

package/lib/typescript/react-query/sync/reactQuerySyncAdapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"reactQuerySyncAdapter.d.ts","sourceRoot":"","sources":["../../../../src/react-query/sync/reactQuerySyncAdapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAiB,KAAK,WAAW,EAAiB,MAAM,uBAAuB,CAAC;AA0BvF,wBAAgB,2BAA2B,CAAC,WAAW,EAAE,WAAW;;;;;;0BAgB1C,MAAM,IAAI;;QAa9B;;;;;;WAMG;8BACmB,OAAO;;;;;;;;;;;;;;;;0BAkCX,OAAO;6BAKJ,OAAO;wBAEZ,OAAO;yBACN,OAAO;+BAGD,OAAO;+BAIP,OAAO;+BAaP,OAAO;iCAEL,OAAO;iCAwBP,OAAO;;;4BA4BZ,OAAO;;EAMhC"}
+{"version":3,"file":"reactQuerySyncAdapter.d.ts","sourceRoot":"","sources":["../../../../src/react-query/sync/reactQuerySyncAdapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EAAiB,KAAK,WAAW,EAAiB,MAAM,uBAAuB,CAAC;AA0BvF,wBAAgB,2BAA2B,CAAC,WAAW,EAAE,WAAW;;;;;;0BAgB1C,MAAM,IAAI;;QAa9B;;;;WAIG;+BACoB,OAAO;;;;;;;;;;;QAY9B;;;;;;WAMG;8BACmB,OAAO;;;;;;;;;;;;;;;;0BAkCX,OAAO;6BAKJ,OAAO;wBAEZ,OAAO;yBACN,OAAO;+BAGD,OAAO;+BAIP,OAAO;+BAaP,OAAO;iCAEL,OAAO;iCAwBP,OAAO;;;4BA4BZ,OAAO;;EAMhC"}

package/lib/typescript/react-query/sync/snapshotProvider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"snapshotProvider.d.ts","sourceRoot":"","sources":["../../../../src/react-query/sync/snapshotProvider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,KAAK,EAAE,WAAW,EAAc,MAAM,uBAAuB,CAAC;AACrE,OAAO,EAEL,KAAK,qBAAqB,EAG3B,MAAM,oBAAoB,CAAC;AAc5B,wBAAgB,2BAA2B,CACzC,WAAW,EAAE,WAAW,GACvB,qBAAqB,CAsFvB;AAED,4EAA4E;AAC5E,wBAAgB,6BAA6B,CAC3C,WAAW,EAAE,WAAW,GACvB,MAAM,IAAI,CAEZ"}
+{"version":3,"file":"snapshotProvider.d.ts","sourceRoot":"","sources":["../../../../src/react-query/sync/snapshotProvider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,KAAK,EAAE,WAAW,EAAc,MAAM,uBAAuB,CAAC;AACrE,OAAO,EAEL,KAAK,qBAAqB,EAK3B,MAAM,oBAAoB,CAAC;AAuC5B,wBAAgB,2BAA2B,CACzC,WAAW,EAAE,WAAW,GACvB,qBAAqB,CAuLvB;AAED,4EAA4E;AAC5E,wBAAgB,6BAA6B,CAC3C,WAAW,EAAE,WAAW,GACvB,MAAM,IAAI,CAEZ"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@buoy-gg/react-query",
-  "version": "7.0.17",
+  "version": "7.0.18",
   "description": "TanStack Query devtools inside your React Native app — cache inspection, refetch & invalidate, offline toggle. Part of Buoy devtools.",
   "main": "lib/commonjs/index.js",
   "module": "lib/module/index.js",
@@ -29,8 +29,8 @@
     "**/snapshotProvider.ts"
   ],
   "dependencies": {
-    "@buoy-gg/shared-ui": "^7.0.17",
-    "@buoy-gg/floating-tools-core": "^7.0.17"
+    "@buoy-gg/floating-tools-core": "^7.0.18",
+    "@buoy-gg/shared-ui": "^7.0.18"
   },
   "peerDependencies": {
     "@tanstack/react-query": ">=5.0.0",