Infinity_Vis_Rust/docs/host_api.md

# Host API

## Purpose

The host API is the stable external product boundary for:

- the creative web UI
- the native engineering GUI
- future remote operator clients
- later external show-control adapters such as a grandMA bridge

The realtime rule remains strict:

- the API is a control and observation layer
- the host core remains the timing authority
- no frontend or external adapter is allowed to become the LED clock

## Runtime Components

Core and API implementation:

- `crates/infinity_host/src/control.rs`
- `crates/infinity_host/src/scene.rs`
- `crates/infinity_host/src/show_store.rs`
- `crates/infinity_host/src/simulation.rs`
- `crates/infinity_host/src/external_control.rs`
- `crates/infinity_host_api/src/dto.rs`
- `crates/infinity_host_api/src/server.rs`

Server startup:

```powershell
cargo run -p infinity_host_api -- --config config/project.example.toml --bind 127.0.0.1:9001 --runtime-state data/runtime_state.json
```

Creative web UI V1 is served by the same process:

```text
http://127.0.0.1:9001/
```

## Versioning Policy

The current public contract is `v1`.

Rules:

- all public HTTP and WebSocket routes are namespaced under `/api/v1`
- every response body carries `api_version: "v1"`
- additive fields are allowed inside `v1`
- semantic breaking changes require a new version namespace
- external consumers must treat undocumented internal-only fields as unstable and ignore them

## Stable External Models

Stable external response families:

- command response
- state snapshot
- preview snapshot
- combined snapshot
- catalog
- event stream
- typed error object

Stable external command families:

- global control
- pattern and preset selection
- group targeting
- scene parameter updates
- transition configuration
- preset persistence
- creative snapshot persistence and recall
- panel test trigger

## Internal Versus External Fields

External and stable in `v1`:

- every field defined in `crates/infinity_host_api/src/dto.rs`
- route names and payload shapes documented below
- error object shape `{ api_version, error: { code, message } }`
- event stream envelope shape `{ api_version, sequence, generated_at_millis, message }`

Internal and not part of the API contract:

- the exact shape of `HostSnapshot` in `crates/infinity_host/src/control.rs`
- simulation-only storage layout in `data/runtime_state.json`
- internal event history buffering size
- internal scene library structures in `show_store.rs`
- engineering-GUI-specific rendering or polling behavior

## HTTP Endpoints

### GET `/api/v1/state`

Returns only the stable state snapshot.

Example:

```json
{
  "api_version": "v1",
  "generated_at_millis": 512,
  "state": {
    "system": {
      "project_name": "Infinity Vis",
      "schema_version": 1,
      "topology_label": "6 nodes / 18 outputs / 106 LEDs"
    },
    "global": {
      "blackout": false,
      "master_brightness": 0.2,
      "selected_pattern": "gradient",
      "selected_group": "top_panels",
      "transition_duration_ms": 320,
      "transition_style": "chase"
    },
    "engine": {
      "logic_hz": 120,
      "frame_hz": 60,
      "preview_hz": 15,
      "uptime_ms": 512,
      "frame_index": 30,
      "dropped_frames": 0,
      "active_transition": {
        "style": "chase",
        "from_pattern_id": "solid_color",
        "to_pattern_id": "gradient",
        "duration_ms": 320,
        "progress": 0.28
      }
    }
  }
}
```

### GET `/api/v1/preview`

Returns only the stable preview snapshot.

Example:

```json
{
  "api_version": "v1",
  "generated_at_millis": 512,
  "preview": {
    "generated_at_millis": 512,
    "panels": [
      {
        "node_id": "node-01",
        "panel_position": "top",
        "representative_color_hex": "#FF8A5B",
        "sample_led_hex": [
          "#FF8A5B",
          "#F36E43",
          "#D85A2F"
        ],
        "energy_percent": 47,
        "source": "transition"
      }
    ]
  }
}
```

### GET `/api/v1/snapshot`

Returns the convenience composition of `state` plus `preview`.

This route exists for lightweight clients and debugging. Consumers that want strict separation should prefer `GET /api/v1/state` and `GET /api/v1/preview`.

### GET `/api/v1/catalog`

Returns the stable creative library:

- patterns
- presets
- groups
- creative snapshots

Example preset summary:

```json
{
  "preset_id": "ocean_gradient",
  "pattern_id": "gradient",
  "target_group": null,
  "transition_duration_ms": 320,
  "transition_style": "crossfade",
  "source": "built_in"
}
```

Example creative snapshot summary:

```json
{
  "snapshot_id": "variant_floor",
  "label": "Variant Floor",
  "pattern_id": "noise",
  "target_group": "bottom_panels",
  "transition_duration_ms": 220,
  "transition_style": "chase",
  "saved_at_unix_ms": 1760000000000
}
```

### GET `/api/v1/presets`

Returns only preset summaries.

### GET `/api/v1/groups`

Returns only group summaries.

### POST `/api/v1/command`

Accepts one versioned command envelope.

Example request:

```json
{
  "request_id": "web-1713352662000",
  "command": {
    "type": "save_creative_snapshot",
    "payload": {
      "snapshot_id": "variant_floor",
      "label": "Variant Floor",
      "overwrite": false
    }
  }
}
```

Example response:

```json
{
  "api_version": "v1",
  "accepted": true,
  "request_id": "web-1713352662000",
  "generated_at_millis": 522,
  "command_type": "save_creative_snapshot",
  "summary": "creative snapshot saved: variant_floor"
}
```

## Stable Error Object

All API failures return:

```json
{
  "api_version": "v1",
  "error": {
    "code": "unknown_creative_snapshot",
    "message": "creative snapshot 'does_not_exist' does not exist"
  }
}
```

Stable `v1` error families currently include:

- `invalid_request_json`
- `invalid_command`
- `unknown_group`
- `unknown_preset`
- `unknown_creative_snapshot`
- `preset_exists`
- `snapshot_exists`
- `group_exists`
- `persist_failed`
- `missing_websocket_key`
- `not_found`

## WebSocket Event Stream

### WS `/api/v1/stream`

The stream emits a typed envelope with a monotonic sequence counter:

```json
{
  "api_version": "v1",
  "sequence": 19,
  "generated_at_millis": 880,
  "message": {
    "type": "event",
    "payload": {
      "kind": "warning",
      "code": "unknown_creative_snapshot",
      "message": "creative snapshot 'does_not_exist' does not exist"
    }
  }
}
```

Stable message types:

- `snapshot`
- `preview`
- `event`

Stable event kinds:

- `info`
- `warning`
- `error`

## Guaranteed Commands In `v1`

Guaranteed control commands:

- `set_blackout`
- `set_master_brightness`
- `select_pattern`
- `recall_preset`
- `select_group`
- `set_scene_parameter`
- `set_transition_duration_ms`
- `set_transition_style`
- `trigger_panel_test`

Guaranteed persistence and creative-library commands:

- `save_preset`
- `save_creative_snapshot`
- `recall_creative_snapshot`
- `upsert_group`

## Persistence Behavior

The simulation-backed host service now persists runtime-facing creative data to `data/runtime_state.json` by default.

Persisted data includes:

- active scene
- global blackout and brightness state
- transition duration and style
- runtime user presets
- runtime user groups
- creative snapshots and variants

This persistence file is an internal runtime artifact, not the public API contract.

## External Show Control Adapter Boundary

The generic internal adapter surface lives in:

- `crates/infinity_host/src/external_control.rs`

Key rule:

- future adapters may only translate external intent into the defined host command surface
- they must not reach into simulation internals, UI state, or hardware driver details directly

## Contract And Integration Coverage

Current software-side hardening lives in:

- `crates/infinity_host_api/tests/contract.rs`
- `crates/infinity_host/src/show_store.rs` tests
- `crates/infinity_host/src/simulation.rs` tests

Covered flows include:

- state, preview, snapshot, catalog, presets, and groups endpoints
- command success and typed command failure
- WebSocket snapshot, preview, and event messages
- group targeting
- parameter updates
- transition configuration
- blackout
- preset save
- creative snapshot save and recall
- persistence across restart
- a longer ignored load-oriented sequence for platform hardening

## Web UI Scope

The current web UI intentionally focuses on creative use:

- pattern and preset selection
- group targeting
- transition configuration
- scene parameters
- preset save and overwrite
- creative snapshot save and recall
- preview
- raw snapshot display
- filterable event feed

Mapping, topology diagnostics, panel-test administration, and low-level node status remain primarily in the native engineering GUI.