Consolidate project docs into CLAUDE.md, remove AGENTS.md

CLAUDE.md is now self-contained: absorbed the still-accurate parts of AGENTS.md (Next.js-is-different warning, port allocation, Nginx block, SEO notes, Meilisearch as phase-2 plan) and dropped the stale bits (pre-width/height schema, "public domain only" content policy, old manga.04080616.xyz domain, aspirational build order). Also added findings surfaced by auditing CLAUDE.md against the actual code: - Placeholder-based reader architecture and its invariants (must have Page.width/height, scroll={false} on Links, history.replaceState for URL sync, prev/next derived from currentChapterNum). - docker-compose.yml only brings up the app; Postgres is external. - localStorage key format sunnymh:last-read:<slug> + legacy bare-number fallback that must be preserved. - Immersive reader route: Header/BottomNav return null on /manga/[slug]/[n]. - signCoverUrls is the single source of truth for signed cover URLs. - iOS Safari conventions: viewportFit cover, pt-safe/pb-safe, WebKit momentum scrolling, overflow-x:hidden. - Dev gotchas: allowedDevOrigins VPN whitelist, prisma/seed.ts is docs-only, scraper is the real data pipeline. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Add scroll={false} to the last two reader-entry Links
2026-04-12 18:25:10 +08:00 · 2026-04-12 18:24:56 +08:00
3 changed files with 154 additions and 201 deletions
--- a/AGENTS.md
+++ b/AGENTS.md
@ -1,163 +0,0 @@
 # 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.
 # Manga Website Project Requirements
 ## Tech Stack
 | Layer | Technology |
 |-------|-----------|
 | Frontend & Backend | Next.js (App Router, TypeScript, Tailwind CSS) |
 | Database | PostgreSQL 16 |
 | ORM | Prisma |
 | Image Storage | Cloudflare R2 |
 | Containerization | Docker + Docker Compose (managed via Portainer) |
 | Reverse Proxy | Nginx via aaPanel |
 | Domain | `manga.04080616.xyz` |
 ## Infrastructure
 - **Server**: Proxmox host, Docker VM/LXC running Portainer
 - **Reverse proxy**: aaPanel Nginx routes `manga.04080616.xyz` → `http://127.0.0.1:3001`
 - **SSL**: Let's Encrypt via aaPanel
 - **DDNS already configured** — no Cloudflare Tunnel needed
 ### Port Allocation
 | Port | Service |
 |------|---------|
 | 3001 | Next.js app (host) → 3000 (container) |
 | 5433 | PostgreSQL (host) → 5432 (container) |
 Ports 3000, 8000–8002, 8005, 2283, 5432, 51820–51821, 9443 are already in use.
 ## Deployment Workflow
 1. Develop on macOS locally
 2. Push code to Gitea (`gitea.04080616.xyz/yiekheng/sunnymh-manga-site`)
 3. On Proxmox Docker host: `git pull` → `docker build` → restart container
 4. Portainer used for container management (GUI)
 ## Image Storage (Cloudflare R2)
 - Images stored in R2 (S3-compatible), **not** on the Proxmox host
 - Upload flow: backend generates presigned URL → browser uploads directly to R2 → database records image path
 - Format: **WebP** (25–35% smaller than JPEG)
 - Multiple resolutions: thumbnail / reading / original
 ### R2 Directory Structure
 ```
 /manga/{manga_id}/{chapter_id}/{page_number}.webp
 /thumbnails/{manga_id}/cover.webp
 ```
 ## Database Schema (Prisma)
 ```prisma
 model Manga {
  id          Int       @id @default(autoincrement())
  title       String
  description String
  coverUrl    String
  slug        String    @unique
  status      Status    @default(PUBLISHED)
  chapters    Chapter[]
  createdAt   DateTime  @default(now())
  updatedAt   DateTime  @updatedAt
 }
 model Chapter {
  id        Int     @id @default(autoincrement())
  mangaId   Int
  number    Int
  title     String
  pages     Page[]
  manga     Manga   @relation(fields: [mangaId], references: [id])
 }
 model Page {
  id        Int     @id @default(autoincrement())
  chapterId Int
  number    Int
  imageUrl  String
  chapter   Chapter @relation(fields: [chapterId], references: [id])
 }
 enum Status {
  PUBLISHED
  DRAFT
 }
 ```
 ## Features
 ### Core (build first)
 - Manga listing page with cover images
 - Manga detail page (title, description, chapter list)
 - Chapter reader page (page-by-page image display)
 - Internal search by manga title (PostgreSQL `contains` query)
 ### SEO
 - Next.js SSR/SSG for all public pages
 - `generateMetadata()` per page (title, description)
 - Auto-generated `/sitemap.xml` via `app/sitemap.ts`
 - Submit sitemap to Google Search Console
 ### Search
 - **Phase 1**: PostgreSQL `contains` with `insensitive` mode (sufficient for < 10k titles)
 - **Phase 2** (future): Meilisearch for fuzzy/full-text search if needed
 ## URL Structure
 ```
 /                          Homepage (manga grid)
 /manga/[slug]              Manga detail + chapter list
 /manga/[slug]/[chapter]    Chapter reader
 /api/search?q=             Search API endpoint
 /api/manga                 Manga CRUD (admin)
 /api/upload                R2 presigned URL generation
 ```
 ## Environment Variables (.env)
 ```env
 DATABASE_URL=postgresql://manga_user:yourpassword@localhost:5433/manga_db
 R2_ACCOUNT_ID=your_cloudflare_account_id
 R2_ACCESS_KEY=your_r2_access_key
 R2_SECRET_KEY=your_r2_secret_key
 R2_BUCKET=manga-images
 R2_PUBLIC_URL=https://your-r2-public-url.r2.dev
 ```
 ## Nginx Reverse Proxy Config (aaPanel)
 ```nginx
 location / {
    proxy_pass http://127.0.0.1:3001;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection 'upgrade';
    proxy_set_header Host $host;
    proxy_cache_bypass $http_upgrade;
 }
 ```
 ## Content Source
 - **Public domain / free manga only** (no copyright issues)
 - Sources: Comic Book Plus, Digital Comic Museum, Internet Archive
 - Initial: manual download and upload
 - Future: automated scraper (Node.js + cheerio) for allowed sources
 ## Recommended Build Order
 1. Set up Prisma schema + connect to PostgreSQL
 2. Build manga listing and reader pages (static UI first)
 3. Wire up database queries via Prisma
 4. Add R2 upload + image serving
 5. Add search API
 6. Add SEO metadata + sitemap
 7. Dockerize and deploy to Proxmox via Gitea
--- a/CLAUDE.md
+++ b/CLAUDE.md
@ -2,67 +2,181 @@
 This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
-@AGENTS.md
+> **This is NOT the Next.js you know.** Next 16 / App Router has breaking
 > changes from older training data — APIs, conventions, and file structure
 > may differ. Check `node_modules/next/dist/docs/` before writing routing
 > or metadata code, and heed deprecation notices.
 ## Build & Development Commands
 ```bash
-npm run dev          # Start dev server (hot reload)
+npm run dev              # Start dev server (hot reload, Turbopack)
 npm run build            # Production build
 npm start                # Start production server
 npm run lint             # ESLint (flat config, v9+)
 npx prisma generate      # Regenerate Prisma client after schema changes
-npx prisma migrate dev --name <name>  # Create and apply a migration
+npx prisma db push       # Sync schema to DB (this repo uses db push, not migrate)
-npx prisma db push   # Push schema changes without migration (dev only)
+npx tsx scripts/backfill-page-dims.ts   # Probe Page.width/height via image-size against R2
 ```
 The DB is managed via `prisma db push`, not `migrate dev`. `prisma/migrations/`
 holds SQL files kept for reference only; `migrate dev` won't work (no shadow
 DB permission on this Postgres).
 ## Architecture
 **Stack**: Next.js 16.2.1 (App Router) · React 19 · TypeScript · Tailwind CSS v4 · Prisma · PostgreSQL 16 · Cloudflare R2
-**Path alias**: `@/*` maps to project root (configured in tsconfig.json).
+**Path alias**: `@/*` maps to project root.
-### App Router Structure
+### Reader is placeholder-based — read this before touching `PageReader.tsx`
-```
+`components/PageReader.tsx` is deliberately **not** a naive `pages.map(<img>)`.
-app/
+Every page renders as a `<div>` placeholder with `style={{ aspectRatio: w/h }}`
-├── page.tsx                          # Homepage (manga grid)
+so the document height is correct before any image bytes load. This avoids
-├── layout.tsx                        # Root layout (Geist fonts, metadata)
+a whole class of iOS Safari scroll-anchoring / prepend-shift bugs that a
-├── manga/[slug]/page.tsx             # Manga detail + chapter list
+simple reader would hit. Key invariants:
 ├── manga/[slug]/[chapter]/page.tsx   # Chapter reader
 ├── api/search/route.ts               # Search endpoint (?q=)
 ├── api/manga/route.ts                # Manga CRUD (admin)
 ├── api/upload/route.ts               # R2 presigned URL generation
 └── sitemap.ts                        # Auto-generated sitemap
 ```
-### Data Flow
+- `Page.width` / `Page.height` **must** be populated for every row. The
  Python scraper writes them on insert; the backfill script covers older
  rows. With dims=0, the reader falls back to 3/4 and layout shifts on
  image load.
 - Initial chapter meta (dims skeleton) is fetched server-side in
  `app/manga/[slug]/[chapter]/page.tsx` and passed as a prop. Later
  chapters' meta is lazy-fetched via `/api/chapters/[id]/meta`.
 - Image URLs (signed, short-TTL) come in batches via `/api/pages` triggered
  by an `IntersectionObserver` with 1200 px margin. A separate
  intersecting-pages `Map` is maintained for the scroll tick so the topmost
  visible page can be found in O(k) without walking every placeholder.
 - Continuous multi-chapter reading auto-appends the next chapter when the
  user gets within `PREFETCH_NEXT_AT = 3` pages of the end.
 - URL syncs to the chapter currently in viewport via
  `window.history.replaceState`. `prevChapter` / `nextChapter` for
  double-tap nav are derived from `currentChapterNum`, **not** from the URL
  or props.
 - All Links into the reader use `scroll={false}`, and the double-tap
  `router.push(..., { scroll: false })`. This is load-bearing — without it,
  App Router's default scroll-to-top clobbers the `useLayoutEffect` that
  restores the resume page.
 - Reading progress is persisted to `localStorage` under the key
  `sunnymh:last-read:<slug>` as JSON `{chapter, page}`. `readProgress`
  in `components/ReadingProgressButton.tsx` also accepts the **legacy
  bare-number format** (just a chapter number string) for backward
  compatibility — preserve this when touching the storage format.
- **Database**: Prisma ORM → PostgreSQL. Models: `Manga`, `Chapter`, `Page` (see `prisma/schema.prisma`).
+### Immersive reader route
 - **Images**: Stored in Cloudflare R2 (S3-compatible). Upload flow: backend generates presigned URL → browser uploads directly to R2 → database records the image path.
 - **R2 bucket layout**: `/manga/{manga_id}/{chapter_id}/{page_number}.webp` and `/thumbnails/{manga_id}/cover.webp`.
 - **Search**: PostgreSQL `contains` with `insensitive` mode (phase 1). No external search engine needed until >10k titles.
-### Key Libraries
+`components/Header.tsx` and `components/BottomNav.tsx` both return `null`
 when the pathname matches `/manga/[slug]/[chapter]` — the reader runs
 full-bleed with its own chrome. Anything new that relies on the global
 nav being present needs to account for this.
- `@aws-sdk/client-s3` + `@aws-sdk/s3-request-presigner` — R2 uploads (S3-compatible API)
+### Data flow
- `prisma` / `@prisma/client` — ORM and database client
+
 - **Prisma models** (see `prisma/schema.prisma`): `Manga`, `Chapter`, `Page`.
  `Page` carries `width` / `height`. `Manga` has `genre` as a
  comma-separated string; parse with `lib/genres.ts`.
 - **Images live in R2** (S3-compatible). Format is **WebP** (~25–35%
  smaller than JPEG). The app **never** serves R2 URLs directly —
  `lib/r2.ts::signUrl` / `signCoverUrls` mint presigned GETs with a 60 s
  TTL; `keyFromPublicUrl` reverses a public URL to its R2 key.
  `signCoverUrls` is the standardized pattern for list pages — homepage
  carousel, genre grid, search results, detail page all route through it.
  Don't bypass it by handing raw `manga.coverUrl` to the browser.
 - **R2 layout** (populated by the scraper — not this app):
  - `manga/<slug>/chapters/<chapter_number>/<page_number>.webp`
  - `manga/<slug>/cover.webp`
 - **Search**: PostgreSQL `contains` + `mode: 'insensitive'`. Fine up to
  ~10k titles. If a future scale requires fuzzy/full-text, the planned
  swap-in is Meilisearch.
 ### Key routes
 - `app/page.tsx` — homepage (trending carousel + genre tabs).
 - `app/manga/[slug]/page.tsx` — detail + chapter list + "continue reading".
 - `app/manga/[slug]/[chapter]/page.tsx` — reader. Issues both required
  queries (manga+chapters, initial chapter page meta) in parallel via
  `Promise.all`.
 - `app/api/pages/route.ts` — batched `{number, imageUrl}` with signed URLs.
 - `app/api/chapters/[chapterId]/meta/route.ts` — `[{number, width, height}]`
  for lazy next-chapter prefetch.
 - `app/api/search/route.ts` — case-insensitive title search.
 - `app/api/upload/route.ts` — R2 presigned PUT (admin/scraper only; no DB
  write happens here).
 - `app/sitemap.ts` — auto-generated `/sitemap.xml`. Each page uses
  `generateMetadata()` for per-route title/description.
 ### Ingestion is a sibling Python repo
 New manga and chapters are created by `../manga-dl/manga.py`, not by this
 web app. It scrapes, converts to WebP, uploads to R2, and writes
 `Manga` / `Chapter` / `Page` rows directly via `psycopg2`. When updating the
 Prisma schema, update the sibling's SQL INSERTs too (they're raw, not ORM).
 ### Branding
 - Source SVGs in `logo/qingtian_*.svg`.
 - Wired up as: `app/icon.svg` (browser favicon, Next.js convention),
  `app/apple-icon.svg` (iOS home-screen), `public/logo.svg` (Header `<img>`).
 - Accent color: `#268a52` (green sunflower), defined as `--accent` in
  `app/globals.css`. Hover: `#1f7044`.
 - Brand name: 晴天漫画 · Sunny MH.
 ### iOS Safari conventions
 - `viewport` in `app/layout.tsx` sets `viewportFit: "cover"` so the app
  extends into the notch; any sticky/fixed chrome must use the
  `pt-safe` / `pb-safe` utilities from `app/globals.css` (they map to
  `env(safe-area-inset-*)`). Header and BottomNav already do.
 - Horizontal carousels (`components/TrendingCarousel.tsx`) set
  `WebkitOverflowScrolling: "touch"` inline for momentum scrolling.
  Preserve this on any new swipe lane.
 - `overflow-x: hidden` on `body` (globals.css) prevents the fixed
  BottomNav from leaking horizontal scroll on mobile.
 ## Deployment
- **Docker**: `docker build` from root Dockerfile → container exposes port 3000, mapped to host port 3001.
+- **Host**: Proxmox VM running Docker + Portainer.
- **Compose**: `docker-compose.yml` runs both the app and PostgreSQL 16.
+- **Flow**: Push to Gitea (`gitea.04080616.xyz/yiekheng/sunnymh-manga-site`)
- **Flow**: Push to Gitea → `git pull` on Proxmox Docker host → rebuild → restart via Portainer.
+  → `git pull` on the Docker host → rebuild → restart via Portainer.
- **Reverse proxy**: aaPanel Nginx routes `manga.04080616.xyz` → `http://127.0.0.1:3001`.
+- **Dockerfile** at repo root; container listens on 3000, mapped to host
- **Port 3001** (app) and **5433** (Postgres) on the host — many other ports are taken.
+  3001. `docker-compose.yml` only brings up the app — **Postgres is
  external** (connected via `DATABASE_URL`), not defined in compose.
 - **Reverse proxy**: aaPanel Nginx routes `www.04080616.xyz` →
  `http://127.0.0.1:3001`. SSL via Let's Encrypt managed in aaPanel. DDNS
  already configured — no Cloudflare Tunnel involved.
 - **Host ports in use elsewhere**: 3000, 8000–8002, 8005, 2283, 5432,
  51820–51821, 9443 — don't collide. Postgres lives on host 5433.
 - After schema changes reach prod, run `scripts/backfill-page-dims.ts`
  once against prod DB to populate dims for historical rows.
 ### Minimal Nginx location block (aaPanel)
 ```nginx
 location / {
    proxy_pass http://127.0.0.1:3001;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection 'upgrade';
    proxy_set_header Host $host;
    proxy_cache_bypass $http_upgrade;
 }
 ```
 ## Environment Variables
-Required in `.env` (see docker-compose.yml for container equivalents):
+Required in `.env` (container equivalents in `docker-compose.yml`):
- `DATABASE_URL` — PostgreSQL connection string
+- `DATABASE_URL` — PostgreSQL connection string, e.g. `postgresql://manga_user:…@localhost:5433/manga_db`
 - `R2_ACCOUNT_ID`, `R2_ACCESS_KEY`, `R2_SECRET_KEY`, `R2_BUCKET`, `R2_PUBLIC_URL` — Cloudflare R2
-## Content Policy
+## Dev gotchas
-All manga content must be **public domain or free** (Comic Book Plus, Digital Comic Museum, Internet Archive). No copyrighted material.
+- **`next.config.ts` has `allowedDevOrigins: ["10.8.0.2"]`** — a VPN-access
  whitelist so dev on macOS is reachable from other devices on the tunnel.
  Removing or breaking it silently blocks hot-reload from those origins;
  update it if the VPN subnet changes.
 - **`prisma/seed.ts` is documentation-only.** The real data pipeline is
  the sibling Python scraper (`../manga-dl/manga.py`) writing directly via
  `psycopg2`. The `npm run seed` script exists for quick local dev but is
  never run in production.
--- a/components/PageReader.tsx
+++ b/components/PageReader.tsx
@ -373,6 +373,7 @@ export function PageReader({
        <div className="flex items-center gap-3 px-4 h-12 max-w-4xl mx-auto">
          <Link
            href={`/manga/${mangaSlug}`}
            scroll={false}
            className="text-foreground/80 hover:text-foreground transition-colors shrink-0"
            aria-label="Back to manga"
          >
@ -476,6 +477,7 @@ export function PageReader({
          <p className="text-base font-semibold">{mangaTitle}</p>
          <Link
            href="/"
            scroll={false}
            className="px-5 py-2 rounded-lg bg-accent text-white text-sm font-semibold transition-colors hover:bg-accent-hover"
          >
            Back to Home