fix(devframe,hub): republish remote-dock WS endpoint once it resolves

Port the second half of vitejs/devtools#520: a remote iframe dock
registered before the standalone WebSocket transport finishes binding
(the common `initHub` sequence — devframes, and their docks, install
before an async side-car/shared-server port resolves) was projected
without a connection descriptor, since `wsEndpoint` wasn't set yet.
Nothing re-registered that dock once the port resolved, so it kept a
stale/empty connection URL for the life of the process.

`DevframeInternalContext` now exposes `setWsEndpoint`/`onWsEndpointChange`
so subscribers learn when the endpoint changes instead of reading a
plain field once at registration time. The hub context subscribes and
re-projects every dock into `devframe:docks` shared state whenever the
endpoint resolves (or is torn down).

#171 already covers the atomic-bind half of #520.

Co-authored-by: webfansplz <webfansplz@gmail.com>

Refs: vitejs/devtools#520, vitejs/devtools#517

Author: antfubot

packages/devframe/src/node/hub-internals/context.ts

@@ -53,6 +53,23 @@ export interface DevframeInternalContext {
     /** Full `ws://` or `wss://` URL with host and port. */
     url: string
   }
+
+  /**
+   * Set {@link DevframeInternalContext.wsEndpoint} and notify subscribers —
+   * the WS-binding tiers (side-car, shared-server, and the `unbound` tier's
+   * `attach()`) call this once the socket is bound (or `undefined` once torn
+   * down) instead of assigning the field directly, so anything that already
+   * projected the endpoint (a hub's remote-dock URLs, registered before an
+   * async bind resolves) gets a chance to re-project it.
+   */
+  setWsEndpoint: (endpoint: { url: string } | undefined) => void
+  /**
+   * Subscribe to every {@link DevframeInternalContext.setWsEndpoint} call.
+   * Returns an unsubscribe function. The hub context uses this to refresh
+   * the `devframe:docks` shared state so a remote dock registered before the
+   * WS port resolves still ends up with a live connection URL.
+   */
+  onWsEndpointChange: (cb: () => void) => () => void
 }
 
 export const internalContextMap = new WeakMap<DevframeNodeContext, DevframeInternalContext>()
@@ -66,6 +83,7 @@ export function getInternalContext(context: DevframeNodeContext): DevframeIntern
       },
     })
     const remoteTokens = new Map<string, RemoteTokenRecord>()
+    const wsEndpointListeners = new Set<() => void>()
 
     function revokeRemoteToken(token: string): void {
       if (!remoteTokens.delete(token))
@@ -78,6 +96,14 @@ export function getInternalContext(context: DevframeNodeContext): DevframeIntern
         auth: storage,
       },
       revokeAuthToken: (token: string) => revokeAuthToken(context, storage, token),
+      setWsEndpoint(endpoint) {
+        internalContext.wsEndpoint = endpoint
+        for (const listener of wsEndpointListeners) listener()
+      },
+      onWsEndpointChange(cb) {
+        wsEndpointListeners.add(cb)
+        return () => wsEndpointListeners.delete(cb)
+      },
       remoteTokens,
       allocateRemoteToken(dockId, origin, originLock) {
         const token = randomToken()

packages/devframe/src/node/instance-shell.ts

@@ -131,7 +131,7 @@ async function bindHttpAndWs(options: BindHttpAndWsOptions): Promise<StartedServ
   const internal = getInternalContext(context)
   const wsUrl = `ws://${formatHostForUrl(bindHost)}:${resolvedPort}${options.path ?? ''}`
   if (websocket)
-    internal.wsEndpoint = { url: wsUrl }
+    internal.setWsEndpoint({ url: wsUrl })
 
   function connectionMeta(): ConnectionMeta {
     const jsonSerializableMethods: string[] = []
@@ -154,7 +154,7 @@ async function bindHttpAndWs(options: BindHttpAndWsOptions): Promise<StartedServ
       if (ownsHttpServer)
         await new Promise<void>(r => httpServer.close(() => r()))
       if (websocket && getInternalContext(context).wsEndpoint?.url === wsUrl)
-        getInternalContext(context).wsEndpoint = undefined
+        getInternalContext(context).setWsEndpoint(undefined)
     },
   }
 }
@@ -701,9 +701,9 @@ export function createInstanceShell<TContext extends DevframeNodeContext>(
       if (typeof address !== 'object' || !address)
         return
       const host = options.host ?? (address.address === '::' || address.address === '0.0.0.0' ? 'localhost' : address.address)
-      getInternalContext(ctx).wsEndpoint = {
+      getInternalContext(ctx).setWsEndpoint({
         url: `ws://${formatHostForUrl(host)}:${address.port}${routePath}`,
-      }
+      })
     }
     if (server.listening)
       record()

packages/hub/src/node/__tests__/context.test.ts

@@ -60,6 +60,49 @@ describe('createHubContext dock activation', () => {
   })
 })
 
+describe('createHubContext remote dock republishing', () => {
+  it('re-projects a remote dock once the WS endpoint resolves after registration', async () => {
+    // Mirrors vitejs/devtools#517/#520: a remote iframe dock can register
+    // before an async WS bind (side-car port probing, an `unbound` tier
+    // waiting on the host's own `attach()`) resolves `wsEndpoint`. Nothing
+    // else re-registers that dock once the port is known, so the fix has to
+    // re-project every dock when the endpoint changes.
+    const context = await createHubContext({
+      cwd: process.cwd(),
+      mode: 'build',
+      host: createHost(),
+    })
+
+    context.docks.register({
+      type: 'iframe',
+      id: 'remote',
+      title: 'Remote',
+      icon: 'ph:cube-duotone',
+      url: 'https://remote.test/app',
+      remote: true,
+    })
+
+    // The registration's own refresh is debounced too — let it settle before
+    // asserting the pre-bind projection.
+    await new Promise(resolve => setTimeout(resolve, 20))
+
+    const docksState = await context.rpc.sharedState.get<DevframeDockEntry[]>('devframe:docks')
+    const beforeBind = docksState.value()[0]
+    expect(beforeBind?.type === 'iframe' ? beforeBind.url : undefined).toBe('https://remote.test/app')
+
+    getInternalContext(context).setWsEndpoint({ url: 'ws://localhost:4173' })
+    // The refresh is debounced (0ms in `mode: 'build'`, still a macrotask).
+    await new Promise(resolve => setTimeout(resolve, 20))
+
+    const afterBind = docksState.value()[0]
+    const afterUrl = afterBind?.type === 'iframe' ? afterBind.url : ''
+    expect(afterUrl).not.toBe('https://remote.test/app')
+    expect(afterUrl).toContain('https://remote.test/app')
+
+    getInternalContext(context).setWsEndpoint(undefined)
+  })
+})
+
 describe('served context remote endpoint metadata', () => {
   it('sets and clears the internal websocket endpoint', async () => {
     const context = await createHostContext({

packages/hub/src/node/context.ts

@@ -6,6 +6,7 @@ import type { DevframeMessageEntry, DevframeMessageEntryInput, DevframeMessagesH
 import type { DevframeTerminalsHost } from '../types/terminals'
 import type { InstallDevframeOptions } from './install-devframe'
 import { createHostContext } from 'devframe/node'
+import { getInternalContext } from 'devframe/node/hub-internals'
 import { debounce } from 'perfect-debounce'
 import { DevframeCommandsHost as CommandsHostImpl } from './host-commands'
 import { DevframeDocksHost as DocksHostImpl } from './host-docks'
@@ -155,6 +156,13 @@ export async function createHubContext(options: CreateHubContextOptions): Promis
     docksSharedState.mutate(() => docks.values())
   }, debounceMs)
   docks.events.on('dock:entry:updated', refreshDocks)
+  // A remote iframe dock registered before the WS transport finishes binding
+  // (the common case: `initHub` installs devframes — and their docks — before
+  // resolving an async side-car/shared-server port) gets projected without a
+  // connection URL, since `wsEndpoint` isn't set yet. Nothing re-registers
+  // that dock once the port resolves, so re-project every dock once the
+  // endpoint becomes known (or is torn down) instead of leaving it stale.
+  getInternalContext(context).onWsEndpointChange(refreshDocks)
   docksSharedState.mutate(() => docks.values())
 
   // Cross-iframe dock activation. A dock activation is a discrete user intent

tests/helpers/serve-test-context.ts

@@ -76,7 +76,7 @@ export async function serveTestContext(options: ServeTestContextOptions): Promis
   // Publish the dialable socket URL on the context, mirroring the shell's own
   // binding, so surfaces that hand out a complete endpoint work in tests too.
   const wsUrl = `ws://${formatHostForUrl(bindHost)}:${resolvedPort}`
-  getInternalContext(context).wsEndpoint = { url: wsUrl }
+  getInternalContext(context).setWsEndpoint({ url: wsUrl })
 
   function connectionMeta(): ConnectionMeta {
     const jsonSerializableMethods: string[] = []
@@ -98,7 +98,7 @@ export async function serveTestContext(options: ServeTestContextOptions): Promis
       await closeWs()
       await new Promise<void>(r => httpServer.close(() => r()))
       if (getInternalContext(context).wsEndpoint?.url === wsUrl)
-        getInternalContext(context).wsEndpoint = undefined
+        getInternalContext(context).setWsEndpoint(undefined)
     },
   }
 }