Visualizar e inspeccionar: la máquina como diagrama vivo

La lección anterior estableció que la máquina es un valor puro y serializable. Esta lección cobra la recompensa de esa propiedad. Porque la definición es una estructura de datos y no código opaco, una herramienta puede leerla y dibujarla como un diagrama de estados —sin ejecutar nada— y, aún mejor, puede hacerlo en las dos direcciones: editas el diagrama y obtienes la máquina, o escribes la máquina y obtienes el diagrama. Ese es el visualizador de Stately. Y porque un actor emite eventos observables en cada transición, otra herramienta puede engancharse a un actor vivo y mostrar su estado moviéndose en tiempo real: eso es inspect. Al final del nivel, la definición, el diagrama y la ejecución dejan de ser tres cosas distintas y se revelan como tres vistas del mismo artefacto.

El diagrama es el código

Un diagrama de estados dibujado a mano se desincroniza del código en cuanto alguien toca el código. La propuesta de Stately elimina esa deriva por construcción: como la máquina ES una estructura de datos, el diagrama se genera a partir de ella y no puede mentir. Pegas la definición en el visualizador —disponible en el estudio de Stately en la web y en su extensión para el editor— y obtienes el autómata dibujado, con sus estados, sus transiciones etiquetadas por evento y sus estados finales marcados. Y como el mapeo es biyectivo, puedes arrastrar en el diagrama y recuperar el código correspondiente.

flowchart LR
A[Definicion con createMachine] --> B[Estructura serializable a JSON]
B --> C[Visualizador de Stately]
B --> D[Actor con la opcion inspect]
C -.edicion de ida y vuelta.-> A
D --> E[Diagrama vivo en el navegador]

El estudio ofrece además un modo de simulación: sin arrancar tu aplicación, haces clic sobre los eventos disponibles y el diagrama recorre las transiciones, resaltando el estado activo. Es la máquina ejecutándose en tu cabeza, pero dibujada —una forma de validar el modelo antes de conectarlo a una sola línea de interfaz—. La extensión para el editor mantiene esa vista junto al código: modificas la definición y el diagrama se redibuja al instante, de modo que revisar una máquina en una petición de cambios es leer su diagrama, no descifrar un objeto anidado. Esto reencuadra qué es una máquina de estados: no un diagrama que documenta el código ni un código que implementa un diagrama, sino un único artefacto con dos representaciones equivalentes. El diagrama no es una ayuda visual sobre el código: es el código, mostrado de otra forma.

inspect: ver el actor en vivo

El visualizador dibuja la definición estática y la simula a mano. Para ver la EJECUCIÓN real —qué transición ocurre cuando, con qué evento, con qué contexto— se usa @statelyai/inspect. La idea es instrumentar el actor: createBrowserInspector abre una vista del diagrama en el navegador, y le pasas su función inspect al crear el actor a través de las opciones. A partir de ahí, cada evento que envías se anima sobre el diagrama, resaltando el estado activo y la flecha recorrida.

import { createActor } from 'xstate'
import { createBrowserInspector } from '@statelyai/inspect'
import { maquina } from './maquina'

const { inspect } = createBrowserInspector()

const actor = createActor(maquina, { inspect })
actor.start()

actor.send({ type: 'ENVIAR' })
actor.send({ type: 'OK' })
// cada send se ilumina en el diagrama abierto en el navegador

La opción inspect es un segundo argumento de createActor, junto a otros como input o id. No cambia el comportamiento del actor en absoluto: es una escucha pasiva. Esa es la clave —observar no altera lo observado—, y por eso puedes dejar el inspector activado en desarrollo sin miedo a que modifique la lógica que estás depurando. Si prefieres controlar cuándo se abre la vista, createBrowserInspector acepta opciones como autoStart para no lanzarla hasta que llames a su método start.

Los eventos de inspección

createBrowserInspector es una comodidad que dibuja por ti, pero por debajo la opción inspect acepta simplemente una función que recibe eventos de inspección. Ese es el sustrato de bajo nivel sobre el que se construye cualquier herramienta —tu propio logger, un trazador, un panel de devtools—. Los eventos tienen un type con prefijo @xstate.

const actor = createActor(maquina, {
  inspect: (ev) => {
    if (ev.type === '@xstate.snapshot') {
      console.log('nuevo estado', ev.snapshot.value)
    }
    if (ev.type === '@xstate.event') {
      console.log('evento recibido', ev.event.type)
    }
  },
})

Con esta función tienes acceso programático a toda la historia del actor a medida que ocurre: cada evento entrante y cada snapshot resultante. Escribir un registro de auditoría, reproducir sesiones, alimentar una línea de tiempo de depuración o exportar trazas para un test se reducen a filtrar estos eventos. El inspector visual del navegador no es más que un consumidor bien hecho de exactamente este flujo, y en el servidor un inspector basado en WebSocket consume los mismos eventos sin navegador alguno.

Construir una línea de tiempo, por ejemplo, es acumular esos eventos en un array a medida que llegan:

const linea = []

const actor = createActor(maquina, {
  inspect: (ev) => {
    if (ev.type === '@xstate.event') {
      linea.push({ tipo: 'evento', valor: ev.event.type })
    }
    if (ev.type === '@xstate.snapshot') {
      linea.push({ tipo: 'estado', valor: ev.snapshot.value })
    }
  },
})

Cada entrada de linea es un fotograma del comportamiento: qué llegó y a qué estado condujo. Volcarla a una tabla da la traza completa de una sesión, y compararla contra una traza esperada convierte la inspección en una forma de prueba de extremo a extremo. La misma estructura de datos que dibuja Stately alimenta tus propias herramientas.

Inspección solo en desarrollo

El inspector es una herramienta de diagnóstico, no de producción: abrir una pestaña con un diagrama no tiene sentido para un usuario final, y el paquete @statelyai/inspect no debería viajar en el código que sirves. El patrón habitual es crear el inspector solo cuando una variable de entorno de desarrollo lo pide, y pasar su inspect —o undefined— al actor. Como inspect es opcional, pasar undefined deja al actor exactamente como estaría sin instrumentar.

import { createActor } from 'xstate'
import { maquina } from './maquina'

let inspect
if (import.meta.env.DEV) {
  const mod = await import('@statelyai/inspect')
  inspect = mod.createBrowserInspector().inspect
}

const actor = createActor(maquina, { inspect })
actor.start()

La importación dinámica dentro de la rama de desarrollo consigue, además, que el empaquetador excluya por completo la librería del build de producción: si el import vive tras una condición que el compilador puede resolver como falsa, el código muerto se poda. El resultado es la mejor de las dos situaciones: observabilidad total mientras desarrollas, cero peso cuando publicas.