@farm.js/core 0.1.48 → 0.1.49

package/dist/{chunk-TQWGOQ7O.mjs → chunk-Z3BXMMFF.mjs}

@@ -12,6 +12,7 @@ import {
   createDefaultErrorMarkup,
   createFarmMetadataRouteResponse,
   createFarmRouteRenderPlan,
+  createFarmStreamedDocumentTransform,
   createFarmThemeDocumentParts,
   createLateNotFoundRecovery,
   createLateRedirectRecovery,
@@ -24,14 +25,15 @@ import {
   getRouteDirectoryDepth,
   getRouteGroupScope,
   isInRouteGroupScope,
+  openFarmStreamedDocument,
   removeFarmDocumentTitles,
   renderFarmLocaleAlternateLinks,
   resolveDefaultErrorStatus,
   routeBoundaryCoversDirectory
-} from "./chunk-NIPKC4DA.mjs";
+} from "./chunk-ZIBIE7AH.mjs";
 import {
   listFarmMCPLlmsTxtLinks
-} from "./chunk-NRFUVDTH.mjs";
+} from "./chunk-DGVVVYKD.mjs";
 import {
   FARM_DEFAULT_MCP_PATH,
   collectFarmDefaultMCPPages,
@@ -248,7 +250,7 @@ import {
 } from "./chunk-LM2YOGDK.mjs";
 import {
   FARM_VERSION
-} from "./chunk-HRLYO2XJ.mjs";
+} from "./chunk-ACI52TCN.mjs";
 import {
   resolveFarmTrailingSlashRedirect,
   setFarmTrailingSlashPreference
@@ -4565,7 +4567,7 @@ function rendererRenderOptions() {
 }
 var FARM_DEV_EARLY_CLIENT_SCRIPT = `<script type="module" async src="/@farm/client.js"></script>`;
 function createDocumentFooter(options) {
-  return `</div>
+  return `${options.closeRoot === false ? "" : "</div>"}
   ${options.suspenseRevealFallback}
   ${options.refreshPPR ? createPPRRefreshScript() : ""}
   ${options.deferredHydrationScript || ""}
@@ -6767,7 +6769,8 @@ window.__FARM_I18N__ = ${getFarmI18nClientSnapshot() ? serializeInlineValue(getF
   async renderWithSSR(element, req, res, clearMiddlewareData, options = {}) {
     const renderToPipeableStream = this.rendererRuntime.renderToPipeableStream;
     const fullDocumentRouteKey = options.observabilityRoute || req.__FARM_ROUTE__ || req.url || "/";
-    if (!renderToPipeableStream || _isFarmMarkdownPageCheck(req.headers?.[FARM_MARKDOWN_PAGE_CHECK_HEADER]) || fullDocumentRoutes.has(fullDocumentRouteKey) || await this.rootLayoutRendersDocument()) {
+    const streamDocument = fullDocumentRoutes.has(fullDocumentRouteKey) || await this.rootLayoutRendersDocument();
+    if (!renderToPipeableStream || _isFarmMarkdownPageCheck(req.headers?.[FARM_MARKDOWN_PAGE_CHECK_HEADER]) || streamDocument && (options.captureStaticShell || !isReactRenderer(this.config.renderer))) {
       return this.renderBufferedSSR(element, req, res, clearMiddlewareData, options);
     }
     return new Promise((resolve3, reject) => {
@@ -6879,6 +6882,7 @@ window.__FARM_I18N__ = ${getFarmI18nClientSnapshot() ? serializeInlineValue(getF
         title,
         tags: metaTags,
         hasFavicon,
+        hasExplicitTitle,
         viewport: viewportTags
       } = renderMetadataHead(req.__FARM_METADATA__, {
         pathname: getFarmMetadataPathname(req),
@@ -6944,25 +6948,70 @@ window.__FARM_I18N__ = ${getFarmI18nClientSnapshot() ? serializeInlineValue(getF
 <body class="">${earlyClient ? `
   ${FARM_DEV_EARLY_CLIENT_SCRIPT}` : ""}
   <div id="root">`;
-          const securedShell = stampDocumentHTML(shell);
-          htmlParts.push(securedShell);
-          staticShellParts?.push(securedShell);
+          const securedShell = streamDocument ? "" : stampDocumentHTML(shell);
+          if (securedShell) {
+            htmlParts.push(securedShell);
+            staticShellParts?.push(securedShell);
+          }
+          const withEarlyClient = (document) => earlyClient ? {
+            ...document,
+            html: document.html.replace(
+              /<body\b[^>]*>/i,
+              (open) => `${open}
+  ${stampDocumentHTML(FARM_DEV_EARLY_CLIENT_SCRIPT)}`
+            )
+          } : document;
+          const documentTransform = streamDocument ? createFarmStreamedDocumentTransform(
+            (opening) => withEarlyClient(
+              openFarmStreamedDocument(
+                hasExplicitTitle ? removeFarmDocumentTitles(opening) : opening,
+                {
+                  fallbackIcon: !hasFavicon,
+                  viewport: viewportTags,
+                  htmlAttributes: `${i18nSnapshot ? ` lang="${escapeHtmlAttribute2(i18nSnapshot.locale)}" dir="${escapeHtmlAttribute2(i18nSnapshot.direction)}"` : ""}${themeDocument.attributes}`,
+                  replaceHtmlAttributes: [
+                    ...i18nSnapshot ? ["lang", "dir"] : [],
+                    ...themeDocument.attributes ? ["data-theme"] : []
+                  ],
+                  headAssets: stampDocumentHTML(
+                    [
+                      themeDocument.head,
+                      `<meta name="farm-deployment-id" content="${escapeHtmlAttribute2(deploymentId)}">`,
+                      hasExplicitTitle ? `<title>${title}</title>` : "",
+                      metaTags,
+                      i18nAlternateTags,
+                      fontHead,
+                      globalStylesheetLink,
+                      ...devStyleLinks,
+                      `<script type="module" src="/@vite/client"></script>`,
+                      propsScript,
+                      hydrationClickQueueScript
+                    ].filter(Boolean).join("\n  ")
+                  ),
+                  // The footer follows the streamed body.
+                  bodyFooter: ""
+                }
+              )
+            ),
+            stampDocumentHTML(shell)
+          ) : void 0;
           let firstChunk = true;
           let checkedFullDocument = false;
           let documentPrefix = "";
           const cspNonceRewriter = cspNonce ? createFarmCspNonceRewriter(cspNonce) : void 0;
           const cspStreamDecoder = cspNonceRewriter ? new TextDecoder() : void 0;
-          const recordRenderedChunk = (chunkText) => {
-            if (!chunkText) return;
-            if (!checkedFullDocument) {
-              documentPrefix += chunkText;
+          const recordRenderedChunk = (chunkText, renderedText = chunkText) => {
+            if (!checkedFullDocument && renderedText) {
+              documentPrefix += renderedText;
               const prefix = classifyFarmDocumentPrefix(documentPrefix);
               if (prefix !== "pending") {
                 checkedFullDocument = true;
                 documentPrefix = "";
                 if (prefix === "document") fullDocumentRoutes.add(fullDocumentRouteKey);
+                else fullDocumentRoutes.delete(fullDocumentRouteKey);
               }
             }
+            if (!chunkText) return;
             htmlParts.push(chunkText);
             if (staticShellParts && findStaticShellBoundary && !staticShellClosed) {
               const dynamicIndex = findStaticShellBoundary(chunkText);
@@ -6988,12 +7037,16 @@ window.__FARM_I18N__ = ${getFarmI18nClientSnapshot() ? serializeInlineValue(getF
               }
               const chunkText = Buffer.isBuffer(chunk) ? cspStreamDecoder ? cspStreamDecoder.decode(chunk, { stream: true }) : chunk.toString() : String(chunk);
               const securedChunkText = cspNonceRewriter ? cspNonceRewriter.write(chunkText) : chunkText;
-              recordRenderedChunk(securedChunkText);
+              const outputText = documentTransform ? documentTransform.write(securedChunkText) : securedChunkText;
+              recordRenderedChunk(outputText, securedChunkText);
               const onWrite = () => {
                 if (typeof res.flush === "function") res.flush();
                 callback();
               };
-              if (cspNonceRewriter) res.write(securedChunkText, onWrite);
+              if (documentTransform) {
+                if (outputText) res.write(outputText, onWrite);
+                else callback();
+              } else if (cspNonceRewriter) res.write(securedChunkText, onWrite);
               else res.write(chunk, encoding, onWrite);
             },
             final: (callback) => {
@@ -7002,7 +7055,8 @@ window.__FARM_I18N__ = ${getFarmI18nClientSnapshot() ? serializeInlineValue(getF
                 lateNavigationError = null;
                 createLateNavigationRecovery(navigationError).then(
                   (recovery) => {
-                    const secured = filterDocumentHTML(recovery);
+                    const filtered = filterDocumentHTML(recovery);
+                    const secured = documentTransform ? documentTransform.write(filtered) : filtered;
                     htmlParts.push(secured);
                     res.write(secured);
                     finishStream(callback);
@@ -7019,16 +7073,24 @@ window.__FARM_I18N__ = ${getFarmI18nClientSnapshot() ? serializeInlineValue(getF
           });
           const finishStream = (callback) => {
             if (cspNonceRewriter) {
-              const tail = cspNonceRewriter.write(cspStreamDecoder.decode(), true);
-              recordRenderedChunk(tail);
+              const rewritten = cspNonceRewriter.write(cspStreamDecoder.decode(), true);
+              const tail = documentTransform ? documentTransform.write(rewritten) : rewritten;
+              recordRenderedChunk(tail, rewritten);
               if (tail) res.write(tail);
             }
+            const documentEnd = documentTransform?.end();
+            if (documentEnd?.text) {
+              recordRenderedChunk(documentEnd.text, "");
+              res.write(documentEnd.text);
+            }
             const suspenseRevealFallback = `<script>(function(){function moveFragment(srcId,placeholderId){var src=document.getElementById(srcId),ph=document.getElementById(placeholderId);if(!src||!ph||!ph.parentNode)return false;while(src.firstChild)ph.parentNode.insertBefore(src.firstChild,ph);ph.parentNode.removeChild(ph);if(src.parentNode)src.parentNode.removeChild(src);return true}function revealBoundary(boundaryId,sectionId){var boundary=document.getElementById(boundaryId),section=document.getElementById(sectionId);if(!boundary||!section||!boundary.parentNode)return false;var start=boundary.previousSibling;if(!start||start.nodeType!==8)return false;var parent=boundary.parentNode;var node=boundary;var depth=0;while(node){if(node.nodeType===8){var data=node.data;if(data==="/$"||data==="/&"){if(depth===0)break;depth--;}else if(data==="$"||data==="$?"||data==="$~"||data==="$!"||data==="&"){depth++;}}var next=node.nextSibling;parent.removeChild(node);node=next;}while(section.firstChild)parent.insertBefore(section.firstChild,node);if(section.parentNode)section.parentNode.removeChild(section);start.data="$";return true}var tries=0;var timer=setInterval(function(){var changed=false;document.querySelectorAll('div[id^="S:"]').forEach(function(section){var suffix=section.id.slice(2);changed=moveFragment('S:'+suffix,'P:'+suffix)||changed;});document.querySelectorAll('template[id^="B:"]').forEach(function(boundary){var suffix=boundary.id.slice(2);changed=revealBoundary('B:'+suffix,'S:'+suffix)||changed;});tries++;if(tries>80||(!document.querySelector('template[id^="B:"]')&&!document.querySelector('template[id^="P:"]'))){clearInterval(timer);}},50);})();</script>`;
             const footer = stampDocumentHTML(
               createDocumentFooter({
                 suspenseRevealFallback,
                 deferredHydrationScript: createDeferredHydrationScript(deferredProps.records),
-                earlyClient
+                earlyClient,
+                // A full document: Farm's #root closes only where Farm opened it.
+                ...documentEnd?.document ? { closeRoot: documentEnd.rootOpened } : {}
               })
             );
             htmlParts.push(footer);

package/dist/{chunk-NE33FRQ5.mjs → chunk-Z4LTSH7D.mjs}

@@ -37,7 +37,7 @@ import {
 } from "./chunk-WB6XES4V.mjs";
 import {
   FARM_PRERENDER_ENV
-} from "./chunk-N6SIQJEJ.mjs";
+} from "./chunk-RYDDUCNJ.mjs";
 import {
   resolveFarmInstrumentationFile
 } from "./chunk-N35YPV4N.mjs";
@@ -84,7 +84,7 @@ import {
   resolveFarmIsolatedClientHydrationMode,
   resolveFarmNotFoundComponentPath,
   usesFarmServerTree
-} from "./chunk-TQWGOQ7O.mjs";
+} from "./chunk-Z3BXMMFF.mjs";
 import {
   loadTailwindVitePlugin
 } from "./chunk-XLLVWLWO.mjs";
@@ -108,7 +108,7 @@ import {
   layoutsCanCoverSamePage,
   routeBoundaryCoversDirectory,
   stripRouteGroups
-} from "./chunk-NIPKC4DA.mjs";
+} from "./chunk-ZIBIE7AH.mjs";
 import {
   farmPluginMayAffectRuntimePath
 } from "./chunk-UUMKLGUU.mjs";
@@ -119,7 +119,7 @@ import {
   listFarmBuiltInRoutePaths,
   resolveFarmApiCatalogInput,
   resolveFarmAppManifestInput
-} from "./chunk-NRFUVDTH.mjs";
+} from "./chunk-DGVVVYKD.mjs";
 import {
   FARM_DEFAULT_MCP_PATH,
   createFarmDefaultMCPServer,
@@ -231,7 +231,7 @@ import {
 } from "./chunk-LM2YOGDK.mjs";
 import {
   FARM_VERSION
-} from "./chunk-HRLYO2XJ.mjs";
+} from "./chunk-ACI52TCN.mjs";
 import {
   getFarmPresetRuntime
 } from "./chunk-UAQD67HM.mjs";
@@ -2510,7 +2510,7 @@ function toBakedMarkdownSourcePath(root, filePath) {
   }
   return relative.split(path10.sep).join("/");
 }
-function generateUniversalRouterStateRuntime() {
+function generateUniversalRouterStateRuntime(streamNavigations = false) {
   return `
 const FARM_PAGE_STATE_KEY = "__farmPageState";
 const FARM_HISTORY_INDEX_KEY = "__farmHistoryIndex";
@@ -2578,6 +2578,46 @@ async function fetchFarmNavigationDocument(url, headers, recover = true, signal)
   return response;
 }
 
+${streamNavigations ? `const FARM_FLUSH_MARKER = "<!--farm-flush-->";
+
+// 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.
+async function readFarmNavigationStream(body) {
+  const reader = body.getReader();
+  const decoder = new TextDecoder();
+  let text = "";
+  let done = false;
+  const next = async function() {
+    for (;;) {
+      const at = text.indexOf(FARM_FLUSH_MARKER);
+      if (at !== -1) {
+        const flush = text.slice(0, at);
+        text = text.slice(at + FARM_FLUSH_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() {}); },
+  };
+}` : ""}
+
 function clearFarmPrefetchCacheOnDeploymentMismatch(router, error) {
   if (error?.name === "FarmDeploymentMismatchError") {
     router.clearCache();
@@ -2781,9 +2821,35 @@ function interpolateRedirectDestination(destination, params) {
 }
 `.trim();
 }
-function generateUniversalRouterStateProperties() {
+function generateUniversalRouterStateProperties(streamNavigations = false) {
   return `
-  blockers: new Set(),
+${streamNavigations ? `  // A streamed navigation swaps in the page's shell; its Suspense content follows flush by flush.
+  navigationStream: null,
+  streamingNavigation: null,
+  takeNavigationStream: function(html) {
+    const stream = this.navigationStream;
+    this.navigationStream = null;
+    if (!stream) return;
+    if (stream.html !== html) {
+      stream.cancel();
+      return;
+    }
+    this.streamingNavigation = stream;
+    void streamFarmNavigation(
+      stream,
+      document.getElementById("root") || document.body,
+      () => this.streamingNavigation === stream,
+    );
+  },
+  stopNavigationStream: function() {
+    this.navigationStream?.cancel();
+    this.streamingNavigation?.cancel();
+    this.navigationStream = null;
+    this.streamingNavigation = null;
+  },
+` : `  takeNavigationStream: function() {},
+  stopNavigationStream: function() {},
+`}  blockers: new Set(),
   unloadBlockers: new Map(),
   navigationListeners: new Set(),
   navigationState: IDLE_NAVIGATION_STATE,
@@ -3077,6 +3143,11 @@ function generateUniversalRouterStateProperties() {
     // Only speculative requests have shared ownership. Ordinary navigations
     // keep their own abort signal and cannot cancel another caller's work.
     const record = recover ? null : { valid: true, deploymentId, promise: null };
+    // A navigation (not a prefetch) streams when the router supports it: the page goes in as
+    // soon as its shell arrives, and its Suspense content follows (takeNavigationStream). A page
+    // whose layouts hydrate, or one rendered in this page's React root, arrives whole.
+    const streamShell = ${streamNavigations ? `recover && !interceptFrom && !partialHeaders["F-Render"] &&
+      !hasHydratableLayout(new URL(url, window.location.href).pathname)` : "false"};
     const request = async () => {
       const response = await fetchFarmNavigationDocument(url, {
         "Accept": "text/html",
@@ -3085,13 +3156,28 @@ function generateUniversalRouterStateProperties() {
         // layouts it shows.
         ...getFarmIslandValueHeaders(),
         ...partialHeaders,
+        ...(streamShell ? { "F-Stream": "flush" } : {}),
       }, recover, signal);
       if (!response.ok) throw new Error("Failed to fetch page");
-      const html = await response.text();
-      if (cacheResult && !signal?.aborted && generation === this.prefetchGeneration &&
-          deploymentId === window.__FARM_DEPLOYMENT_ID__ && (!record || record.valid)) {
-        this.storePrefetchedHtml(cacheKey, html);
+      const store = (html) => {
+        if (cacheResult && !signal?.aborted && generation === this.prefetchGeneration &&
+            deploymentId === window.__FARM_DEPLOYMENT_ID__ && (!record || record.valid)) {
+          this.storePrefetchedHtml(cacheKey, html);
+        }
+      };
+${streamNavigations ? `      if (streamShell && response.body) {
+        const streamed = await readFarmNavigationStream(response.body);
+        if (!streamed.next) {
+          store(streamed.shell);
+          return streamed.shell;
+        }
+        this.stopNavigationStream();
+        this.navigationStream = { html: streamed.shell, next: streamed.next, cancel: streamed.cancel, store };
+        return streamed.shell;
       }
+` : ""}
+      const html = await response.text();
+      store(html);
       return html;
     };
     if (!record) return request();
@@ -4169,7 +4255,7 @@ let currentPathname = null;
 let isHydrated = false;
 let pendingPageHydrationController = null;
 
-${generateUniversalRouterStateRuntime()}
+${generateUniversalRouterStateRuntime(islandValues)}
 
 function cancelPendingPageHydration() {
   pendingPageHydrationController?.abort();
@@ -4357,6 +4443,55 @@ function activateNavigationScripts(root) {
   }
 }
 
+${islandValues ? `// Adds the flushes after a streamed navigation's shell: React's staged Suspense content and the
+// scripts that reveal it. In islands mode, the islands React reveals hydrate as they appear, and
+// the ones it removes (a replaced fallback) are released.
+async function streamFarmNavigation(stream, root, isCurrent) {
+  let html = stream.html;
+  let streaming = true;
+  ${isolatedHydrationEnabled ? `const removed = new Set();
+  let queued = false;
+  const run = function() {
+    queued = false;
+    if (!isCurrent()) return observer.disconnect();
+    for (const node of removed) if (!node.isConnected) disposeFarmIsolatedClientBoundaries(node);
+    removed.clear();
+    if (!streaming && !root.querySelector('div[hidden][id^="S:"]')) observer.disconnect();
+    hydrateFarmIsolatedClientBoundaries(root).catch(function(error) {
+      console.error("[Farm.js] Hydrating streamed islands failed:", error);
+    });
+  };
+  const observer = new MutationObserver(function(records) {
+    for (const record of records) for (const node of record.removedNodes) removed.add(node);
+    if (queued) return;
+    queued = true;
+    queueMicrotask(run);
+  });
+  observer.observe(root, { childList: true, subtree: true });` : "const observer = { disconnect: function() {} };"}
+  try {
+    for (let flush = await stream.next(); flush !== null; flush = await stream.next()) {
+      if (!isCurrent()) return stream.cancel();
+      html += flush;
+      const parsed = new DOMParser().parseFromString('<div id="root">' + flush, "text/html");
+      const fragment = document.createDocumentFragment();
+      for (const node of Array.from(parsed.getElementById("root").childNodes)) fragment.appendChild(node);
+      activateNavigationScripts(fragment);
+      root.appendChild(fragment);
+    }
+  } catch (error) {
+    streaming = false;
+    if (!isCurrent()) return observer.disconnect();
+    console.error("[Farm.js] A streamed navigation failed:", error);
+    ${isolatedHydrationEnabled ? "farmIsolatedHydrationRuntime.endStream?.(root);\n    if (!queued) run();" : ""}
+    return;
+  }
+  // A cancelled stream ends early: keep its partial document out of the cache.
+  if (!isCurrent()) return observer.disconnect();
+  streaming = false;
+  stream.store(html);
+  ${isolatedHydrationEnabled ? "farmIsolatedHydrationRuntime.endStream?.(root);\n  if (!queued) run();" : ""}
+}` : ""}
+
 function replaceSharedLayoutBoundary(currentRoot, nextRoot, refresh = false) {
   const currentPatterns = getLayoutPatterns(currentRoot);
   const nextPatterns = getLayoutPatterns(nextRoot);
@@ -4399,7 +4534,7 @@ function replaceSharedLayoutBoundary(currentRoot, nextRoot, refresh = false) {
 
 // SPA Router
 const spaRouter = {
-${generateUniversalRouterStateProperties()}
+${generateUniversalRouterStateProperties(islandValues)}
   prefetchCache: new Map(),
 ${islandValues ? `  // Islands mode: navigations name the layouts on screen, and say when this page renders the
   // next one in its own React root; the server leaves out what the browser keeps or rebuilds.
@@ -4411,7 +4546,7 @@ ${islandValues ? `  // Islands mode: navigations name the layouts on screen, and
       ...(reactRoot && reactRootContainer === root ? { "F-Render": "tree" } : {}),
     };
   },
-` : ""}  
+` : ""}
   navigate: async function(href, options = {}) {
     const url = new URL(href, window.location.href);
     if (isFarmBlockedNavigationURL(url)) return;
@@ -4464,6 +4599,7 @@ ${islandValues ? `  // Islands mode: navigations name the layouts on screen, and
 
     // A route transition invalidates any trigger waiting on the previous DOM boundary.
     cancelPendingPageHydration();
+    this.stopNavigationStream();
     this.saveScrollPosition(window.location.pathname + window.location.search);
     const navigation = this.startNavigation(from, url, action);
     // A refresh keeps the islands still on the page (islands mode).
@@ -4588,6 +4724,7 @@ ${islandValues ? `  // Islands mode: navigations name the layouts on screen, and
         if (!this.isCurrentNavigation(navigation, clientNavigation)) return;
         await this.runViewTransition(options.viewTransition, async () => {
           if (!this.isCurrentNavigation(navigation, clientNavigation)) return;
+          let swappedHtml = html;
           let swapped = await this.swapContent(
             html,
             url.pathname + url.search,
@@ -4607,6 +4744,7 @@ ${islandValues ? `  // Islands mode: navigations name the layouts on screen, and
               false,
             );
             if (!this.isCurrentNavigation(navigation, clientNavigation)) return;
+            swappedHtml = documentHtml;
             swapped = await this.swapContent(
               documentHtml,
               url.pathname + url.search,
@@ -4618,6 +4756,7 @@ ${islandValues ? `  // Islands mode: navigations name the layouts on screen, and
           if (!swapped || swapped === "segment-mismatch") {
             throw new Error("Farm could not swap the target document");
           }
+          this.takeNavigationStream(swappedHtml);
           this.writeHistoryEntry(action, url.pathname + url.search, options.state, url);
           currentPathname = pathname;
           this.currentPath = to;
@@ -6796,11 +6935,16 @@ function escapeFarmHtmlAttribute(value) {
     .replace(/>/g, "&gt;");
 }
 
-async function renderFarmElement(ReactDOMServer, element, routeKey) {
+async function renderFarmElement(ReactDOMServer, element, routeKey, flushMarkers = false) {
+  // Written after each React flush in a streamed navigation (flushMarkers): the browser swaps in
+  // the shell, then adds each Suspense boundary as soon as the flush that completed it ends.
+  const FARM_FLUSH_MARKER = "<!--farm-flush-->";
   // Islands mode: each render writes its islands' values itself, so a request that renders twice
   // (notFound(), or a synchronous attempt that suspends and streams) still sends them.
   if (typeof farmIslandsRender === "function") element = farmIslandsRender(element);
   const streamErrors = [];
+  // A browser that leaves the page cancels the stream: React's abort errors are not failures.
+  let cancelled = false;
   const syncHtml = renderFarmElementSync(ReactDOMServer, element, routeKey);
   if (syncHtml !== undefined) return { html: syncHtml, shellHtml: syncHtml, streamErrors };
   let encoder;
@@ -6838,7 +6982,7 @@ async function renderFarmElement(ReactDOMServer, element, routeKey) {
         // request handler must still receive them to map the response status,
         // but they should not produce a misleading SSR failure log.
         streamErrors.push(error);
-        if (isFarmRedirectError(error) || isFarmNotFoundError(error)) return;
+        if (cancelled || isFarmRedirectError(error) || isFarmNotFoundError(error)) return;
         console.error("[Farm SSR stream]", error);
       },
     });
@@ -6885,13 +7029,33 @@ async function renderFarmElement(ReactDOMServer, element, routeKey) {
     }
 
     let replayFirstChunk = true;
+    let pendingRead = null;
+    // A flush is the chunks React has queued when a task boundary passes.
+    const drainFlush = async function(controller, waitForFirst) {
+      for (let first = waitForFirst; ; first = false) {
+        const read = pendingRead || (pendingRead = reader.read());
+        const result = first
+          ? await read
+          : await Promise.race([read, new Promise(function(resolve) { setTimeout(resolve, 0); })]);
+        if (!result) break;
+        pendingRead = null;
+        if (result.done) {
+          controller.close();
+          return;
+        }
+        controller.enqueue(normalizeChunk(result.value));
+      }
+      controller.enqueue(normalizeChunk(FARM_FLUSH_MARKER));
+    };
     const replayStream = new ReadableStream({
       pull(controller) {
         if (replayFirstChunk) {
           replayFirstChunk = false;
           controller.enqueue(firstChunk);
+          if (flushMarkers) return drainFlush(controller, false);
           return;
         }
+        if (flushMarkers) return drainFlush(controller, true);
         return reader.read().then(
           function(result) {
             if (result.done) controller.close();
@@ -6903,6 +7067,7 @@ async function renderFarmElement(ReactDOMServer, element, routeKey) {
         );
       },
       cancel(reason) {
+        cancelled = true;
         return reader.cancel(reason);
       },
     });
@@ -6927,6 +7092,7 @@ async function renderFarmElement(ReactDOMServer, element, routeKey) {
     let settleComplete;
     let rejectComplete;
     const chunks = [];
+    let unflushed = false;
     const decision = new Promise(function(resolve, reject) {
       settleDecision = resolve;
       rejectDecision = reject;
@@ -6949,8 +7115,15 @@ async function renderFarmElement(ReactDOMServer, element, routeKey) {
         const normalized = normalizeChunk(chunk);
         if (streamStarted) streamController.enqueue(normalized);
         else chunks.push(normalized);
+        unflushed = true;
         return true;
       },
+      // React calls this after each flush.
+      flush() {
+        if (!flushMarkers || !streamStarted || streamClosed || !unflushed) return;
+        unflushed = false;
+        streamController.enqueue(normalizeChunk(FARM_FLUSH_MARKER));
+      },
       end() {
         if (streamClosed) return;
         streamClosed = true;
@@ -6979,6 +7152,9 @@ async function renderFarmElement(ReactDOMServer, element, routeKey) {
                   streamController = controller;
                 },
                 cancel(reason) {
+                  // React writes its abort instructions: the stream no longer takes them.
+                  cancelled = true;
+                  streamClosed = true;
                   if (pipeableStream && typeof pipeableStream.abort === "function") {
                     pipeableStream.abort(reason);
                   }
@@ -6998,7 +7174,7 @@ async function renderFarmElement(ReactDOMServer, element, routeKey) {
       onError(error) {
         // Same control-flow guard as the readable-stream path above.
         streamErrors.push(error);
-        if (isFarmRedirectError(error) || isFarmNotFoundError(error)) return;
+        if (cancelled || isFarmRedirectError(error) || isFarmNotFoundError(error)) return;
         console.error("[Farm SSR stream]", error);
       },
     });
@@ -7019,6 +7195,11 @@ async function renderFarmElement(ReactDOMServer, element, routeKey) {
 
     streamStarted = true;
     for (const chunk of chunks) streamController.enqueue(chunk);
+    // What React wrote while its shell was ready is the shell; Suspense content follows.
+    if (flushMarkers && unflushed) {
+      unflushed = false;
+      streamController.enqueue(normalizeChunk(FARM_FLUSH_MARKER));
+    }
     if (streamClosed) streamController.close();
     return {
       stream,
@@ -9293,8 +9474,12 @@ ${hasServerRuntimeIntegrations ? `
           shouldHydrateLayout &&
           route.serverTree === true &&
           !route.shouldHydrate &&
-          request.headers.get("f-render") === "tree";` : `const farmLayoutKeyOf = null;
-        const farmPayloadOnlyNavigation = false;`}
+          request.headers.get("f-render") === "tree";
+        // A navigation the browser streams marks where each React flush ends, so the browser
+        // shows the page before its Suspense content arrives (FARM_FLUSH_MARKER).
+        const farmFlushMarkers = request.headers.get("f-stream") === "flush";` : `const farmLayoutKeyOf = null;
+        const farmPayloadOnlyNavigation = false;
+        const farmFlushMarkers = false;`}
         const renderPageElement = async () => {
             // First, render the page content
             let pageElement;
@@ -9416,7 +9601,7 @@ ${hasServerRuntimeIntegrations ? `
           }
 
           wrappedElement = wrapWithFarmIntegrationProviders(wrappedElement);
-          return renderFarmElement(ReactDOMServer, wrappedElement, route.pattern);
+          return renderFarmElement(ReactDOMServer, wrappedElement, route.pattern, farmFlushMarkers);
         };
         const renderedPage = ${hasMiddlewareRuntime ? `await _runWithMiddlewareData(middlewareData, () =>
           _runWithMiddlewareContext(middlewareContext, renderPageElement)
@@ -9539,7 +9724,7 @@ ${hasServerRuntimeIntegrations ? `
         // gets HTML without them.
         responseHeaders["Vary"] = farmSharedCacheableRoute
           ? "F-Layouts"
-          : "F-Values, F-Layouts, F-Render";` : ""}
+          : "F-Values, F-Layouts, F-Render, F-Stream";` : ""}
         let html = renderedPage.html;
         
         // Check if the layout already rendered a full HTML document