Контракт оболочки

Контракт оболочки определяет именованные области приложения. Темы стилизуют эти области; плагины добавляют в них контент через стабильные слоты.

Именованные области оболочки

Хост публикует каждую основную область со стабильным атрибутом слота:

Слот	Область
app.shell	Корень оболочки приложения
navigation.primary	Навигационная панель
chat.header	Заголовок чата
chat.viewport	Прокручиваемая область просмотра чата
chat.composer	Композер сообщений
character.browser	Корень браузера персонажей
panel.left	Левая контекстная панель
status.area	Область статуса соединения
modal.layer	Слой модальных окон (плагины ниже системной поверхности)
notification.layer	Слой уведомлений

Два слота зарезервированы, но не входят в v1: navigation.secondary и panel.right.

Что разрешает контракт

Тема может:

• Стилизовать любую именованную область через её атрибут data-slot и хуки компонентов внутри неё.
• Располагать основные области через декларативный shellLayout в манифесте — в настоящее время порядок навигационной панели (группы main и bottom) и размещение вкладок управления (pinned).
• Заменять фон холста чата через токены chat-wallpaper-*.

Свободная перестановка областей — например, перенос панели на правую сторону — не входит в v1. Слоты стилизуются и заполняются, а не перемещаются.

Как плагины добавляют контент

Плагины получают API регистрации SDK, и хост размещает их контент в стабильных слотах. Например, панель боковой панели, зарегистрированная со slot: 'left', отображается внутри panel.left, а диалоги плагинов складываются внутри modal.layer ниже системной поверхности.

Контракт, вытекающий из этого разделения:

• Темы никогда не зависят от внутреннего DOM плагина.
• Плагины никогда не зависят от внутренней иерархии React или конкретных генерируемых имён классов.
• Обе стороны встречаются только на именованных слотах и атрибутах хуков.

Стабильные хуки внутри областей

Внутри областей компоненты публикуют стандартные атрибуты хуков. Примечательные примеры:

• Корень композера публикует data-slot="chat.composer" с частью панели инструментов, частью поля и входом data-component="textarea".
• Кнопки публикуют data-component="button" с data-part="icon" и data-part="label"; связанные действия живут в панели действий (data-component="action-bar") с группами primary и secondary.
• Вкладки публикуют data-component="tabs" с частями list, trigger и content; панели управления используют вариант-сегмент.
• Сообщения публикуют data-component="chat-message" с data-role="user|assistant|system|tool" и состояниями вроде streaming.
• Навигационная панель публикует data-component="navigation-rail" с data-part="main-items", data-part="bottom-items" и data-item="<id>" для каждой записи, плюс data-state="expanded|collapsed".
• У всех панелей панели общий заголовочный chrome (data-component="sidebar-panel-header"), поэтому тема стилизует их один раз.

Обязанности макета

Хост владеет критичным для поведения макетом: захватом фокуса, логическим направлением RTL, отступами безопасных областей и минимальными размерами интерактивных целей. Тема оболочки может менять вид и расположение областей, но должна сохранять порядок DOM там, где он документирован, горизонтальную прокрутку списков действий и поведение клавиатуры. Контрольные точки регистрируются в SDK (VIEWPORT_BREAKPOINTS для ширины области просмотра в px, CONTAINER_BREAKPOINTS для размеров контейнера в rem), а feature-запросы вроде prefers-reduced-motion не являются макетными контрольными точками.

О слое стилизации, который скинирует эти области, см. Скин компонентов; о восстановлении при сломанной оболочке — Безопасный режим.