# Payload types

Every port declares a `dtype`. Fluksio checks values against it and offers
compatible messages when you bind dashboard widgets.

Messages carry JSON. Binary data lives in the artifact store; messages carry
references to it.

## Scalars

| `dtype` | Accepts |
|---|---|
| `float` | integer or floating-point number, excluding booleans |
| `int` | integer, excluding booleans |
| `str` | string |
| `bool` | `true` or `false` |

`NaN` and infinity are rejected, including in structured payloads. For an
unavailable numeric result, omit that output or return `None` to publish
nothing. A numeric port does not accept `None` as its value.

## Structured payloads

### `record`

An object with string keys and scalar or null values. Nested objects and
lists are not allowed.

```json
{"title": "Boiler", "body": "Pressure low", "severity": "warning"}
```

Notification and Player widgets read records. Dashboard alert channels also
publish them.

### `list`

An array with a declared item type:

| `item` | Accepts |
|---|---|
| unset or `record` | flat records; used by Agenda and Forecast |
| `float`, `int`, `str`, `bool` | scalars of that type |
| `json` | arbitrary JSON values |

`list` and `series` cannot be declared as item types. Use `item: "json"` if
items need arbitrary nested structures.

### `series`

Labelled lines of numeric `[timestamp, value]` pairs:

```json
{
  "lines": [
    {"label": "living", "points": [[1717000000, 21.4], [1717000060, 21.5]]}
  ],
  "range_s": 86400,
  "interval_s": 60
}
```

Additional top-level keys are preserved. A Query chart expects the
`range_s` and `interval_s` from its request in the response; this prevents
an answer for another window from replacing its chart.

The run-series comparison endpoint also returns this shape.

### `artifact`

A reference to bytes in the content-addressed artifact store:

```json
{"digest": "sha256:…", "size": 4194304, "media_type": "application/octet-stream", "name": "weights.pt"}
```

`digest` and `size` identify the content. `media_type` and `name` describe it.
The reference works wherever the store is reachable.

Create one with `fluksio.save_artifact` and read its bytes with
`fluksio.load_artifact`. See [Artifacts](../code/nodes.md#bytes-artifacts).

### `image`, `audio`, `video`

Artifact references restricted to the matching `media_type` family:

```json
{
  "digest": "sha256:…",
  "size": 61344,
  "media_type": "image/jpeg",
  "name": "frame.jpg",
  "meta": {"width": 1280, "height": 720, "seq": 41}
}
```

An `audio` port accepts `audio/*`; `image` and `video` work the same way.
An `artifact` port accepts all three. Optional `meta` fields are for the
consumer; Fluksio does not interpret them.

A media stream is a [streaming port](../concepts/flows.md#streaming-ports)
publishing one reference per frame or chunk. Saving with
[`volatile=True`](../code/nodes.md#media) keeps bytes in memory and lets local
websocket clients receive them with the value. Stored media and portal views
fetch the bytes separately.

Use occasional snapshots through a portal. For continuous video, point a
Media widget's **Live stream** at a browser-compatible source URL reachable
by the screen.

### `json`

Any JSON-serializable value. Use it for payloads without a fixed shape.
Prefer a specific type when one fits; it gives widgets and other authors a
clearer contract.

## Referencing a run's output

A run parameter can name an existing value instead of repeating it:

- `@run:<id>.<output>` resolves an earlier run's output.
- `sha256:…` resolves an artifact digest.

These strings resolve before the run starts, regardless of the input's type.
Both prefixes are reserved even for `str` inputs; they cannot be passed as
literal text in run parameters.

## Widget bindings

| Widget | Accepts |
|---|---|
| Gauge, live Chart, Slider, Bar | `float`, `int` |
| Query Chart | `series` response, `record` request |
| Switch | `bool` |
| Agenda, Forecast | `list` |
| Notification, Player | `record` |
| Colour | `list` for HSV/RGB, `str` for hex |
| Media | `image`, `audio`, `video`, `artifact` |
| Value, Icon, Button, Buttons, Input, Selector | no fixed type restriction |
| Clock, Text, Website | no message binding |

Player transport commands publish to a separate `str` message.
Binding checks apply in the editor and on the server.

## Icon and colour names

Forecast reads a list of records with `label`, `icon` and `value`, plus
optional `color`:

```json
[{"label": "Today", "icon": "cloud-rain", "color": "primary", "value": "14°"}]
```

The Icon widget uses the same vocabulary:

| | Names |
|---|---|
| Icons | `sun`, `moon`, `cloudy`, `cloud-rain`, `cloud-drizzle`, `cloud-snow`, `cloud-lightning`, `cloud-fog`, `wind`, `umbrella`, `snowflake`, `droplets`, `thermometer`, `thermometer-sun`, `flame`, `fan`, `sun-snow`, `door-open`, `house`, `bed`, `lightbulb`, `plug`, `cctv`, `music`, `volume-2`, `volume-x`, `zap`, `battery-charging`, `arrow-up`, `arrow-down`, `triangle-alert`, `check`, `circle-check` |
| Colours | `default`, `muted`, `primary`, `success`, `danger` |

An empty icon draws nothing. Unknown icons use a placeholder; unknown colours
use `default`. Each warns once in the browser console.

## Type failures

A mismatched value raises an error on the node that produced it, naming the
port and received value. It is not published downstream.

## See also

- [Flows, nodes and messages](../concepts/flows.md)
- [Node types](node-types.md)
- [Dashboards and panels](../interface/dashboards.md)