A layout already says what matters: its controls. The glance block projects them onto every iOS surface *outside* the app — Home and Lock Screen widgets, the Dynamic Island, the lock-screen Live Activity banner, StandBy, the watch Smart Stack, CarPlay, and Control Center / the Action button — and keeps them live tiles bound to control ids.
Symbol
platter.filled.top.and.arrow.up.iphone
Docs
Docs complete
Fields
13 fields, each with what it does.
Fields
Field
Type
Default
What it does
enabledenabled
on / off
—
Turn all phone surfaces on or off
Setting false hides every surface outside the app, including the automatic glance; the default is on.
titletitle
text
—
The name shown on the surfaces
Sets the title on widgets and the Live Activity; falls back to the layout's header title or name.
iconicon
text
—
The layout's little picture
Sets the SF Symbol used in the Dynamic Island's leading slot and the widget header.
tinttint
text
—
The accent colour
Colours the surfaces with this hex accent; falls back to the layout's accent colour.
herohero
text
—
The one number that matters most
Picks the control whose value stands for the layout on the smallest surfaces, such as the compact island.
slotsslots
string[]
—
A few extra readings
Names up to 3 more controls whose values appear as secondary readouts next to the hero.
liveActivityliveActivity
on / off
—
Keep a live card on the lock screen
When true, a Live Activity (Dynamic Island and lock screen) runs while the layout is connected; the default is off.
controlscontrols
object[]
—
Buttons for Control Center
Declares the toggles and buttons offered in Control Center, the lock screen corners and the Action button, and allowed on the Live Activity row and larger widgets.
livelive
object
—
How fresh each surface stays
Sets a freshness tier plus per-surface update speeds and stale windows, which decides how often values refresh while the app is closed.
widgetswidgets
object[]
—
Home and lock screen widgets
Defines the widgets people can add, each built from tiles bound to your controls.
islandisland
object
—
What the Dynamic Island shows
Defines the compact, minimal and expanded Dynamic Island regions as tiles.
lockScreenlockScreen
object
—
The lock screen card
Defines the lock-screen Live Activity banner as a scene; when absent it reuses the island's expanded bottom.
warmOpenwarmOpen
on / off
—
Open with the last known values
When true, the layout opens showing its last glance snapshot (under 24 hours old) marked stale until live data arrives; false opens on defaults.
Examples
3 examples, each one a control you can paste into a layout.
while the app is closed or force-quit. The same JSON vocabulary as the layout:
Every field is optional. A layout with no glance block still gets a best-effort
glance (hero + slots picked from gauges, rings, lights and server-fed numerics,
plus Control Center tiles derived from its own buttons, toggles, sliders and
steppers). Add the block when you want to choose.
This page is the overview. Each surface has its own page with every field, a
machine-readable constraints block (per-family limits, allowed tiles, cadences) and
verified examples:
Control Center, lock-screen corners, Action button
toggle and button only — iOS has no slider or text control here. A slider becomes step/set buttons; a multi-state picker becomes a cycle button.
none
the user places every control by hand; the app can only offer them
Widgets (Home, Lock Screen, StandBy, CarPlay)
toggle, button, step tiles
numeric roll (numericText), symbol effects on change, timers
no scrolling, no free-running animation, refresh budgeted by iOS
Dynamic Island / lock-screen banner (Live Activity)
same interactive tiles (two-ish fit in the expanded bottom)
numeric roll, symbol effects on change, add/remove transitions, self-ticking timers and rings
4 KB of state per update; 8 h max session; the user can disable Live Activities per app
Custom withAnimation / .animation are ignored by the system on every one of
these surfaces. The effect, transition, timer and numeric tiles below are the
motion that does work — Apple's own choreography, keyed to your values.
Control Center controls (controls[])
Field
Type
Description
id
string
Stable id within the layout (the registry key is <layoutId>#<id>)
kind
string
toggle · button (default) · cycle · step · set
label / icon
string
Gallery + control appearance (SF Symbol)
control
string
Layout control this tile mirrors and drives. Required for cycle/step/set; optional for toggle/button. Its live value is what the tile shows, and by default its own action (with {{value}} substituted) is what a press sends.
event / payload
string / object
Explicit MeshSocket action instead of the bound control's ({{value}} substituted; toggles also merge {"value": <bool>})
on / off
object
{ "label", "icon", "tint" } styling per toggle state
valueControl
string
Show THIS control's formatted value as the toggle's value label (e.g. a lux reading beside the lights toggle)
valueLabel
string
Template over the value label; {{value}} is the bound (or valueControl) display value
states
object[]
cycle: { "value", "label", "icon", "tint" } in order; a press sends the next state and the button shows the current one
delta
number
step: added to the control's current value (negative to decrement), clamped to the control's min/max
value
any
set: the value sent
Presses work with the app closed: the control posts straight to the relay
(POST /mesh/broadcast) with the layout's own credential, exactly the frame the
in-app control would send. Offline presses queue for 24 h and deliver when the
layout next connects. The rendered state only flips once the relay confirms the
frame was published — a press that reached nothing is rolled back and reported.
Tiles
Widgets, the island and the lock-screen banner are all scenes: rows of tiles.
270° arc with a lit end cap / closed progress ring / linear bar, the reading inside or beside it
numeric with min/max
light
status dot + state text (statusColors)
statusLight or string
sparkline
recent history (up to 24 points)
numeric
text / icon / spacer
static label / SF Symbol / flexible space
— (an icon may bind a control whose string value names the symbol)
timer
a self-ticking clock counting to or from a unix-seconds value
numeric
freshness
LIVE pill, or the age ("14m") once the data is stale, or WAITING before anything arrived
—
toggle
interactive on/off, sends the control's action
toggle control
button
interactive press, sends the control's action (or inline event/payload)
button control
step
−/+ buttons (delta) or presets
slider / stepper
open
deep-links into the layout (tab optional)
—
Tiles are drawn in the app's Glass look on every surface: the reading dims when its
data is stale, and a value that never arrived shows a dashed track and no number.
Lock-screen accessory widgets draw the same tiles in the system's monochrome.
Tile field
Type
Description
control
string
Layout control id. Unknown id ⇒ the tile is omitted, never a crash
label, icon, tint, format
string
Overrides of the control's label / symbol / hex tint / formatValue
span
number
Columns spanned (default 1)
delta, presets, value, event, payload, tab
—
Per-tile action parameters (see the tile table)
effect
string
Symbol effect played once per value change: bounce (default for icons) · pulse · wiggle · rotate · breathe · variableColor
transition
string
When the tile appears or disappears: opacity (default) · slide · push · move
Widgets (widgets[])
Field
Type
Description
id
string
Stable id; the widget gallery offers "<title> · <layout>" per id
title / icon
string
Gallery name and glyph
families
string[]
Any of systemSmallsystemMediumsystemLargesystemExtraLargeaccessoryCircularaccessoryRectangularaccessoryInline
scene
object
The scene rendered for every family without an override
<family>
object
Optional per-family scene override, e.g. "systemSmall": { "rows": <span class="wikibroken" title="unresolved: …">…</span> }
Without an override, systemSmall renders the first row, accessoryRectangular
renders the first row as values, accessoryCircular the first gauge/ring/value,
and accessoryInline "label value" of the first bound tile.
The user adds the CAR-TER Scene widget and picks a scene; the zero-config
Layout Glance (hero + slots) and Control Value (any single control) widgets
remain for layouts that declare no widgets.
Dynamic Island and lock screen (island, lockScreen)
Region
Takes
Default
compactLeading
one tile
layout icon (bounces on update)
compactTrailing
one tile
the hero value / ring / dot
minimal
one tile
freshness ring around the connection dot
expanded.leading / .trailing / .center
one tile or a scene
icon + title / freshness / the LIVE session clock
expanded.bottom
a scene
hero + slot chips + hero sparkline + two controls
lockScreen
a scene
expanded.bottom
Requires "liveActivity": true (or live.activity.start). Keep the expanded
bottom to two rows — the island has a hard height budget and clips.
Liveness (live)
Tier
Live Activity (in app / remote)
Widgets
Controls
Cost
realtime
1 s / 2 s, immediate priority
pushed on change, ≥ 60 s apart
pushed on change
burns the Live Activity and widget budgets; for genuinely live sessions only
fresh (default)
1 s / 5 s, immediate
pushed on change, ≥ 5 min apart
pushed on change
safe indefinitely
periodic
1 s / 30 s, opportunistic
pulled every pullEvery (15 min)
pulled on system reload
near zero
manual
app-driven only
app-driven only
app-driven only
the old behaviour
Field
Type
Description
tier
string
Preset above; explicit fields override it
activity.cadence / .remoteCadence
number
Seconds between updates while the app is open / when pushed by the relay (floors 1 / 2)
activity.stale
number
Seconds until the surface marks its data stale (default 120, floor 30)
activity.priority
string
immediate (budgeted) or opportunistic
activity.start
string
onConnect (default) · remote (only a hub starts it, via push-to-start) · never
widgets.refresh
string
push (relay pokes the widget, iOS 26) · pull (widget fetches on its own schedule) · app
widgets.pullEvery / .stale
number
Seconds (floors 300 / 30)
controls.refresh
string
push (iOS 18) or app
background.silentPush
bool
Also wake the app with a silent push on relay updates (heavily throttled by iOS; off by default)
Floors are enforced by the app and the relay; the connection console shows the
granted cadence. A surface always shows how old its data is — a stale window ends
the LIVE clock and greys the freshness dot rather than pretending.
How values reach a closed app
Live Activity — the relay pushes the island directly (ActivityKit push, and
push-to-start for layouts the app is not showing).
Widgets (iOS 26) and Control Center controls (iOS 18) — the relay pokes
them with a "content changed" push; the surface then pulls the layout's latest
values from the relay's retained state.
Alert pushes — any alert rule fire also carries a glance refresh (the
notification extension applies it), which works even after a force-quit.
Bindings — the relay watches the layout's listen syncs on the mesh, so an
existing hub that just broadcasts telemetry drives every surface with no code
change (not available in end-to-end-encrypted rooms — there, the hub publishes
explicitly with hub.surfaces.publish(...) in carterkit).
Notes
Ids: the relay addresses a layout by its stable id; give shared layouts one.
Everything here is a request — the user places widgets and controls, may
disable Live Activities, and iOS budgets every refresh path.
Sliders, text entry, scrolling and continuous animation exist only inside the app.
Generated from ControlDocs/glance.md. Something unclear or missing? Tell me.