Maria AI — WebUI Debug Panel

🇬🇧 English version: README.en.md

Developer WebUI и debug-кокпит для Maria AI Character Engine — локального AI-персонажа с собственной системой отношений, памятью, характером и проактивным поведением.

WebUI не является финальным user-facing клиентом Марии. Этот фронт нужен, чтобы видеть как Мария себя ведёт: внутренние шкалы, анализ последнего сообщения, очереди offline-cognition, юмор, социальную сцену, эмоциональное здоровье.

---

Скриншоты

Живой режим

WebUI подключён к backend runtime: чат, история по дням, runtime state панель, sprite overlay.

Backend offline

Базовая разметка, когда backend недоступен: чат, ввод, debug-панель.

---

Что это и зачем

Это developer cockpit, а не конечный продукт. WebUI намеренно обнажает внутреннее состояние, потому что Мария — не чат-бот, а character runtime: память, эмоции, доверие, привязанность, мнения, эмоциональное здоровье. Без debug-видимости калибровать характер тяжело.

Что умеет:

• посылать сообщения в Maria backend и видеть ответы;
• листать историю диалогов по дням;
• наблюдать в реальном времени шкалы attachment / trust / romance / mood / interest / irritation;
• видеть последний анализ сообщения — эмоция, intensity, warmth, sincerity, knowledge_gap, assistant_task;
• следить за offline-cognition: reflection jobs, opinion jobs, growth limits, pending_growth, consolidation log;
• ловить юмор и социальную сцену (humor adaptive taste, scene roles);
• инспектировать эмоциональное здоровье и вручную триггерить recovery-события (reassurance / apology);
• видеть proactive-инициативу Марии («сама напишет через ~30м»);
• проверять sprite overlay для будущего визуального клиента.

---

Стек

Фреймворк	React 19
Сборщик	Vite 6
Язык	JavaScript (JSX)
Стили	Чистый CSS, CSS-vars, inline-style в компонентах
API	REST к Maria backend через /api/webui/*
Зависимости рантайма	react, react-dom (две)

Нет UI-китов, нет роутера (одно SPA-окно), нет state-менеджера — локальное состояние через хуки.

---

Структура проекта

frontend/
├── public/
│   └── screens/                  ← скриншоты для README
├── src/
│   ├── main.jsx                  ← entry
│   ├── App.jsx                   ← корневой компонент, держит чат/архив/debug
│   ├── assets/main.css           ← глобальные стили + CSS vars
│   ├── components/
│   │   ├── Header.jsx            ← шапка: статус, кнопки История/Сон/Debug
│   │   ├── ChatInput.jsx         ← textarea + плейсхолдер для archive/breakup
│   │   ├── ChatMessage.jsx       ← bubble + декораторы + regen/save
│   │   ├── DecoratedText.jsx     ← рендер *action* и **environment**
│   │   ├── TypingIndicator.jsx   ← три точки во время LLM-вызова
│   │   ├── HistorySidebar.jsx    ← календарь + список дней (архив)
│   │   ├── SpriteOverlay.jsx     ← PNG-аватар в правом нижнем углу
│   │   ├── DebugPanel.jsx        ← правая панель: бары, анализ, jobs, humor, EH
│   │   └── Toast.jsx             ← уведомления
│   ├── hooks/
│   │   ├── useMariState.js       ← snapshot состояния + merge из chat-ответа
│   │   └── useProactivePoll.js   ← long-poll с jitter + reaction на visibility
│   └── utils/
│       └── api.js                ← API-клиент (mariApi.*)
├── index.html                    ← Vite entry
├── vite.config.js                ← dev-proxy → localhost:5000
├── package.json
├── README.md                     ← этот файл
├── README.en.md                  ← English version
└── LICENSE                       ← MIT

---

Быстрый старт

Перед запуском WebUI запусти Maria backend локально. По умолчанию Vite проксирует API-запросы на:

http://localhost:5000

# 1. Зависимости
npm install

# 2. Dev-сервер
npm run dev
# → http://localhost:5173

# 3. Прод-сборка
npm run build

# 4. Локальный preview прод-сборки
npm run preview

Команда	Что делает
npm run dev	Dev-сервер с HMR на порту 5173
npm run build	Прод-сборка в dist/
npm run preview	Запуск dist/ локально

Если backend на другом порту — править vite.config.js.

---

Архитектура

API-клиент

src/utils/api.js — единственная точка интеграции с backend. Все вызовы идут через namespace /api/webui/*.

mariApi экспортирует методы:

• Чат: chat, regen, state, poll, proactiveStatus, health, version
• WebUI debug: saveMemory, sleep, historyDays, historyDay, sprite, spriteUrl
• Jobs: jobsStatus, reflectionJobs, reflectionTick, opinionJobs, opinionTick
• Growth limits: growthLimitsState, growthLimitsPending, growthLimitsConsolidate
• Consolidation: consolidationTick, consolidationLog
• Active path / offline cognition: activePathMeta, offlineCognitionSummary, offlineCognitionTick
• Feature flags + social / EH / humor: featureFlags, socialPeople, socialPerson, socialEvents, socialSceneLast, emotionalHealthState, emotionalHealthEvents, emotionalHealthRecover, humorLast, humorTaste
• LLM usage: llmUsage, llmUsageReset

При HTTP-ошибке — выбрасывает Error с .status и .payload. При breakup-разрыве backend возвращает 403, фронт ловит и блокирует ввод, показывает финальное сообщение Марии.

Поток данных

useMariState (initial /api/state)
       │
       ▼
App.jsx ─── sendMessage ──► /api/webui/chat ──► merge state, analysis, director
       │
       ├─── useProactivePoll ──► /api/webui/poll ──► append spontaneous message
       │
       └─── DebugPanel (every 15s) ──► version/jobs/growth/humor/scene/eh/llm

useMariState хранит snapshot и мерджит инкрементальные обновления из chat-ответа. Архивный режим (выбран день в HistorySidebar) переключает источник сообщений и блокирует ввод.

Поведение при breakup

Если Мария «ушла» (state.ended === true):

• input блокируется и показывает final_message как placeholder;
• баннер сверху чата сообщает о разрыве;
• proactive-poll останавливается;
• /api/webui/chat отвечает 403, фронт показывает system-сообщение.

Декораторы сообщений

В тексте Марии:

• *текст* — действие персонажа (italic, акцентный цвет);
• **текст** — окружение / описание сцены (серый блок-цитата);
• ~, ..., ), (( — тон, рендерятся как обычный текст.

Реализация: src/components/DecoratedText.jsx.

---

Как редактировать

Цвета и стили

CSS-переменные в src/assets/main.css в :root:

--bg, --surface, --surface2, --surface3
--text, --text2, --text3
--accent, --accent-soft, --accent-mid, --accent2
--red, --green, --blue
--border, --radius, --radius-sm

Меняешь там — меняется по всему UI, включая бары и теги в DebugPanel.

Layout

App.jsx — flex-контейнер на всю высоту окна. История слева (drawer), чат по центру, DebugPanel справа (фиксированная ширина 330 px), SpriteOverlay поверх как position: fixed.

Добавить debug-секцию

В DebugPanel.jsx — добавить новый useState + новый pull в loadDebug (через Promise.allSettled) + новую <Section> с рендером. Секция отображается только если backend вернул данные — неудачный запрос не ломает остальные.

---

Тонкости

• Vite proxy: /api/* уходит на localhost:5000. Если backend на другом порту — править vite.config.js.
• useProactivePoll реагирует на visibilitychange — когда вкладка скрыта, polling приостанавливается. Не пытается опрашивать в архивном режиме или после breakup.
• DebugPanel auto-refresh раз в 15 секунд + при изменении refreshKey после действий (sleep, save memory). При невидимости панели polling не запускается.
• SpriteOverlay скрывается тихо, если sprite пустой или изображение не загрузилось (404). Это нормально — sprites опциональны.

---

Развитие

WebUI будет обновляться по мере усложнения бэкенда. Каждый новый endpoint и каждое новое поле в state'е появляется здесь как отдельная секция или ряд в DebugPanel. Цель — оставаться актуальным зеркалом того, что умеет backend, без UI-полишинга.

---

Связанный проект

WebUI имеет смысл только когда backend runtime запущен локально.

Репозиторий backend/runtime:

Maria AI Character Engine

---

CI

.github/workflows/webui-ci.yml прогоняет на каждый push в main и каждый pull request: npm ci + npm run build. Этого достаточно, чтобы ловить регрессии в JSX и зависимостях — юнит-тестов пока нет, основной валидатор — успешная прод-сборка.

---

Лицензия

Этот debug-WebUI распространяется под лицензией MIT — см. LICENSE.

Это отдельный development/debug-интерфейс для backend'а Maria AI Character Engine. Репозиторий backend'а может использовать другую лицензию.