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

package/dist/client.cjs

@@ -31,6 +31,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/client.ts
 var client_exports = {};
 __export(client_exports, {
+  APIClientError: () => APIClientError,
   FarmClientPluginManager: () => FarmClientPluginManager,
   IntegrationClientError: () => IntegrationClientError,
   Link: () => Link,
@@ -63,6 +64,8 @@ __export(client_exports, {
   readPageState: () => readPageState,
   replaceState: () => replaceState,
   useBlocker: () => useBlocker,
+  useFetcher: () => useFetcher,
+  useMutation: () => useMutation,
   useNavigation: () => useNavigation,
   usePageState: () => usePageState,
   useRouter: () => useRouter,
@@ -180,7 +183,7 @@ function mergeIntegrationClientData(...values) {
       continue;
     }
     merged = {
-      ...merged || {},
+      ...merged,
       ...data
     };
   }
@@ -981,14 +984,44 @@ function formatError(error) {
 __name(formatError, "formatError");
 
 // src/cache-invalidation.ts
+var FARM_CACHE_INVALIDATION_HEADER = "x-farm-cache-invalidations";
 var FARM_CACHE_INVALIDATION_STATE = /* @__PURE__ */ Symbol.for("farm.cacheInvalidationState");
 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");
+function notifyFarmCacheInvalidation(key) {
+  if (typeof key !== "string" || key.length === 0) return;
+  for (const listener of getFarmCacheInvalidationState().listeners) {
+    listener(key);
+  }
+}
+__name(notifyFarmCacheInvalidation, "notifyFarmCacheInvalidation");
+function applyFarmCacheInvalidations(keys) {
+  if (!Array.isArray(keys)) return;
+  for (const key of keys) {
+    if (typeof key === "string") {
+      notifyFarmCacheInvalidation(key);
+    }
+  }
+}
+__name(applyFarmCacheInvalidations, "applyFarmCacheInvalidations");
+function decodeFarmCacheInvalidations(value) {
+  if (!value) return [];
+  try {
+    const parsed = JSON.parse(decodeURIComponent(value));
+    return Array.isArray(parsed) ? Array.from(
+      new Set(parsed.filter((key) => typeof key === "string" && key.length > 0))
+    ) : [];
+  } catch {
+    return [];
+  }
+}
+__name(decodeFarmCacheInvalidations, "decodeFarmCacheInvalidations");
 function subscribeFarmCacheInvalidation(listener) {
   const state = getFarmCacheInvalidationState();
   state.listeners.add(listener);
@@ -1008,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;
@@ -1048,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 ?? []) {
@@ -1060,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)
@@ -1073,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();
@@ -1086,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;
@@ -1098,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);
@@ -1106,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);
@@ -1122,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;
     }
@@ -1132,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(() => {
@@ -1144,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()) {
@@ -1171,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;
@@ -1240,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}`;
@@ -1436,7 +1739,86 @@ 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);
+    this.name = "APIClientError";
+    this.code = code;
+    this.data = data;
+    this.status = options.status;
+    this.response = options.response;
+  }
+};
+__name(_APIClientError, "APIClientError");
+var APIClientError = _APIClientError;
 function createAPIClient(options = {}) {
   options ?? (options = {});
   const baseURL = options.baseURL || (typeof window !== "undefined" ? window.location.origin : "http://localhost:3000");
@@ -1462,21 +1844,30 @@ 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(
+      decodeFarmCacheInvalidations(response.headers?.get?.(FARM_CACHE_INVALIDATION_HEADER))
+    );
     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");
@@ -1622,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,
@@ -1704,19 +2095,48 @@ 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, {
     // When accessing a property (api.hello)
     get(_target, prop) {
+      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];
       }
-      return createNestedProxy([...path, prop], client, routeMeta, baseURL, rootAliases);
+      if (typeof prop !== "string") {
+        return Reflect.get(_target, prop);
+      }
+      return createNestedProxy(
+        [...path, prop],
+        client,
+        routeMeta,
+        baseURL,
+        sameOrigin,
+        rootAliases
+      );
     },
     // When calling as a function
     apply(_target, _thisArg, args) {
@@ -1738,6 +2158,26 @@ function createNestedProxy(path, client, routeMeta, baseURL, rootAliases) {
   return proxy;
 }
 __name(createNestedProxy, "createNestedProxy");
+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;
@@ -1804,7 +2244,10 @@ function resolveTargetKey(routeMeta, target, input, baseURL = "http://localhost:
   }
   if (Array.isArray(target)) {
     const [route2, routeInput] = target;
-    return resolveTargetKey(routeMeta, route2, routeInput, baseURL);
+    if (typeof route2 === "function") {
+      return resolveTargetKey(routeMeta, route2, routeInput, baseURL);
+    }
+    return normalizeFarmClientCacheKey(target);
   }
   if ("key" in target) return normalizeFarmClientCacheKey(target.key);
   if ("path" in target) {
@@ -1830,21 +2273,381 @@ function resolveRouteMeta(meta) {
 }
 __name(resolveRouteMeta, "resolveRouteMeta");
 function normalizeError(error) {
-  if (error instanceof Error) return error;
-  return new Error(typeof error === "string" ? error : "Unknown error");
+  if (error instanceof APIClientError) return error;
+  const normalized = new APIClientError("network_error", void 0, {
+    status: 0,
+    message: error instanceof Error ? error.message : typeof error === "string" ? error : "Network request failed"
+  });
+  normalized.cause = 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 error = new Error(`HTTP ${response.status}: ${response.statusText}`);
-  error.status = response.status;
-  error.response = response;
-  error.data = data;
-  return error;
+  const expected = readEndpointErrorEnvelope(data);
+  if (expected) {
+    return new APIClientError(expected.code, expected.data, {
+      status: response.status,
+      message: expected.message,
+      response
+    });
+  }
+  return new APIClientError("http_error", data, {
+    status: response.status,
+    message: `HTTP ${response.status}: ${response.statusText}`,
+    response
+  });
 }
 __name(createResponseError2, "createResponseError");
+function readEndpointErrorEnvelope(data) {
+  if (!data || typeof data !== "object") return null;
+  const error = data.error;
+  if (!error || typeof error !== "object") return null;
+  const code = error.code;
+  const message = error.message;
+  if (typeof code !== "string" || typeof message !== "string") return null;
+  return {
+    code,
+    message,
+    data: error.data
+  };
+}
+__name(readEndpointErrorEnvelope, "readEndpointErrorEnvelope");
 
-// src/server-query-client.ts
+// src/mutation-client.ts
 var import_react = require("react");
+function useMutation(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 initialState = {
+    pendingCount: 0,
+    status: "idle",
+    data: initialData,
+    error: null,
+    variables: void 0
+  };
+  const stateRef = (0, import_react.useRef)(initialState);
+  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 mutateAsync = (0, import_react.useCallback)(
+    async (variables) => {
+      const requestId = ++requestIdRef.current;
+      const currentOptions = optionsRef.current;
+      const previousData = stateRef.current.data;
+      const optimisticData = 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
+      }));
+      try {
+        const mutationTarget = targetRef.current;
+        const rawResult = isAPIRouteRef(mutationTarget) ? await mutationTarget(variables, currentOptions.request) : await mutationTarget(variables);
+        const data = unwrapMutationResult(rawResult, isAPIRouteRef(mutationTarget));
+        const isLatestRequest = requestId === requestIdRef.current;
+        setMutationState((current) => {
+          const pendingCount = Math.max(0, current.pendingCount - 1);
+          if (!isLatestRequest) {
+            return {
+              ...current,
+              pendingCount,
+              status: pendingCount > 0 ? "pending" : current.status
+            };
+          }
+          return {
+            pendingCount,
+            status: "success",
+            data,
+            error: null,
+            variables
+          };
+        });
+        if (isLatestRequest) {
+          currentOptions.onSuccess?.(data, variables);
+          currentOptions.onSettled?.(data, null, variables);
+        }
+        return data;
+      } catch (cause) {
+        const error = normalizeMutationError(cause);
+        const isLatestRequest = requestId === requestIdRef.current;
+        setMutationState((current) => {
+          const pendingCount = Math.max(0, current.pendingCount - 1);
+          if (!isLatestRequest) {
+            return {
+              ...current,
+              pendingCount,
+              status: pendingCount > 0 ? "pending" : current.status
+            };
+          }
+          return {
+            pendingCount,
+            status: "error",
+            data: hasOptimisticData && currentOptions.rollbackOnError ? previousData : currentOptions.resetOnMutate === false ? current.data : null,
+            error,
+            variables
+          };
+        });
+        if (isLatestRequest) {
+          currentOptions.onError?.(error, variables);
+          currentOptions.onSettled?.(null, error, variables);
+        }
+        throw error;
+      }
+    },
+    [setMutationState]
+  );
+  const mutate = (0, import_react.useCallback)(
+    (variables) => {
+      void mutateAsync(variables).catch(() => {
+      });
+    },
+    [mutateAsync]
+  );
+  const reset = (0, import_react.useCallback)(() => {
+    requestIdRef.current += 1;
+    setMutationState({
+      pendingCount: 0,
+      status: "idle",
+      data: optionsRef.current.initialData ?? null,
+      error: null,
+      variables: void 0
+    });
+  }, [setMutationState]);
+  return (0, import_react.useMemo)(
+    () => ({
+      pending: state.pendingCount > 0,
+      status: state.status,
+      data: state.data,
+      error: state.error,
+      variables: state.variables,
+      mutate,
+      mutateAsync,
+      reset
+    }),
+    [
+      mutate,
+      mutateAsync,
+      reset,
+      state.data,
+      state.error,
+      state.pendingCount,
+      state.status,
+      state.variables
+    ]
+  );
+}
+__name(useMutation, "useMutation");
+function unwrapMutationResult(result, apiRoute) {
+  if (!apiRoute) return result;
+  const apiResult = result;
+  if (apiResult.error) {
+    throw apiResult.error;
+  }
+  return apiResult.data;
+}
+__name(unwrapMutationResult, "unwrapMutationResult");
+function normalizeMutationError(error) {
+  if (error instanceof Error) return error;
+  const normalized = new Error(typeof error === "string" ? error : "Mutation failed");
+  normalized.cause = error;
+  return normalized;
+}
+__name(normalizeMutationError, "normalizeMutationError");
+
+// 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] = {
@@ -1876,25 +2679,25 @@ __name(prefetchServerQuery, "prefetchServerQuery");
 function useServerQuery(query, input, options = {}) {
   const cache = getFarmClientDataCache();
   const key = createServerQueryCallKey(query, input);
-  const inputRef = (0, import_react.useRef)(input);
-  const optionsRef = (0, import_react.useRef)(options);
-  const mountedKeyRef = (0, import_react.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_react.useCallback)(
+  const subscribe = (0, import_react3.useCallback)(
     (listener) => cache.subscribe(key, listener),
     [cache, key]
   );
-  const getSnapshot = (0, import_react.useCallback)(() => cache.get(key), [cache, key]);
-  const entry = (0, import_react.useSyncExternalStore)(subscribe, getSnapshot, () => void 0);
-  const run = (0, import_react.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_react.useEffect)(() => {
+  (0, import_react3.useEffect)(() => {
     if (options.enabled === false) return;
     const firstReadForKey = mountedKeyRef.current !== key;
     if (firstReadForKey) mountedKeyRef.current = key;
@@ -1902,7 +2705,7 @@ function useServerQuery(query, input, options = {}) {
       void run().catch(() => void 0);
     }
   }, [cache, entry, key, options.enabled, run]);
-  (0, import_react.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);
@@ -2215,7 +3018,7 @@ var api = {
 var endpoint = api;
 
 // src/store.ts
-var import_react2 = require("react");
+var import_react4 = require("react");
 var RESERVED_STORE_KEYS = /* @__PURE__ */ new Set([
   "use",
   "get",
@@ -2347,20 +3150,20 @@ function createStore(initialState, extend) {
         }
         return lastSlice;
       }, "getSnapshot");
-      return (0, import_react2.useSyncExternalStore)(
+      return (0, import_react4.useSyncExternalStore)(
         (notify) => addSubscription(keys, () => notify()),
         getSnapshot,
         getSnapshot
       );
     }
     if (typeof keyOrKeys === "string") {
-      return (0, import_react2.useSyncExternalStore)(
+      return (0, import_react4.useSyncExternalStore)(
         (notify) => addSubscription([keyOrKeys], () => notify()),
         () => state[keyOrKeys],
         () => state[keyOrKeys]
       );
     }
-    return (0, import_react2.useSyncExternalStore)(
+    return (0, import_react4.useSyncExternalStore)(
       (notify) => addSubscription(null, () => notify()),
       () => state,
       () => state
@@ -2412,7 +3215,7 @@ function createStore(initialState, extend) {
 __name(createStore, "createStore");
 
 // src/client/link.tsx
-var import_react3 = require("react");
+var import_react5 = require("react");
 
 // src/router.ts
 function createFarmRouter(routes) {
@@ -2812,9 +3615,9 @@ function LinkInner({
   onTouchStart,
   ...props
 }, ref) {
-  const elementRef = (0, import_react3.useRef)(null);
-  const intentTimeoutRef = (0, import_react3.useRef)(null);
-  const hasPrefetched = (0, import_react3.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,
@@ -2823,17 +3626,17 @@ function LinkInner({
   });
   const resolvedHref = localizeActiveFarmHref(baseHref, locale);
   const isExternal = isExternalUrl(resolvedHref);
-  const doPrefetch = (0, import_react3.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_react3.useEffect)(() => {
+  (0, import_react5.useEffect)(() => {
     hasPrefetched.current = false;
   }, [resolvedHref]);
-  (0, import_react3.useEffect)(() => {
+  (0, import_react5.useEffect)(() => {
     const element = elementRef.current;
     if (!element || isExternal) return;
     const router = getRouter();
@@ -2843,7 +3646,7 @@ function LinkInner({
       return () => router.unobserveForPrefetch(element);
     }
   }, [resolvedHref, viewport, isExternal]);
-  (0, import_react3.useEffect)(() => {
+  (0, import_react5.useEffect)(() => {
     if (!render || isExternal) return;
     let cancelled = false;
     let timeoutId = null;
@@ -2865,7 +3668,7 @@ function LinkInner({
       }
     };
   }, [render, isExternal, resolvedHref]);
-  (0, import_react3.useEffect)(() => {
+  (0, import_react5.useEffect)(() => {
     return () => {
       if (intentTimeoutRef.current) {
         clearTimeout(intentTimeoutRef.current);
@@ -2873,13 +3676,13 @@ function LinkInner({
       }
     };
   }, []);
-  const cancelIntent = (0, import_react3.useCallback)(() => {
+  const cancelIntent = (0, import_react5.useCallback)(() => {
     if (intentTimeoutRef.current) {
       clearTimeout(intentTimeoutRef.current);
       intentTimeoutRef.current = null;
     }
   }, []);
-  const scheduleIntentPrefetch = (0, import_react3.useCallback)(() => {
+  const scheduleIntentPrefetch = (0, import_react5.useCallback)(() => {
     if (isExternal || !intent || hasPrefetched.current) return;
     cancelIntent();
     intentTimeoutRef.current = setTimeout(() => {
@@ -2887,42 +3690,42 @@ function LinkInner({
       doPrefetch();
     }, prefetchDelay);
   }, [intent, isExternal, prefetchDelay, doPrefetch, cancelIntent]);
-  const handleMouseEnter = (0, import_react3.useCallback)(
+  const handleMouseEnter = (0, import_react5.useCallback)(
     (event) => {
       onMouseEnter?.(event);
       scheduleIntentPrefetch();
     },
     [onMouseEnter, scheduleIntentPrefetch]
   );
-  const handleMouseLeave = (0, import_react3.useCallback)(
+  const handleMouseLeave = (0, import_react5.useCallback)(
     (event) => {
       onMouseLeave?.(event);
       cancelIntent();
     },
     [onMouseLeave, cancelIntent]
   );
-  const handleTouchStart = (0, import_react3.useCallback)(
+  const handleTouchStart = (0, import_react5.useCallback)(
     (event) => {
       onTouchStart?.(event);
       scheduleIntentPrefetch();
     },
     [onTouchStart, scheduleIntentPrefetch]
   );
-  const handleFocus = (0, import_react3.useCallback)(
+  const handleFocus = (0, import_react5.useCallback)(
     (event) => {
       onFocus?.(event);
       scheduleIntentPrefetch();
     },
     [onFocus, scheduleIntentPrefetch]
   );
-  const handleBlur = (0, import_react3.useCallback)(
+  const handleBlur = (0, import_react5.useCallback)(
     (event) => {
       onBlur?.(event);
       cancelIntent();
     },
     [onBlur, cancelIntent]
   );
-  const handleClick = (0, import_react3.useCallback)(
+  const handleClick = (0, import_react5.useCallback)(
     (event) => {
       onClick?.(event);
       if (event.defaultPrevented) return;
@@ -2947,7 +3750,7 @@ function LinkInner({
     },
     [resolvedHref, replace, scroll, viewTransition, target, isExternal, onClick]
   );
-  const setRefs = (0, import_react3.useCallback)(
+  const setRefs = (0, import_react5.useCallback)(
     (node) => {
       elementRef.current = node;
       if (typeof ref === "function") ref(node);
@@ -2976,7 +3779,7 @@ function LinkInner({
   );
 }
 __name(LinkInner, "LinkInner");
-var LinkWithRef = (0, import_react3.forwardRef)(LinkInner);
+var LinkWithRef = (0, import_react5.forwardRef)(LinkInner);
 LinkWithRef.displayName = "Link";
 var Link = LinkWithRef;
 function resolveLinkHref(href, params, options) {
@@ -3077,7 +3880,7 @@ function matchManifestRoute(pathname, route2) {
 __name(matchManifestRoute, "matchManifestRoute");
 
 // src/client/router.ts
-var import_react4 = require("react");
+var import_react6 = require("react");
 
 // src/deferred.ts
 var FARM_DEFERRED_CONTENT_TYPE = "application/x-farm-deferred+json";
@@ -3296,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,
@@ -3366,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) {
@@ -3384,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;
@@ -3426,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 {
@@ -3505,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 {
@@ -3560,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)) {
@@ -3586,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()
     });
@@ -3617,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);
       }
@@ -3648,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;
   }
   /**
@@ -3805,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,
@@ -3833,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_react4.useMemo)(
+  const routeMatcher = (0, import_react6.useMemo)(
     () => routeKey ? createFarmRouter(routeKey.split("\n")) : null,
     [routeKey]
   );
-  const [state, setState] = (0, import_react4.useState)(() => {
+  const [state, setState] = (0, import_react6.useState)(() => {
     return readRouterState(basePath, routeMatcher);
   });
-  (0, import_react4.useEffect)(() => {
+  (0, import_react6.useEffect)(() => {
     if (typeof window === "undefined") return;
     const handlePopState = /* @__PURE__ */ __name(() => {
       setState(readRouterState(basePath, routeMatcher));
@@ -3891,8 +4719,8 @@ function useRouter(options = {}) {
 }
 __name(useRouter, "useRouter");
 function usePageState() {
-  const [state, setState] = (0, import_react4.useState)(() => readPageState());
-  (0, import_react4.useEffect)(() => {
+  const [state, setState] = (0, import_react6.useState)(() => readPageState());
+  (0, import_react6.useEffect)(() => {
     if (typeof window === "undefined") return;
     const handlePopState = /* @__PURE__ */ __name(() => {
       setState(readPageState());
@@ -3905,10 +4733,10 @@ function usePageState() {
 }
 __name(usePageState, "usePageState");
 function useNavigation() {
-  const [state, setState] = (0, import_react4.useState)(
+  const [state, setState] = (0, import_react6.useState)(
     () => getRouter2().getNavigationState()
   );
-  (0, import_react4.useEffect)(() => {
+  (0, import_react6.useEffect)(() => {
     if (typeof window === "undefined") return;
     return getRouter2().subscribeNavigation(setState);
   }, []);
@@ -3916,10 +4744,10 @@ function useNavigation() {
 }
 __name(useNavigation, "useNavigation");
 function useBlocker(options) {
-  const optionsRef = (0, import_react4.useRef)(options);
+  const optionsRef = (0, import_react6.useRef)(options);
   optionsRef.current = options;
   const active = Boolean(options.when);
-  (0, import_react4.useEffect)(() => {
+  (0, import_react6.useEffect)(() => {
     if (typeof window === "undefined" || !active) {
       return;
     }
@@ -3940,8 +4768,8 @@ function useBlocker(options) {
 }
 __name(useBlocker, "useBlocker");
 function useScrollRestoration(key) {
-  const ref = (0, import_react4.useRef)(null);
-  (0, import_react4.useEffect)(() => {
+  const ref = (0, import_react6.useRef)(null);
+  (0, import_react6.useEffect)(() => {
     const element = ref.current;
     if (!element) return;
     return getRouter2().registerScrollElement(key, element);
@@ -4530,6 +5358,7 @@ function isObject(value) {
 __name(isObject, "isObject");
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  APIClientError,
   FarmClientPluginManager,
   IntegrationClientError,
   Link,
@@ -4562,6 +5391,8 @@ __name(isObject, "isObject");
   readPageState,
   replaceState,
   useBlocker,
+  useFetcher,
+  useMutation,
   useNavigation,
   usePageState,
   useRouter,