@neat.is/web 0.2.10 → 0.3.1

package/app/components/AppShell.tsx

@@ -6,6 +6,8 @@ import { Rail } from './Rail'
 import { GraphCanvas } from './GraphCanvas'
 import { Inspector } from './Inspector'
 import { StatusBar } from './StatusBar'
+import { DebugPanel } from './DebugPanel'
+import { Toaster } from './Toaster'
 import type { GraphNode, GraphEdge } from '@neat.is/types'
 
 export interface GraphData {
@@ -36,10 +38,12 @@ export function AppShell() {
   const [selectedNodeId, setSelectedNodeId] = useState<string | null>(null)
   const [graphData, setGraphData] = useState<GraphData | null>(null)
   // ADR-057 #2 — start with URL or localStorage (synchronous), then resolve
-  // against /projects on mount if neither was set.
+  // against /projects on mount if neither was set. Safe because AppShell
+  // mounts client-only via dynamic({ ssr: false }) in app/page.tsx (ADR-062).
   const [project, setProjectState] = useState<string>(() => {
     return readUrlProject() ?? readStoredProject() ?? 'default'
   })
+  const [debugOpen, setDebugOpen] = useState(false)
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   const cyRef = useRef<any>(null)
   const resolvedRef = useRef(readUrlProject() !== null || readStoredProject() !== null)
@@ -85,6 +89,18 @@ export function AppShell() {
     if (nodeId) setSelectedNodeId(nodeId)
   }, [])
 
+  // ADR-058 #4 — Ctrl+Shift+D / Cmd+Shift+D toggles the debug panel.
+  useEffect(() => {
+    const handler = (e: KeyboardEvent) => {
+      if ((e.ctrlKey || e.metaKey) && e.shiftKey && (e.key === 'D' || e.key === 'd')) {
+        e.preventDefault()
+        setDebugOpen((v) => !v)
+      }
+    }
+    document.addEventListener('keydown', handler)
+    return () => document.removeEventListener('keydown', handler)
+  }, [])
+
   return (
     <div className="app">
       <TopBar
@@ -104,6 +120,8 @@ export function AppShell() {
       />
       <Inspector project={project} selectedNodeId={selectedNodeId} graphData={graphData} />
       <StatusBar project={project} graphData={graphData} />
+      <Toaster />
+      {debugOpen && <DebugPanel project={project} onClose={() => setDebugOpen(false)} />}
     </div>
   )
 }

package/app/components/DebugPanel.tsx

@@ -0,0 +1,112 @@
+'use client'
+
+import { useEffect, useState } from 'react'
+import {
+  CORE_URL_PUBLIC,
+  apiCallBus,
+  connectionBus,
+  sseEventBus,
+  type ApiCallEvent,
+  type ConnectionEvent,
+  type SseEvent,
+} from '../../lib/proxy-client'
+
+interface DebugPanelProps {
+  project: string
+  onClose: () => void
+}
+
+// ADR-058 #4 — read-only diagnostic overlay toggled via Ctrl+Shift+D.
+// Subscribes to the in-memory event buses populated by trackedFetch and the
+// SSE/health hooks. No POST/PUT/DELETE buttons — observation only.
+export function DebugPanel({ project, onClose }: DebugPanelProps) {
+  const [calls, setCalls] = useState<ApiCallEvent[]>([])
+  const [sseEvents, setSseEvents] = useState<SseEvent[]>([])
+  const [heartbeats, setHeartbeats] = useState<ConnectionEvent[]>([])
+
+  useEffect(() => {
+    const unsubCalls = apiCallBus.subscribe((e) => {
+      setCalls((prev) => [e, ...prev].slice(0, 10))
+    })
+    const unsubSse = sseEventBus.subscribe((e) => {
+      setSseEvents((prev) => [e, ...prev].slice(0, 10))
+    })
+    const unsubConn = connectionBus.subscribe((e) => {
+      setHeartbeats((prev) => [e, ...prev].slice(0, 20))
+    })
+    return () => {
+      unsubCalls()
+      unsubSse()
+      unsubConn()
+    }
+  }, [])
+
+  return (
+    <div
+      role="dialog"
+      aria-label="Debug panel"
+      style={{
+        position: 'fixed',
+        top: 60,
+        right: 16,
+        width: 420,
+        maxHeight: '70vh',
+        overflow: 'auto',
+        background: 'var(--ink-2, #14141a)',
+        border: '1px solid var(--rule, #2a2a30)',
+        color: 'var(--paper-1, #d8d3c9)',
+        fontFamily: 'JetBrains Mono, monospace',
+        fontSize: 11,
+        padding: 12,
+        zIndex: 1000,
+        boxShadow: '0 16px 40px rgba(0,0,0,0.45)',
+      }}
+    >
+      <div style={{ display: 'flex', justifyContent: 'space-between', alignItems: 'baseline', marginBottom: 8 }}>
+        <strong style={{ fontFamily: 'Spectral, serif', fontStyle: 'italic' }}>NEAT debug</strong>
+        <button onClick={onClose} aria-label="Close debug panel" title="Close (Ctrl+Shift+D)" style={{ background: 'transparent', border: 'none', color: 'inherit', cursor: 'pointer', fontSize: 14 }}>×</button>
+      </div>
+
+      <section style={{ marginBottom: 10 }}>
+        <div style={{ color: 'var(--paper-3)', marginBottom: 4 }}>environment</div>
+        <div>project: <code>{project}</code></div>
+        <div>NEAT_API_URL: <code>{CORE_URL_PUBLIC}</code></div>
+      </section>
+
+      <section style={{ marginBottom: 10 }}>
+        <div style={{ color: 'var(--paper-3)', marginBottom: 4 }}>last {calls.length} api calls</div>
+        {calls.length === 0 && <div style={{ opacity: 0.5 }}>none yet</div>}
+        {calls.map((c, i) => (
+          <div key={i} style={{ display: 'flex', gap: 8, lineHeight: 1.5 }}>
+            <span style={{ width: 36, color: c.status >= 400 ? '#e87a7a' : c.status === 0 ? '#d3a847' : 'var(--paper-2)' }}>{c.status || '—'}</span>
+            <span style={{ width: 50, opacity: 0.6 }}>{c.durationMs}ms</span>
+            <span style={{ flex: 1, overflow: 'hidden', textOverflow: 'ellipsis', whiteSpace: 'nowrap' }}>{c.path}</span>
+          </div>
+        ))}
+      </section>
+
+      <section style={{ marginBottom: 10 }}>
+        <div style={{ color: 'var(--paper-3)', marginBottom: 4 }}>last {sseEvents.length} sse events</div>
+        {sseEvents.length === 0 && <div style={{ opacity: 0.5 }}>none yet</div>}
+        {sseEvents.map((e, i) => (
+          <div key={i} style={{ display: 'flex', gap: 8 }}>
+            <span style={{ width: 90 }}>{new Date(e.timestamp).toLocaleTimeString()}</span>
+            <span>{e.type}</span>
+          </div>
+        ))}
+      </section>
+
+      <section>
+        <div style={{ color: 'var(--paper-3)', marginBottom: 4 }}>heartbeats</div>
+        {heartbeats.length === 0 && <div style={{ opacity: 0.5 }}>none yet</div>}
+        {heartbeats.map((h, i) => (
+          <div key={i} style={{ display: 'flex', gap: 8 }}>
+            <span style={{ width: 90 }}>{new Date(h.timestamp).toLocaleTimeString()}</span>
+            <span style={{ width: 60 }}>{h.state}</span>
+            <span style={{ opacity: 0.6 }}>{h.rttMs ? `${h.rttMs}ms` : ''}</span>
+          </div>
+        ))}
+      </section>
+    </div>
+  )
+}

package/app/components/GraphCanvas.tsx

@@ -486,12 +486,14 @@ export function GraphCanvas({ project, selectedNodeId, onNodeSelect, onGraphLoad
       })
       sse.addEventListener('node-removed', (e) => {
         const { id } = JSON.parse(e.data) as { id: string }
-        cy.getElementById(id).remove()
+        const el = cy.getElementById(id)
+        if (el && el.length) el.remove()
         pushGraphUpdate()
       })
       sse.addEventListener('edge-removed', (e) => {
         const { id } = JSON.parse(e.data) as { id: string }
-        cy.getElementById(id).remove()
+        const el = cy.getElementById(id)
+        if (el && el.length) el.remove()
         pushGraphUpdate()
       })
       sse.addEventListener('error', () => {

package/app/components/Inspector.tsx

@@ -62,7 +62,7 @@ interface InspectorProps {
 export function Inspector({ project, selectedNodeId, graphData }: InspectorProps) {
   const [node, setNode] = useState<GraphNode | null>(null)
   const [rootCause, setRootCause] = useState<RootCauseResult | null>(null)
-  const [activeTab, setActiveTab] = useState<'inspect' | 'edges'>('inspect')
+  const [activeTab, setActiveTab] = useState<'inspect' | 'edges' | 'owners' | 'history'>('inspect')
 
   // Stable synthetic metrics — re-randomised per node, not per render
   const metrics = useMemo(() => ({
@@ -99,8 +99,10 @@ export function Inspector({ project, selectedNodeId, graphData }: InspectorProps
         <div className="inspect-tabs" role="tablist">
           <div className="inspect-tab on" role="tab" aria-selected={true}>Inspect</div>
           <div className="inspect-tab" role="tab" aria-selected={false}>Edges</div>
-          <div className="inspect-tab" role="tab" aria-selected={false}>Owners</div>
-          <div className="inspect-tab" role="tab" aria-selected={false}>History</div>
+          {/* ADR-056 — Owners deferred: explicit disabled affordance. */}
+          <div className="inspect-tab disabled" role="tab" aria-selected={false} aria-disabled={true} title="Owners — coming in v0.3.x" style={{ opacity: 0.4, cursor: 'not-allowed' }}>Owners</div>
+          {/* ADR-056 — History deferred: explicit disabled affordance. */}
+          <div className="inspect-tab disabled" role="tab" aria-selected={false} aria-disabled={true} title="History — coming in v0.3.x" style={{ opacity: 0.4, cursor: 'not-allowed' }}>History</div>
         </div>
         <div className="insp-section" style={{ paddingTop: 32 }}>
           <div style={{ fontFamily: 'Spectral, serif', fontStyle: 'italic', color: 'var(--paper-3)', textAlign: 'center' }}>
@@ -156,6 +158,7 @@ export function Inspector({ project, selectedNodeId, graphData }: InspectorProps
   const showMetrics = !['ConfigNode', 'FrontierNode'].includes(node.type)
   const p99Num = parseFloat(metrics.p99)
   const errNum = parseFloat(metrics.err)
+  const owner = (node as unknown as { owner?: string }).owner
 
   return (
     <aside className="inspect" id="inspect">
@@ -176,8 +179,26 @@ export function Inspector({ project, selectedNodeId, graphData }: InspectorProps
         >
           Edges<span className="ct">{edgeCount}</span>
         </div>
-        <div className="inspect-tab" role="tab" aria-selected={false}>Owners</div>
-        <div className="inspect-tab" role="tab" aria-selected={false}>History</div>
+        {/* ADR-056 — Owners wired: shows ServiceNode.owner when available (ADR-054). */}
+        <div
+          className={`inspect-tab${activeTab === 'owners' ? ' on' : ''}`}
+          role="tab"
+          aria-selected={activeTab === 'owners'}
+          onClick={() => setActiveTab('owners')}
+        >
+          Owners
+        </div>
+        {/* ADR-056 — History deferred: explicit disabled affordance. */}
+        <div
+          className="inspect-tab disabled"
+          role="tab"
+          aria-selected={false}
+          aria-disabled={true}
+          title="History — coming in v0.3.x"
+          style={{ opacity: 0.4, cursor: 'not-allowed' }}
+        >
+          History
+        </div>
       </div>
 
       <div id="inspect-body">
@@ -323,6 +344,21 @@ export function Inspector({ project, selectedNodeId, graphData }: InspectorProps
           </section>
         )}
 
+        {activeTab === 'owners' && (
+          <section className="insp-section">
+            <div className="insp-h">Owners</div>
+            {owner ? (
+              <dl className="kv">
+                <dt>owner</dt>
+                <dd>{escapeHtml(owner)}</dd>
+              </dl>
+            ) : (
+              <div style={{ color: 'var(--paper-3)', fontStyle: 'italic', fontFamily: 'Spectral, serif', fontSize: 12 }}>
+                no owner declared in package.json or pyproject.toml (ADR-054)
+              </div>
+            )}
+          </section>
+        )}
       </div>
     </aside>
   )

package/app/components/Rail.tsx

@@ -31,10 +31,23 @@ export function Rail({ project }: RailProps) {
       .catch(() => {})
   }, [project])
 
+  // ADR-056 — Find is wired: dispatches a custom event TopBar's search input listens for.
+  // ADR-056 — Layers / NeatScript / Time travel / Diff / Comments / Agents / Settings
+  // are deferred features; rendered with `disabled` + tooltip affordance so the user
+  // perceives them as unavailable, not broken.
+  function focusFind(): void {
+    const input = document.querySelector<HTMLInputElement>('.top-search input')
+    input?.focus()
+  }
+
+  function disabledTip(label: string): string {
+    return `${label} — coming in v0.3.x`
+  }
+
   return (
     <nav className="rail">
       <div className="rail-group">
-        <button className="rail-btn active" aria-label="Graph view">
+        <button className="rail-btn active" aria-label="Graph view" title="Graph view">
           <svg viewBox="0 0 24 24" fill="none" stroke="currentColor">
             <circle cx="6" cy="6" r="2.5" /><circle cx="18" cy="6" r="2.5" />
             <circle cx="6" cy="18" r="2.5" /><circle cx="18" cy="18" r="2.5" />
@@ -42,13 +55,13 @@ export function Rail({ project }: RailProps) {
           </svg>
           <span className="rail-tip">Graph<span className="k">G</span></span>
         </button>
-        <button className="rail-btn" aria-label="Layers view">
+        <button className="rail-btn" aria-label="Layers (coming soon)" disabled title={disabledTip('Layers')} style={{ opacity: 0.35, cursor: 'not-allowed' }}>
           <svg viewBox="0 0 24 24" fill="none" stroke="currentColor">
             <path d="M4 7h16M4 12h10M4 17h16" />
           </svg>
           <span className="rail-tip">Layers<span className="k">L</span></span>
         </button>
-        <button className="rail-btn" aria-label="Find node">
+        <button className="rail-btn" aria-label="Find node" onClick={focusFind} title="Find — focus search">
           <svg viewBox="0 0 24 24" fill="none" stroke="currentColor">
             <circle cx="11" cy="11" r="6" /><path d="m20 20-4-4" />
           </svg>
@@ -57,19 +70,19 @@ export function Rail({ project }: RailProps) {
       </div>
 
       <div className="rail-group">
-        <button className="rail-btn" aria-label="NeatScript editor">
+        <button className="rail-btn" aria-label="NeatScript editor (coming soon)" disabled title={disabledTip('NeatScript')} style={{ opacity: 0.35, cursor: 'not-allowed' }}>
           <svg viewBox="0 0 24 24" fill="none" stroke="currentColor">
             <path d="M4 4h6v6H4zM14 4h6v6h-6zM4 14h6v6H4zM14 14h6v6h-6z" />
           </svg>
           <span className="rail-tip">NeatScript<span className="k">N</span></span>
         </button>
-        <button className="rail-btn" aria-label="Time travel">
+        <button className="rail-btn" aria-label="Time travel (coming soon)" disabled title={disabledTip('Time travel')} style={{ opacity: 0.35, cursor: 'not-allowed' }}>
           <svg viewBox="0 0 24 24" fill="none" stroke="currentColor">
             <circle cx="12" cy="12" r="9" /><path d="M12 7v5l3 2" />
           </svg>
           <span className="rail-tip">Time travel<span className="k">T</span></span>
         </button>
-        <button className="rail-btn" aria-label="Blast radius analysis">
+        <button className="rail-btn" aria-label="Blast radius (coming soon)" disabled title={disabledTip('Blast radius')} style={{ opacity: 0.35, cursor: 'not-allowed' }}>
           <svg viewBox="0 0 24 24" fill="none" stroke="currentColor">
             <circle cx="12" cy="12" r="3" /><circle cx="12" cy="12" r="7" />
             <path d="M12 3v2M12 19v2M3 12h2M19 12h2" />
@@ -77,7 +90,7 @@ export function Rail({ project }: RailProps) {
           <span className="rail-tip">Blast radius<span className="k">B</span></span>
           {blastBadge > 0 && <span className="badge">{blastBadge}</span>}
         </button>
-        <button className="rail-btn" aria-label="Graph diff">
+        <button className="rail-btn" aria-label="Graph diff (coming soon)" disabled title={disabledTip('Diff')} style={{ opacity: 0.35, cursor: 'not-allowed' }}>
           <svg viewBox="0 0 24 24" fill="none" stroke="currentColor">
             <path d="M8 4 4 8l4 4M16 12l4 4-4 4M14 4l-4 16" />
           </svg>
@@ -86,7 +99,7 @@ export function Rail({ project }: RailProps) {
       </div>
 
       <div className="rail-group">
-        <button className="rail-btn" aria-label="Comments">
+        <button className="rail-btn" aria-label="Comments (coming soon)" disabled title={disabledTip('Comments')} style={{ opacity: 0.35, cursor: 'not-allowed' }}>
           <svg viewBox="0 0 24 24" fill="none" stroke="currentColor">
             <path d="M4 6c0-1 1-2 2-2h12c1 0 2 1 2 2v9c0 1-1 2-2 2h-7l-4 4v-4H6c-1 0-2-1-2-2z" />
           </svg>
@@ -99,7 +112,7 @@ export function Rail({ project }: RailProps) {
           <span className="rail-tip">Incidents</span>
           {incidentBadge > 0 && <span className="badge">{incidentBadge}</span>}
         </Link>
-        <button className="rail-btn" aria-label="Agent control panel">
+        <button className="rail-btn" aria-label="Agents (coming soon)" disabled title={disabledTip('Agents')} style={{ opacity: 0.35, cursor: 'not-allowed' }}>
           <svg viewBox="0 0 24 24" fill="none" stroke="currentColor">
             <path d="M12 3v3M12 18v3M5 12H2M22 12h-3M6 6l2 2M16 16l2 2M6 18l2-2M16 8l2-2" />
             <circle cx="12" cy="12" r="3" />
@@ -111,7 +124,7 @@ export function Rail({ project }: RailProps) {
       <div className="rail-spacer" />
 
       <div className="rail-group" style={{ borderTop: '1px solid var(--rule)' }}>
-        <button className="rail-btn" aria-label="Settings">
+        <button className="rail-btn" aria-label="Settings (coming soon)" disabled title={disabledTip('Settings')} style={{ opacity: 0.35, cursor: 'not-allowed' }}>
           <svg viewBox="0 0 24 24" fill="none" stroke="currentColor">
             <circle cx="12" cy="12" r="3" />
             <path d="M19 12a7 7 0 0 1-.4 2.3l2 1.5-2 3.4-2.3-1a7 7 0 0 1-4 2.3l-.4 2.5h-4l-.4-2.5a7 7 0 0 1-4-2.3l-2.3 1-2-3.4 2-1.5A7 7 0 0 1 5 12a7 7 0 0 1 .4-2.3l-2-1.5 2-3.4 2.3 1a7 7 0 0 1 4-2.3L12 1h4l.4 2.5a7 7 0 0 1 4 2.3l2.3-1 2 3.4-2 1.5" />

package/app/components/StatusBar.tsx

@@ -2,18 +2,33 @@
 
 import { useEffect, useState } from 'react'
 import type { GraphData } from './AppShell'
+import {
+  CORE_URL_PUBLIC,
+  connectionBus,
+  sseEventBus,
+  type ConnectionEvent,
+  type SseEvent,
+} from '../../lib/proxy-client'
 
 interface StatusBarProps {
   project: string
   graphData: GraphData | null
 }
 
+type ConnState = 'ok' | 'slow' | 'down'
+type SseState = 'connected' | 'reconnecting' | 'disconnected'
+
 function formatTime(d: Date): string {
   return d.toTimeString().slice(0, 8) + ' ' + d.toTimeString().slice(9, 12)
 }
 
 export function StatusBar({ project, graphData }: StatusBarProps) {
   const [now, setNow] = useState(() => formatTime(new Date()))
+  // ADR-058 #1 — daemon connection state visible. Tracks /health latency
+  // and consecutive failures.
+  const [connState, setConnState] = useState<ConnState>('down')
+  // ADR-058 #2 — SSE state visible.
+  const [sseState, setSseState] = useState<SseState>('disconnected')
   const [healthy, setHealthy] = useState<boolean | null>(null)
 
   useEffect(() => {
@@ -21,28 +36,112 @@ export function StatusBar({ project, graphData }: StatusBarProps) {
     return () => clearInterval(id)
   }, [])
 
-  // ADR-057 #3 — re-check health when project changes so the indicator
-  // reflects the active project's daemon state.
+  // ADR-058 #1 — heartbeat every 5s; classify latency.
   useEffect(() => {
-    const check = () =>
-      fetch(`/api/health?project=${encodeURIComponent(project)}`)
-        .then((r) => r.json())
-        .then((d: { ok: boolean }) => setHealthy(d.ok === true))
-        .catch(() => setHealthy(false))
-    check()
-    const id = setInterval(check, 15_000)
+    let consecutiveFailures = 0
+    const SLOW_MS = 800
+    const DOWN_FAILS = 2
+
+    async function check(): Promise<void> {
+      const start = performance.now()
+      try {
+        const r = await fetch('/api/health', { cache: 'no-store' })
+        const rtt = Math.round(performance.now() - start)
+        const ok = r.ok
+        if (!ok) {
+          consecutiveFailures += 1
+          const next: ConnState = consecutiveFailures >= DOWN_FAILS ? 'down' : 'slow'
+          setConnState(next)
+          setHealthy(false)
+          connectionBus.emit({ state: next, rttMs: rtt, timestamp: Date.now() })
+          return
+        }
+        consecutiveFailures = 0
+        const next: ConnState = rtt > SLOW_MS ? 'slow' : 'ok'
+        setConnState(next)
+        setHealthy(true)
+        connectionBus.emit({ state: next, rttMs: rtt, timestamp: Date.now() })
+      } catch {
+        consecutiveFailures += 1
+        const next: ConnState = consecutiveFailures >= DOWN_FAILS ? 'down' : 'slow'
+        setConnState(next)
+        setHealthy(false)
+        connectionBus.emit({ state: next, timestamp: Date.now() })
+      }
+    }
+
+    void check()
+    const id = setInterval(() => void check(), 5_000)
     return () => clearInterval(id)
   }, [project])
 
+  // ADR-058 #2 — track SSE connection state. EventSource auto-reconnects
+  // per spec; we surface the state transitions.
+  useEffect(() => {
+    const sse = new EventSource('/api/events')
+    setSseState('reconnecting')
+
+    sse.onopen = () => {
+      setSseState('connected')
+    }
+    sse.onerror = () => {
+      // EventSource toggles readyState; readyState 0 = CONNECTING (reconnect),
+      // 2 = CLOSED.
+      setSseState(sse.readyState === EventSource.CLOSED ? 'disconnected' : 'reconnecting')
+    }
+
+    function record(type: string): (e: MessageEvent) => void {
+      return () => {
+        sseEventBus.emit({ type, timestamp: Date.now() })
+      }
+    }
+    sse.addEventListener('node-added', record('node-added'))
+    sse.addEventListener('edge-added', record('edge-added'))
+    sse.addEventListener('node-removed', record('node-removed'))
+    sse.addEventListener('edge-removed', record('edge-removed'))
+
+    return () => sse.close()
+  }, [])
+
   const nodeCount = graphData?.nodes.length ?? '—'
   const edgeCount = graphData?.edges.length ?? '—'
 
+  // ADR-058 #1 — `data-connection-state` is a stable attribute the contract
+  // test asserts. The colour classes follow.
+  const connColor: Record<ConnState, string> = {
+    ok: 'var(--prov-observed)',
+    slow: '#d3a847',
+    down: '#e87a7a',
+  }
+  const sseColor: Record<SseState, string> = {
+    connected: 'var(--prov-observed)',
+    reconnecting: '#d3a847',
+    disconnected: '#e87a7a',
+  }
+
+  // Suppress unused-var warnings for buses imported above so we keep the
+  // module-side effect (event subscriptions in DebugPanel are wired).
+  void connectionBus
+  void sseEventBus
+  type _typecheck = ConnectionEvent | SseEvent
+  void (null as unknown as _typecheck)
+
   return (
     <footer className="status">
-      <div className={`st-item${healthy ? ' live' : ' live-dead'}`}>
+      <div
+        className="st-item"
+        data-connection-state={connState}
+        title={`daemon @ ${CORE_URL_PUBLIC} — ${connState}`}
+      >
+        <span className="dot" style={{ background: connColor[connState] }} />
         <span className="k">neat</span>
         <span className="v">{project}</span>
       </div>
+      <div className="st-item" data-sse-state={sseState} title={`live updates: ${sseState}`}>
+        <span className="dot" style={{ background: sseColor[sseState] }} />
+        <span className="k">sse</span>
+        <span className="v">{sseState}</span>
+      </div>
       <div className="st-item">
         <span className="k">nodes</span>
         <span className="v" id="st-nodes">{nodeCount}</span>

package/app/components/Toaster.tsx

@@ -0,0 +1,67 @@
+'use client'
+
+import { useEffect, useState } from 'react'
+import { toastBus, type ToastEvent } from '../../lib/proxy-client'
+
+// ADR-058 #3 — surfaces non-2xx fetch responses as transient toasts.
+// Subscribes to `toastBus` populated by trackedFetch. Auto-dismisses after
+// six seconds; stacks up to four at a time.
+export function Toaster() {
+  const [toasts, setToasts] = useState<ToastEvent[]>([])
+
+  useEffect(() => {
+    const unsub = toastBus.subscribe((t) => {
+      setToasts((prev) => [...prev, t].slice(-4))
+      window.setTimeout(() => {
+        setToasts((prev) => prev.filter((p) => p.id !== t.id))
+      }, 6_000)
+    })
+    return unsub
+  }, [])
+
+  if (toasts.length === 0) return null
+
+  return (
+    <div
+      role="status"
+      aria-live="polite"
+      style={{
+        position: 'fixed',
+        bottom: 56,
+        right: 16,
+        display: 'flex',
+        flexDirection: 'column',
+        gap: 8,
+        zIndex: 999,
+      }}
+    >
+      {toasts.map((t) => {
+        const color = t.level === 'error' ? '#e87a7a' : t.level === 'warn' ? '#d3a847' : 'var(--prov-observed)'
+        return (
+          <div
+            key={t.id}
+            className="toast"
+            onClick={() => setToasts((prev) => prev.filter((p) => p.id !== t.id))}
+            style={{
+              background: 'var(--ink-2, #14141a)',
+              border: `1px solid ${color}`,
+              borderLeft: `3px solid ${color}`,
+              padding: '8px 12px',
+              fontFamily: 'JetBrains Mono, monospace',
+              fontSize: 11,
+              color: 'var(--paper-1, #d8d3c9)',
+              maxWidth: 360,
+              cursor: 'pointer',
+              boxShadow: '0 8px 16px rgba(0,0,0,0.35)',
+            }}
+          >
+            <div style={{ display: 'flex', gap: 8, alignItems: 'baseline' }}>
+              <span style={{ color, fontWeight: 600 }}>{t.status ?? t.level}</span>
+              <span style={{ flex: 1 }}>{t.message}</span>
+            </div>
+          </div>
+        )
+      })}
+    </div>
+  )
+}

package/app/components/TopBar.tsx

@@ -1,6 +1,7 @@
 'use client'
 
 import { useEffect, useRef, useState } from 'react'
+import { CORE_URL_PUBLIC } from '../../lib/proxy-client'
 
 interface Project {
   name: string
@@ -189,10 +190,36 @@ export function TopBar({ project, onProjectChange, onNodeSelect, onRelayout, onT
       </div>
 
       <div className="top-actions">
+        {/* ADR-058 #5 — daemon URL visible. */}
+        <span className="daemon-url" title="NEAT daemon URL">{CORE_URL_PUBLIC}</span>
         <button className="top-btn" aria-label={isLive ? 'Core connected' : 'Core offline'}>
           <span className={`dot${isLive ? ' live' : ''}`} />
           {isLive ? 'Live' : 'Offline'}
         </button>
+        {/* ADR-056 — History deferred; explicitly disabled with affordance. */}
+        <button className="top-btn" disabled title="History — coming in v0.3.x" aria-label="History (coming soon)" style={{ opacity: 0.4, cursor: 'not-allowed' }}>
+          <svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="1.5">
+            <circle cx="12" cy="12" r="9" /><path d="M12 7v5l3 2" />
+          </svg>
+          History
+        </button>
+        {/* ADR-056 — Share wired: copies the deep-link URL to clipboard. */}
+        <button
+          className="top-btn"
+          title="Copy current view URL"
+          aria-label="Share — copy URL"
+          onClick={() => {
+            if (typeof navigator !== 'undefined' && navigator.clipboard) {
+              void navigator.clipboard.writeText(window.location.href)
+            }
+          }}
+        >
+          <svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="1.5">
+            <circle cx="6" cy="12" r="2.5" /><circle cx="18" cy="6" r="2.5" /><circle cx="18" cy="18" r="2.5" />
+            <path d="m8 11 8-4M8 13l8 4" />
+          </svg>
+          Share
+        </button>
         <button className="top-btn" title="Re-run cose layout" onClick={onRelayout}>
           <svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="1.5">
             <path d="M12 8v4l3 2" /><circle cx="12" cy="12" r="9" />

package/app/incidents/IncidentsClient.tsx

@@ -0,0 +1,150 @@
+'use client'
+
+import { useEffect, useState } from 'react'
+import Link from 'next/link'
+
+interface Incident {
+  nodeId: string
+  timestamp: string
+  type: string
+  message: string
+  stacktrace?: string
+}
+
+interface IncidentsResponse {
+  count: number
+  total: number
+  events: Incident[]
+}
+
+function formatTs(iso: string): string {
+  try {
+    const d = new Date(iso)
+    return d.toLocaleDateString() + ' ' + d.toTimeString().slice(0, 8)
+  } catch {
+    return iso
+  }
+}
+
+export function IncidentsClient() {
+  const [data, setData] = useState<IncidentsResponse | null>(null)
+  const [loading, setLoading] = useState(true)
+  const [error, setError] = useState<string | null>(null)
+  const [openRow, setOpenRow] = useState<string | null>(null)
+
+  // ADR-057 #2 — read project from URL (deep-linkable) or localStorage,
+  // matching AppShell's resolution chain. The lazy initializer reads
+  // window.* synchronously; safe because the page mounts client-only via
+  // dynamic({ ssr: false }) per ADR-062 §4 (2026-05-11 amendment). The
+  // typeof window guard stays as belt-and-suspenders — if someone later
+  // removes the dynamic wrapper, this degrades to a flicker, not a crash.
+  const [project] = useState<string>(() => {
+    if (typeof window === 'undefined') return 'default'
+    const fromUrl = new URLSearchParams(window.location.search).get('project')
+    if (fromUrl) return fromUrl
+    try {
+      const stored = window.localStorage.getItem('neat:lastProject')
+      if (stored) return stored
+    } catch { /* noop */ }
+    return 'default'
+  })
+
+  // ADR-057 #3 — re-fetch when project changes.
+  useEffect(() => {
+    setLoading(true)
+    fetch(`/api/incidents?limit=100&project=${encodeURIComponent(project)}`)
+      .then((r) => r.json())
+      .then((d: IncidentsResponse) => {
+        setData(d)
+        setLoading(false)
+      })
+      .catch((e: Error) => {
+        setError(e.message)
+        setLoading(false)
+      })
+  }, [project])
+
+  return (
+    <div style={{ background: 'var(--ink-0)', minHeight: '100vh' }}>
+      <header className="topbar">
+        <div className="brand" title="NEAT">N</div>
+        <div className="crumbs">
+          <Link href="/" className="incidents-nav-link">graph view</Link>
+          <span className="sep">/</span>
+          <span className="here">incidents</span>
+        </div>
+      </header>
+
+      <div className="incidents-page" style={{ marginTop: 44 }}>
+        <h1>Incidents</h1>
+        <div className="subtitle">
+          {data ? `${data.total} total events — showing ${data.events.length}` : 'loading…'}
+        </div>
+
+        {loading && (
+          <div className="incidents-empty">loading…</div>
+        )}
+
+        {error && (
+          <div className="incidents-empty" style={{ color: '#e87a7a' }}>
+            failed to load: {error}
+          </div>
+        )}
+
+        {!loading && !error && data && data.events.length === 0 && (
+          <div className="incidents-empty">no incidents recorded</div>
+        )}
+
+        {!loading && !error && data && data.events.length > 0 && (
+          <table className="incidents-table">
+            <thead>
+              <tr>
+                <th>Node</th>
+                <th>Time</th>
+                <th>Type</th>
+                <th>Message</th>
+              </tr>
+            </thead>
+            <tbody>
+              {data.events.map((evt, i) => {
+                const rowKey = `${i}-${evt.nodeId}`
+                const isOpen = openRow === rowKey
+                return (
+                  <>
+                    <tr
+                      key={rowKey}
+                      style={{ cursor: evt.stacktrace ? 'pointer' : undefined }}
+                      onClick={() => evt.stacktrace && setOpenRow(isOpen ? null : rowKey)}
+                      title={evt.stacktrace ? (isOpen ? 'Collapse stacktrace' : 'Expand stacktrace') : undefined}
+                    >
+                      <td className="td-node">
+                        <Link href={`/?node=${encodeURIComponent(evt.nodeId)}&project=${encodeURIComponent(project)}`} className="incidents-node-link">
+                          {evt.nodeId}
+                        </Link>
+                      </td>
+                      <td className="td-time">{formatTs(evt.timestamp)}</td>
+                      <td className="td-type">{evt.type}</td>
+                      <td className="td-msg">
+                        {evt.message}
+                        {evt.stacktrace && (
+                          <span className="stack-toggle">{isOpen ? ' ▲' : ' ▼'}</span>
+                        )}
+                      </td>
+                    </tr>
+                    {isOpen && evt.stacktrace && (
+                      <tr key={`${rowKey}-stack`}>
+                        <td colSpan={4} className="td-stacktrace">
+                          <pre className="stacktrace-pre">{evt.stacktrace}</pre>
+                        </td>
+                      </tr>
+                    )}
+                  </>
+                )
+              })}
+            </tbody>
+          </table>
+        )}
+      </div>
+    </div>
+  )
+}

package/app/incidents/page.tsx

@@ -1,145 +1,16 @@
-'use client'
-
-import { useEffect, useState } from 'react'
-import Link from 'next/link'
-
-interface Incident {
-  nodeId: string
-  timestamp: string
-  type: string
-  message: string
-  stacktrace?: string
-}
-
-interface IncidentsResponse {
-  count: number
-  total: number
-  events: Incident[]
-}
-
-function formatTs(iso: string): string {
-  try {
-    const d = new Date(iso)
-    return d.toLocaleDateString() + ' ' + d.toTimeString().slice(0, 8)
-  } catch {
-    return iso
-  }
-}
-
-export default function IncidentsPage() {
-  const [data, setData] = useState<IncidentsResponse | null>(null)
-  const [loading, setLoading] = useState(true)
-  const [error, setError] = useState<string | null>(null)
-  const [openRow, setOpenRow] = useState<string | null>(null)
-
-  // ADR-057 #2 — page reads project from URL (deep-linkable) or localStorage,
-  // matching AppShell's resolution chain so the incidents view stays in sync
-  // with whichever project the operator last selected on the graph view.
-  const [project, setProject] = useState<string>('default')
-  useEffect(() => {
-    if (typeof window === 'undefined') return
-    const fromUrl = new URLSearchParams(window.location.search).get('project')
-    let stored: string | null = null
-    try { stored = window.localStorage.getItem('neat:lastProject') } catch { /* noop */ }
-    setProject(fromUrl || stored || 'default')
-  }, [])
-
-  // ADR-057 #3 — re-fetch when project changes.
-  useEffect(() => {
-    setLoading(true)
-    fetch(`/api/incidents?limit=100&project=${encodeURIComponent(project)}`)
-      .then((r) => r.json())
-      .then((d: IncidentsResponse) => {
-        setData(d)
-        setLoading(false)
-      })
-      .catch((e: Error) => {
-        setError(e.message)
-        setLoading(false)
-      })
-  }, [project])
-
-  return (
-    <div style={{ background: 'var(--ink-0)', minHeight: '100vh' }}>
-      <header className="topbar">
-        <div className="brand" title="NEAT">N</div>
-        <div className="crumbs">
-          <Link href="/" className="incidents-nav-link">graph view</Link>
-          <span className="sep">/</span>
-          <span className="here">incidents</span>
-        </div>
-      </header>
-
-      <div className="incidents-page" style={{ marginTop: 44 }}>
-        <h1>Incidents</h1>
-        <div className="subtitle">
-          {data ? `${data.total} total events — showing ${data.events.length}` : 'loading…'}
-        </div>
-
-        {loading && (
-          <div className="incidents-empty">loading…</div>
-        )}
-
-        {error && (
-          <div className="incidents-empty" style={{ color: '#e87a7a' }}>
-            failed to load: {error}
-          </div>
-        )}
-
-        {!loading && !error && data && data.events.length === 0 && (
-          <div className="incidents-empty">no incidents recorded</div>
-        )}
-
-        {!loading && !error && data && data.events.length > 0 && (
-          <table className="incidents-table">
-            <thead>
-              <tr>
-                <th>Node</th>
-                <th>Time</th>
-                <th>Type</th>
-                <th>Message</th>
-              </tr>
-            </thead>
-            <tbody>
-              {data.events.map((evt, i) => {
-                const rowKey = `${i}-${evt.nodeId}`
-                const isOpen = openRow === rowKey
-                return (
-                  <>
-                    <tr
-                      key={rowKey}
-                      style={{ cursor: evt.stacktrace ? 'pointer' : undefined }}
-                      onClick={() => evt.stacktrace && setOpenRow(isOpen ? null : rowKey)}
-                      title={evt.stacktrace ? (isOpen ? 'Collapse stacktrace' : 'Expand stacktrace') : undefined}
-                    >
-                      <td className="td-node">
-                        <Link href={`/?node=${encodeURIComponent(evt.nodeId)}&project=${encodeURIComponent(project)}`} className="incidents-node-link">
-                          {evt.nodeId}
-                        </Link>
-                      </td>
-                      <td className="td-time">{formatTs(evt.timestamp)}</td>
-                      <td className="td-type">{evt.type}</td>
-                      <td className="td-msg">
-                        {evt.message}
-                        {evt.stacktrace && (
-                          <span className="stack-toggle">{isOpen ? ' ▲' : ' ▼'}</span>
-                        )}
-                      </td>
-                    </tr>
-                    {isOpen && evt.stacktrace && (
-                      <tr key={`${rowKey}-stack`}>
-                        <td colSpan={4} className="td-stacktrace">
-                          <pre className="stacktrace-pre">{evt.stacktrace}</pre>
-                        </td>
-                      </tr>
-                    )}
-                  </>
-                )
-              })}
-            </tbody>
-          </table>
-        )}
-      </div>
-    </div>
-  )
+import dynamic from 'next/dynamic'
+
+// ADR-062 §4 (2026-05-11 amendment) — /incidents renders client-only.
+// Same shape as app/page.tsx: the IncidentsClient subtree reads the URL
+// and localStorage synchronously inside its useState lazy initializer,
+// which would diverge from the SSR pass; removing the SSR pass keeps the
+// resolution chain honest and avoids the double-fetch the deferred shape
+// produced on every page load.
+const IncidentsClient = dynamic(
+  () => import('./IncidentsClient').then((m) => m.IncidentsClient),
+  { ssr: false },
+)
+
+export default function IncidentsPage(): JSX.Element {
+  return <IncidentsClient />
 }

package/app/page.tsx

@@ -1,4 +1,12 @@
-import { AppShell } from './components/AppShell'
+import dynamic from 'next/dynamic'
+
+// ADR-062 — AppShell renders client-only. The Next.js server emits the
+// static HTML shell (head, fonts, CSS); the React tree builds on mount.
+// Removing { ssr: false } reintroduces the hydration bug ADR-062 closed.
+const AppShell = dynamic(
+  () => import('./components/AppShell').then((m) => m.AppShell),
+  { ssr: false },
+)
 
 export default function Home(): JSX.Element {
   return <AppShell />

package/lib/proxy-client.ts

@@ -0,0 +1,118 @@
+'use client'
+
+// Public-facing daemon URL string. Browsers don't get NEAT_API_URL directly —
+// the Next.js server routes proxy at /api/* — but the operator wants to see
+// which daemon is on the other end (ADR-058 #5). This is the human-readable
+// label, not a fetched URL.
+export const CORE_URL_PUBLIC: string =
+  (typeof process !== 'undefined' && process.env?.NEXT_PUBLIC_NEAT_API_URL) ||
+  'localhost:8080'
+
+// Tiny pub-sub for transient surfaces (toasts, debug-panel call log).
+type Subscriber<T> = (value: T) => void
+
+class Channel<T> {
+  private subs = new Set<Subscriber<T>>()
+  subscribe(fn: Subscriber<T>): () => void {
+    this.subs.add(fn)
+    return () => {
+      this.subs.delete(fn)
+    }
+  }
+  emit(value: T): void {
+    this.subs.forEach((fn) => {
+      try {
+        fn(value)
+      } catch {
+        /* never let a subscriber kill the bus */
+      }
+    })
+  }
+}
+
+export interface ToastEvent {
+  id: number
+  level: 'error' | 'warn' | 'info'
+  message: string
+  status?: number
+  timestamp: number
+}
+
+export interface ApiCallEvent {
+  path: string
+  status: number
+  durationMs: number
+  timestamp: number
+}
+
+export interface SseEvent {
+  type: string
+  timestamp: number
+}
+
+export interface ConnectionEvent {
+  state: 'ok' | 'slow' | 'down'
+  rttMs?: number
+  timestamp: number
+}
+
+export const toastBus = new Channel<ToastEvent>()
+export const apiCallBus = new Channel<ApiCallEvent>()
+export const sseEventBus = new Channel<SseEvent>()
+export const connectionBus = new Channel<ConnectionEvent>()
+
+let toastIdCounter = 0
+function nextId(): number {
+  toastIdCounter += 1
+  return toastIdCounter
+}
+
+// ADR-058 #3 — every non-2xx fetch surfaces a toast carrying the error
+// envelope from ADR-040 (`{ error, status, details? }`). Wrap raw `fetch`
+// instead of editing every call-site so the rule is centralized.
+export async function trackedFetch(input: string, init?: RequestInit): Promise<Response> {
+  const start = performance.now()
+  let status = 0
+  try {
+    const res = await fetch(input, init)
+    status = res.status
+    if (!res.ok) {
+      let message = `${input} → ${res.status}`
+      try {
+        const cloned = res.clone()
+        const ct = cloned.headers.get('content-type') ?? ''
+        if (ct.includes('application/json')) {
+          const body = (await cloned.json()) as { error?: string; details?: string }
+          if (body?.error) {
+            message = body.error + (body.details ? ` — ${body.details}` : '')
+          }
+        }
+      } catch {
+        /* fall back to the default message */
+      }
+      toastBus.emit({
+        id: nextId(),
+        level: res.status >= 500 ? 'error' : 'warn',
+        message,
+        status: res.status,
+        timestamp: Date.now(),
+      })
+    }
+    return res
+  } catch (err) {
+    toastBus.emit({
+      id: nextId(),
+      level: 'error',
+      message: `${input} — ${(err as Error).message}`,
+      timestamp: Date.now(),
+    })
+    throw err
+  } finally {
+    apiCallBus.emit({
+      path: input,
+      status,
+      durationMs: Math.round(performance.now() - start),
+      timestamp: Date.now(),
+    })
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neat.is/web",
-  "version": "0.2.10",
+  "version": "0.3.1",
   "description": "NEAT web shell — minimal Next.js app fronting the core API",
   "license": "BUSL-1.1",
   "homepage": "https://neat.is",
@@ -34,17 +34,22 @@
     "clean": "rm -rf .next .turbo"
   },
   "dependencies": {
-    "@neat.is/types": "^0.2.10",
+    "@neat.is/types": "^0.3.1",
     "cytoscape": "^3.33.3",
     "next": "14.2.35",
     "react": "^18",
     "react-dom": "^18"
   },
   "devDependencies": {
+    "@testing-library/jest-dom": "^6.6.0",
+    "@testing-library/react": "^16.1.0",
+    "@testing-library/user-event": "^14.5.2",
     "@types/cytoscape": "^3.21.9",
     "@types/node": "^20",
     "@types/react": "^18",
     "@types/react-dom": "^18",
+    "@vitejs/plugin-react": "^4.3.4",
+    "jsdom": "^25.0.1",
     "postcss": "^8",
     "tailwindcss": "^3.4.1",
     "typescript": "^5",