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

package/dist/{chunk-XJSHJN4M.mjs → chunk-A2LUXHD2.mjs}

@@ -42,7 +42,7 @@ import {
 } from "./chunk-GY2STC2S.mjs";
 import {
   resolveServerActionsConfig
-} from "./chunk-45LKHSHJ.mjs";
+} from "./chunk-UB5UOSHB.mjs";
 import {
   createMarkdownMirrorResponse,
   resolveMarkdownConfig
@@ -91,7 +91,7 @@ import {
   discoverProgrammaticRoutePaths,
   findProgrammaticRouteFiles,
   loadProgrammaticRouteManifests
-} from "./chunk-LG3YINQN.mjs";
+} from "./chunk-Z5CQMP54.mjs";
 import {
   _runWithFarmI18nRequest,
   _setDefaultFarmI18nRuntime,
@@ -115,7 +115,7 @@ import {
   parseProgrammaticRouteModuleId,
   parseProgrammaticRoutePath,
   scanProgrammaticPagePaths
-} from "./chunk-CSU4KJJF.mjs";
+} from "./chunk-C2ROET2V.mjs";
 import {
   resolveFarmRouteContext,
   withFarmRouteContext
@@ -142,7 +142,7 @@ import {
 } from "./chunk-RHIFZZUI.mjs";
 import {
   FARM_VERSION
-} from "./chunk-JNYVN7YP.mjs";
+} from "./chunk-EEABSBKK.mjs";
 import {
   FARM_DEPLOYMENT_ID_HEADER,
   createFarmDeploymentCookie,
@@ -161,10 +161,11 @@ import {
   stripFarmLocaleFromPathname
 } from "./chunk-44ZCFSKE.mjs";
 import {
+  configureFarmCache,
   createFarmCacheKey,
   getFarmDataCache,
   normalizeRevalidatePath
-} from "./chunk-GZWT6VI5.mjs";
+} from "./chunk-V3XURYJO.mjs";
 import {
   configureFarmObservability,
   emitFarmEvent
@@ -778,6 +779,76 @@ async function readAltText(filePath) {
 }
 __name(readAltText, "readAltText");
 
+// 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) => {
@@ -791,6 +862,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();
@@ -806,6 +878,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();
@@ -816,6 +889,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)
@@ -831,7 +911,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;
@@ -845,10 +925,12 @@ var _RouteManager = class _RouteManager {
       }
     }
     const layouts = this.findMatchingLayouts(normalizedPath);
+    const slots = this.findMatchingRouteSlots(normalizedPath, options.interceptFrom);
     return {
       route: matchedRoute,
       params,
-      layouts
+      layouts,
+      slots
     };
   }
   /**
@@ -863,6 +945,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);
@@ -1021,7 +1106,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
@@ -1098,6 +1198,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);
@@ -1106,7 +1207,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]
@@ -1130,6 +1231,32 @@ var _RouteManager = class _RouteManager {
         });
       }
     }
+    for (const file of [...pageFiles, ...slotDefaultFiles]) {
+      const slot = parseRouteSlotFile(file);
+      if (!slot) continue;
+      const modulePath = path3.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 = path3.basename(file, path3.extname(file));
       const kind = fileBase === "twitter-image" ? "twitter" : "opengraph";
@@ -1255,6 +1382,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);
@@ -1659,7 +1851,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) {
@@ -1682,11 +1876,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;
@@ -1698,12 +1892,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(page, html, options) {
-    this.dataCache.set(
+  async cacheSSGPage(page, html, options) {
+    await this.dataCache.setAsync(
       this.getSSGCacheKey(page.urlPath),
       { html, document: options.document },
       {
@@ -1715,11 +1909,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 },
       {
@@ -1817,7 +2011,7 @@ var _ServerRenderer = class _ServerRenderer {
           }
           const { renderToString } = await import("react-dom/server");
           const html = renderToString(await this.wrapWithIntegrationProviders(pageElement));
-          this.cacheSSGPage(page, html, { document: false });
+          await this.cacheSSGPage(page, html, { document: false });
           logger.info(`ISR: Regenerated ${page.urlPath}`);
         } catch (error) {
           logger.error(`ISR regeneration failed for ${page.urlPath}: ${error}`);
@@ -1831,7 +2025,7 @@ var _ServerRenderer = class _ServerRenderer {
    * Serve a pre-rendered SSG page
    */
   async serveSSGPage(req, res, page) {
-    const cached = this.getCachedSSGPage(page.urlPath);
+    const cached = await this.getCachedSSGPage(page.urlPath);
     if (cached) {
       res.setHeader("Content-Type", "text/html; charset=utf-8");
       res.setHeader("X-Farm-SSG", "cached");
@@ -1849,9 +2043,12 @@ var _ServerRenderer = class _ServerRenderer {
       if (fs2.existsSync(htmlPath)) {
         const stat = fs2.statSync(htmlPath);
         const html = fs2.readFileSync(htmlPath, "utf-8");
-        this.cacheSSGPage(page, html, { document: true, createdAt: stat.mtimeMs });
-        const fileCacheEntry = this.getCachedSSGPage(page.urlPath);
-        if (fileCacheEntry && this.dataCache.isStale(fileCacheEntry)) {
+        await this.cacheSSGPage(page, html, {
+          document: true,
+          createdAt: stat.mtimeMs
+        });
+        const fileCacheEntry = await this.getCachedSSGPage(page.urlPath);
+        if (fileCacheEntry && await this.dataCache.isStaleAsync(fileCacheEntry)) {
           this.regenerateSSGPage(page);
         }
         res.setHeader("Content-Type", "text/html; charset=utf-8");
@@ -1897,6 +2094,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();
@@ -1929,7 +2127,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) {
@@ -1942,6 +2140,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);
@@ -1958,7 +2157,9 @@ var _ServerRenderer = class _ServerRenderer {
       errorBoundaryEntry = this.routeManager.getMatchingError(pathname);
       middlewareMap = toMiddlewareMap(req.__FARM_MIDDLEWARE_DATA__);
       middlewareContext = toMiddlewareMap(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,
@@ -2022,8 +2223,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 });
@@ -2031,14 +2240,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) {
@@ -2062,14 +2279,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,
@@ -2129,12 +2409,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 = React.createElement(
+                  slot.module.default,
+                  slot.props
+                );
+                slotElement = React.createElement(
+                  "div",
+                  {
+                    id: slot.containerId,
+                    "data-farm-route-slot": slot.name,
+                    "data-farm-slot-owner": slot.ownerPattern
+                  },
+                  slotElement
+                );
+                slotProps[slot.name] = slotElement;
+              }
               wrappedElement = React.createElement(
                 LayoutComponent,
                 {
                   children: wrappedElement,
-                  params
+                  params,
+                  ...slotProps
                 }
               );
             }
@@ -2171,7 +2471,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
               }
             );
@@ -2219,7 +2522,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) {
@@ -2272,7 +2579,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
+          })
         );
       }
     }
@@ -2503,7 +2812,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] = {
@@ -2525,9 +2840,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)};
@@ -2540,7 +2872,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,
@@ -2651,7 +2983,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();
@@ -2662,7 +2998,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
+            });
           }
         }
       });
@@ -2836,6 +3176,7 @@ var _FarmApp = class _FarmApp {
       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();
@@ -2867,6 +3208,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: [] },
@@ -3339,6 +3681,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);
@@ -3665,7 +4008,7 @@ function loadFarmWorkflowsDevRuntime() {
 }
 __name(loadFarmWorkflowsDevRuntime, "loadFarmWorkflowsDevRuntime");
 function loadFarmDevtoolsSnapshotRuntime() {
-  return import("./devtools-HE4FTUDN.mjs");
+  return import("./devtools-LVC3VB5P.mjs");
 }
 __name(loadFarmDevtoolsSnapshotRuntime, "loadFarmDevtoolsSnapshotRuntime");
 function loadFarmDevtoolsUIRuntime() {
@@ -4071,7 +4414,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");
@@ -4762,7 +5105,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,
@@ -4778,7 +5124,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");
@@ -4833,6 +5179,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)) {
@@ -4853,13 +5247,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(
@@ -5195,6 +5597,7 @@ function farmPlugin(options = {}, initialPluginManager) {
 export const getManifest = () => ({
   routes: {},
   layouts: {},
+  slots: [],
   clientEntry: "/@farm/client.js",
   sharedAssets: []
 });
@@ -5205,6 +5608,7 @@ export const getManifest = () => ({
           clientEntry: "/@farm/client.js",
           routes: {},
           layouts: {},
+          slots: [],
           sharedAssets: [
             {
               tag: "link",
@@ -5234,6 +5638,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
@@ -5876,7 +6287,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!)
@@ -6215,6 +6626,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 } : {};
@@ -6227,6 +6641,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
@@ -6461,6 +6992,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,
@@ -6689,7 +7231,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
     }
@@ -7084,4 +7628,4 @@ export {
   farmPlugin,
   defineConfig
 };
-//# sourceMappingURL=chunk-XJSHJN4M.mjs.map
+//# sourceMappingURL=chunk-A2LUXHD2.mjs.map