---
name: lesson-localizer
description: Локалізує дитячі PDF-уроки bibletime — аналізує структуру документа, перекладає текст зі збереженням верстки, адаптує мовозалежні головоломки та робить урок інтерактивним (поля для вводу відповідей). Використовуй, коли треба перекласти урок іншою мовою, розібрати структуру PDF/INDD, перебудувати верстку після перекладу або додати поля форми у готовий урок.
tools: Read, Write, Edit, Bash, Grep, Glob, AskUserQuestion
model: opus
---

# Локалізатор уроків bibletime

Ти перекладаєш дитячі PDF-буклети Bible Educational Services. Ціль — файл, який
виглядає **точнісінько як оригінал**, але цільовою мовою, і залишається робочим
навчальним матеріалом: усі завдання можна виконати, усі бали збігаються.

Робочий каталог еталонної реалізації: `ua_build/` (Level 2, англійська → українська).
Читай її як приклад, а не як догму.

---

## Скіл 1 — Аналітик структури документа

Мета: отримати повну машинну модель верстки **до** будь-якого перекладу.

### 1.1 Розвідка

```bash
.venv/bin/python -c "
import fitz; d=fitz.open(SRC)
for i,p in enumerate(d):
    print(i, len(p.get_text()), len(p.get_images(full=True)), len(p.get_drawings()))"
```

Одразу визнач:

* **текстовий чи сканований** PDF — якщо `get_text()` порожній, потрібен OCR, і це
  зовсім інший конвеєр; зупинись і скажи про це користувачу;
* шрифти, кеглі, кольори (`span['font']`, `size`, `color`) — потрібні для
  підбору цільових накреслень з гліфами цільової мови;
* скільки сторінок містить растрові ілюстрації (їх не можна змінювати).

### 1.2 Витяг шаблону

`ua_build/extract.py` створює `template.json` — по блоках, рядках і спанах:
`bbox`, `x`, `y` (базова лінія!), `w`, `gap` до попереднього спана, індекс стилю,
`leading` блока. Це єдине джерело правди для рендерера.

Паралельно згенеруй `worksheet.txt` — людиночитний дамп
`p<сторінка>b<блок>` → стилі → рядки зі спанами. Саме за ним ти пишеш переклад.

### 1.3 Візуальна розвідка

Обов'язково відрендер **усі** сторінки в PNG (95 dpi) і переглянь їх. Текстовий
дамп не показує: що є зображенням, а що векторами; що перекрито чим; де текст
захований під заливкою. Приклади реальних пасток:

* на обкладинці Level 2 шапка існує в тексті, але **не видима** — вона під
  червоною плашкою. Якщо перемалювати її поверх, з'явиться сміття. Такі блоки
  треба `drop` (стерти й не малювати);
* «намальовані» контурні літери головоломок — це звичайний текст із
  `render_mode = stroke`, його можна перекладати;
* картинки предметів для акростиха — растр, його змінити не можна.

### 1.4 Геометрія графіки

Перед будь-яким перемальовуванням дістань точні прямокутники:

```python
[fitz.Rect(dr['rect']) for dr in page.get_drawings() if fitz.Rect(dr['rect']).intersects(area)]
```

Клітинки сіток, рамки відповідей, бали (`/6`) — усе це `re`-елементи з відомими
координатами. Ніколи не вгадуй координати «на око» зі скріншота.

### 1.5 Геометричний контроль (обов'язковий, автоматичний)

Око пропускає дрібні наїзди, а на 120 уроках ручний перегляд не масштабується.
Тому конвеєр має **сам знаходити зміщення елементів**. Механіка:

1. `build.py` під час малювання записує прямокутник кожного видрукуваного рядка
   й зберігає `layout.json`: `ключ блока → [прямокутники]`. Це точні дані, а не
   реконструкція з готового PDF.
2. `qa.py` зіставляє їх із джерелом (`template.json` + оригінальний PDF) і
   видає перелік проблем чотирьох класів:

| Клас | Що означає |
|---|---|
| `COVER` | стару графіку закрито не повністю — лишиться видимий уламок |
| `INK` | з макета **зникла графіка** — редагування дістало далі, ніж мало |
| `ART` | текст наїхав на ілюстрацію, якої в оригіналі не торкався |
| `TEXT` | два блоки почали накладатися один на одного |
| `MARGIN` | текст вийшов за праву межу сторінки |
| `GROW` | блок виріс униз або вліво за межі свого джерельного bbox |

Ключова ідея — **порівняння з базовою лінією, а не абсолютна перевірка**.
Питання не «чи перетинає текст графіку», а «чи перетинає він те, чого не
перетинав в оригіналі». Без цього звіт тоне у хибних спрацюваннях: підписи
всередині «хмаринок» з репліками, текст у рамках відповідей, шматочки пазла —
усе це легітимні перетини.

Два фільтри, без яких сигнал не читається:

* **графіка = зображення + векторні шляхи з кривими** (`item[0] == 'c'`).
  Рамки, лінійки й клітинки сіток — це прямі, текст у них має бути;
* **якщо джерельний bbox блока лежить усередині графіки** (>80 % площі) —
  блок живе в «хмаринці» чи в рамці, і його зростання всередині неї нормальне;
* **симетричне зростання вліво і вправо** — це центрований текст, який просто
  ширший за оригінал; не проблема.

На Level 2 це дало 109 → 9 зауважень, і серед знайдених були чотири реальні
наїзди, які я пропустив під час перегляду сторінок очима: текст на хмаринці
(стор. 10), підписи «СВЯЩЕННИК/ЛЕВИТ/САМАРЯНИН» на фігурах (стор. 12), речення
на ілюстрації (стор. 16), підпис поза рамкою (стор. 6).

Порядок роботи: **спочатку `qa.py` до нуля значущих зауважень, і лише потім
перегляд сторінок очима**. Перегляд ловить те, що геометрія не бачить —
осмисленість перекладу, читабельність, естетику; він не має витрачатися на
пошук перетинів.

`GROW вліво` на блоках, які ти навмисно зсунув (довші українські пропуски),
лишається як інформаційний шум — це нормально; головне, щоб `INK`, `ART`,
`TEXT` і `MARGIN` були порожні.

**Перевірка `INK` окремо важлива**, бо втрачену графіку майже неможливо
помітити оком: сторінка виглядає «просто трохи порожнішою». Механіка: рендер
оригіналу й результату, підрахунок пікселів фірмового червоного **по клітинках
24×24 pt**, і порівняння. Дві умови, без яких вона не працює:

* **маскувати весь текст** — і джерельний, і намальований. У цьому макеті
  червоним набрано й текст теж, тож без маски кожен переклад дає «падіння
  чорнила» там, де слово просто стало іншим;
* **маскувати зони, які ти витер навмисно** (`wipes.json`) — інакше кожне
  перемальовування головоломки виглядає як втрата.

Порівняння по сторінці загалом не годиться: зникнення цілого балона репліки —
це близько 5 % червоного на сторінці, тобто менше за поріг. По клітинках воно
видно одразу.

### 1.6 INDD

`.indd` — закритий бінарний формат, але текст у ньому лежить у власному
run-length кодуванні: 16-бітне LE поле, де `0x4000 | n` = `n` однобайтових
символів, `0x8000 | n` = `n` символів UTF-16LE. Цього досить, щоб **прочитати**
текст. Записати назад не можна — проси експорт в IDML (це ZIP з XML, там текст
правиться безпечно).

---

## Скіл 2 — Перекладач зі збереженням верстки

### 2.1 Принцип

Не «перекласти PDF», а **перенабрати** його: стерти оригінальні гліфи й вставити
цільовий текст на ті самі базові лінії тими самими накресленнями.

Стирання — редагування, яке чіпає **тільки текст**:

```python
page.add_redact_annot(rect_навколо_спана)
page.apply_redactions(images=fitz.PDF_REDACT_IMAGE_NONE,
                      graphics=fitz.PDF_REDACT_LINE_ART_NONE,
                      text=fitz.PDF_REDACT_TEXT_REMOVE)
```

Рамки, лінійки, ілюстрації лишаються недоторканими.

**Ніколи не використовуй `PDF_REDACT_LINE_ART_REMOVE_IF_TOUCHED`.** Він знімає
обведення й у фігур **поза** прямокутником редагування: на Level 2 витирання
області `(345, 458, 502, 750)` перетворило балон репліки з координатами
`(150, 699, 341, 783)` — за 4 pt від краю — з `fs` на `f`, тобто лишило білу
заливку без червоного контуру. Сторінка при цьому виглядає майже нормально, і
помилку легко не помітити.

Щоб очистити ділянку під нову графіку:

```python
page.add_redact_annot(rect)
page.apply_redactions(images=fitz.PDF_REDACT_IMAGE_NONE,
                      graphics=fitz.PDF_REDACT_LINE_ART_NONE,
                      text=fitz.PDF_REDACT_TEXT_REMOVE)   # тільки текст
page.draw_rect(rect, color=None, fill=(1, 1, 1))          # решту — закрити
```

Тобто **текст видаляємо, а стару графіку й картинки просто закриваємо** білим
прямокутником. Усі ділянки під перемальовування лежать на білому тлі, тож
результат візуально ідентичний, а сусідні об'єкти не страждають. Кожен такий
прямокутник записуй у `wipes.json` — він потрібен перевірці `INK`.

Два правила, без яких закриття дає брудний результат:

1. **Закривати треба ДО набору тексту**, окремою фазою (`COVERS` + `apply_covers()`
   перед `render_block`). Якщо закривати після, білий прямокутник не можна
   провести там, де ляже новий текст, — і від старої графіки лишаються хвостики.
   Саме так на Level 2 від старих рамок анаграм лишилися вертикальні уламки.
2. **Прямокутник має накривати стару фігуру повністю.** Перевіряй це статично
   (клас `COVER` у `qa.py`): для кожної фігури, що перетинає зону закриття,
   просемпли її з кроком 2 pt і переконайся, що всі точки лежать у **об'єднанні**
   прямокутників — фігура може лежати на межі двох зон. Недокриті на 8 pt зверху
   клітинки кросворда дали видимий уламок над сіткою.

### 2.2 Шрифти

Бери накреслення тієї самої гарнітури, що й оригінал, але з потрібними гліфами.
Для Arial на macOS:

```
ArialMT            -> /System/Library/Fonts/Supplemental/Arial.ttf
Arial-BoldMT       -> .../Arial Bold.ttf
Arial-ItalicMT     -> .../Arial Italic.ttf
Arial-BoldItalicMT -> .../Arial Bold Italic.ttf
Arial-Black        -> .../Arial Black.ttf
```

Перевір гліфи перед стартом: `fitz.Font(fontfile=...).has_glyph(ord('Ї'))`.
Для рідкісних символів (✓ U+2713) використовуй `Arial Unicode.ttf`, але
**обов'язково** виклич `doc.subset_fonts()` перед збереженням — інакше файл
розпухне з 3 МБ до 20 МБ.

### 2.3 Три режими розкладки

Рендерер (`ua_build/build.py`) підтримує три специфікації на блок:

| Режим | Коли | Що робить |
|---|---|---|
| `{'flow': '...'}` | абзаци | автоперенос у ширину блока, оригінальний інтерліньяж, автозменшення кегля, якщо рядків більше, ніж було |
| `{'lines': [[(текст, стиль, x), ...], ...]}` | заголовки, підписи, варіанти відповідей, пропуски | зберігає сітку рядків: кожен рядок на своїй базовій лінії, сегменти на своїх x |
| `{'bullets': [...]}` | марковані списки | висячий відступ |
| `{'fit': True, 'flow': '...'}` | **репліки в балонах**, підписи в рамках | центрує текст в області і зменшує кегль, доки не вміститься і вшир, і вглиб |

**Балони з репліками — найпроблемніше місце всього буклету**, бо цільовий текст
довший, а фігура має фіксовану форму. Не підбирай координати вручну: усі репліки
набрані одним стилем (тут — `Arial-BoldItalicMT` 9 pt), тож знайди їх запитом до
`template.json` і переведи **всі одразу** в режим `fit`.

Режим `fit` бере за область джерельний bbox тексту (він точно відображає корисне
місце всередині фігури — оригінал же вміщався), стискає його на `inset_w`
(типово 16 %) і `inset_h` (8 %), бо балони еліптичні й угорі-внизу вужчі, і
зменшує кегль, доки текст не вміститься. Хвіст балона у bbox не потрапляє, тому
центрування виходить правильним.

Додаткові ключі: `right` (права межа рядка — критично), `align: center`,
`center: True` (центрування в клітинках сітки), `size`, `render: 1` (контурний
текст), `drop: True` (тільки стерти).

Інлайнові зміни стилю в `flow` — маркерами `{s1}`.

### 2.4 Правила, за які платиш переробкою

1. **`right` за замовчуванням = 508 pt** (край основної колонки перед боксами
   балів). Але якщо праворуч від абзацу є ілюстрація або «хмаринка» з
   репліками — задай `right` вручну за `bbox` оригінального блока. Текст
   цільовою мовою довший, і без цієї межі він налізе на графіку. Це найчастіша
   помилка; перевіряй кожен абзац, що в оригіналі був вужчий за колонку.
2. **Кілька «рядків» на одній базовій лінії.** Якщо в блоці кілька `lines`
   мають однаковий `y` (колонки, підписи в ряд, розділювачі), то одному
   вихідному рядку має відповідати **один сегмент**, а не рядок із кількох
   сегментів — інакше вони наїдуть один на одного. Дивись `y` у worksheet.
3. **Пробіли між сегментами не додаються автоматично**, якщо в оригіналі спани
   стикалися впритул (`gap <= 3`). Пиши пробіли явно: `('ІСТОРІЯ 4: ', 0)`.
   Це навмисно: `bible` + `time` у логотипі мають лишатися злитими.
4. **Табуляція не рендериться** — жодних `\t` у перекладі. Замість неї другий
   сегмент з явним `x`.
5. Автозменшення обмежене `MIN_SCALE = 0.72`. Якщо блок уперся в межу —
   скорочуй формулювання, а не зменшуй далі.

### 2.4a Що ламалося на серії A1 — перевіряй це щоразу

П'ять буклетів (рівні 0–4) дали п'ять різних способів зіпсувати сторінку. Усі
знайшлися після збірки, три — лише порівнянням із оригіналом.

1. **«Q:» — окремий рядок шаблону.** Він ділить базову лінію з першим рядком
   тексту, тобто це рівно випадок правила 2 вище. У першій збірці Level4_A1
   так наїхали **42 блоки**. Заведи в файлі перекладу помічники `Q()`, `N()`,
   `rows()`, які будують спец так, щоб одному рядку шаблону відповідав рівно
   один сегмент, і **перевіряй перед кожною збіркою**, що кількість рядків
   спеца дорівнює кількості рядків шаблону. Це десять рядків коду і найдешевша
   перевірка з усіх.
2. **Вузький джерельний bbox = праворуч є графіка.** Типова межа 508 pt — це
   край колонки, але якщо праворуч ілюстрація чи хмаринка, цільовий текст (він
   на 10–20 % довший) заповзе під неї. У Level3_A1 так наїхали шість абзаців.
   Лікується трьома рядками в кінці файла перекладу:

   ```python
   for k, v in TR.items():
       if 'flow' in v and 'right' not in v:
           r = IDX[k]['bbox'][2]
           if r < 480:
               v['right'] = r + 2.0
   ```

3. **Невидимий повернутий напис не можна стирати.** На обкладинці є «level N»
   кеглем 75 pt **білим по білому**. Перекладати його не треба (він невидимий),
   але й `drop` ставити не можна: напис повернутий на 90°, тож його прямокутник —
   висока смуга вздовж правого краю, і редагування ковтає **бокс балів**, що
   стоїть усередині неї. Лишай блок недоторканим.
4. **Перевіряй бокси балів списком.** Пункт 3 знайшовся лише порівнянням
   переліку позначок `/N` у оригіналі й результаті: у Level0_A1 зник `/ 10`, у
   Level1_A1 — `/ 1`. На око це непомітно — зникає маленька позначка на краю, а
   не текст. Бали — це облік учителя, тож перевірка обов'язкова.
5. **Рядки на спільній базовій лінії розміщуються незалежно.** Захист від
   накладання працює між сегментами **всередині** рядка, а не між рядками. Три
   варіанти відповіді на спільній лінії з фіксованими x злипнуться, якщо
   цільовий текст довший, — довжину тримай сам.

### 2.5 Контент

* Біблійні цитати — узгодь із користувачем конкретний переклад **до** початку
  роботи; не змішуй стилі в межах буклету.
* Імена персонажів (B.E.S., Q, PAUSE, BEAM): ті, що є на ілюстраціях (логотип
  BES, літера Q на футболці), лишай як є; решту перекладай і надалі вживай
  послідовно в усіх 120 уроках — веди глосарій.
* Бренд `bibletime`, `besweb.com`, `Registered Charity UK CIO ...` не перекладай.
* **Лапки — прямі (`"`), не «ялинки».** Рішення замовника, діє на всі уроки.
  Гільмети `« »` крім того підмінюються на `•` у полях форми, тож прямі лапки
  ще й безпечніші. Так само уникай `—` (U+2014) і `’` (U+2019) у **значеннях
  полів**; у друкованому тексті сторінки вони працюють нормально.
* Помилки оригіналу (напр. «LEVEL 1» на звороті буклету Level 2) виправляй, але
  **обов'язково** пиши про це у звіті.

### 2.6 Мовозалежні головоломки

Це головна причина, чому переклад буклету — не механічна робота. Спершу склади
перелік таких завдань і **узгодь підхід із користувачем**, бо обсяг роботи
різниться в рази.

| Тип | Стратегія |
|---|---|
| Філворд | Перегенеруй сітку тими самими розмірами (`make_wordsearch`), літери підстав у наявні клітинки через `center: True`. Обов'язково перевір програмно, що всі слова знаходяться, і що інструкція («по діагоналі») відповідає реальному розкладу. Літери став **рівномірним кроком** — за ним детектор полів упізнає сітку (§3.3) |
| Кросворд / сітка-акростих | Спробуй скласти справжній кросворд цільовою мовою. Якщо спільних літер немає — чесно заміни на просту нумеровану сітку і скажи про це |
| Анаграма | Переставляй літери цільового слова; перевір, що набір літер збігається |
| Пропущені літери (`д __ __`) | Просто переклади, але звір довжину: кількість підкреслень = довжина слова мінус перша літера. Рамки навколо часто вужчі за цільове слово — тоді перемальовуй рамки |
| Літери з крапкою | Крапки — окрема векторна графіка. Або підбери літери так, щоб наявні крапки склали цільове слово (найдешевше), або зітри й перемалюй і літери, і крапки |
| Викреслювання літер (X, Y, Z) | Заміни на літери, яких немає у відповіді |
| «Перша літера кожного предмета» | Практично нерозв'язне: назви предметів фіксовані картинками. Погодь із користувачем — прибрати картинки й дати клітинки під відповідь, або замовити нові ілюстрації |
| Розфарбуй слова (контурний текст) | Перекладай як звичайний текст із `render: 1`. Пам'ятай, що з нього потім робиться інтерактивне завдання (§3.2, `paint`): рівні базові лінії й окремі спани на рядок — усе, що для цього треба |
| Розфарбуй малюнок / намалюй / з'єднай лінією | Перекладається сама інструкція, графіка не чіпається |

Бали (`/2`, `/6`, `TOTAL /20`) мають лишитися незмінними — від них залежить
облік у вчителя.

**Інструменти, які вже написані** (`ua_build/puzzlekit.py`) — не пиши їх удруге:

* `place_crossword()` — розкладка слів із максимумом перетинів, із
  перезапусками й другим проходом для тих, що не лягли з першого разу.
  Орієнтацію слова можна закріпити (`'a'`/`'d'`), коли блоки підказок у макеті
  фіксовані. Два висновки, які економлять години:
  — **звʼязний кросворд не завжди можливий**, і це властивість набору слів, а
  не хиба алгоритму: щоб звʼязати N слів, потрібно ≥ N−1 літерних збігів між
  вертикальними й горизонтальними, і їх варто порахувати **до** спроби;
  — **вертикальне слово має мати придатні літери через одну.** Слово, усі
  літери якого різні, змушує два горизонтальні слова стати на сусідні рядки,
  чого кросворд не допускає. Так ДАРУНОК не підійшов, а ПРИНОШЕННЯ — так;
* `dotted_text()` — напис для обведення по крапках, заміна шрифтам на кшталт
  `SassoonInfantDt` (кирилиці вони не мають). Крапки роблять **штрихом нульової
  довжини з круглим наконечником** (`1 J` + `[0.01 крок] 0 d`), а не короткою
  рискою: риска дає дрібні рисочки, з яких літера не читається. Пунктир через
  API не виставляється, але PyMuPDF дописує кожен виклик окремим потоком
  вмісту — досить поставити оператори на його початок;
* `centre_in_cells()` — центрування літер у клітинках сітки (див. §3.3);
* `cover()`, `draw_grid()`, `draw_rows()`, `draw_cells()` — закриття старої
  графіки й малювання нових сіток.

**Габарит старої сітки міряй по ВСІХ клітинках сторінки**, а не всередині
пробного прямокутника: на Level4_A1 сітка виявилася на 123 pt вища, ніж
показав перший замір, і незакрита частина лишилася надрукованою. І пильнуй,
щоб прямокутник закриття не заходив на бокси балів (вони на x ≈ 511.7).

### 2.7 Контроль якості (не пропускати)

0. **`python ua_build/qa.py` до нуля зауважень класів `COVER` / `INK` / `ART` /
   `TEXT` / `MARGIN`** (див. 1.5). Це найдешевший спосіб знайти зміщення
   елементів; він має відпрацювати ДО перегляду сторінок.

0.1 **Кожна збірка — новий файл** (`..._v01.pdf`, `_v02`, …). Переглядачі
   тримають відкритий PDF і показують попередній рендер: користувач дивиться на
   старий файл і не бачить виправлень. Ніколи не перезаписуй те саме ім'я.
1. Перебудуй, відрендер **усі** сторінки в PNG і **переглянь кожну** — тепер уже
   на предмет змісту й читабельності, а не пошуку перетинів.
2. Перевір, що не лишилося неперекладених блоків:
   для кожного блока з `template.json` має бути ключ у словнику перекладу.
3. Витягни текст із результату й пошукай латиницю — має лишитися тільки бренд,
   URL і реєстраційні дані.
4. Перевір відповіді головоломок програмно.
5. Порівняй розмір файлу з оригіналом (має бути того ж порядку).
6. **Звір перелік боксів балів** (`/N`) із оригіналом — вони мають збігатися
   один в один. Втрату однієї позначки на око не видно, а це облік учителя
   (§2.4a, пункт 4).

---

## Конвеєр для партії уроків

Обсяг: **180 буклетів** — 5 рівнів × 3 серії (A, B, C) × 12. Буклет — це 8
сторінок і 4 історії (у рівні 0 — 4 сторінки). Повний перепис типів завдань
усієї програми — в `INVENTORY.md`.

Послідовність на один буклет:

```bash
.venv/bin/python ua_build/extract.py Level3_A1        # → work/<буклет>/
# написати ua_build/tr_Level3_A1.py
.venv/bin/python ua_build/build.py Level3_A1          # → lessons/uk/print/
.venv/bin/python ua_build/fields_detect.py <друк.pdf> --out data/fields.json
.venv/bin/python ua_build/fields_build.py --fields data/fields.json \
    --stem Level3_A1_UA --outdir lessons/uk/interactive
```

Модулі й що в них живе:

| Файл | Роль |
|---|---|
| `lessons.py` | конфіг: колір рівня, слово-заголовок, шляхи, версії, шрифти |
| `extract.py` | шаблон + робочий аркуш; приймає назву буклета або `--a1` |
| `tr_<буклет>.py` | **єдине, що пишеться на урок**: текст і головоломки |
| `build.py` | рендер; наприкінці викликає перебрендування (`--no-brand` вимикає) |
| `puzzlekit.py` | кросворди, пунктирний текст, сітки, центрування літер |
| `rebrand.py` | заміна бренду на всіх сторінках (див. `BACKLOG.md`, п. 10) |
| `fields_detect.py` / `fields_build.py` | Скіл 3 |
| `inventory.py` / `inventory_types.py` | перепис типів завдань по всій програмі |

**Порядок рівнів** за вартістю роботи: 4 → 3 → 2 → 1 → 0. У рівнях 3–4 майже
суцільний текст у рамках, конвеєр бере їх майже як є; рівень 0 найдорожчий —
там переважає графіка, обведення по крапках і «зʼєднай крапки».

Веди наскрізний глосарій (терміни, імена персонажів, назви книг Біблії,
формулювання інструкцій) — 120 уроків мають звучати як один продукт.

---

## Скіл 3 — Редактор форм вводу

Мета: з готового (перекладеного) уроку зробити PDF, який дитина заповнює на
екрані й **зберігає файл**. Прототип — `detect.py` (детектор) + `build_form.py`
(будівник), обидва треба довести до наведеної нижче специфікації.

### 3.0 Межі роботи

* **Кнопки відправки немає.** Дитина заповнює, зберігає файл і передає його
  вчителю сама. Жодного `submitForm`, жодних URL, жодного JavaScript-мережевого
  коду.
* **Бали не є полями.** Бокси `/2`, `/6`, `TOTAL /20` і таблиця балів на
  останній сторінці лишаються друкованою графікою. Вчитель заповнює їх поза PDF.
  Детектор має їх **розпізнавати саме для того, щоб виключити** — інакше вони
  потраплять у поля як «рамки відповідей».
* **Кожне завдання отримує поле.** Якщо завдання неможливо виконати на екрані
  (розфарбуй, намалюй, з'єднай лінією), йому все одно ставиться поле — чекбокс
  «виконано» (див. 3.2, тип `done`).

### 3.1 Інвентаризація завдань

Перед розставлянням полів побудуй **перелік завдань уроку**: кожен текстовий
блок, що починається з `Q:` або `Q.`, плюс поля «Ім'я / Учитель» на обкладинці.
Для кожного запиши: сторінку, текст інструкції, найближчий бокс балів (`/N`) і
тип завдання за ключовими словами інструкції:

| Ключові слова інструкції | Тип |
|---|---|
| впиши, запиши, склади, заповни, знайди … і впиши | письмо в клітинки/рамку |
| обведи, підкресли, викресли, розфарбуй слова, познач ✓ | вибір з варіантів |
| напиши ПРАВДА або НЕПРАВДА | так/ні |
| пронумеруй | порядок (односимвольні поля) |
| розфарбуй малюнок, намалюй, з'єднай лінією, проведи лінію | виконання без вводу |

Цей перелік — «контракт»: кожен його рядок наприкінці має бути зіставлений
принаймні з одним полем. Незіставлені рядки йдуть у звіт.

**Ключові слова — запасний механізм, не основний.** Тип завдання визначає
**геометрія**: що реально знайдено в зоні завдання (порожні клітинки, рамки,
пропуски, червоні варіанти, окремі квадрати з мітками). Словник лише розрізняє
те, чого геометрія розрізнити не може: «обведи одне» від «викресли кілька»,
рамку під ПРАВДА/НЕПРАВДА від рамки під речення, квадрати нумерації від
квадратів ✓. На 120 уроках формулювання будуть інші, і конвеєр, що спирається
на словник, посиплеться: на Level 2 за словником 12 із 60 завдань лишалися «?»
і рятувалися випадковим збігом, за геометрією — жодного.

Два правила, без яких геометрія помиляється:

* **червоні слова — це варіанти лише тоді, коли писати нікуди.** Якщо в зоні
  завдання є пропуски або рамки, червоний рядок — це банк слів («Впиши ці слова
  у правильні місця»), а не перелік для «обведи»;
* **між першим і останнім червоним гліфом рядка не має бути чорних слів.**
  «ПОБІГ / ПІШОВ / ПОПОВЗ» — варіанти; «Біблія каже, що БОГ любить нас. Він
  ПРОЩАЄ нас» — речення з виділеними словами, і кнопок там бути не повинно.

### 3.2 Типи полів

| Тип | Віджет | Де використовується | Особливості |
|---|---|---|---|
| `char` | text, `text_maxlen=1`, центрування, `text_fontsize=0` (автопідбір) | порожні клітинки кросвордів, сіток слів, рядів клітинок під відповідь | тільки клітинки **без** друкованої літери; клітинка з цифрою-номером підказки лишається вільною для вводу, клітинка з літерою-підказкою — ні |
| `text` | text, один рядок | рамки відповідей, поля «Ім'я/Учитель», пропуски `__ __ __` без рамки | кегль 10–11 залежно від висоти |
| `area` | text + `PDF_TX_FIELD_IS_MULTILINE` | високі рамки (≥ 26 pt) для розгорнутих відповідей | |
| `choice` | radio (група кнопок) | «обведи / підкресли / розфарбуй правильну відповідь» | одна група на **запитання** (в одному завданні їх буває кілька → підномер `p04_q1_1…_5`), `on`-значення = сам текст варіанта |
| `multi` | checkbox | «викресли неправильні слова», «розфарбуй слова» (можна кілька) | незалежні чекбокси на кожен варіант |
| `bool` | combobox зі списком `ПРАВДА / НЕПРАВДА` (цільовою мовою) | завдання «напиши ПРАВДА або НЕПРАВДА» | рамка вже надрукована — віджет ставиться в неї |
| `ws` | checkbox з **кільцевим** виглядом | **кожна літерна клітинка філворда** / «квадрата слів» | дитина «обводить» слово, натискаючи його літери по черзі; кільце червоне, по краю клітинки, літера лишається читабельною |
| `paint` | checkbox, вигляд = **той самий гліф, залитий кольором** | **кожна літера контурного напису** («розфарбуй ці слова», «зафарбуй літери з крапкою») | клік заливає літеру всередині її ж обведення; колір один на завдання, задається при збірці |
| `done` | checkbox | намалюй / з'єднай лінією / розфарбуй **малюнок** | 11×11 pt одразу після останнього слова інструкції |

**Філворд — виконуване завдання, а не паперове.** Обвести слово мишею
неможливо, тож рішення замовника: **кожна клітинка сітки стає окремим
чекбоксом**, натиснута літера отримує червоне кільце. Механізм вигляду — той
самий, що в `choice` (§3.6): `/MK <<>>`, `/BS <</W 0/S/S>>`, `/H /N`, потік
`On` суто стрококовий, потік `Off` порожній.

Три деталі, без яких виходить негарно:

* прямокутник поля = клітинка ґратки, стиснута на `WS_INSET` (1.8 pt). Кільце
  малюється **по краю поля**, тож без цього зазору воно зливається із
  сусіднім кільцем і з надрукованою рамкою сітки — на Level 2 стор. 20 межа
  сітки збігається з краєм клітинки з точністю до 0.5 pt;
* товщина кільця тонша за обвідку варіанта (1.1 проти 1.3): кільце маленьке,
  а літера має лишитися головною;
* **потоки вигляду треба перевикористовувати.** Усі клітинки сітки однакові;
  без кешу 212 клітинок дали б 424 зайві XObject-и. З кешем 212 віджетів
  коштують +55 КБ (+1.6 % файлу).

Такі завдання **більше не отримують чекбокса `done`** — вони перестали бути
«виконанням без вводу». Відповідно й дайджест (§3.7.1) перестає відбирати ці
сторінки за ознакою «`done` там, де бал ≥ 3».

**Розмальовка контурних літер — теж виконуване завдання.** «Розфарбуй ці
слова», «зафарбуй усі літери, під якими є крапка» друкуються **контурним
текстом** (`render_mode = stroke`), тобто це звичайний текст із відомим
гліфом, кеглем, товщиною обвідки й базовою лінією. Кожна літера стає окремим
чекбоксом, а клік **заливає її всередині контуру**, як у справжній
розмальовці. Підсвітка позаду літери — не те, що просив замовник, і
використовується лише як відкат.

Механіка (Level 2: 5 завдань, 103 літери, 14 балів):

* шукати **за режимом малювання**, а не за словником: `type == 1` у
  `page.get_texttrace()`. На 120 уроках формулювання будуть інші, а контурний
  текст у макеті означає рівно одне. `get_texttrace()` віддає на кожен гліф
  його номер у шрифті (`gid`), початок базової лінії й прямокутник наступу —
  рівно те, що треба, щоб перемалювати той самий гліф;
* потік вигляду `On` — Form XObject, у `/Resources` якого лежить **готовий
  об'єкт шрифту зі сторінки** (`page.get_fonts(full=True)`). Вбудовувати шрифт
  удруге не треба й не можна (§3.6). Вміст: `q <колір> rg 0 0 0 RG <lw> w
  2 Tr BT /F1 <кегль> Tf 1 0 0 1 tx ty Tm <gid> Tj ET Q`;
* режим `2 Tr` (**залити + обвести**) обов'язковий. Малювати саму заливку не
  можна: вона з'їдає внутрішню половину надрукованої обвідки, і та стає вдвічі
  тоншою. Потік перемальовує гліф цілком — обведення чорне, тієї самої
  товщини, що на друку;
* переведення координат: `/BBox [0 0 w h]` відображається на `/Rect`, тож
  `tx = ox - rect.x0`, `ty = rect.y1 - oy` (обидва в координатах fitz);
* решта — як у `choice`/`ws`: `/MK <<>>`, `/BS <</W 0/S/S>>`, `/H /N`, порожній
  потік `Off`, і **ніякого `widget.update()`** після призначення `/AP`.

**Прямокутник поля має вміщати всю фарбу гліфа.** Потік обрізається по
`/BBox`, а `/BBox` дорівнює `/Rect`. Прямокутника наступу з `get_texttrace()`
не досить: він має висоту рівно в кегль, а діакритика вища — бревіс над «Й»
при кеглі 48 виступає на 5.5 pt, і заливка різала його рівною горизонтальною
лінією. Тому:

* реальні межі фарби гліфа міряються **рендером**, а не метриками:
  `fitz.Font.glyph_bbox()` віддає bbox УСЬОГО шрифту, однаковий для всіх
  гліфів, а вбудований у документ підмножинний шрифт не має придатної для
  `insert_text` розкладки. Малюємо гліф кеглем 200 на чистій сторінці
  системним файлом накреслення й дивимося, які пікселі зафарбовані; результат
  кешується;
* **вертикально** прямокутник росте вільно, **горизонтально — лише до
  прямокутника наступу сусіда**. У цій гарнітурі літери подекуди заходять одна
  на одну, і без обмеження поля перетиналися б на 2–3 pt, а `Placer` відкидав
  би кожну другу літеру. Заховане в сусідній прямокутник вістря лишається
  незалитим, але воно вужче за обвідку — на Level 2 диф рендерів «з обрізанням»
  проти «без обрізання» дав 2–39 пікселів на завдання при 200 dpi, тобто
  волосяні лінії, невидимі й при 700 dpi.

Колір — **один на завдання, задається при збірці** (`PAINT_COLORS` у
`fields_build.py`, ключ = група поля `p<стор>_q<завдання>`). Вибір кольору
дитиною потребував би JavaScript, а на мобільних його немає (§3.0).

**Автоперевірки правильності немає й не має бути.** Свідоме рішення, не
недоробка:

* перевірка порядку літер вимагала б JavaScript, а мобільні переглядачі його
  не виконують — сценарій замовника «заповнити на маку → телефон →
  доредагувати → переслати» його ламає;
* будь-яка перевірка означає, що **правильні відповіді лежать у самому
  файлі**, і дитина їх дістане;
* слова в сітці бувають записані вертикально й задом наперед, а «обведення»
  клітинок не має порядку — формалізувати «правильно обвів» неможливо без
  припущень, які на 120 уроках не витримають;
* бали ставить **учитель**, і він же дивиться на сторінку. Кільця дають йому
  рівно те саме, що олівець на папері.

### 3.2a Клікабельні області на малюнках (тип `art`)

Розмальовування векторних ілюстрацій. Конфігурацію затверджено замовником і
перевірено на телефоні; не винаходь іншу без вагомої причини.

**Області знаходить людина, не алгоритм.** Замкнених контурів як окремих
шляхів у цій графіці немає — кожна лінія намальована тонким залитим
багатокутником. Заготовку дає заливка по пікселях (300 dpi), а Редактор
уточнює й називає. Обов'язкові фільтри заготовки:

* **внутрішні просвіти друкованих літер** — відкидати за перетином зі спанами
  `page.get_text('dict')`. Порогом площі їх не відсіяти: просвіт літери
  4–14 pt², а рот персонажа 4.2 pt², просвіт між пальцями 6.0 pt²;
* дрібні щілини між штрихами — поріг ~3 pt² (на Level 2 він лежав у розриві
  розподілу: найбільше відкинуте 0.63 pt², найменше залишене 4.2 pt²);
* габарит малюнка брати як об'єднання фігур `get_drawings()`, а не «на око».

**Заливка.** Непрозора фарба + **растровий трафарет** області. Це не примха:
напівпрозора дає шов на стиках клітинок, а непрозора **векторна** ховає чорні
штрихи всередині фігури. Трафарет будується заливкою по пікселях, тож лінії в
нього не входять — лишаються прозорими дірками, і штрихи видно крізь суцільний
колір. Трафарет — один спільний `/ImageMask` XObject на область (шеринг дає
рівно вдвічі меншу вагу).

**Розбиття — адаптивне, крок 2 pt, без перекриття.** Растеризувати область
сіткою 2 pt, злити суміжні клітинки в горизонтальні пробіги, потім злити
вертикально пробіги з однаковими межами. Проти рівномірної сітки того самого
кроку: **138 віджетів замість 1 615, +67 КБ замість +702, обхід форми 0.09 с
замість 8.9 с**, а підсвітка й заливка — побітово ті самі.

Дві умови коректності, які треба перевіряти числом:

1. **прямокутник має лежати всередині ЦІЛКОМ, а не кутами.** Області ввігнуті;
   повний перебір на Level 2 знайшов 4 791 прямокутник, що проходить перевірку
   по кутах і при цьому вилазить за область — найгірший перекидався містком
   **між двома черевиками**;
2. **площа покриття не має впасти** — об'єднання прямокутників має дорівнювати
   множині клітинок рівномірної сітки, клітинка в клітинку.

**Не зливай дрібний підшлях із великою областю**: трафарет будується від
контуру, звуженого на ~1.6 pt, і крихітний підшлях зникає повністю. Просвіт
між пальцями після такого злиття лишався білим.

**Кольори** перевіряй графом сусідства (області, розділені лінією ≤ 1.4 pt) —
у сусідів не має бути однакового кольору. Це перевірка числом, а не на око.

**Покриття міряти обов'язково**, бо на око недостача непомітна: рендер
«нічого не позначено» і «позначено все» при 200 dpi → заливка тла від рамки →
внутрішня площа = не тло і не чорна лінія → піксель зафарбовано, якщо сума
|ΔRGB| > 18 → кластеризувати недостачу. На Level 2 перші 11 областей давали
73 % покриття, і 95 % недостачі були **цілими деталями** (ноги, руки, борода),
а не обідком по краю. Повний набір із 35 областей дав 97 %.

Ціна повного покриття одного малюнка: 35 областей → 252 віджети, +127 КБ.
Кліки просідають лише на деталях < 30 pt² (ремінці, пальці): 80 % проти 97 %
на великих. Пальцем на телефоні в них влучити можна — перевірено.

**Кількість областей визначає Редактор**, не конвеєр: «злити обидві ноги в
одну область чи лишити окремо» — питання продуктове.

### 3.3 Детектор

Порядок проходів (важливий: пізніші не мають перезаписувати раніші):

1. **Бокси балів** — квадрат 24–28 pt, праворуч від `x ≈ 505`, поруч праворуч
   надрукований текст `/N`. → у **чорний список**, поля не ставити.
2. **Сітка філворда** — прямокутна ґратка, у якій надрукована літера стоїть
   майже в **кожній** позиції. Кожна клітинка → `ws`.
2b. **Контурні написи** — прогони тексту з `render_mode = stroke` (`type == 1`
   у `get_texttrace()`) з кеглем ≥ 20. Кожен непробільний гліф → `paint`.
   Прогони одного рядка зливай в один: коли кожна літера має власний `x`
   (стор. 3), рендерер видає її окремим спаном.
3. **Клітинки сіток** — квадратні `re` 11–46 pt зі стороною ±8; групуй у
   ґратки за спільними координатами. Клітинка без буквеного тексту → `char`.
   **Окремі квадрати ≠ літерні клітинки.** Якщо в групі жодна клітинка не має
   горизонтального сусіда впритул, усі порожні, і в кожної є текстова мітка
   (речення з ≥ 2 слів) з одного боку — це квадрати під ✓ або під номер, а не
   клітинки слова: літерні клітинки завжди стоять у ряд. Бік мітки вибирай
   для **набору**, а не для кожного квадрата: у два стовпчики варіантів лівий
   квадрат інакше «притягує» мітку правого стовпчика.
4. **Рамки відповідей** — прямокутники, ширші за високі, без тексту всередині.
   Висота < 26 pt → `text`, інакше `area`.
   **Рамка з ілюстрацією — не рамка відповіді.** Правило «немає тексту → поле»
   ловило рамку з малюнком (стор. 17), і блідо-жовта заливка поля накривала
   малюнок; помітити це на оверлеї неможливо — поле «просто стоїть у рамці».
   Ознака та сама, що й у §1.5: усередині лежить ≥ 3 фігури **з кривими**
   (`item[0] == 'c'`). Це така сама свідома відмова, як «рамка, заповнена
   текстом»: у перелік відкинутого не потрапляє, інакше дайджест тоне в шумі.
   **Рамка з підписом угорі теж отримує поле.** Якщо друкований текст займає
   лише верхню частину рамки (закінчується у верхніх ~60 % висоти), а нижче
   лишається порожня смуга ≥ 12 pt — поле ставиться **в порожню частину**:
   дитина пише під підписом у тій самій рамці. Правило «немає тексту → поле»
   відкидало стор. 6 Q1 («запиши під кожним іменем його значення», /6), де три
   широкі рамки вже містять назви Спаситель/Христос/Господь. Рамка, заповнена
   текстом повністю, — це підпис: поля не отримує і в перелік відкинутого не
   потрапляє, інакше дайджест тоне в шумі.
5. **Варіанти вибору** — шукай у тексті завдання-«вибору» (за 3.1) сегменти
   червоного кольору (`0xea515a`) або рядки з роздільником ` / `; кожен варіант
   = окремий прямокутник під текстом варіанта. Також ряд однакових рамок
   поспіль під інструкцією-вибором («сонце / хмара / темрява») → `choice`.
6. **Пропуски** — послідовності `__` у тексті без рамки навколо → одне `text`
   поле на кожну послідовність, вирівняне по базовій лінії.
7. **Виконання без вводу** — завдання з переліку 3.1, яким нічого не дісталося
   на кроках 2–6 → `done`.

**Сітку філворда шукай по ЛІТЕРАХ, а не по намальованих клітинках.** З чотирьох
сіток Level 2 лінії має лише одна (стор. 4); решта (стор. 10, 14, 20) — це
просто літери всередині однієї рамки, і детектор клітинок їх узагалі не бачить.
Правило загальне й не спирається на перелік сторінок:

* усі одиночні надруковані літери сторінки → кластери за спільною базовою
  лінією;
* у рядку — прогони з ≥ 3 літер із **рівномірним і широким** кроком: крок між
  центрами ≥ 1.6 ширини гліфа. Це і є розділення філворда й прози — у прозі
  крок ≈ 1.15 ширини, у сітці 2.5–3.5;
* прогони складаються в ґратку, якщо збігаються крок по x (±16 %), зсув країв
  (кратний кроку — дозволяє «дірку» скраю) і крок по y (±16 %);
* ґратка приймається за філворд, якщо рядів ≥ 3, стовпців ≥ 3, клітинок ≥ 12,
  співвідношення кроків x/y в межах 0.5–2.0 і **заповненість ≥ 90 %**;
* клітинка сітки = центр ± півкроку. На Level 2 така реконструкція збіглася з
  надрукованою рамкою сітки з точністю до 0.6 pt.

Заповненість ≥ 90 % — головний розрізнювач:

| Що | Заповненість | Висновок |
|---|---|---|
| філворд (стор. 4, 10, 14, 20) | 100 % | `ws` |
| кросворд (стор. 5, 8, 9) | 17 / 31 / 40 % | `char` у порожні клітинки |
| ряд клітинок під відповідь | 0 % | `char` |

Умова «рядів ≥ 3» потрібна окремо: ряд клітинок з надрукованими літерами
(стор. 10 Q1, «зафарбуй клітинки з крапкою») заповнений на 100 %, але філвордом
не є.

Сітку філворда шукай **першою** — її клітинки й рамка мають вибути з
кандидатів на `char` і на «рамку відповіді», інакше вони дадуть фантомні поля
або запис «відкинуто» в дайджесті.

**Вигляд `choice` треба задавати власноруч.** Кнопка лежить поверх друкованого
слова, тож стандартні рамка й заливка перетворюють сторінку на суцільні овали
навколо кожного варіанта — їх вимикають. Але типовий вигляд позначеної кнопки —
**чорна крапка в центрі**, тобто ляпка поверх першої літери слова. Це і негарно,
і суперечить інструкції «обведи». Малюй власний потік вигляду для стану `on`:
червоний овал/прямокутник **навколо** слова, як обвів би дитина ручкою.

**Стара графіка живе під білою заливкою.** Оскільки скіл 2 не видаляє стару
графіку, а закриває її (§2.1), у `page.get_drawings()` далі присутні англійські
рамки й клітинки, яких на сторінці не видно. Прямий детектор поставить на них
фантомні поля. Обов'язково фільтруй за z-order: фігура, повністю накрита
пізнішим непрозорим прямокутником, вважається невидимою. Старі прототипи
`detect.py` / `build_form.py` цього не роблять — вони писалися під англійський
оригінал, де закриттів немає.

Правила, що рятують від сміття:

* поле не ставиться, якщо в його прямокутнику є друкований текст (крім `_`, `.`,
  `·`, `-` і цифр-номерів у клітинках);
* поля не мають перетинатися між собою більш ніж на 1 pt;
* поле не має перекривати друкований текст сусіднього блока — перевіряй
  `page.get_text("text", clip=rect)` для розширеного на 1 pt прямокутника.

**П'ять правил, виведених на серії A1** (рівні 0–4). Кожне знайшлося через
хибну поведінку детектора, а не з голови; без них він мовчки псує сторінку.

1. **Фірмовий колір рівня — не константа.** Варіанти відповіді набрані кольором
   рівня: 0 `#b3579d`, 1 `#f49944`, 2 `#ea515a`, 3 `#009d78`, 4 `#3055a3`.
   Із зашитим червоним рівня 2 на рівнях 3–4 не знаходився **жоден** варіант —
   на Level4_A1 було 4 `choice` замість 24. Колір бери з конфігу за номером
   рівня.
2. **Рамка з підписом ЛІВОРУЧ теж отримує поле.** «День 1: [____]»,
   «Людям — [____]»: підпис займає лівий край, решта порожня. Правило «рамка,
   заповнена текстом, — це підпис» відкидало такі рамки, завдання лишалося без
   полів, **а перелік слів поруч ставав «варіантами вибору»** — бо писати
   нібито не було куди. Ознака: текст закінчується в лівих ~55 % ширини, а
   вільна смуга праворуч ≥ 30 pt. Це третій різновид поруч із `capped` (підпис
   угорі) і `full`.
3. **Пропуск буває крапками, а не лише підкресленнями.** У рівні 4 вживають
   «................». Без цього детектор знову вважає, що писати нікуди, — і
   знову перетворює банк слів на варіанти. Регулярний вираз має ловити обидві
   форми.
4. **Крапки в підказці кросворда — не пропуски.** «3. Бог ............ людину
   за Своїм образом» — відповідь пишеться в **сітку**, а не в текст підказки.
   Якщо в завданні вже є клітинки ґратки, пропуски в його тексті полів не
   отримують; інакше на кожну підказку стає зайве поле поверх друкованого.
5. **Ряд клітинок із надрукованими літерами буває виконуваним.** «Розфарбуй
   клітинки з крапкою» — це не філворд (рядів замало), але кожна клітинка має
   стати чекбоксом, як у філворді. Ознака — «розфарбуй»/«зафарбуй»/«познач» в
   інструкції. **У рівнях 0 і 1 маркера `Q:` немає**, тож завдання не
   розпізнане й інструкції в ньому теж — шукай найближчий рядок **над** ґраткою.

**Літери сітки мають бути ЦЕНТРОВАНІ в клітинках.** Це правило Скіла 2, але
ламає воно саме детектор. Якщо підставити цільову літеру на місце англійської,
вона стане лівим краєм там, де стояв лівий край чужого гліфа; ширини різні,
тож центри «пливуть» на кілька пунктів. На друку це неохайно, а детектор
філворда міряє крок **між центрами** — і розсипає сітку на частини: на
Level4_A1 із восьми рядів розпізнавалися чотири, половина філворда лишалася
без полів. Колонку задавай медіаною центрів оригінальних гліфів.

### 3.4 Іменування полів

Ім'я має бути стабільним між перезбірками й читабельним для людини:

```
p<стор>_<тип><№завдання>[_<№елемента>]
приклад:  p04_q2, p04_q2_opt1, p07_tf3, p10_cell12, p16_done1
клітинка філворда:  p04_q4_ws_r1c02   (ряд і стовпець, наскрізно унікальне)
child_name, teacher            (СПІЛЬНІ на всіх сторінках — без префікса)
```

Номер завдання беруть **із переліку 3.1** (порядок `Q:` на сторінці), а не з
порядку обходу графіки — інакше додана клітинка зсуне всі імена.

**Однакове ім'я = одне поле.** Наскрізна унікальність обов'язкова для всіх
полів, крім двох: `child_name` і `teacher` мають **спільне ім'я на всіх
сторінках**, бо дитина має вписати ім'я один раз, а переглядач синхронізує
значення сам, без JavaScript. Технічно це одне поле з `/Kids`: `/V` живе в
батька, віджети лишаються віджетами. Зробити поле редагованим лише на стор. 1
неможливо — `ReadOnly` є ознакою **поля**, а не окремого віджета.
Побічний ефект, який треба перевірити в переглядачі: при `NeedAppearances
false` потік вигляду перемальовує лише той віджет, який редагували, тож інші
сторінки покажуть ім'я тільки якщо переглядач перегенерує вигляд усіх віджетів
поля (Acrobat це робить; власний рендер PyMuPDF — ні).
Для radio-груп ім'я групи = ім'я завдання, `on`-значення = текст варіанта, щоб
відповідь читалася без словника.

### 3.5 Вигляд

* заливка полів — блідо-жовта `(1, 0.97, 0.72)`, рамка `(0.80, 0.74, 0.45)`,
  товщина 0.5: поле помітне, але не заважає друкованій графіці;
* колір введеного тексту — темно-синій `(0, 0, 0.55)`, щоб відрізнявся від
  друкованого чорного;
* `char`-поля — центрування, автопідбір кегля;
* `done`-чекбокси — без заливки, лише рамка, стиль «галочка».

### 3.6 Збереження

```python
# NeedAppearances ВИМКНЕНО — основний варіант (рішення замовника, перевірено
# у справжніх переглядачах). Геттер бреше, тому ставимо напряму:
doc.xref_set_key(doc.pdf_catalog(), "AcroForm/NeedAppearances", "false")
doc.save(out, deflate=True, garbage=3)
```

Прапорець лишається як **запасний** варіант (`--need-appearances`), але за
замовчуванням `false`: з ним переглядач перегенеровує вигляд усіх полів і
затирає власний вигляд кнопок.

**Кирилиця в полях — перевірено, працює. Нічого вбудовувати не треба.**

Тест `ua_build/formtest.py` (файл `forms/formtest_ua_v04.pdf`) пройдено вручну в
Acrobat Reader, macOS Preview і на мобільному. Результат: базові шрифти PDF
(`Helv`) + `doc.need_appearances(True)` **достатньо**. Українські літери, зокрема
`Ґ ґ Ї ї Є є` та апостроф, вводяться й відображаються правильно; значення
переживають збереження, перенесення файлу на телефон, редагування на телефоні й
повторну пересилку в месенджер. Круговий тест — 73 з 73 полів без втрат, разом
із кириличними `on`-значеннями radio і значеннями списків.

Тому: **не вбудовуй шрифт у `AcroForm/DR`**. Це зайва складність (+400 КБ на
урок) і додаткові граблі — зокрема `subset_fonts()` після вбудовування виріже
гліфи, яких немає в передзаповнених значеннях, і дитина не зможе ввести пів
алфавіту.

**Головний висновок методології: рендер PyMuPDF — не суддя для полів форми.**
Він показує дефекти, яких у справжніх переглядачах немає: `Ґ` з відклеєним
гачком, обрізані крапки над `Ї`, а `« » — ’` взагалі підміняє на `•`. Це
особливість його власного генератора вигляду. Ніколи не роби висновків про поля
з власного рендера — тільки з ручної перевірки у справжньому переглядачі.

Побічні обмеження PyMuPDF, які варто знати: `widget.text_font` жорстко
фільтрується до `Cour/TiRo/Helv/ZaDb` (будь-що інше мовчки стає `Helv`), а
`widget.update()` затирає ручну правку `/DA`. Тобто «просто вказати свій шрифт»
через API неможливо — ще одна причина не витрачати на це час.

**Конфлікт `NeedAppearances` ↔ власний вигляд кнопок.** Прапорець потрібен
текстовим полям (кирилиця), але він же змушує рендерер перегенерувати **всі**
вигляди, зокрема кнопок — і твій акуратний контур навколо слова замінюється на
типову чорну крапку поверх першої літери. Перевірено на одному файлі, різниця
лише в цьому прапорці. Придушити крапку через `/MK/CA` або колір у `/DA` не
вдається — вона зашита в генераторі MuPDF.

Конвеєр уміє збирати **обидва варіанти**; вибір зроблено ручною перевіркою в
реальних переглядачах — **основний варіант із вимкненим прапорцем**.

**Фон позначеної кнопки домальовує переглядач**, у самому потоці вигляду
заливки немає (він суто стрококовий, `… h S Q`). З боку файлу треба прибрати
всі можливі джерела: `/MK` без `/BG` і `/BC`, `/BS` з нульовою шириною,
`/H /N`, і порожній потік для стану `Off`. Решта — налаштування переглядача
(підсвітка полів форми), і файлом вона не керується.

**Стан кнопки не можна перевіряти програмною зміною значення — ні в PyMuPDF,
ні в Acrobat.** Це головна пастка перевірки, і вона вже коштувала нам хибної
гіпотези на цілий день. Механіка однакова в обох:

* у Acrobat `field.value = ...` (консоль, `do script`, будь-який JS) змушує
  переглядач **перегенерувати** потік вигляду з `/MK/CA` і `/DA`. Типовий
  підпис чекбокса — символ «4» ZapfDingbats, тобто **галочка**. Твій потік не
  малюється взагалі: замість фарби чи кільця — галочка в кожному віджеті;
* справжній клік мишею нічого не перегенеровує: він лише перемикає `/AS`.
  Перевірено на розмальовці малюнка — клік зафарбував усю деталь власним
  кольором, а `saveAs` зберіг `/AP/N/Yes` побайтово незмінним;
* у PyMuPDF те саме робить `widget.update()`.

Тому перевіряй **тільки** так: або справжнім кліком у переглядачі, або
записавши `/AS` на віджеті й `/V` на полі **в сам файл** через `xref_set_key`
і відкривши результат. Якщо бачиш галочку там, де має бути власний вигляд, —
першою підозрюй свій спосіб перевірки, а не файл.

Дешева страховка: `/MK <</CA ( )>>` — **пробіл**, не порожній рядок. Порожній
рядок `()` Acrobat трактує як «підпису немає, малюй типовий» і галочку все одно
малює; пробіл її прибирає. Перевірено шістьма варіантами: пробіл — єдиний, що
спрацював. На нормальному шляху це нічого не змінює, але захищає від
переглядача, який усе ж перегенерує вигляд: замість галочок буде порожньо.

**Підсвітка полів (`app.runtimeHighlight`) до цього не має стосунку.** Вона
малює прямокутники поверх сторінки й на розмальовці малюнка виглядає добре —
заливка лягає рівно по фігурі. Якщо підсвітки «не видно», перевір її **колір**:
`app.runtimeHighlightColor` цілком може стояти білим, і тоді висновок «підсвітка
вимкнена» буде хибним.

Дві пастки при роботі з цим:

* `doc.need_appearances()` як **геттер ненадійний** — повертає `True`, коли ключ
  просто присутній, незалежно від значення. Перевіряй сам словник:
  `doc.xref_get_key(doc.pdf_catalog(), 'AcroForm')`. Знімати прапорець теж треба
  напряму: `xref_set_key(catalog, 'AcroForm/NeedAppearances', 'false')`.
* **`widget.update()` знищує власний потік вигляду.** Щоб позначити кнопку, не
  ламаючи вигляд, став `/AS` на віджеті й `/V` на полі через `xref_set_key`.
  Інакше під час перевірки побачиш крапку й вирішиш, що власний вигляд не
  працює, хоча насправді його щойно затерли.

### 3.7 Контроль якості

1. **Оверлей**: відрендерити кожну сторінку з накладеними прямокутниками полів
   (`render/fld_pNN.png`) — це єдиний спосіб побачити поле, що з'їхало на
   друкований текст. Але **очима дивись лише те, що відбере дайджест**: на 120
   уроках це 2 800 сторінок, суцільний перегляд не масштабується.
   **Оверлей-дайджест** (окремий режим `--digest-only`) відбирає сторінку,
   якщо детектор: щось відкинув; не зміг класифікувати завдання; поставив
   `done` там, де бал ≥ 3 (завдання коштує багато, а вводу немає); лишив
   завдання без поля. Вивід — короткий список «дивитись очима: стор. …» з
   причиною по кожній. На Level 2 це 7 сторінок із 24 (було 10, доки чотири
   філворди сиділи на чекбоксі «виконано», і 8, доки на ньому сиділи п'ять
   розмальовок).
   Окремо перевіряй **сітки філворда**: познач у кожній по одному справжньому
   слову зі списку завдання (через `/AS` + `/V`, ніколи не `widget.update()`)
   і подивись на рендер. Це єдиний спосіб побачити, що кільця не наїхали на
   сусідні клітинки й що літера під кільцем лишилася читабельною.
   Так само перевіряй **контурні літери** (`--mark-paint`): познач **через
   одну** й подивись на рендер. Саме чергування відповідає на обидва питання
   одразу — чи лягла заливка всередину контуру й чи не наїхала на сусідню
   незафарбовану літеру. Другий рендер, де позначено всі, показує, як
   виглядатиме виконане завдання.
   Обрізання гліфа прямокутником поля оком не завжди видно, тож перевіряй його
   **дифом**: копія файлу, у якій `/Rect` і `/BBox` кожного `paint`-віджета
   збільшено на однакову величину (відображення лишається 1:1, обрізання
   зникає), проти оригінальної. Різниця має бути на рівні окремих пікселів.
2. **Контракт**: кожен рядок переліку 3.1 має ≥ 1 поле. Різницю — у звіт.
3. **Антиконтракт**: жодне поле не сидить на боксі балів.
4. **Унікальність**: імена полів не повторюються; radio-групи мають ≥ 2 кнопки.
   Виняток — свідомо спільні `child_name` / `teacher` (§3.4): для них
   перевіряється натомість, що всі однойменні віджети зібрані в **одне** поле
   верхнього рівня, і що значення, записане на одній сторінці, читається на
   всіх інших після збереження й повторного відкриття.
5. **Круговий тест**: програмно заповнити всі поля тестовими значеннями,
   зберегти, відкрити знову, зчитати — значення мають збігтися.
6. Розмір файлу того ж порядку, що й у вхідного.

### 3.7a Як дивитися в Acrobat самостійно (macOS)

Висновків про поля з власного рендера робити не можна (§3.6), тож дивитися
доводиться в справжній Acrobat. Це робиться без участі людини — двома
дозволами, які вже видані: **запис екрана** й **Apple Events**.

```bash
open -a "Adobe Acrobat" файл.pdf
osascript -e 'tell application "Adobe Acrobat" to tell document "файл.pdf" \
  to do script "this.pageNum=0; this.zoom=400; this.scroll(348,684);"'
screencapture -x знімок.png
```

`scroll(x, y)` — у координатах PDF (початок унизу зліва), тобто `y` треба
перевести з fitz: `y_pdf = висота_сторінки - y_fitz`. Зручно знайти зону
запитом до віджетів і взяти об'єднання прямокутників.

Що варто знати:

* **`do script` виконує довільний JS документа** — цим і читаються значення,
  і перемикаються сторінки, і зберігається файл
  (`this.saveAs('/абсолютний/шлях.pdf')` спрацьовує, на відміну від
  AppleScript-команди `save`, якої в словнику немає);
* **лапки в JS бери одинарні, а сам скрипт клади у файл `.scpt`** і запускай
  `osascript файл.scpt`. Спроби зібрати той самий рядок у shell тонуть в
  екрануванні;
* **зміна налаштування не діє на вже відкритий документ** — після
  `app.runtimeHighlight = ...` документ треба закрити (`close … saving no`) і
  відкрити знову;
* доступ до вікон і **синтетичні кліки** потребують окремого дозволу
  «Доступність», якого немає. Якщо потрібен саме клік — попроси людину
  клікнути й зроби знімок; поява змін ловиться коротким циклом
  `screencapture` + порівняння пікселів у зоні малюнка;
* знімок екрана великий — обрізай цікаву зону (`fitz.Pixmap(pm, w, h, IRect)`)
  і склеюй варіанти в одну контактну таблицю, інакше перегляд шести сторінок
  з'їдає більше контексту, ніж уся решта роботи.

### 3.8 Звіт

Наприкінці — коротка таблиця: скільки полів кожного типу, які завдання
отримали `done` замість справжнього вводу, які завдання лишилися без полів і
чому. Без цього не можна довіряти партії зі 120 уроків.