Add group depth tracking to instant validation boundary discovery (#91208)

The depth-based instant validation previously only iterated
URL-consuming segments as potential shared/new boundaries. Route groups
between URL segments were invisible — when a route group layout with
Suspense was shared in a client navigation, its Suspense appeared to
cover blocking code in the validation render even though it wouldn't in
reality.

This adds a second dimension to the validation iteration: group depth.
At each URL depth, we now also step through route group boundaries. A
new `discoverValidationDepths` function walks the LoaderTree and returns
an array where each entry represents the max group depth at that URL
depth. The validation loop iterates from deepest group depth to
shallowest within each URL depth, stopping on the first error.

Key design decisions:
- URL depth and group depth counters are advanced before the boundary
check, making the boundary condition a simple `nextUrlDepth > depth &&
currentGroupDepth >= groupDepth`
- The synthetic `(slot)` segment that Next.js inserts for parallel slots
is excluded from group depth counting since it doesn't represent a real
navigation boundary
- Group depths are discovered from the LoaderTree rather than the URL
pathname, making the tree the source of truth for validation bounds

Author: gnoff

crates/next-core/src/app_structure.rs

@@ -1264,7 +1264,7 @@ async fn directory_tree_to_loader_tree_internal(
     let current_level_is_parallel_route = is_parallel_route(&directory_name);
 
     if current_level_is_parallel_route {
-        tree.segment = rcstr!("(slot)");
+        tree.segment = rcstr!("(__SLOT__)");
     }
 
     if let Some(page) = (app_path == for_app_path || app_path.is_catchall())

packages/next/src/build/webpack/loaders/next-app-loader/index.ts

@@ -429,7 +429,7 @@ async function createTreeCodeFromPath(
       parallelSegmentKey =
         parallelSegmentKey === PARALLEL_VIRTUAL_SEGMENT ||
         parallelSegmentKey === PAGE_SEGMENT
-          ? '(slot)'
+          ? '(__SLOT__)'
           : parallelSegmentKey
 
       const normalizedParallelKey = normalizeParallelKey(parallelKey)

packages/next/src/client/components/layout-router.tsx

@@ -877,9 +877,9 @@ function getBoundaryDebugNameFromSegment(segment: Segment): string | undefined {
 
 function isVirtualLayout(segment: string): boolean {
   return (
-    // This is inserted by the loader. We should consider encoding these
-    // in a more special way instead of checking the name, to distinguish them
-    // from app-defined groups.
-    segment === '(slot)'
+    // This is inserted by the loader. Uses double-underscore convention
+    // (like __PAGE__ and __DEFAULT__) to avoid collisions with
+    // user-defined route groups.
+    segment === '(__SLOT__)'
   )
 }

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

@@ -4662,6 +4662,7 @@ async function validateInstantConfigs(
     createCombinedPayloadAtDepth,
     createCombinedPayloadStream,
     collectStagedSegmentData,
+    discoverValidationDepths,
   } = ctx.componentMod.InstantValidation()!
 
   const { createValidationSampleTracking } =
@@ -4707,13 +4708,15 @@ async function validateInstantConfigs(
    * runtime and dynamic errors, returning the more specific result.
    */
   async function validateAtDepth(
-    depth: number
+    depth: number,
+    groupDepthForValidation: number
   ): Promise<Array<unknown> | null> {
-    return validateAtDepthImpl(depth, null)
+    return validateAtDepthImpl(depth, groupDepthForValidation, null)
   }
 
   async function validateAtDepthImpl(
     depth: number,
+    groupDepthForValidation: number,
     previousBoundaryState: null | ValidationBoundaryTracking
   ): Promise<null | Array<unknown>> {
     const extraChunksController = new AbortController()
@@ -4735,6 +4738,7 @@ async function validateInstantConfigs(
       ctx.getDynamicParamFromSegment,
       ctx.query,
       depth,
+      groupDepthForValidation,
       extraChunksController.signal,
       boundaryState,
       clientReferenceManifest,
@@ -4914,7 +4918,11 @@ async function validateInstantConfigs(
     if (previousBoundaryState === null && payloadResult.hasAmbiguousErrors) {
       // This is the first validation attempt. we prepared a payload where dynamic holes might be runtime data dependencies
       // or dynamic data dependencies. We do a followup validation using a payload with only Runtime segments to discriminate
-      const dynamicOnlyErrors = await validateAtDepthImpl(depth, boundaryState)
+      const dynamicOnlyErrors = await validateAtDepthImpl(
+        depth,
+        groupDepthForValidation,
+        boundaryState
+      )
 
       if (dynamicOnlyErrors !== null && dynamicOnlyErrors.length > 0) {
         // The dynamic errors only validation found errors to report so we favor those
@@ -4926,25 +4934,43 @@ async function validateInstantConfigs(
     return errors
   }
 
-  const urlSegments = ctx.url.pathname.split('/').filter(Boolean)
-  const maxDepth = urlSegments.length + 1 // +1 for root
+  // Discover validation depth bounds from the LoaderTree. The array
+  // length is the max URL depth; each entry is the max group depth
+  // (route group segments) between that URL depth and the next.
+  const groupDepthsByUrlDepth = discoverValidationDepths(loaderTree)
+  const maxDepth = groupDepthsByUrlDepth.length
 
   for (let depth = maxDepth - 1; depth >= 0; depth--) {
-    debug?.(`Trying depth ${depth}...`)
+    const maxGroupDepth = groupDepthsByUrlDepth[depth]
 
-    const errors = await validateAtDepth(depth)
+    for (
+      let currentGroupDepth = maxGroupDepth;
+      currentGroupDepth >= 0;
+      currentGroupDepth--
+    ) {
+      debug?.(
+        `Trying depth ${depth}` +
+          (currentGroupDepth > 0
+            ? ` + groupDepth ${currentGroupDepth}...`
+            : '...')
+      )
 
-    if (errors === null) {
-      debug?.(`  No config at depth ${depth}, skipping.`)
-      continue
-    }
+      const errors = await validateAtDepth(depth, currentGroupDepth)
 
-    if (errors.length > 0) {
-      debug?.(`  Depth ${depth}: ❌ Failed (${errors.length} errors)`)
-      return errors
-    }
+      if (errors === null) {
+        debug?.(`  No config at depth ${depth}+${currentGroupDepth}, skipping.`)
+        continue
+      }
+
+      if (errors.length > 0) {
+        debug?.(
+          `  Depth ${depth}+${currentGroupDepth}: ❌ Failed (${errors.length} errors)`
+        )
+        return errors
+      }
 
-    debug?.(`  Depth ${depth}: ✅ Passed`)
+      debug?.(`  Depth ${depth}+${currentGroupDepth}: ✅ Passed`)
+    }
   }
 
   debug?.(`✅ All depths passed`)

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

@@ -785,6 +785,86 @@ function segmentConsumesURLDepth(segment: Segment): boolean {
   return true
 }
 
+/**
+ * Walks the LoaderTree to discover validation depth bounds.
+ *
+ * Each route group between URL segments represents a potential
+ * shared/new boundary in a client navigation. When a user navigates
+ * between sibling routes that share a route group layout, that
+ * layout is already mounted — its Suspense boundaries are revealed
+ * and don't cover new content below. By tracking the max group
+ * depth at each URL depth, we can iterate all possible group
+ * boundaries and validate that blocking code is always covered by
+ * Suspense in the new tree. This is conservative: some boundaries
+ * may not correspond to real navigations (e.g. a route group with
+ * no siblings), but it ensures we don't miss real violations.
+ *
+ * The max is taken across all parallel slots. When slots have
+ * different numbers of groups, the deepest slot determines the
+ * iteration range. Shallower slots simply stay entirely shared
+ * at group depths beyond their own group count — they run out
+ * of groups before reaching the boundary, so their content
+ * remains in the Dynamic stage.
+ *
+ * Returns an array where:
+ * - length = max URL depth (number of URL-consuming segments)
+ * - array[i] = max group depth at URL depth i (number of route group
+ *   segments between this URL depth and the next)
+ *
+ * For example, a tree like:
+ *   '' / (outer) / (inner) / dashboard / page
+ * returns [2, 0] — URL depth 0 (root) has 2 group layers before
+ * the next URL segment (dashboard), and URL depth 1 (dashboard) has
+ * 0 group layers before the leaf.
+ */
+export function discoverValidationDepths(loaderTree: LoaderTree): number[] {
+  const groupDepthsByUrlDepth: number[] = []
+
+  function recordGroupDepth(urlDepth: number, groupDepth: number): void {
+    while (groupDepthsByUrlDepth.length <= urlDepth) {
+      groupDepthsByUrlDepth.push(0)
+    }
+    if (groupDepth > groupDepthsByUrlDepth[urlDepth]) {
+      groupDepthsByUrlDepth[urlDepth] = groupDepth
+    }
+  }
+
+  // urlDepth tracks the index of the current URL-consuming segment.
+  // Groups accumulate at the same index. When the next URL segment
+  // is reached, it increments the index and resets the group counter.
+  // We start at -1 so the root segment '' increments to 0.
+  function walk(tree: LoaderTree, urlDepth: number, groupDepth: number): void {
+    const segment = tree[0]
+    const { parallelRoutes } = parseLoaderTree(tree)
+    const consumesDepth = segmentConsumesURLDepth(segment)
+
+    let nextUrlDepth = urlDepth
+    let nextGroupDepth = groupDepth
+    if (consumesDepth) {
+      nextUrlDepth = urlDepth + 1
+      nextGroupDepth = 0
+      recordGroupDepth(nextUrlDepth, 0)
+    } else if (
+      typeof segment === 'string' &&
+      isGroupSegment(segment) &&
+      segment !== '(__SLOT__)'
+    ) {
+      // Count real route groups but not the synthetic '(__SLOT__)' segment
+      // that Next.js inserts for parallel slots. The synthetic group
+      // can't be a real navigation boundary.
+      nextGroupDepth++
+      recordGroupDepth(urlDepth, nextGroupDepth)
+    }
+
+    for (const key in parallelRoutes) {
+      walk(parallelRoutes[key], nextUrlDepth, nextGroupDepth)
+    }
+  }
+
+  walk(loaderTree, -1, 0)
+  return groupDepthsByUrlDepth
+}
+
 /**
  * Builds a combined RSC payload for validation at a given URL depth.
  *
@@ -815,6 +895,7 @@ export async function createCombinedPayloadAtDepth(
   getDynamicParamFromSegment: GetDynamicParamFromSegment,
   query: NextParsedUrlQuery | null,
   depth: number,
+  groupDepth: number,
   releaseSignal: AbortSignal,
   boundaryState: ValidationBoundaryTracking,
   clientReferenceManifest: ClientReferenceManifest,
@@ -837,7 +918,8 @@ export async function createCombinedPayloadAtDepth(
     loaderTree: LoaderTree,
     parentPath: SegmentPath | null,
     key: string | null,
-    urlDepthConsumed: number
+    urlDepthConsumed: number,
+    groupDepthConsumed: number
   ): Promise<TreeResult> {
     const { parallelRoutes } = parseLoaderTree(loaderTree)
 
@@ -862,12 +944,35 @@ export async function createCombinedPayloadAtDepth(
       null
     )
 
-    const consumesDepth = segmentConsumesURLDepth(segment)
+    const consumesUrlDepth = segmentConsumesURLDepth(segment)
+    const isGroup =
+      typeof segment === 'string' &&
+      isGroupSegment(segment) &&
+      segment !== '(__SLOT__)'
+
+    // Advance counters for this segment before the boundary check,
+    // mirroring how discoverValidationDepths counts. URL segments
+    // increment urlDepthConsumed, groups increment groupDepthConsumed.
+    // The synthetic '(__SLOT__)' segment is excluded — it can't be a
+    // real navigation boundary.
+    let nextUrlDepth = urlDepthConsumed
+    let currentGroupDepth = groupDepthConsumed
+    if (consumesUrlDepth) {
+      nextUrlDepth++
+      currentGroupDepth = 0
+    } else if (isGroup) {
+      currentGroupDepth++
+    }
+
+    const pastUrlBoundary = nextUrlDepth > depth
+    const isBoundary = pastUrlBoundary && currentGroupDepth >= groupDepth
 
-    if (consumesDepth && urlDepthConsumed === depth) {
-      debug?.(`    ['${path}' is the boundary]`)
+    if (isBoundary) {
+      debug?.(
+        `    ['${path}' is the boundary (url=${nextUrlDepth}, group=${currentGroupDepth})]`
+      )
       boundaryState.expectedIds.add(path)
-      const wrappedSegmentData: SegmentData = {
+      const finalSegmentData: SegmentData = {
         ...segmentData,
         node: (
           // eslint-disable-next-line @next/internal/no-ambiguous-jsx -- bundled in the server layer
@@ -876,6 +981,7 @@ export async function createCombinedPayloadAtDepth(
           </PlaceValidationBoundaryBelowThisLevel>
         ),
       }
+
       const slots: CacheNodeSeedDataSlots = {}
       let requiresInstantUI = false
       let createInstantStack: (() => Error) | null = null
@@ -895,13 +1001,13 @@ export async function createCombinedPayloadAtDepth(
         }
       }
       return {
-        seedData: getCacheNodeSeedDataFromSegment(wrappedSegmentData, slots),
+        seedData: getCacheNodeSeedDataFromSegment(finalSegmentData, slots),
         requiresInstantUI,
         createInstantStack,
       }
     }
 
-    // Not the boundary yet — keep walking the shared tree.
+    // Not at the boundary yet — keep walking as shared.
     const slots: CacheNodeSeedDataSlots = {}
     let requiresInstantUI = false
     let createInstantStack: (() => Error) | null = null
@@ -910,7 +1016,8 @@ export async function createCombinedPayloadAtDepth(
         parallelRoutes[parallelRouteKey],
         path,
         parallelRouteKey,
-        consumesDepth ? urlDepthConsumed + 1 : urlDepthConsumed
+        nextUrlDepth,
+        currentGroupDepth
       )
       slots[parallelRouteKey] = result.seedData
       if (result.requiresInstantUI) {
@@ -947,7 +1054,6 @@ export async function createCombinedPayloadAtDepth(
     if (layoutOrPageMod !== undefined) {
       instantConfig =
         (layoutOrPageMod as AppSegmentConfig).unstable_instant ?? null
-
       if (instantConfig && typeof instantConfig === 'object') {
         const rawFactory: unknown = (layoutOrPageMod as any)
           .__debugCreateInstantConfigStack
@@ -1042,7 +1148,8 @@ export async function createCombinedPayloadAtDepth(
       initialLoaderTree,
       null /* parentPath */,
       null /* key */,
-      0 /* urlDepthConsumed */
+      0 /* urlDepthConsumed */,
+      0 /* groupDepthConsumed */
     )
 
   if (!requiresInstantUI) {

test/e2e/app-dir/instant-validation/app/suspense-in-root/page.tsx

@@ -91,7 +91,7 @@ export default async function Page() {
           <DebugLinks href="/suspense-in-root/static/valid-only-loading-around-dynamic" />
         </li>
         <li>
-          <DebugLinks href="/suspense-in-root/static/valid-only-loading-around-dynamic-higher" />
+          <DebugLinks href="/suspense-in-root/static/invalid-loading-above-route-group" />
         </li>
         <li>
           <DebugLinks href="/suspense-in-root/static/invalid-dynamic-layout-with-loading" />
@@ -185,6 +185,12 @@ export default async function Page() {
         <li>
           <DebugLinks href="/suspense-in-root/static/route-group-shared-boundary" />
         </li>
+        <li>
+          <DebugLinks href="/suspense-in-root/static/parallel-group-depths-deep-slot-hole" />
+        </li>
+        <li>
+          <DebugLinks href="/suspense-in-root/static/parallel-group-depths-shallow-slot-hole" />
+        </li>
         <li>
           <DebugLinks href="/suspense-in-root/static/route-group-shared-boundary/foo" />
         </li>

…g-around-dynamic-higher/(group)/page.tsx …ading-above-route-group/(group)/page.tsxtest/e2e/app-dir/instant-validation/app/suspense-in-root/static/valid-only-loading-around-dynamic-higher/(group)/page.tsx renamed to test/e2e/app-dir/instant-validation/app/suspense-in-root/static/invalid-loading-above-route-group/(group)/page.tsx test/e2e/app-dir/instant-validation/app/suspense-in-root/static/valid-only-loading-around-dynamic-higher/(group)/page.tsx renamed to test/e2e/app-dir/instant-validation/app/suspense-in-root/static/invalid-loading-above-route-group/(group)/page.tsx

@@ -11,8 +11,12 @@ export default async function Page() {
     <main>
       <p>
         This page doesn't wrap runtime/dynamic components in suspense, but it
-        has a loading.tsx above it. a self-navigation with a different search
-        param value would block, but we accept that.
+        has a loading.tsx above it. However, the page is inside a route group
+        and the loading.tsx is on the parent URL segment. Validation considers
+        the route group as a potential shared boundary where the loading.tsx
+        Suspense would already be revealed. In a more advanced system we would
+        analyze siblings of the route group to determine if such a navigation is
+        actually possible, but for now we conservatively report an error.
       </p>
       <div>
         <Runtime />

…oading-around-dynamic-higher/loading.tsx …id-loading-above-route-group/loading.tsxtest/e2e/app-dir/instant-validation/app/suspense-in-root/static/valid-only-loading-around-dynamic-higher/loading.tsx renamed to test/e2e/app-dir/instant-validation/app/suspense-in-root/static/invalid-loading-above-route-group/loading.tsx test/e2e/app-dir/instant-validation/app/suspense-in-root/static/valid-only-loading-around-dynamic-higher/loading.tsx renamed to test/e2e/app-dir/instant-validation/app/suspense-in-root/static/invalid-loading-above-route-group/loading.tsx

@@ -0,0 +1,7 @@
+import { cookies } from 'next/headers'
+import { ReactNode } from 'react'
+
+export default async function B2Layout({ children }: { children: ReactNode }) {
+  await cookies()
+  return <div>{children}</div>
+}

test/e2e/app-dir/instant-validation/app/suspense-in-root/static/parallel-group-depths-deep-slot-hole/(b1)/(b2)/layout.tsx

@@ -0,0 +1,9 @@
+export const unstable_instant = { prefetch: 'static' }
+
+export default function Page() {
+  return (
+    <main>
+      <p>Children page inside 2 nested route groups</p>
+    </main>
+  )
+}