Skip to content
Vulpine
Esc
↑↓navigate↵open⌘Jpreview
On this page

Panel cards

The panel card (card.v1) the brain or a tool fills: one composite of a title, a spoken one-line summary, an optional headline number and one to four typed blocks (stats, list, chart, table, heatmap, timeline, progress, status, compare, breakdown, forecast, text), their bounds, the refusals with the path the brain must fix, the fallback ladder (an undeclared block as text, a table projection), the render frame's appended turn_id, and what the Admin shows.

Living doc, checked against the code 2026-11-14

panel-card.v1 — the panel the brain or a tool fills, drawn in the conversation

  • Status: landed on protocol 5, additive. The kind card.v1, its body CardSpec and the block kinds below are in the protocol crate. The gateway validates, bounds, degrades and projects cards; the brain’s pi_show_render sends them, and some tools fill their own panels.
  • Scope: the brain (through pi_show_render) or the tool that already holds the numbers fills one JSON card. The gateway checks it and relays it as the render frame, stamped with the turn it belongs to. Each frontend draws it with its own renderer. No HTML, no server-side rendering, no pictures, no colors, no layout, no URLs.
  • Relates to answer-card.v1: its render frame is the transport, and its closed schema is the model. A card is passive: it rides a reply and has no verbs.

What the brain fills

A card is one constrained composite with fixed slots, drawn in this order: a header (title, subtitle, a status flag), an optional headline number, one to four typed blocks, and a footer note. Panels vary the blocks, not the frame, so the brain learns one shape.

summary is the one line the reply says aloud whether or not a panel draws anything. It is also the card’s accessible name, the conversation log’s caption and the text fallback. Plain words, never an id or a hex token.

CardSpec, the body of card.v1

field type bound required
title string 1..=80, no hex token yes
subtitle string ≤ 80 no
summary string 1..=160, no hex token yes
flag {text, state} text 1..=24 no (the header’s right-hand flag)
headline {value, unit?, delta?, delta_unit?, better?, caption?} unit ≤ 16, delta_unit ≤ 8, caption ≤ 60 no (the big number)
blocks array of blocks 1..=4, drawn in order yes
note string ≤ 120 no (the footer’s provenance line)

Every text field refuses < and control characters, and a required one refuses blank text. Every number is finite. Every object refuses an unknown field. The card-wide budget is 720 numbers and cells across the headline and all blocks (series values, heatmap and table cells, tiles, rows, items, steps, parts; a compared row and a forecast day count two). The brain tool’s 7 KiB body cap also applies on its path.

Shared values

type wire rule
PanelValue a number or a string a finite number, or text 1..=24 ("1m 42s"), sent only when the value is not a number. The client formats numbers
unit string 1..=16 ("ms", "%", "°C", "$"). $ € £ are drawn before the number, any other unit after it
delta, delta_unit, better number, string ≤ 8, up or down the change, its unit (default the value’s unit), and which direction is good (default up), so a chip is tinted good or bad, not up or down
PanelState ok warn bad idle active pending done failed skipped one closed set for every block; the theme maps it
Sky clear partly cloudy fog drizzle rain snow sleet storm wind a forecast day’s icon key; the frontend owns the icons
ChartMark bar line area step how a chart block draws

The blocks (PanelBlockKind, internally tagged by type)

The block kinds are a second closed registry, versioned like the frame kinds; a version is never changed in place. table.v1 and heatmap.v1 reuse the frame kinds’ bodies, so a frontend that draws those kinds draws those blocks.

block body bounds
text.v1 {text} 1..=280. The degrade target every card client must draw
stats.v1 {tiles: [{label, value, unit?, delta?, delta_unit?, better?, of?, caption?, state?}]} 1..=6 tiles; label ≤ 40, caption ≤ 40; of > 0 makes the tile a meter (value of max)
list.v1 {rows: [{label, detail?, value?, unit?, delta?, state?, share?}], more?} 1..=12 rows; label ≤ 60, detail ≤ 80; share 0..=1 draws an inline bar; more draws “and N more”
chart.v1 {mark, x?, series: [{label, values}], unit?, stacked?, threshold?: {value, label?}, band?: {from, to, label?}, highlight?, forecast_from?} 1..=6 series, every series as long as the others (and as x when given), 1..=120 values each after the gateway’s downsampling; x labels ≤ 16; stacked for bar and area only; band.from ≤ band.to; highlight and forecast_from are indexes into the values
table.v1 {columns, rows} inside a card: 1..=6 columns, 1..=12 rows, cells ≤ 80
heatmap.v1 {title?, x_labels, y_labels, cells, unit?} as the heatmap.v1 kind (≤ 48 × 24, ≤ 600 cells), within the card budget
timeline.v1 {items: [{at, label, detail?, state?}], now_after?} 1..=12 items in the order given; at 1..=24 (a display time: "09:30", "Tue 14:00"); label ≤ 60, detail ≤ 80; now_after is the index after which the NOW line is drawn
progress.v1 {steps: [{label, state, detail?}], done?, total?} 1..=12 steps; label ≤ 40, detail ≤ 40; total ≥ the steps shown, done ≤ total (“3 of 12”)
status.v1 {items: [{label, state, value?, detail?}]} 1..=24 items (a grid); label ≤ 32, detail ≤ 40
compare.v1 {a_label, b_label, rows: [{label, a, b}], unit?, better?} column labels 1..=24, 1..=12 rows of finite numbers
breakdown.v1 {parts: [{label, value}], unit?, total?} 1..=8 parts, each ≥ 0; total ≥ their sum (else the sum). The producer folds the rest into “other”
forecast.v1 {unit, days: [{label, sky, high, low, precip_pct?}]} 1..=10 days, label ≤ 12, unit 1..=4 ("°C"); high ≥ low; precip_pct 0..=100
template.v1 {template, text, data, svg?} a curated template’s block, behind the gateway’s [panels] templates flag (off); see template.v1

Examples (synthetic)

A forecast card (what the weather tool would send):

{"title": "Week ahead", "subtitle": "five days", "summary": "Mild and dry until Thursday, then rain on Friday.",
 "flag": {"text": "rain Fri", "state": "warn"},
 "headline": {"value": 18, "unit": "°C", "delta": 3, "better": "up", "caption": "high today, warmer than yesterday"},
 "blocks": [{"type": "forecast.v1", "unit": "°C", "days": [
   {"label": "Mon", "sky": "clear", "high": 18, "low": 7},
   {"label": "Tue", "sky": "partly", "high": 21, "low": 9},
   {"label": "Wed", "sky": "cloudy", "high": 19, "low": 8},
   {"label": "Thu", "sky": "drizzle", "high": 15, "low": 5, "precip_pct": 40},
   {"label": "Fri", "sky": "rain", "high": 16, "low": 6, "precip_pct": 80}]}],
 "note": "forecast · updated 06:00"}

One block of each kind (each is one entry of a card’s blocks):

{"type": "text.v1", "text": "Latency is flat almost everywhere; two windows stand above the limit at the same hours each day."}
{"type": "stats.v1", "tiles": [
  {"label": "memory", "value": 61, "unit": "%", "of": 100, "state": "ok"},
  {"label": "disk free", "value": 212, "unit": "GB", "delta": -14, "better": "up"},
  {"label": "uptime", "value": "6d 4h"}]}
{"type": "list.v1", "rows": [
  {"label": "Water the plants", "detail": "due today", "state": "warn"},
  {"label": "Return the library book", "detail": "due Friday"},
  {"label": "Order filters", "detail": "overdue 2 days", "state": "bad"}], "more": 4}
{"type": "chart.v1", "mark": "bar", "x": ["Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"],
 "series": [{"label": "steps", "values": [6100, 7400, 5200, 9800, 8800, 12100, 4300]}],
 "unit": "steps", "threshold": {"value": 8000, "label": "goal"}, "highlight": 5}
{"type": "chart.v1", "mark": "line", "x": ["Mon", "Tue", "Wed", "Thu", "Fri"],
 "series": [{"label": "high", "values": [18, 21, 19, 15, 16]}, {"label": "low", "values": [7, 9, 8, 5, 6]}],
 "unit": "°C", "forecast_from": 1}
{"type": "table.v1", "columns": ["worktree", "state"], "rows": [["main", "clean"], ["lane-a", "2 uncommitted"]]}
{"type": "heatmap.v1", "x_labels": ["06", "09", "12", "15", "18", "21"], "y_labels": ["Mon", "Tue", "Wed"],
 "cells": [[0, 2, 5, 3, 1, 0], [1, 4, 6, 2, 2, 1], [0, 1, 3, 4, 2, 0]], "unit": "updates"}
{"type": "timeline.v1", "items": [
  {"at": "09:00", "label": "Planning", "state": "done"},
  {"at": "11:30", "label": "Walk", "state": "active"},
  {"at": "14:00", "label": "Review", "detail": "45 min"},
  {"at": "17:30", "label": "Dinner"}], "now_after": 1}
{"type": "progress.v1", "steps": [
  {"label": "build", "state": "done", "detail": "4 min"},
  {"label": "review", "state": "active"},
  {"label": "test", "state": "pending"}]}
{"type": "status.v1", "items": [
  {"label": "host one", "state": "ok", "value": "load 2.4"},
  {"label": "host two", "state": "ok", "value": "load 3.1"},
  {"label": "host three", "state": "bad", "detail": "not answering"}]}
{"type": "compare.v1", "a_label": "last week", "b_label": "this week", "unit": "h", "better": "up",
 "rows": [{"label": "sleep", "a": 6.8, "b": 7.3}, {"label": "focus", "a": 18, "b": 15}]}
{"type": "breakdown.v1", "unit": "agents", "parts": [
  {"label": "busy", "value": 7}, {"label": "awaiting input", "value": 3}, {"label": "done, unseen", "value": 2}]}

The brain may leave the version off a block type: the tool stamps a bare type with its current version (status becomes status.v1). The wire is always versioned. An unknown bare type is left as written, for the gateway to refuse:

{"kind": "card.v1", "body": {"title": "Fleet right now", "summary": "Two hosts are up and one is not answering.",
  "blocks": [{"type": "status", "items": [{"label": "host one", "state": "ok"}, {"label": "host two", "state": "ok"},
  {"label": "host three", "state": "bad", "detail": "not answering"}]}]}}

The frame

A card rides the render frame, with one optional field appended:

{"type": "render", "render_id": "render-7", "kind": "card.v1", "status": "complete", "ttl_ms": 300000,
 "turn_id": "00000000-0000-4000-8000-0000000000a1",   // appended, optional
 "data": { /* CardSpec */ }}

The gateway stamps turn_id, never the producer: a render from pi_show_render carries the turn its call was made in. The preview door and the gateway-events bar carry none. The conversation log places a panel under its turn; a frame without one binds to the turn in flight. The Client Core relays it as RenderFrame.turnId (null when absent), and the native client crate as RenderFrame.turn_id.

Negotiation and the fallback ladder

A frontend lists the frame kinds and the block kinds it draws in render_kinds. Unknown names are ignored, so an older gateway ignores the block ids. The gateway then sends a card:

  1. to a frontend that declared card.v1, with each block whose kind it did not declare replaced by a text.v1 block holding that block’s one-line text (panel_block_text: stats → “memory 61 %, disk free 212 GB, uptime 6d 4h”; a list → its first three labels and “and N more”; a chart → each series’ last value; progress → “review active, 1 of 3 done”; and so on, at most 160 characters). The trace row render_sent gains blocks and degraded;
  2. else to a frontend that declared table.v1, as a table.v1 projection under the same render id (card_table: two columns item and value, a row for the headline, then each block’s rows, at most 50). The trace row is render_projected {from, to}, and the frontend’s receipt speaks for the table;
  3. else nowhere: render_dropped {reason: undeclared}, as for any kind. Nothing is lost: the reply says the summary.

Downsampling: a line, area or step chart block with no x and 121 to 600 values per series is reduced to 120 by LTTB. The kept positions are chosen on the first series and every series keeps the same ones; highlight and forecast_from move to the kept position at or before theirs. A bar block, or any series with x, over 120 is refused.

Errors

The gateway refuses a card before relay with one of the closed render refusals and where, a path of field names and indexes joined by dots, so the brain can fix its body:

refusal example at
over_limit five blocks blocks
over_limit more than 720 numbers and cells blocks
empty no blocks blocks
bad_text a hex token in the summary summary
bad_text markup in the title title
shape_mismatch x shorter than the series blocks.0.x
empty a list with no rows blocks.1.rows
shape_mismatch an unknown block type (the body does not parse) blocks.2.type
shape_mismatch an unknown field in a block blocks.0.color
over_limit a share over 1, a high under the low, an index past the values blocks.0.rows.1.share, blocks.0.days.2.low, blocks.0.highlight
not_finite a NaN in a Rust producer’s series blocks.0.series.0.values.3

pi_show_render’s answer is render_shown {kind, outcome, reason, waited_ms, at?, projected_to?, degraded?}: at on a refused card; projected_to: "table.v1" when the card reached a panel as its table; degraded when one or more blocks reached it as text. The tool says “It is on the panel.” only for drawn (“It is on the panel, as a table.” for a projection). Each refusal case has a file in benchmarks/fixtures/panel-card.v1/invalid/.

The brain has one pi_show_render call open at a time. It closes when the brain’s turn ends or is cut, as a producer’s call does, so a result that never came does not block later panels. A panel already sent stays until its ttl_ms. A late show_render from the closed call is refused as brain_tool_call_or_continuity_mismatch. The close is a show_render_call_closed trace row and an Admin timeline row. close_turn_tool_calls in crates/voice_gateway/src/ws/state/lifecycle.rs closes every per-turn call at the turn’s end and at its cut. The Render card counts the closed pi_show_render calls (AdminRenderRouting.calls_closed).

Panels the tools fill

A tool that already holds the numbers builds its own card and puts it up with no pi_show_render call. The brain spends no tokens on it, and the numbers never pass through the model. The producers are a closed list in the gateway (PANEL_PRODUCER_TOOLS in crates/voice_gateway/src/routing.rs):

tool card built from
pi_utility (weather) “Next N days”: a forecast.v1 block of up to five days (open-meteo’s weather codes mapped to Sky, highs and lows rounded, the rain chance), today’s reading as the headline, a flag for storms or a day of 50 % rain or more. With no forecast asked, “Weather now”: the reading as the headline and a stats.v1 block (the sky, the wind) the open-meteo answer the tool already fetched
pi_fleet_status “Fleet right now”: a stats.v1 block (waiting on you, busy, finished unseen, errors) and a status.v1 grid of the hosts, worst first (bad for an agent in error or a failed CI run, warn for one waiting on the operator, active, done, ok) the gateway’s own fleet snapshot
brain_vulpine_report Per topic: “Reply time by hour” (a chart.v1 of the median and 90th percentile per hour, the slowest hour highlighted, and a stats.v1 block); “Nightly, ” (counts and a list.v1 of the suites that did not pass); “What went wrong”, “Connections”, “Vulpine health”, “What gets used” (stats.v1 with a list.v1 or status.v1) the card the gateway builds in crates/voice_gateway/src/vulpine_report.rs and answers over the Admin socket; the tool relays it unchanged
pi_house_now “House now”: a stats.v1 block, a status.v1 grid of the rooms and a timeline.v1 of recent camera events, with a flag when home is unknown or a camera stalled the house document the gateway answered (catalog/pi/extensions/vulpine-tools/house_now.ts)
pi_feeds (unread) “Unread in your feeds”: a links.v1 panel of the items the tool listed (the title, the feed; at most 12, “and N more” for the rest), the tool’s counts as the summary. A frontend that does not declare links.v1 gets it as a card.v1 list. The titles are the sites’ own words, drawn as plain text and never sent back to the brain the feedctl answer the tool already read (catalog/pi/extensions/vulpine-tools/feeds.ts, feeds_links.ts)
pi_github (stars, repo_read) “Your recent stars”: a list.v1 of the newest stars (the name, the language and description, how long ago). A starred repo: stats.v1 (files, folders, stars, README words), its top folders as a list.v1, its language mix as a breakdown.v1 and its description as a text.v1. The tool’s other actions send no card the gh api answers the tool already read (catalog/pi/extensions/vulpine-tools/github/stars.ts)

The builders are catalog/pi/extensions/vulpine-tools/panels.ts (GitHub’s in catalog/pi/extensions/vulpine-tools/github/stars.ts). Their cards from synthetic inputs are in benchmarks/fixtures/panel-card.v1/tools/.

  • One panel per open call. When the brain calls a producer, the gateway registers the call with the turn it was made in. While the call is open it accepts ONE show_render line on the mutation socket under that call’s id (the same line pi_show_render sends), stamps the call’s turn on the frame, and routes it like any card. A second panel from the call, a panel after the tool answered or after the brain’s turn ended, a call of another continuity, and any tool off the list are refused as brain_tool_call_or_continuity_mismatch. At most four producer calls are open at once.
  • Never in the way. The gateway answers a producer’s panel at once with where it went (sent, dropped + undeclared, or refused with the reason and at), never on the panel’s receipt. The tool waits at most 750 ms for that word. The tool’s own answer is the same with or without a panel. A brain with no mutation socket gets no panel. The panel’s receipt reaches the router and the Admin row when it comes.
  • What the brain is told. The tools’ descriptions and the voice prompt’s pi_show_render line say they put their own card up. The brain never sends a second one for the same numbers, and says the answer in words as usual.
  • One card per subject per turn. An older forecast card never shows beside the current one. A card whose subject an earlier card of the same turn already showed goes out under that card’s render id, and every frontend replaces the older card in place (crates/voice_gateway/src/render_subject.rs; trace row render_replaced {subject}). The subjects are closed: only the forecast (a card carrying a forecast.v1 block). Another turn’s card, a card with no subject and a render bound to no turn keep their own ids. A frontend receipts a complete body that replaces a different complete body of the same id (the Glyph look’s panel stack; Vigil receipts every frame), so the brain’s call hears drawn.

template.v1: a curated template’s block

A block can be a curated panel template (ADR 0045): a folder under catalog/panels/ holding a Typst template.typ, its schema.json, a sample.json and a README. A new panel is a folder, not a block kind plus a builder plus a renderer per client. The producer names the template and fills its data. It never writes markup and never sends a drawing.

field type bound who fills it
template string [a-z][a-z0-9-]*, ≤ 40: the folder’s name the producer
text string 1..=160, no hex token: the block’s accessible name and its degrade line the producer
data object the template’s schema.json (a closed JSON Schema subset), the card’s text rule on every string, the card’s budget the producer
svg {dark, light, width, height} each drawing ≤ 384 KiB, one inert <svg> (no script, foreign object, handler or outside link); sides 1..=2000 pt the gateway: a producer’s own svg is refused at blocks.N.svg

The gateway, with [panels] templates = true:

  1. checks the block’s shape with the card (validate_card_at: the name, the line, an object for data);
  2. checks data against the template’s schema, refusing with the card’s closed reasons and where: blocks.0.data.days.2.color (shape_mismatch, a field the schema does not name), blocks.0.data.counts.busy (over_limit), blocks.0.data.hosts (empty), blocks.0.data.hosts.1.detail (bad_text). An unknown template, a template’s own assert or any compile fault is shape_mismatch at blocks.N.template, and a missed deadline is over_limit there;
  3. for a frontend that declared template.v1, compiles the template with the data in the sandbox (crates/panel_templates: the folder and the kit in memory, no file system, no network, no clock, a deadline), once per scheme with the panel kit’s dark and light tokens, and fills svg. A frontend that did not declare it gets the block as text.v1 holding text (degrade_card), as for any undeclared block.

With the flag off (the default) a template block is refused at blocks.N.type. The trace rows are render_template_compiled {template, compile_ms, cached, svg_bytes} and render_template_refused {template, reason, detail} (the compiler’s word, never the data). A client draws the scheme its look asks for as an image (the panel kit: porcelain the light drawing, the other looks the dark one), never as inline markup. Vigil and Glyph draw it but do not declare it by default (UNDECLARED_BY_DEFAULT; Vigil’s ?declare=template declares it).

The forecast and fleet panels are templates too (catalog/panels/forecast, catalog/panels/fleet-status), with their cards in benchmarks/fixtures/panel-card.v1/templates/. The tools send the native blocks.

Which frontends get panels

pi_show_render is allowed in the loadouts that any frontend with a screen binds: vigil.toml (Vigil binds vigil by default), laptop.toml and loadout.toml, the default loadout. A frontend that binds default and declares no render kinds (a satellite, the TUI) gets the tool’s “the panel here cannot show that” answer at once.

Vigil draws cards with the panel kit. Its hello declares card.v1 and its block kinds by default (VIGIL_DECLARED_KINDS in apps/vigil/src/render/registry.tsx); ?declare=card changes nothing. The table.v1 and heatmap.v1 blocks share their ids with the frame kinds whose bodies they reuse, so declaring the heatmap block also declares the heatmap frame kind. Vigil leaves heatmap.v1 out by default, and a card’s heatmap block reaches it as its one line of text. ?declare=heatmap declares both. Vulpine.app’s Glyph look declares card.v1 and the block kinds the panel kit draws (GLYPH_RENDER_KINDS in apps/glyph/src/panels/draw.tsx).

Compatibility

  • The protocol stays version 5. RenderComponentKind::Card, RenderData::Card and ServerEvent::Render.turn_id are appended. The TypeScript bindings are generated by ts-rs.
  • An older frontend never declares card.v1, so it never gets a card; one that declared table.v1 gets the projection. An older Vigil that gets one anyway keeps the kind a string and draws its fallback card.
  • An older gateway sends no turn_id; the Client Core reads null.
  • PanelBlock::Template, TemplateBlock and TemplateSvg are appended (the thirteenth block kind, template.v1). An older frontend never declares it, so it gets the block’s line. An older gateway refuses a template block (blocks.N.type, an unknown block type).
  • An older gateway answers pi_show_render {kind: "card.v1"} with refused + unknown_kind. The tool’s answer parse accepts the new fields only in their exact shapes.
  • The Admin’s render row names frame kinds only: card.v1 counts there like any kind, with last_kind: card.v1 even when the card went as its table. Block ids never enter AdminRenderRouting.kinds: the Admin validator refuses a name the frame registry does not know.

The Admin

The Admin draws no card. A card moves the Presentation section’s “Render panel” counters like any render: sent or dropped, the receipts, the last kind (card.v1), its producer (tool for pi_show_render and for a tool’s own card alike) and its outcome. A refused card is an event-timeline row (gateway.render, render_refused) with the closed reason. So is a pi_show_render call closed at its turn’s end with no result (gateway.render, show_render_call_closed). The “Render panel” block counts those closes since the frontend bound, in amber: “calls closed with no result: 2 at turn end · 1 cut — last 4s ago” (calls_closed {turn_end, turn_cut, last_at_ms} on the row, absent until the first close).

Was this page helpful?