Cache components migration

apps/web/AGENTS.md

@@ -1,5 +1,3 @@
-<!-- NEXT-AGENTS-MD-START -->[Next.js Docs Index]|root: ./.next-docs|STOP. What you remember about Next.js is WRONG for this project. Always search docs and read before any task.|If docs missing, run this command first: npx @next/codemod agents-md --output CLAUDE.md|01-app:{04-glossary.mdx}|01-app/01-getting-started:{01-installation.mdx,02-project-structure.mdx,03-layouts-and-pages.mdx,04-linking-and-navigating.mdx,05-server-and-client-components.mdx,06-fetching-data.mdx,07-mutating-data.mdx,08-caching.mdx,09-revalidating.mdx,10-error-handling.mdx,11-css.mdx,12-images.mdx,13-fonts.mdx,14-metadata-and-og-images.mdx,15-route-handlers.mdx,16-proxy.mdx,17-deploying.mdx,18-upgrading.mdx}|01-app/02-guides:{ai-agents.mdx,analytics.mdx,authentication.mdx,backend-for-frontend.mdx,caching-without-cache-components.mdx,ci-build-caching.mdx,content-security-policy.mdx,css-in-js.mdx,custom-server.mdx,data-security.mdx,debugging.mdx,draft-mode.mdx,environment-variables.mdx,forms.mdx,incremental-static-regeneration.mdx,instant-navigation.mdx,instrumentation.mdx,internationalization.mdx,json-ld.mdx,lazy-loading.mdx,local-development.mdx,mcp.mdx,mdx.mdx,memory-usage.mdx,migrating-to-cache-components.mdx,multi-tenant.mdx,multi-zones.mdx,open-telemetry.mdx,package-bundling.mdx,prefetching.mdx,preserving-ui-state.mdx,production-checklist.mdx,progressive-web-apps.mdx,public-static-pages.mdx,redirecting.mdx,sass.mdx,scripts.mdx,self-hosting.mdx,single-page-applications.mdx,static-exports.mdx,streaming.mdx,tailwind-v3-css.mdx,third-party-libraries.mdx,videos.mdx}|01-app/02-guides/migrating:{app-router-migration.mdx,from-create-react-app.mdx,from-vite.mdx}|01-app/02-guides/testing:{cypress.mdx,jest.mdx,playwright.mdx,vitest.mdx}|01-app/02-guides/upgrading:{codemods.mdx,version-14.mdx,version-15.mdx,version-16.mdx}|01-app/03-api-reference:{07-edge.mdx,08-turbopack.mdx}|01-app/03-api-reference/01-directives:{use-cache-private.mdx,use-cache-remote.mdx,use-cache.mdx,use-client.mdx,use-server.mdx}|01-app/03-api-reference/02-components:{font.mdx,form.mdx,image.mdx,link.mdx,script.mdx}|01-app/03-api-reference/03-file-conventions/01-metadata:{app-icons.mdx,manifest.mdx,opengraph-image.mdx,robots.mdx,sitemap.mdx}|01-app/03-api-reference/03-file-conventions/02-route-segment-config:{dynamicParams.mdx,instant.mdx,maxDuration.mdx,preferredRegion.mdx,runtime.mdx}|01-app/03-api-reference/03-file-conventions:{default.mdx,dynamic-routes.mdx,error.mdx,forbidden.mdx,instrumentation-client.mdx,instrumentation.mdx,intercepting-routes.mdx,layout.mdx,loading.mdx,mdx-components.mdx,not-found.mdx,page.mdx,parallel-routes.mdx,proxy.mdx,public-folder.mdx,route-groups.mdx,route.mdx,src-folder.mdx,template.mdx,unauthorized.mdx}|01-app/03-api-reference/04-functions:{after.mdx,cacheLife.mdx,cacheTag.mdx,catchError.mdx,connection.mdx,cookies.mdx,draft-mode.mdx,fetch.mdx,forbidden.mdx,generate-image-metadata.mdx,generate-metadata.mdx,generate-sitemaps.mdx,generate-static-params.mdx,generate-viewport.mdx,headers.mdx,image-response.mdx,next-request.mdx,next-response.mdx,not-found.mdx,permanentRedirect.mdx,redirect.mdx,refresh.mdx,revalidatePath.mdx,revalidateTag.mdx,unauthorized.mdx,unstable_cache.mdx,unstable_noStore.mdx,unstable_rethrow.mdx,updateTag.mdx,use-link-status.mdx,use-params.mdx,use-pathname.mdx,use-report-web-vitals.mdx,use-router.mdx,use-search-params.mdx,use-selected-layout-segment.mdx,use-selected-layout-segments.mdx,userAgent.mdx}|01-app/03-api-reference/05-config/01-next-config-js:{adapterPath.mdx,allowedDevOrigins.mdx,appDir.mdx,assetPrefix.mdx,authInterrupts.mdx,basePath.mdx,cacheComponents.mdx,cacheHandlers.mdx,cacheLife.mdx,compress.mdx,crossOrigin.mdx,cssChunking.mdx,deploymentId.mdx,devIndicators.mdx,distDir.mdx,env.mdx,expireTime.mdx,exportPathMap.mdx,generateBuildId.mdx,generateEtags.mdx,headers.mdx,htmlLimitedBots.mdx,httpAgentOptions.mdx,images.mdx,incrementalCacheHandlerPath.mdx,inlineCss.mdx,logging.mdx,mdxRs.mdx,onDemandEntries.mdx,optimizePackageImports.mdx,output.mdx,pageExtensions.mdx,poweredByHeader.mdx,productionBrowserSourceMaps.mdx,proxyClientMaxBodySize.mdx,reactCompiler.mdx,reactMaxHeadersLength.mdx,reactStrictMode.mdx,redirects.mdx,rewrites.mdx,sassOptions.mdx,serverActions.mdx,serverComponentsHmrCache.mdx,serverExternalPackages.mdx,staleTimes.mdx,staticGeneration.mdx,taint.mdx,trailingSlash.mdx,transpilePackages.mdx,turbopack.mdx,turbopackFileSystemCache.mdx,turbopackIgnoreIssue.mdx,typedRoutes.mdx,typescript.mdx,urlImports.mdx,useLightningcss.mdx,viewTransition.mdx,webVitalsAttribution.mdx,webpack.mdx}|01-app/03-api-reference/05-config:{02-typescript.mdx,03-eslint.mdx}|01-app/03-api-reference/06-cli:{create-next-app.mdx,next.mdx}|02-pages/01-getting-started:{01-installation.mdx,02-project-structure.mdx,04-images.mdx,05-fonts.mdx,06-css.mdx,11-deploying.mdx}|02-pages/02-guides:{analytics.mdx,authentication.mdx,babel.mdx,ci-build-caching.mdx,content-security-policy.mdx,css-in-js.mdx,custom-server.mdx,debugging.mdx,draft-mode.mdx,environment-variables.mdx,forms.mdx,incremental-static-regeneration.mdx,instrumentation.mdx,internationalization.mdx,lazy-loading.mdx,mdx.mdx,multi-zones.mdx,open-telemetry.mdx,package-bundling.mdx,post-css.mdx,preview-mode.mdx,production-checklist.mdx,redirecting.mdx,sass.mdx,scripts.mdx,self-hosting.mdx,static-exports.mdx,tailwind-v3-css.mdx,third-party-libraries.mdx}|02-pages/02-guides/migrating:{app-router-migration.mdx,from-create-react-app.mdx,from-vite.mdx}|02-pages/02-guides/testing:{cypress.mdx,jest.mdx,playwright.mdx,vitest.mdx}|02-pages/02-guides/upgrading:{codemods.mdx,version-10.mdx,version-11.mdx,version-12.mdx,version-13.mdx,version-14.mdx,version-9.mdx}|02-pages/03-building-your-application/01-routing:{01-pages-and-layouts.mdx,02-dynamic-routes.mdx,03-linking-and-navigating.mdx,05-custom-app.mdx,06-custom-document.mdx,07-api-routes.mdx,08-custom-error.mdx}|02-pages/03-building-your-application/02-rendering:{01-server-side-rendering.mdx,02-static-site-generation.mdx,04-automatic-static-optimization.mdx,05-client-side-rendering.mdx}|02-pages/03-building-your-application/03-data-fetching:{01-get-static-props.mdx,02-get-static-paths.mdx,03-forms-and-mutations.mdx,03-get-server-side-props.mdx,05-client-side.mdx}|02-pages/03-building-your-application/06-configuring:{12-error-handling.mdx}|02-pages/04-api-reference:{06-edge.mdx,08-turbopack.mdx}|02-pages/04-api-reference/01-components:{font.mdx,form.mdx,head.mdx,image-legacy.mdx,image.mdx,link.mdx,script.mdx}|02-pages/04-api-reference/02-file-conventions:{instrumentation.mdx,proxy.mdx,public-folder.mdx,src-folder.mdx}|02-pages/04-api-reference/03-functions:{get-initial-props.mdx,get-server-side-props.mdx,get-static-paths.mdx,get-static-props.mdx,next-request.mdx,next-response.mdx,use-params.mdx,use-report-web-vitals.mdx,use-router.mdx,use-search-params.mdx,userAgent.mdx}|02-pages/04-api-reference/04-config/01-next-config-js:{adapterPath.mdx,allowedDevOrigins.mdx,assetPrefix.mdx,basePath.mdx,bundlePagesRouterDependencies.mdx,compress.mdx,crossOrigin.mdx,deploymentId.mdx,devIndicators.mdx,distDir.mdx,env.mdx,exportPathMap.mdx,generateBuildId.mdx,generateEtags.mdx,headers.mdx,httpAgentOptions.mdx,images.mdx,logging.mdx,onDemandEntries.mdx,optimizePackageImports.mdx,output.mdx,pageExtensions.mdx,poweredByHeader.mdx,productionBrowserSourceMaps.mdx,proxyClientMaxBodySize.mdx,reactStrictMode.mdx,redirects.mdx,rewrites.mdx,serverExternalPackages.mdx,trailingSlash.mdx,transpilePackages.mdx,turbopack.mdx,typescript.mdx,urlImports.mdx,useLightningcss.mdx,webVitalsAttribution.mdx,webpack.mdx}|02-pages/04-api-reference/04-config:{01-typescript.mdx,02-eslint.mdx}|02-pages/04-api-reference/05-cli:{create-next-app.mdx,next.mdx}|03-architecture:{accessibility.mdx,fast-refresh.mdx,nextjs-compiler.mdx,supported-browsers.mdx}|04-community:{01-contribution-guide.mdx,02-rspack.mdx}<!-- NEXT-AGENTS-MD-END -->
-
 ## Internationalization
 
 The Next.js app uses `next-intl` for internationalization, with `en.json`, `ko.json`, and `zh.json` files living at `apps/web/messages`. When building user-facing components, make sure to include proper translation support.
@@ -8,6 +6,33 @@ The Next.js app uses `next-intl` for internationalization, with `en.json`, `ko.j
 
 Before committing, ensure that changes are formatted, linted, typechecked, and pass the test suite.
 
+## Cache Components (Cache Components / PPR is enabled)
+
+`cacheComponents: true` + `partialPrefetching: true` are on. PPR prerenders every request **twice** (a cache-warming pass, then the final prerender), so four rules prevent the recurring `HANGING_PROMISE_REJECTION` (`dynamic "use cache"`) and `Unexpected cache miss after cache warming phase` errors:
+
+1. **`use cache` inputs must be deterministic across passes.** A cached function's arguments (and closure values) become its cache key. Only pass route params, scalar DB columns, or **fixed-order** constant arrays. Never pass:
+   - a raw `findFirst`/`findMany` result — add an explicit `orderBy` (an unordered query can return a different row/order between passes; e.g. `resolveScrimMapDataId`, flag `identify`'s team `idArray`).
+   - a `Set`→array, `Object.keys/values/entries`, or any array whose order isn't pinned.
+   - a `new Date()`/`Date.now()`/`Math.random()` value — quantize it (e.g. day-align, like `computeDateRange`) or don't key on it.
+
+2. **Reads that reach `use cache` in a layout's static-shell region must be request-time.** `@vercel/edge-config`'s `get()` and every feature flag (`@/lib/flags`) compile to `use cache`. If such a read runs outside a page's dynamic boundary (e.g. in the `Footer`/a `layout.tsx`) without already being request-time, add `await connection()` as the first line (see `AuthedAppHeader`, `Footer`, the team-stats layout). Note: awaiting `getTranslations`/`getLocale` does **not** defer — only `connection()`/`headers()`/`cookies()`/`auth()` do.
+
+3. **Flag reads in render code must use the precomputed code.** `proxy.ts` evaluates all `pageFlags` once per request and forwards a signed code on the `x-flags-code` request header; pages/layouts/server components MUST read flags via `getFlag`/`getAllFlags` (`@/lib/flags-helpers`), never by calling the flag function directly. A live flag call can transiently fail and silently fall back to `defaultValue` in only one of the two prerender passes — the passes then disagree about *which* `use cache` calls run, which is the classic cause of `HANGING_PROMISE_REJECTION`. Route handlers and server actions (never prerendered) still call flags live (`resolveAllFlags` or the flag itself). New flags must be appended to `pageFlags` in `src/lib/flags-precompute.ts`.
+
+4. **The static shell must stay request-free — providers hydrate via islands, fallbacks are sync.** The root layout's provider tree is prerendered; request-derived values (locale override, flags, session extras) stream in as Suspense islands that hydrate stateful client providers (`IntlProvider`/`FeatureFlagsProvider`/`BrandThemeProvider` + their `*Hydrator` components in `layout.tsx`). Consequences:
+   - `loading.tsx` and Suspense fallbacks must be synchronous and cookie-free. For translated text in them use `getStaticTranslations` (`@/lib/metadata-i18n`) — `getTranslations` reads the LOCALE cookie and forces the shell dynamic. Same for client components that prerender: `useTranslations` works because the intl provider carries the default-locale catalog (plus explicit `timeZone`) — never remove those props or next-intl "environment-falls-back" into `cookies()`.
+   - A client provider above `{children}` must not read request data (`useSearchParams`, cookies): hold state and sync via a Suspense-wrapped child (see `TeamSwitcherProvider`).
+   - Prefer ONE content boundary per page whose fallback mirrors the real content's own pending layout (see `/dashboard`'s `ScrimListSkeleton` mirroring `ScrimPagination`), instead of stacking route `loading.tsx` + layout skeleton + component skeletons — that's what causes multi-skeleton flashing.
+   - Page chrome (`DashboardLayout`/`AppHeader`) must render exactly once, in the page's static shell — never in both a `loading.tsx` and the page (the fallback→content swap remounts it and re-suspends the header), and never below a layout-level auth gate. Auth gates are the FIRST step of the page's Suspense-wrapped content component (`isAuthedToViewScrim`/`isAuthedToViewMap` → `<NoAuthCard />`, see the `[scrimId]` routes), so they resolve inside the page's single skeleton. Chrome that needs param-derived request data takes a thunk resolved inside the streamed header (`DashboardLayout`'s `guestModeSource`).
+
+5. **Runtime prefetching (`prefetch = 'allow-runtime'`) requires the whole render path to be cache-safe.** The map page prefetches `?tab=` URLs on hover/trajectory (`MapTabs` + `prefetchRoute` in `use-predictive-prefetch.ts`); the server resolves the target tab ahead of the click only as far as the caching structure allows. Rules that make it work:
+   - Per-viewer request work (auth gate, session, user row, colorblind palette) lives in ONE `"use cache: private"` scope (`getMapViewerContext`) — an uncached session/DB read aborts the runtime prerender at the surrounding Suspense boundary, and in `generateMetadata` it fails the whole prefetch with E1370 ("couldn't prerender metadata"). `cacheLife` stale must be ≥ 30s for prefetching.
+   - Tab/server components on the prefetch path are `"use cache"` components: locale and feature flags come in as PROPS (request APIs are forbidden in public cache scopes) — translate with `getLocaleTranslations(locale, ns)` (`@/lib/metadata-i18n`), never `getTranslations`. Cached output embedding presigned URLs must cap `expire` below the URL's lifetime (see HeatmapTab/RoutesTab).
+   - `router.prefetch` can't issue runtime prefetches directly (Next internals); the standard prefetch is enough — the server's `allow-runtime` hint upgrades it. `typedRoutes` narrows `prefetch` to one arg, so use `prefetchRoute`.
+   - Testing gotcha: Next disables ALL prefetching for bot user agents — headless-Chrome UAs ("HeadlessChrome") silently no-op; pass a real UA when verifying with agent-browser, and use a production build (`next start`), never dev.
+
+These surface only at request time on real `[param]` routes (not `next build`); check Vercel runtime logs after deploying cache-touching changes.
+
 ## Agent skills
 
 ### Issue tracker
@@ -21,3 +46,11 @@ Canonical defaults (`needs-triage`, `needs-info`, `ready-for-agent`, `ready-for-
 ### Domain docs
 
 Single-context: one `CONTEXT.md` + `docs/adr/` at the repo root (created lazily by `/grill-with-docs`). See `docs/agents/domain.md`.
+
+<!-- BEGIN:nextjs-agent-rules -->
+# This is NOT the Next.js you know
+
+This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in `node_modules/next/dist/docs/` before writing any code. Heed deprecation notices.
+
+**Keep this block, including in commits.** It is part of the project's agent setup, maintained by `next dev` for every agent that works here. If it appears as an uncommitted change, that is intentional — commit it as-is. Do not remove it to clean up a diff; it will be regenerated.
+<!-- END:nextjs-agent-rules -->

apps/web/messages/en.json

@@ -2187,6 +2187,7 @@
     "back": "Back to scrim overview",
     "dashboard": "Dashboard",
     "tabsLabel": "Map sections",
+    "loadingTab": "Loading tab data",
     "mobileBanner": {
       "message": "For the best experience, we recommend using a larger screen.",
       "dismiss": "Dismiss"

apps/web/messages/ko.json

@@ -2187,6 +2187,7 @@
     "back": "스크림 개요로 돌아가기",
     "dashboard": "대시보드",
     "tabsLabel": "맵 섹션",
+    "loadingTab": "탭 데이터 불러오는 중",
     "mobileBanner": {
       "message": "최상의 경험을 위해 더 큰 화면 사용을 권장합니다.",
       "dismiss": "닫기"

apps/web/messages/zh.json

@@ -2187,6 +2187,7 @@
     "back": "返回比赛概览",
     "dashboard": "仪表板",
     "tabsLabel": "地图分区",
+    "loadingTab": "正在加载标签页数据",
     "mobileBanner": {
       "message": "为了获得最佳体验，建议使用更大的屏幕。",
       "dismiss": "关闭"

apps/web/next.config.ts

@@ -25,6 +25,8 @@ const cspHeader = `
 `;
 
 const nextConfig: NextConfig = {
+  cacheComponents: true,
+  partialPrefetching: true,
   reactCompiler: true,
   typedRoutes: true,
   transpilePackages: ["@parsertime/transactional"],

apps/web/package.json

@@ -135,7 +135,7 @@
     "media-chrome": "^4.18.2",
     "motion": "^12.23.26",
     "nanoid": "^5.1.5",
-    "next": "16.2.9",
+    "next": "16.3.0-preview.5",
     "next-axiom": "^1.9.2",
     "next-intl": "^4.9.2",
     "next-seo": "^7.2.0",

apps/web/src/app/(auth)/auth-error/layout.tsx

@@ -1,9 +1,9 @@
 import { Footer } from "@/components/footer";
+import { getMetadataTranslations } from "@/lib/metadata-i18n";
 import type { Metadata } from "next";
-import { getTranslations } from "next-intl/server";
 
-export async function generateMetadata(): Promise<Metadata> {
-  const t = await getTranslations("authError.metadata");
+export function generateMetadata(): Metadata {
+  const t = getMetadataTranslations("authError.metadata");
   return { title: t("title"), description: t("description") };
 }
 

apps/web/src/app/(auth)/auth-error/page.tsx

@@ -1,6 +1,9 @@
 import { Button } from "@/components/ui/button";
+import { Skeleton } from "@/components/ui/skeleton";
+import { getStaticTranslations } from "@/lib/metadata-i18n";
 import { getTranslations } from "next-intl/server";
 import Link from "next/link";
+import { Suspense } from "react";
 
 type Error =
   | "Configuration"
@@ -10,9 +13,31 @@ type Error =
   | "AdapterError"
   | "Default";
 
-export default async function AuthErrorPage(props: PageProps<"/auth-error">) {
-  const searchParams = await props.searchParams;
-  const t = await getTranslations("authError");
+// Static shell: the page frame and heading prerender (default-locale title via
+// the cookie-free translator); the searchParams-derived error message streams
+// into ONE boundary whose fallback mirrors the loaded content's layout.
+export default function AuthErrorPage(props: PageProps<"/auth-error">) {
+  const t = getStaticTranslations("authError");
+
+  return (
+    <div className="flex h-[90vh] flex-col items-center justify-center space-y-6 p-6 text-center">
+      <h1 className="text-3xl font-bold">{t("title")}</h1>
+      <Suspense fallback={<AuthErrorSkeleton />}>
+        <AuthErrorContent searchParams={props.searchParams} />
+      </Suspense>
+    </div>
+  );
+}
+
+async function AuthErrorContent({
+  searchParams,
+}: {
+  searchParams: PageProps<"/auth-error">["searchParams"];
+}) {
+  const [params, t] = await Promise.all([
+    searchParams,
+    getTranslations("authError"),
+  ]);
 
   const errorMessages: Record<Error, string> = {
     Configuration: t("errors.configuration"),
@@ -22,15 +47,14 @@ export default async function AuthErrorPage(props: PageProps<"/auth-error">) {
     AdapterError: t("errors.adapterError"),
     Default: t("errors.default"),
   };
-  const rawError = searchParams.error;
+  const rawError = params.error;
   const error: Error =
     typeof rawError === "string" && Object.hasOwn(errorMessages, rawError)
       ? (rawError as Error)
       : "Default";
 
   return (
-    <div className="flex h-[90vh] flex-col items-center justify-center space-y-6 p-6 text-center">
-      <h1 className="text-3xl font-bold">{t("title")}</h1>
+    <>
       <p className="max-w-[600px] text-gray-500 dark:text-gray-400">
         <span className="font-bold">{t("error")}</span>{" "}
         {errorMessages[error] ?? errorMessages.Default}
@@ -52,6 +76,20 @@ export default async function AuthErrorPage(props: PageProps<"/auth-error">) {
           <Link href="/sign-in">{t("signIn")}</Link>
         </Button>
       </div>
-    </div>
+    </>
+  );
+}
+
+// Mirrors the loaded content: two message lines and the button row.
+function AuthErrorSkeleton() {
+  return (
+    <>
+      <Skeleton className="h-4 w-[500px] max-w-full" />
+      <Skeleton className="h-4 w-[440px] max-w-full" />
+      <div className="flex space-x-4">
+        <Skeleton className="h-10 w-24" />
+        <Skeleton className="h-10 w-24" />
+      </div>
+    </>
   );
 }