From 20ce12208f355e06d63ff8857a1d4d069f3173a4 Mon Sep 17 00:00:00 2001
From: Po-Lin Lai <bolin8017@gmail.com>
Date: Sat, 18 Apr 2026 18:01:05 +0800
Subject: [PATCH] feat(web): adopt next.js 16 cache components
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Enable Partial Prerendering across every route. Cached shell HTML is
produced at build time; the dynamic regions — auth state, per-user
progress, admin data — stream in from a Suspense boundary at request
time. Tag-based invalidation replaces the hourly ISR window so admin
content edits propagate to public pages in seconds instead of up to
an hour.

The migration is wide because `cacheComponents: true` enforces that
every uncached runtime data access (cookies, headers, awaited params/
searchParams, Supabase auth/queries that read cookies) sits inside a
Suspense boundary during static prerender. One earlier attempt was
reverted for exactly this reason; the fix is the mechanical extraction
done in this PR.

Structural changes:

- next.config.ts: `cacheComponents: true`.
- Layouts: root + admin + (auth) now have a static chrome shell plus
  a Suspense-wrapped async child that reads `headers()` / does the
  auth check. Redirect semantics unchanged — proxy.ts is still the
  primary gate; layout Suspense is the belt-and-suspenders path.
- Pages: every page that awaits params/searchParams or reads cookies
  now has a sync default export wrapping an async `PageBody` child
  in `<Suspense>`. Applies to all 4 public pages, 7 admin pages, 6
  auth pages, the landing page, and the login page.
- Public pages: static data fetches (`getProblemBySlug`,
  `getListBySlug`, `getListProblems`, `getFilteredProblems`,
  `getFilteredLists`, sitemap data) converted from `react.cache` to
  `'use cache'` + `cacheLife('hours')` + `cacheTag(...)`. Tags use
  `problems`, `problem:<slug>`, `lists`, `list:<slug>`,
  `list:<id>:problems` so admin mutations can target precisely.
- Admin mutations: `_admin-helpers.ts` gains an optional `tags` array.
  `deleteProblem` revalidates `['problems', 'lists']`;
  `flag`/`unflagRegeneration` revalidate `['problems']`. Pair with
  existing `revalidatePath` so admin pages still re-render in-place.
- API routes: `dynamic = 'force-dynamic'` removed from
  `api/cron/push` and `api/health` — incompatible with
  cacheComponents; route handlers default to dynamic anyway.
- Request-scoped time: admin pages that use `new Date()`/`Date.now()`
  to construct queries now `await connection()` first (Next.js
  requires this signal so the value isn't frozen into the prerender).
- Page-level `revalidate = 3600` + `dynamicParams = true` removed
  from the four public pages; those behaviours are now governed by
  the cached helpers' `cacheLife` + `cacheTag`.

Testing:

- Added `revalidateTag` to the `next/cache` mock in admin-action
  tests so `tags: [...]` paths don't fail.
- Exposed `LoginPageBody` as a named export so the existing direct-
  invoke tests can keep exercising the async body.
- `pnpm build`: all 32 routes compile; 18 are Partial Prerender,
  the rest static or API-dynamic.
- `pnpm test`: 186 shared + 571 web all green.
- `tsc --noEmit`, `eslint`: clean.

Docs:

- `.claude/rules/web-patterns.md`: new Cache Components section
  documenting the page pattern, `use cache` helpers, cacheTag
  vocabulary, and the `await connection()` requirement.
- `.claude/rules/push-pipeline.md`: cron route no longer mandates
  `force-dynamic`.
- `docs/deferred-improvements.md`: Cache Components section removed
  (done); Branded channel-identifier types rewritten as an explicit
  "decided to skip" with revisit triggers.
---
 .claude/rules/push-pipeline.md                |  3 +-
 .claude/rules/web-patterns.md                 | 12 ++-
 apps/web/__tests__/login-page.test.ts         | 10 +-
 apps/web/app/(admin)/admin/channels/page.tsx  | 17 +++-
 apps/web/app/(admin)/admin/content/page.tsx   | 15 ++-
 apps/web/app/(admin)/admin/layout.tsx         | 44 ++++++---
 apps/web/app/(admin)/admin/lists/page.tsx     | 11 ++-
 apps/web/app/(admin)/admin/page.tsx           | 13 ++-
 apps/web/app/(admin)/admin/problems/page.tsx  | 15 ++-
 apps/web/app/(admin)/admin/push/page.tsx      | 13 ++-
 apps/web/app/(admin)/admin/users/page.tsx     | 15 ++-
 apps/web/app/(auth)/dashboard/page.tsx        | 13 ++-
 apps/web/app/(auth)/garden/page.tsx           | 11 ++-
 apps/web/app/(auth)/layout.tsx                | 21 +++--
 apps/web/app/(auth)/onboarding/page.tsx       | 11 ++-
 apps/web/app/(auth)/settings/account/page.tsx | 17 +++-
 .../web/app/(auth)/settings/learning/page.tsx | 11 ++-
 apps/web/app/(auth)/settings/page.tsx         | 11 ++-
 apps/web/app/(public)/lists/[slug]/page.tsx   | 61 +++++++-----
 apps/web/app/(public)/lists/page.tsx          | 50 ++++++----
 .../web/app/(public)/problems/[slug]/page.tsx | 24 +++--
 apps/web/app/(public)/problems/page.tsx       | 60 ++++++++----
 apps/web/app/api/cron/push/route.ts           |  1 -
 apps/web/app/api/health/route.ts              |  2 -
 apps/web/app/layout.tsx                       | 38 +++++---
 apps/web/app/login/page.tsx                   | 15 ++-
 apps/web/app/page.tsx                         | 83 ++++++++++------
 apps/web/app/sitemap.ts                       | 16 +++-
 apps/web/lib/__tests__/admin-actions.test.ts  |  2 +-
 apps/web/lib/actions/_admin-helpers.ts        |  5 +-
 apps/web/lib/actions/admin.ts                 | 21 ++++-
 apps/web/next.config.ts                       |  1 +
 docs/deferred-improvements.md                 | 94 +++----------------
 pnpm-lock.yaml                                | 51 ++--------
 34 files changed, 498 insertions(+), 289 deletions(-)

diff --git a/.claude/rules/push-pipeline.md b/.claude/rules/push-pipeline.md
index 83484d0..ee6f341 100644
--- a/.claude/rules/push-pipeline.md
+++ b/.claude/rules/push-pipeline.md
@@ -23,7 +23,8 @@ The push pipeline lives in `packages/shared/src/push/`. It is invoked by `apps/w
 
 ## Cron Entry (apps/web/app/api/cron/push/route.ts)
 
-- `export const dynamic = 'force-dynamic'` + `export const maxDuration = 300`
+- `export const maxDuration = 300` (Vercel function timeout)
+- No `dynamic = 'force-dynamic'` — incompatible with `cacheComponents: true`; route handlers default to dynamic.
 - Auth: `Authorization: Bearer ${CRON_SECRET}` verified with `timingSafeEqual` (see `isValidCronSecret`)
 - 10-minute overlap guard: skips if another run completed in the last 10 minutes
 - Calls `buildPushJobs(supabase, channelRegistry, dispatchLimit)` and `recordPushRun`
diff --git a/.claude/rules/web-patterns.md b/.claude/rules/web-patterns.md
index 6739d2f..4173fc1 100644
--- a/.claude/rules/web-patterns.md
+++ b/.claude/rules/web-patterns.md
@@ -17,6 +17,16 @@ paths:
 - **x-user-profile header**: `proxy.ts` queries user profile once -> sets header -> `layout.tsx` reads it -> passes to `<Nav>`. Value is `encodeURIComponent(JSON.stringify({...}))` for ASCII-safe CJK names. Both `nav.tsx` and `admin/layout.tsx` consume this header.
 - **revalidatePath caution**: Do NOT call from Server Actions that return data the caller displays (e.g. link tokens) — it wipes `useState` immediately.
 
+## Cache Components (Next.js 16)
+
+- **`cacheComponents: true`** enabled in `next.config.ts`. Every runtime data access (`cookies()`, `headers()`, `await params`, `await searchParams`, `supabase.auth.getUser()`) MUST sit inside a `<Suspense>` boundary or it fails build.
+- **Page pattern**: default export is a sync shell that wraps the async body in `<Suspense>`; body lives in a sibling `PageBody` async function. Applies to every page that accesses auth or searchParams.
+- **Layouts**: extract dynamic portions (`headers()` reads, auth checks) into Suspense-wrapped child components; keep static chrome (sidebar, nav links) as the synchronous outer shell.
+- **`use cache` helpers**: shared/static data fetches (`getProblemBySlug`, `getListBySlug`, `getFilteredProblems`, `getFilteredLists`, sitemap data) use the `'use cache'` directive + `cacheLife('hours')` + `cacheTag(...)`. Cannot read `cookies()`/`headers()` inside these.
+- **`cacheTag` vocabulary**: `'problems'` (any problem data), `'problem:<slug>'` (single problem), `'lists'` (any list data), `'list:<slug>'` / `'list:<id>:problems'` (scoped). Use these tags in `runAdminAction({ tags: [...] })` to invalidate on mutation.
+- **`await connection()`**: add at the top of any Server Component that reads `new Date()` / `Date.now()` for query construction — tells Next.js the component is request-scoped (otherwise it errors during prerender).
+- **No `force-dynamic` / `revalidate` exports**: incompatible with `cacheComponents`. Route handlers default to dynamic; pages become Partial Prerender automatically.
+
 ## UI Patterns
 
 - **Sticky bottom bar**: `ProblemActions` uses `IntersectionObserver` on sentinel div; when header action bar scrolls out, `fixed bottom-0` bar slides in via CSS `transition-all duration-200`. iOS safe area: `@utility pb-safe` in globals.css + `generateViewport({ viewportFit: 'cover' })`.
@@ -32,7 +42,7 @@ paths:
 
 **Routes**:
 - `app/page.tsx` — Landing page
-- `app/(public)/` — /problems, /problems/[slug], /lists, /lists/[slug] (ISR `revalidate = 3600`)
+- `app/(public)/` — /problems, /problems/[slug], /lists, /lists/[slug] (Partial Prerender; shared data cached via `'use cache'` + `cacheTag`)
 - `app/robots.ts` — Dynamic robots.txt
 - `app/(auth)/` — /dashboard, /settings, /settings/learning, /settings/account, /settings/notifications, /onboarding, /garden
 - `app/(admin)/admin/` — Health dashboard, problems, content, lists, users, push monitor, channels
diff --git a/apps/web/__tests__/login-page.test.ts b/apps/web/__tests__/login-page.test.ts
index 7cf4c28..36cb27e 100644
--- a/apps/web/__tests__/login-page.test.ts
+++ b/apps/web/__tests__/login-page.test.ts
@@ -39,7 +39,7 @@ describe('LoginPage', () => {
   it('redirects to /dashboard when user already authenticated', async () => {
     setupUser({ id: 'u1' })
 
-    const { default: LoginPage } = await import('../app/login/page')
+    const { LoginPageBody: LoginPage } = await import('../app/login/page')
 
     await expect(
       LoginPage({ searchParams: Promise.resolve({}) })
@@ -52,7 +52,7 @@ describe('LoginPage', () => {
   it('does not redirect when user is null (unauthenticated)', async () => {
     setupUser(null)
 
-    const { default: LoginPage } = await import('../app/login/page')
+    const { LoginPageBody: LoginPage } = await import('../app/login/page')
     // Should not throw (no redirect)
     const result = await LoginPage({ searchParams: Promise.resolve({}) })
     expect(result).toBeDefined()
@@ -61,7 +61,7 @@ describe('LoginPage', () => {
   it('passes error search param to LoginForm component', async () => {
     setupUser(null)
 
-    const { default: LoginPage } = await import('../app/login/page')
+    const { LoginPageBody: LoginPage } = await import('../app/login/page')
     const result = await LoginPage({
       searchParams: Promise.resolve({ error: 'auth_failed' }),
     }) as unknown as { props: { error?: string } }
@@ -72,7 +72,7 @@ describe('LoginPage', () => {
   it('passes redirect search param to LoginForm component', async () => {
     setupUser(null)
 
-    const { default: LoginPage } = await import('../app/login/page')
+    const { LoginPageBody: LoginPage } = await import('../app/login/page')
     const result = await LoginPage({
       searchParams: Promise.resolve({ redirect: '/settings' }),
     }) as unknown as { props: { redirectTo?: string } }
@@ -83,7 +83,7 @@ describe('LoginPage', () => {
   it('handles missing search params gracefully', async () => {
     setupUser(null)
 
-    const { default: LoginPage } = await import('../app/login/page')
+    const { LoginPageBody: LoginPage } = await import('../app/login/page')
     const result = await LoginPage({
       searchParams: Promise.resolve({}),
     }) as unknown as { props: { error?: string; redirectTo?: string } }
diff --git a/apps/web/app/(admin)/admin/channels/page.tsx b/apps/web/app/(admin)/admin/channels/page.tsx
index 4cf35a5..5bdbd01 100644
--- a/apps/web/app/(admin)/admin/channels/page.tsx
+++ b/apps/web/app/(admin)/admin/channels/page.tsx
@@ -1,4 +1,6 @@
 import { createServiceClient } from '@/lib/supabase/server'
+import { connection } from 'next/server'
+import { Suspense } from 'react'
 import { ChannelActions } from './channel-actions'
 import { PAGE_SIZE } from '@/lib/utils/filter-url'
 import { FilterChips, SortableHeader, Pagination } from '@/components/data-table'
@@ -15,11 +17,24 @@ interface SearchParams {
   page?: string
 }
 
-export default async function AdminChannelsPage({
+export default function AdminChannelsPage({
   searchParams,
 }: {
   searchParams: Promise<SearchParams>
 }) {
+  return (
+    <Suspense fallback={null}>
+      <AdminChannelsPageBody searchParams={searchParams} />
+    </Suspense>
+  )
+}
+
+async function AdminChannelsPageBody({
+  searchParams,
+}: {
+  searchParams: Promise<SearchParams>
+}) {
+  await connection()
   const params = await searchParams
   const statusFilter = params.status ?? 'all'
   const typeFilter = params.type ?? 'all'
diff --git a/apps/web/app/(admin)/admin/content/page.tsx b/apps/web/app/(admin)/admin/content/page.tsx
index 78b8280..a061457 100644
--- a/apps/web/app/(admin)/admin/content/page.tsx
+++ b/apps/web/app/(admin)/admin/content/page.tsx
@@ -1,4 +1,5 @@
 import { z } from 'zod'
+import { Suspense } from 'react'
 import { createServiceClient } from '@/lib/supabase/server'
 import { flagForRegeneration, unflagRegeneration } from '@/lib/actions/admin'
 import { PAGE_SIZE } from '@/lib/utils/filter-url'
@@ -17,7 +18,19 @@ const FILTER_OPTIONS = [
   { value: 'low_score', label: 'Low Score (<3★)' },
 ]
 
-export default async function AdminContentPage({
+export default function AdminContentPage({
+  searchParams,
+}: {
+  searchParams: Promise<SearchParams>
+}) {
+  return (
+    <Suspense fallback={null}>
+      <AdminContentPageBody searchParams={searchParams} />
+    </Suspense>
+  )
+}
+
+async function AdminContentPageBody({
   searchParams,
 }: {
   searchParams: Promise<SearchParams>
diff --git a/apps/web/app/(admin)/admin/layout.tsx b/apps/web/app/(admin)/admin/layout.tsx
index d6426a9..6b23a58 100644
--- a/apps/web/app/(admin)/admin/layout.tsx
+++ b/apps/web/app/(admin)/admin/layout.tsx
@@ -1,6 +1,7 @@
 import { verifyAdminAccess } from '@/lib/auth'
 import { redirect } from 'next/navigation'
 import { headers } from 'next/headers'
+import { Suspense } from 'react'
 import Link from 'next/link'
 import type { Metadata } from 'next'
 import {
@@ -36,24 +37,13 @@ const NAV_GROUPS = [
   },
 ]
 
-export default async function AdminLayout({ children }: { children: React.ReactNode }) {
-  const result = await verifyAdminAccess()
-  if (!result.authorized) redirect(result.redirectTo)
-  const user = result.user
-
-  // Header is display-only (name/avatar in sidebar) — safe to use for UI
-  const encoded = (await headers()).get('x-user-profile')
-  const profile = encoded
-    ? JSON.parse(decodeURIComponent(encoded)) as { display_name: string | null }
-    : null
-
+export default function AdminLayout({ children }: { children: React.ReactNode }) {
   return (
     <div className="flex min-h-screen">
       <aside className="w-56 shrink-0 border-r bg-muted/30 flex flex-col">
-        <div className="px-4 py-5 border-b">
-          <p className="text-xs font-semibold text-muted-foreground uppercase tracking-wider">Admin</p>
-          <p className="text-sm font-medium mt-0.5 truncate">{profile?.display_name ?? user.email}</p>
-        </div>
+        <Suspense fallback={<AdminHeaderFallback />}>
+          <AdminHeader />
+        </Suspense>
         <nav className="flex-1 py-3 px-2">
           {NAV_GROUPS.map((group, gi) => (
             <div key={group.label} className={gi > 0 ? 'mt-4' : ''}>
@@ -85,3 +75,27 @@ export default async function AdminLayout({ children }: { children: React.ReactN
     </div>
   )
 }
+
+async function AdminHeader() {
+  const result = await verifyAdminAccess()
+  if (!result.authorized) redirect(result.redirectTo)
+  const encoded = (await headers()).get('x-user-profile')
+  const profile = encoded
+    ? JSON.parse(decodeURIComponent(encoded)) as { display_name: string | null }
+    : null
+  return (
+    <div className="px-4 py-5 border-b">
+      <p className="text-xs font-semibold text-muted-foreground uppercase tracking-wider">Admin</p>
+      <p className="text-sm font-medium mt-0.5 truncate">{profile?.display_name ?? result.user.email}</p>
+    </div>
+  )
+}
+
+function AdminHeaderFallback() {
+  return (
+    <div className="px-4 py-5 border-b">
+      <p className="text-xs font-semibold text-muted-foreground uppercase tracking-wider">Admin</p>
+      <div className="h-4 w-28 rounded bg-muted/50 mt-1.5" />
+    </div>
+  )
+}
diff --git a/apps/web/app/(admin)/admin/lists/page.tsx b/apps/web/app/(admin)/admin/lists/page.tsx
index 2c74e62..96bf51b 100644
--- a/apps/web/app/(admin)/admin/lists/page.tsx
+++ b/apps/web/app/(admin)/admin/lists/page.tsx
@@ -1,6 +1,15 @@
 import { createServiceClient } from '@/lib/supabase/server'
+import { Suspense } from 'react'
 
-export default async function AdminListsPage() {
+export default function AdminListsPage() {
+  return (
+    <Suspense fallback={null}>
+      <AdminListsPageBody />
+    </Suspense>
+  )
+}
+
+async function AdminListsPageBody() {
   const supabase = createServiceClient()
 
   const { data: lists } = await supabase
diff --git a/apps/web/app/(admin)/admin/page.tsx b/apps/web/app/(admin)/admin/page.tsx
index 63c1578..18467f0 100644
--- a/apps/web/app/(admin)/admin/page.tsx
+++ b/apps/web/app/(admin)/admin/page.tsx
@@ -1,7 +1,18 @@
 import { createServiceClient } from '@/lib/supabase/server'
+import { connection } from 'next/server'
 import Link from 'next/link'
+import { Suspense } from 'react'
 
-export default async function AdminDashboardPage() {
+export default function AdminDashboardPage() {
+  return (
+    <Suspense fallback={null}>
+      <AdminDashboardPageBody />
+    </Suspense>
+  )
+}
+
+async function AdminDashboardPageBody() {
+  await connection()
   const supabase = createServiceClient()
 
   const [
diff --git a/apps/web/app/(admin)/admin/problems/page.tsx b/apps/web/app/(admin)/admin/problems/page.tsx
index 044a71d..fdba9d4 100644
--- a/apps/web/app/(admin)/admin/problems/page.tsx
+++ b/apps/web/app/(admin)/admin/problems/page.tsx
@@ -1,4 +1,5 @@
 import { createServiceClient } from '@/lib/supabase/server'
+import { Suspense } from 'react'
 import { DeleteProblemButton } from './delete-button'
 import { PAGE_SIZE } from '@/lib/utils/filter-url'
 import { sanitizeSearch } from '@/lib/utils/sanitize-search'
@@ -10,7 +11,19 @@ interface SearchParams {
   page?: string
 }
 
-export default async function AdminProblemsPage({
+export default function AdminProblemsPage({
+  searchParams,
+}: {
+  searchParams: Promise<SearchParams>
+}) {
+  return (
+    <Suspense fallback={null}>
+      <AdminProblemsPageBody searchParams={searchParams} />
+    </Suspense>
+  )
+}
+
+async function AdminProblemsPageBody({
   searchParams,
 }: {
   searchParams: Promise<SearchParams>
diff --git a/apps/web/app/(admin)/admin/push/page.tsx b/apps/web/app/(admin)/admin/push/page.tsx
index 110f226..d34d6fa 100644
--- a/apps/web/app/(admin)/admin/push/page.tsx
+++ b/apps/web/app/(admin)/admin/push/page.tsx
@@ -1,4 +1,6 @@
 import { createServiceClient } from '@/lib/supabase/server'
+import { connection } from 'next/server'
+import { Suspense } from 'react'
 import { ForceNotifyButton } from './force-notify-button'
 
 function getLastNUtcDates(n: number): string[] {
@@ -16,7 +18,16 @@ function toUtcDate(utcTimestamp: string): string {
   return new Date(utcTimestamp).toISOString().slice(0, 10)
 }
 
-export default async function AdminPushPage() {
+export default function AdminPushPage() {
+  return (
+    <Suspense fallback={null}>
+      <AdminPushPageBody />
+    </Suspense>
+  )
+}
+
+async function AdminPushPageBody() {
+  await connection()
   const supabase = createServiceClient()
   // eslint-disable-next-line react-hooks/purity -- async Server Component renders once per request
   const now = Date.now()
diff --git a/apps/web/app/(admin)/admin/users/page.tsx b/apps/web/app/(admin)/admin/users/page.tsx
index 47c1091..43ff5f4 100644
--- a/apps/web/app/(admin)/admin/users/page.tsx
+++ b/apps/web/app/(admin)/admin/users/page.tsx
@@ -1,4 +1,5 @@
 import { createServiceClient } from '@/lib/supabase/server'
+import { Suspense } from 'react'
 import { LineToggle } from './line-toggle'
 import { DeleteButton } from './delete-button'
 import { PAGE_SIZE } from '@/lib/utils/filter-url'
@@ -25,7 +26,19 @@ interface UserWithChannels {
   notification_channels: Array<{ channel_type: string; is_verified: boolean }>
 }
 
-export default async function AdminUsersPage({
+export default function AdminUsersPage({
+  searchParams,
+}: {
+  searchParams: Promise<SearchParams>
+}) {
+  return (
+    <Suspense fallback={null}>
+      <AdminUsersPageBody searchParams={searchParams} />
+    </Suspense>
+  )
+}
+
+async function AdminUsersPageBody({
   searchParams,
 }: {
   searchParams: Promise<SearchParams>
diff --git a/apps/web/app/(auth)/dashboard/page.tsx b/apps/web/app/(auth)/dashboard/page.tsx
index 5569176..c87e53a 100644
--- a/apps/web/app/(auth)/dashboard/page.tsx
+++ b/apps/web/app/(auth)/dashboard/page.tsx
@@ -4,7 +4,9 @@ import { getActiveListProgress } from '@/lib/repositories/list.repository'
 import { getRecentHistory, getStreakHistory } from '@/lib/repositories/history.repository'
 import { calculateStreak } from '@/lib/services/streak.service'
 import { redirect } from 'next/navigation'
+import { connection } from 'next/server'
 import Link from 'next/link'
+import { Suspense } from 'react'
 import { CircleCheck } from 'lucide-react'
 import type { Metadata } from 'next'
 import { UnsolvedQueue } from './unsolved-queue'
@@ -42,7 +44,16 @@ function ProgressRing({ pct }: { pct: number }) {
   )
 }
 
-export default async function DashboardPage() {
+export default function DashboardPage() {
+  return (
+    <Suspense fallback={null}>
+      <DashboardPageBody />
+    </Suspense>
+  )
+}
+
+async function DashboardPageBody() {
+  await connection()
   const supabase = await createClient()
   const { data: { user } } = await supabase.auth.getUser()
   if (!user) redirect('/login')
diff --git a/apps/web/app/(auth)/garden/page.tsx b/apps/web/app/(auth)/garden/page.tsx
index 45df099..201e171 100644
--- a/apps/web/app/(auth)/garden/page.tsx
+++ b/apps/web/app/(auth)/garden/page.tsx
@@ -3,6 +3,7 @@ import { getTopicProficiency, getGardenSummary } from '@/lib/repositories/garden
 import { getUserBadges } from '@/lib/repositories/badge.repository'
 import { redirect } from 'next/navigation'
 import Link from 'next/link'
+import { Suspense } from 'react'
 import { CoffeeTree } from './coffee-tree'
 import { GardenTracker } from './garden-tracker'
 import { BadgeShowcase } from './badge-showcase'
@@ -10,7 +11,15 @@ import type { Metadata } from 'next'
 
 export const metadata: Metadata = { title: '咖啡莊園 — CaffeCode' }
 
-export default async function GardenPage() {
+export default function GardenPage() {
+  return (
+    <Suspense fallback={null}>
+      <GardenPageBody />
+    </Suspense>
+  )
+}
+
+async function GardenPageBody() {
   const supabase = await createClient()
   const { data: { user } } = await supabase.auth.getUser()
   if (!user) redirect('/login')
diff --git a/apps/web/app/(auth)/layout.tsx b/apps/web/app/(auth)/layout.tsx
index 502ed0c..ccda2d8 100644
--- a/apps/web/app/(auth)/layout.tsx
+++ b/apps/web/app/(auth)/layout.tsx
@@ -1,25 +1,28 @@
 import { createClient } from '@/lib/supabase/server'
 import { redirect } from 'next/navigation'
+import { Suspense } from 'react'
 import { PostHogIdentify } from '@/components/posthog-identify'
 
 // Belt-and-suspenders auth guard — proxy handles the primary redirect,
 // but this catches any edge cases where proxy is bypassed.
-export default async function AuthLayout({
+export default function AuthLayout({
   children,
 }: {
   children: React.ReactNode
 }) {
-  const supabase = await createClient()
-  const { data: { user } } = await supabase.auth.getUser()
-
-  if (!user) {
-    redirect('/login')
-  }
-
   return (
     <>
-      <PostHogIdentify userId={user.id} email={user.email ?? null} />
+      <Suspense fallback={null}>
+        <AuthGuard />
+      </Suspense>
       {children}
     </>
   )
 }
+
+async function AuthGuard() {
+  const supabase = await createClient()
+  const { data: { user } } = await supabase.auth.getUser()
+  if (!user) redirect('/login')
+  return <PostHogIdentify userId={user.id} email={user.email ?? null} />
+}
diff --git a/apps/web/app/(auth)/onboarding/page.tsx b/apps/web/app/(auth)/onboarding/page.tsx
index 8f7e807..5e503df 100644
--- a/apps/web/app/(auth)/onboarding/page.tsx
+++ b/apps/web/app/(auth)/onboarding/page.tsx
@@ -1,11 +1,20 @@
 import { createClient, createServiceClient } from '@/lib/supabase/server'
 import { redirect } from 'next/navigation'
+import { Suspense } from 'react'
 import { OnboardingWizard } from './onboarding-wizard'
 import type { Metadata } from 'next'
 
 export const metadata: Metadata = { title: '開始設定 — CaffeCode' }
 
-export default async function OnboardingPage() {
+export default function OnboardingPage() {
+  return (
+    <Suspense fallback={null}>
+      <OnboardingPageBody />
+    </Suspense>
+  )
+}
+
+async function OnboardingPageBody() {
   const supabase = await createClient()
   const { data: { user } } = await supabase.auth.getUser()
   if (!user) redirect('/login')
diff --git a/apps/web/app/(auth)/settings/account/page.tsx b/apps/web/app/(auth)/settings/account/page.tsx
index 3426b27..d00e98d 100644
--- a/apps/web/app/(auth)/settings/account/page.tsx
+++ b/apps/web/app/(auth)/settings/account/page.tsx
@@ -1,22 +1,29 @@
 import { createClient } from '@/lib/supabase/server'
 import { redirect } from 'next/navigation'
+import { Suspense } from 'react'
 import { AccountForm } from './account-form'
 import type { Metadata } from 'next'
 
 export const metadata: Metadata = { title: '帳號 — CaffeCode' }
 
-export default async function AccountPage() {
-  const supabase = await createClient()
-  const { data: { user } } = await supabase.auth.getUser()
-  if (!user) redirect('/login')
-
+export default function AccountPage() {
   return (
     <div className="space-y-8">
       <div>
         <h1 className="text-2xl font-bold mb-1">帳號</h1>
         <p className="text-sm text-muted-foreground">管理帳號資料與資料匯出</p>
       </div>
+      <Suspense fallback={null}>
+        <AccountGuard />
+      </Suspense>
       <AccountForm />
     </div>
   )
 }
+
+async function AccountGuard() {
+  const supabase = await createClient()
+  const { data: { user } } = await supabase.auth.getUser()
+  if (!user) redirect('/login')
+  return null
+}
diff --git a/apps/web/app/(auth)/settings/learning/page.tsx b/apps/web/app/(auth)/settings/learning/page.tsx
index 816bf11..21db848 100644
--- a/apps/web/app/(auth)/settings/learning/page.tsx
+++ b/apps/web/app/(auth)/settings/learning/page.tsx
@@ -1,12 +1,21 @@
 import { createClient, createServiceClient } from '@/lib/supabase/server'
 import { redirect } from 'next/navigation'
+import { Suspense } from 'react'
 import { LearningForm } from './learning-form'
 import { getSuggestedRange } from '@/lib/repositories/user.repository'
 import type { Metadata } from 'next'
 
 export const metadata: Metadata = { title: '學習模式 — CaffeCode' }
 
-export default async function LearningPage() {
+export default function LearningPage() {
+  return (
+    <Suspense fallback={null}>
+      <LearningPageBody />
+    </Suspense>
+  )
+}
+
+async function LearningPageBody() {
   const supabase = await createClient()
   const { data: { user } } = await supabase.auth.getUser()
   if (!user) redirect('/login')
diff --git a/apps/web/app/(auth)/settings/page.tsx b/apps/web/app/(auth)/settings/page.tsx
index 55ff1cf..2f3df38 100644
--- a/apps/web/app/(auth)/settings/page.tsx
+++ b/apps/web/app/(auth)/settings/page.tsx
@@ -2,6 +2,7 @@ import { createClient } from '@/lib/supabase/server'
 import { getUserSettings } from '@/lib/repositories/user.repository'
 import { getChannelsForUser } from '@/lib/repositories/channel.repository'
 import { redirect } from 'next/navigation'
+import { Suspense } from 'react'
 import { PushSettingsForm } from './push-settings-form'
 import { ChannelConnectButton } from './notifications/channel-connect-button'
 import { connectTelegram } from '@/lib/actions/telegram'
@@ -19,7 +20,15 @@ const CHANNEL_LABELS: Record<string, string> = {
   email: 'Email',
 }
 
-export default async function PushNotificationsPage() {
+export default function PushNotificationsPage() {
+  return (
+    <Suspense fallback={null}>
+      <PushNotificationsPageBody />
+    </Suspense>
+  )
+}
+
+async function PushNotificationsPageBody() {
   const supabase = await createClient()
   const { data: { user } } = await supabase.auth.getUser()
   if (!user) redirect('/login')
diff --git a/apps/web/app/(public)/lists/[slug]/page.tsx b/apps/web/app/(public)/lists/[slug]/page.tsx
index 313a68f..616cb82 100644
--- a/apps/web/app/(public)/lists/[slug]/page.tsx
+++ b/apps/web/app/(public)/lists/[slug]/page.tsx
@@ -5,21 +5,21 @@ import Link from 'next/link'
 import type { Metadata } from 'next'
 import { ListSubscribeBar, StartFromHereButton } from './list-subscribe-bar'
 
-import { cache } from 'react'
+import { Suspense } from 'react'
+import { cacheLife, cacheTag } from 'next/cache'
 import { JsonLd } from '@/components/seo/json-ld'
 import { breadcrumbSchema, itemListSchema } from '@/lib/seo/schemas'
 
-export const revalidate = 3600
-export const dynamicParams = true
-
 const DIFFICULTY_COLORS: Record<string, string> = {
   Easy: 'bg-emerald-50 text-emerald-900 dark:bg-emerald-950 dark:text-emerald-200',
   Medium: 'bg-amber-50 text-amber-900 dark:bg-amber-950 dark:text-amber-200',
   Hard: 'bg-rose-50 text-rose-900 dark:bg-rose-950 dark:text-rose-200',
 }
 
-// Deduplicate the list query between generateMetadata and page render
-const getListBySlug = cache(async (slug: string) => {
+async function getListBySlug(slug: string) {
+  'use cache'
+  cacheLife('hours')
+  cacheTag('lists', `list:${slug}`)
   const supabase = createServiceClient()
   const { data } = await supabase
     .from('curated_lists')
@@ -27,7 +27,25 @@ const getListBySlug = cache(async (slug: string) => {
     .eq('slug', slug)
     .single()
   return data
-})
+}
+
+async function getListProblems(listId: number) {
+  'use cache'
+  cacheLife('hours')
+  cacheTag('lists', 'problems', `list:${listId}:problems`)
+  const supabase = createServiceClient()
+  const { data } = await supabase
+    .from('list_problems')
+    .select(`
+      sequence_number,
+      problems (
+        id, leetcode_id, title, slug, difficulty, rating
+      )
+    `)
+    .eq('list_id', listId)
+    .order('sequence_number')
+  return data ?? []
+}
 
 interface PageProps {
   params: Promise<{ slug: string }>
@@ -46,24 +64,21 @@ export async function generateMetadata({ params }: PageProps): Promise<Metadata>
   }
 }
 
-export default async function ListDetailPage({ params }: PageProps) {
+export default function ListDetailPage({ params }: PageProps) {
+  return (
+    <Suspense fallback={null}>
+      <ListDetailPageBody params={params} />
+    </Suspense>
+  )
+}
+
+async function ListDetailPageBody({ params }: PageProps) {
   const { slug } = await params
   const list = await getListBySlug(slug)
 
   if (!list) notFound()
 
-  // Fetch problems in sequence order
-  const serviceClient = createServiceClient()
-  const { data: listProblems } = await serviceClient
-    .from('list_problems')
-    .select(`
-      sequence_number,
-      problems (
-        id, leetcode_id, title, slug, difficulty, rating
-      )
-    `)
-    .eq('list_id', list.id)
-    .order('sequence_number')
+  const listProblems = await getListProblems(list.id)
 
   // Check if user is authenticated and fetch their progress
   const supabase = await createClient()
@@ -72,7 +87,7 @@ export default async function ListDetailPage({ params }: PageProps) {
   let userProgress: { current_position: number; is_active: boolean } | null = null
   let solvedIds: Set<number> = new Set()
   if (user) {
-    const problemIds = (listProblems ?? [])
+    const problemIds = listProblems
       .map(lp => (lp.problems as unknown as { id: number } | null)?.id)
       .filter((id): id is number => id != null)
 
@@ -99,7 +114,7 @@ export default async function ListDetailPage({ params }: PageProps) {
     <main className="mx-auto max-w-4xl px-6 py-10">
       <JsonLd data={itemListSchema(
         list.name,
-        (listProblems ?? [])
+        listProblems
           .map(lp => lp.problems as unknown as { title: string; slug: string } | null)
           .filter((p): p is { title: string; slug: string } => p != null)
       )} />
@@ -160,7 +175,7 @@ export default async function ListDetailPage({ params }: PageProps) {
             </tr>
           </thead>
           <tbody className="divide-y">
-            {listProblems?.map((lp, idx) => {
+            {listProblems.map((lp, idx) => {
               const p = lp.problems as unknown as {
                 id: number; leetcode_id: number; title: string
                 slug: string; difficulty: string; rating: number | null
diff --git a/apps/web/app/(public)/lists/page.tsx b/apps/web/app/(public)/lists/page.tsx
index bb4f512..172e5ee 100644
--- a/apps/web/app/(public)/lists/page.tsx
+++ b/apps/web/app/(public)/lists/page.tsx
@@ -1,12 +1,12 @@
 import { createServiceClient } from '@/lib/supabase/server'
 import Link from 'next/link'
+import { Suspense } from 'react'
+import { cacheLife, cacheTag } from 'next/cache'
 import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card'
 import type { Metadata } from 'next'
 import { PAGE_SIZE } from '@/lib/utils/filter-url'
 import { FilterChips, Pagination } from '@/components/data-table'
 
-export const revalidate = 3600
-
 export const metadata: Metadata = {
   title: '學習清單',
   description: '45 份精選刷題清單，涵蓋演算法、資料結構與各大廠面試高頻題型',
@@ -34,29 +34,45 @@ interface SearchParams {
   page?: string
 }
 
-export default async function ListsPage({
-  searchParams,
-}: {
-  searchParams: Promise<SearchParams>
-}) {
-  const params = await searchParams
-  const currentPage = Math.max(1, Number(params.page ?? '1'))
-  const offset = (currentPage - 1) * PAGE_SIZE
-
+async function getFilteredLists(category: string, offset: number, limit: number) {
+  'use cache'
+  cacheLife('hours')
+  cacheTag('lists')
   const supabase = createServiceClient()
   let query = supabase
     .from('curated_lists')
     .select('id, slug, name, description, problem_count, type', { count: 'exact' })
     .order('id')
-    .range(offset, offset + PAGE_SIZE - 1)
-
-  const category = params.category ?? ''
+    .range(offset, offset + limit - 1)
   if (category && CATEGORY_DB_TYPES[category]) {
     query = query.in('type', CATEGORY_DB_TYPES[category])
   }
+  const { data, count } = await query
+  return { lists: data ?? [], count: count ?? 0 }
+}
+
+export default function ListsPage({
+  searchParams,
+}: {
+  searchParams: Promise<SearchParams>
+}) {
+  return (
+    <Suspense fallback={null}>
+      <ListsPageBody searchParams={searchParams} />
+    </Suspense>
+  )
+}
 
-  const { data: lists, count } = await query
-  const totalCount = count ?? 0
+async function ListsPageBody({
+  searchParams,
+}: {
+  searchParams: Promise<SearchParams>
+}) {
+  const params = await searchParams
+  const currentPage = Math.max(1, Number(params.page ?? '1'))
+  const offset = (currentPage - 1) * PAGE_SIZE
+  const category = params.category ?? ''
+  const { lists, count: totalCount } = await getFilteredLists(category, offset, PAGE_SIZE)
   const totalPages = Math.ceil(totalCount / PAGE_SIZE)
 
   return (
@@ -76,7 +92,7 @@ export default async function ListsPage({
       </div>
 
       <div className="grid grid-cols-1 gap-4 sm:grid-cols-2 lg:grid-cols-3">
-        {lists?.map((list) => (
+        {lists.map((list) => (
           <Link key={list.id} href={`/lists/${list.slug}`} className="group">
             <Card className="h-full transition-shadow group-hover:shadow-md">
               <CardHeader className="pb-2">
diff --git a/apps/web/app/(public)/problems/[slug]/page.tsx b/apps/web/app/(public)/problems/[slug]/page.tsx
index 6579040..9f79dab 100644
--- a/apps/web/app/(public)/problems/[slug]/page.tsx
+++ b/apps/web/app/(public)/problems/[slug]/page.tsx
@@ -11,13 +11,11 @@ import { createClient } from '@/lib/supabase/server'
 import { FeedbackWidget } from './feedback-widget'
 import { ProblemActions } from './problem-actions'
 import { cn } from '@/lib/utils'
-import { cache } from 'react'
+import { Suspense } from 'react'
+import { cacheLife, cacheTag } from 'next/cache'
 import { JsonLd } from '@/components/seo/json-ld'
 import { breadcrumbSchema, learningResourceSchema } from '@/lib/seo/schemas'
 
-export const revalidate = 3600
-export const dynamicParams = true
-
 const ReactMarkdown = dynamic(() => import('react-markdown'))
 
 const DIFFICULTY_COLORS: Record<string, string> = {
@@ -26,8 +24,10 @@ const DIFFICULTY_COLORS: Record<string, string> = {
   Hard: 'bg-rose-50 text-rose-900 dark:bg-rose-950 dark:text-rose-200',
 }
 
-// Deduplicate the problem query between generateMetadata and page render
-const getProblemBySlug = cache(async (slug: string) => {
+async function getProblemBySlug(slug: string) {
+  'use cache'
+  cacheLife('hours')
+  cacheTag('problems', `problem:${slug}`)
   const supabase = createServiceClient()
   const { data } = await supabase
     .from('problems')
@@ -41,7 +41,7 @@ const getProblemBySlug = cache(async (slug: string) => {
     .eq('slug', slug)
     .single()
   return data
-})
+}
 
 interface PageProps {
   params: Promise<{ slug: string }>
@@ -65,7 +65,15 @@ export async function generateMetadata({ params }: PageProps): Promise<Metadata>
   }
 }
 
-export default async function ProblemPage({ params }: PageProps) {
+export default function ProblemPage({ params }: PageProps) {
+  return (
+    <Suspense fallback={null}>
+      <ProblemPageBody params={params} />
+    </Suspense>
+  )
+}
+
+async function ProblemPageBody({ params }: PageProps) {
   const { slug } = await params
   const problem = await getProblemBySlug(slug)
 
diff --git a/apps/web/app/(public)/problems/page.tsx b/apps/web/app/(public)/problems/page.tsx
index 2f42b8d..3012cfa 100644
--- a/apps/web/app/(public)/problems/page.tsx
+++ b/apps/web/app/(public)/problems/page.tsx
@@ -2,13 +2,13 @@ import { createServiceClient, createClient } from '@/lib/supabase/server'
 import { getSolvedProblemIds } from '@/lib/repositories/history.repository'
 import { Badge } from '@/components/ui/badge'
 import Link from 'next/link'
+import { Suspense } from 'react'
+import { cacheLife, cacheTag } from 'next/cache'
 import type { Metadata } from 'next'
 import { PAGE_SIZE } from '@/lib/utils/filter-url'
 import { sanitizeSearch } from '@/lib/utils/sanitize-search'
 import { SearchInput, FilterChips, Pagination } from '@/components/data-table'
 
-export const revalidate = 3600
-
 export const metadata: Metadata = {
   title: '題庫',
   description: '瀏覽所有資料結構與演算法題目，含 AI 解題說明',
@@ -35,37 +35,63 @@ interface SearchParams {
   page?: string
 }
 
-export default async function ProblemsPage({
-  searchParams,
-}: {
-  searchParams: Promise<SearchParams>
-}) {
-  const params = await searchParams
-  const currentPage = Math.max(1, Number(params.page ?? '1'))
-  const offset = (currentPage - 1) * PAGE_SIZE
-
+async function getFilteredProblems(
+  difficulty: string,
+  q: string,
+  offset: number,
+  limit: number,
+) {
+  'use cache'
+  cacheLife('hours')
+  cacheTag('problems')
   const supabase = createServiceClient()
   let query = supabase
     .from('problems')
     .select('id, leetcode_id, title, slug, difficulty, rating, topics, problem_content!inner(id)', { count: 'exact' })
     .order('leetcode_id')
+  if (difficulty) query = query.eq('difficulty', difficulty)
+  if (q) query = query.ilike('title', `%${sanitizeSearch(q)}%`)
+  const { data, count } = await query.range(offset, offset + limit - 1)
+  return { problems: data ?? [], count: count ?? 0 }
+}
 
-  if (params.difficulty) query = query.eq('difficulty', params.difficulty)
-  if (params.q) query = query.ilike('title', `%${sanitizeSearch(params.q)}%`)
+export default function ProblemsPage({
+  searchParams,
+}: {
+  searchParams: Promise<SearchParams>
+}) {
+  return (
+    <Suspense fallback={null}>
+      <ProblemsPageBody searchParams={searchParams} />
+    </Suspense>
+  )
+}
 
-  const { data: problems, count } = await query.range(offset, offset + PAGE_SIZE - 1)
+async function ProblemsPageBody({
+  searchParams,
+}: {
+  searchParams: Promise<SearchParams>
+}) {
+  const params = await searchParams
+  const currentPage = Math.max(1, Number(params.page ?? '1'))
+  const offset = (currentPage - 1) * PAGE_SIZE
+  const { problems, count: totalCount } = await getFilteredProblems(
+    params.difficulty ?? '',
+    params.q ?? '',
+    offset,
+    PAGE_SIZE,
+  )
 
   // Conditionally fetch solved status for logged-in users
   let solvedIds: Set<number> = new Set()
   const userClient = await createClient()
   const { data: { user } } = await userClient.auth.getUser()
-  if (user && problems?.length) {
+  if (user && problems.length) {
     solvedIds = await getSolvedProblemIds(
       userClient, user.id, problems.map(p => p.id)
     )
   }
 
-  const totalCount = count ?? 0
   const totalPages = Math.ceil(totalCount / PAGE_SIZE)
 
   return (
@@ -103,7 +129,7 @@ export default async function ProblemsPage({
             </tr>
           </thead>
           <tbody className="divide-y">
-            {problems?.map((p) => (
+            {problems.map((p) => (
               <tr key={p.id} className="hover:bg-muted/30 transition-colors">
                 {user && (
                   <td className="px-2 py-3 text-center">
diff --git a/apps/web/app/api/cron/push/route.ts b/apps/web/app/api/cron/push/route.ts
index 8a020e2..1288fd3 100644
--- a/apps/web/app/api/cron/push/route.ts
+++ b/apps/web/app/api/cron/push/route.ts
@@ -8,7 +8,6 @@ import {
   createChannelRegistry,
 } from '@caffecode/shared'
 
-export const dynamic = 'force-dynamic'
 export const maxDuration = 300
 
 function isValidCronSecret(authHeader: string | null, cronSecret: string | undefined): boolean {
diff --git a/apps/web/app/api/health/route.ts b/apps/web/app/api/health/route.ts
index b8e9135..67cbdb4 100644
--- a/apps/web/app/api/health/route.ts
+++ b/apps/web/app/api/health/route.ts
@@ -1,7 +1,5 @@
 import { createServiceClient } from '@/lib/supabase/server'
 
-export const dynamic = 'force-dynamic'
-
 export async function GET() {
   try {
     const supabase = createServiceClient()
diff --git a/apps/web/app/layout.tsx b/apps/web/app/layout.tsx
index 6c1ae58..4aa6ba4 100644
--- a/apps/web/app/layout.tsx
+++ b/apps/web/app/layout.tsx
@@ -1,4 +1,5 @@
 import type { Metadata, Viewport } from 'next'
+import { Suspense } from 'react'
 import { Noto_Sans_TC, Geist_Mono } from 'next/font/google'
 import './globals.css'
 import { Toaster } from 'sonner'
@@ -41,27 +42,20 @@ export const metadata: Metadata = {
   },
 }
 
-export default async function RootLayout({
+export default function RootLayout({
   children,
 }: Readonly<{
   children: React.ReactNode
 }>) {
-  // Read user profile from proxy header (set in updateSession)
-  const headerStore = await headers()
-  const profileHeader = headerStore.get('x-user-profile')
-  const userProfile = profileHeader ? JSON.parse(decodeURIComponent(profileHeader)) as {
-    display_name: string | null
-    avatar_url: string | null
-    is_admin: boolean
-  } : null
-
   return (
     <html lang="zh-Hant">
       <body className={`${notoSansTC.variable} ${geistMono.variable} antialiased font-sans`}>
         <JsonLd data={organizationSchema()} />
         <JsonLd data={webSiteSchema()} />
         <PostHogProvider>
-          <Nav userProfile={userProfile} />
+          <Suspense fallback={<NavFallback />}>
+            <NavWithProfile />
+          </Suspense>
           {children}
         </PostHogProvider>
         <Toaster position="bottom-center" duration={3000} />
@@ -69,3 +63,25 @@ export default async function RootLayout({
     </html>
   )
 }
+
+async function NavWithProfile() {
+  const headerStore = await headers()
+  const profileHeader = headerStore.get('x-user-profile')
+  const userProfile = profileHeader ? JSON.parse(decodeURIComponent(profileHeader)) as {
+    display_name: string | null
+    avatar_url: string | null
+    is_admin: boolean
+  } : null
+  return <Nav userProfile={userProfile} />
+}
+
+function NavFallback() {
+  return (
+    <nav className="border-b bg-background sticky top-0 z-40">
+      <div className="mx-auto flex max-w-6xl items-center justify-between px-6 py-3">
+        <div className="h-7 w-28 rounded bg-muted/50" />
+        <div className="h-7 w-24 rounded bg-muted/50" />
+      </div>
+    </nav>
+  )
+}
diff --git a/apps/web/app/login/page.tsx b/apps/web/app/login/page.tsx
index e6d45fd..be7e4dd 100644
--- a/apps/web/app/login/page.tsx
+++ b/apps/web/app/login/page.tsx
@@ -1,5 +1,6 @@
 import { createClient } from '@/lib/supabase/server'
 import { redirect } from 'next/navigation'
+import { Suspense } from 'react'
 import { LoginForm } from './login-form'
 import type { Metadata } from 'next'
 
@@ -9,7 +10,19 @@ export const metadata: Metadata = {
   alternates: { canonical: '/login' },
 }
 
-export default async function LoginPage({
+export default function LoginPage({
+  searchParams,
+}: {
+  searchParams: Promise<{ error?: string; redirect?: string }>
+}) {
+  return (
+    <Suspense fallback={null}>
+      <LoginPageBody searchParams={searchParams} />
+    </Suspense>
+  )
+}
+
+export async function LoginPageBody({
   searchParams,
 }: {
   searchParams: Promise<{ error?: string; redirect?: string }>
diff --git a/apps/web/app/page.tsx b/apps/web/app/page.tsx
index 5d38a5d..6314841 100644
--- a/apps/web/app/page.tsx
+++ b/apps/web/app/page.tsx
@@ -1,11 +1,10 @@
 import Link from 'next/link'
+import { Suspense } from 'react'
 import { Button } from '@/components/ui/button'
 import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card'
 import { createClient } from '@/lib/supabase/server'
 import type { Metadata } from 'next'
 
-export const revalidate = 3600
-
 export const metadata: Metadata = {
   alternates: { canonical: '/' },
 }
@@ -33,10 +32,7 @@ const features = [
   },
 ]
 
-export default async function HomePage() {
-  const supabase = await createClient()
-  const { data: { user } } = await supabase.auth.getUser()
-
+export default function HomePage() {
   return (
     <main>
       {/* Hero */}
@@ -54,16 +50,9 @@ export default async function HomePage() {
           <p className="mt-2 text-sm text-muted-foreground/70 italic">
             久了之後，有些答案，只是比較有邏輯的咖啡話
           </p>
-          <div className="mt-8 flex items-center justify-center gap-4">
-            <Button asChild size="lg">
-              <Link href={user ? '/dashboard' : '/login'}>
-                {user ? '前往主頁' : '免費開始'}
-              </Link>
-            </Button>
-            <Button asChild variant="outline" size="lg">
-              <Link href="/problems">瀏覽題庫</Link>
-            </Button>
-          </div>
+          <Suspense fallback={<HeroCtaFallback />}>
+            <HeroCta />
+          </Suspense>
         </div>
       </section>
 
@@ -87,18 +76,56 @@ export default async function HomePage() {
         </div>
       </section>
 
-      {/* CTA — 未登入才顯示 */}
-      {!user && (
-        <section className="border-t py-20 px-6 text-center">
-          <div className="mx-auto max-w-lg">
-            <h2 className="text-2xl font-bold">準備好了嗎？</h2>
-            <p className="mt-2 text-muted-foreground">立即加入，今天就建立你的刷題習慣。</p>
-            <Button asChild size="lg" className="mt-6">
-              <Link href="/login">用 Google 或 GitHub 登入</Link>
-            </Button>
-          </div>
-        </section>
-      )}
+      <Suspense fallback={null}>
+        <SignInCta />
+      </Suspense>
     </main>
   )
 }
+
+async function HeroCta() {
+  const supabase = await createClient()
+  const { data: { user } } = await supabase.auth.getUser()
+  return (
+    <div className="mt-8 flex items-center justify-center gap-4">
+      <Button asChild size="lg">
+        <Link href={user ? '/dashboard' : '/login'}>
+          {user ? '前往主頁' : '免費開始'}
+        </Link>
+      </Button>
+      <Button asChild variant="outline" size="lg">
+        <Link href="/problems">瀏覽題庫</Link>
+      </Button>
+    </div>
+  )
+}
+
+function HeroCtaFallback() {
+  return (
+    <div className="mt-8 flex items-center justify-center gap-4">
+      <Button asChild size="lg">
+        <Link href="/login">免費開始</Link>
+      </Button>
+      <Button asChild variant="outline" size="lg">
+        <Link href="/problems">瀏覽題庫</Link>
+      </Button>
+    </div>
+  )
+}
+
+async function SignInCta() {
+  const supabase = await createClient()
+  const { data: { user } } = await supabase.auth.getUser()
+  if (user) return null
+  return (
+    <section className="border-t py-20 px-6 text-center">
+      <div className="mx-auto max-w-lg">
+        <h2 className="text-2xl font-bold">準備好了嗎？</h2>
+        <p className="mt-2 text-muted-foreground">立即加入，今天就建立你的刷題習慣。</p>
+        <Button asChild size="lg" className="mt-6">
+          <Link href="/login">用 Google 或 GitHub 登入</Link>
+        </Button>
+      </div>
+    </section>
+  )
+}
diff --git a/apps/web/app/sitemap.ts b/apps/web/app/sitemap.ts
index 13efb1d..aca105e 100644
--- a/apps/web/app/sitemap.ts
+++ b/apps/web/app/sitemap.ts
@@ -1,15 +1,23 @@
 import { createServiceClient } from '@/lib/supabase/server'
+import { cacheLife, cacheTag } from 'next/cache'
+import { connection } from 'next/server'
 import type { MetadataRoute } from 'next'
 
-export const revalidate = 3600
-
-export default async function sitemap(): Promise<MetadataRoute.Sitemap> {
+async function getSitemapData() {
+  'use cache'
+  cacheLife('hours')
+  cacheTag('problems', 'lists')
   const supabase = createServiceClient()
-
   const [problemsRes, listsRes] = await Promise.all([
     supabase.from('problems').select('slug').not('slug', 'is', null).limit(5000),
     supabase.from('curated_lists').select('slug').limit(1000),
   ])
+  return { problemsRes, listsRes }
+}
+
+export default async function sitemap(): Promise<MetadataRoute.Sitemap> {
+  await connection()
+  const { problemsRes, listsRes } = await getSitemapData()
 
   const baseUrl = process.env.NEXT_PUBLIC_SITE_URL ?? 'https://caffecode.net'
   const now = new Date()
diff --git a/apps/web/lib/__tests__/admin-actions.test.ts b/apps/web/lib/__tests__/admin-actions.test.ts
index fbd8b27..fe1727f 100644
--- a/apps/web/lib/__tests__/admin-actions.test.ts
+++ b/apps/web/lib/__tests__/admin-actions.test.ts
@@ -30,7 +30,7 @@ vi.mock('@caffecode/shared', () => ({
   resetChannelFailures: vi.fn().mockResolvedValue(undefined),
 }))
 
-vi.mock('next/cache', () => ({ revalidatePath: vi.fn() }))
+vi.mock('next/cache', () => ({ revalidatePath: vi.fn(), revalidateTag: vi.fn() }))
 vi.mock('@/lib/logger', () => ({
   logger: { error: vi.fn(), warn: vi.fn(), info: vi.fn() },
 }))
diff --git a/apps/web/lib/actions/_admin-helpers.ts b/apps/web/lib/actions/_admin-helpers.ts
index f195948..2bf9ae3 100644
--- a/apps/web/lib/actions/_admin-helpers.ts
+++ b/apps/web/lib/actions/_admin-helpers.ts
@@ -7,7 +7,7 @@
  * input validation and DB mutations.
  */
 import type { SupabaseClient } from '@supabase/supabase-js'
-import { revalidatePath } from 'next/cache'
+import { revalidatePath, revalidateTag } from 'next/cache'
 import { createClient, createServiceClient } from '@/lib/supabase/server'
 import { logger } from '@/lib/logger'
 
@@ -40,6 +40,8 @@ export interface RunAdminActionOptions {
   errorMessage: string
   /** Path to revalidate after a successful mutation. */
   revalidate?: string
+  /** Cache tags to invalidate after a successful mutation (for use-cache helpers). */
+  tags?: string[]
   /** Additional log fields attached to the error log. */
   logContext?: Record<string, unknown>
 }
@@ -59,6 +61,7 @@ export async function runAdminAction<T>(
   try {
     const result = await handler(ctx)
     if (options.revalidate) revalidatePath(options.revalidate)
+    if (options.tags) options.tags.forEach(tag => revalidateTag(tag, 'max'))
     return result
   } catch (err) {
     logger.error(
diff --git a/apps/web/lib/actions/admin.ts b/apps/web/lib/actions/admin.ts
index 286b848..1c23464 100644
--- a/apps/web/lib/actions/admin.ts
+++ b/apps/web/lib/actions/admin.ts
@@ -25,7 +25,12 @@ export async function deleteProblem(id: number) {
       const { error } = await db.from('problems').delete().eq('id', id)
       if (error) throw error
     },
-    { revalidate: '/admin/problems', errorMessage: 'Failed to delete problem', logContext: { problemId: id } },
+    {
+      revalidate: '/admin/problems',
+      tags: ['problems', 'lists'],
+      errorMessage: 'Failed to delete problem',
+      logContext: { problemId: id },
+    },
   )
 }
 
@@ -42,7 +47,12 @@ export async function flagForRegeneration(problemId: number) {
         .eq('problem_id', problemId)
       if (error) throw error
     },
-    { revalidate: '/admin/content', errorMessage: 'Failed to flag for regeneration', logContext: { problemId } },
+    {
+      revalidate: '/admin/content',
+      tags: ['problems'],
+      errorMessage: 'Failed to flag for regeneration',
+      logContext: { problemId },
+    },
   )
 }
 
@@ -57,7 +67,12 @@ export async function unflagRegeneration(problemId: number) {
         .eq('problem_id', problemId)
       if (error) throw error
     },
-    { revalidate: '/admin/content', errorMessage: 'Failed to unflag regeneration', logContext: { problemId } },
+    {
+      revalidate: '/admin/content',
+      tags: ['problems'],
+      errorMessage: 'Failed to unflag regeneration',
+      logContext: { problemId },
+    },
   )
 }
 
diff --git a/apps/web/next.config.ts b/apps/web/next.config.ts
index 5b427ad..317f00c 100644
--- a/apps/web/next.config.ts
+++ b/apps/web/next.config.ts
@@ -2,6 +2,7 @@ import { withSentryConfig } from '@sentry/nextjs'
 import type { NextConfig } from "next";
 
 const nextConfig: NextConfig = {
+  cacheComponents: true,
   images: {
     remotePatterns: [
       {
diff --git a/docs/deferred-improvements.md b/docs/deferred-improvements.md
index b73b1d9..a82cf73 100644
--- a/docs/deferred-improvements.md
+++ b/docs/deferred-improvements.md
@@ -5,92 +5,22 @@ deferred, along with the reasoning and the minimum work required to pick them up
 later. Complements the merged PRs from the 2026-04-17 full-project review
 (PRs #38–#49).
 
-## Next.js 16 Cache Components adoption
+## Branded channel-identifier types — decided to skip
 
-**Status**: attempted, reverted. Tracked for a dedicated future PR.
-
-**Goal**: replace `export const revalidate = 3600` on public pages with
-`'use cache' + cacheLife + cacheTag`, enabling Partial Prerendering (PPR) and
-targeted tag-based invalidation from admin mutations.
-
-**Attempt**: branch `feat/next16-cache-components` set `cacheComponents: true`
-in `next.config.ts` and migrated:
-
-- `app/sitemap.ts` — fully cached (no user state).
-- `app/(public)/lists/page.tsx` — extracted data fetch into a cached helper.
-- `app/(public)/lists/[slug]/page.tsx` — `getListBySlug` + `getListProblems`
-  as cached helpers; per-user progress stays dynamic in the page body.
-- `app/(public)/problems/page.tsx` — catalog query cached; solved-IDs fetch
-  stays dynamic.
-- `app/(public)/problems/[slug]/page.tsx` — `getProblemBySlug` cached with
-  `cacheTag('problems', 'problem:<slug>')`.
-- `app/page.tsx` — made dynamic (auth-aware CTA).
-- `app/api/{cron/push,health}/route.ts` — removed `dynamic = 'force-dynamic'`
-  (incompatible with cacheComponents; defaults to dynamic).
-- `lib/actions/admin.ts` — `deleteProblem` wired to
-  `revalidateTag('problems', 'max')` + `revalidateTag('lists', 'max')`.
-
-**Why reverted**: `next build` with `cacheComponents: true` enforces that
-**every uncached data access must sit inside a `<Suspense>` boundary during
-static generation**. Admin pages (each one fetches user-specific or live data)
-and several public pages (per-user solved checkmarks, progress bar) fail the
-build with errors like:
-
-```
-Route "/admin/channels": Uncached data was accessed outside of <Suspense>.
-Route "/lists/[slug]": Uncached data was accessed outside of <Suspense>.
-```
-
-Making this work cleanly requires Suspense-wrapping every dynamic region on
-every page that currently blends static and user-specific data — roughly
-20+ files in `app/(admin)/**` plus the public routes that show solved status.
-That exceeds what the original review item scoped and is a meaningful UI
-refactor (streaming fallbacks, layout shifts, etc.) rather than a drop-in
-migration.
-
-**Resume checklist** when someone picks this up:
-
-1. Re-apply the changes from the `feat/next16-cache-components` attempt as a
-   starting point (see git history for the branch or this document's summary).
-2. Audit each page under `app/(admin)/**` and `app/(public)/**`. For each
-   Server Component that mixes cached and dynamic data, wrap the dynamic
-   section in `<Suspense fallback={...}>` and move the dynamic fetch into the
-   child component.
-3. Design skeleton fallbacks consistent with the current layout to avoid
-   perceived layout shift.
-4. Verify `next build` with `cacheComponents: true` succeeds for every route.
-5. Extend admin mutations to call `revalidateTag('problems'|'lists', 'max')`
-   alongside the existing `revalidatePath` so updates propagate instantly.
-6. Remove every remaining `export const revalidate` from app routes.
-
-**Why this is worth revisiting**: when complete, content edits in the admin UI
-show up on public pages within seconds instead of up to an hour, and static
-shells render immediately while dynamic regions stream in — real UX win for
-SEO-critical problem and list pages.
-
-## Branded channel-identifier types
-
-**Status**: deferred in PR #42. Low-value-per-effort.
+**Status**: reviewed 2026-04-18, decided not to pursue unless conditions change.
 
 **Goal**: prevent swapping a Telegram chat-id for a LINE user-id or an email
 address at compile time by branding the `string` identifier type per channel.
 
-**Why deferred**: would require threading branded types through every channel
-call site across shared + web. With only three channel types and the bundled
-push pipeline (PR #40) already failing loudly on mismatched registry entries,
-the compile-time gain is narrow.
-
-## Node 22 -> 24 LTS, pnpm 9 -> 10
-
-**Status**: deferred in PR #43. Needs manual install + regression verification.
-
-**Goal**: stay on current LTS (Vercel's default is Node 24 as of 2026-03).
+**Why skipped**: threading branded types through every channel call site
+across `packages/shared` and `apps/web` touches dozens of files for a narrow
+compile-time gain. The push pipeline (PR #40) already fails loudly on
+mismatched registry entries at runtime, and with only three channel types the
+mental overhead of remembering which string is which is small.
 
-**Resume checklist**:
+**When to revisit**:
 
-1. Update `.nvmrc` and `.github/workflows/ci.yml` to `24`.
-2. Bump `packageManager` in root `package.json` to `pnpm@10.x` and re-run
-   `pnpm install` to regenerate the lockfile.
-3. Full regression: `pnpm build`, `pnpm test`,
-   `pnpm --filter @caffecode/web exec playwright test`.
-4. Watch for pnpm 10 breaking changes (strict peer deps, different hoisting).
+- A real mis-routing bug lands in production.
+- The channel count grows beyond three (e.g. Slack, Discord, Matrix).
+- An adjacent refactor already touches most channel call sites, making the
+  type tightening nearly free.
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 0fd8e59..210774a 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -141,40 +141,6 @@ importers:
         specifier: ^4.0.18
         version: 4.0.18(@opentelemetry/api@1.9.0)(@types/node@20.19.33)(jiti@2.6.1)(jsdom@28.1.0(@noble/hashes@1.8.0))(lightningcss@1.31.1)(msw@2.12.10(@types/node@20.19.33)(typescript@5.9.3))(terser@5.46.0)(tsx@4.21.0)
 
-  apps/worker:
-    dependencies:
-      '@caffecode/shared':
-        specifier: workspace:*
-        version: link:../../packages/shared
-      '@supabase/supabase-js':
-        specifier: ^2.97.0
-        version: 2.97.0
-      p-limit:
-        specifier: ^7.3.0
-        version: 7.3.0
-      pino:
-        specifier: ^10.3.1
-        version: 10.3.1
-      zod:
-        specifier: ^4.3.6
-        version: 4.3.6
-    devDependencies:
-      '@types/node':
-        specifier: ^20
-        version: 20.19.33
-      pino-pretty:
-        specifier: ^13.1.3
-        version: 13.1.3
-      tsx:
-        specifier: ^4.21.0
-        version: 4.21.0
-      typescript:
-        specifier: ^5
-        version: 5.9.3
-      vitest:
-        specifier: ^4.0.18
-        version: 4.0.18(@opentelemetry/api@1.9.0)(@types/node@20.19.33)(jiti@2.6.1)(jsdom@28.1.0(@noble/hashes@1.8.0))(lightningcss@1.31.1)(msw@2.12.10(@types/node@20.19.33)(typescript@5.9.3))(terser@5.46.0)(tsx@4.21.0)
-
   packages/shared:
     dependencies:
       '@react-email/components':
@@ -9633,8 +9599,8 @@ snapshots:
       '@next/eslint-plugin-next': 16.1.6
       eslint: 9.39.3(jiti@2.6.1)
       eslint-import-resolver-node: 0.3.9
-      eslint-import-resolver-typescript: 3.10.1(eslint-plugin-import@2.32.0)(eslint@9.39.3(jiti@2.6.1))
-      eslint-plugin-import: 2.32.0(@typescript-eslint/parser@8.56.1(eslint@9.39.3(jiti@2.6.1))(typescript@5.9.3))(eslint-import-resolver-typescript@3.10.1)(eslint@9.39.3(jiti@2.6.1))
+      eslint-import-resolver-typescript: 3.10.1(eslint-plugin-import@2.32.0(@typescript-eslint/parser@8.56.1(eslint@9.39.3(jiti@2.6.1))(typescript@5.9.3))(eslint@9.39.3(jiti@2.6.1)))(eslint@9.39.3(jiti@2.6.1))
+      eslint-plugin-import: 2.32.0(@typescript-eslint/parser@8.56.1(eslint@9.39.3(jiti@2.6.1))(typescript@5.9.3))(eslint-import-resolver-typescript@3.10.1(eslint-plugin-import@2.32.0(@typescript-eslint/parser@8.56.1(eslint@9.39.3(jiti@2.6.1))(typescript@5.9.3))(eslint@9.39.3(jiti@2.6.1)))(eslint@9.39.3(jiti@2.6.1)))(eslint@9.39.3(jiti@2.6.1))
       eslint-plugin-jsx-a11y: 6.10.2(eslint@9.39.3(jiti@2.6.1))
       eslint-plugin-react: 7.37.5(eslint@9.39.3(jiti@2.6.1))
       eslint-plugin-react-hooks: 7.0.1(eslint@9.39.3(jiti@2.6.1))
@@ -9656,7 +9622,7 @@ snapshots:
     transitivePeerDependencies:
       - supports-color
 
-  eslint-import-resolver-typescript@3.10.1(eslint-plugin-import@2.32.0)(eslint@9.39.3(jiti@2.6.1)):
+  eslint-import-resolver-typescript@3.10.1(eslint-plugin-import@2.32.0(@typescript-eslint/parser@8.56.1(eslint@9.39.3(jiti@2.6.1))(typescript@5.9.3))(eslint@9.39.3(jiti@2.6.1)))(eslint@9.39.3(jiti@2.6.1)):
     dependencies:
       '@nolyfill/is-core-module': 1.0.39
       debug: 4.4.3
@@ -9667,22 +9633,22 @@ snapshots:
       tinyglobby: 0.2.15
       unrs-resolver: 1.11.1
     optionalDependencies:
-      eslint-plugin-import: 2.32.0(@typescript-eslint/parser@8.56.1(eslint@9.39.3(jiti@2.6.1))(typescript@5.9.3))(eslint-import-resolver-typescript@3.10.1)(eslint@9.39.3(jiti@2.6.1))
+      eslint-plugin-import: 2.32.0(@typescript-eslint/parser@8.56.1(eslint@9.39.3(jiti@2.6.1))(typescript@5.9.3))(eslint-import-resolver-typescript@3.10.1(eslint-plugin-import@2.32.0(@typescript-eslint/parser@8.56.1(eslint@9.39.3(jiti@2.6.1))(typescript@5.9.3))(eslint@9.39.3(jiti@2.6.1)))(eslint@9.39.3(jiti@2.6.1)))(eslint@9.39.3(jiti@2.6.1))
     transitivePeerDependencies:
       - supports-color
 
-  eslint-module-utils@2.12.1(@typescript-eslint/parser@8.56.1(eslint@9.39.3(jiti@2.6.1))(typescript@5.9.3))(eslint-import-resolver-node@0.3.9)(eslint-import-resolver-typescript@3.10.1)(eslint@9.39.3(jiti@2.6.1)):
+  eslint-module-utils@2.12.1(@typescript-eslint/parser@8.56.1(eslint@9.39.3(jiti@2.6.1))(typescript@5.9.3))(eslint-import-resolver-node@0.3.9)(eslint-import-resolver-typescript@3.10.1(eslint-plugin-import@2.32.0(@typescript-eslint/parser@8.56.1(eslint@9.39.3(jiti@2.6.1))(typescript@5.9.3))(eslint@9.39.3(jiti@2.6.1)))(eslint@9.39.3(jiti@2.6.1)))(eslint@9.39.3(jiti@2.6.1)):
     dependencies:
       debug: 3.2.7
     optionalDependencies:
       '@typescript-eslint/parser': 8.56.1(eslint@9.39.3(jiti@2.6.1))(typescript@5.9.3)
       eslint: 9.39.3(jiti@2.6.1)
       eslint-import-resolver-node: 0.3.9
-      eslint-import-resolver-typescript: 3.10.1(eslint-plugin-import@2.32.0)(eslint@9.39.3(jiti@2.6.1))
+      eslint-import-resolver-typescript: 3.10.1(eslint-plugin-import@2.32.0(@typescript-eslint/parser@8.56.1(eslint@9.39.3(jiti@2.6.1))(typescript@5.9.3))(eslint@9.39.3(jiti@2.6.1)))(eslint@9.39.3(jiti@2.6.1))
     transitivePeerDependencies:
       - supports-color
 
-  eslint-plugin-import@2.32.0(@typescript-eslint/parser@8.56.1(eslint@9.39.3(jiti@2.6.1))(typescript@5.9.3))(eslint-import-resolver-typescript@3.10.1)(eslint@9.39.3(jiti@2.6.1)):
+  eslint-plugin-import@2.32.0(@typescript-eslint/parser@8.56.1(eslint@9.39.3(jiti@2.6.1))(typescript@5.9.3))(eslint-import-resolver-typescript@3.10.1(eslint-plugin-import@2.32.0(@typescript-eslint/parser@8.56.1(eslint@9.39.3(jiti@2.6.1))(typescript@5.9.3))(eslint@9.39.3(jiti@2.6.1)))(eslint@9.39.3(jiti@2.6.1)))(eslint@9.39.3(jiti@2.6.1)):
     dependencies:
       '@rtsao/scc': 1.1.0
       array-includes: 3.1.9
@@ -9693,7 +9659,7 @@ snapshots:
       doctrine: 2.1.0
       eslint: 9.39.3(jiti@2.6.1)
       eslint-import-resolver-node: 0.3.9
-      eslint-module-utils: 2.12.1(@typescript-eslint/parser@8.56.1(eslint@9.39.3(jiti@2.6.1))(typescript@5.9.3))(eslint-import-resolver-node@0.3.9)(eslint-import-resolver-typescript@3.10.1)(eslint@9.39.3(jiti@2.6.1))
+      eslint-module-utils: 2.12.1(@typescript-eslint/parser@8.56.1(eslint@9.39.3(jiti@2.6.1))(typescript@5.9.3))(eslint-import-resolver-node@0.3.9)(eslint-import-resolver-typescript@3.10.1(eslint-plugin-import@2.32.0(@typescript-eslint/parser@8.56.1(eslint@9.39.3(jiti@2.6.1))(typescript@5.9.3))(eslint@9.39.3(jiti@2.6.1)))(eslint@9.39.3(jiti@2.6.1)))(eslint@9.39.3(jiti@2.6.1))
       hasown: 2.0.2
       is-core-module: 2.16.1
       is-glob: 4.0.3
@@ -12309,6 +12275,7 @@ snapshots:
       get-tsconfig: 4.13.6
     optionalDependencies:
       fsevents: 2.3.3
+    optional: true
 
   turbo-darwin-64@2.8.14:
     optional: true