---
name: pdf-visual-qa
description: >
  Визуальная проверка PDF-документа рендером в картинки. Брать ВСЕГДА после генерации
  или правки любого PDF (КП, отчёт, договор, прайс, постер, инвойс; reportlab / LaTeX /
  weasyprint / любой генератор) — нельзя считать документ готовым, пока сам не посмотрел
  на отрендеренные страницы. Ловит: разрывы и пустые страницы, осиротевшие заголовки,
  overflow и непереносящийся текст в таблицах, отсутствующие глифы (₽, emoji → чёрные
  квадраты), уехавшую вёрстку, дубли. Также для извлечения текста/таблиц из чужого PDF.
  Триггеры: «собери PDF», «проверь документ», «местами разрывы», «съехал пункт»,
  «проверь скриншотами», «положи КП на рабочий стол».
---

# pdf-visual-qa — визуальная вычитка PDF рендером в картинки

**Правило:** PDF не «готов», пока ты сам не посмотрел на КАЖДУЮ страницу как на картинку.
Структура кода/«должно влезть» не считается проверкой — reportlab/LaTeX молча роняют
текст за поля, рвут блоки и плодят пустые страницы. Глаз на рендере — единственный
надёжный тест вёрстки.

## Когда брать
- Сразу после того, как сгенерировал или поправил PDF (особенно reportlab/platypus).
- Когда пользователь жалуется: «разрывы», «съехал пункт», «пустая страница», «уехало».
- Когда нужно вытащить текст/таблицы из готового PDF (тогда → pdftotext / pdfplumber).

## Метод (3 шага)

### 1. Рендер в PNG
```bash
~/.claude/skills/pdf-visual-qa/tools/render_pdf.sh "/path/to/doc.pdf"          # все страницы, 110 dpi
~/.claude/skills/pdf-visual-qa/tools/render_pdf.sh "/path/to/doc.pdf" 150 4-6   # стр. 4–6, 150 dpi
```
Печатает количество страниц и абсолютные пути к PNG (по умолчанию в `/tmp/pdfqa/`).
Требует `pdftoppm` (poppler; `brew install poppler`). dpi: 100–110 для обзора всей
страницы, 150 для вычитки мелкого текста и таблиц.

### 2. Смотреть КАЖДУЮ страницу через Read
Открой PNG инструментом Read (он показывает картинку). Идёшь по чек-листу ниже.
Несколько страниц — несколькими Read в одном сообщении (параллельно).

### 3. Чек-лист вёрстки (что искать глазами)
- **Пустые / почти пустые страницы** — хвост (дисклеймер, подпись) свесился один на
  последнюю страницу → ужать контент выше, чтобы документ закончился раньше.
- **Осиротевшие заголовки** — заголовок внизу страницы, контент на следующей →
  `keepWithNext=1` в стиле заголовка.
- **Разрыв блока** — карточку/таблицу/мокап порвало между страницами → `KeepTogether([...])`.
  Но: KeepTogether блока крупнее страницы молча переедет и оставит провал — следи за этим.
- **Большой провал внизу** — обычно `KeepTogether` перекинул следующий блок целиком на
  новую страницу. Сократи блок или убери дубль.
- **Чёрные квадраты вместо символов** — шрифт без глифа. ₽ (U+20BD) в Arial = квадрат →
  писать «руб.». Emoji в reportlab не рендерятся → цветной `●` или цветная ячейка.
- **Текст вылез за поля / не переносится** — в reportlab Table простая строка НЕ
  переносится; оборачивай в `Paragraph()`.
- **Дубли** — один и тот же кейс/блок повторён (напр. краткая карточка дублирует полный пример).
- **Уехавшие отступы** — лишние/нехватающие Spacer, неровные колонки.

После правок — пересобрать PDF и **пройти чек-лист заново на свежем рендере**. Итерируй,
пока чисто. Не отдавай документ, не закрыв все пункты.

## tools/
- `render_pdf.sh` — `<pdf> [dpi=110] [pages=all]` → рендер в PNG, печать путей и числа страниц.
- `reportlab_gotchas.md` — справочник граблей reportlab/platypus (кириллица, ₽, emoji,
  переносы в таблицах, orphan-заголовки, пустые страницы, бейджи, скруглённые рамки).

## Извлечь текст/таблицы из чужого PDF (не вёрстка)
```bash
pdftotext -layout doc.pdf -            # текст с сохранением раскладки в stdout
```
Таблицы — `pdfplumber` (`page.extract_tables()`); сканы без текстового слоя — OCR
(pdf2image + pytesseract). Подробности — в плагине anthropic-skills:pdf.
