Redesign the unrendered-segment instant validation overlay

packages/next/.storybook/decorators/use-overlay-reducer.ts

@@ -11,6 +11,7 @@ import {
   ACTION_BUILDING_INDICATOR_HIDE,
   ACTION_BUILDING_INDICATOR_SHOW,
   ACTION_CACHE_INDICATOR,
+  ACTION_INSTANT_ERRORS_CLEAR,
   ACTION_INSTANT_NAVS_TOGGLE,
   ACTION_INSTANT_NAVS_RESET,
   ACTION_DEBUG_INFO,
@@ -88,6 +89,7 @@ export function useStorybookOverlayReducer(initialState?: OverlayState) {
         case ACTION_RENDERING_INDICATOR_HIDE:
         case ACTION_RENDERING_INDICATOR_SHOW:
         case ACTION_CACHE_INDICATOR:
+        case ACTION_INSTANT_ERRORS_CLEAR:
         case ACTION_INSTANT_NAVS_TOGGLE:
         case ACTION_INSTANT_NAVS_RESET:
         case ACTION_STATIC_INDICATOR:

packages/next/.storybook/fixtures/errors.ts

@@ -648,3 +648,18 @@ export const instantClientMathRandomErrors: ReadyRuntimeError[] = [
     type: 'runtime',
   },
 ]
+
+export const instantUnrenderedSegmentErrors: ReadyRuntimeError[] = [
+  {
+    id: 130,
+    runtime: true,
+    error: Object.assign(
+      new Error(
+        'Route "/81-instant-wrapper-unrendered-segment/trigger": Could not validate that a segment in your UI has instant navigation.\n\nThis segment was dropped from rendering. Issues that would prevent instant navigation will go undetected.\n\nDropped segment:\n  test-app/app/81-instant-wrapper-unrendered-segment/trigger/page.tsx\n\nWays to fix this:\n  - Render the dropped segment\n  - Set `export const instant = false` on the dropped segment to skip validation\n\nLearn more: https://nextjs.org/docs/messages/unrendered-instant-segment'
+      ),
+      { __NEXT_ERROR_CODE: 'E1248' }
+    ),
+    frames: () => Promise.resolve([]),
+    type: 'runtime',
+  },
+]

packages/next/errors.json

@@ -1244,5 +1244,12 @@
   "1243": "This \"use cache\" has a dynamic cache life that was propagated to its parent.",
   "1244": "A \"use cache\" with short \\`expire\\` (under 5 minutes) is nested inside another \"use cache\" that has no explicit \\`cacheLife\\`, which is not allowed during prerendering. Add \\`cacheLife()\\` to the outer \"use cache\" to choose whether it should be prerendered (with longer \\`expire\\`) or remain dynamic (with short \\`expire\\`). Read more: https://nextjs.org/docs/messages/nested-use-cache-no-explicit-cachelife",
   "1245": "A \"use cache\" with zero \\`revalidate\\` is nested inside another \"use cache\" that has no explicit \\`cacheLife\\`, which is not allowed during prerendering. Add \\`cacheLife()\\` to the outer \"use cache\" to choose whether it should be prerendered (with non-zero \\`revalidate\\`) or remain dynamic (with zero \\`revalidate\\`). Read more: https://nextjs.org/docs/messages/nested-use-cache-no-explicit-cachelife",
-  "1246": "Could not validate instant UI because an expected segment was not rendered."
+  "1246": "Route \"%s\": Next.js encountered uncached data during the initial render or a navigation.\\n\\n\\`fetch(...)\\` or \\`connection()\\` accessed under \\`<Suspense>\\` prevents the route from being prerendered or the navigation from being instant, leading to a slower user experience.\\n\\nWays to fix this:\\n  - Cache the data access with \\`\"use cache\"\\`\\n  - Provide a placeholder with \\`<Suspense fallback={...}>\\` around the data access\\n  - Set \\`export const instant = false\\` to allow a blocking route\\n\\nLearn more: https://nextjs.org/docs/messages/blocking-route",
+  "1247": "Route \"%s\": Next.js encountered runtime data during the initial render or a navigation.\\n\\n\\`cookies()\\`, \\`headers()\\`, \\`params\\`, or \\`searchParams\\` accessed under \\`<Suspense>\\` prevents the route from being prerendered or the navigation from being instant, leading to a slower user experience.\\n\\nWays to fix this:\\n  - Use \\`generateStaticParams\\` to make route params static\\n  - Provide a placeholder with \\`<Suspense fallback={...}>\\` around the data access\\n  - Set \\`export const instant = false\\` to allow a blocking route\\n\\nLearn more: https://nextjs.org/docs/messages/blocking-route",
+  "1248": "Could not validate instant UI because an expected segment was not rendered.",
+  "1249": "Route \"%s\": Next.js encountered uncached data during the initial render or a navigation.\\n\\n\\`fetch(...)\\` or \\`connection()\\` accessed outside of \\`<Suspense>\\` prevents the route from being prerendered or the navigation from being instant, leading to a slower user experience.\\n\\nWays to fix this:\\n  - Cache the data access with \\`\"use cache\"\\`\\n  - Provide a placeholder with \\`<Suspense fallback={...}>\\` around the data access\\n  - Set \\`export const instant = false\\` to allow a blocking route\\n\\nLearn more: https://nextjs.org/docs/messages/blocking-route",
+  "1250": "Route \"%s\": Next.js encountered runtime data during the initial render or a navigation.\\n\\n\\`cookies()\\`, \\`headers()\\`, \\`params\\`, or \\`searchParams\\` accessed outside of \\`<Suspense>\\` prevents the route from being prerendered or the navigation from being instant, leading to a slower user experience.\\n\\nWays to fix this:\\n  - Use \\`generateStaticParams\\` to make route params static\\n  - Provide a placeholder with \\`<Suspense fallback={...}>\\` around the data access\\n  - Set \\`export const instant = false\\` to allow a blocking route\\n\\nLearn more: https://nextjs.org/docs/messages/blocking-route",
+  "1251": "Route \"%s\": Next.js encountered runtime data during the initial render or a navigation.\\n\\n\\`cookies()\\`, \\`headers()\\`, \\`params\\`, or \\`searchParams\\` accessed outside of \\`<Suspense>\\` prevents the route from being prerendered or the navigation from being instant, leading to a slower user experience.\\n\\nWays to fix this:\\n  - Provide a placeholder with \\`<Suspense fallback={...}>\\` around the data access\\n  - Use \\`generateStaticParams\\` to make route params static\\n  - Set \\`export const instant = false\\` to allow a blocking route\\n\\nLearn more: https://nextjs.org/docs/messages/blocking-route",
+  "1252": "Route \"%s\": Could not validate instant UI because an expected segment was not rendered.",
+  "1253": "Route \"%s\": Could not validate that a segment in your UI has instant navigation."
 }

packages/next/src/next-devtools/dev-overlay/components/code-frame/code-frame-shell.tsx

@@ -0,0 +1,39 @@
+import type { ReactNode } from 'react'
+import { ExternalIcon } from '../../icons/external'
+
+type CodeFrameShellProps = {
+  header: ReactNode
+  onOpen?: () => void
+  openLabel?: string
+  children: ReactNode
+}
+
+export function CodeFrameShell({
+  header,
+  onOpen,
+  openLabel,
+  children,
+}: CodeFrameShellProps) {
+  return (
+    <div data-nextjs-codeframe>
+      <div className="code-frame-header">
+        <p className="code-frame-link">
+          {header}
+          {onOpen && (
+            <button
+              aria-label={openLabel ?? 'Open in editor'}
+              data-with-open-in-editor-link-source-file
+              onClick={onOpen}
+              type="button"
+            >
+              <ExternalIcon />
+            </button>
+          )}
+        </p>
+      </div>
+      <pre className="code-frame-pre">
+        <div className="code-frame-lines">{children}</div>
+      </pre>
+    </div>
+  )
+}

packages/next/src/next-devtools/dev-overlay/components/code-frame/code-frame.tsx

@@ -2,8 +2,8 @@ import { useMemo } from 'react'
 import { HotlinkedText } from '../hot-linked-text'
 import { getStackFrameFile, type StackFrame } from '../../../shared/stack-frame'
 import { useOpenInEditor } from '../../utils/use-open-in-editor'
-import { ExternalIcon } from '../../icons/external'
 import { FileIcon } from '../../icons/file'
+import { CodeFrameShell } from './code-frame-shell'
 import {
   formatCodeFrame,
   groupCodeFrameLines,
@@ -35,69 +35,55 @@ export function CodeFrame({ stackFrame, codeFrame }: CodeFrameProps) {
 
   const fileExtension = stackFrame?.file?.split('.').pop()
   return (
-    <div data-nextjs-codeframe>
-      <div className="code-frame-header">
-        {/* TODO: This is <div> in `Terminal` component.
-        Changing now will require multiple test snapshots updates.
-        Leaving as <div> as is trivial and does not affect the UI.
-        Change when the new redbox matcher `toDisplayRedbox` is used.
-        */}
-        <p className="code-frame-link">
+    <CodeFrameShell
+      header={
+        <>
           <span className="code-frame-icon">
             <FileIcon lang={fileExtension} />
           </span>
           <span data-text>
             {getStackFrameFile(stackFrame)} @{' '}
             <HotlinkedText text={stackFrame.methodName} />
           </span>
-          <button
-            aria-label="Open in editor"
-            data-with-open-in-editor-link-source-file
-            onClick={open}
-          >
-            <ExternalIcon />
-          </button>
-        </p>
-      </div>
-      <pre className="code-frame-pre">
-        <div className="code-frame-lines">
-          {parsedLineStates.map(({ line, parsedLine }, lineIndex) => {
-            const { lineNumber, isErroredLine } = parsedLine
-
-            const lineNumberProps: Record<string, string | boolean> = {}
-            if (lineNumber) {
-              lineNumberProps['data-nextjs-codeframe-line'] = lineNumber
-            }
-            if (isErroredLine) {
-              lineNumberProps['data-nextjs-codeframe-line--errored'] = true
-            }
-
-            return (
-              <div key={`line-${lineIndex}`} {...lineNumberProps}>
-                {line.map((entry, entryIndex) => (
-                  <span
-                    key={`frame-${entryIndex}`}
-                    style={{
-                      color: entry.fg ? `var(--color-${entry.fg})` : undefined,
-                      ...(entry.decoration === 'bold'
-                        ? // TODO(jiwon): This used to be 800, but the symbols like `─┬─` are
-                          // having longer width than expected on Geist Mono font-weight
-                          // above 600, hence a temporary fix is to use 500 for bold.
-                          { fontWeight: 500 }
-                        : entry.decoration === 'italic'
-                          ? { fontStyle: 'italic' }
-                          : undefined),
-                    }}
-                  >
-                    {entry.content}
-                  </span>
-                ))}
-              </div>
-            )
-          })}
-        </div>
-      </pre>
-    </div>
+        </>
+      }
+      onOpen={open}
+    >
+      {parsedLineStates.map(({ line, parsedLine }, lineIndex) => {
+        const { lineNumber, isErroredLine } = parsedLine
+
+        const lineNumberProps: Record<string, string | boolean> = {}
+        if (lineNumber) {
+          lineNumberProps['data-nextjs-codeframe-line'] = lineNumber
+        }
+        if (isErroredLine) {
+          lineNumberProps['data-nextjs-codeframe-line--errored'] = true
+        }
+
+        return (
+          <div key={`line-${lineIndex}`} {...lineNumberProps}>
+            {line.map((entry, entryIndex) => (
+              <span
+                key={`frame-${entryIndex}`}
+                style={{
+                  color: entry.fg ? `var(--color-${entry.fg})` : undefined,
+                  ...(entry.decoration === 'bold'
+                    ? // TODO(jiwon): This used to be 800, but the symbols like `─┬─` are
+                      // having longer width than expected on Geist Mono font-weight
+                      // above 600, hence a temporary fix is to use 500 for bold.
+                      { fontWeight: 500 }
+                    : entry.decoration === 'italic'
+                      ? { fontStyle: 'italic' }
+                      : undefined),
+                }}
+              >
+                {entry.content}
+              </span>
+            ))}
+          </div>
+        )
+      })}
+    </CodeFrameShell>
   )
 }
 
@@ -218,7 +204,7 @@ export const CODE_FRAME_STYLES = `
   }
 
   [data-nextjs-codeframe-line] > span:first-child {
-    color: var(--color-gray-alpha-700) !important;
+    color: var(--color-gray-alpha-500) !important;
   }
 
   [data-nextjs-codeframe-line][data-nextjs-codeframe-line--errored="true"]

packages/next/src/next-devtools/dev-overlay/components/instant/instant-guidance-data.ts

@@ -10,6 +10,8 @@ export type FixCardGroup =
   | 'client'
   | 'defer'
   | 'measure'
+  | 'silence'
+  | 'render'
 
 export type FixCardIcon =
   | 'align-left'
@@ -35,6 +37,8 @@ export const FIX_CARD_GROUPS: Record<
   client: { label: 'Client', color: 'amber', icon: 'layout' },
   defer: { label: 'Defer', color: 'amber', icon: 'pointer-click' },
   measure: { label: 'Measure', color: 'gray', icon: 'timer' },
+  silence: { label: 'Silence', color: 'red', icon: 'octagon' },
+  render: { label: 'Render', color: 'gray', icon: 'layout' },
 }
 
 export type FixCard = {
@@ -146,6 +150,47 @@ const dynamicCards: FixCard[] = [
   },
 ]
 
+// ── Unrendered-segment cards ──────────────────────
+
+const unrenderedSegmentCards: FixCard[] = [
+  {
+    id: 'render-the-dropped-segment',
+    title: 'Render the dropped segment',
+    group: 'render',
+    link: 'https://nextjs.org/docs/messages/unrendered-instant-segment#render-the-dropped-segment',
+    snippets: [
+      {
+        text: 'function Layout({ children }) {',
+        parts: [
+          { text: 'function Layout({ ' },
+          { text: 'children', highlight: true },
+          { text: ' }) {' },
+        ],
+      },
+      {
+        text: '  return <><Nav />{children}</>',
+        parts: [
+          { text: '  return <><Nav />{' },
+          { text: 'children', highlight: true },
+          { text: '}</>' },
+        ],
+      },
+      { text: '}' },
+    ],
+  },
+  {
+    id: 'skip-validation-on-the-segment',
+    title: 'Skip validation on the segment',
+    group: 'silence',
+    link: 'https://nextjs.org/docs/messages/unrendered-instant-segment#skip-validation-on-the-segment',
+    snippets: [
+      { text: '// page.tsx or layout.tsx' },
+      { text: '' },
+      { text: 'export const instant = false', highlight: true },
+    ],
+  },
+]
+
 // ── Metadata cards ────────────────────────────────
 
 const metadataRuntimeCards: FixCard[] = [
@@ -485,15 +530,18 @@ export type GuidanceKind =
   | 'viewport'
   | 'sync-io'
   | 'sync-io-client'
+  | 'unrendered-segment'
 
-export type GuidanceVariant = 'runtime' | 'navigation'
+export type GuidanceVariant = 'runtime' | 'dynamic'
 
 export const DOCS_URLS: Record<GuidanceKind, string> = {
   'blocking-route': 'https://nextjs.org/docs/messages/blocking-route',
   metadata: 'https://nextjs.org/docs/messages/next-prerender-dynamic-metadata',
   viewport: 'https://nextjs.org/docs/messages/next-prerender-dynamic-viewport',
   'sync-io': '',
   'sync-io-client': '',
+  'unrendered-segment':
+    'https://nextjs.org/docs/messages/unrendered-instant-segment',
 }
 
 export const SYNC_IO_DOCS: Record<string, string> = {
@@ -560,8 +608,13 @@ export const EXPLANATIONS: Record<GuidanceKind, string> = {
   'sync-io': '',
   'sync-io-client':
     'This value would be evaluated during the prerender and fixed at build time, instead of recomputed on each visit.',
+  'unrendered-segment':
+    'This segment was dropped from rendering. Issues that would prevent instant navigation will go undetected.',
 }
 
+export const BLOCKING_ROUTE_NAVIGATION_EXPLANATION =
+  'This prevents the navigation from being instant, leading to a slower user experience.'
+
 const syncCardsByCause: Record<string, FixCard[]> = {
   'Math.random()': syncMathCards,
   'Date.now()': syncDateCards,
@@ -601,7 +654,7 @@ export function getCards(
 ): FixCard[] {
   switch (kind) {
     case 'blocking-route':
-      return variant === 'navigation' ? dynamicCards : runtimeCards
+      return variant === 'dynamic' ? dynamicCards : runtimeCards
     case 'metadata':
       return variant === 'runtime' ? metadataRuntimeCards : metadataDynamicCards
     case 'viewport':
@@ -610,6 +663,8 @@ export function getCards(
       return (cause && syncCardsByCause[cause]) || []
     case 'sync-io-client':
       return (cause && syncClientCardsByCause[cause]) || []
+    case 'unrendered-segment':
+      return unrenderedSegmentCards
     default:
       return kind satisfies never
   }