create-wakii-stack 0.0.0-stage → 0.1.1

package/stack-template/app/ui-kit/src/templates/experience/index.stories.tsx

@@ -0,0 +1,51 @@
+// Templates/Cinematic Experience — composition (owner @v2, contract EXPERIENCE-DESIGN.md).
+// Ghép Hero + 5 chương (team điền theo contract từng file) + Anchor side-nav làm
+// progress + mood provider: `--mood-progress` (0..1) set trên wrapper → chapters
+// đọc qua CSS var; nền crossfade do CrossfadeBackdrop (lib/scroll-mood) lo.
+// Stubs render null lúc skeleton — trang đầy dần khi team điền, không đụng file nhau.
+import type { CSSProperties } from 'react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import Hero from './chapters/hero';
+import Ch1DeepFocus from './chapters/ch1-deep-focus';
+import Ch2LivingDocs from './chapters/ch2-living-docs';
+import Ch3TeamVelocity from './chapters/ch3-team-velocity';
+import Ch4ShipYourApp from './chapters/ch4-ship-your-app';
+import Ch5Future from './chapters/ch5-future';
+import NavFooter from './chapters/nav-footer';
+import { CrossfadeBackdrop, usePageProgress } from './lib/scroll-mood.js';
+
+const meta = { title: 'Templates/Cinematic Experience', tags: ['autodocs'] } satisfies Meta;
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+function ExperiencePage() {
+  const pct = usePageProgress();
+  return (
+    <div className="relative" style={{ '--mood-progress': pct } as CSSProperties}>
+      <CrossfadeBackdrop pct={pct} />
+
+      {/* Side-nav + footer: nguồn duy nhất là chapters/nav-footer (worker D) — placeholder
+       * Anchor ở đây đã GỠ để hết chồng lớp 'CHƯƠNG 0X' (bugfix R10 2026-10-18). */}
+
+      <Hero />
+      <Ch1DeepFocus />
+      <Ch2LivingDocs />
+      <Ch3TeamVelocity />
+      <Ch4ShipYourApp />
+      <Ch5Future />
+      <NavFooter />
+    </div>
+  );
+}
+
+/** Full experience — hero starfield + 5 chương theo mood bands (EXPERIENCE-DESIGN.md). */
+export const Experience: Story = {
+  name: 'Experience — 5 chương + hero starfield + Anchor progress',
+  render: () => <ExperiencePage />,
+};
+
+/** HeroOnly — starfield + trailer Modal, gọn để soi canvas + reduced-motion. */
+export const HeroOnly: Story = {
+  name: 'Hero only — starfield 3 lớp + mouse-parallax + trailer Modal',
+  render: () => <Hero />,
+};

package/stack-template/app/ui-kit/src/templates/experience/lib/ChapterShell.tsx

@@ -0,0 +1,84 @@
+// ChapterShell — khung chương SF-3 theo EXPERIENCE-DESIGN.md v1.0: label mono
+// 'CHƯƠNG 0X' 11px/700 tracking 2.64px + title ALL-CAPS ~29px/300 leading-snug
+// tracking 0.02em + copy punchy 2 dòng (body 12px/400 tracking 0.3 leading 1.7)
+// + parallax nền gần-fixed speed 0.08 / strength 280 (§4 — layer vignette trôi,
+// KHÔNG đục: màu mood do MoodBackdrop crossfade page-wide lo, §2 — cùng kiến
+// trúc mood-engine; ch1 chú thích "KHÔNG tự đặt nền đặc"). Section contract §6:
+// relative min-h-screen + id + data-mood. Theme-independent qua white-alpha cố
+// định (§6 — KHÔNG token flip); band sáng (mood 'future') dùng tone="light" →
+// ink theme-flip đúng bảng ink §2.
+import type { ReactNode } from 'react';
+import { Parallax } from '../../../index';
+
+/** Ink theo tone — dark: white-alpha cố định trên nền tối tự chủ; light: token
+ * theme-flip trên band sáng (contract §2 mood 'future' ink --ink). */
+const TONE = {
+  dark: { label: 'text-white/85', title: 'text-white', copy: 'text-white/92' },
+  light: { label: 'text-ink3', title: 'text-ink', copy: 'text-ink2' },
+} as const;
+
+export interface ChapterShellProps {
+  /** id anchor của chương: ch1..ch5 (SideNav scroll-spy trỏ về đây). */
+  id: string;
+  /** Số chương hiển thị trên label mono: '01'..'05'. */
+  chapter: string;
+  /** data-mood cho ranh giới crossfade (focus/docs/velocity/ship/future…). */
+  mood: string;
+  /** Title chương — data gốc; ALL-CAPS là CSS uppercase (REF-SPEC H2 ~29px/300). */
+  title: string;
+  /** Copy punchy ~2 dòng dưới title. */
+  copy: string;
+  /** Ink của chương: 'dark' (mặc định — nền tối) | 'light' (band sáng mood future). */
+  tone?: keyof typeof TONE;
+  /** Nội dung riêng của chương (parallax ảnh, cards, counter…). */
+  children?: ReactNode;
+  className?: string;
+}
+
+export function ChapterShell({
+  id,
+  chapter,
+  mood,
+  title,
+  copy,
+  tone = 'dark',
+  children,
+  className,
+}: ChapterShellProps) {
+  const ink = TONE[tone];
+  return (
+    <section
+      id={id}
+      data-mood={mood}
+      data-tone={tone}
+      className={`relative min-h-screen overflow-hidden ${className ?? ''}`}
+    >
+      {/* Nền chương gần-fixed (§4: chapter BG parallax speed 0.08 / strength 280) —
+       * vignette alpha LOW để crossfade MoodBackdrop phía sau vẫn lộ trọn. Layer cao
+       * hơn section (inset âm) để trôi không hở mép; overflow-hidden của section cắt. */}
+      <Parallax speed={0.08} strength={280} className="absolute -inset-y-16 inset-x-0">
+        <div
+          data-chapter-bg=""
+          aria-hidden="true"
+          className="h-full w-full bg-[linear-gradient(180deg,transparent_40%,var(--scrim-2)_100%)]"
+        />
+      </Parallax>
+
+      {/* Content rail §3: max-w-5xl px-10 (max-md px-6) · padding chương py-16. */}
+      <div className="relative mx-auto flex min-h-screen w-full max-w-5xl flex-col justify-center px-10 py-16 max-md:px-6">
+        {/* Label mono — 11px/700 UPPERCASE tracking 2.64px (§1); nhạt white/85
+         * (REF-SPEC rgb(220,225,236) trên nền tối). */}
+        <p className={`m-0 font-mono text-[11px] font-bold uppercase tracking-[2.64px] ${ink.label}`}>
+          Chương {chapter}
+        </p>
+        {/* Title — 29px/300 LIGHT leading-snug tracking 0.02em (§1 H2 chapter). */}
+        <h2 className={`m-0 mt-3 text-[29px] font-light uppercase leading-snug tracking-[0.02em] ${ink.title}`}>
+          {title}
+        </h2>
+        {/* Copy punchy 2 dòng — body 12px/400 tracking 0.3px leading 1.7 (§1). */}
+        <p className={`mb-0 mt-4 max-w-prose text-[12px] leading-[1.7] tracking-[0.3px] ${ink.copy}`}>{copy}</p>
+        {children}
+      </div>
+    </section>
+  );
+}

package/stack-template/app/ui-kit/src/templates/experience/lib/SideNav.tsx

@@ -0,0 +1,173 @@
+// SideNav — single-source side-nav cinematic experience (SF-3).
+// REDESIGN theo PO 2026-10-19 — rail tối giản cao cấp kiểu glass (thay look list
+// thường của Anchor — Anchor không express được glass/pill/progress nên rail tự
+// render, giữ nguyên triết lý: 1 nguồn dữ liệu EXPERIENCE_CHAPTERS, CHỈ 1 scroll-spy,
+// aria-current + keyboard qua <a> thật):
+//   1) rail dọc trái GLASS: canvas/70 + backdrop-blur + hairline phải (không hộp card)
+//   2) item: dot tròn nhỏ + mono số + label ngắn ALL-CAPS tracking 2.64; ACTIVE = text
+//      accent + dot accent + translate-x nhẹ (transition 200ms — UI micro §4)
+//   3) hover: label/dot sáng dần — KHÔNG đổi bg
+//   4) mobile <768: dot-nav đáy cố định — 5 dot, active thành pill accent + label ngắn
+//   5) scroll progress 2px chạy dọc rail theo % trang (accent, rAF qua usePageProgress)
+// Ink = THEME token (ink3/ink2) — glass là bề mặt theme (canvas/70 + blur), KHÔNG
+// theo mood chương: token flip tự ăn 2 theme, trắng-alpha theo mood sẽ mất contrast
+// trên glass sáng. a11y: nav landmark duy nhất, aria-current 2 variant, focus ring,
+// no-underline (preflight tắt), reduced-motion → nhảy tức thì.
+import { useEffect, useState } from 'react';
+import type { JSX, MouseEvent as ReactMouseEvent } from 'react';
+import { useMediaQuery } from '../../../hooks/useMediaQuery.js';
+import { usePageProgress } from './scroll-mood.js';
+
+export interface ExperienceChapter {
+  id: string;
+  num: string;
+  /** Title đầy đủ (footer nav lặp dùng). */
+  title: string;
+  /** Label ngắn cho rail/dot-nav (PO: label ngắn ALL-CAPS — uppercase là CSS). */
+  short: string;
+}
+
+/** 5 chương experience — nguồn danh sách dùng chung (nav + footer lặp + compose).
+ * (data của chính nav — precedent DRAG_MIME drag-drop, nên ở cùng file.) */
+// eslint-disable-next-line react-refresh/only-export-components
+export const EXPERIENCE_CHAPTERS: ExperienceChapter[] = [
+  { id: 'ch1', num: '01', title: 'Deep focus', short: 'Focus' },
+  { id: 'ch2', num: '02', title: 'Living docs', short: 'Docs' },
+  { id: 'ch3', num: '03', title: 'Team velocity', short: 'Velocity' },
+  { id: 'ch4', num: '04', title: 'Ship your app', short: 'Ship' },
+  { id: 'ch5', num: '05', title: 'Future', short: 'Future' },
+];
+
+/** Nav chrome experience — desktop glass rail trái + mobile dot-nav đáy (1 landmark). */
+export function SideNav(): JSX.Element {
+  const [activeId, setActiveId] = useState<string | undefined>(undefined);
+  const reduced = useMediaQuery('(prefers-reduced-motion: reduce)');
+  const pct = usePageProgress();
+
+  useEffect(() => {
+    let raf = 0;
+    const sync = () => {
+      raf = 0;
+      // Section cuối có đỉnh chạm mép viewport → active (thuật toán offsetTop 0 —
+      // cùng语义 Anchor).
+      let current: string | undefined;
+      for (const c of EXPERIENCE_CHAPTERS) {
+        const el = document.getElementById(c.id);
+        if (el && el.getBoundingClientRect().top <= 1) current = c.id;
+      }
+      setActiveId(current);
+    };
+    const schedule = () => {
+      if (!raf) raf = requestAnimationFrame(sync);
+    };
+    sync();
+    document.addEventListener('scroll', schedule, true);
+    window.addEventListener('resize', schedule);
+    return () => {
+      document.removeEventListener('scroll', schedule, true);
+      window.removeEventListener('resize', schedule);
+      if (raf) cancelAnimationFrame(raf);
+    };
+  }, []);
+
+  const go = (e: ReactMouseEvent<HTMLAnchorElement>, id: string) => {
+    e.preventDefault();
+    document
+      .getElementById(id)
+      ?.scrollIntoView({ behavior: reduced ? 'auto' : 'smooth', block: 'start' });
+  };
+
+  return (
+    <nav aria-label="Chương">
+      {/* DESKTOP (md+) — glass rail trái: canvas/70 + blur + hairline phải */}
+      <div className="pointer-events-none fixed inset-y-0 left-0 z-[var(--z-popover)] hidden md:block">
+        <div
+          className="pointer-events-auto relative flex h-full w-40 flex-col justify-center gap-1 border-r border-line py-6 pl-6 pr-3 backdrop-blur-md"
+          style={{ background: 'color-mix(in srgb, var(--c-canvas) 70%, transparent)' }}
+        >
+          {/* Scroll progress 2px chạy dọc rail theo % trang */}
+          <div
+            data-nav-progress=""
+            aria-hidden="true"
+            className="absolute left-0 top-0 w-0.5 bg-accent"
+            style={{ height: `${Math.round(pct * 100)}%` }}
+          />
+          {EXPERIENCE_CHAPTERS.map((c) => {
+            const isActive = activeId === c.id;
+            return (
+              <a
+                key={c.id}
+                href={`#${c.id}`}
+                aria-current={isActive || undefined}
+                onClick={(e) => go(e, c.id)}
+                className={`group flex items-center gap-2.5 rounded-lg py-1.5 no-underline outline-none transition-transform duration-200 focus-visible:ring-2 focus-visible:ring-accent/40 ${
+                  isActive ? 'translate-x-1' : 'translate-x-0'
+                }`}
+              >
+                <span
+                  aria-hidden="true"
+                  className={`size-1.5 shrink-0 rounded-full transition-all duration-200 ${
+                    isActive ? 'scale-100 bg-accent' : 'scale-75 bg-ink4 group-hover:scale-90'
+                  }`}
+                />
+                <span
+                  aria-hidden="true"
+                  className={`font-mono text-[11px] font-bold tracking-[2.64px] transition-colors duration-200 ${
+                    isActive ? 'text-accent' : 'text-ink3'
+                  }`}
+                >
+                  {c.num}
+                </span>
+                <span
+                  className={`text-[11px] font-bold uppercase tracking-[2.64px] transition-colors duration-200 ${
+                    isActive ? 'text-accent' : 'text-ink2 group-hover:text-ink'
+                  }`}
+                >
+                  {c.short}
+                </span>
+              </a>
+            );
+          })}
+        </div>
+      </div>
+
+      {/* MOBILE (<768) — dot-nav đáy: 5 dot, active mở thành pill accent + label ngắn */}
+      <div className="pointer-events-none fixed inset-x-0 bottom-0 z-[var(--z-popover)] md:hidden">
+        <div
+          className="pointer-events-auto flex h-14 items-center justify-center gap-4 border-t border-line px-4 backdrop-blur-md"
+          style={{ background: 'color-mix(in srgb, var(--c-canvas) 70%, transparent)' }}
+        >
+          {EXPERIENCE_CHAPTERS.map((c) => {
+            const isActive = activeId === c.id;
+            return (
+              <a
+                key={c.id}
+                href={`#${c.id}`}
+                aria-current={isActive || undefined}
+                onClick={(e) => go(e, c.id)}
+                aria-label={c.title}
+                className={`flex items-center gap-1.5 rounded-pill no-underline outline-none transition-all duration-200 focus-visible:ring-2 focus-visible:ring-accent/40 ${
+                  isActive ? 'bg-accent/10 px-3 py-1.5' : 'p-1.5'
+                }`}
+              >
+                <span
+                  aria-hidden="true"
+                  className={`size-1.5 rounded-full transition-all duration-200 ${
+                    isActive ? 'scale-100 bg-accent' : 'scale-75 bg-ink4 group-hover:scale-90'
+                  }`}
+                />
+                <span
+                  className={`font-mono text-[11px] font-bold uppercase tracking-[2.64px] text-accent ${
+                    isActive ? 'inline' : 'hidden'
+                  }`}
+                >
+                  {c.short}
+                </span>
+              </a>
+            );
+          })}
+        </div>
+      </div>
+    </nav>
+  );
+}

package/stack-template/app/ui-kit/src/templates/experience/lib/chapter-shell.test.tsx

@@ -0,0 +1,266 @@
+// ChapterShell + SideNav tests (SF-3) — contract EXPERIENCE-DESIGN v1.0: section
+// §6 (id/data-mood/min-h-screen, TRONG SUỐT — MoodBackdrop lo màu), typography §1
+// (label mono 11px/700 tracking 2.64 · title 29px/300 leading-snug tracking 0.02em
+// · copy 12px leading 1.7 tracking 0.3), parallax §4 (0.08/280 vignette alpha),
+// nav single-source single-landmark scroll-spy aria-current 5 mục — glass rail
+// (PO redesign 2026-10-19): canvas/70 + blur + hairline phải, dot-nav mobile,
+// progress 2px, hover không đổi bg, active accent + translate-x.
+import { act, cleanup, fireEvent, render, screen } from '@testing-library/react';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { ChapterShell } from './ChapterShell.js';
+import { EXPERIENCE_CHAPTERS, SideNav } from './SideNav.js';
+
+const originalMatchMedia = window.matchMedia;
+// jsdom thiếu matchMedia — pattern parallax.test (useMediaQuery cần)
+window.matchMedia = vi.fn(() => ({
+  matches: false,
+  media: '',
+  onchange: null,
+  addListener: vi.fn(),
+  removeListener: vi.fn(),
+  addEventListener: vi.fn(),
+  removeEventListener: vi.fn(),
+  dispatchEvent: vi.fn(),
+})) as unknown as typeof window.matchMedia;
+
+afterEach(() => {
+  cleanup();
+  document.body.innerHTML = ''; // mountSection gắn body — dọn để id không trùng giữa test
+  vi.restoreAllMocks();
+  window.matchMedia = originalMatchMedia;
+});
+
+describe('ChapterShell', () => {
+  it('section §6: id + data-mood + relative min-h-screen overflow-hidden, KHÔNG nền đục (MoodBackdrop lộ)', () => {
+    const { container } = render(
+      <ChapterShell id="ch2" chapter="02" mood="docs" title="LIVING DOCS" copy="Tài liệu sống theo task." />,
+    );
+    const section = container.querySelector('section')!;
+    expect(section).toHaveAttribute('id', 'ch2');
+    expect(section).toHaveAttribute('data-mood', 'docs');
+    expect(section).toHaveAttribute('data-tone', 'dark'); // mặc định — metadata cho SideNav ink
+    expect(section.className).toContain('relative');
+    expect(section.className).toContain('min-h-screen');
+    expect(section.className).toContain('overflow-hidden');
+    // Kiến trúc mood SF-1: section trong suốt — KHÔNG tự đặt nền đặc (bg-black/bg-[...])
+    expect(section.className).not.toContain('bg-black');
+    expect(section.className).not.toContain('bg-[');
+  });
+
+  it('typography §1: label mono 11px/700 tracking 2.64 + title 29px/300 leading-snug tracking 0.02em + copy 12px leading 1.7 tracking 0.3', () => {
+    render(
+      <ChapterShell id="ch3" chapter="03" mood="velocity" title="Team Velocity" copy="Nhịp_team 24 giờ một vòng." />,
+    );
+    const label = screen.getByText(/Chương 03/);
+    expect(label.className).toContain('font-mono');
+    expect(label.className).toContain('text-[11px]');
+    expect(label.className).toContain('font-bold');
+    expect(label.className).toContain('uppercase');
+    expect(label.className).toContain('tracking-[2.64px]');
+    // REF-SPEC: label nhạt rgb(220,225,236) ≈ white/85 (không white/60 mờ)
+    expect(label.className).toContain('text-white/85');
+
+    const title = screen.getByRole('heading', { level: 2 });
+    expect(title.textContent).toBe('Team Velocity'); // data gốc — ALL-CAPS là CSS
+    expect(title.className).toContain('uppercase');
+    expect(title.className).toContain('text-[29px]');
+    expect(title.className).toContain('font-light');
+    expect(title.className).toContain('leading-snug');
+    expect(title.className).toContain('tracking-[0.02em]');
+    expect(title.className).toContain('text-white'); // ink heading §2 focus
+
+    const copy = screen.getByText(/Nhịp_team/);
+    expect(copy.className).toContain('text-[12px]');
+    expect(copy.className).toContain('leading-[1.7]');
+    expect(copy.className).toContain('tracking-[0.3px]');
+    expect(copy.className).toContain('text-white/92'); // ink body §2
+  });
+
+  it('tone light (band sáng mood future) → ink theme-flip đúng bảng ink §2', () => {
+    render(<ChapterShell id="ch5" chapter="05" mood="future" title="Future" copy="c" tone="light" />);
+    expect(screen.getByRole('heading', { level: 2 }).className).toContain('text-ink');
+    expect(screen.getByText(/Chương 05/).className).toContain('text-ink3');
+    expect(screen.getByText('c').className).toContain('text-ink2');
+    expect(document.getElementById('ch5')).toHaveAttribute('data-tone', 'light');
+  });
+
+  it('parallax §4: layer data-chapter-bg trong Parallax speed 0.08/strength 280 — vignette alpha, không gradient mood đục', () => {
+    const { container } = render(<ChapterShell id="ch4" chapter="04" mood="ship" title="SHIP" copy="c" />);
+    const bg = container.querySelector('[data-chapter-bg]') as HTMLElement;
+    expect(bg).not.toBeNull();
+    // vignette alpha LOW qua scrim token — crossfade mood phía sau vẫn lộ
+    expect(bg.className).toContain('var(--scrim-2)');
+    expect(bg.getAttribute('aria-hidden')).toBe('true');
+  });
+
+  it('content rail §3: max-w-5xl px-10 (max-md px-6) py-16', () => {
+    const { container } = render(<ChapterShell id="ch1" chapter="01" mood="focus" title="F" copy="c" />);
+    const rail = container.querySelector('section > div.relative')!;
+    expect(rail.className).toContain('max-w-5xl');
+    expect(rail.className).toContain('px-10');
+    expect(rail.className).toContain('max-md:px-6');
+    expect(rail.className).toContain('py-16');
+  });
+
+  it('children render bên trong shell (nội dung riêng chương)', () => {
+    render(
+      <ChapterShell id="ch5" chapter="05" mood="future" title="FUTURE" copy="c">
+        <div data-testid="chapter-content">content</div>
+      </ChapterShell>,
+    );
+    expect(screen.getByTestId('chapter-content')).toBeInTheDocument();
+  });
+});
+
+describe('SideNav (single-source SF-3 — glass rail PO redesign)', () => {
+  /** Section stub gắn body với top viewport điều khiển được (pattern anchor.test). */
+  function mountSection(id: string, tops: Map<string, number>) {
+    const el = document.createElement('div');
+    el.id = id;
+    document.body.appendChild(el);
+    vi.spyOn(el, 'getBoundingClientRect').mockImplementation(
+      () =>
+        ({
+          top: tops.get(id) ?? 0,
+          bottom: (tops.get(id) ?? 0) + 100,
+          left: 0,
+          right: 100,
+          width: 100,
+          height: 100,
+          x: 0,
+          y: tops.get(id) ?? 0,
+          toJSON: () => ({}),
+        }) as DOMRect,
+    );
+    return el;
+  }
+
+  it('1 nav landmark duy nhất; 5 chương × 2 variant (rail md+ + dot-nav <768); short label single-source', () => {
+    const { container } = render(<SideNav />);
+    const navs = container.querySelectorAll('nav');
+    expect(navs.length).toBe(1);
+    const nav = navs[0]!;
+    for (const c of EXPERIENCE_CHAPTERS) {
+      // rail desktop + dot-nav mobile — cùng nguồn EXPERIENCE_CHAPTERS
+      expect(nav.querySelectorAll(`a[href="#${c.id}"]`).length).toBe(2);
+    }
+    expect(nav.textContent).toContain('Velocity'); // short label — không title dài
+    expect(nav.textContent).not.toContain('Team velocity');
+  });
+
+  it('glass rail: canvas/70 + backdrop-blur + hairline phải + progress 2px; dot-nav md:hidden', () => {
+    const { container } = render(<SideNav />);
+    const glass = Array.from(container.querySelectorAll('div')).filter((d) =>
+      d.className.includes('backdrop-blur-md'),
+    );
+    expect(glass.length).toBe(2); // rail + dot-nav bar
+    expect(glass[0]!.className).toContain('border-r'); // hairline phải
+    expect(glass[0]!.className).toContain('w-40');
+    expect(glass[1]!.className).toContain('border-t');
+    expect(container.querySelector('[data-nav-progress]')).not.toBeNull();
+    // progress: thanh accent 2px (w-0.5), height % trang
+    const progress = container.querySelector('[data-nav-progress]') as HTMLElement;
+    expect(progress.className).toContain('bg-accent');
+    expect(progress.style.height).toBe('0%'); // jsdom chưa cuộn
+    // dot-nav bar ẩn từ md (md:hidden ở wrapper ngoài bar)
+    expect(glass[1]!.parentElement!.className).toContain('md:hidden');
+  });
+
+  /** Fire scroll + flush rAF (spy throttle rAF — act không tự flush frame).
+   * Dispatch trên document: spy listen capture-phase document (scroll thật
+   * target document); event dispatch thẳng lên window KHÔNG qua capture đó. */
+  async function fireScroll() {
+    await act(async () => {
+      document.dispatchEvent(new Event('scroll'));
+      await new Promise((r) => setTimeout(r, 25));
+    });
+  }
+
+  it('item: dot tròn + mono số 11px tracking 2.64 + label ALL-CAPS tracking 2.64; active = accent + translate-x, hover không đổi bg', async () => {
+    const tops = new Map<string, number>(EXPERIENCE_CHAPTERS.map((c) => [c.id, 400]));
+    for (const c of EXPERIENCE_CHAPTERS) mountSection(c.id, tops);
+    const { container } = render(<SideNav />);
+    tops.set('ch2', 0);
+    await fireScroll();
+
+    const railLabels = container.querySelectorAll('a[href="#ch2"]');
+    const railLink = railLabels[0]!; // rail desktop trước dot-nav (thứ tự DOM)
+    expect(railLink.className).toContain('translate-x-1'); // active dịch nhẹ
+    expect(railLink.getAttribute('aria-current')).toBe('true');
+    // active: label accent + dot accent
+    const label = railLink.lastElementChild as HTMLElement;
+    expect(label.className).toContain('uppercase');
+    expect(label.className).toContain('tracking-[2.64px]');
+    expect(label.className).toContain('text-accent');
+    expect(railLink.querySelector('span')!.className).toContain('bg-accent');
+    // inactive: KHÔNG đổi bg hộp (chỉ màu chữ/dot) — không class hover:bg-*
+    const inactiveLink = container.querySelector('a[href="#ch1"]')!;
+    expect(inactiveLink.className).not.toMatch(/hover:bg/);
+    expect(inactiveLink.className).not.toContain('translate-x-1');
+  });
+
+  it('scroll-spy đúng 5 mục: aria-current chuyển theo section chạm offsetTop 0 (cả 2 variant)', async () => {
+    const tops = new Map<string, number>(
+      EXPERIENCE_CHAPTERS.map((c, i) => [c.id, (i + 1) * 400]),
+    );
+    for (const c of EXPERIENCE_CHAPTERS) mountSection(c.id, tops);
+    const { getAllByText } = render(<SideNav />);
+    expect(document.querySelector('[aria-current]')).toBeNull();
+
+    const links = (title: string) => getAllByText(title).map((el) => el.closest('a')!);
+
+    tops.set('ch1', 0); // cuộn tới chương 01
+    await fireScroll();
+    for (const a of links('Focus')) expect(a).toHaveAttribute('aria-current', 'true');
+
+    tops.set('ch3', 0); // cuộn tiếp sang chương 03
+    await fireScroll();
+    for (const a of links('Focus')) expect(a).not.toHaveAttribute('aria-current');
+    for (const a of links('Velocity')) expect(a).toHaveAttribute('aria-current', 'true');
+
+    tops.set('ch5', 0); // cuối trang — chương 05
+    await fireScroll();
+    for (const a of links('Future')) expect(a).toHaveAttribute('aria-current', 'true');
+  });
+
+  it('ink rail = theme token (glass là bề mặt theme): inactive ink2/ink3 + hover ink, active accent — không phụ thuộc mood chương', async () => {
+    const tops = new Map<string, number>(EXPERIENCE_CHAPTERS.map((c) => [c.id, 400]));
+    for (const c of EXPERIENCE_CHAPTERS) {
+      mountSection(c.id, tops);
+      if (c.id === 'ch5') document.getElementById(c.id)!.dataset.tone = 'light'; // mood đổi — rail KHÔNG đổi
+    }
+    const { getAllByText } = render(<SideNav />);
+
+    tops.set('ch1', 0);
+    await fireScroll();
+    // ch1 active → label nó accent; item inactive dùng theme token
+    expect(getAllByText('Focus')[0]!.className).toContain('text-accent');
+    const velocityLabel = getAllByText('Velocity')[0]!; // [0] rail — [1] dot-nav
+    expect(velocityLabel.className).toContain('text-ink2');
+    expect(velocityLabel.className).toContain('group-hover:text-ink');
+    expect(velocityLabel.closest('a')!.className).toContain('no-underline'); // preflight tắt
+
+    tops.set('ch5', 0); // band sáng — rail KHÔNG flip theo mood (glass theo theme)
+    await fireScroll();
+    const velocityAfter = getAllByText('Velocity')[0]!;
+    expect(velocityAfter.className).toContain('text-ink2');
+    expect(velocityAfter.className).not.toContain('text-accent');
+  });
+
+  it('click → preventDefault + scrollIntoView smooth tới section (reduced-motion → auto)', () => {
+    const tops = new Map<string, number>(EXPERIENCE_CHAPTERS.map((c) => [c.id, 400]));
+    const el = mountSection('ch2', tops);
+    // jsdom không define scrollIntoView — gắn mock thẳng lên element
+    const scrollIntoView = vi.fn();
+    (el as HTMLElement & { scrollIntoView: unknown }).scrollIntoView = scrollIntoView;
+    const { getAllByText } = render(<SideNav />);
+
+    let docPrevented: boolean | undefined;
+    document.addEventListener('click', (e) => {
+      docPrevented = e.defaultPrevented;
+    });
+    fireEvent.click(getAllByText('Docs')[0]!);
+    expect(docPrevented).toBe(true);
+    expect(scrollIntoView).toHaveBeenCalledWith({ behavior: 'smooth', block: 'start' });
+  });
+});