Sprinter-SDCC/examples/mdview2/docs/mdview2-plan.md

# mdview2 — план: рендер-кэш вместо живого парсинга на каждый скролл

Контекст и обоснование — см. обсуждение 2026-06-23 (после оптимизации mdview через
`<bios/text.h>`, см. `mdview-модель-документа-и-рендеринг.md`). Идея: вместо того
чтобы при каждом скролле повторно идти в файл (`fb()`, W3-банкинг) и гонять
markdown inline-парсер (`handle_inline_marker`/emphasis state machine), один раз
отрендерить каждую логическую строку в готовый байтовый буфер и дальше выводить
его на экран напрямую — без парсинга, без обращения к исходному файлу.

Ключевые подтверждённые факты (эмпирически в MAME, не из документации):

- **Формат буфера ESTEX `WINCOPY`(59h)/`WINREST`(5Ah)** — пара байт `(char, attr)`
  на ячейку, по строкам, шаг строки = `width*2`, без паддинга. Можно генерировать
  самим, не вызывая `WINCOPY`. `WINREST` копирует сразу `H` строк одним вызовом.
  Детали ABI и регистров — см. `tests/winrest/winrest.c`.
- **Бюджет EMM**: 256 страниц (4 МБ) total, 215 (3440 КБ) free на старте программы.
  Файл+индекс в худшем случае (128 КБ файл) съедают 16 страниц (256 КБ) — остаётся
  ≈199 страниц (3184 КБ). Кэш всего документа целиком (даже худший случай:
  16384 строк × 160 байт = 2.6 МБ) укладывается без LRU/частичного кэша.

## Единый формат строки (пересмотрено 2026-06-23)

Исходно планировалось два типа строк (тип 1 — многоцветные, помещающиеся;
тип 2 — nowrap/code, один стиль, чистый текст для экономии памяти). От этого
деления отказались: строки таблиц (`IF_NOWRAP`, но не `IF_CODE`) всё равно
проходят inline-парсер и могут содержать несколько атрибутов (bold/italic в
ячейках) — предположение "один стиль" для них неверно. Бюджет EMM
([[sprinter_emm_budget]]) с большим запасом покрывает (char,attr)-формат для
ВСЕХ строк без исключения, поэтому усложнение не оправдано.

**Единый формат**: кэш-запись = `len` пар `(char,attr)` — реальная длина
контента в ячейках, без паддинга до 80, капается на `MAX_CACHE_LINE_LEN`=255.
Вывод: `bios_fillcharattr(' ', base_attr, SCREEN_W)` (очистить строку) →
`win_rest(row, left_margin, 1, len, page)` (контент). Для широких nowrap-строк
горизонтальный скролл (Фаза 5) — это просто смещение НАЧАЛА среза внутри ТОГО
ЖЕ (char,attr)-буфера на `hscroll*2` байт, тот же `win_rest`, без отдельного
плain-текстового формата и без необходимости на лету "разворачивать" текст+
атрибут в пары.

## Фазы реализации

### Фаза 0 — скаффолдинг `examples/mdview2/` [СДЕЛАНО 2026-06-23]
Новая директория со своим `Makefile`/`app.mk` (по аналогии с `mdview/`, не
модифицируем `mdview.c`). `mdview2.c` — копия `mdview.c` без изменений логики
(только usage-строка/заголовок комментария). Собирается чисто, дискета собрана.

### Фаза 1 — формат кэша и директория строк [СДЕЛАНО и ЗАКРЫТО 2026-06-23]
Реализовано в `mdview2.c`:
- `cache_rec_t` (РОВНО 8 байт: `page`, `off` (uint16_t), `len`, `flags`,
  `reserved`, `pad[2]`; размер задаётся `CACHE_DIR_REC_SIZE = sizeof(cache_rec_t)`,
  НЕ хардкодом — см. разобранный инцидент ниже) — **отдельная** директория
  (`cache_dir_phys[]`/`cache_dir_get`/`cache_dir_put`), своя ёмкость =
  `file_pages+1` страниц (как у индекса). **Важное уточнение к исходному тексту
  плана ниже**: директория НЕ переиспользует слоты `idx_rec_t` in-place —
  рендер-воркер (Фаза 2) при обработке строки N может заглядывать в idx-записи
  СОСЕДНИХ строк (откат cont-сегментов, line_idx+1 для границы сегмента); если
  бы строка N-1 была перезатёрта сразу после своего рендера, воркер строки N
  прочитал бы уже не исходные off/flags, а указатель в кэш — поломав откат.
  Бюджет EMM ([[sprinter_emm_budget]]) позволяет отдельный массив — он безопаснее.
- Пул контента — отдельные EMM-страницы (`cache_content_phys[]`), ленивый рост
  по 1 странице в `cache_reserve()` (bump-allocator, запись никогда не
  разбивается через границу страницы; длина капается на `MAX_CACHE_LINE_LEN`=255
  ячеек).
- `cache_commit()` = один `bank_write()` на строку (буфер строки собирается
  локально в W1/W2 заранее, не в W3 — иначе конфликт с `fb()` при чтении
  исходника во время рендера).
- `win_rest()` (ESTEX WINREST 5Ah) — вывод готового буфера на экран.
- `phase1_selftest()` — самопроверка (резервирует/коммитит 4 тестовые ячейки,
  кладёт запись в директорию по индексу 0, рисует через `win_rest` дважды
  подряд с координатами через параметры функции) — убрать в Фазе 2.

**Подтверждено визуально в MAME (2026-06-23)**: оба квадрата 2×2 на месте, без
единой задержки, с координатами через переменные — Фаза 1 полностью закрыта.

**Разобранный инцидент (НЕ платформенный квирк)**: по пути долго казалось, что
`win_rest()` после "всплеска" обычных BIOS print-вызовов рисует буфер в
неправильном месте, причём воспроизводилось только когда `row`/`col` приходили
через переменные, а не как константы — это и было ключом. Настоящая причина:
`cache_rec_t` фактически занимал 7 байт (SDCC z80 не паддит структуры), а
`CACHE_DIR_REC_SIZE` был захардкожен как 8 — `bank_read`/`bank_write` копировали
8 байт в 7-байтный буфер на стеке, затирая соседнюю переменную (параметр `col`)
вызывающей функции. Фикс — `cache_rec_t` явно до 8 байт + размер через
`sizeof()`. Полная история и общий урок — [[sprinter_winrest_format]] и
[[defer_unexplained_quirks]].

### Фаза 2 — рендер-воркер (бывший `render_line`) [СДЕЛАНО 2026-06-23]
`render_line_to_cache(line_idx)` — адаптация `render_line()`: та же классификация
строк/префиксов/inline-парсинг (`handle_inline_marker`, emphasis state machine,
soft-wrap join) БЕЗ ИЗМЕНЕНИЙ, но вместо `bios_writeattr`/`flush_run`/`wrchar`/
`bios_fillcharattr` на экран — пишем `(char,attr)` пары через `cc_put`/`cc_fill`
в локальный `cellbuf` (без батчинга через `runbuf`/`flush_run` — тот паттерн был
нужен только чтобы минимизировать число BIOS-вызовов, при записи в локальный
буфер смысла нет, пишем посимвольно сразу по месту), затем ОДНИМ
`cache_reserve()`+`cache_commit()`+`cache_dir_put()` коммитим всю строку.
Кэшируется ПОЛНЫЙ контент строки до `MAX_CACHE_LINE_LEN`, без обрезки по
`SCREEN_W` и без среза по `viewport_x` (view/scroll-time понятия, Фаза 4-5).
Также найден и исправлен по ходу баг в `win_rest()`: `IX` всегда указывал на
начало страницы (`#0xC000`), полностью игнорируя `off` — работало только в
Фазе 1, где в кэше была ровно одна запись со смещением 0; как только Фаза 2
начала пакетировать много строк на одной странице с разными `off`, все строки
стали читаться с начала страницы. Фикс: `win_rest()` принимает `off`
(uint16_t), `IX = 0xC000 + off` (новая раскладка ABI сверена через `sdcc -S`
с непустым телом — у `__naked` с пустым телом SDCC не генерирует код доступа
к параметрам, нужен пробный non-naked враппер). Подтверждено визуально в MAME.

### Фаза 3 — фоновый пре-рендер с прогрессом [СДЕЛАНО 2026-06-23]
`emit_seg()` вызывает `render_line_to_cache()` **interleaved** с построением
индекса — но с отставанием на одну строку: рендер строки N требует уже
существующей idx-записи N+1 (источник `seg_end`), которой ещё нет в момент,
когда строка N только создана. Поэтому `emit_seg()` для новой строки рендерит
ПРЕДЫДУЩУЮ (`n_lines-2` после инкремента) — её флаги (`IF_NOWRAP`/`IF_CODE`/
`IF_BLANK`) к этому моменту уже дописаны вызовом `set_*_cur()` на предыдущей
итерации `index_lines()`. Последнюю строку файла (у которой "следующей" не
будет) дорендеривает сам `index_lines()` после выхода из цикла, как и
`render_line()` делал для последней строки при живом рендере (`seg_end =
file_size`). Требует, чтобы `cache_dir_phys[]` был выделен ДО `index_lines()` —
это уже так (`load_file()` выделяет директорию кэша, затем вызывается
`index_lines()`).

**Важное сужение скоупа относительно исходного текста плана ниже**: пункты
"спиннер крутится, пока `rendered_up_to < n_lines`" и "скролл ограничен
диапазоном `[0, rendered_up_to]`" **не реализованы и не нужны** в этой
архитектуре — рендеринг происходит СИНХРОННО внутри той же однопроходной
`index_lines()`, без событийного цикла во время загрузки; пользователь
физически не может начать скроллить, пока `index_lines()` не вернёт
управление, а к этому моменту весь документ уже полностью в кэше. Спиннер
из `index_lines()` (каждые 16 строк) сохранён как есть — он покрывает
индексацию+рендер вместе, отдельный прогресс-индикатор не нужен.

### Фаза 4 — cache-only draw path при скролле
Цикл перерисовки видимой области (после пре-рендера) идёт **только** по
директории строк → `win_rest` (тип 1) или срез текста+`bios_writeattr` (тип 2).
Никаких обращений к `fb()`/исходному файлу в steady-state скролле.

### Фаза 5 — горизонтальный скролл для широких nowrap-строк
Срез ТОГО ЖЕ (char,attr)-кэш-буфера по текущему `hscroll`-офсету (смещение
начала на `hscroll*2` байт внутри буфера строки), `win_rest(row, col, 1,
visible_len, page)` с новым `off`. Никакого отдельного плоско-текстового
формата не нужно (см. пересмотр "Единый формат строки" выше).

### Фаза 6 — тестирование в MAME
Тот же набор паттернов, что использовался для mdview1 (заголовки/списки/цитаты/
code-block/bold-italic/nowrap-обрезка), ПЛЮС: реальный замер EMM на большом
документе (не синтетика — проверить, что бюджет из [[sprinter_emm_budget]]
действительно держится на чём-то близком к 128 КБ); UX пре-рендера (спиннер +
ограничение скролла, отсутствие "дыр" в недорендеренной области); проверка
`win_rest` на РЕАЛЬНОМ отрендеренном контенте (не только синтетический A/B/C/D
тест из `tests/winrest`).

## Открытые вопросы (решить по ходу, не блокируют старт Фазы 0)

- ~~Хранение длины строки в директории~~ — решено в Фазе 1: поле `len` (uint8_t)
  прямо в `cache_rec_t`.
- ~~Деление строк на тип 1/тип 2~~ — отказались (см. "Единый формат строки"
  выше): единый (char,attr)-формат для всех строк, капается на
  `MAX_CACHE_LINE_LEN`=255 ячеек (с тем же индикатором обрезки на этапе вывода,
  что уже есть в рендере для nowrap-строк).
- Освобождать ли страницы исходного файла после того, как все его строки
  отрендерены (вернуть EMM в пул) — даёт больше места про запас, но усложняет
  (нужна гарантия, что назад к файлу обращаться больше не придётся — а это не
  так, если позже добавится поиск по тексту). Не делать в v1.
- BIOS-вариант `WIN_COPY_WIN`/`WIN_RESTORE_WIN` (0B2h/0B3h, RST 8) не проверен
  (см. [[sprinter_winrest_format]]) — ESTEX-варианта достаточно для v1, проверять
  BIOS-вариант только если понадобится экономия на RST-диспетчеризации.