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>

applications/PoP/roomtest/TASKS.md

@@ -13,6 +13,8 @@
 
 ## P0 — делаем сейчас
 
+*(KBD-1 закрыт до финальной полировки — см. ниже; следующая в работе — CLIP-1.)*
+
 ### KBD-1. Shift + стрелки: нажатия теряются — **ПРИЧИНА НАЙДЕНА, ФИКС ПРОВЕРЕН**
 
 > **Итог (2026-08-01).**  Причина — не наш код и не DI-окна графики: при
@@ -27,6 +29,30 @@
 > четыре Shift+→ подряд дали четыре осторожных шага, `Kid.x` 114 → 147.
 > Цена: `_CODE` +170 Б, кадровый бюджет не затронут (опрос стоит в
 > простое).  Ниже — полный протокол, как к этому пришли.
+>
+> **ОСТАТОК (ручная проверка пользователем, 2026-08-01): «стало значительно
+> лучше, но иногда при зажатом Shift стрелка всё-таки пропускается».**
+> Ощущение, не замер — счётчики на 35 нажатиях подряд потерь не показали,
+> значит остаточная частота заметно ниже прежних ~15 %.  **Задача осознанно
+> ОТЛОЖЕНА до финальной полировки всей программы** (решение пользователя);
+> сейчас клавиатура пригодна для работы.
+>
+> **Где именно осталась дыра — чтобы на полировке не начинать с нуля.**
+> Idle-хук покрывает простой, то есть ~2/3 кадра.  Оставшаяся треть — это
+> занятая фаза, и там DI-окно одного accel-прохода доходит до ~650 мкс при
+> допуске FIFO ~300 мкс.  Пачка байт, целиком попавшая в такое окно, всё
+> ещё может потерять байт — ровно «иногда».  Порядок действий, если
+> вернёмся:
+> 1. Вернуть вызовы `kbd_raw_poll()` между блитами занятой фазы (они
+>    бесплатны; сами по себе не помогали, но вместе с хуком закрывают
+>    именно этот зазор) и при необходимости внутрь тайловых циклов
+>    `pop_bg` — тогда слепым остаётся только тело одного блита.
+> 2. Мерить тем же счётным методом (см. ниже), а не на ощупь: скриптовые
+>    нажатия ровнее человеческих, поэтому набирать выборку от 50 нажатий.
+> 3. Если и это не добьёт — остаются два рычага вне нашего кода: Scan Code
+>    Set 3 через BIOS `$EA` (убирает «fake shift» в корне, но в MAME
+>    непроверяемо — обратный путь к клавиатуре не разведён) и общий
+>    `m_irq_off_timer` в драйвере MAME.
 
 **Симптом (пользователь, 2026-08-01).**  Залипаний почти нет, но при
 УДЕРЖИВАЕМОМ Shift первые один-два нажатия ← дают осторожные шаги, дальше

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 переполняется.  Полный протокол и куда копать —
+и трёхбайтовый FIFO переполняется.
-`applications/PoP/roomtest/TASKS.md`, задача KBD-1.  Смысл может быть
+
-только у ПЛОТНОГО опроса (в цикле ожидания кадра), это ещё не проверено.
+**Работает только ПЛОТНЫЙ опрос — порядка раза в 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 подряд отдаёт

libc/include/kbd_raw.h

@@ -68,14 +68,18 @@ void kbd_raw_sync(void);
  * этом переполняют FIFO: теряется make («нажатие не сработало») или break
  * (залипание).
  *
- * ЧЕСТНАЯ ОГОВОРКА ПО ЭФФЕКТИВНОСТИ (замер 2026-08-01, PoP roomtest,
+ * КАК ЕЁ ЗВАТЬ (замеры 2026-08-01, PoP roomtest — см.
- * см. applications/PoP/roomtest/TASKS.md, KBD-1): расстановка «несколько
+ * applications/PoP/roomtest/TASKS.md, KBD-1):
- * вызовов за кадр, после тяжёлых фаз» НЕ ДАЁТ НИЧЕГО — потери те же, что
+ *  - «несколько вызовов за кадр, после тяжёлых фаз» НЕ ДАЁТ НИЧЕГО —
- * без неё.  Такие вызовы попадают в участки, где прерывания и так
+ *    потери те же, что без них: такие вызовы попадают в участки, где
- * разрешены, и лишь дублируют трамплин.  Смысл появляется только у
+ *    прерывания и так разрешены, и лишь дублируют трамплин;
- * ПЛОТНОГО опроса (в цикле ожидания, десятки-сотни раз за кадр), и это
+ *  - работает только ПЛОТНЫЙ опрос, порядка раза в 0.5 мс.  Столько
- * ещё не подтверждено замером.  Не ставить эту функцию в игровой цикл
+ *    времени есть даром в ожидании кадра, поэтому штатный способ —
- * «на всякий случай» — сначала померить.
+ *    повесить эту функцию idle-хуком графики:
+ *        gfx_set_idle_hook(my_poll_wrapper);   // <gfx.h>
+ *    Проверено: 35 нажатий стрелки с зажатым Shift → 35 дошедших make
+ *    против 9 из 10 без хука.
+ * Не ставить в игровой цикл «на всякий случай» — сначала померить.
  *
  * Тело идёт под DI и БЕЗУСЛОВНО делает EI на выходе: рассчитано на вызов
  * из главного цикла, из ISR звать нельзя. */