From 70935a16c61a79fde7b41c4a790d869424294ecd Mon Sep 17 00:00:00 2001
From: Sakana <15715093608@163.com>
Date: Sat, 5 Sep 2026 17:25:43 +0800
Subject: [PATCH] fix(webext): bridge tools to the inspected page

Bind the DevTools panel to its inspected tab and exact document, and relay page actions and in-page channels through dedicated ports. This lets Vue Tracer and A11y operate on the user app instead of the extension iframe.

Dispose connections on navigation and surface unsupported page bridges. Requires the companion Devframe bridge release before the downstream dependency upgrade and merge.
---
 packages/webext/app/panel/App.vue             |  38 ++++-
 .../app/panel/inspected-page-relay.test.ts    |  98 ++++++++++++
 .../webext/app/panel/inspected-page-relay.ts  |  74 +++++++++
 .../webext/app/panel/inspected-page.test.ts   | 143 ++++++++++++++++++
 packages/webext/app/panel/inspected-page.ts   | 119 +++++++++++++++
 5 files changed, 468 insertions(+), 4 deletions(-)
 create mode 100644 packages/webext/app/panel/inspected-page-relay.test.ts
 create mode 100644 packages/webext/app/panel/inspected-page-relay.ts
 create mode 100644 packages/webext/app/panel/inspected-page.test.ts
 create mode 100644 packages/webext/app/panel/inspected-page.ts

diff --git a/packages/webext/app/panel/App.vue b/packages/webext/app/panel/App.vue
index 09289d97d..34b20fad2 100644
--- a/packages/webext/app/panel/App.vue
+++ b/packages/webext/app/panel/App.vue
@@ -1,12 +1,16 @@
 <script setup lang="ts">
 import { computed, onMounted, onUnmounted, ref } from 'vue'
+import { createInspectedPageBridge } from './inspected-page'
 import { getInspectedWindowConnection } from './inspected-window'
 
 const viewerUrl = ref<string | null>(null)
+const viewer = ref<HTMLIFrameElement>()
 const errorMessage = ref<string | null>(null)
 const status = ref<'loading' | 'unavailable'>('loading')
 const METADATA_RETRY_COUNT = 200
 const METADATA_RETRY_DELAY = 100
+let generation = 0
+let disposeBridge: (() => void) | undefined
 
 function sleep(ms: number) {
   return new Promise(resolve => setTimeout(resolve, ms))
@@ -18,8 +22,10 @@ const statusText = computed(() => {
     : 'Vite DevTools unavailable'
 })
 
-async function resolveInspectedWindowConnection() {
+async function resolveInspectedWindowConnection(currentGeneration: number) {
   for (let i = 0; i < METADATA_RETRY_COUNT; i++) {
+    if (currentGeneration !== generation)
+      return
     const connection = await getInspectedWindowConnection()
     if (connection)
       return connection
@@ -29,15 +35,36 @@ async function resolveInspectedWindowConnection() {
 }
 
 async function initialize() {
+  const currentGeneration = ++generation
+  disposeBridge?.()
+  disposeBridge = undefined
+  viewerUrl.value = null
   status.value = 'loading'
   errorMessage.value = null
 
   try {
-    const connection = await resolveInspectedWindowConnection()
+    const connection = await resolveInspectedWindowConnection(currentGeneration)
+    if (currentGeneration !== generation)
+      return
     if (!connection)
       throw new Error('Unable to reconnect to the inspected page.')
 
-    viewerUrl.value = new URL('./', connection.metaBaseUrl).href
+    const session = crypto.randomUUID()
+    const url = new URL('./', connection.metaBaseUrl)
+    url.searchParams.set('devframe-inspected-page', session)
+    url.searchParams.set('devframe-parent-origin', location.origin)
+    disposeBridge = createInspectedPageBridge({
+      tabId: chrome.devtools.inspectedWindow.tabId,
+      viewerUrl: url.href,
+      session,
+      getViewerWindow: () => viewer.value?.contentWindow,
+      onError(message) {
+        viewerUrl.value = null
+        status.value = 'unavailable'
+        errorMessage.value = message
+      },
+    })
+    viewerUrl.value = url.href
   }
   catch (err) {
     status.value = 'unavailable'
@@ -46,7 +73,7 @@ async function initialize() {
 }
 
 function handleInspectedWindowNavigated() {
-  location.reload()
+  initialize()
 }
 
 onMounted(() => {
@@ -55,6 +82,8 @@ onMounted(() => {
 })
 
 onUnmounted(() => {
+  generation++
+  disposeBridge?.()
   chrome.devtools.network.onNavigated.removeListener(handleInspectedWindowNavigated)
 })
 </script>
@@ -62,6 +91,7 @@ onUnmounted(() => {
 <template>
   <iframe
     v-if="viewerUrl"
+    ref="viewer"
     :src="viewerUrl"
     title="Vite DevTools"
     class="h-screen w-screen border-0"
diff --git a/packages/webext/app/panel/inspected-page-relay.test.ts b/packages/webext/app/panel/inspected-page-relay.test.ts
new file mode 100644
index 000000000..8eb325ff4
--- /dev/null
+++ b/packages/webext/app/panel/inspected-page-relay.test.ts
@@ -0,0 +1,98 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { installInspectedPageRelay } from './inspected-page-relay'
+
+function listeners() {
+  const callbacks = new Set<(...args: any[]) => void>()
+  return {
+    addListener: vi.fn(callback => callbacks.add(callback)),
+    removeListener: vi.fn(callback => callbacks.delete(callback)),
+    emit: (...args: any[]) => callbacks.forEach(callback => callback(...args)),
+  }
+}
+
+function setup() {
+  vi.useFakeTimers()
+  const window = Object.assign(new EventTarget(), { postMessage: vi.fn() })
+  const onConnect = listeners()
+  const channels: {
+    port1: { onmessage?: (event: { data: unknown }) => void, close: ReturnType<typeof vi.fn>, postMessage: ReturnType<typeof vi.fn> }
+    port2: object
+  }[] = []
+  vi.stubGlobal('window', window)
+  vi.stubGlobal('location', { origin: 'http://localhost:5173' })
+  vi.stubGlobal('chrome', { runtime: { onConnect } })
+  vi.stubGlobal('MessageChannel', class {
+    port1 = { close: vi.fn(), postMessage: vi.fn() }
+    port2 = {}
+    constructor() {
+      channels.push(this)
+    }
+  })
+  const extensionPort = {
+    name: 'vite-devtools:inspected-page:session',
+    onMessage: listeners(),
+    onDisconnect: listeners(),
+    postMessage: vi.fn(),
+    disconnect: vi.fn(),
+  }
+  installInspectedPageRelay()
+  onConnect.emit(extensionPort)
+  return { channels, window, onConnect, extensionPort }
+}
+
+describe('isolated inspected page relay', () => {
+  afterEach(() => {
+    Reflect.deleteProperty(globalThis, '__VITE_DEVTOOLS_PAGE_RELAY__')
+    vi.unstubAllGlobals()
+    vi.useRealTimers()
+  })
+
+  it('reuses the isolated-world listener across panel reconnections', () => {
+    const state = setup()
+    installInspectedPageRelay()
+    expect(state.onConnect.addListener).toHaveBeenCalledOnce()
+    expect(state.window.postMessage).toHaveBeenCalledWith(
+      { type: 'devframe:inspected-page:connect', session: 'session' },
+      'http://localhost:5173',
+      [state.channels[0]!.port2],
+    )
+    state.extensionPort.onDisconnect.emit()
+  })
+
+  it('waits for the page bootstrap and drains requests only after its handshake', () => {
+    const state = setup()
+    const request = { type: 'request', id: '1', method: 'prepare', entryId: 'a11y' }
+    state.extensionPort.onMessage.emit(request)
+    expect(state.channels[0]!.port1.postMessage).not.toHaveBeenCalled()
+    vi.advanceTimersByTime(250)
+    expect(state.channels[0]!.port1.close).toHaveBeenCalledOnce()
+    expect(state.channels).toHaveLength(2)
+    state.channels[1]!.port1.onmessage?.({ data: { type: 'ready' } })
+    expect(state.channels[1]!.port1.postMessage).toHaveBeenCalledWith(request)
+    expect(state.extensionPort.postMessage).toHaveBeenCalledWith({ type: 'ready' })
+    vi.advanceTimersByTime(1000)
+    expect(state.channels).toHaveLength(2)
+    state.extensionPort.onDisconnect.emit()
+  })
+
+  it('releases page actions and stops relaying after the panel disconnects', () => {
+    const state = setup()
+    const page = state.channels[0]!.port1
+    page.onmessage?.({ data: { type: 'ready' } })
+    state.extensionPort.onDisconnect.emit()
+    expect(page.postMessage).toHaveBeenCalledWith({ type: 'disconnect' })
+    expect(page.close).toHaveBeenCalledOnce()
+    page.postMessage.mockClear()
+    state.extensionPort.onMessage.emit({ type: 'request' })
+    expect(page.postMessage).not.toHaveBeenCalled()
+    vi.advanceTimersByTime(1000)
+    expect(state.channels).toHaveLength(1)
+  })
+
+  it('disconnects the extension port when its specific page is unloaded', () => {
+    const state = setup()
+    state.window.dispatchEvent(new Event('pagehide'))
+    expect(state.extensionPort.disconnect).toHaveBeenCalledOnce()
+    expect(state.channels[0]!.port1.close).toHaveBeenCalledOnce()
+  })
+})
diff --git a/packages/webext/app/panel/inspected-page-relay.ts b/packages/webext/app/panel/inspected-page-relay.ts
new file mode 100644
index 000000000..c9e9b3e2c
--- /dev/null
+++ b/packages/webext/app/panel/inspected-page-relay.ts
@@ -0,0 +1,74 @@
+/** Runs in the inspected document's isolated world; keep this function self-contained. */
+export function installInspectedPageRelay() {
+  const global = globalThis as typeof globalThis & { __VITE_DEVTOOLS_PAGE_RELAY__?: boolean }
+  if (global.__VITE_DEVTOOLS_PAGE_RELAY__)
+    return
+  global.__VITE_DEVTOOLS_PAGE_RELAY__ = true
+
+  chrome.runtime.onConnect.addListener((extensionPort) => {
+    const prefix = 'vite-devtools:inspected-page:'
+    if (!extensionPort.name.startsWith(prefix))
+      return
+
+    const session = extensionPort.name.slice(prefix.length)
+    if (!/^[\w-]+$/.test(session))
+      return
+
+    let pagePort: MessagePort | undefined
+    let ready = false
+    let closed = false
+    let retry: ReturnType<typeof setTimeout> | undefined
+    const pending: unknown[] = []
+
+    function close() {
+      if (closed)
+        return
+      closed = true
+      clearTimeout(retry)
+      pagePort?.postMessage({ type: 'disconnect' })
+      pagePort?.close()
+      pending.length = 0
+      extensionPort.onMessage.removeListener(receive)
+      extensionPort.onDisconnect.removeListener(close)
+      window.removeEventListener('pagehide', disconnect)
+    }
+
+    function disconnect() {
+      close()
+      extensionPort.disconnect()
+    }
+
+    function receive(message: unknown) {
+      if (ready)
+        pagePort?.postMessage(message)
+      else
+        pending.push(message)
+    }
+
+    function connect() {
+      if (closed || ready)
+        return
+      pagePort?.close()
+      const channel = new MessageChannel()
+      pagePort = channel.port1
+      pagePort.onmessage = ({ data }) => {
+        if (closed)
+          return
+        if (data?.type === 'ready') {
+          ready = true
+          clearTimeout(retry)
+          for (const message of pending.splice(0))
+            pagePort?.postMessage(message)
+        }
+        extensionPort.postMessage(data)
+      }
+      window.postMessage({ type: 'devframe:inspected-page:connect', session }, location.origin, [channel.port2])
+      retry = setTimeout(connect, 250)
+    }
+
+    extensionPort.onMessage.addListener(receive)
+    extensionPort.onDisconnect.addListener(close)
+    window.addEventListener('pagehide', disconnect)
+    connect()
+  })
+}
diff --git a/packages/webext/app/panel/inspected-page.test.ts b/packages/webext/app/panel/inspected-page.test.ts
new file mode 100644
index 000000000..7619c9280
--- /dev/null
+++ b/packages/webext/app/panel/inspected-page.test.ts
@@ -0,0 +1,143 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { createInspectedPageBridge, isViewerBridgeConnect } from './inspected-page'
+import { installInspectedPageRelay } from './inspected-page-relay'
+
+function eventListeners() {
+  const listeners = new Set<(...args: any[]) => void>()
+  return {
+    addListener: vi.fn(listener => listeners.add(listener)),
+    removeListener: vi.fn(listener => listeners.delete(listener)),
+    emit: (...args: any[]) => listeners.forEach(listener => listener(...args)),
+  }
+}
+
+function setup() {
+  const window = new EventTarget()
+  vi.stubGlobal('window', window)
+  const viewerWindow = {} as Window
+  const viewerPort = {
+    postMessage: vi.fn(),
+    close: vi.fn(),
+    onmessage: undefined as ((event: { data: unknown }) => void) | undefined,
+  }
+  const runtimePort = {
+    onMessage: eventListeners(),
+    onDisconnect: eventListeners(),
+    postMessage: vi.fn(),
+    disconnect: vi.fn(),
+  }
+  const executeScript = vi.fn().mockResolvedValue([{ documentId: 'inspected-document', frameId: 0 }])
+  const connect = vi.fn(() => runtimePort)
+  vi.stubGlobal('chrome', {
+    scripting: { executeScript },
+    tabs: { connect },
+    runtime: {},
+  })
+  const onError = vi.fn()
+  const dispose = createInspectedPageBridge({
+    tabId: 42,
+    session: 'panel-session',
+    viewerUrl: 'http://localhost:5173/__devtools/',
+    getViewerWindow: () => viewerWindow,
+    onError,
+  })
+  function message(overrides: Record<string, unknown> = {}) {
+    const event = new Event('message')
+    Object.assign(event, {
+      source: viewerWindow,
+      origin: 'http://localhost:5173',
+      data: { type: 'devframe:inspected-page:connect', session: 'panel-session' },
+      ports: [viewerPort],
+    }, overrides)
+    window.dispatchEvent(event)
+  }
+  return { message, viewerWindow, viewerPort, runtimePort, executeScript, connect, onError, dispose }
+}
+
+describe('inspected page bridge', () => {
+  afterEach(() => {
+    vi.unstubAllGlobals()
+    vi.useRealTimers()
+  })
+
+  it('requires the viewer window, origin, session, and exactly one port', () => {
+    const source = {} as Window
+    const event = {
+      source,
+      origin: 'http://localhost:5173',
+      data: { type: 'devframe:inspected-page:connect', session: 'session' },
+      ports: [{} as MessagePort],
+    }
+    expect(isViewerBridgeConnect(event, source, event.origin, 'session')).toBe(true)
+    expect(isViewerBridgeConnect(event, {} as Window, event.origin, 'session')).toBe(false)
+    expect(isViewerBridgeConnect(event, null, event.origin, 'session')).toBe(false)
+    expect(isViewerBridgeConnect(event, source, 'http://localhost:5174', 'session')).toBe(false)
+    expect(isViewerBridgeConnect(event, source, event.origin, 'another-session')).toBe(false)
+    expect(isViewerBridgeConnect({ ...event, ports: [] }, source, event.origin, 'session')).toBe(false)
+  })
+
+  it('injects only into the inspected tab main frame and connects to that document', async () => {
+    const state = setup()
+    state.message({ origin: 'http://unrelated.test' })
+    expect(state.executeScript).not.toHaveBeenCalled()
+    state.message()
+    await vi.waitFor(() => expect(state.connect).toHaveBeenCalled())
+    expect(state.executeScript).toHaveBeenCalledWith({
+      func: installInspectedPageRelay,
+      target: { tabId: 42, frameIds: [0] },
+      world: 'ISOLATED',
+    })
+    expect(state.connect).toHaveBeenCalledWith(42, {
+      documentId: 'inspected-document',
+      name: 'vite-devtools:inspected-page:panel-session',
+    })
+    state.dispose()
+  })
+
+  it('relays requests and page selections through the bound ports', async () => {
+    const state = setup()
+    state.message()
+    const request = { type: 'request', id: '1', method: 'activate', entryId: 'tracer' }
+    state.viewerPort.onmessage?.({ data: request })
+    await vi.waitFor(() => expect(state.runtimePort.postMessage).toHaveBeenCalledWith(request))
+    const selection = { type: 'selection', entryId: null }
+    state.runtimePort.onMessage.emit({ type: 'ready' })
+    state.runtimePort.onMessage.emit(selection)
+    expect(state.viewerPort.postMessage).toHaveBeenCalledWith(selection)
+    state.dispose()
+  })
+
+  it('disconnects and reports page navigation or port loss without a fallback target', async () => {
+    const state = setup()
+    state.message()
+    await vi.waitFor(() => expect(state.connect).toHaveBeenCalled())
+    state.runtimePort.onDisconnect.emit()
+    expect(state.viewerPort.postMessage).toHaveBeenCalledWith({ type: 'disconnect' })
+    expect(state.viewerPort.close).toHaveBeenCalledOnce()
+    expect(state.runtimePort.disconnect).toHaveBeenCalledOnce()
+    expect(state.onError).toHaveBeenCalledWith(expect.stringContaining('inspected page disconnected'))
+    state.dispose()
+  })
+
+  it('does not connect if disposed while the injection was pending', async () => {
+    const state = setup()
+    let finish!: (result: unknown) => void
+    state.executeScript.mockImplementation(() => new Promise(resolve => finish = resolve))
+    state.message()
+    state.dispose()
+    finish([{ documentId: 'old-document' }])
+    await Promise.resolve()
+    expect(state.connect).not.toHaveBeenCalled()
+    state.message()
+    expect(state.executeScript).toHaveBeenCalledOnce()
+  })
+
+  it('reports unsupported viewers even if they never request a bridge', () => {
+    vi.useFakeTimers()
+    const state = setup()
+    vi.advanceTimersByTime(10_000)
+    expect(state.onError).toHaveBeenCalledWith(expect.stringContaining('Update Vite DevTools and @devframes/hub'))
+    expect(state.connect).not.toHaveBeenCalled()
+    state.dispose()
+  })
+})
diff --git a/packages/webext/app/panel/inspected-page.ts b/packages/webext/app/panel/inspected-page.ts
new file mode 100644
index 000000000..6380bc195
--- /dev/null
+++ b/packages/webext/app/panel/inspected-page.ts
@@ -0,0 +1,119 @@
+import { installInspectedPageRelay } from './inspected-page-relay'
+
+interface InspectedPageBridgeOptions {
+  tabId: number
+  viewerUrl: string
+  session: string
+  getViewerWindow: () => Window | null | undefined
+  onError: (message: string) => void
+}
+
+export function isViewerBridgeConnect(
+  event: Pick<MessageEvent, 'source' | 'origin' | 'data' | 'ports'>,
+  viewerWindow: Window | null | undefined,
+  viewerOrigin: string,
+  session: string,
+) {
+  return !!viewerWindow
+    && event.source === viewerWindow
+    && event.origin === viewerOrigin
+    && event.data?.type === 'devframe:inspected-page:connect'
+    && event.data.session === session
+    && event.ports.length === 1
+}
+
+export function createInspectedPageBridge(options: InspectedPageBridgeOptions) {
+  let disposed = false
+  let viewerPort: MessagePort | undefined
+  let runtimePort: chrome.runtime.Port | undefined
+  let timer: ReturnType<typeof setTimeout> | undefined
+  const viewerOrigin = new URL(options.viewerUrl).origin
+
+  function disconnect() {
+    clearTimeout(timer)
+    viewerPort?.postMessage({ type: 'disconnect' })
+    viewerPort?.close()
+    viewerPort = undefined
+    runtimePort?.onDisconnect.removeListener(handleDisconnect)
+    runtimePort?.disconnect()
+    runtimePort = undefined
+  }
+
+  function fail(message: string) {
+    if (disposed)
+      return
+    viewerPort?.postMessage({ type: 'error', message })
+    disconnect()
+    options.onError(message)
+  }
+
+  function startTimeout() {
+    timer = setTimeout(() => {
+      fail('The inspected page does not support the DevTools page bridge. Update Vite DevTools and @devframes/hub, restart the dev server, then reload the page.')
+    }, 10_000)
+  }
+
+  function handleDisconnect() {
+    // Read lastError so Chrome does not report a second, unhandled error.
+    const detail = chrome.runtime.lastError?.message
+    fail(detail || 'The inspected page disconnected. Reload the page to reconnect Vite DevTools.')
+  }
+
+  async function connect(event: MessageEvent) {
+    if (disposed || !isViewerBridgeConnect(event, options.getViewerWindow(), viewerOrigin, options.session))
+      return
+
+    disconnect()
+    const port = event.ports[0]!
+    viewerPort = port
+    const pending: unknown[] = []
+    port.onmessage = ({ data }) => {
+      if (runtimePort)
+        runtimePort.postMessage(data)
+      else
+        pending.push(data)
+    }
+    startTimeout()
+
+    try {
+      const [injection] = await chrome.scripting.executeScript({
+        func: installInspectedPageRelay,
+        target: { tabId: options.tabId, frameIds: [0] },
+        world: 'ISOLATED',
+      })
+      if (disposed || viewerPort !== port)
+        return
+      if (!injection?.documentId)
+        throw new Error('Unable to identify the inspected document. Reload the page and reconnect Vite DevTools.')
+
+      runtimePort = chrome.tabs.connect(options.tabId, {
+        documentId: injection.documentId,
+        name: `vite-devtools:inspected-page:${options.session}`,
+      })
+      runtimePort.onDisconnect.addListener(handleDisconnect)
+      runtimePort.onMessage.addListener((data) => {
+        if (data?.type === 'ready')
+          clearTimeout(timer)
+        if (data?.type === 'error') {
+          fail(String(data.message))
+          return
+        }
+        port.postMessage(data)
+      })
+      for (const message of pending)
+        runtimePort.postMessage(message)
+    }
+    catch (error) {
+      if (!disposed && viewerPort === port)
+        fail(error instanceof Error ? error.message : String(error))
+    }
+  }
+
+  window.addEventListener('message', connect)
+  startTimeout()
+  return () => {
+    disposed = true
+    window.removeEventListener('message', connect)
+    disconnect()
+  }
+}