フロントエンド Facade :id=frontend-facade

wippy/facade を使って、バックエンドのみのアプリから Wippy の Web UI を配信します。ファサードは薄い静的シェルです。Wippy Web Host のフロントエンドバンドルを CDN から読み込み、アプリが配信する JSON エンドポイントから構成します — プロジェクト側にフロントエンドのビルドステップはありません。ブランディング、テーマ設定、機能フラグはすべて依存関係のパラメータで駆動されます。

分類: 部分的な統合レシピです。Facadeシェルと設定エンドポイントの構成・検証は完結していますが、認証システムやWeb Hostが利用するアプリケーションAPIを新たに定義するものではありません。

構築するもの

Wippy UI を配信するバックエンドアプリ：

HTTP サーバーとパブリックルーター。
そのサーバーとルーターに接続され、カスタムブランディングを持つ wippy/facade 依存関係。
/ で動作するシェルと、/api/public/facade/config のその構成。

前提条件

Wippyランタイムv0.3.32aと、wippy initまたは Wippyアプリケーションテンプレートで作成したプロジェクト。
ブラウザでレンダリングする場合は、実際のバックエンドトークンを取得し、localStorageの @wippy_token_infoキーへ{"token":"..."}として保存する同一オリジンのログインフロー。 Facade自体はそのトークンを発行も検証もしません。
ファサードがインストールされていること：
```
wippy add wippy/facade@0.6.37
wippy install
```

動作の仕組み

シェルはファサードのテンプレートからレンダリングされ、HTTP サーバーの / で配信されます。そのアセットとディープリンクのフォールバックは、同じサーバー上の静的マウントから提供されます。
読み込み時に GET /api/public/facade/config を取得します。
localStorageから@wippy_token_infoを読み取り、その項目が存在しないかJSONとして解析できない場合のみlogin_pathへリダイレクトします。
CDN (facade_url + '/module.js') から Web Host バンドルをインポートし、その構成で initWippyApp(...) を呼び出します。

アプリが提供するのはシェルと構成のみです。UI 自体は CDN から提供されます。

依存関係

ファサードはアプリから 2 つのものを必要とします。ファイルを配信する http.service と、その構成エンドポイントがマウントされる http.router です。それ以外はすべてオプションのブランディングで、適切なデフォルト値が設定されています。

version: "1.0"
namespace: app

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

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

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

シェルは構成、テーマスクリプト、CSS 変数を /api/public/facade/ の下で要求するため、パブリックルーターのプレフィックスは /api/public でなければなりません。

実行

wippy run

シェルはサーバーのルートで配信され、構成エンドポイントはランタイム構成を返します：

curl http://localhost:8087/api/public/facade/config

{
  "facade_url": "https://web-host.wippy.ai/webcomponents-1.0.58",
  "iframe_origin": "https://web-host.wippy.ai",
  "iframe_url": "https://web-host.wippy.ai/webcomponents-1.0.58/iframe.html?waitForCustomConfig",
  "module_file": "/module.js",
  "mode": "compat",
  "login_path": "/login.html",
  "themeMode": "auto",
  "themePersist": "none",
  "themeStorageKey": "@wippy-theme-mode",
  "env": { "APP_API_URL": "", "APP_AUTH_API_URL": "", "APP_WEBSOCKET_URL": "" },
  "themeMode": "auto",
  "themePersist": "none",
  "themeStorageKey": "@wippy-theme-mode",
  "theming": {
    "host": { "i18n": { "app": { "title": "Verify App", "icon": "wippy:logo", "appName": "Wippy AI" } } }
  },
  "hostConfig": {
    "showAdmin": true, "allowSelectModel": false, "hideNavBar": false,
    "disableRightPanel": false, "startNavOpen": false, "hideSessionSelector": false,
    "renderEngine": "iframe", "session": { "type": "non-persistent" }, "history": "hash"
  }
}

以下はレスポンスから選んだフィールドです。

app_titleパラメータはtheming.host.i18n.app.titleとして現れます。

ルートドキュメントも取得します：

curl http://localhost:8087/

設定エンドポイントを取得し、@wippy_token_infoを確認するHTMLシェルが返ります。この2つのHTTP確認で、認証を回避せずにレシピを検証できます。

ブラウザ認証とレンダリング

FacadeのlocalStorage契約はオリジン単位です。別のポートやホスト名のログインページからは http://localhost:8087用のトークンを保存できません。同一オリジンで実際のトークン交換に成功した後、ログインページはトークンを書き込んでシェルへ戻ります：

localStorage.setItem('@wippy_token_info', JSON.stringify({token: result.token}));
window.location.assign('/');

シェルはトークンを読み取り、https://web-host.wippy.ai/webcomponents-1.0.56/module.jsをインポートしてHostへ渡します。ブラウザがリダイレクトされずにHostを表示し、APIリクエストの認証に成功して初めてレンダリング完了です。リダイレクトを抑えるだけのプレースホルダートークンは使用しないでください。シェルは値を検証しないため、最初の保護されたAPIリクエストへ失敗が移るだけです。

構成

パラメータは依存関係の parameters として渡されます (値は文字列で、JSON 値は JSON エンコードされた文字列です)。一般的なものは次のとおりです：

パラメータ	目的
`server` / `router`	(必須) HTTP サーバーとパブリックルーター
`app_title` / `app_name` / `app_icon`	ブランディング (アイコンは Iconify 参照)
`show_admin` / `hide_nav_bar`	機能フラグ (`"true"` / `"false"`)
`login_path`	認証トークンがない場合にシェルがリダイレクトする先
`session_type`	`non-persistent` または `cookie`
`history_mode`	`hash` または `browser`
`css_variables`	CSS カスタムプロパティの JSON 文字列、例: `'{"--p-primary":"#6366f1"}'`
`fe_facade_url`	CDN バンドル URL (ファサードリリースごとに固定。オーバーライドしない限りデフォルトのままにする)

2 つの値は、パラメータではなく PUBLIC_API_URL からランタイムに導出されます。API ベース URL と WebSocket URL (http→ws、https→wss) です。ファサードはこれを env レジストリ経由で読み取るため、アプリで env.variable として宣言してください。未設定の場合、ブラウザは window.location.origin にフォールバックします。

注意事項

ファサードは認証を提供しません。localStorage にトークンを書き込む認証フローを前提としており、それがない場合は login_path にリダイレクトします。userspace/users または独自の認証と組み合わせてください。
UIバンドルはCDN（fe_facade_url）から読み込まれるため、ユーザーのブラウザからそのURLへ到達できる必要があります。

トラブルシューティング

/login.htmlへのリダイレクトループは、現在のオリジンに解析可能な@wippy_token_infoがないことを示します。同じオリジンで実際のログインフローを完了してください。tokenが空または欠けた解析可能なオブジェクトでもリダイレクトは抑えられますが、Hostが保護されたAPIへアクセスすると失敗します。
/api/public/facade/configのHTTP 404は、ルータープレフィックスが/api/publicでないか、 router依存パラメータが別のエントリを指していることを示します。
設定レスポンスが正しくてもシェルが空白の場合、通常はブラウザがfacade_url + module_fileを読み込めていません。ブラウザのネットワークパネルとCDNポリシーを確認してください。
Host表示後の認証済みAPIエラーは、FacadeシェルではなくアプリケーションのAPIおよびトークン検証層の問題です。

次のステップ

Hello World — 最小限のプロジェクトレイアウト
認証 — シェルが期待するログインフローを接続する
HTTP エンドポイント — ルーター、静的ファイル、ハンドラ