@farm.js/core 0.1.0-beta.10 → 0.1.0-beta.13

package/dist/{chunk-DTOWEQRV.mjs → chunk-VSDZEB5M.mjs}

@@ -1,27 +1,24 @@
+import {
+  withProductionNodeEnv
+} from "./chunk-4S3ORGFA.mjs";
 import {
   canUseRolldownForRouteDiscovery,
   loadFarmProductionVite
 } from "./chunk-SL6HTIOK.mjs";
-import {
-  withProductionNodeEnv
-} from "./chunk-4S3ORGFA.mjs";
 import {
   FARM_DOCS_LAST_MODIFIED_MANIFEST,
   createFarmDocsLastModifiedManifest,
   getFarmDocsRouteTypeEntries
-} from "./chunk-4LND3PXF.mjs";
+} from "./chunk-OPHK6OJN.mjs";
 import {
   generateFarmDocsSearchClientRuntime,
   isFarmDocsSearchEnabled,
   resolveFarmDocsSearchClientModule
 } from "./chunk-V7RBCSDJ.mjs";
-import {
-  mergeFarmViteConfig
-} from "./chunk-QM746KUO.mjs";
 import {
   hasCustomFarmRouteContext,
   resolveDeployOutputPath
-} from "./chunk-K5ZTUF22.mjs";
+} from "./chunk-L2PE36GQ.mjs";
 import {
   PluginManager
 } from "./chunk-DJSGLHCN.mjs";
@@ -32,11 +29,16 @@ import {
   generateFarmTypeArtifacts,
   getClientModuleMetadata,
   mergeFarmFontCss,
+  mergeFarmViteConfig,
   resolveRouteRenderingConfigFromFile
-} from "./chunk-E2AI2CW7.mjs";
+} from "./chunk-Z3YG4OZT.mjs";
 import {
   farmEnvironmentFunctionsPlugin
 } from "./chunk-V6WE6JSZ.mjs";
+import {
+  resolveFarmDocsFontAssets,
+  toFarmDocsPublicFontAssets
+} from "./chunk-USLFXFFH.mjs";
 import {
   routeRulesToNitroRouteRules
 } from "./chunk-YW7OBE6Q.mjs";
@@ -319,6 +321,31 @@ function escapeRegExp(value) {
 }
 __name(escapeRegExp, "escapeRegExp");
 
+// src/nitro/vercel-assets.ts
+var FARM_IMMUTABLE_ASSET_CACHE_CONTROL = "public, max-age=31536000, immutable";
+function createFarmVercelImmutableAssetRoute(basePath = "/") {
+  const normalizedBasePath = normalizeBasePath(basePath);
+  const escapedBasePath = escapeRegex(normalizedBasePath);
+  const prefix = escapedBasePath ? `/${escapedBasePath}` : "";
+  return {
+    src: `^${prefix}/(?:assets|chunks)/(?:.+/)*[^/]+-h(?:[a-fA-F0-9]{8}|[a-fA-F0-9]{12}|[a-fA-F0-9]{16})\\.(?!(?:[hH][tT][mM][lL]?)$)[^/]+$`,
+    headers: {
+      "Cache-Control": FARM_IMMUTABLE_ASSET_CACHE_CONTROL
+    },
+    continue: true,
+    caseSensitive: true
+  };
+}
+__name(createFarmVercelImmutableAssetRoute, "createFarmVercelImmutableAssetRoute");
+function normalizeBasePath(basePath) {
+  return basePath.trim().replace(/^\/+|\/+$/g, "");
+}
+__name(normalizeBasePath, "normalizeBasePath");
+function escapeRegex(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+__name(escapeRegex, "escapeRegex");
+
 // src/build/vite-plugin-compat.ts
 function adaptTailwindVitePlugin(pluginOption, builder) {
   if (builder !== "rolldown") return pluginOption;
@@ -463,6 +490,10 @@ function isCloudflareImagePreset(preset) {
   return preset === "cloudflare" || preset === "cloudflare-pages" || preset === "cloudflare-module";
 }
 __name(isCloudflareImagePreset, "isCloudflareImagePreset");
+function shouldUseExternalMetadataImageRuntime(preset, hasGeneratedMetadataImages) {
+  return hasGeneratedMetadataImages && preset !== "vercel-edge" && !isCloudflareImagePreset(preset);
+}
+__name(shouldUseExternalMetadataImageRuntime, "shouldUseExternalMetadataImageRuntime");
 function resolveImageRuntime(config, preset) {
   if (config.images.provider === "none") return "none";
   const cloudflarePreset = isCloudflareImagePreset(preset);
@@ -480,6 +511,31 @@ function isNitroRollupExternal(id) {
   return NODE_BUILTIN_MODULES.has(id) || NITRO_EXTERNAL_MODULES.has(id) || normalizedId.startsWith(".prisma/") || normalizedId.includes("/node_modules/@prisma/client/") || normalizedId.includes("/node_modules/.prisma/client/");
 }
 __name(isNitroRollupExternal, "isNitroRollupExternal");
+var FARM_METADATA_IMAGE_WASM_PREFIX = "\0farm-metadata-image-wasm:";
+function createMetadataImageWasmPlugin() {
+  return {
+    name: "farm-metadata-image-wasm",
+    resolveId(source, importer) {
+      if (!source.endsWith(".wasm?module") || !importer?.replace(/\\/g, "/").includes("/@vercel/og/")) {
+        return null;
+      }
+      const requestPath = source.slice(0, -"?module".length);
+      const resolvedPath = path3.isAbsolute(requestPath) ? requestPath : path3.resolve(path3.dirname(importer.split("?", 1)[0]), requestPath);
+      return `${FARM_METADATA_IMAGE_WASM_PREFIX}${resolvedPath}`;
+    },
+    load(id) {
+      if (!id.startsWith(FARM_METADATA_IMAGE_WASM_PREFIX)) return null;
+      const wasmPath = id.slice(FARM_METADATA_IMAGE_WASM_PREFIX.length);
+      const encoded = readFileSync(wasmPath).toString("base64");
+      return `
+const encoded = ${JSON.stringify(encoded)};
+const bytes = Uint8Array.from(atob(encoded), (character) => character.charCodeAt(0));
+export default new WebAssembly.Module(bytes);
+`;
+    }
+  };
+}
+__name(createMetadataImageWasmPlugin, "createMetadataImageWasmPlugin");
 function collectSSRExternalPackages(ssrBundle) {
   const emittedFiles = new Set(
     Object.keys(ssrBundle).map((fileName) => fileName.replace(/^\.\//, ""))
@@ -863,6 +919,9 @@ async function buildUniversal(config, routeManager, apiRouteManager, serverRende
     }
     const { bundle: ssrBundle, entryFile: ssrEntryFile, configuredHeaderRoutes } = ssrResult;
     await writeSSRAssetsToClient(ssrBundle, clientOutputDir);
+    if (config.docs.enabled) {
+      await copyFarmDocsFontAssetsToClient(root, clientOutputDir);
+    }
     logger.info(`\u{1F680} Building server with Nitro (preset: ${preset})...`);
     await buildNitroUniversal(
       config,
@@ -917,6 +976,17 @@ async function writeSSRAssetsToClient(bundle, outputDir) {
   }
 }
 __name(writeSSRAssetsToClient, "writeSSRAssetsToClient");
+async function copyFarmDocsFontAssetsToClient(root, outputDir) {
+  const fs = await import("fs/promises");
+  await Promise.all(
+    resolveFarmDocsFontAssets(root).map(async ({ sourcePath, url }) => {
+      const targetPath = path3.join(outputDir, url.replace(/^\/+/, ""));
+      await fs.mkdir(path3.dirname(targetPath), { recursive: true });
+      await fs.copyFile(sourcePath, targetPath);
+    })
+  );
+}
+__name(copyFarmDocsFontAssetsToClient, "copyFarmDocsFontAssetsToClient");
 async function mergeBuiltFontCss(outputDir, fontCssSource) {
   const fs = await import("fs/promises");
   const fontCssPath = path3.join(outputDir, "farm-fonts.css");
@@ -935,11 +1005,8 @@ async function mergeBuiltFontCss(outputDir, fontCssSource) {
   } catch {
   }
   const normalizedFontCss = typeof fontCss === "string" ? fontCss : Buffer.from(fontCss).toString("utf8");
+  await fs.writeFile(fontCssPath, normalizedFontCss);
   await fs.writeFile(clientCssPath, mergeFarmFontCss(clientCss, normalizedFontCss));
-  try {
-    await fs.rm(fontCssPath, { force: true });
-  } catch {
-  }
 }
 __name(mergeBuiltFontCss, "mergeBuiltFontCss");
 var _IncompleteClientBuildOutputError = class _IncompleteClientBuildOutputError extends Error {
@@ -1004,7 +1071,11 @@ async function buildClient(productionVite, config, root, srcDir, outputDir, page
       const metadata = getClientModuleMetadata(route.modulePath, root);
       if (metadata.shouldHydrate) {
         const relativePath = route.modulePath.replace(root, "").replace(/^\//, "");
-        clientPages.push({ ...route, relativePath });
+        clientPages.push({
+          ...route,
+          relativePath,
+          islandStrategy: metadata.islandStrategy ?? "load"
+        });
         logger.info(`\u{1F4F1} Found hydratable route: ${route.pattern} -> ${route.modulePath}`);
       }
     } catch (error) {
@@ -1078,13 +1149,14 @@ async function buildClient(productionVite, config, root, srcDir, outputDir, page
           },
           output: {
             entryFileNames: "[name].js",
-            chunkFileNames: "chunks/[name]-[hash].js",
+            chunkFileNames: "chunks/[name]-h[hash].js",
+            hashCharacters: "hex",
             // Use predictable name for CSS so we can reference it in SSR HTML
             assetFileNames: /* @__PURE__ */ __name((assetInfo) => {
               if (assetInfo.name?.endsWith(".css")) {
                 return "farm-client.css";
               }
-              return "assets/[name]-[hash][extname]";
+              return "assets/[name]-h[hash][extname]";
             }, "assetFileNames")
           },
           // Externalize Node.js built-ins and server-side modules for client build
@@ -1683,10 +1755,13 @@ document.addEventListener("click", function(e) {
   const imports = [];
   const routeEntries = [];
   const routeSlotEntries = [];
-  clientPages.forEach((page, index) => {
+  clientPages.forEach((page) => {
     const importPath = toImportPath(page.modulePath);
-    imports.push(`import Page${index} from "${importPath}";`);
-    routeEntries.push(`  { pattern: ${JSON.stringify(page.pattern)}, Component: Page${index} }`);
+    routeEntries.push(`  {
+    pattern: ${JSON.stringify(page.pattern)},
+    islandStrategy: ${JSON.stringify(page.islandStrategy)},
+    load: () => import(${JSON.stringify(importPath)}).then((module) => module.default),
+  }`);
   });
   clientRouteSlots.forEach((slot, index) => {
     const importPath = toImportPath(slot.modulePath);
@@ -1707,7 +1782,7 @@ ${cssImport}
 ${layoutImports}
 import React from "react";
 import { createRoot, hydrateRoot } from "react-dom/client";
-import { createClientPluginManager, installChunkErrorRecovery } from "@farm.js/core/internal/client-runtime";
+import { createClientPluginManager, installChunkErrorRecovery, scheduleFarmIslandHydration } from "@farm.js/core/internal/client-runtime";
 import { matchFarmRoute } from "@farm.js/core/router";
 ${clientPluginEntry.imports}
 ${i18nClientRuntime}
@@ -1780,6 +1855,12 @@ function matchRoute(pathname) {
   return null;
 }
 
+async function loadRouteComponent(route) {
+  if (route.Component) return route.Component;
+  route.Component = await route.load();
+  return route.Component;
+}
+
 function matchesRoutePrefix(pathname, pattern) {
   if (pattern === "/") return true;
   const pathSegments = getFarmRoutePathname(pathname).split("/").filter(Boolean);
@@ -1922,15 +2003,24 @@ function clearRouteInterception(destination) {
 
 // State
 let reactRoot = null;
+let reactRootContainer = null;
 let currentPathname = null;
 let isHydrated = false;
+let pendingPageHydrationController = null;
 
 ${generateUniversalRouterStateRuntime()}
 
+function cancelPendingPageHydration() {
+  pendingPageHydrationController?.abort();
+  pendingPageHydrationController = null;
+}
+
 function resetReactRoot() {
+  cancelPendingPageHydration();
   if (!reactRoot) return;
   reactRoot.unmount();
   reactRoot = null;
+  reactRootContainer = null;
   isHydrated = false;
 }
 
@@ -1944,49 +2034,77 @@ async function hydrate() {
     return;
   }
   
-  const hasRouteSlots =
-    Array.isArray(window.__FARM_ROUTE_SLOTS__) && window.__FARM_ROUTE_SLOTS__.length > 0;
   const container =
-    (hasRouteSlots ? document.getElementById("__farm_page__") : null) ||
+    document.getElementById("__farm_page__") ||
     document.getElementById("root");
   if (!container) {
     console.error("[Farm.js] No root element found");
     return;
   }
   
-  const Component = matched.route.Component;
-  const params = matched.params;
-  const searchParams = Object.fromEntries(new URLSearchParams(window.location.search));
-  
-  const props = { params: params, searchParams: Promise.resolve(searchParams) };
-  
-  // Create page element and wrap with layouts
-  const pageElement = React.createElement(Component, props);
-  const wrappedElement = hasRouteSlots
-    ? pageElement
-    : wrapWithLayouts(pageElement, pathname, params);
-
-  const shouldHydrate = !isHydrated && Boolean(container.innerHTML.trim());
-  const hydrationSession = await farmClientRuntime.beginHydration({
-    container,
-    mode: shouldHydrate ? "hydrate" : "render",
-  });
+  container.dataset.farmIsland = "page";
+  container.dataset.farmIslandStrategy = matched.route.islandStrategy || "load";
 
+  const hydrationController = new AbortController();
+  pendingPageHydrationController = hydrationController;
   try {
-    if (shouldHydrate) {
-      reactRoot = hydrateRoot(container, wrappedElement);
-      isHydrated = true;
-    } else {
-      if (!reactRoot) {
-        reactRoot = createRoot(container);
-      }
-      reactRoot.render(wrappedElement);
+    await scheduleFarmIslandHydration({
+      container,
+      strategy: matched.route.islandStrategy,
+      signal: hydrationController.signal,
+      hydrate: async function() {
+        const Component = await loadRouteComponent(matched.route);
+        if (
+          hydrationController.signal.aborted ||
+          !container.isConnected ||
+          window.location.pathname !== pathname
+        ) {
+          return;
+        }
+        const params = matched.params;
+        const searchParams = Object.fromEntries(new URLSearchParams(window.location.search));
+        const props = { params: params, searchParams: Promise.resolve(searchParams) };
+        const pageElement = React.createElement(Component, props);
+        const wrappedElement = container.id === "__farm_page__"
+          ? pageElement
+          : wrapWithLayouts(pageElement, pathname, params);
+        const shouldHydrate = !isHydrated && Boolean(container.innerHTML.trim());
+        const hydrationSession = await farmClientRuntime.beginHydration({
+          container,
+          mode: shouldHydrate ? "hydrate" : "render",
+        });
+
+        try {
+          if (hydrationController.signal.aborted || !container.isConnected) {
+            await farmClientRuntime.failHydration(
+              hydrationSession,
+              new DOMException("Route hydration was cancelled", "AbortError"),
+            );
+            return;
+          }
+          if (shouldHydrate) {
+            reactRoot = hydrateRoot(container, wrappedElement);
+            reactRootContainer = container;
+            isHydrated = true;
+          } else {
+            if (!reactRoot) {
+              reactRoot = createRoot(container);
+              reactRootContainer = container;
+            }
+            reactRoot.render(wrappedElement);
+          }
+          currentPathname = pathname;
+          await farmClientRuntime.completeHydration(hydrationSession);
+        } catch (error) {
+          await farmClientRuntime.failHydration(hydrationSession, error);
+          console.error("[Farm.js] Hydration error:", error);
+        }
+      },
+    });
+  } finally {
+    if (pendingPageHydrationController === hydrationController) {
+      pendingPageHydrationController = null;
     }
-    currentPathname = pathname;
-    await farmClientRuntime.completeHydration(hydrationSession);
-  } catch (error) {
-    await farmClientRuntime.failHydration(hydrationSession, error);
-    console.error("[Farm.js] Hydration error:", error);
   }
 }
 
@@ -2015,6 +2133,8 @@ ${generateUniversalRouterStateProperties()}
     const from = this.currentPath;
     if (await this.shouldBlockNavigation({ from, to, action })) return;
 
+    // A route transition invalidates any trigger waiting on the previous DOM boundary.
+    cancelPendingPageHydration();
     this.saveScrollPosition(window.location.pathname);
     this.startNavigation(from, url, action);
     let clientNavigation;
@@ -2081,7 +2201,9 @@ ${generateUniversalRouterStateProperties()}
       }
 
       if (matched) {
-        const Component = matched.route.Component;
+        // Navigation itself signals intent, so destination routes load eagerly even
+        // when their initial document hydration strategy is deferred.
+        const Component = await loadRouteComponent(matched.route);
         const params = matched.params;
         const searchParams = Object.fromEntries(url.searchParams);
         const props = { params: params, searchParams: Promise.resolve(searchParams) };
@@ -2107,8 +2229,10 @@ ${generateUniversalRouterStateProperties()}
 
           const container = document.getElementById("root");
           if (container) {
+            if (reactRoot && reactRootContainer !== container) resetReactRoot();
             if (!reactRoot) {
               reactRoot = createRoot(container);
+              reactRootContainer = container;
             }
             reactRoot.render(wrappedElement);
             currentPathname = pathname;
@@ -2118,7 +2242,7 @@ ${generateUniversalRouterStateProperties()}
         const html = await this.fetchPage(url.pathname + url.search);
         await farmClientRuntime.markNavigationLoaded(clientNavigation, html);
         await this.runViewTransition(options.viewTransition, async () => {
-          if (!this.swapContent(html, url.pathname + url.search)) {
+          if (!(await this.swapContent(html, url.pathname + url.search))) {
             throw new Error("Farm could not swap the target document");
           }
           const historyState = createHistoryState(
@@ -2173,7 +2297,7 @@ ${generateUniversalRouterStateProperties()}
     return html;
   },
   
-  swapContent: function(html, targetPath) {
+  swapContent: async function(html, targetPath) {
     const parser = new DOMParser();
     const doc = parser.parseFromString(html, "text/html");
     if (isFarmLocaleDocumentChange(doc)) return false;
@@ -2213,18 +2337,18 @@ ${generateUniversalRouterStateProperties()}
     const matched = matchRoute(newPathname);
     if (matched) {
       // Re-hydrate the client component
-      const Component = matched.route.Component;
+      const Component = await loadRouteComponent(matched.route);
       const params = matched.params;
       const searchParams = Object.fromEntries(targetUrl.searchParams);
       const props = { params: params, searchParams: Promise.resolve(searchParams) };
       const pageElement = React.createElement(Component, props);
-      const hasRouteSlots = nextRouteSlots.length > 0;
       const pageContainer =
-        (hasRouteSlots ? document.getElementById("__farm_page__") : null) || currentRoot;
-      const wrappedElement = hasRouteSlots
+        document.getElementById("__farm_page__") || currentRoot;
+      const wrappedElement = pageContainer.id === "__farm_page__"
         ? pageElement
         : wrapWithLayouts(pageElement, newPathname, params);
       reactRoot = hydrateRoot(pageContainer, wrappedElement);
+      reactRootContainer = pageContainer;
       isHydrated = true;
     }
     return true;
@@ -2515,6 +2639,10 @@ async function buildSSRInMemory(productionVite, config, root, routeManager, apiR
     i18nCatalogs
   );
   const virtualEntryId = "\0virtual:farm-ssr-entry";
+  const useExternalMetadataImageRuntime = shouldUseExternalMetadataImageRuntime(
+    preset,
+    metadataImageRoutes.some((image) => image.sourceType === "module")
+  );
   try {
     await viteBuild({
       root,
@@ -2535,6 +2663,7 @@ async function buildSSRInMemory(productionVite, config, root, routeManager, apiR
           external: [
             "fsevents",
             "sharp",
+            ...useExternalMetadataImageRuntime ? ["@vercel/og"] : [],
             "@prisma/client",
             "@prisma/client/default",
             "@prisma/client/default.js",
@@ -2563,6 +2692,7 @@ async function buildSSRInMemory(productionVite, config, root, routeManager, apiR
         external: [
           "fsevents",
           "sharp",
+          ...useExternalMetadataImageRuntime ? ["@vercel/og"] : [],
           "esbuild",
           "lightningcss",
           "rollup",
@@ -2589,7 +2719,12 @@ async function buildSSRInMemory(productionVite, config, root, routeManager, apiR
         // React runtime. Leaving a React component package external can make it
         // resolve a second React instance at runtime and break hooks during SSR.
         // Native and build-only packages above remain explicitly external.
-        noExternal: preset === "cloudflare-module" ? ["@farm.js/core", "@farm.js/core/image", "better-call"] : true
+        noExternal: preset === "cloudflare-module" ? [
+          "@farm.js/core",
+          "@farm.js/core/image",
+          "better-call",
+          ...metadataImageRoutes.some((image) => image.sourceType === "module") ? ["@vercel/og"] : []
+        ] : true
       },
       define: {
         __FARM_ENV__: JSON.stringify(config.env || { server: {}, public: {} }),
@@ -2597,6 +2732,7 @@ async function buildSSRInMemory(productionVite, config, root, routeManager, apiR
       },
       plugins: [
         ...tailwindVitePlugin ? [tailwindVitePlugin] : [],
+        ...!useExternalMetadataImageRuntime && metadataImageRoutes.some((image) => image.sourceType === "module") ? [createMetadataImageWasmPlugin()] : [],
         {
           name: "farm-react-production-mode",
           enforce: "pre",
@@ -2675,8 +2811,12 @@ async function buildSSRInMemory(productionVite, config, root, routeManager, apiR
 __name(buildSSRInMemory, "buildSSRInMemory");
 function generateVirtualEntryCode(apiRoutes, pageRoutes, layoutRoutes, routeSlots, errorRoutes, metadataImageRoutes, middlewareRoutes, redirectRoutes, configuredRewriteRoutes, configuredHeaderRoutes, notFoundPath, config, configModulePath, hasServerRuntimeIntegrations, hasRuntimeIntegrationConfig, hasConfiguredRuntimePlugins, preset, i18nCatalogs) {
   const hasPluginRuntime = hasRuntimeIntegrationConfig || hasConfiguredRuntimePlugins;
+  const hasGeneratedMetadataImages = metadataImageRoutes.some(
+    (image) => image.sourceType === "module"
+  );
   const hasMiddlewareRuntime = middlewareRoutes.length > 0 || hasFarmMiddlewareConfig(config.middleware);
   const farmDocsBaseConfig = config.docs?.enabled ? { ...config.docs, config: void 0 } : void 0;
+  const farmDocsFontAssets = config.docs?.enabled ? toFarmDocsPublicFontAssets(resolveFarmDocsFontAssets(config.root)) : [];
   const apiImports = [];
   const apiRegistrations = [];
   apiRoutes.forEach((route, index) => {
@@ -2715,12 +2855,13 @@ function generateVirtualEntryCode(apiRoutes, pageRoutes, layoutRoutes, routeSlot
       return;
     }
     pageImports.push(`import * as ${varName} from "${route.modulePath}";`);
-    const shouldHydrate = getClientModuleMetadata(route.modulePath, config.root).shouldHydrate;
+    const clientMetadata = getClientModuleMetadata(route.modulePath, config.root);
     pageRegistrations.push(`
   {
     pattern: ${JSON.stringify(route.pattern)},
     module: ${varName},
-    shouldHydrate: ${JSON.stringify(shouldHydrate)},
+    shouldHydrate: ${JSON.stringify(clientMetadata.shouldHydrate)},
+    islandStrategy: ${JSON.stringify(clientMetadata.islandStrategy)},
     ${route.source !== void 0 ? `markdownSource: {
       source: ${JSON.stringify(route.source)},
       filePath: ${JSON.stringify(route.markdownSourcePath)},
@@ -2818,16 +2959,21 @@ function generateVirtualEntryCode(apiRoutes, pageRoutes, layoutRoutes, routeSlot
   isFarmRedirectError,
   localizeFarmHref,
   localizeFarmPathname,
+  manageFarmDocumentPreloads,
+  manageFarmLinkHeaderPreloads,
   mergeMetadata,
   normalizeRevalidatePath,
+  reportFarmPreloadWarnings,
   renderMetadataHead,
   resolveFarmRouteContext,
   stripFarmLocaleFromPathname,
   withFarmRouteContext,
 } from "@farm.js/core/internal/production-runtime";`;
+  const metadataImageRuntimeImport = hasGeneratedMetadataImages ? `import { createFarmMetadataImageResponse } from "@farm.js/core/internal/metadata-image-runtime";` : "";
   const pluginRuntimeImport = hasPluginRuntime ? `import { PluginManager } from "@farm.js/core/plugin";` : "";
   const i18nServerImport = config.i18n.enabled ? `import { _runWithFarmI18nRequest, _setDefaultFarmI18nRuntime, createFarmI18nRuntime, getFarmI18nClientSnapshot } from "@farm.js/core/i18n/server";` : "";
   const docsHandlerImport = config.docs?.enabled ? `import { createFarmDocsAPIHandler, createFarmDocsHandler, isFarmDocsAPIRequest } from "@farm.js/core/docs";` : "";
+  const docsFontImport = config.docs?.enabled ? `import { resolveFarmLayoutFonts } from "@farm.js/core/font";` : "";
   const docsRuntimeImport = config.docs?.enabled ? `import { existsSync as farmDocsExistsSync } from "node:fs";
 import { dirname as farmDocsDirname, join as farmDocsJoin } from "node:path";
 import { fileURLToPath as farmDocsFileURLToPath } from "node:url";` : "";
@@ -2915,9 +3061,11 @@ ${middlewareImports.join("\n")}
 ${notFoundImport}
 ${apiRouteHelpersImport}
 ${productionRuntimeImport}
+${metadataImageRuntimeImport}
 ${pluginRuntimeImport}
 ${i18nServerImport}
 ${docsHandlerImport}
+${docsFontImport}
 ${docsRuntimeImport}
 ${markdownHandlerImport}
 ${appMarkdownImport}
@@ -2929,6 +3077,8 @@ import { farmFontPreloadHeader } from "virtual:farm-font-runtime";
 import * as React from "react";
 import * as ReactDOMServer from "react-dom/server";
 
+const farmPreloadConfig = ${JSON.stringify(config.performance.preload)};
+
 // Custom 404 page component (if provided)
 const hasCustomNotFound = ${notFoundPath ? "true" : "false"};
 const CustomNotFoundComponent = ${notFoundPath ? "CustomNotFound.default || CustomNotFound" : "null"};
@@ -3020,7 +3170,17 @@ globalThis.__FARM_DOCS_RUNTIME_CONFIG__ = {
   srcDir: ${JSON.stringify(config.srcDir)},
   docs: farmDocsResolvedConfig,
 };
-const farmDocsHandler = ${config.docs?.enabled ? `createFarmDocsHandler(farmDocsResolvedConfig, { root: farmDocsRuntimeRoot, srcDir: ${JSON.stringify(config.srcDir)}, clientEntry: "/farm-client.js" })` : "null"};
+const farmDocsHandler = ${config.docs?.enabled ? `createFarmDocsHandler(farmDocsResolvedConfig, {
+  root: farmDocsRuntimeRoot,
+  srcDir: ${JSON.stringify(config.srcDir)},
+  clientEntry: "/farm-client.js",
+  fontAssets: ${JSON.stringify(farmDocsFontAssets)},
+  resolveLayoutFonts: (pathname) =>
+    resolveFarmLayoutFonts(
+      getApplicableLayouts(getFarmRoutePathname(pathname)).map((layout) => layout.module),
+    ),
+  fontStylesheetHref: "/farm-fonts.css",
+})` : "null"};
 const farmDocsAPIHandler = ${config.docs?.enabled ? `createFarmDocsAPIHandler({ rootDir: farmDocsRuntimeRoot, srcDir: ${JSON.stringify(config.srcDir)}, docs: farmDocsResolvedConfig })` : "null"};
 
 // API routes bundled at build time
@@ -3681,30 +3841,10 @@ async function handleMetadataImageRequest(request, routePathname) {
       ? await imageModule.default(props)
       : imageModule.default;
 
-    if (value instanceof Response) {
-      return method === "HEAD"
-        ? new Response(null, { status: value.status, headers: value.headers })
-        : value;
-    }
-
-    let body;
-    if (typeof value === "string" || value instanceof ArrayBuffer || ArrayBuffer.isView(value)) {
-      body = value;
-    } else {
-      if (!React.isValidElement(value)) {
-        throw new Error("Metadata image must return a Response, string, bytes, or React element");
-      }
-      body = ReactDOMServer.renderToStaticMarkup(value);
-    }
-
-    return new Response(method === "HEAD" ? null : body, {
-      status: 200,
-      headers: {
-        "Content-Type": imageModule.contentType || "image/svg+xml; charset=utf-8",
-        "Cache-Control": "public, max-age=0, must-revalidate",
-        "X-Content-Type-Options": "nosniff",
-      },
-    });
+    ${hasGeneratedMetadataImages ? `return createFarmMetadataImageResponse(value, imageModule, {
+      method,
+      ifNoneMatch: request.headers.get("if-none-match"),
+    });` : 'throw new Error("Generated metadata image runtime is unavailable");'}
   } catch (error) {
     console.error("Metadata image render failed:", error);
     return new Response("Internal Server Error", {
@@ -4240,7 +4380,16 @@ async function handleFarmRequestInContext(
   if (farmDocsHandler) {
     const docsResponse = await farmDocsHandler(request.clone());
     if (docsResponse) {
-      return docsResponse;
+      if (!docsResponse.headers.get("content-type")?.toLowerCase().includes("text/html")) {
+        return docsResponse;
+      }
+      const docsHeaders = new Headers(docsResponse.headers);
+      docsHeaders.set("x-farm-preload-buffered", "1");
+      return new Response(docsResponse.body, {
+        status: docsResponse.status,
+        statusText: docsResponse.statusText,
+        headers: docsHeaders,
+      });
     }
   }
   ` : ""}
@@ -4368,6 +4517,7 @@ async function handleFarmRequestInContext(
             status: 200,
             headers: {
               "Content-Type": "text/html; charset=utf-8",
+              "x-farm-preload-buffered": "1",
               ...(farmFontPreloadHeader ? { "Link": farmFontPreloadHeader } : {}),
               ...getPPRHeaders("hit", pprConfig),
             },
@@ -4595,10 +4745,15 @@ async function handleFarmRequestInContext(
               pageElement = React.createElement(PageComponent, pageProps);
             }
 
-            if (route.shouldHydrate && renderedRouteSlots.length > 0) {
+            if (route.shouldHydrate) {
               pageElement = React.createElement(
                 "div",
-                { id: "__farm_page__", "data-farm-client": "true" },
+                {
+                  id: "__farm_page__",
+                  "data-farm-client": "true",
+                  "data-farm-island": "page",
+                  "data-farm-island-strategy": route.islandStrategy || "load",
+                },
                 pageElement,
               );
             }
@@ -4749,7 +4904,7 @@ async function handleFarmRequestInContext(
           );
           return applyProductionMiddlewareHeaders(new Response(streamedDocument, {
             status: pageStatus,
-            headers: responseHeaders,
+            headers: { ...responseHeaders, "x-farm-preload-streaming": "1" },
           }), middlewareHeaders);
         }
 
@@ -4850,7 +5005,7 @@ async function handleFarmRequestInContext(
           fullHtml,
           { 
             status: pageStatus,
-            headers: responseHeaders
+            headers: { ...responseHeaders, "x-farm-preload-buffered": "1" }
           }
         ), middlewareHeaders);
       }
@@ -4954,6 +5109,7 @@ async function handleFarmRequestInContext(
             headers: {
               "Content-Type": "text/html; charset=utf-8",
               "Cache-Control": "private, no-store",
+              "x-farm-preload-buffered": "1",
             },
           }), middlewareHeaders);
         } catch (boundaryError) {
@@ -4976,6 +5132,7 @@ async function handleFarmRequestInContext(
           headers: {
             "Content-Type": "text/html; charset=utf-8",
             "Cache-Control": "private, no-store",
+            "x-farm-preload-buffered": "1",
           },
         }
       ), middlewareHeaders);
@@ -5122,13 +5279,19 @@ async function handleFarmRequestInContext(
 
     return applyProductionMiddlewareHeaders(new Response(fullHtml, {
       status: 404,
-      headers: { "Content-Type": "text/html; charset=utf-8" }
+      headers: {
+        "Content-Type": "text/html; charset=utf-8",
+        "x-farm-preload-buffered": "1",
+      }
     }), middlewareHeaders);
   } catch (error) {
     console.error("404 render error:", error);
     return applyProductionMiddlewareHeaders(new Response(
       \`<!DOCTYPE html><html><head><title>404</title></head><body><h1>404 - Page Not Found</h1><p>The page \${pathname} doesn't exist.</p><a href="/">Go Home</a></body></html>\`,
-      { status: 404, headers: { "Content-Type": "text/html" } }
+      {
+        status: 404,
+        headers: { "Content-Type": "text/html", "x-farm-preload-buffered": "1" },
+      }
     ), middlewareHeaders);
   }
   ${hasMiddlewareRuntime ? `
@@ -5170,7 +5333,10 @@ async function handleFarmPluginRequest(request, runtimeOptions) {
   await farmPluginRuntime.runHookParallel("beforeRender", renderPayload);
 
   const response = await handleFarmRequest(request);
-  if (!hasFarmPluginHTMLTransforms || !response.headers.get("content-type")?.includes("text/html")) {
+  if (
+    !hasFarmPluginHTMLTransforms ||
+    !response.headers.get("content-type")?.toLowerCase().includes("text/html")
+  ) {
     return response;
   }
 
@@ -5180,6 +5346,8 @@ async function handleFarmPluginRequest(request, runtimeOptions) {
 
   const headers = new Headers(response.headers);
   headers.delete("content-length");
+  headers.delete("x-farm-preload-streaming");
+  headers.set("x-farm-preload-buffered", "1");
   return new Response(html, {
     status: response.status,
     statusText: response.statusText,
@@ -5187,6 +5355,49 @@ async function handleFarmPluginRequest(request, runtimeOptions) {
   });
 }
 
+async function applyFarmPreloadBudget(response, pathname) {
+  const headers = new Headers(response.headers);
+  const linkHeader = headers.get("Link") || "";
+  const isHtml = headers.get("Content-Type")?.toLowerCase().includes("text/html");
+  const isStreaming = headers.get("x-farm-preload-streaming") === "1";
+  const isBuffered = headers.get("x-farm-preload-buffered") === "1";
+  headers.delete("x-farm-preload-streaming");
+  headers.delete("x-farm-preload-buffered");
+
+  if (!isHtml) {
+    if (!isStreaming && !isBuffered) return response;
+    return new Response(response.body, {
+      status: response.status,
+      statusText: response.statusText,
+      headers,
+    });
+  }
+
+  if (isStreaming || !isBuffered || response.body === null) {
+    const managed = manageFarmLinkHeaderPreloads(linkHeader, farmPreloadConfig);
+    if (managed.value) headers.set("Link", managed.value);
+    else headers.delete("Link");
+    reportFarmPreloadWarnings(managed.warnings, "route " + pathname);
+    return new Response(response.body, {
+      status: response.status,
+      statusText: response.statusText,
+      headers,
+    });
+  }
+
+  const html = await response.text();
+  const managed = manageFarmDocumentPreloads(html, linkHeader, farmPreloadConfig);
+  if (managed.linkHeader) headers.set("Link", managed.linkHeader);
+  else headers.delete("Link");
+  if (managed.html !== html) headers.delete("Content-Length");
+  reportFarmPreloadWarnings(managed.warnings, "route " + pathname);
+  return new Response(managed.html, {
+    status: response.status,
+    statusText: response.statusText,
+    headers,
+  });
+}
+
 // Export as Web Standard fetch API
 export async function fetch(request, context) {
   const runtimeOptions = farmPluginRuntime ? getFarmPluginRequestOptions(request) : null;
@@ -5209,7 +5420,8 @@ export async function fetch(request, context) {
   const response = await _runWithCurrentRequest(request, () =>
     _runWithAfterRequest(request, runRequest, context),
   );
-  return applyConfiguredResponseHeaders(response, new URL(request.url).pathname);
+  const pathname = new URL(request.url).pathname;
+  return applyFarmPreloadBudget(applyConfiguredResponseHeaders(response, pathname), pathname);
 }
 export default { fetch };
   `.trim();
@@ -5365,8 +5577,19 @@ async function buildNitroUniversal(config, routeManager, apiRouteManager, server
   const outputDir = resolveDeployOutputPath(root, config.deploy.outputDir);
   const ssrOutputDir = path3.join(root, distDir, "ssr");
   const imageRuntime = resolveImageRuntime(config, preset);
+  const hasGeneratedMetadataImages = Array.from(routeManager.getMetadataImages().values()).some(
+    (image) => image.sourceType === "module"
+  );
+  const useExternalMetadataImageRuntime = shouldUseExternalMetadataImageRuntime(
+    preset,
+    hasGeneratedMetadataImages
+  );
+  const nitroRollupExternal = /* @__PURE__ */ __name((id) => useExternalMetadataImageRuntime && id === "@vercel/og" || isNitroRollupExternal(id), "nitroRollupExternal");
   const ssrExternalPackages = collectSSRExternalPackages(ssrBundle);
-  const copiedRuntimePackages = new Set(imageRuntime === "node" ? ["sharp"] : []);
+  const copiedRuntimePackages = /* @__PURE__ */ new Set([
+    ...imageRuntime === "node" ? ["sharp"] : [],
+    ...useExternalMetadataImageRuntime ? ["@vercel/og"] : []
+  ]);
   const isPrebuiltSSRCandidate = preset === "node-server" && [...ssrExternalPackages].every((packageName) => copiedRuntimePackages.has(packageName));
   logger.info(`\u{1F4E6} Nitro output directory: ${outputDir}`);
   logger.info(`\u{1F4E6} SSR entry file: ${ssrEntryFile}`);
@@ -5582,11 +5805,13 @@ export default async function farmNitroEventHandler(event) {
         ".prisma/client",
         ".prisma/client/default",
         "better-sqlite3",
-        "sharp"
+        "sharp",
+        ...useExternalMetadataImageRuntime ? ["@vercel/og"] : []
       ]
     },
     rollupConfig: {
-      external: isNitroRollupExternal
+      external: nitroRollupExternal,
+      plugins: hasGeneratedMetadataImages && !useExternalMetadataImageRuntime ? [createMetadataImageWasmPlugin()] : []
     },
     // Keep the public Nitro boolean intact for build hooks. It is translated to
     // Nitro's existing esbuild pass after hooks run, avoiding a second Terser pass.
@@ -5614,7 +5839,7 @@ export default async function farmNitroEventHandler(event) {
     snapshotSSRRebundleOptions(nitroConfig)
   );
   const requestedBuilder = nitroConfig.builder ?? process.env.NITRO_BUILDER;
-  const canReusePrebuiltSSR = isPrebuiltSSRCandidate && nitroConfig.preset === "node-server" && (requestedBuilder === void 0 || requestedBuilder === "rollup" || requestedBuilder === "rolldown") && nitroConfig.sourceMap === false && !hasUnsupportedEsbuildOverrides && !hasLateBuildMutationConfig && !hasUnsupportedSSRRebundleOverrides && nitroConfig.rollupConfig?.external === isNitroRollupExternal && !hasRollupPlugins(nitroConfig.rollupConfig?.plugins) && customRollupKeys.length === 0 && path3.resolve(nitroConfig.output?.serverDir || "") === path3.resolve(expectedServerDir) && Boolean(
+  const canReusePrebuiltSSR = isPrebuiltSSRCandidate && nitroConfig.preset === "node-server" && (requestedBuilder === void 0 || requestedBuilder === "rollup" || requestedBuilder === "rolldown") && nitroConfig.sourceMap === false && !hasUnsupportedEsbuildOverrides && !hasLateBuildMutationConfig && !hasUnsupportedSSRRebundleOverrides && nitroConfig.rollupConfig?.external === nitroRollupExternal && !hasRollupPlugins(nitroConfig.rollupConfig?.plugins) && customRollupKeys.length === 0 && path3.resolve(nitroConfig.output?.serverDir || "") === path3.resolve(expectedServerDir) && Boolean(
     nitroConfig.handlers?.some(
       (handler) => path3.resolve(handler?.handler || "") === nitroEntryPath
     )
@@ -5702,7 +5927,8 @@ export default async function farmNitroEventHandler(event) {
       effectiveMinify,
       fs
     ) : Promise.resolve(),
-    imageRuntime === "node" ? copySharpRuntime(config, root, path3.join(outputDir, "server"), fs) : Promise.resolve()
+    imageRuntime === "node" ? copySharpRuntime(config, root, path3.join(outputDir, "server"), fs) : Promise.resolve(),
+    useExternalMetadataImageRuntime ? copyMetadataImageRuntime(root, path3.join(outputDir, "server"), fs) : Promise.resolve()
   ]);
   const failedCopy = copyResults.find(
     (result) => result.status === "rejected"
@@ -5814,6 +6040,9 @@ async function postProcessVercelOutput(root, outputDir, fs, config, farmWorkflow
     fs
   );
   vercelConfig.routes = [
+    // Apply the header before the filesystem handler. `continue` lets Vercel
+    // serve the matching file while preserving the immutable cache policy.
+    createFarmVercelImmutableAssetRoute(config.basePath),
     // Serve static files first
     {
       handle: "filesystem"
@@ -5931,6 +6160,42 @@ async function copySharpRuntime(config, root, nitroFuncDir, fs) {
   logger.info(`\u{1F5BC}\uFE0F  Bundled Sharp image runtime (${copiedPackages.size} packages)`);
 }
 __name(copySharpRuntime, "copySharpRuntime");
+async function copyMetadataImageRuntime(root, nitroFuncDir, fs) {
+  const projectRequire = createRequire(path3.join(root, "package.json"));
+  let runtimeRequire = projectRequire;
+  let packageJsonPath = resolvePackageJson(runtimeRequire, "@vercel/og");
+  if (!packageJsonPath) {
+    try {
+      runtimeRequire = createRequire(projectRequire.resolve("@farm.js/core"));
+      packageJsonPath = resolvePackageJson(runtimeRequire, "@vercel/og");
+    } catch {
+    }
+  }
+  if (!packageJsonPath) {
+    throw new Error(
+      "Generated metadata images require @vercel/og. Reinstall @farm.js/core with production dependencies."
+    );
+  }
+  const packageJson = JSON.parse(await fs.readFile(packageJsonPath, "utf8"));
+  const packageDir = path3.dirname(packageJsonPath);
+  const targetDir = path3.join(nitroFuncDir, "node_modules", "@vercel", "og");
+  await fs.mkdir(path3.dirname(targetDir), { recursive: true });
+  await fs.cp(packageDir, targetDir, {
+    recursive: true,
+    force: true,
+    dereference: true,
+    mode: fsConstants.COPYFILE_FICLONE
+  });
+  const functionPackagePath = path3.join(nitroFuncDir, "package.json");
+  const functionPackage = JSON.parse(await fs.readFile(functionPackagePath, "utf8"));
+  functionPackage.dependencies = {
+    ...functionPackage.dependencies,
+    "@vercel/og": String(packageJson.version || "0.11.1")
+  };
+  await fs.writeFile(functionPackagePath, JSON.stringify(functionPackage, null, 2));
+  logger.info("\u{1F5BC}\uFE0F  Bundled generated metadata image runtime");
+}
+__name(copyMetadataImageRuntime, "copyMetadataImageRuntime");
 function resolvePackageJson(parentRequire, packageName) {
   for (const request of [`${packageName}/package.json`, `${packageName}/package`]) {
     try {
@@ -6320,4 +6585,4 @@ __name(buildNitro, "buildNitro");
 export {
   build
 };
-//# sourceMappingURL=chunk-DTOWEQRV.mjs.map
+//# sourceMappingURL=chunk-VSDZEB5M.mjs.map