Skip to content

ARCHITECTURE.md

Latest commit

 

History

History
157 lines (131 loc) · 9.61 KB

ARCHITECTURE.md

File metadata and controls

157 lines (131 loc) · 9.61 KB
Raw

Архитектурный обзор mtrm

Этот документ нужен как быстрый вход в проект при следующем запуске: что уже реализовано, как модули связаны между собой и куда смотреть за деталями.

Общая схема

mtrm собран как workspace из независимых Rust-библиотек и одного исполняемого пакета.

Поток работы сверху вниз такой:

  1. app запускает приложение и главный цикл.
  2. input преобразует нажатия клавиш в команды приложения или байты для PTY.
  3. tabs координирует вкладки, раскладки и живые процессы.
  4. process управляет оболочками в псевдотерминалах.
  5. ui рисует текущий кадр интерфейса.
  6. слой терминального экрана преобразует байты PTY в экранное состояние панели.
  7. keymap загружает символьные привязки буквенных горячих клавиш.
  8. state и session сохраняют и восстанавливают состояние.
  9. config определяет файловую структуру ~/.mtrm.
  10. core задает общие типы и команды.

Слои

Нижний слой:

  • core
  • config
  • layout
  • keymap
  • clipboard
  • process
  • terminal_screen
  • input

Средний слой:

  • session
  • state
  • tabs
  • ui
  • терминальный экран панели

Верхний слой:

  • app

Зависимости между модулями

  • core ни от чего внутри workspace не зависит.
  • config ни от чего внутри workspace не зависит.
  • layout зависит от core.
  • clipboard не зависит от других модулей workspace.
  • keymap зависит от config.
  • process не зависит от других модулей workspace.
  • terminal_screen не зависит от других модулей workspace.
  • input зависит от core.
  • session зависит от core и layout.
  • state зависит от config и session.
  • tabs зависит от core, layout, process, session.
  • ui зависит от core и layout.
  • app зависит от всех прикладных модулей, но сам не должен дублировать их внутреннюю логику.

Ответственность модулей

  • core: общие идентификаторы, команды приложения и базовые перечисления.
  • config: вычисление и создание ~/.mtrm и ~/.mtrm/state.yaml.
  • layout: нормализованное n-арное дерево разбиений окон, прямоугольники, фокус, resize pane и сериализуемый снимок раскладки.
  • clipboard: системный буфер обмена и тестовая реализация в памяти.
  • keymap: встроенный keymap.toml, автоматическое создание ~/.mtrm/keymap.toml, загрузка и валидация символьных привязок клавиш.
  • process: запуск оболочки в PTY, запись, чтение, SIGINT, cwd, resize, завершение.
  • terminal_screen: применение байтов terminal output к экранному состоянию одной панели и управление scrollback на уровне экрана.
  • input: чистое отображение KeyEvent -> InputAction по уже загруженному Keymap.
  • session: чистые сериализуемые структуры снимка состояния и их проверка.
  • state: чтение и атомарная запись снимка состояния на диск в формате YAML, с legacy fallback чтения из TOML и приемом старого YAML 0.0.1.
  • tabs: живой набор вкладок и окон, связь раскладки с процессами, экранным состоянием панелей, прокруткой истории активной панели и построение снимка.
  • ui: отрисовка полосы вкладок и окон по готовому FrameView, содержащему уже подготовленные экранные линии и курсор панели.
  • app: главный цикл, маршрутизация событий, сохранение состояния, сборка FrameView, запуск интерфейса. app больше не хранит вывод панелей сам и получает представление панели из tabs. При стандартном запуске app поднимает shell по умолчанию в интерактивном режиме. Для Meta-комбинаций app также умеет синтезировать Alt+<буква> из короткой Esc-prefixed последовательности, если внешний терминал присылает именно такой ввод.

Важные принципы

  • Состояние сохраняется автоматически в ~/.mtrm/state.yaml.
  • При отсутствии state.yaml состояние может быть прочитано из legacy ~/.mtrm/state.toml.
  • Текущая версия формата state.yaml — 0.1.0.
  • layout внутри state.yaml теперь хранится в n-арной форме через children, а старая бинарная форма first/second читается как legacy input.
  • Положение прокрутки истории панели не входит в сохраняемое состояние.
  • При восстановлении создаются новые процессы оболочки, а не оживляются старые.
  • Ctrl+C используется для копирования, а не для стандартного прерывания.
  • Прерывание активного процесса идет через Alt+X.
  • Изменение размеров pane идет через Alt+Shift+Arrow и работает шагом в одну ячейку.
  • При потере фокуса внешнего окна активная вкладка и рамка активной панели подсвечиваются красным.
  • Закрытие последнего окна во вкладке запрещено.
  • Закрытие последней вкладки запрещено.

Что уже реализовано

  • Все библиотеки из workspace реализованы.
  • Для каждого модуля есть тесты.
  • Для каждого модуля есть свой README.
  • Для app есть интеграционные тесты на восстановление, сохранение, ввод и прерывание.

Куда смотреть

README модулей

Что важно помнить при следующем запуске

  • Если нужно быстро понять проект, сначала читать этот файл, потом app/README.md, потом README нужного модуля.
  • Если нужно менять поведение клавиш, смотреть crates/input и app.
  • Если нужно менять сохранение и восстановление, смотреть crates/session, crates/state, crates/tabs.
  • Если нужно менять поведение окон и фокуса, смотреть crates/layout и crates/tabs.
  • Если нужно менять UI, смотреть crates/ui.