@statorjs/stator 2.6.0 → 2.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@statorjs/stator",
-  "version": "2.6.0",
+  "version": "2.7.0",
   "description": "Server-canonical web framework: business logic in composable state machines, UI as a thin renderer binding machine outputs to DOM positions. Ships TypeScript source, loaded natively by its own toolchain — no build step.",
   "license": "MIT",
   "type": "module",
@@ -95,7 +95,7 @@
     "pino-pretty": "^13.1.3",
     "vite": "^6.0.0",
     "vitest": "^2.1.0",
-    "@statorjs/stator": "2.6.0"
+    "@statorjs/stator": "2.7.0"
   },
   "scripts": {
     "typecheck": "tsc --noEmit",

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) => {

package/src/engine/describe.ts

@@ -0,0 +1,129 @@
+/**
+ * describeMachine — a machine def serialized to plain data.
+ *
+ * The def already IS the statechart: states, per-state `on` maps, guards,
+ * effects, emits, selectors and `serverOnly` are all present at runtime (only
+ * the event-union *type* is erased). This walks that structure into a
+ * JSON-able description — the SHAPE half of introspection. Consumers: the dev
+ * inspector's machine view; later the manifest, `stator check`, and viz.
+ *
+ * Closures stay opaque by design: a guard/action/effect reports presence,
+ * never its body. The walk normalizes the three authored transition forms
+ * (bare action fn, config object, ordered candidate array) exactly as
+ * `actor.send` does.
+ */
+
+import type {
+  AnyMachineDef,
+  EventObject,
+  Lifecycle,
+  OnMap,
+  StateNode,
+  Transition,
+  TransitionConfig,
+} from './types.ts'
+
+export interface TransitionDescription {
+  /** Target state; absent = self-transition (action only, no state change). */
+  to?: string
+  guarded: boolean
+  action: boolean
+  emits: string[]
+  effect: boolean
+}
+
+export interface StateDescription {
+  /** Event type → ordered guarded candidates (first whose guard passes wins). */
+  on: Record<string, TransitionDescription[]>
+  entry: boolean
+  after: Array<{ delay: number | 'dynamic'; send: string }>
+}
+
+export interface MachineDescription {
+  name: string
+  lifecycle: Lifecycle
+  persist: boolean
+  initial: string
+  states: Record<string, StateDescription>
+  /** Machine-level fallback handlers (consulted when the state declares none). */
+  on: Record<string, TransitionDescription[]>
+  /** Every event type the chart handles somewhere (state ∪ machine level), sorted. */
+  events: string[]
+  serverOnly: string[]
+  emits: string[]
+  selectors: string[]
+  reads: string[]
+  subscribes: Array<{ from: string; event: string; dispatch: string }>
+  /** The def's initial context (the shape a fresh instance starts from). */
+  context: unknown
+}
+
+type AnyTransition = Transition<unknown, EventObject, string>
+type AnyOnMap = OnMap<unknown, EventObject, string>
+
+function describeTransitions(value: AnyTransition | AnyTransition[]): TransitionDescription[] {
+  const candidates = Array.isArray(value) ? value : [value]
+  return candidates.map((entry) => {
+    // A bare function is sugar for `{ do: fn }` — same normalization as actor.send.
+    const config: TransitionConfig<unknown, EventObject, string> =
+      typeof entry === 'function' ? { do: entry } : entry
+    const emits =
+      config.emit === undefined ? [] : Array.isArray(config.emit) ? [...config.emit] : [config.emit]
+    return {
+      ...(config.to !== undefined ? { to: config.to } : {}),
+      guarded: config.when !== undefined,
+      action: config.do !== undefined,
+      emits,
+      effect: config.effect !== undefined,
+    }
+  })
+}
+
+function describeOn(on: AnyOnMap | undefined): Record<string, TransitionDescription[]> {
+  const out: Record<string, TransitionDescription[]> = {}
+  for (const [type, value] of Object.entries(on ?? {})) {
+    if (value !== undefined) out[type] = describeTransitions(value as AnyTransition)
+  }
+  return out
+}
+
+/** Serialize a def to plain JSON-able data. Pure; never invokes app code. */
+export function describeMachine(def: AnyMachineDef): MachineDescription {
+  const states: Record<string, StateDescription> = {}
+  for (const [name, node] of Object.entries(
+    def.states as Record<string, StateNode<unknown, EventObject, string>>,
+  )) {
+    states[name] = {
+      on: describeOn(node.on),
+      entry: node.entry !== undefined,
+      after: (node.after ?? []).map((a) => ({
+        delay: typeof a.delay === 'number' ? a.delay : 'dynamic',
+        send: a.send.type,
+      })),
+    }
+  }
+  const on = describeOn(def.on)
+  const events = new Set<string>(Object.keys(on))
+  for (const state of Object.values(states)) {
+    for (const type of Object.keys(state.on)) events.add(type)
+  }
+  return {
+    name: def.name,
+    lifecycle: def.lifecycle,
+    persist: def.persist,
+    initial: def.initial,
+    states,
+    on,
+    events: [...events].sort(),
+    serverOnly: [...def.serverOnly],
+    emits: Object.keys(def.emits),
+    selectors: Object.keys(def.selectors),
+    reads: def.reads.map((d) => d.name),
+    subscribes: def.subscribes.map((s) => ({
+      from: s.from.name,
+      event: s.event,
+      dispatch: typeof s.dispatch === 'string' ? s.dispatch : s.dispatch.type,
+    })),
+    context: def.context,
+  }
+}

package/src/engine/index.ts

@@ -10,6 +10,12 @@ export type { Actor, AnyActor, CreateActorOptions } from './actor.ts'
 export { createActor } from './actor.ts'
 export type { DefineMachineConfig } from './define-machine.ts'
 export { defineMachine } from './define-machine.ts'
+export type {
+  MachineDescription,
+  StateDescription,
+  TransitionDescription,
+} from './describe.ts'
+export { describeMachine } from './describe.ts'
 export type {
   Action,
   ActionHelpers,

package/src/server/dev-native.ts

@@ -382,6 +382,7 @@ export async function createNativeDevApp(config: DevAppConfig): Promise<NativeDe
       staticDir,
       headExtras,
       inspector: inspectorOn,
+      inspect: true,
       trustedOrigins: resolved.trustedOrigins,
       sameSite: resolved.sameSite,
       origin: resolved.origin,

package/src/server/dev-vite.ts

@@ -203,6 +203,7 @@ export async function createViteDevApp(config: DevAppConfig): Promise<DevApp> {
       staticDir: config.staticDir,
       headExtras,
       inspector: inspectorOn,
+      inspect: true,
       trustedOrigins: resolved.trustedOrigins,
       sameSite: resolved.sameSite,
       origin: resolved.origin,

package/src/server/http.ts

@@ -9,6 +9,7 @@ import { applyRenderedEffects, runApiRoute } from './api-route.ts'
 import { crossSiteGuard } from './csrf.ts'
 import { scheduleSessionEffects } from './effects.ts'
 import { record, replayFor } from './event-dedupe.ts'
+import { buildInspectPayload } from './inspect.ts'
 import { scopedLogger } from './logger.ts'
 import type { MachineStore } from './machine-store.ts'
 import type { MiddlewareDefinition } from './middleware.ts'
@@ -36,6 +37,11 @@ export interface HttpConfig {
   /** Serve the dev inspector asset at `/@stator/inspector.js`. The dev server
    *  sets this and injects the script tag; production leaves it off. */
   inspector?: boolean
+  /** Serve the state-inspection endpoint at `/@stator/inspect` — the caller's
+   *  own session's machine snapshots plus the machine/route catalog. Only the
+   *  dev servers set this; production never does (machine context is working
+   *  state and may hold anything), even when it opts into the wire toolbar. */
+  inspect?: boolean
   /** SSE heartbeat interval in ms (default 25s). Tests shorten it. */
   ssePingMs?: number
   /** Origins allowed to make cross-site writes despite the guard (exact or
@@ -246,6 +252,22 @@ export async function buildHonoApp(config: HttpConfig): Promise<Hono> {
     })
   }
 
+  // Dev state inspection — cookie-scoped to the caller's own session (the
+  // request bridge above established it). See server/inspect.ts for the
+  // privacy stance; the flag is dev-server-only by construction.
+  if (config.inspect) {
+    app.get('/@stator/inspect', async (c) => {
+      const payload = await buildInspectPayload({
+        store: config.store,
+        routes: config.routes,
+        sessionId: getSessionState(c)?.sid,
+        buildId: config.buildId,
+      })
+      c.header('Cache-Control', 'no-cache')
+      return c.json(payload)
+    })
+  }
+
   if (config.staticDir) {
     const staticDir = resolve(config.staticDir)
     app.get('/static/*', async (c) => {

package/src/server/index.ts

@@ -52,6 +52,8 @@ export {
 export { scheduleSessionEffects, wireAppEffects } from './effects.ts'
 export type { HttpConfig } from './http.ts'
 export { buildHonoApp } from './http.ts'
+export type { InspectPayload, InspectRoute, InspectRouteMethod } from './inspect.ts'
+export { buildInspectPayload } from './inspect.ts'
 export type { InstanceHandle } from './instance-proxy.ts'
 export { createInstanceProxy, defForProxy } from './instance-proxy.ts'
 export { logger, scopedLogger, setLogLevel } from './logger.ts'

package/src/server/inspect.ts

@@ -0,0 +1,101 @@
+/**
+ * Dev state inspection — the data feed for the inspector's Machines view.
+ *
+ * Serves the caller's OWN session: the payload is scoped to the session the
+ * request's cookie addresses (app-lifecycle machines are process-global and
+ * labeled as such by their lifecycle). Registered only by the dev servers —
+ * machine context is working state and may hold anything, so this endpoint
+ * never exists in production.
+ *
+ * Read-only by construction: no actors are instantiated, no session lock is
+ * taken, nothing is dispatched. Session snapshots come straight from the
+ * persistence store — a machine never touched by this session reads as null
+ * (it would start from the def's initial context on first dispatch).
+ */
+
+import { describeMachine, type MachineDescription } from '../engine/describe.ts'
+import type { Snapshot } from '../engine/types.ts'
+import { codeHashOf } from './machine-hash.ts'
+import type { MachineStore } from './machine-store.ts'
+import { type DiscoveredRoute, HTTP_METHODS } from './route-discovery.ts'
+import { isStatorQueryRoute, isStatorRoute } from './routing.ts'
+
+export interface InspectRouteMethod {
+  /** `page` = defineRoute, `data` = defineApiRoute({method:'GET'}), `api` = the rest. */
+  kind: 'page' | 'data' | 'api'
+  reads: string[]
+  /** Page routes only: whether the route opened an SSE live channel. */
+  live?: boolean
+}
+
+export interface InspectRoute {
+  urlPath: string
+  methods: Record<string, InspectRouteMethod>
+}
+
+export interface InspectPayload {
+  buildId?: string
+  /** All registered machines, described + their running code hash. */
+  machines: Array<MachineDescription & { hash?: string }>
+  /** The caller's session's persisted snapshots (null = never touched). */
+  session: Record<string, Snapshot<unknown> | null>
+  /** App-lifecycle live snapshots — process-global, same for every caller. */
+  app: Record<string, Snapshot<unknown>>
+  routes: InspectRoute[]
+}
+
+export async function buildInspectPayload(opts: {
+  store: MachineStore
+  routes: DiscoveredRoute[]
+  sessionId?: string
+  buildId?: string
+}): Promise<InspectPayload> {
+  const defs = [...opts.store.allDefs()].sort((a, b) => a.name.localeCompare(b.name))
+
+  const machines = defs.map((def) => {
+    const hash = codeHashOf(def)
+    return { ...describeMachine(def), ...(hash !== undefined ? { hash } : {}) }
+  })
+
+  const session: Record<string, Snapshot<unknown> | null> = {}
+  if (opts.sessionId !== undefined) {
+    for (const def of defs) {
+      if (def.lifecycle !== 'session') continue
+      session[def.name] =
+        ((await opts.store.persistence.get(
+          opts.sessionId,
+          def.name,
+        )) as Snapshot<unknown> | null) ?? null
+    }
+  }
+
+  const app: Record<string, Snapshot<unknown>> = {}
+  for (const def of defs) {
+    if (def.lifecycle !== 'app') continue
+    const handle = opts.store.appInstance(def.name)
+    if (handle) app[def.name] = handle.actor.getSnapshot()
+  }
+
+  const routes = opts.routes.map((route): InspectRoute => {
+    const methods: Record<string, InspectRouteMethod> = {}
+    for (const method of HTTP_METHODS) {
+      const def = route[method]
+      if (!def) continue
+      const reads = def.reads.map((d) => d.name)
+      if (isStatorRoute(def)) {
+        methods[method] = { kind: 'page', reads, live: def.live }
+      } else {
+        methods[method] = { kind: isStatorQueryRoute(def) ? 'data' : 'api', reads }
+      }
+    }
+    return { urlPath: route.urlPath, methods }
+  })
+
+  return {
+    ...(opts.buildId !== undefined ? { buildId: opts.buildId } : {}),
+    machines,
+    session,
+    app,
+    routes,
+  }
+}