@farm.js/core 0.1.51-beta.3 → 0.1.60

package/dist/{chunk-NOTSHVRN.mjs → chunk-T7I62A4C.mjs}

@@ -24,14 +24,14 @@ import {
 } from "./chunk-KQH2COEJ.mjs";
 import {
   FARM_MOBILE_SESSION_PLUGIN
-} from "./chunk-C3BOESDW.mjs";
+} from "./chunk-B4CWYGCG.mjs";
 import {
   assertFarmDocsAdapterServesNoGuardedPages,
   compileFarmDocsAdapterEdgeManifest,
   createFarmDocsAPIHandler,
   hasFarmDocsRuntimeAdapter,
   listFarmDocsAdapterPages
-} from "./chunk-5FXPJIOT.mjs";
+} from "./chunk-F6Y7ZAPQ.mjs";
 import {
   FARM_DOCS_LAST_MODIFIED_MANIFEST,
   createFarmDocsHandler,
@@ -43,7 +43,7 @@ import {
   loadFarmDocsPage,
   resolveFarmDocsContentDir,
   toFarmDocsMarkdownPage
-} from "./chunk-ZD2VKAUI.mjs";
+} from "./chunk-2KTYMMWT.mjs";
 import {
   generateFarmDocsSearchClientRuntime,
   isFarmDocsSearchEnabled,
@@ -51,13 +51,7 @@ import {
 } from "./chunk-ALEUMLJN.mjs";
 import {
   FARM_PRERENDER_ENV
-} from "./chunk-3SMXQNFD.mjs";
-import {
-  resolveFarmInstrumentationFile
-} from "./chunk-N35YPV4N.mjs";
-import {
-  resolveFarmInstrumentationRuntime
-} from "./chunk-WNDAISB7.mjs";
+} from "./chunk-FORSVMEJ.mjs";
 import {
   loadFarmDocsEngine
 } from "./chunk-VE3FWJBO.mjs";
@@ -66,12 +60,21 @@ import {
   getDeployTargetForPreset,
   hasCustomFarmRouteContext,
   resolveDeployOutputPath
-} from "./chunk-GAO7MS5O.mjs";
+} from "./chunk-VPTWKOCY.mjs";
+import {
+  resolveFarmInstrumentationFile
+} from "./chunk-N35YPV4N.mjs";
+import {
+  resolveFarmInstrumentationRuntime
+} from "./chunk-WNDAISB7.mjs";
 import {
   DEFAULT_NOT_FOUND_STYLES,
   FARM_LAYOUT_ELEMENT_CLIENT_SOURCE,
+  FARM_NAVIGATION_STREAM_READER_SOURCE,
   FARM_SERVER_TREE_LAYOUT_CLIENT_SOURCE,
   SHARP_INSTALL_HINT,
+  canBootFarmIslandsClient,
+  collectFarmServerStylesheets,
   collectFarmWebMCPTools,
   createFarmApp,
   createFarmSourceAlias,
@@ -97,13 +100,14 @@ import {
   resolveFarmImageServerRuntime,
   resolveFarmIsolatedClientHydrationMode,
   resolveFarmNotFoundComponentPath,
+  resolveFarmRouteRootStrategy,
   usePackageClientBoundaryCacheFile,
   usesFarmServerTree,
   withPackageClientBoundaryCache
-} from "./chunk-3TLKUBXG.mjs";
+} from "./chunk-ZFUKPWFC.mjs";
 import {
   loadTailwindVitePlugin
-} from "./chunk-PIHKO25G.mjs";
+} from "./chunk-OM7WILES.mjs";
 import {
   PluginManager
 } from "./chunk-GHNW564E.mjs";
@@ -111,7 +115,7 @@ import {
   generateFarmTypeArtifacts,
   readRouteRenderingDirectiveFromFile,
   resolveRouteRenderingConfigFromFile
-} from "./chunk-CZ35L6PL.mjs";
+} from "./chunk-LJVNMGE3.mjs";
 import {
   HOISTED_HEAD_ELEMENT,
   appMiddlewareMayHandlePath,
@@ -124,7 +128,7 @@ import {
   layoutsCanCoverSamePage,
   routeBoundaryCoversDirectory,
   stripRouteGroups
-} from "./chunk-YUEYBL35.mjs";
+} from "./chunk-PCXIJKPM.mjs";
 import {
   FARM_NATIVE_TREE_CONTENT_TYPE
 } from "./chunk-LLZSYFOM.mjs";
@@ -141,18 +145,15 @@ import {
   listFarmBuiltInRoutePaths,
   resolveFarmApiCatalogInput,
   resolveFarmAppManifestInput
-} from "./chunk-4TKAIO2F.mjs";
+} from "./chunk-ZMHAFH4R.mjs";
 import {
   FARM_DEFAULT_MCP_PATH,
   createFarmDefaultMCPServer,
   farmConfigMountsMCP
-} from "./chunk-E5DXF5GE.mjs";
+} from "./chunk-UZZ6IEQP.mjs";
 import {
   farmEnvironmentFunctionsPlugin
 } from "./chunk-ZQ5BDNKW.mjs";
-import {
-  isFarmMarkdownPageFile
-} from "./chunk-3Z63X45F.mjs";
 import {
   generateFarmDocsAdapterClientRuntime,
   getFarmDocsAdapterConfigModule
@@ -180,50 +181,53 @@ import {
   applyFarmCspHashesToHtml,
   createFarmCspNonce
 } from "./chunk-22W4FNTG.mjs";
+import {
+  getFarmAppDirectories
+} from "./chunk-52Y3C3HG.mjs";
 import {
   createBundledEnv
 } from "./chunk-N33DLJBC.mjs";
 import {
-  getFarmAppDirectories
-} from "./chunk-52Y3C3HG.mjs";
+  isFarmMarkdownPageFile
+} from "./chunk-E72UD6ME.mjs";
 import {
   resolveFarmMdxComponentsModulePath,
   resolveMdxConfig
 } from "./chunk-UIJOLBUL.mjs";
+import {
+  getFarmMarkdownAlternatePath
+} from "./chunk-YSXTNSXS.mjs";
 import {
   applyFarmWorkflowVercelCrons,
   prepareFarmWorkflowsForNitro
-} from "./chunk-LZ4SB57H.mjs";
+} from "./chunk-JPIUGDK4.mjs";
 import {
   applyFarmCronVercelCrons,
   createFarmCronCloudflareConfig,
   mergeScheduledTasks,
   prepareFarmCronForNitro
-} from "./chunk-X3JNB2TB.mjs";
+} from "./chunk-3PX4AIXO.mjs";
 import {
   resolveServerActionsConfig
 } from "./chunk-FSQMN2MQ.mjs";
-import {
-  getFarmMarkdownAlternatePath
-} from "./chunk-LPDKG6RA.mjs";
 import {
   _collectFarmStorageModules
 } from "./chunk-TJVUTGED.mjs";
 import {
   getFarmIntegrationPluginServerRuntime,
   getIntegrationProviders
-} from "./chunk-Y2G5SJFB.mjs";
+} from "./chunk-IFHPDLIS.mjs";
 import {
   FARM_INTEGRATION_API_BASE_PATH_KEY
-} from "./chunk-F6TLUMH7.mjs";
+} from "./chunk-M53MIIXY.mjs";
 import {
   appendMiddlewareDirectory,
   appendMiddlewareRoutePath,
   compareMiddlewareRouteLocations
-} from "./chunk-5ENW27SL.mjs";
+} from "./chunk-MMK4MZUN.mjs";
 import {
   APIRouteManager
-} from "./chunk-KY32FWK7.mjs";
+} from "./chunk-BHJAYPYU.mjs";
 import {
   readFarmI18nCatalogs
 } from "./chunk-DU4VHHPJ.mjs";
@@ -243,14 +247,14 @@ import {
   logger,
   toPosixPath,
   toViteModuleId
-} from "./chunk-Y3N5BFRJ.mjs";
+} from "./chunk-JSDV2NUN.mjs";
 import {
   resolveFarmAPIServerBasePath,
   resolveFarmAPIServerRoutePath
-} from "./chunk-LM2YOGDK.mjs";
+} from "./chunk-2I6PUKWJ.mjs";
 import {
   FARM_VERSION
-} from "./chunk-R4PHCZ3G.mjs";
+} from "./chunk-HPWB57PZ.mjs";
 import {
   getFarmPresetRuntime
 } from "./chunk-UAQD67HM.mjs";
@@ -272,6 +276,7 @@ import { randomBytes } from "crypto";
 import path from "path";
 var FARM_CLIENT_CSS_HREF_PLACEHOLDER = "/__farm_client_css_href__";
 var FARM_CLIENT_JS_SRC_PLACEHOLDER = "/__farm_client_js_src__";
+var FARM_CLIENT_BOOT_SRC_PLACEHOLDER = "/__farm_client_boot_src__";
 async function hashAndCopy(sourcePath, destinationDir, hashedName) {
   const fs4 = await import("fs/promises");
   try {
@@ -304,6 +309,16 @@ async function findFingerprintedClientEntry(clientOutputDir) {
     return null;
   }
 }
+async function resolveClientBootSrc(clientOutputDir) {
+  const fs4 = await import("fs/promises");
+  try {
+    const entries = await fs4.readdir(clientOutputDir);
+    const name = entries.find((entry) => /^farm-client-boot-h[0-9a-f]+\.js$/.test(entry));
+    return name ? `/${name}` : null;
+  } catch {
+    return null;
+  }
+}
 async function resolveHashedClientJsSrc(clientOutputDir) {
   const entryName = await findFingerprintedClientEntry(clientOutputDir);
   if (!entryName) return "/farm-client.js";
@@ -1169,6 +1184,20 @@ async function readMiddlewareFileConfig(filePath) {
 }
 
 // src/nitro/universal-build.ts
+var FARM_NATIVE_STYLESHEETS_PLACEHOLDER = "__FARM_NATIVE_STYLESHEETS__";
+async function readFarmNativeStylesheets(clientOutputDir, clientCssHref) {
+  const fs4 = await import("fs/promises");
+  try {
+    return {
+      [clientCssHref]: await fs4.readFile(
+        path10.join(clientOutputDir, clientCssHref.slice(1)),
+        "utf8"
+      )
+    };
+  } catch {
+    return {};
+  }
+}
 function preloadFarmNitroBuilder() {
   return import("nitro/builder").then(
     (value) => ({ status: "fulfilled", value }),
@@ -2050,15 +2079,8 @@ ${islandsErrors.map((error) => `  - ${error}`).join("\n")}`
     rendererBuild?.abort();
   }
 }
-function shouldBuildFarmMobileClient(config, options = {}) {
-  if (!config.mobileClient || config.desktop) return false;
-  const mode = resolveFarmServerComponentsMode(config.experimental?.serverComponents);
-  if (mode === void 0) return true;
-  if (!options.quiet)
-    logger.info(
-      `\u{1F4F1} No mobile client for experimental.serverComponents (${mode}) yet; a mobile shell loads the web client.`
-    );
-  return false;
+function shouldBuildFarmMobileClient(config) {
+  return Boolean(config.mobileClient) && !config.desktop;
 }
 function varyFarmNitroCacheRulesByShell(rules) {
   return Object.fromEntries(
@@ -2254,6 +2276,7 @@ async function buildClient(productionVite, config, root, srcDir, outputDir, page
   });
   const layoutAppliesToRoute = routeBoundaryCoversDirectory;
   const routeDirectory = (route) => route.directory ?? route.pattern;
+  const islandsMode = resolveFarmServerComponentsMode(config.experimental?.serverComponents) === "islands";
   const adapterOwnsDocsRuntime = Boolean(
     isReactRenderer(config.renderer) && config.docs?.enabled && config.docs.adapter?.server && config.docs.adapter.react
   );
@@ -2309,7 +2332,8 @@ async function buildClient(productionVite, config, root, srcDir, outputDir, page
         }
       }))
     ],
-    layoutAppliesToRoute
+    layoutAppliesToRoute,
+    { serverOwners: islandsMode }
   );
   for (const layout of clientLayouts) {
     const matchesBuiltRoute = pageRoutes.some((route) => layoutAppliesToRoute(layout.pattern, routeDirectory(route))) || docsEntries.some((docsEntry) => layoutAppliesToRoute(layout.pattern, docsEntry));
@@ -2343,15 +2367,13 @@ async function buildClient(productionVite, config, root, srcDir, outputDir, page
       }
       if (metadata.shouldHydrate || metadata.hasIsolatedClientBoundaries || applicableClientLayouts.length > 0) {
         const relativePath = route.modulePath.replace(root, "").replace(/^\//, "");
-        const hydrationStrategies = [
-          ...metadata.islandStrategy ? [metadata.islandStrategy] : [],
-          ...applicableClientLayouts.flatMap(
-            (layout) => layout.islandStrategy ? [layout.islandStrategy] : []
-          )
-        ];
-        const islandStrategy = hydrationStrategies.every(
-          (strategy) => strategy === hydrationStrategies[0]
-        ) ? hydrationStrategies[0] ?? "load" : "load";
+        const islandStrategy = resolveFarmRouteRootStrategy(
+          route,
+          metadata,
+          clientLayouts,
+          root,
+          islandsMode
+        );
         clientPages.push({
           ...route,
           relativePath,
@@ -2433,10 +2455,26 @@ async function buildClient(productionVite, config, root, srcDir, outputDir, page
       generateClientCachePersistenceCode(resolveFarmClientCacheAdapterEntry(root, config.cache)),
       adapterOwnsDocsRuntime ? getFarmDocsAdapterConfigModule(config.docs) : void 0,
       resolveFarmServerComponentsMode(config.experimental?.serverComponents) === "islands",
-      platform
+      platform,
+      islandsMode ? collectFarmServerStylesheets(
+        [
+          ...layoutRoutes.map((layout) => layout.modulePath),
+          ...pageRoutes.filter((route) => !isAdapterDocsRoute(route.pattern)).map((route) => route.modulePath)
+        ],
+        root
+      ) : []
     );
     const entryName = platform === "mobile" ? FARM_MOBILE_CLIENT_ENTRY_NAME : "farm-client";
     await fs4.writeFile(clientEntryPath, clientHydrationCode);
+    const clientInput = { [entryName]: clientEntryPath };
+    if (platform === "web" && canBootFarmIslandsClient(config)) {
+      const clientBootPath = path10.join(clientEntryDir, "farm-client-boot.tsx");
+      await fs4.writeFile(
+        clientBootPath,
+        'import { startFarmIslandsBoot } from "@farm.js/core/internal/islands-boot";\nstartFarmIslandsBoot();\n'
+      );
+      clientInput[`${entryName}-boot`] = clientBootPath;
+    }
     const hasScopedPostcssConfig = hasProjectPostcssConfig(root);
     let postcssSearchPath;
     let tailwindVitePlugin = void 0;
@@ -2477,9 +2515,7 @@ async function buildClient(productionVite, config, root, srcDir, outputDir, page
           cssCodeSplit: false,
           // Bundle all CSS into one file
           rollupOptions: {
-            input: {
-              [entryName]: clientEntryPath
-            },
+            input: clientInput,
             output: {
               entryFileNames: "[name]-h[hash].js",
               chunkFileNames: "chunks/[name]-h[hash].js",
@@ -2709,48 +2745,7 @@ async function fetchFarmNavigationDocument(url, headers, recover = true, signal)
   return response;
 }
 
-${streamNavigations ? `// Reads a streamed navigation (F-Stream) up to the end of React's shell. \`next\` then resolves
-// with each later flush as it ends, and null at the end; a document without a marker is all shell.
-// The marker carries the random token the server sent in the F-Flush header, so page content
-// cannot forge a boundary; a response without a valid token is all shell.
-async function readFarmNavigationStream(body, flushToken) {
-  const reader = body.getReader();
-  const decoder = new TextDecoder();
-  const marker = typeof flushToken === "string" && /^[0-9a-f]{32}$/.test(flushToken)
-    ? "<!--farm-flush:" + flushToken + "-->"
-    : "";
-  let text = "";
-  let done = false;
-  const next = async function() {
-    for (;;) {
-      const at = marker ? text.indexOf(marker) : -1;
-      if (at !== -1) {
-        const flush = text.slice(0, at);
-        text = text.slice(at + marker.length);
-        return flush;
-      }
-      if (done) {
-        const flush = text;
-        text = "";
-        return flush ? flush : null;
-      }
-      const result = await reader.read();
-      if (result.done) {
-        done = true;
-        text += decoder.decode();
-      } else {
-        text += decoder.decode(result.value, { stream: true });
-      }
-    }
-  };
-  const shell = await next();
-  if (done && !text) return { shell: shell || "" };
-  return {
-    shell: shell,
-    next: next,
-    cancel: function() { reader.cancel().catch(function() {}); },
-  };
-}` : ""}
+${streamNavigations ? FARM_NAVIGATION_STREAM_READER_SOURCE : ""}
 
 function clearFarmPrefetchCacheOnDeploymentMismatch(router, error) {
   if (error?.name === "FarmDeploymentMismatchError") {
@@ -3506,7 +3501,7 @@ function generateClientHydrationEntry(clientPages, layoutRoutes, clientRouteSlot
     secure: false
   },
   direction: {}
-}, plugins = [], renderer = REACT_RENDERER, publicRuntimeConfig = void 0, trailingSlash = false, integrationProviders = [], basePath = "/", clientCachePersistence = { imports: "", init: "" }, docsConfigModule, islandValues = false, platform) {
+}, plugins = [], renderer = REACT_RENDERER, publicRuntimeConfig = void 0, trailingSlash = false, integrationProviders = [], basePath = "/", clientCachePersistence = { imports: "", init: "" }, docsConfigModule, islandValues = false, platform, serverStylesheets = []) {
   const toImportPath = (targetPath) => targetPath.replace(/\\/g, "/");
   const clientPluginEntry = generateFarmClientPluginEntryCode(
     plugins,
@@ -3526,7 +3521,20 @@ __farmConfigureApp(__farmAppSetup);` : `import React, { createRoot, hydrateRoot
     renderer.componentExtensions ?? []
   );
   const globalsCssPath = path10.join(root, srcDir, "app", "globals.css");
-  const cssImport = existsSync2(globalsCssPath) ? `import ${JSON.stringify(toImportPath(globalsCssPath))};` : "";
+  const serverStyleModules = [];
+  const cssImport = [
+    ...existsSync2(globalsCssPath) ? [globalsCssPath] : [],
+    ...serverStylesheets.filter((stylesheet) => stylesheet !== globalsCssPath)
+  ].map((stylesheet) => {
+    if (!/\.module\.[a-z]+$/.test(stylesheet)) {
+      return `import ${JSON.stringify(toImportPath(stylesheet))};`;
+    }
+    const binding = `__farmServerStyle${serverStyleModules.length}`;
+    serverStyleModules.push(binding);
+    return `import * as ${binding} from ${JSON.stringify(toImportPath(stylesheet))};`;
+  }).concat(
+    serverStyleModules.length > 0 ? [`globalThis.__FARM_SERVER_STYLES__ = [${serverStyleModules.join(", ")}];`] : []
+  ).join("\n");
   const layoutImportStatements = [];
   const layoutRegistrations = [];
   const hydratingLayoutPatterns = layoutRoutes.filter((layout) => layout.shouldHydrate).map((layout) => layout.pattern);
@@ -4466,9 +4474,9 @@ async function hydrate() {
     !matched.route.pageShouldHydrate &&
     !hasHydratableLayout(pathname)
   ) {
-    const hydrationController = new AbortController();
-    pendingPageHydrationController = hydrationController;
-    await hydrateFarmIsolatedClientBoundaries(document, hydrationController.signal);
+    // Not cancelled by a navigation: an island it removes is disposed with its DOM, and one in a
+    // layout it keeps still waits for its trigger, with any click it already holds.
+    await hydrateFarmIsolatedClientBoundaries(document);
     return;
   }` : ""}
   
@@ -5303,6 +5311,10 @@ async function buildSSRInMemory(productionVite, config, root, routeManager, apiR
       modulePath: entry.modulePath
     })
   );
+  const mobileShellLoadingRoutes = config.mobileShells ? Array.from(routeManager.getLoadings().values(), (entry) => ({
+    pattern: entry.pattern,
+    modulePath: entry.modulePath
+  })) : [];
   const i18nCatalogs = config.i18n.enabled ? (await readFarmI18nCatalogs(config.i18n)).catalogs : {};
   const appDirs = getFarmAppDirectories(config);
   let openAPIReference = null;
@@ -5416,7 +5428,8 @@ async function buildSSRInMemory(productionVite, config, root, routeManager, apiR
     preset,
     i18nCatalogs,
     isolatedClientBoundaryModules,
-    hydrationPlanCache
+    hydrationPlanCache,
+    mobileShellLoadingRoutes
   );
   const virtualEntryId = "\0virtual:farm-ssr-entry";
   const useExternalMetadataImageRuntime = shouldUseExternalMetadataImageRuntime(preset, true);
@@ -6022,9 +6035,11 @@ if (typeof ReactDOMServer.configureApp !== "function") {
 }
 ReactDOMServer.configureApp(__farmAppSetup);`;
 }
-function generateVirtualEntryCode(apiRoutes, pageRoutes, layoutRoutes, routeSlots, errorRoutes, metadataImageRoutes, applicationMetadataRoutes, middlewareRoutes, redirectRoutes, configuredRewriteRoutes, configuredHeaderRoutes, openAPIReference, notFoundPath, instrumentationPath, config, farmDocsPrecompiledManifest, configModulePath, hasServerRuntimeIntegrations, hasRuntimeIntegrationConfig, hasConfiguredRuntimePlugins, hasServerRuntimePlugins, preset, i18nCatalogs, isolatedClientBoundaryModules, hydrationPlanCache) {
+function generateVirtualEntryCode(apiRoutes, pageRoutes, layoutRoutes, routeSlots, errorRoutes, metadataImageRoutes, applicationMetadataRoutes, middlewareRoutes, redirectRoutes, configuredRewriteRoutes, configuredHeaderRoutes, openAPIReference, notFoundPath, instrumentationPath, config, farmDocsPrecompiledManifest, configModulePath, hasServerRuntimeIntegrations, hasRuntimeIntegrationConfig, hasConfiguredRuntimePlugins, hasServerRuntimePlugins, preset, i18nCatalogs, isolatedClientBoundaryModules, hydrationPlanCache, mobileShellLoadingRoutes = []) {
   const farmIslandsMode = resolveFarmServerComponentsMode(config.experimental?.serverComponents) === "islands";
-  const farmMobileClient = shouldBuildFarmMobileClient(config, { quiet: true });
+  const farmClientBoot = canBootFarmIslandsClient(config);
+  const farmMobileClient = shouldBuildFarmMobileClient(config);
+  const farmMobileShells = farmMobileClient && config.mobileShells ? config.mobileShells : null;
   const hasCompressionRuntime = config.compress && resolveFarmInstrumentationRuntime(preset) === "nodejs";
   const servesAgentRobotsTxt = Boolean(config.agent?.crawlers?.enabled) && !applicationMetadataRoutes.some(
     (metadata) => metadata.kind === "robots" && metadata.pattern === "/"
@@ -6175,7 +6190,8 @@ function renderFarmServerTreeLayout(Layout, props, outlets) {
       depth: getRouteDirectoryDepth(route.directory ?? route.pattern),
       metadata: pageHydrationPlans.get(route.modulePath)
     })),
-    routeBoundaryCoversDirectory
+    routeBoundaryCoversDirectory,
+    { serverOwners: pageHydrationPlanOptions.serverOwners }
   );
   const providerServerImports = [
     providerServerModules.hasClerkProvider ? `import { ClerkProvider as FarmClerkProvider } from "@clerk/react";` : "",
@@ -6237,7 +6253,17 @@ function renderFarmServerTreeLayout(Layout, props, outlets) {
     module: ${varName},
     shouldHydrate: ${JSON.stringify(clientMetadata.shouldHydrate)},${clientMetadata.shouldHydrate ? `
     clientModule: ${JSON.stringify(toViteModuleId(route.modulePath, config.root))},` : ""}
-    islandStrategy: ${JSON.stringify(clientMetadata.islandStrategy)},${usesFarmServerTree(clientMetadata) ? "\n    serverTree: true," : ""}${renderingDirective ? `
+    islandStrategy: ${JSON.stringify(clientMetadata.islandStrategy)},${usesFarmServerTree(clientMetadata) ? "\n    serverTree: true," : ""}${(() => {
+      const rootStrategy = resolveFarmRouteRootStrategy(
+        route,
+        clientMetadata,
+        layoutHydrationPlans.map((layout) => ({ ...layout, ...layout.hydration })),
+        config.root,
+        pageHydrationPlanOptions.serverOwners
+      );
+      return rootStrategy === "load" ? "" : `
+    rootStrategy: ${JSON.stringify(rootStrategy)},`;
+    })()}${renderingDirective ? `
     rendering: ${JSON.stringify(renderingDirective)},` : ""}
     ${route.source !== void 0 ? `markdownSource: {
       source: ${JSON.stringify(route.source)},
@@ -6310,6 +6336,24 @@ function renderFarmServerTreeLayout(Layout, props, outlets) {
     module: ${varName},
   }`);
   });
+  const loadingImports = [];
+  const loadingRegistrations = [];
+  if (farmMobileShells) {
+    mobileShellLoadingRoutes.forEach((loadingRoute, index) => {
+      const varName = `loadingRoute${index}`;
+      loadingImports.push(
+        `import * as ${varName} from ${toVirtualEntryImportSpecifier(loadingRoute.modulePath)};`
+      );
+      const groupScope = getRouteGroupScope(loadingRoute.pattern);
+      loadingRegistrations.push(`
+  {
+    pattern: ${JSON.stringify(stripRouteGroups(loadingRoute.pattern))},${groupScope ? `
+    groupScope: ${JSON.stringify(groupScope)},
+    directoryDepth: ${getRouteDirectoryDepth(loadingRoute.pattern)},` : ""}
+    module: ${varName},
+  }`);
+    });
+  }
   const metadataImageImports = [];
   const metadataImageRegistrations = [];
   metadataImageRoutes.forEach((image, index) => {
@@ -6468,7 +6512,45 @@ function applyFarmMobileShellResponse(request, response, context) {
 // No mobile block: no mobile client, and documents ignore X-Farm-Shell.
 function applyFarmMobileShellResponse(request, response) {
   return response;
-}`}${farmIslandsMode ? `
+}`}${farmMobileShells ? `
+import {
+  _checkFarmMobileShellRoute,
+  _isFarmMobileShellRenderRequest,
+} from "@farm.js/core/internal/production-runtime";
+// farm build --mobile with mobile.shells (RFC 0004, 7.2): this server renders a page shell, the
+// route's layouts around its loading file, for requests that carry this build's token. A web
+// build has no token and none of this.
+const farmMobileShellToken = ${JSON.stringify(farmMobileShells.token)};
+const loadingRoutes = [${loadingRegistrations.join(",")}
+];
+
+/**
+ * A request for a page shell: the loading component it renders in place of the page, or a
+ * Response saying why the route has none. Null for every other request.
+ */
+function resolveFarmMobileShellRender(request, route, routePathname) {
+  if (!_isFarmMobileShellRenderRequest(request, farmMobileShellToken)) return null;
+  const loading = getMatchingErrorBoundary(routePathname, loadingRoutes);
+  const reason = _checkFarmMobileShellRoute({
+    requested: request.headers.get("x-farm-shell-route"),
+    route: route.pattern,
+    layouts: getApplicableLayouts(routePathname, route.directory || route.pattern).map(
+      (layout) => layout.pattern,
+    ),
+    loading: loading && loading.route.module.default ? loading.route.pattern : null,
+  });
+  if (reason) {
+    return farmOwnedResponse(reason, {
+      status: 404,
+      headers: {
+        "Content-Type": "text/plain; charset=utf-8",
+        "Cache-Control": "private, no-store",
+        "X-Farm-Shell-Render": "none",
+      },
+    });
+  }
+  return loading.route.module.default;
+}` : ""}${farmIslandsMode ? `
 import { getSharedLayoutPrefixLength, handleFarmFormActionRequest, ignoreFarmHeldValues, installFarmIslandValues, parseFarmLayoutChainHeader } from "@farm.js/core/internal/production-runtime";
 import { installFarmIslandsServer } from "@farm.js/core/internal/islands-server";
 installFarmIslandsServer();
@@ -6630,7 +6712,8 @@ ${apiImports.join("\n")}
 ${pageImports.join("\n")}
 ${layoutImports.join("\n")}
 ${routeSlotImports.join("\n")}
-${errorImports.join("\n")}
+${errorImports.join("\n")}${loadingImports.length > 0 ? `
+${loadingImports.join("\n")}` : ""}
 ${metadataImageImports.join("\n")}
 ${applicationMetadataImports.join("\n")}
 ${middlewareImports.join("\n")}
@@ -7157,6 +7240,32 @@ function renderFarmClientEntryScript(early) {
   return stampFarmCspNonce('<script type="module"' + (early ? ' async' : '') + ' src="/__farm_client_js_src__"></script>');
 }
 
+// Islands mode: a whole document in which nothing hydrates at load (no island with \`load\`, and no
+// page, layout or route slot hydrating as a root) starts with the boot entry, which loads the
+// client runtime on an island's own trigger, a link or a form (RFC 0003, section 10).
+const FARM_CLIENT_BOOT = ${JSON.stringify(farmClientBoot)};
+const FARM_ISLAND_OPENING_TAG = /<f-island\\b[^>]*>/g;
+const FARM_DEFERRED_ISLAND_STRATEGY = /\\sstrategy="(?:interaction|visible|idle)"/;
+
+function farmDocumentBootsClient(markup, hydratesAtLoad, routeSlots) {
+  if (!FARM_CLIENT_BOOT || hydratesAtLoad || typeof markup !== "string") return false;
+  if (routeSlots && routeSlots.length > 0) return false;
+  // A Suspense boundary the server gave up on, which the browser renders.
+  if (markup.includes("<!--$!-->") || markup.includes("<!--$?-->")) return false;
+  for (const match of markup.matchAll(FARM_ISLAND_OPENING_TAG)) {
+    if (!FARM_DEFERRED_ISLAND_STRATEGY.test(match[0])) return false;
+  }
+  return true;
+}
+
+// The boot entry runs the client entry from the URL on its script. A root that waits (the element
+// a hydrating layout or client page hydrates) is named with its strategy, for the boot to watch.
+function renderFarmClientBootScript(root, rootStrategy) {
+  return stampFarmCspNonce('<script type="module" src="${farmClientBoot ? FARM_CLIENT_BOOT_SRC_PLACEHOLDER : ""}" data-farm-runtime="/__farm_client_js_src__"' +
+    (root ? ' data-farm-root="' + root + '" data-farm-root-strategy="' + rootStrategy + '"' : '') +
+    '></script>');
+}
+
 // Renderer options for the response being rendered: its CSP nonce, which the
 // renderer puts on the inline scripts it emits.
 function getFarmRendererRenderOptions() {
@@ -7927,12 +8036,13 @@ function withFarmDocsRequestCache(response, request, farmLocaleResolution, middl
 
 ${generateRuntimePathMatcherSource()}
 
-function getMatchingErrorBoundary(pathname) {
+// The nearest boundary file for a page path. Page shells pass their loading files.
+function getMatchingErrorBoundary(pathname, boundaries = errorRoutes) {
   const pathSegments = splitRuntimePath(pathname);
   let bestMatch = null;
   let directory;
 
-  for (const errorRoute of errorRoutes) {
+  for (const errorRoute of boundaries) {
     const patternDepth = splitRuntimePath(errorRoute.pattern).length;
     if (patternDepth > pathSegments.length) continue;
     const candidatePath = patternDepth === 0
@@ -9206,6 +9316,7 @@ ${hasServerRuntimeIntegrations ? `
   ${config.mobileClient ? `
   // The mobile app's native-tier screens: the page, rendered as for a browser, read into a
   // tree of native views.
+  const farmNativeStylesheets = JSON.parse(${JSON.stringify(FARM_NATIVE_STYLESHEETS_PLACEHOLDER)});
   if (
     (request.method === "GET" || request.method === "HEAD") &&
     request.headers.get("accept")?.includes(${JSON.stringify(FARM_NATIVE_TREE_CONTENT_TYPE)})
@@ -9213,6 +9324,8 @@ ${hasServerRuntimeIntegrations ? `
     const treeResponse = await createFarmNativeTreeResponse({
       request,
       renderPage: (targetRequest) => fetchFarmInnerRequest(targetRequest, adapterContext),
+      // The client CSS this build emitted, embedded once it settled (FARM_NATIVE_STYLESHEETS).
+      loadStylesheet: (href) => farmNativeStylesheets[href],
     });
     return applyProductionMiddlewareHeaders(treeResponse, middlewareHeaders);
   }
@@ -9423,8 +9536,12 @@ ${hasServerRuntimeIntegrations ? `
     const actionResponse = await handleFarmFormActionRequest(request, farmFormActionsConfig);
     if (actionResponse) return applyProductionMiddlewareHeaders(actionResponse, middlewareHeaders);
   }` : ""}
-  if (matchedRoute) {
-    const trailingSlashLocation = resolveFarmTrailingSlashRedirect(
+  if (matchedRoute) {${farmMobileShells ? `
+    // A page shell request renders the route's loading file in place of its page, with no params,
+    // data, slots, or page metadata; a route without a shell answers why.
+    const farmShellLoading = resolveFarmMobileShellRender(request, matchedRoute.route, routePathname);
+    if (farmShellLoading instanceof Response) return farmShellLoading;` : ""}
+    const trailingSlashLocation = ${farmMobileShells ? "farmShellLoading ? null : " : ""}resolveFarmTrailingSlashRedirect(
       url,
       ${JSON.stringify(config.trailingSlash)}
     );
@@ -9437,7 +9554,19 @@ ${hasServerRuntimeIntegrations ? `
         middlewareHeaders
       );
     }
-    const { route, params } = matchedRoute;
+    const { route, params } = ${farmMobileShells ? `farmShellLoading
+      ? {
+          route: {
+            ...matchedRoute.route,
+            module: { default: farmShellLoading, viewport: matchedRoute.route.module.viewport },
+            shouldHydrate: false,
+            serverTree: false,
+            rendering: undefined,
+            markdownSource: undefined,
+          },
+          params: {},
+        }
+      : matchedRoute` : "matchedRoute"};
     emitFarmEvent({ type: "route.matched", pathname, route: route.pattern, params });
     
     try {
@@ -9456,7 +9585,7 @@ ${hasServerRuntimeIntegrations ? `
           : countFarmKeptLayouts(request, farmSegmentLayouts, params);
       // The root layout always renders, so keeping one layout keeps nothing.
       const farmKeptLayouts = farmKeptLayoutCount > 1 ? farmKeptLayoutCount : 0;` : `const farmKeptLayouts = 0;`}
-      const pprConfig = resolvePPRConfig(route);
+      ${farmMobileShells ? "const pprConfig = farmShellLoading ? { enabled: false } : resolvePPRConfig(route);" : "const pprConfig = resolvePPRConfig(route);"}
       const pprBypassReason = pprConfig.enabled
         ? getPPRShellBypassReason(request, middlewareData, middlewareContext)
         : undefined;
@@ -9527,12 +9656,13 @@ ${hasServerRuntimeIntegrations ? `
           layout.shouldHydrate && layout.islandStrategy ? [layout.islandStrategy] : [],
         ),
       ];
-      const hydrationIslandStrategy = hydrationStrategies.every(
+      // A root that waits carries its resolved strategy, inferred ones included.
+      const hydrationIslandStrategy = route.rootStrategy || (hydrationStrategies.every(
         (strategy) => strategy === hydrationStrategies[0],
       )
         ? (hydrationStrategies[0] || "load")
-        : "load";
-      const selectedRouteSlots = matchRouteSlots(
+        : "load");
+      const selectedRouteSlots = ${farmMobileShells ? "farmShellLoading ? [] : " : ""}matchRouteSlots(
         routePathname,
         request.headers.get("x-farm-intercept-from"),
       );
@@ -9853,9 +9983,12 @@ ${hasServerRuntimeIntegrations ? `
                   {
                     "data-farm-layout-boundary": "true",
                     "data-farm-layout-pattern": layout.pattern,
-                    "data-farm-layout-key": farmLayoutKeyOf
-                      ? farmLayoutKeyOf(layout.pattern, params)
-                      : undefined,
+                    // A layout chain that hydrates is drawn by React in the browser
+                    // (document-layout-client.ts), without a key; it renders whole anyway.
+                    "data-farm-layout-key":
+                      farmLayoutKeyOf && !shouldHydrateLayout
+                        ? farmLayoutKeyOf(layout.pattern, params)
+                        : undefined,
                     style: { display: "contents" },
                   },
                   wrappedElement,
@@ -10004,6 +10137,9 @@ ${hasServerRuntimeIntegrations ? `
         // renderer-emitted one; explicit metadata titles still come first.
         const suppressDefaultTitle =
           !renderedMetadata.hasExplicitTitle && rendererHasTitle;
+        // Set once the whole document is rendered: whether it starts with the boot entry, which
+        // preloads nothing.
+        let farmBootsClient = false;
         // A layout's own <html> document with Farm's head assets merged in and the #root the client
         // hydrates opening its body: the whole document, or a streamed one's opening.
         const composeFarmFullDocument = function(markup) {
@@ -10013,7 +10149,7 @@ ${hasServerRuntimeIntegrations ? `
           );
           composed = composed
             // Inject CSS link after opening head tag or first meta tag
-            .replace(/<head([^>]*)>/i, function(match, attrs) { return '<head' + attrs + '>\\n  <link rel="stylesheet" href="/__farm_client_css_href__">' + renderFarmClientModulePreloads(composed, route.clientModule); })
+            .replace(/<head([^>]*)>/i, function(match, attrs) { return '<head' + attrs + '>\\n  <link rel="stylesheet" href="/__farm_client_css_href__">' + (farmBootsClient ? "" : renderFarmClientModulePreloads(composed, route.clientModule)); })
             .replace(/<\\/head>/i, () => renderFarmRendererHydrationScript() + '\\n</head>')
             // Explicit metadata wins over renderer and layout titles. Without
             // explicit metadata, a renderer title wins over the layout title.
@@ -10189,7 +10325,20 @@ ${hasServerRuntimeIntegrations ? `
             throw renderedPage.streamErrors[0];
           }
         }
-        
+        // A route that hydrates as one root starts with the boot entry only when that root waits.
+        const farmHydratesRoot = route.shouldHydrate || shouldHydrateLayout;
+        farmBootsClient = farmDocumentBootsClient(
+          html,
+          (farmHydratesRoot && !route.rootStrategy) || Boolean(pprCacheKey),
+          routeSlotPayload
+        );
+        const farmEntryScript = farmBootsClient
+          ? renderFarmClientBootScript(
+              farmHydratesRoot ? (shouldHydrateLayout ? "root" : "__farm_page__") : "",
+              route.rootStrategy
+            )
+          : renderFarmClientEntryScript();
+
         let fullHtml;
         if (hasFullDocument) {
           // Layout provides full HTML structure - inject CSS and client script
@@ -10205,7 +10354,7 @@ ${hasServerRuntimeIntegrations ? `
                 routeSlotPayload,
                 clientPageProps
               ) + '\\n' +
-                '  ' + renderFarmClientEntryScript() + '\\n</body>',
+                '  ' + farmEntryScript + '\\n</body>',
             );
         } else {
           // No layout with full document - wrap in HTML structure
@@ -10216,13 +10365,13 @@ ${hasServerRuntimeIntegrations ? `
   \${viewportTags}
   \${hasFavicon ? "" : '<link rel="icon" href="data:,">'}
   \${suppressDefaultTitle ? "" : "<title>" + title + "</title>"}\${metaTags}\${rendererHead ? "\\n  " + rendererHead : ""}
-  <link rel="stylesheet" href="/__farm_client_css_href__">\${renderFarmClientModulePreloads(html, route.clientModule)}
+  <link rel="stylesheet" href="/__farm_client_css_href__">\${farmBootsClient ? "" : renderFarmClientModulePreloads(html, route.clientModule)}
   \${renderFarmRendererHydrationScript()}
 </head>
 <body>
   <div id="root">\${html}</div>
   \${renderFarmClientBootstrapScript(pageProps.__farmCanonicalPath, routeSlotPayload, clientPageProps)}
-  \${renderFarmClientEntryScript()}
+  \${farmEntryScript}
 </body>
 </html>\`;
         }
@@ -11007,15 +11156,17 @@ async function buildNitroUniversal(config, routeManager, apiRouteManager, server
   }
   const scheduledTasks = mergeScheduledTasks(farmWorkflows.scheduledTasks, farmCron.scheduledTasks);
   const cloudflareCronConfig = createFarmCronCloudflareConfig(farmCron.jobs);
-  const [clientCssHref, clientJsSrc, docsModulePreloads, clientModulePreloads] = await Promise.all([
+  const [clientCssHref, clientJsSrc, clientBootSrc, docsModulePreloads, clientModulePreloads] = await Promise.all([
     resolveHashedClientCssHref(clientOutputDir),
     resolveHashedClientJsSrc(clientOutputDir),
+    resolveClientBootSrc(clientOutputDir),
     readFarmDocsModulePreloads(path10.join(root, distDir)),
     readFarmClientModulePreloads(path10.join(root, distDir))
   ]);
+  let nativeStylesheets;
   const encodedDocsModulePreloads = encodeFarmDocsModulePreloads(docsModulePreloads);
   const encodedClientModulePreloads = encodeFarmClientModulePreloads(clientModulePreloads);
-  const encodedMobileShellClient = shouldBuildFarmMobileClient(config, { quiet: true }) ? encodeFarmMobileShellClient(
+  const encodedMobileShellClient = shouldBuildFarmMobileClient(config) ? encodeFarmMobileShellClient(
     await finalizeFarmMobileClient({
       buildDir: path10.join(root, distDir),
       clientOutputDir,
@@ -11041,6 +11192,16 @@ async function buildNitroUniversal(config, routeManager, apiRouteManager, server
     if (output.code.includes(FARM_CLIENT_JS_SRC_PLACEHOLDER)) {
       output.code = output.code.split(FARM_CLIENT_JS_SRC_PLACEHOLDER).join(clientJsSrc);
     }
+    if (output.code.includes(FARM_CLIENT_BOOT_SRC_PLACEHOLDER)) {
+      if (!clientBootSrc) {
+        throw new IncompleteClientBuildOutputError("farm-client-boot is missing");
+      }
+      output.code = output.code.split(FARM_CLIENT_BOOT_SRC_PLACEHOLDER).join(clientBootSrc);
+    }
+    if (config.mobileClient && output.code.includes(JSON.stringify(FARM_NATIVE_STYLESHEETS_PLACEHOLDER))) {
+      nativeStylesheets ?? (nativeStylesheets = await readFarmNativeStylesheets(clientOutputDir, clientCssHref));
+      output.code = output.code.split(JSON.stringify(FARM_NATIVE_STYLESHEETS_PLACEHOLDER)).join(JSON.stringify(JSON.stringify(nativeStylesheets)));
+    }
   }
   await fs4.mkdir(ssrOutputDir, { recursive: true });
   await Promise.all(
@@ -11306,7 +11467,7 @@ function toFarmNodeResponse(request, response) {
     ssrOutputDir,
     ssrEntryFile
   );
-  const configuredNitroRouteRules = shouldBuildFarmMobileClient(config, { quiet: true }) ? varyFarmNitroCacheRulesByShell(routeRulesToNitroRouteRules(config.routeRules)) : routeRulesToNitroRouteRules(config.routeRules);
+  const configuredNitroRouteRules = shouldBuildFarmMobileClient(config) ? varyFarmNitroCacheRulesByShell(routeRulesToNitroRouteRules(config.routeRules)) : routeRulesToNitroRouteRules(config.routeRules);
   const prerenderNitroRouteRules = Object.fromEntries(
     prerenderRoutes.map((route) => {
       const configuredRule = configuredNitroRouteRules[route] || {};
@@ -12425,7 +12586,7 @@ function resolveLegacyPageEntry(config, root, srcDir) {
 }
 async function buildNitro(config, routeManager, apiRouteManager, serverRenderer, preset, root, distDir, pluginManager) {
   const [{ createNitroConfig }, { createNitro, build: nitroBuild }] = await Promise.all([
-    import("./nitro-R444AF3O.mjs"),
+    import("./nitro-FLN6DRGJ.mjs"),
     import("nitro/builder")
   ]);
   let nitroConfig = await createNitroConfig(