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

package/dist/client.cjs

@@ -32,11 +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,
@@ -47,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,
@@ -66,6 +73,7 @@ __export(client_exports, {
   readPageState: () => readPageState,
   replaceState: () => replaceState,
   setTheme: () => setTheme,
+  storageClientCacheAdapter: () => storageClientCacheAdapter,
   toggleTheme: () => toggleTheme,
   useAction: () => useAction,
   useBlocker: () => useBlocker,
@@ -223,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 {
       }
@@ -727,7 +735,8 @@ async function executeServerOperation(operation2, input, options, requestOptions
         serverRequestOptions?.baseURL ?? options.baseURL,
         request
       );
-      const url = new URL(operation2.path, baseURL);
+      const origin = resolveServerBaseURL(void 0, request);
+      const url = new URL(operation2.path, new URL(baseURL, origin));
       appendQuery(url, input.query);
       const headers = new Headers();
       appendHeaders(
@@ -780,7 +789,9 @@ async function executeServerOperation(operation2, input, options, requestOptions
       }
       appendIntegrationClientDataHeader(headers, data);
       const body = createOperationBody(operation2, input.body, headers);
-      const response = await (options.fetch ?? fetch)(url.toString(), {
+      const httpURL = resolveFarmAPIRequestURL(operation2.path, baseURL, origin);
+      appendQuery(httpURL, input.query);
+      const response = await (options.fetch ?? fetch)(httpURL.toString(), {
         method: operation2.method,
         headers,
         body,
@@ -1214,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;
@@ -1311,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)) {
@@ -1336,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");
@@ -1498,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");
@@ -1514,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 {
@@ -2193,6 +2246,31 @@ function stableSerialize(value, seen = /* @__PURE__ */ new WeakSet()) {
 __name(stableSerialize, "stableSerialize");
 
 // src/client-cache.ts
+var invalidationTrackers = /* @__PURE__ */ new WeakMap();
+function trackFarmClientCacheInvalidations(cache) {
+  let trackers = invalidationTrackers.get(cache);
+  if (!trackers) {
+    trackers = /* @__PURE__ */ new Set();
+    invalidationTrackers.set(cache, trackers);
+  }
+  const keys = /* @__PURE__ */ new Set();
+  trackers.add(keys);
+  return {
+    has(key) {
+      const resolved = cache.resolveKey(key);
+      for (const invalidated of keys) {
+        if (cache.resolveKey(invalidated) === resolved) return true;
+      }
+      return false;
+    },
+    dispose() {
+      if (!trackers.delete(keys)) return;
+      keys.clear();
+      if (trackers.size === 0) invalidationTrackers.delete(cache);
+    }
+  };
+}
+__name(trackFarmClientCacheInvalidations, "trackFarmClientCacheInvalidations");
 var cacheFinalizer = typeof FinalizationRegistry === "function" ? new FinalizationRegistry((unsubscribe) => unsubscribe()) : void 0;
 function subscribeWeakCache(reference) {
   const unsubscribe = subscribeFarmCacheInvalidation((key) => {
@@ -2208,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();
@@ -2215,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);
@@ -2231,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();
@@ -2246,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;
     }
@@ -2259,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;
   }
@@ -2266,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;
   }
@@ -2275,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()) {
@@ -2288,6 +2381,7 @@ var _FarmClientDataCache = class _FarmClientDataCache {
   }
   invalidate(key, now2 = Date.now()) {
     const resolved = this.resolveKey(key);
+    for (const keys of invalidationTrackers.get(this) ?? []) keys.add(resolved);
     this.invalidatedAt.set(resolved, now2);
     const entry = this.entries.get(resolved);
     if (entry) {
@@ -2307,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),
@@ -2348,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) {
@@ -2360,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) {
@@ -2764,6 +2885,7 @@ function readJSONStream(response) {
   const decoder = new TextDecoder();
   let buffer = "";
   let completed = false;
+  let cancelled = false;
   let claimed = false;
   let released = false;
   const releaseReader = /* @__PURE__ */ __name(() => {
@@ -2783,39 +2905,54 @@ function readJSONStream(response) {
       throw error;
     }
   }, "parseLine");
-  const iterator = {
-    async next() {
-      while (true) {
-        const lineEnd = buffer.indexOf("\n");
-        if (lineEnd >= 0) {
-          const line = buffer.slice(0, lineEnd).trim();
-          buffer = buffer.slice(lineEnd + 1);
-          if (!line) continue;
-          return { done: false, value: await parseLine(line) };
-        }
-        if (completed) {
-          const line = buffer.trim();
-          buffer = "";
-          if (!line) {
-            releaseReader();
-            return { done: true, value: void 0 };
-          }
-          return { done: false, value: await parseLine(line) };
-        }
-        let chunk;
-        try {
-          chunk = await reader.read();
-        } catch (error) {
-          completed = true;
-          buffer = "";
+  const readNext = /* @__PURE__ */ __name(async () => {
+    while (true) {
+      if (cancelled) return { done: true, value: void 0 };
+      const lineEnd = buffer.indexOf("\n");
+      if (lineEnd >= 0) {
+        const line = buffer.slice(0, lineEnd).trim();
+        buffer = buffer.slice(lineEnd + 1);
+        if (!line) continue;
+        return { done: false, value: await parseLine(line) };
+      }
+      if (completed) {
+        const line = buffer.trim();
+        buffer = "";
+        if (!line) {
           releaseReader();
-          throw error;
+          return { done: true, value: void 0 };
         }
-        completed = chunk.done;
-        buffer += decoder.decode(chunk.value, { stream: !chunk.done });
+        return { done: false, value: await parseLine(line) };
       }
+      let chunk;
+      try {
+        chunk = await reader.read();
+      } catch (error) {
+        if (cancelled) return { done: true, value: void 0 };
+        completed = true;
+        buffer = "";
+        releaseReader();
+        throw error;
+      }
+      if (cancelled) return { done: true, value: void 0 };
+      completed = chunk.done;
+      buffer += decoder.decode(chunk.value, { stream: !chunk.done });
+    }
+  }, "readNext");
+  let readQueue = Promise.resolve();
+  const iterator = {
+    next() {
+      const result = readQueue.then(readNext);
+      readQueue = result.then(
+        () => {
+        },
+        () => {
+        }
+      );
+      return result;
     },
     async return() {
+      cancelled = true;
       completed = true;
       buffer = "";
       if (!released) {
@@ -2831,6 +2968,7 @@ function readJSONStream(response) {
   return {
     response,
     async cancel(reason) {
+      cancelled = true;
       completed = true;
       buffer = "";
       if (!released) {
@@ -2980,69 +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
-    };
-  }, "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();
@@ -3275,6 +3350,9 @@ function createAPIClientRuntime(options = {}, transport) {
       const executeNetwork = /* @__PURE__ */ __name(async (opts) => {
         const release = cancellation.hold();
         let unsubscribeInvalidation;
+        let readOwners;
+        let readOwner;
+        const resolvedCacheKey = cacheState.resolveKey(cacheKey);
         try {
           const dedupeMs = cacheOptions?.dedupeMs ?? 0;
           const inflight = inflightState.get(cacheKey);
@@ -3298,6 +3376,9 @@ function createAPIClientRuntime(options = {}, transport) {
           }
           let invalidatedDuringRequest = false;
           if (isCacheEnabled) {
+            readOwners = getCacheReadOwners(cacheState);
+            readOwner = {};
+            readOwners.set(resolvedCacheKey, readOwner);
             unsubscribeInvalidation = cacheState.subscribe(cacheKey, (event) => {
               if (event === "invalidate") invalidatedDuringRequest = true;
             });
@@ -3405,15 +3486,27 @@ function createAPIClientRuntime(options = {}, transport) {
           inflightState.set(cacheKey, inflightEntry);
           try {
             const result2 = await promise;
-            if (inflightState.get(cacheKey) === inflightEntry && !invalidatedDuringRequest && !result2.error && isCacheEnabled && !isFarmAPIStream(result2.data)) {
+            if (inflightState.get(cacheKey) === inflightEntry && readOwners?.get(resolvedCacheKey) === readOwner && !invalidatedDuringRequest && !result2.error && isCacheEnabled && !isFarmAPIStream(result2.data)) {
               const updatedAt = Date.now();
-              cacheState.set(cacheKey, {
+              const cached = {
                 data: result2.data,
                 updatedAt,
                 staleAt: updatedAt + staleTime,
                 gcAt: getGcAt(updatedAt, cacheOptions?.gcTime),
-                invalidatedAt: void 0
-              });
+                invalidatedAt: void 0,
+                persist: cacheOptions?.persist === true ? true : void 0,
+                [API_CACHE_REFETCH]: createCacheRefetch(
+                  request,
+                  path,
+                  method,
+                  input,
+                  cacheKey,
+                  cacheOptions,
+                  clientOptions,
+                  options.onError
+                )
+              };
+              cacheState.set(cacheKey, cached);
             }
             if (result2.error) {
               emitStatus("error", { error: result2.error, isBackground: opts?.isBackground });
@@ -3441,6 +3534,9 @@ function createAPIClientRuntime(options = {}, transport) {
             }
           }
         } finally {
+          if (readOwner && readOwners?.get(resolvedCacheKey) === readOwner) {
+            readOwners.delete(resolvedCacheKey);
+          }
           unsubscribeInvalidation?.();
           release();
         }
@@ -3451,6 +3547,7 @@ function createAPIClientRuntime(options = {}, transport) {
           targets: clientOptions.invalidate.targets,
           refetch: clientOptions.invalidate.refetch ?? false
         };
+        const refetches = /* @__PURE__ */ new Set();
         for (const target of invalidateOptions.targets) {
           const targetKey = resolveTargetKey(
             routeMeta,
@@ -3462,20 +3559,22 @@ function createAPIClientRuntime(options = {}, transport) {
           );
           if (!targetKey) continue;
           const existing = cacheState.get(targetKey);
+          const invalidatedAt = Date.now();
+          cacheState.invalidate(targetKey, invalidatedAt);
           if (existing) {
-            const invalidatedAt = Date.now();
             const stack = optimisticState.get(targetKey);
-            cacheState.invalidate(targetKey, invalidatedAt);
             if (stack?.renderedEntry === existing) {
               stack.invalidatedAt = invalidatedAt;
               stack.renderedEntry = cacheState.get(targetKey);
             }
           }
           emitStatus("invalidated", { key: targetKey });
-          if (invalidateOptions.refetch && existing && targetKey === cacheKey) {
-            void executeNetwork({ isBackground: true, callCallbacks: false });
+          const refetch = existing?.[API_CACHE_REFETCH];
+          if (invalidateOptions.refetch && refetch) {
+            refetches.add(refetch);
           }
         }
+        for (const refetch of refetches) refetch();
       }, "invalidateTargets");
       const optimisticSnapshots = requestContextError ? [] : applyOptimisticUpdates();
       if (isCacheEnabled && !requestContextError && !cancellation.signal?.aborted) {
@@ -3709,7 +3808,31 @@ function createServerAPIClient(endpoints, options = {}) {
   return endpoints;
 }
 __name(createServerAPIClient, "createServerAPIClient");
+var API_CACHE_REFETCH = /* @__PURE__ */ Symbol.for("farm.api.cache-refetch");
+function createCacheRefetch(request, path, method, input, key, cache, options, onError) {
+  const readOptions = {
+    cache: { ...cache, key, policy: "network-only", dedupeMs: 0 },
+    retry: options?.retry,
+    timeoutMs: options?.timeoutMs
+  };
+  return () => {
+    void request(path, method, input, readOptions).catch((error) => {
+      notifyClientObserver(onError, [normalizeError(error)]);
+    });
+  };
+}
+__name(createCacheRefetch, "createCacheRefetch");
 var optimisticStates = /* @__PURE__ */ new WeakMap();
+var cacheReadOwners = /* @__PURE__ */ new WeakMap();
+function getCacheReadOwners(cache) {
+  let owners = cacheReadOwners.get(cache);
+  if (!owners) {
+    owners = /* @__PURE__ */ new Map();
+    cacheReadOwners.set(cache, owners);
+  }
+  return owners;
+}
+__name(getCacheReadOwners, "getCacheReadOwners");
 function getOptimisticState(cache) {
   let state = optimisticStates.get(cache);
   if (!state) {
@@ -3719,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,
@@ -3897,65 +4165,176 @@ __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;
+}
+__name(useMutation, "useMutation");
+function useMutationLifecycle(target, options = {}) {
   const initialData = options.initialData ?? null;
   const optionsRef = (0, import_react.useRef)(options);
   const targetRef = (0, import_react.useRef)(target);
   const requestIdRef = (0, import_react.useRef)(0);
+  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;
   const setMutationState = (0, import_react.useCallback)(
     (value) => {
-      setState((current) => {
-        const next = typeof value === "function" ? value(current) : value;
-        stateRef.current = next;
-        return next;
-      });
+      const next = typeof value === "function" ? value(stateRef.current) : value;
+      stateRef.current = next;
+      setState(next);
     },
     []
   );
-  const mutateAsync = (0, import_react.useCallback)(
-    async (variables) => {
+  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;
       const currentOptions = optionsRef.current;
       const previousData = stateRef.current.data;
-      const optimisticData = currentOptions.optimistic?.({
-        variables,
-        current: previousData
-      });
+      let variables;
+      let preparationFailed = false;
+      let preparationError;
+      try {
+        variables = prepare();
+      } catch (error) {
+        preparationFailed = true;
+        preparationError = error;
+      }
+      const optimisticData = preparationFailed ? void 0 : currentOptions.optimistic?.({ variables, current: previousData });
       const hasOptimisticData = optimisticData !== void 0;
-      setMutationState((current) => ({
-        pendingCount: current.pendingCount + 1,
-        status: "pending",
-        data: hasOptimisticData ? optimisticData : currentOptions.resetOnMutate === false ? current.data : null,
-        error: null,
-        variables
-      }));
+      setMutationState((current) => {
+        if (requestId < lastResetIdRef.current) return current;
+        const pendingCount = current.pendingCount + 1;
+        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 {
-        const mutationTarget = targetRef.current;
-        const rawResult = isAPIRouteRef(mutationTarget) ? await mutationTarget(variables, currentOptions.request) : await mutationTarget(variables);
-        const data = unwrapMutationResult(rawResult, isAPIRouteRef(mutationTarget));
+        if (preparationFailed) throw preparationError;
+        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;
           const pendingCount = Math.max(0, current.pendingCount - 1);
           if (!isLatestRequest) {
             return {
               ...current,
-              pendingCount,
-              status: pendingCount > 0 ? "pending" : current.status
+              pendingCount
             };
           }
           return {
             pendingCount,
+            pausedCount: current.pausedCount,
             status: "success",
             data,
             error: null,
@@ -3963,24 +4342,35 @@ function useMutation(target, options = {}) {
           };
         });
         if (isLatestRequest) {
-          currentOptions.onSuccess?.(data, variables);
-          currentOptions.onSettled?.(data, null, variables);
+          notifyClientObserver(currentOptions.onSuccess, [data, variables], "Mutation onSuccess");
+          if (requestId === requestIdRef.current) {
+            notifyClientObserver(
+              currentOptions.onSettled,
+              [data, null, variables],
+              "Mutation onSettled"
+            );
+          }
         }
         return data;
       } catch (cause) {
+        settleServerFnOptimisticUpdates(
+          sharedSnapshots,
+          sharedOptimistic?.rollbackOnError ? "rollback" : "invalidate"
+        );
         const error = normalizeMutationError(cause);
         const isLatestRequest = requestId === requestIdRef.current;
         setMutationState((current) => {
+          if (requestId < lastResetIdRef.current) return current;
           const pendingCount = Math.max(0, current.pendingCount - 1);
           if (!isLatestRequest) {
             return {
               ...current,
-              pendingCount,
-              status: pendingCount > 0 ? "pending" : current.status
+              pendingCount
             };
           }
           return {
             pendingCount,
+            pausedCount: current.pausedCount,
             status: "error",
             data: hasOptimisticData && currentOptions.rollbackOnError ? previousData : currentOptions.resetOnMutate === false ? current.data : null,
             error,
@@ -3988,13 +4378,23 @@ function useMutation(target, options = {}) {
           };
         });
         if (isLatestRequest) {
-          currentOptions.onError?.(error, variables);
-          currentOptions.onSettled?.(null, error, variables);
+          notifyClientObserver(currentOptions.onError, [error, variables], "Mutation onError");
+          if (requestId === requestIdRef.current) {
+            notifyClientObserver(
+              currentOptions.onSettled,
+              [null, error, variables],
+              "Mutation onSettled"
+            );
+          }
         }
         throw error;
       }
     },
-    [setMutationState]
+    [setMutationState, waitForReconnect]
+  );
+  const mutateAsync = (0, import_react.useCallback)(
+    (variables) => mutatePreparedAsync(() => variables),
+    [mutatePreparedAsync]
   );
   const mutate = (0, import_react.useCallback)(
     (variables) => {
@@ -4004,18 +4404,23 @@ function useMutation(target, options = {}) {
     [mutateAsync]
   );
   const reset = (0, import_react.useCallback)(() => {
-    requestIdRef.current += 1;
+    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]);
-  return (0, import_react.useMemo)(
+  const mutation = (0, import_react.useMemo)(
     () => ({
       pending: state.pendingCount > 0,
+      paused: state.pausedCount > 0,
       status: state.status,
       data: state.data,
       error: state.error,
@@ -4030,13 +4435,15 @@ function useMutation(target, options = {}) {
       reset,
       state.data,
       state.error,
+      state.pausedCount,
       state.pendingCount,
       state.status,
       state.variables
     ]
   );
+  return { mutation, mutatePreparedAsync };
 }
-__name(useMutation, "useMutation");
+__name(useMutationLifecycle, "useMutationLifecycle");
 function unwrapMutationResult(result, apiRoute) {
   if (!apiRoute) return result;
   const apiResult = result;
@@ -4056,13 +4463,27 @@ __name(normalizeMutationError, "normalizeMutationError");
 
 // src/fetcher-client.tsx
 var import_react2 = require("react");
+var _FetcherInputError = class _FetcherInputError extends Error {
+  constructor(cause) {
+    super(
+      cause instanceof Error ? cause.message : typeof cause === "string" ? cause : "Could not prepare form input"
+    );
+    this.name = "FetcherInputError";
+    this.code = "input_error";
+    this.status = 0;
+    this.data = void 0;
+    this.cause = cause;
+  }
+};
+__name(_FetcherInputError, "FetcherInputError");
+var FetcherInputError = _FetcherInputError;
 var formDataContexts = /* @__PURE__ */ new WeakMap();
 function useFetcher(target, options = {}) {
   const targetRef = (0, import_react2.useRef)(target);
   const optionsRef = (0, import_react2.useRef)(options);
   const submissionIdRef = (0, import_react2.useRef)(0);
   const [formData, setFormData] = (0, import_react2.useState)(null);
-  const mutation = useMutation(target, options);
+  const { mutation, mutatePreparedAsync } = useMutationLifecycle(target, options);
   targetRef.current = target;
   optionsRef.current = options;
   const submitAsync = (0, import_react2.useCallback)(
@@ -4071,15 +4492,20 @@ function useFetcher(target, options = {}) {
       const submittedFormData = isFormData2(input) ? input : null;
       setFormData(submittedFormData);
       try {
-        const variables = submittedFormData ? mapFetcherFormData(targetRef.current, submittedFormData, optionsRef.current) : input;
-        return await mutation.mutateAsync(variables);
+        return await mutatePreparedAsync(() => {
+          try {
+            return submittedFormData ? mapFetcherFormData(targetRef.current, submittedFormData, optionsRef.current) : input;
+          } catch (error) {
+            throw new FetcherInputError(error);
+          }
+        });
       } finally {
         if (submissionId === submissionIdRef.current) {
           setFormData(null);
         }
       }
     },
-    [mutation.mutateAsync]
+    [mutatePreparedAsync]
   );
   const submit = (0, import_react2.useCallback)(
     (input) => {
@@ -4129,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,
@@ -4143,6 +4570,7 @@ function useFetcher(target, options = {}) {
       formData,
       mutation.data,
       mutation.error,
+      mutation.paused,
       mutation.pending,
       mutation.status,
       mutation.variables,
@@ -4161,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) {
@@ -4175,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;
@@ -4188,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);
@@ -4223,6 +4664,7 @@ function useServerFn(serverFn, options = {}) {
   const { initialResult = null, resetOnSubmit = true } = options;
   const callbacksRef = (0, import_react3.useRef)({});
   const requestIdRef = (0, import_react3.useRef)(0);
+  const lastResetIdRef = (0, import_react3.useRef)(0);
   const initialState = {
     pendingCount: 0,
     status: "idle",
@@ -4233,11 +4675,9 @@ function useServerFn(serverFn, options = {}) {
   const [state, setState] = (0, import_react3.useState)(initialState);
   const setActionState = (0, import_react3.useCallback)(
     (value) => {
-      setState((current) => {
-        const next = typeof value === "function" ? value(current) : value;
-        stateRef.current = next;
-        return next;
-      });
+      const next = typeof value === "function" ? value(stateRef.current) : value;
+      stateRef.current = next;
+      setState(next);
     },
     []
   );
@@ -4258,63 +4698,88 @@ function useServerFn(serverFn, options = {}) {
         current: previousResult
       });
       const hasOptimisticResult = optimisticResult !== void 0;
-      setActionState((current) => ({
-        pendingCount: current.pendingCount + 1,
-        status: "pending",
-        result: hasOptimisticResult ? optimisticResult : resetOnSubmit ? null : current.result,
-        error: null
-      }));
+      setActionState((current) => {
+        if (requestId < lastResetIdRef.current) return current;
+        const pendingCount = current.pendingCount + 1;
+        if (requestId !== requestIdRef.current) return { ...current, pendingCount };
+        return {
+          pendingCount,
+          status: "pending",
+          result: hasOptimisticResult ? optimisticResult : resetOnSubmit ? null : current.result,
+          error: null
+        };
+      });
       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;
           const pendingCount = Math.max(0, current.pendingCount - 1);
           if (!isLatestRequest) {
             return {
               ...current,
-              pendingCount,
-              status: pendingCount > 0 ? "pending" : current.status
+              pendingCount
             };
           }
           return {
             pendingCount,
-            status: pendingCount > 0 ? "pending" : "success",
+            status: "success",
             result,
             error: null
           };
         });
         if (isLatestRequest) {
-          callbacksRef.current.onSuccess?.(result);
-          callbacksRef.current.onSettled?.(result, null);
+          notifyClientObserver(callbacksRef.current.onSuccess, [result], "Action onSuccess");
+          if (requestId === requestIdRef.current) {
+            notifyClientObserver(
+              callbacksRef.current.onSettled,
+              [result, null],
+              "Action onSettled"
+            );
+          }
         }
         return result;
       } catch (cause) {
         const error = normalizeServerFnError(cause);
         const isLatestRequest = requestId === requestIdRef.current;
         setActionState((current) => {
+          if (requestId < lastResetIdRef.current) return current;
           const pendingCount = Math.max(0, current.pendingCount - 1);
           if (!isLatestRequest) {
             return {
               ...current,
-              pendingCount,
-              status: pendingCount > 0 ? "pending" : current.status
+              pendingCount
             };
           }
           return {
             pendingCount,
-            status: pendingCount > 0 ? "pending" : "error",
+            status: "error",
             result: hasOptimisticResult && options.rollbackOnError ? previousResult : resetOnSubmit ? null : current.result,
             error
           };
         });
         if (isLatestRequest) {
-          callbacksRef.current.onError?.(error);
-          callbacksRef.current.onSettled?.(null, error);
+          notifyClientObserver(callbacksRef.current.onError, [error], "Action onError");
+          if (requestId === requestIdRef.current) {
+            notifyClientObserver(callbacksRef.current.onSettled, [null, error], "Action onSettled");
+          }
         }
         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) => {
@@ -4329,7 +4794,7 @@ function useServerFn(serverFn, options = {}) {
     [submit]
   );
   const reset = (0, import_react3.useCallback)(() => {
-    requestIdRef.current += 1;
+    lastResetIdRef.current = ++requestIdRef.current;
     setActionState({
       pendingCount: 0,
       status: "idle",
@@ -4354,14 +4819,17 @@ __name(useServerFn, "useServerFn");
 function useAction(target, options = {}) {
   const serverFn = resolveServerFnTarget(target);
   const action = useServerFn(serverFn, options);
+  const formActionRef = (0, import_react3.useRef)(action.formAction);
+  formActionRef.current = action.formAction;
   const Form = (0, import_react3.useMemo)(() => {
+    const submitForm = /* @__PURE__ */ __name((formData) => formActionRef.current(formData), "submitForm");
     const ActionForm = /* @__PURE__ */ __name((props) => (0, import_react3.createElement)("form", {
       ...props,
-      action: action.formAction
+      action: submitForm
     }), "ActionForm");
     ActionForm.displayName = "FarmActionForm";
     return ActionForm;
-  }, [action.formAction]);
+  }, []);
   return (0, import_react3.useMemo)(() => {
     const call = /* @__PURE__ */ __name(((input) => action.submit(input)), "call");
     return Object.assign(call, {
@@ -4413,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;
@@ -4420,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;
@@ -4436,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) {
@@ -4451,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");
@@ -4469,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 = {};
+  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,
@@ -4495,12 +5010,12 @@ 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,
           updatedAt,
-          staleAt: options.staleTime === false ? Number.POSITIVE_INFINITY : updatedAt + (options.staleTime ?? 0),
+          staleAt: owner.invalidations.has(provisionalKey) ? 0 : options.staleTime === false ? Number.POSITIVE_INFINITY : updatedAt + (options.staleTime ?? 0),
           status: "success",
           error: null,
           fetching: false
@@ -4509,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,
@@ -4524,12 +5039,17 @@ async function executeServerQuery(query, input, provisionalKey, options) {
       }
       throw error;
     } finally {
+      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);
       }
       if (serverQueryClientState.latestOwners.get(provisionalKey) === owner) {
         serverQueryClientState.latestOwners.delete(provisionalKey);
       }
+      if (invalidated) cache.invalidate(provisionalKey);
     }
   })();
   cache.setInflight(provisionalKey, promise);
@@ -4551,19 +5071,29 @@ function useServerQuery(query, input, options = {}) {
   const inputRef = (0, import_react4.useRef)(input);
   const optionsRef = (0, import_react4.useRef)(options);
   const mountedKeyRef = (0, import_react4.useRef)(void 0);
+  const pendingInvalidationRef = (0, import_react4.useRef)(false);
   inputRef.current = input;
   optionsRef.current = options;
   const subscribe = (0, import_react4.useCallback)(
-    (listener) => cache.subscribe(key, listener),
+    (listener) => cache.subscribe(key, (event) => {
+      if (event === "invalidate") pendingInvalidationRef.current = true;
+      else if (cache.get(key)?.fetching) {
+        pendingInvalidationRef.current = false;
+      }
+      listener();
+    }),
     [cache, key]
   );
   const getSnapshot = (0, import_react4.useCallback)(() => cache.get(key), [cache, key]);
   const entry = (0, import_react4.useSyncExternalStore)(subscribe, getSnapshot, () => void 0);
   const run = (0, import_react4.useCallback)(
-    (force = false) => fetchServerQuery(query, inputRef.current, {
-      ...optionsRef.current,
-      force
-    }),
+    (force = false) => {
+      pendingInvalidationRef.current = false;
+      return fetchServerQuery(query, inputRef.current, {
+        ...optionsRef.current,
+        force
+      });
+    },
     [query]
   );
   (0, import_react4.useEffect)(() => {
@@ -4573,23 +5103,21 @@ function useServerQuery(query, input, options = {}) {
     }
     const firstReadForKey = mountedKeyRef.current !== key;
     if (firstReadForKey) mountedKeyRef.current = key;
-    if (firstReadForKey && (!entry || cache.isStale(key)) || entry?.invalidatedAt !== void 0 && !entry.fetching) {
+    if (firstReadForKey && (!entry || cache.isStale(key)) || pendingInvalidationRef.current && entry?.invalidatedAt !== void 0 && !entry.fetching) {
       void run().catch(() => void 0);
     }
   }, [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;
@@ -4605,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 {
@@ -4847,11 +5665,14 @@ function pickState(state, keys) {
   return slice;
 }
 __name(pickState, "pickState");
+function getEnumerableKeys(state) {
+  return Reflect.ownKeys(state).filter(
+    (key) => Object.prototype.propertyIsEnumerable.call(state, key)
+  );
+}
+__name(getEnumerableKeys, "getEnumerableKeys");
 function getChangedKeys(state, previousState) {
-  const keys = /* @__PURE__ */ new Set([
-    ...Object.keys(state),
-    ...Object.keys(previousState)
-  ]);
+  const keys = /* @__PURE__ */ new Set([...getEnumerableKeys(state), ...getEnumerableKeys(previousState)]);
   return [...keys].filter((key) => !Object.is(state[key], previousState[key]));
 }
 __name(getChangedKeys, "getChangedKeys");
@@ -4872,7 +5693,11 @@ function createStore(initialState, extend) {
   let state = cloneState(initialState);
   const subscriptions = /* @__PURE__ */ new Set();
   const addSubscription = /* @__PURE__ */ __name((keys, notify) => {
-    const subscription = { keys, notify };
+    const subscription = {
+      // Object property enumeration returns numeric keys as strings.
+      keys: keys?.map((key) => typeof key === "number" ? String(key) : key) ?? null,
+      notify
+    };
     subscriptions.add(subscription);
     return () => {
       subscriptions.delete(subscription);
@@ -4964,7 +5789,7 @@ function createStore(initialState, extend) {
         getSnapshot
       );
     }
-    if (typeof keyOrKeys === "string") {
+    if (isStoreKey(keyOrKeys)) {
       return (0, import_react5.useSyncExternalStore)(
         (notify) => addSubscription([keyOrKeys], () => notify()),
         () => state[keyOrKeys],
@@ -4985,7 +5810,7 @@ function createStore(initialState, extend) {
     reset: /* @__PURE__ */ __name(() => replaceState2(cloneState(initialSnapshot)), "reset"),
     subscribe: subscribeState
   };
-  for (const key of Object.keys(initialSnapshot)) {
+  for (const key of getEnumerableKeys(initialSnapshot)) {
     if (RESERVED_STORE_KEYS.has(key)) {
       throw new Error(
         `createStore does not allow the reserved key "${String(key)}" in the initial state.`
@@ -6679,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) {
@@ -7768,7 +8595,7 @@ body {
 `;
 
 // package.json
-var version = "0.1.0-beta.95";
+var version = "0.1.0-beta.97";
 
 // src/version.ts
 var FARM_VERSION = version;
@@ -9069,11 +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,
@@ -9084,13 +9915,16 @@ __name(isObject, "isObject");
   createIntegrations,
   createServerAPIClient,
   createStore,
+  defineClientCacheAdapter,
   defineIntegrationAPI,
   defineIntegrationAPIOperation,
+  enableCrossTabCacheInvalidation,
   endpoint,
   fetchServerQuery,
   getIntegrationAPIManifest,
   getRouter,
   getTheme,
+  initPersistedClientCache,
   installChunkErrorRecovery,
   integrationClients,
   integrationsClient,
@@ -9103,6 +9937,7 @@ __name(isObject, "isObject");
   readPageState,
   replaceState,
   setTheme,
+  storageClientCacheAdapter,
   toggleTheme,
   useAction,
   useBlocker,