feat(plugins): show connection/auth/rpc errors instead of spinning

Every built-in plugin now renders a clear connection state — connecting,
disconnected, unauthorized, or error, with a reload affordance — driven by the
devframe client's status, replacing the indefinite spinners that appeared when
the socket dropped or auth was refused. git (React), inspect (Vue), terminals
(Svelte), code-server (vanilla) and messages (Vue) gate their surface on the
status; a11y (Solid) keeps its BroadcastChannel-first UI and surfaces a
degraded backend as a quiet tag.

Author: antfubot

plugins/a11y/src/spa/app.tsx

@@ -52,7 +52,7 @@ export function App() {
         scanning={channel.scanning()}
         onRescan={channel.rescan}
       />
-      <MetaLine report={channel.report} backend={devframe.backend} />
+      <MetaLine report={channel.report} backend={devframe.backend} status={devframe.status} />
 
       <Show when={channel.report() && total() > 0}>
         <Summary counts={counts()} active={filter()} onToggle={toggleFilter} />

plugins/a11y/src/spa/components/header.tsx

@@ -45,14 +45,24 @@ export function Header(props: HeaderProps) {
   )
 }
 
-export function MetaLine(props: { report: Accessor<ScanReport | null>, backend: Accessor<string | null> }) {
+export function MetaLine(props: {
+  report: Accessor<ScanReport | null>
+  backend: Accessor<string | null>
+  status?: Accessor<string | null>
+}) {
+  // The backend is optional here, so a degraded connection is shown as a quiet
+  // tag rather than taking over the panel.
+  const degraded = () => {
+    const s = props.status?.()
+    return s === 'disconnected' || s === 'unauthorized' || s === 'error' ? s : null
+  }
   return (
     <Show when={props.report()}>
       {report => (
         <div class="meta">
           <span class="meta__url" title={report().url}>{report().url}</span>
-          <Show when={props.backend()}>
-            {b => <span class="meta__tag">{b()}</span>}
+          <Show when={degraded()} fallback={<Show when={props.backend()}>{b => <span class="meta__tag">{b()}</span>}</Show>}>
+            {s => <span class="meta__tag meta__tag--warn" title="devframe backend connection">{s()}</span>}
           </Show>
           <span class="meta__tag">
             axe

plugins/a11y/src/spa/lib/devframe.ts

@@ -1,3 +1,4 @@
+import type { DevframeConnectionStatus } from 'devframe/client'
 import type { Accessor } from 'solid-js'
 import type { Impact } from '../../shared/protocol.ts'
 import { connectDevframe } from 'devframe/client'
@@ -19,6 +20,12 @@ export interface A11yConfig {
 export interface DevframeState {
   /** `'websocket'` in dev, `'static'` for a baked build, `null` while/if unreachable. */
   backend: Accessor<string | null>
+  /**
+   * Connection status of the (optional) devframe backend. The panel's core
+   * scan loop runs over BroadcastChannel, so this is informational only —
+   * surfaced as a tag rather than blocking the UI.
+   */
+  status: Accessor<DevframeConnectionStatus | null>
   /** Impact taxonomy + copy from the `get-config` RPC. */
   config: Accessor<A11yConfig | null>
 }
@@ -31,11 +38,14 @@ export interface DevframeState {
  */
 export function connectDevframeState(): DevframeState {
   const [backend, setBackend] = createSignal<string | null>(null)
+  const [status, setStatus] = createSignal<DevframeConnectionStatus | null>(null)
   const [config, setConfig] = createSignal<A11yConfig | null>(null)
 
   connectDevframe()
     .then(async (rpc) => {
       setBackend(rpc.connectionMeta.backend)
+      setStatus(rpc.status)
+      rpc.events.on('connection:status', s => setStatus(s))
       try {
         await rpc.ensureTrusted(2000)
       }
@@ -51,7 +61,8 @@ export function connectDevframeState(): DevframeState {
     })
     .catch(() => {
       // No reachable backend (e.g. agent loaded outside a devframe host).
+      setStatus('error')
     })
 
-  return { backend, config }
+  return { backend, status, config }
 }

plugins/a11y/src/spa/styles.css

@@ -148,6 +148,12 @@ body {
   border-radius: 5px;
 }
 
+.meta__tag--warn {
+  border-color: color-mix(in oklab, #d9a441 60%, var(--line));
+  color: #d9a441;
+  text-transform: capitalize;
+}
+
 /* ── severity summary ──────────────────────────────────────────────────── */
 
 .summary {

plugins/code-server/src/client/connection-state.ts

@@ -0,0 +1,99 @@
+import type { DevframeConnectionStatus } from 'devframe/client'
+import { button, cx } from './design'
+
+interface StateCopy {
+  icon: string
+  title: string
+  body: string
+}
+
+const COPY: Record<Exclude<DevframeConnectionStatus, 'connected'>, StateCopy> = {
+  connecting: {
+    icon: 'i-ph-plugs-connected-duotone',
+    title: 'Connecting…',
+    body: 'Establishing a connection to the devframe server.',
+  },
+  disconnected: {
+    icon: 'i-ph-plugs-duotone',
+    title: 'Disconnected',
+    body: 'Lost the connection to the devframe server. Reload once it is back up.',
+  },
+  unauthorized: {
+    icon: 'i-ph-lock-key-duotone',
+    title: 'Not authorized',
+    body: 'Reopen the link printed by your dev server, then reload.',
+  },
+  error: {
+    icon: 'i-ph-warning-octagon-duotone',
+    title: 'Connection failed',
+    body: 'Could not reach the devframe server.',
+  },
+}
+
+export interface ConnectionStateHandle {
+  /** Render for a status. Returns `true` when it took over the container. */
+  update: (status: DevframeConnectionStatus, error?: string | null) => boolean
+  dispose: () => void
+}
+
+/**
+ * A full-container connection state, shown whenever the devframe client isn't
+ * `connected` so the launcher never sits on an unexplained blank while the
+ * socket is down. Reload is the recovery path (no auto-reconnect).
+ */
+export function createConnectionState(container: HTMLElement): ConnectionStateHandle {
+  const root = document.createElement('div')
+  root.className = 'absolute inset-0 flex flex-col items-center justify-center gap-4 bg-base color-base p-8 text-center z-nav'
+  root.hidden = true
+  container.append(root)
+
+  function update(status: DevframeConnectionStatus, error?: string | null): boolean {
+    if (status === 'connected') {
+      root.hidden = true
+      root.replaceChildren()
+      return false
+    }
+    const copy = COPY[status]
+    root.replaceChildren()
+
+    const glyph = document.createElement('div')
+    glyph.className = cx(copy.icon, 'text-4xl color-active')
+    root.append(glyph)
+
+    const text = document.createElement('div')
+    text.className = 'flex flex-col gap-1'
+    const title = document.createElement('p')
+    title.className = 'text-lg font-medium'
+    title.textContent = copy.title
+    const body = document.createElement('p')
+    body.className = 'text-sm color-muted max-w-sm'
+    body.textContent = copy.body
+    text.append(title, body)
+    if (error && status === 'error') {
+      const code = document.createElement('code')
+      code.className = 'mt-1 max-w-sm break-words font-mono text-xs color-faint'
+      code.textContent = error
+      text.append(code)
+    }
+    root.append(text)
+
+    if (status !== 'connecting') {
+      const reload = document.createElement('button')
+      reload.type = 'button'
+      reload.className = button({ variant: 'primary', size: 'sm' })
+      reload.textContent = 'Reload'
+      reload.addEventListener('click', () => location.reload())
+      root.append(reload)
+    }
+
+    root.hidden = false
+    return true
+  }
+
+  return {
+    update,
+    dispose() {
+      root.remove()
+    },
+  }
+}

plugins/code-server/src/client/index.ts

@@ -9,6 +9,7 @@ import type {
 import type { CodeServerViewState } from './view'
 import { connectDevframe } from 'devframe/client'
 import { STATE_KEY } from '../constants'
+import { createConnectionState } from './connection-state'
 import { createCodeServerView } from './view'
 
 export interface MountCodeServerOptions {
@@ -42,6 +43,18 @@ export async function mountCodeServer(
   if (rpc.connectionMeta.backend === 'websocket')
     await rpc.ensureTrusted(5000).catch(() => {})
 
+  // Overlay the launcher with a clear connection state whenever the client
+  // isn't connected — a dropped socket or refused auth would otherwise leave
+  // an unexplained blank / stale editor. Needs a positioned container.
+  if (!container.style.position)
+    container.style.position = 'relative'
+  const connectionState = createConnectionState(container)
+  const syncConnection = (): void => {
+    connectionState.update(rpc.status, rpc.connectionError?.message)
+  }
+  syncConnection()
+  const offConnection = rpc.events.on('connection:status', syncConnection)
+
   let detection: CodeServerDetection = { checked: false, installed: false, bin: 'code-server' }
   let server: CodeServerServerInfo = { status: 'stopped' }
   let auth: CodeServerAuth | undefined
@@ -148,6 +161,8 @@ export async function mountCodeServer(
     dispose() {
       disposed = true
       off?.()
+      offConnection?.()
+      connectionState.dispose()
       view.dispose()
     },
   }

plugins/git/src/client/components/connection-state.tsx

@@ -0,0 +1,68 @@
+'use client'
+
+import type { DevframeConnectionStatus } from 'devframe/client'
+import { button } from '../lib/design'
+import { Icon } from './ui/icon'
+
+interface StateCopy {
+  icon: string
+  title: string
+  body: string
+  spin?: boolean
+}
+
+const COPY: Record<Exclude<DevframeConnectionStatus, 'connected'>, StateCopy> = {
+  connecting: {
+    icon: 'i-ph-plugs-connected-duotone',
+    title: 'Connecting…',
+    body: 'Establishing a connection to the devframe server.',
+    spin: true,
+  },
+  disconnected: {
+    icon: 'i-ph-plugs-duotone',
+    title: 'Disconnected',
+    body: 'Lost the connection to the devframe server. Reload once it is back up.',
+  },
+  unauthorized: {
+    icon: 'i-ph-lock-key-duotone',
+    title: 'Not authorized',
+    body: 'This client isn’t authorized. Reopen the link printed by your dev server, then reload.',
+  },
+  error: {
+    icon: 'i-ph-warning-octagon-duotone',
+    title: 'Connection failed',
+    body: 'Could not reach the devframe server.',
+  },
+}
+
+/**
+ * Full-panel connection state — shown whenever the client isn't `connected`,
+ * so the UI never sits on an infinite spinner without saying why. Reload is the
+ * recovery path (the client doesn't auto-reconnect).
+ */
+export function ConnectionState({ status, error }: { status: DevframeConnectionStatus, error?: string | null }) {
+  if (status === 'connected')
+    return null
+  const copy = COPY[status]
+  return (
+    <div className="bg-base flex h-svh w-full flex-col items-center justify-center gap-4 p-8 text-center">
+      <Icon
+        name={copy.icon}
+        className={`color-active size-10 ${copy.spin ? 'animate-pulse' : ''}`}
+      />
+      <div className="flex flex-col gap-1">
+        <p className="color-base text-lg font-medium">{copy.title}</p>
+        <p className="color-muted max-w-sm text-sm">{copy.body}</p>
+        {error && status === 'error' && (
+          <p className="color-faint mt-1 max-w-sm break-words font-mono text-xs">{error}</p>
+        )}
+      </div>
+      {status !== 'connecting' && (
+        <button type="button" className={button({ variant: 'primary', size: 'sm' })} onClick={() => location.reload()}>
+          <Icon name="i-ph-arrow-clockwise" className="size-4" />
+          Reload
+        </button>
+      )}
+    </div>
+  )
+}

plugins/git/src/client/components/dashboard.tsx

@@ -6,6 +6,7 @@ import type { GitBranches } from '../../index'
 import { useCallback, useEffect, useRef, useState } from 'react'
 import { nav as navBar, navBrand, tab as tabClass, tabsList } from '../lib/design'
 import { CommitDetailsPanel } from './commit-details-panel'
+import { ConnectionState } from './connection-state'
 import { LogPanel } from './log-panel'
 import { RpcProvider, useRpc } from './rpc-provider'
 import { StatusPanel } from './status-panel'
@@ -91,10 +92,12 @@ function Resizer({ onPointerDown, label }: { onPointerDown: (e: ReactPointerEven
 }
 
 function ConnectionBadge() {
-  const { rpc, error } = useRpc()
-  if (error)
-    return <Badge variant="destructive">disconnected</Badge>
-  if (!rpc)
+  const { rpc, status } = useRpc()
+  if (status === 'error' || status === 'disconnected')
+    return <Badge variant="destructive">{status}</Badge>
+  if (status === 'unauthorized')
+    return <Badge variant="warning">unauthorized</Badge>
+  if (status === 'connecting' || !rpc)
     return <Badge variant="secondary">connecting…</Badge>
   const backend = rpc.connectionMeta.backend
   return (
@@ -251,10 +254,20 @@ function DashboardBody() {
   )
 }
 
+function DashboardGate() {
+  const { status, error } = useRpc()
+  // A static backend reports `connected` immediately; a websocket backend
+  // shows the connection state until it's live, so data views never spin
+  // against a socket that will never answer.
+  if (status !== 'connected')
+    return <ConnectionState status={status} error={error} />
+  return <DashboardBody />
+}
+
 export function Dashboard() {
   return (
     <RpcProvider>
-      <DashboardBody />
+      <DashboardGate />
     </RpcProvider>
   )
 }