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

# mdview2 — поддержка кодировок (CP866 / CP1251 / KOI8-R / UTF-8)

Статус: РЕАЛИЗОВАНО (2026-06-25). Все фазы сделаны; Фаза 4 — eager-кооперативным
вариантом (см. ниже), а не idle-build. Осталась только проверка на железе и
возможная оптимизация «не строить заведомо бесполезный вторичный набор».

## Цель

- CP1251, KOI8-R — простой 1:1 маппинг байтов [128-255] в CP866 (кириллица
  + основная пунктуация). KOI8-R равнозначна, входит в общий цикл.
- UTF-8 — декодирование с маппингом кириллицы в CP866 + подстановка части
  некириллических символов (стрелки, галочки, тире, буллеты, box-drawing) в
  CP866/ASCII-глифы.
- Автоопределение кодировки при открытии (BOM + дешёвая эвристика).
- F8 (Codepage) — переключение по циклу CP866 → CP1251 → KOI8-R → UTF8.

## Ключевые наблюдения (определяют архитектуру)

1. **8-битные кодировки имеют ОДНУ структуру.** markdown-разметка вся в ASCII
   (`# * | -` …); 8-битные различаются только глифами [128-255]. Значит индекс
   и кэш (смещения, переносы, ширины таблиц) для CP866/CP1251/KOI8-R —
   **общие**; переключение между ними = ремап глифов [128-255], БЕЗ
   переиндексации.
2. **UTF-8 — другая структура** (кириллица 2 байта). Нужен отдельный
   конвертированный CP866-буфер со своим индексом/кэшем.
3. **Проблема рамок таблиц / маркеров.** В кэше намешаны контентные глифы
   (байты-из-источника [128-255] — НАДО ремапить) и вставленные нами CP866-
   глифы (box `│─┼…`, маркер списка 0x07, цитата 0xB3, HR 0xC4 — ремапить
   НЕЛЬЗЯ). По значению байта не различить → различаем по **атрибуту**.

## Архитектура

### Буферы
- `src_phys[]` — оригинальные байты файла (грузим как сейчас; храним всегда —
  под ремап и raw-view, см. memory/mdview2_file_phys_preserve).
- 8-битный режим: `fb()` читает `src_phys` напрямую. Кэш контентных ячеек
  хранит **исходный байт** (не пред-конвертированный).
- UTF-8 режим: отдельные EMM-страницы `utf_phys[]` = UTF8→CP866 конвертация
  src; свой индекс/кэш; `fb()` читает `utf_phys`.

### Различение контент/структура по attr
Каждый структурный глиф получает НЕ-контентный attr:
- box-рамка таблиц → новый `ATTR_BOX` (сейчас TBL_ATTR=ATTR_TEXT — поменять);
- HR (0xC4) → ATTR_HR; маркер списка (0x07) → ATTR_LIST_MARKER; цитата
  (0xB3) → ATTR_QUOTE_MARKER — уже различимы.
Правило ремапа: ремапить `char>=128` только если attr ∈ контентных
(TEXT/BOLD/ITALIC/UNDER/CODE/STRIKE/TITLE1-4). Структурные — как есть.

### Ремап на этапе отрисовки
`draw_line_from_cache`:
- encoding == CP866 или UTF-8: прямой `win_rest` из кэш-страницы (ремап не
  нужен — CP866 identity; UTF-8-кэш уже CP866).
- encoding == CP1251/KOI8-R: читаем кэш-строку в near-буфер, ремапим
  контентные байты [128-255] через активную таблицу (структурные пропускаем
  по attr), пишем в scratch-страницу, `win_rest` из неё. Только видимые ~30
  строк, на скролле — дёшево.

Итого: переключение между 8-битными — мгновенно (меняем активную таблицу +
redraw, draw ремапит). Переиндексация только при переходе в/из UTF-8.

## Детекция кодировки (дешёвый скан байтов, ДО построения)

1. **BOM**: первые 3 байта EF BB BF → UTF8 (и пропустить BOM).
2. **UTF-8 валидность** (если нет BOM): проход, проверка структуры
   (лид-байты 0xC2-0xDF/0xE0-0xEF/0xF0-0xF4 + континюэйшны 0x80-0xBF;
   одиночный 0x80-0xBF, 0xC0/0xC1, 0xF5+ → нарушение). 0 нарушений И есть
   ≥1 multibyte → UTF8. Любое нарушение → 8-бит.
3. **8-бит дизамбигуация** (CP866/CP1251/KOI8-R): счёт попаданий в байты
   самых ходовых строчных русских букв (о е а и н т с р в л) каждой кодировки;
   максимум выигрывает. (Предрасчёт байт-наборов по таблицам.)
4. **Фолбэк**: нет байт ≥0x80 или неоднозначно → CP866 (родная).

## Таблицы (static const, CODE/const-сегмент)

- `cp1251_to_866[256]`, `koi8r_to_866[256]` — байт→байт (ASCII identity;
  кириллица по раскладкам; en/em-dash, «ёлочки», … → CP866-аналоги или '?').
- UTF-8: `utf_cyr_to_866[]` для U+0400..U+045F + компактная таблица символов
  `utf_sym[]` (codepoint→CP866): U+2192→'>'/стрелка, U+2190→'<', U+2713/14 ✓
  →'v'/box, U+2022 •→0x07/0xF9, U+2014/2013 —→'-', U+2026 …→"...",
  U+00A0→' ', U+2500.. box→CP866 box; прочее → '?'.

## Поток загрузки

1. Грузим в `src_phys`. Детект-скан → кодировка E.
2. Если E ∈ {UTF8}: строим UTF-8-набор (utf_phys + конвертация + индекс),
   показываем UTF-8. Иначе: показываем 8-битный (общий индекс на src,
   активная таблица = E).
3. **Ленивый build второго набора в простое.** Главный цикл — НЕ блокирующий
   getkey, а kbhit-поллинг: пока нет клавиш и второй набор (UTF-8 при
   стартовом 8-бит, либо 8-бит при стартовом UTF-8) не построен — докручиваем
   его инкрементально. После — F8 в любую сторону мгновенно.

## F8 — переключение

- Цикл g_encoding: CP866 → CP1251 → KOI8-R → UTF8 → CP866.
- 8-бит↔8-бит: сменить активную таблицу + redraw (без переиндексации).
- в/из UTF-8: переключить активный индекс/кэш на соответствующий набор
  (если построен; иначе достроить — но при ленивом build обычно уже готов).
- Статус-бар: имя кодировки; меню (строка 31): «F8 Codepage».

## Фазы реализации (ИТОГ)

1. ✅ **Ядро 8-бит**: ATTR_BOX; кэш хранит исходный байт; таблицы CP1251/KOI8R;
   ремап в draw (`win_rest_remap`).
2. ✅ **UTF-8 набор**: `alloc_and_convert_utf8` + `utf8_convert` (декодер 1/2/3-
   байт, 4-байтные/битые → `?`); `utf_cyr_to_866[96]` + символьные подстановки
   в `conv_emit_cp` (стрелки 0x18-0x1B, галка 0xFB, буллет 0xF9, тире/кавычки/
   box/° и т.п.; «» → `<`/`>`, т.к. в CP866 гильеметов нет).
3. ✅ **Детекция** (BOM + эвристика), сэмпл — первые **4 КБ** (быстро); хвост-
   обрезка multibyte на границе сэмпла не штрафуется.
4. ✅ **Сосуществование 2 наборов** (`docset_t g_doc[2]` + `doc_save/load/switch`,
   свап «живых» глобалов). Сборка — **ленивая (build-on-demand)**: при старте
   строится только первичный (показываемый) набор; UTF-8 конвертация тоже
   ленивая (в `build_doc`, не до первого экрана → старт быстрый). Второй набор
   достраивается `switch_encoding()` при первом F8-переходе в него (спиннер,
   потом кэш). Eager-вариант отвергнут: удваивал старт и блокировал F8 на время
   фоновой сборки.
5. ✅ **F8** полный цикл CP866→CP1251→KOI8R→UTF8→CP866 (внутри 8-бит — ремап,
   на границе — `doc_switch`/ленивая сборка). Статус: `enc_name` кол.37. Меню
   «F8 Codepage» показывается только когда переключение возможно (`g_f8_enabled`):
   во время сборки 8-битного первичного F8 разрешён в `load_key` (только цикл
   8-бит); во время сборки UTF-8 первичного метка F8 скрыта. F1-справка: секция
   Encoding.

NB: меню-строка разбита на 10 блоков по 8 колонок, метки Fn кладутся в блок
(n-1)*8 (F1→0, F8→7, F10→9).

## Память
- 8-бит: src + scratch-страница для ремапа (1 стр.). Доп. индекса нет.
- UTF-8 набор: utf_phys (≤8 стр.) + свой индекс/кэш-контент. Строится лениво.
- Бюджет 215 свободных страниц (sprinter_emm_budget) — с запасом.

## Открытые вопросы (к реализации)
1. Имя кодировки в статусе — где (зона имени файла / отдельный слот).
2. Набор UTF-8-подстановок символов — приоритет (→ ← ✓ ✗ • — … « » box).
3. Глубина таблиц пунктуации CP1251/KOI8 (минимум кириллица+dash или полнее).
4. Объём детект-сэмпла (весь файл или первые N КБ).

## Риски
- Корректность различения контент/структура по attr — нужно, чтобы ВСЕ
  вставленные глифы имели не-контентный attr (проверить box/markers).
- Два набора индекс/кэш (8-бит + UTF-8) + переключение активного — учёт
  страниц, чтобы не течь и не путать.
- Точность таблиц (особенно UTF-8 символы) — итеративно по факту.