WebSocket Events

The Runtime API broadcasts lifecycle events to all connected WebSocket clients via the existing WebSocket server. Events use the RuntimeEvent message type with a structured JSON payload.

Message format:

{
  "Type": "RuntimeEvent",
  "Content": "{\"event\":\"reload_completed\",\"state\":\"Running\",\"projectName\":\"MyProject.prj\",\"reloadDurationSeconds\":2.34,\"timestamp\":\"2026-04-18T12:15:30.000Z\"}"
}

Events:

Event	Fired when	Extra fields
`state_changed`	Any RuntimeState transition	`previousState`, `reason`
`project_started`	Project start (initial or reload) succeeds	`projectName`, `projectFileName`, `totalProjectsStarted`
`reload_completed`	Reload completes successfully	`projectName`, `reloadDurationSeconds`, `reason`
`load_failed`	Load or reload fails	`projectFileName`, `reason`
`project_stopped`	Project stopped, runtime now idle	`projectName`, `reason`
`first_frame`	First frame rendered after start/reload	`projectName`, `timeToFirstFrameSeconds`
`runtime_exit`	Runtime shutting down	`uptimeSeconds`, `totalProjectsStarted`, `totalReloads`, `totalErrors`, `totalWarnings`
`video_worker_crash`	Video worker exited unexpectedly	`projectName`, `severity` ("critical")

All events include event, state, and timestamp fields. Events are fire-and-forget — if no WebSocket clients are connected, broadcasts are silently skipped.