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

package/dist/server.cjs

@@ -118,7 +118,7 @@ function createFarmMarkdownRouteModule(input) {
         ...props,
         components: {
           ...components,
-          ...props?.components || {}
+          ...props?.components
         }
       })
     );
@@ -635,7 +635,11 @@ async function prepareFarmWorkflowsForNitro(config) {
     };
   }
   const handlerPath = path23.join(generatedDir, "http-handler.mjs");
-  await fs9.writeFile(handlerPath, createNitroWorkflowHTTPHandler(workflowConfig, workflows), "utf8");
+  await fs9.writeFile(
+    handlerPath,
+    createNitroWorkflowHTTPHandler(workflowConfig, workflows),
+    "utf8"
+  );
   const manifestPath = path23.join(generatedDir, "manifest.json");
   await fs9.writeFile(
     manifestPath,
@@ -709,13 +713,7 @@ function normalizeSchedule(schedule) {
   return (Array.isArray(schedule) ? schedule : [schedule]).map((value) => value.trim()).filter(Boolean);
 }
 function resolveWorkflowDefinition(module2) {
-  const candidates = [
-    module2.default,
-    module2.workflow,
-    module2.cron,
-    module2.task,
-    module2.job
-  ];
+  const candidates = [module2.default, module2.workflow, module2.cron, module2.task, module2.job];
   for (const candidate of candidates) {
     if (candidate && typeof candidate === "object" && typeof candidate.run === "function") {
       return candidate;
@@ -1708,8 +1706,8 @@ function compareFarmRouteRuleSpecificity(left, right) {
 }
 function getFarmRouteRuleSpecificity(pattern) {
   return normalizeRoutePattern(pattern).split("/").filter(Boolean).reduce((score, segment) => {
-    if (segment === "**" || /^\[\[\.\.\./.test(segment)) return score + 1;
-    if (segment === "*" || /^\[\.\.\./.test(segment)) return score + 10;
+    if (segment === "**" || segment.startsWith("[[...")) return score + 1;
+    if (segment === "*" || segment.startsWith("[...")) return score + 10;
     if (/^\[.+\]$/.test(segment) || /^:.+$/.test(segment)) return score + 50;
     return score + 100;
   }, 0);
@@ -1770,7 +1768,7 @@ function routeRulesToHeaders(routeRules) {
   for (const [source, rule] of Object.entries(routeRules)) {
     const headers = {
       ...normalizeCorsHeaders(rule.cors),
-      ...rule.headers || {}
+      ...rule.headers
     };
     const entries = Object.entries(headers);
     if (entries.length === 0) continue;
@@ -1821,7 +1819,8 @@ var init_route_rules = __esm({
 // src/cache-invalidation.ts
 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()
   });
 }
 function notifyFarmCacheInvalidation(key) {
@@ -1830,6 +1829,11 @@ function notifyFarmCacheInvalidation(key) {
     listener(key);
   }
 }
+function notifyFarmCacheTask(task) {
+  for (const listener of getFarmCacheInvalidationState().taskListeners) {
+    listener(task);
+  }
+}
 function applyFarmCacheInvalidations(keys) {
   if (!Array.isArray(keys)) return;
   for (const key of keys) {
@@ -1838,21 +1842,49 @@ function applyFarmCacheInvalidations(keys) {
     }
   }
 }
+function encodeFarmCacheInvalidations(keys) {
+  const normalized = Array.from(
+    new Set(keys.filter((key) => typeof key === "string" && key.length > 0))
+  );
+  if (normalized.length === 0) return null;
+  return encodeURIComponent(JSON.stringify(normalized));
+}
+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 [];
+  }
+}
 function subscribeFarmCacheInvalidation(listener) {
   const state = getFarmCacheInvalidationState();
   state.listeners.add(listener);
   return () => state.listeners.delete(listener);
 }
-var FARM_CACHE_INVALIDATION_STATE, globalState;
+function subscribeFarmCacheTask(listener) {
+  const state = getFarmCacheInvalidationState();
+  state.taskListeners.add(listener);
+  return () => state.taskListeners.delete(listener);
+}
+var FARM_CACHE_INVALIDATION_HEADER, FARM_CACHE_INVALIDATION_STATE, globalState;
 var init_cache_invalidation = __esm({
   "src/cache-invalidation.ts"() {
     "use strict";
+    FARM_CACHE_INVALIDATION_HEADER = "x-farm-cache-invalidations";
     FARM_CACHE_INVALIDATION_STATE = /* @__PURE__ */ Symbol.for("farm.cacheInvalidationState");
     globalState = globalThis;
     __name(getFarmCacheInvalidationState, "getFarmCacheInvalidationState");
     __name(notifyFarmCacheInvalidation, "notifyFarmCacheInvalidation");
+    __name(notifyFarmCacheTask, "notifyFarmCacheTask");
     __name(applyFarmCacheInvalidations, "applyFarmCacheInvalidations");
+    __name(encodeFarmCacheInvalidations, "encodeFarmCacheInvalidations");
+    __name(decodeFarmCacheInvalidations, "decodeFarmCacheInvalidations");
     __name(subscribeFarmCacheInvalidation, "subscribeFarmCacheInvalidation");
+    __name(subscribeFarmCacheTask, "subscribeFarmCacheTask");
   }
 });
 
@@ -1948,16 +1980,24 @@ function sanitizeServerActionError(_error) {
     message: "Server function failed"
   };
 }
-function runWithServerActionRequest(request, callback) {
+async function runWithServerActionRequest(request, callback) {
   throwIfAborted(request.signal);
-  return getServerActionStorage().run(
-    {
-      request,
-      signal: request.signal,
-      invalidations: /* @__PURE__ */ new Set()
-    },
-    callback
-  );
+  const context = {
+    request,
+    signal: request.signal,
+    invalidations: /* @__PURE__ */ new Set(),
+    cacheTasks: /* @__PURE__ */ new Set()
+  };
+  return getServerActionStorage().run(context, async () => {
+    try {
+      const result = await callback();
+      await Promise.all(context.cacheTasks);
+      return result;
+    } catch (error) {
+      await Promise.allSettled(context.cacheTasks);
+      throw error;
+    }
+  });
 }
 function getServerActionExecutionContext() {
   return getServerActionStorage().getStore();
@@ -2268,6 +2308,9 @@ var init_server_action_security = __esm({
     subscribeFarmCacheInvalidation((key) => {
       getServerActionExecutionContext()?.invalidations.add(key);
     });
+    subscribeFarmCacheTask((task) => {
+      getServerActionExecutionContext()?.cacheTasks.add(task);
+    });
     __name(getServerActionStorage, "getServerActionStorage");
     __name(getFallbackAbortController, "getFallbackAbortController");
     __name(parseBodySizeLimit, "parseBodySizeLimit");
@@ -5898,7 +5941,9 @@ function readManifest(contentDir) {
   const manifestPath = import_node_path7.default.join(contentDir, FARM_DOCS_LAST_MODIFIED_MANIFEST);
   if (!(0, import_node_fs5.existsSync)(manifestPath)) return null;
   try {
-    const parsed = JSON.parse((0, import_node_fs5.readFileSync)(manifestPath, "utf8"));
+    const parsed = JSON.parse(
+      (0, import_node_fs5.readFileSync)(manifestPath, "utf8")
+    );
     if (parsed.version !== 1 || !parsed.pages || typeof parsed.pages !== "object") return null;
     const pages = Object.fromEntries(
       Object.entries(parsed.pages).filter(
@@ -9446,6 +9491,7 @@ async function resolveConfig(userConfig, mode) {
     observability: userConfig.observability ?? false,
     devtools: resolveFarmDevtoolsConfig(userConfig.devtools, mode),
     storage: userConfig.storage || {},
+    cache: userConfig.cache || {},
     suppressLintOnLink: userConfig.suppressLintOnLink ?? false,
     experimental: {
       serverComponents: false,
@@ -12417,16 +12463,7 @@ __export(devtools_client_exports, {
 function parseShortcut(shortcut) {
   const tokens = shortcut.toLowerCase().split("+").map((token) => token.trim()).filter(Boolean);
   const key = tokens.find(
-    (token) => ![
-      "alt",
-      "ctrl",
-      "control",
-      "meta",
-      "cmd",
-      "command",
-      "mod",
-      "shift"
-    ].includes(token)
+    (token) => !["alt", "ctrl", "control", "meta", "cmd", "command", "mod", "shift"].includes(token)
   );
   if (!key) {
     return null;
@@ -12709,6 +12746,7 @@ var init_image_sharp = __esm({
 // src/server.ts
 var server_exports = {};
 __export(server_exports, {
+  DEFAULT_FARM_DEV_SERVER_PORT: () => DEFAULT_FARM_DEV_SERVER_PORT,
   DEFAULT_SERVER_ACTION_BODY_SIZE_LIMIT: () => DEFAULT_SERVER_ACTION_BODY_SIZE_LIMIT,
   FARM_SERVER_QUERY_SYMBOL: () => FARM_SERVER_QUERY_SYMBOL,
   FarmApp: () => FarmApp,
@@ -12721,7 +12759,9 @@ __export(server_exports, {
   _runWithAfterRequest: () => _runWithAfterRequest,
   _withAfterNodeMiddleware: () => _withAfterNodeMiddleware,
   after: () => after,
+  applyFarmCacheInvalidationTargets: () => applyFarmCacheInvalidationTargets,
   applyFarmCacheInvalidations: () => applyFarmCacheInvalidations,
+  configureFarmCache: () => configureFarmCache,
   createClientOnlyFn: () => createClientOnlyFn,
   createFarmApp: () => createFarmApp,
   createFarmCacheKey: () => createFarmCacheKey,
@@ -12736,6 +12776,7 @@ __export(server_exports, {
   createServerQuery: () => createServerQuery,
   createStorageClient: () => createStorageClient,
   databaseStorage: () => databaseStorage,
+  defineCacheKey: () => defineCacheKey,
   defineConfig: () => defineConfig2,
   defineStorageClient: () => defineStorageClient,
   disposeStorage: () => disposeStorage,
@@ -12786,6 +12827,7 @@ __export(server_exports, {
   segmentsToPattern: () => segmentsToPattern,
   sqliteStorage: () => sqliteStorage,
   startDevServer: () => startDevServer,
+  storageCacheAdapter: () => storageCacheAdapter,
   toViteModuleId: () => toViteModuleId,
   unstable_cache: () => unstable_cache,
   updateTag: () => updateTag,
@@ -13472,12 +13514,109 @@ __name(getActiveFarmI18nSnapshot, "getActiveFarmI18nSnapshot");
 
 // src/cache.ts
 init_cache_invalidation();
+function defineCacheKey() {
+  return (factory) => {
+    if (typeof factory !== "function") {
+      throw new TypeError("defineCacheKey expects a key factory function.");
+    }
+    return ((...args) => {
+      const key = factory(...args);
+      if (typeof key !== "string" && !Array.isArray(key)) {
+        throw new TypeError(
+          "A defined cache key factory must return a string or structured array."
+        );
+      }
+      return key;
+    });
+  };
+}
+__name(defineCacheKey, "defineCacheKey");
+function storageCacheAdapter(storage, options = {}) {
+  if (!storage || typeof storage.getItem !== "function" || typeof storage.setItem !== "function") {
+    throw new TypeError("storageCacheAdapter expects a compatible storage client.");
+  }
+  const base = normalizeCacheNamespace(options.base || "farm-cache");
+  const entryKey = /* @__PURE__ */ __name((key) => `${base}:entry:${key}`, "entryKey");
+  const tagKey = /* @__PURE__ */ __name((tag) => `${base}:tag:${tag}`, "tagKey");
+  return {
+    name: "storage",
+    get: /* @__PURE__ */ __name((key) => storage.getItem(entryKey(key)), "get"),
+    set: /* @__PURE__ */ __name(async (key, entry) => {
+      await storage.setItem(entryKey(key), entry);
+    }, "set"),
+    delete: /* @__PURE__ */ __name(async (key) => {
+      await storage.removeItem(entryKey(key));
+    }, "delete"),
+    clear: storage.clear ? async () => {
+      await storage.clear(base);
+    } : void 0,
+    getTagVersions: /* @__PURE__ */ __name(async (tags) => {
+      const versions = await Promise.all(
+        tags.map(async (tag) => {
+          const value = await storage.getItem(tagKey(tag));
+          return [tag, normalizeAdapterVersion(value)];
+        })
+      );
+      return Object.fromEntries(versions);
+    }, "getTagVersions"),
+    invalidateTags: /* @__PURE__ */ __name(async (tags) => {
+      await Promise.all(
+        tags.map(async (tag) => {
+          const key = tagKey(tag);
+          const current = normalizeAdapterVersion(await storage.getItem(key));
+          await storage.setItem(key, Math.max(Date.now(), current + 1));
+        })
+      );
+    }, "invalidateTags")
+  };
+}
+__name(storageCacheAdapter, "storageCacheAdapter");
 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;
@@ -13513,6 +13652,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 ?? []) {
@@ -13525,6 +13703,7 @@ var _FarmDataCache = class _FarmDataCache {
       key,
       value,
       tags,
+      tagVersions: void 0,
       createdAt: options.createdAt ?? Date.now(),
       createdVersion: ++this.version,
       revalidate: normalizeRevalidate(options.revalidate)
@@ -13538,11 +13717,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();
@@ -13551,6 +13764,10 @@ var _FarmDataCache = class _FarmDataCache {
     this.version = 0;
     emitFarmEvent({ type: "cache.clear", count });
   }
+  async clearAsync() {
+    this.clear();
+    await this.adapter?.clear?.();
+  }
   isStale(entry, now = Date.now()) {
     if (typeof entry.revalidate === "number" && entry.revalidate > 0 && now - entry.createdAt >= entry.revalidate * 1e3) {
       return true;
@@ -13563,6 +13780,12 @@ var _FarmDataCache = class _FarmDataCache {
     }
     return false;
   }
+  async isStaleAsync(entry, now = Date.now()) {
+    if (this.adapter) {
+      return this.isAdapterEntryStale(entry, now);
+    }
+    return this.isStale(entry, now);
+  }
   revalidateTag(tag, options = {}) {
     const normalized = normalizeCacheTag(tag);
     const count = this.invalidateTag(normalized);
@@ -13571,6 +13794,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);
@@ -13587,8 +13819,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;
     }
@@ -13597,10 +13846,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(() => {
@@ -13609,6 +13856,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()) {
@@ -13636,11 +13917,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, now = Date.now()) {
+    if (typeof entry.revalidate === "number" && entry.revalidate > 0 && now - 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;
@@ -13653,6 +13976,10 @@ function getFarmDataCache() {
   return sharedFarmDataCache;
 }
 __name(getFarmDataCache, "getFarmDataCache");
+function configureFarmCache(config) {
+  sharedFarmDataCache.configure(config);
+}
+__name(configureFarmCache, "configureFarmCache");
 function unstable_cache(fn, keyParts = [], options = {}) {
   return async (...args) => {
     const locale = getActiveFarmI18nSnapshot()?.locale;
@@ -13668,30 +13995,71 @@ function unstable_cache(fn, keyParts = [], options = {}) {
 }
 __name(unstable_cache, "unstable_cache");
 function revalidateTag(_tag, _profile) {
-  getFarmDataCache().revalidateTag(_tag, {
+  const cache = getFarmDataCache();
+  if (cache.hasAdapter) {
+    const task = cache.revalidateTagAsync(_tag, {
+      source: "revalidateTag",
+      profile: _profile
+    }).then(() => void 0);
+    notifyFarmCacheTask(task);
+    return task;
+  }
+  cache.revalidateTag(_tag, {
     source: "revalidateTag",
     profile: _profile
   });
 }
 __name(revalidateTag, "revalidateTag");
 function updateTag(tag) {
-  getFarmDataCache().revalidateTag(tag, { source: "updateTag" });
+  const cache = getFarmDataCache();
+  if (cache.hasAdapter) {
+    const task = cache.revalidateTagAsync(tag, { source: "updateTag" }).then(() => void 0);
+    notifyFarmCacheTask(task);
+    return task;
+  }
+  cache.revalidateTag(tag, { source: "updateTag" });
 }
 __name(updateTag, "updateTag");
 function revalidatePath(routePath) {
-  getFarmDataCache().revalidatePath(routePath);
+  const cache = getFarmDataCache();
+  if (cache.hasAdapter) {
+    const task = cache.revalidatePathAsync(routePath).then(() => void 0);
+    notifyFarmCacheTask(task);
+    return task;
+  }
+  cache.revalidatePath(routePath);
 }
 __name(revalidatePath, "revalidatePath");
 function invalidate(key) {
   const clientKey = createRouteDataCacheKey(key);
-  getFarmDataCache().revalidateTag(createRouteDataCacheTag(key), { source: "updateTag" });
+  const task = updateTag(createRouteDataCacheTag(key));
   notifyFarmCacheInvalidation(clientKey);
+  return task;
 }
 __name(invalidate, "invalidate");
 function invalidateRouteData(key) {
-  invalidate(key);
+  return invalidate(key);
 }
 __name(invalidateRouteData, "invalidateRouteData");
+async function applyFarmCacheInvalidationTargets(targets) {
+  if (!Array.isArray(targets)) {
+    throw new TypeError("Cache invalidations must resolve to an array of targets.");
+  }
+  const clientKeys = [];
+  for (const target of targets) {
+    assertFarmCacheInvalidationTarget(target);
+    if ("key" in target) {
+      await invalidate(target.key);
+      clientKeys.push(createRouteDataCacheKey(target.key));
+    } else if ("path" in target) {
+      await revalidatePath(target.path);
+    } else {
+      await updateTag(target.tag);
+    }
+  }
+  return Array.from(new Set(clientKeys));
+}
+__name(applyFarmCacheInvalidationTargets, "applyFarmCacheInvalidationTargets");
 function createPathCacheTag(routePath) {
   return `path:${normalizeRevalidatePath(routePath)}`;
 }
@@ -13752,6 +14120,67 @@ 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((resolve5) => setTimeout(resolve5, 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 assertFarmCacheInvalidationTarget(target) {
+  if (!target || typeof target !== "object") {
+    throw new TypeError("Cache invalidation targets must be { key }, { path }, or { tag }.");
+  }
+  if ("key" in target) {
+    const key = target.key;
+    if (typeof key === "string" || Array.isArray(key)) return;
+  } else if ("path" in target && typeof target.path === "string") {
+    return;
+  } else if ("tag" in target && typeof target.tag === "string") {
+    return;
+  }
+  throw new TypeError("Cache invalidation targets must contain a string/array key, path, or tag.");
+}
+__name(assertFarmCacheInvalidationTarget, "assertFarmCacheInvalidationTarget");
 function getFunctionCacheIdentity(fn) {
   if (fn.name) {
     return `name:${fn.name}`;
@@ -14892,6 +15321,76 @@ function normalizePathname(pathname) {
 }
 __name(normalizePathname, "normalizePathname");
 
+// src/routing/route-slots.ts
+var SLOT_SEGMENT = /^@([A-Za-z][A-Za-z0-9_-]*)$/;
+function parseRouteSlotFile(filePath) {
+  const normalized = filePath.replace(/\\/g, "/");
+  const parts = normalized.split("/").filter(Boolean);
+  const fileName = parts.at(-1) ?? "";
+  const baseName = fileName.replace(/\.(tsx?|jsx?)$/, "");
+  if (baseName !== "page" && baseName !== "default") return null;
+  const slotIndex = parts.findIndex((part) => SLOT_SEGMENT.test(part));
+  if (slotIndex < 0) return null;
+  if (parts.slice(slotIndex + 1, -1).some((part) => SLOT_SEGMENT.test(part))) {
+    throw new Error(`Nested route slots are not supported in "${filePath}"`);
+  }
+  const slotMatch = parts[slotIndex].match(SLOT_SEGMENT);
+  const name = slotMatch?.[1];
+  if (!name) return null;
+  const ownerParts = parts.slice(0, slotIndex);
+  const contentParts = parts.slice(slotIndex + 1, -1);
+  const marker = parseInterceptionMarker(contentParts[0]);
+  let targetBase = ownerParts;
+  let targetParts = contentParts;
+  if (marker) {
+    targetBase = marker.root === true ? [] : ownerParts.slice(0, Math.max(0, ownerParts.length - marker.up));
+    targetParts = [...marker.remainder ? [marker.remainder] : [], ...contentParts.slice(1)];
+  }
+  const ownerFile = [...ownerParts, "layout.tsx"].join("/");
+  const routeFile = [
+    ...baseName === "default" ? ownerParts : targetBase,
+    ...baseName === "default" ? [] : targetParts,
+    "page.tsx"
+  ].join("/");
+  return {
+    name,
+    ownerRoute: parseRoutePath(ownerFile || "layout.tsx"),
+    route: parseRoutePath(routeFile || "page.tsx"),
+    interception: marker !== null,
+    fallback: baseName === "default"
+  };
+}
+__name(parseRouteSlotFile, "parseRouteSlotFile");
+function createRouteSlotContainerId(name, ownerPattern) {
+  const owner = ownerPattern === "/" ? "root" : ownerPattern.replace(/^\//, "").replace(/[^A-Za-z0-9_-]+/g, "-").replace(/^-+|-+$/g, "");
+  return `__farm_slot_${name}_${owner || "root"}__`;
+}
+__name(createRouteSlotContainerId, "createRouteSlotContainerId");
+function parseInterceptionMarker(segment) {
+  if (!segment) return null;
+  if (segment.startsWith("(...)")) {
+    return {
+      up: 0,
+      root: true,
+      remainder: segment.slice(5)
+    };
+  }
+  if (segment.startsWith("(.)")) {
+    return {
+      up: 0,
+      remainder: segment.slice(3)
+    };
+  }
+  let remainder = segment;
+  let up = 0;
+  while (remainder.startsWith("(..)")) {
+    up += 1;
+    remainder = remainder.slice(4);
+  }
+  return up > 0 ? { up, remainder } : null;
+}
+__name(parseInterceptionMarker, "parseInterceptionMarker");
+
 // src/routing/route-manager.ts
 function routeSpecificity(entry) {
   return entry.route.segments.reduce((score, segment) => {
@@ -14905,6 +15404,7 @@ var _RouteManager = class _RouteManager {
   constructor(config, viteServer) {
     this.routes = /* @__PURE__ */ new Map();
     this.layouts = /* @__PURE__ */ new Map();
+    this.routeSlots = /* @__PURE__ */ new Map();
     this.loadings = /* @__PURE__ */ new Map();
     this.errors = /* @__PURE__ */ new Map();
     this.metadataImages = /* @__PURE__ */ new Map();
@@ -14920,6 +15420,7 @@ var _RouteManager = class _RouteManager {
   async discoverRoutes() {
     this.routes.clear();
     this.layouts.clear();
+    this.routeSlots.clear();
     this.loadings.clear();
     this.errors.clear();
     this.metadataImages.clear();
@@ -14930,6 +15431,13 @@ var _RouteManager = class _RouteManager {
       await this.discoverFileRoutes(source);
       await this.discoverProgrammaticRoutes(source);
     }
+    for (const slot of this.routeSlots.values()) {
+      if (slot.interception && !this.routes.has(slot.pattern)) {
+        throw new Error(
+          `Intercepting route slot "${slot.name}" targets "${slot.pattern}", but no canonical page exists for that URL`
+        );
+      }
+    }
     this.routes = new Map(
       Array.from(this.routes.entries()).sort(
         ([, left], [, right]) => routeSpecificity(right) - routeSpecificity(left)
@@ -14945,7 +15453,7 @@ var _RouteManager = class _RouteManager {
   /**
    * Find matching route for a given URL path
    */
-  matchRoute(pathname) {
+  matchRoute(pathname, options = {}) {
     const routePathname = this.toRoutePathname(pathname);
     const normalizedPath = routePathname === "/" ? "/" : routePathname.replace(/\/$/, "");
     let matchedRoute = null;
@@ -14959,10 +15467,12 @@ var _RouteManager = class _RouteManager {
       }
     }
     const layouts = this.findMatchingLayouts(normalizedPath);
+    const slots = this.findMatchingRouteSlots(normalizedPath, options.interceptFrom);
     return {
       route: matchedRoute,
       params,
-      layouts
+      layouts,
+      slots
     };
   }
   /**
@@ -14977,6 +15487,9 @@ var _RouteManager = class _RouteManager {
   getLayouts() {
     return new Map(this.layouts);
   }
+  getRouteSlots() {
+    return new Map(this.routeSlots);
+  }
   /** Resolve route rules, inherited layouts, and the page export in precedence order. */
   async resolveRouteRuntimeConfig(pattern) {
     const routeEntry = this.routes.get(pattern);
@@ -15135,7 +15648,22 @@ var _RouteManager = class _RouteManager {
       pattern: entry.pattern,
       modulePath: toUrlPath(entry.modulePath)
     }));
-    return { routes, layouts };
+    const slots = Array.from(this.routeSlots.values()).map((entry) => {
+      const metadata = getClientModuleMetadata(entry.modulePath, projectRoot);
+      return {
+        name: entry.name,
+        ownerPattern: entry.ownerPattern,
+        pattern: entry.pattern,
+        modulePath: toUrlPath(entry.modulePath),
+        containerId: entry.containerId,
+        interception: entry.interception,
+        fallback: entry.fallback,
+        shouldHydrate: metadata.shouldHydrate,
+        isClientComponent: metadata.isClientComponent,
+        segments: entry.route.segments
+      };
+    });
+    return { routes, layouts, slots };
   }
   /**
    * Load a route module dynamically
@@ -15212,6 +15740,7 @@ var _RouteManager = class _RouteManager {
   async discoverFileRoutes(source) {
     const appDir = resolveAppPath(source.root, source.srcDir, "app");
     const pageFiles = await safeGlobFiles("**/page.{ts,tsx,js,jsx,md,mdx}", appDir);
+    const slotDefaultFiles = await safeGlobFiles("**/@*/**/default.{ts,tsx,js,jsx}", appDir);
     const layoutFiles = await safeGlobFiles("**/layout.{ts,tsx,js,jsx}", appDir);
     const loadingFiles = await safeGlobFiles("**/loading.{ts,tsx,js,jsx}", appDir);
     const errorFiles = await safeGlobFiles("**/error.{ts,tsx,js,jsx}", appDir);
@@ -15220,7 +15749,7 @@ var _RouteManager = class _RouteManager {
       appDir
     );
     for (const [kind, files, target] of [
-      ["page", pageFiles, this.routes],
+      ["page", pageFiles.filter((file) => parseRouteSlotFile(file) === null), this.routes],
       ["layout", layoutFiles, this.layouts],
       ["loading", loadingFiles, this.loadings],
       ["error", errorFiles, this.errors]
@@ -15244,6 +15773,32 @@ var _RouteManager = class _RouteManager {
         });
       }
     }
+    for (const file of [...pageFiles, ...slotDefaultFiles]) {
+      const slot = parseRouteSlotFile(file);
+      if (!slot) continue;
+      const modulePath = import_path5.default.join(appDir, file);
+      const pattern = this.createRoutePattern(slot.route);
+      const ownerPattern = this.createRoutePattern(slot.ownerRoute);
+      const key = `${ownerPattern}:${slot.name}:${slot.interception ? "intercept" : "slot"}:${slot.fallback ? "default" : pattern}`;
+      const existing = this.routeSlots.get(key);
+      if (existing?.sourceRoot === source.root) {
+        throw new Error(
+          `Duplicate route slot "${slot.name}" for "${pattern}". Found both ${existing.modulePath} and ${modulePath}.`
+        );
+      }
+      this.routeSlots.set(key, {
+        route: slot.route,
+        modulePath,
+        pattern,
+        source: "file",
+        sourceRoot: source.root,
+        name: slot.name,
+        ownerPattern,
+        interception: slot.interception,
+        fallback: slot.fallback,
+        containerId: createRouteSlotContainerId(slot.name, ownerPattern)
+      });
+    }
     for (const file of metadataImageFiles) {
       const fileBase = import_path5.default.basename(file, import_path5.default.extname(file));
       const kind = fileBase === "twitter-image" ? "twitter" : "opengraph";
@@ -15369,6 +15924,71 @@ var _RouteManager = class _RouteManager {
     }
     return matchingLayouts;
   }
+  findMatchingRouteSlots(pathname, interceptFrom) {
+    const groups = /* @__PURE__ */ new Map();
+    for (const entry of this.routeSlots.values()) {
+      if (!this.matchesRoutePrefix(pathname, entry.ownerPattern)) continue;
+      const key = `${entry.ownerPattern}:${entry.name}`;
+      const entries = groups.get(key) ?? [];
+      entries.push(entry);
+      groups.set(key, entries);
+    }
+    const normalizedFrom = interceptFrom ? this.toRoutePathname(new URL(interceptFrom, "http://farm.local").pathname) : void 0;
+    const matches = [];
+    for (const entries of groups.values()) {
+      const candidates = entries.filter((entry) => !entry.fallback).filter(
+        (entry) => !entry.interception || normalizedFrom !== void 0 && this.matchesRoutePrefix(normalizedFrom, entry.ownerPattern)
+      ).map((entry) => ({
+        entry,
+        match: matchRoute(pathname, entry.route.segments)
+      })).filter((candidate) => candidate.match.matches).sort((left, right) => {
+        if (left.entry.interception !== right.entry.interception) {
+          return left.entry.interception ? -1 : 1;
+        }
+        return routeSpecificity(right.entry) - routeSpecificity(left.entry);
+      });
+      const selected = candidates[0];
+      if (selected) {
+        matches.push({
+          name: selected.entry.name,
+          ownerPattern: selected.entry.ownerPattern,
+          containerId: selected.entry.containerId,
+          interception: selected.entry.interception,
+          fallback: false,
+          route: selected.entry,
+          params: selected.match.params
+        });
+        continue;
+      }
+      const fallback = entries.find((entry) => entry.fallback);
+      if (fallback) {
+        matches.push({
+          name: fallback.name,
+          ownerPattern: fallback.ownerPattern,
+          containerId: fallback.containerId,
+          interception: false,
+          fallback: true,
+          route: fallback,
+          params: {}
+        });
+      }
+    }
+    return matches.sort((left, right) => {
+      const ownerDifference = left.route.route.segments.length - right.route.route.segments.length;
+      return ownerDifference || left.name.localeCompare(right.name);
+    });
+  }
+  matchesRoutePrefix(pathname, pattern) {
+    if (pattern === "/") return true;
+    const patternSegments = parseRoutePath(`${pattern}/page.tsx`).segments;
+    const pathSegments = pathname.split("/").filter(Boolean);
+    if (patternSegments.length > pathSegments.length) return false;
+    for (let index = 0; index < patternSegments.length; index++) {
+      const segment = patternSegments[index];
+      if (!segment.isDynamic && segment.segment !== pathSegments[index]) return false;
+    }
+    return true;
+  }
   findNearestBoundary(pathname, boundaries) {
     const normalizedPath = pathname === "/" ? "/" : pathname.replace(/\/$/, "");
     const pathSegments = normalizedPath.split("/").filter(Boolean);
@@ -15985,7 +16605,7 @@ function mergeMetadata(base, next) {
 __name(mergeMetadata, "mergeMetadata");
 function addMetadataImageReference(metadata, reference) {
   if (reference.kind === "opengraph") {
-    const openGraph = { ...metadata.openGraph || {} };
+    const openGraph = { ...metadata.openGraph };
     if (!hasMetadataImages(openGraph.images) && !hasMetadataImages(openGraph.image)) {
       openGraph.images = [
         {
@@ -16002,7 +16622,7 @@ function addMetadataImageReference(metadata, reference) {
       openGraph
     };
   }
-  const twitter = { ...metadata.twitter || {} };
+  const twitter = { ...metadata.twitter };
   if (!hasMetadataImages(twitter.images)) {
     twitter.images = [reference.href];
     twitter.card = twitter.card || "summary_large_image";
@@ -16608,8 +17228,8 @@ var _FarmI18nRuntime = class _FarmI18nRuntime {
       cookie: this.config.cookie,
       direction: getFarmLocaleDirection(resolution.locale, this.config.direction),
       messages: {
-        ...this.catalogs[this.config.fallbackLocale] || {},
-        ...this.catalogs[resolution.locale] || {}
+        ...this.catalogs[this.config.fallbackLocale],
+        ...this.catalogs[resolution.locale]
       }
     };
   }
@@ -16911,7 +17531,9 @@ var _ServerRenderer = class _ServerRenderer {
   async runWithRequestContext(request, fn) {
     return _runWithCurrentRequest(
       request,
-      () => this.i18nRuntime?.config.enabled ? _runWithFarmI18nRequest(this.i18nRuntime, request, fn, { redirect: false }) : fn()
+      () => this.i18nRuntime?.config.enabled ? _runWithFarmI18nRequest(this.i18nRuntime, request, fn, {
+        redirect: false
+      }) : fn()
     );
   }
   async resolveRouteContext(input) {
@@ -16934,11 +17556,11 @@ var _ServerRenderer = class _ServerRenderer {
   /**
    * Check if a path should be served from SSG cache
    */
-  shouldServeSSG(pathname) {
+  async shouldServeSSG(pathname) {
     const ssgPage = matchSSGPage(pathname, this.ssgManifest);
     if (!ssgPage) return null;
-    const cached = this.getCachedSSGPage(pathname);
-    if (cached && this.dataCache.isStale(cached)) {
+    const cached = await this.getCachedSSGPage(pathname);
+    if (cached && await this.dataCache.isStaleAsync(cached)) {
       this.regenerateSSGPage(ssgPage);
     }
     return ssgPage;
@@ -16950,12 +17572,12 @@ var _ServerRenderer = class _ServerRenderer {
     return createFarmCacheKey(["ppr", normalizeRevalidatePath(pathname), search]);
   }
   getCachedSSGPage(urlPath) {
-    return this.dataCache.getEntry(this.getSSGCacheKey(urlPath), {
+    return this.dataCache.getEntryAsync(this.getSSGCacheKey(urlPath), {
       allowStale: true
     });
   }
-  cacheSSGPage(page2, html, options) {
-    this.dataCache.set(
+  async cacheSSGPage(page2, html, options) {
+    await this.dataCache.setAsync(
       this.getSSGCacheKey(page2.urlPath),
       { html, document: options.document },
       {
@@ -16967,11 +17589,11 @@ var _ServerRenderer = class _ServerRenderer {
     );
   }
   getCachedPPRShell(pathname, search) {
-    return this.dataCache.getEntry(this.getPPRCacheKey(pathname, search));
+    return this.dataCache.getEntryAsync(this.getPPRCacheKey(pathname, search));
   }
-  cachePPRShell(options, html) {
+  async cachePPRShell(options, html) {
     const key = this.getPPRCacheKey(options.pathname, options.search);
-    this.dataCache.set(
+    await this.dataCache.setAsync(
       key,
       { html },
       {
@@ -17069,7 +17691,7 @@ var _ServerRenderer = class _ServerRenderer {
           }
           const { renderToString } = await import("react-dom/server");
           const html = renderToString(await this.wrapWithIntegrationProviders(pageElement));
-          this.cacheSSGPage(page2, html, { document: false });
+          await this.cacheSSGPage(page2, html, { document: false });
           logger.info(`ISR: Regenerated ${page2.urlPath}`);
         } catch (error) {
           logger.error(`ISR regeneration failed for ${page2.urlPath}: ${error}`);
@@ -17083,7 +17705,7 @@ var _ServerRenderer = class _ServerRenderer {
    * Serve a pre-rendered SSG page
    */
   async serveSSGPage(req, res, page2) {
-    const cached = this.getCachedSSGPage(page2.urlPath);
+    const cached = await this.getCachedSSGPage(page2.urlPath);
     if (cached) {
       res.setHeader("Content-Type", "text/html; charset=utf-8");
       res.setHeader("X-Farm-SSG", "cached");
@@ -17101,9 +17723,12 @@ var _ServerRenderer = class _ServerRenderer {
       if (fs2.existsSync(htmlPath)) {
         const stat = fs2.statSync(htmlPath);
         const html = fs2.readFileSync(htmlPath, "utf-8");
-        this.cacheSSGPage(page2, html, { document: true, createdAt: stat.mtimeMs });
-        const fileCacheEntry = this.getCachedSSGPage(page2.urlPath);
-        if (fileCacheEntry && this.dataCache.isStale(fileCacheEntry)) {
+        await this.cacheSSGPage(page2, html, {
+          document: true,
+          createdAt: stat.mtimeMs
+        });
+        const fileCacheEntry = await this.getCachedSSGPage(page2.urlPath);
+        if (fileCacheEntry && await this.dataCache.isStaleAsync(fileCacheEntry)) {
           this.regenerateSSGPage(page2);
         }
         res.setHeader("Content-Type", "text/html; charset=utf-8");
@@ -17149,6 +17774,7 @@ var _ServerRenderer = class _ServerRenderer {
     let pathname = "/";
     let params = {};
     let layouts = [];
+    let routeSlots = [];
     let searchParamsObject = {};
     let middlewareMap = /* @__PURE__ */ new Map();
     let middlewareContext = /* @__PURE__ */ new Map();
@@ -17181,7 +17807,7 @@ var _ServerRenderer = class _ServerRenderer {
       }
       this.applyDeploymentHeaders(req, res);
       if (process.env.NODE_ENV === "production") {
-        const ssgPage = this.shouldServeSSG(pathname);
+        const ssgPage = await this.shouldServeSSG(pathname);
         if (ssgPage) {
           const served = await this.serveSSGPage(req, res, ssgPage);
           if (served) {
@@ -17194,6 +17820,7 @@ var _ServerRenderer = class _ServerRenderer {
       const route = match.route;
       params = match.params;
       layouts = match.layouts;
+      routeSlots = match.slots ?? [];
       if (!route) {
         emitFarmEvent({ type: "route.notFound", pathname });
         await this.render404(req, res);
@@ -17210,7 +17837,9 @@ var _ServerRenderer = class _ServerRenderer {
       errorBoundaryEntry = this.routeManager.getMatchingError(pathname);
       middlewareMap = toMiddlewareMap2(req.__FARM_MIDDLEWARE_DATA__);
       middlewareContext = toMiddlewareMap2(req.__FARM_MIDDLEWARE_CONTEXT__);
-      pluginExposedContext = getRequestContextSnapshot(req, { exposedOnly: true });
+      pluginExposedContext = getRequestContextSnapshot(req, {
+        exposedOnly: true
+      });
       const currentRequest = createWebRequestFromFarmRequest(req);
       const routeContext = await this.resolveRouteContext({
         request: currentRequest,
@@ -17274,8 +17903,16 @@ var _ServerRenderer = class _ServerRenderer {
         revalidate: renderingConfig.revalidate
       } : void 0;
       if (renderingConfig.ppr && pprBypassReason) {
-        emitFarmEvent({ type: "ppr.shell.bypass", route: pathname, reason: pprBypassReason });
-        emitFarmEvent({ type: "cache.bypass", route: pathname, reason: pprBypassReason });
+        emitFarmEvent({
+          type: "ppr.shell.bypass",
+          route: pathname,
+          reason: pprBypassReason
+        });
+        emitFarmEvent({
+          type: "cache.bypass",
+          route: pathname,
+          reason: pprBypassReason
+        });
         if (pprBypassReason === "refresh") {
           pprRefreshRoute = pathname;
           emitFarmEvent({ type: "ppr.refresh.start", route: pathname });
@@ -17283,14 +17920,22 @@ var _ServerRenderer = class _ServerRenderer {
       }
       if (pprShellOptions) {
         const pprCacheKey = this.getPPRCacheKey(pathname, url.search);
-        const cachedPPRShell = this.getCachedPPRShell(pathname, url.search);
+        const cachedPPRShell = await this.getCachedPPRShell(pathname, url.search);
         if (cachedPPRShell) {
-          emitFarmEvent({ type: "ppr.shell.hit", route: pathname, key: pprCacheKey });
+          emitFarmEvent({
+            type: "ppr.shell.hit",
+            route: pathname,
+            key: pprCacheKey
+          });
           this.serveCachedPPRShell(res, cachedPPRShell.value, renderingConfig.revalidate);
           completeRender(res.statusCode || 200, pathname);
           return;
         }
-        emitFarmEvent({ type: "ppr.shell.miss", route: pathname, key: pprCacheKey });
+        emitFarmEvent({
+          type: "ppr.shell.miss",
+          route: pathname,
+          key: pprCacheKey
+        });
       }
       let LoadingFallbackComponent = null;
       if (loadingBoundaryEntry) {
@@ -17314,14 +17959,77 @@ var _ServerRenderer = class _ServerRenderer {
       );
       const moduleMetadata = routeManifestEntry || getClientModuleMetadata(route.modulePath, this.config.root);
       const isClientComponent = moduleMetadata.isClientComponent;
+      const renderedRouteSlots = await Promise.all(
+        routeSlots.map(async (slot) => {
+          const slotModule = await this.routeManager.loadRouteModule(slot.route.modulePath);
+          if (!slotModule.default) {
+            throw new Error(
+              `Route slot "${slot.name}" module ${slot.route.modulePath} does not export a default component`
+            );
+          }
+          const slotContext = await this.resolveRouteContext({
+            request: currentRequest,
+            rawRequest: req,
+            params: slot.params,
+            search: searchParamsObject,
+            path: pathname
+          });
+          const rawSlotProps = withFarmRouteContext(
+            {
+              params: slot.params,
+              searchParams: Promise.resolve(searchParamsObject),
+              path: pathname,
+              middleware: middlewareMap.size > 0 ? { data: middlewareMap } : void 0,
+              context: pluginExposedContext.size > 0 ? { data: pluginExposedContext } : void 0
+            },
+            slotContext
+          );
+          const slotProps = await parseRouteModuleProps(slotModule, {
+            props: rawSlotProps,
+            search: searchParamsObject,
+            routePath: slot.route.pattern
+          });
+          const metadata = getClientModuleMetadata(slot.route.modulePath, this.config.root);
+          return {
+            ...slot,
+            module: slotModule,
+            props: slotProps,
+            isClientComponent: metadata.isClientComponent,
+            shouldHydrate: metadata.shouldHydrate
+          };
+        })
+      );
       const shouldHydrate = moduleMetadata.shouldHydrate;
+      const hasHydratableRouteSlots = renderedRouteSlots.some(
+        (slot) => slot.isClientComponent || slot.shouldHydrate
+      );
       req.__FARM_PAGE_PATH__ = route.modulePath;
       req.__FARM_ROUTE__ = pathname;
       req.__FARM_IS_CLIENT_COMPONENT__ = isClientComponent;
       req.__FARM_SHOULD_HYDRATE__ = shouldHydrate;
+      req.__FARM_HAS_HYDRATABLE_ROUTE_SLOTS__ = hasHydratableRouteSlots;
       req.__FARM_LOADING_MODULE_PATH__ = loadingBoundaryEntry?.modulePath ? loadingBoundaryEntry.modulePath.substring(
         loadingBoundaryEntry.modulePath.indexOf("/src/app/")
       ) : null;
+      req.__FARM_ROUTE_SLOTS__ = renderedRouteSlots.map((slot) => ({
+        name: slot.name,
+        ownerPattern: slot.ownerPattern,
+        containerId: slot.containerId,
+        interception: slot.interception,
+        fallback: slot.fallback,
+        modulePath: slot.route.modulePath,
+        isClientComponent: slot.isClientComponent,
+        shouldHydrate: slot.shouldHydrate,
+        props: {
+          params: slot.props.params,
+          search: slot.props.search,
+          searchParams: slot.props.search,
+          ..."data" in slot.props ? { data: slot.props.data } : {},
+          ...slot.props.__farmCanonicalPath ? { __farmCanonicalPath: slot.props.__farmCanonicalPath } : {},
+          ...slot.props.__farmRoutePropsResolved ? { __farmRoutePropsResolved: true } : {},
+          path: pathname
+        }
+      }));
       req.__FARM_PROPS__ = {
         params: pageProps.params,
         search: pageProps.search,
@@ -17381,12 +18089,32 @@ var _ServerRenderer = class _ServerRenderer {
             let wrappedElement = pageElement;
             for (let i = layoutModules.length - 1; i >= 0; i--) {
               const layoutModule = layoutModules[i];
+              const layoutEntry = layouts[i];
               const LayoutComponent = layoutModule.default;
+              const slotProps = {};
+              for (const slot of renderedRouteSlots) {
+                if (slot.ownerPattern !== layoutEntry.pattern) continue;
+                let slotElement = import_react4.default.createElement(
+                  slot.module.default,
+                  slot.props
+                );
+                slotElement = import_react4.default.createElement(
+                  "div",
+                  {
+                    id: slot.containerId,
+                    "data-farm-route-slot": slot.name,
+                    "data-farm-slot-owner": slot.ownerPattern
+                  },
+                  slotElement
+                );
+                slotProps[slot.name] = slotElement;
+              }
               wrappedElement = import_react4.default.createElement(
                 LayoutComponent,
                 {
                   children: wrappedElement,
-                  params
+                  params,
+                  ...slotProps
                 }
               );
             }
@@ -17423,7 +18151,10 @@ var _ServerRenderer = class _ServerRenderer {
                 routeManifest,
                 captureStaticShell: Boolean(pprShellOptions),
                 observabilityRoute: pathname,
-                onSuspenseHoleDetected: pprShellOptions ? () => emitFarmEvent({ type: "ppr.suspense.holeDetected", route: pathname }) : void 0,
+                onSuspenseHoleDetected: pprShellOptions ? () => emitFarmEvent({
+                  type: "ppr.suspense.holeDetected",
+                  route: pathname
+                }) : void 0,
                 onComplete: pprShellOptions && req.method !== "HEAD" ? (html) => this.cachePPRShell(pprShellOptions, html) : void 0
               }
             );
@@ -17471,7 +18202,11 @@ var _ServerRenderer = class _ServerRenderer {
       }
       emitFarmEvent({ type: "render.error", route: pathname, error });
       if (pprRefreshRoute) {
-        emitFarmEvent({ type: "ppr.refresh.error", route: pprRefreshRoute, error });
+        emitFarmEvent({
+          type: "ppr.refresh.error",
+          route: pprRefreshRoute,
+          error
+        });
       }
       logger.error(`Error rendering page: ${error}`);
       if (res.headersSent || res.writableEnded) {
@@ -17524,7 +18259,9 @@ var _ServerRenderer = class _ServerRenderer {
       if (typeof layoutModule.generateMetadata === "function") {
         metadata = mergeMetadata(
           metadata,
-          await layoutModule.generateMetadata({ params: options.pageProps.params })
+          await layoutModule.generateMetadata({
+            params: options.pageProps.params
+          })
         );
       }
     }
@@ -17755,7 +18492,13 @@ var _ServerRenderer = class _ServerRenderer {
         clientEntry: "/@farm/client.js",
         routes: {},
         layouts: {},
-        sharedAssets: [{ tag: "link", attrs: { rel: "stylesheet", href: "/src/app/globals.css" } }]
+        slots: [],
+        sharedAssets: [
+          {
+            tag: "link",
+            attrs: { rel: "stylesheet", href: "/src/app/globals.css" }
+          }
+        ]
       };
       for (const routeEntry of manifest.routes) {
         clientManifest.routes[routeEntry.pattern] = {
@@ -17777,9 +18520,26 @@ var _ServerRenderer = class _ServerRenderer {
           assets: []
         };
       }
-      const deferredProps = prepareDeferredData(req.__FARM_PROPS__ || {});
+      for (const slotEntry of manifest.slots ?? []) {
+        clientManifest.slots.push({
+          ...slotEntry,
+          preloads: [slotEntry.modulePath],
+          assets: []
+        });
+      }
+      const routeSlotPayload = (req.__FARM_ROUTE_SLOTS__ || []).map(
+        (slot) => ({
+          ...slot,
+          modulePath: typeof slot.modulePath === "string" && slot.modulePath.startsWith(this.config.root) ? slot.modulePath.slice(this.config.root.length) : slot.modulePath
+        })
+      );
+      const deferredProps = prepareDeferredData({
+        page: req.__FARM_PROPS__ || {},
+        slots: routeSlotPayload
+      });
       const propsScript = `<script>
-window.__FARM_PROPS__ = ${serializeInlineValue(deferredProps.data)};
+window.__FARM_PROPS__ = ${serializeInlineValue(deferredProps.data.page)};
+window.__FARM_ROUTE_SLOTS__ = ${serializeInlineValue(deferredProps.data.slots)};
 window.__FARM_DEPLOYMENT_ID__ = ${serializeInlineValue(deploymentId)};
 window.__FARM_PATH__ = ${JSON.stringify(req.__FARM_ROUTE__ || req.url || "/")};
 window.__FARM_IS_CLIENT__ = ${JSON.stringify(isClientComponent)};
@@ -17792,7 +18552,7 @@ window.__FARM_MANIFEST__ = ${JSON.stringify(clientManifest)};
 window.__FARM_INTEGRATION_API_MANIFEST__ = ${JSON.stringify(getRegisteredIntegrationAPIManifest())};
 ${getFarmI18nClientSnapshot() ? `window.__FARM_I18N__ = ${serializeInlineValue(getFarmI18nClientSnapshot())};` : ""}
 </script>`;
-      const hydrationClickQueueScript = isClientComponent || req.__FARM_SHOULD_HYDRATE__ === true ? createPreHydrationClickQueueScript() : "";
+      const hydrationClickQueueScript = isClientComponent || req.__FARM_SHOULD_HYDRATE__ === true || req.__FARM_HAS_HYDRATABLE_ROUTE_SLOTS__ === true ? createPreHydrationClickQueueScript() : "";
       const {
         title,
         tags: metaTags,
@@ -17903,7 +18663,11 @@ ${getFarmI18nClientSnapshot() ? `window.__FARM_I18N__ = ${serializeInlineValue(g
           didError = true;
           if (!isFarmRedirectError(error) && !isFarmNotFoundError(error)) {
             logger.error(`SSR shell error: ${error}`);
-            emitFarmEvent({ type: "render.error", route: observabilityRoute, error });
+            emitFarmEvent({
+              type: "render.error",
+              route: observabilityRoute,
+              error
+            });
           }
           if (clearMiddlewareData) {
             clearMiddlewareData();
@@ -17914,7 +18678,11 @@ ${getFarmI18nClientSnapshot() ? `window.__FARM_I18N__ = ${serializeInlineValue(g
           didError = true;
           if (!isFarmRedirectError(error) && !isFarmNotFoundError(error)) {
             logger.error(`SSR streaming error: ${error}`);
-            emitFarmEvent({ type: "render.error", route: observabilityRoute, error });
+            emitFarmEvent({
+              type: "render.error",
+              route: observabilityRoute,
+              error
+            });
           }
         }
       });
@@ -18083,17 +18851,14 @@ var _FarmApp = class _FarmApp {
     _setDefaultFarmI18nRuntime(this.i18nRuntime);
     this.viteServer = viteServer;
     this.routeManager = new RouteManager(this.config, viteServer);
-    this.serverRenderer = new ServerRenderer(
-      this.config,
-      this.routeManager,
-      this.i18nRuntime
-    );
+    this.serverRenderer = new ServerRenderer(this.config, this.routeManager, this.i18nRuntime);
   }
   async initialize() {
     if (process.env.FARM_VERBOSE) {
       logger.info("Initializing Farm.js application...");
     }
     await initStorage(this.config.storage);
+    await configureFarmCache(this.config.cache);
     await this.i18nRuntime.initialize();
     await this.verifyAppStructure();
     await this.routeManager.discoverRoutes();
@@ -18125,6 +18890,7 @@ var _FarmApp = class _FarmApp {
       preset: config.preset ?? "node-server",
       deploy: config.deploy || {},
       storage: config.storage || {},
+      cache: config.cache || {},
       integrations: config.integrations || {},
       plugins: config.plugins || [],
       migrations: config.migrations || { commands: [] },
@@ -18536,6 +19302,29 @@ var fs3 = __toESM(require("fs"));
 var path10 = __toESM(require("path"));
 init_route_runtime();
 
+// src/api/runtime.ts
+init_cache_invalidation();
+
+// src/api/endpoint.ts
+var import_better_call = require("better-call");
+var _EndpointFailure = class _EndpointFailure extends Error {
+  constructor(code, data, options) {
+    super(options.message);
+    this.name = "EndpointFailure";
+    this.code = code;
+    this.data = data;
+    this.status = options.status;
+  }
+};
+__name(_EndpointFailure, "EndpointFailure");
+var EndpointFailure = _EndpointFailure;
+function isEndpointFailure(value) {
+  return value instanceof EndpointFailure;
+}
+__name(isEndpointFailure, "isEndpointFailure");
+var EMPTY_ENDPOINT_MIDDLEWARE = Object.freeze([]);
+var EMPTY_ENDPOINT_CONTEXT = Object.freeze(/* @__PURE__ */ Object.create(null));
+
 // src/api/runtime.ts
 function matchAPIRoute(routes, pathname) {
   const exactRoute = routes.get(pathname);
@@ -18568,10 +19357,10 @@ __name(invokeAPIRouteEndpoint, "invokeAPIRouteEndpoint");
 async function invokeAPIRouteEndpointInContext(endpoint, request, params) {
   const farmHandler = endpoint.__handler || (isFarmContextHandler(endpoint) ? endpoint : null);
   if (!farmHandler) {
-    const result2 = await endpoint(request, {
+    const result = await endpoint(request, {
       params: Promise.resolve(params)
     });
-    return normalizeRouteResponse(result2);
+    return normalizeRouteResponse(result);
   }
   const url = new URL(request.url);
   const query = {};
@@ -18580,7 +19369,7 @@ async function invokeAPIRouteEndpointInContext(endpoint, request, params) {
   });
   let body = void 0;
   if (request.method.toUpperCase() !== "GET" && request.method.toUpperCase() !== "HEAD") {
-    body = await readJSONBody(request);
+    body = await readRequestBody2(request);
   }
   const headers = Object.fromEntries(request.headers.entries());
   const types = endpoint.__types || {};
@@ -18596,15 +19385,30 @@ async function invokeAPIRouteEndpointInContext(endpoint, request, params) {
   if (headersValidation instanceof Response) {
     return headersValidation;
   }
-  const result = await farmHandler({
+  const handlerContext = {
     query: queryValidation,
     body: bodyValidation,
     headers: headersValidation,
     request,
     context: {},
     params
-  });
-  return normalizeRouteResponse(result);
+  };
+  let execution;
+  try {
+    execution = typeof endpoint.__farmInvoke === "function" ? await endpoint.__farmInvoke(handlerContext) : {
+      result: await farmHandler(handlerContext),
+      context: handlerContext.context,
+      handlerExecuted: true,
+      invalidations: []
+    };
+  } catch (error) {
+    if (isEndpointFailure(error)) {
+      return createEndpointFailureResponse(error);
+    }
+    throw error;
+  }
+  const response = normalizeRouteResponse(execution.result);
+  return attachEndpointInvalidations(response, execution.invalidations);
 }
 __name(invokeAPIRouteEndpointInContext, "invokeAPIRouteEndpointInContext");
 function normalizeRouteResponse(result) {
@@ -18624,6 +19428,40 @@ function isWebResponse2(value) {
   return value instanceof Response || typeof value === "object" && value !== null && "headers" in value && "status" in value && typeof value.arrayBuffer === "function";
 }
 __name(isWebResponse2, "isWebResponse");
+function attachEndpointInvalidations(response, keys) {
+  const existing = decodeFarmCacheInvalidations(
+    response.headers.get(FARM_CACHE_INVALIDATION_HEADER)
+  );
+  const encoded = encodeFarmCacheInvalidations([...existing, ...keys]);
+  if (!encoded) return response;
+  const headers = new Headers(response.headers);
+  headers.set(FARM_CACHE_INVALIDATION_HEADER, encoded);
+  return new Response(response.body, {
+    status: response.status,
+    statusText: response.statusText,
+    headers
+  });
+}
+__name(attachEndpointInvalidations, "attachEndpointInvalidations");
+function createEndpointFailureResponse(failure) {
+  return new Response(
+    JSON.stringify({
+      error: {
+        code: failure.code,
+        message: failure.message,
+        data: failure.data
+      }
+    }),
+    {
+      status: failure.status,
+      headers: {
+        "cache-control": "no-store",
+        "content-type": "application/json"
+      }
+    }
+  );
+}
+__name(createEndpointFailureResponse, "createEndpointFailureResponse");
 function isFarmContextHandler(endpoint) {
   if (typeof endpoint !== "function") {
     return false;
@@ -18635,17 +19473,50 @@ function isFarmContextHandler(endpoint) {
   return firstParameter === "ctx" || firstParameter === "context" || firstParameter.startsWith("{");
 }
 __name(isFarmContextHandler, "isFarmContextHandler");
-async function readJSONBody(request) {
+async function readRequestBody2(request) {
+  const contentType = request.headers.get("content-type")?.split(";", 1)[0]?.trim().toLowerCase();
   try {
+    if (contentType === "multipart/form-data") {
+      return formDataToObject(await request.clone().formData());
+    }
     const text2 = await request.clone().text();
-    if (text2) {
+    if (!text2) return void 0;
+    if (contentType === "application/x-www-form-urlencoded") {
+      return searchParamsToObject2(new URLSearchParams(text2));
+    }
+    if (contentType === "application/json" || contentType?.endsWith("+json")) {
       return JSON.parse(text2);
     }
+    return JSON.parse(text2);
   } catch {
   }
   return void 0;
 }
-__name(readJSONBody, "readJSONBody");
+__name(readRequestBody2, "readRequestBody");
+function formDataToObject(formData) {
+  return entriesToObject(formData.entries());
+}
+__name(formDataToObject, "formDataToObject");
+function searchParamsToObject2(searchParams) {
+  return entriesToObject(searchParams.entries());
+}
+__name(searchParamsToObject2, "searchParamsToObject");
+function entriesToObject(entries) {
+  const output = /* @__PURE__ */ Object.create(null);
+  for (const [key, value] of 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(entriesToObject, "entriesToObject");
 function validateInput(schema, value, error) {
   if (!schema || typeof schema.parse !== "function") {
     return value;
@@ -19652,7 +20523,7 @@ var _MiddlewareManager = class _MiddlewareManager {
     if (!nestedMatch.matched) {
       return { matched: false };
     }
-    const params = { ...nestedMatch.params || {} };
+    const params = { ...nestedMatch.params };
     delete params.__farmRest;
     return {
       matched: true,
@@ -19800,6 +20671,7 @@ async function generateRouteTypes(options) {
         absolute: false
       });
       for (const file of pageFiles) {
+        if (parseRouteSlotFile(file)) continue;
         const route = parseRoutePath(file);
         if (route.type === "page") {
           const pattern = createRoutePattern(route);
@@ -20534,6 +21406,12 @@ function transformError(id, message) {
 }
 __name(transformError, "transformError");
 
+// package.json
+var version = "0.1.0-beta.4";
+
+// src/version.ts
+var FARM_VERSION = version;
+
 // src/after.ts
 var import_node_async_hooks4 = require("async_hooks");
 var AFTER_STORAGE = /* @__PURE__ */ Symbol.for("@farm.js/core/after-storage");
@@ -21005,7 +21883,7 @@ function isResolvedEnvScope(value) {
 }
 __name(isResolvedEnvScope, "isResolvedEnvScope");
 function isPotentialProgrammaticRouteSourceFile(normalizedFile, srcDirSlug) {
-  return normalizedFile.startsWith(`${srcDirSlug}/`) && /\.(ts|tsx|js|jsx)$/.test(normalizedFile) && !/\.d\.ts$/.test(normalizedFile) && !normalizedFile.endsWith("/farm-routes.d.ts") && !normalizedFile.endsWith("/farm-env.d.ts") && !normalizedFile.endsWith("/lib/api.generated.ts");
+  return normalizedFile.startsWith(`${srcDirSlug}/`) && /\.(ts|tsx|js|jsx)$/.test(normalizedFile) && !normalizedFile.endsWith(".d.ts") && !normalizedFile.endsWith("/farm-routes.d.ts") && !normalizedFile.endsWith("/farm-env.d.ts") && !normalizedFile.endsWith("/lib/api.generated.ts");
 }
 __name(isPotentialProgrammaticRouteSourceFile, "isPotentialProgrammaticRouteSourceFile");
 function fileContainsProgrammaticPageRoute(file) {
@@ -21248,7 +22126,7 @@ function farmPlugin(options = {}, initialPluginManager) {
       }, "isProgrammaticRouteSourceFile");
       const isAppRuntimeFile = /* @__PURE__ */ __name((file) => {
         const normalized = file.replace(/\\/g, "/");
-        return appDirSlugs.some((appDir) => normalized.startsWith(`${appDir}/`)) && /\/(?:page|layout|loading|error|middleware|route)\.(?:ts|tsx|js|jsx|md|mdx)$|\/(?:opengraph-image|twitter-image)(?:\.(?:ts|tsx|js|jsx|png|jpg|jpeg|gif|webp)|\.alt\.txt)$/.test(
+        return appDirSlugs.some((appDir) => normalized.startsWith(`${appDir}/`)) && /\/(?:page|default|layout|loading|error|middleware|route)\.(?:ts|tsx|js|jsx|md|mdx)$|\/(?:opengraph-image|twitter-image)(?:\.(?:ts|tsx|js|jsx|png|jpg|jpeg|gif|webp)|\.alt\.txt)$/.test(
           normalized
         );
       }, "isAppRuntimeFile");
@@ -21939,7 +22817,10 @@ function farmPlugin(options = {}, initialPluginManager) {
                     method: req.method || "GET"
                   });
                 }
-                const match = routeManager3.matchRoute(targetPath);
+                const interceptFromHeader = request.headers.get("x-farm-intercept-from") || void 0;
+                const match = routeManager3.matchRoute(targetRequestUrl.pathname, {
+                  interceptFrom: interceptFromHeader
+                });
                 if (pm) {
                   await pm.runHookParallel("afterRouteMatch", {
                     pathname: targetPath,
@@ -21955,7 +22836,7 @@ function farmPlugin(options = {}, initialPluginManager) {
                   res.end(JSON.stringify({ error: "Route not found" }));
                   return;
                 }
-                const { route, params, layouts } = match;
+                const { route, params, layouts, slots } = match;
                 if (!route) {
                   res.statusCode = 404;
                   res.setHeader("Content-Type", "application/json");
@@ -22010,6 +22891,54 @@ function farmPlugin(options = {}, initialPluginManager) {
                   search: searchParams,
                   routePath: route.pattern
                 });
+                const routeSlots = await Promise.all(
+                  slots.map(async (slot) => {
+                    const slotModule = await routeManager3.loadRouteModule(slot.route.modulePath);
+                    const slotMetadata = getClientModuleMetadata(
+                      slot.route.modulePath,
+                      server.config.root
+                    );
+                    const slotContext = await resolveFarmRouteContext(farmApp.getConfig(), {
+                      request,
+                      params: slot.params,
+                      search: searchParams,
+                      path: targetUrl.pathname
+                    });
+                    const slotProps = await parseRouteModuleProps2(slotModule, {
+                      props: withFarmRouteContext(
+                        {
+                          params: slot.params,
+                          searchParams: Promise.resolve(searchParams),
+                          path: targetUrl.pathname
+                        },
+                        slotContext
+                      ),
+                      search: searchParams,
+                      routePath: slot.route.pattern
+                    });
+                    return {
+                      name: slot.name,
+                      ownerPattern: slot.ownerPattern,
+                      containerId: slot.containerId,
+                      interception: slot.interception,
+                      fallback: slot.fallback,
+                      modulePath: slot.route.modulePath,
+                      isClientComponent: slotMetadata.isClientComponent,
+                      shouldHydrate: slotMetadata.shouldHydrate,
+                      props: {
+                        params: slotProps.params,
+                        search: slotProps.search,
+                        searchParams: slotProps.search,
+                        ..."data" in slotProps ? { data: slotProps.data } : {},
+                        ...slotProps.__farmCanonicalPath ? {
+                          __farmCanonicalPath: slotProps.__farmCanonicalPath
+                        } : {},
+                        ...slotProps.__farmRoutePropsResolved ? { __farmRoutePropsResolved: true } : {},
+                        path: targetUrl.pathname
+                      }
+                    };
+                  })
+                );
                 const projectRoot = server.config.root;
                 const toUrlPath = /* @__PURE__ */ __name((absolutePath) => {
                   if (absolutePath.startsWith(projectRoot)) {
@@ -22030,13 +22959,21 @@ function farmPlugin(options = {}, initialPluginManager) {
                   },
                   canonicalPath: routeProps.__farmCanonicalPath,
                   modulePath: toUrlPath(route.modulePath),
-                  isClientComponent,
-                  shouldHydrate,
+                  isClientComponent: routeSlots.length > 0 ? false : isClientComponent,
+                  shouldHydrate: shouldHydrate || routeSlots.some((slot) => slot.isClientComponent || slot.shouldHydrate),
                   metadata: {
                     title: mergedMetadata.title,
                     description: mergedMetadata.description
                   },
                   layoutModules: layouts.map((l) => toUrlPath(l.modulePath)),
+                  routeSlots: routeSlots.map((slot) => ({
+                    ...slot,
+                    modulePath: toUrlPath(slot.modulePath)
+                  })),
+                  interception: routeSlots.some((slot) => slot.interception) ? {
+                    from: interceptFromHeader,
+                    slots: routeSlots.filter((slot) => slot.interception).map((slot) => slot.name)
+                  } : void 0,
                   i18n: getFarmI18nClientSnapshot()
                 };
                 await sendWebResponse(
@@ -22372,6 +23309,7 @@ function farmPlugin(options = {}, initialPluginManager) {
 export const getManifest = () => ({
   routes: {},
   layouts: {},
+  slots: [],
   clientEntry: "/@farm/client.js",
   sharedAssets: []
 });
@@ -22382,6 +23320,7 @@ export const getManifest = () => ({
           clientEntry: "/@farm/client.js",
           routes: {},
           layouts: {},
+          slots: [],
           sharedAssets: [
             {
               tag: "link",
@@ -22411,6 +23350,13 @@ export const getManifest = () => ({
             assets: []
           };
         }
+        for (const slot of manifest.slots) {
+          fullManifest.slots.push({
+            ...slot,
+            preloads: [slot.modulePath],
+            assets: []
+          });
+        }
         return `
 // Auto-generated manifest for SPA navigation (TanStack Start pattern)
 // This manifest is inlined in the server bundle - no file on disk
@@ -23053,7 +23999,7 @@ window.__FARM_WRAP_PROVIDERS__ = wrapWithIntegrationProviders;
 
 // Get manifest from window (inlined by server in HTML)
 // Fallback to empty manifest if not available yet
-const getManifest = () => window.__FARM_MANIFEST__ || { routes: {}, layouts: {}, clientEntry: '', sharedAssets: [] };
+const getManifest = () => window.__FARM_MANIFEST__ || { routes: {}, layouts: {}, slots: [], clientEntry: '', sharedAssets: [] };
 
 // ====== CLIENT-SIDE ROUTE MATCHING ======
 // Matches URL to route using manifest (no server request!)
@@ -23392,6 +24338,9 @@ let LayoutComponent = null;
 
 // Track if we've taken over rendering from SSR
 let hasClientTakenOver = false;
+const routeSlotRoots = new Map();
+const routeSlotDefinitions = new Map();
+let activeRouteInterception = null;
 
 function normalizeServerProps(rawProps) {
   const props = rawProps && typeof rawProps === 'object' ? { ...rawProps } : {};
@@ -23404,6 +24353,123 @@ function normalizeServerProps(rawProps) {
   return props;
 }
 
+function getRouteSlotKey(slot) {
+  return slot.ownerPattern + ':' + slot.name;
+}
+
+async function renderRouteSlot(slot, mode = 'render') {
+  const container = document.getElementById(slot.containerId);
+  if (!container || !slot.modulePath) return false;
+  if (mode === 'intercept' && !slot.isClientComponent && !slot.shouldHydrate) {
+    return false;
+  }
+
+  let slotModule = pageModuleCache.get(slot.modulePath);
+  if (!slotModule) {
+    slotModule = await import(/* @vite-ignore */ slot.modulePath);
+    pageModuleCache.set(slot.modulePath, slotModule);
+  }
+  const SlotComponent = slotModule?.default;
+  if (!SlotComponent) return false;
+
+  const props = reviveDeferredData(
+    normalizeServerProps(slot.props || {}),
+    window.__FARM_DEFERRED_DATA__ || {},
+  );
+  const element = wrapWithIntegrationProviders(
+    React.createElement(SlotComponent, props),
+  );
+  const key = getRouteSlotKey(slot);
+  const existingRoot = routeSlotRoots.get(key);
+
+  if (mode === 'hydrate') {
+    if (existingRoot) return true;
+    const root = hydrateRoot(container, element);
+    routeSlotRoots.set(key, root);
+  } else {
+    if (existingRoot) {
+      try { existingRoot.unmount(); } catch (error) {}
+    }
+    const root = createRoot(container);
+    root.render(element);
+    routeSlotRoots.set(key, root);
+  }
+
+  routeSlotDefinitions.set(key, slot);
+  return true;
+}
+
+async function hydrateInitialRouteSlots() {
+  const slots = Array.isArray(window.__FARM_ROUTE_SLOTS__)
+    ? window.__FARM_ROUTE_SLOTS__
+    : [];
+  let hydrated = false;
+
+  for (const slot of slots) {
+    routeSlotDefinitions.set(getRouteSlotKey(slot), slot);
+    if (!slot.isClientComponent && !slot.shouldHydrate) continue;
+    try {
+      hydrated = (await renderRouteSlot(slot, 'hydrate')) || hydrated;
+    } catch (error) {
+      console.warn('[Farm.js] Could not hydrate route slot:', slot.name, error);
+    }
+  }
+
+  return hydrated;
+}
+
+async function renderRouteInterception(pageData) {
+  const slots = Array.isArray(pageData.routeSlots)
+    ? pageData.routeSlots.filter((slot) => slot.interception)
+    : [];
+  if (!pageData.interception || slots.length === 0) return false;
+
+  const previous = new Map();
+  for (const slot of slots) {
+    const key = getRouteSlotKey(slot);
+    previous.set(key, routeSlotDefinitions.get(key) || null);
+    if (!(await renderRouteSlot(slot, 'intercept'))) {
+      return false;
+    }
+  }
+
+  activeRouteInterception = {
+    from: pageData.interception.from,
+    slots,
+    previous,
+  };
+  return true;
+}
+
+async function clearRouteInterception(destination) {
+  if (!activeRouteInterception) return false;
+  const active = activeRouteInterception;
+  activeRouteInterception = null;
+
+  for (const slot of active.slots) {
+    const key = getRouteSlotKey(slot);
+    const root = routeSlotRoots.get(key);
+    if (root) {
+      try { root.unmount(); } catch (error) {}
+      routeSlotRoots.delete(key);
+    }
+
+    const previous = active.previous.get(key);
+    if (previous && (previous.isClientComponent || previous.shouldHydrate)) {
+      await renderRouteSlot(previous, 'render');
+    } else {
+      const container = document.getElementById(slot.containerId);
+      if (container) container.replaceChildren();
+      if (previous) routeSlotDefinitions.set(key, previous);
+      else routeSlotDefinitions.delete(key);
+    }
+  }
+
+  if (!active.from) return false;
+  const background = new URL(active.from, window.location.origin);
+  return destination === background.pathname + background.search;
+}
+
 function applyCanonicalPathFromProps(props) {
   const canonicalPath = props && typeof props.__farmCanonicalPath === 'string'
     ? props.__farmCanonicalPath
@@ -23638,6 +24704,17 @@ async function tryHydrateImportedPage(
 async function renderPage(pageData) {
   const container = document.getElementById('root');
   if (!container) return;
+  const destination = window.location.pathname + window.location.search;
+
+  if (pageData.interception) {
+    if (await renderRouteInterception(pageData)) return;
+    window.location.assign(destination);
+    return;
+  }
+
+  if (await clearRouteInterception(destination)) {
+    return;
+  }
 
   const route = {
     modulePath: pageData.modulePath,
@@ -23866,7 +24943,9 @@ async function hydrate() {
       window.__FARM_SHOULD_HYDRATE__ === true ||
       isClientComponent ||
       await moduleLooksClient(modulePath);
+    const hydratedSlots = await hydrateInitialRouteSlots();
     if (!shouldHydrate) {
+      if (hydratedSlots) replayPreHydrationClicks();
       console.log('[Farm.js] Server component - SPA router ready')
       return
     }
@@ -24131,7 +25210,7 @@ async function defineConfig2(config = {}) {
           const isExposed = hostConfig === true || hostConfig === "0.0.0.0";
           console.log("");
           console.log(
-            `  ${pc.bold(pc.green("Farm.js"))} ${pc.dim("v1.0.0")} ${pc.dim(`ready in ${elapsed}ms`)}`
+            `  ${pc.bold(pc.green("Farm.js"))} ${pc.dim(`v${FARM_VERSION}`)} ${pc.dim(`ready in ${elapsed}ms`)}`
           );
           console.log("");
           console.log(
@@ -24250,7 +25329,7 @@ function createServerFn(options) {
   const middleware = resolveServerFnMiddleware(options.middleware);
   const serverFn = /* @__PURE__ */ __name(async (value) => {
     const formData = isFormData(value) ? value : void 0;
-    const rawInput = formData ? formDataToObject(formData) : value;
+    const rawInput = formData ? formDataToObject2(formData) : value;
     const input = await _parseServerFnSchema(options.input, rawInput, "input");
     const executionContext = getServerActionExecutionContext();
     const request = executionContext?.request ?? _resolveCurrentRequest();
@@ -24262,8 +25341,21 @@ function createServerFn(options) {
       request,
       signal
     };
-    const result = await runServerFnMiddleware(middleware, handlerContext, options.handler);
-    return _parseServerFnSchema(options.output, result, "output");
+    let resolvedContext = Object.freeze(/* @__PURE__ */ Object.create(null));
+    const result = await runServerFnMiddleware(middleware, handlerContext, async (context) => {
+      resolvedContext = context.context;
+      return options.handler(context);
+    });
+    const parsedResult = await _parseServerFnSchema(options.output, result, "output");
+    if (options.invalidates) {
+      const declaration = typeof options.invalidates === "function" ? await options.invalidates({
+        ...handlerContext,
+        context: resolvedContext,
+        result: parsedResult
+      }) : options.invalidates;
+      await applyFarmCacheInvalidationTargets(declaration);
+    }
+    return parsedResult;
   }, "serverFn");
   Object.defineProperties(serverFn, {
     [FARM_SERVER_FN_SYMBOL]: {
@@ -24285,6 +25377,10 @@ function createServerFn(options) {
     __farmServerFnMiddleware: {
       value: middleware,
       enumerable: false
+    },
+    __farmServerFnInvalidates: {
+      value: options.invalidates,
+      enumerable: false
     }
   });
   return serverFn;
@@ -24382,7 +25478,7 @@ function unwrapSafeParseResult(result) {
   return result;
 }
 __name(unwrapSafeParseResult, "unwrapSafeParseResult");
-function formDataToObject(formData) {
+function formDataToObject2(formData) {
   const output = /* @__PURE__ */ Object.create(null);
   for (const [key, value] of formData.entries()) {
     if (!isSafeFormKey(key)) continue;
@@ -24397,7 +25493,7 @@ function formDataToObject(formData) {
   }
   return output;
 }
-__name(formDataToObject, "formDataToObject");
+__name(formDataToObject2, "formDataToObject");
 function isSafeFormKey(key) {
   return !key.startsWith("$ACTION_") && !UNSAFE_FORM_KEYS.has(key);
 }
@@ -24459,7 +25555,7 @@ function createServerQuery(options) {
           tags: [createRouteDataCacheTag(routeKey)],
           revalidate: staleTime === false ? false : Math.max(1, Math.ceil(staleTime / 1e3))
         });
-        updatedAt = cache.getEntry(cacheKey, { allowStale: true })?.createdAt ?? Date.now();
+        updatedAt = (await cache.getEntryAsync(cacheKey, { allowStale: true }))?.createdAt ?? Date.now();
       }
       return createFarmServerQueryResult(data, {
         key: clientKey,
@@ -25295,7 +26391,7 @@ __name(createLoggerPlugin, "createLoggerPlugin");
 // src/server/vite-config.ts
 function mergeNoExternal(farmValue, userValue) {
   if (farmValue === true || userValue === true) return true;
-  const normalize = /* @__PURE__ */ __name((value) => value == null ? [] : Array.isArray(value) ? value : [value], "normalize");
+  const normalize = /* @__PURE__ */ __name((value) => value == null || value === true ? [] : Array.isArray(value) ? value : [value], "normalize");
   return Array.from(/* @__PURE__ */ new Set([...normalize(farmValue), ...normalize(userValue)]));
 }
 __name(mergeNoExternal, "mergeNoExternal");
@@ -25308,6 +26404,13 @@ function mergeFarmViteConfig(farmConfig, userConfig = {}) {
       ...farmConfig.server,
       ...userConfig.server
     },
+    resolve: {
+      ...farmConfig.resolve,
+      ...userConfig.resolve,
+      dedupe: Array.from(
+        /* @__PURE__ */ new Set([...farmConfig.resolve?.dedupe || [], ...userConfig.resolve?.dedupe || []])
+      )
+    },
     optimizeDeps: {
       ...farmConfig.optimizeDeps,
       ...userConfig.optimizeDeps,
@@ -25334,6 +26437,7 @@ function mergeFarmViteConfig(farmConfig, userConfig = {}) {
 __name(mergeFarmViteConfig, "mergeFarmViteConfig");
 
 // src/server/create-server.ts
+var DEFAULT_FARM_DEV_SERVER_PORT = 3e3;
 function createBrandingPlugin() {
   let serverStarted = false;
   let startTime = Date.now();
@@ -25369,7 +26473,7 @@ function createBrandingPlugin() {
           const pc = getColors();
           console.log("");
           console.log(
-            `  ${pc.bold(pc.green("Farm.js"))} ${pc.dim("v1.0.0")} ${pc.dim(`ready in ${elapsed}ms`)}`
+            `  ${pc.bold(pc.green("Farm.js"))} ${pc.dim(`v${FARM_VERSION}`)} ${pc.dim(`ready in ${elapsed}ms`)}`
           );
           console.log("");
           console.log(
@@ -25495,7 +26599,13 @@ async function createServer(config = {}) {
             createBrandingPlugin()
           ],
           server: {
-            middlewareMode: false
+            middlewareMode: false,
+            port: DEFAULT_FARM_DEV_SERVER_PORT,
+            strictPort: true
+          },
+          resolve: {
+            // Keep framework and application modules on one React runtime.
+            dedupe: ["react", "react-dom"]
           },
           optimizeDeps: {
             // Avoid Vite scanning server/native-only deps from framework internals.
@@ -25570,7 +26680,7 @@ async function createServer(config = {}) {
   }
 }
 __name(createServer, "createServer");
-async function startDevServer(config = {}, port = 3e3) {
+async function startDevServer(config = {}, port) {
   const server = await createServer(config);
   await server.listen(port);
   const pluginManager = server.__farmPluginManager;
@@ -25651,6 +26761,7 @@ function assertFunction(value, label) {
 __name(assertFunction, "assertFunction");
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  DEFAULT_FARM_DEV_SERVER_PORT,
   DEFAULT_SERVER_ACTION_BODY_SIZE_LIMIT,
   FARM_SERVER_QUERY_SYMBOL,
   FarmApp,
@@ -25663,7 +26774,9 @@ __name(assertFunction, "assertFunction");
   _runWithAfterRequest,
   _withAfterNodeMiddleware,
   after,
+  applyFarmCacheInvalidationTargets,
   applyFarmCacheInvalidations,
+  configureFarmCache,
   createClientOnlyFn,
   createFarmApp,
   createFarmCacheKey,
@@ -25678,6 +26791,7 @@ __name(assertFunction, "assertFunction");
   createServerQuery,
   createStorageClient,
   databaseStorage,
+  defineCacheKey,
   defineConfig,
   defineStorageClient,
   disposeStorage,
@@ -25728,6 +26842,7 @@ __name(assertFunction, "assertFunction");
   segmentsToPattern,
   sqliteStorage,
   startDevServer,
+  storageCacheAdapter,
   toViteModuleId,
   unstable_cache,
   updateTag,