From 1dd4017d7e17e65ef640c5955bc1010cf13f003b Mon Sep 17 00:00:00 2001
From: s1gr1d <32902192+s1gr1d@users.noreply.github.com>
Date: Wed, 30 Sep 2026 11:43:52 +0200
Subject: [PATCH] test(nextjs): Add UI components for cached/dynamic content

---
 .../cached-mid-layout/[id]/layout.tsx         |  16 ++-
 .../cached-mid-layout/[id]/page.tsx           |   7 +-
 .../[id]/layout-cached-leaf/page.tsx          |   9 +-
 .../dynamic-layouts/[id]/layout.tsx           |  11 +-
 .../mixed-lifetimes/[id]/layout.tsx           |  16 ++-
 .../mixed-lifetimes/[id]/page.tsx             |  16 ++-
 .../shared-layout/[id]/a/page.tsx             |   7 +-
 .../shared-layout/[id]/b/page.tsx             |   7 +-
 .../shared-layout/[id]/layout.tsx             |  16 ++-
 .../app/cached-sibling-components/page.tsx    |  23 ++--
 .../nextjs-16-cacheComponents/app/layout.tsx  |   7 +-
 .../app/nested-caches/page.tsx                |  25 +++-
 .../nextjs-16-cacheComponents/app/page.tsx    | 119 +++++++++++++++++-
 .../app/use-cache-page/page.tsx               |  19 ++-
 .../components/scenarioBox.tsx                |  34 +++++
 .../cached-mid-layout/[id]/layout.tsx         |  16 ++-
 .../cached-mid-layout/[id]/page.tsx           |   7 +-
 .../[id]/layout-cached-leaf/page.tsx          |   9 +-
 .../dynamic-layouts/[id]/layout.tsx           |  11 +-
 .../mixed-lifetimes/[id]/layout.tsx           |  16 ++-
 .../mixed-lifetimes/[id]/page.tsx             |  16 ++-
 .../shared-layout/[id]/a/page.tsx             |   7 +-
 .../shared-layout/[id]/b/page.tsx             |   7 +-
 .../shared-layout/[id]/layout.tsx             |  16 ++-
 .../app/cached-sibling-components/page.tsx    |  23 ++--
 .../app/layout.tsx                            |   7 +-
 .../app/nested-caches/page.tsx                |  25 +++-
 .../app/page.tsx                              | 114 ++++++++++++++++-
 .../components/scenarioBox.tsx                |  34 +++++
 29 files changed, 548 insertions(+), 92 deletions(-)
 create mode 100644 dev-packages/e2e-tests/test-applications/nextjs-16-cacheComponents/components/scenarioBox.tsx
 create mode 100644 dev-packages/e2e-tests/test-applications/nextjs-16-streaming-cacheComponents/components/scenarioBox.tsx

diff --git a/dev-packages/e2e-tests/test-applications/nextjs-16-cacheComponents/app/(cached-nesting)/cached-mid-layout/[id]/layout.tsx b/dev-packages/e2e-tests/test-applications/nextjs-16-cacheComponents/app/(cached-nesting)/cached-mid-layout/[id]/layout.tsx
index a61f15ee7e3f..ed7d8d1716d8 100644
--- a/dev-packages/e2e-tests/test-applications/nextjs-16-cacheComponents/app/(cached-nesting)/cached-mid-layout/[id]/layout.tsx
+++ b/dev-packages/e2e-tests/test-applications/nextjs-16-cacheComponents/app/(cached-nesting)/cached-mid-layout/[id]/layout.tsx
@@ -1,5 +1,6 @@
 import type { ReactNode } from 'react';
 import { cacheLife } from 'next/cache';
+import { CachedBox } from '@/components/scenarioBox';
 
 // The awaited param puts the request id into the cache key, so a fresh id is a guaranteed miss
 // and the entry cannot come from a build-time fill. `children` passes through as an uncached hole.
@@ -15,11 +16,14 @@ export default async function CachedMidLayout({
   const { id } = await params;
   await new Promise(resolve => setTimeout(resolve, 100));
   return (
-    <div data-testid="cached-mid-layout">
-      <p id="cached-layout-stamp">
-        {id}:{Date.now()}
-      </p>
-      {children}
-    </div>
+    <main>
+      <h1>Cached layout, dynamic page</h1>
+      <CachedBox label="CachedMidLayout · use cache · hours · keyed by [id]">
+        <p id="cached-layout-stamp">
+          {id}:{Date.now()}
+        </p>
+        {children}
+      </CachedBox>
+    </main>
   );
 }
diff --git a/dev-packages/e2e-tests/test-applications/nextjs-16-cacheComponents/app/(cached-nesting)/cached-mid-layout/[id]/page.tsx b/dev-packages/e2e-tests/test-applications/nextjs-16-cacheComponents/app/(cached-nesting)/cached-mid-layout/[id]/page.tsx
index 94196e6e5ee8..1edb269289ba 100644
--- a/dev-packages/e2e-tests/test-applications/nextjs-16-cacheComponents/app/(cached-nesting)/cached-mid-layout/[id]/page.tsx
+++ b/dev-packages/e2e-tests/test-applications/nextjs-16-cacheComponents/app/(cached-nesting)/cached-mid-layout/[id]/page.tsx
@@ -1,6 +1,11 @@
 import { headers } from 'next/headers';
+import { DynamicBox } from '@/components/scenarioBox';
 
 export default async function Page() {
   await headers();
-  return <p id="dynamic-leaf">Dynamic leaf: {Date.now()}</p>;
+  return (
+    <DynamicBox label="page · awaits headers">
+      <p id="dynamic-leaf">Dynamic leaf: {Date.now()}</p>
+    </DynamicBox>
+  );
 }
diff --git a/dev-packages/e2e-tests/test-applications/nextjs-16-cacheComponents/app/(cached-nesting)/dynamic-layouts/[id]/layout-cached-leaf/page.tsx b/dev-packages/e2e-tests/test-applications/nextjs-16-cacheComponents/app/(cached-nesting)/dynamic-layouts/[id]/layout-cached-leaf/page.tsx
index 8e7de36d156a..494dee2483e2 100644
--- a/dev-packages/e2e-tests/test-applications/nextjs-16-cacheComponents/app/(cached-nesting)/dynamic-layouts/[id]/layout-cached-leaf/page.tsx
+++ b/dev-packages/e2e-tests/test-applications/nextjs-16-cacheComponents/app/(cached-nesting)/dynamic-layouts/[id]/layout-cached-leaf/page.tsx
@@ -1,13 +1,16 @@
 import { cacheLife } from 'next/cache';
+import { CachedBox } from '@/components/scenarioBox';
 
 async function CachedLeaf({ id }: { id: string }) {
   'use cache';
   cacheLife('hours');
   await new Promise(resolve => setTimeout(resolve, 100));
   return (
-    <p id="cached-leaf">
-      {id}:{Date.now()}
-    </p>
+    <CachedBox label="CachedLeaf · use cache · hours">
+      <p id="cached-leaf">
+        {id}:{Date.now()}
+      </p>
+    </CachedBox>
   );
 }
 
diff --git a/dev-packages/e2e-tests/test-applications/nextjs-16-cacheComponents/app/(cached-nesting)/dynamic-layouts/[id]/layout.tsx b/dev-packages/e2e-tests/test-applications/nextjs-16-cacheComponents/app/(cached-nesting)/dynamic-layouts/[id]/layout.tsx
index 412587fd8f33..4b9b4cffc9bf 100644
--- a/dev-packages/e2e-tests/test-applications/nextjs-16-cacheComponents/app/(cached-nesting)/dynamic-layouts/[id]/layout.tsx
+++ b/dev-packages/e2e-tests/test-applications/nextjs-16-cacheComponents/app/(cached-nesting)/dynamic-layouts/[id]/layout.tsx
@@ -1,7 +1,16 @@
 import type { ReactNode } from 'react';
 import { headers } from 'next/headers';
+import { DynamicBox } from '@/components/scenarioBox';
 
 export default async function DynamicLayout({ children }: { children: ReactNode }) {
   await headers();
-  return <div data-testid="dynamic-layout">{children}</div>;
+  return (
+    <main>
+      <h1>Dynamic layout, cached leaf</h1>
+      <DynamicBox label="DynamicLayout · awaits headers">
+        <p>request-time: {Date.now()}</p>
+        {children}
+      </DynamicBox>
+    </main>
+  );
 }
diff --git a/dev-packages/e2e-tests/test-applications/nextjs-16-cacheComponents/app/(cached-nesting)/mixed-lifetimes/[id]/layout.tsx b/dev-packages/e2e-tests/test-applications/nextjs-16-cacheComponents/app/(cached-nesting)/mixed-lifetimes/[id]/layout.tsx
index 2b0b77b6e3a9..7920ef335dc2 100644
--- a/dev-packages/e2e-tests/test-applications/nextjs-16-cacheComponents/app/(cached-nesting)/mixed-lifetimes/[id]/layout.tsx
+++ b/dev-packages/e2e-tests/test-applications/nextjs-16-cacheComponents/app/(cached-nesting)/mixed-lifetimes/[id]/layout.tsx
@@ -1,5 +1,6 @@
 import type { ReactNode } from 'react';
 import { cacheLife } from 'next/cache';
+import { CachedBox } from '@/components/scenarioBox';
 
 // Hard-expires after 2s while the page's cached component lives for hours, so one request can
 // refill the layout while hitting the component: two cached levels with different origin traces.
@@ -14,11 +15,14 @@ export default async function ShortLivedLayout({
   cacheLife({ revalidate: 1, expire: 2 });
   const { id } = await params;
   return (
-    <div data-testid="short-lived-layout">
-      <p id="layout-stamp">
-        {id}:{Date.now()}
-      </p>
-      {children}
-    </div>
+    <main>
+      <h1>Mixed lifetimes</h1>
+      <CachedBox label="ShortLivedLayout · use cache · expires after 2s · keyed by [id]">
+        <p id="layout-stamp">
+          {id}:{Date.now()}
+        </p>
+        {children}
+      </CachedBox>
+    </main>
   );
 }
diff --git a/dev-packages/e2e-tests/test-applications/nextjs-16-cacheComponents/app/(cached-nesting)/mixed-lifetimes/[id]/page.tsx b/dev-packages/e2e-tests/test-applications/nextjs-16-cacheComponents/app/(cached-nesting)/mixed-lifetimes/[id]/page.tsx
index 18913cbe9790..c1c0e31494f6 100644
--- a/dev-packages/e2e-tests/test-applications/nextjs-16-cacheComponents/app/(cached-nesting)/mixed-lifetimes/[id]/page.tsx
+++ b/dev-packages/e2e-tests/test-applications/nextjs-16-cacheComponents/app/(cached-nesting)/mixed-lifetimes/[id]/page.tsx
@@ -1,19 +1,27 @@
 import { headers } from 'next/headers';
 import { cacheLife } from 'next/cache';
+import { CachedBox, DynamicBox } from '@/components/scenarioBox';
 
 async function LongLivedComponent({ id }: { id: string }) {
   'use cache';
   cacheLife('hours');
   await new Promise(resolve => setTimeout(resolve, 100));
   return (
-    <p id="component-stamp">
-      {id}:{Date.now()}
-    </p>
+    <CachedBox label="LongLivedComponent · use cache · hours">
+      <p id="component-stamp">
+        {id}:{Date.now()}
+      </p>
+    </CachedBox>
   );
 }
 
 export default async function Page({ params }: { params: Promise<{ id: string }> }) {
   const { id } = await params;
   await headers();
-  return <LongLivedComponent id={id} />;
+  return (
+    <DynamicBox label="page · awaits headers">
+      <p>request-time: {Date.now()}</p>
+      <LongLivedComponent id={id} />
+    </DynamicBox>
+  );
 }
diff --git a/dev-packages/e2e-tests/test-applications/nextjs-16-cacheComponents/app/(cached-nesting)/shared-layout/[id]/a/page.tsx b/dev-packages/e2e-tests/test-applications/nextjs-16-cacheComponents/app/(cached-nesting)/shared-layout/[id]/a/page.tsx
index ec8d5e21d947..606b9f01a2b2 100644
--- a/dev-packages/e2e-tests/test-applications/nextjs-16-cacheComponents/app/(cached-nesting)/shared-layout/[id]/a/page.tsx
+++ b/dev-packages/e2e-tests/test-applications/nextjs-16-cacheComponents/app/(cached-nesting)/shared-layout/[id]/a/page.tsx
@@ -1,6 +1,11 @@
 import { headers } from 'next/headers';
+import { DynamicBox } from '@/components/scenarioBox';
 
 export default async function Page() {
   await headers();
-  return <p id="route-a">Route a: {Date.now()}</p>;
+  return (
+    <DynamicBox label="route a · awaits headers">
+      <p id="route-a">Route a: {Date.now()}</p>
+    </DynamicBox>
+  );
 }
diff --git a/dev-packages/e2e-tests/test-applications/nextjs-16-cacheComponents/app/(cached-nesting)/shared-layout/[id]/b/page.tsx b/dev-packages/e2e-tests/test-applications/nextjs-16-cacheComponents/app/(cached-nesting)/shared-layout/[id]/b/page.tsx
index 9a1b84b2ca28..18bff4a0ed35 100644
--- a/dev-packages/e2e-tests/test-applications/nextjs-16-cacheComponents/app/(cached-nesting)/shared-layout/[id]/b/page.tsx
+++ b/dev-packages/e2e-tests/test-applications/nextjs-16-cacheComponents/app/(cached-nesting)/shared-layout/[id]/b/page.tsx
@@ -1,6 +1,11 @@
 import { headers } from 'next/headers';
+import { DynamicBox } from '@/components/scenarioBox';
 
 export default async function Page() {
   await headers();
-  return <p id="route-b">Route b: {Date.now()}</p>;
+  return (
+    <DynamicBox label="route b · awaits headers">
+      <p id="route-b">Route b: {Date.now()}</p>
+    </DynamicBox>
+  );
 }
diff --git a/dev-packages/e2e-tests/test-applications/nextjs-16-cacheComponents/app/(cached-nesting)/shared-layout/[id]/layout.tsx b/dev-packages/e2e-tests/test-applications/nextjs-16-cacheComponents/app/(cached-nesting)/shared-layout/[id]/layout.tsx
index 220fdcf92ca8..16fa37dbd71e 100644
--- a/dev-packages/e2e-tests/test-applications/nextjs-16-cacheComponents/app/(cached-nesting)/shared-layout/[id]/layout.tsx
+++ b/dev-packages/e2e-tests/test-applications/nextjs-16-cacheComponents/app/(cached-nesting)/shared-layout/[id]/layout.tsx
@@ -1,5 +1,6 @@
 import type { ReactNode } from 'react';
 import { cacheLife } from 'next/cache';
+import { CachedBox } from '@/components/scenarioBox';
 
 // One cache entry (keyed by id) shared by the sibling routes `a` and `b` below.
 export default async function SharedLayout({
@@ -14,11 +15,14 @@ export default async function SharedLayout({
   const { id } = await params;
   await new Promise(resolve => setTimeout(resolve, 100));
   return (
-    <div data-testid="shared-layout">
-      <p id="shared-layout-stamp">
-        {id}:{Date.now()}
-      </p>
-      {children}
-    </div>
+    <main>
+      <h1>Shared layout across sibling routes</h1>
+      <CachedBox label="SharedLayout · use cache · hours · shared by /a and /b">
+        <p id="shared-layout-stamp">
+          {id}:{Date.now()}
+        </p>
+        {children}
+      </CachedBox>
+    </main>
   );
 }
diff --git a/dev-packages/e2e-tests/test-applications/nextjs-16-cacheComponents/app/cached-sibling-components/page.tsx b/dev-packages/e2e-tests/test-applications/nextjs-16-cacheComponents/app/cached-sibling-components/page.tsx
index c8b8858f7785..c3e4050539bb 100644
--- a/dev-packages/e2e-tests/test-applications/nextjs-16-cacheComponents/app/cached-sibling-components/page.tsx
+++ b/dev-packages/e2e-tests/test-applications/nextjs-16-cacheComponents/app/cached-sibling-components/page.tsx
@@ -1,14 +1,17 @@
 import { Suspense } from 'react';
 import { cacheLife } from 'next/cache';
+import { CachedBox, DynamicBox } from '@/components/scenarioBox';
 
 async function CachedSection({ id, label }: { id: string; label: string }) {
   'use cache';
   cacheLife('hours');
   await new Promise(resolve => setTimeout(resolve, 100));
   return (
-    <section id={`cached-${label}`}>
-      {label}:{id}:{Date.now()}
-    </section>
+    <CachedBox label={`CachedSection "${label}" · use cache · hours`}>
+      <section id={`cached-${label}`}>
+        {label}:{id}:{Date.now()}
+      </section>
+    </CachedBox>
   );
 }
 
@@ -18,17 +21,21 @@ async function DynamicContent({ searchParams }: { searchParams: Promise<{ id?: s
   // separate entries (the props are part of the cache key).
   const { id = 'default-id' } = await searchParams;
   return (
-    <>
+    <DynamicBox label="dynamic hole · awaits searchParams">
+      <p>request-time: {Date.now()}</p>
       <CachedSection id={id} label="first" />
       <CachedSection id={id} label="second" />
-    </>
+    </DynamicBox>
   );
 }
 
 export default function Page({ searchParams }: { searchParams: Promise<{ id?: string }> }) {
   return (
-    <Suspense fallback={<div>Loading...</div>}>
-      <DynamicContent searchParams={searchParams} />
-    </Suspense>
+    <main>
+      <h1>Cached sibling components</h1>
+      <Suspense fallback={<div>Loading...</div>}>
+        <DynamicContent searchParams={searchParams} />
+      </Suspense>
+    </main>
   );
 }
diff --git a/dev-packages/e2e-tests/test-applications/nextjs-16-cacheComponents/app/layout.tsx b/dev-packages/e2e-tests/test-applications/nextjs-16-cacheComponents/app/layout.tsx
index c8f9cee0b787..5ffd72655346 100644
--- a/dev-packages/e2e-tests/test-applications/nextjs-16-cacheComponents/app/layout.tsx
+++ b/dev-packages/e2e-tests/test-applications/nextjs-16-cacheComponents/app/layout.tsx
@@ -1,7 +1,12 @@
 export default function Layout({ children }: { children: React.ReactNode }) {
   return (
     <html lang="en">
-      <body>{children}</body>
+      <body style={{ fontFamily: 'system-ui, sans-serif', maxWidth: 760, margin: '0 auto', padding: '0 16px' }}>
+        <header style={{ borderBottom: '1px solid #ddd', padding: '10px 0', marginBottom: 16 }}>
+          <a href="/">← Cache scenarios</a>
+        </header>
+        {children}
+      </body>
     </html>
   );
 }
diff --git a/dev-packages/e2e-tests/test-applications/nextjs-16-cacheComponents/app/nested-caches/page.tsx b/dev-packages/e2e-tests/test-applications/nextjs-16-cacheComponents/app/nested-caches/page.tsx
index 481d7e5e46e6..1115c4054b3f 100644
--- a/dev-packages/e2e-tests/test-applications/nextjs-16-cacheComponents/app/nested-caches/page.tsx
+++ b/dev-packages/e2e-tests/test-applications/nextjs-16-cacheComponents/app/nested-caches/page.tsx
@@ -1,5 +1,6 @@
 import { Suspense } from 'react';
 import { cacheLife } from 'next/cache';
+import { CachedBox, DynamicBox } from '@/components/scenarioBox';
 
 async function getSlowChangingValue(id: string): Promise<{ id: string; createdAt: number }> {
   'use cache';
@@ -14,20 +15,34 @@ async function ShortLivedSection({ id }: { id: string }) {
   // delayed request refills the component and reads the nested entry as a hit inside that fill.
   cacheLife({ revalidate: 1, expire: 2 });
   const nested = await getSlowChangingValue(id);
-  return <div id="nested-data">{JSON.stringify({ ...nested, renderedAt: Date.now() })}</div>;
+  return (
+    <CachedBox label="ShortLivedSection · use cache · expires after 2s">
+      <CachedBox label="getSlowChangingValue · use cache · hours">
+        <div id="nested-data">{JSON.stringify({ ...nested, renderedAt: Date.now() })}</div>
+      </CachedBox>
+    </CachedBox>
+  );
 }
 
 async function DynamicContent({ searchParams }: { searchParams: Promise<{ id?: string }> }) {
   // Awaiting searchParams makes this hole dynamic, so every request renders it and consults the
   // cache handler instead of serving prerendered output.
   const { id = 'default-id' } = await searchParams;
-  return <ShortLivedSection id={id} />;
+  return (
+    <DynamicBox label="dynamic hole · awaits searchParams">
+      <p>request-time: {Date.now()}</p>
+      <ShortLivedSection id={id} />
+    </DynamicBox>
+  );
 }
 
 export default function Page({ searchParams }: { searchParams: Promise<{ id?: string }> }) {
   return (
-    <Suspense fallback={<div>Loading...</div>}>
-      <DynamicContent searchParams={searchParams} />
-    </Suspense>
+    <main>
+      <h1>Nested caches with different lifetimes</h1>
+      <Suspense fallback={<div>Loading...</div>}>
+        <DynamicContent searchParams={searchParams} />
+      </Suspense>
+    </main>
   );
 }
diff --git a/dev-packages/e2e-tests/test-applications/nextjs-16-cacheComponents/app/page.tsx b/dev-packages/e2e-tests/test-applications/nextjs-16-cacheComponents/app/page.tsx
index 433db8283beb..bea2cf1d875f 100644
--- a/dev-packages/e2e-tests/test-applications/nextjs-16-cacheComponents/app/page.tsx
+++ b/dev-packages/e2e-tests/test-applications/nextjs-16-cacheComponents/app/page.tsx
@@ -1,3 +1,120 @@
+'use client';
+
+import { useEffect, useState } from 'react';
+
+type Scenario = { name: string; href: (id: string) => string; description: string };
+
+const groups: { title: string; scenarios: Scenario[] }[] = [
+  {
+    title: 'Route handlers (JSON)',
+    scenarios: [
+      {
+        name: '/api/use-cache',
+        href: id => `/api/use-cache?id=${id}`,
+        description: 'cached function that lives for hours. The second request with the same id is a hit.',
+      },
+      {
+        name: '/api/use-cache-expiring',
+        href: id => `/api/use-cache-expiring?id=${id}`,
+        description: 'the entry expires after 2 seconds. Request again after 3 seconds for a refill.',
+      },
+      {
+        name: '/api/use-cache-swr',
+        href: id => `/api/use-cache-swr?id=${id}`,
+        description:
+          'the entry goes stale after 2 seconds. A stale read serves the old value and refills in the background.',
+      },
+    ],
+  },
+  {
+    title: 'Rendered pages',
+    scenarios: [
+      {
+        name: '/use-cache-page',
+        href: id => `/use-cache-page?id=${id}`,
+        description: 'a cached data function inside a dynamic hole.',
+      },
+      {
+        name: '/cached-sibling-components',
+        href: id => `/cached-sibling-components?id=${id}`,
+        description: 'two cached sibling components. Each section is its own cache entry.',
+      },
+      {
+        name: '/nested-caches',
+        href: id => `/nested-caches?id=${id}`,
+        description:
+          'a cached component that expires after 2 seconds and calls a cached function that lives for hours.',
+      },
+    ],
+  },
+  {
+    title: 'Nested layouts',
+    scenarios: [
+      {
+        name: '/cached-mid-layout/[id]',
+        href: id => `/cached-mid-layout/${id}`,
+        description: 'a cached layout above a dynamic page.',
+      },
+      {
+        name: '/dynamic-layouts/[id]/layout-cached-leaf',
+        href: id => `/dynamic-layouts/${id}/layout-cached-leaf`,
+        description: 'dynamic layouts above a cached leaf component.',
+      },
+      {
+        name: '/mixed-lifetimes/[id]',
+        href: id => `/mixed-lifetimes/${id}`,
+        description: 'a cached layout that expires after 2 seconds around a cached component that lives for hours.',
+      },
+      {
+        name: '/shared-layout/[id]/a',
+        href: id => `/shared-layout/${id}/a`,
+        description: 'route a fills the layout entry that routes a and b share.',
+      },
+      {
+        name: '/shared-layout/[id]/b',
+        href: id => `/shared-layout/${id}/b`,
+        description: 'route b hits the layout entry that route a filled.',
+      },
+    ],
+  },
+  {
+    title: 'Pageload',
+    scenarios: [
+      {
+        name: '/pageload-tracing',
+        href: () => '/pageload-tracing',
+        description: 'a prerendered shell with a dynamic hole. Check the pageload and server trace connection here.',
+      },
+    ],
+  },
+];
+
+// The links are plain `<a>` elements so that every click is a full document request with its own
+// server trace. `<Link>` would navigate through the client-side router instead.
 export default function Page() {
-  return <p>Next 16 CacheComponents test app</p>;
+  const [id, setId] = useState('');
+  // Generated after hydration so the prerendered shell does not bake in one fixed id.
+  useEffect(() => setId(crypto.randomUUID()), []);
+
+  return (
+    <main>
+      <h1>Next 16 Cache Components scenarios</h1>
+      <p>
+        Every link carries a random id that becomes part of the cache key. The first click fills the cache. A second
+        click on the same link, or a reload of the target page, hits it. Reload this page to get fresh ids.
+      </p>
+      {groups.map(group => (
+        <section key={group.title}>
+          <h2 style={{ fontSize: 16 }}>{group.title}</h2>
+          <ul>
+            {group.scenarios.map(scenario => (
+              <li key={scenario.name} style={{ margin: '6px 0' }}>
+                <a href={id ? scenario.href(id) : '#'}>{scenario.name}</a>: {scenario.description}
+              </li>
+            ))}
+          </ul>
+        </section>
+      ))}
+    </main>
+  );
 }
diff --git a/dev-packages/e2e-tests/test-applications/nextjs-16-cacheComponents/app/use-cache-page/page.tsx b/dev-packages/e2e-tests/test-applications/nextjs-16-cacheComponents/app/use-cache-page/page.tsx
index 1e41b4436e20..3450928fe090 100644
--- a/dev-packages/e2e-tests/test-applications/nextjs-16-cacheComponents/app/use-cache-page/page.tsx
+++ b/dev-packages/e2e-tests/test-applications/nextjs-16-cacheComponents/app/use-cache-page/page.tsx
@@ -1,5 +1,6 @@
 import { Suspense } from 'react';
 import { cacheLife } from 'next/cache';
+import { CachedBox, DynamicBox } from '@/components/scenarioBox';
 
 async function getCachedPageData(id: string): Promise<{ id: string; createdAt: number }> {
   'use cache';
@@ -10,9 +11,12 @@ async function getCachedPageData(id: string): Promise<{ id: string; createdAt: n
 
 export default function Page({ searchParams }: { searchParams: Promise<{ id?: string }> }) {
   return (
-    <Suspense fallback={<div>Loading...</div>}>
-      <CachedContent searchParams={searchParams} />
-    </Suspense>
+    <main>
+      <h1>Cached data function in a page</h1>
+      <Suspense fallback={<div>Loading...</div>}>
+        <CachedContent searchParams={searchParams} />
+      </Suspense>
+    </main>
   );
 }
 
@@ -21,5 +25,12 @@ async function CachedContent({ searchParams }: { searchParams: Promise<{ id?: st
   // cache handler instead of serving prerendered output.
   const { id = 'default-id' } = await searchParams;
   const data = await getCachedPageData(id);
-  return <div id="cached-data">{JSON.stringify(data)}</div>;
+  return (
+    <DynamicBox label="dynamic hole · awaits searchParams">
+      <p>request-time: {Date.now()}</p>
+      <CachedBox label="getCachedPageData · use cache · hours">
+        <div id="cached-data">{JSON.stringify(data)}</div>
+      </CachedBox>
+    </DynamicBox>
+  );
 }
diff --git a/dev-packages/e2e-tests/test-applications/nextjs-16-cacheComponents/components/scenarioBox.tsx b/dev-packages/e2e-tests/test-applications/nextjs-16-cacheComponents/components/scenarioBox.tsx
new file mode 100644
index 000000000000..cf2d318d64cc
--- /dev/null
+++ b/dev-packages/e2e-tests/test-applications/nextjs-16-cacheComponents/components/scenarioBox.tsx
@@ -0,0 +1,34 @@
+import type { CSSProperties, ReactNode } from 'react';
+
+const box: CSSProperties = {
+  padding: '8px 12px',
+  margin: '12px 0',
+  borderRadius: 8,
+};
+
+const badge: CSSProperties = {
+  display: 'inline-block',
+  fontSize: 12,
+  fontWeight: 600,
+  color: '#fff',
+  padding: '1px 8px',
+  borderRadius: 4,
+};
+
+export function CachedBox({ label, children }: { label: string; children: ReactNode }) {
+  return (
+    <section style={{ ...box, border: '2px solid #7c3aed', background: '#f5f3ff' }}>
+      <span style={{ ...badge, background: '#7c3aed' }}>Cached · {label}</span>
+      {children}
+    </section>
+  );
+}
+
+export function DynamicBox({ label, children }: { label: string; children: ReactNode }) {
+  return (
+    <section style={{ ...box, border: '2px dashed #2563eb', background: '#eff6ff' }}>
+      <span style={{ ...badge, background: '#2563eb' }}>Dynamic · {label}</span>
+      {children}
+    </section>
+  );
+}
diff --git a/dev-packages/e2e-tests/test-applications/nextjs-16-streaming-cacheComponents/app/(cached-nesting)/cached-mid-layout/[id]/layout.tsx b/dev-packages/e2e-tests/test-applications/nextjs-16-streaming-cacheComponents/app/(cached-nesting)/cached-mid-layout/[id]/layout.tsx
index a61f15ee7e3f..ed7d8d1716d8 100644
--- a/dev-packages/e2e-tests/test-applications/nextjs-16-streaming-cacheComponents/app/(cached-nesting)/cached-mid-layout/[id]/layout.tsx
+++ b/dev-packages/e2e-tests/test-applications/nextjs-16-streaming-cacheComponents/app/(cached-nesting)/cached-mid-layout/[id]/layout.tsx
@@ -1,5 +1,6 @@
 import type { ReactNode } from 'react';
 import { cacheLife } from 'next/cache';
+import { CachedBox } from '@/components/scenarioBox';
 
 // The awaited param puts the request id into the cache key, so a fresh id is a guaranteed miss
 // and the entry cannot come from a build-time fill. `children` passes through as an uncached hole.
@@ -15,11 +16,14 @@ export default async function CachedMidLayout({
   const { id } = await params;
   await new Promise(resolve => setTimeout(resolve, 100));
   return (
-    <div data-testid="cached-mid-layout">
-      <p id="cached-layout-stamp">
-        {id}:{Date.now()}
-      </p>
-      {children}
-    </div>
+    <main>
+      <h1>Cached layout, dynamic page</h1>
+      <CachedBox label="CachedMidLayout · use cache · hours · keyed by [id]">
+        <p id="cached-layout-stamp">
+          {id}:{Date.now()}
+        </p>
+        {children}
+      </CachedBox>
+    </main>
   );
 }
diff --git a/dev-packages/e2e-tests/test-applications/nextjs-16-streaming-cacheComponents/app/(cached-nesting)/cached-mid-layout/[id]/page.tsx b/dev-packages/e2e-tests/test-applications/nextjs-16-streaming-cacheComponents/app/(cached-nesting)/cached-mid-layout/[id]/page.tsx
index 94196e6e5ee8..1edb269289ba 100644
--- a/dev-packages/e2e-tests/test-applications/nextjs-16-streaming-cacheComponents/app/(cached-nesting)/cached-mid-layout/[id]/page.tsx
+++ b/dev-packages/e2e-tests/test-applications/nextjs-16-streaming-cacheComponents/app/(cached-nesting)/cached-mid-layout/[id]/page.tsx
@@ -1,6 +1,11 @@
 import { headers } from 'next/headers';
+import { DynamicBox } from '@/components/scenarioBox';
 
 export default async function Page() {
   await headers();
-  return <p id="dynamic-leaf">Dynamic leaf: {Date.now()}</p>;
+  return (
+    <DynamicBox label="page · awaits headers">
+      <p id="dynamic-leaf">Dynamic leaf: {Date.now()}</p>
+    </DynamicBox>
+  );
 }
diff --git a/dev-packages/e2e-tests/test-applications/nextjs-16-streaming-cacheComponents/app/(cached-nesting)/dynamic-layouts/[id]/layout-cached-leaf/page.tsx b/dev-packages/e2e-tests/test-applications/nextjs-16-streaming-cacheComponents/app/(cached-nesting)/dynamic-layouts/[id]/layout-cached-leaf/page.tsx
index 8e7de36d156a..494dee2483e2 100644
--- a/dev-packages/e2e-tests/test-applications/nextjs-16-streaming-cacheComponents/app/(cached-nesting)/dynamic-layouts/[id]/layout-cached-leaf/page.tsx
+++ b/dev-packages/e2e-tests/test-applications/nextjs-16-streaming-cacheComponents/app/(cached-nesting)/dynamic-layouts/[id]/layout-cached-leaf/page.tsx
@@ -1,13 +1,16 @@
 import { cacheLife } from 'next/cache';
+import { CachedBox } from '@/components/scenarioBox';
 
 async function CachedLeaf({ id }: { id: string }) {
   'use cache';
   cacheLife('hours');
   await new Promise(resolve => setTimeout(resolve, 100));
   return (
-    <p id="cached-leaf">
-      {id}:{Date.now()}
-    </p>
+    <CachedBox label="CachedLeaf · use cache · hours">
+      <p id="cached-leaf">
+        {id}:{Date.now()}
+      </p>
+    </CachedBox>
   );
 }
 
diff --git a/dev-packages/e2e-tests/test-applications/nextjs-16-streaming-cacheComponents/app/(cached-nesting)/dynamic-layouts/[id]/layout.tsx b/dev-packages/e2e-tests/test-applications/nextjs-16-streaming-cacheComponents/app/(cached-nesting)/dynamic-layouts/[id]/layout.tsx
index 412587fd8f33..4b9b4cffc9bf 100644
--- a/dev-packages/e2e-tests/test-applications/nextjs-16-streaming-cacheComponents/app/(cached-nesting)/dynamic-layouts/[id]/layout.tsx
+++ b/dev-packages/e2e-tests/test-applications/nextjs-16-streaming-cacheComponents/app/(cached-nesting)/dynamic-layouts/[id]/layout.tsx
@@ -1,7 +1,16 @@
 import type { ReactNode } from 'react';
 import { headers } from 'next/headers';
+import { DynamicBox } from '@/components/scenarioBox';
 
 export default async function DynamicLayout({ children }: { children: ReactNode }) {
   await headers();
-  return <div data-testid="dynamic-layout">{children}</div>;
+  return (
+    <main>
+      <h1>Dynamic layout, cached leaf</h1>
+      <DynamicBox label="DynamicLayout · awaits headers">
+        <p>request-time: {Date.now()}</p>
+        {children}
+      </DynamicBox>
+    </main>
+  );
 }
diff --git a/dev-packages/e2e-tests/test-applications/nextjs-16-streaming-cacheComponents/app/(cached-nesting)/mixed-lifetimes/[id]/layout.tsx b/dev-packages/e2e-tests/test-applications/nextjs-16-streaming-cacheComponents/app/(cached-nesting)/mixed-lifetimes/[id]/layout.tsx
index 2b0b77b6e3a9..7920ef335dc2 100644
--- a/dev-packages/e2e-tests/test-applications/nextjs-16-streaming-cacheComponents/app/(cached-nesting)/mixed-lifetimes/[id]/layout.tsx
+++ b/dev-packages/e2e-tests/test-applications/nextjs-16-streaming-cacheComponents/app/(cached-nesting)/mixed-lifetimes/[id]/layout.tsx
@@ -1,5 +1,6 @@
 import type { ReactNode } from 'react';
 import { cacheLife } from 'next/cache';
+import { CachedBox } from '@/components/scenarioBox';
 
 // Hard-expires after 2s while the page's cached component lives for hours, so one request can
 // refill the layout while hitting the component: two cached levels with different origin traces.
@@ -14,11 +15,14 @@ export default async function ShortLivedLayout({
   cacheLife({ revalidate: 1, expire: 2 });
   const { id } = await params;
   return (
-    <div data-testid="short-lived-layout">
-      <p id="layout-stamp">
-        {id}:{Date.now()}
-      </p>
-      {children}
-    </div>
+    <main>
+      <h1>Mixed lifetimes</h1>
+      <CachedBox label="ShortLivedLayout · use cache · expires after 2s · keyed by [id]">
+        <p id="layout-stamp">
+          {id}:{Date.now()}
+        </p>
+        {children}
+      </CachedBox>
+    </main>
   );
 }
diff --git a/dev-packages/e2e-tests/test-applications/nextjs-16-streaming-cacheComponents/app/(cached-nesting)/mixed-lifetimes/[id]/page.tsx b/dev-packages/e2e-tests/test-applications/nextjs-16-streaming-cacheComponents/app/(cached-nesting)/mixed-lifetimes/[id]/page.tsx
index 18913cbe9790..c1c0e31494f6 100644
--- a/dev-packages/e2e-tests/test-applications/nextjs-16-streaming-cacheComponents/app/(cached-nesting)/mixed-lifetimes/[id]/page.tsx
+++ b/dev-packages/e2e-tests/test-applications/nextjs-16-streaming-cacheComponents/app/(cached-nesting)/mixed-lifetimes/[id]/page.tsx
@@ -1,19 +1,27 @@
 import { headers } from 'next/headers';
 import { cacheLife } from 'next/cache';
+import { CachedBox, DynamicBox } from '@/components/scenarioBox';
 
 async function LongLivedComponent({ id }: { id: string }) {
   'use cache';
   cacheLife('hours');
   await new Promise(resolve => setTimeout(resolve, 100));
   return (
-    <p id="component-stamp">
-      {id}:{Date.now()}
-    </p>
+    <CachedBox label="LongLivedComponent · use cache · hours">
+      <p id="component-stamp">
+        {id}:{Date.now()}
+      </p>
+    </CachedBox>
   );
 }
 
 export default async function Page({ params }: { params: Promise<{ id: string }> }) {
   const { id } = await params;
   await headers();
-  return <LongLivedComponent id={id} />;
+  return (
+    <DynamicBox label="page · awaits headers">
+      <p>request-time: {Date.now()}</p>
+      <LongLivedComponent id={id} />
+    </DynamicBox>
+  );
 }
diff --git a/dev-packages/e2e-tests/test-applications/nextjs-16-streaming-cacheComponents/app/(cached-nesting)/shared-layout/[id]/a/page.tsx b/dev-packages/e2e-tests/test-applications/nextjs-16-streaming-cacheComponents/app/(cached-nesting)/shared-layout/[id]/a/page.tsx
index ec8d5e21d947..606b9f01a2b2 100644
--- a/dev-packages/e2e-tests/test-applications/nextjs-16-streaming-cacheComponents/app/(cached-nesting)/shared-layout/[id]/a/page.tsx
+++ b/dev-packages/e2e-tests/test-applications/nextjs-16-streaming-cacheComponents/app/(cached-nesting)/shared-layout/[id]/a/page.tsx
@@ -1,6 +1,11 @@
 import { headers } from 'next/headers';
+import { DynamicBox } from '@/components/scenarioBox';
 
 export default async function Page() {
   await headers();
-  return <p id="route-a">Route a: {Date.now()}</p>;
+  return (
+    <DynamicBox label="route a · awaits headers">
+      <p id="route-a">Route a: {Date.now()}</p>
+    </DynamicBox>
+  );
 }
diff --git a/dev-packages/e2e-tests/test-applications/nextjs-16-streaming-cacheComponents/app/(cached-nesting)/shared-layout/[id]/b/page.tsx b/dev-packages/e2e-tests/test-applications/nextjs-16-streaming-cacheComponents/app/(cached-nesting)/shared-layout/[id]/b/page.tsx
index 9a1b84b2ca28..18bff4a0ed35 100644
--- a/dev-packages/e2e-tests/test-applications/nextjs-16-streaming-cacheComponents/app/(cached-nesting)/shared-layout/[id]/b/page.tsx
+++ b/dev-packages/e2e-tests/test-applications/nextjs-16-streaming-cacheComponents/app/(cached-nesting)/shared-layout/[id]/b/page.tsx
@@ -1,6 +1,11 @@
 import { headers } from 'next/headers';
+import { DynamicBox } from '@/components/scenarioBox';
 
 export default async function Page() {
   await headers();
-  return <p id="route-b">Route b: {Date.now()}</p>;
+  return (
+    <DynamicBox label="route b · awaits headers">
+      <p id="route-b">Route b: {Date.now()}</p>
+    </DynamicBox>
+  );
 }
diff --git a/dev-packages/e2e-tests/test-applications/nextjs-16-streaming-cacheComponents/app/(cached-nesting)/shared-layout/[id]/layout.tsx b/dev-packages/e2e-tests/test-applications/nextjs-16-streaming-cacheComponents/app/(cached-nesting)/shared-layout/[id]/layout.tsx
index 220fdcf92ca8..16fa37dbd71e 100644
--- a/dev-packages/e2e-tests/test-applications/nextjs-16-streaming-cacheComponents/app/(cached-nesting)/shared-layout/[id]/layout.tsx
+++ b/dev-packages/e2e-tests/test-applications/nextjs-16-streaming-cacheComponents/app/(cached-nesting)/shared-layout/[id]/layout.tsx
@@ -1,5 +1,6 @@
 import type { ReactNode } from 'react';
 import { cacheLife } from 'next/cache';
+import { CachedBox } from '@/components/scenarioBox';
 
 // One cache entry (keyed by id) shared by the sibling routes `a` and `b` below.
 export default async function SharedLayout({
@@ -14,11 +15,14 @@ export default async function SharedLayout({
   const { id } = await params;
   await new Promise(resolve => setTimeout(resolve, 100));
   return (
-    <div data-testid="shared-layout">
-      <p id="shared-layout-stamp">
-        {id}:{Date.now()}
-      </p>
-      {children}
-    </div>
+    <main>
+      <h1>Shared layout across sibling routes</h1>
+      <CachedBox label="SharedLayout · use cache · hours · shared by /a and /b">
+        <p id="shared-layout-stamp">
+          {id}:{Date.now()}
+        </p>
+        {children}
+      </CachedBox>
+    </main>
   );
 }
diff --git a/dev-packages/e2e-tests/test-applications/nextjs-16-streaming-cacheComponents/app/cached-sibling-components/page.tsx b/dev-packages/e2e-tests/test-applications/nextjs-16-streaming-cacheComponents/app/cached-sibling-components/page.tsx
index c8b8858f7785..c3e4050539bb 100644
--- a/dev-packages/e2e-tests/test-applications/nextjs-16-streaming-cacheComponents/app/cached-sibling-components/page.tsx
+++ b/dev-packages/e2e-tests/test-applications/nextjs-16-streaming-cacheComponents/app/cached-sibling-components/page.tsx
@@ -1,14 +1,17 @@
 import { Suspense } from 'react';
 import { cacheLife } from 'next/cache';
+import { CachedBox, DynamicBox } from '@/components/scenarioBox';
 
 async function CachedSection({ id, label }: { id: string; label: string }) {
   'use cache';
   cacheLife('hours');
   await new Promise(resolve => setTimeout(resolve, 100));
   return (
-    <section id={`cached-${label}`}>
-      {label}:{id}:{Date.now()}
-    </section>
+    <CachedBox label={`CachedSection "${label}" · use cache · hours`}>
+      <section id={`cached-${label}`}>
+        {label}:{id}:{Date.now()}
+      </section>
+    </CachedBox>
   );
 }
 
@@ -18,17 +21,21 @@ async function DynamicContent({ searchParams }: { searchParams: Promise<{ id?: s
   // separate entries (the props are part of the cache key).
   const { id = 'default-id' } = await searchParams;
   return (
-    <>
+    <DynamicBox label="dynamic hole · awaits searchParams">
+      <p>request-time: {Date.now()}</p>
       <CachedSection id={id} label="first" />
       <CachedSection id={id} label="second" />
-    </>
+    </DynamicBox>
   );
 }
 
 export default function Page({ searchParams }: { searchParams: Promise<{ id?: string }> }) {
   return (
-    <Suspense fallback={<div>Loading...</div>}>
-      <DynamicContent searchParams={searchParams} />
-    </Suspense>
+    <main>
+      <h1>Cached sibling components</h1>
+      <Suspense fallback={<div>Loading...</div>}>
+        <DynamicContent searchParams={searchParams} />
+      </Suspense>
+    </main>
   );
 }
diff --git a/dev-packages/e2e-tests/test-applications/nextjs-16-streaming-cacheComponents/app/layout.tsx b/dev-packages/e2e-tests/test-applications/nextjs-16-streaming-cacheComponents/app/layout.tsx
index c8f9cee0b787..5ffd72655346 100644
--- a/dev-packages/e2e-tests/test-applications/nextjs-16-streaming-cacheComponents/app/layout.tsx
+++ b/dev-packages/e2e-tests/test-applications/nextjs-16-streaming-cacheComponents/app/layout.tsx
@@ -1,7 +1,12 @@
 export default function Layout({ children }: { children: React.ReactNode }) {
   return (
     <html lang="en">
-      <body>{children}</body>
+      <body style={{ fontFamily: 'system-ui, sans-serif', maxWidth: 760, margin: '0 auto', padding: '0 16px' }}>
+        <header style={{ borderBottom: '1px solid #ddd', padding: '10px 0', marginBottom: 16 }}>
+          <a href="/">← Cache scenarios</a>
+        </header>
+        {children}
+      </body>
     </html>
   );
 }
diff --git a/dev-packages/e2e-tests/test-applications/nextjs-16-streaming-cacheComponents/app/nested-caches/page.tsx b/dev-packages/e2e-tests/test-applications/nextjs-16-streaming-cacheComponents/app/nested-caches/page.tsx
index 481d7e5e46e6..1115c4054b3f 100644
--- a/dev-packages/e2e-tests/test-applications/nextjs-16-streaming-cacheComponents/app/nested-caches/page.tsx
+++ b/dev-packages/e2e-tests/test-applications/nextjs-16-streaming-cacheComponents/app/nested-caches/page.tsx
@@ -1,5 +1,6 @@
 import { Suspense } from 'react';
 import { cacheLife } from 'next/cache';
+import { CachedBox, DynamicBox } from '@/components/scenarioBox';
 
 async function getSlowChangingValue(id: string): Promise<{ id: string; createdAt: number }> {
   'use cache';
@@ -14,20 +15,34 @@ async function ShortLivedSection({ id }: { id: string }) {
   // delayed request refills the component and reads the nested entry as a hit inside that fill.
   cacheLife({ revalidate: 1, expire: 2 });
   const nested = await getSlowChangingValue(id);
-  return <div id="nested-data">{JSON.stringify({ ...nested, renderedAt: Date.now() })}</div>;
+  return (
+    <CachedBox label="ShortLivedSection · use cache · expires after 2s">
+      <CachedBox label="getSlowChangingValue · use cache · hours">
+        <div id="nested-data">{JSON.stringify({ ...nested, renderedAt: Date.now() })}</div>
+      </CachedBox>
+    </CachedBox>
+  );
 }
 
 async function DynamicContent({ searchParams }: { searchParams: Promise<{ id?: string }> }) {
   // Awaiting searchParams makes this hole dynamic, so every request renders it and consults the
   // cache handler instead of serving prerendered output.
   const { id = 'default-id' } = await searchParams;
-  return <ShortLivedSection id={id} />;
+  return (
+    <DynamicBox label="dynamic hole · awaits searchParams">
+      <p>request-time: {Date.now()}</p>
+      <ShortLivedSection id={id} />
+    </DynamicBox>
+  );
 }
 
 export default function Page({ searchParams }: { searchParams: Promise<{ id?: string }> }) {
   return (
-    <Suspense fallback={<div>Loading...</div>}>
-      <DynamicContent searchParams={searchParams} />
-    </Suspense>
+    <main>
+      <h1>Nested caches with different lifetimes</h1>
+      <Suspense fallback={<div>Loading...</div>}>
+        <DynamicContent searchParams={searchParams} />
+      </Suspense>
+    </main>
   );
 }
diff --git a/dev-packages/e2e-tests/test-applications/nextjs-16-streaming-cacheComponents/app/page.tsx b/dev-packages/e2e-tests/test-applications/nextjs-16-streaming-cacheComponents/app/page.tsx
index 433db8283beb..8f7d5cf7558e 100644
--- a/dev-packages/e2e-tests/test-applications/nextjs-16-streaming-cacheComponents/app/page.tsx
+++ b/dev-packages/e2e-tests/test-applications/nextjs-16-streaming-cacheComponents/app/page.tsx
@@ -1,3 +1,115 @@
+'use client';
+
+import { useEffect, useState } from 'react';
+
+type Scenario = { name: string; href: (id: string) => string; description: string };
+
+const groups: { title: string; scenarios: Scenario[] }[] = [
+  {
+    title: 'Route handlers (JSON)',
+    scenarios: [
+      {
+        name: '/api/use-cache',
+        href: id => `/api/use-cache?id=${id}`,
+        description: 'cached function that lives for hours. The second request with the same id is a hit.',
+      },
+      {
+        name: '/api/use-cache-expiring',
+        href: id => `/api/use-cache-expiring?id=${id}`,
+        description: 'the entry expires after 2 seconds. Request again after 3 seconds for a refill.',
+      },
+      {
+        name: '/api/use-cache-swr',
+        href: id => `/api/use-cache-swr?id=${id}`,
+        description:
+          'the entry goes stale after 2 seconds. A stale read serves the old value and refills in the background.',
+      },
+    ],
+  },
+  {
+    title: 'Rendered pages',
+    scenarios: [
+      {
+        name: '/cached-sibling-components',
+        href: id => `/cached-sibling-components?id=${id}`,
+        description: 'two cached sibling components. Each section is its own cache entry.',
+      },
+      {
+        name: '/nested-caches',
+        href: id => `/nested-caches?id=${id}`,
+        description:
+          'a cached component that expires after 2 seconds and calls a cached function that lives for hours.',
+      },
+    ],
+  },
+  {
+    title: 'Nested layouts',
+    scenarios: [
+      {
+        name: '/cached-mid-layout/[id]',
+        href: id => `/cached-mid-layout/${id}`,
+        description: 'a cached layout above a dynamic page.',
+      },
+      {
+        name: '/dynamic-layouts/[id]/layout-cached-leaf',
+        href: id => `/dynamic-layouts/${id}/layout-cached-leaf`,
+        description: 'dynamic layouts above a cached leaf component.',
+      },
+      {
+        name: '/mixed-lifetimes/[id]',
+        href: id => `/mixed-lifetimes/${id}`,
+        description: 'a cached layout that expires after 2 seconds around a cached component that lives for hours.',
+      },
+      {
+        name: '/shared-layout/[id]/a',
+        href: id => `/shared-layout/${id}/a`,
+        description: 'route a fills the layout entry that routes a and b share.',
+      },
+      {
+        name: '/shared-layout/[id]/b',
+        href: id => `/shared-layout/${id}/b`,
+        description: 'route b hits the layout entry that route a filled.',
+      },
+    ],
+  },
+  {
+    title: 'Pageload',
+    scenarios: [
+      {
+        name: '/pageload-tracing',
+        href: () => '/pageload-tracing',
+        description: 'a prerendered shell with a dynamic hole. Check the pageload and server trace connection here.',
+      },
+    ],
+  },
+];
+
+// The links are plain `<a>` elements so that every click is a full document request with its own
+// server trace. `<Link>` would navigate through the client-side router instead.
 export default function Page() {
-  return <p>Next 16 CacheComponents test app</p>;
+  const [id, setId] = useState('');
+  // Generated after hydration so the prerendered shell does not bake in one fixed id.
+  useEffect(() => setId(crypto.randomUUID()), []);
+
+  return (
+    <main>
+      <h1>Next 16 Cache Components scenarios (span streaming)</h1>
+      <p>
+        Every link carries a random id that becomes part of the cache key. The first click fills the cache. A second
+        click on the same link, or a reload of the target page, hits it. Reload this page to get fresh ids.
+      </p>
+      {groups.map(group => (
+        <section key={group.title}>
+          <h2 style={{ fontSize: 16 }}>{group.title}</h2>
+          <ul>
+            {group.scenarios.map(scenario => (
+              <li key={scenario.name} style={{ margin: '6px 0' }}>
+                <a href={id ? scenario.href(id) : '#'}>{scenario.name}</a>: {scenario.description}
+              </li>
+            ))}
+          </ul>
+        </section>
+      ))}
+    </main>
+  );
 }
diff --git a/dev-packages/e2e-tests/test-applications/nextjs-16-streaming-cacheComponents/components/scenarioBox.tsx b/dev-packages/e2e-tests/test-applications/nextjs-16-streaming-cacheComponents/components/scenarioBox.tsx
new file mode 100644
index 000000000000..cf2d318d64cc
--- /dev/null
+++ b/dev-packages/e2e-tests/test-applications/nextjs-16-streaming-cacheComponents/components/scenarioBox.tsx
@@ -0,0 +1,34 @@
+import type { CSSProperties, ReactNode } from 'react';
+
+const box: CSSProperties = {
+  padding: '8px 12px',
+  margin: '12px 0',
+  borderRadius: 8,
+};
+
+const badge: CSSProperties = {
+  display: 'inline-block',
+  fontSize: 12,
+  fontWeight: 600,
+  color: '#fff',
+  padding: '1px 8px',
+  borderRadius: 4,
+};
+
+export function CachedBox({ label, children }: { label: string; children: ReactNode }) {
+  return (
+    <section style={{ ...box, border: '2px solid #7c3aed', background: '#f5f3ff' }}>
+      <span style={{ ...badge, background: '#7c3aed' }}>Cached · {label}</span>
+      {children}
+    </section>
+  );
+}
+
+export function DynamicBox({ label, children }: { label: string; children: ReactNode }) {
+  return (
+    <section style={{ ...box, border: '2px dashed #2563eb', background: '#eff6ff' }}>
+      <span style={{ ...badge, background: '#2563eb' }}>Dynamic · {label}</span>
+      {children}
+    </section>
+  );
+}