# HTML Output Format

Renacer provides HTML output format for generating rich visual trace reports with styled tables, embedded CSS, and interactive features.

> **TDD-Verified:** All examples validated by [`tests/sprint22_html_output_tests.rs`](../../../tests/sprint22_html_output_tests.rs)

## Overview

HTML output format generates standalone HTML documents containing syscall trace data in a visually appealing, interactive format:

- **Standalone Documents:** Self-contained HTML with embedded CSS (no external dependencies)
- **Responsive Design:** Modern CSS with hover effects and zebra striping
- **XSS Prevention:** Automatic HTML escaping for security
- **Statistics Integration:** Combined with `-c` flag for visual statistics tables
- **Optional Columns:** Timing (-T) and source location (--source) support
- **Error Highlighting:** Visual distinction for failed syscalls

## Basic Usage

### Generate HTML Report

```bash
renacer --format html -- ls -la > trace.html
```

**Tested by:** `test_html_format_flag_accepted`, `test_html_output_basic`

This generates a complete HTML document with:
- Syscall trace table
- Embedded CSS styles
- Responsive layout

### View HTML Report

```bash
# Generate and open in browser
renacer --format html -- cargo test > report.html
xdg-open report.html  # Linux
open report.html      # macOS
```

**Tested by:** `test_html_output_basic`

## HTML Document Structure

### Basic HTML Output

```bash
$ renacer --format html -- echo "test" > trace.html
```

**Generated HTML:**

```html
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Renacer Trace Report</title>
    <style>
        /* Embedded CSS styles */
        body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; }
        table { border-collapse: collapse; width: 100%; }
        th { background-color: #4a90d9; color: white; }
        ...
    </style>
</head>
<body>
    <h1>Syscall Trace Report</h1>
    <table>
        <tr><th>Syscall</th><th>Arguments</th><th>Result</th></tr>
        <tr><td class="syscall">write</td><td class="args">1, "test\n", 5</td><td class="result">5</td></tr>
        <tr><td class="syscall">exit_group</td><td class="args">0</td><td class="result">?</td></tr>
    </table>
    <div class="footer">Generated by Renacer - System Call Tracer</div>
</body>
</html>
```

**Tested by:** `test_html_output_basic`, `test_html_output_contains_syscalls`

## Integration with Flags

### With Statistics Mode (-c)

```bash
renacer --format html -c -- cargo build > build-stats.html
```

**Tested by:** `test_html_output_with_statistics`

**Output includes:**

1. **Syscall Trace Table** - Individual syscall events
2. **Statistics Summary Table** - Call counts, timing, errors

```html
<h2>Statistics Summary</h2>
<table class="stats-table">
    <tr><th>% time</th><th>seconds</th><th>usecs/call</th><th>calls</th><th>errors</th><th>syscall</th></tr>
    <tr><td>45.23</td><td>0.012345</td><td>1234</td><td>10</td><td>0</td><td class="syscall">read</td></tr>
    <tr><td>32.15</td><td>0.008765</td><td>876</td><td>10</td><td>0</td><td class="syscall">write</td></tr>
</table>
```

### With Timing Mode (-T)

```bash
renacer --format html -T -- ./my-app > trace-timing.html
```

**Tested by:** `test_html_output_with_timing`

**Output includes Duration column:**

```html
<table>
    <tr><th>Syscall</th><th>Arguments</th><th>Result</th><th>Duration</th></tr>
    <tr><td class="syscall">write</td><td class="args">...</td><td>5</td><td class="duration">1234 us</td></tr>
</table>
```

### With Filtering (-e)

```bash
renacer --format html -e trace=file -- ./app > file-ops.html
```

**Tested by:** `test_html_output_with_filtering`

HTML output includes only filtered syscalls (e.g., `open`, `read`, `write`, `close` for `trace=file`).

### With Source Correlation (--source)

```bash
renacer --format html --source -- ./my-binary > trace-with-source.html
```

**Output includes Source column:**

```html
<table>
    <tr><th>Syscall</th><th>Arguments</th><th>Result</th><th>Source</th></tr>
    <tr><td class="syscall">write</td><td>...</td><td>5</td><td class="source">src/main.rs:42</td></tr>
</table>
```

## CSS Styling and Visual Features

### Embedded CSS Styles

HTML output includes embedded CSS for:

- **Modern Font Stack:** `-apple-system`, `BlinkMacSystemFont`, `Segoe UI`, `Roboto`
- **Table Styling:** Borders, padding, box-shadow
- **Zebra Striping:** Alternating row colors (`nth-child(even)`)
- **Hover Effects:** Row highlighting on mouse hover
- **Color Coding:**
  - Syscall names: Blue (`#0066cc`)
  - Error results: Red (`#cc0000`)
  - Source locations: Gray (`#888`)

**Tested by:** `test_html_output_standalone`

### Standalone Output

HTML output is **completely standalone** with:
- ✅ Embedded CSS (no external stylesheet links)
- ✅ No JavaScript dependencies
- ✅ No external fonts or images
- ✅ Single-file distribution

**Tested by:** `test_html_output_standalone`

This ensures HTML reports can be:
- Shared via email
- Archived offline
- Opened without internet connection

## Security Features

### XSS Prevention

HTML output **automatically escapes** special characters to prevent XSS attacks:

```bash
$ renacer --format html -- echo "<script>alert('xss')</script>" > safe.html
```

**Tested by:** `test_html_output_escape_special_chars`

**Escaped characters:**
- `<` → `&lt;`
- `>` → `&gt;`
- `&` → `&amp;`
- `"` → `&quot;`
- `'` → `&#39;`

**Example output:**

```html
<td class="args">&lt;script&gt;alert(&#39;xss&#39;)&lt;/script&gt;</td>
```

The HTML output will display `<script>alert('xss')</script>` as text (safe) instead of executing it as code.

### Security Best Practices

1. **Always use `--format html`** for untrusted input (syscall arguments from external sources)
2. **HTML escaping** is automatic (no configuration needed)
3. **No inline JavaScript** - CSS-only styling
4. **Safe to open** in any browser without security warnings

## Table Structure

### Basic Table Layout

```html
<table>
    <tr>
        <th>Syscall</th>
        <th>Arguments</th>
        <th>Result</th>
    </tr>
    <tr>
        <td class="syscall">write</td>
        <td class="args">1, "test", 4</td>
        <td class="result">4</td>
    </tr>
</table>
```

**Tested by:** `test_html_output_has_table_structure`

### Dynamic Columns

Table columns adapt based on flags:

| Flags | Columns |
|-------|---------|
| *(none)* | Syscall, Arguments, Result |
| `-T` | Syscall, Arguments, Result, **Duration** |
| `--source` | Syscall, Arguments, Result, **Source** |
| `-T --source` | Syscall, Arguments, Result, **Duration**, **Source** |

### Error Highlighting

Failed syscalls (negative result) are highlighted in red:

```html
<td class="result result-error">-2</td>  <!-- ENOENT -->
<td class="result result-error">-13</td> <!-- EACCES -->
<td class="result">0</td>                <!-- Success -->
```

**CSS:**
```css
.result-error {
    color: #cc0000;
}
```

## Practical Examples

### Example 1: Build Performance Analysis

```bash
$ renacer --format html -c -T -- cargo build > build-report.html
```

**Tested by:** `test_html_output_with_statistics`, `test_html_output_with_timing`

**Use case:** Analyze build performance with visual statistics table

**Report includes:**
- Individual syscall traces with timing
- Statistics summary sorted by time consumption
- Percentage breakdown of I/O operations

### Example 2: Debugging I/O Issues

```bash
$ renacer --format html -e trace=file -T -- ./slow-app > io-trace.html
```

**Tested by:** `test_html_output_with_filtering`, `test_html_output_with_timing`

**Use case:** Focus on file I/O operations with timing

**Report shows:**
- Only file-related syscalls (open, read, write, close, etc.)
- Duration column for identifying slow I/O
- Easy-to-read table format for non-technical stakeholders

### Example 3: Sharing Trace Results

```bash
$ renacer --format html -c -T --source -- ./app > detailed-trace.html
# Email detailed-trace.html to team members
```

**Use case:** Share comprehensive trace report with team

**Benefits:**
- Standalone HTML file (no dependencies)
- Professional visual presentation
- Source correlation for debugging
- Statistics summary for overview

## Backward Compatibility

HTML format works alongside existing formats:

```bash
renacer --format json -- ./app > trace.json  # JSON still works
renacer --format csv -- ./app > trace.csv    # CSV still works
renacer --format html -- ./app > trace.html  # New HTML format
```

**Tested by:** `test_html_output_backward_compatibility`

Default format remains **text** (strace-compatible).

## Comparison with Other Formats

| Feature | Text | JSON | CSV | HTML |
|---------|------|------|-----|------|
| **Human-readable** | ✅ | ❌ | ⚠️ | ✅ |
| **Visual styling** | ❌ | ❌ | ❌ | ✅ |
| **Programmatic parsing** | ⚠️ | ✅ | ✅ | ❌ |
| **Statistics integration** | ✅ | ✅ | ✅ | ✅ |
| **Standalone** | ✅ | ✅ | ❌ | ✅ |
| **Shareable** | ✅ | ⚠️ | ⚠️ | ✅ |
| **Browser viewable** | ❌ | ⚠️ | ❌ | ✅ |

**Use HTML when:**
- Sharing reports with non-technical stakeholders
- Creating documentation or presentations
- Need visual distinction (error highlighting, hover effects)
- Archiving reports for later review

**Use JSON/CSV when:**
- Post-processing with scripts or tools
- Integrating with CI/CD pipelines
- Machine parsing required

## Troubleshooting

### HTML Output Contains Child Process Output

**Problem:**
```bash
$ renacer --format html -- bash -c "echo test" > trace.html
# HTML contains "test" text from child process
```

**Solution:** HTML is generated after trace completes. Child process output appears before `<!DOCTYPE html>`.

**Workaround:** Redirect child stderr/stdout:
```bash
renacer --format html -- bash -c "echo test >/dev/null" > clean-trace.html
```

### HTML Not Rendering Properly

**Check:**
1. **File extension:** Ensure file ends with `.html`
2. **Browser:** Try different browser (Firefox, Chrome, Safari)
3. **Encoding:** HTML uses UTF-8 charset (line 191 in implementation)

**Tested by:** `test_html_output_basic`

### Missing Statistics Table

**Cause:** `-c` flag not provided

**Solution:**
```bash
renacer --format html -c -- ./app > with-stats.html
```

**Tested by:** `test_html_output_with_statistics`

## Performance

- **Generation time:** <1ms for typical traces (<1000 syscalls)
- **File size:** ~2-5KB base HTML + ~50-100 bytes per syscall
- **Browser performance:** Tested up to 10,000 rows (smooth scrolling)

**Scalability:**
- ✅ <1000 syscalls: Excellent performance
- ✅ 1K-10K syscalls: Good performance (some browser lag on old hardware)
- ⚠️ >10K syscalls: Consider filtering or using CSV for analysis

## Summary

HTML output format provides:
- ✅ **Visual trace reports** with modern CSS styling
- ✅ **Standalone HTML** (no external dependencies)
- ✅ **XSS prevention** via automatic HTML escaping
- ✅ **Statistics integration** with `-c` flag
- ✅ **Responsive design** with hover effects and color coding
- ✅ **Security-first** approach (no JavaScript, safe for untrusted input)
- ✅ **Shareable** single-file reports
- ✅ **Professional presentation** for non-technical audiences

**All examples tested in:** [`tests/sprint22_html_output_tests.rs`](../../../tests/sprint22_html_output_tests.rs)

## Related

- [JSON Output Format](./format-json.md) - Machine-readable output
- [CSV Output Format](./format-csv.md) - Spreadsheet-compatible output
- [Statistics Mode](../core-concepts/statistics.md) - Call counts and timing
- [HTML Reports Example](../examples/html-reports.md) - Practical use cases
