@statorjs/stator 2.5.1 → 2.7.0

package/src/cli/commands/dev.ts

@@ -3,9 +3,13 @@ import { createDevApp } from '../../server/dev.ts'
 import { loadConfig, resolvePort } from '../config.ts'
 import type { CliContext } from '../run.ts'
 
-/** Run the dev server (Vite-backed today: live reload, compile-error overlay,
- *  inspector). Conventions for machines/routes/static; `stator.config.ts` for
- *  the store/session/port an app previously hand-wrote a `server.ts` for. */
+/** Run the dev server. Live reload, inspector, conventions for machines/routes/
+ *  static; `stator.config.ts` for the store/session/port an app previously
+ *  hand-wrote a `server.ts` for.
+ *
+ *  The app runs natively from its source tree, exactly as `stator start` runs a
+ *  build. `STATOR_VITE_DEV=1` keeps the previous Vite-embedded dev server for
+ *  one minor as an escape hatch. */
 export async function run(ctx: CliContext): Promise<void> {
   const config = await loadConfig(ctx.root)
   const app = await createDevApp({

package/src/cli/commands/start.ts

@@ -16,7 +16,7 @@ export async function run(ctx: CliContext): Promise<void> {
   }
 
   const config = await loadConfig(ctx.root)
-  const { headExtras, buildId } = await loadProductionHead(dist)
+  const { headExtras, buildId, machines } = await loadProductionHead(dist)
   const app = await createApp({
     machinesDir: resolve(dist, 'machines'),
     routesDir: resolve(dist, 'routes'),
@@ -31,6 +31,7 @@ export async function run(ctx: CliContext): Promise<void> {
     cors: config.cors,
     headExtras,
     buildId,
+    machineHashes: machines,
     middlewareFile: resolve(dist, 'middleware.ts'),
     bootFile: resolve(dist, 'boot.ts'),
   })

package/src/cli/run.ts

@@ -65,7 +65,7 @@ const ctx: CliContext = {
 const { loadDotenv } = await import('../server/env.ts')
 loadDotenv(ctx.root)
 
-// Dynamic import per command so `check` never loads the dev server's Vite, etc.
+// Dynamic import per command so `check` never loads the dev server's watcher, etc.
 const { run } = (await import(`./commands/${command}.ts`)) as {
   run: (ctx: CliContext) => Promise<void>
 }

package/src/cli/stator.js

@@ -23,5 +23,14 @@ if (typeof register !== 'function') {
 
 register('./loader.js', import.meta.url)
 
+// Apply sourcemaps to stack traces. Every transform in the owned pipeline (the
+// TS loader above, the dev loader's `.stator` compile) already EMITS an inline
+// map, but V8 ignores maps when capturing stacks unless the process opts in —
+// this is the runtime equivalent of `--enable-source-maps`, which a bin script
+// can't put on its own invocation. Covers dev and `stator start` alike.
+// (`.stator` traces resolve to the compiled server module — right file,
+// generated lines — until the compiler emits its own map to compose.)
+process.setSourceMapsEnabled?.(true)
+
 // The real CLI is TypeScript, transformed on import by the loader just registered.
 await import('./run.ts')

package/src/client/inspector.css

@@ -189,6 +189,204 @@
   border-top: 1px dashed #2a2a2a;
 }
 
+.stator-inspector-tabs {
+  display: inline-flex;
+  gap: 0.25rem;
+}
+.stator-inspector-header button.stator-inspector-tab {
+  border-color: transparent;
+}
+.stator-inspector-header button.stator-inspector-tab--active {
+  border-color: #333;
+  background: #232323;
+  color: #f0f0f0;
+}
+/* Resize grip: the drawer's draggable top edge. */
+.stator-inspector-grip {
+  flex-shrink: 0;
+  height: 5px;
+  cursor: ns-resize;
+  touch-action: none;
+  background: transparent;
+}
+.stator-inspector-grip:hover,
+.stator-inspector-grip:active {
+  background: #333;
+}
+/* Machines tab: master-detail — nav of machines (live state inline), detail pane. */
+.stator-inspector-machines {
+  flex: 1;
+  min-height: 0;
+  display: flex;
+  align-items: stretch;
+}
+.stator-inspector-machines[hidden],
+.stator-inspector-body[hidden],
+.stator-inspector-legend[hidden],
+.stator-inspector-header button[hidden] {
+  display: none;
+}
+.stator-inspector-mnav {
+  flex: 0 0 230px;
+  min-width: 0;
+  overflow-y: auto;
+  border-right: 1px solid #1f1f1f;
+  padding-bottom: 0.4rem;
+}
+.stator-inspector-mnav-head {
+  padding: 0.45rem 0.9rem 0.2rem;
+  color: #6a6a6a;
+  text-transform: uppercase;
+  letter-spacing: 0.06em;
+  font-size: 0.68rem;
+}
+.stator-inspector-mnav-row {
+  display: flex;
+  justify-content: space-between;
+  align-items: baseline;
+  gap: 0.5rem;
+  width: 100%;
+  text-align: left;
+  background: transparent;
+  border: none;
+  color: #d0d0d0;
+  padding: 0.3rem 0.9rem;
+  font: inherit;
+  cursor: pointer;
+}
+.stator-inspector-mnav-row:hover {
+  background: #1c1c1c;
+}
+.stator-inspector-mnav-row--active {
+  background: #232323;
+  color: #f5f5f5;
+}
+.stator-inspector-mnav-name {
+  color: #c586c0;
+  font-weight: 500;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+.stator-inspector-mnav-state {
+  color: #4ec9b0;
+  white-space: nowrap;
+}
+.stator-inspector-mdetail {
+  flex: 1;
+  min-width: 0;
+  overflow-y: auto;
+  padding: 0.5rem 0.9rem 0.75rem;
+}
+.stator-inspector-detail-head {
+  display: flex;
+  align-items: baseline;
+  gap: 0.75rem;
+  padding-bottom: 0.4rem;
+}
+.stator-inspector-badge {
+  color: #6a6a6a;
+  border: 1px solid #2a2a2a;
+  border-radius: 4px;
+  padding: 0 0.35rem;
+  font-size: 0.7rem;
+}
+.stator-inspector-state {
+  color: #4ec9b0;
+  font-weight: 500;
+}
+.stator-inspector-dim {
+  color: #6a6a6a;
+  font-weight: 400;
+  font-style: italic;
+}
+.stator-inspector-stale {
+  color: #d16969;
+  border: 1px solid rgba(209, 105, 105, 0.4);
+  border-radius: 4px;
+  padding: 0 0.35rem;
+  font-size: 0.7rem;
+  margin-left: 0.3rem;
+}
+.stator-inspector-accepts {
+  color: #888;
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.3rem;
+  align-items: baseline;
+  padding-bottom: 0.45rem;
+}
+.stator-inspector-chip {
+  color: #dcdcaa;
+  border: 1px solid #2f2f2f;
+  border-radius: 4px;
+  padding: 0 0.3rem;
+  font-size: 0.72rem;
+  white-space: nowrap;
+}
+.stator-inspector-chip--server {
+  color: #6a6a6a;
+  border-style: dashed;
+}
+/* Cross-link chips: machine selectors (buttons) and route links (anchors). */
+button.stator-inspector-chip {
+  font: inherit;
+  font-size: 0.72rem;
+  background: transparent;
+  cursor: pointer;
+}
+a.stator-inspector-chip {
+  text-decoration: none;
+}
+.stator-inspector-chip--link {
+  color: #c586c0;
+}
+.stator-inspector-chip--link:hover {
+  background: #1c1c1c;
+  text-decoration: underline;
+}
+.stator-inspector-chip-guard {
+  color: #9cdcfe;
+  margin-left: 0.15rem;
+}
+.stator-inspector-context {
+  margin: 0;
+  padding: 0.4rem 0.6rem;
+  background: #0e0e0e;
+  color: #cfcfcf;
+  font-size: 0.74rem;
+  white-space: pre-wrap;
+  word-break: break-word;
+  border: 1px solid #1f1f1f;
+  border-radius: 4px;
+}
+.stator-inspector-context--initial {
+  color: #7a7a7a;
+}
+.stator-inspector-route {
+  display: grid;
+  grid-template-columns: minmax(120px, max-content) 1fr;
+  gap: 0.75rem;
+  padding: 0.25rem 0;
+  border-bottom: 1px solid #1a1a1a;
+}
+.stator-inspector-route:last-child {
+  border-bottom: none;
+}
+.stator-inspector-route-path {
+  color: #c586c0;
+}
+a.stator-inspector-route-path {
+  text-decoration: none;
+}
+a.stator-inspector-route-path:hover {
+  text-decoration: underline;
+}
+.stator-inspector-route-method {
+  color: #888;
+  font-size: 0.72rem;
+}
+
 @media (max-height: 600px) {
   .stator-inspector-drawer {
     max-height: 50vh;

package/src/client/inspector.ts

@@ -1,13 +1,25 @@
 /**
  * Stator dev inspector — a framework-owned, dev-only observability toolbar.
  *
- * Auto-injected by `createDevApp` (never in production). It subscribes to the
- * public `stator:*` CustomEvent contract the client runtime dispatches on
- * `window` and renders a bottom drawer with one row per outgoing event (↑) and
- * per incoming patch batch (↓), plus a brief flash on each patched element.
+ * Auto-injected by `createDevApp` (never in production). Two tabs in a
+ * height-adjustable drawer (drag the top edge; the size persists):
  *
- * It depends on nothing but that event contract — the same surface any external
- * devtool would use. Self-contained: it injects its own styles.
+ * - **Wire** subscribes to the public `stator:*` CustomEvent contract the
+ *   client runtime dispatches on `window` and renders one row per outgoing
+ *   event (↑) and per incoming patch batch (↓), plus a brief flash on each
+ *   patched element.
+ * - **Machines** fetches `/@stator/inspect` — the dev server's cookie-scoped
+ *   state endpoint — into a master-detail view: a nav listing every machine
+ *   with its live state (your session's machines first, then app-lifecycle
+ *   machines, which are process-global and labeled as such — their context is
+ *   whatever the app aggregates there), and a detail pane with the selected
+ *   machine's context and accepted events. The endpoint exists only on the
+ *   dev server, so on a production page that opted into the toolbar the tab
+ *   degrades to a notice.
+ *
+ * The wire tab depends on nothing but the public event contract — the same
+ * surface any external devtool would use. Self-contained: it injects its own
+ * styles.
  *
  * The widget is a `<stator-inspector>` custom element with a shadow root
  * (the Astro-dev-toolbar / vite-error-overlay pattern): the inspected app's
@@ -21,11 +33,60 @@ import inspectorCss from './inspector.css'
 import flashCss from './inspector-flash.css'
 
 const STORAGE_KEY = 'stator:inspector:open'
+const TAB_KEY = 'stator:inspector:tab'
+const HEIGHT_KEY = 'stator:inspector:height'
+const SELECTED_KEY = 'stator:inspector:machine'
+const ROUTES_SELECTION = '@routes' // storage sentinel; machine names are identifiers
 const MAX_ENTRIES = 40
 const FLASH_MS = 1200
+const REFRESH_DEBOUNCE_MS = 250
+const MIN_DRAWER_PX = 140
 
 const w = window as unknown as { __statorInspectorMounted?: boolean }
 
+/** Structural mirror of the server's InspectPayload — the toolbar depends on
+ *  the wire shape, not the server module. */
+interface TransitionDesc {
+  to?: string
+  guarded: boolean
+  action: boolean
+  emits: string[]
+  effect: boolean
+}
+interface StateDesc {
+  on: Record<string, TransitionDesc[]>
+  entry: boolean
+  after: Array<{ delay: number | 'dynamic'; send: string }>
+}
+interface MachineDesc {
+  name: string
+  lifecycle: 'app' | 'session'
+  persist: boolean
+  initial: string
+  states: Record<string, StateDesc>
+  on: Record<string, TransitionDesc[]>
+  events: string[]
+  serverOnly: string[]
+  selectors: string[]
+  reads: string[]
+  context: unknown
+  hash?: string
+}
+interface SnapshotDesc {
+  value: string[]
+  context: unknown
+  code?: string
+}
+interface InspectPayloadDesc {
+  machines: MachineDesc[]
+  session: Record<string, SnapshotDesc | null>
+  app: Record<string, SnapshotDesc>
+  routes: Array<{
+    urlPath: string
+    methods: Record<string, { kind: string; reads: string[]; live?: boolean }>
+  }>
+}
+
 function escapeHtml(s: unknown): string {
   if (s == null) return ''
   return String(s)
@@ -57,6 +118,116 @@ function formatEventParams(event: Record<string, unknown>): string {
   return keys.map((k) => `${k}=${JSON.stringify(rest[k])}`).join(' ')
 }
 
+const snapshotOf = (p: InspectPayloadDesc, m: MachineDesc): SnapshotDesc | null | undefined =>
+  m.lifecycle === 'session' ? p.session[m.name] : p.app[m.name]
+
+const leafOf = (m: MachineDesc, snap: SnapshotDesc | null | undefined): string =>
+  snap ? (snap.value[snap.value.length - 1] ?? m.initial) : m.initial
+
+/** Stale = a PERSISTED snapshot stamped by different machine code (absent
+ *  stamp included — a pre-policy snapshot also resets on hydration). Session
+ *  machines only: an app machine's snapshot is the live actor's, which never
+ *  carries the persist-time `code` stamp and can't be stale — it is, by
+ *  construction, running the current code. */
+const isStale = (m: MachineDesc, snap: SnapshotDesc | null | undefined): boolean =>
+  m.lifecycle === 'session' && Boolean(snap && m.hash && snap.code !== m.hash)
+
+/** Events the machine accepts in `leaf`: the state's own handlers plus the
+ *  machine-level fallbacks the state doesn't shadow — actor.send's lookup. */
+function acceptedEvents(
+  m: MachineDesc,
+  leaf: string,
+): Array<{ type: string; serverOnly: boolean; guarded: boolean }> {
+  const stateOn = m.states[leaf]?.on ?? {}
+  const merged: Record<string, TransitionDesc[]> = { ...m.on, ...stateOn }
+  return Object.keys(merged)
+    .sort()
+    .map((type) => ({
+      type,
+      serverOnly: m.serverOnly.includes(type),
+      guarded: (merged[type] ?? []).every((t) => t.guarded),
+    }))
+}
+
+const STALE_TITLE =
+  'the persisted snapshot was written by different machine code — this session resets on its next request'
+
+function navRow(m: MachineDesc, p: InspectPayloadDesc, active: boolean): string {
+  const snap = snapshotOf(p, m)
+  const leaf = leafOf(m, snap)
+  return `<button type="button" class="stator-inspector-mnav-row${active ? ' stator-inspector-mnav-row--active' : ''}" data-name="${escapeHtml(m.name)}">
+    <span class="stator-inspector-mnav-name">${escapeHtml(m.name)}</span>
+    <span class="stator-inspector-mnav-state">${escapeHtml(leaf)}${isStale(m, snap) ? `<span class="stator-inspector-stale" title="${STALE_TITLE}">!</span>` : ''}</span>
+  </button>`
+}
+
+/** A cross-link chip selecting a machine's detail — wired up after render. */
+const machineChip = (name: string): string =>
+  `<button type="button" class="stator-inspector-chip stator-inspector-chip--link" data-machine="${escapeHtml(name)}">${escapeHtml(name)}</button>`
+
+const isNavigable = (r: InspectPayloadDesc['routes'][number]): boolean =>
+  r.methods.GET !== undefined && !/[:*]/.test(r.urlPath)
+
+function machineDetail(
+  m: MachineDesc,
+  snap: SnapshotDesc | null | undefined,
+  payload: InspectPayloadDesc,
+): string {
+  const leaf = leafOf(m, snap)
+  const context = snap ? snap.context : m.context
+  const chips = acceptedEvents(m, leaf)
+    .map(
+      (e) =>
+        `<span class="stator-inspector-chip${e.serverOnly ? ' stator-inspector-chip--server' : ''}" title="${e.serverOnly ? 'server-only — clients may not dispatch this' : 'dispatchable'}${e.guarded ? '; guarded' : ''}">${escapeHtml(e.type)}${e.guarded ? '<span class="stator-inspector-chip-guard">?</span>' : ''}</span>`,
+    )
+    .join('')
+  // The graph glue: which machines this one reads, and which routes read it.
+  // Navigable routes render as real links (go look at the page showing this
+  // machine); parameterized ones stay text.
+  const reads = m.reads.map(machineChip).join('')
+  const readBy = payload.routes
+    .filter((r) => Object.values(r.methods).some((meth) => meth.reads.includes(m.name)))
+    .map((r) =>
+      isNavigable(r)
+        ? `<a class="stator-inspector-chip stator-inspector-chip--link" href="${escapeHtml(r.urlPath)}">${escapeHtml(r.urlPath)}</a>`
+        : `<span class="stator-inspector-chip">${escapeHtml(r.urlPath)}</span>`,
+    )
+    .join('')
+  return `<div class="stator-inspector-detail-head">
+      <span class="stator-inspector-machine">${escapeHtml(m.name)}</span>
+      <span class="stator-inspector-badge">${m.lifecycle}${m.persist ? ' · persist' : ''}</span>
+      <span class="stator-inspector-state">${escapeHtml(leaf)}${snap ? '' : ' <span class="stator-inspector-dim">(initial — not touched this session)</span>'}</span>
+      ${isStale(m, snap) ? `<span class="stator-inspector-stale" title="${STALE_TITLE}">stale</span>` : ''}
+    </div>
+    <div class="stator-inspector-accepts">accepts ${chips || '<span class="stator-inspector-dim">nothing in this state</span>'}</div>
+    ${reads ? `<div class="stator-inspector-accepts">reads ${reads}</div>` : ''}
+    <div class="stator-inspector-accepts">read by ${readBy || '<span class="stator-inspector-dim">no routes</span>'}</div>
+    <pre class="stator-inspector-context${snap ? '' : ' stator-inspector-context--initial'}">${escapeHtml(JSON.stringify(context, null, 2))}</pre>`
+}
+
+function routesDetail(payload: InspectPayloadDesc): string {
+  const rows = payload.routes
+    .map((r) => {
+      const methods = Object.entries(r.methods)
+        .map(([method, m]) => {
+          const reads = m.reads.length
+            ? m.reads.map(machineChip).join('')
+            : '<span class="stator-inspector-dim">no reads</span>'
+          return `<span class="stator-inspector-route-method">${escapeHtml(method)}·${escapeHtml(m.kind)}${m.live ? '·live' : ''}</span> ${reads}`
+        })
+        .join('<br>')
+      // A static GET route is navigable — render it as a real link (cmd-click
+      // works; the toolbar's persisted state survives the navigation). A
+      // parameterized path has no concrete URL to offer.
+      const path = isNavigable(r)
+        ? `<a class="stator-inspector-route-path" href="${escapeHtml(r.urlPath)}">${escapeHtml(r.urlPath)}</a>`
+        : `<span class="stator-inspector-route-path">${escapeHtml(r.urlPath)}</span>`
+      return `<div class="stator-inspector-route">${path}<span>${methods}</span></div>`
+    })
+    .join('')
+  return `<div class="stator-inspector-detail-head"><span class="stator-inspector-machine">Routes</span><span class="stator-inspector-badge">url → reads</span></div>${rows || '<p class="stator-inspector-empty">No routes discovered.</p>'}`
+}
+
 function mount(): void {
   // Flash styles decorate APP elements, so they can't live in the widget's
   // shadow — they're document-level, in `@layer stator-inspector` (see
@@ -80,25 +251,168 @@ function mount(): void {
       <span aria-hidden="true">{ }</span> Inspect
     </button>
     <section class="stator-inspector-drawer" aria-label="Stator inspector" hidden>
+      <div class="stator-inspector-grip" title="Drag to resize"></div>
       <header class="stator-inspector-header">
         <span class="stator-inspector-title"><span class="stator-inspector-dot" aria-hidden="true"></span> Stator inspector</span>
+        <nav class="stator-inspector-tabs" aria-label="Inspector tabs">
+          <button class="stator-inspector-tab" type="button" data-tab="wire">Wire</button>
+          <button class="stator-inspector-tab" type="button" data-tab="machines">Machines</button>
+        </nav>
         <span class="stator-inspector-legend">
           <span class="stator-inspector-key stator-inspector-key--up">↑ event</span>
           <span class="stator-inspector-key stator-inspector-key--down">↓ patches</span>
         </span>
         <button class="stator-inspector-clear" type="button" title="Clear log">clear</button>
+        <button class="stator-inspector-refresh" type="button" title="Refresh machine state" hidden>refresh</button>
         <button class="stator-inspector-close" type="button" aria-label="Close inspector">×</button>
       </header>
       <div class="stator-inspector-body">
         <p class="stator-inspector-empty">Interact with the page to see events and patches.</p>
       </div>
+      <div class="stator-inspector-machines" hidden>
+        <p class="stator-inspector-empty">Loading machine state…</p>
+      </div>
     </section>`
   document.body.appendChild(root)
 
   const q = (sel: string) => shadow.querySelector(sel) as HTMLElement
   const drawer = q('.stator-inspector-drawer')
   const body = q('.stator-inspector-body')
+  const machinesEl = q('.stator-inspector-machines')
   const toggle = q('.stator-inspector-toggle')
+  const legend = q('.stator-inspector-legend')
+  const clearBtn = q('.stator-inspector-clear')
+  const refreshBtn = q('.stator-inspector-refresh')
+  const grip = q('.stator-inspector-grip')
+
+  // ── Drawer resize: drag the top edge; height persists ────────────────────
+  const clampHeight = (h: number): number =>
+    Math.min(Math.max(h, MIN_DRAWER_PX), Math.round(window.innerHeight * 0.85))
+  const applyHeight = (h: number): void => {
+    drawer.style.height = `${clampHeight(h)}px`
+    drawer.style.maxHeight = 'none'
+  }
+  try {
+    const stored = Number.parseInt(localStorage.getItem(HEIGHT_KEY) ?? '', 10)
+    if (Number.isFinite(stored)) applyHeight(stored)
+  } catch {}
+  grip.addEventListener('pointerdown', (e: PointerEvent) => {
+    e.preventDefault()
+    grip.setPointerCapture(e.pointerId)
+    const move = (ev: PointerEvent) => applyHeight(window.innerHeight - ev.clientY)
+    const up = () => {
+      grip.removeEventListener('pointermove', move)
+      grip.removeEventListener('pointerup', up)
+      try {
+        localStorage.setItem(HEIGHT_KEY, String(Number.parseInt(drawer.style.height, 10)))
+      } catch {}
+    }
+    grip.addEventListener('pointermove', move)
+    grip.addEventListener('pointerup', up)
+  })
+
+  // ── Machines tab: fetch + master-detail render ───────────────────────────
+  let refreshTimer: number | undefined
+  let lastPayload: InspectPayloadDesc | undefined
+  let selected: string = ((): string => {
+    try {
+      return localStorage.getItem(SELECTED_KEY) ?? ''
+    } catch {
+      return ''
+    }
+  })()
+
+  const renderMachines = (payload: InspectPayloadDesc): void => {
+    lastPayload = payload
+    // Your session's machines first — they're what you came to see.
+    const session = payload.machines.filter((m) => m.lifecycle === 'session')
+    const appMachines = payload.machines.filter((m) => m.lifecycle === 'app')
+    // A stored selection may name a machine that no longer exists.
+    const names = new Set(payload.machines.map((m) => m.name))
+    if (selected !== ROUTES_SELECTION && !names.has(selected)) {
+      selected = session[0]?.name ?? appMachines[0]?.name ?? ROUTES_SELECTION
+    }
+    const section = (label: string, machines: MachineDesc[]): string =>
+      machines.length
+        ? `<div class="stator-inspector-mnav-head">${label}</div>${machines.map((m) => navRow(m, payload, selected === m.name)).join('')}`
+        : ''
+    const nav = `<nav class="stator-inspector-mnav">
+      ${section('your session', session)}
+      ${section('app · process-global', appMachines)}
+      <div class="stator-inspector-mnav-head">pages</div>
+      <button type="button" class="stator-inspector-mnav-row${selected === ROUTES_SELECTION ? ' stator-inspector-mnav-row--active' : ''}" data-routes>
+        <span class="stator-inspector-mnav-name">Routes</span>
+        <span class="stator-inspector-mnav-state">${payload.routes.length}</span>
+      </button>
+    </nav>`
+    const selectedMachine = payload.machines.find((m) => m.name === selected)
+    const detail =
+      selected === ROUTES_SELECTION || !selectedMachine
+        ? routesDetail(payload)
+        : machineDetail(selectedMachine, snapshotOf(payload, selectedMachine), payload)
+    // Re-render in place, keeping each pane's scroll position (live refreshes
+    // arrive on every patch batch — a jumping pane would be unusable).
+    const prevNav = machinesEl.querySelector('.stator-inspector-mnav')
+    const prevDetail = machinesEl.querySelector('.stator-inspector-mdetail')
+    const navScroll = prevNav?.scrollTop ?? 0
+    const detailScroll = prevDetail?.scrollTop ?? 0
+    machinesEl.innerHTML = `${nav}<div class="stator-inspector-mdetail">${detail}</div>`
+    const navEl = machinesEl.querySelector('.stator-inspector-mnav')
+    const detailEl = machinesEl.querySelector('.stator-inspector-mdetail')
+    if (navEl) navEl.scrollTop = navScroll
+    if (detailEl) detailEl.scrollTop = detailScroll
+    const select = (name: string): void => {
+      selected = name
+      try {
+        localStorage.setItem(SELECTED_KEY, selected)
+      } catch {}
+      if (lastPayload) renderMachines(lastPayload)
+    }
+    for (const row of Array.from(
+      machinesEl.querySelectorAll<HTMLButtonElement>('.stator-inspector-mnav-row'),
+    )) {
+      row.addEventListener('click', () =>
+        select('routes' in row.dataset ? ROUTES_SELECTION : (row.dataset.name ?? '')),
+      )
+    }
+    // Cross-link chips (route reads, a machine's own reads) select that machine.
+    for (const chip of Array.from(
+      machinesEl.querySelectorAll<HTMLButtonElement>('button[data-machine]'),
+    )) {
+      chip.addEventListener('click', () => select(chip.dataset.machine ?? ''))
+    }
+  }
+  const refreshMachines = (): void => {
+    fetch('/@stator/inspect', { headers: { Accept: 'application/json' } })
+      .then((res) => (res.ok ? res.json() : Promise.reject(new Error(String(res.status)))))
+      .then((payload: InspectPayloadDesc) => renderMachines(payload))
+      .catch(() => {
+        machinesEl.innerHTML =
+          '<p class="stator-inspector-empty">State inspection is served by the dev server only — this page has the wire toolbar without it.</p>'
+      })
+  }
+  const scheduleRefresh = (): void => {
+    if (drawer.hidden || machinesEl.hidden) return
+    window.clearTimeout(refreshTimer)
+    refreshTimer = window.setTimeout(refreshMachines, REFRESH_DEBOUNCE_MS)
+  }
+
+  // ── Tabs ─────────────────────────────────────────────────────────────────
+  const tabs = Array.from(shadow.querySelectorAll<HTMLButtonElement>('.stator-inspector-tab'))
+  const setTab = (tab: string) => {
+    try {
+      localStorage.setItem(TAB_KEY, tab)
+    } catch {}
+    const machines = tab === 'machines'
+    body.hidden = machines
+    machinesEl.hidden = !machines
+    legend.hidden = machines
+    clearBtn.hidden = machines
+    refreshBtn.hidden = !machines
+    for (const t of tabs) t.classList.toggle('stator-inspector-tab--active', t.dataset.tab === tab)
+    if (machines) refreshMachines()
+  }
+  for (const t of tabs) t.addEventListener('click', () => setTab(t.dataset.tab ?? 'wire'))
 
   const setOpen = (open: boolean) => {
     try {
@@ -106,16 +420,23 @@ function mount(): void {
     } catch {}
     ;(drawer as HTMLElement).hidden = !open
     ;(toggle as HTMLElement).hidden = open
+    if (open && !machinesEl.hidden) refreshMachines()
   }
   let initiallyOpen = true
   try {
     initiallyOpen = localStorage.getItem(STORAGE_KEY) !== 'false'
   } catch {}
+  let initialTab = 'wire'
+  try {
+    initialTab = localStorage.getItem(TAB_KEY) === 'machines' ? 'machines' : 'wire'
+  } catch {}
+  setTab(initialTab)
   setOpen(initiallyOpen)
 
   toggle.addEventListener('click', () => setOpen(true))
   q('.stator-inspector-close').addEventListener('click', () => setOpen(false))
-  q('.stator-inspector-clear').addEventListener('click', () => {
+  refreshBtn.addEventListener('click', refreshMachines)
+  clearBtn.addEventListener('click', () => {
     body.innerHTML = '<p class="stator-inspector-empty">Log cleared.</p>'
   })
 
@@ -185,6 +506,8 @@ function mount(): void {
       </div>`,
       (e as CustomEvent).detail,
     )
+    // Patches mean state moved — keep the Machines tab current while visible.
+    scheduleRefresh()
   })
 
   window.addEventListener('stator:patch-applied', (e: Event) => {