What Gerry shows on the page
Two things sit on top of your page: the face, in the corner, and — while a filter is being applied — a pointer layer that shows what Gerry just touched. Both are a tenant setting, changed in the panel and never in your code.
The face and its eight states
The default look is face: four orange blocks over a base block, a heavy outline, two round eyes, and no mouth, ever — the spoken sentence is the mouth, in a bubble under the stack. It drives all eight states off what the widget already knows about the call:
sleep | The call is stopped (or has errored out) and nobody's pointer or keyboard focus is on the control — the eyes sink behind the blocks. |
|---|---|
idle | Same, but the pointer is over the control or it has keyboard focus. |
thinking | Connecting — the lids sit at half, the pupils drift, the black centre cell blinks like a caret. |
listening | The call is live and the assistant isn't talking — a teal ring breathes and the blocks meter the visitor's own voice. |
speaking | The assistant is talking — the eyes bob with the audio level, the blocks run as a wave. |
acting | A command was just dispatched: the eyes look toward it and one block presses white. |
done | That command answered ok — all four blocks flash and the eyes close and open. |
refuse | That command failed, or the call errored — the lids angle, the stack shakes, then back to sleep. |
The eyes follow the visitor's pointer while idle, and everything about motion turns off under prefers-reduced-motion.
preview.html: every variant and tone, driven by Gerry.preview with no microphone and no real session.
The pointer — showing what Gerry is doing to the page
A filter in map mode changes the page in front of the visitor; the pointer layer is what makes that visible rather than mysterious. With it on, before the address is even fetched, the widget draws a cursor travelling to the control on YOUR page that corresponds to the filter, a ring on it, and a click — then, once the swap lands, a soft highlight over the region that changed.
| applies, clears or sorts a filter | a ring on the site's own control for it — the radio, the select, the price box, the facet link |
|---|---|
| follows a facet link the panel wrote | the same, on that link |
| opens a listing | the same, on that row |
| the results region swaps in | a soft highlight over the region that changed, and the ring moves onto the replacement control if the panel was swapped too |
Which control gets the ring is a ladder that stops at the first confident hit and otherwise draws nothing at all — a ring on the wrong row would say Gerry touched something it didn't. It never waits on the animation; the gesture plays while the underlying fetch runs, and it's off entirely under prefers-reduced-motion (the ring still appears, just without the travel).
Appearance settings
Changed in the panel's Appearance screen, with a live preview beside the form; a page in code mode may also pass its own, partial, appearance object that wins over the tenant's, the same way language does.
variant | face (default) · badge (the honey name plate it replaced) · button (a pill with a mic, no eyes) · minimal (a bare icon circle). |
|---|---|
tone | orange · honey · ink · teal · custom (uses accent). |
accent | A hex colour, only read when tone is custom. |
eyes | always · talking (default) · never. On face: always means the eyes never sink at rest; never keeps them sunk in every state but speaking, since with no mouth the eyes are the only thing that still reads as a voice. button and minimal have no eyes and ignore this. |
captions | auto (follows the page's colour scheme) · light · dark · off. Themes both caption bubbles and, on face, the sentence bubble under the stack. |
pointer | on (default) or off — the layer described above. |
position | bottom-right (default) or bottom-left. |
label | Text beside the control before a session opens; null uses the assistant's own name. badge and button show it; face has no name plate to write on and ignores it. |
offset | { x, y } in pixels from the corner, 0–80, default 20/20. |
Every tenant written before pointer or appearance existed parses to the defaults above — the face, in orange, with the pointer on — so nothing that shipped earlier changes underfoot.
Questions: hello@heygerry.io. These pages describe what is built today; nothing here is a promise about what is not.