# PDF Export Feature Documentation

## Overview

The CV application provides a comprehensive PDF export system with three predefined options and dynamic filename generation. Users can download their CV in different formats through an interactive modal interface with an intuitive, clear naming convention.

## 🎯 Architecture: Dual Rendering Modes

**Critical Design Decision**: The PDF generator uses **different media emulation** depending on the version:

### Clean Version (Short CV) - Print Mode
- **Uses**: `@media print` CSS rules (default browser print behavior)
- **Purpose**: Print-friendly, minimal layout
- **Characteristics**:
  - No skills sidebars (hidden by print.css)
  - No UI elements (navigation, buttons, footer hidden by print.css)
  - Print-optimized typography, margins, and page breaks
  - ~4 pages, ~2.2 MB
  - Clean, professional print appearance

### Extended Version (Long CV) - Screen Mode + UI Hiding
- **Uses**: `@media screen` CSS (emulated via CDP) + injected CSS to hide UI elements
- **Purpose**: Pixel-perfect screen capture with content sidebars, minus UI chrome
- **Characteristics**:
  - Shows skills sidebars (screen layout preserved)
  - No UI elements (hidden via injected CSS: `.action-bar`, `.navigation-menu`, `footer`, etc.)
  - Uses natural screen layout (pixel-perfect rendering)
  - ~16 pages, ~3.6 MB
  - Full digital experience without UI chrome

**Why This Approach?**
1. **Clean version** needs print-optimized layout (compact, professional)
2. **Extended version** needs pixel-perfect screen layout with sidebars visible
3. CDP's `emulation.SetEmulatedMedia()` allows switching between `@media print` and `@media screen`
4. Injected CSS surgically hides only UI elements without affecting content layout

**Implementation Details**:
- `RenderModePrint`: Uses default `@media print` (hides sidebars + UI via print.css)
- `RenderModeScreen`:
  1. Emulates `@media screen` to preserve natural layout
  2. Injects CSS to hide UI: `.no-print, .action-bar, .navigation-menu, .hamburger-btn, footer, .back-to-top, .info-button, .info-modal, .error-toast, .cv-title-badges-header, .cv-footer`
  3. Keeps all content and sidebars with their natural screen styling

**See**: `internal/pdf/generator.go` lines 146-165 for implementation

### PDF Generation Flow

```
User selects PDF option in modal
    ↓
Frontend: /export/pdf?lang={lang}&length={length}&icons={icons}&version={version}
    ↓
Backend: GenerateFromURLWithOptions(url, cookies, RenderMode)
    ↓
Chromedp: Navigate to URL with cookies
    ↓
CSS Injection: Override print.css + Show/hide sidebars + Layout adjustments
    ↓
PDF Generation: PrintToPDF with A4 dimensions
    ↓
Output: PDF file (4, 5, 7, or 9 pages depending on configuration)
```

### 2-Column vs 3-Column Layout Decision

**Critical Architecture Decision** for long CV with sidebars:

#### ❌ Previous Approach (3-column - WRONG)
```css
.page-1, .page-2: 25% | 50% | 25%  /* Always 3 columns */
```
**Problems:**
- Page 1 had empty right column (25% wasted space)
- Page 2 had empty left column (25% wasted space)
- Result: 10-19 pages (excessive)

#### ✅ Current Approach (2-column - CORRECT)
```css
.page-1: 25% | 75%    /* Left sidebar + Main, NO right space */
.page-2: 75% | 25%    /* Main + Right sidebar, NO left space */
```
**Benefits:**
- No wasted space on either page
- Matches web's actual layout exactly
- Result: **9 pages** (optimal)

### Sidebar Width Configuration

Sidebar width affects page count and readability:

| Width | Layout | Pages | Notes |
|-------|--------|-------|-------|
| 18% | 18% \| 82% | 9 pages | Too narrow, cramped |
| 20% | 20% \| 80% | 8 pages | Minimal sidebars |
| **25%** | **25% \| 75%** | **9 pages** | ✅ **Current** (optimal balance) |
| 30% | 30% \| 70% | 10+ pages | Too wide, excessive |

**Current Setting**: 25% sidebars (configured in `internal/pdf/generator.go:176,181`)

**To adjust sidebar width**, update these lines in `internal/pdf/generator.go`:
```go
// Page 1: Left sidebar (XX%) + Main (YY%) - NO right space
'.page-1 .page-content { grid-template-columns: XX% YY% !important; }' +

// Page 2: Main (YY%) + Right sidebar (XX%) - NO left space
'.page-2 .page-content { grid-template-columns: YY% XX% !important; }'

// Where XX + YY = 100
```

### Detailed CSS Injection Strategy

For `RenderModeScreen` (long CV with sidebars), the following CSS is injected:

```javascript
// Override parent width constraints (full A4 width)
'.cv-page, .cv-paper, .cv-container { max-width: 100% !important; width: 100% !important; }'

// Show sidebars (override print.css hiding)
'.cv-sidebar, .cv-sidebar-left, .cv-sidebar-right { display: block !important; }'

// Hide mobile UI elements (accordion headers, navigation, etc.)
'.sidebar-accordion-header { display: none !important; }'
'.no-print, .action-bar, .navigation-menu, .hamburger-btn { display: none !important; }'
'footer, .back-to-top, .info-button, .info-modal { display: none !important; }'

// Force page break before page 2
'.page-2 { page-break-before: always !important; break-before: page !important; }'

// 2-column layouts (no wasted space)
'.page-1 .page-content { grid-template-columns: 25% 75% !important; }'  // Left + Main
'.page-2 .page-content { grid-template-columns: 75% 25% !important; }'  // Main + Right
```

### HTML Structure

**Page 1** - Left sidebar + Main content:
```html
<div class="cv-page page-1">
  <div class="page-content">
    <aside class="cv-sidebar cv-sidebar-left">
      <!-- Skills, languages, etc. -->
    </aside>
    <main class="cv-main">
      <!-- Work experience, education -->
    </main>
  </div>
</div>
```

**Page 2** - Main content + Right sidebar:
```html
<div class="cv-page page-2">
  <div class="page-content">
    <main class="cv-main">
      <!-- Continued work experience -->
    </main>
    <aside class="cv-sidebar cv-sidebar-right">
      <!-- Additional skills, references -->
    </aside>
  </div>
</div>
```

### Compact Sidebar Fonts Feature

**Overview:**
Automatically reduces sidebar font sizes by 2-6% **only for short CVs with skills** (`length=short&version=with_skills`), reducing page count from 6 to 5 pages while maintaining readability.

**Impact:**
- Page count reduction: 6 → 5 pages (16.7% reduction)
- Font size reduction: 2-6% (very subtle, 0.94-0.98em)
- Readability: Maintained - fonts remain professional
- **Only for short version** - Long version uses full-size fonts

**Activation Conditions:**
1. `length=short` (detected via `cv-length` cookie)
2. `version=with_skills` (RenderModeScreen with sidebars)

**Does NOT activate for:**
- Long CVs (`length=long`) - always use full-size fonts
- Clean version (`version=clean`) - no sidebars shown

**Implementation** (`internal/pdf/generator.go` lines 154-215):
```go
// Check if this is a short version (to apply compact sidebar fonts)
isShortVersion := cookies["cv-length"] == "short"

compactFontCSS := ""
if isShortVersion {
    compactFontCSS = `
        /* Compact sidebar fonts (SHORT VERSION ONLY) */
        .cv-sidebar * { font-size: 0.96em !important; line-height: 1.4 !important; }
        .cv-sidebar h3 { font-size: 0.98em !important; margin: 0.4em 0 !important; }
        .cv-sidebar h4 { font-size: 0.96em !important; margin: 0.35em 0 !important; }
        .cv-sidebar p, .cv-sidebar li { font-size: 0.94em !important; line-height: 1.4 !important; }
        .cv-sidebar ul, .cv-sidebar ol { margin: 0.4em 0 0.4em 1.2em !important; }
        .cv-sidebar li { margin-bottom: 0.25em !important; }
        .cv-sidebar section { margin-bottom: 0.8em !important; }
    `
}
```

**Font Size Breakdown:**

| Element | Full-Size (Long) | Compact (Short) | Reduction |
|---------|------------------|-----------------|-----------|
| General text | 1.0em | 0.96em | 4% |
| H3 headings | 1.0em | 0.98em | 2% |
| H4 headings | 1.0em | 0.96em | 4% |
| Paragraphs & lists | 1.0em | 0.94em | 6% |

**Design Philosophy:**
- **Readability first**: 2-6% reduction is barely noticeable
- **Professional appearance**: No "squeezed" or cramped feel
- **Natural flow**: Content reflows organically, not forced
- **Consistent UX**: Main content uses full-size fonts

## Feature Specifications

### Export Options

#### 1. Short CV (Clean Version - **Short**)
- **Length**: `short` (essential information only)
- **Version**: `clean` (no skills sidebar)
- **Page Count**: 4 pages
- **Use Case**: Job applications requiring concise CVs
- **Parameters**: `?lang={lang}&length=short&icons=show&version=clean`
- **Filename**: `cv-short-jamr-{year}-{lang}.pdf` *(version omitted for clean)*

#### 2. Long CV (Extended Version - **With Skills**)
- **Length**: `extended` (comprehensive information)
- **Version**: `with_skills` (includes skills sidebar)
- **Page Count**: ~16 pages (natural screen layout with sidebars preserved)
- **Use Case**: Detailed applications requiring full work history with skills showcase
- **Parameters**: `?lang={lang}&length=long&icons=show&version=with_skills`
- **Filename**: `cv-long-with-skills-jamr-{year}-{lang}.pdf`

#### 3. Current View
- **Length**: From localStorage (`cv-length`) - mapped to new naming
- **Version**: From localStorage (`cv-theme`) - mapped to new naming
- **Icons**: From localStorage (`cv-icons`)
- **Page Count**: Variable based on settings
- **Use Case**: Export exactly what's displayed on screen
- **Parameters**: Dynamic based on localStorage with automatic mapping

### Naming Convention - Clear and Descriptive

All exported PDFs follow a consistent, intuitive naming convention:

```
cv-{length}[-{version}]-{initials}-{year}-{lang}.pdf

WHERE:
  {length}   = short | long
  {version}  = OMITTED for clean | with_skills for extended
  {initials} = User initials (e.g., "jamr")
  {year}     = Current year (2025)
  {lang}     = es | en
```

**Key Design Decision**: Version is **OMITTED** when it's "clean" to keep filenames concise and clear.

### Filename Examples

| Modal Option | Settings | Generated Filename |
|-------------|----------|-------------------|
| **Short CV** | short + clean | `cv-short-jamr-2025-es.pdf` |
| **Long CV** | long + with_skills | `cv-long-with-skills-jamr-2025-en.pdf` |
| **Current View** | short + with_skills | `cv-short-with-skills-jamr-2025-es.pdf` |
| **Current View** | long + clean | `cv-long-jamr-2025-en.pdf` |

### Comprehensive Combinations Matrix

| Length | Version | Filename Pattern |
|--------|---------|------------------|
| **short** | clean | `cv-short-jamr-{year}-{lang}.pdf` |
| **short** | with_skills | `cv-short-with-skills-jamr-{year}-{lang}.pdf` |
| **long** | clean | `cv-long-jamr-{year}-{lang}.pdf` |
| **long** | with_skills | `cv-long-with-skills-jamr-{year}-{lang}.pdf` |

### Dynamic Features

#### 1. Year Placeholder System
Static PDF URLs in JSON data files use a `{{YEAR}}` placeholder that's automatically replaced with the current year when the application loads.

**JSON Configuration:**
```json
{
  "url": "https://juan.andres.morenorub.io/static/pdf/cv-short-jamr-{{YEAR}}-es.pdf"
}
```

**Runtime Replacement:**
- Handled by `LoadCV()` function in `internal/models/cv.go`
- Replaces `{{YEAR}}` with `time.Now().Year()`
- Ensures URLs always reference current year's PDFs

#### 2. Initials Extraction
Initials are dynamically generated from the user's full name:

```go
nameParts := strings.Fields(cv.Personal.Name)
initials := ""
for _, part := range nameParts {
    if len(part) > 0 {
        initials += string([]rune(part)[0])
    }
}
initials = strings.ToLower(initials)
```

**Example:** "Juan Andrés Moreno Rubio" → "jamr"

#### 3. Legacy LocalStorage Mapping

For backwards compatibility, the system automatically maps old localStorage values to the new naming convention:

```javascript
// Old → New mapping (for backwards compatibility)
'long' → 'long'
'long' (theme) → 'with_skills'
// Note: 'short' now stays as 'short' (no longer maps to 'detailed')
'clean' → 'clean' (unchanged)
```

This ensures existing users' preferences continue to work seamlessly.

## Print-Friendly Design: Light Mode Only

### Critical Policy

**PDFs are ALWAYS generated in light mode, regardless of the user's color theme preference.**

This is a fundamental design decision for print-friendliness and readability:

- ✅ Light backgrounds with dark text for optimal printing
- ✅ Professional appearance in any context
- ✅ Reduced printer ink consumption
- ✅ Consistent output across all use cases
- ❌ Dark mode is NEVER used for PDF generation

### Multi-Layer Enforcement

The system enforces light mode at THREE levels to guarantee print-friendly PDFs:

#### 1. Backend Cookie Enforcement
**File:** `internal/handlers/cv.go`

The PDF export handler ALWAYS sets the `color-theme` cookie to "light":

```go
// CRITICAL: ALWAYS force light mode for PDF generation (print-friendly)
// This ensures PDFs are NEVER generated in dark mode, regardless of user's preference
cookies["color-theme"] = "light"
```

This ensures the browser context used for PDF generation starts with light mode enabled.

#### 2. CSS Print Media Query Override
**File:** `static/css/08-contexts/_print.css`

The print stylesheet forcibly overrides ALL color theme CSS variables:

```css
@media print {
    /* CRITICAL: FORCE LIGHT MODE FOR ALL PDFs */
    /* PDF generation MUST ALWAYS use light mode colors */
    /* This overrides ANY color theme (dark/auto/light) */
    *,
    :root,
    [data-color-theme="dark"],
    [data-color-theme="auto"],
    [data-color-theme="light"],
    html,
    body {
        --page-bg: #b8bbbe !important;
        --paper-bg: #ffffff !important;
        --text-primary: #1a1a1a !important;
        --text-secondary: #333333 !important;
        /* ... all light mode variables ... */
    }
}
```

This ensures that even if JavaScript fails or cookies don't propagate, the CSS will force light mode colors during print/PDF generation.

#### 3. Print Color Accuracy
The print stylesheet also includes critical browser directives:

```css
@media print {
    * {
        -webkit-print-color-adjust: exact !important;
        print-color-adjust: exact !important;
        color-adjust: exact !important;
    }
}
```

This ensures browsers render colors exactly as specified, preventing automatic adjustments that could affect print quality.

### Why Three Layers?

This defense-in-depth approach guarantees light mode PDFs even if:
- Cookies fail to set or propagate
- JavaScript doesn't execute properly
- Browser preferences override theme settings
- CSS cascade issues occur

**Result:** Bulletproof light mode enforcement for all PDF exports.

## Technical Implementation

### File Structure

```
/Users/txeo/Git/yo/cv/
├── internal/
│   ├── handlers/
│   │   └── cv.go                    # PDF export handler with filename generation
│   └── models/
│       └── cv.go                    # CV data loading with year placeholder replacement
├── templates/
│   └── partials/
│       └── modals/
│           └── pdf-modal.html       # Interactive PDF download modal
├── static/
│   ├── css/
│   │   └── 04-interactive/
│   │       └── _remaining.css       # Modal styling (red theme for PDF)
│   └── pdf/
│       ├── cv-short-jamr-2025-es.pdf
│       ├── cv-short-jamr-2025-en.pdf
│       ├── cv-long-with-skills-jamr-2025-es.pdf
│       └── cv-long-with-skills-jamr-2025-en.pdf
├── data/
│   ├── cv-es.json                   # Spanish CV data with {{YEAR}} placeholders
│   └── cv-en.json                   # English CV data with {{YEAR}} placeholders
└── tests/
    └── mjs/
        ├── 14-pdf-modal.test.mjs           # Modal UI and interaction tests
        └── 24-pdf-download-params.test.mjs # Parameter validation tests
```

### Backend: Parameter Validation and Filename Generation

**File:** `internal/handlers/cv.go`

**Parameter Validation:**
```go
// Length parameter: "short" or "long"
length := r.URL.Query().Get("length")
if length == "" {
    length = "short"
}
if length != "short" && length != "long" {
    HandleError(w, r, BadRequestError("Unsupported length. Use 'short' or 'long'"))
    return
}

// Version parameter: "clean" or "with_skills"
version := r.URL.Query().Get("version")
if version == "" {
    version = "with_skills"
}
if version != "with_skills" && version != "clean" {
    HandleError(w, r, BadRequestError("Unsupported version. Use 'with_skills' or 'clean'"))
    return
}
```

**Filename Generation:**
```go
// Generate initials from name
nameParts := strings.Fields(cv.Personal.Name)
initials := ""
for _, part := range nameParts {
    if len(part) > 0 {
        initials += string([]rune(part)[0])
    }
}
initials = strings.ToLower(initials)

// Get current year
currentYear := time.Now().Year()

// Build filename: cv-{length}[-{version}]-{initials}-{year}-{lang}.pdf
// Omit version if it's "clean"
var filename string
if version == "clean" {
    filename = fmt.Sprintf("cv-%s-%s-%d-%s.pdf", length, initials, currentYear, lang)
} else {
    filename = fmt.Sprintf("cv-%s-%s-%s-%d-%s.pdf", length, version, initials, currentYear, lang)
}
```

**Examples:**
- short + clean → `cv-short-jamr-2025-es.pdf`
- long + with_skills → `cv-long-with-skills-jamr-2025-en.pdf`

### Frontend: Modal Interaction with Legacy Mapping

**File:** `templates/partials/modals/pdf-modal.html`

```javascript
function downloadPDF() {
    const selectedCard = document.querySelector('#pdf-modal .pdf-option-card.selected');
    const selectedFormat = selectedCard.getAttribute('data-cv-format');
    const lang = '{{.Lang}}';
    let url;

    if (selectedFormat === 'short') {
        // Short CV: clean version (no skills), short length
        url = `/export/pdf?lang=${lang}&length=short&icons=show&version=clean`;
    } else if (selectedFormat === 'long') {
        // Long CV: with skills sidebar, extended length
        url = `/export/pdf?lang=${lang}&length=long&icons=show&version=with_skills`;
    } else if (selectedFormat === 'current') {
        // Current view: use localStorage settings with mapping
        let currentLength = localStorage.getItem('cv-length') || 'short';

        // Map old values to new naming convention
        if (currentLength === 'long') currentLength = 'long';
        // 'short' stays as 'short' - no mapping needed

        const currentIcons = localStorage.getItem('cv-icons') || 'show';
        const currentTheme = localStorage.getItem('cv-theme') || 'default';
        const version = currentTheme === 'clean' ? 'clean' : 'with_skills';

        url = `/export/pdf?lang=${lang}&length=${currentLength}&icons=${currentIcons}&version=${version}`;
    }

    window.location.href = url;
}
```

## Testing

### Test Suite

#### 1. Modal UI Test: `14-pdf-modal.test.mjs`
Tests the modal interface and user interactions:
- ✅ Modal structure (3 thumbnail cards, download button)
- ✅ Card selection behavior (radio button pattern)
- ✅ Download button enable/disable logic
- ✅ Keyboard navigation (Tab, Enter, Space, ESC)
- ✅ Accessibility (ARIA attributes, screen reader support)
- ✅ Responsive layout (mobile/tablet/desktop)
- ✅ Multilingual support (EN/ES)

#### 2. Parameter Validation Test: `24-pdf-download-params.test.mjs`
Tests PDF export parameters and filename generation:
- ✅ Short CV parameters: `length=short&version=clean`
- ✅ Long CV parameters: `length=long&version=with_skills`
- ✅ Current View parameters: reads from localStorage with mapping
- ✅ Filename format: `cv-{length}[-{version}]-{initials}-{year}-{lang}.pdf`
- ✅ Version omitted for clean
- ✅ Dynamic year generation
- ✅ Legacy value mapping (long→extended)

**Run Tests:**
```bash
# Run modal UI tests
bun tests/mjs/14-pdf-modal.test.mjs

# Run parameter validation tests
bun tests/mjs/24-pdf-download-params.test.mjs

# Run all tests
bun tests/run-all.mjs
```

### Manual Testing Checklist

- [ ] Open PDF modal from download button
- [ ] Select each of the three options
- [ ] Verify download button enables after selection
- [ ] Click download button for each option
- [ ] Verify correct filename generated (check version omission for clean)
- [ ] Check PDF opens correctly
- [ ] Test in Spanish and English
- [ ] Test on mobile/tablet/desktop
- [ ] Verify keyboard navigation (Tab, Enter, ESC)
- [ ] Test with different localStorage settings for Current View
- [ ] Verify legacy localStorage values map correctly

## API Endpoint

### `/export/pdf`

**Method:** GET

**Parameters:**
- `lang` (optional, default: "en"): `es` or `en`
- `length` (optional, default: "short"): `short` or `extended`
- `icons` (optional, default: "show"): `show` or `hide`
- `version` (optional, default: "with_skills"): `clean` or `with_skills`

**Response:**
- **Success**: PDF file with appropriate filename and `Content-Disposition` header
- **Rate Limited**: `429 Too Many Requests` with "Rate limit exceeded" message
- **Error**: `400 Bad Request` for invalid parameters, `500 Internal Server Error` for generation failures

**Example Requests:**
```bash
# Short clean CV in Spanish
curl -O http://localhost:1999/export/pdf?lang=es&length=short&icons=show&version=clean
# Filename: cv-short-jamr-2025-es.pdf

# Extended with skills CV in English
curl -O http://localhost:1999/export/pdf?lang=en&length=long&icons=show&version=with_skills
# Filename: cv-long-with-skills-jamr-2025-en.pdf
```

## Shortcut URLs (Year-Aware)

### Overview

The application provides memorable shortcut URLs for the default CV (short with skills, 5 pages) that are easy to share and remember.

**Pattern:** `/cv-jamr-{year}-{lang}.pdf`

**Examples:**
- `https://juan.andres.morenorub.io/cv-jamr-2025-en.pdf` (English)
- `https://juan.andres.morenorub.io/cv-jamr-2025-es.pdf` (Spanish)

### Year Validation

The shortcut URLs include automatic year validation that auto-updates annually:

**Current Year (2025):**
- ✅ `/cv-jamr-2025-en.pdf` → Works (301 redirect)
- ✅ `/cv-jamr-2025-es.pdf` → Works (301 redirect)

**Past/Future Years:**
- ❌ `/cv-jamr-2024-en.pdf` → 404 Not Found
- ❌ `/cv-jamr-2026-en.pdf` → 404 Not Found (until 2026)

**Auto-Update:** Next year (2026), the 2026 URLs will automatically work and 2025 URLs will return 404.

### Implementation

**Backend Handler** (`internal/handlers/cv.go`):
```go
func (h *CVHandler) DefaultCVShortcut(w http.ResponseWriter, r *http.Request) {
    // Extract year and language from URL path
    path := r.URL.Path  // e.g., "/cv-jamr-2025-en.pdf"
    parts := strings.Split(strings.TrimPrefix(path, "/"), "-")

    yearStr := parts[2]
    lang := strings.TrimSuffix(parts[3], ".pdf")

    // Validate year matches current year
    currentYear := fmt.Sprintf("%d", time.Now().Year())
    if yearStr != currentYear {
        http.NotFound(w, r)
        return
    }

    // Validate language
    if lang != "en" && lang != "es" {
        http.NotFound(w, r)
        return
    }

    // Redirect to default PDF (short with skills)
    redirectURL := fmt.Sprintf("/export/pdf?lang=%s&length=short&icons=show&version=with_skills", lang)
    http.Redirect(w, r, redirectURL, http.StatusMovedPermanently)
}
```

**Route Registration** (`internal/routes/routes.go`):
```go
// Shortcut routes - must be before "/" route for precedence
mux.HandleFunc("/cv-jamr-", cvHandler.DefaultCVShortcut)
```

**Frontend Integration** (`templates/partials/modals/pdf-modal.html`):
```javascript
if (selectedFormat === 'default') {
    // Default CV: use shortcut URL
    const currentYear = new Date().getFullYear();
    url = `/cv-jamr-${currentYear}-${lang}.pdf`;
}
```

### Benefits

**For Users:**
- ✅ Memorable URL pattern
- ✅ Easy to type and share
- ✅ No complex query parameters
- ✅ Professional appearance

**For Developers:**
- ✅ Auto-updates yearly (no manual changes)
- ✅ Simple validation logic
- ✅ SEO-friendly clean URLs
- ✅ Minimal maintenance overhead

### Testing

```bash
# Test current year (should work)
curl -I http://localhost:1999/cv-jamr-2025-en.pdf
# Expected: HTTP/1.1 301 Moved Permanently
# Location: /export/pdf?lang=en&length=short&icons=show&version=with_skills

# Test invalid year (should fail)
curl -I http://localhost:1999/cv-jamr-2024-en.pdf
# Expected: HTTP/1.1 404 Not Found

# Run automated test
bun tests/mjs/28-references-pdf-download.test.mjs
```

### References Section Integration

The shortcut URLs are integrated into the **References section** of the CV for easy access:

**Template Integration** (`templates/partials/sections/references.html`):
```html
{{if eq .Action "downloadPDF"}}
  <a href="/cv-jamr-{{$.CurrentYear}}-{{$.Lang}}.pdf"
     target="_blank"
     rel="noopener noreferrer">
    <strong>{{.LinkText}}</strong>
  </a>
{{end}}
```

**Data Configuration** (`data/cv-en.json`, `data/cv-es.json`):
```json
{
  "title": "Download this curriculum in English",
  "action": "downloadPDF",
  "textBefore": "Download this curriculum in",
  "linkText": "English"
}
```

**Key Features:**
- **Direct link** - No modal, no JavaScript dependency
- **Language-aware** - Spanish CV gets Spanish link, English CV gets English link
- **Year-aware** - Automatically uses current year
- **Works everywhere** - PDF exports, emails, external shares
- **Security** - Proper `target="_blank"` and `rel="noopener noreferrer"` attributes

**Use Cases:**
- ✅ Works in printed PDFs (link remains functional)
- ✅ Works in email clients (direct download link)
- ✅ Works without JavaScript (static HTML link)
- ✅ Works when shared externally (permanent, memorable URL)

## Design Philosophy

### Why This Naming Convention?

1. **Clarity**: "short" and "long" clearly communicate content depth
2. **Simplicity**: Version omitted for clean keeps filenames concise
3. **Consistency**: All components follow the same pattern
4. **Intuitive**: Non-technical users can understand what each filename means
5. **Professional**: Matches industry standards for document naming

### Old vs New Comparison

| Old Naming | New Naming | Improvement |
|-----------|------------|-------------|
| `cv-detailed-jamr-2025-es.pdf` (v1) | `cv-short-jamr-2025-es.pdf` | Simpler, more intuitive |
| `cv-long-extended-en-jamr-2025.pdf` | `cv-long-with-skills-jamr-2025-en.pdf` | More descriptive, better clarity |
| Language before year | Language after year | Better organization |

## Maintenance

### Updating Static PDFs

To regenerate static PDFs referenced in JSON files:

```bash
# Short + clean (version omitted)
curl -o static/pdf/cv-short-jamr-2025-es.pdf \
  "http://localhost:1999/export/pdf?lang=es&length=short&icons=show&version=clean"

curl -o static/pdf/cv-short-jamr-2025-en.pdf \
  "http://localhost:1999/export/pdf?lang=en&length=short&icons=show&version=clean"

# Extended + with_skills
curl -o static/pdf/cv-long-with-skills-jamr-2025-es.pdf \
  "http://localhost:1999/export/pdf?lang=es&length=long&icons=show&version=with_skills"

curl -o static/pdf/cv-long-with-skills-jamr-2025-en.pdf \
  "http://localhost:1999/export/pdf?lang=en&length=long&icons=show&version=with_skills"
```

### Year Rollover

The system automatically handles year rollovers:
- **Filename Generation**: Uses `time.Now().Year()` at runtime
- **URL Placeholders**: `{{YEAR}}` replaced during data load
- **No Manual Updates Required**: All year references are dynamic

## Troubleshooting

### Wrong Filename Format

**Symptom**: Filename doesn't match `cv-{length}[-{version}]-{initials}-{year}-{lang}.pdf`

**Solutions:**
1. Verify backend logic in `internal/handlers/cv.go` lines 306-313
2. Check version is correctly omitted for clean
3. Ensure language appears at the end
4. Verify year extraction logic

### Legacy localStorage Not Mapping

**Symptom**: Old localStorage values (`short`, `long`) not working in Current View

**Solutions:**
1. Check JavaScript mapping logic in `pdf-modal.html` lines 257-260
2. Verify mapping: `short` → `detailed`, `long` → `extended`
3. Test with console.log to see actual values
4. Clear localStorage and test with fresh values

### Parameter Validation Errors

**Symptom**: 400 Bad Request when downloading PDF

**Solutions:**
1. Check allowed values: `length` ∈ {short, extended}, `version` ∈ {clean, with_skills}
2. Verify frontend sends correct parameters
3. Check browser network tab for actual request
4. Run parameter validation test: `bun tests/mjs/24-pdf-download-params.test.mjs`

### PDF Generated in Dark Mode

**Symptom**: Downloaded PDF has dark background and light text

**Root Cause**: Light mode enforcement not working at one or more layers

**Solutions:**

1. **Verify Backend Cookie Setting** (`internal/handlers/cv.go:260-270`):
   ```go
   // Ensure this line exists:
   cookies["color-theme"] = "light"
   ```
   - Check server logs for cookie setting
   - Restart server if code was recently updated

2. **Verify CSS Print Overrides** (`static/css/08-contexts/_print.css:4-60`):
   ```css
   @media print {
       /* Verify this section exists at the top */
       *,
       :root,
       [data-color-theme="dark"],
       [data-color-theme="auto"] {
           --paper-bg: #ffffff !important;
           --text-primary: #1a1a1a !important;
           /* ... all light mode variables ... */
       }
   }
   ```
   - Clear browser cache
   - Check CSS file is being served correctly

3. **Test with Browser Dev Tools**:
   - Open page in browser
   - Enable dark mode
   - Open Print Preview (Cmd/Ctrl+P)
   - Verify preview shows light background
   - If preview is dark, CSS overrides aren't working

4. **Manual Testing**:
   ```bash
   # Set user to dark mode
   # Then generate PDF
   curl -O "http://localhost:1999/export/pdf?lang=es&length=short&version=clean"

   # Open PDF and verify it has white background
   ```

**Expected Result**: PDF ALWAYS has white background (`#ffffff`) and dark text (`#1a1a1a`), regardless of user's color theme preference.

---

## Changelog

### Version 2.0.0 (2025-11-19) - New Naming Convention & Light Mode Enforcement

**🎯 Major Changes:**

#### 1. Complete Naming Convention Overhaul
- **BREAKING**: Changed from `short/long` to `short/extended` for better clarity
- **BREAKING**: Changed from `extended` (theme) to `with_skills` for better clarity
- **NEW**: Version omitted from filename when `clean` (no skills sidebar)
- **NEW**: Language moved to end: `cv-{length}[-{version}]-{initials}-{year}-{lang}.pdf`
- **UPDATE**: Originally used `detailed/extended`, changed to `short/extended` for better contrast

**Old Naming Examples:**
- ❌ `cv-short-clean-es-jamr-2025.pdf` (v0)
- ❌ `cv-long-extended-en-jamr-2025.pdf` (v0)

**New Naming Examples:**
- ✅ `cv-short-jamr-2025-es.pdf` (version omitted, final naming)
- ✅ `cv-long-with-skills-jamr-2025-en.pdf` (version included)

#### 2. Light Mode Enforcement - Defense in Depth
**CRITICAL**: PDFs are now GUARANTEED to always use light mode, regardless of user's color theme preference.

**Three-Layer Protection:**
1. **Backend Cookie Enforcement** (`internal/handlers/cv.go:262-264`)
   - Forces `color-theme=light` cookie for all PDF generation requests
   - Ensures browser context starts in light mode

2. **CSS Print Media Query Override** (`static/css/08-contexts/_print.css:4-60`)
   - Forcibly overrides ALL CSS variables to light mode values
   - Uses `!important` to override any theme settings
   - Applies to `:root`, `[data-color-theme="dark"]`, `[data-color-theme="auto"]`

3. **Browser Print Directives** (`static/css/08-contexts/_print.css:65-69`)
   - `print-color-adjust: exact !important`
   - Ensures browsers render colors exactly as specified

**Why Three Layers?**
- Guarantees light mode even if cookies fail, JavaScript doesn't execute, or browser settings override
- Provides optimal print quality and reduced ink consumption
- Professional appearance in all contexts

#### 3. Backend Improvements
- **Added**: `time` package import to `internal/models/cv.go` for year placeholder system
- **Updated**: Parameter validation for new naming (`detailed`/`extended`, `clean`/`with_skills`)
- **Updated**: Filename generation logic with conditional version inclusion

#### 4. Frontend Updates
- **Updated**: PDF modal JavaScript to use new parameters
- **Added**: Legacy localStorage mapping for backwards compatibility
  - `long` → `extended`
  - `extended` (theme) → `with_skills`
  - Note: `short` now stays as `short` (no longer maps to `detailed`)

#### 5. Static Assets
- **Generated**: 4 new PDFs with correct naming convention (2.2 MB each)
  - `cv-short-jamr-2025-es.pdf` (updated from `cv-detailed`)
  - `cv-short-jamr-2025-en.pdf` (updated from `cv-detailed`)
  - `cv-long-with-skills-jamr-2025-es.pdf`
  - `cv-long-with-skills-jamr-2025-en.pdf`
- **Removed**: Old PDFs with deprecated naming (`cv-detailed-*`)

#### 6. Documentation
- **NEW**: "Print-Friendly Design: Light Mode Only" section
- **NEW**: Comprehensive multi-layer enforcement explanation
- **NEW**: Troubleshooting section for dark mode PDF issues
- **Updated**: All examples to use new naming convention
- **Updated**: Filename combinations matrix
- **Updated**: Design philosophy section

#### 7. Tests
- **Updated**: `24-pdf-download-params.test.mjs` with new parameter expectations
- **Note**: Test needs adjustments to handle PDF downloads (doesn't navigate page)

**Migration Path for Existing Users:**
- Old localStorage values automatically map to new naming
- No user action required - seamless transition
- Old PDFs can be regenerated with new naming using provided curl commands

**Benefits:**
- ✅ Clearer, more intuitive naming convention
- ✅ More professional filename format
- ✅ Bulletproof light mode enforcement
- ✅ Better print quality and ink efficiency
- ✅ Backwards compatible with existing user preferences
- ✅ Comprehensive documentation and troubleshooting

### Version 2.1.0 (2025-11-20) - Year-Aware Shortcut URLs

**🎯 New Features:**

#### Shortcut URLs for Default CV
- **NEW**: Memorable shortcut pattern `/cv-jamr-{year}-{lang}.pdf`
- **NEW**: Automatic year validation (only current year accepted)
- **NEW**: Auto-updates yearly without code changes
- **NEW**: "Default CV (Recommended)" option in PDF modal
- **Benefits**:
  - ✅ Easy to remember and share: `juan.andres.morenorub.io/cv-jamr-2025-en.pdf`
  - ✅ No complex query parameters
  - ✅ Professional, clean URLs
  - ✅ 301 redirect to proper PDF export endpoint

**Implementation:**
- Handler: `DefaultCVShortcut()` in `internal/handlers/cv.go:222-263`
- Route: Registered in `internal/routes/routes.go:17`
- Modal: "Default CV" option with visual highlighting (purple gradient, star emoji)
- Frontend: Dynamic year detection via JavaScript

**Testing:**
- ✅ Current year URLs (2025): 301 redirect to default PDF
- ✅ Past/future years: 404 Not Found
- ✅ Both languages supported (en, es)

---

**Last Updated**: 2025-11-20
**Version**: 2.1.0 (Year-Aware Shortcut URLs)
**Status**: Production ✅
**Maintainer**: Development Team