# Host API

## Purpose

The host API is the stable boundary that all operator surfaces and later external show-control adapters must use.

Current rule:

- no UI is allowed to become the realtime clock
- no frontend-specific assumptions are allowed to leak into scene simulation or transport planning
- future grandMA support must land as an adapter on this API, not as a special-case core path

## Current Implementation

The API lives in:

- `crates/infinity_host/src/control.rs`
- `crates/infinity_host/src/scene.rs`
- `crates/infinity_host/src/simulation.rs`

The engineering GUI already consumes this API through the `HostApiPort` / `HostUiPort` trait boundary.

## Snapshot Model

`HostSnapshot` currently exposes:

- system metadata
- global controls
- engine timing and transition state
- catalog of patterns, presets, and groups
- active scene with parameter values
- simulated preview panels
- node and panel status
- recent event log

This makes it suitable as the shared read model for:

- engineering GUI
- upcoming web UI
- CLI inspection
- later external control bridges

## Command Model

`HostCommand` currently supports:

- blackout
- master brightness
- pattern selection
- preset recall
- group selection
- scene parameter changes
- transition duration changes
- per-panel test triggers

## Simulation Layer

The current `SimulationHostService` is not a throwaway mock. It is the software-first runtime for:

- look exploration
- preset development
- parameter tuning
- future web UI integration
- API contract testing before hardware activation

It simulates:

- active scene state
- pattern rendering previews
- group gating
- transitions
- node connectivity status
- per-panel mapping tests

## Near-Term Direction

1. Keep extending this API instead of adding surface-specific data paths.
2. Add a network-facing adapter for the same API when the web UI starts.
3. Keep engineering GUI focused on topology, mapping, diagnostics, and admin.
4. Add grandMA later as an external show-control adapter against this API.