Screen context
The assistant knows what’s on screen because it reads what the page already holds, not because each page tells it.
The problem
Someone looks at a list and asks “which of these is worst?” The assistant has to know what “these” means.
The usual answer is a context object per page, built by hand and passed to the assistant. It drifts. Half the pages never get one, and the ones that do go stale the first time a component changes what it fetches. Nobody notices until the assistant is confidently wrong about the screen.
What I concluded
The page already knows what it’s showing. So the assistant reads the screen from the sources the page itself uses, at the moment you send, and no page registers anything.
The data: read the query cache
Every query is built through one helper that requires a description in a reader’s words. When you send a message, one function collects the queries that are active, described and have data. That list, with each description on top of a sample of its rows, is the page.
describedQuery({
queryKey: ["orders", customerId, "open"],
queryFn: () => api.orders.list({ customerId, status: "open" }),
description: "Open orders for this customer", // required
});
Data that shows on every page, like the signed-in user, is marked as session data and left out. Things the page holds but never fetched, like an unsaved draft, get published under a key while the page is mounted.
The rendering: read the visible text
The cache says what was fetched, not what the page did with it: which rows are showing, what the empty state says, which drawer is open. For that, read the text the person sees, in order, plus any open overlay. An overlay names itself with a constant title, so the request says “they’re looking at Order details”, not the page behind it.
Reading waits until the page settles. Pages you click straight through are never read, and a slow page is read once, as it stands, and flagged as partial.
The map: send it by hash
The list of every page the assistant can open is big and changes only on deploy. So the client sends a hash, and the server keeps the full list per account. On a miss the server says so, and the client resends the list once.
client ── { catalog: { hash } } ──────────▶ hit: run the turn
◀─────────────── miss: send the list
── { catalog: { hash, targets } } ─▶ verify, store, run
Rules
- Read at send, not at mount. You get the screen after the last filter or tab switch, and it rides with the request, so old turns never drag a stale screen along.
- Described or invisible. A query without a description doesn’t compile, so whatever is left after the session filter really is the page.
- Two budgets, both honest. The client samples, the server trims for the model and says what it cut. A read tool hands back the full view when the question needs it.
- Slow-changing goes by hash, live goes in full. Routes change on deploy. What’s on screen changes every message.
- The server checks the hash. A list that doesn’t match its hash is refused, so no client can store a list under someone else’s.
What you get
Awareness costs nothing per page. A new page is visible to the assistant the day it ships, because writing its queries already described them. The assistant can only be as right as the screen, which is the honest failure.
Related: Site map, UI as rendering engine, Navigation.