feat(inspect): explain the Instances tab and register example hub hosts

Give the Instances tab a self-describing empty state — what it lists,
where discovery comes from (`~/.devframe/instances/`), and how to make
instances appear (start another dev server, or a host that calls
`registerDevframeInstance`; note the disable env var) — plus a one-line
toolbar hint.

Register the in-process example hub hosts in the instance registry so
they show up in the tab like any standalone devframe: the vite-devframe-hub
(which the tab previously left empty) and the a11y-messages-playground,
mirroring the next-devframe-hub that already self-registers. Registration
waits for the dev server to listen, reuses its own origin, and is folded
into teardown so restarts don't leave ghost records. READMEs updated to
keep the hub examples at parity.

Author: antfubot

examples/a11y-messages-playground/README.md

@@ -78,7 +78,7 @@ the focused dock — the same path a manual dock click takes.
 
 | File | Role |
 |---|---|
-| `src/a11y-messages-playground.ts` | The Vite host — hub context, static + connection-meta mounts, side-car WS |
+| `src/a11y-messages-playground.ts` | The Vite host — hub context, static + connection-meta mounts, side-car WS, instance-registry registration |
 | `vite.config.ts` | Mounts a11y + messages; attaches the a11y agent as its dock's `clientScript` |
 | `src/client/main.ts` | Boots the client host, renders the dock rail + iframe stage |
 | `src/client/app-under-test.ts` | The intentionally-broken, multi-route app the agent scans |

examples/a11y-messages-playground/src/a11y-messages-playground.ts

@@ -1,11 +1,13 @@
 import type { DevframeHubContext } from '@devframes/hub/node'
 import type { ClientScriptEntry } from '@devframes/hub/types'
+import type { DevframeInstanceRegistration } from 'devframe/node'
 import type { DevframeDefinition, DevframeHost } from 'devframe/types'
 import type { Plugin, ResolvedConfig, ViteDevServer } from 'vite'
 import { homedir } from 'node:os'
+import process from 'node:process'
 import { createHubContext, mountDevframe } from '@devframes/hub/node'
 import { DEVFRAME_CONNECTION_META_FILENAME } from 'devframe/constants'
-import { startHttpAndWs } from 'devframe/node'
+import { registerDevframeInstance, startHttpAndWs } from 'devframe/node'
 import { serveStaticNodeMiddleware } from 'devframe/utils/serve-static'
 import { getPort } from 'get-port-please'
 import { join } from 'pathe'
@@ -37,6 +39,7 @@ export function a11yMessagesPlayground(options: A11yMessagesPlaygroundOptions =
   const base = normalizeBase(options.base ?? '/__hub/')
   let viteConfig: ResolvedConfig | undefined
   let started: { close: () => Promise<void> } | undefined
+  let registration: DevframeInstanceRegistration | undefined
 
   return {
     name: 'a11y-messages-playground',
@@ -48,9 +51,12 @@ export function a11yMessagesPlayground(options: A11yMessagesPlaygroundOptions =
 
     async configureServer(server: ViteDevServer) {
       // Vite re-invokes `configureServer` on restart — tear the old server down
-      // so we don't leak the WS port.
+      // so we don't leak the WS port, and drop the previous registry record so
+      // a restart doesn't leave a ghost instance behind.
       await started?.close().catch(() => {})
       started = undefined
+      registration?.unregister()
+      registration = undefined
 
       const cwd = viteConfig!.root
       const port = options.port ?? await getPort({ port: 9878, portRange: [9878, 9978] })
@@ -103,6 +109,37 @@ export function a11yMessagesPlayground(options: A11yMessagesPlaygroundOptions =
       // Tell the hub UI (served at `base`) where to find the WS endpoint.
       serveConnectionMeta(base)
 
+      // Register this playground in the global instance registry
+      // (`~/.devframe/instances/`) so discovery tooling — `devframe connect`
+      // and the inspector's Instances tab — lists it like any standalone
+      // devframe. See `examples/vite-devframe-hub` for the same pattern.
+      const register = (): void => {
+        const origin = host.resolveOrigin()
+        const url = new URL(origin)
+        registration = registerDevframeInstance({
+          pid: process.pid,
+          port: Number(url.port) || (url.protocol === 'https:' ? 443 : 80),
+          origin,
+          basePath: base,
+          id: 'example:a11y-messages-playground',
+          name: 'A11y + Messages Playground',
+          rootDir: cwd,
+          mcp: null,
+          startedAt: Date.now(),
+        })
+      }
+      if (server.httpServer?.listening)
+        register()
+      else
+        server.httpServer?.once('listening', register)
+
+      const closeStarted = started.close
+      started.close = async () => {
+        registration?.unregister()
+        registration = undefined
+        await closeStarted()
+      }
+
       server.httpServer?.once('close', () => {
         void started?.close().catch(() => {})
       })

examples/next-devframe-hub/README.md

@@ -20,6 +20,8 @@ Selecting a tool loads its SPA in the stage. The bottom drawer mirrors the hub's
 
 The A11y Inspector shows a live axe-core report of this hub's own page: the host serves the plugin's in-page agent module (`a11yAgentBundlePath`) same-origin through the catch-all route and attaches it as the a11y dock's `clientScript`; the hub client runtime — `createDevframeClientHost()` booted in `app/page.tsx` — imports it into the page, so the docked panel and the agent share the origin their BroadcastChannel rides.
 
+The **RPC & State Inspector** carries an **Instances** tab that lists every devframe dev server running on your machine. The host registers itself in the shared registry (`~/.devframe/instances/`) on startup via `registerDevframeInstance()`, so it shows up as "this instance"; start another example (e.g. `pnpm --filter vite-devframe-hub dev`, or any `node bin.mjs` CLI example) in a second terminal and it appears there too, each linking to its own SPA.
+
 ## What the example proves
 
 - `createHubContext()` boots a hub with no Vite-specific code path; a `DevframeHost` impl plugs Next specifics (static mounts, connection meta, storage, origin) in uniformly
@@ -35,7 +37,7 @@ The plugins run node-side (child processes, the native `zigpty` PTY backend) and
 
 | File | Role |
 |---|---|
-| `src/client/devframe/next-devframe-hub.ts` | The Next host — hub context, static-mount registry (incl. the a11y agent), side-car WS |
+| `src/client/devframe/next-devframe-hub.ts` | The Next host — hub context, static-mount registry (incl. the a11y agent), side-car WS, instance-registry registration |
 | `src/client/app/%5F_hub/%5F_connection.json/route.ts` | Boots the singleton host and serves `/__hub/__connection.json` |
 | `src/client/app/%5F_[id]/[[...path]]/route.ts` | Serves each mounted SPA and its connection meta under `/__<id>/` |
 | `src/client/app/page.tsx` | The browser UI that consumes the hub protocol |

examples/vite-devframe-hub/README.md

@@ -20,6 +20,8 @@ Selecting a tool loads its SPA in the stage. The bottom drawer mirrors the hub's
 
 The A11y Inspector shows a live axe-core report of this hub's own page. `vite.config.ts` attaches the plugin's in-page agent as the a11y dock's `clientScript` (served via `/@fs/`), and the hub client runtime — `createDevframeClientHost()` booted in `src/client/main.ts` — imports it into the host page. Panel and agent share the Vite origin their BroadcastChannel rides; hover a violation to ring the offending element in the hub UI.
 
+The **RPC & State Inspector** carries an **Instances** tab that lists every devframe dev server running on your machine. The host registers itself in the shared registry (`~/.devframe/instances/`) on startup via `registerDevframeInstance()`, so it shows up as "this instance"; start another example (`pnpm --filter a11y-messages-playground dev`, or any `node bin.mjs` CLI example) in a second terminal and it appears there too, each linking to its own SPA.
+
 ## What the example proves
 
 - `createHubContext()` boots a hub with no Vite-specific code path; a `DevframeHost` impl plugs framework specifics (static mounts, connection meta, storage, origin) in uniformly
@@ -36,7 +38,7 @@ The dock UI is plain DOM in `src/client/`. To skin your own viewer, read the sam
 
 | File | Role |
 |---|---|
-| `src/vite-devframe-hub.ts` | The Vite host — hub context, static + connection-meta mounts, side-car WS |
+| `src/vite-devframe-hub.ts` | The Vite host — hub context, static + connection-meta mounts, side-car WS, instance-registry registration |
 | `vite.config.ts` | Mounts the built-in plugins via the host's `devframes` option; attaches the a11y agent as its dock's `clientScript` |
 | `src/client/main.ts` | The browser UI that consumes the hub protocol |
 | `src/client/icons.ts` | Offline Phosphor icons for the dock |

examples/vite-devframe-hub/src/vite-devframe-hub.ts

@@ -1,12 +1,14 @@
 import type { DevframeHubContext } from '@devframes/hub/node'
 import type { ClientScriptEntry } from '@devframes/hub/types'
+import type { DevframeInstanceRegistration } from 'devframe/node'
 import type { DevframeDefinition, DevframeHost } from 'devframe/types'
 import type { Plugin, ResolvedConfig, ViteDevServer } from 'vite'
 import { homedir } from 'node:os'
+import process from 'node:process'
 import { defineHubRpcFunction } from '@devframes/hub'
 import { createHubContext, mountDevframe } from '@devframes/hub/node'
 import { DEVFRAME_CONNECTION_META_FILENAME } from 'devframe/constants'
-import { startHttpAndWs } from 'devframe/node'
+import { registerDevframeInstance, startHttpAndWs } from 'devframe/node'
 import { serveStaticNodeMiddleware } from 'devframe/utils/serve-static'
 import { getPort } from 'get-port-please'
 import { join } from 'pathe'
@@ -74,6 +76,7 @@ export function viteDevframeHub(options: ViteDevframeHubOptions = {}): Plugin {
   const base = normalizeBase(options.base ?? '/__hub/')
   let viteConfig: ResolvedConfig | undefined
   let started: { close: () => Promise<void> } | undefined
+  let registration: DevframeInstanceRegistration | undefined
 
   return {
     name: 'vite-devframe-hub',
@@ -85,9 +88,12 @@ export function viteDevframeHub(options: ViteDevframeHubOptions = {}): Plugin {
 
     async configureServer(server: ViteDevServer) {
       // Vite re-invokes `configureServer` on each restart. Tear down the
-      // previous server so we don't leak the WS port.
+      // previous server so we don't leak the WS port, and drop the previous
+      // registry record so a restart doesn't leave a ghost instance behind.
       await started?.close().catch(() => {})
       started = undefined
+      registration?.unregister()
+      registration = undefined
 
       const cwd = viteConfig!.root
       // Prefer 9777 but keep booting when it's taken (e.g. a lingering
@@ -175,6 +181,41 @@ export function viteDevframeHub(options: ViteDevframeHubOptions = {}): Plugin {
       // Tell the hub UI (served at `base`) where to find the WS endpoint.
       serveConnectionMeta(base)
 
+      // Record this hub in the global instance registry (`~/.devframe/instances/`)
+      // so discovery tooling — `devframe connect` and the inspector's Instances
+      // tab — lists it like any standalone devframe. `createDevServer` registers
+      // automatically; an in-process host like this one registers explicitly,
+      // reusing the Vite dev server's own origin (where `<base>__connection.json`
+      // is served). Registration waits for the server to be listening so the
+      // origin/port are known. Folded into `started.close` so every teardown
+      // path (restart, httpServer close, `closeBundle`) also unregisters.
+      const register = (): void => {
+        const origin = host.resolveOrigin()
+        const url = new URL(origin)
+        registration = registerDevframeInstance({
+          pid: process.pid,
+          port: Number(url.port) || (url.protocol === 'https:' ? 443 : 80),
+          origin,
+          basePath: base,
+          id: 'example:vite-devframe-hub',
+          name: 'Vite Devframe Hub',
+          rootDir: cwd,
+          mcp: null,
+          startedAt: Date.now(),
+        })
+      }
+      if (server.httpServer?.listening)
+        register()
+      else
+        server.httpServer?.once('listening', register)
+
+      const closeStarted = started.close
+      started.close = async () => {
+        registration?.unregister()
+        registration = undefined
+        await closeStarted()
+      }
+
       server.httpServer?.once('close', () => {
         void started?.close().catch(() => {})
       })

plugins/inspect/src/spa/components/InstancesView.vue

@@ -34,13 +34,29 @@ function formatUptime(startedAt: number): string {
   <div class="pane">
     <div class="toolbar">
       <span class="muted">{{ (instances ?? []).length }} running {{ (instances ?? []).length === 1 ? 'instance' : 'instances' }}</span>
+      <span class="muted">Devframe dev servers running on this machine, discovered via the shared registry (<code>~/.devframe/instances/</code>).</span>
     </div>
 
     <div v-if="!instances" class="center">
       Discovering instances…
     </div>
-    <div v-else-if="instances.length === 0" class="empty">
-      No running devframe instances discovered. Each dev server registers itself while it runs — start one to see it here.
+    <div v-else-if="instances.length === 0" class="inst-empty">
+      <span class="i-ph-broadcast-duotone inst-empty-icon" />
+      <p class="inst-empty-title">
+        No devframe instances discovered
+      </p>
+      <p>
+        This tab lists every devframe dev server running on your machine, so you
+        can jump between them. Each server registers itself in
+        <code>~/.devframe/instances/</code> while it runs.
+      </p>
+      <p>
+        Nothing shows up when only static/build servers are running, when
+        discovery is turned off (<code>DEVFRAME_DISABLE_INSTANCE_REGISTRY=1</code>),
+        or when an in-process host hasn't opted in. Start another
+        <code>devframe</code> dev server — or a hub host that calls
+        <code>registerDevframeInstance()</code> — then hit refresh.
+      </p>
     </div>
 
     <div v-else class="cards">

plugins/inspect/src/spa/style.css

@@ -701,3 +701,39 @@ textarea.args:focus {
   text-overflow: ellipsis;
   white-space: nowrap;
 }
+
+.inst-empty {
+  max-width: 560px;
+  margin: 0 auto;
+  padding: 40px 20px;
+  text-align: center;
+  color: var(--df-fg-dim);
+}
+
+.inst-empty p {
+  margin: 8px 0 0;
+  font-size: 12.5px;
+  line-height: 1.55;
+}
+
+.inst-empty-icon {
+  font-size: 32px;
+  color: var(--df-fg-faint);
+}
+
+.inst-empty-title {
+  margin-top: 10px !important;
+  font-size: 14px;
+  font-weight: 600;
+  color: var(--df-fg);
+}
+
+.inst-empty code,
+.toolbar code {
+  font-family: var(--df-mono);
+  font-size: 0.92em;
+  padding: 1px 5px;
+  border-radius: 4px;
+  background: var(--df-bg-active);
+  color: var(--df-fg-dim);
+}