textmachine/frontend/docs/S4_SESSION_PROMPT.md

Промт: фронт-сессия S4 — библиотека, загрузка, разбор, прогресс (+ спек-правка 0.2.3)

Выдан оркестратором №16 14.08.2026 по D39.130 («гейт S4 пал»). Запуск — по слову владельца.

0. Какую проблему решаем и что даст твой результат

Продукт — веб-сервис художественного перевода книг: пользователь загружает книгу, запускает перевод, подписывает словарь терминов, читает результат. Фронт строится этапами S0–S7; пройдено всё до S3.7 включительно: оболочка трёх панелей по референсу Fleet, слой данных на контракте OpenAPI (MSW как сетевой мок), i18n-каталог, гейты. Чего до сих пор НЕ существует — пути пользователя от «у меня есть файл» до «книга переводится»: форма добавления книги есть как вид (модал S3.5 по antigravity_add_folder.png), но никуда не отправляет; статусы uploading/parsing/rejected в контракте есть, а экраном не прожиты; запустить прогон с экрана нельзя. До сих пор это было честно: серверной ручки загрузки не существовало. 14.08 платформа P5 принята (D39.130) — POST /books построен и жив, и вместе с его приёмкой владелец контракта ратифицировал пакет правок спеки (0.2.3), которые вносишь ты. Твой результат = пользовательский путь загрузки и запуска работает на форме контракта 0.2.3, и следующая сессия (S5, подпись банка) строится на книге, которую в интерфейсе можно завести, а не только замокать.

Ты — девятая фронт-сессия. Промт — твой ЕДИНСТВЕННЫЙ контекст: ты не видишь чужих переписок; всё несущее — здесь или в названных доках. Дом фронта остаётся миром моков (MSW по контракту); живой стенд платформы — только опциональная проба, §10.

1. Онбординг (порядок чтения, до кода)

1. CLAUDE.md (корень) — гардрейлы проекта; из них жёсткие для тебя: зона записи ТОЛЬКО frontend/, ты НЕ коммитишь, .env не читать, чужие незакоммиченные файлы не трогать.
2. frontend/docs/FRONTEND_SESSION_PROMPT.md — живой носитель норм зоны: §«Зона и git», §3 сценарий (тебе — §3.1–3.4), §4 жёсткие ограничения, §5.1 поддерживаемость, §7 «как работать». Статусные абзацы там частично исторические — статус этапов только в frontend-PROGRESS.md.
3. frontend/docs/frontend-PROGRESS.md — шапка «Текущее состояние» + раздел «Решения владельца по продукту» (перевешивает всё в старых промтах) + записи S3.5–S3.7 и приёмок.
4. frontend/docs/BACKLOG.md (Ф-строки) и frontend/docs/STACK_DECISIONS.md (пины — не двигать).
5. Контракт: зонная копия frontend/docs/api-contract/openapi.yaml (0.2.2, байт-зеркало канона docs/architecture/14-api-contract/openapi.yaml) + компаньон-README рядом с каноном (провенанс, К-вопросы, §2.15 — потолок прогона).
6. Референсы frontend/references/*.png — открой глазами, если трогаешь вид.

Эхо-протокол: первый деливерабл — ≤10 строк «что я понял: скоуп / инварианты / не-делать» ДО работы. Расхождение чинится на минуте пять, не на приёмке.

2. Задача 1 — спек-правка 0.2.3 (делай РОВНО так; ратифицировано D39.130 п.2в + ратификация ниже)

Правишь ЗОННУЮ копию frontend/docs/api-contract/openapi.yaml, бампаешь info.version до 0.2.3, перегенерируешь типы (npm run contract), spectral зелёный. Канон правит оркестратор диффом при лендинге — байт-сверку не выравнивай сам, расхождение с каноном на время сессии легально (прецедент Ф-47/0.2.2). Пять правок:

• PD-172: у createBook записать проводное правило — часть file идёт последней в multipart-форме; поля после файла = 400. Причина (одной строкой в описание): платформа читает форму потоково и обязана увидеть языки до тела файла.
• PD-173: у отклонённой книги появляется машинная причина — поле с закрытым enum по словарю платформы (source_unreadable · not_configured · parser_unavailable; её колонка books.reject_reason, миграция 00013 — сверь имена значений по platform/ read-only, код первичен). Продуктовые фразы различения пишешь ТЫ (слово владельца 14.08: «пусть сам придумает, только над хорошими вариантами подумает»). Рамки: фразы должны честно ложиться на РЕАЛЬНЫЙ флоу отказов (движок отдаёт платформе классы отказа, платформа сводит их в этот enum — прочитай маппинг read-only, чтобы фраза не врала о причине), при этом НЕ раскрывать внутреннее устройство (ПТ-33: ни стадий, ни моделей, ни слов вроде «манифест»/«парсер движка»; та же дисциплина, что у Problem.title) и не звучать тревожно (§3.8). Разное следующее действие — разные фразы: «файл не тот» → проверить файл; «сервис недоступен» → повторить позже. В UI — через словарь с веткой неизвестного, как все enum; свои фразы вынеси в отчёте отдельным списком на утверждение владельцем.
• PD-174: назвать классы ответов, которые провод уже даёт, а спека молчит: 404 на POST /books у инстанса без интейка; 503 у resume на деплое без маркер-команды/шаблона потолка (0.2.1 ратифицировала 503 только для СТАРТА).
• PD-180: описание createBook честное: 201 несёт parsing, не «responds immediately … enters uploading» (uploading наблюдаем только параллельным чтением библиотеки); плюс перечень отказов интейка: 400 (>16 частей формы; текстовое поле >1 КиБ), 413 (потолок тела — порог принадлежит деплою, числа в спеку не зашивать), 408 (тело не успело за дедлайн маршрута — медленный клиент, лечение повтором).
• title в BookIntake — необязательное поле: пустое/отсутствующее = «название даст разбор» (сегодня платформа берёт имя загруженного файла), заполненное = задано вручную и разбор его не перепишет. Ратифицировано оркестратором 14.08 как исполнение замечания 12 владельца (S3.5: «автор вводит название руками ЛИБО скипает — источники различать»; форма это уже разводит, а отправить рукописное название до сих пор некуда — черновик S3.5 висел без ратификации). Владелец промт ревьюит — отмена этого пункта одной репликой; дошла отмена аддендумом → эхо-подтверди и отрази в отчёте.

3. Задача 2 — загрузка книги (форма → createBook)

Половина Ф-26. Модал «Добавить книгу» отправляет форму через слой src/api/ (типы createBook уже сгенерены), MSW-хендлер — по форме 0.2.3, включая порядок частей (file последним) и ветки отказов. Экранный путь по §3.2–3.3 сценария:

• Прогресс отправки файла видимый (книги бывают десятки МиБ). fetch прогресса отправки не даёт — механизм выбери сам (XHR либо иное) и аргументируй в отчёте; слой данных остаётся одним входом, гейт транспорта (src/api/** only) в силе.
• После 201 книга в библиотеке в parsing — разбор это отдельный видимый шаг, не часть перевода. ⚠ Числового прогресса разбора у контракта НЕТ — процент не выдумывать, честное состояние «разбирается»; по завершении главы появляются в дереве, статус not_started.
• Отказ (rejected) — с причиной по PD-173 и советом, различимым по классу (файл не тот ≠ сервис недоступен), фразы — как в задаче 1. Отказные ветки (400/408/413/404) — честные состояния формы, не алерты; тон — §3.8 («если экран выглядит тревожным — он неправильный»).
• Подтверждение успешной загрузки видимое: размер/объём/язык (§3.2) — из данных контракта (character_count, chapter_count, языки), не выдумывая полей.

4. Задача 3 — запуск прогона с ручкой потолка (остаток строки 126 единого бэклога)

Форма запуска перевода. Ратифицировано (D39.110/115, компаньон §2.15 — не переоткрывать):

• Перед показом формы читается GET /books/{id}/run-options; шкала потолка строится из CeilingBounds в ГЛАВАХ — никаких долларов, сумм и оценок стоимости на экране (§4.8 в силе; пересчёт «главы→деньги» — целиком платформа).
• ceiling_chapters обязателен, ноль выбрать нельзя; предустановка шкалы = default_chapters от платформы (клиент своё значение не выбирает — это продуктовая политика); max_chapters: 0 = старт недоступен, честное исчерпанное состояние вместо шкалы.
• Bounds приходят готовыми и уже подрезанными — клиент не клампит второй раз и не выводит свои; между чтением и стартом они могут уехать — 409 на старте обрабатывается пере-чтением run-options и честной фразой, не ретраем втихую.
• Галочка «остановиться на подписи банка» (verify_bank) — параметр ЭТОГО запуска, не глобальная настройка (решение владельца 02.08, §4 п.11 промта зоны).
• paused — прожитое состояние прогресса (ПТ-35: стоп по потолку = статус paused + оповещение). Фраза «остановлена: лимиты» зарезервирована за владельцем (В-3/В-6) — берёшь существующую из каталога, не переписываешь; механизм оповещения (статус-полоса/бейдж уже несут состояние — нужен ли отдельный тост) реши сам и аргументируй. После потолочного стопа resume сам по себе прогон не двигает — resume как «продолжить после потолка» не предлагать (описание resume в спеке); различение «свой потолок vs нет кредита» — К-13, на владельце, не решай. Страница лимитов GET /usage остаётся в настройках = S7 (Ф-27) — эту диспозицию не двигай.
• ⚠ На ЖИВОЙ платформе потолочный стоп сегодня приезжает failed — потребительская половина шва (П-15 зоны платформы) ещё не построена, PD-113 открыт. В мире моков строй ПО КОНТРАКТУ (paused, EventCeiling); от живого стенда правильного поведения не жди и не подгоняй под него ни код, ни тесты.

Прогресс во время прогона — по построенному useRunStream: пер-главные индикаторы в дереве и общий прогресс в статус-полосе уже живут на фикстурах (одна доля без названий фаз, ETA из eta_seconds — ратифицировано); доведи их до пути «книга, заведённая формой, переводится» в мире моков. Внутренности конвейера не раскрывать (§4.1).

5. Задача 4 — библиотека на настоящем масштабе

• Хвост Ф-12: дерево глав ПЛОСКОЕ — на 2284 разделах нужна группировка (по сотням или иная — реши сам по референсу и замеру на /scale, аргументируй).
• Все статусы BookStatus прожиты в дереве и карточке книги — включая uploading (виден параллельным чтением), parsing, rejected с причиной. Метки состояния — из словаря с веткой неизвестного; слова, зарезервированные за владельцем (В-3/В-8), НЕ трогать и не укорачивать.
• Ф-42 (потолок keep-alive вкладок) — по замеру: реши сам, чинить или отложить с записью.

6. Задача 5 — находки приёмки S3.7 (все получают диспозицию)

Ревью приёмки: 12 подтверждённых (1 high) + 16 минорных. Из подтверждённых 9 несущих — список ниже; остальные 3 — поправки к записи S3.7 (цена бандла, дрейф ширин hidden, счёт «106 из 119»), их носители — запись оркестратора 14.08 в журнале и задача 7. Каждой — диспозиция в записке-плане (починено с тестом / не воспроизводится с замером / отложено со строкой):

1. (high) Дубль подстановки строк: запись S3.7 ложно клеймила «заполнение вынесено в src/i18n/fill.ts, его импортируют и приложение, и сцены» — scenes.mjs держит собственный инлайн-филлер say() с ДРУГОЙ семантикой пропуска, добавленный самой S3.7. Сведи к одному носителю.
2. Отметка «перечитывание в пути» ставится без старта чтения и глушит следующие кадры ключа (useRunStream.ts:146 на момент приёмки).
3. onResync не чистит asked — отметки прежней эпохи съедают кадр в окне ресинка (:42).
4. Клейм «resync не рвёт живой поток» — принять только по живому инструментированному прогону с задержкой ответа (статика resetQueries говорит обратное).
5. Сцена hidden: прекондиция «ушли до прихода банка» не ассертится (гонка с синхронным моком), сторож дифференциальный — симметричная регрессия замера пройдёт; и «таблица вообще нарисована» не проверяется (два пустых замера равны).
6. Дырка ESLint-гейта строк: вычисленный литерал (?? 'Word', тернарник) в читаемом атрибуте и литерал в expression-child проходят — живой экземпляр Showcase.tsx:134.
7. Perf-оседание может проходить вакуумно: заходы 2–5 ждут 300 мс против конвенции 700.
8. Zoom-ассерт «в ряд» не запрещает стопку (сравнивает left с left, не с right).
9. Кадр status не перечитывает список глав — по собственной посылке Ф-49 его счётчики на границе стадии тоже протухают.

Минорные (актуальный остаток свода; часть уже закрыта попутно — сверь и диспозиционируй коротко): свип языка catalogue.test.ts не метёт package.json и безрасширенный scripts/githooks/pre-commit · гейт вызовов каталога держится на имени локальной переменной text · шапка ru.ts ссылается на несуществующий src/i18n.test.ts · perf: удлинение запроса с 3 до 5 символов само занижает мс/клавишу · защёлка флага съёмки — эвристика окна 150 мс (знать, не чинить без замера).

file:line — ориентиры на момент приёмки, код первичен. Несогласие с находкой = диспозиция с замером, не молчание (образец: арбитраж 8.1, где права оказалась сессия).

7. Задача 6 — гигиена зонных доков и арбитраж двух чисел

Стейлы (аудит-свип 14.08), чинить по факту кода:

• FRONTEND_PLAN.md:42-43 — «платформа = ноль строк кода» устарело (P5 принята, D39.130); :26-30 — таблица §0.1 подаёт строки 95/99–103 как «чего ещё нет» (95 ратифицирована D39.99, 99/100/103 построены D39.122/131) и шлёт читать API_CONTRACT_INPUT.md как живой вход (он под баннером «исполнено»); :207-208 — ссылка на удалённый src/api/types.ts.
• STACK_DECISIONS.md:179 — тулчейн платформы «≥1.26.5» → ратифицирован 1.26.6 (D39.130); :144 — состав npm run check отстал (4 шага против нынешних 7).
• FRONTEND_SESSION_PROMPT.md:62 — «скелет P0 ждёт приёмки» → P5 принята и залендена.
• frontend/README.md:63-66 — зонная копия спеки названа «черновик на ратификацию» — она давно байт-зеркало ратифицированного канона (D39.99/115).

Арбитраж чисел ЗАМЕРОМ (два носителя врозь, оба претендуют на факт): цена бандла i18n — запись S3.7 говорит «724130 (+7999)», Ф-35 говорит «723102 (+6971)»; ключей каталога — запись «147», Ф-35 и живой ru.ts — «157» (верно 157). Прогони сборку и счёт ключей на текущем дереве, живые носители (BACKLOG/план) приведи к замеру; записи хроники НЕ правятся — расхождение назови попуткой в своей записи.

8. Задача 7 — завести Ф-строки (долги без носителя, найдены свипом 14.08)

• RTL-проверка: триггер «появление I18nProvider» НАСТУПИЛ в S3.7 — строка с честной ценой.
• Спойлер достаётся в обход: размытие глифов не прячет текст от поиска по странице (Ctrl+F) и печати в PDF — продуктовое слово нужно, строка + В-вопрос владельцу.
• Канвас-замер ширин не знает lang: при двух CJK-лицах один код-пойнт рендерится по-разному — строка с условием срабатывания.

Плюс одно закрытие по слову владельца 14.08 — Ф-52: поднять --color-danger на ступень до ≥3:1 на полотне панели (тот же приём, что у --color-note 2.98→3.07 в S3.7 — минимальный сдвиг тона, не редизайн), пере-прогнать axe, закрыть строку замером.

9. На владельце — НЕ решать и не трогать

В-7 (плотность интерфейса; держит Ф-54 — обрезку центра на зуме: ЧИСЛО печатай, не чини) · В-8 (слово состояния в дереве) · В-9 (языки интерфейса) · В-4/Ф-30 (глава без заголовка — «на экране ничего не менять», ждёт и строку 160 движка) · Ф-38 (вкладка «Замечания») · К-13/Ф-31 (различение причин паузы) · В-3/В-6 (фразы ступени и паузы) · граница ПТ-33 (добавочные поля BankTerm — форм не выдумывать). Фразы PD-173 — исключение: их пишешь ты (§2), владелец утверждает по отчёту. Пины STACK_DECISIONS не двигать (Ф-28 — измерено и передано, не патчить).

10. Границы скоупа

Подпись банка и его редактирование — S5. Читалка — S6. Экспорт, настройки (вкл. страницу лимитов), светлая тема — S7. Живого канала банка нет (строка 169 единого — гейт S5). Добавление ГЛАВЫ (§3.10 промта зоны) не строить: ручки в контракте не существует — кнопка без действия запрещена нормой зоны; счёл нужным — предложи черновиком правки спеки с пингом, не кодом. Мок-слой остаётся домом фронта (Ф-29 — триггер сноса не наступил); опционально, если локальный стенд платформы поднимется без боя — smoke живого POST /books через dev-прокси (same-origin, В-кватер; переключатель TM_PLATFORM дев-сервера уже существует — S3 чинила его достижимость) с честным отчётом; это НЕ гейт сдачи, со стендом не воюй, и помни каветы §4 про П-15: живой стенд местами отстаёт от контракта — эталон формы всегда спека, не стенд.

11. Самопроверка и сдача (мандат, не пожелание)

• Ревью исполнением: каждый экранный путь прогнан живым браузером (скриншот-цикл/сценарии), каждый новый гейт и тест проверен ЖИВЫМ нарушением, тесты фиксов падают на до-фиксном коде. Вердикт о поведении браузера без живого прогона = PLAUSIBLE, не факт (D39.129).
• Адверсариальное ревью диффа — механизмом, author≠reviewer: независимые ревью-агенты по диффу с установкой опровергать; субагенты/параллельные агенты для этого разрешены явно — дефолт-запреты харнесса на этот пункт не распространяются. Артефакт — таблица «находка → диспозиция» в записи журнала; «перечитал внимательно сам» исполнением НЕ считается.
• Предметные оси ревью этого пака (вправе добавить свою или аргументированно снять): (1) контракт — каждая форма данных из спеки, новая потребность = черновик правки спеки, не фикстура (класс «фикстура выдумала форму» ловился четырежды); (2) доступность — axe на новых экранах/сценах, полный путь загрузки и шкала потолка проходимы клавиатурой; (3) статусные ветки — каждая (uploading/parsing/rejected по причинам/404/408/413/409/paused) показана сценой или кадром, не только тестом.
• Заявление = команда: каждое число отчёта — с командой, которой получено; «сделано» без прогона не писать; чего НЕ сделал/не удалось — отдельным явным списком.
• Гейты не подгонять: порог/проверку не двигать ради зелени; несогласие с гейтом — пинг.
• Сдача: npm run check и npm run check:full зелёные; новые сцены в батарее; запись в frontend/docs/frontend-PROGRESS.md (механика, замеры, диспозиции всех находок §6, В-вопросы); BACKLOG обновлён; дерево НЕ коммитить — лендит оркестратор.

12. Канал вопросов

Непонятно / промт конфликтует с кодом или доками / нужна правка вне frontend/ → пинг оркестратору через владельца и запись в зонный журнал; НЕ интерпретация и НЕ правка чужой зоны. Настоящие развилки эскалируй быстро — это норма, а не слабость.