Glance block reference

Glance blocks are the vocabulary of result cards, attached at runtime via glanceResult([...]). This page is exhaustive; the renderer silently drops anything off-schema, so treat every cap as hard.

Global rules

1–3 blocks per card; at most one chart (bars, line, splitBar) — extras are dropped, not truncated.
Every string is trimmed and must be non-empty; every number must be finite.
tone is always "neutral" | "good" | "bad" — a meaning, not a color. The renderer owns hues.
Glance cards render on the notch’s dark glass; there is no light variant on this surface.
One failing block never sinks the card (per-block error boundaries), and one invalid block never invalidates its siblings — it’s dropped and counted.

Prop	Type	Required	Cap
`icon`	glyph name	—	allowlist
`appIcon`	`string`	—	1–40 chars; wins over `icon`
`title`	`string`	✅	1–60 chars
`trailing`	`string`	—	1–40 chars, right-aligned

appIcon renders a real app logo (e.g. "notion") — but only when the visible title starts with that app’s name; otherwise the slot is dropped so one brand can’t wear another’s icon.

`stats`

Prop	Type	Required	Cap
`items`	array	✅	1–3 items
`items[].label`	`string`	✅	1–48 chars
`items[].value`	`string`	✅	1–20 chars — pre-format numbers
`items[].delta`	`string`	—	1–12 chars; colors by sign (`-` red, `+` green)
`items[].tone`	tone	—	colors the value

Wraps to a second line before truncating.

`bars` ^chart

Prop	Type	Required	Cap
`title`	`string`	—	1–60 chars
`labels`	`string[]`	✅	2–7 items, each 1–12 chars
`values`	`number[]`	✅	same length as `labels`; each ≥ 0
`unit`	`string`	—	1–8 chars; `$ ¥ € £` prefix, others suffix

Every bar carries its value label; the series switches to compact form (16K, 1.2M) when exact numbers would collide.

`line` ^chart

Prop	Type	Required	Cap
`title`	`string`	—	1–60 chars
`points`	`number[]`	✅	2–60 finite numbers (negatives allowed)
`start` / `end`	`string`	—	1–16 chars; x-axis edge labels
`unit`	`string`	—	1–8 chars
`tone`	tone	—	tints the trend green/red
`baseline`	`number`	—	dashed reference line, pulled into range

The latest value is always called out.

`splitBar` ^chart

Prop	Type	Required	Cap
`title`	`string`	—	1–60 chars
`unit`	`string`	—	1–8 chars
`segments`	`[label, value][]`	✅	2–4 tuples; label 1–20 chars; value ≥ 0

Segment colors are assigned by index (blue → teal → purple → neutral) — never by the author, and never green/red, so composition can’t be confused with good/bad. Sliver segments are floored at ~2% so they stay visible.

`progress`

Prop	Type	Required	Default	Cap
`style`	`"bar" \| "ring"`	—	`"bar"`	—
`value`	`number`	✅	—	≥ 0
`max`	`number`	—	`100`	> 0
`label`	`string`	—	—	1–60 chars
`icon`	glyph	—	—	allowlist; ring shows it in the center instead of the %
`tone`	tone	—	neutral	—

max defaults to 100, not 1 — { "value": 0.4 } renders as 0%. Send { "value": 40 } or set max explicitly.

`list`

Prop	Type	Required	Cap
`header`	`string`	—	1–60 chars
`rows`	array	✅	1–6 rows
`rows[].icon`	glyph	—	allowlist
`rows[].appIcon`	`string`	—	1–40 chars; wins over `icon`; same title-match gate as `header`
`rows[].title`	`string`	✅	1–60 chars
`rows[].subtitle`	`string`	—	1–72 chars
`rows[].trailing`	`string`	—	1–24 chars
`rows[].badge`	`{ text, tone? }`	—	text 1–24 chars

badge and trailing are mutually exclusive at render time — a badge wins. A subtitle that repeats the badge text is dropped automatically.

`keyValue`

Prop	Type	Required	Cap
`pairs`	`[label, value][]`	✅	1–5 tuples; label 1–32, value 1–64 chars

`clock` ^live

Prop	Type	Required	Default
`tz`	IANA timezone	—	local time
`label`	`string` (1–60)	—	city from `tz`, else “Local”
`style`	`"analog" \| "digital"`	—	`"analog"`

Ticks every second. An unknown timezone falls back to local time and relabels itself “Local” rather than showing a wrong city.

`countdown` ^live

Prop	Type	Required	Cap
`until`	ISO-8601 datetime	one of	— (no cap)
`seconds`	`number`	one of	> 0, ≤ 2,592,000 (30 days)
`label`	`string`	—	1–60 chars

Exactly one of until / seconds is required. Prefer until — an absolute target survives remounts. The 30-day cap applies to seconds only; a far-future until renders honestly (168d 04:30). Turns green at zero.

`badges`

Prop	Type	Required	Cap
`items`	`{ text, tone? }[]`	✅	1–3; text 1–24 chars

`divider`

{ "type": "divider" } — no props.

`row`

Prop	Type	Required	Cap
`children`	leaf blocks	✅	2–3 children

Lays children side by side. Rules: rows never nest, widget can’t be a child, and at most one chart per row (it consumes the card’s chart budget). Children size themselves two ways:

Behavior	Blocks
Stretch to fill the space	charts, `list`, `stats`, `keyValue`, bar-style `progress`
Hug their content	rings, `clock`, `countdown`, `badges`

The sandboxed escape hatch — see Custom widgets.

Prop	Type	Required	Cap
`html`	`string`	✅	1–131,072 chars
`height`	`number`	—	60–420 (default 180)
`data`	JSON-serializable	—	≤ 16,384 chars serialized
`label`	`string`	—	1–60 chars (frame’s accessible title)

Not available to the model — only integration tool results can carry one. Cannot sit inside a row.

Glyphs

The 34-name allowlist for every icon prop:

calendar clock timer bed car mail message music sun moon cloud rain star
folder file globe pin phone person heart bolt check x mic note list
battery chart dollar home wifi coffee plane sparkle

Unknown names invalidate the block. Rendered as stroked template icons that inherit the surrounding ink color.

Parse & degradation semantics

The wire format is { "blocks": [...] } under the _voiceos_glance key of your tool’s JSON result; VoiceOS strips it before the model reads the result.
Invalid blocks are dropped individually; a card with zero valid blocks is dropped whole.
After validation, the first 3 blocks survive and the first chart consumes the chart budget; the rest are dropped.
Extraction caps the whole glance payload at 32,000 chars — raised to 96,000 when a widget block is present.

Get started

Building blocks

Custom widgets

Ship it

Reference

Glance block reference

Global rules

`header`

`stats`

`bars` ^chart

`line` ^chart

`splitBar` ^chart

`progress`

`list`

`keyValue`

`clock` ^live

`countdown` ^live

`badges`

`divider`

`row`

`widget`

Glyphs

Parse & degradation semantics

​Global rules

​header

​stats

​bars chart

​line chart

​splitBar chart

​progress

​list

​keyValue

​clock live

​countdown live

​badges

​divider

​row

​widget

​Glyphs

​Parse & degradation semantics

Global rules

`header`

`stats`

`bars` ^chart

`line` ^chart

`splitBar` ^chart

`progress`

`list`

`keyValue`

`clock` ^live

`countdown` ^live

`badges`

`divider`

`row`

`widget`

Glyphs

Parse & degradation semantics