vis-preview

name	vis-preview
description	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.
author	PaperDoctor Research
license	MIT
argument-hint	["paper_dir"]
dependencies	["read-txt","read-vis","read-bib","read-code","read-theory","read-prior","read-exp"]
allowed-tools	Read, Glob, Bash(python *)

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

- [ ] 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).

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

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