Sincronizar con una API imperativa: el elemento real como actor invocado

Hay una asimetría incómoda en el fondo de todo reproductor: tu máquina de estados no es la única máquina de estados en juego. El elemento multimedia del navegador ya tiene la suya, implementada en el motor, con sus propias posiciones —HAVE_NOTHING, HAVE_METADATA, HAVE_ENOUGH_DATA— y sus propias transiciones que ocurren sin pedirte permiso porque dependen de la red, del decodificador y del sistema operativo. Esa máquina ajena no expone su estado como valor sino como una colección de propiedades mutables y un torrente de eventos del DOM, y su interfaz de control es imperativa: métodos que se invocan por efecto, no eventos que se envían. El error de principiante es tratarla como un almacén de datos que se lee y se escribe a voluntad. El patrón correcto la trata como lo que es —otro actor, con vida propia y latencia propia— y establece con ella un protocolo de dos canales: tú envías órdenes, ella responde con hechos, y ninguno de los dos lee directamente el interior del otro.

Dos canales: órdenes hacia dentro, hechos hacia fuera

fromCallback es el único de los creadores de lógica que ofrece comunicación en ambos sentidos, y por eso es el envoltorio natural de cualquier recurso imperativo. Recibe sendBack para empujar hechos hacia la máquina padre y receive para escuchar órdenes que la máquina padre le manda. Cada dirección tiene un vocabulario distinto y mezclarlos es el primer error a evitar: las órdenes están en imperativo y en minúsculas, los hechos en pasado y en mayúsculas.

import { fromCallback } from 'xstate'

type Orden =
  | { type: 'cargar'; src: string }
  | { type: 'play' }
  | { type: 'pause' }
  | { type: 'buscar'; segundo: number }

export const medioReal = fromCallback<Orden, { el: HTMLVideoElement }>(
  ({ input, sendBack, receive }) => {
    const el = input.el

    const listo = () => sendBack({ type: 'PUEDE_REPRODUCIR' })
    const esperando = () => sendBack({ type: 'ESPERANDO_DATOS' })
    const sonando = () => sendBack({ type: 'DATOS_SUFICIENTES' })
    const detenido = () => sendBack({ type: 'PAUSA_CONFIRMADA' })
    const final = () => sendBack({ type: 'FIN' })
    const fallo = () =>
      sendBack({ type: 'FALLO', motivo: el.error?.message ?? 'medio no disponible' })

    el.addEventListener('canplay', listo)
    el.addEventListener('waiting', esperando)
    el.addEventListener('playing', sonando)
    el.addEventListener('pause', detenido)
    el.addEventListener('ended', final)
    el.addEventListener('error', fallo)

    receive((orden) => {
      switch (orden.type) {
        case 'cargar':
          el.src = orden.src
          el.load()
          break
        case 'play':
          void el.play().catch(fallo)
          break
        case 'pause':
          el.pause()
          break
        case 'buscar':
          el.currentTime = orden.segundo
          break
      }
    })

    return () => {
      el.removeEventListener('canplay', listo)
      el.removeEventListener('waiting', esperando)
      el.removeEventListener('playing', sonando)
      el.removeEventListener('pause', detenido)
      el.removeEventListener('ended', final)
      el.removeEventListener('error', fallo)
      el.pause()
      el.removeAttribute('src')
      el.load()
    }
  },
)

La máquina lo invoca en la raíz, para que el actor viva mientras viva el reproductor entero, y le habla con sendTo desde las acciones de entrada de los estados que corresponden.

invoke: { id: 'medio', src: 'medioReal', input: ({ context }) => ({ el: context.el }) },
states: {
  reproduciendo: { entry: sendTo('medio', { type: 'play' }) },
  pausado: { entry: sendTo('medio', { type: 'pause' }) },
}

El bucle de realimentación y cómo cortarlo

El fallo más sutil de este patrón aparece cuando una orden provoca un evento que provoca la misma orden. Entrar en reproduciendo emite play; el elemento responde con playing; si tradujeras playing como un evento REPRODUCIR dirigido a la máquina, la máquina volvería a entrar en reproduciendo y volvería a emitir play. Con la reentrada eso es un ciclo infinito silencioso; sin ella, es simplemente ruido que enmascara los defectos reales.

flowchart LR
M[maquina de estados] -->|ordenes: play pause buscar| A[actor envoltorio]
A -->|metodos imperativos| E[elemento del navegador]
E -->|eventos del DOM| A
A -->|hechos: PUEDE_REPRODUCIR ESPERANDO_DATOS FIN FALLO| M
style M fill:#89b4fa,color:#11111b
style E fill:#f9e2af,color:#11111b

La regla que corta el ciclo es que un hecho jamás debe traducirse al evento que lo causó. playing no significa reproduce, significa hay datos suficientes y el reloj avanza, y por eso se traduce como DATOS_SUFICIENTES, que solo tiene destino desde buffering. En reproduciendo ese hecho no declara transición y se descarta sin consecuencias, que es justo el comportamiento deseado: la confirmación de algo que ya sabías no debe cambiar nada.

Quién manda cuando ambos creen mandar

Queda una pregunta de gobierno: si el usuario usa los controles nativos del elemento, el recurso cambia por su cuenta y tu máquina se entera después. La respuesta no es prohibir esa vía sino declarar cuál de las dos partes es la fuente de verdad y ser consecuente. Si tu máquina manda, ocultas los controles nativos y todo pasa por eventos tuyos. Si conviven, tratas cada cambio externo como un hecho que debe subir y ajustar tu estado, y aceptas que tus acciones de entrada deben ser idempotentes: emitir pause sobre algo ya pausado no debe producir nada observable, y por suerte la API imperativa cumple esa propiedad de forma natural.