Facade

The wippy/facade module serves a page that loads and configures the Wippy Web Host from a CDN. The page loads module.js for the default compatibility shell or managed-layout.js for managed mode, handles authentication, and passes backend configuration to the frontend. The loaded module controls the page and its browser history.

For isolated or partial-page integrations, the host can still be embedded manually through iframe.html and a SetConfig postMessage handshake. The facade itself does not use this delivery mode.

This page is a partial deployment recipe and configuration reference. The setup block can be adapted to an existing Wippy project, while the theming, config-response, navigation, and publishing blocks are independent reference snippets. Provide any login page, filesystem entries, static assets, and frontend view entries that an adapted snippet names. For a complete runnable facade project, follow Serve the Web Host with Facade.

Setup

Add the module to your project:

wippy add wippy/facade
wippy install

Declare the dependency:

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

Configuration Parameters

Render Engine

render_engine selects the page render engine for the whole deployment. It is emitted as hostConfig.renderEngine and read by the Web Host at its single page-render fork.

Only the exact string fragment opts in; any other value — including a typo like fragmnet — is clamped to iframe (fail-safe, but silent). Enabling the fragment engine also requires the /@fragment gateway, which is self-provided by wippy/views (≥ 0.5.9) — no consumer wiring. A page can override the deployment default per-page with wippy.renderEngine.

App Identity

Feature Flags

The facade shell's bootstrap token is separate from session_type. The shell always reads localStorage["@wippy_token_info"], parses its JSON token field, and redirects to login_path when the value is missing or invalid. It passes that token to the Web Host. In cookie mode the Web Host also stores the token in its @wippy-gen2/token cookie; in non-persistent mode it does not use that secondary cookie.

Theming

Three scopes apply: global (everywhere), host (the Web Host chrome — sidebar, chat, page area), and children (child view.page render contexts and view.component web components). For which surface each knob reaches, see the CSS Delivery Matrix.

Put shared brand styling in the global custom_css and css_variables parameters so it reaches every surface. Use host_custom_css and host_css_variables for host-only elements such as the sidebar, chat panel, and splitters. A view.component can opt out of shadow-root *_custom_css with customCss: false.

Theme Mode and Persistence

Theme persistence is opt-in: theme_persist defaults to none, so nothing is stored until a deployment sets it to cookie or localStorage. When enabled the facade serves a ready-made script at GET /facade/theme-persist.js with the key and mode baked in; include it on any page that should share the theme. See Theme Persistence for the full model, the themeChanged host event, and non-Wippy-page integration.

Reusing Facade Theming on Non-Web-Host Pages

A page served outside the Web Host, such as login.html, an error page, or an email confirmation page, can reuse the facade theme. This keeps brand tokens and custom rules in one place.

First, keep custom_css and css_variables in standalone files rather than inlining them, and point the parameters at those files with fs:// plus a content_fs filesystem:

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

Use fs:// (resolved by content_fs at runtime), not file:// — file:// is inlined by the wippy loader relative to the YAML at load time. Keep the files in the same static folder your login_path page is served from (in app, static/ served at /app).

fs:// resolution applies to exactly the six theming parameters — custom_css, css_variables, host_custom_css, host_css_variables, children_custom_css, children_css_variables (CSS strings are read verbatim; JSON *_css_variables files are parsed as the variable map). icon_sets / host_icon_sets and every other JSON parameter (api_routes, chat, tanstack, …) are inline-only; fs:// is not resolved there.

A standalone page then links both:

• custom_css — already a .css file, so link it directly from where it is served.
• css_variables — JSON, so it is not linkable as-is. The facade renders it at GET /facade/variables.css as base plus effective Auto-light, Auto-dark, forced Light, and forced Dark blocks. Top-level values apply everywhere; @light / @dark replace selected names. The sheet is cached for 1h and registered on the same public router as /facade/config, so it carries the router prefix.

<!-- in login.html, served outside the Web Host -->
<link rel="stylesheet" href="/api/public/facade/variables.css">  <!-- css_variables, generated CSS -->
<link rel="stylesheet" href="/app/custom-css.facade.css">        <!-- custom_css file -->

To also share the theme mode (so a login.html honours and persists the same light/dark choice as the host), add the generated theme-persist script and call its write() from your switcher:

<script src="/api/public/facade/theme-persist.js"></script>
<!-- early-applies the stored theme and exposes window.wippyThemePersist -->

See Theme Persistence → Non-Wippy-hosted pages for a complete switcher example.

Optional JSON Parameters

Each of the following is a JSON-encoded string parameter; defaults are empty ({} or []).

These four are surfaced verbatim under hostConfig for the frontend:

These three are emitted as top-level AppConfig fields (siblings of hostConfig), not under hostConfig:

Config Endpoint

The facade registers GET /facade/config on the configured public router, so the effective URL includes that router's prefix. With the /api/public prefix from Setup, the page fetches /api/public/facade/config. The same router exposes GET /facade/variables.css, which renders css_variables as a text/css stylesheet for pages outside the Web Host. See Reusing Facade Theming on Non-Web-Host Pages. The frontend fetches the configuration on load:

{
    "facade_url": "https://web-host.wippy.ai/webcomponents-1.0.56",
    "iframe_origin": "https://web-host.wippy.ai",
    "iframe_url": "https://web-host.wippy.ai/webcomponents-1.0.56/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",
    "themeMode": "auto",
    "themePersist": "none",
    "themeStorageKey": "@wippy-theme-mode",
    "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": { "w-chart": ["data", "type"] },
        "chat":              { "...": "..." }
    }
}

The API URL is read from the PUBLIC_API_URL environment variable; APP_WEBSOCKET_URL is derived by replacing http:// with ws:// or https:// with wss://. Theming has three scopes (global, host, children) — host.i18n carries app branding. hostConfig keys are camelCased and assembled from facade parameters: session_type, history_mode, render_engine, show_admin, allow_select_model, start_nav_open, hide_nav_bar, disable_right_panel, hide_session_selector, plus optional additional_nav_items, state_cache, allow_additional_tags, and chat. render_engine becomes renderEngine (see Render engine). The api_routes, axios_defaults, and tanstack parameters are emitted as top-level AppConfig fields (apiRoutes, axiosDefaults, tanstack), siblings of hostConfig, not inside it.

The facade_url, iframe_origin, iframe_url, login_path, mode, and module_file fields are shell-level fields used by the embedding page to build itself — they are not part of the child AppConfig that the host initializes with. The iframe_origin/iframe_url fields are consumed only by manual, facade-less iframe embeddings (see Facade Entry Point). The mode field is the normalized fe_mode (compat or managed), and module_file is the JS-module entry the facade page loads — /module.js for compat, /managed-layout.js for managed.

Navigation Sidebar

Pages registered via wippy/views appear in the sidebar automatically based on their metadata:

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/

Sidebar Groups

Pages with the same group value are collected into collapsible sections. Groups are sorted by group_order (lower first), pages within groups by order.

Pages without a group appear as top-level items.

Controlling Visibility

Publishing with Embedded Assets

When publishing a component that includes static files (like the facade's public/ directory), use --embed to include fs.directory entries in the package:

wippy publish --embed facade:public_files

Without --embed, fs.directory entries are excluded from the published package. The --embed flag accepts entry IDs or names matching fs.directory entries.

See Also

• Views — Page and component system
• HTTP Server — HTTP service configuration
• Framework Overview — Framework module usage
• Facade Entry Point — How the facade starts the Web Host
• CSS Injection — How facade theming reaches child iframes
• Render Engines — Iframe and Web Fragment page rendering