@_daniel_jiang/ai-host 0.1.0

package/src/iframe.ts

@@ -0,0 +1,751 @@
+import { AGENT_HOST_MSG, type ChildToParentMessage, type ParentToChildMessage, type WidgetPayload, cloneForPostMessage, isAgentHostMessage } from './messages'
+import { getActionAnchorElement, getActionAnchorRect, type PrimaryPageHint } from './store'
+
+const HUB_LAUNCHER_ID = 'agent-host-launcher'
+const HUB_PANEL_OVERLAY_ID = 'agent-host-hub-panel-overlay'
+const HUB_IFRAME_ID = 'agent-host-hub-iframe'
+const WIDGET_OVERLAY_ID = 'agent-host-widget-overlay'
+const WIDGET_IFRAME_ID = 'agent-host-widget-iframe'
+
+const HOST_SDK_STYLE_ID = 'agent-host-ai-host-styles'
+
+type IframeSurface = 'hub' | 'widget'
+
+/** 保留部署子路径（iframe src），仅去掉末尾 `/` */
+function normalizeBase(base: string): string {
+  return base.replace(/\/$/, '')
+}
+
+/**
+ * postMessage 的 targetOrigin / event.origin 只有「协议+主机+端口」，不含路径。
+ * agent_web_origin 常为 `https://host/agent-platform`，必须先取 URL.origin 再比对。
+ */
+function toBrowserOrigin(value: string): string {
+  try {
+    return new URL(value).origin
+  } catch {
+    return value.replace(/\/$/, '')
+  }
+}
+
+/** localhost / 127.0.0.1 视为等价，避免 dev 环境 origin 校验失败 */
+function originsMatch(expected: string, actual: string): boolean {
+  const a = toBrowserOrigin(expected)
+  const b = toBrowserOrigin(actual)
+  if (a === b) return true
+  try {
+    const ua = new URL(a)
+    const ub = new URL(b)
+    const loopback = new Set(['localhost', '127.0.0.1', '[::1]'])
+    return (
+      ua.protocol === ub.protocol &&
+      ua.port === ub.port &&
+      loopback.has(ua.hostname) &&
+      loopback.has(ub.hostname)
+    )
+  } catch {
+    return false
+  }
+}
+
+function ensureHostSdkStyles() {
+  if (typeof document === 'undefined' || document.getElementById(HOST_SDK_STYLE_ID)) return
+  const style = document.createElement('style')
+  style.id = HOST_SDK_STYLE_ID
+  style.textContent = `
+#${HUB_LAUNCHER_ID} {
+  position: fixed;
+  right: 24px;
+  bottom: 24px;
+  z-index: 2147482999;
+  width: 56px;
+  height: 56px;
+  border: none;
+  border-radius: 50%;
+  cursor: pointer;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  color: #fff;
+  font-size: 22px;
+  line-height: 1;
+  background: linear-gradient(145deg, #12a892 0%, #0d8f7b 55%, #0a7a6a 100%);
+  box-shadow: 0 4px 18px rgba(13, 143, 123, 0.42);
+  transition: transform 0.15s ease, opacity 0.2s ease, visibility 0.2s ease;
+}
+#${HUB_LAUNCHER_ID}:hover { transform: scale(1.05); }
+#${HUB_LAUNCHER_ID}.is-hidden {
+  opacity: 0;
+  visibility: hidden;
+  pointer-events: none;
+  transform: scale(0.85);
+}
+#${HUB_LAUNCHER_ID}.is-pulse {
+  animation: agent-host-fab-pulse 2s ease-in-out infinite;
+}
+#${HUB_LAUNCHER_ID} .agent-host-launcher-icon {
+  display: inline-block;
+  line-height: 1;
+  transform-origin: center center;
+}
+#${HUB_LAUNCHER_ID}.is-breathe .agent-host-launcher-icon {
+  animation: agent-host-clover-breathe 1.8s ease-in-out infinite;
+}
+#${HUB_LAUNCHER_ID} .agent-host-launcher-bell {
+  display: none;
+  width: 22px;
+  height: 22px;
+  line-height: 0;
+  transform-origin: top center;
+}
+#${HUB_LAUNCHER_ID} .agent-host-launcher-bell.is-visible {
+  display: inline-block;
+  animation: agent-host-bell-shake 0.85s ease-in-out infinite;
+}
+#${HUB_LAUNCHER_ID} .agent-host-launcher-bell svg {
+  width: 100%;
+  height: 100%;
+  display: block;
+}
+#${HUB_LAUNCHER_ID} .agent-host-launcher-badge {
+  position: absolute;
+  top: -4px;
+  right: -4px;
+  box-sizing: border-box;
+  min-width: 20px;
+  height: 20px;
+  padding: 0 5px;
+  border-radius: 999px;
+  font-size: 11px;
+  font-weight: 600;
+  line-height: 1;
+  display: none;
+  align-items: center;
+  justify-content: center;
+  border: 2px solid #fff;
+  background: #f59e0b;
+  color: #fff;
+}
+#${HUB_LAUNCHER_ID} .agent-host-launcher-badge.is-visible { display: flex; }
+#${HUB_LAUNCHER_ID} .agent-host-launcher-badge.is-waiting { background: #ef4444; }
+#agent-host-launcher-hint {
+  position: fixed;
+  right: 24px;
+  bottom: 88px;
+  z-index: 2147482998;
+  max-width: min(800px, calc(100vw - 48px));
+  padding: 10px 14px;
+  border-radius: 10px;
+  font-size: 13px;
+  line-height: 1.45;
+  color: #333;
+  background: #fff;
+  border: 1px solid rgba(13, 143, 123, 0.22);
+  box-shadow: 0 4px 20px rgba(0, 0, 0, 0.12);
+  display: none;
+  pointer-events: auto;
+}
+#agent-host-launcher-hint.is-visible { display: block; }
+#agent-host-launcher-hint.is-anchored {
+  right: auto;
+  bottom: auto;
+}
+#agent-host-launcher-hint .agent-host-hint-inner {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  flex-wrap: wrap;
+}
+#agent-host-launcher-hint .agent-host-hint-icon {
+  flex-shrink: 0;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 20px;
+  height: 20px;
+  font-size: 16px;
+  line-height: 1;
+  color: #0d8f7b;
+  transform-origin: center center;
+  animation: agent-host-hint-clover 4.5s ease-in-out infinite;
+}
+#agent-host-launcher-hint .agent-host-hint-text {
+  flex: 1;
+  min-width: 140px;
+  color: #333;
+}
+#agent-host-launcher-hint .agent-host-hint-actions {
+  display: flex;
+  align-items: center;
+  gap: 4px;
+  flex-shrink: 0;
+}
+#agent-host-launcher-hint .agent-host-hint-use {
+  border: 1px solid #0d8f7b;
+  border-radius: 6px;
+  padding: 0 12px;
+  height: 28px;
+  font-size: 12px;
+  font-weight: 500;
+  color: #0d8f7b;
+  background: transparent;
+  cursor: pointer;
+}
+#agent-host-launcher-hint .agent-host-hint-use:hover {
+  color: #fff;
+  background: #0d8f7b;
+}
+#agent-host-launcher-hint .agent-host-hint-dismiss {
+  border: none;
+  border-radius: 6px;
+  padding: 0 8px;
+  height: 28px;
+  font-size: 12px;
+  color: #999;
+  background: transparent;
+  cursor: pointer;
+}
+#agent-host-launcher-hint .agent-host-hint-dismiss:hover { color: #666; }
+#${HUB_PANEL_OVERLAY_ID} {
+  position: fixed;
+  inset: 0;
+  z-index: 2147483000;
+  pointer-events: none;
+}
+#${HUB_PANEL_OVERLAY_ID}.is-open {
+  pointer-events: auto;
+}
+#${HUB_PANEL_OVERLAY_ID} .agent-host-hub-backdrop {
+  position: absolute;
+  inset: 0;
+  background: rgba(15, 23, 42, 0.42);
+  opacity: 0;
+  transition: opacity 0.35s ease;
+}
+#${HUB_PANEL_OVERLAY_ID}.is-open .agent-host-hub-backdrop {
+  opacity: 1;
+}
+/* FAB 位圆形 → 居中工作室模态 */
+#${HUB_PANEL_OVERLAY_ID} .agent-host-hub-panel-shell {
+  position: absolute;
+  right: 24px;
+  bottom: 24px;
+  width: 56px;
+  height: 56px;
+  border-radius: 50%;
+  background: #fff;
+  box-shadow: 0 4px 18px rgba(13, 143, 123, 0.35);
+  overflow: hidden;
+  opacity: 0;
+  transform: scale(0.92);
+  transition:
+    width 0.42s cubic-bezier(0.22, 1, 0.36, 1),
+    height 0.42s cubic-bezier(0.22, 1, 0.36, 1),
+    right 0.42s cubic-bezier(0.22, 1, 0.36, 1),
+    bottom 0.42s cubic-bezier(0.22, 1, 0.36, 1),
+    border-radius 0.42s cubic-bezier(0.22, 1, 0.36, 1),
+    box-shadow 0.42s ease,
+    opacity 0.2s ease,
+    transform 0.42s cubic-bezier(0.22, 1, 0.36, 1);
+}
+#${HUB_PANEL_OVERLAY_ID}.is-open .agent-host-hub-panel-shell {
+  right: max(24px, calc((100vw - min(1120px, calc(100vw - 48px))) / 2));
+  bottom: max(24px, calc((100vh - min(780px, calc(100vh - 48px))) / 2));
+  width: min(1120px, calc(100vw - 48px));
+  height: min(780px, calc(100vh - 48px));
+  border-radius: 16px;
+  box-shadow: 0 24px 64px rgba(15, 23, 42, 0.22);
+  opacity: 1;
+  transform: scale(1);
+}
+@media (max-width: 720px) {
+  #${HUB_PANEL_OVERLAY_ID}.is-open .agent-host-hub-panel-shell {
+    right: 12px;
+    bottom: 12px;
+    width: calc(100vw - 24px);
+    height: calc(100vh - 24px);
+    border-radius: 12px;
+  }
+}
+#${HUB_PANEL_OVERLAY_ID} iframe {
+  width: 100%;
+  height: 100%;
+  border: none;
+  background: #fff;
+  display: block;
+  opacity: 0;
+  transition: opacity 0.2s ease 0.18s;
+}
+#${HUB_PANEL_OVERLAY_ID}.is-open iframe {
+  opacity: 1;
+}
+@keyframes agent-host-fab-pulse {
+  0%, 100% { box-shadow: 0 4px 18px rgba(13, 143, 123, 0.42); }
+  50% { box-shadow: 0 4px 26px rgba(13, 143, 123, 0.62); }
+}
+@keyframes agent-host-clover-breathe {
+  0%, 100% { transform: scale(1); }
+  50% { transform: scale(1.28); }
+}
+@keyframes agent-host-hint-clover {
+  0% { transform: scale(0.88) rotate(0deg); }
+  16.67% { transform: scale(1.12) rotate(0deg); }
+  33.33% { transform: scale(0.88) rotate(0deg); }
+  50% { transform: scale(1.12) rotate(0deg); }
+  66.67% { transform: scale(1) rotate(0deg); }
+  100% { transform: scale(1) rotate(360deg); }
+}
+@keyframes agent-host-bell-shake {
+  0%, 100% { transform: rotate(0deg); }
+  12% { transform: rotate(14deg); }
+  24% { transform: rotate(-12deg); }
+  36% { transform: rotate(10deg); }
+  48% { transform: rotate(-8deg); }
+  60% { transform: rotate(5deg); }
+  72% { transform: rotate(-3deg); }
+  84% { transform: rotate(1deg); }
+}
+`
+  document.head.appendChild(style)
+}
+
+export class IframeBridge {
+  private agentOrigin = ''
+  private hubLauncher: HTMLButtonElement | null = null
+  private hubLauncherBadge: HTMLSpanElement | null = null
+  private hubLauncherHint: HTMLDivElement | null = null
+  private hubPanelOverlay: HTMLDivElement | null = null
+  private hubIframe: HTMLIFrameElement | null = null
+  private widgetIframe: HTMLIFrameElement | null = null
+  private hubReady = false
+  private widgetReady = false
+  private hubPanelOpen = false
+  private lastRunning = 0
+  private lastWaiting = 0
+  private launcherHintAction: PrimaryPageHint | null = null
+  private hintRepositionBound = false
+  private hintScrollParents: EventTarget[] = []
+  private pendingHubMessages: ParentToChildMessage[] = []
+  private pendingWidgetMessages: ParentToChildMessage[] = []
+  private onChildMessage?: (msg: ChildToParentMessage) => void
+  private onHintUse?: (pageId: string, actionId: string) => void
+  private onHintDismiss?: () => void
+
+  constructor(
+    agentOrigin: string,
+    onChildMessage: (msg: ChildToParentMessage) => void,
+    handlers?: {
+      onHintUse?: (pageId: string, actionId: string) => void
+      onHintDismiss?: () => void
+    },
+  ) {
+    this.agentOrigin = normalizeBase(agentOrigin)
+    this.onChildMessage = onChildMessage
+    this.onHintUse = handlers?.onHintUse
+    this.onHintDismiss = handlers?.onHintDismiss
+    window.addEventListener('message', this.handleMessage)
+  }
+
+  destroy() {
+    window.removeEventListener('message', this.handleMessage)
+    this.unbindHintReposition()
+    this.removeHub()
+    this.closeWidget()
+  }
+
+  /** Launcher（宿主 DOM）+ 居中工作室模态（显隐用 CSS，不改 iframe 尺寸） */
+  mountHub() {
+    if (this.hubPanelOverlay || typeof document === 'undefined') return
+    ensureHostSdkStyles()
+    this.mountLauncher()
+    this.mountHubPanel()
+  }
+
+  openHubPanel() {
+    if (!this.hubPanelOverlay) return
+    this.hubPanelOpen = true
+    this.hubPanelOverlay.classList.add('is-open')
+    this.hubLauncher?.classList.add('is-hidden')
+    this.hubLauncherHint?.classList.remove('is-visible')
+    this.post('hub', { channel: AGENT_HOST_MSG, type: 'open-hub-panel' })
+    this.applyLauncherVisual()
+  }
+
+  closeHubPanel() {
+    if (!this.hubPanelOverlay) return
+    this.hubPanelOpen = false
+    this.hubPanelOverlay.classList.remove('is-open')
+    this.hubLauncher?.classList.remove('is-hidden')
+    this.post('hub', { channel: AGENT_HOST_MSG, type: 'close-hub-panel' })
+    this.updateLauncherHint(this.launcherHintAction)
+    this.applyLauncherVisual()
+  }
+
+  /** @deprecated 工作室模态固定宽度，忽略半屏展开 */
+  setHubPanelExpanded(_expanded: boolean) {
+    /* no-op: studio modal has fixed size */
+  }
+
+  updateLauncherHint(action: PrimaryPageHint | null) {
+    this.launcherHintAction = action
+    const el = this.hubLauncherHint
+    if (!el) return
+    if (this.hubPanelOpen) {
+      el.classList.remove('is-visible', 'is-anchored')
+      this.unbindHintReposition()
+      return
+    }
+    if (!action || !action.hint.trim()) {
+      el.innerHTML = ''
+      el.classList.remove('is-visible', 'is-anchored')
+      this.unbindHintReposition()
+      return
+    }
+    el.innerHTML = `
+      <div class="agent-host-hint-inner">
+        <span class="agent-host-hint-icon" aria-hidden="true">✦</span>
+        <span class="agent-host-hint-text"></span>
+        <div class="agent-host-hint-actions">
+          <button type="button" class="agent-host-hint-use">立即开始</button>
+          <button type="button" class="agent-host-hint-dismiss">稍后</button>
+        </div>
+      </div>`
+    const textEl = el.querySelector('.agent-host-hint-text')
+    if (textEl) textEl.textContent = action.hint
+    const useBtn = el.querySelector('.agent-host-hint-use')
+    const dismissBtn = el.querySelector('.agent-host-hint-dismiss')
+    const preventFocusSteal = (e: Event) => e.preventDefault()
+    useBtn?.addEventListener('mousedown', preventFocusSteal)
+    dismissBtn?.addEventListener('mousedown', preventFocusSteal)
+    useBtn?.addEventListener('click', (e) => {
+      e.stopPropagation()
+      this.onHintUse?.(action.pageId, action.actionId)
+    })
+    dismissBtn?.addEventListener('click', (e) => {
+      e.stopPropagation()
+      this.onHintDismiss?.()
+    })
+    el.classList.add('is-visible')
+    this.layoutHint(el, action)
+    this.bindHintReposition()
+  }
+
+  private layoutHint(el: HTMLDivElement, action: PrimaryPageHint) {
+    if (action.placement !== 'anchor') {
+      el.classList.remove('is-anchored')
+      el.style.top = ''
+      el.style.left = ''
+      return
+    }
+    const rect = getActionAnchorRect(action.pageId, action.actionId)
+    if (!rect) {
+      el.classList.remove('is-anchored')
+      el.style.top = ''
+      el.style.left = ''
+      return
+    }
+    el.classList.add('is-anchored')
+    const gap = 8
+    const hintW = el.offsetWidth || 320
+    const hintH = el.offsetHeight || 48
+    let top = rect.top
+    let left = rect.right + gap
+    if (left + hintW > window.innerWidth - 16) {
+      left = Math.max(16, rect.left)
+      top = rect.bottom + gap
+    }
+    if (top + hintH > window.innerHeight - 16) {
+      top = Math.max(16, rect.top - hintH - gap)
+    }
+    if (top < 16) top = 16
+    if (left < 16) left = 16
+    el.style.top = `${Math.round(top)}px`
+    el.style.left = `${Math.round(left)}px`
+  }
+
+  private onHintReposition = () => {
+    const action = this.launcherHintAction
+    const el = this.hubLauncherHint
+    if (!action || !el || !el.classList.contains('is-visible')) return
+    this.layoutHint(el, action)
+  }
+
+  private collectScrollParents(node: HTMLElement | null): HTMLElement[] {
+    const out: HTMLElement[] = []
+    let p = node?.parentElement ?? null
+    while (p) {
+      const style = window.getComputedStyle(p)
+      const oy = style.overflowY
+      const ox = style.overflowX
+      if (/(auto|scroll|overlay)/.test(`${ox} ${oy}`)) out.push(p)
+      p = p.parentElement
+    }
+    return out
+  }
+
+  private bindHintReposition() {
+    if (typeof window === 'undefined') return
+    if (!this.hintRepositionBound) {
+      window.addEventListener('scroll', this.onHintReposition, true)
+      window.addEventListener('resize', this.onHintReposition)
+      window.visualViewport?.addEventListener('resize', this.onHintReposition)
+      window.visualViewport?.addEventListener('scroll', this.onHintReposition)
+      this.hintRepositionBound = true
+    }
+    const action = this.launcherHintAction
+    for (const node of this.hintScrollParents) {
+      node.removeEventListener('scroll', this.onHintReposition)
+    }
+    this.hintScrollParents = []
+    if (!action || action.placement !== 'anchor') return
+    const anchor = getActionAnchorElement(action.pageId, action.actionId)
+    this.hintScrollParents = this.collectScrollParents(anchor)
+    for (const node of this.hintScrollParents) {
+      node.addEventListener('scroll', this.onHintReposition, { passive: true })
+    }
+  }
+
+  private unbindHintReposition() {
+    if (typeof window === 'undefined') return
+    if (this.hintRepositionBound) {
+      window.removeEventListener('scroll', this.onHintReposition, true)
+      window.removeEventListener('resize', this.onHintReposition)
+      window.visualViewport?.removeEventListener('resize', this.onHintReposition)
+      window.visualViewport?.removeEventListener('scroll', this.onHintReposition)
+      this.hintRepositionBound = false
+    }
+    for (const node of this.hintScrollParents) {
+      node.removeEventListener('scroll', this.onHintReposition)
+    }
+    this.hintScrollParents = []
+  }
+
+  private mountLauncher() {
+    if (this.hubLauncher || document.getElementById(HUB_LAUNCHER_ID)) return
+    const btn = document.createElement('button')
+    btn.id = HUB_LAUNCHER_ID
+    btn.type = 'button'
+    btn.title = '景行 AI'
+    btn.setAttribute('aria-label', '景行 AI')
+    btn.innerHTML =
+      '<span class="agent-host-launcher-icon" aria-hidden="true">✦</span>' +
+      '<span class="agent-host-launcher-bell" aria-hidden="true">' +
+      '<svg viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg">' +
+      '<path d="M12 3a5 5 0 0 0-5 5v1.5c0 1.3-.4 2.6-1.2 3.7L4.5 15.5c-.4.5-.1 1.3.5 1.3h14c.6 0 .9-.8.5-1.3l-1.3-2.3A6.6 6.6 0 0 1 17 9.5V8a5 5 0 0 0-5-5Z" fill="#f59e0b"/>' +
+      '<path d="M10 18.5a2 2 0 0 0 4 0" stroke="#f59e0b" stroke-width="1.8" stroke-linecap="round"/>' +
+      '</svg></span>' +
+      '<span class="agent-host-launcher-badge"></span>'
+    btn.addEventListener('click', () => this.openHubPanel())
+    document.body.appendChild(btn)
+    this.hubLauncher = btn
+    this.hubLauncherBadge = btn.querySelector('.agent-host-launcher-badge')
+
+    if (!document.getElementById('agent-host-launcher-hint')) {
+      const hint = document.createElement('div')
+      hint.id = 'agent-host-launcher-hint'
+      document.body.appendChild(hint)
+      this.hubLauncherHint = hint
+    } else {
+      this.hubLauncherHint = document.getElementById('agent-host-launcher-hint') as HTMLDivElement
+    }
+  }
+
+  private mountHubPanel() {
+    const overlay = document.createElement('div')
+    overlay.id = HUB_PANEL_OVERLAY_ID
+
+    const backdrop = document.createElement('div')
+    backdrop.className = 'agent-host-hub-backdrop'
+    backdrop.addEventListener('click', () => this.closeHubPanel())
+
+    const shell = document.createElement('div')
+    shell.className = 'agent-host-hub-panel-shell'
+
+    const iframe = document.createElement('iframe')
+    iframe.id = HUB_IFRAME_ID
+    iframe.title = '景行 AI'
+    iframe.src = `${this.agentOrigin}/host/hub?embed=1&panel=1&layout=studio`
+    iframe.allow = 'clipboard-read; clipboard-write'
+
+    shell.appendChild(iframe)
+    overlay.appendChild(backdrop)
+    overlay.appendChild(shell)
+    document.body.appendChild(overlay)
+
+    this.hubPanelOverlay = overlay
+    this.hubIframe = iframe
+  }
+
+  updateLauncherStats(running: number, waiting: number) {
+    this.lastRunning = running
+    this.lastWaiting = waiting
+    this.applyLauncherVisual()
+  }
+
+  private applyLauncherVisual() {
+    const btn = this.hubLauncher
+    const badge = this.hubLauncherBadge
+    if (!btn || !badge) return
+    const icon = btn.querySelector('.agent-host-launcher-icon') as HTMLElement | null
+    const bell = btn.querySelector('.agent-host-launcher-bell') as HTMLElement | null
+    const running = this.lastRunning
+    const waiting = this.lastWaiting
+    // 抽屉关闭且有待确认：中间换成橙色抖动铃铛（底色不变）
+    const hitlAlert = waiting > 0 && !this.hubPanelOpen
+
+    btn.classList.toggle('is-pulse', running > 0)
+    // 有进行中/待确认任务且显示四叶草时：图标变大呼吸
+    btn.classList.toggle('is-breathe', (running > 0 || waiting > 0) && !hitlAlert)
+    if (hitlAlert) {
+      btn.title = '有待确认事项，点击打开助手'
+      btn.setAttribute('aria-label', '有待确认事项，点击打开助手')
+    } else {
+      btn.title = '景行 AI'
+      btn.setAttribute('aria-label', '景行 AI')
+    }
+    if (icon) icon.style.display = hitlAlert ? 'none' : ''
+    if (bell) bell.classList.toggle('is-visible', hitlAlert)
+
+    if (running > 0) {
+      badge.textContent = String(running)
+      badge.classList.add('is-visible')
+      badge.classList.remove('is-waiting')
+    } else if (waiting > 0) {
+      badge.textContent = '!'
+      badge.classList.add('is-visible', 'is-waiting')
+    } else {
+      badge.textContent = ''
+      badge.classList.remove('is-visible', 'is-waiting')
+    }
+  }
+
+  removeHub() {
+    document.getElementById(HUB_LAUNCHER_ID)?.remove()
+    document.getElementById('agent-host-launcher-hint')?.remove()
+    document.getElementById(HUB_PANEL_OVERLAY_ID)?.remove()
+    this.hubLauncher = null
+    this.hubLauncherBadge = null
+    this.hubLauncherHint = null
+    this.hubPanelOverlay = null
+    this.hubIframe = null
+    this.hubReady = false
+    this.hubPanelOpen = false
+    this.pendingHubMessages = []
+  }
+
+  openWidget(payload: WidgetPayload, token: string, refreshToken?: string) {
+    this.closeWidget()
+    const overlay = document.createElement('div')
+    overlay.id = WIDGET_OVERLAY_ID
+    overlay.style.cssText =
+      'position:fixed;inset:0;z-index:2147483646;background:rgba(15,23,42,0.45);display:flex;align-items:center;justify-content:center;padding:16px;'
+    overlay.addEventListener('click', (e) => {
+      if (e.target === overlay) this.closeWidget()
+    })
+
+    const iframe = document.createElement('iframe')
+    iframe.id = WIDGET_IFRAME_ID
+    iframe.title = payload.title || payload.workflow
+    const q = new URLSearchParams({
+      embed: '1',
+      workflow: payload.workflow,
+      host: payload.host || '',
+      title: payload.title || '',
+    })
+    iframe.src = `${this.agentOrigin}/host/widget?${q.toString()}`
+    iframe.style.cssText =
+      'width:min(560px,100%);height:80vh;border:none;border-radius:12px;background:#fff;box-shadow:0 20px 60px rgba(0,0,0,0.25);display:block;'
+    overlay.appendChild(iframe)
+    document.body.appendChild(overlay)
+    this.widgetIframe = iframe
+    this.widgetReady = false
+
+    const initMsg: ParentToChildMessage = {
+      channel: AGENT_HOST_MSG,
+      type: 'init',
+      token,
+      refreshToken,
+    }
+    const safePayload: WidgetPayload = {
+      workflow: payload.workflow,
+      title: payload.title,
+      host: payload.host,
+      prefilled: payload.prefilled ? cloneForPostMessage(payload.prefilled) : undefined,
+      hostContext: payload.hostContext ? cloneForPostMessage(payload.hostContext) : undefined,
+      sessionId: payload.sessionId,
+      preferSandboxFiles: payload.preferSandboxFiles,
+    }
+    const openMsg: ParentToChildMessage = {
+      channel: AGENT_HOST_MSG,
+      type: 'open-widget',
+      payload: safePayload,
+    }
+    this.pendingWidgetMessages = [initMsg, openMsg]
+    // 须等 iframe 内 postMessage('ready') 后再 flush，否则 init/open-widget 会丢失
+  }
+
+  closeWidget() {
+    document.getElementById(WIDGET_OVERLAY_ID)?.remove()
+    this.widgetIframe = null
+    this.widgetReady = false
+    this.pendingWidgetMessages = []
+  }
+
+  sendToHub(msg: ParentToChildMessage) {
+    this.post('hub', msg)
+  }
+
+  private post(surface: IframeSurface, msg: ParentToChildMessage) {
+    const ready = surface === 'hub' ? this.hubReady : this.widgetReady
+    const queue = surface === 'hub' ? this.pendingHubMessages : this.pendingWidgetMessages
+    if (!ready) {
+      queue.push(msg)
+      return
+    }
+    const iframe = surface === 'hub' ? this.hubIframe : this.widgetIframe
+    iframe?.contentWindow?.postMessage(msg, toBrowserOrigin(this.agentOrigin))
+  }
+
+  private flush(surface: IframeSurface) {
+    const queue = surface === 'hub' ? this.pendingHubMessages : this.pendingWidgetMessages
+    const iframe = surface === 'hub' ? this.hubIframe : this.widgetIframe
+    if (!iframe?.contentWindow) return
+    const targetOrigin = toBrowserOrigin(this.agentOrigin)
+    while (queue.length) {
+      const msg = queue.shift()
+      if (msg) iframe.contentWindow.postMessage(msg, targetOrigin)
+    }
+  }
+
+  private handleMessage = (event: MessageEvent) => {
+    if (!originsMatch(this.agentOrigin, event.origin)) return
+    if (!isAgentHostMessage(event.data)) return
+    const msg = event.data as ChildToParentMessage
+    if (msg.type === 'ready') {
+      if (msg.surface === 'hub') {
+        this.hubReady = true
+        this.flush('hub')
+      } else {
+        this.widgetReady = true
+        this.flush('widget')
+      }
+      // 继续交给上层：Hub ready 时需重发 init + 同步 register-page
+      this.onChildMessage?.(msg)
+      return
+    }
+    if (msg.type === 'hub-panel-close') {
+      this.closeHubPanel()
+      return
+    }
+    if (msg.type === 'hub-panel-width') {
+      this.setHubPanelExpanded(Boolean(msg.expanded))
+      return
+    }
+    if (msg.type === 'hub-stats') {
+      this.updateLauncherStats(msg.running, msg.waiting)
+      this.onChildMessage?.(msg)
+      return
+    }
+    this.onChildMessage?.(msg)
+  }
+}