@farm.js/core 0.1.0-beta.96 → 0.1.0-beta.97

package/dist/client.cjs

@@ -32,12 +32,15 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var client_exports = {};
 __export(client_exports, {
   APIClientError: () => APIClientError,
+  FARM_CACHE_INVALIDATION_CHANNEL: () => FARM_CACHE_INVALIDATION_CHANNEL,
+  FARM_CLIENT_CACHE_PERSIST_VERSION: () => FARM_CLIENT_CACHE_PERSIST_VERSION,
   FarmClientPluginManager: () => FarmClientPluginManager,
   FetcherInputError: () => FetcherInputError,
   IntegrationClientError: () => IntegrationClientError,
   Link: () => Link,
   SPARouter: () => SPARouter,
   api: () => api,
+  clearPersistedCache: () => clearPersistedCache,
   createAPIClient: () => createAPIClient,
   createApiClients: () => createApiClients,
   createClientPluginManager: () => createClientPluginManager,
@@ -48,13 +51,16 @@ __export(client_exports, {
   createIntegrations: () => createIntegrations,
   createServerAPIClient: () => createServerAPIClient,
   createStore: () => createStore,
+  defineClientCacheAdapter: () => defineClientCacheAdapter,
   defineIntegrationAPI: () => defineIntegrationAPI,
   defineIntegrationAPIOperation: () => defineIntegrationAPIOperation,
+  enableCrossTabCacheInvalidation: () => enableCrossTabCacheInvalidation,
   endpoint: () => endpoint,
   fetchServerQuery: () => fetchServerQuery,
   getIntegrationAPIManifest: () => getIntegrationAPIManifest,
   getRouter: () => getRouter2,
   getTheme: () => getTheme,
+  initPersistedClientCache: () => initPersistedClientCache,
   installChunkErrorRecovery: () => installChunkErrorRecovery,
   integrationClients: () => integrationClients,
   integrationsClient: () => integrationsClient,
@@ -67,6 +73,7 @@ __export(client_exports, {
   readPageState: () => readPageState,
   replaceState: () => replaceState,
   setTheme: () => setTheme,
+  storageClientCacheAdapter: () => storageClientCacheAdapter,
   toggleTheme: () => toggleTheme,
   useAction: () => useAction,
   useBlocker: () => useBlocker,
@@ -224,10 +231,10 @@ __name(createClientCancellation, "createClientCancellation");
 function notifyClientObserver(observer, args, label = "Client lifecycle") {
   if (!observer) return;
   const report = /* @__PURE__ */ __name((error) => {
-    const reportError = globalThis.reportError;
-    if (typeof reportError === "function") {
+    const reportError2 = globalThis.reportError;
+    if (typeof reportError2 === "function") {
       try {
-        reportError.call(globalThis, error);
+        reportError2.call(globalThis, error);
         return;
       } catch {
       }
@@ -1218,7 +1225,13 @@ function recordFarmEventTrace(event) {
       activeSpan.addEvent(event.type, toEventAttributes(event), event.timestamp);
     }
     const error = event.type === "request.error" ? void 0 : getEventError(event);
-    if (error !== void 0) recordSpanError(activeSpan, error);
+    if (error !== void 0) {
+      if (event.type === "render.error") {
+        recordSpanException(activeSpan, error);
+      } else {
+        recordSpanError(activeSpan, error);
+      }
+    }
   }
   const completedTraceContext = recordCompletedEventSpan(event, activeContext);
   return traceContext ?? completedTraceContext;
@@ -1315,12 +1328,26 @@ function getCompletedSpanDescriptor(event) {
   }
 }
 __name(getCompletedSpanDescriptor, "getCompletedSpanDescriptor");
+function hashFarmCacheKey(value) {
+  let hash = 2166136261;
+  for (let index = 0; index < value.length; index++) {
+    hash ^= value.charCodeAt(index);
+    hash = Math.imul(hash, 16777619);
+  }
+  return (hash >>> 0).toString(16).padStart(8, "0");
+}
+__name(hashFarmCacheKey, "hashFarmCacheKey");
 function toEventAttributes(event) {
   const attributes = {};
+  const redactKey = typeof event.type === "string" && event.type.startsWith("cache.");
   for (const [key, value] of Object.entries(event)) {
     if (key === "timestamp" || key === "level" || key === "error" || key === "traceId" || key === "spanId" || key === "traceSampled" || value === void 0) {
       continue;
     }
+    if (redactKey && key === "key" && typeof value === "string") {
+      attributes["farm.key_hash"] = hashFarmCacheKey(value);
+      continue;
+    }
     if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
       attributes[`farm.${key}`] = value;
     } else if (Array.isArray(value)) {
@@ -1340,9 +1367,14 @@ function getEventError(event) {
   return "error" in event ? event.error : void 0;
 }
 __name(getEventError, "getEventError");
-function recordSpanError(span, error) {
+function recordSpanException(span, error) {
   const normalized = error instanceof Error ? error : new Error(String(error));
   span.recordException(normalized);
+  return normalized;
+}
+__name(recordSpanException, "recordSpanException");
+function recordSpanError(span, error) {
+  const normalized = recordSpanException(span, error);
   span.setStatus({ code: import_api.SpanStatusCode.ERROR, message: normalized.message });
 }
 __name(recordSpanError, "recordSpanError");
@@ -1502,10 +1534,19 @@ function getFarmCacheInvalidationState() {
   });
 }
 __name(getFarmCacheInvalidationState, "getFarmCacheInvalidationState");
+function warnFarmCacheListenerError(scope, error) {
+  const detail = error instanceof Error ? error.stack ?? error.message : String(error);
+  console.warn(`[farm:cache] ${scope} listener failed: ${detail}`);
+}
+__name(warnFarmCacheListenerError, "warnFarmCacheListenerError");
 function notifyFarmCacheInvalidation(key) {
   if (typeof key !== "string" || key.length === 0) return;
   for (const listener of getFarmCacheInvalidationState().listeners) {
-    listener(key);
+    try {
+      listener(key);
+    } catch (error) {
+      warnFarmCacheListenerError("invalidation", error);
+    }
   }
 }
 __name(notifyFarmCacheInvalidation, "notifyFarmCacheInvalidation");
@@ -1518,6 +1559,14 @@ function applyFarmCacheInvalidations(keys) {
   }
 }
 __name(applyFarmCacheInvalidations, "applyFarmCacheInvalidations");
+function encodeFarmCacheInvalidations(keys) {
+  const normalized = Array.from(
+    new Set(keys.filter((key) => typeof key === "string" && key.length > 0))
+  );
+  if (normalized.length === 0) return null;
+  return encodeURIComponent(JSON.stringify(normalized));
+}
+__name(encodeFarmCacheInvalidations, "encodeFarmCacheInvalidations");
 function decodeFarmCacheInvalidations(value) {
   if (!value) return [];
   try {
@@ -2237,6 +2286,7 @@ function subscribeWeakCache(reference) {
   return dispose;
 }
 __name(subscribeWeakCache, "subscribeWeakCache");
+var DEFAULT_GC_SWEEP_INTERVAL_MS = 3e4;
 var _FarmClientDataCache = class _FarmClientDataCache {
   constructor(options = {}) {
     this.entries = /* @__PURE__ */ new Map();
@@ -2244,6 +2294,7 @@ var _FarmClientDataCache = class _FarmClientDataCache {
     this.invalidatedAt = /* @__PURE__ */ new Map();
     this.listeners = /* @__PURE__ */ new Map();
     this.inflight = /* @__PURE__ */ new Map();
+    this.gcSweepIntervalMs = options.gcSweepIntervalMs ?? DEFAULT_GC_SWEEP_INTERVAL_MS;
     if (options.subscribeToInvalidation !== false) {
       if (typeof WeakRef === "function") {
         const reference = new WeakRef(this);
@@ -2260,6 +2311,10 @@ var _FarmClientDataCache = class _FarmClientDataCache {
   get size() {
     return this.entries.size;
   }
+  /** @internal Attach or detach the persistence engine's observation sink. */
+  attachPersistence(sink) {
+    this.persistence = sink;
+  }
   resolveKey(key) {
     let resolved = key;
     const seen = /* @__PURE__ */ new Set();
@@ -2275,6 +2330,7 @@ var _FarmClientDataCache = class _FarmClientDataCache {
     if (!entry) return void 0;
     if (entry.gcAt !== void 0 && now2 >= entry.gcAt) {
       this.entries.delete(resolved);
+      this.persistence?.onDelete(resolved);
       this.emit(resolved);
       return void 0;
     }
@@ -2288,6 +2344,8 @@ var _FarmClientDataCache = class _FarmClientDataCache {
       this.invalidatedAt.delete(resolved);
     }
     this.entries.set(resolved, nextEntry);
+    if (nextEntry.gcAt !== void 0) this.scheduleGcSweep();
+    this.persistence?.onSet(resolved, nextEntry);
     this.emit(resolved);
     return this;
   }
@@ -2295,6 +2353,7 @@ var _FarmClientDataCache = class _FarmClientDataCache {
     const resolved = this.resolveKey(key);
     const deleted = this.entries.delete(resolved);
     this.inflight.delete(resolved);
+    if (deleted) this.persistence?.onDelete(resolved);
     this.emit(resolved);
     return deleted;
   }
@@ -2304,11 +2363,16 @@ var _FarmClientDataCache = class _FarmClientDataCache {
     this.aliases.clear();
     this.invalidatedAt.clear();
     this.inflight.clear();
+    this.persistence?.onClear();
     for (const key of keys) this.emit(key);
   }
   dispose() {
     this.unsubscribeInvalidation?.();
     this.unsubscribeInvalidation = void 0;
+    if (this.gcTimer !== void 0) {
+      clearTimeout(this.gcTimer);
+      this.gcTimer = void 0;
+    }
     this.clear();
   }
   isStale(key, now2 = Date.now()) {
@@ -2337,8 +2401,9 @@ var _FarmClientDataCache = class _FarmClientDataCache {
     const resolvedInvalidatedAt = this.invalidatedAt.get(resolved);
     if (aliasEntry && !this.entries.has(resolved)) {
       this.entries.set(resolved, aliasEntry);
+      this.persistence?.onSet(resolved, aliasEntry);
     }
-    this.entries.delete(alias);
+    if (this.entries.delete(alias)) this.persistence?.onDelete(alias);
     this.invalidatedAt.delete(alias);
     const invalidatedAt = [aliasInvalidatedAt, resolvedInvalidatedAt].reduce(
       (latest, value) => value === void 0 ? latest : latest === void 0 ? value : Math.max(latest, value),
@@ -2378,7 +2443,9 @@ var _FarmClientDataCache = class _FarmClientDataCache {
     listeners2.add(listener);
     return () => {
       listeners2.delete(listener);
-      if (listeners2.size === 0) this.listeners.delete(key);
+      if (listeners2.size === 0 && this.listeners.get(key) === listeners2) {
+        this.listeners.delete(key);
+      }
     };
   }
   getInflight(key) {
@@ -2390,6 +2457,30 @@ var _FarmClientDataCache = class _FarmClientDataCache {
   deleteInflight(key) {
     this.inflight.delete(this.resolveKey(key));
   }
+  scheduleGcSweep() {
+    if (this.gcSweepIntervalMs === false || this.gcTimer !== void 0) return;
+    const timer = setTimeout(() => {
+      this.gcTimer = void 0;
+      this.sweepExpiredEntries();
+    }, this.gcSweepIntervalMs);
+    timer.unref?.();
+    this.gcTimer = timer;
+  }
+  sweepExpiredEntries(now2 = Date.now()) {
+    const watched = /* @__PURE__ */ new Set();
+    for (const key of this.listeners.keys()) watched.add(this.resolveKey(key));
+    let remaining = false;
+    for (const [key, entry] of this.entries) {
+      if (entry.gcAt === void 0) continue;
+      if (now2 < entry.gcAt || entry.fetching || this.inflight.has(key) || watched.has(key)) {
+        remaining = true;
+        continue;
+      }
+      this.entries.delete(key);
+      this.persistence?.onDelete(key);
+    }
+    if (remaining) this.scheduleGcSweep();
+  }
   emit(key, event) {
     this.notifyListeners(key, event);
     for (const [alias, target] of this.aliases) {
@@ -3027,70 +3118,6 @@ function createAPIClientRuntime(options = {}, transport) {
   let scopedRequestState;
   const routeMeta = transport?.routeMeta ?? /* @__PURE__ */ new WeakMap();
   let requestCounter = 0;
-  const applyOptimisticLayer = /* @__PURE__ */ __name((entry, layer) => {
-    let data = entry?.data;
-    for (const updater of layer.updaters) data = updater(data);
-    return {
-      data,
-      updatedAt: layer.updatedAt,
-      staleAt: entry?.staleAt ?? layer.staleAt,
-      gcAt: entry?.gcAt ?? layer.gcAt,
-      invalidatedAt: entry?.invalidatedAt,
-      [API_CACHE_REFETCH]: entry?.[API_CACHE_REFETCH]
-    };
-  }, "applyOptimisticLayer");
-  const storeOptimisticEntry = /* @__PURE__ */ __name((cacheState, key, stack, entry) => {
-    if (!entry) {
-      cacheState.delete(key);
-      stack.renderedEntry = void 0;
-      return;
-    }
-    cacheState.set(key, entry);
-    if (stack.invalidatedAt !== void 0) {
-      cacheState.invalidate(key, stack.invalidatedAt);
-    }
-    stack.renderedEntry = cacheState.get(key);
-  }, "storeOptimisticEntry");
-  const reconcileOptimisticInvalidation = /* @__PURE__ */ __name((cacheState, key, stack) => {
-    const current = cacheState.get(key);
-    const rendered = stack.renderedEntry;
-    if (current === rendered) return true;
-    if (!current || !rendered || current.data !== rendered.data || current.updatedAt !== rendered.updatedAt || current.gcAt !== rendered.gcAt || current.status !== rendered.status || current.error !== rendered.error || current.fetching !== rendered.fetching || current.staleAt !== 0 || current.invalidatedAt === void 0) {
-      return false;
-    }
-    stack.invalidatedAt = current.invalidatedAt;
-    stack.renderedEntry = current;
-    return true;
-  }, "reconcileOptimisticInvalidation");
-  const renderOptimisticStack = /* @__PURE__ */ __name((cacheState, key, stack) => {
-    let entry = stack.entry ? { ...stack.entry } : void 0;
-    for (const layer of stack.layers) entry = applyOptimisticLayer(entry, layer);
-    storeOptimisticEntry(cacheState, key, stack, entry);
-  }, "renderOptimisticStack");
-  const settleOptimisticUpdates = /* @__PURE__ */ __name((cacheState, optimisticState, snapshots, outcome) => {
-    const settledKeys = [];
-    for (const snapshot of snapshots) {
-      const stack = optimisticState.get(snapshot.key);
-      if (stack !== snapshot.stack) continue;
-      if (!reconcileOptimisticInvalidation(cacheState, snapshot.key, stack)) {
-        optimisticState.delete(snapshot.key);
-        continue;
-      }
-      if (outcome === "rollback") {
-        stack.layers = stack.layers.filter((layer) => layer !== snapshot.layer);
-      } else {
-        snapshot.layer.committed = true;
-        if (outcome === "invalidate") stack.invalidatedAt = Date.now();
-      }
-      while (stack.layers[0]?.committed) {
-        stack.entry = applyOptimisticLayer(stack.entry, stack.layers.shift());
-      }
-      renderOptimisticStack(cacheState, snapshot.key, stack);
-      if (stack.layers.length === 0) optimisticState.delete(snapshot.key);
-      settledKeys.push(snapshot.key);
-    }
-    return settledKeys;
-  }, "settleOptimisticUpdates");
   const fetchClient = /* @__PURE__ */ __name(async (path, requestOptions, defaultHeaders, cancellation) => {
     const url = resolveFarmAPIRequestURL(path, baseURL);
     const method = String(requestOptions.method || "GET").toUpperCase();
@@ -3467,6 +3494,7 @@ function createAPIClientRuntime(options = {}, transport) {
                 staleAt: updatedAt + staleTime,
                 gcAt: getGcAt(updatedAt, cacheOptions?.gcTime),
                 invalidatedAt: void 0,
+                persist: cacheOptions?.persist === true ? true : void 0,
                 [API_CACHE_REFETCH]: createCacheRefetch(
                   request,
                   path,
@@ -3814,6 +3842,151 @@ function getOptimisticState(cache) {
   return state;
 }
 __name(getOptimisticState, "getOptimisticState");
+function applyOptimisticLayer(entry, layer) {
+  let data = entry?.data;
+  for (const updater of layer.updaters) data = updater(data);
+  return {
+    data,
+    updatedAt: layer.updatedAt,
+    staleAt: entry?.staleAt ?? layer.staleAt,
+    gcAt: entry?.gcAt ?? layer.gcAt,
+    invalidatedAt: entry?.invalidatedAt,
+    [API_CACHE_REFETCH]: entry?.[API_CACHE_REFETCH]
+  };
+}
+__name(applyOptimisticLayer, "applyOptimisticLayer");
+function storeOptimisticEntry(cacheState, key, stack, entry) {
+  if (!entry) {
+    cacheState.delete(key);
+    stack.renderedEntry = void 0;
+    return;
+  }
+  cacheState.set(key, entry);
+  if (stack.invalidatedAt !== void 0) {
+    cacheState.invalidate(key, stack.invalidatedAt);
+  }
+  stack.renderedEntry = cacheState.get(key);
+}
+__name(storeOptimisticEntry, "storeOptimisticEntry");
+function reconcileOptimisticInvalidation(cacheState, key, stack) {
+  const current = cacheState.get(key);
+  const rendered = stack.renderedEntry;
+  if (current === rendered) return true;
+  if (!current || !rendered || current.data !== rendered.data || current.updatedAt !== rendered.updatedAt || current.gcAt !== rendered.gcAt || current.status !== rendered.status || current.error !== rendered.error || current.fetching !== rendered.fetching || current.staleAt !== 0 || current.invalidatedAt === void 0) {
+    return false;
+  }
+  stack.invalidatedAt = current.invalidatedAt;
+  stack.renderedEntry = current;
+  return true;
+}
+__name(reconcileOptimisticInvalidation, "reconcileOptimisticInvalidation");
+function renderOptimisticStack(cacheState, key, stack) {
+  let entry = stack.entry ? { ...stack.entry } : void 0;
+  for (const layer of stack.layers) entry = applyOptimisticLayer(entry, layer);
+  storeOptimisticEntry(cacheState, key, stack, entry);
+}
+__name(renderOptimisticStack, "renderOptimisticStack");
+function settleOptimisticUpdates(cacheState, optimisticState, snapshots, outcome) {
+  const settledKeys = [];
+  for (const snapshot of snapshots) {
+    const stack = optimisticState.get(snapshot.key);
+    if (stack !== snapshot.stack) continue;
+    if (!reconcileOptimisticInvalidation(cacheState, snapshot.key, stack)) {
+      optimisticState.delete(snapshot.key);
+      continue;
+    }
+    if (outcome === "rollback") {
+      stack.layers = stack.layers.filter((layer) => layer !== snapshot.layer);
+    } else {
+      snapshot.layer.committed = true;
+      if (outcome === "invalidate") stack.invalidatedAt = Date.now();
+    }
+    while (stack.layers[0]?.committed) {
+      stack.entry = applyOptimisticLayer(stack.entry, stack.layers.shift());
+    }
+    renderOptimisticStack(cacheState, snapshot.key, stack);
+    if (stack.layers.length === 0) optimisticState.delete(snapshot.key);
+    settledKeys.push(snapshot.key);
+  }
+  return settledKeys;
+}
+__name(settleOptimisticUpdates, "settleOptimisticUpdates");
+function applyServerFnOptimisticUpdates(updates, now2 = Date.now()) {
+  const cacheState = getFarmClientDataCache();
+  const optimisticState = getOptimisticState(cacheState);
+  const snapshots = /* @__PURE__ */ new Map();
+  for (const update of updates) {
+    if (update.length !== 2) continue;
+    const [target, updater] = update;
+    if (typeof updater !== "function") continue;
+    const targetKey = typeof target === "string" || Array.isArray(target) ? normalizeFarmClientCacheKey(target) : null;
+    if (!targetKey) continue;
+    const targetEntry = getValidCacheEntry(cacheState, targetKey, now2);
+    const currentEntry = cacheState.get(targetKey);
+    let stack = optimisticState.get(targetKey);
+    if (stack && !reconcileOptimisticInvalidation(cacheState, targetKey, stack)) {
+      stack = void 0;
+    }
+    if (!stack) {
+      stack = {
+        entry: targetEntry ? { ...targetEntry } : void 0,
+        layers: [],
+        renderedEntry: currentEntry
+      };
+      optimisticState.set(targetKey, stack);
+    }
+    let snapshot = snapshots.get(targetKey);
+    if (!snapshot) {
+      const previousEntry = stack.layers.length === 0 ? stack.entry : stack.renderedEntry;
+      const layer = {
+        updaters: [],
+        updatedAt: now2,
+        // A server function has no cache policy of its own; preserve the
+        // target read's freshness metadata when it exists.
+        staleAt: targetEntry?.staleAt ?? now2,
+        gcAt: targetEntry?.gcAt
+      };
+      stack.layers.push(layer);
+      snapshot = { key: targetKey, stack, layer };
+      snapshots.set(targetKey, snapshot);
+      snapshot.layer.updaters.push(updater);
+      const nextEntry2 = applyOptimisticLayer(previousEntry, {
+        ...snapshot.layer,
+        updaters: [updater]
+      });
+      storeOptimisticEntry(cacheState, targetKey, stack, nextEntry2);
+      continue;
+    }
+    snapshot.layer.updaters.push(updater);
+    const nextEntry = applyOptimisticLayer(stack.renderedEntry, {
+      ...snapshot.layer,
+      updaters: [updater]
+    });
+    storeOptimisticEntry(cacheState, targetKey, stack, nextEntry);
+  }
+  return Array.from(snapshots.values());
+}
+__name(applyServerFnOptimisticUpdates, "applyServerFnOptimisticUpdates");
+function settleServerFnOptimisticUpdates(snapshots, outcome) {
+  if (snapshots.length === 0) return;
+  const cacheState = getFarmClientDataCache();
+  settleOptimisticUpdates(cacheState, getOptimisticState(cacheState), snapshots, outcome);
+}
+__name(settleServerFnOptimisticUpdates, "settleServerFnOptimisticUpdates");
+function resolveServerFnInvalidateTargets(invalidate) {
+  const targets = Array.isArray(invalidate) ? invalidate : invalidate.targets;
+  const keys = [];
+  for (const target of targets) {
+    if (typeof target === "string" || Array.isArray(target)) {
+      if (Array.isArray(target) && typeof target[0] === "function") continue;
+      keys.push(normalizeFarmClientCacheKey(target));
+    } else if (target && typeof target === "object" && "key" in target) {
+      keys.push(normalizeFarmClientCacheKey(target.key));
+    }
+  }
+  return keys;
+}
+__name(resolveServerFnInvalidateTargets, "resolveServerFnInvalidateTargets");
 function buildCacheKey(method, path, input, baseURL, defaultHeaders) {
   const keyInput = input && typeof input === "object" ? {
     query: input.query,
@@ -3992,6 +4165,42 @@ __name(readEndpointErrorEnvelope, "readEndpointErrorEnvelope");
 
 // src/mutation-client.ts
 var import_react = require("react");
+
+// src/client-network-status.ts
+function isNavigatorOnline() {
+  if (typeof navigator === "undefined" || typeof navigator.onLine !== "boolean") return true;
+  return navigator.onLine;
+}
+__name(isNavigatorOnline, "isNavigatorOnline");
+function subscribeOnline(listener) {
+  if (typeof window === "undefined") return () => {
+  };
+  window.addEventListener("online", listener);
+  return () => window.removeEventListener("online", listener);
+}
+__name(subscribeOnline, "subscribeOnline");
+
+// src/mutation-retry.ts
+async function invokeMutationWithRetry(invoke, retry, shouldContinue) {
+  const maxRetries = Math.max(0, retry?.count ?? 0);
+  let attempt = 0;
+  while (true) {
+    try {
+      return await invoke();
+    } catch (error) {
+      if (attempt >= maxRetries || !shouldContinue()) throw error;
+      attempt += 1;
+      const delay2 = typeof retry?.delay === "function" ? retry.delay(attempt) : retry?.delay ?? 0;
+      if (delay2 > 0) {
+        await new Promise((resolve) => setTimeout(resolve, delay2));
+        if (!shouldContinue()) throw error;
+      }
+    }
+  }
+}
+__name(invokeMutationWithRetry, "invokeMutationWithRetry");
+
+// src/mutation-client.ts
 function useMutation(target, options = {}) {
   return useMutationLifecycle(target, options).mutation;
 }
@@ -4004,12 +4213,14 @@ function useMutationLifecycle(target, options = {}) {
   const lastResetIdRef = (0, import_react.useRef)(0);
   const initialState = {
     pendingCount: 0,
+    pausedCount: 0,
     status: "idle",
     data: initialData,
     error: null,
     variables: void 0
   };
   const stateRef = (0, import_react.useRef)(initialState);
+  const resetWakersRef = (0, import_react.useRef)(/* @__PURE__ */ new Set());
   const [state, setState] = (0, import_react.useState)(initialState);
   optionsRef.current = options;
   targetRef.current = target;
@@ -4021,6 +4232,31 @@ function useMutationLifecycle(target, options = {}) {
     },
     []
   );
+  const waitForReconnect = (0, import_react.useCallback)(
+    async (requestId) => {
+      while (!isNavigatorOnline()) {
+        if (requestId < lastResetIdRef.current) return;
+        setMutationState((current) => ({ ...current, pausedCount: current.pausedCount + 1 }));
+        try {
+          await new Promise((resolve) => {
+            const wake = /* @__PURE__ */ __name(() => {
+              unsubscribe();
+              resetWakersRef.current.delete(wake);
+              resolve();
+            }, "wake");
+            const unsubscribe = subscribeOnline(wake);
+            resetWakersRef.current.add(wake);
+          });
+        } finally {
+          setMutationState((current) => ({
+            ...current,
+            pausedCount: Math.max(0, current.pausedCount - 1)
+          }));
+        }
+      }
+    },
+    [setMutationState]
+  );
   const mutatePreparedAsync = (0, import_react.useCallback)(
     async (prepare) => {
       const requestId = ++requestIdRef.current;
@@ -4043,17 +4279,49 @@ function useMutationLifecycle(target, options = {}) {
         if (requestId !== requestIdRef.current) return { ...current, pendingCount };
         return {
           pendingCount,
+          pausedCount: current.pausedCount,
           status: "pending",
           data: hasOptimisticData ? optimisticData : currentOptions.resetOnMutate === false ? current.data : null,
           error: null,
           variables
         };
       });
+      const mutationTarget = targetRef.current;
+      const isAPITarget = isAPIRouteRef(mutationTarget);
+      const sharedOptimistic = !preparationFailed && !isAPITarget ? currentOptions.request?.optimistic : void 0;
+      const sharedSnapshots = sharedOptimistic?.update?.length ? applyServerFnOptimisticUpdates(sharedOptimistic.update) : [];
       try {
         if (preparationFailed) throw preparationError;
-        const mutationTarget = targetRef.current;
-        const rawResult = isAPIRouteRef(mutationTarget) ? await mutationTarget(variables, currentOptions.request) : await mutationTarget(variables);
-        const data = unwrapMutationResult(rawResult, isAPIRouteRef(mutationTarget));
+        let data;
+        while (true) {
+          if (currentOptions.networkMode === "online") {
+            await waitForReconnect(requestId);
+            if (requestId < lastResetIdRef.current) {
+              throw new Error("Mutation reset while waiting for reconnection");
+            }
+          }
+          try {
+            const rawResult = isAPITarget ? await mutationTarget(variables, currentOptions.request) : await invokeMutationWithRetry(
+              () => targetRef.current(variables),
+              currentOptions.request?.retry,
+              // A reset disowns this submission; stop scheduling retries then.
+              () => requestId >= lastResetIdRef.current
+            );
+            data = unwrapMutationResult(rawResult, isAPITarget);
+            break;
+          } catch (cause) {
+            if (currentOptions.networkMode === "online" && !isNavigatorOnline() && requestId >= lastResetIdRef.current) {
+              continue;
+            }
+            throw cause;
+          }
+        }
+        settleServerFnOptimisticUpdates(sharedSnapshots, "commit");
+        if (!isAPITarget && currentOptions.request?.invalidate) {
+          for (const key of resolveServerFnInvalidateTargets(currentOptions.request.invalidate)) {
+            notifyFarmCacheInvalidation(key);
+          }
+        }
         const isLatestRequest = requestId === requestIdRef.current;
         setMutationState((current) => {
           if (requestId < lastResetIdRef.current) return current;
@@ -4066,6 +4334,7 @@ function useMutationLifecycle(target, options = {}) {
           }
           return {
             pendingCount,
+            pausedCount: current.pausedCount,
             status: "success",
             data,
             error: null,
@@ -4084,6 +4353,10 @@ function useMutationLifecycle(target, options = {}) {
         }
         return data;
       } catch (cause) {
+        settleServerFnOptimisticUpdates(
+          sharedSnapshots,
+          sharedOptimistic?.rollbackOnError ? "rollback" : "invalidate"
+        );
         const error = normalizeMutationError(cause);
         const isLatestRequest = requestId === requestIdRef.current;
         setMutationState((current) => {
@@ -4097,6 +4370,7 @@ function useMutationLifecycle(target, options = {}) {
           }
           return {
             pendingCount,
+            pausedCount: current.pausedCount,
             status: "error",
             data: hasOptimisticData && currentOptions.rollbackOnError ? previousData : currentOptions.resetOnMutate === false ? current.data : null,
             error,
@@ -4116,7 +4390,7 @@ function useMutationLifecycle(target, options = {}) {
         throw error;
       }
     },
-    [setMutationState]
+    [setMutationState, waitForReconnect]
   );
   const mutateAsync = (0, import_react.useCallback)(
     (variables) => mutatePreparedAsync(() => variables),
@@ -4133,15 +4407,20 @@ function useMutationLifecycle(target, options = {}) {
     lastResetIdRef.current = ++requestIdRef.current;
     setMutationState({
       pendingCount: 0,
+      pausedCount: 0,
       status: "idle",
       data: optionsRef.current.initialData ?? null,
       error: null,
       variables: void 0
     });
+    const wakers = Array.from(resetWakersRef.current);
+    resetWakersRef.current.clear();
+    for (const wake of wakers) wake();
   }, [setMutationState]);
   const mutation = (0, import_react.useMemo)(
     () => ({
       pending: state.pendingCount > 0,
+      paused: state.pausedCount > 0,
       status: state.status,
       data: state.data,
       error: state.error,
@@ -4156,6 +4435,7 @@ function useMutationLifecycle(target, options = {}) {
       reset,
       state.data,
       state.error,
+      state.pausedCount,
       state.pendingCount,
       state.status,
       state.variables
@@ -4275,6 +4555,7 @@ function useFetcher(target, options = {}) {
       state: mutation.pending ? "submitting" : "idle",
       status: mutation.status,
       pending: mutation.pending,
+      paused: mutation.paused,
       data: mutation.data,
       error: mutation.error,
       variables: mutation.variables,
@@ -4289,6 +4570,7 @@ function useFetcher(target, options = {}) {
       formData,
       mutation.data,
       mutation.error,
+      mutation.paused,
       mutation.pending,
       mutation.status,
       mutation.variables,
@@ -4307,9 +4589,18 @@ function mapFetcherFormData(target, formData, options) {
   if (!isAPIRouteRef(target)) {
     return formData;
   }
-  const values = formDataToObject(formData);
   const method = getAPIRouteRefMetadata(target)?.method;
-  return method === "GET" || method === "HEAD" ? { query: values } : { body: values };
+  const query = method === "GET" || method === "HEAD";
+  const encoding = context2.submitter?.getAttribute("formenctype") ?? context2.form?.enctype;
+  if (!query && (encoding?.toLowerCase() === "multipart/form-data" || Array.from(formData.values()).some((value) => typeof value !== "string"))) {
+    const body = new FormData();
+    for (const [key, value] of formData) {
+      if (!isUnsafeFormKey(key)) body.append(key, value);
+    }
+    return { body };
+  }
+  const values = formDataToObject(formData);
+  return query ? { query: values } : { body: values };
 }
 __name(mapFetcherFormData, "mapFetcherFormData");
 function resolveFetcherFormAction(target, metadata) {
@@ -4321,7 +4612,7 @@ __name(resolveFetcherFormAction, "resolveFetcherFormAction");
 function formDataToObject(formData) {
   const output = /* @__PURE__ */ Object.create(null);
   for (const [key, value] of formData.entries()) {
-    if (key === "__proto__" || key === "constructor" || key === "prototype") continue;
+    if (isUnsafeFormKey(key)) continue;
     const current = output[key];
     if (current === void 0) {
       output[key] = value;
@@ -4334,6 +4625,10 @@ function formDataToObject(formData) {
   return output;
 }
 __name(formDataToObject, "formDataToObject");
+function isUnsafeFormKey(key) {
+  return key === "__proto__" || key === "constructor" || key === "prototype";
+}
+__name(isUnsafeFormKey, "isUnsafeFormKey");
 function createSubmitterFormData(form, submitter) {
   try {
     return new FormData(form, submitter);
@@ -4415,7 +4710,12 @@ function useServerFn(serverFn, options = {}) {
         };
       });
       try {
-        const result = await serverFn(input);
+        const result = await invokeMutationWithRetry(
+          () => serverFn(input),
+          options.retry,
+          // A reset disowns this submission; stop scheduling retries then.
+          () => requestId >= lastResetIdRef.current
+        );
         const isLatestRequest = requestId === requestIdRef.current;
         setActionState((current) => {
           if (requestId < lastResetIdRef.current) return current;
@@ -4472,7 +4772,14 @@ function useServerFn(serverFn, options = {}) {
         throw error;
       }
     },
-    [options.optimistic, options.rollbackOnError, resetOnSubmit, serverFn, setActionState]
+    [
+      options.optimistic,
+      options.retry,
+      options.rollbackOnError,
+      resetOnSubmit,
+      serverFn,
+      setActionState
+    ]
   );
   const formAction = (0, import_react3.useCallback)(
     async (formData) => {
@@ -4574,6 +4881,21 @@ __name(isFormData3, "isFormData");
 // src/server-query-client.ts
 var import_react4 = require("react");
 
+// src/client-revalidation.ts
+function attachRevalidationListeners(refresh, options = {}) {
+  if (typeof window === "undefined") return () => {
+  };
+  const onFocus = options.refetchOnWindowFocus === false ? void 0 : refresh;
+  const onOnline = options.refetchOnReconnect === false ? void 0 : refresh;
+  if (onFocus) window.addEventListener("focus", onFocus);
+  if (onOnline) window.addEventListener("online", onOnline);
+  return () => {
+    if (onFocus) window.removeEventListener("focus", onFocus);
+    if (onOnline) window.removeEventListener("online", onOnline);
+  };
+}
+__name(attachRevalidationListeners, "attachRevalidationListeners");
+
 // src/server-query-runtime.ts
 var FARM_SERVER_QUERY_CLIENT_STATE = /* @__PURE__ */ Symbol.for("farm.serverQueryClientState");
 var serverQueryClientGlobal = globalThis;
@@ -4581,9 +4903,30 @@ var serverQueryClientState = serverQueryClientGlobal[FARM_SERVER_QUERY_CLIENT_ST
   functionIds: /* @__PURE__ */ new WeakMap(),
   nextFunctionId: 0,
   active: [],
-  latestOwners: /* @__PURE__ */ new Map()
+  latestOwners: /* @__PURE__ */ new Map(),
+  owners: /* @__PURE__ */ new Set()
 });
 serverQueryClientState.latestOwners ?? (serverQueryClientState.latestOwners = /* @__PURE__ */ new Map());
+serverQueryClientState.owners ?? (serverQueryClientState.owners = /* @__PURE__ */ new Set());
+function isServerQueryOwnerSuperseded(owner, key) {
+  const cache = getFarmClientDataCache();
+  const resolved = cache.resolveKey(key);
+  for (const superseded of owner.supersededKeys ?? []) {
+    if (cache.resolveKey(superseded) === resolved) return true;
+  }
+  return false;
+}
+__name(isServerQueryOwnerSuperseded, "isServerQueryOwnerSuperseded");
+function claimServerQueryKey(owner, key) {
+  if (isServerQueryOwnerSuperseded(owner, key)) return false;
+  const resolved = getFarmClientDataCache().resolveKey(key);
+  for (const older of serverQueryClientState.owners) {
+    if (older === owner) break;
+    older.supersededKeys.add(resolved);
+  }
+  return true;
+}
+__name(claimServerQueryKey, "claimServerQueryKey");
 var RAW_SERVER_QUERY_SYMBOL = /* @__PURE__ */ Symbol.for("farm.server-query");
 function assertNotRawServerQueryInBrowser(query) {
   if (typeof window === "undefined" || typeof document === "undefined") return;
@@ -4597,6 +4940,10 @@ function assertNotRawServerQueryInBrowser(query) {
   );
 }
 __name(assertNotRawServerQueryInBrowser, "assertNotRawServerQueryInBrowser");
+function isCurrentServerQueryOwner(provisionalKey, owner) {
+  return serverQueryClientState.latestOwners.get(provisionalKey) === owner && !isServerQueryOwnerSuperseded(owner, provisionalKey);
+}
+__name(isCurrentServerQueryOwner, "isCurrentServerQueryOwner");
 function createServerQueryCallKey(query, input) {
   let id = serverQueryClientState.functionIds.get(query);
   if (!id) {
@@ -4612,12 +4959,14 @@ async function fetchServerQuery(query, input, options = {}) {
   const entry = cache.get(provisionalKey);
   const stale = cache.isStale(provisionalKey);
   const inflight = cache.getInflight(provisionalKey);
-  if (inflight && !options.force) return inflight;
-  if (!options.force && entry && !stale && entry.status !== "error") return entry.data;
-  if (!options.force && entry && stale && entry.status !== "pending" && entry.status !== "error" && (options.swr ?? true)) {
-    void executeServerQuery(query, input, provisionalKey, options).catch(() => void 0);
+  if (!options.force && entry && stale && (entry.status !== "pending" || entry.updatedAt !== 0) && entry.status !== "error" && (options.swr ?? true)) {
+    if (!inflight) {
+      void executeServerQuery(query, input, provisionalKey, options).catch(() => void 0);
+    }
     return entry.data;
   }
+  if (inflight && !options.force) return inflight;
+  if (!options.force && entry && !stale && entry.status !== "error") return entry.data;
   return executeServerQuery(query, input, provisionalKey, options);
 }
 __name(fetchServerQuery, "fetchServerQuery");
@@ -4630,8 +4979,13 @@ async function executeServerQuery(query, input, provisionalKey, options) {
   const cache = getFarmClientDataCache();
   const inflight = cache.getInflight(provisionalKey);
   if (inflight && !options.force) return inflight;
-  const owner = { invalidations: trackFarmClientCacheInvalidations(cache) };
+  const owner = {
+    invalidations: trackFarmClientCacheInvalidations(cache),
+    supersededKeys: /* @__PURE__ */ new Set()
+  };
   serverQueryClientState.latestOwners.set(provisionalKey, owner);
+  serverQueryClientState.owners.add(owner);
+  claimServerQueryKey(owner, provisionalKey);
   const previous = cache.get(provisionalKey);
   cache.set(provisionalKey, {
     data: previous?.data,
@@ -4656,7 +5010,7 @@ async function executeServerQuery(query, input, provisionalKey, options) {
       }
       const data = await pending;
       const transported = cache.get(provisionalKey);
-      if (serverQueryClientState.latestOwners.get(provisionalKey) === owner && (!transported || transported.fetching)) {
+      if (isCurrentServerQueryOwner(provisionalKey, owner) && (!transported || transported.fetching)) {
         const updatedAt = Date.now();
         cache.set(provisionalKey, {
           data,
@@ -4670,7 +5024,7 @@ async function executeServerQuery(query, input, provisionalKey, options) {
       return data;
     } catch (cause) {
       const error = normalizeServerQueryError(cause);
-      if (serverQueryClientState.latestOwners.get(provisionalKey) === owner) {
+      if (isCurrentServerQueryOwner(provisionalKey, owner)) {
         const current = cache.get(provisionalKey);
         cache.set(provisionalKey, {
           data: current?.data,
@@ -4685,8 +5039,10 @@ async function executeServerQuery(query, input, provisionalKey, options) {
       }
       throw error;
     } finally {
-      const invalidated = serverQueryClientState.latestOwners.get(provisionalKey) === owner && owner.invalidations.has(provisionalKey);
+      const invalidated = isCurrentServerQueryOwner(provisionalKey, owner) && owner.invalidations.has(provisionalKey);
       owner.invalidations.dispose();
+      serverQueryClientState.owners.delete(owner);
+      owner.supersededKeys.clear();
       if (cache.getInflight(provisionalKey) === promise) {
         cache.deleteInflight(provisionalKey);
       }
@@ -4752,18 +5108,16 @@ function useServerQuery(query, input, options = {}) {
     }
   }, [cache, entry, key, options.enabled, run]);
   (0, import_react4.useEffect)(() => {
-    if (options.enabled === false || typeof window === "undefined") return;
-    const refreshIfStale = /* @__PURE__ */ __name(() => {
-      if (cache.isStale(key)) void run().catch(() => void 0);
-    }, "refreshIfStale");
-    const onFocus = options.refetchOnWindowFocus === false ? void 0 : refreshIfStale;
-    const onOnline = options.refetchOnReconnect === false ? void 0 : refreshIfStale;
-    if (onFocus) window.addEventListener("focus", onFocus);
-    if (onOnline) window.addEventListener("online", onOnline);
-    return () => {
-      if (onFocus) window.removeEventListener("focus", onFocus);
-      if (onOnline) window.removeEventListener("online", onOnline);
-    };
+    if (options.enabled === false) return;
+    return attachRevalidationListeners(
+      () => {
+        if (cache.isStale(key)) void run().catch(() => void 0);
+      },
+      {
+        refetchOnWindowFocus: options.refetchOnWindowFocus,
+        refetchOnReconnect: options.refetchOnReconnect
+      }
+    );
   }, [cache, key, options.enabled, options.refetchOnReconnect, options.refetchOnWindowFocus, run]);
   const status = entry?.status ?? (entry ? "success" : "idle");
   const fetching = entry?.fetching ?? false;
@@ -4779,6 +5133,296 @@ function useServerQuery(query, input, options = {}) {
 }
 __name(useServerQuery, "useServerQuery");
 
+// src/cache-invalidation-broadcast.ts
+var FARM_CACHE_INVALIDATION_CHANNEL = "farm:cache-invalidation";
+var activeBridge;
+function enableCrossTabCacheInvalidation(options = {}) {
+  if (typeof BroadcastChannel !== "function") return () => {
+  };
+  const channelName = options.channelName ?? FARM_CACHE_INVALIDATION_CHANNEL;
+  if (activeBridge) {
+    if (activeBridge.channelName !== channelName) {
+      throw new Error(
+        `Cross-tab cache invalidation is already enabled on channel "${activeBridge.channelName}".`
+      );
+    }
+    activeBridge.refCount += 1;
+  } else {
+    activeBridge = createBridge(channelName);
+  }
+  let disposed = false;
+  return () => {
+    if (disposed || !activeBridge) return;
+    disposed = true;
+    activeBridge.refCount -= 1;
+    if (activeBridge.refCount === 0) {
+      activeBridge.teardown();
+      activeBridge = void 0;
+    }
+  };
+}
+__name(enableCrossTabCacheInvalidation, "enableCrossTabCacheInvalidation");
+function createBridge(channelName) {
+  const channel = new BroadcastChannel(channelName);
+  let applyingRemote = false;
+  let pending = [];
+  let flushScheduled = false;
+  let closed = false;
+  const flush = /* @__PURE__ */ __name(() => {
+    flushScheduled = false;
+    if (closed || pending.length === 0) return;
+    const encoded = encodeFarmCacheInvalidations(pending);
+    pending = [];
+    if (encoded !== null) channel.postMessage(encoded);
+  }, "flush");
+  const unsubscribe = subscribeFarmCacheInvalidation((key) => {
+    if (applyingRemote || closed) return;
+    pending.push(key);
+    if (!flushScheduled) {
+      flushScheduled = true;
+      queueMicrotask(flush);
+    }
+  });
+  channel.onmessage = (event) => {
+    const keys = decodeFarmCacheInvalidations(
+      typeof event.data === "string" ? event.data : void 0
+    );
+    if (keys.length === 0) return;
+    applyingRemote = true;
+    try {
+      for (const key of keys) notifyFarmCacheInvalidation(key);
+    } finally {
+      applyingRemote = false;
+    }
+  };
+  return {
+    channelName,
+    refCount: 1,
+    teardown() {
+      closed = true;
+      pending = [];
+      unsubscribe();
+      channel.onmessage = null;
+      channel.close();
+    }
+  };
+}
+__name(createBridge, "createBridge");
+
+// src/client-cache-persistence.ts
+var FARM_CLIENT_CACHE_PERSIST_VERSION = "1";
+function defineClientCacheAdapter(adapter) {
+  for (const method of ["keys", "get", "set", "delete", "clear"]) {
+    if (typeof adapter?.[method] !== "function") {
+      throw new TypeError(
+        `defineClientCacheAdapter expects a "${method}" method. Implement keys/get/set/delete/clear over your storage.`
+      );
+    }
+  }
+  return adapter;
+}
+__name(defineClientCacheAdapter, "defineClientCacheAdapter");
+function storageClientCacheAdapter(storage, options = {}) {
+  if (!storage || typeof storage.getItem !== "function" || typeof storage.setItem !== "function" || typeof storage.removeItem !== "function") {
+    throw new TypeError("storageClientCacheAdapter expects a compatible key-value client.");
+  }
+  const base = options.base ?? "farm-client-cache";
+  const entryKey = /* @__PURE__ */ __name((key) => `${base}:${key}`, "entryKey");
+  const enumerate = storage.getKeys?.bind(storage) ?? storage.keys?.bind(storage);
+  return {
+    async keys() {
+      if (!enumerate) return [];
+      const keys = await enumerate(base);
+      const prefix = `${base}:`;
+      return keys.filter((key) => key.startsWith(prefix)).map((key) => key.slice(prefix.length));
+    },
+    async get(key) {
+      return await storage.getItem(entryKey(key)) ?? null;
+    },
+    async set(key, entry) {
+      await storage.setItem(entryKey(key), entry);
+    },
+    async delete(key) {
+      await storage.removeItem(entryKey(key));
+    },
+    async clear() {
+      if (storage.clear) {
+        await storage.clear(base);
+        return;
+      }
+      if (!enumerate) return;
+      const prefix = `${base}:`;
+      for (const key of await enumerate(base)) {
+        if (key.startsWith(prefix)) await storage.removeItem(key);
+      }
+    }
+  };
+}
+__name(storageClientCacheAdapter, "storageClientCacheAdapter");
+var activeEngine;
+function reportPersistenceFailure(error) {
+  const report = typeof reportError === "function" ? reportError : console.error;
+  if (error instanceof Error) {
+    report(error);
+    return;
+  }
+  const normalized = new Error("Client cache persistence failed");
+  normalized.cause = error;
+  report(normalized);
+}
+__name(reportPersistenceFailure, "reportPersistenceFailure");
+function disableEngine(engine, error) {
+  if (engine.disabled) return;
+  engine.disabled = true;
+  engine.pendingSets.clear();
+  engine.pendingDeletes.clear();
+  if (engine.flushTimer !== void 0) {
+    clearTimeout(engine.flushTimer);
+    engine.flushTimer = void 0;
+  }
+  reportPersistenceFailure(error);
+}
+__name(disableEngine, "disableEngine");
+function scheduleFlush(engine) {
+  if (engine.disabled || engine.flushTimer !== void 0) return;
+  const timer = setTimeout(() => {
+    engine.flushTimer = void 0;
+    void flushEngine(engine);
+  }, engine.flushDelayMs);
+  timer.unref?.();
+  engine.flushTimer = timer;
+}
+__name(scheduleFlush, "scheduleFlush");
+async function flushEngine(engine) {
+  if (engine.disabled) return;
+  const sets = Array.from(engine.pendingSets.entries());
+  const deletes = Array.from(engine.pendingDeletes);
+  engine.pendingSets.clear();
+  engine.pendingDeletes.clear();
+  try {
+    if (sets.length > 0) {
+      if (engine.adapter.setMany) await engine.adapter.setMany(sets);
+      else for (const [key, entry] of sets) await engine.adapter.set(key, entry);
+    }
+    for (const key of deletes) await engine.adapter.delete(key);
+  } catch (error) {
+    disableEngine(engine, error);
+  }
+}
+__name(flushEngine, "flushEngine");
+async function hydrateEngine(engine) {
+  const now2 = Date.now();
+  const keys = await engine.adapter.keys();
+  if (keys.length === 0) return;
+  const persisted = engine.adapter.getMany ? await engine.adapter.getMany(keys) : await Promise.all(keys.map((key) => engine.adapter.get(key)));
+  engine.hydrating = true;
+  try {
+    for (let index = 0; index < keys.length; index += 1) {
+      const key = keys[index];
+      const entry = persisted[index];
+      if (engine.disabled) return;
+      if (!entry || entry.version !== engine.version || entry.gcAt !== void 0 && now2 >= entry.gcAt) {
+        engine.pendingDeletes.add(key);
+        continue;
+      }
+      if (engine.cache.get(key, now2)) continue;
+      engine.cache.set(key, {
+        data: entry.data,
+        updatedAt: entry.updatedAt,
+        staleAt: 0,
+        gcAt: entry.gcAt,
+        status: "success",
+        error: null,
+        persist: true
+      });
+    }
+  } finally {
+    engine.hydrating = false;
+  }
+  if (engine.pendingDeletes.size > 0) scheduleFlush(engine);
+}
+__name(hydrateEngine, "hydrateEngine");
+function createSink(engine) {
+  return {
+    onSet(key, entry) {
+      if (engine.disabled || engine.hydrating) return;
+      if (!entry.persist || entry.fetching || entry.error || entry.status === "pending") return;
+      if (engine.persistKey && !engine.persistKey(key)) return;
+      engine.pendingDeletes.delete(key);
+      engine.pendingSets.set(key, {
+        data: entry.data,
+        updatedAt: entry.updatedAt,
+        staleAt: entry.staleAt,
+        gcAt: entry.gcAt,
+        version: engine.version
+      });
+      scheduleFlush(engine);
+    },
+    onDelete(key) {
+      if (engine.disabled) return;
+      engine.pendingSets.delete(key);
+      engine.pendingDeletes.add(key);
+      scheduleFlush(engine);
+    },
+    onClear() {
+      if (engine.disabled) return;
+      engine.pendingSets.clear();
+      engine.pendingDeletes.clear();
+      void engine.adapter.clear().catch((error) => disableEngine(engine, error));
+    }
+  };
+}
+__name(createSink, "createSink");
+function initPersistedClientCache(adapter, options = {}) {
+  defineClientCacheAdapter(adapter);
+  disposePersistedClientCache();
+  const engine = {
+    adapter,
+    cache: getFarmClientDataCache(),
+    version: options.version ? `${FARM_CLIENT_CACHE_PERSIST_VERSION}:${options.version}` : FARM_CLIENT_CACHE_PERSIST_VERSION,
+    persistKey: options.persistKey,
+    flushDelayMs: options.flushDelayMs ?? 300,
+    pendingSets: /* @__PURE__ */ new Map(),
+    pendingDeletes: /* @__PURE__ */ new Set(),
+    flushTimer: void 0,
+    hydrating: false,
+    disabled: false
+  };
+  activeEngine = engine;
+  engine.cache.attachPersistence(createSink(engine));
+  void hydrateEngine(engine).catch((error) => disableEngine(engine, error));
+  return () => {
+    if (activeEngine !== engine) return;
+    disposePersistedClientCache();
+  };
+}
+__name(initPersistedClientCache, "initPersistedClientCache");
+function disposePersistedClientCache() {
+  const engine = activeEngine;
+  if (!engine) return;
+  activeEngine = void 0;
+  engine.cache.attachPersistence(void 0);
+  if (engine.flushTimer !== void 0) {
+    clearTimeout(engine.flushTimer);
+    engine.flushTimer = void 0;
+  }
+  engine.pendingSets.clear();
+  engine.pendingDeletes.clear();
+}
+__name(disposePersistedClientCache, "disposePersistedClientCache");
+async function clearPersistedCache() {
+  const engine = activeEngine;
+  if (!engine) return;
+  engine.pendingSets.clear();
+  engine.pendingDeletes.clear();
+  try {
+    await engine.adapter.clear();
+  } catch (error) {
+    disableEngine(engine, error);
+  }
+}
+__name(clearPersistedCache, "clearPersistedCache");
+
 // src/integration-api.ts
 function defineIntegrationAPIOperation(operation2) {
   return {
@@ -6860,7 +7504,9 @@ var _SPARouter = class _SPARouter {
       if (this.onNavigate) {
         await this.onNavigate(pageData);
       }
-      if (this.options.scrollRestoration) {
+      if (window.location.hash) {
+        getHashTargetElement(window.location.hash)?.scrollIntoView();
+      } else if (this.options.scrollRestoration) {
         this.restoreScrollPosition(window.location.pathname + window.location.search);
       }
       if (clientNavigation) {
@@ -7949,7 +8595,7 @@ body {
 `;
 
 // package.json
-var version = "0.1.0-beta.96";
+var version = "0.1.0-beta.97";
 
 // src/version.ts
 var FARM_VERSION = version;
@@ -9250,12 +9896,15 @@ __name(isObject, "isObject");
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   APIClientError,
+  FARM_CACHE_INVALIDATION_CHANNEL,
+  FARM_CLIENT_CACHE_PERSIST_VERSION,
   FarmClientPluginManager,
   FetcherInputError,
   IntegrationClientError,
   Link,
   SPARouter,
   api,
+  clearPersistedCache,
   createAPIClient,
   createApiClients,
   createClientPluginManager,
@@ -9266,13 +9915,16 @@ __name(isObject, "isObject");
   createIntegrations,
   createServerAPIClient,
   createStore,
+  defineClientCacheAdapter,
   defineIntegrationAPI,
   defineIntegrationAPIOperation,
+  enableCrossTabCacheInvalidation,
   endpoint,
   fetchServerQuery,
   getIntegrationAPIManifest,
   getRouter,
   getTheme,
+  initPersistedClientCache,
   installChunkErrorRecovery,
   integrationClients,
   integrationsClient,
@@ -9285,6 +9937,7 @@ __name(isObject, "isObject");
   readPageState,
   replaceState,
   setTheme,
+  storageClientCacheAdapter,
   toggleTheme,
   useAction,
   useBlocker,