Instant Validation

Copyasync function visit(tree: LoaderTree): Promise<void> {
  if (disabled) return
 
  const { mod: layoutOrPageMod } = await getLayoutOrPageModule(tree)
  const instantConfig = layoutOrPageMod
    ? (layoutOrPageMod as AppSegmentConfig).instant
    : undefined
 
  if (instantConfig === false) {
    // Explicit opt-out. Doesn't itself trigger validation.
  } else if (instantConfig === true) {
    // Explicit opt-in using the default level.
    if (level <= baseValidationLevel) {
      needsValidation = true
    }
  } else if (typeof instantConfig === 'object' && instantConfig !== null) {
    if (
      instantConfig.unstable_disableValidation === true ||
      (level === VALIDATION_LEVEL.WARNING &&
        instantConfig.unstable_disableDevValidation === true) ||
      (level === VALIDATION_LEVEL.ERROR &&
        instantConfig.unstable_disableBuildValidation === true)
    ) {
      disabled = true
      return
    }
 
    if (instantConfig.level !== undefined) {
      const configuredLevel =
        instantConfig.level === 'experimental-error'
          ? VALIDATION_LEVEL.ERROR
          : VALIDATION_LEVEL.WARNING
      if (level <= configuredLevel) {
        needsValidation = true
      }
    } else if (level <= baseValidationLevel) {
      needsValidation = true
    }
  } else if (applyDefaultValidation && isImplicitValidationSegment(tree[0])) {
    // No explicit config. Implicit validation applies to page/default
    // segments when the default level is active for this mode.
    needsValidation = true
  }
 
  const { parallelRoutes } = parseLoaderTree(tree)
  for (const parallelRouteKey in parallelRoutes) {
    await visit(parallelRoutes[parallelRouteKey])
    if (disabled) return
  }
}

Copyenum VALIDATION_LEVEL {
  WARNING = 0,
  ERROR = 1,
}
 
/**
 * Walks the loader tree and checks if any segment has an `instant` config
 * that needs validating for the given mode.
 *
 * - Explicit `instant` exports are checked against mode.
 * - Page and default segments without an explicit config get implicit
 *   validation when the default validation level applies to this mode.
 * - `unstable_disableValidation` on any segment kills validation for
 *   the whole tree.
 */
async function anySegmentNeedsInstantValidation(
  rootTree: LoaderTree,
  level: VALIDATION_LEVEL
): Promise<boolean> {
  const workStore = workAsyncStorage.getStore()
  if (!workStore) {
    throw new InvariantError(
      'anySegmentNeedsInstantValidation must run inside a WorkStore'
    )
  }
  const { validationLevel } = workStore
 
  let baseValidationLevel: number = VALIDATION_LEVEL.WARNING
  let manualValidation: boolean = false
  switch (validationLevel) {
    case 'manual-warning':
      manualValidation = true
    // intentional fallthrough
    case 'warning':
      baseValidationLevel = VALIDATION_LEVEL.WARNING
      break
    case 'experimental-manual-error':
      manualValidation = true
    // intentional fallthrough
    case 'experimental-error':
      baseValidationLevel = VALIDATION_LEVEL.ERROR
      break
    default:
      validationLevel satisfies never
  }

Copyexport function isImplicitValidationSegment(segment: Segment): boolean {
  const key = typeof segment === 'string' ? segment : segment[0]
  return key === PAGE_SEGMENT_KEY || key === DEFAULT_SEGMENT_KEY
}

Copytype BoundaryPlacement =
  | null // do not place here
  | string // boundaryId -- place here
 
export const InstantValidationBoundaryContext =
  createContext<BoundaryPlacement>(null)
 
export function PlaceValidationBoundaryBelowThisLevel({
  id,
  children,
}: {
  id: string
  children: ReactNode
}) {
  return (
    // OuterLayoutRouter will see this and render a `RenderValidationBoundaryAtThisLevel`.
    <InstantValidationBoundaryContext value={id}>
      {children}
    </InstantValidationBoundaryContext>
  )
}

Copyexport function RenderValidationBoundaryAtThisLevel({
  id,
  children,
}: {
  id: string
  children: ReactNode
}) {
  // We got a boundaryId from the context. Clear the context so that the children don't render another boundary.
  return (
    <InstantValidationBoundary id={id}>
      <InstantValidationBoundaryContext value={null}>
        {children}
      </InstantValidationBoundaryContext>
    </InstantValidationBoundary>
  )
}

Copyconst NameSpace = {
  [INSTANT_VALIDATION_BOUNDARY_NAME]: function ({
    id,
    children,
  }: {
    id: string
    children: ReactNode
  }) {
    // Track which boundaries we actually managed to render.
    const state = getValidationBoundaryTracking()
    if (state === null) {
      throw new InvariantError('Missing boundary tracking state')
    }
    state.renderedIds.add(id)
 
    return children
  },
}

Copyexport const INSTANT_VALIDATION_BOUNDARY_NAME =
  '__next_instant_validation_boundary__'
 
export const INSTANT_SLOT_MARKER_PREFIX = '__next_instant_slot_'
export const INSTANT_SLOT_MARKER_SUFFIX = '__'

Copyconst slotMarkerCache = new Map<
  string,
  (props: { children: ReactNode }) => ReactNode
>()
 
export function SlotMarker({
  name,
  children,
}: {
  name: string
  children: ReactNode
}) {
  let Marker = slotMarkerCache.get(name)
  if (!Marker) {
    const ns = {
      [name]: function ({ children: c }: { children: ReactNode }) {
        return c
      },
    }
    Marker = ns[name]
    slotMarkerCache.set(name, Marker)
  }
  return <Marker>{children}</Marker>
}

Copyexport type ValidationBoundaryTracking = {
  /**
   * Map from boundary id (the SegmentPath where a validation boundary is
   * placed) to the file paths of modules inside that boundary's subtree.
   * When the boundary spans multiple parallel slots, each slot contributes
   * its own first-found module path so all unrendered segments can be
   * reported together.
   */
  requiredIds: Map<string, string[]>
  renderedIds: Set<string>
}

Copyexport function createValidationBoundaryTracking(
  /** Pass if the render is expected to render the same IDs as a previous one. */
  matchPrevious?: ValidationBoundaryTracking
): ValidationBoundaryTracking {
  return {
    requiredIds: matchPrevious ? new Map(matchPrevious.requiredIds) : new Map(),
    renderedIds: new Set(),
  }
}
 
export function allRequiredBoundariesRendered(
  state: ValidationBoundaryTracking
): boolean {
  for (const id of state.requiredIds.keys()) {
    if (!state.renderedIds.has(id)) {
      return false
    }
  }
  return true
}

Copyfunction getValidationBoundaryTracking(): ValidationBoundaryTracking | null {
  const store = workUnitAsyncStorage.getStore()
  if (!store) return null
  switch (store.type) {
    case 'validation-client':
      return store.boundaryState
    case 'prerender':
    case 'prerender-client':
    case 'prerender-legacy':
    case 'prerender-runtime':
    case 'request':
    case 'cache':
    case 'private-cache':
    case 'unstable-cache':
    case 'build-time-generator':
      break
    default:
      store satisfies never
  }
  return null
}

Copy    // Track which boundaries we actually managed to render.
    const state = getValidationBoundaryTracking()
    if (state === null) {
      throw new InvariantError('Missing boundary tracking state')
    }
    state.renderedIds.add(id)
 
    return children
  },
}

Copyexport function createCookiesFromSample(
  sampleCookies: InstantSample['cookies'],
  route: string
): ReadonlyRequestCookies {
  const declaredNames = new Set<string>()
 
  const cookies = new RequestCookies(new Headers())
  if (sampleCookies) {
    for (const cookie of sampleCookies) {
      declaredNames.add(cookie.name)
      if (cookie.value !== null) {
        cookies.set(cookie.name, cookie.value)
      }
    }
  }
 
  const sealed = RequestCookiesAdapter.seal(cookies)
 
  return new Proxy(sealed, {
    get(target, prop, receiver) {
      if (prop === 'has') {
        const originalMethod = Reflect.get(target, prop, receiver)
        const wrappedMethod: typeof originalMethod = function (name) {
          if (!declaredNames.has(name)) {
            trackMissingSampleErrorAndThrow(
              createMissingCookieSampleError(route, name)
            )
          }
          return originalMethod.call(target, name)
        }
        return wrappedMethod
      }
      if (prop === 'get') {
        const originalMethod = Reflect.get(target, prop, receiver)
        const wrappedMethod: typeof originalMethod = function (nameOrCookie) {
          let name: string
          if (typeof nameOrCookie === 'string') {
            name = nameOrCookie
          } else if (
            nameOrCookie &&
            typeof nameOrCookie === 'object' &&
            typeof nameOrCookie.name === 'string'
          ) {
            name = nameOrCookie.name
          } else {
            // This is an invalid input. Pass it through to the original method so it can error.
            return originalMethod.call(target, nameOrCookie)
          }
 
          if (!declaredNames.has(name)) {
            trackMissingSampleErrorAndThrow(
              createMissingCookieSampleError(route, name)
            )
          }
          return originalMethod.call(target, name)
        }
        return wrappedMethod
      }
 
      // TODO(instant-validation-build): what should getAll do?
      // Maybe we should only allow it if there's an array (possibly empty?)
 
      return Reflect.get(target, prop, receiver)
    },
  })
}

Copyexport function instrumentParamsForClientValidation<TPArams extends Params>(
  underlyingParams: TPArams
): TPArams {
  const workStore = workAsyncStorage.getStore()
  const workUnitStore = workUnitAsyncStorage.getStore()
  if (workStore && workUnitStore) {
    switch (workUnitStore.type) {
      case 'validation-client': {
        if (workUnitStore.validationSamples) {
          const declaredKeys = new Set(
            Object.keys(workUnitStore.validationSamples.params ?? {})
          )
          return createExhaustiveParamsProxy(
            underlyingParams,
            declaredKeys,
            workStore.route
          )
        }
        break
      }
      case 'prerender-runtime':
      case 'prerender-client':
      case 'prerender-legacy':
      case 'prerender':
      case 'cache':
      case 'request':
      case 'private-cache':
      case 'unstable-cache':
      case 'build-time-generator':
        break
      default:
        workUnitStore satisfies never
    }
  }
  return underlyingParams
}

Copyexport async function collectStagedSegmentData(
  prefetchKind: ValidationPrefetchKind,
  ComponentMod: FlightComponentMod,
  renderFlightStream: RenderToFlightStream,
  fullPageChunks: StageChunks,
  fullPageDebugChunks: Uint8Array[] | null,
  startTime: number,
  stageEndTimes: StageEndTimes,
  clientReferenceManifest: ClientReferenceManifest,
  createDebugChannel: () => DebugChannelPair | undefined
): Promise<{ cache: SegmentCache; payload: InitialRSCPayload }> {
  const cache = createSegmentCache()
 
  let partialStages: SegmentStage[]
  switch (prefetchKind) {
    case ValidationPrefetchKind.StaticAppShell: {
      partialStages = [
        RenderStage.ShellStatic,
        RenderStage.PrefetchStatic_prefetchApi,
        RenderStage.PrefetchStatic,
        RenderStage.NavigationStatic, // TODO(cache-stages): only if needed
        RenderStage.PrefetchRuntime,
      ]
      break
    }
    case ValidationPrefetchKind.RuntimeAppShell: {
      partialStages = [
        RenderStage.ShellRuntime,
        RenderStage.PrefetchRuntime_prefetchApi,
        RenderStage.PrefetchRuntime,
        RenderStage.NavigationRuntime, // TODO(cache-stages): only if needed

Copyfunction traverseRootSeedDataSegments(
  initialRSCPayload: InitialRSCPayload,
  processSegment: (segmentPath: SegmentPath, data: TransportSegmentData) => void
) {
  const rootNode = initialRSCPayload.t.t
  const rootPath = stringifySegment(transportSegmentToSegment(rootNode.s))
  return traverseTransportNodeSegments(rootPath, rootNode, processSegment)
}
 
function traverseTransportNodeSegments(
  path: SegmentPath,
  node: FullTransportNode,
  processSegment: (segmentPath: SegmentPath, data: TransportSegmentData) => void
): void {
  processSegment(path, node.d)
 
  const children = node.c
  if (children === undefined) {
    return
  }
  for (const [parallelRouteKey, childNode] of children) {
    const childPath = createChildSegmentPath(
      path,
      parallelRouteKey,
      transportSegmentToSegment(childNode.s)
    )
 
    traverseTransportNodeSegments(childPath, childNode, processSegment)
  }
}
 
function createChildSegmentPath(
  parentPath: SegmentPath,
  parallelRouteKey: string,
  segment: Segment
): SegmentPath {
  const parallelRoutePrefix =
    parallelRouteKey === 'children'
      ? ''
      : `@${encodeURIComponent(parallelRouteKey)}/`
  return `${parentPath}/${parallelRoutePrefix}${stringifySegment(segment)}` as SegmentPath
}
 
function stringifySegment(segment: Segment): SegmentPath {
  return (
    typeof segment === 'string'
      ? encodeURIComponent(segment)
      : encodeURIComponent(segment[0]) + '|' + segment[1] + '|' + segment[2]
  ) as SegmentPath
}

Copyexport 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

Copyexport async function buildDevValidationSnapshot(
  ctx: AppRenderContext,
  instantInputs: ResolvedValidationInputs | null,
  staticInputs: ResolvedValidationInputs,
  prefetchMode: PrefetchingMode,
  fallbackRouteParams: OpaqueFallbackRouteParams | null,
  devRenderDidError: boolean
): Promise<DevValidationSnapshot> {

Copyreturn {
  page: ctx.workStore.page,
  route: ctx.workStore.route,
  requestId: ctx.requestId,
  responseFinished,
  prefetchMode,
  devRenderDidError,
  nonce: ctx.nonce,
  query: ctx.query,
  request: {
    headers: [...requestStore.headers.entries()],
    urlPathname: requestStore.url.pathname,
    urlSearch: requestStore.url.search,
    rootParams: requestStore.rootParams,
    isDraftMode: requestStore.draftMode.isEnabled,
    isHmrRefresh: requestStore.isHmrRefresh ?? false,
    hmrRefreshHash: requestStore.hmrRefreshHash,
    requestStartTime: ctx.workStore.requestStartTime,
  },
  interpolatedParams: ctx.interpolatedParams,
  requestFallbackRouteParams: ctx.fallbackRouteParams,
  fallbackRouteParams,
  optimisticRouting: ctx.renderOpts.experimental.optimisticRouting,
  forceStatic: ctx.workStore.forceStatic,
  validationLevel: ctx.workStore.validationLevel,
  implicitTags: ctx.implicitTags.tags,
  additionalClientReferenceManifestPages: ctx.workStore
    .additionalClientReferenceManifestPages
    ? [...ctx.workStore.additionalClientReferenceManifestPages]
    : [],
  reactBrowserBailout: ctx.renderOpts.experimental.reactBrowserBailout,
  isDebugChannelEnabled: !!ctx.renderOpts.setReactDebugChannel,
  renderOpts: {
    images: ctx.renderOpts.images,
    allowEmptyStaticShell: ctx.renderOpts.allowEmptyStaticShell,
    partialPrefetching: ctx.renderOpts.partialPrefetching,
  },
  instantInputs: instantInputs
    ? await toSerializedInputs(instantInputs)
    : null,
  staticInputs: await toSerializedInputs(staticInputs),
}

Copyexport async function runDevValidation(
  message: DevValidationWorkerMessage,
  abortBuffer: SharedArrayBuffer
): Promise<DevValidationWorkerResult> {
  // Load the native SWC bindings and wire the code-frame renderer so the errors
  // logged below render with a source-mapped code frame, matching the
  // in-process dev output (the E2E tests snapshot the CLI text between the
  // validation markers). The `build/swc` graph these pull in is bundled as a
  // runtime external (see `next-runtime.webpack-config.js`), so it resolves
  // from the installed `next/dist` tree rather than being compiled into this
  // worker bundle, the same way the unbundled build worker loads it.
  await installBindings()
  installCodeFrameSupport()
  setBundlerFindSourceMapImplementation(
    createDiskSourceMapLookup(message.distDir)
  )
  setHttpClientAndAgentOptions({
    httpAgentOptions: message.nextConfigSerializable.httpAgentOptions,
  })
 
  // Populates the manifests singleton for the route via `setManifestsSingleton`
  // inside `loadComponents`, exactly as a real request does. The pool tears the
  // worker down on HMR / route recompile so the next validation reloads from a
  // clean require cache.
  const { ComponentMod } = await loadComponents<AppPageModule>({
    distDir: message.distDir,
    page: message.page,
    isAppPath: true,
    isDev: true,
    sriEnabled: false,
    needsManifestsForLegacyReasons: true,
  })
 
  await registerAdditionalClientReferenceManifests(
    message.distDir,
    message.additionalClientReferenceManifestPages
  )

Copyfunction createDiskSourceMapLookup(
  distDir: string
): (sourceURL: string) => ModernSourceMapPayload | undefined {
  // The frames carry resolved paths, so compare against the resolved `distDir`
  // to keep the containment check meaningful when the project sits behind a
  // symlink.
  let canonicalDistDir = distDir
  try {
    canonicalDistDir = realpathSync(distDir)
  } catch {}
 
  const payloads = new Map<string, ModernSourceMapPayload | undefined>()
 

Copy// Crossing into the app-page bundle: the entire validation runs there, so
// the client prerenders use the same React the user's client components
// resolve through `ComponentMod`.
const validationErrors = await ComponentMod.routeModule.runValidationInDev(
  ComponentMod,
  message,
  signal
)
 

Copycase 'dynamic-viewport': {
  switch (errorDetails.variant) {
    case 'link':
      errorMessage = (
        <>
          Next.js encountered URL data in <code>generateViewport()</code>.
        </>
      )
      break
    case 'runtime':
      errorMessage = (
        <>
          Next.js encountered runtime data in{' '}
          <code>generateViewport()</code>.
        </>
      )
      break
    case 'navigation':
      errorMessage = (
        <>
          Next.js encountered <code>navigation()</code> in{' '}
          <code>generateViewport()</code>.
        </>
      )
      break
    case 'prefetch':
      errorMessage = (
        <>
          Next.js encountered <code>prefetch()</code> in{' '}
          <code>generateViewport()</code>.
        </>
      )
      break
    case 'dynamic':
      errorMessage = (
        <>
          Next.js encountered uncached data in{' '}
          <code>generateViewport()</code>.
        </>
      )
      break
    default:
      errorMessage = errorDetails.variant satisfies never
  }

Copycase 'unrendered-segment':
  return (
    <ErrorOverlayLayout
      errorType={errorType}
      errorMessage="Next.js could not validate that a segment in your UI has instant navigation."
      headerChildren={
        <InstantHeaderExplanation kind="unrendered-segment" />
      }
      renderTabBar={renderTabBar}
      canGoPrevious={canGoPrevious}
      canGoNext={canGoNext}
      onPrevious={handlePrevious}
      onNext={handleNext}
      onClose={isServerError ? undefined : onClose}
      debugInfo={debugInfo}
      error={error}
      runtimeErrors={activeErrors}
      activeIdx={activeIdx}
      setActiveIndex={setActiveIndex}
      dialogResizerRef={dialogResizerRef}
      generateErrorInfo={generateErrorInfo}
      {...props}
    >
      <UnrenderedSegmentInfo
        route={errorDetails.route}