# Kế hoạch triển khai: Tối ưu hiệu năng web phy-vr360

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Giảm tải GPU/CPU để web hết giật/lag, laptop không còn nóng/quạt rú, vẫn giữ thẩm mỹ.

**Architecture:** Tối ưu theo 4 giai đoạn — (1) chặn vòng lặp vẽ chạy nền vô ích, (2) nén tài nguyên ảnh/model + giới hạn cache VRAM, (3) cắt animation CSS luôn-bật & hiệu ứng nặng, (4) cấu hình build + chia nhỏ bundle. Mỗi giai đoạn đo lại trước khi sang bước kế.

**Tech Stack:** Next.js 16 (bản đã chỉnh sửa), React 19, three.js 0.184, framer-motion, @paper-design/shaders-react, sharp (đã cài), @gltf-transform/cli (sẽ cài).

**Spec:** `docs/superpowers/specs/2026-06-25-toi-uu-hieu-nang-design.md`

---

## Lưu ý chung cho người triển khai

- **Next.js 16 ở đây là bản đã chỉnh sửa** (`AGENTS.md`). Trước khi sửa `next.config.ts` hoặc dùng `next/dynamic`, **đọc** tài liệu tương ứng trong `node_modules/next/dist/docs/` để dùng đúng API.
- **Không có test tự động** cho hiệu năng. "Kiểm chứng" ở đây = `npm run lint` + `npm run build` pass, **xem bằng mắt** không vỡ giao diện, và **đo** (DevTools Performance/Rendering, kích thước file). Mỗi task nêu rõ cách đo.
- Làm việc trên nhánh `main` (đúng quy ước hiện tại của dự án). Commit thường xuyên, mỗi task một commit.
- Mở DevTools → **Rendering → "Frame Rendering Stats"** và tab **Performance** để so trước/sau. Đếm ngữ cảnh WebGL bằng `about:gpu` hoặc đếm thẻ `<canvas>` đang vẽ.

---

## File Structure

| File | Trách nhiệm | Hành động |
|---|---|---|
| `src/app/lib/render-gate.ts` | Tiện ích chung: bật/tắt vòng lặp vẽ theo khả năng nhìn + trạng thái tab | Create |
| `src/app/components/ui/hero-shader-background.tsx` | Nền hero: bỏ canvas three.js, còn 1 shader, gate theo tầm nhìn | Modify |
| `src/app/components/ui/hero-panorama-background.tsx` | Canvas three.js xoay (gỡ khỏi hero) | Delete (hoặc bỏ dùng) |
| `src/app/components/antiquity/AntiquityViewer.tsx` | Viewer .glb: render theo nhu cầu + gate + giảm pixelRatio + meshopt | Modify |
| `scripts/optimize-images.mjs` | Nén panorama: 4096px + xuất WebP, sinh LQIP theo path webp | Modify |
| `scripts/optimize-models.mjs` | Nén .glb (meshopt + texture webp), backup bản gốc | Create |
| `src/app/tours/chua-thai-lac.ts` | Trỏ ảnh tour sang `.webp` | Modify |
| `src/app/components/VirtualTour.tsx` | Cache texture có giới hạn (LRU) + pin cảnh hiện tại/lân cận | Modify |
| `src/app/globals.css` | Tắt animation vô hạn ít giá trị, giảm blur/will-change | Modify |
| `src/app/layout.tsx` | (Tùy chọn) tinh giản lớp grain | Modify |
| `next.config.ts` | Bật tối ưu ảnh (AVIF/WebP) | Modify |
| `src/app/tour/chua-thai-lac/page.tsx` | Dynamic import viewer | Modify |
| `src/app/co-vat/page.tsx` | Dynamic import showcase | Modify |
| `package.json` | Thêm script `optimize:images`, `optimize:models` | Modify |

---

# GIAI ĐOẠN 1 — Chặn việc chạy nền vô ích

## Task 1: Tiện ích render-gate dùng chung

**Files:**
- Create: `src/app/lib/render-gate.ts`

- [ ] **Step 1: Tạo file tiện ích**

```ts
// src/app/lib/render-gate.ts
// Chỉ cho phép vòng lặp vẽ (rAF/setAnimationLoop) chạy khi phần tử nằm trong vùng nhìn
// VÀ tab đang hiển thị. Gọi onChange(active) mỗi khi trạng thái đổi. Trả về hàm dọn dẹp.
export function createRenderGate(
  element: Element,
  onChange: (active: boolean) => void,
): () => void {
  let onScreen = false;
  let visible = typeof document === "undefined" ? true : !document.hidden;
  let last = false;

  const emit = () => {
    const next = onScreen && visible;
    if (next !== last) {
      last = next;
      onChange(next);
    }
  };

  const io = new IntersectionObserver(
    (entries) => {
      onScreen = entries.some((entry) => entry.isIntersecting);
      emit();
    },
    { threshold: 0.01 },
  );
  io.observe(element);

  const onVisibility = () => {
    visible = !document.hidden;
    emit();
  };
  document.addEventListener("visibilitychange", onVisibility);

  return () => {
    io.disconnect();
    document.removeEventListener("visibilitychange", onVisibility);
  };
}
```

- [ ] **Step 2: Kiểm chứng biên dịch**

Run: `npm run lint`
Expected: không lỗi mới ở file vừa tạo.

- [ ] **Step 3: Commit**

```bash
git add src/app/lib/render-gate.ts
git commit -m "perf: tiện ích render-gate (dừng vòng lặp vẽ khi ngoài màn hình/đổi tab)"
```

---

## Task 2: Hero — bỏ canvas three.js, còn 1 shader, gate theo tầm nhìn

**Files:**
- Modify: `src/app/components/ui/hero-shader-background.tsx`
- Delete: `src/app/components/ui/hero-panorama-background.tsx`

Hiện hero chồng: ảnh nền CSS + `HeroPanoramaBackground` (canvas three.js xoay liên tục) + 2× `MeshGradient` + `mix-blend-mode: soft-light`. Sau task: ảnh nền CSS giữ nguyên (đã đủ "nền"), **bỏ canvas three.js**, **còn 1 `MeshGradient`**, bỏ `soft-light`, và **chỉ render shader khi hero trong tầm nhìn**.

- [ ] **Step 1: Viết lại `hero-shader-background.tsx`**

```tsx
"use client";

import { MeshGradient } from "@paper-design/shaders-react";
import type React from "react";
import { useEffect, useRef, useState } from "react";
import { createRenderGate } from "@/app/lib/render-gate";

interface HeroShaderBackgroundProps {
  children: React.ReactNode;
  imageSrc: string;
}

export function HeroShaderBackground({ children, imageSrc }: HeroShaderBackgroundProps) {
  const rootRef = useRef<HTMLDivElement>(null);
  const [shaderActive, setShaderActive] = useState(false);

  useEffect(() => {
    const el = rootRef.current;
    if (!el) return;
    return createRenderGate(el, setShaderActive);
  }, []);

  return (
    <div
      ref={rootRef}
      className="relative isolate overflow-hidden border-b border-[var(--surface-border)]"
    >
      <div
        aria-hidden
        className="absolute inset-0 bg-cover bg-center opacity-[0.58] saturate-[1.12] contrast-[1.04]"
        style={{ backgroundImage: `url("${imageSrc}")` }}
      />
      <div aria-hidden className="absolute inset-0 bg-[rgb(243_247_240_/_0.12)]" />

      {/* Một lớp shader duy nhất, chỉ vẽ khi hero trong tầm nhìn + tab hiển thị */}
      {shaderActive ? (
        <div aria-hidden className="absolute inset-0 overflow-hidden opacity-40">
          <MeshGradient
            className="absolute inset-0 h-full w-full"
            colors={["#f8fbf2", "#d6b468", "#e0eddf", "#245f4b", "#ffffff"]}
            speed={0.24}
          />
        </div>
      ) : null}

      <div
        aria-hidden
        className="absolute inset-0 bg-[linear-gradient(90deg,rgb(243_247_240_/_0.93)_0%,rgb(243_247_240_/_0.72)_42%,rgb(243_247_240_/_0.14)_100%)]"
      />
      <div
        aria-hidden
        className="absolute inset-x-0 bottom-0 h-44 bg-[linear-gradient(180deg,transparent,rgb(243_247_240_/_0.98))]"
      />

      {children}
    </div>
  );
}
```

> Ghi chú: đã bỏ `HeroPanoramaBackground`, bỏ `<svg>` filter `feTurbulence`, bỏ `MeshGradient` thứ 2 và `mix-blend-mode: soft-light`. Ảnh nền tĩnh (`imageSrc`, vốn là `01.jpg`) vẫn cho cảm giác panorama.

- [ ] **Step 2: Xóa component không còn dùng**

```bash
git rm src/app/components/ui/hero-panorama-background.tsx
```

- [ ] **Step 3: Kiểm chứng không còn tham chiếu**

Run: `grep -rn "hero-panorama-background\|HeroPanoramaBackground" src/`
Expected: không còn kết quả.

- [ ] **Step 4: Build + xem bằng mắt**

Run: `npm run build`
Expected: build pass. Chạy `npm run dev`, mở `/` — hero vẫn đẹp; mở DevTools → chỉ còn **0–1** canvas WebGL ở hero (trước đây 3 lớp). Cuộn xuống dưới: shader ngừng vẽ (kiểm tra Performance không còn frame liên tục từ hero).

- [ ] **Step 5: Commit**

```bash
git add -A
git commit -m "perf: hero bỏ canvas three.js + còn 1 shader, gate theo tầm nhìn (giảm 3 ngữ cảnh WebGL)"
```

---

## Task 3: AntiquityViewer — render theo nhu cầu + gate + giảm pixelRatio

**Files:**
- Modify: `src/app/components/antiquity/AntiquityViewer.tsx`

Hiện `tick()` render **mọi frame vô điều kiện** (kể cả khi đứng yên, autoRotate tắt) và pixelRatio tới 2. Chuyển sang render-on-demand như tour viewer + gate khi ngoài màn hình + pixelRatio tối đa 1.5.

- [ ] **Step 1: Thêm import**

Sửa đầu file, thêm 2 import (sau dòng `import { RoomEnvironment } ...`):

```ts
import { MeshoptDecoder } from "three/examples/jsm/libs/meshopt_decoder.module.js";
import { createRenderGate } from "@/app/lib/render-gate";
```

- [ ] **Step 2: Giảm pixelRatio**

Sửa `AntiquityViewer.tsx` dòng pixelRatio:

```ts
// CŨ:
renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2));
// MỚI:
renderer.setPixelRatio(Math.min(window.devicePixelRatio, 1.5));
```

- [ ] **Step 3: Nạp meshopt decoder cho GLTFLoader**

Sửa chỗ tạo loader:

```ts
// CŨ:
const loader = new GLTFLoader();
// MỚI:
const loader = new GLTFLoader();
loader.setMeshoptDecoder(MeshoptDecoder);
```

- [ ] **Step 4: Render theo nhu cầu + gate**

Thay khối từ `const resize = () => {` (giữ nguyên `resize`) và đặc biệt thay **vòng `tick`** + thêm gate. Cụ thể, thay đoạn:

```ts
    const tick = () => {
      controls.update();
      renderer.render(scene, camera);
      raf = requestAnimationFrame(tick);
    };
    tick();
```

bằng:

```ts
    let needsRender = true;
    let active = true;
    const requestRender = () => {
      needsRender = true;
    };
    controls.addEventListener("change", requestRender);

    const stopGate = createRenderGate(mount, (isActive) => {
      active = isActive;
      if (isActive) requestRender();
    });

    const tick = () => {
      raf = requestAnimationFrame(tick);
      if (!active) return;
      // controls.update() trả về true khi camera còn chuyển động (damping/autoRotate)
      const moving = controls.update();
      if (needsRender || moving || controls.autoRotate) {
        renderer.render(scene, camera);
        needsRender = false;
      }
    };
    tick();
```

Thêm `requestRender()` sau khi model load xong (trong callback `loader.load` success, ngay sau `setStatus("ready");`):

```ts
        setStatus("ready");
        requestRender();
```

Trong `resize`, ép vẽ lại — sửa cuối hàm `resize`:

```ts
    const resize = () => {
      const w = mount.clientWidth;
      const h = mount.clientHeight;
      if (!w || !h) return;
      renderer.setSize(w, h, false);
      camera.aspect = w / h;
      camera.updateProjectionMatrix();
      needsRender = true;
    };
```

> `needsRender` được khai báo sau `resize` trong code hiện tại — chuyển khai báo `let needsRender = true;` lên **trước** hàm `resize` (ngay sau dòng tạo `controls`/`controlsRef.current = controls;`) để `resize` dùng được. Đảm bảo thứ tự: khai báo `needsRender`/`active`/`requestRender` trước cả `resize` và `tick`.

- [ ] **Step 5: Dọn dẹp trong cleanup**

Trong hàm cleanup (return của useEffect), thêm trước `controls.dispose();`:

```ts
      stopGate();
      controls.removeEventListener("change", requestRender);
```

- [ ] **Step 6: Build + đo**

Run: `npm run build`
Expected: pass. Chạy dev, mở `/co-vat`:
- Khi **tắt tự xoay** và không tương tác → DevTools Performance cho thấy **không còn render liên tục** (đường GPU phẳng).
- Cuộn để viewer ra khỏi màn hình → vòng lặp dừng.
- Bật tự xoay vẫn mượt.

- [ ] **Step 7: Commit**

```bash
git add src/app/components/antiquity/AntiquityViewer.tsx
git commit -m "perf: AntiquityViewer render theo nhu cầu + gate ngoài màn hình + pixelRatio 1.5 + meshopt"
```

---

# GIAI ĐOẠN 2 — Pipeline tài nguyên

## Task 4: Mở rộng script nén ảnh — 4096px + xuất WebP

**Files:**
- Modify: `scripts/optimize-images.mjs`
- Modify: `package.json`
- Sinh ra: `public/images/chua-thai-lac/NN.webp` (×26) + cập nhật `src/app/tours/chua-thai-lac.lqip.ts`

Script hiện nén panorama **in-place JPEG ở 6144px** (vì vậy vẫn 2–4MB) và sinh LQIP theo path `.jpg`. Đổi sang: resize **4096px**, **xuất thêm WebP**, và **khóa LQIP theo path `.webp`** (vì tour sẽ nạp `.webp`). Vẫn giữ nén `.jpg` (cho các `<Image>` next/image ở trang landing đang dùng `img("NN.jpg")`).

- [ ] **Step 1: Sửa hằng số**

```js
// CŨ:
const PANO_WIDTH = 6144;
// MỚI:
const PANO_WIDTH = 4096;
const PANO_WEBP_QUALITY = 78;
```

- [ ] **Step 2: Trong `optimizePanoramas()` — xuất thêm WebP và khóa LQIP theo `.webp`**

Thay thân vòng `for (const f of files) { ... }` bằng:

```js
  for (const f of files) {
    const dest = path.join(PANO_DIR, f);
    const src = await sourceFrom(dest, "chua-thai-lac");
    const before = (await fs.stat(dest)).size;

    // JPEG (giữ cho next/image ở trang landing) — cũng hạ về 4096
    const jpgBuf = await sharp(src)
      .rotate()
      .resize({ width: PANO_WIDTH, withoutEnlargement: true })
      .jpeg({ quality: PANO_QUALITY, mozjpeg: true, progressive: true })
      .toBuffer();
    await fs.writeFile(dest, jpgBuf);

    // WebP (tour viewer nạp bản này) — cùng tên, đuôi .webp
    const webpName = f.replace(/\.jpe?g$/i, ".webp");
    const webpDest = path.join(PANO_DIR, webpName);
    const webpBuf = await sharp(src)
      .rotate()
      .resize({ width: PANO_WIDTH, withoutEnlargement: true })
      .webp({ quality: PANO_WEBP_QUALITY })
      .toBuffer();
    await fs.writeFile(webpDest, webpBuf);

    // LQIP khóa theo path .webp (đúng path tour yêu cầu)
    const lqipBuf = await sharp(src).rotate().resize({ width: LQIP_WIDTH }).jpeg({ quality: 40 }).toBuffer();
    lqip["/images/chua-thai-lac/" + webpName] = "data:image/jpeg;base64," + lqipBuf.toString("base64");

    console.log(
      `${f}: ${fmt(before)} -> jpg ${fmt(jpgBuf.length)} | webp ${fmt(webpBuf.length)}`,
    );
  }
```

- [ ] **Step 3: Thêm npm script**

Trong `package.json`, mục `scripts`, thêm:

```json
    "optimize:images": "node scripts/optimize-images.mjs",
```

- [ ] **Step 4: Chạy script (an toàn — luôn nén từ backup gốc trong `image-originals/`)**

Run: `npm run optimize:images`
Expected: in ra mỗi ảnh `… -> jpg ~0.6–1.0MB | webp ~0.25–0.5MB`; cuối cùng `Wrote src/app/tours/chua-thai-lac.lqip.ts (26 entries)`.

- [ ] **Step 5: Đo tổng dung lượng giảm**

Run (PowerShell):
```powershell
"{0:N1} MB" -f ((Get-ChildItem public/images/chua-thai-lac/*.webp | Measure-Object Length -Sum).Sum/1MB)
```
Expected: tổng WebP ~7–12MB (so với ~70MB JPEG 6144 trước đây).

- [ ] **Step 6: Commit**

```bash
git add scripts/optimize-images.mjs package.json public/images/chua-thai-lac/ src/app/tours/chua-thai-lac.lqip.ts
git commit -m "perf: nén panorama 4096px + xuất WebP, LQIP theo path webp"
```

---

## Task 5: Trỏ tour sang ảnh WebP

**Files:**
- Modify: `src/app/tours/chua-thai-lac.ts:12`

Đổi **một dòng** `imageForFile` để mọi `scene.image`, `welcomeBackgroundImage`, `welcomeCards[].image` tự động dùng `.webp` (đều derive từ hàm này).

- [ ] **Step 1: Sửa `imageForFile`**

```ts
// CŨ:
const imageForFile = (fileNumber: number) => `${base}/${String(fileNumber).padStart(2, "0")}.jpg`;
// MỚI:
const imageForFile = (fileNumber: number) => `${base}/${String(fileNumber).padStart(2, "0")}.webp`;
```

- [ ] **Step 2: Build + xem tour**

Run: `npm run build`
Expected: pass. Chạy dev, mở `/tour/chua-thai-lac` → ảnh 360 hiển thị bình thường (giờ tải bản webp nhẹ), blur-up LQIP vẫn hiện (vì LQIP đã khóa theo `.webp`). Mạng (Network tab) tải `.webp` ~0.3MB thay vì `.jpg` vài MB.

- [ ] **Step 3: Commit**

```bash
git add src/app/tours/chua-thai-lac.ts
git commit -m "perf: tour nạp panorama WebP thay cho JPEG"
```

---

## Task 6: Cache texture có giới hạn (LRU) trong VirtualTour

**Files:**
- Modify: `src/app/components/VirtualTour.tsx` (vùng cache module-level ~dòng 214–285 và hàm `preloadTourScene` ~dòng 1312)

Hiện `panoramaTextureCache` giữ **toàn bộ** texture vĩnh viễn → tràn VRAM. Thêm giới hạn LRU + "ghim" cảnh hiện tại/lân cận để không bao giờ dispose texture đang dùng.

- [ ] **Step 1: Thêm hằng số + tiện ích cache (ngay sau khai báo `panoramaTextureCache`, gần dòng 214)**

```ts
const MAX_CACHED_PANORAMAS = 8; // đủ cho cảnh hiện tại + các cảnh lân cận
const pinnedPanoramaUrls = new Set<string>();

// Ghim các ảnh không được phép dispose (cảnh hiện tại + lân cận).
function setPinnedPanoramas(urls: string[]) {
  pinnedPanoramaUrls.clear();
  urls.forEach((url) => pinnedPanoramaUrls.add(url));
}

// Đánh dấu ảnh là mới-dùng-nhất (Map giữ thứ tự chèn) rồi dọn nếu vượt giới hạn.
function touchPanoramaCache(image: string, texture: THREE.Texture) {
  panoramaTextureCache.delete(image);
  panoramaTextureCache.set(image, texture);
  evictPanoramaTextures();
}

function evictPanoramaTextures() {
  if (panoramaTextureCache.size <= MAX_CACHED_PANORAMAS) {
    return;
  }
  for (const [url, texture] of panoramaTextureCache) {
    if (panoramaTextureCache.size <= MAX_CACHED_PANORAMAS) {
      break;
    }
    if (pinnedPanoramaUrls.has(url)) {
      continue; // không dispose ảnh đang ghim (đang hiển thị/lân cận)
    }
    panoramaTextureCache.delete(url);
    texture.dispose();
  }
}
```

- [ ] **Step 2: Gọi `touchPanoramaCache` trong `loadPanoramaTexture`**

Trong `loadPanoramaTexture`, nhánh cache-hit (đầu hàm):

```ts
// CŨ:
  if (cachedTexture) {
    onProgress?.(100);
    return Promise.resolve(cachedTexture);
  }
// MỚI:
  if (cachedTexture) {
    touchPanoramaCache(image, cachedTexture);
    onProgress?.(100);
    return Promise.resolve(cachedTexture);
  }
```

Và trong callback load thành công:

```ts
// CŨ:
        panoramaTextureCache.set(image, texture);
        panoramaTexturePromises.delete(image);
// MỚI:
        panoramaTextureCache.set(image, texture);
        evictPanoramaTextures();
        panoramaTexturePromises.delete(image);
```

- [ ] **Step 3: Ghim cảnh hiện tại + lân cận trong `preloadTourScene`**

Hàm `preloadTourScene` (≈ dòng 1312) đã liệt kê cảnh hiện tại + các cảnh đích của hotspot. Thêm ghim ở **đầu** hàm, trước khi preload:

```ts
  const preloadTourScene = useCallback(
    (scene: TourScene) => {
      // Ghim ảnh đang dùng + các cảnh lân cận để LRU không dispose nhầm.
      const neighborImages = scene.hotspots
        .map((hotspot) => tourConfig.sceneById.get(hotspot.targetId)?.image)
        .filter((image): image is string => Boolean(image));
      setPinnedPanoramas([scene.image, ...neighborImages]);

      const preloadImage = (image: string) => {
        loadPanoramaTexture(image)
          .then((texture) => warmPanoramaTexture(image, texture))
          .catch(() => undefined);
      };
      // ... phần còn lại giữ nguyên
```

- [ ] **Step 4: Build + đo VRAM/độ mượt khi chuyển nhiều cảnh**

Run: `npm run build`
Expected: pass. Chạy dev, đi qua **nhiều cảnh** (>10) trong tour. Trước đây mọi texture tích lại; giờ DevTools → Memory (hoặc `about:gpu`) cho thấy số texture giữ lại ổn định (~8). Không có nhấp nháy/blank khi quay lại cảnh trước.

- [ ] **Step 5: Commit**

```bash
git add src/app/components/VirtualTour.tsx
git commit -m "perf: giới hạn cache panorama (LRU) + ghim cảnh hiện tại/lân cận, tránh tràn VRAM"
```

---

## Task 7: Nén model .glb (meshopt + texture WebP)

**Files:**
- Create: `scripts/optimize-models.mjs`
- Modify: `package.json`
- Sinh ra: `public/antiquity/chuong-1.glb`, `chuong-2.glb` (ghi đè bản nén; gốc lưu ở `model-originals/`)

`chuong-2.glb` 40MB, `chuong-1.glb` 27MB → đơ khi parse. Nén bằng `@gltf-transform/cli` (meshopt cho geometry + nén texture webp). Decoder meshopt đã nạp ở Task 3.

- [ ] **Step 1: Cài công cụ**

Run: `npm i -D @gltf-transform/cli`
Expected: cài xong, có `node_modules/.bin/gltf-transform`.

- [ ] **Step 2: Tạo script nén model**

```js
// scripts/optimize-models.mjs
// Nén .glb: backup bản gốc rồi tối ưu (meshopt + nén texture webp).
// Chạy: node scripts/optimize-models.mjs  (an toàn chạy lại — luôn nén từ backup gốc)
import { promises as fs } from "node:fs";
import path from "node:path";
import { execFile } from "node:child_process";
import { promisify } from "node:util";

const run = promisify(execFile);
const ROOT = process.cwd();
const MODEL_DIR = path.join(ROOT, "public/antiquity");
const BACKUP_DIR = path.join(ROOT, "model-originals");
const fmt = (b) => (b / 1024 / 1024).toFixed(2) + "MB";
const exists = (p) => fs.access(p).then(() => true).catch(() => false);

async function optimizeModel(file) {
  const dest = path.join(MODEL_DIR, file);
  const backup = path.join(BACKUP_DIR, file);
  await fs.mkdir(BACKUP_DIR, { recursive: true });
  if (!(await exists(backup))) {
    await fs.copyFile(dest, backup);
  }
  const before = (await fs.stat(dest)).size;
  // Luôn tối ưu TỪ backup gốc; ghi đè ra dest.
  const bin = path.join(ROOT, "node_modules/.bin/gltf-transform");
  await run(bin, [
    "optimize",
    backup,
    dest,
    "--compress", "meshopt",
    "--texture-compress", "webp",
  ]);
  const after = (await fs.stat(dest)).size;
  console.log(`${file}: ${fmt(before)} -> ${fmt(after)} (-${Math.round((1 - after / before) * 100)}%)`);
}

try {
  const files = (await fs.readdir(MODEL_DIR)).filter((f) => /\.glb$/i.test(f)).sort();
  for (const f of files) {
    await optimizeModel(f);
  }
  console.log("Done.");
} catch (err) {
  console.error("optimize-models failed:", err);
  process.exit(1);
}
```

- [ ] **Step 3: Thêm npm script**

Trong `package.json` mục `scripts`, thêm:

```json
    "optimize:models": "node scripts/optimize-models.mjs",
```

- [ ] **Step 4: Chạy nén**

Run: `npm run optimize:models`
Expected: in ra `chuong-1.glb: 27.26MB -> ~3–8MB (-…%)` và tương tự `chuong-2.glb`. Nếu công cụ báo lỗi về meshopt, thử `--compress draco` (decoder DRACOLoader cũng có sẵn — khi đó Task 3 đổi sang `DRACOLoader` + `loader.setDRACOLoader(...)`, đường dẫn `node_modules/three/examples/jsm/libs/draco/`).

- [ ] **Step 5: Build + xem model**

Run: `npm run build`
Expected: pass. Chạy dev, mở `/co-vat` → 2 mô hình tải **nhanh hơn hẳn**, không đơ tab khi parse; xoay/zoom đúng hình khối, hoa văn còn nét. Network tab cho thấy `.glb` nhỏ hơn nhiều.

- [ ] **Step 6: Commit**

```bash
git add scripts/optimize-models.mjs package.json package-lock.json public/antiquity/
git commit -m "perf: nén model .glb (meshopt + texture webp), backup bản gốc model-originals/"
```

---

# GIAI ĐOẠN 3 — Ngân sách hiệu ứng CSS

## Task 8: Tắt các animation vô hạn ít giá trị

**Files:**
- Modify: `src/app/globals.css`

Giữ hiệu ứng **xuất hiện-khi-cuộn** (chạy 1 lần) và marquee. Tắt các vòng lặp `infinite` chạy mãi: `public-ambient-pan`, `public-gradient-flow`, logo/CTA "breathe", header "glint".

- [ ] **Step 1: Bỏ animation nền `public-page::before`**

Trong `.public-page::before`, xóa dòng:

```css
  animation: public-ambient-pan 18s ease-in-out infinite alternate;
```

- [ ] **Step 2: Gỡ animation chữ gradient (giữ gradient tĩnh)**

Trong `.public-gradient-text`, xóa dòng:

```css
  animation: public-gradient-flow 8s ease-in-out infinite alternate;
```

- [ ] **Step 3: Tắt các vòng "breathe"/"glint" trong khối `@media (prefers-reduced-motion: no-preference)`**

Xóa các quy tắc gán animation **vô hạn** sau (giữ lại `public-header-drop`, `public-line-draw`, `public-section-reveal`, `public-stagger-reveal`, `public-rise` vì chỉ chạy 1 lần):

```css
  .public-header::after { animation: public-header-glint 7s ease-in-out 1.2s infinite; }
  .public-logo-mark { animation: public-logo-breathe 4.8s ease-in-out infinite; }
  .public-header-cta,
  .public-cta { animation: public-cta-breathe 4.2s ease-in-out infinite; }
  .public-subpage-hero-image { animation: public-photo-breathe 12s ease-in-out infinite alternate; }
  .public-hero-inner .public-image-stage { animation: public-stage-float 7.2s ease-in-out 900ms infinite alternate; }
  .public-back-to-top[data-visible="true"] { animation: public-back-to-top-float 4.8s ease-in-out infinite; }
```

> Xóa **các quy tắc gán animation** ở trên (giữ lại các thuộc tính khác của chính selector đó nếu nằm ngoài khối media này — các selector này trong khối media chỉ có mỗi dòng animation, nên xóa cả khối). `@keyframes` tương ứng có thể để lại (không tốn gì nếu không dùng) hoặc xóa kèm.

- [ ] **Step 4: Build + đo lúc rảnh**

Run: `npm run build`
Expected: pass. Chạy dev, mở `/`, **không tương tác**. DevTools → Performance ghi 5s khi đứng yên: trước đây có nhiều "Recalculate Style/Composite" lặp lại do animation nền; sau khi sửa, hoạt động compositor lúc rảnh **giảm rõ rệt**. Hiệu ứng cuộn-hiện và marquee vẫn chạy.

- [ ] **Step 5: Commit**

```bash
git add src/app/globals.css
git commit -m "perf: tắt animation CSS vô hạn ít giá trị (ambient-pan, gradient-flow, breathe, glint)"
```

---

## Task 9: Giảm backdrop-filter blur & will-change

**Files:**
- Modify: `src/app/globals.css`

`backdrop-filter: blur(18px)` trên mọi `.public-panel` + `will-change: transform` (luôn-bật) rất tốn repaint/bộ nhớ layer.

- [ ] **Step 1: Giảm blur + bỏ will-change ở `.public-panel`**

```css
/* CŨ (trong .public-panel): */
  backdrop-filter: blur(18px) saturate(132%);
  -webkit-backdrop-filter: blur(18px) saturate(132%);
  will-change: transform;
/* MỚI: */
  backdrop-filter: blur(10px) saturate(120%);
  -webkit-backdrop-filter: blur(10px) saturate(120%);
```

- [ ] **Step 2: Giảm blur + bỏ will-change ở `.public-card`**

```css
/* CŨ (trong .public-card): */
  backdrop-filter: blur(12px) saturate(125%);
  -webkit-backdrop-filter: blur(12px) saturate(125%);
  will-change: transform;
/* MỚI: */
  backdrop-filter: blur(8px) saturate(118%);
  -webkit-backdrop-filter: blur(8px) saturate(118%);
```

- [ ] **Step 3: Build + đo cuộn**

Run: `npm run build`
Expected: pass. Chạy dev, cuộn trang `/di-tich` (nhiều card). DevTools → Rendering → bật "Paint flashing": vùng repaint khi cuộn ít/nhỏ hơn; FPS cuộn ổn định hơn. Giao diện vẫn có cảm giác kính mờ.

- [ ] **Step 4: Commit**

```bash
git add src/app/globals.css
git commit -m "perf: giảm backdrop-blur và bỏ will-change luôn-bật trên panel/card"
```

---

# GIAI ĐOẠN 4 — Cấu hình build & chia nhỏ bundle

## Task 10: Bật tối ưu ảnh trong next.config

**Files:**
- Modify: `next.config.ts`

- [ ] **Step 1: Đọc tài liệu Next 16 (bản đã sửa)**

Run: `ls node_modules/next/dist/docs/ 2>/dev/null; grep -rl "images" node_modules/next/dist/docs/ 2>/dev/null | head`
Đọc trang nói về cấu hình `images` để xác nhận khóa `formats`/`deviceSizes` đúng với bản này trước khi sửa.

- [ ] **Step 2: Cập nhật config**

```ts
import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  images: {
    formats: ["image/avif", "image/webp"],
    deviceSizes: [360, 640, 768, 1024, 1280, 1536, 1920],
    minimumCacheTTL: 2678400, // 31 ngày
  },
};

export default nextConfig;
```

> Nếu tài liệu bản này chỉ định khác (tên khóa/cấu trúc), theo tài liệu — mục tiêu: bật AVIF/WebP cho `next/image` và đặt `deviceSizes` hợp lý.

- [ ] **Step 3: Build + kiểm tra ảnh landing**

Run: `npm run build`
Expected: pass. Chạy dev/preview, mở `/` → Network tab cho thấy ảnh từ `<Image>` (vd `img("01.jpg")`) được phục vụ dạng AVIF/WebP, kích thước nhỏ theo viewport.

- [ ] **Step 4: Commit**

```bash
git add next.config.ts
git commit -m "perf: bật tối ưu ảnh AVIF/WebP + deviceSizes cho next/image"
```

---

## Task 11: Dynamic import các viewer nặng (three.js)

**Files:**
- Modify: `src/app/tour/chua-thai-lac/page.tsx`
- Modify: `src/app/co-vat/page.tsx`

Tách three.js khỏi bundle chính bằng `next/dynamic` (chỉ tải ở client, kèm fallback).

- [ ] **Step 1: Đọc tài liệu dynamic import của bản Next này**

Run: `grep -rl "next/dynamic\|dynamic" node_modules/next/dist/docs/ 2>/dev/null | head`
Xác nhận cú pháp `dynamic(() => import(...), { ssr: false })` còn đúng ở bản này.

- [ ] **Step 2: Tour page — dynamic import**

`src/app/tour/chua-thai-lac/page.tsx` thành:

```tsx
import type { Metadata } from "next";
import dynamic from "next/dynamic";

const VirtualTour = dynamic(() => import("@/app/components/VirtualTour"), {
  ssr: false,
  loading: () => (
    <div className="grid min-h-[100dvh] place-items-center bg-[#f5f1e6] text-[#4a3f35]">
      <p className="text-sm font-bold">Đang tải không gian 360°…</p>
    </div>
  ),
});

export const metadata: Metadata = {
  title: "VR360 Chùa Thái Lạc (Pháp Vân tự)",
  description:
    "Trải nghiệm tham quan thực tế ảo 360° Chùa Thái Lạc (Pháp Vân tự), di tích quốc gia tại Xã Như Quỳnh, tỉnh Hưng Yên.",
};

export default function ChuaThaiLacTourPage() {
  return <VirtualTour tourId="chua-thai-lac" />;
}
```

> Nếu bản Next này không cho `ssr: false` trong Server Component, tạo một wrapper client nhỏ (`"use client"`) bọc `dynamic(...)` và import wrapper vào page. Theo tài liệu ở Step 1.

- [ ] **Step 3: Co-vat page — dynamic import showcase**

Trong `src/app/co-vat/page.tsx`:

```tsx
// CŨ:
import { AntiquityShowcase } from "@/app/components/antiquity/AntiquityShowcase";
// MỚI:
import dynamic from "next/dynamic";
const AntiquityShowcase = dynamic(
  () => import("@/app/components/antiquity/AntiquityShowcase").then((m) => m.AntiquityShowcase),
  {
    ssr: false,
    loading: () => (
      <div className="mx-auto max-w-7xl px-4 py-16 text-center text-sm text-[var(--muted-foreground)] sm:px-6">
        Đang tải phòng trưng bày 3D…
      </div>
    ),
  },
);
```

(Phần JSX `<AntiquityShowcase items={antiquities} />` giữ nguyên.)

- [ ] **Step 4: Build + kiểm tra bundle**

Run: `npm run build`
Expected: pass; báo cáo build cho thấy route `/` và các trang tĩnh **không** còn gánh three.js trong chunk chính (three nằm ở chunk động của `/tour/...` và `/co-vat`). Mở các trang → vẫn hoạt động, có fallback khi tải.

- [ ] **Step 5: Commit**

```bash
git add src/app/tour/chua-thai-lac/page.tsx src/app/co-vat/page.tsx
git commit -m "perf: dynamic import viewer three.js (tách khỏi bundle chính)"
```

---

## Task 12: Nghiệm thu tổng thể

**Files:** không sửa code — chỉ đo và ghi nhận.

- [ ] **Step 1: Đếm ngữ cảnh WebGL ở trang chủ**

Mở `/`, DevTools Console: `document.querySelectorAll('canvas').length`
Expected: **0–1** (trước đây 3 lớp ở hero).

- [ ] **Step 2: Đo lúc rảnh**

Trang `/` đứng yên, Performance ghi 5s.
Expected: GPU/CPU gần như phẳng khi không tương tác; không còn rAF nền từ hero.

- [ ] **Step 3: Đo cuộn**

Cuộn `/` và `/di-tich`.
Expected: ~60fps, không tụt khung rõ rệt; quạt không rú.

- [ ] **Step 4: Đo tải tài nguyên**

Network (disable cache) mở `/tour/chua-thai-lac` và `/co-vat`.
Expected: panorama `.webp` ~0.3MB/ảnh; `.glb` nhỏ hơn nhiều lần so với 27–40MB.

- [ ] **Step 5: Lighthouse**

Chạy Lighthouse (Performance) cho `/` ở chế độ build production (`npm run build` + `npm run start`).
Expected: điểm Performance tăng so với trước; không lỗi giao diện.

- [ ] **Step 6: Ghi nhận kết quả** vào cuối file spec (`docs/superpowers/specs/2026-06-25-toi-uu-hieu-nang-design.md`), commit:

```bash
git add docs/superpowers/specs/2026-06-25-toi-uu-hieu-nang-design.md
git commit -m "docs: ghi nhận kết quả nghiệm thu tối ưu hiệu năng"
```

---

## Tự rà soát (đã thực hiện khi viết kế hoạch)

- **Phủ spec:** GĐ1 (hero + gate + antiquity) ✓ Task 1–3; GĐ2 (nén ảnh ✓T4–5, LRU ✓T6, nén model ✓T7); GĐ3 (animation ✓T8, blur/will-change ✓T9); GĐ4 (next.config ✓T10, dynamic import ✓T11); nghiệm thu ✓T12.
- **Không placeholder:** mọi step có code/lệnh cụ thể.
- **Nhất quán tên:** `createRenderGate` (T1) dùng đúng ở T2/T3; `setPinnedPanoramas`/`touchPanoramaCache`/`evictPanoramaTextures` (T6) nhất quán; `imageForFile` (T5) khớp khóa LQIP `.webp` (T4).
- **Rủi ro đã chặn:** LRU không dispose ảnh đang ghim; nén ảnh/model luôn từ backup gốc (chạy lại an toàn); đọc tài liệu Next 16 trước khi sửa config/dynamic.