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

Answer cards

Draft: the closed card (list, metric, camera still, approval pointer) Glyph shows beside a spoken answer.

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

answer-card.v1 — what the desktop app shows beside a spoken answer

  • Status: draft, design only for the four card types (list, metric, camera_still, approval): no type, frame or renderer exists for them. Live: the render frame, its kinds, the render receipt, the preview door and the brain’s pi_show_render with card number grounding.
  • Pattern: json-render. The model fills a closed schema and the client owns the rendering. The brain never sends HTML, CSS, script or a layout.
  • Relates to proactive-card.v1, which says what Vulpine may say unprompted. An answer card is passive: it rides a reply the operator asked for, and it has no verbs.

Why

A spoken answer stays short. A calendar, a camera list or a feed has a list behind it that is tiring to hear in full. The voice says the summary and the panel shows the rest. The spoken reply is the same whether or not anything renders: a frontend without a panel (a room speaker) drops the frame and loses nothing it needs.

The card types (not built)

The design’s four card types and its brain tool pi_show_card are not built. Today a brain shows a list or a metric as a card.v1 render (panel-card.v1) through pi_show_render.

The render frame

The gateway sends ServerEvent::Render {render_id, kind, data, status, ttl_ms?, turn_id?} only to a frontend that declared kind.

  • render_id is minted by the gateway. A later render with the same id replaces the earlier one in place.
  • status is partial (the body is still growing: draw it and expect more) or complete (final, the default).
  • ttl_ms is 5 000..=600 000 when present. Absent, the render stays until it is replaced or dismissed.
  • turn_id is the turn of the producer’s open tool call, stamped by the gateway. It is absent for the preview door and the gateway-events bar.

Kinds

RenderComponentKind is a closed, versioned registry. A new kind, or a new version of a kind, is a new variant; a version never changes in place. The kinds are bar.v1, sparkline.v1, table.v1, line.v1, heatmap.v1, card.v1 (panel-card.v1), visual.v1, file.v1, page.v1 and links.v1. The last four have their own contracts. The chart, table and heatmap bodies:

kind body bounds
bar.v1 ChartSpec, each series takes values (one bar per series; several values make a group) ≤ 24 series, ≤ 24 values each
sparkline.v1 ChartSpec, values or points ≤ 6 series, ≤ 120 points each after downsampling
line.v1 ChartSpec, values or points ≤ 6 series, ≤ 600 points each after downsampling
table.v1 TableSpec {columns, rows}, plain-text cells, every row as wide as columns ≤ 12 columns, ≤ 50 rows
heatmap.v1 HeatmapSpec {title? (≤ 80), x_labels, y_labels, cells, unit? (≤ 16)}, cells[row][column], one row per y_labels entry, every row as wide as x_labels ≤ 48 columns, ≤ 24 rows, ≤ 600 cells

ChartSpec is {title? (≤ 80), series: [{label (1..=40), points?: [{x, y}], values?: [...]}], unit? (≤ 16)}. A series has exactly one of points and values. Heatmap labels are 1..=40 characters. Every body refuses unknown fields, so it carries no color, no HTML and no layout. The theme owns color, and maps a heatmap’s values to a scale. A text field refuses < and control characters. A number must be finite.

Negotiation and downsampling

A frontend declares the kinds it draws in FrontendCapabilities.render_kinds. The declaration holds for the whole connection, across start_session. At hello the gateway writes render_kinds_declared {kinds, blocks}: the frame kinds it kept and the number of block kinds.

For an undeclared kind, or a body that fails its kind, the gateway drops the render and writes render_dropped {kind, reason}. reason is undeclared or the body’s refusal: shape_mismatch, empty, over_limit, bad_text, not_finite or bad_envelope. A sent render writes render_sent {kind, points_in, points_out}. No trace row carries a body.

The gateway runs LTTB on a line or sparkline series over its cap before it validates and relays it. LTTB keeps the first and last points and the largest-triangle point of each bucket. A heatmap is never downsampled.

A frontend’s registry maps every kind to a renderer. An unknown kind, or a body of the wrong shape, becomes a fallback card. Vigil declares bar.v1, sparkline.v1, table.v1, line.v1, card.v1 and page.v1.

The render receipt

A frontend answers each render with the client frame render_receipt {render_id, kind, outcome, reason?}:

  • outcome: drawn (its renderer drew the body), refused (its registry drew the fallback card) or dropped (it never showed the render).
  • reason: unknown_kind, bad_body, render_failed, bad_envelope (the Client Core refused the envelope) or no_panel. A drawn receipt carries no reason.

render_receipt is an additive ClientControl variant. The Client Core sends an additive control only to a gateway whose hello offers the feature of the same name. Otherwise it drops the control with one control_not_offered trace per type.

The session’s render router keeps the latest outcome for each of the newest 32 render ids: sent (no receipt yet), dropped + undeclared, refused + the body’s refusal, or the frontend’s receipt. A receipt for an id not sent on that connection is refused (unknown_render) and counts nothing. The trace row is render_receipt {render_id, kind, outcome, reason}. Producers read the outcome with RenderRouter::outcome, so a reply never claims a chart that did not land.

The Admin

The Presentation panel shows a “Render panel” card per connection (AdminPresentationSession.render_routing, an AdminRenderRouting): the declared kinds, renders sent and dropped since bind, the last render with its age, and the receipt counts (receipts, optional):

frontend: drawn 3 · refused 1 · dropped 0 — last refused bar.v1 (bad_body)

The line is a warning when the last receipt was not drawn. last_producer (optional) names who drew last, read from the render id: preview, gateway_events, tool (pi_show_render) or brain (a render with no id). The Admin validator refuses any other word. calls_closed (optional) counts pi_show_render calls closed with no result because their turn ended (turn_end) or was cut (turn_cut).

A render the gateway refused (not an undeclared drop), and a refused or dropped receipt, also make a row on the Admin event timeline: component gateway.render, phase render_refused or render_receipt_refused, with the kind and the closed reason. Rows are coalesced over a minute for each side.

The gateway-events bar

With [frontend] render_gateway_events = true (default false), the gateway sends a bar.v1 of its Admin event timeline’s rows per component over the last [frontend] render_gateway_events_minutes (default 15). It sends the bar when a declaring frontend binds, and again on get_state when the counts changed.

The preview door

vulpine-glyphctl render <kind> --file <body.json> [--ttl <secs>] and vulpine-glyphctl render --sample <kind> post a render to the gateway’s render_preview door. The gateway answers this invoke_tool itself; it is not a brain tool. It answers only when [frontend] render_preview = true (default false). --sample sends the Vigil showcase’s sample body (apps/vigil/src/render/samples.json).

  • Input. {kind, data, ttl_ms?}. The kind must be in the registry. The body is downsampled, then checked against the kind like any producer’s body. A refusal answers with the closed reason.
  • The board. An accepted preview goes on the preview board as render id preview, so a later preview replaces it. The calling connection draws it at once when it declared the kind. The post also wakes every bound connection that declared a render kind, which offers the preview at once (trace row render_preview_nudged).
  • The answer. The door answers when a panel’s receipt for the post arrives, from any connection, or after 7 s without one. Its details carry this_frontend, receipt (drawn, refused, dropped or none), receipt_reason and waited_ms, and its message says it in words (“drawn: a panel drew the bar.v1 preview”). The board keeps the newest receipt per post; a drawn post stays drawn when another panel refuses it. The trace row is render_preview_answered {kind, seq, receipt, waited_ms}.
  • The CLI. vulpine-glyphctl render prints the receipt word alone on its first line, then the door’s JSON line. It exits 1 on a door refusal or when a panel refused or dropped the render, else 0 (none is 0).

The brain’s render tool

pi_show_render {kind, body} is a pi_* tool in catalog/pi/extensions/vulpine-tools (show_render.ts). A loadout allows it per client.

  • It sends show_render {kind, data} over the mutation socket. The socket’s line bound is 8 KiB, and the tool refuses a body over 7 KiB before it sends.
  • The gateway answers only an open call of this continuity. It parses the kind and the body, mints a render id and routes the render through the session’s RenderRouter, like any producer’s render.
  • A gateway refusal or an undeclared drop answers at once. A sent render waits up to 3 s for the panel’s render_receipt.
  • The answer is render_shown {kind, outcome, reason, waited_ms}. outcome is drawn, refused or dropped with the closed reason, or sent + no_receipt when the panel never confirmed it. The trace row is show_render_answered {kind, outcome, reason, waited_ms}.
  • The tool says “It is on the panel.” only for drawn. The voice system prompt tells the brain the panel is never spoken: the reply says the answer in words, “on the panel” only for drawn, the reason and the numbers aloud for refused or dropped, and no claim for sent + no_receipt.

The brain’s rule prefers card.v1. The chart, table and heatmap kinds also work alone.

Card number grounding

The gateway relays a pi_show_render card only when every number written in its text fields is grounded. Otherwise it refuses the card, and the spoken reply goes out unchanged. [frontend] card_number_grounding is on by default; false turns off the check and the grounds. The tool’s description tells the brain: “Restate a tool’s numbers; never compute new ones in a card.”

  • The grounds. The session’s last 16 brain tool results, as they came. From each: every JSON number, every number written in a string, and every array’s length (a list of three hosts grounds “3 hosts”), up to 2 048 numbers and 64 KiB of text. A panel-producing tool’s own panel counts as its result. The card’s own array lengths count too (“Top 3” over three rows).
  • The turn’s own words. The prompt the gateway writes to the brain (the operator’s words, the turn and session context, retrieved evidence, a capture’s block) and every brain tool call’s arguments, except a show-render call’s own. They sit apart from the 16 results, at most 16 in one turn, and are dropped when the next turn’s prompt starts. In a prompt, spelled numbers count: zero to nineteen, the tens, and a tens word with a unit word (twenty-five). A result’s, a call’s or a card’s spelled numbers do not.
  • Numbers on the card. A digit run that is a word of its own: 3, 1234, 1,234 (commas only between groups of three), 12.5, .5, and digits followed by letters (5km, 10am, 3rd). Not numbers: a word that starts with a letter (v1, Qwen3), a word whose digits resume after its letters (4f9c2ab1), a dotted version (3.11.2), and a list marker (one or two digits that start a line, then . or ) and a space: 1. Rome). A time or a date is read as its parts (14:30, 2026-11-05, an ISO T). An hour followed by pm also stands for the 24-hour hour, and 12 am stands for 0. The sign is ignored.
  • Rounding. A written number stands for anything that rounds to it at its written precision: 12.5 for 12.45 to 12.55, 3 for 2.5 to 3.5. An integer of four or more digits counts trailing zeros as rounding and keeps at least two significant digits: 12,000 stands for 11 500 to 12 500. A k/K, m/M, b/B/bn suffix, or thousand/million/billion after one space, stands for the scaled value (1.2k for 1 150 to 1 250). A % also stands for the fraction (60% for 0.595 to 0.605). A decade (a round number of tens from 20 with s: 80s, mid-90s) stands for its ten (80s for 80 to 90).
  • Durations. A number with ms also stands for its seconds; with sec, secs, second or seconds, for its minutes. A result’s number under a key naming the unit (ackMs, timeout_ms, timeout_s, waitSeconds) grounds the next unit too.
  • Which fields are read. Every string, except links and references (link, url, href, sha256, frame_ref, ref), templates and scripts (template, data, script, svg), block type tags (type), and axis and header labels (x, x_labels, y_labels, columns). A card’s value (a PanelValue) is read in both its forms, except a threshold’s and a breakdown part’s numbers-only value. Numbers-only data fields are not read: series values, heatmap cells, compare, forecast, delta and share numbers. A file.v1 is not read.
  • The refusal. The check runs after the body parses and before the render is routed. The brain’s answer is render_shown {outcome: refused, reason: unsupported_number, at}, where at is the first field that failed (blocks.0.tiles.1.value). Nothing reaches the panel. The trace rows are card_refused {kind, reason, at, numbers, results, words, us} and show_render_answered. A grounded card writes card_grounded {kind, numbers, results, words, us}. No row carries the card’s text or the number. The Admin event timeline gets one warning row, gateway.render / card_refused, coalesced over a minute.
  • What is refused. A number the brain derives: a sum, a difference, a unit conversion, a relative time (“3 minutes ago” from an epoch stamp) or a time-zone shift. The brain can restate the card from the tool’s own numbers.

Was this page helpful?