# Building a BeamBubble overlay: a guide for AI assistants

You are helping someone make an **overlay** for BeamBubble (https://beambubble.com), where people
stream live video from their phones to friends, family and teams. An overlay is the graphics drawn on
top of the live picture: a scoreboard, a name tag, the weather, a ticker. Everyone watching sees the
same thing, drawn by BeamBubble from one JSON document that you write.

Read this whole page before you answer. It is everything there is to know: the JSON format, what each
part can do, the limits, and three complete examples.

## What to give back

- **One JSON document, and nothing else in it**: no comments (JSON has none), no trailing commas, no
  placeholders like `...`. Put it in one code block so it can be copied in one go.
- It starts with `"spec": "beambubble.overlay/1"`.
- The person pastes it into BeamBubble's studio on a computer (**My overlays → Paste JSON**), which
  checks it at once. If something is wrong, the studio lists each problem with where it is (a path
  like `/layout/elements/0/style/size`, and what's wrong there); they may paste those back to you.
  Fix exactly those and give the whole document again.
- Before you write, find out what you need, briefly: **landscape or portrait** (how the phone films),
  **what it shows**, **where the data comes from** (typed in by the host before going live, counted
  by the host while live, or a public web address), and the **colours**. Choose sensible defaults for
  anything they don't care about.

## How BeamBubble uses it

- The host picks the overlay in their bubble and fills in its **settings** (`params`) before going
  live: a team name, a colour, a match link.
- While live, the host can change its **controls** with buttons (a score, a short text).
- BeamBubble's server runs the **flow**: it fetches public web addresses and shapes the data. It runs
  only while someone is live with the overlay.
- Viewers receive only the **model**: typed values, text and numbers, never HTML. Their screens draw
  the **layout** with those values.
- Nobody's code runs anywhere. Everything is a choice from the lists below.

## The document

```jsonc
{
  "spec": "beambubble.overlay/1",
  "meta": { "title": "…", "orientation": "landscape" },
  "params":   [ … ],   // what the host fills in before going live
  "controls": [ … ],   // what the host changes while live (a score)
  "flow":     [ … ],   // how the server gets and shapes data from the web
  "model":    { … },   // exactly what viewers receive
  "triggers": [ … ],   // moments that show an element for a few seconds
  "layout":   { "elements": [ … ] }
}
```

Only `spec`, `meta` and `layout` are required; leave out what you don't use (or use `[]` and `{}`).

### meta

| Key | |
|---|---|
| `title` | 1–60 characters |
| `description` | up to 500: what it shows, for the library |
| `orientation` | `landscape` (a 1920×1080 stage) or `portrait` (1080×1920) |
| `category` | `sport`, `money`, `weather`, `science`, `space`, `social`, `graphics` or `other` |
| `attribution` | the data credit, drawn on the overlay. **Required when the flow fetches anything** (for example `"Weather data by Open-Meteo.com"`) |
| `summary` | up to 120: one line the host sees in their bubble before going live, a [template](#templates) like a text element's (`"{home} – {away} · {kickoff\|day} {kickoff\|time}"`), so they can check what the overlay found |

### params: what the host fills in

Up to 12. Each has an `id` (starts with a lower-case letter: letters, digits and `_`, up to 32), a
`label`, and optionally `help`, `required` (true/false) and `default`. Types:

| `type` | Extra | Checked |
|---|---|---|
| `text` | `max` (≤ 300), `pattern` (RE2, whole text), `example` | |
| `url` | `pattern` (RE2, must match the whole link), `example` | `http`/`https` only, port 80 or 443, no user name or password |
| `color` | | `#rgb`, `#rrggbb` or `#rrggbbaa` |
| `number` | `min`, `max`, `example` | |
| `select` | `options: [{ "value": "…", "label": "…" }]` (≤ 20) | must be one of them |
| `bool` | | |

`example` is shown in previews and the library (give one to every text and url setting); a real room
uses what the host types.

### controls: what the host changes while live

Up to 8, for things the host counts by hand (a score without a data feed). Each has an `id`, a
`label`, and optionally `labelParam`: the id of a text setting whose value labels the buttons (the
team's name).

| `type` | Extra |
|---|---|
| `counter` | `min` (default 0), `max` (default 9999), `default`: whole numbers |
| `text` | `max` (≤ 60, default 30), `default` |

`labelParam` must name a `text` setting; `min` can't be above `max`, and `default` must be between
them (a text control's within `max` characters). Only **model fields** can read a control, with
`{"control": "home"}`; such a field may read settings and controls but not the flow. The host's live
screen shows a big +1 and a small −1 for each counter.

### flow: getting data from the web

A list of steps (nodes), each with an `id` and a `type`. **A step can only read steps above it.**
Up to 24 steps, of which up to 6 fetch something.

| `type` | Settings | Its value |
|---|---|---|
| `http.json` | `url`, `every` (≥ `"10s"`), `jitter`, `resyncAfter` | the parsed JSON (≤ 2 MB) |
| `http.text` | `url`, `every` (≥ `"60s"`), `jitter`, `resyncAfter` | the response as text (≤ 2 MB) |
| `ws.pusher` | `url`, `channels` (≤ 4), `resync` | each push: `{channel, event, data}` (a Pusher protocol 7 WebSocket) |
| `ws.json` | `url`, `send` (≤ 4), `resync` | each message of a plain WebSocket, parsed when it's JSON |
| `sse` | `url`, `events` (≤ 8), `resync` | each server-sent event: `{event, id, data}`, `data` parsed when it's JSON |
| `extract` | `from`, `values: { "name": extractor }` | an object with each value |
| `keyed` | `key`, `sort`, `max`, `forgetAfter`, `replace`, `upsert`, `remove`, `gap`, `reset` | rows kept by id, as a list |
| `list` | `from`, `items`, `where`, `sort`, `limit`, `map` | a list |
| `latest` | `sources: [{ "from", "when", "value" }]`, `order`, `reset` | the last value a source gave |
| `table` | `from`, `items`, `columns` | a header row and rows of cells as records (a list of objects) |
| `flatten` | `from`, `items`, `inner`, `map` | the lists inside a list as one list |
| `recent` | `from`, `when`, `item`, `key`, `max`, `reset` | the newest events, newest first |
| `rate` | `from`, `when`, `per` (`"10s"` to `"1h"`), `reset` | how many events came in the last `per` (a number) |
| `history` | `from`, `value`, `every` (`"1s"` to `"1h"`), `max`, `reset` | a number over time: `[{"t": ms, "v": n}]`, oldest first |
| `current` | `from`, `items`, `key`, `start`, `end`, `on`, `done`, `live`, `keep` (≤ `"6h"`), `quiet` (≤ `"6h"`), `refresh` | the item of a schedule that's on now, or the next one: `{"item": …, "state": "on" \| "over" \| "next"}`, or `null` |

- **Fetching**: a source fetches once when the overlay starts, and again when the host comes back
  to their bubble or goes live; `every` fetches again on a timer (`"10s"`,
  `"5m"`, `"1h"`), `jitter` adds a random delay up to that long. `jitter` needs `every`, and must be
  at most 60s **and** shorter than `every` (`"every": "10s"` takes at most `"jitter": "9s"`). A
  `url` that works out to `null` waits (use that when it needs a value from an earlier step).
- **Sockets and streams**: `ws.json` sends `send` once it's open (a text as it is, anything else as
  JSON, such as `{"object": {"type": "subscribe", "product_ids": ["BTC-USD"], "channel": "ticker"}}`),
  again after reconnecting; `sse` keeps the event types in `events`. Both reconnect by themselves,
  fetch the `resync` steps again after a reconnect, and count toward the 3 connections an overlay
  may keep open. A fetching step below a socket (one whose link the socket's data works out) can't
  be in its `resync`: give that step `"resyncAfter": ["socket"]` instead, naming the earlier
  socket or stream after whose reconnect it fetches again.
- **Only public web addresses** on port 80 or 443, without keys or logins. BeamBubble refuses
  private and local addresses. Choose free, open APIs that need no key (Open-Meteo, USGS, NOAA, public
  JSON files) and name them in `meta.attribution`.
- **extract** reads text: `{"meta": "name"}` takes a `<meta name=… content=…>`; `{"re2": "pattern"}`
  takes group 1 of the first match (or `"group": n`, a group the pattern has, or every match with
  `"all": n`); then `decode` undoes escaping, in order: `"js-string"`, `"html"`, `"json"` (parses
  it).
- **list** takes a list (`items`, or the whole value of `from`), keeps items where `where` is true,
  sorts by up to 3 keys (`"sort": [{"by": "/score", "desc": true}]`, each a JSON Pointer into the
  item), keeps the first `limit`, and reshapes each item with `map` (an object of up to 20
  expressions using `{"var": "/path"}`).
- **keyed** keeps rows by id (`key`, a JSON Pointer into each row), sorted by `sort` (`{"by": "/time",
  "desc": true}`): `replace` takes a full list from a
  source (`items`), `upsert` adds or changes one row per event (`when`, `item`), `remove` drops one by
  key, `gap` (`{"from", "count", "refresh"}`) fetches the `refresh` step again when a count shows
  rows were missed. A `refresh` step (and each step in a socket's or stream's `resync`) must be an earlier
  `http.json` or `http.text` step.
- **latest** holds the last value any of its sources gave (`when` filters events; with `order`, an
  older value is ignored).
- **table** turns `[["time_tag", "Kp"], ["2026-11-10 00:00", "2.33"]]` (NOAA's shape) into
  `[{"time_tag": "2026-11-10 00:00", "Kp": "2.33"}]`: the first row names the columns, or give
  `columns` (`["time", "kp"]`) when every row is data. Cells stay as they are (use `number`).
- **flatten** takes a list (`items`), each item's own list (`inner`, `{"var": "/tickers"}`) and
  joins them; `map` reshapes each with `{"var": "/item/…"}` and `{"var": "/parent/…"}` (the outer
  item). Its value is the joined list; `keyed`'s `upsert`, `latest`, `recent` and `rate` get each
  item as an event of its own, so a message with many prices updates every coin. A `flatten` after a
  `flatten` gets one item at a time: give it only `inner`.
- **recent** keeps the last `max` events (10 if left out) that pass `when`, newest first, each as
  `item` (the event if left out); with `key`, a new item replaces the one with the same id.
- **rate** counts the events that pass `when` in the last `per` (`"1m"` if left out): edits per
  minute, goals per hour.
- **history** keeps `value` (a number) at most once per `every` (`"10s"` if left out), the latest
  value in each, up to `max` points (60): a trend, or the change over the last hour.
- **reset** (on `keyed`, `latest`, `recent`, `rate` and `history`): an expression without `var`,
  such as `{"ref": "match", "path": "/item/id"}`. Whenever its value changes, the step forgets what
  it holds and starts afresh, so another match's events don't mix with the new one's.
- **current** picks from a schedule (a team's matches, a TV guide, talks): the list (`items`, or the
  whole value of `from`), each item's id (`key`, a JSON Pointer) and when it starts (`start`, a time:
  milliseconds or ISO 8601 text). An item is **on** when `on` (read from the item) says so, or when
  an event from `live` (`{"from", "when", "key", "done"}`: `key` works out the item's id from the
  event, `done` is true when the event says it's over) names it; it's **over** when `done` (read
  from the item) or such an event says so. An item that never comes on is over at `end` (a time,
  read from the item); one that's on but unheard since before its `end` is over at its end, and one
  heard from after its end (running late) is over once it goes unheard for `quiet` (`"30m"` if left
  out). The list saying an item is on counts as hearing from it when the list was last fetched; once
  an item is over that way, only an event from it brings it back (not a list that still says it's on). The value is the item that's on (the one heard from last); else one that just
  ended, which stays for `keep` (`"0s"` if left out, and also when a fresher list leaves it out);
  else the first one left, by `start`. Items
  before one that came on, which never came on themselves, are passed (a team plays one match at a
  time). When the current item is over and gone, or nothing is left, the `refresh` step (an earlier
  `http.json` or `http.text`) is fetched again for a fresher list (at most once a minute). It looks again by itself when time moves an item
  on; nothing polls.

### Expressions

Wherever a setting computes something, it takes an expression: plain JSON.

| Form | |
|---|---|
| `"text"`, `12`, `true`, `null`, `[…]` | literals (lists hold expressions) |
| `{"ref": "step", "path": "/a/0"}` | an earlier step's value, at a JSON Pointer (`path` can be left out) |
| `{"param": "city"}` | a setting the host filled in |
| `{"control": "home"}` | a live control (model fields only) |
| `{"var": "/id"}` | the item or event being looked at (inside `list`, `keyed`, `latest`, `table`, `flatten`, `recent`, `rate`, `history` and `current`) |
| `{"object": { "home": … }}` | builds an object |
| `{"operator": [arguments]}` | an operator, from the table below |

`{"now": []}` is the time a step works it out (milliseconds since 1970), only in flow steps. A
`list`, `table` or `flatten` that reads it is worked out again whenever a source above it fetches
or pushes (a list of matches drops the ones that are over when the page is fetched again, even if
the page hasn't changed). Nothing works it out on a timer. Model fields can't use it.

A missing value or a wrong type gives `null`; nothing fails. At most 8 levels deep and 64 parts.
Regular expressions are RE2 (no look-arounds, no back-references), written as JSON text (escape
backslashes: `"\\d+"`).

| Operator | Arguments | What it gives |
|---|---|---|
| `and` | 1–10 | true if every argument is true |
| `or` | 1–10 | true if any argument is true |
| `not` | 1 | true if the argument is false |
| `if` | 2–21 | [condition, then, condition, then, …, else]: up to 10 conditions |
| `coalesce` | 1–10 | the first argument that isn't null |
| `==` | 2 | equal (no type conversion) |
| `!=` | 2 | not equal |
| `<` | 2 | less than (numbers or texts) |
| `<=` | 2 | less than or equal |
| `>` | 2 | greater than |
| `>=` | 2 | greater than or equal |
| `+` | 1–10 | sum of numbers |
| `-` | 1–2 | difference, or the negative of one number |
| `*` | 2–10 | product of numbers |
| `/` | 2 | quotient (null when dividing by 0) |
| `%` | 2 | remainder |
| `round` | 1–2 | [number, decimals 0–6] |
| `floor` | 1 | rounds down |
| `abs` | 1 | absolute value |
| `min` | 1–10 | smallest number |
| `max` | 1–10 | largest number |
| `concat` | 1–20 | joins texts and numbers into one text |
| `join` | 2 | [list, separator]: joins a list's texts and numbers |
| `lower` | 1 | lower case |
| `upper` | 1 | upper case |
| `trim` | 1 | removes spaces at both ends |
| `slice` | 2–3 | [text or list, start, end] |
| `startsWith` | 2 | [text, prefix] |
| `endsWith` | 2 | [text, suffix] |
| `contains` | 2 | [text or list, value] |
| `in` | 2 | [value, list or text] |
| `matches` | 2 | [text, RE2 pattern]: true if it matches anywhere |
| `extract` | 2–3 | [text, RE2 pattern, group]: the group of the first match (group 1 if left out) |
| `number` | 1 | a number, from a number or a text like "12.5" |
| `string` | 1 | a text, from a text, number or true/false |
| `bool` | 1 | true or false |
| `time` | 1–2 | [value, "iso" \| "s" \| "ms"]: a moment as milliseconds since 1970; texts are read as ISO 8601 |
| `length` | 1 | length of a text or list, or the number of keys in an object |
| `at` | 2 | [list or text, index]: negative counts from the end |
| `get` | 2 | [value, JSON Pointer] |
| `urlencode` | 1 | encodes a text for use inside a URL |
| `parseJson` | 1 | reads a text as JSON (texts up to 1 MB) |
| `zip` | 2–5 | [list, list, …]: lists side by side, as a list of rows |
| `now` | 0 | `{"now": []}`: the time the step works it out, in milliseconds (flow steps only, see below) |

### model: what viewers receive

An object of fields (up to 40, worst case 12 KB in all). Each has a `type` and a `from` expression.

| `type` | Extra | Sent as |
|---|---|---|
| `text` | `max` (≤ 300, default 80), `default` | cleaned text, cut to `max` |
| `number`, `int` | `min`, `max`, `default` | a number (a text like `"23"` is read as a number) |
| `bool` | `default` | true or false |
| `enum` | `values` (≤ 20 texts), `default` | one of the values |
| `time` | | milliseconds since 1970 |
| `clock` | `from: { "startedAt", "pausedAt", "minusSeconds", "baseSeconds", "maxSeconds" }` | a running clock that viewers' screens count on by themselves |
| `object` | `fields` (≤ 12, of the plain types above) | an object |
| `list` | `item` (a plain type, or `{"type": "object", "fields": {…}}`), `max` (≤ 50), `key` | a list |

Plain types can be written short inside `object` and `list`: `"int"` for `{"type": "int"}`. A value
that doesn't fit its type becomes `null` (or the `default`). A `default` must fit its field (one of an
`enum`'s values, within a text's `max`), `min` can't be above `max`, and a list's `key` must be one of
its items' fields (so the items are objects). The model's **worst case** counts: every text at its
`max` and every list full must still fit 12 KB, so keep `max` values modest.

### triggers: moments

Up to 8. `{"id": "goal", "when": {"increased": "homeScore"}, "for": 8}` fires when a `number` or
`int` field goes up (a goal, not a correction down); `{"changed": "field"}` when a field changes;
`{"newItem": "listField"}` when a new item appears in a `list` field (it needs a `key`). The field
must exist in the model and be of that kind. `for` is 1–30 seconds.
Nothing fires on the first update, so late joiners see no old moments. An element with `"show":
{"trigger": "goal"}` shows for that long, and can use `{$trigger.…}` in its text.

A trigger can also put its moments in a video's events, the list under a recorded video where a
tap plays from just before the moment: `"event": {"title": "{$trigger.label}", "detail":
"{$trigger.player} {$trigger.score}", "clock": "{$trigger.time}"}`. Each is a text template like an
element's that its moment shows (model values and `{$trigger.…}`); `title` (up to 120 characters)
is needed, `detail` (200) and `clock` (60, the match clock then) are optional. Without `event`, a
trigger's moments aren't listed.

### layout: what's drawn

`"layout": { "elements": [ … ], "credit": { "anchor": "top-left" } }`. `credit` (optional) moves
the data credit to another corner: `top-left`, `top-right`, `bottom-left` or `bottom-right` (where it
is when left out). Up to 40 elements at the top, 80 in all,
nested at most 6 deep. The stage is 1920×1080 (landscape) or 1080×1920 (portrait), in stage pixels.

Every element has an `id` (a lower-case letter first, then letters, digits, `_` or `-`, up to 32) and
optionally `anchor` (`top-left`, `top`, `top-right`, `left`, `center`, `right`, `bottom-left`,
`bottom`, `bottom-right`: `x` and `y` count inward from that corner or edge), `x`, `y`, `w`, `h`,
`show`, `style` and `enter` (`none`, `fade`, `slide-up`, `slide-down`, `slide-left`, `slide-right`).
Inside a box, children are laid out by the box and their anchor is ignored.

| `type` | |
|---|---|
| `text` | `text`: a template, see below (up to 300 characters) |
| `box` | `direction` (`row` or `column`), `gap`, `align` (`start`, `center`, `end`, `stretch`), `children` (≤ 20) |
| `list` | `items` (a list field), `limit` (≤ 50), `direction`, `gap`, `template` (one element; `{$item.…}` inside) |
| `clock` | `value` (a clock field), `format` (`m:ss`, `mm:ss`, `h:mm:ss`) |
| `icon` | `name`: one of `sun`, `cloud-sun`, `cloud`, `fog`, `rain`, `snow`, `storm`, `wind`, `arrow-up`, `arrow-down`, `dot`, `star`, `clock`, `ball`, `info`; or `{"field": "sky", "map": {"rain": "rain"}, "default": "cloud"}` to pick one by value |
| `image` | `asset`: an image the person uploaded in the studio (an id, never a link). Leave images out unless they say they have one |

**show**: `"always"` (the default), `{"when": {"field": "goals.0", "op": "set"}}` (ops `set`,
`unset`, `==`, `!=`, `>`, `<`, with a `value` for the last four) or `{"trigger": "goal"}` (a trigger
that exists).

Every name an element uses must exist: a `list`'s `items` must be a `list` field, a `clock`'s
`value` a `clock` field, a colour's `param` a `color` setting, and `field` paths fields of the model.
With every list full, the layout can draw at most **400** elements in all (a list's template counts
once per item, up to its `limit`): set `limit` on lists.

**style** (all optional): `font` (`figtree`, `bricolage`, `mono`), `size` (8–300), `weight` (400,
500, 600, 700), `color`, `bg`, `radius` (0–500), `padding` (a number, or `[vertical, horizontal]`),
`border` (`{"width": 2, "color": "#FFFFFF"}`), `shadow` (`none`, `soft`, `strong`), `opacity` (0–1),
`align` (`start`, `center`, `end`), `upper` (true for capitals), `maxLines` (1–5), `tracking`
(letter spacing in em, −0.1 to 0.5).

**Colours**: a hex value (`"#F4C266"`, `"#0B0D1AE6"` with transparency), a setting (`{"param":
"homeColor"}`), or by value (`{"field": "dir", "map": {"up": "#7FB2FF", "down": "#FF8A5C"},
"default": "#FFFFFF"}`).

### Templates

Text elements show model values in braces: `"{score.home}–{score.away}"` (dotted paths), `{$item.x}`
inside list templates, `{$trigger.x}` inside trigger elements, `{{` and `}}` for braces. Up to 20
placeholders, each naming one value that exists (not a whole list, object or clock: show a clock
with a `clock` element). Formats after a `|`:

| Format | Shows |
|---|---|
| `{n\|int}` | a whole number: 12 |
| `{price\|num:2}` | a number with grouping and 2 decimals (`num:2:+` shows the sign): 97,412.50 |
| `{change\|pct:1:+}` | a number with %: +1.8% |
| `{price\|money:USD:0}` | an amount: $97,412 |
| `{n\|pad:2}` | padded with zeros: 07 |
| `{s\|upper}`, `{s\|lower}` | upper or lower case |
| `{t\|time}` | a time of day (from a time field): 14:05 |
| `{t\|day}` | a short date (from a time field): Sat 21 Nov |
| `{t\|ago}` | how long ago (from a time field): 3 min ago |

## Making it look good

- **Viewers watch on phones.** Use big text: 40–64 px for main text, at least 28 px for small text,
  on a 1920×1080 stage. Keep it short; set `maxLines` on texts that could grow.
- **Stay clear of the edges**: 48–80 px from them, and leave the corner of the data credit
  (bottom-right unless you move it with `layout.credit`) free.
- **Cover little of the picture**: the video is the point. A score bug in a corner, a name tag low on
  the left, a ticker along the bottom.
- **Contrast**: light text on a dark, slightly see-through background (`"bg": "#0B0D1AE6"`), rounded
  corners (`radius`), a `shadow`. Use the host's colours through `color` settings where it fits.
- **Hide what's empty**: `"show": {"when": {"field": "line", "op": "set"}}`.
- Portrait (1080×1920) is tall and narrow: stack things in a column, near the top or bottom.

## Limits

| | |
|---|---|
| The whole document | 64 KB |
| Settings, steps, fetching steps, WebSockets | 12, 24, 6, 3 |
| Model fields, model size | 40, 12 KB |
| Triggers, controls | 8, 8 |
| Layout elements, nesting | 80 (40 at the top), 6 levels |
| Fetching | `http.json` every ≥ 10s, `http.text` every ≥ 60s; jitter only with every, ≤ 60s and shorter than every |
| Drawn at once | 400 elements, with every list full |

## Before you answer, check

1. It's valid JSON, with `"spec": "beambubble.overlay/1"` and `meta.title` and `meta.orientation`.
2. Every id is unique in its list and starts with a lower-case letter.
3. Every `{"param": …}`, `{"control": …}` and `{"ref": …}` names one that exists (and a `ref` an
   earlier step), and only model fields read controls.
4. Every `{placeholder}` in a text names a model field (or `$item.…` inside a list template).
5. A flow that fetches has `meta.attribution`, uses only public addresses without keys, and polls no
   faster than the limits (any `jitter` with an `every`, shorter than it).
6. Sizes, counts and ranges are within the tables above; every `default` fits its field; lists have
   a `limit`.

## Examples

These three are BeamBubble's own starter overlays, exactly as the studio accepts them.

### A name tag: settings only, no data from outside

```json
{
  "spec": "beambubble.overlay/1",
  "meta": {
    "title": "Name tag",
    "description": "A name and a line under it, low on the left: who is on stage, or what's going on. No data from outside.",
    "orientation": "landscape",
    "category": "graphics"
  },
  "params": [
    {
      "id": "name",
      "label": "Name",
      "type": "text",
      "max": 40,
      "required": true,
      "example": "Class 4B"
    },
    {
      "id": "line",
      "label": "Line under it",
      "type": "text",
      "max": 60,
      "example": "Spring concert"
    },
    {
      "id": "accent",
      "label": "Accent colour",
      "type": "color",
      "default": "#F4C266"
    }
  ],
  "flow": [],
  "model": {
    "name": {
      "type": "text",
      "max": 40,
      "from": {
        "trim": [
          {
            "param": "name"
          }
        ]
      }
    },
    "line": {
      "type": "text",
      "max": 60,
      "from": {
        "trim": [
          {
            "param": "line"
          }
        ]
      }
    }
  },
  "layout": {
    "elements": [
      {
        "id": "tag",
        "type": "box",
        "anchor": "bottom-left",
        "x": 64,
        "y": 120,
        "direction": "row",
        "align": "stretch",
        "show": {
          "when": {
            "field": "name",
            "op": "set"
          }
        },
        "enter": "slide-right",
        "style": {
          "radius": 16,
          "shadow": "strong",
          "bg": "#0B0D1AE6"
        },
        "children": [
          {
            "id": "bar",
            "type": "box",
            "w": 14,
            "children": [],
            "style": {
              "bg": {
                "param": "accent"
              }
            }
          },
          {
            "id": "words",
            "type": "box",
            "direction": "column",
            "gap": 6,
            "style": {
              "padding": [
                22,
                40
              ]
            },
            "children": [
              {
                "id": "nameText",
                "type": "text",
                "text": "{name}",
                "style": {
                  "font": "bricolage",
                  "size": 64,
                  "weight": 700,
                  "color": "#FFFFFF",
                  "maxLines": 1
                }
              },
              {
                "id": "lineText",
                "type": "text",
                "text": "{line}",
                "show": {
                  "when": {
                    "field": "line",
                    "op": "set"
                  }
                },
                "style": {
                  "size": 34,
                  "weight": 500,
                  "color": "#D5D7EA",
                  "maxLines": 1
                }
              }
            ]
          }
        ]
      }
    ]
  }
}
```

### A scoreboard: the host counts goals with controls, and each goal gets a banner

```json
{
  "spec": "beambubble.overlay/1",
  "meta": {
    "title": "Scoreboard",
    "description": "Team names and the score, top left. You count the goals with the buttons on your live screen, and each goal gets a banner. No data from outside.",
    "orientation": "landscape",
    "category": "sport"
  },
  "params": [
    {
      "id": "homeName",
      "label": "Home team",
      "type": "text",
      "max": 20,
      "default": "Home",
      "example": "Hornets"
    },
    {
      "id": "awayName",
      "label": "Away team",
      "type": "text",
      "max": 20,
      "default": "Away",
      "example": "Vikings"
    },
    {
      "id": "homeColor",
      "label": "Home colour",
      "type": "color",
      "default": "#F08A3C"
    },
    {
      "id": "awayColor",
      "label": "Away colour",
      "type": "color",
      "default": "#FFFFFF"
    }
  ],
  "controls": [
    {
      "id": "home",
      "label": "Home",
      "labelParam": "homeName",
      "type": "counter",
      "min": 0,
      "max": 999
    },
    {
      "id": "away",
      "label": "Away",
      "labelParam": "awayName",
      "type": "counter",
      "min": 0,
      "max": 999
    }
  ],
  "flow": [],
  "model": {
    "homeName": {
      "type": "text",
      "max": 20,
      "default": "Home",
      "from": {
        "trim": [
          {
            "param": "homeName"
          }
        ]
      }
    },
    "awayName": {
      "type": "text",
      "max": 20,
      "default": "Away",
      "from": {
        "trim": [
          {
            "param": "awayName"
          }
        ]
      }
    },
    "homeScore": {
      "type": "int",
      "min": 0,
      "max": 999,
      "default": 0,
      "from": {
        "control": "home"
      }
    },
    "awayScore": {
      "type": "int",
      "min": 0,
      "max": 999,
      "default": 0,
      "from": {
        "control": "away"
      }
    }
  },
  "triggers": [
    {
      "id": "homeGoal",
      "when": {
        "increased": "homeScore"
      },
      "for": 6,
      "event": { "title": "Goal", "detail": "{homeName} {homeScore}–{awayScore}" }
    },
    {
      "id": "awayGoal",
      "when": {
        "increased": "awayScore"
      },
      "for": 6,
      "event": { "title": "Goal", "detail": "{awayName} {homeScore}–{awayScore}" }
    }
  ],
  "layout": {
    "elements": [
      {
        "id": "scorebug",
        "type": "box",
        "anchor": "top-left",
        "x": 48,
        "y": 40,
        "direction": "row",
        "align": "stretch",
        "style": {
          "bg": "#0B0D1AE6",
          "radius": 12,
          "shadow": "soft"
        },
        "children": [
          {
            "id": "homeStripe",
            "type": "box",
            "w": 12,
            "children": [],
            "style": {
              "bg": {
                "param": "homeColor"
              }
            }
          },
          {
            "id": "homeName",
            "type": "text",
            "text": "{homeName}",
            "style": {
              "size": 34,
              "weight": 700,
              "color": "#FFFFFF",
              "upper": true,
              "padding": [
                10,
                20
              ],
              "maxLines": 1
            }
          },
          {
            "id": "score",
            "type": "text",
            "text": "{homeScore}–{awayScore}",
            "style": {
              "font": "mono",
              "size": 36,
              "weight": 700,
              "color": "#0B0D1A",
              "bg": "#F4C266",
              "padding": [
                10,
                22
              ]
            }
          },
          {
            "id": "awayName",
            "type": "text",
            "text": "{awayName}",
            "style": {
              "size": 34,
              "weight": 700,
              "color": "#FFFFFF",
              "upper": true,
              "padding": [
                10,
                20
              ],
              "maxLines": 1
            }
          },
          {
            "id": "awayStripe",
            "type": "box",
            "w": 12,
            "children": [],
            "style": {
              "bg": {
                "param": "awayColor"
              }
            }
          }
        ]
      },
      {
        "id": "homeGoal",
        "type": "box",
        "anchor": "bottom-left",
        "x": 48,
        "y": 96,
        "direction": "row",
        "align": "stretch",
        "show": {
          "trigger": "homeGoal"
        },
        "enter": "slide-right",
        "style": {
          "radius": 14,
          "shadow": "strong",
          "bg": "#F4C266"
        },
        "children": [
          {
            "id": "homeGoalStripe",
            "type": "box",
            "w": 14,
            "children": [],
            "style": {
              "bg": {
                "param": "homeColor"
              }
            }
          },
          {
            "id": "homeGoalBody",
            "type": "box",
            "direction": "row",
            "gap": 24,
            "align": "center",
            "style": {
              "padding": [
                20,
                32
              ]
            },
            "children": [
              {
                "id": "homeGoalLabel",
                "type": "text",
                "text": "GOAL",
                "style": {
                  "font": "bricolage",
                  "size": 56,
                  "weight": 700,
                  "color": "#1A1405"
                }
              },
              {
                "id": "homeGoalTeam",
                "type": "text",
                "text": "{homeName}",
                "style": {
                  "size": 38,
                  "weight": 700,
                  "color": "#1A1405",
                  "upper": true,
                  "maxLines": 1
                }
              },
              {
                "id": "homeGoalScore",
                "type": "text",
                "text": "{homeScore}–{awayScore}",
                "style": {
                  "font": "mono",
                  "size": 36,
                  "weight": 700,
                  "color": "#1A1405"
                }
              }
            ]
          }
        ]
      },
      {
        "id": "awayGoal",
        "type": "box",
        "anchor": "bottom-left",
        "x": 48,
        "y": 96,
        "direction": "row",
        "align": "stretch",
        "show": {
          "trigger": "awayGoal"
        },
        "enter": "slide-right",
        "style": {
          "radius": 14,
          "shadow": "strong",
          "bg": "#F4C266"
        },
        "children": [
          {
            "id": "awayGoalStripe",
            "type": "box",
            "w": 14,
            "children": [],
            "style": {
              "bg": {
                "param": "awayColor"
              }
            }
          },
          {
            "id": "awayGoalBody",
            "type": "box",
            "direction": "row",
            "gap": 24,
            "align": "center",
            "style": {
              "padding": [
                20,
                32
              ]
            },
            "children": [
              {
                "id": "awayGoalLabel",
                "type": "text",
                "text": "GOAL",
                "style": {
                  "font": "bricolage",
                  "size": 56,
                  "weight": 700,
                  "color": "#1A1405"
                }
              },
              {
                "id": "awayGoalTeam",
                "type": "text",
                "text": "{awayName}",
                "style": {
                  "size": 38,
                  "weight": 700,
                  "color": "#1A1405",
                  "upper": true,
                  "maxLines": 1
                }
              },
              {
                "id": "awayGoalScore",
                "type": "text",
                "text": "{homeScore}–{awayScore}",
                "style": {
                  "font": "mono",
                  "size": 36,
                  "weight": 700,
                  "color": "#1A1405"
                }
              }
            ]
          }
        ]
      }
    ]
  }
}
```

### The weather: data from a public API, every 10 minutes

```json
{
  "spec": "beambubble.overlay/1",
  "meta": {
    "title": "Weather corner",
    "description": "Temperature, sky and wind in a town of your choice, and the next four hours. Updates every 10 minutes.",
    "orientation": "portrait",
    "category": "weather",
    "attribution": "Weather data by Open-Meteo.com"
  },
  "params": [
    {
      "id": "city",
      "label": "Town or city",
      "type": "text",
      "max": 60,
      "required": true,
      "example": "Göteborg"
    }
  ],
  "flow": [
    {
      "id": "place",
      "type": "http.json",
      "url": {
        "concat": [
          "https://geocoding-api.open-meteo.com/v1/search?count=1&language=en&format=json&name=",
          {
            "urlencode": [
              {
                "param": "city"
              }
            ]
          }
        ]
      }
    },
    {
      "id": "forecast",
      "type": "http.json",
      "every": "10m",
      "jitter": "30s",
      "url": {
        "if": [
          {
            "ref": "place",
            "path": "/results/0"
          },
          {
            "concat": [
              "https://api.open-meteo.com/v1/forecast?latitude=",
              {
                "ref": "place",
                "path": "/results/0/latitude"
              },
              "&longitude=",
              {
                "ref": "place",
                "path": "/results/0/longitude"
              },
              "&current=temperature_2m,weather_code,wind_speed_10m&hourly=temperature_2m&forecast_hours=5&wind_speed_unit=ms&timezone=auto"
            ]
          },
          null
        ]
      }
    },
    {
      "id": "hours",
      "type": "list",
      "from": "forecast",
      "items": {
        "slice": [
          {
            "zip": [
              {
                "var": "/hourly/time"
              },
              {
                "var": "/hourly/temperature_2m"
              }
            ]
          },
          1,
          5
        ]
      },
      "map": {
        "hour": {
          "slice": [
            {
              "var": "/0"
            },
            11,
            13
          ]
        },
        "temp": {
          "round": [
            {
              "var": "/1"
            }
          ]
        }
      }
    }
  ],
  "model": {
    "city": {
      "type": "text",
      "max": 40,
      "from": {
        "ref": "place",
        "path": "/results/0/name"
      }
    },
    "temp": {
      "type": "number",
      "min": -90,
      "max": 70,
      "from": {
        "round": [
          {
            "ref": "forecast",
            "path": "/current/temperature_2m"
          }
        ]
      }
    },
    "wind": {
      "type": "number",
      "min": 0,
      "max": 150,
      "from": {
        "round": [
          {
            "ref": "forecast",
            "path": "/current/wind_speed_10m"
          }
        ]
      }
    },
    "sky": {
      "type": "enum",
      "values": [
        "clear",
        "partly",
        "cloudy",
        "fog",
        "rain",
        "snow",
        "storm"
      ],
      "from": {
        "if": [
          {
            "==": [
              {
                "ref": "forecast",
                "path": "/current/weather_code"
              },
              null
            ]
          },
          null,
          {
            "==": [
              {
                "ref": "forecast",
                "path": "/current/weather_code"
              },
              0
            ]
          },
          "clear",
          {
            "<=": [
              {
                "ref": "forecast",
                "path": "/current/weather_code"
              },
              2
            ]
          },
          "partly",
          {
            "==": [
              {
                "ref": "forecast",
                "path": "/current/weather_code"
              },
              3
            ]
          },
          "cloudy",
          {
            "<=": [
              {
                "ref": "forecast",
                "path": "/current/weather_code"
              },
              48
            ]
          },
          "fog",
          {
            "<=": [
              {
                "ref": "forecast",
                "path": "/current/weather_code"
              },
              67
            ]
          },
          "rain",
          {
            "<=": [
              {
                "ref": "forecast",
                "path": "/current/weather_code"
              },
              77
            ]
          },
          "snow",
          {
            "<=": [
              {
                "ref": "forecast",
                "path": "/current/weather_code"
              },
              82
            ]
          },
          "rain",
          {
            "<=": [
              {
                "ref": "forecast",
                "path": "/current/weather_code"
              },
              86
            ]
          },
          "snow",
          "storm"
        ]
      }
    },
    "hours": {
      "type": "list",
      "max": 4,
      "item": {
        "type": "object",
        "fields": {
          "hour": {
            "type": "text",
            "max": 2
          },
          "temp": "int"
        }
      },
      "from": {
        "ref": "hours"
      }
    }
  },
  "layout": {
    "elements": [
      {
        "id": "card",
        "type": "box",
        "anchor": "top-right",
        "x": 48,
        "y": 160,
        "w": 520,
        "direction": "column",
        "gap": 16,
        "show": {
          "when": {
            "field": "temp",
            "op": "set"
          }
        },
        "style": {
          "bg": "#0B0D1ADB",
          "radius": 32,
          "padding": [
            32,
            36
          ],
          "shadow": "soft"
        },
        "children": [
          {
            "id": "cityName",
            "type": "text",
            "text": "{city}",
            "style": {
              "size": 34,
              "weight": 500,
              "color": "#D5D7EA",
              "maxLines": 1
            }
          },
          {
            "id": "now",
            "type": "box",
            "direction": "row",
            "gap": 24,
            "align": "center",
            "children": [
              {
                "id": "skyIcon",
                "type": "icon",
                "w": 96,
                "h": 96,
                "name": {
                  "field": "sky",
                  "map": {
                    "clear": "sun",
                    "partly": "cloud-sun",
                    "cloudy": "cloud",
                    "fog": "fog",
                    "rain": "rain",
                    "snow": "snow",
                    "storm": "storm"
                  },
                  "default": "cloud"
                },
                "style": {
                  "color": "#F1EFFA"
                }
              },
              {
                "id": "tempNow",
                "type": "text",
                "text": "{temp|int}°",
                "style": {
                  "font": "bricolage",
                  "size": 110,
                  "weight": 700,
                  "color": "#FFFFFF"
                }
              }
            ]
          },
          {
            "id": "windNow",
            "type": "text",
            "text": "Wind {wind|int} m/s",
            "style": {
              "size": 32,
              "color": "#D5D7EA"
            }
          },
          {
            "id": "hourList",
            "type": "list",
            "items": "hours",
            "direction": "row",
            "limit": 4,
            "template": {
              "id": "hour",
              "type": "box",
              "direction": "column",
              "align": "center",
              "w": 112,
              "gap": 4,
              "children": [
                {
                  "id": "hourLabel",
                  "type": "text",
                  "text": "{$item.hour}",
                  "style": {
                    "size": 26,
                    "color": "#A6A9C8",
                    "align": "center"
                  }
                },
                {
                  "id": "hourTemp",
                  "type": "text",
                  "text": "{$item.temp}°",
                  "style": {
                    "size": 30,
                    "weight": 700,
                    "color": "#FFFFFF",
                    "align": "center"
                  }
                }
              ]
            }
          }
        ]
      }
    ]
  }
}
```
