Spaces:

Aditya150
/

Veritas-AI

Sleeping

Veritas-AI / ui_implementation_plan.md

Aditya-Jadhav150

feat: implement AEGIS-AI v4 MSCVN 5-stream engine & UI/UX modular overhaul

f5125ca about 1 month ago

19.5 kB

# AEGIS-AI UI/UX Overhaul Plan

## Scope

Frontend-only changes. **Zero changes** to `core/`, `aegis/`, `app.py` routes, or the detection engine. The API contract (`/api/predict` JSON response) stays identical.

---

## Current Problems

| # | Problem | Impact |
|---|---|---|
| 1 | **83KB monolithic `index.html`** — 2,029 lines mixing HTML, CSS (~870 lines), and JS (~500 lines) | Unmaintainable, impossible to iterate on |
| 2 | **Fake 5.1-second scanning delay** — hardcoded `setTimeout` stages even if backend returns instantly | Users wait for nothing, feels sluggish |
| 3 | **Broken video preview** — video files assigned to `<img>` tag, shows broken icon | Critical bug |
| 4 | **Vertical scroll wall** — all result cards stacked in one endless column | Overwhelming, key findings buried |
| 5 | **Static heatmaps** — ELA/FFT/Attention shown as plain images in tabs | No comparison with original, hard to interpret |
| 6 | **No export capability** — no PDF report, no JSON download, no share link | Useless for actual forensic workflows |
| 7 | **No audio visualization** — just text numbers for audio analysis | Misses opportunity to show spectrogram |
| 8 | **Orphaned `main.css`** — 379-line stylesheet exists but is never linked | Wasted work |
| 9 | **XGBoost Fusion badge in nav** — references old pipeline, misleading | Outdated branding |

---

## Design Direction

Keep the **cyberpunk glassmorphism dark theme** — it's striking and fits a security/forensics tool. But refine it:

- **Reduce visual noise**: Fewer glowing borders, more whitespace between sections
- **Information hierarchy**: Verdict + evidence summary visible immediately, deep metrics available on demand
- **Progressive disclosure**: Collapsed sections that expand, not a wall of everything at once
- **Interactivity**: Heatmap overlays, audio waveforms, video timeline — make the data explorable

---

## Proposed Changes

### 1. Modularize the Codebase

Split the monolithic `index.html` into clean, maintainable files:

```
templates/
  └── index.html              # Clean HTML structure only (~300 lines)
static/
  ├── css/
  │   ├── variables.css       # CSS custom properties (colors, spacing, fonts)
  │   ├── base.css            # Reset, typography, layout grid
  │   ├── components.css      # Cards, badges, buttons, modals, toasts
  │   ├── upload.css           # Drop zone, preview, scan overlay
  │   ├── results.css          # Verdict, heatmaps, metrics, evidence
  │   └── responsive.css      # Media queries (900px, 768px, 600px, 480px)
  │
  └── js/
      ├── upload.js            # File handling, drag-drop, preview rendering
      ├── analysis.js          # API call, progress tracking, result rendering
      ├── heatmap-viewer.js    # Interactive heatmap overlay slider
      ├── audio-viewer.js      # Audio waveform + spectrogram canvas
      ├── video-timeline.js    # Video frame scrubber with risk bars
      ├── export.js            # PDF/JSON report generation
      ├── settings.js          # Profile, username, opt-in toggles
      └── utils.js             # Toast system, metric scaling, helpers
```

> [!IMPORTANT]
> The HTML goes from **2,029 lines → ~300 lines**. Each JS/CSS file has a single responsibility.

---

### 2. Fix Video Preview Bug

**Current**: `FileReader.readAsDataURL` feeds into `<img>` tag → broken for video.

**Fix**: Detect media type from file, dynamically create `<video>` or `<img>`:

```javascript
// upload.js
if (file.type.startsWith('video/')) {
    const videoEl = document.createElement('video');
    videoEl.src = URL.createObjectURL(file);
    videoEl.muted = true;
    videoEl.autoplay = true;
    videoEl.loop = true;
    previewContainer.replaceChild(videoEl, previewImg);
} else if (file.type.startsWith('audio/')) {
    // Show audio waveform preview (Web Audio API)
} else {
    previewImg.src = URL.createObjectURL(file);
}
```

---

### 3. Replace Fake Delay with Real Progress Tracking

**Current**: 6 hardcoded `setTimeout` stages (total 5.1s) regardless of actual backend speed.

**Fix**: Use **Server-Sent Events (SSE)** or a simple polling approach. But since the backend is a single POST request, we'll do this:

- Show a **single clean progress indicator** (not 6 fake stages)
- Start a real timer showing actual elapsed time
- Display the result **immediately** when the backend responds
- If the backend takes >2 seconds, show a pulsing "Analyzing..." state with the real elapsed time

```javascript
// analysis.js
const startTime = performance.now();
const timerInterval = setInterval(() => {
    elapsed.textContent = ((performance.now() - startTime) / 1000).toFixed(1) + 's';
}, 100);
const response = await fetch('/api/predict', { ... });
clearInterval(timerInterval);
renderResults(await response.json()); // Instant — no fake delay
```

---

### 4. Redesign Results Layout — Progressive Disclosure

**Current**: 11 cards stacked vertically — overwhelming scroll wall.

**New layout**: **3-tier progressive disclosure**

```
┌─────────────────────────────────────────────────────────────┐
│  TIER 1: VERDICT (always visible)                           │
│  ┌─────────────────────────────────────────────────────┐    │
│  │  DEEPFAKE DETECTED   97%   HIGH RISK                │    │
│  │  Evidence: "Primary ViT: 96.5% fake probability"    │    │
│  │  [Download Report]  [Share]  [Analyze Another]      │    │
│  └─────────────────────────────────────────────────────┘    │
├─────────────────────────────────────────────────────────────┤
│  TIER 2: VISUAL EVIDENCE (expandable, open by default)      │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐      │
│  │   Original    │  │  Aligned     │  │  Heatmap     │      │
│  │   Preview     │  │  Face Crop   │  │  Overlay     │      │
│  │              │  │              │  │  [Slider]    │      │
│  └──────────────┘  └──────────────┘  └──────────────┘      │
│                                                             │
│  Confidence Breakdown (animated bars)                       │
├─────────────────────────────────────────────────────────────┤
│  TIER 3: DEEP FORENSICS (collapsed by default, expandable)  │
│                                                             │
│  ▸ Ensemble Model Breakdown                                 │
│  ▸ Metadata & Provenance Analysis                           │
│  ▸ 9 Forensic Metrics                                       │
│  ▸ Audio Analysis                    (only if audio exists) │
│  ▸ Temporal / Video Analysis         (only if video)        │
│  ▸ Processing Performance Stats                             │
└─────────────────────────────────────────────────────────────┘
```

- **Tier 1** answers "is it fake?" in 1 second of reading
- **Tier 2** shows visual proof — the heatmaps and confidence bars
- **Tier 3** is for deep investigation — collapsed by default, click to expand any section

---

### 5. Interactive Heatmap Overlay Slider

**Current**: Static images in tabs (ELA, Frequency, Attention).

**New**: A **before/after slider** that lets users drag to compare original vs heatmap:

```
┌────────────────────────────────┐
│  Original    ◄═══╪═══►  ELA   │
│              drag slider       │
│  [ELA] [FFT] [Attention]      │
│  Opacity: ████████░░ 80%      │
└────────────────────────────────┘
```

- **Drag slider** reveals original on left, heatmap on right
- **Opacity control** lets user blend heatmap over original
- **Tab switching** swaps between ELA / FFT / Attention
- Pure CSS + JS — no library needed (CSS `clip-path` on drag)

---

### 6. Forensic Report Export

Add export capabilities — critical for a real forensic tool:

#### A. JSON Download
```javascript
// export.js
function downloadJSON(data) {
    const blob = new Blob([JSON.stringify(data, null, 2)], { type: 'application/json' });
    const url = URL.createObjectURL(blob);
    // trigger download: AEGIS_Report_2026-08-18_142305.json
}
```

#### B. PDF Report (client-side via html2canvas + jsPDF)
```
┌──────────────────────────────────────┐
│  AEGIS-AI FORENSIC ANALYSIS REPORT   │
│  Date: 2026-08-18 14:23:05 IST       │
│  File: suspicious_image.jpg          │
│  SHA-256: a3f2b1c9...               │
│                                      │
│  VERDICT: DEEPFAKE DETECTED (97%)    │
│  Risk Level: HIGH                    │
│                                      │
│  Evidence Summary:                   │
│  • Primary ViT: 96.5% fake          │
│  • Metadata: Midjourney signature    │
│                                      │
│  [Heatmap images embedded]           │
│  [Confidence breakdown chart]        │
│  [9 forensic metrics table]          │
│                                      │
│  Generated by AEGIS-AI v4            │
└──────────────────────────────────────┘
```

#### C. Share Link (copy to clipboard)
- Encode verdict + score into a shareable URL hash
- Not the full report — just a summary card

---

### 7. Audio Waveform & Spectrogram Visualizer

**Current**: Plain text showing "Audio Verdict: FAKE, Confidence: 88.5%".

**New**: Interactive audio player with visual waveform:

```
┌──────────────────────────────────────────────┐
│  🔊 Audio Analysis                           │
│                                              │
│  ┌──────────────────────────────────────┐    │
│  │  ▁▂▃▅▇█▇▅▃▂▁▂▃▅▇█▇▅▃▂▁▂▃▅▇        │    │
│  │  ◄━━━━━━━━━━━━━━━━━━━━━━━━━━►       │    │
│  │  0:00                    0:05        │    │
│  │       [▶ Play]  [Pause]              │    │
│  └──────────────────────────────────────┘    │
│                                              │
│  Verdict: SYNTHETIC VOICE DETECTED           │
│  Confidence: 88.5%                           │
│  Segments Analyzed: 3                        │
│  Synthetic segments highlighted in red ━━    │
└──────────────────────────────────────────────┘
```

- Uses **Web Audio API** + `<canvas>` for waveform rendering
- Color-coded segments: green (real) vs red (synthetic)
- Requires backend to return the extracted audio file path (already does via `ffmpeg`)

---

### 8. Video Timeline Scrubber

**Current**: Video results show aggregate stats only — no per-frame view.

**New**: Color-coded timeline bar showing per-frame risk:

```
┌──────────────────────────────────────────────┐
│  🎬 Video Temporal Analysis                  │
│                                              │
│  Frame Risk Timeline:                        │
│  ┌──────────────────────────────────────┐    │
│  │ ██░░██████░░░░██████████░░░░░░████  │    │
│  │ ▲ green=real  red=fake              │    │
│  └──────────────────────────────────────┘    │
│  Frame 7/12  |  Fake Prob: 92.4%             │
│                                              │
│  Identity Tracking:                          │
│  ┌────┬────────┬──────┬─────────┐            │
│  │ ID │ Frames │ Prob │ Verdict │            │
│  ├────┼────────┼──────┼─────────┤            │
│  │ 1  │ 10     │ 92%  │ FAKE    │            │
│  └────┴────────┴──────┴─────────┘            │
└──────────────────────────────────────────────┘
```

- Clickable timeline bar — click any segment to jump to that frame's analysis
- Color gradient from green (real) to red (fake) per frame
- Uses existing `temporal_analysis.identities` data from API

---

### 9. Visual Polish & Micro-Interactions

| Change | Detail |
|---|---|
| **Remove XGBoost badge** | Replace with `MSCVN Engine` or just `v4` when new model ships |
| **Smooth card transitions** | Cards slide in with staggered `animation-delay` on result load |
| **Skeleton loading states** | Show grey pulsing placeholder cards while waiting for results |
| **Verdict animation** | Score counts up from 0% to final value (CSS counter animation) |
| **Tooltip cleanup** | Standardize all 9 metric tooltips with consistent formatting |
| **Scroll-to-verdict** | Auto-scroll right panel to verdict banner when results arrive |
| **Keyboard shortcuts** | `Ctrl+U` = upload, `Ctrl+E` = export, `Escape` = discard |
| **File size limit indicator** | Show max upload size and file type icons in drop zone |

---

### 10. Updated Nav Branding

```
Before:  🔍 AEGIS-AI  [XGBoost Fusion]
After:   🛡️ AEGIS-AI  [Forensic Engine v4]
```

- Update badge text to reflect current/new engine
- Keep the admin link and operator pill unchanged

---

## Files Changed

| File | Action | Description |
|---|---|---|
| `templates/index.html` | **REWRITE** | Strip down to ~300 lines of clean HTML structure |
| `static/css/variables.css` | **NEW** | CSS custom properties |
| `static/css/base.css` | **NEW** | Reset, typography, grid layout |
| `static/css/components.css` | **NEW** | Cards, badges, buttons, modals |
| `static/css/upload.css` | **NEW** | Drop zone, preview states |
| `static/css/results.css` | **NEW** | Verdict, heatmaps, metrics, evidence |
| `static/css/responsive.css` | **NEW** | Mobile breakpoints |
| `static/js/upload.js` | **NEW** | File handling, drag-drop, preview |
| `static/js/analysis.js` | **NEW** | API call, real progress, result rendering |
| `static/js/heatmap-viewer.js` | **NEW** | Interactive overlay slider |
| `static/js/audio-viewer.js` | **NEW** | Waveform + spectrogram canvas |
| `static/js/video-timeline.js` | **NEW** | Timeline scrubber with risk bars |
| `static/js/export.js` | **NEW** | PDF + JSON report generation |
| `static/js/settings.js` | **NEW** | Profile modal logic |
| `static/js/utils.js` | **NEW** | Toasts, metric scaling, helpers |
| `static/css/main.css` | **DELETE** | Orphaned file, never linked |
| `templates/login.html` | **MINOR** | Link to new CSS variables for consistency |
| `templates/admin.html` | **MINOR** | Link to new CSS variables for consistency |
| `app.py` | **NO CHANGE** | Zero backend changes |
| `core/*` | **NO CHANGE** | Zero detection engine changes |

---

## What This Does NOT Change

- ❌ No changes to `app.py` routes or API contract
- ❌ No changes to `core/` detection modules
- ❌ No changes to the model or inference pipeline
- ❌ No changes to database schema or auth flow
- ❌ No changes to `Dockerfile` or `requirements.txt`

---

## Build Order

### Step 1 — Extract & Modularize (Foundation)
- [ ] Create CSS files from inline styles in `index.html`
- [ ] Create JS files from inline scripts
- [ ] Rewrite `index.html` as clean HTML linking external CSS/JS
- [ ] Verify everything renders identically to current state

### Step 2 — Fix Critical Bugs
- [ ] Fix video preview (use `<video>` element for video files)
- [ ] Remove fake scanning delay — show real elapsed time
- [ ] Fix orphaned `main.css` (delete it)

### Step 3 — Results Layout Redesign
- [ ] Implement 3-tier progressive disclosure layout
- [ ] Add collapsible accordion sections for Tier 3
- [ ] Smooth card entrance animations
- [ ] Skeleton loading states
- [ ] Score count-up animation

### Step 4 — Interactive Heatmap Viewer
- [ ] Build before/after drag slider component
- [ ] Add opacity blend control
- [ ] Tab switching between ELA / FFT / Attention

### Step 5 — Export & Reporting
- [ ] JSON download button
- [ ] PDF report generation (html2canvas + jsPDF)
- [ ] Copy-to-clipboard share summary

### Step 6 — Audio & Video Enhancements
- [ ] Audio waveform canvas renderer (Web Audio API)
- [ ] Color-coded synthetic segment highlighting
- [ ] Video timeline scrubber with per-frame risk bars
- [ ] Clickable frame selection

### Step 7 — Polish & Ship
- [ ] Update nav branding
- [ ] Keyboard shortcuts
- [ ] Final responsive testing (mobile, tablet, desktop)
- [ ] Cross-browser testing (Chrome, Firefox, Edge)
- [ ] Push to GitHub → Deploy to HF Spaces

---

## Verification Plan

### Visual Testing
- Upload a known real image → verify REAL verdict renders correctly with green theme
- Upload a known fake image → verify FAKE verdict renders with red theme + all heatmaps
- Upload a video → verify video preview, temporal timeline, identity table
- Upload an audio file → verify waveform visualization renders
- Test on mobile viewport (Chrome DevTools responsive mode)

### Functional Testing
- Heatmap slider: drag left/right, verify clip-path updates smoothly
- Export JSON: download and verify JSON matches API response
- Export PDF: generate and verify all sections render in PDF
- Collapsible sections: expand/collapse each Tier 3 section
- Keyboard shortcuts: `Ctrl+U`, `Ctrl+E`, `Escape`

### Regression Testing
- Verify `/api/predict` response is consumed correctly (no JSON key mismatches)
- Verify login/logout flow unchanged
- Verify admin panel unchanged
- Verify settings modal (username change, opt-in toggle) works

	# AEGIS-AI UI/UX Overhaul Plan

	## Scope

	Frontend-only changes. Zero changes to `core/`, `aegis/`, `app.py` routes, or the detection engine. The API contract (`/api/predict` JSON response) stays identical.

	---

	## Current Problems

	\| # \| Problem \| Impact \|
	\|---\|---\|---\|
	\| 1 \| 83KB monolithic `index.html` — 2,029 lines mixing HTML, CSS (~870 lines), and JS (~500 lines) \| Unmaintainable, impossible to iterate on \|
	\| 2 \| Fake 5.1-second scanning delay — hardcoded `setTimeout` stages even if backend returns instantly \| Users wait for nothing, feels sluggish \|
	\| 3 \| Broken video preview — video files assigned to `<img>` tag, shows broken icon \| Critical bug \|
	\| 4 \| Vertical scroll wall — all result cards stacked in one endless column \| Overwhelming, key findings buried \|
	\| 5 \| Static heatmaps — ELA/FFT/Attention shown as plain images in tabs \| No comparison with original, hard to interpret \|
	\| 6 \| No export capability — no PDF report, no JSON download, no share link \| Useless for actual forensic workflows \|
	\| 7 \| No audio visualization — just text numbers for audio analysis \| Misses opportunity to show spectrogram \|
	\| 8 \| Orphaned `main.css` — 379-line stylesheet exists but is never linked \| Wasted work \|
	\| 9 \| XGBoost Fusion badge in nav — references old pipeline, misleading \| Outdated branding \|

	---

	## Design Direction

	Keep the cyberpunk glassmorphism dark theme — it's striking and fits a security/forensics tool. But refine it:

	- Reduce visual noise: Fewer glowing borders, more whitespace between sections
	- Information hierarchy: Verdict + evidence summary visible immediately, deep metrics available on demand
	- Progressive disclosure: Collapsed sections that expand, not a wall of everything at once
	- Interactivity: Heatmap overlays, audio waveforms, video timeline — make the data explorable

	---

	## Proposed Changes

	### 1. Modularize the Codebase

	Split the monolithic `index.html` into clean, maintainable files:

	```
	templates/
	└── index.html # Clean HTML structure only (~300 lines)

	static/
	├── css/
	│ ├── variables.css # CSS custom properties (colors, spacing, fonts)
	│ ├── base.css # Reset, typography, layout grid
	│ ├── components.css # Cards, badges, buttons, modals, toasts
	│ ├── upload.css # Drop zone, preview, scan overlay
	│ ├── results.css # Verdict, heatmaps, metrics, evidence
	│ └── responsive.css # Media queries (900px, 768px, 600px, 480px)
	│
	└── js/
	├── upload.js # File handling, drag-drop, preview rendering
	├── analysis.js # API call, progress tracking, result rendering
	├── heatmap-viewer.js # Interactive heatmap overlay slider
	├── audio-viewer.js # Audio waveform + spectrogram canvas
	├── video-timeline.js # Video frame scrubber with risk bars
	├── export.js # PDF/JSON report generation
	├── settings.js # Profile, username, opt-in toggles
	└── utils.js # Toast system, metric scaling, helpers
	```

	> [!IMPORTANT]
	> The HTML goes from 2,029 lines → ~300 lines. Each JS/CSS file has a single responsibility.

	---

	### 2. Fix Video Preview Bug

	Current: `FileReader.readAsDataURL` feeds into `<img>` tag → broken for video.

	Fix: Detect media type from file, dynamically create `<video>` or `<img>`:

	```javascript
	// upload.js
	if (file.type.startsWith('video/')) {
	const videoEl = document.createElement('video');
	videoEl.src = URL.createObjectURL(file);
	videoEl.muted = true;
	videoEl.autoplay = true;
	videoEl.loop = true;
	previewContainer.replaceChild(videoEl, previewImg);
	} else if (file.type.startsWith('audio/')) {
	// Show audio waveform preview (Web Audio API)
	} else {
	previewImg.src = URL.createObjectURL(file);
	}
	```

	---

	### 3. Replace Fake Delay with Real Progress Tracking

	Current: 6 hardcoded `setTimeout` stages (total 5.1s) regardless of actual backend speed.

	Fix: Use Server-Sent Events (SSE) or a simple polling approach. But since the backend is a single POST request, we'll do this:

	- Show a single clean progress indicator (not 6 fake stages)
	- Start a real timer showing actual elapsed time
	- Display the result immediately when the backend responds
	- If the backend takes >2 seconds, show a pulsing "Analyzing..." state with the real elapsed time

	```javascript
	// analysis.js
	const startTime = performance.now();
	const timerInterval = setInterval(() => {
	elapsed.textContent = ((performance.now() - startTime) / 1000).toFixed(1) + 's';
	}, 100);

	const response = await fetch('/api/predict', { ... });
	clearInterval(timerInterval);
	renderResults(await response.json()); // Instant — no fake delay
	```

	---

	### 4. Redesign Results Layout — Progressive Disclosure

	Current: 11 cards stacked vertically — overwhelming scroll wall.

	New layout: 3-tier progressive disclosure

	```
	┌─────────────────────────────────────────────────────────────┐
	│ TIER 1: VERDICT (always visible) │
	│ ┌─────────────────────────────────────────────────────┐ │
	│ │ DEEPFAKE DETECTED 97% HIGH RISK │ │
	│ │ Evidence: "Primary ViT: 96.5% fake probability" │ │
	│ │ [Download Report] [Share] [Analyze Another] │ │
	│ └─────────────────────────────────────────────────────┘ │
	├─────────────────────────────────────────────────────────────┤
	│ TIER 2: VISUAL EVIDENCE (expandable, open by default) │
	│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
	│ │ Original │ │ Aligned │ │ Heatmap │ │
	│ │ Preview │ │ Face Crop │ │ Overlay │ │
	│ │ │ │ │ │ [Slider] │ │
	│ └──────────────┘ └──────────────┘ └──────────────┘ │
	│ │
	│ Confidence Breakdown (animated bars) │
	├─────────────────────────────────────────────────────────────┤
	│ TIER 3: DEEP FORENSICS (collapsed by default, expandable) │
	│ │
	│ ▸ Ensemble Model Breakdown │
	│ ▸ Metadata & Provenance Analysis │
	│ ▸ 9 Forensic Metrics │
	│ ▸ Audio Analysis (only if audio exists) │
	│ ▸ Temporal / Video Analysis (only if video) │
	│ ▸ Processing Performance Stats │
	└─────────────────────────────────────────────────────────────┘
	```

	- Tier 1 answers "is it fake?" in 1 second of reading
	- Tier 2 shows visual proof — the heatmaps and confidence bars
	- Tier 3 is for deep investigation — collapsed by default, click to expand any section

	---

	### 5. Interactive Heatmap Overlay Slider

	Current: Static images in tabs (ELA, Frequency, Attention).

	New: A before/after slider that lets users drag to compare original vs heatmap:

	```
	┌────────────────────────────────┐
	│ Original ◄═══╪═══► ELA │
	│ drag slider │
	│ [ELA] [FFT] [Attention] │
	│ Opacity: ████████░░ 80% │
	└────────────────────────────────┘
	```

	- Drag slider reveals original on left, heatmap on right
	- Opacity control lets user blend heatmap over original
	- Tab switching swaps between ELA / FFT / Attention
	- Pure CSS + JS — no library needed (CSS `clip-path` on drag)

	---

	### 6. Forensic Report Export

	Add export capabilities — critical for a real forensic tool:

	#### A. JSON Download
	```javascript
	// export.js
	function downloadJSON(data) {
	const blob = new Blob([JSON.stringify(data, null, 2)], { type: 'application/json' });
	const url = URL.createObjectURL(blob);
	// trigger download: AEGIS_Report_2026-08-18_142305.json
	}
	```

	#### B. PDF Report (client-side via html2canvas + jsPDF)
	```
	┌──────────────────────────────────────┐
	│ AEGIS-AI FORENSIC ANALYSIS REPORT │
	│ Date: 2026-08-18 14:23:05 IST │
	│ File: suspicious_image.jpg │
	│ SHA-256: a3f2b1c9... │
	│ │
	│ VERDICT: DEEPFAKE DETECTED (97%) │
	│ Risk Level: HIGH │
	│ │
	│ Evidence Summary: │
	│ • Primary ViT: 96.5% fake │
	│ • Metadata: Midjourney signature │
	│ │
	│ [Heatmap images embedded] │
	│ [Confidence breakdown chart] │
	│ [9 forensic metrics table] │
	│ │
	│ Generated by AEGIS-AI v4 │
	└──────────────────────────────────────┘
	```

	#### C. Share Link (copy to clipboard)
	- Encode verdict + score into a shareable URL hash
	- Not the full report — just a summary card

	---

	### 7. Audio Waveform & Spectrogram Visualizer

	Current: Plain text showing "Audio Verdict: FAKE, Confidence: 88.5%".

	New: Interactive audio player with visual waveform:

	```
	┌──────────────────────────────────────────────┐
	│ 🔊 Audio Analysis │
	│ │
	│ ┌──────────────────────────────────────┐ │
	│ │ ▁▂▃▅▇█▇▅▃▂▁▂▃▅▇█▇▅▃▂▁▂▃▅▇ │ │
	│ │ ◄━━━━━━━━━━━━━━━━━━━━━━━━━━► │ │
	│ │ 0:00 0:05 │ │
	│ │ [▶ Play] [Pause] │ │
	│ └──────────────────────────────────────┘ │
	│ │
	│ Verdict: SYNTHETIC VOICE DETECTED │
	│ Confidence: 88.5% │
	│ Segments Analyzed: 3 │
	│ Synthetic segments highlighted in red ━━ │
	└──────────────────────────────────────────────┘
	```

	- Uses Web Audio API + `<canvas>` for waveform rendering
	- Color-coded segments: green (real) vs red (synthetic)
	- Requires backend to return the extracted audio file path (already does via `ffmpeg`)

	---

	### 8. Video Timeline Scrubber

	Current: Video results show aggregate stats only — no per-frame view.

	New: Color-coded timeline bar showing per-frame risk:

	```
	┌──────────────────────────────────────────────┐
	│ 🎬 Video Temporal Analysis │
	│ │
	│ Frame Risk Timeline: │
	│ ┌──────────────────────────────────────┐ │
	│ │ ██░░██████░░░░██████████░░░░░░████ │ │
	│ │ ▲ green=real red=fake │ │
	│ └──────────────────────────────────────┘ │
	│ Frame 7/12 \| Fake Prob: 92.4% │
	│ │
	│ Identity Tracking: │
	│ ┌────┬────────┬──────┬─────────┐ │
	│ │ ID │ Frames │ Prob │ Verdict │ │
	│ ├────┼────────┼──────┼─────────┤ │
	│ │ 1 │ 10 │ 92% │ FAKE │ │
	│ └────┴────────┴──────┴─────────┘ │
	└──────────────────────────────────────────────┘
	```

	- Clickable timeline bar — click any segment to jump to that frame's analysis
	- Color gradient from green (real) to red (fake) per frame
	- Uses existing `temporal_analysis.identities` data from API

	---

	### 9. Visual Polish & Micro-Interactions

	\| Change \| Detail \|
	\|---\|---\|
	\| Remove XGBoost badge \| Replace with `MSCVN Engine` or just `v4` when new model ships \|
	\| Smooth card transitions \| Cards slide in with staggered `animation-delay` on result load \|
	\| Skeleton loading states \| Show grey pulsing placeholder cards while waiting for results \|
	\| Verdict animation \| Score counts up from 0% to final value (CSS counter animation) \|
	\| Tooltip cleanup \| Standardize all 9 metric tooltips with consistent formatting \|
	\| Scroll-to-verdict \| Auto-scroll right panel to verdict banner when results arrive \|
	\| Keyboard shortcuts \| `Ctrl+U` = upload, `Ctrl+E` = export, `Escape` = discard \|
	\| File size limit indicator \| Show max upload size and file type icons in drop zone \|

	---

	### 10. Updated Nav Branding

	```
	Before: 🔍 AEGIS-AI [XGBoost Fusion]
	After: 🛡️ AEGIS-AI [Forensic Engine v4]
	```

	- Update badge text to reflect current/new engine
	- Keep the admin link and operator pill unchanged

	---

	## Files Changed

	\| File \| Action \| Description \|
	\|---\|---\|---\|
	\| `templates/index.html` \| REWRITE \| Strip down to ~300 lines of clean HTML structure \|
	\| `static/css/variables.css` \| NEW \| CSS custom properties \|
	\| `static/css/base.css` \| NEW \| Reset, typography, grid layout \|
	\| `static/css/components.css` \| NEW \| Cards, badges, buttons, modals \|
	\| `static/css/upload.css` \| NEW \| Drop zone, preview states \|
	\| `static/css/results.css` \| NEW \| Verdict, heatmaps, metrics, evidence \|
	\| `static/css/responsive.css` \| NEW \| Mobile breakpoints \|
	\| `static/js/upload.js` \| NEW \| File handling, drag-drop, preview \|
	\| `static/js/analysis.js` \| NEW \| API call, real progress, result rendering \|
	\| `static/js/heatmap-viewer.js` \| NEW \| Interactive overlay slider \|
	\| `static/js/audio-viewer.js` \| NEW \| Waveform + spectrogram canvas \|
	\| `static/js/video-timeline.js` \| NEW \| Timeline scrubber with risk bars \|
	\| `static/js/export.js` \| NEW \| PDF + JSON report generation \|
	\| `static/js/settings.js` \| NEW \| Profile modal logic \|
	\| `static/js/utils.js` \| NEW \| Toasts, metric scaling, helpers \|
	\| `static/css/main.css` \| DELETE \| Orphaned file, never linked \|
	\| `templates/login.html` \| MINOR \| Link to new CSS variables for consistency \|
	\| `templates/admin.html` \| MINOR \| Link to new CSS variables for consistency \|
	\| `app.py` \| NO CHANGE \| Zero backend changes \|
	\| `core/` \| NO CHANGE* \| Zero detection engine changes \|

	---

	## What This Does NOT Change

	- ❌ No changes to `app.py` routes or API contract
	- ❌ No changes to `core/` detection modules
	- ❌ No changes to the model or inference pipeline
	- ❌ No changes to database schema or auth flow
	- ❌ No changes to `Dockerfile` or `requirements.txt`

	---

	## Build Order

	### Step 1 — Extract & Modularize (Foundation)
	- [ ] Create CSS files from inline styles in `index.html`
	- [ ] Create JS files from inline scripts
	- [ ] Rewrite `index.html` as clean HTML linking external CSS/JS
	- [ ] Verify everything renders identically to current state

	### Step 2 — Fix Critical Bugs
	- [ ] Fix video preview (use `<video>` element for video files)
	- [ ] Remove fake scanning delay — show real elapsed time
	- [ ] Fix orphaned `main.css` (delete it)

	### Step 3 — Results Layout Redesign
	- [ ] Implement 3-tier progressive disclosure layout
	- [ ] Add collapsible accordion sections for Tier 3
	- [ ] Smooth card entrance animations
	- [ ] Skeleton loading states
	- [ ] Score count-up animation

	### Step 4 — Interactive Heatmap Viewer
	- [ ] Build before/after drag slider component
	- [ ] Add opacity blend control
	- [ ] Tab switching between ELA / FFT / Attention

	### Step 5 — Export & Reporting
	- [ ] JSON download button
	- [ ] PDF report generation (html2canvas + jsPDF)
	- [ ] Copy-to-clipboard share summary

	### Step 6 — Audio & Video Enhancements
	- [ ] Audio waveform canvas renderer (Web Audio API)
	- [ ] Color-coded synthetic segment highlighting
	- [ ] Video timeline scrubber with per-frame risk bars
	- [ ] Clickable frame selection

	### Step 7 — Polish & Ship
	- [ ] Update nav branding
	- [ ] Keyboard shortcuts
	- [ ] Final responsive testing (mobile, tablet, desktop)
	- [ ] Cross-browser testing (Chrome, Firefox, Edge)
	- [ ] Push to GitHub → Deploy to HF Spaces

	---

	## Verification Plan

	### Visual Testing
	- Upload a known real image → verify REAL verdict renders correctly with green theme
	- Upload a known fake image → verify FAKE verdict renders with red theme + all heatmaps
	- Upload a video → verify video preview, temporal timeline, identity table
	- Upload an audio file → verify waveform visualization renders
	- Test on mobile viewport (Chrome DevTools responsive mode)

	### Functional Testing
	- Heatmap slider: drag left/right, verify clip-path updates smoothly
	- Export JSON: download and verify JSON matches API response
	- Export PDF: generate and verify all sections render in PDF
	- Collapsible sections: expand/collapse each Tier 3 section
	- Keyboard shortcuts: `Ctrl+U`, `Ctrl+E`, `Escape`

	### Regression Testing
	- Verify `/api/predict` response is consumed correctly (no JSON key mismatches)
	- Verify login/logout flow unchanged
	- Verify admin panel unchanged
	- Verify settings modal (username change, opt-in toggle) works