プロキシと分離

Web Hostは各子マイクロフロントエンドをサンドボックス化されたコンテキストで実行し、Proxy APIを通じてホストに橋渡しします。マイクロフロントエンドアプリもWebコンポーネントも、@wippy-fe/proxy からimportすることでホストに到達します。

Proxy API

Proxy APIはホストへの入口です。ランタイムである proxy.js がこれを配信します。APIと現在の AppConfig をページ上に置き、@wippy-fe/proxy モジュールを通じて公開します。

• マイクロフロントエンドアプリ（view.page）の場合、ホストはページの srcdoc に proxy.js を注入します。
• Webコンポーネント（view.component）の場合、ランタイムは既にホストページ内に存在します。コンポーネントは別のiframeではなく、ホストのDOMにマウントされます。

コードは @wippy-fe/proxy がエクスポートする同期ゲッターを通じてこれを消費します:

import { host, api, on, config } from '@wippy-fe/proxy'

host.navigate('/dashboard')
const data = await api.get('/api/v1/agents')   // api は axios インスタンス。await は HTTP 呼び出し
on('@visibility', (visible) => { /* 処理を一時停止または再開する */ })

ポータブルなVueのルーティングは例外です。@wippy-fe/router が @history を消費し、ローカルの遷移を代わりに報告します。その周りに手動のルーティング購読を追加してはいけません。

これらのゲッターは同期的です。host、api、on、config などは、コードが実行される時点で既に利用可能です。設定はランタイムの初期化前に配置されるため（後述）、待つべきハンドシェイクはありません。Viteのビルドでは @wippy-fe/proxy を external としてマークしてください。ホストがimport mapを通じて提供します。全体の面についてはプロキシAPIを参照してください。

設定がアプリのiframeに届くまで

ホストが view.page を読み込むとき、srcdoc を構築し、アプリのスクリプトの前に、この順序で注入します:

<!-- 1. 子の AppConfig — ランタイムの読み込み前に同期的に設定される -->
<script>window.__WIPPY_APP_CONFIG__ = { /* auth, env, theming, hostConfig, context */ }</script>
<!-- 2. このページ向けの CSS 注入フラグ -->
<script>window.__WIPPY_PROXY_CONFIG__ = { injections: { css: { themeConfig: true, primevue: true /* … */ } } }</script>
<!-- 3. ランタイム (先行して loading.js) -->
<script src="/.../loading.js"></script>
<script src="/.../proxy.js"></script>

設定のグローバルが proxy.js の実行前に設定されるため、ランタイムは同期的に初期化され、@wippy-fe/proxy のゲッターは即座に機能します。ハンドシェイクはありません。ページがこれらのスクリプトを直接参照することはありません。<script data-role="@wippy/scripts"> のプレースホルダーが、ホストによって正しい順序のタグに置き換えられます。ページごとのオーバーライドは window.__WIPPY_CONFIG_OVERRIDES__ として届きます（プロキシAPI — 設定のオーバーライドを参照）。

Webコンポーネントも同じグローバルを見ます。ホストページ内で動作し、そこではコンポーネントの connectedCallback が発火する前にランタイムが既にそれらを設定しているからです。

アプリとWebコンポーネントの違い

どちらも @wippy-fe/proxy から同じAPIをimportします。異なるのは実行コンテキストとスタイルの配信方法です:

合成とネスト

子は合成できます。マイクロフロントエンドアプリやWebコンポーネントは、それ自体が子（同じくマイクロフロントエンドアプリやWebコンポーネント）をホストでき、その子もまた自身の子をホストできます。深さに制限はありません。どの階層も同じ @wippy-fe/proxy APIを使用します。

ノードが子をホストする方法は、子の種類によって異なります:

• iframeの子（マイクロフロントエンドアプリ、アーティファクト、任意のWippy HTML）は、<w-iframe>、<w-artifact>、html.inject を経由します。これらは子の srcdoc にランタイム（ベースURL、import map、loading.js、proxy.js、設定）を注入するため、トップレベルのアプリとまったく同じようにProxy APIを得ます。そのプロキシは親を経由してホストへ橋渡しします。
• Webコンポーネントの子にはそれらは一切不要です。そのタグをレンダリングするか、loadWebComponent / loadByTagName で読み込むだけで、同じDOM内で動作し、Proxy APIを直接importします。

子自身のコードは、トップレベルで動作しても何段もネストされていても同一です。@wippy-fe/proxy からimportして使うだけです。ネスト固有の特別なルールはありません。

仕組みについては、以下の<w-iframe>、<w-artifact>、高度なHTML注入を参照してください。

内部 — 読み取りもオーバーライドもしないこと

proxy.js は自身の用途のために以下のグローバルをインストールします。アプリケーションやコンポーネントのコードがこれらを読んだり代入したりしてはいけません。 代わりに @wippy-fe/proxy を使用してください。誤って上書きしないよう、ここに記載しています:

公開のJavaScript APIは2つのエントリポイントで構成されます。initWippyApp(config, rootContainer?) はWeb Host全体をマウントし（ファサードが使うモジュール埋め込みのエントリ。ファサードのエントリポイントを参照）、@wippy-fe/proxy は子アプリとコンポーネントのための同期APIです。上の表にあるものはすべて内部用です。

PostMessageプロトコル（IFrameMessageType） — 内部トランスポート

これはランタイムが内部的に使うワイヤープロトコルです。アプリケーションコードがこれらのメッセージを送受信することはありません。 @wippy-fe/proxy が代わりに処理します。

ホストが注入する標準の経路では、起動にハンドシェイクは不要です。設定は proxy.js の実行前に window.__WIPPY_APP_CONFIG__ として既に同期的に存在するため、ランタイムは即座にインスタンスを構築します。この経路でも get-config/set-config のやり取りは行われますが、それはブロックしない再同期およびライブ更新のチャネルとしてのみです。同期的にインスタンスが構築された後、iframeのランタイムは常に get-config を送り、ホストは set-config で応答し、以降の設定更新のたびに set-config を再送します。ネストされた <w-iframe> の子も同じように振る舞います。コードがこれらを待つことはありません。同期ゲッターは既に有効です。

ハンドシェイクが唯一のブロックする設定ソースになるのは、ただ1つのシナリオ、すなわち手動のファサードなしiframe埋め込み（iframe.html?waitForCustomConfig）の場合だけです。そこでは事前注入された window.__WIPPY_APP_CONFIG__ が存在しないため、初期化が最初の set-config でブロックし、親が get-config の要求に応答しなければなりません（ファサードのエントリポイント § 手動のiframe埋め込みを参照）。

すべてのメッセージは { type: '@gen2-chat', action: IFrameMessageType.*, ...payload } という形のJSONエンベロープです。type フィールドは APP_CONFIG_IFRAME_EVENT_TYPE で設定可能ですが、デフォルトは '@gen2-chat' です。

すべてのメッセージ型は IFrameMessageType の列挙で定義されています:

アプリケーションコードがこれらのメッセージを直接送受信することはありません。プロキシがプロトコルを透過的に処理し、@wippy-fe/proxy のAPI面だけを公開します。

<w-iframe> カスタム要素

<w-iframe> は proxy.js に組み込まれた低レベルのiframeプリミティブです。生のソースHTMLを受け取り、Wippyランタイム一式（ベースURL、import map、loading.js、proxy.js、子の設定）を注入し、その結果をサンドボックス化された srcdoc iframeとしてレンダリングします。

ソースHTMLを持っていて、Wippyのマイクロフロントエンドアプリが自動的に得るのと同じランタイムの挙動（認証付きAPI、状態の中継、WebSocketの中継、nav-ownerルーティング、親子間のブリッジメッセージング）が欲しい場合に <w-iframe> を使用します。

属性とプロパティ

要素が受け付けるJSのプロパティ:

const frame = document.querySelector('w-iframe')
frame.proxyConfig = { injections: { css: { markdown: false } } }
frame.configOverrides = { customization: { customCSS: ':root { --brand: red }' } }
frame.srcdoc = sourceHtml

イベントとメソッド

Shadow parts: loader、error、frame。

nav-owner が設定されている場合、デフォルトのルート同期の往復は完全に抑制されます。ホストは自身のURLバーを更新せず、子に UrlWasUpdatedInParent を返送しません。ナビゲーションの所有権は、nav-owner-route を待ち受ける親のコードに完全に委譲されます。イベントのdetailにある path は、子が host.onRouteChanged(internalRoute, navId?) に渡したままの生の内部ルートであり、マウントプレフィックスは付いていません（ホストがページのマウントプレフィックスを前置するデフォルトの CmdRouteChanged の経路とは異なります）。プレフィックスの付与やルーターへのマッピングは、埋め込み側の親の責任です:

const frame = document.querySelector('w-iframe')
frame.addEventListener('nav-owner-route', (event) => {
  const { path, navId } = event.detail
  myRouter.push(path)
})

親子間のブリッジ

ブリッジは名前付きチャネルを使うため、どちらの側も生の postMessage エンベロープを扱う必要がありません。

親側:

const frame = document.querySelector('w-iframe')

frame.addEventListener('wippy-message', async (event) => {
  const { channel, payload, respond, reject } = event.detail

  if (channel === 'pick-file') {
    try {
      respond({ id: 'file-1', name: 'data.csv' })
    } catch (error) {
      reject(error)
    }
  }
})

frame.post('refresh', { reason: 'parent-click' })
const result = await frame.request('get-selection', undefined, { timeoutMs: 5000 })

子側:

import { host } from '@wippy-fe/proxy'

host.bridge.post('ready', { value: 1 })
const file = await host.bridge.request('pick-file', { accept: '.csv' })

const off = host.bridge.on('refresh', async (payload) => {
  console.log('refresh requested', payload)
  return { ok: true }
})

host.bridge.on() は購読解除関数（() => void）を返します。1チャネルにつきアクティブなハンドラは1つです。 同じチャネルに複数のハンドラが登録された場合、最後に登録されたものが優先され、そのチャネルのすべての受信メッセージ（一方向の post() と request() の両方）を処理します。on() は加算的ではありません。以前のハンドラは（削除されるのではなく）隠され、新しいハンドラが存在する間は実行されません。プロキシは重複登録時に console.warn を出力します。最新のハンドラが購読を解除すると、そのチャネルの以前のハンドラが再びアクティブになります。独立した複数のリスナーが必要な場合は、別々のチャネル名を使用してください。

options.timeoutMs を省略した場合、host.bridge.request()（および親側の frame.request()）は10秒（10000 ミリ秒）の期限をデフォルトとします。タイムアウト時、返されるPromiseは Bridge request <id> timed out after <ms>ms というメッセージの Error で拒否されます。相手側にハンドラが登録されていないチャネルへの要求は、期限を待たずに No handler registered for channel "<channel>" で即座に拒否されます。

<w-artifact> カスタム要素

<w-artifact> はアーティファクトまたはページのメタデータとコンテンツを解決し、iframeを背景に持つ型については内部的に <w-iframe> に委譲します。コンテンツ型の検出（HTML、Markdown、Webページのパッケージ、ESMのパッケージ、直接タグのコンポーネント）を処理し、生の <w-iframe> より高レベルなAPIを提供します。

属性

イベント

CSSのstatusとparts

この要素は status 属性（loading、ready、error）を設定し、shadow partsを公開します:

w-artifact[status="loading"] { opacity: 0.5; }
w-artifact[status="error"]   { border: 1px solid var(--p-danger-color); }

w-artifact::part(loader) { font-size: 1rem; }
w-artifact::part(frame)  { border: 0; }

<w-iframe> と <w-artifact> と生の <iframe> の比較

WippyのアーティファクトUUIDやページIDを持っていて、プラットフォームにすべての解決を任せたい場合は <w-artifact> を使用します。既にソースHTMLを持っていて、直接ランタイムを注入したい場合は <w-iframe> を使用します。生の <iframe> は、Wippy APIを必要としない完全に外部のコンテンツにのみ使用します。

高度なHTML注入

要素をマウントせずにソースHTMLからsrcdocへの変換だけが必要な場合のために、プロキシは html.inject(...) を公開しています:

import { html } from '@wippy-fe/proxy'

const processed = await html.inject(sourceHtml, {
  baseUrl: 'https://example.com/app/',
  resourceId: 'child-id',
  resourceType: 'page',
  route: '/initial',
})

同じ関数は instance.html.inject、$W.html、import { html } from '@wippy-fe/proxy' としてもアクセスできます。通常のマウントには <w-iframe> を優先し、html.inject(...) はカスタムのホスティング基盤を構築する場合にのみ使用してください。