---
title: "Web pages in the panel"
description: "A named web page in the render panel (page.v1): the gateway's registry [panels.pages] (a name, an https URL, the words that ask for it; retro-weather is the seed), the show_page verb and pi_show_page {name} (never a URL), the PageSpec body and its bounds, the unknown_page refusal, who frames the page (Vigil, the Glyph) and who gets its card, the frame's sandbox, the gateway.pages Health row and the GPUI page host still to come."
type: "living"
source: "docs/contracts/page.v1.md"
verified: "2026-11-14"
group: "Contracts"
---

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

page.v1 — a named web page from the gateway's registry, shown in the render panel

- Status: **landed on protocol 5, additive**.
- Scope: the visual response channel's web tier, beside [`panel-card.v1`](/docs/contracts/panel-card.v1),
  [`visual.v1`](/docs/contracts/visual.v1) and [`file.v1`](/docs/contracts/file.v1): a live page someone else made (The Weather Channel's
  RetroCast), shown as it is. A card is for numbers a tool holds; a page is for a whole site the operator wants to
  look at.

## Why a kind of its own, not a card block

`page.v1` is its own render kind with its own closed body, because card.v1 allows no HTML, pictures, colors, layout
or URLs. It uses the projection rule of visual.v1 and file.v1: whole to a frontend that declared it, as its card to
one that draws only cards. The card frontends never learn a URL.

## The registry, not the brain, names the address

The brain never sends a URL. A page is a **name** in the gateway's registry, `[panels.pages]` in the gateway config:

```toml
[panels.pages.retro-weather]
url = "https://weather.com/retro/"
aliases = ["retro weather", "retrocast"]
# title = "Retro weather"   # optional; default the name as words, capitalized
```

| key | bound |
|---|---|
| the table's key (the page's name) | a lowercase letter, then lowercase letters, digits and `-`; at most 40 (`page_name_ok`) |
| `url` | `https://` (lowercase), a host of letters, digits, `.`, `-` and an optional `:port` (no user or password), then printable ASCII with no space, quote, backslash or markup; at most 512 (`page_url_ok`) |
| `aliases` | at most 8, each lowercase letters, digits and single spaces, at most 40; the name said as words ("retro weather" for `retro-weather`) always counts too; two pages never share an alias |
| `title` | optional, card.v1's title rule (1..=80, plain) |
| the table | at most 32 pages |

The default config holds one seed page, `retro-weather`. A config that sets `[panels.pages]` names the whole list:
copy the seed's three lines to keep it. An empty table shows no page, and the verb below matches nothing. A page out
of bounds fails the config's load, naming the page and the field. To add a page, edit the config and restart the
gateway.

## `PageSpec`, the body of `page.v1`

| field | type | bound |
|---|---|---|
| `name` | string | the registry's name (`page_name_ok`) |
| `title` | string | card.v1's title rule |
| `summary` | string | card.v1's summary rule; the gateway writes "<title>, a web page." |
| `url` | string | `page_url_ok` |

Closed (`deny_unknown_fields`). `validate_render` checks every bound before relay: a bad name or URL is
`bad_envelope`, bad text `bad_text`. The gateway fills it from the registry; a producer never writes one.

## The two ways in

**The verb** (`show_page`, a closed gateway verb with an open subject, no brain turn). The whole request must be one of
a page's aliases, with at most a lead ("show", "show me", "open", "open up", "pull up", "bring up", "put up", "put",
"display"), a "the", a tail ("page", "on the screen", "on the panel", "on screen", "for me") and a "please" at either
end. The wake and polite leads come off first (tier 2, `verb_tier::relaxed_form`). "Retro weather", "show retro
weather", "show me the retro weather please" and "open retrocast" match. "Show me the weather like the 90s", "what is
the retro weather like" and "turn on retro weather mode" do not, and reach the brain. Both the verb (show) and the
subject (a registry alias) are closed, so the grammar cannot swallow a sentence about anything else, and a gateway
with no pages matches nothing. It sits in `tier_one_verb` ahead of the restart and cancel phrases.

The ws loop routes the page under one render id per page (`page-<name>`, so asking again replaces the panel) with the
render frame's longest ttl, 600000 ms, and stamps the turn. Nothing is spoken when a panel drew the page: the page is
the answer, and it may play its own sound. A panel that took only its card hears "This screen can't show web pages, so
it shows a card instead." A session whose frontend neither hosts pages nor draws cards hears "No screen here can show
web pages." A page that left the registry before the panel is "That page is not set up." The trace row is `page_shown {name, source: verb, sent, projected_to}`.

**The brain's tool** (`pi_show_page`, tool.v1 `create {name}`, in the vigil, laptop and default loadouts). The tool
sends the gateway's `show_render` mutation line with kind `page.v1` and `{name}` as the body. The mutation listener
resolves the name before the line reaches the session (`page_show::answered`). A known name replaces the body with its
`PageSpec`. Anything else is answered at once and goes no further:

```json
{"status": "render_shown", "kind": "page.v1", "outcome": "refused", "reason": "unknown_page", "waited_ms": 0,
 "error": "I have no page by that name; the pages I can show are retro weather"}
```

`bad_request` is a body that is not `{name}` alone: a body with a `url` is refused, never followed. The tool's
answer: `drawn` (with `projected_to: card.v1` when only the card reached a panel), else the closed codes
`unknown_page` (the hint carries the gateway's words), `not_drawn`, `not_set_up` and `unavailable`. The receipt keeps
the page's name and the outcome.

## Who gets what

| frontend | declares | gets |
|---|---|---|
| Vulpine in a browser (the Vigil look) | `page.v1` (`VIGIL_RENDER_KINDS`) | the page, in a sandboxed frame inside the panel kit's card frame (`PanelPage`) |
| Vulpine.app (the Glyph look, a WebKit window) | `page.v1` (the kit's `PANEL_RENDER_KINDS`) | the same, in its panel stack |
| the conversation window (apps/convo-gpui, an observer), any card-only frontend | `card.v1`, not `page.v1` | the page's **card projection** (`page_card`): its title, its summary, and the note "A web page; this panel cannot show web pages. It shows in Vigil and the Glyph." |
| a frontend that draws neither (a satellite, the TUI) | nothing | nothing (`dropped`, `undeclared`); the verb says so aloud |

The frame (`PAGE_FRAME_SANDBOX`): `sandbox="allow-scripts allow-same-origin"` (the page runs its own scripts at its
own origin, which it needs to draw; no top navigation, no popups, no forms, no modals, no downloads),
`referrerpolicy="no-referrer"`, `allow=""` (no camera, microphone, location or autoplay grant). A page's own settings,
such as RetroCast's location by IP and its music toggle, stay the page's and the user's. The frontends check the body
again (`pageSpecOf`) and draw nothing for a body the contract would refuse. Close it with the panel's ×, or with Esc
in Vulpine.app while it has the keys. It leaves on its own after its ttl, held while the pointer is on it.

A page that refuses framing (`X-Frame-Options`, `frame-ancestors`) draws the browser's own refusal inside the panel;
drop it from the registry.


## Latency

The verb's grammar runs once per committed utterance on the commit path: a tokenize and a compare against the
registry's aliases, about 9 µs per call in a debug build (under 0.02 ms per commit). A page asked for by the verb
skips the brain round trip: the commit-to-first-text leg is not run.

## The Admin

The Health panel's `gateway.pages` row shows the registry read-only: how many pages, then each page's name, its
address without the scheme and the words that ask for it ("retro-weather: weather.com/retro/ (said as retro weather,
retrocast)"). The Configuration view does not show it: the Admin socket withholds any text with `://`, a query or a
fragment. An address the socket would still withhold shows its host alone. The Direct verbs card lists `show_page`
with its phrases and 30-day uses. A page counts on the Presentation section's "Render panel" row like any render
(`last_kind: page.v1`).

The conversation window has no page host yet and shows the page's card. The gateway cannot dismiss a panel by voice,
and the brain's tool has no `list` action; its refusal names the pages.

