Redesign the unrendered-segment instant validation overlay

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

@@ -1250,7 +1250,9 @@
   "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": "\\`experimental.cssChunking: \"graph\"\\` is only supported with Turbopack. Please remove the option or run Next.js with Turbopack in %s.",
-  "1253": "\\`experimental.cssChunking: \"strict\"\\` is only supported with webpack. Please remove the option or run Next.js with webpack in %s.",
-  "1254": "\\`experimental.cssChunking: false\\` is only supported with webpack. Please remove the option or run Next.js with webpack in %s."
+  "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.",
+  "1254": "\\`experimental.cssChunking: \"graph\"\\` is only supported with Turbopack. Please remove the option or run Next.js with Turbopack in %s.",
+  "1255": "\\`experimental.cssChunking: \"strict\"\\` is only supported with webpack. Please remove the option or run Next.js with webpack in %s.",
+  "1256": "\\`experimental.cssChunking: false\\` is only supported with webpack. Please remove the option or run Next.js with webpack in %s."
 }

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'
+  | 'ignore'
+  | 'render'
 
 export type FixCardIcon =
   | 'align-left'
@@ -18,6 +20,7 @@ export type FixCardIcon =
   | 'layout'
   | 'octagon'
   | 'pointer-click'
+  | 'minus-circle'
   | 'server-stack'
   | 'timer'
   | 'zap'
@@ -35,6 +38,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' },
+  ignore: { label: 'Ignore', color: 'red', icon: 'minus-circle' },
+  render: { label: 'Render', color: 'gray', icon: 'layout' },
 }
 
 export type FixCard = {
@@ -146,6 +151,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: 'ignore',
+    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,6 +531,7 @@ export type GuidanceKind =
   | 'viewport'
   | 'sync-io'
   | 'sync-io-client'
+  | 'unrendered-segment'
 
 export type GuidanceVariant = 'runtime' | 'dynamic'
 
@@ -494,6 +541,8 @@ export const DOCS_URLS: Record<GuidanceKind, string> = {
   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,6 +609,8 @@ 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 =
@@ -613,6 +664,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
   }

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

@@ -5,6 +5,7 @@ import {
   FixCardLayoutIcon,
   FixCardOctagonIcon,
   FixCardPointerClickIcon,
+  FixCardMinusCircleIcon,
   FixCardServerStackIcon,
   FixCardTimerIcon,
   FixCardZapIcon,
@@ -43,6 +44,8 @@ function getCardIcon(icon: FixCardIcon) {
       return <FixCardTimerIcon />
     case 'octagon':
       return <FixCardOctagonIcon />
+    case 'minus-circle':
+      return <FixCardMinusCircleIcon />
     case 'zap':
       return <FixCardZapIcon />
     case 'layout':