fix(devframe): clean up and deduplicate relay handshakes

Close unclaimed grant ports and end their opposite endpoints. Retry pending document handshakes with distinct identities so delayed grants cannot replace newer connections. Cover cancellation, delayed grants, late scripts, and direct in-page connections.

Author: SaKaNa-Y

docs/content/8.references/5.browser-api.md

@@ -71,7 +71,7 @@ The browser-only endpoint methods of the [in-page channel](/guide/in-page-channe
 | `transport.postMessage(data)` | Send a relay envelope to the paired relay. Preserve message order and structured-cloneable payloads. |
 | `transport.onMessage(handler)` | Subscribe to incoming relay envelopes and return an unsubscribe function. |
 
-The returned function removes listeners and closes relayed ports. The hub UI provider binds the transport to one inspected document and one hub UI provider document, validates the transport's sender, and disposes both relays on navigation or disconnection. The panel relay accepts same-origin descendant-frame handshakes; the page relay grants connections through the existing page script. Channel calls, shared state, and heartbeat messages retain the existing protocol.
+The returned function removes listeners and closes relayed ports. The hub UI provider binds the transport to one inspected document and one hub UI provider document, validates the transport's sender, and disposes both relays on navigation or disconnection. The panel relay accepts same-origin descendant-frame handshakes; the page relay grants connections through the existing page script. Channel calls, shared state, and heartbeat messages retain the existing protocol. Pending document handshakes retry every second. Each attempt uses an opaque relay-owned panel identity; superseded grants are closed, while the original identity is restored in the grant delivered to the panel.
 
 ## In-page channel error codes
 

packages/devframe/src/in-page-channel/relay.test.ts

@@ -202,3 +202,109 @@ describe('in-page channel relay', () => {
     await vi.waitFor(() => expect(send).toHaveBeenCalledOnce())
   })
 })
+
+it('deduplicates panel retries while the transport grant is delayed', async () => {
+  const s = session('/')
+  const send = s.transport.page.postMessage
+  const grants: unknown[] = []
+  s.transport.page.postMessage = (data) => {
+    if ((data as { kind: string }).kind === 'grant')
+      grants.push(data)
+    else
+      send(data)
+  }
+  await vi.waitFor(() => expect(grants).toHaveLength(1))
+  await new Promise(resolve => setTimeout(resolve, 80))
+  expect(grants).toHaveLength(1)
+  send(grants[0])
+  await vi.waitFor(() => expect(s.panel.status).toBe('connected'))
+  await expect(s.panel.call('highlight', '#slow')).resolves.toBe('/:#slow')
+  expect(s.pageScript.panels).toHaveLength(1)
+})
+
+it('cleans a late page grant after the relay connection was cancelled without heartbeat', async () => {
+  const s = session('/')
+  const post = s.page.win.postMessage
+  let release: (() => void) | undefined
+  s.page.win.postMessage = (data, origin, ports) => {
+    if ((data as { kind: string }).kind === 'grant')
+      release = () => post(data, origin, ports)
+    else
+      post(data, origin, ports)
+  }
+  await vi.waitFor(() => expect(s.pageScript.panels).toHaveLength(1))
+  s.stopPanel()
+  await new Promise(resolve => setTimeout(resolve, 0))
+  release!()
+  await vi.waitFor(() => expect(s.pageScript.panels).toHaveLength(0))
+})
+
+it('keeps one peer when a pending open is repeated before the local grant arrives', async () => {
+  const s = session('/')
+  const post = s.page.win.postMessage
+  const grants: (() => void)[] = []
+  s.page.win.postMessage = (data, origin, ports) => {
+    if ((data as { kind: string }).kind === 'grant')
+      grants.push(() => post(data, origin, ports))
+    else
+      post(data, origin, ports)
+  }
+  await vi.waitFor(() => expect(grants.length).toBeGreaterThan(0))
+  await new Promise(resolve => setTimeout(resolve, 80))
+  expect(grants).toHaveLength(1)
+  grants[0]!()
+  await vi.waitFor(() => expect(s.panel.status).toBe('connected'))
+  await expect(s.panel.call('highlight', '#pending')).resolves.toBe('/:#pending')
+})
+
+it('retries a timed-out local handshake and rejects its late grant', async () => {
+  const s = session('/')
+  const post = s.page.win.postMessage
+  const grants: (() => void)[] = []
+  s.page.win.postMessage = (data, origin, ports) => {
+    if ((data as { kind: string }).kind === 'grant')
+      grants.push(() => post(data, origin, ports))
+    else
+      post(data, origin, ports)
+  }
+  await vi.waitFor(() => expect(grants).toHaveLength(2), { timeout: 2500 })
+  grants[1]!()
+  await vi.waitFor(() => expect(s.panel.status).toBe('connected'))
+  grants[0]!()
+  await vi.waitFor(() => expect(s.pageScript.panels).toHaveLength(1))
+  await expect(s.panel.call('highlight', '#new-attempt')).resolves.toBe('/:#new-attempt')
+})
+
+it('connects when the page script starts after the first handshake', async () => {
+  const s = session('/')
+  s.pageScript.close()
+  await new Promise(resolve => setTimeout(resolve, 50))
+  const pageScript = createPageScriptChannel<Protocol>({
+    name: 'devframes:relay-test',
+    window: s.page.window,
+    heartbeat: false,
+    functions: { highlight: { handler: s.highlight } },
+  })
+  cleanup.push(() => pageScript.close())
+  await vi.waitFor(() => expect(s.panel.status).toBe('connected'), { timeout: 2500 })
+  await expect(s.panel.call('highlight', '#late-script')).resolves.toBe('/:#late-script')
+  expect(pageScript.panels).toHaveLength(1)
+})
+
+it('leaves direct in-page grants available to their own panel', async () => {
+  const s = session('/')
+  const direct = connectPanelChannel<Protocol>({
+    name: 'devframes:relay-test',
+    window: s.page.window,
+    targets: [s.page.window],
+    heartbeat: false,
+    functions: {},
+  })
+  cleanup.push(() => direct.close())
+  await vi.waitFor(() => {
+    expect(s.panel.status).toBe('connected')
+    expect(direct.status).toBe('connected')
+  })
+  await expect(direct.call('highlight', '#direct')).resolves.toBe('/:#direct')
+  expect(s.pageScript.panels).toHaveLength(2)
+})

packages/devframe/src/in-page-channel/relay.ts

@@ -29,6 +29,8 @@ interface RelayConnection {
   source?: Window
   port?: MessagePort
   detach?: () => void
+  forwardedHello?: InPageChannelHandshakeMessage
+  retryTimer?: ReturnType<typeof setTimeout>
 }
 
 function validHandshake(data: unknown, kind: 'hello' | 'grant'): data is InPageChannelHandshakeMessage {
@@ -77,6 +79,10 @@ export function createInPageChannelRelay(options: InPageChannelRelayOptions): ()
     throw new Error('An in-page channel relay requires a document with an origin')
   const connections = new Map<string, RelayConnection>()
   let disposed = false
+  const grantPrefix = `${nanoid()}:`
+  // Panel retries may arrive before the document answers. Only the page relay
+  // retries the local handshake, with a fresh identity to reject late grants.
+  const helloRetryMs = 1000
 
   function send(message: Omit<RelayMessage, 'channel' | 'relay'>): void {
     try {
@@ -92,6 +98,7 @@ export function createInPageChannelRelay(options: InPageChannelRelayOptions): ()
     if (!connection)
       return
     connections.delete(id)
+    clearTimeout(connection.retryTimer)
     connection.detach?.()
     // Endpoints recognize bye immediately, including browsers where closing
     // the other port does not dispatch a close event.
@@ -107,6 +114,7 @@ export function createInPageChannelRelay(options: InPageChannelRelayOptions): ()
   }
 
   function attach(id: string, connection: RelayConnection, port: MessagePort): void {
+    clearTimeout(connection.retryTimer)
     connection.port = port
     const onMessage = (event: MessageEvent): void => {
       send({ id, kind: 'data', data: event.data })
@@ -129,10 +137,6 @@ export function createInPageChannelRelay(options: InPageChannelRelayOptions): ()
       && (!hello.instanceId || grant.instanceId === hello.instanceId)
   }
 
-  function sameHello(left: InPageChannelHandshakeMessage, right: InPageChannelHandshakeMessage): boolean {
-    return left.name === right.name && left.panelId === right.panelId && left.instanceId === right.instanceId
-  }
-
   function onPanelHello(event: MessageEvent): void {
     if (!validHandshake(event.data, 'hello') || !event.source
       || !isDescendant(event.source as Window, win)) {
@@ -155,15 +159,28 @@ export function createInPageChannelRelay(options: InPageChannelRelayOptions): ()
   }
 
   function onPageGrant(event: MessageEvent): void {
-    if (event.source !== win || !validHandshake(event.data, 'grant') || !event.ports[0])
+    if (event.source !== win || !validHandshake(event.data, 'grant') || !event.ports[0]
+      || !event.data.panelId.startsWith(grantPrefix)) {
       return
+    }
     for (const [id, connection] of connections) {
-      if (!connection.port && matches(event.data, connection.hello)) {
+      if (!connection.port && connection.forwardedHello && matches(event.data, connection.forwardedHello)) {
         attach(id, connection, event.ports[0])
-        send({ id, kind: 'grant', handshake: event.data })
+        send({ id, kind: 'grant', handshake: { ...event.data, panelId: connection.hello.panelId } })
         return
       }
     }
+    // The page script has already registered its opposite endpoint. Explicitly
+    // end it even when heartbeat is disabled or peer close events are unavailable.
+    try {
+      event.ports[0].postMessage({ __dfIpc: 'bye' })
+    }
+    catch {
+      // A detached port is already disconnected.
+    }
+    finally {
+      event.ports[0].close()
+    }
   }
 
   const onWindowMessage = (event: MessageEvent): void => {
@@ -176,11 +193,20 @@ export function createInPageChannelRelay(options: InPageChannelRelayOptions): ()
   }
 
   function forwardHello(id: string, hello: InPageChannelHandshakeMessage): void {
-    const connection = connections.get(id)
-    if (connection?.port || (connection && !sameHello(connection.hello, hello)))
+    if (connections.has(id))
       return
-    connections.set(id, { hello })
-    win.postMessage(hello, origin)
+    const connection: RelayConnection = { hello }
+    connections.set(id, connection)
+    const requestPort = (): void => {
+      if (disposed || connections.get(id) !== connection || connection.port)
+        return
+      // Scope grants to this attempt so a timed-out reply cannot replace a
+      // newer connection, or be confused with a direct in-page panel's grant.
+      connection.forwardedHello = { ...hello, panelId: `${grantPrefix}${nanoid()}` }
+      connection.retryTimer = setTimeout(requestPort, helloRetryMs)
+      win.postMessage(connection.forwardedHello, origin)
+    }
+    requestPort()
   }
 
   const unsubscribe = options.transport.onMessage((data) => {