# Vis Preview

> Generate an interactive HTML review with PDF page images (left) + code viewer with syntax highlighting (middle) + findings with bidirectional navigation (right). All findings are permanently highlighted on the PDF and clickable in both directions.

- Skill: `qinghonglin/vis-preview` (Agent Skill)
- Install (CLI): `npx skillmds@latest add qinghonglin/vis-preview`
- Raw SKILL.md: https://api.skillmd.com/api/skills/qinghonglin/vis-preview/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- License: MIT
- Author: QinghongLin (https://skillmd.com/u/qinghonglin)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/qinghonglin/vis-preview

---


# Visual Preview Report

Generate a single HTML report in `{paper_dir}/display/` with a three-panel layout: PDF page images on the left, code viewer with syntax highlighting in the middle, and review findings on the right. All findings are permanently highlighted on the PDF with colored overlays, and clicking works bidirectionally (PDF → finding, finding → PDF).

## Prerequisites

- `{paper_dir}/*.pdf` — the paper PDF
- `{paper_dir}/reports/check_*.json` — all available check reports
- `{paper_dir}/metadata/code/index.json` — code tree (optional)

Any missing report is skipped with a notice.

## Workflow

```text
- [ ] Step 1: Collect inputs and confirm the main PDF
- [ ] Step 2: Generate HTML via build_review.py (renders pages, runs quote search)
- [ ] Step 3: Copy assets
```

---

## Step 1: Collect Inputs and Confirm the Main PDF

- List PDF files in `{paper_dir}/` (e.g. via `Glob`)
- **Pick the main paper PDF**. Heuristics, in order:
  1. A file named exactly `{paper_dir.name}.pdf`
  2. The largest PDF (main text usually larger than appendix)
  3. The single PDF if only one exists
  Skip files like `appendix.pdf`, `supplementary.pdf`, or version-suffixed older PDFs unless they are the only candidate.
- Record the chosen path as `{pdf_path}` to pass to `build_review.py` later.
- Read all `check_*.json` files from `{paper_dir}/reports/`
- Read `{paper_dir}/metadata/code/index.json` for the code file tree

If no PDF is found, fail with a clear message — do not proceed.

---

## Step 2: Generate HTML via build_review.py

Run the build tool to generate the complete paperdoctor.html. Pass the main PDF chosen in Step 1 via `--pdf`. `build_review.py` handles three things internally:

- Renders PDF page images at 150 DPI into `{paper_dir}/display/pages/` (skipped if already present, idempotent across reruns).
- Collects all `quote` fields from `check_*.json` and runs `pdf_search.search_pdf` to produce `{paper_dir}/reports/quote_positions.json` for permanent highlight rendering.
- Detects the title from PDF metadata (or the first large-font line on page 1 as fallback).

```bash
python tools/build_review.py {paper_dir} --pdf {pdf_path}
```

This reads all `check_*.json`, `quote_positions.json`, and `index.json`, then generates `{paper_dir}/display/paperdoctor.html` with:

### Top Header Bar

White header with PaperDoctor logo (left) + "PaperDoctor" brand text (center).

### Layout: Three-panel split

- **Left panel** (33%, dark bg): PDF page images with permanent colored highlight overlays for all findings
- **Middle panel** (34%, dark bg): Code structure tree from `index.json` by default; switches to code viewer on click
- **Right panel** (33%, white bg): Paper title, donut summary chart, then all findings grouped by report

### Claims Summary Donut Chart

At the top of the right panel (below paper title), an SVG donut pie chart summarizing claim verification results by status:

- **pass** — `#10b981` (green)
- **warning** — `#f59e0b` (amber)
- **error** — `#ef4444` (red)
- **unverifiable** — `#6b7280` (gray)
- **blocked** — `#3b82f6` (blue)

### Bidirectional Navigation

- **Click PDF highlight → scroll right panel** to the corresponding finding card (auto-opens collapsed section)
- **Click finding card → scroll left panel** to the corresponding PDF page with highlight pulse animation
- Highlight tooltip on hover shows the finding ID

### Full Detail Cards

Each finding card shows:
- Status badge, claim ID, section source
- Summary line (claim text or reason)
- Expandable "Details" section with all fields: Quote, Claim, Evidence type, Verification, Reason, Suggestion, Reference (with clickable links)

---

## Step 3: Copy Assets

Copy each of these from the repo's top-level `assets/` directory into the `{paper_dir}/display/` folder:

- `highlight.min.js` — syntax highlighting (local, from highlight.js)
- `python.min.js` — Python language support
- `github-dark.min.css` — code theme
- `logo.png` — PaperDoctor logo

```bash
cp assets/{highlight.min.js,python.min.js,github-dark.min.css,logo.png} {paper_dir}/display/
```

Output directory: `{paper_dir}/display/`

Contents:
```
display/
├── paperdoctor.html          # the interactive report (generated by build_review.py)
├── pages/               # pre-rendered PDF page images
│   ├── page-001.png
│   ├── page-002.png
│   └── ...
├── highlight.min.js     # syntax highlighting (local)
├── python.min.js        # Python language support
├── github-dark.min.css  # code theme
└── logo.png             # PaperDoctor logo
```

## Style Guide

Follow the autolab.moe/blog aesthetic:
- White background, light card backgrounds (`#f9fafb`)
- Card borders: 2px solid with color tint, hard pixel shadow (`4px 4px 0px #d1d5db`)
- Font: system sans-serif stack
- Monospace for quotes and code
- Status colors: green (`#10b981`), amber (`#f59e0b`), red (`#ef4444`), gray (`#6b7280`)
- Left/middle panel background: `#1a1a1a` / `#1e1e1e` (dark, for PDF/code contrast)
- Top header: white background, black text

## Tips

- All assets are local — no CDN or server required. HTML works with `file://` protocol.
- Permanent highlight overlays are `position: absolute` inside each page wrapper, scaled to match the displayed image size
- Use `<details>` for collapsible sections in both report sections and individual finding detail
- If a report file is missing, show a gray "not available" card
- The `build_review.py` tool handles all HTML generation — do not hand-edit `paperdoctor.html`