aibridgejs — 跨 Context 橋接

import { Aside } from ‘@astrojs/starlight/components’;

aibridgejs 解決的問題是：不同 host runtime 的通訊方式各自不同，但你不想在業務邏輯裡散落 postMessage、flutter_inappwebview.callHandler 等平台細節。它提供一個穩定的 call / on / emit API，host 的差異由 adapter 封裝。

安裝

pnpm add aibridgejs

Subpath exports

Subpath	內容
aibridgejs	核心：createBridge、型別、error classes
aibridgejs/mock	createMockAdapter — loopback，適合開發與單元測試
aibridgejs/iframe	createIframeAdapter — origin 驗證的 postMessage
aibridgejs/flutter	createFlutterAdapter — Flutter InAppWebView JS handler
aibridgejs/detect	detectBridgeAdapter — 自動依 host globals 選擇 adapter

快速開始（mock adapter，適合開發環境）

import { createBridge } from "aibridgejs";
import { createMockAdapter } from "aibridgejs/mock";

const adapter = createMockAdapter();
const bridge = createBridge({ adapter, timeoutMs: 5_000 });

// 等 adapter ready（InAppWebView 環境中 JS handler registry 可能比 bridge 早 ready）
await bridge.ready();

// RPC call：送出請求，等待 response
const token = await bridge.call("session.getToken", { scope: "game" });

// 訂閱 host 推送的事件
const off = bridge.on("game.stateChanged", (payload) => {
  console.log("state:", payload);
});

// 單向通知（不等 response）
await bridge.emit("player.ready", { playerId: "p1" });

// 清理
off();
bridge.dispose();

切換到 iframe adapter

import { createBridge } from "aibridgejs";
import { createIframeAdapter } from "aibridgejs/iframe";

const adapter = createIframeAdapter({
  targetOrigin: "https://game.example.com",
  targetWindow: iframe.contentWindow!,
});

const bridge = createBridge({ adapter });
await bridge.ready();

自動偵測 adapter

import { createBridge } from "aibridgejs";
import { detectBridgeAdapter } from "aibridgejs/detect";

// 依序嘗試 flutter → iframe → mock
const adapter = detectBridgeAdapter();
const bridge = createBridge({ adapter });

`bridge.call()` 支援 `signal` 選項，適合場景切換時取消還沒回應的請求：

const ctrl = new AbortController();
const result = await bridge.call("scene.load", { id: "level2" }, {
  signal: ctrl.signal,
});
// 場景切換時：ctrl.abort()

協議結構

每個 envelope 都帶一個 string id 用於 request/response 對應，支援並發的多個 call()，各自由 id 匹配回傳。host 在 bridge ready 前的 call 會被 gating 機制擋住，確保不會提前發送。

常見搭配

• 與 aiecsjs 搭配：用 aiecsjs/serialize 序列化 world snapshot，透過 bridge 傳到另一個 window 或 Flutter shell
• 與 aifsmjs 搭配：machine definition 是純 JSON，可直接透過 bridge 傳輸後在另一端建立 runtime
• 混合 App：Flutter + WebView 場景中做原生功能呼叫（相機、存檔、通知）