@farm.js/core 0.1.0-beta.3 → 0.1.0-beta.4

package/dist/client.cjs

@@ -64,6 +64,7 @@ __export(client_exports, {
   readPageState: () => readPageState,
   replaceState: () => replaceState,
   useBlocker: () => useBlocker,
+  useFetcher: () => useFetcher,
   useMutation: () => useMutation,
   useNavigation: () => useNavigation,
   usePageState: () => usePageState,
@@ -988,7 +989,8 @@ var FARM_CACHE_INVALIDATION_STATE = /* @__PURE__ */ Symbol.for("farm.cacheInvali
 var globalState = globalThis;
 function getFarmCacheInvalidationState() {
   return globalState[FARM_CACHE_INVALIDATION_STATE] ?? (globalState[FARM_CACHE_INVALIDATION_STATE] = {
-    listeners: /* @__PURE__ */ new Set()
+    listeners: /* @__PURE__ */ new Set(),
+    taskListeners: /* @__PURE__ */ new Set()
   });
 }
 __name(getFarmCacheInvalidationState, "getFarmCacheInvalidationState");
@@ -1039,11 +1041,51 @@ __name(getActiveFarmI18nSnapshot, "getActiveFarmI18nSnapshot");
 
 // src/cache.ts
 var _FarmDataCache = class _FarmDataCache {
-  constructor() {
+  constructor(config = {}) {
     this.entries = /* @__PURE__ */ new Map();
     this.inflight = /* @__PURE__ */ new Map();
     this.invalidatedTagVersions = /* @__PURE__ */ new Map();
     this.version = 0;
+    this.namespace = "farm";
+    this.local = true;
+    this.lease = {
+      enabled: true,
+      ttlMs: 1e4,
+      waitTimeoutMs: 1e4,
+      pollIntervalMs: 25
+    };
+    this.configure(config);
+  }
+  configure(config = {}) {
+    this.adapter = config.adapter;
+    this.namespace = normalizeCacheNamespace(config.namespace || "farm");
+    this.local = !config.adapter;
+    this.lease = config.lease === false ? { ...this.lease, enabled: false } : {
+      enabled: true,
+      ttlMs: normalizePositiveDuration(config.lease?.ttlMs, 1e4, "cache.lease.ttlMs"),
+      waitTimeoutMs: normalizePositiveDuration(
+        config.lease?.waitTimeoutMs,
+        1e4,
+        "cache.lease.waitTimeoutMs"
+      ),
+      pollIntervalMs: normalizePositiveDuration(
+        config.lease?.pollIntervalMs,
+        25,
+        "cache.lease.pollIntervalMs"
+      )
+    };
+    if (!this.local) {
+      this.entries.clear();
+      this.inflight.clear();
+      this.invalidatedTagVersions.clear();
+      this.version = 0;
+    }
+  }
+  get adapterName() {
+    return this.adapter?.name || (this.adapter ? "custom" : "memory");
+  }
+  get hasAdapter() {
+    return this.adapter !== void 0;
   }
   get size() {
     return this.entries.size;
@@ -1079,6 +1121,45 @@ var _FarmDataCache = class _FarmDataCache {
     });
     return this.toPublicEntry(entry);
   }
+  async getEntryAsync(key, options = {}) {
+    if (this.local) {
+      const localEntry = this.getEntry(key, options);
+      if (localEntry) return localEntry;
+    }
+    if (!this.adapter) {
+      return this.local ? void 0 : this.getEntry(key, options);
+    }
+    const entry = await this.adapter.get(this.createAdapterKey(key));
+    if (!entry) {
+      emitFarmEvent({ type: "cache.miss", key });
+      return void 0;
+    }
+    assertFarmCacheEntry(entry, key);
+    const stale = await this.isAdapterEntryStale(entry, options.now);
+    if (stale) {
+      emitFarmEvent({
+        type: "cache.stale",
+        key,
+        tags: [...entry.tags],
+        revalidate: entry.revalidate
+      });
+      if (!options.allowStale) {
+        emitFarmEvent({ type: "cache.miss", key, reason: "stale" });
+        return void 0;
+      }
+    }
+    emitFarmEvent({
+      type: "cache.hit",
+      key,
+      tags: [...entry.tags],
+      revalidate: entry.revalidate,
+      stale
+    });
+    if (this.local && !stale) {
+      this.hydrateLocalEntry(entry);
+    }
+    return { ...entry, key };
+  }
   set(key, value, options = {}) {
     const tags = /* @__PURE__ */ new Set();
     for (const tag of options.tags ?? []) {
@@ -1091,6 +1172,7 @@ var _FarmDataCache = class _FarmDataCache {
       key,
       value,
       tags,
+      tagVersions: void 0,
       createdAt: options.createdAt ?? Date.now(),
       createdVersion: ++this.version,
       revalidate: normalizeRevalidate(options.revalidate)
@@ -1104,11 +1186,45 @@ var _FarmDataCache = class _FarmDataCache {
     });
     return this.toPublicEntry(entry);
   }
+  async setAsync(key, value, options = {}, tagVersions) {
+    const tags = normalizeCacheOptionsTags(options);
+    const capturedVersions = tagVersions ?? await this.getAdapterTagVersions(Array.from(tags.values()));
+    const entry = {
+      key,
+      value,
+      tags: Array.from(tags),
+      tagVersions: capturedVersions,
+      createdAt: options.createdAt ?? Date.now(),
+      createdVersion: ++this.version,
+      revalidate: normalizeRevalidate(options.revalidate)
+    };
+    if (this.local) {
+      this.hydrateLocalEntry(entry);
+    }
+    if (this.adapter) {
+      await this.adapter.set(this.createAdapterKey(key), entry);
+    }
+    emitFarmEvent({
+      type: "cache.set",
+      key,
+      tags: [...entry.tags],
+      revalidate: entry.revalidate
+    });
+    return entry;
+  }
   delete(key) {
     const deleted = this.entries.delete(key);
     emitFarmEvent({ type: "cache.delete", key, deleted });
     return deleted;
   }
+  async deleteAsync(key) {
+    const deleted = this.entries.delete(key);
+    if (this.adapter) {
+      await this.adapter.delete(this.createAdapterKey(key));
+    }
+    emitFarmEvent({ type: "cache.delete", key, deleted: this.adapter ? true : deleted });
+    return this.adapter ? true : deleted;
+  }
   clear() {
     const count = this.entries.size;
     this.entries.clear();
@@ -1117,6 +1233,10 @@ var _FarmDataCache = class _FarmDataCache {
     this.version = 0;
     emitFarmEvent({ type: "cache.clear", count });
   }
+  async clearAsync() {
+    this.clear();
+    await this.adapter?.clear?.();
+  }
   isStale(entry, now2 = Date.now()) {
     if (typeof entry.revalidate === "number" && entry.revalidate > 0 && now2 - entry.createdAt >= entry.revalidate * 1e3) {
       return true;
@@ -1129,6 +1249,12 @@ var _FarmDataCache = class _FarmDataCache {
     }
     return false;
   }
+  async isStaleAsync(entry, now2 = Date.now()) {
+    if (this.adapter) {
+      return this.isAdapterEntryStale(entry, now2);
+    }
+    return this.isStale(entry, now2);
+  }
   revalidateTag(tag, options = {}) {
     const normalized = normalizeCacheTag(tag);
     const count = this.invalidateTag(normalized);
@@ -1137,6 +1263,15 @@ var _FarmDataCache = class _FarmDataCache {
     );
     return count;
   }
+  async revalidateTagAsync(tag, options = {}) {
+    const normalized = normalizeCacheTag(tag);
+    const count = this.invalidateTag(normalized);
+    await this.adapter?.invalidateTags?.([this.createAdapterTag(normalized)]);
+    emitFarmEvent(
+      options.source === "updateTag" ? { type: "cache.updateTag", tag: normalized, count } : { type: "cache.revalidateTag", tag: normalized, profile: options.profile, count }
+    );
+    return count;
+  }
   revalidatePath(routePath) {
     const normalizedPath = normalizeRevalidatePath(routePath);
     const pathTag = createPathCacheTag(normalizedPath);
@@ -1153,8 +1288,25 @@ var _FarmDataCache = class _FarmDataCache {
     }
     return count;
   }
+  async revalidatePathAsync(routePath) {
+    const normalizedPath = normalizeRevalidatePath(routePath);
+    const pathTag = createPathCacheTag(normalizedPath);
+    const pprCount = this.countEntriesForTags([pathTag, "ppr"]);
+    const count = this.invalidateTag(pathTag);
+    await this.adapter?.invalidateTags?.([this.createAdapterTag(pathTag)]);
+    emitFarmEvent({ type: "cache.revalidatePath", path: normalizedPath, count });
+    if (pprCount > 0) {
+      emitFarmEvent({
+        type: "ppr.shell.invalidated",
+        route: normalizedPath,
+        reason: "revalidatePath",
+        count: pprCount
+      });
+    }
+    return count;
+  }
   async getOrSet(key, producer, options = {}) {
-    const cached = this.getEntry(key);
+    const cached = await this.getEntryAsync(key);
     if (cached) {
       return cached.value;
     }
@@ -1163,10 +1315,8 @@ var _FarmDataCache = class _FarmDataCache {
       emitFarmEvent({ type: "cache.dedupe", key });
       return inflight;
     }
-    const promise = Promise.resolve().then(producer).then((value) => {
-      this.set(key, value, options);
-      return value;
-    }).catch((error) => {
+    const tags = Array.from(normalizeCacheOptionsTags(options));
+    const promise = this.fillCacheEntry(key, producer, options, tags).catch((error) => {
       emitFarmEvent({ type: "cache.error", key, operation: "set", error });
       throw error;
     }).finally(() => {
@@ -1175,6 +1325,40 @@ var _FarmDataCache = class _FarmDataCache {
     this.inflight.set(key, promise);
     return promise;
   }
+  async fillCacheEntry(key, producer, options, tags) {
+    const leaseKey = `${this.namespace}:lease:${key}`;
+    let leaseToken;
+    if (this.adapter?.acquireLease && this.adapter.releaseLease && this.lease.enabled) {
+      leaseToken = await this.adapter.acquireLease(leaseKey, this.lease.ttlMs);
+      if (!leaseToken) {
+        const shared = await this.waitForAdapterEntry(key);
+        if (shared) {
+          emitFarmEvent({ type: "cache.dedupe", key });
+          return shared.value;
+        }
+        leaseToken = await this.adapter.acquireLease(leaseKey, this.lease.ttlMs);
+      }
+    }
+    try {
+      const initialTagVersions = await this.getAdapterTagVersions(tags);
+      const value = await producer();
+      await this.setAsync(key, value, options, initialTagVersions);
+      return value;
+    } finally {
+      if (leaseToken && this.adapter?.releaseLease) {
+        await this.adapter.releaseLease(leaseKey, leaseToken);
+      }
+    }
+  }
+  async waitForAdapterEntry(key) {
+    const deadline = Date.now() + this.lease.waitTimeoutMs;
+    while (Date.now() < deadline) {
+      await delay(this.lease.pollIntervalMs);
+      const entry = await this.getEntryAsync(key);
+      if (entry) return entry;
+    }
+    return void 0;
+  }
   countEntriesForTag(tag) {
     let count = 0;
     for (const entry of this.entries.values()) {
@@ -1202,11 +1386,53 @@ var _FarmDataCache = class _FarmDataCache {
       key: entry.key,
       value: entry.value,
       tags: Array.from(entry.tags),
+      tagVersions: entry.tagVersions,
       createdAt: entry.createdAt,
       createdVersion: entry.createdVersion,
       revalidate: entry.revalidate
     };
   }
+  hydrateLocalEntry(entry) {
+    this.entries.set(entry.key, {
+      key: entry.key,
+      value: entry.value,
+      tags: new Set(entry.tags.map(normalizeCacheTag)),
+      tagVersions: entry.tagVersions,
+      createdAt: entry.createdAt,
+      createdVersion: entry.createdVersion ?? ++this.version,
+      revalidate: normalizeRevalidate(entry.revalidate)
+    });
+  }
+  createAdapterKey(key) {
+    return `${this.namespace}:entry:${key}`;
+  }
+  createAdapterTag(tag) {
+    return `${this.namespace}:tag:${tag}`;
+  }
+  async getAdapterTagVersions(tags) {
+    if (!this.adapter?.getTagVersions || tags.length === 0) return {};
+    const normalized = tags.map(normalizeCacheTag);
+    const physicalTags = normalized.map((tag) => this.createAdapterTag(tag));
+    const versions = await this.adapter.getTagVersions(physicalTags);
+    return Object.fromEntries(
+      normalized.map((tag, index) => [
+        tag,
+        normalizeAdapterVersion(versions[physicalTags[index]])
+      ])
+    );
+  }
+  async isAdapterEntryStale(entry, now2 = Date.now()) {
+    if (typeof entry.revalidate === "number" && entry.revalidate > 0 && now2 - entry.createdAt >= entry.revalidate * 1e3) {
+      return true;
+    }
+    const currentVersions = await this.getAdapterTagVersions(entry.tags);
+    for (const tag of entry.tags) {
+      if (normalizeAdapterVersion(currentVersions[tag]) > normalizeAdapterVersion(entry.tagVersions?.[tag])) {
+        return true;
+      }
+    }
+    return false;
+  }
 };
 __name(_FarmDataCache, "FarmDataCache");
 var FarmDataCache = _FarmDataCache;
@@ -1271,6 +1497,52 @@ function normalizeCacheTag(tag) {
   return normalized;
 }
 __name(normalizeCacheTag, "normalizeCacheTag");
+function normalizeCacheNamespace(namespace) {
+  if (typeof namespace !== "string") {
+    throw new TypeError("Cache namespace must be a string.");
+  }
+  const normalized = namespace.trim().replace(/:+$/g, "");
+  if (!normalized) {
+    throw new Error("Cache namespace cannot be empty.");
+  }
+  return normalized;
+}
+__name(normalizeCacheNamespace, "normalizeCacheNamespace");
+function normalizeAdapterVersion(value) {
+  return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : 0;
+}
+__name(normalizeAdapterVersion, "normalizeAdapterVersion");
+function normalizePositiveDuration(value, fallback, name) {
+  if (value === void 0) return fallback;
+  if (!Number.isFinite(value) || value <= 0) {
+    throw new TypeError(`${name} must be a positive number of milliseconds.`);
+  }
+  return Math.floor(value);
+}
+__name(normalizePositiveDuration, "normalizePositiveDuration");
+function delay(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+__name(delay, "delay");
+function normalizeCacheOptionsTags(options) {
+  const tags = /* @__PURE__ */ new Set();
+  for (const tag of options.tags ?? []) {
+    tags.add(normalizeCacheTag(tag));
+  }
+  for (const routePath of options.paths ?? []) {
+    tags.add(createPathCacheTag(routePath));
+  }
+  return tags;
+}
+__name(normalizeCacheOptionsTags, "normalizeCacheOptionsTags");
+function assertFarmCacheEntry(entry, expectedKey) {
+  if (!entry || typeof entry !== "object" || entry.key !== expectedKey || !Array.isArray(entry.tags) || typeof entry.createdAt !== "number") {
+    throw new TypeError(
+      `Cache adapter returned an invalid entry for ${JSON.stringify(expectedKey)}.`
+    );
+  }
+}
+__name(assertFarmCacheEntry, "assertFarmCacheEntry");
 function getFunctionCacheIdentity(fn) {
   if (fn.name) {
     return `name:${fn.name}`;
@@ -1467,8 +1739,74 @@ function normalizeFarmClientCacheKey(key) {
 }
 __name(normalizeFarmClientCacheKey, "normalizeFarmClientCacheKey");
 
+// src/api/transport.ts
+function isJSONStreamResponse(response) {
+  const contentType = response.headers?.get?.("content-type")?.toLowerCase() ?? "";
+  return contentType.includes("application/x-ndjson") || contentType.includes("application/ndjson");
+}
+__name(isJSONStreamResponse, "isJSONStreamResponse");
+function readJSONStream(response) {
+  if (!response.body) {
+    throw new TypeError("Cannot read a JSON stream response without a body");
+  }
+  const reader = response.body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+  let completed = false;
+  let claimed = false;
+  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: JSON.parse(line) };
+        }
+        if (completed) {
+          const line = buffer.trim();
+          buffer = "";
+          if (!line) return { done: true, value: void 0 };
+          return { done: false, value: JSON.parse(line) };
+        }
+        const chunk = await reader.read();
+        completed = chunk.done;
+        buffer += decoder.decode(chunk.value, { stream: !chunk.done });
+      }
+    },
+    async return() {
+      completed = true;
+      buffer = "";
+      await reader.cancel();
+      return { done: true, value: void 0 };
+    }
+  };
+  return {
+    response,
+    async cancel(reason) {
+      completed = true;
+      buffer = "";
+      await reader.cancel(reason);
+    },
+    [Symbol.asyncIterator]() {
+      if (claimed) {
+        throw new TypeError("Farm API streams can only be consumed once");
+      }
+      claimed = true;
+      return iterator;
+    }
+  };
+}
+__name(readJSONStream, "readJSONStream");
+function isFarmAPIStream(value) {
+  return typeof value === "object" && value !== null && "response" in value && typeof value.cancel === "function" && typeof value[Symbol.asyncIterator] === "function";
+}
+__name(isFarmAPIStream, "isFarmAPIStream");
+
 // src/api/client.ts
 var FARM_API_ROUTE_REF_SYMBOL = /* @__PURE__ */ Symbol.for("farm.api.route-ref");
+var FARM_API_ROUTE_META_SYMBOL = /* @__PURE__ */ Symbol.for("farm.api.route-meta");
 var _APIClientError = class _APIClientError extends Error {
   constructor(code, data, options) {
     super(options.message);
@@ -1506,16 +1844,22 @@ function createAPIClient(options = {}) {
         }
       });
     }
+    const headers = {
+      "Content-Type": "application/json",
+      ...options.headers,
+      ...requestOptions.headers
+    };
     const fetchOptions = {
       method: requestOptions.method || "GET",
-      headers: {
-        "Content-Type": "application/json",
-        ...options.headers,
-        ...requestOptions.headers
-      }
+      headers
     };
-    if (requestOptions.body) {
-      fetchOptions.body = JSON.stringify(requestOptions.body);
+    if (requestOptions.body !== void 0) {
+      if (isFormData(requestOptions.body)) {
+        deleteHeader(headers, "content-type");
+        fetchOptions.body = requestOptions.body;
+      } else {
+        fetchOptions.body = JSON.stringify(requestOptions.body);
+      }
     }
     const response = await fetch(url.toString(), fetchOptions);
     applyFarmCacheInvalidations(
@@ -1523,7 +1867,7 @@ function createAPIClient(options = {}) {
     );
     let data = void 0;
     if (response.status !== 204 && response.status !== 205) {
-      data = await response.json();
+      data = isJSONStreamResponse(response) ? readJSONStream(response) : await response.json();
     }
     return { response, data };
   }, "fetchClient");
@@ -1669,16 +2013,16 @@ function createAPIClient(options = {}) {
             }
           }
           attempt += 1;
-          const delay = typeof clientOptions?.retry?.delay === "function" ? clientOptions.retry.delay(attempt) : clientOptions?.retry?.delay ?? 0;
-          if (delay > 0) {
-            await new Promise((resolve) => setTimeout(resolve, delay));
+          const delay2 = typeof clientOptions?.retry?.delay === "function" ? clientOptions.retry.delay(attempt) : clientOptions?.retry?.delay ?? 0;
+          if (delay2 > 0) {
+            await new Promise((resolve) => setTimeout(resolve, delay2));
           }
         }
       })();
       inflightState.set(cacheKey, { promise, startedAt: now2 });
       try {
         const result2 = await promise;
-        if (!result2.error && isCacheEnabled) {
+        if (!result2.error && isCacheEnabled && !isFarmAPIStream(result2.data)) {
           const updatedAt = Date.now();
           cacheState.set(cacheKey, {
             data: result2.data,
@@ -1751,10 +2095,17 @@ function createAPIClient(options = {}) {
     clientOptions?.onSettled?.(result.data, result.error);
     return result;
   }, "request");
-  return createNestedProxy([], request, routeMeta, baseURL, rootAliases);
+  return createNestedProxy(
+    [],
+    request,
+    routeMeta,
+    baseURL,
+    options.baseURL === void 0,
+    rootAliases
+  );
 }
 __name(createAPIClient, "createAPIClient");
-function createNestedProxy(path, client, routeMeta, baseURL, rootAliases) {
+function createNestedProxy(path, client, routeMeta, baseURL, sameOrigin, rootAliases) {
   const target = /* @__PURE__ */ __name(() => {
   }, "target");
   const proxy = new Proxy(target, {
@@ -1763,13 +2114,29 @@ function createNestedProxy(path, client, routeMeta, baseURL, rootAliases) {
       if (prop === FARM_API_ROUTE_REF_SYMBOL) {
         return path.length > 0;
       }
+      if (prop === FARM_API_ROUTE_META_SYMBOL) {
+        const metadata = resolveRouteMeta({ path, baseURL });
+        return Object.freeze({
+          path: metadata.routePath,
+          method: metadata.method,
+          baseURL,
+          sameOrigin
+        });
+      }
       if (path.length === 0 && typeof prop === "string" && rootAliases && prop in rootAliases) {
         return rootAliases[prop];
       }
       if (typeof prop !== "string") {
         return Reflect.get(_target, prop);
       }
-      return createNestedProxy([...path, prop], client, routeMeta, baseURL, rootAliases);
+      return createNestedProxy(
+        [...path, prop],
+        client,
+        routeMeta,
+        baseURL,
+        sameOrigin,
+        rootAliases
+      );
     },
     // When calling as a function
     apply(_target, _thisArg, args) {
@@ -1795,6 +2162,22 @@ function isAPIRouteRef(value) {
   return typeof value === "function" && value[FARM_API_ROUTE_REF_SYMBOL] === true;
 }
 __name(isAPIRouteRef, "isAPIRouteRef");
+function getAPIRouteRefMetadata(value) {
+  if (!isAPIRouteRef(value)) return null;
+  const metadata = value[FARM_API_ROUTE_META_SYMBOL];
+  if (!metadata || typeof metadata !== "object") return null;
+  const candidate = metadata;
+  if (typeof candidate.path !== "string" || typeof candidate.method !== "string" || typeof candidate.baseURL !== "string" || typeof candidate.sameOrigin !== "boolean") {
+    return null;
+  }
+  return {
+    path: candidate.path,
+    method: candidate.method,
+    baseURL: candidate.baseURL,
+    sameOrigin: candidate.sameOrigin
+  };
+}
+__name(getAPIRouteRefMetadata, "getAPIRouteRefMetadata");
 function createServerAPIClient(endpoints, options = {}) {
   if (options.integrations === false || Object.prototype.hasOwnProperty.call(endpoints, "integrations")) {
     return endpoints;
@@ -1899,6 +2282,17 @@ function normalizeError(error) {
   return normalized;
 }
 __name(normalizeError, "normalizeError");
+function isFormData(value) {
+  return typeof value === "object" && value !== null && (typeof FormData !== "undefined" && value instanceof FormData || Object.prototype.toString.call(value) === "[object FormData]" && typeof value.entries === "function");
+}
+__name(isFormData, "isFormData");
+function deleteHeader(headers, name) {
+  const normalized = name.toLowerCase();
+  for (const key of Object.keys(headers)) {
+    if (key.toLowerCase() === normalized) delete headers[key];
+  }
+}
+__name(deleteHeader, "deleteHeader");
 function createResponseError2(response, data) {
   const expected = readEndpointErrorEnvelope(data);
   if (expected) {
@@ -2089,8 +2483,171 @@ function normalizeMutationError(error) {
 }
 __name(normalizeMutationError, "normalizeMutationError");
 
-// src/server-query-client.ts
+// src/fetcher-client.tsx
 var import_react2 = require("react");
+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);
+  targetRef.current = target;
+  optionsRef.current = options;
+  const submitAsync = (0, import_react2.useCallback)(
+    async (input) => {
+      const submissionId = ++submissionIdRef.current;
+      const submittedFormData = isFormData2(input) ? input : null;
+      setFormData(submittedFormData);
+      try {
+        const variables = submittedFormData ? mapFetcherFormData(targetRef.current, submittedFormData, optionsRef.current) : input;
+        return await mutation.mutateAsync(variables);
+      } finally {
+        if (submissionId === submissionIdRef.current) {
+          setFormData(null);
+        }
+      }
+    },
+    [mutation.mutateAsync]
+  );
+  const submit = (0, import_react2.useCallback)(
+    (input) => {
+      void submitAsync(input).catch(() => {
+      });
+    },
+    [submitAsync]
+  );
+  const Form = (0, import_react2.useMemo)(() => {
+    const FetcherForm = /* @__PURE__ */ __name(({ action, method, encType, onSubmit, ...props }) => {
+      const targetValue = targetRef.current;
+      const metadata = getAPIRouteRefMetadata(targetValue);
+      const nativeAction = action ?? resolveFetcherFormAction(targetValue, metadata);
+      const nativeMethod = method ?? (metadata && (metadata.method === "GET" || metadata.method === "POST") ? metadata.method.toLowerCase() : metadata ? "post" : void 0);
+      const functionAction = typeof nativeAction === "function";
+      const handleSubmit = /* @__PURE__ */ __name((event) => {
+        onSubmit?.(event);
+        if (event.defaultPrevented) return;
+        event.preventDefault();
+        const submitter = getSubmitter(event);
+        const nextFormData = createSubmitterFormData(event.currentTarget, submitter);
+        formDataContexts.set(nextFormData, {
+          form: event.currentTarget,
+          submitter
+        });
+        void submitAsync(nextFormData).catch(() => {
+        });
+      }, "handleSubmit");
+      return (0, import_react2.createElement)("form", {
+        ...props,
+        action: nativeAction,
+        method: functionAction ? void 0 : nativeMethod,
+        encType: functionAction ? void 0 : encType,
+        onSubmit: handleSubmit
+      });
+    }, "FetcherForm");
+    FetcherForm.displayName = "FetcherForm";
+    return FetcherForm;
+  }, [submitAsync]);
+  const reset = (0, import_react2.useCallback)(() => {
+    submissionIdRef.current += 1;
+    setFormData(null);
+    mutation.reset();
+  }, [mutation.reset]);
+  return (0, import_react2.useMemo)(
+    () => ({
+      state: mutation.pending ? "submitting" : "idle",
+      status: mutation.status,
+      pending: mutation.pending,
+      data: mutation.data,
+      error: mutation.error,
+      variables: mutation.variables,
+      formData,
+      submit,
+      submitAsync,
+      Form,
+      reset
+    }),
+    [
+      Form,
+      formData,
+      mutation.data,
+      mutation.error,
+      mutation.pending,
+      mutation.status,
+      mutation.variables,
+      reset,
+      submit,
+      submitAsync
+    ]
+  );
+}
+__name(useFetcher, "useFetcher");
+function mapFetcherFormData(target, formData, options) {
+  const context = formDataContexts.get(formData) ?? { form: null, submitter: null };
+  if (options.mapFormData) {
+    return options.mapFormData(formData, context);
+  }
+  if (!isAPIRouteRef(target)) {
+    return formData;
+  }
+  const values = formDataToObject(formData);
+  const method = getAPIRouteRefMetadata(target)?.method;
+  return method === "GET" || method === "HEAD" ? { query: values } : { body: values };
+}
+__name(mapFetcherFormData, "mapFetcherFormData");
+function resolveFetcherFormAction(target, metadata) {
+  if (!metadata) return isProgressiveFormAction(target) ? target : void 0;
+  if (metadata.sameOrigin) return metadata.path;
+  return new URL(metadata.path, metadata.baseURL).href;
+}
+__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;
+    const current = output[key];
+    if (current === void 0) {
+      output[key] = value;
+    } else if (Array.isArray(current)) {
+      current.push(value);
+    } else {
+      output[key] = [current, value];
+    }
+  }
+  return output;
+}
+__name(formDataToObject, "formDataToObject");
+function createSubmitterFormData(form, submitter) {
+  try {
+    return new FormData(form, submitter);
+  } catch {
+    const formData = new FormData(form);
+    const candidate = submitter;
+    if (candidate && !candidate.disabled && candidate.name) {
+      formData.append(candidate.name, candidate.value ?? "");
+    }
+    return formData;
+  }
+}
+__name(createSubmitterFormData, "createSubmitterFormData");
+function getSubmitter(event) {
+  const nativeEvent = event.nativeEvent;
+  return nativeEvent.submitter instanceof HTMLElement ? nativeEvent.submitter : null;
+}
+__name(getSubmitter, "getSubmitter");
+function isProgressiveFormAction(target) {
+  const candidate = target;
+  return candidate.__farmServerFn === true || typeof candidate.$$FORM_ACTION === "function" || candidate.$$typeof === /* @__PURE__ */ Symbol.for("react.server.reference");
+}
+__name(isProgressiveFormAction, "isProgressiveFormAction");
+function isFormData2(value) {
+  if (!value || typeof value !== "object") return false;
+  return typeof FormData !== "undefined" && value instanceof FormData || Object.prototype.toString.call(value) === "[object FormData]" && typeof value.entries === "function";
+}
+__name(isFormData2, "isFormData");
+
+// src/server-query-client.ts
+var import_react3 = require("react");
 var FARM_SERVER_QUERY_CLIENT_STATE = /* @__PURE__ */ Symbol.for("farm.serverQueryClientState");
 var serverQueryClientGlobal = globalThis;
 var serverQueryClientState = serverQueryClientGlobal[FARM_SERVER_QUERY_CLIENT_STATE] ?? (serverQueryClientGlobal[FARM_SERVER_QUERY_CLIENT_STATE] = {
@@ -2122,25 +2679,25 @@ __name(prefetchServerQuery, "prefetchServerQuery");
 function useServerQuery(query, input, options = {}) {
   const cache = getFarmClientDataCache();
   const key = createServerQueryCallKey(query, input);
-  const inputRef = (0, import_react2.useRef)(input);
-  const optionsRef = (0, import_react2.useRef)(options);
-  const mountedKeyRef = (0, import_react2.useRef)();
+  const inputRef = (0, import_react3.useRef)(input);
+  const optionsRef = (0, import_react3.useRef)(options);
+  const mountedKeyRef = (0, import_react3.useRef)();
   inputRef.current = input;
   optionsRef.current = options;
-  const subscribe = (0, import_react2.useCallback)(
+  const subscribe = (0, import_react3.useCallback)(
     (listener) => cache.subscribe(key, listener),
     [cache, key]
   );
-  const getSnapshot = (0, import_react2.useCallback)(() => cache.get(key), [cache, key]);
-  const entry = (0, import_react2.useSyncExternalStore)(subscribe, getSnapshot, () => void 0);
-  const run = (0, import_react2.useCallback)(
+  const getSnapshot = (0, import_react3.useCallback)(() => cache.get(key), [cache, key]);
+  const entry = (0, import_react3.useSyncExternalStore)(subscribe, getSnapshot, () => void 0);
+  const run = (0, import_react3.useCallback)(
     (force = false) => fetchServerQuery(query, inputRef.current, {
       ...optionsRef.current,
       force
     }),
     [query]
   );
-  (0, import_react2.useEffect)(() => {
+  (0, import_react3.useEffect)(() => {
     if (options.enabled === false) return;
     const firstReadForKey = mountedKeyRef.current !== key;
     if (firstReadForKey) mountedKeyRef.current = key;
@@ -2148,7 +2705,7 @@ function useServerQuery(query, input, options = {}) {
       void run().catch(() => void 0);
     }
   }, [cache, entry, key, options.enabled, run]);
-  (0, import_react2.useEffect)(() => {
+  (0, import_react3.useEffect)(() => {
     if (options.enabled === false || typeof window === "undefined") return;
     const refreshIfStale = /* @__PURE__ */ __name(() => {
       if (cache.isStale(key)) void run().catch(() => void 0);
@@ -2461,7 +3018,7 @@ var api = {
 var endpoint = api;
 
 // src/store.ts
-var import_react3 = require("react");
+var import_react4 = require("react");
 var RESERVED_STORE_KEYS = /* @__PURE__ */ new Set([
   "use",
   "get",
@@ -2593,20 +3150,20 @@ function createStore(initialState, extend) {
         }
         return lastSlice;
       }, "getSnapshot");
-      return (0, import_react3.useSyncExternalStore)(
+      return (0, import_react4.useSyncExternalStore)(
         (notify) => addSubscription(keys, () => notify()),
         getSnapshot,
         getSnapshot
       );
     }
     if (typeof keyOrKeys === "string") {
-      return (0, import_react3.useSyncExternalStore)(
+      return (0, import_react4.useSyncExternalStore)(
         (notify) => addSubscription([keyOrKeys], () => notify()),
         () => state[keyOrKeys],
         () => state[keyOrKeys]
       );
     }
-    return (0, import_react3.useSyncExternalStore)(
+    return (0, import_react4.useSyncExternalStore)(
       (notify) => addSubscription(null, () => notify()),
       () => state,
       () => state
@@ -2658,7 +3215,7 @@ function createStore(initialState, extend) {
 __name(createStore, "createStore");
 
 // src/client/link.tsx
-var import_react4 = require("react");
+var import_react5 = require("react");
 
 // src/router.ts
 function createFarmRouter(routes) {
@@ -3058,9 +3615,9 @@ function LinkInner({
   onTouchStart,
   ...props
 }, ref) {
-  const elementRef = (0, import_react4.useRef)(null);
-  const intentTimeoutRef = (0, import_react4.useRef)(null);
-  const hasPrefetched = (0, import_react4.useRef)(false);
+  const elementRef = (0, import_react5.useRef)(null);
+  const intentTimeoutRef = (0, import_react5.useRef)(null);
+  const hasPrefetched = (0, import_react5.useRef)(false);
   const { intent, viewport, render } = normalizePrefetch(prefetch2);
   const baseHref = resolveLinkHref(href, params, {
     query,
@@ -3069,17 +3626,17 @@ function LinkInner({
   });
   const resolvedHref = localizeActiveFarmHref(baseHref, locale);
   const isExternal = isExternalUrl(resolvedHref);
-  const doPrefetch = (0, import_react4.useCallback)(() => {
+  const doPrefetch = (0, import_react5.useCallback)(() => {
     if (isExternal || hasPrefetched.current) return;
     const router = getRouter();
     if (!router) return;
     hasPrefetched.current = true;
     router.prefetch(resolvedHref);
   }, [resolvedHref, isExternal]);
-  (0, import_react4.useEffect)(() => {
+  (0, import_react5.useEffect)(() => {
     hasPrefetched.current = false;
   }, [resolvedHref]);
-  (0, import_react4.useEffect)(() => {
+  (0, import_react5.useEffect)(() => {
     const element = elementRef.current;
     if (!element || isExternal) return;
     const router = getRouter();
@@ -3089,7 +3646,7 @@ function LinkInner({
       return () => router.unobserveForPrefetch(element);
     }
   }, [resolvedHref, viewport, isExternal]);
-  (0, import_react4.useEffect)(() => {
+  (0, import_react5.useEffect)(() => {
     if (!render || isExternal) return;
     let cancelled = false;
     let timeoutId = null;
@@ -3111,7 +3668,7 @@ function LinkInner({
       }
     };
   }, [render, isExternal, resolvedHref]);
-  (0, import_react4.useEffect)(() => {
+  (0, import_react5.useEffect)(() => {
     return () => {
       if (intentTimeoutRef.current) {
         clearTimeout(intentTimeoutRef.current);
@@ -3119,13 +3676,13 @@ function LinkInner({
       }
     };
   }, []);
-  const cancelIntent = (0, import_react4.useCallback)(() => {
+  const cancelIntent = (0, import_react5.useCallback)(() => {
     if (intentTimeoutRef.current) {
       clearTimeout(intentTimeoutRef.current);
       intentTimeoutRef.current = null;
     }
   }, []);
-  const scheduleIntentPrefetch = (0, import_react4.useCallback)(() => {
+  const scheduleIntentPrefetch = (0, import_react5.useCallback)(() => {
     if (isExternal || !intent || hasPrefetched.current) return;
     cancelIntent();
     intentTimeoutRef.current = setTimeout(() => {
@@ -3133,42 +3690,42 @@ function LinkInner({
       doPrefetch();
     }, prefetchDelay);
   }, [intent, isExternal, prefetchDelay, doPrefetch, cancelIntent]);
-  const handleMouseEnter = (0, import_react4.useCallback)(
+  const handleMouseEnter = (0, import_react5.useCallback)(
     (event) => {
       onMouseEnter?.(event);
       scheduleIntentPrefetch();
     },
     [onMouseEnter, scheduleIntentPrefetch]
   );
-  const handleMouseLeave = (0, import_react4.useCallback)(
+  const handleMouseLeave = (0, import_react5.useCallback)(
     (event) => {
       onMouseLeave?.(event);
       cancelIntent();
     },
     [onMouseLeave, cancelIntent]
   );
-  const handleTouchStart = (0, import_react4.useCallback)(
+  const handleTouchStart = (0, import_react5.useCallback)(
     (event) => {
       onTouchStart?.(event);
       scheduleIntentPrefetch();
     },
     [onTouchStart, scheduleIntentPrefetch]
   );
-  const handleFocus = (0, import_react4.useCallback)(
+  const handleFocus = (0, import_react5.useCallback)(
     (event) => {
       onFocus?.(event);
       scheduleIntentPrefetch();
     },
     [onFocus, scheduleIntentPrefetch]
   );
-  const handleBlur = (0, import_react4.useCallback)(
+  const handleBlur = (0, import_react5.useCallback)(
     (event) => {
       onBlur?.(event);
       cancelIntent();
     },
     [onBlur, cancelIntent]
   );
-  const handleClick = (0, import_react4.useCallback)(
+  const handleClick = (0, import_react5.useCallback)(
     (event) => {
       onClick?.(event);
       if (event.defaultPrevented) return;
@@ -3193,7 +3750,7 @@ function LinkInner({
     },
     [resolvedHref, replace, scroll, viewTransition, target, isExternal, onClick]
   );
-  const setRefs = (0, import_react4.useCallback)(
+  const setRefs = (0, import_react5.useCallback)(
     (node) => {
       elementRef.current = node;
       if (typeof ref === "function") ref(node);
@@ -3222,7 +3779,7 @@ function LinkInner({
   );
 }
 __name(LinkInner, "LinkInner");
-var LinkWithRef = (0, import_react4.forwardRef)(LinkInner);
+var LinkWithRef = (0, import_react5.forwardRef)(LinkInner);
 LinkWithRef.displayName = "Link";
 var Link = LinkWithRef;
 function resolveLinkHref(href, params, options) {
@@ -3323,7 +3880,7 @@ function matchManifestRoute(pathname, route2) {
 __name(matchManifestRoute, "matchManifestRoute");
 
 // src/client/router.ts
-var import_react5 = require("react");
+var import_react6 = require("react");
 
 // src/deferred.ts
 var FARM_DEFERRED_CONTENT_TYPE = "application/x-farm-deferred+json";
@@ -3542,6 +4099,7 @@ __name(createFarmDeploymentMismatchError, "createFarmDeploymentMismatchError");
 
 // src/client/spa-router.ts
 var FARM_PAGE_STATE_KEY = "__farmPageState";
+var FARM_INTERCEPT_FROM_KEY = "__farmInterceptFrom";
 var IDLE_NAVIGATION_STATE = {
   state: "idle",
   pending: false,
@@ -3612,7 +4170,11 @@ var _SPARouter = class _SPARouter {
       return;
     }
     const from = window.location.pathname + window.location.search;
-    if (await this.shouldBlockNavigation({ from, to: fullPath, action: replace ? "replace" : "push" })) {
+    if (await this.shouldBlockNavigation({
+      from,
+      to: fullPath,
+      action: replace ? "replace" : "push"
+    })) {
       return;
     }
     if (this.options.scrollRestoration) {
@@ -3630,11 +4192,11 @@ var _SPARouter = class _SPARouter {
         to: url,
         action: replace ? "replace" : "push"
       });
-      const pageData = await this.fetchPageData(fullPath);
+      const pageData = await this.fetchPageData(fullPath, true, from);
       if (clientNavigation) {
         await this.clientPlugins?.markNavigationLoaded(clientNavigation, pageData);
       }
-      if (pageData.isClientComponent === false) {
+      if (pageData.isClientComponent === false && !pageData.interception) {
         this.finishNavigation();
         window.location.assign(pageData.canonicalPath || fullPath);
         return;
@@ -3672,11 +4234,12 @@ var _SPARouter = class _SPARouter {
     if (isFarmLocaleChangeHref(href)) return;
     const url = new URL(href, window.location.origin);
     const fullPath = url.pathname + url.search;
+    const interceptFrom = window.location.pathname + window.location.search;
     if (this.prefetchingUrls.has(fullPath)) return;
-    if (this.isCached(fullPath)) return;
+    if (this.isCached(fullPath, interceptFrom)) return;
     this.prefetchingUrls.add(fullPath);
     try {
-      await this.fetchPageData(fullPath, false);
+      await this.fetchPageData(fullPath, false, interceptFrom);
     } catch (error) {
       console.warn("[Farm.js] Prefetch failed:", href, error);
     } finally {
@@ -3751,7 +4314,12 @@ var _SPARouter = class _SPARouter {
   }
   async commitNavigation(options) {
     const historyPath = options.pageData.canonicalPath || options.fullPath;
-    const historyState = createHistoryState(historyPath, options.state);
+    const historyState = createHistoryState(
+      historyPath,
+      options.state,
+      void 0,
+      options.pageData.interception?.from ?? null
+    );
     if (options.replace) {
       window.history.replaceState(historyState, "", historyPath);
     } else {
@@ -3806,15 +4374,17 @@ var _SPARouter = class _SPARouter {
   /**
    * Fetch page data from cache or server
    */
-  async fetchPageData(path, recover = true) {
-    const cached = this.cache.get(path);
+  async fetchPageData(path, recover = true, interceptFrom) {
+    const cacheKey = getPageDataCacheKey(path, interceptFrom);
+    const cached = this.cache.get(cacheKey);
     if (cached && Date.now() - cached.timestamp < this.options.cacheMaxAge) {
       return cached.data;
     }
     const response = await fetch(`/__farm/page-data?path=${encodeURIComponent(path)}`, {
       headers: createFarmDeploymentRequestHeaders(this.options.deploymentId, {
         Accept: "application/x-farm-deferred+json, application/json",
-        "X-Farm-SPA": "1"
+        "X-Farm-SPA": "1",
+        ...interceptFrom ? { "X-Farm-Intercept-From": interceptFrom } : {}
       })
     });
     if (isFarmDeploymentMismatchResponse(response, this.options.deploymentId)) {
@@ -3832,7 +4402,7 @@ var _SPARouter = class _SPARouter {
       throw new Error(`Failed to fetch page data: ${response.status}`);
     }
     const data = await readDeferredDataResponse(response);
-    this.cache.set(path, {
+    this.cache.set(cacheKey, {
       data,
       timestamp: Date.now()
     });
@@ -3863,7 +4433,8 @@ var _SPARouter = class _SPARouter {
         to: window.location.href,
         action: "pop"
       });
-      const pageData = await this.fetchPageData(path);
+      const interceptFrom = typeof event.state?.[FARM_INTERCEPT_FROM_KEY] === "string" ? event.state[FARM_INTERCEPT_FROM_KEY] : void 0;
+      const pageData = await this.fetchPageData(path, true, interceptFrom);
       if (clientNavigation) {
         await this.clientPlugins?.markNavigationLoaded(clientNavigation, pageData);
       }
@@ -3894,8 +4465,8 @@ var _SPARouter = class _SPARouter {
   /**
    * Check if URL is cached
    */
-  isCached(path) {
-    const cached = this.cache.get(path);
+  isCached(path, interceptFrom) {
+    const cached = this.cache.get(getPageDataCacheKey(path, interceptFrom));
     return cached !== void 0 && Date.now() - cached.timestamp < this.options.cacheMaxAge;
   }
   /**
@@ -4051,15 +4622,26 @@ function readPageState() {
   return state[FARM_PAGE_STATE_KEY] ?? null;
 }
 __name(readPageState, "readPageState");
-function createHistoryState(path, pageState, currentState) {
+function createHistoryState(path, pageState, currentState, interceptFrom) {
   const base = currentState && typeof currentState === "object" ? { ...currentState } : {};
-  return {
+  const nextState = {
     ...base,
     path,
     [FARM_PAGE_STATE_KEY]: pageState
   };
+  if (interceptFrom === null) {
+    delete nextState[FARM_INTERCEPT_FROM_KEY];
+  } else if (interceptFrom) {
+    nextState[FARM_INTERCEPT_FROM_KEY] = interceptFrom;
+  }
+  return nextState;
 }
 __name(createHistoryState, "createHistoryState");
+function getPageDataCacheKey(path, interceptFrom) {
+  return interceptFrom ? `${path}
+intercept:${interceptFrom}` : path;
+}
+__name(getPageDataCacheKey, "getPageDataCacheKey");
 function createNavigationLocation(url) {
   return {
     href: url.href,
@@ -4079,14 +4661,14 @@ function useRouter(options = {}) {
   const basePath = options.basePath || "";
   const routes = options.routes;
   const routeKey = routes?.map((route2) => typeof route2 === "string" ? route2 : route2.path).join("\n") || "";
-  const routeMatcher = (0, import_react5.useMemo)(
+  const routeMatcher = (0, import_react6.useMemo)(
     () => routeKey ? createFarmRouter(routeKey.split("\n")) : null,
     [routeKey]
   );
-  const [state, setState] = (0, import_react5.useState)(() => {
+  const [state, setState] = (0, import_react6.useState)(() => {
     return readRouterState(basePath, routeMatcher);
   });
-  (0, import_react5.useEffect)(() => {
+  (0, import_react6.useEffect)(() => {
     if (typeof window === "undefined") return;
     const handlePopState = /* @__PURE__ */ __name(() => {
       setState(readRouterState(basePath, routeMatcher));
@@ -4137,8 +4719,8 @@ function useRouter(options = {}) {
 }
 __name(useRouter, "useRouter");
 function usePageState() {
-  const [state, setState] = (0, import_react5.useState)(() => readPageState());
-  (0, import_react5.useEffect)(() => {
+  const [state, setState] = (0, import_react6.useState)(() => readPageState());
+  (0, import_react6.useEffect)(() => {
     if (typeof window === "undefined") return;
     const handlePopState = /* @__PURE__ */ __name(() => {
       setState(readPageState());
@@ -4151,10 +4733,10 @@ function usePageState() {
 }
 __name(usePageState, "usePageState");
 function useNavigation() {
-  const [state, setState] = (0, import_react5.useState)(
+  const [state, setState] = (0, import_react6.useState)(
     () => getRouter2().getNavigationState()
   );
-  (0, import_react5.useEffect)(() => {
+  (0, import_react6.useEffect)(() => {
     if (typeof window === "undefined") return;
     return getRouter2().subscribeNavigation(setState);
   }, []);
@@ -4162,10 +4744,10 @@ function useNavigation() {
 }
 __name(useNavigation, "useNavigation");
 function useBlocker(options) {
-  const optionsRef = (0, import_react5.useRef)(options);
+  const optionsRef = (0, import_react6.useRef)(options);
   optionsRef.current = options;
   const active = Boolean(options.when);
-  (0, import_react5.useEffect)(() => {
+  (0, import_react6.useEffect)(() => {
     if (typeof window === "undefined" || !active) {
       return;
     }
@@ -4186,8 +4768,8 @@ function useBlocker(options) {
 }
 __name(useBlocker, "useBlocker");
 function useScrollRestoration(key) {
-  const ref = (0, import_react5.useRef)(null);
-  (0, import_react5.useEffect)(() => {
+  const ref = (0, import_react6.useRef)(null);
+  (0, import_react6.useEffect)(() => {
     const element = ref.current;
     if (!element) return;
     return getRouter2().registerScrollElement(key, element);
@@ -4809,6 +5391,7 @@ __name(isObject, "isObject");
   readPageState,
   replaceState,
   useBlocker,
+  useFetcher,
   useMutation,
   useNavigation,
   usePageState,