jellybit/openspec/changes/archive/2026-06-30-web-ui-design-port/design.md

Context

Веб-UI — тонкий транспорт над ядром (приём в ingest, команды в worker, чтение в store). Рендер server-rendered через html/template, ассеты встраиваются go:embed (web/web.go). Сейчас встроены только шаблоны; статика (CSS/JS/шрифты) не отдаётся, «живость» сделана грубым <meta http-equiv="refresh" content="5">, оформление — инлайн-<style> с хардкодом цветов.

Готов дизайн (tmp/design/): семантический HTML + единый jellybit.css (токены, тёмная тема по ОС), спроектированный под этот стек — без сборки, npm, React. Превью целевых путей раскладки уже считается на сервере через internal/layout.BuildLinks (поле reviewView.Preview) — это источник истины имён, дублировать его нельзя (инвариант: превью = реальная раскладка).

Стек зафиксирован с заказчиком: htmx (через манифест с checksum, без Node), шрифты self-hosted, статика через go:embed. Реактивных фреймворков нет: клиентский режим ручной раскладки файл→серия отложен (операция редкая), вместе с ним отложен и Alpine.js — его добавим, когда виджет понадобится. Живые обновления прогресса — отдельный change (web-live-updates), здесь meta-refresh просто убирается.

Goals / Non-Goals

Goals:

• Перенести дизайн tmp/design/ в прод-шаблоны без шага сборки.
• Встроить и отдавать статику (CSS, htmx, Alpine, шрифты) из одного бинаря.
• Единая дизайн-система: один CSS, токены, тёмная тема по ОС, бейджи статусов.
• Общие партиалы (шапка, бейдж, виджет «файл→раскладка») вместо дублей.
• Добавить страницу download (просмотр одной загрузки).
• Превью путей на ревью — показ из единого серверного расчёта internal/layout.

Non-Goals:

• Живые обновления прогресса/SSE (отдельный change).
• Клиентский режим ручной раскладки файл→серия (S·E, нумерация, live-превью) и Alpine.js под него — отложены до реальной необходимости (операция редкая).
• Изменение доменного поведения (приём, распознавание, петля ревью, команды).
• Авторизация веб-UI (остаётся вне scope, доверенная LAN).
• npm/бандлер/CSS-постпроцессинг.

Decisions

D1. Статика через go:embed + http.FileServer под /static/

web/web.go встраивает static/* рядом с templates/*. Роут r.Handle("/static/*", http.StripPrefix("/static/", fileServer)) с Cache-Control (длинный max-age для вендорных файлов и шрифтов; для CSS — умеренный, либо cache-busting через ?v=<hash>, посчитанный при старте).

Альтернативы: отдавать с диска — отвергнуто (ломает однобинарность); CDN для htmx/Alpine — отвергнуто (внешняя сеть, инвариант self-host).

D2. Шрифты self-hosted через @font-face

IBM Plex Sans/Mono кладём в web/static/fonts/, подключаем @font-face в jellybit.css. Из шаблонов убираем <link> на Google Fonts.

Почему: umbar — домашний сервер, не зависим от внешней сети, не утекает referrer. Handoff сам это рекомендует.

D3. Зависимости фронта — наколеночный менеджер: gitignore + идемпотентный фетч

Вендорные ассеты (htmx + шрифты IBM Plex) не храним в репозитории — web/static/vendor/ в gitignore. Источник истины — манифест web/assets.manifest (строки <путь под web/static/> <url> <sha256>). task assets идемпотентен: для каждой записи — если файл есть и sha256 совпал, берём с диска; иначе качаем и сверяем (несовпадение валит таргет). Node/бандлер не вводим. Alpine.js не вводим — реактивных виджетов в этом change нет (см. Non-Goals).

Граница вендора. В vendor только фетчабельные третьесторонние пакеты (htmx, woff2-шрифты). Авторские jellybit.css (с вшитым @font-face на ../vendor/ fonts/) и app.js — наш исходник, коммитятся как обычно (качать неоткуда).

Сборка. go:embed templates static встраивает и vendor, поэтому файлы должны быть на диске к моменту go build. task build/task run зависят от task assets. Бинарь остаётся самодостаточным (всё встроено), репозиторий — без вендора. Размен: канонична сборка через Task; голый go build без task assets соберёт бинарь с неполной статикой (css есть, шрифтов/htmx нет) — это принято.

Альтернативы: (1) коммитить результат фетча — отвергнуто заказчиком (не хотим вендор в репо). (2) npm + бандлер (Parcel/esbuild) через Docker — отвергнуто сейчас: бандлить нечего (htmx — готовый <script>, своего JS ~ноль), целый рантайм ради пары файлов. Дорастёт фронт до своих компонентов — отдельный change и esbuild (проще Parcel; есть Go-биндинги, можно без Node).

D4. Партиалы через template.ParseFS нескольких файлов

Выносим общие куски в web/templates/partials/: header.html, status_badge.html (карта state→class/подпись), layout_widget.html (виджет «файл источника → раскладка», общий для review и download). Бейдж рендерится по state — карту держим в одном партиале ({{define}}), не дублируем по страницам. Текущий add-FuncMap сохраняем; при нужде добавляем маленькие чистые функции-хелперы.

Почему: handoff (п. 7) прямо просит вынести шапку, бейдж и виджет в общие партиалы — сейчас они продублированы.

D5. download.html — новая страница /download/{id}

Новый GET-хендлер + view-структура: распознавание, файлы→раскладка (тот же партиал), раздача, история/таймлайн. Действия — по состоянию (как в index), формы переиспользуют уже существующие /ui/downloads/{id}/* эндпоинты.

D6. Ручная раскладка файл→серия — отложена

Клиентский режим ручного редактирования (S·E по файлам, нумерация, live-превью) в этот change не входит — операция редкая, не оправдывает реактивный виджет и Alpine.js сейчас. На ревью остаётся показ файлов и серверного превью (read-only) + существующие действия через формы/htmx (уточнить/перераспознать/выбрать кандидата/применить/позже/отклонить).

Когда понадобится — заведём отдельный change: тогда же выберем подход (клиентская валидация + серверный dry-run превью переиспользует layout.BuildLinks, чтобы не дублировать правила имён в JS) и добавим Alpine.

D7. Убрать meta-refresh и инлайн-стили

<meta http-equiv="refresh"> и <style> удаляются. До change живых обновлений список статичен (обновление — перезагрузкой). Это осознанный временный шаг, чтобы не смешивать презентацию с поведенческим изменением.

Risks / Trade-offs

• Устаревание/дрейф htmx → версия и sha256 в манифесте; обновление осознанное (правка манифеста + task assets с проверкой хеша).
• URL-rot / офлайн-сборка (vendor не в репо) → первая сборка требует сети, дальше файлы кэшируются на диске (идемпотентно). Митигация: пиннинг версий + два рабочих зеркала (unpkg/jsdelivr), URL правится в манифесте. Если понадобится жёсткая офлайн-воспроизводимость — внутреннее зеркало или возврат к коммиту.
• Регресс действий при переносе шаблонов (поле без name, не та форма) → опираемся на разметку <!-- action: … --> в прототипах и существующие хендлеры; проверяем каждое действие по состоянию; ревью кода до archive.
• Временная потеря авто-обновления (D7) → приемлемо, закрывается следующим change; список обновляется перезагрузкой.
• Рассинхрон карты статусов между бейджем и доменом → карта в одном партиале + спека требует полноты покрытия всех состояний.

Migration Plan

1. Манифест + идемпотентный task assets (фетч htmx и шрифтов в gitignored web/static/vendor/ с проверкой sha256); task build/run зависят от assets; добавить авторские web/static/{css,js}, расширить go:embed.
2. Роут /static/* + Cache-Control.
3. Партиалы (header, status_badge, layout_widget); переключить index/review.
4. Добавить download.html + хендлер /download/{id}.
5. Убрать meta-refresh и инлайн-стили.
6. task lint + task test; ручная проверка действий по состояниям.

Откат — презентационный, без миграций БД и схемы: revert коммита восстанавливает прежние шаблоны.

Open Questions

• Cache-busting CSS: ?v=<hash> при старте или фиксированный Cache-Control с коротким max-age. Решим при реализации D1 (склонность — хеш при старте).