┌─────────────────────────────────────────────────────────────┐
│ DEVELOPER MACHINE                                           │
│                                                             │
│  content/**/*.md ──┐                                        │
│  css/style.css ────┤   node scripts/workflow.js             │
│  js/*.js ──────────┤   ├─ build-toc.js    → toc.json       │
│                    ├──→├─ build-static.js → public/*.html   │
│                    │   ├─ CleanCSS        → app.min.css     │
│                    │   ├─ esbuild+terser  → app.min.js      │
│                    │   └─ mermaid SVGs    → mermaid-svg/*   │
│                    │                                        │
│                    └──→ public/  (complete static site)     │
│                             │                               │
│                      git push main                          │
└─────────────────────┬───────────────────────────────────────┘
                      │
                      ▼
┌─────────────────────────────────────────────────────────────┐
│ GITHUB  →  main branch                                      │
└─────────────────────┬───────────────────────────────────────┘
                      │ webhook
                      ▼
┌─────────────────────────────────────────────────────────────┐
│ VERCEL                                                      │
│  ├─ Deploys static files (no build step, "build": "exit 0")│
│  ├─ Edge CDN (global)                                       │
│  ├─ Cache: CSS/JS immutable 1y, HTML 1h+SWR, images 1y     │
│  └─ SSL/TLS automatic                                       │
└─────────────────────┬───────────────────────────────────────┘
                      │
                      ▼
┌─────────────────────────────────────────────────────────────┐
│ NAMECHEAP DNS                                               │
│  serard.dev CNAME → cname.vercel-dns.com                    │
│  (Vercel manages SSL certificate for custom domain)         │
└─────────────────────────────────────────────────────────────┘
                      │
                      ▼
                  🌐 https://serard.dev

┌─────────────────────────────────────────────────┐
│ <header id="terminal-bar">  38px fixe, z:100    │
│  [dots/btns OS] [titre] [theme] [search] [menu] │
├────────────┬────────────────────────────────────┤
│ <nav>      │ <main id="content">                │
│ #sidebar   │   <article id="markdown-output">   │
│ 280px      │   flex:1, overflow-y:auto          │
│ resizable  │   padding: 32px 48px               │
│            │   #code-watermark (parallax)       │
├────────────┤                                    │
│ footer:    │                                    │
│ CTA, links │                                    │
└────────────┴────────────────────────────────────┘

--font-mono: 'JetBrains Mono', 'Fira Code', 'Cascadia Code', 'Consolas'
--font-sans: system fonts fallback
--sidebar-width: 280px
--topbar-height: 38px
--transition-speed: 0.25s
--transition-fast: 0.15s
--transition-slow: 0.3s

html.theme-switching,
html.theme-switching body,
html.theme-switching #terminal-bar,
html.theme-switching #sidebar,
html.theme-switching #content,
html.theme-switching #markdown-output,
html.theme-switching .toc-item,
html.theme-switching .theme-btn,
html.theme-switching pre,
html.theme-switching code {
  transition: background-color 0.2s ease, color 0.2s ease;
}

#markdown-output h1 { color: var(--accent-green); }
#markdown-output h1::before { content: '# '; color: var(--text-muted); }
#markdown-output h2 { color: var(--accent-blue); }
#markdown-output h2::before { content: '## '; }
#markdown-output h3 { color: var(--accent-purple); }
#markdown-output h3::before { content: '### '; }

[data-color-mode="light"] #markdown-output pre { background: #f6f8fa; }
[data-color-mode="light"] #markdown-output code { color: #0550ae; }

.toc-items {
  overflow: hidden;
  display: grid;
  grid-template-rows: 0fr;          /* closed */
  transition: grid-template-rows 0.3s ease;
}
.toc-items > div { min-height: 0; } /* allows shrink to 0 */
.toc-items.open {
  grid-template-rows: 1fr;          /* open */
}

#sidebar { position: fixed; left: -100%; transition: left 0.3s ease; }
#sidebar.open { left: 0; }
#sidebar-backdrop { display: block; opacity: 0; transition: opacity 0.3s; }
#sidebar-backdrop.visible { opacity: 1; }
#content { padding: 24px 16px; }
.os-selector, #btn-color-theme { display: none !important; }

html { font-size: 14px; }
#content { padding: 16px 12px; }

@media print {
  #sidebar, #terminal-bar, #sidebar-backdrop, .search-modal {
    display: none !important;
  }
  body {
    background: white; color: black;
    overflow: visible; height: auto;
  }
  #markdown-output h1::before,
  #markdown-output h2::before,
  #markdown-output h3::before {
    display: none; /* remove # ## ### */
  }
}

::-webkit-scrollbar { width: 12px; }
::-webkit-scrollbar-track { background: var(--bg-secondary); }
::-webkit-scrollbar-thumb {
  background: var(--text-muted);
  border-radius: 6px;
  border: 3px solid var(--bg-secondary); /* visual margin */
}
::-webkit-scrollbar-thumb:hover { background: var(--text-secondary); }

PHASE 1 — Inline <head> script (BEFORE render)
  → localStorage → setAttribute data-color-mode/os-style/color-theme
  → localStorage → style.fontSize (font-size preference)
  → CSS :root[data-color-mode="..."] active immediately
  → No transitions at this point (no .theme-switching class)

PHASE 2 — ThemeSwitcher.init() (synchronous)
  → applyColorMode + applyColorTheme + applyOS + applyAccentColor + applyFontSize
  → All applied instantly, no animation

PHASE 3 — User clicks theme toggle later
  → withThemeTransition() adds .theme-switching class
  → Theme change applied (setAttribute, CSS vars)
  → body transitionend fires → .theme-switching removed
  → Transition only active for ~0.2s, only on targeted elements

TRIGGER: click dark/light │ click HC │ swatch accent
    │
    ▼
applyColorMode/Theme/AccentColor
    │
    ├→ setAttribute on <html>
    ├→ localStorage
    ├→ applyAccentColor (re-compute for dark/light)
    │     HC active? → remove all inline vars
    │     HC off? → set 6 vars for the current mode
    ▼
getMermaidConfig(isDark)
    │ Reads inline CSS vars for themeVariables
    ▼
mermaid.initialize() → reRenderMermaid() (dev)
    │
    ▼
MutationObserver (static) → updateMermaidTheme() → swap img[data-src-*]
    │
    ▼
CSS: .theme-switching on ~10 elements { transition: bg/color 0.2s }
    → transitionend on body → remove .theme-switching

updateFavicon(path)
  1. Remove all <link rel="icon">
  2. Insert blank: href="data:,"
     → forces browser to "forget" the old one
  3. rAF (browser displays the blank)
  4. Remove blank
  5. Insert new: href=resolved?v=Date.now()
     → cache-bust with timestamp
     → type by extension (png/svg/ico)
     → no favicon? fallback /favicon.ico

let fired = false;
const onEnd = () => { if (fired) return; fired = true; /* action */ };
el.addEventListener('transitionend', onEnd);
setTimeout(onEnd, DURATION + MARGIN);

el.style.transition = 'none';
el.style.opacity = '1';           // "from"
el.getBoundingClientRect();        // FORCE LAYOUT — browser notes the "from"
el.style.transition = '0.08s';
el.style.opacity = '0';           // "to" — browser animates from "from" to "to"

┌──────────┐  hover   ┌──────────┐  html   ┌────────────┐
│ TOC Item │ ───────→ │ Prefetch │ ──────→ │ Navigation │
│ (mouse)  │  click   │ Manager  │         │ SPA        │
└──────────┘ ───────→ └──────────┘         └─────┬──────┘
                                                 │
                   ┌─────────────┬────────────────┼──────────┐
                   ▼             ▼                ▼          ▼
             ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐
             │ Content  │ │ TOC      │ │ Headings │ │ Sidebar  │
             │ Fade     │ │ .active  │ │ Panel    │ │ Mobile   │
             │ out→in   │ │ update   │ │ build    │ │ close    │
             └──────────┘ └──────────┘ └────┬─────┘ └──────────┘
                                            │ transitionend
                                            ▼
                                      ┌──────────────┐
                                      │ toc-headings │
                                      │ -rendered    │
                                      └──────┬───────┘
                                             ▼
                                      ┌──────────────┐
                                      │ Scroll Spy   │ ←── scroll content
                                      │ re-sync      │
                                      └──────┬───────┘
                                             │ scrollspy-active
                                             ▼
                                      ┌──────────────┐
                                      │ TocExpand    │
                                      │ .active      │
                                      └──────────────┘

ThemeSwitcher.init() → anti-FOUC (instant, no transition)

DOMContentLoaded
  ├── SidebarResize.init()
  ├── TocTooltip.init()
  ├── AnalyticsConsent.init()
  ├── TourModule.init()
  └── AppStatic.init()
        ├── wire everything (sync)
        ├── animateTocStaggered() → toc-active-ready → headings panel
        │                        → toc-animation-done → app-ready
        │                                                  ├→ pulse
        │                                                  └→ tour (+1s)
        └── fetch(toc.json) ──async──→ SearchModule.init()
                                      + headings (if ready)

click dark/light
  │
  ├→ withThemeTransition: add .theme-switching
  ├→ applyColorMode → applyAccentColor → getMermaidConfig
  │                                            │
  │                                      mermaid.initialize
  │                                            │
  │                                   MutationObserver
  │                                            │
  │                                   updateMermaidTheme
  │                                            │
  │                                   swap img[data-src-*]
  │
  └→ body transitionend → remove .theme-switching

┌──────┐  click A−   ┌──────┐  click A−   ┌──────┐
│ XL   │ ──────────→ │ L    │ ──────────→ │ M    │ (default: 15px)
│ 18px │ ←────────── │ 17px │ ←────────── │ 15px │
└──────┘  click A+   └──────┘  click A+   └──────┘
                                              │ click A−
                                              ▼
                                           ┌──────┐  click A−   ┌──────┐
                                           │ S    │ ──────────→ │ XS   │
                                           │ 13px │ ←────────── │ 12px │
                                           └──────┘  click A+   └──────┘

Persistence: localStorage('cv-font-size') = 12|13|15|17|18
Restoration: inline <head> script (anti-FOUC)
Application: html { font-size: Xpx; }

<button id="btn-font-decrease" class="theme-btn font-size-btn"
  title="Decrease font size (A−)" aria-label="Decrease font size">
  <span aria-hidden="true">A−</span>
</button>
<button id="btn-font-increase" class="theme-btn font-size-btn"
  title="Increase font size (A+)" aria-label="Increase font size">
  <span aria-hidden="true">A+</span>
</button>

.font-size-btn { font-size: 11px; font-weight: 700; letter-spacing: -0.5px; }
/* Steps: 12, 13, 15 (default), 17, 18 */

const STORAGE_FONT_SIZE = 'cv-font-size';
const FONT_STEPS = [12, 13, 15, 17, 18]; // px
const DEFAULT_FONT_SIZE = 15;

function getStoredFontSize() {
  try { return parseInt(localStorage.getItem(STORAGE_FONT_SIZE)) || DEFAULT_FONT_SIZE; }
  catch { return DEFAULT_FONT_SIZE; }
}

function applyFontSize(size) {
  document.documentElement.style.fontSize = size + 'px';
  try { localStorage.setItem(STORAGE_FONT_SIZE, size); } catch {}
}

function changeFontSize(delta) {
  const current = getStoredFontSize();
  const idx = FONT_STEPS.indexOf(current);
  const nextIdx = Math.max(0, Math.min(FONT_STEPS.length - 1, idx + delta));
  applyFontSize(FONT_STEPS[nextIdx]);
}

var f=localStorage.getItem('cv-font-size');
if(f)document.documentElement.style.fontSize=f+'px';

test('hover on idle starts fetch')
test('hover on loading is noop')
test('hover on loaded is noop')
test('click on loaded returns cached result')
test('click on loading waits for fetch')
test('click on idle starts fetch and waits')
test('error state flushes waiters with null')
test('onStateChange called on each transition')

test('hover TOC link → network request appears')
test('hover then click → single network request')
test('click without hover → fetch + navigation')
test('CSS class lifecycle: idle → loading → loaded')
test('prefetch-bar animation visible during loading')

test('navigateTo swaps innerHTML')
test('navigateTo updates currentPath')
test('navigateTo with hash scrolls to element')
test('navigateTo pushes history state')
test('navigateTo with pushState=false does not push')
test('same page + hash does smoothScroll only')

test('full navigation: click TOC → content changes → URL updates')
test('back button restores previous page')
test('deep link on load scrolls to heading')
test('mobile sidebar closes after navigation')
test('headings panel appears after page load')

test('click section title toggles open class')
test('aria-expanded matches open state')
test('click expand btn toggles children')
test('expand btn stopPropagation')
test('tocExpand section navigates instead of toggling')

test('section expand/collapse animation completes')
test('nested tree expand shows children')
test('keyboard Enter/Space triggers toggle')

test('buildHeadingsPanel creates correct DOM')
test('cleanupHeadingWrappers removes all wrappers')
test('heading click pauses scroll spy')
test('heading click scrolls to target')
test('copy button copies URL to clipboard')
test('tocExpand items skip headings panel')

test('navigate to page → headings panel appears')
test('navigate away → old panel closes, new opens')
test('scroll content → active heading updates in panel')
test('grid transition completes → toc-headings-rendered fires')

test('onScroll finds heading within 60px of top')
test('pause() sets paused flag')
test('resume via scrollend event')
test('resume via 2xRAF fallback')
test('h4 slug walks up to parent h2/h3')
test('markTocUserScrolled sets flag')
test('resetTocUserScrolled clears flag')
test('scrollTocToActiveItem noop when user scrolled')

test('scroll content → sidebar heading highlights')
test('click heading → spy paused → spy resumes after scroll')
test('user scrolls TOC → auto-scroll disabled')
test('navigate → auto-scroll re-enabled')

test('animateTocStaggered opens all sections')
test('animateTocStaggered dispatches toc-active-ready')
test('animateTocStaggered dispatches toc-animation-done')
test('pulseElement applies then removes styles')

test('pointerenter starts 650ms timer')
test('pointerleave cancels timer')
test('tooltip positioned at rect.right + 10px')
test('tooltip shows title and description')

test('mousedown starts dragging')
test('mousemove updates sidebar width')
test('mouseup saves to localStorage')
test('width clamped 180-50vw')
test('autoSize when no user width')
test('mobile toggle adds open class')
test('backdrop click removes open class')

test('start() transitions to running')
test('next() increments stepIndex')
test('prev() decrements stepIndex')
test('end(true) transitions to completed')
test('end(false) transitions to skipped')
test('markCompleted writes localStorage')
test('showAffordance returns false if not first visit')
test('focus trap cycles through buttons')

test('full tour: start → 8 steps → complete')
test('Escape at any step → skipped')
test('first visit shows pulse + tooltip')
test('second visit no affordance')
test('mobile: sidebar opens for sidebar targets')

test('createOverlay returns DOM element')
test('toggleOverlay shows/hides')
test('zoom clamp 0.1 to 5')
test('pan updates transform')
test('reset resets zoom and pan')
test('CV hover starts fetch')
test('CV request returns blob when loaded')
test('CV request waits when loading')

test('matchScore returns 0 for no match')
test('matchScore title > tag > desc')
test('highlight wraps matching text in <mark>')
test('navigateResults wraps at boundaries')
test('selectActive navigates and closes')
test('empty query shows first 20 items')
test('buildIndex creates entries from tocData')

test('toggleColorMode flips dark/light')
test('applyColorMode sets attribute and localStorage')
test('applyColorTheme sets attribute')
test('applyAccentColor sets 6 CSS vars')
test('applyAccentColor removes vars in HC mode')
test('applyOS updates terminal title')
test('detectOS returns correct platform')
test('buildPaletteDOM creates 9 swatches')

test('dark→light → all colors transition smoothly')
test('HC mode → accent palette shows override notice')
test('accent change → Mermaid diagrams re-render')
test('reload → same theme restored (no flash)')
test('OS change → terminal dots/title update')

test('getConsent returns null initially')
test('setConsent yes enables script')
test('setConsent no removes banner')
test('track noop without consent')
test('showBanner does not show if consent exists')

test('hire modal opens on button click')
test('hire form builds correct mailto URL')
test('help modal toggles on ? key')
test('CV tray toggles on button click')
test('CV modal sets iframe src from blob')
test('escape chain priority order correct')

test('changeFontSize(+1) increments step')
test('changeFontSize(-1) decrements step')
test('changeFontSize clamps at min 12px')
test('changeFontSize clamps at max 18px')
test('applyFontSize sets documentElement.style.fontSize')
test('applyFontSize saves to localStorage')
test('getStoredFontSize returns default when no LS')
test('getStoredFontSize returns stored value')

test('click A+ → font size increases visually')
test('click A− → font size decreases visually')
test('reload → font size restored from localStorage')
test('no FOUC: font size applied before first paint')
test('font size works with dark/light/HC themes')
test('A+ at max → no change')
test('A− at min → no change')

Unit tests     : vitest (already Node.js, fast, native ESM)
DOM tests      : @testing-library/dom + jsdom
Integration    : Playwright (real browser, screenshots)
Assertions     : vitest built-in (expect, vi.fn())

test/
├── unit/
│   ├── prefetch-manager.test.js
│   ├── tour-state.test.js
│   ├── search-scoring.test.js
│   ├── font-size.test.js
│   ├── scroll-spy.test.js
│   ├── theme-switcher.test.js
│   └── analytics-consent.test.js
├── integration/
│   ├── navigation.test.js
│   ├── toc-interactions.test.js
│   ├── theme-cascade.test.js
│   ├── tour-flow.test.js
│   └── font-size-persistence.test.js
└── setup.js