Facade

Модуль wippy/facade предоставляет переносимый фасад, который загружает и настраивает фронтенд Wippy из CDN. Он отдаёт тонкую HTML-страницу, загружающую запись JS-модуля Web Host (module.js для стандартной compat-оболочки или managed-layout.js для managed-режима), обрабатывает аутентификацию и связывает конфигурацию бэкенда с фронтендом. Загруженный модуль забирает себе всю страницу и её историю браузера.

Доставка через iframe (iframe.html плюс рукопожатие SetConfig через PostMessage) остаётся доступной для ручных встраиваний без фасада, когда вы сами встраиваете хост ради изоляции или использования на части страницы, но сам фасад её больше не использует.

Настройка

Добавьте модуль в проект:

wippy add wippy/facade
wippy install

Объявите зависимость:

version: "1.0"
namespace: app

entries:
  - name: gateway
    kind: http.service
    addr: :8090
    lifecycle:
      auto_start: true

  - name: api
    kind: http.router
    meta:
      server: app:gateway
    prefix: /api/public

  - name: dep.facade
    kind: ns.dependency
    component: wippy/facade
    version: "*"
    parameters:
      - name: server
        value: app:gateway
      - name: router
        value: app:api

Параметры конфигурации

Движок рендеринга

render_engine выбирает движок рендеринга страниц для всего развёртывания. Он выдаётся как hostConfig.renderEngine и читается Web Host в его единственной точке ветвления рендеринга страницы.

Включает режим только точная строка fragment; любое другое значение — включая опечатку вроде fragmnet — приводится к iframe (безопасно, но молча). Для включения fragment-движка также нужен шлюз /@fragment, который wippy/views (≥ 0.5.9) предоставляет сам — настройка на стороне потребителя не требуется. Страница может переопределить умолчание развёртывания для себя через wippy.renderEngine.

Идентичность приложения

Флаги функций

Оформление

Применяются три области: global (везде), host (хром Web Host — боковая панель, чат, область страницы) и children (и дочерние iframe view.page, и веб-компоненты view.component). О том, какой поверхности достигает каждая настройка, см. Матрицу доставки CSS.

Рекомендация по умолчанию: общие и брендовые стили размещайте в custom_css и css_variables (global) — туда относится примерно 95% оформления, и оно достигает каждой поверхности. host_custom_css / host_css_variables оставьте для хрома, специфичного для хоста (боковая панель, панель чата, разделители). view.component отказывается от *_custom_css в shadow root через customCss: false.

Режим темы и сохранение

Сохранение темы включается явно: theme_persist по умолчанию равен none, поэтому ничего не сохраняется, пока развёртывание не установит cookie или localStorage. При включении фасад отдаёт готовый скрипт по адресу GET /facade/theme-persist.js с зашитыми ключом и режимом; подключайте его на любой странице, которая должна разделять тему. Полную модель, событие хоста themeChanged и интеграцию со страницами вне Wippy см. в Сохранении темы.

Переиспользование оформления фасада на страницах вне Web Host

Страница, отдаваемая вне Web Host — ваш login.html, страница ошибки, страница подтверждения почты — может переиспользовать ту же брендовую тему фасада вместо её дублирования, так что токены и собственные правила живут в одном месте.

Сначала держите custom_css и css_variables в отдельных файлах, а не встраивайте их, и укажите параметрам на эти файлы через fs:// плюс файловую систему content_fs:

custom_css:    fs://custom-css.facade.css
css_variables: fs://css-variables.facade.json
content_fs:    app:app_fs

Используйте fs:// (разрешается через content_fs во время выполнения), а не file:// — file:// встраивается загрузчиком wippy относительно YAML на этапе загрузки. Держите файлы в той же статической папке, из которой отдаётся страница login_path (в app это static/, отдаваемая по /app).

Разрешение fs:// применяется ровно к шести параметрам оформления — custom_css, css_variables, host_custom_css, host_css_variables, children_custom_css, children_css_variables (CSS-строки читаются как есть; JSON-файлы *_css_variables разбираются как карта переменных). icon_sets / host_icon_sets и любой другой JSON-параметр (api_routes, chat, tanstack, …) — только inline; fs:// там не разрешается.

Отдельная страница затем подключает оба:

• custom_css — уже .css-файл, поэтому подключайте его напрямую оттуда, откуда он отдаётся.
• css_variables — JSON, поэтому его нельзя подключить как есть. Фасад рендерит его по адресу GET /facade/variables.css как базу плюс действующие блоки Auto-light, Auto-dark, принудительного Light и принудительного Dark. Значения верхнего уровня применяются везде; @light / @dark заменяют выбранные имена. Таблица кэшируется на 1 час и регистрируется на том же публичном роутере, что и /facade/config, поэтому несёт префикс роутера.

<!-- в login.html, отдаваемом вне Web Host -->
<link rel="stylesheet" href="/api/public/facade/variables.css">  <!-- css_variables, сгенерированный CSS -->
<link rel="stylesheet" href="/app/custom-css.facade.css">        <!-- файл custom_css -->

Чтобы также разделять режим темы (чтобы login.html учитывал и сохранял тот же выбор светлой/тёмной темы, что и хост), добавьте сгенерированный скрипт сохранения темы и вызывайте его write() из своего переключателя:

<script src="/api/public/facade/theme-persist.js"></script>
<!-- заранее применяет сохранённую тему и предоставляет window.wippyThemePersist -->

Полный пример переключателя см. в Сохранение темы → Страницы вне Wippy.

Опциональные JSON-параметры

Каждый из следующих параметров — строка, закодированная в JSON; значения по умолчанию пустые ({} или []).

Эти четыре передаются без изменений под hostConfig для фронтенда:

Эти три выдаются как поля AppConfig верхнего уровня (соседи hostConfig), а не внутри hostConfig:

Эндпоинт конфигурации

Фасад регистрирует GET /facade/config на настроенном роутере. Этот путь регистрируется на публичном роутере, поэтому URL, который страница фактически запрашивает, включает префикс роутера — с префиксом из примера /api/public (см. Настройка) это /api/public/facade/config, ровно то, что запрашивает поставляемая страница фасада. (Фасад регистрирует на том же роутере ещё один маршрут — GET /facade/variables.css, css_variables, отрендеренные как таблица стилей text/css для страниц вне Web Host; см. Переиспользование оформления фасада на страницах вне Web Host.) Фронтенд запрашивает конфигурацию при загрузке:

{
    "facade_url": "https://web-host.wippy.ai/<release-tag>",
    "iframe_origin": "https://web-host.wippy.ai",
    "iframe_url": "https://web-host.wippy.ai/<release-tag>/iframe.html?waitForCustomConfig",
    "login_path": "/login.html",
    "login_redirect_param": null,
    "mode": "compat",
    "module_file": "/module.js",
    "extraScripts": null,
    "env": {
        "APP_API_URL": "https://api.example.com",
        "APP_AUTH_API_URL": "https://api.example.com",
        "APP_WEBSOCKET_URL": "wss://api.example.com"
    },
    "routePrefix": "https://api.example.com",
    "apiRoutes":     { "...": "..." },
    "axiosDefaults": { "...": "..." },
    "tanstack":      { "lists": { "refetchOnWindowFocus": true } },
    "theming": {
        "global":  { "customCSS": "...", "cssVariables": {}, "iconSets": {} },
        "host":    { "customCSS": "...", "cssVariables": {}, "iconSets": {}, "i18n": { "app": { "title": "Wippy", "icon": "wippy:logo", "appName": "Wippy AI" } } },
        "children": { "customCSS": "...", "cssVariables": {} }
    },
    "hostConfig": {
        "session": { "type": "non-persistent" },
        "history": "hash",
        "renderEngine": "iframe",
        "showAdmin": true,
        "allowSelectModel": false,
        "startNavOpen": false,
        "hideNavBar": false,
        "disableRightPanel": false,
        "hideSessionSelector": false,
        "additionalNavItems": [],
        "stateCache":        { "...": "..." },
        "allowAdditionalTags": [],
        "chat":              { "...": "..." }
    }
}

API URL читается из переменной окружения PUBLIC_API_URL; APP_WEBSOCKET_URL получается заменой http:// на ws:// или https:// на wss://. Оформление имеет три области (global, host, children) — host.i18n содержит брендинг приложения. Ключи hostConfig записаны в camelCase и собираются из параметров фасада: session_type, history_mode, render_engine, show_admin, allow_select_model, start_nav_open, hide_nav_bar, disable_right_panel, hide_session_selector, плюс опциональные additional_nav_items, state_cache, allow_additional_tags и chat. render_engine становится renderEngine (см. Движок рендеринга). Параметры api_routes, axios_defaults и tanstack выдаются как поля AppConfig верхнего уровня (apiRoutes, axiosDefaults, tanstack), соседние с hostConfig, а не внутри него.

Поля facade_url, iframe_origin, iframe_url, login_path, mode и module_file — поля уровня оболочки, используемые встраивающей страницей для сборки самой себя; они не входят в дочерний AppConfig, которым инициализируется хост. Поля iframe_origin/iframe_url используются только ручными встраиваниями через iframe без фасада (см. Точка входа фасада). Поле mode — нормализованный fe_mode (compat или managed), а module_file — точка входа JS-модуля, которую загружает страница фасада: /module.js для compat, /managed-layout.js для managed.

Боковая панель навигации

Страницы, зарегистрированные через wippy/views, появляются в боковой панели автоматически на основании своих метаданных:

entries:
  - name: dashboard
    kind: registry.entry
    meta:
      type: view.page
      name: dashboard
      title: Dashboard
      icon: tabler:chart-bar
      group: Analytics
      group_icon: tabler:chart-dots
      group_order: 10
      order: 1
      announced: true
      secure: true
      url: https://cdn.example.com/dashboard/

Группы боковой панели

Страницы с одинаковым значением group собираются в сворачиваемые секции. Группы сортируются по group_order (меньшие первыми), страницы внутри групп — по order.

Страницы без group появляются как элементы верхнего уровня.

Управление видимостью

Публикация со встроенными ресурсами

При публикации компонента, включающего статические файлы (например, каталог public/ фасада), используйте --embed, чтобы включить в пакет записи fs.directory:

wippy publish --embed facade:public_files

Без --embed записи fs.directory исключаются из публикуемого пакета. Флаг --embed принимает ID записей или имена, соответствующие записям fs.directory.

См. также

• Views - Система страниц и компонентов
• HTTP-сервер - Конфигурация HTTP-сервиса
• Обзор фреймворка - Использование модулей фреймворка
• Точка входа фасада - Как фасад загружает Web Host (со стороны фронтенда)
• Внедрение CSS - Как оформление фасада попадает в дочерние iframe
• Движки рендеринга - Рендеринг страниц через iframe или Web Fragment (переключатель render_engine)