[Segment Bundling] [Scaffolding] Ensure inlining hint correctness (#91320)

Inlining hints (which segments to bundle together) are computed once at
build time by measuring gzip sizes, then persisted to
`prefetch-hints.json`. There are several scenarios where these hints may
not be available at render time. This commit addresses each scenario to
ensure the client always receives correct hints and never enters a bad
state.

### Build-time static pages (stale hints)

The initial RSC payload baked into the HTML is generated before hints
are computed, since hint computation requires at least one completed
render to measure sizes. The server marks these trees with
`InliningHintsStale`. The client immediately expires the route cache
entry so that the next prefetch re-fetches the correct tree from the
`/_tree` response. The segment data doesn't need re-fetching since it
was already cached from the initial HTML payload.

### ISR / revalidation

Hints are always available from the manifest. A missing entry is an
internal error — it means the build pipeline failed to produce hints for
a route that needs them.

### Fully dynamic routes at runtime

No hints exist and none will ever be computed. Every segment gets
`PrefetchDisabled`, which tells the client not to attempt prefetching.
This avoids an infinite re-fetch loop that would occur if the client
kept trying to fetch "correct" hints.

### Unified response format

Also simplifies the segment prefetch response format: every response is
now a `SegmentPrefetchResponse` with a top-level `buildId` and a `data`
array, treating a single-segment response as a bundle that happens to
have length one. This unifies the format so that bundled multi-segment
responses (added in a follow-up) require no additional client parsing
logic.

Author: acdlite

packages/next/errors.json

@@ -1140,5 +1140,9 @@
   "1139": "`unstable_catchError` can only be used in Client Components.",
   "1140": "Route %s used \\`import('next/root-params').%s()\\` inside \\`\"use cache\"\\` nested within \\`unstable_cache\\`. Root params are not available in this context.",
   "1141": "Route %s used \\`import('next/root-params').%s()\\` inside \\`unstable_cache\\`. This is not supported. Use \\`\"use cache\"\\` instead.",
-  "1142": "Route %s used \\`import('next/root-params').%s()\\` inside \\`generateStaticParams\\`, but the \\`%s\\` parameter was not provided by a parent \\`generateStaticParams\\`. In \\`generateStaticParams\\`, root params are only available for segments nested below the segment that provides them."
+  "1142": "Route %s used \\`import('next/root-params').%s()\\` inside \\`generateStaticParams\\`, but the \\`%s\\` parameter was not provided by a parent \\`generateStaticParams\\`. In \\`generateStaticParams\\`, root params are only available for segments nested below the segment that provides them.",
+  "1143": "Prefetch inlining is enabled but no hint tree was provided during incremental static revalidation. The prefetch-hints.json manifest should contain an entry for this route.",
+  "1144": "Prefetch inlining is enabled but no hints were found for route \"%s\". This is a bug in the Next.js build pipeline — prefetch-hints.json should contain an entry for every route that produces segment data.",
+  "1145": "Internal Next.js Error: Prefetch inlining is enabled but no hints were found for route \"%s\". prefetch-hints.json should contain an entry for every route that produces segment data. This is a bug in Next.js.",
+  "1146": "Internal Next.js Error: Prefetch inlining is enabled but no hint tree was provided during incremental static revalidation. The prefetch-hints.json manifest should contain an entry for this route. This is a bug in Next.js."
 }

packages/next/src/client/components/router-reducer/create-initial-router-state.ts

@@ -75,12 +75,12 @@ export function createInitialRouterState({
   // head is embedded into the CacheNode tree, but eventually we'll lift it out
   // and store it on the top-level state object.
   //
-  // TODO: For statically-generated-at-build-time HTML pages, the
-  // FlightRouterState baked into the initial RSC payload won't have the
-  // correct segment inlining hints (ParentInlinedIntoSelf, InlinedIntoChild)
-  // because those are computed after the pre-render. The client will need to
-  // fetch the correct hints from the route tree prefetch (/_tree) response
-  // before acting on inlining decisions.
+  // For statically-generated-at-build-time HTML pages, the FlightRouterState
+  // baked into the initial RSC payload won't have the correct segment inlining
+  // hints because those are computed after the pre-render. The server marks
+  // these trees with InliningHintsStale, which causes the route cache entry
+  // to be immediately expired. The next prefetch will re-fetch the tree with
+  // correct hints from the /_tree response.
   const acc = { metadataVaryPath: null }
   const initialRouteTree = convertRootFlightRouterStateToRouteTree(
     initialTree,

packages/next/src/client/components/segment-cache/cache.ts

@@ -1,7 +1,7 @@
 import type {
   TreePrefetch,
   RootTreePrefetch,
-  SegmentPrefetch,
+  SegmentPrefetchResponse,
   InlinedPrefetchResponse,
   InlinedSegmentPrefetch,
 } from '../../../server/app-render/collect-segment-data'
@@ -10,6 +10,7 @@ import type {
   FlightData,
   Segment as FlightRouterStateSegment,
 } from '../../../shared/lib/app-router-types'
+import { PrefetchHint } from '../../../shared/lib/app-router-types'
 import {
   readVaryParams,
   type VaryParams,
@@ -452,7 +453,7 @@ export function readRouteCacheEntry(
   // No cache hit. Attempt to construct from template using the new
   // optimistic routing mechanism (pattern-based matching).
   if (process.env.__NEXT_OPTIMISTIC_ROUTING) {
-    return matchKnownRoute(key.pathname, key.search)
+    return matchKnownRoute(now, key.pathname, key.search)
   }
 
   return null
@@ -1070,7 +1071,17 @@ export function fulfillRouteCacheEntry(
   // Always use the static stale time.
   // NOTE: An exception is rewrites/redirects in middleware or proxy, which can
   // change routes dynamically. We have other strategies for handling those.
-  fulfilledEntry.staleAt = now + STATIC_STALETIME_MS
+  //
+  // If the route tree has stale inlining hints (e.g. the initial RSC payload
+  // for a build-time static page, generated before collectPrefetchHints ran),
+  // immediately expire the entry so it gets re-fetched with correct hints.
+  // The segment data itself is still valid — only the route tree (which
+  // contains the hint bits) needs to be re-fetched.
+  if (tree.prefetchHints & PrefetchHint.InliningHintsStale) {
+    fulfilledEntry.staleAt = -1
+  } else {
+    fulfilledEntry.staleAt = now + STATIC_STALETIME_MS
+  }
   fulfilledEntry.couldBeIntercepted = couldBeIntercepted
   fulfilledEntry.canonicalUrl = canonicalUrl
   fulfilledEntry.renderedSearch = renderedSearch
@@ -1924,42 +1935,57 @@ export async function fetchSegmentOnCacheMiss(
       await createNonTaskyPrefetchResponseStream(response.body)
     closed.resolve()
     setSizeInCacheMap(segmentCacheEntry, responseSize)
-    const serverData = await createFromNextReadableStream<SegmentPrefetch>(
-      prefetchStream,
-      headers,
-      { allowPartialStream: true }
-    )
+    const serverResponse =
+      await createFromNextReadableStream<SegmentPrefetchResponse>(
+        prefetchStream,
+        headers,
+        { allowPartialStream: true }
+      )
     if (
       (response.headers.get(NEXT_NAV_DEPLOYMENT_ID_HEADER) ??
-        serverData.buildId) !== getNavigationBuildId()
+        serverResponse.buildId) !== getNavigationBuildId()
     ) {
       // The server build does not match the client. Treat as a 404. During
       // an actual navigation, the router will trigger an MPA navigation.
       rejectSegmentCacheEntry(segmentCacheEntry, Date.now() + 10 * 1000)
       return null
     }
-    const now = Date.now()
-    const staleAt = now + getStaleTimeMs(serverData.staleTime)
-    const fulfilledEntry = fulfillSegmentCacheEntry(
-      segmentCacheEntry,
-      serverData.rsc,
-      staleAt,
-      serverData.isPartial
-    )
+    // Iterate over the segment data in the response array. Currently each
+    // per-segment response contains a single entry, but the format supports
+    // bundled responses with multiple entries (used when segment inlining
+    // is enabled).
+    let fulfilledEntry: FulfilledSegmentCacheEntry | null = null
+    for (const serverData of serverResponse.data) {
+      if (serverData === null) {
+        // Null entries represent segments with static prefetch disabled
+        // (runtime prefetch or unstable_instant = false). Skip them.
+        continue
+      }
+      const now = Date.now()
+      const staleAt = now + getStaleTimeMs(serverData.staleTime)
+      fulfilledEntry = fulfillSegmentCacheEntry(
+        segmentCacheEntry,
+        serverData.rsc,
+        staleAt,
+        serverData.isPartial
+      )
 
-    // If the server tells us which params the segment varies by, we can re-key
-    // the entry to a more generic vary path. This allows the entry to be reused
-    // across different param values for params that the segment doesn't
-    // actually depend on.
-    const varyParams = serverData.varyParams
-    const fulfilledVaryPath =
-      process.env.__NEXT_VARY_PARAMS && varyParams !== null
-        ? getFulfilledSegmentVaryPath(tree.varyPath, varyParams)
-        : getSegmentVaryPathForRequest(segmentCacheEntry.fetchStrategy, tree)
-    // Re-key and upsert the entry at the fulfilled vary path. This ensures
-    // the entry is stored at the most generic path possible based on which
-    // params the segment actually depends on.
-    upsertSegmentEntry(now, fulfilledVaryPath, fulfilledEntry)
+      // If the server tells us which params the segment varies by, we can
+      // re-key the entry to a more generic vary path. This allows the entry
+      // to be reused across different param values for params that the
+      // segment doesn't actually depend on.
+      const varyParams = serverData.varyParams
+      const fulfilledVaryPath =
+        process.env.__NEXT_VARY_PARAMS && varyParams !== null
+          ? getFulfilledSegmentVaryPath(tree.varyPath, varyParams)
+          : getSegmentVaryPathForRequest(segmentCacheEntry.fetchStrategy, tree)
+      upsertSegmentEntry(now, fulfilledVaryPath, fulfilledEntry)
+    }
+
+    if (fulfilledEntry === null) {
+      rejectSegmentCacheEntry(segmentCacheEntry, Date.now() + 10 * 1000)
+      return null
+    }
 
     return {
       value: fulfilledEntry,
@@ -2037,7 +2063,7 @@ export async function fetchInlinedSegmentsOnCacheMiss(
 
     if (
       (response.headers.get(NEXT_NAV_DEPLOYMENT_ID_HEADER) ??
-        serverData.tree.segment.buildId) !== getNavigationBuildId()
+        serverData.buildId) !== getNavigationBuildId()
     ) {
       rejectSegmentEntriesIfStillPending(spawnedEntries, Date.now() + 10 * 1000)
       return null

packages/next/src/client/components/segment-cache/optimistic-routes.ts

@@ -49,9 +49,11 @@ import {
   EntryStatus,
   writeRouteIntoCache,
   fulfillRouteCacheEntry,
+  getCurrentRouteCacheVersion,
   type PendingRouteCacheEntry,
   createMetadataRouteTree,
 } from './cache'
+import { isValueExpired } from './cache-map'
 import { doesStaticSegmentAppearInURL } from '../../route-params'
 import type { NormalizedPathname, NormalizedSearch } from './cache-key'
 import {
@@ -137,6 +139,30 @@ type KnownRoutePart =
  */
 type ResolvedParams = Map<string, string | string[]>
 
+/**
+ * Read the pattern from a KnownRoutePart, evicting it if expired.
+ *
+ * This prevents stale patterns (e.g. from InliningHintsStale route entries
+ * with staleAt = -1) from being cloned into synthetic entries indefinitely.
+ * Once evicted, the pattern slot can be repopulated by the next
+ * discoverKnownRoute call with a fresh entry from a /_tree response.
+ */
+function readPattern(
+  now: number,
+  part: KnownRoutePart
+): FulfilledRouteCacheEntry | null {
+  const pattern = part.pattern
+  if (pattern === null) {
+    return null
+  }
+  if (isValueExpired(now, getCurrentRouteCacheVersion(), pattern)) {
+    // The pattern is expired. Null it out so the slot can be repopulated.
+    part.pattern = null
+    return null
+  }
+  return pattern
+}
+
 function createEmptyPart(): KnownRoutePart {
   return {
     staticChildren: null,
@@ -442,12 +468,13 @@ function discoverKnownRoutePart(
 
   // Reached a page node. Create/get the route cache entry and store as a
   // pattern. First, check if there's already a pattern for this route.
-  if (knownRoutePart.pattern !== null) {
+  const existingPattern = readPattern(now, knownRoutePart)
+  if (existingPattern !== null) {
     // If this route has a dynamic rewrite, mark the existing pattern.
     if (hasDynamicRewrite) {
-      knownRoutePart.pattern.hasDynamicRewrite = true
+      existingPattern.hasDynamicRewrite = true
     }
-    return knownRoutePart.pattern
+    return existingPattern
   }
 
   // Get or create the entry
@@ -486,12 +513,14 @@ function discoverKnownRoutePart(
  * pattern, or null if no match is found (fall back to server resolution).
  */
 export function matchKnownRoute(
+  now: number,
   pathname: string,
   search: NormalizedSearch
 ): FulfilledRouteCacheEntry | null {
   const pathnameParts = pathname.split('/').filter((p) => p !== '')
   const resolvedParams: ResolvedParams = new Map()
   const match = matchKnownRoutePart(
+    now,
     knownRouteTreeRoot,
     pathnameParts,
     0,
@@ -593,6 +622,7 @@ type KnownRouteMatch = {
  * Returns null if no match found (caller should fall back to server).
  */
 function matchKnownRoutePart(
+  now: number,
   part: KnownRoutePart,
   pathnameParts: string[],
   partIndex: number,
@@ -610,7 +640,7 @@ function matchKnownRoutePart(
   if (part.staticChildren === null) {
     // The only safe match is a direct pattern when no URL parts remain.
     if (urlPart === null) {
-      const pattern = part.pattern
+      const pattern = readPattern(now, part)
       if (pattern !== null && !pattern.hasDynamicRewrite) {
         return { part, pattern }
       }
@@ -636,6 +666,7 @@ function matchKnownRoutePart(
         return null
       }
       const match = matchKnownRoutePart(
+        now,
         staticChild,
         pathnameParts,
         partIndex + 1,
@@ -658,7 +689,7 @@ function matchKnownRoutePart(
     const dynamicPart = part.dynamicChild
     const paramName = part.dynamicChildParamName
     const paramType = part.dynamicChildParamType
-    const dynamicPattern = dynamicPart.pattern
+    const dynamicPattern = readPattern(now, dynamicPart)
 
     switch (paramType) {
       case 'c':
@@ -672,7 +703,7 @@ function matchKnownRoutePart(
           return { part: dynamicPart, pattern: dynamicPattern }
         }
         break
-      case 'oc':
+      case 'oc': {
         // Optional catch-all [[...param]]: consumes 0+ URL parts
         if (dynamicPattern !== null && !dynamicPattern.hasDynamicRewrite) {
           if (urlPart !== null) {
@@ -681,19 +712,22 @@ function matchKnownRoutePart(
           }
           // urlPart is null - can match with zero parts, but a direct pattern
           // (e.g., page.tsx alongside [[...param]]) takes precedence.
-          if (part.pattern === null || part.pattern.hasDynamicRewrite) {
+          const directPattern = readPattern(now, part)
+          if (directPattern === null || directPattern.hasDynamicRewrite) {
             resolvedParams.set(paramName, [])
             return { part: dynamicPart, pattern: dynamicPattern }
           }
         }
         break
+      }
       case 'd':
         // Regular dynamic [param]: consumes exactly 1 URL part.
         // Unlike catch-all which terminates here, regular dynamic must
         // continue recursing to find the leaf pattern.
         if (urlPart !== null) {
           resolvedParams.set(paramName, urlPart)
           return matchKnownRoutePart(
+            now,
             dynamicPart,
             pathnameParts,
             partIndex + 1,
@@ -721,7 +755,7 @@ function matchKnownRoutePart(
   // No children matched. If we've consumed all URL parts, check for a direct
   // pattern at this node (the route terminates here).
   if (urlPart === null) {
-    const pattern = part.pattern
+    const pattern = readPattern(now, part)
     if (pattern !== null && !pattern.hasDynamicRewrite) {
       return { part, pattern }
     }

packages/next/src/server/app-render/app-render.tsx

@@ -13,6 +13,7 @@ import type {
   FlightDataPath,
   PrefetchHints,
 } from '../../shared/lib/app-router-types'
+import { PrefetchHint } from '../../shared/lib/app-router-types'
 import type { Readable } from 'node:stream'
 import {
   workAsyncStorage,
@@ -1733,9 +1734,15 @@ async function getRSCPayload(
   } = ctx
 
   const hints = ctx.renderOpts.prefetchHints?.[ctx.pagePath] ?? null
+  const prefetchInliningEnabled = Boolean(
+    ctx.renderOpts.experimental.prefetchInlining
+  )
   const initialTree = await createFlightRouterStateFromLoaderTree(
     tree,
     hints,
+    prefetchInliningEnabled,
+    workStore.isStaticGeneration,
+    ctx.renderOpts.isBuildTimePrerendering ?? false,
     getDynamicParamFromSegment,
     query
   )
@@ -1924,9 +1931,15 @@ async function getErrorRSCPayload(
   )
 
   const errorHints = ctx.renderOpts.prefetchHints?.[ctx.pagePath] ?? null
+  const errorPrefetchInliningEnabled = Boolean(
+    ctx.renderOpts.experimental.prefetchInlining
+  )
   const initialTree = await createFlightRouterStateFromLoaderTree(
     tree,
     errorHints,
+    errorPrefetchInliningEnabled,
+    workStore.isStaticGeneration,
+    ctx.renderOpts.isBuildTimePrerendering ?? false,
     getDynamicParamFromSegment,
     query
   )
@@ -7244,7 +7257,27 @@ async function collectSegmentData(
   } else {
     // Runtime: use hints from the manifest. Never compute fresh hints
     // during ISR/revalidation.
-    hints = renderOpts.prefetchHints?.[pagePath] ?? null
+    const manifestHints = renderOpts.prefetchHints?.[pagePath]
+    if (manifestHints === undefined) {
+      // TODO(#91407): No hints found for this route. This currently
+      // happens for routes with `instant = false` at the root segment,
+      // which causes the prerender to run per-request and the hints
+      // manifest to be unavailable at runtime.
+      //
+      // Fall back to a hint tree that marks everything as unprefetchable.
+      // The root gets PrefetchDisabled, and children inherit null hints
+      // which triggers PrefetchDisabled in createFlightRouterStateFromLoaderTree.
+      //
+      // Once the instant:false bug is fixed, this should become an error —
+      // the manifest should always have an entry for every route that
+      // reaches collectSegmentData.
+      hints = {
+        hints: PrefetchHint.PrefetchDisabled,
+        slots: null,
+      }
+    } else {
+      hints = manifestHints
+    }
   }
 
   // Pass the resolved hints so collectSegmentData can union them into