docs: итог KBD-1 — что лечит плотный опрос и что осталось

Ручная проверка пользователем: стало значительно лучше, но редкие пропуски
стрелок при зажатом Shift всё же ощущаются.  Счётчики на 35 нажатиях подряд
потерь не показали, то есть остаточная частота заметно ниже прежних ~15 %.
Задача отложена до финальной полировки программы (решение пользователя) —
для работы клавиатура пригодна.

Записано, где именно осталась дыра, чтобы не начинать с нуля: idle-хук
покрывает простой (~2/3 кадра), а в занятой трети DI-окно одного
accel-прохода доходит до ~650 мкс при допуске FIFO ~300 мкс — пачка байт,
целиком попавшая в такое окно, ещё может потерять байт.  Порядок действий
на возврат: вызовы между блитами занятой фазы, замер тем же счётным методом
от 50 нажатий, и только потом рычаги вне нашего кода (Scan Code Set 3 через
BIOS $EA — в MAME непроверяемо; общий m_irq_off_timer в драйвере).

Заодно сняты оговорки «плотный опрос ещё не подтверждён замером» в
kbd_raw.h и libc-reference.md — теперь там штатный рецепт через
gfx_set_idle_hook.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

docs/TODO.md

@@ -301,6 +301,13 @@ Quick wins:
       подозреваемый — `m_irq_off_timer` в sprinter.cpp: он ОДИН на два
       источника (экран + клавиатура), `irq_off()` гасит обе линии, так
       что кадровое прерывание способно обрезать клавиатурный импульс.
+      **ЗАКРЫТО в рабочем объёме 2026-08-01:** лечится ПЛОТНЫМ опросом —
+      `kbd_raw_poll` повешен idle-хуком графики (`gfx_set_idle_hook`,
+      новый API libbgi) на ожидание кадра, где процессор всё равно
+      простаивает ~2/3 периода.  35 нажатий с зажатым Shift → 35
+      дошедших make против 9 из 10 без хука.  Пользователь на ручной
+      проверке отмечает, что редкие пропуски всё же ощущаются — остаток
+      отложен до финальной полировки, следующий шаг описан там же.
       Полный протокол — applications/PoP/roomtest/TASKS.md, KBD-1.
       Recovery-политика уже терпима к частым overrun'ам (селективный
       wipe, docs/kbd-games.md), но аккорды «держу →, тапнул ↑» и

docs/libc-reference.md

@@ -351,16 +351,23 @@ FIFO SIO — 3 байта, и рассчитывать на «каждый ба
 (чтение порта 0x18 деструктивно, а read-modify-write карты гонится с
 трамплином) и БЕЗУСЛОВНО делает `EI` на выходе — из ISR звать нельзя.
 
-**Замер эффективности (2026-08-01, PoP roomtest — читать до применения!).**
+**Как её звать (замеры 2026-08-01, PoP roomtest — читать до применения!).**
 Расстановка «несколько вызовов за кадр, после тяжёлых фаз» **не даёт
-ничего**: 9 дошедших make-байт из 10 нажатий и с ней, и без неё.  Причина —
-такие вызовы попадают ровно в участки с разрешёнными прерываниями и лишь
+ничего**: 9 дошедших make-байт из 10 нажатий и с ней, и без неё — такие
+вызовы попадают ровно в участки с разрешёнными прерываниями и лишь
 дублируют трамплин.  Там же измерено, что длина DI-окон графики на потери
 НЕ влияет (в кадре вообще без блитов потерь больше), а теряется байт ДО
 чтения порта: примерно 44 % импульсов запроса прерывания не обслуживаются,
-и трёхбайтовый FIFO переполняется.  Полный протокол и куда копать —
-`applications/PoP/roomtest/TASKS.md`, задача KBD-1.  Смысл может быть
-только у ПЛОТНОГО опроса (в цикле ожидания кадра), это ещё не проверено.
+и трёхбайтовый FIFO переполняется.
+
+**Работает только ПЛОТНЫЙ опрос — порядка раза в 0.5 мс.**  Штатный способ
+взять эту частоту даром — повесить функцию idle-хуком графики:
+`gfx_set_idle_hook()` (`<gfx.h>`) зовёт её, пока `gfx_wait_vsync` крутит
+опрос луча, а это ~2/3 периода кадра.  Проверено: 35 нажатий стрелки с
+зажатым Shift → 35 дошедших make против 9 из 10 без хука.  Остаточные
+редкие потери возможны (пачка целиком внутри DI-окна одного accel-прохода);
+полный протокол и что делать дальше — `applications/PoP/roomtest/TASKS.md`,
+задача KBD-1.
 
 **ГЛАВНОЕ СЛЕДСТВИЕ:** пока `kbd_raw_open()` активен, `kbhit/getch/getkey/
 kbd_mod_state` НЕ получают новых событий (в т.ч. CTRLKEY подряд отдаёт