UI_CONTRACT.ru.md

UI-контракт

English · Русский · 简体中文

Обновление CanvasTTY

Раздел «Обновления» показывает текущую версию, проверку обновлений, найденную стабильную версию и release notes, загрузку с прогрессом, готовность к установке и ошибки. Когда проверка находит обновление, на рабочем экране появляется компактное закрываемое уведомление с номером версии и кнопкой «Скачать». Во время загрузки оно показывает прогресс, а по готовности — кнопку «Установить»; нажатие на название открывает раздел «Обновления». Windows portable вместо загрузки из приложения открывает релиз. Закрытие уведомления подавляет его повтор для той же версии и стадии в течение текущей сессии окна; новая версия или стадия готовности может показать новое уведомление. Установка и перезапуск доступны только по явному действию пользователя; при живых сессиях перед ними показано подтверждение завершения. Повторное открытие настроек показывает актуальное состояние из main-процесса. Фоновая проверка не открывает модальные окна и не начинает загрузку.

На macOS системное меню CanvasTTY содержит пункт «Проверить обновления…». Он открывает раздел «Обновления» и запускает ту же ручную проверку, что и кнопка в интерфейсе. Название пункта следует выбранному языку; выбор пункта не начинает скачивание или установку.

Сообщение об ошибке

В «О приложении» есть форма описания проблемы, пояснение состава диагностики и адрес сервера. Отправка происходит только по кнопке; без настроенного сервера и во время отправки кнопка недоступна. Успешная отправка показывает номер отчёта, ошибка сохраняет описание для повторной попытки. Используются текущий язык и оформление настроек. Текст терминалов и переписка не прикладываются.

Этот контракт сохраняет утверждённую концепцию MVP и не даёт ответственности фич расползаться.

Зона Home

• HOME использует фиксированные логические ячейки 82 × 72 с промежутками 18px, поэтому увеличение страницы не уменьшает существующие виджеты. Новый профиль начинает с 16 × 12; исходная композиция остаётся в верхней левой области 12 × 8, оставляя явный запас для плагинов. Сохраняемые граница и сетка видны только в Edit HOME, где правый нижний угол меняет область до безопасного потолка 48 × 36.
• Широкая левая плитка содержит выбранное пользователем подмножество строк лимитов Codex, Claude, Qwen Code, Kimi, OpenCode Go и Grok Build; по умолчанию выбраны только провайдеры с найденным CLI. Видимые строки делят высоту плитки поровну, а при четырёх и более строках переходят в компактную плотность, чтобы каждая иконка, countdown и usage rail оставались внутри дефолтной плитки. Пустой выбор показывает явное пустое состояние. Настройка отображения не отключает фоновые запросы лимитов. У каждой строки есть source-backed adapter: Qwen честно показывает cli-not-found или unsupported-protocol, потому что его мультипровайдерный CLI не имеет универсального quota API. Строки с читаемыми квотами предпочитают самое длинное настоящее default quota window провайдера (weekly, если доступно) и только при необходимости переключаются на другое реальное окно. Каждая доступная строка показывает countdown до resetsAt этого окна и соответствующий usage rail. Значения короче суток используют HH:MM, длиннее — Nд HHч/Nd HHh. Длина окна остаётся в accessible metadata; недоступные данные подписаны и не получают выдуманный reset или percentage. Короткая жёлтая полоска означает, что после неудачного свежего обновления показан последний валидный snapshot; это не выбор строки и не progress использования.
• Правая плитка — единственный список сессий. Viewport показывает три строки и прокручивается при большем числе реальных сессий, не отбрасывая их. Каждая строка показывает mark провайдера, локализованный semantic state и identity. Hover на error mark неудачной сессии открывает доступную панель с ограниченным финальным выводом PTY без terminal-control последовательностей, включая переданный traceback; действие Copy копирует только этот показанный вывод. Если PTY не передал видимого вывода, панель сообщает этот факт с фактическим кодом завершения. UI не выдумывает причину и не определяет state по тексту терминала. Session duration и progress rails в стиле лимитов здесь не появляются.
• Часы — доминирующая средняя плитка и показывают только HH:MM. Соседняя media tile автономна: нажмите, чтобы выбрать/заменить image/GIF; удаление находится в самом виджете.
• Нижний dock всегда содержит Terminal и Browser, а также включённых в Settings агентских провайдеров. Его равные по ширине колонки вычисляются из реально видимых кнопок, поэтому отключённый агент не оставляет пустую ячейку. В новых и мигрированных профилях выбраны только агенты с найденным CLI. Отсутствующие агенты удаляются из сохранённых списков запуска и лимитов; скрытие launcher-кнопки не останавливает и не удаляет существующую сессию. Settings — отдельная плитка. Browser открывает или фокусирует единственную встроенную карточку браузера и никогда не запускает внешний браузер. Agent badges не накладываются на launcher-иконку Browser.
• Любую default tile, кроме Settings, можно скрыть. Settings остаётся recovery entry point. Edit HOME показывает полную сетку и точную границу HOME, скрывает terminal/canvas-plugin windows и хранит изменения как draft до Save. Плитки двигаются без overlap и могут временно пересекать любую границу HOME; Save выключен, пока каждая плитка не окажется целиком внутри. Любая грань/угол меняет размер с сохранением противоположной грани; видимые подсказки есть только в верхнем левом и нижнем правом углах. Граница растёт/сжимается, не пересекая размещённые widgets. Добавление виджета автоматически расширяет HOME, если текущая область заполнена.
• Runtime HOME widgets используют те же tile bounds и zoom behavior. Их UI работает в sandboxed iframe и не имеет доступа к trusted renderer DOM или window.canvasTTY.

Запуск и настройки

• Агенты без найденного CLI остаются в Settings со статусом отсутствия и внешней ссылкой на официальную установку вместо переключателя. «Проверить снова» обновляет обнаружение, доступность запуска и лимиты без перезапуска и не затрагивает работающие сессии. Найденный позже CLI остаётся невыбранным до ручного включения. Обнаружение файла не подтверждает авторизацию или поддержку лимитов.

• Нажатие на провайдера открывает его Focus Card. Провайдер зафиксирован; второго выбора провайдера нет.

• Focus Card содержит только mark провайдера, project folder, profile Normal/Auto/YOLO (Auto только где у CLI есть авторежим), launch action и контекстное подтверждение опасности.

• Settings использует верхнюю полосу General, Appearance, Agents, Controls, Browser и Plugins. General владеет языком. Appearance — двумя независимыми цветовыми настройками: ролевыми preset/custom-палитрами HOME и фоном Canvas. Изменение одной не должно перекрашивать другую. Appearance также владеет узором Canvas, shortcut hint, системными HOME tiles и входом в HOME editor. Свои цвета HOME принимаются только как проверенные значения #RRGGBB и не перекрашивают provider marks. Agents независимо определяет, кнопки каких провайдеров видны в HOME launcher и строки лимитов каких реальных провайдеров видны в HOME; изменение одного выбора не меняет другой. Controls — click focus, hover focus, window snapping, edge panning, режим взаимодействия с мини-картой, zoom sensitivity, wheel direction, режимом pan/zoom для обычного scroll, режимом Off/On/Key для wheel/pinch над виджетами, полным canvas navigation override и action shortcuts. Browser — agent access, видимостью agent indicators, восстановлением вкладок, downloads, редактированной activity и очисткой browser data. Plugins — install preview, permission review, installed-plugin list, enable/disable/uninstall и contribution actions. Media controls там не появляются.

• Click focus имеет явные режимы Off, Single click и Double click и по умолчанию выключен. Selection и видимая рамка работают даже без camera focus; режим double click никогда не прыгает камерой по первому клику.

• Сейчас selection эксклюзивен для терминалов и встроенного Browser: нажатие на пустой canvas снимает его. Input focus хранится отдельно, чтобы будущий multi-selection не требовал переопределять wheel ownership.

• Hover focus — отдельный, выключенный по умолчанию режим input-фокуса. После настраиваемой задержки (медленно 500ms, обычно 250ms, быстро 80ms) input-виджет под указателем получает логический focus без изменения selection; keyboard input терминала и native Browser следует за этим focus. Уход указателя только отменяет ещё не сработавший перенос; назначенный focus сохраняется, пока пользователь не кликнет/наведётся на другой focusable-виджет или не кликнет вне всех виджетов. Focusable-поверхности: терминалы, native Browser, plugin iframe/canvas и действительно прокручиваемые HOME-списки; декоративные и action-only tiles фокус не забирают.

• Keyboard shortcuts переназначаются пользователем и сохраняются локально. Defaults: Home фокусирует Home, F2 переименовывает выбранное окно терминала. Rename происходит inline в header и не пересоздаёт PTY. Компактная пассивная подсказка справа внизу canvas сразу отражает сохранённые bindings и скрывается в Appearance.

• Snapping включён по умолчанию и выключается без изменения существующих window bounds. Edge panning по умолчанию выключен и имеет slow/normal/fast speed. Направления колеса для terminal scroll и canvas navigation настраиваются раздельно; canvas inversion применяется к обеим осям pan и к историческому wheel zoom. Свежий профиль использует обычный scroll для pan, а мигрированный сохраняет wheel zoom, направление и чувствительность.

Визуальная система

• Плоские крупные pastel tiles, сильный dark/light contrast, сдержанные тени; без декоративных micro-controls и поясняющего microcopy вокруг очевидных controls.
• Home рисуется 1:1, если помещается текущая сохраняемая граница. Auto-fit использует дискретные шаги до 0.2× и целые camera coordinates, чтобы borders и spacing dock оставались визуально ровными в больших plugin layouts.
• Системные actions используют локально сохранённые SVG из официального Lucide repository. Нельзя рисовать system icons вручную в TSX или добавлять icon runtime package.
• Provider marks используют неизменённые vendor assets. Их нельзя перерисовывать, перекрашивать, фильтровать или аппроксимировать. Raster mark Kimi не рисуется больше родных 48px.
• Dots, grid, диагонали и кольца — сдержанные CSS patterns. Waves используют бесшовную SVG tile assets/patterns/waves.svg; radial gradients её не заменяют.
• Terminal cards сохраняют header 54px. При нормальном масштабе header показывает provider mark и working directory, пока пользователь явно не переименует окно; custom title затем заменяет путь. Close всегда видимо справа; maximize/fullscreen в canvas cards нет. Lifecycle dot в terminal chrome отсутствует.
• После завершения provider PTY его terminal card позволяет перезапустить процесс в той же сессии через header action или Ctrl+D. Card, title, bounds, scrollback и xterm сохраняются, а provider process и browser capability создаются заново.
• Ниже 0.5× terminal cards переходят в semantic summary. Typography counter-scale увеличивается при отдалении камеры, чтобы одинаковые карточки сохраняли читаемую иерархию вместо мелкого xterm text.
• В semantic summary нажатие по карточке по-прежнему выбирает её с видимой рамкой, а camera focus подчиняется только Off/Single click/Double click. Renderer-, xterm- и plugin-карточки используют ту же wheel focus-матрицу, что и при нормальном масштабе: только focused input-карточка может оставить wheel себе в Off или при отпущенном Key; On, активный Key binding или полный navigation override передаёт его канвасу. Browser summary и другие non-native placeholder-поверхности всегда передают wheel/pinch канвасу.
• Любая грань/угол terminal — resize target. Минимальный размер 420 × 260; resize обновляет viewport xterm и сохраняет противоположную грань.
• Selection живого терминала следует за видимой позицией указателя при любом canvas zoom. При непустом выделении Ctrl+C/Ctrl+Shift+C или Cmd+C копирует; Ctrl+Shift+V/Cmd+V и Shift+Insert вставляют из system clipboard. Обычный Ctrl+C без выделения остаётся PTY interrupt. Shift+Enter отправляет line-break sequence (ESC [ 13 ; 2 u) в PTY вместо отправки строки.
• В «Управлении» есть выключенная по умолчанию настройка Копировать при выделении. Она сохраняется и сразу применяется ко всем агентам и терминалам, включая полноэкранные карточки. После завершения непустого выделения мышью текст копируется в системный буфер, подсветка сохраняется. Поиск и снятие выделения не запускают копирование. При включённой настройке Shift позволяет выделять текст в TUI, перехватывающих мышь, на всех desktop-платформах; на macOS адаптер мыши терминала переводит Shift в Option для xterm, сохраняя навигацию канвасом через Option.
• Canvas plugin apps используют ту же movable card grammar, header 54px, resize/snap и semantic summary ниже 0.5×. Contribution window открывает отдельное sandboxed окно под управлением CanvasTTY; произвольные native windows не встраиваются.
• Built-in Browser — одна movable/resizable core canvas card, а не plugin contribution. Она использует тот же внешний header 54px, что и другие canvas cards: identity и hide-card action отделены от внутренней полосы вкладок ниже. Trusted DOM chrome владеет tabs/favicons, address/search, back/forward/reload, downloads, per-tab provider badges, site dialogs и явными Close tab/Close all. Скрытие карточки сохраняет вкладки и общий аутентифицированный Chromium profile. Ниже 0.5×, в Edit HOME и за trusted dialogs/popovers native page скрывается и заменяется стабильной semantic surface. Во время движения карточки или камеры он остаётся live и следует за frame-coalesced viewport geometry.
• Само authenticated connection или heartbeat не показывает agent presence. Branded badge появляется только после реальной browser-команды агента, а cursor — только после появления настоящей pointer position. Claude использует #D97757, Codex — #10A37F, Qwen — #6D44E8, Kimi — #7C5CFC, OpenCode — #5A5858, Hermes — #D6A700, unknown provider — #7A8291. Browser Settings отдельно управляет видимостью индикаторов, не отзывая доступ; kill switch доступа агентов отзывает само подключение.
• При включённом snapping drag/resize используют скрытую сетку 10px, magnetic threshold 10px для соседних edges/centers и постоянный gap 20px.
• Drag по пустому canvas всегда выполняет pan. В свежем профиле обычный scroll над пустым canvas перемещает его по обеим осям, а pinch и Cmd/Ctrl + scroll масштабируют вокруг указателя. Зум обычным скроллом возвращает исторический wheel zoom и автоматически включается при миграции существующего профиля. Только focused input-виджет прерывает canvas wheel/pinch; над unfocused или нефокусируемым виджетом события остаются канвасу. Перехват wheel/pinch над виджетами имеет режимы Off, On и Key: Off сохраняет владение focused-виджета, On постоянно передаёт канвасу только wheel/pinch, а Key делает это при удержании комбинации. Поэтому focused live Browser page прокручивается обычным scroll в Off или при отпущенном Key; unfocused Browser, On, активный Key binding, полный override, pinch и Cmd/Ctrl + scroll принадлежат канвасу. Выбранный в начале Browser wheel-sequence владелец сохраняется до 250 мс без wheel-событий. Browser summary и placeholder всегда принадлежат канвасу. Свежий профиль использует Key с Command на macOS или Ctrl на остальных платформах. Отдельный Перехват навигации канвасом (по умолчанию Option на macOS и Alt на остальных платформах) передаёт wheel/pinch и drag; одиночный Command/Ctrl разрешён. При удержании полного override все canvas-поверхности показывают grab, а начатый pan — grabbing до pointer up/cancel даже после отпускания комбинации.
• Мини-карта центрирует камеру по нажатию без изменения масштаба. В Controls выбирается Клик (по умолчанию, движение указателя игнорируется) или Перетаскивание (мини-карта захватывает указатель и непрерывно двигает камеру); клавиши-стрелки работают в обоих режимах.
• Canvas двигается RTS-style, пока указатель находится в пределах 56px от viewport edge над пустым canvas; скорость линейно возрастает до 900px/s на самой границе. Edge panning выключен по умолчанию и включается в Settings. Motion останавливается над interactive surfaces и во время drag-pan.
• Dialog close actions остаются внутри своей header/control row с одинаковым inset и не перекрывают field, outline или panel boundary.

Приёмочные проверки

• Нет собственных <svg> или <path> в React TSX.
• В Settings нет media picker или media-fit selector.
• В AgentLaunchDialog нет provider picker.
• В canvas card нет maximize/fullscreen.
• Нет выдуманных counts, percentages, reset timers, determinate progress или placeholder sessions.
• Plugin install всегда показывает validated manifest и requested permissions до подтверждения; repository scripts не выполняются.
• Обычный терминал начинается как idle, а агент остаётся unavailable до lifecycle-сигнала provider hook. Codex, Claude Code, Qwen Code, Kimi Code, OpenCode, Hermes и Grok Build передают idle, working и needs_approval через машинные hooks; OSC title markers Claude/Qwen остаются fallback совместимости.
• needs_approval показывается только после structured provider-adapter signal; человекочитаемый terminal output и существование PTY не используются для выдумывания активности.
• Home, Focus Card, Settings, минимум один живой терминал и встроенный Browser проверены в изолированном настоящем Electron после build.