Топология платформы
Цепочка доставки
| Этап | Владелец | Проверка |
|---|---|---|
| Исходный код и сборка пакета | Фронтенд-модуль | Сборка пакета выпускает ожидаемый входной файл. |
| Расположение артефакта | Цель сборки развёртывания | Команда сборки получает --outDir; Vite его не зашивает. |
| Запись реестра | Бэкенд-модуль | view.page или view.component указывает на выпущенный вход. |
| Раздаваемый URL | Записи реестра файловой системы и HTTP | Прямой запрос ресурса возвращает собранный JavaScript или HTML. |
| Рантайм-контейнер | Web Host | Страница использует about:srcdoc; компонент использует пользовательский элемент, обычно с shadow DOM. |
| Контекст | AppConfig и пакеты Wippy | Маршрутизация, доступ к API и данные темы приходят через поддерживаемые пакеты. |
Наличие исходного кода, успешная сборка или корректная запись реестра не доказывают следующий этап. Проверяйте каждую границу.
Страницы
view.page работает в iframe about:srcdoc. URL iframe — не маршрут хоста. Не изучайте window.location, window.parent.location или query-параметры, чтобы узнать состояние хоста. Используйте AppConfig и @wippy-fe/router; пакет берёт на себя интеграцию с маршрутизацией Wippy.
Инъекция CSS iframe сейчас обеспечивает оформление полос прокрутки по теме по умолчанию. Её имя историческое и шире её нынешнего назначения. Оставляйте её включённой ради единообразия полос прокрутки; не описывайте её как сброс вёрстки.
Веб-компоненты
view.component работает в документе хоста и обычно владеет shadow root. CSS-селекторы не каскадируются через границу shadow DOM. Web Host может доставлять одобренные таблицы стилей и CSS фасада в этот корень согласно конфигурации компонента.
Наследование CSS-переменных и инъекция таблиц стилей — разные механизмы:
- Публичные наследуемые переменные могут пересекать границу от хоста к shadow DOM.
- Правила с селекторами действуют в shadow root только тогда, когда доставлены в этот корень.
- Доставка не делает произвольный селектор переносимым API.
Тема и оверлеи
Тему PrimeVue предоставляет фасад. Общие правила .p-* в custom_css фасада — корректная реализация темы и могут быть глобальными, когда предназначены для хоста и потомков. Используйте .wippy-host-app только для оболочки, специфичной для хоста.
Режим темы — это состояние AppConfig, а не API CSS-классов. Приложения,
компоненты, фикстуры и браузерные тесты переключают режим вызовом
host.setThemeMode('auto' | 'light' | 'dark') из @wippy-fe/proxy, затем ждут
@theme и проверяют host.getThemeMode(). AppConfig переносит изменение через
транспорт от хоста к потомкам. Хост обновляет свой документ, повторно
транслирует AppConfig в живые iframe about:srcdoc и зеркалит режим в корни
веб-компонентов. Никогда не выставляйте классы w-theme-dark или
w-theme-light вручную.
Никогда не выставляйте классы w-theme-dark или w-theme-light вручную.
Оверлеи PrimeVue могут телепортироваться. Проверяйте фактический корень оверлея в верхнем документе, документах iframe и рекурсивно обнаруженных shadow root. Не полагайтесь на предполагаемое размещение PrimeVue.
Порядок отладки во время выполнения
- Убедитесь, что бэкенд слушает.
- Изучите логи бэкенда на предмет неожиданных ответов 5xx.
- Подтвердите владельца записи реестра и раздаваемый URL ресурса.
- Подтвердите, что именно эта сборка пакета выпустила этот ресурс.
- Загрузите корень хоста перед навигацией по SPA, если прямые глубокие ссылки не поддерживаются.
- Изучите ошибки консоли и сети после навигации и взаимодействия.
- Для сценариев с темой вызовите публичный метод темы прокси, дождитесь
@themeи проверьтеhost.getThemeMode(), прежде чем принимать скриншот.