~ knotless Search/
↑↓ move↵ open⇧↵ all results

chadtmiller.com/hud

A remote MCP server that shows atproto records as interactive UI inside MCP Apps hosts

0
0
1809 lines · 116.2 KB Raw History
---
title: Views
section: HUD
order: 3
summary: "How HUD draws a collection or a query's answer: joins, summaries, layouts, query joins and the bundled views."
---

A lexicon describes one record, but a gallery is three. There's a `social.grain.gallery`, the
`social.grain.gallery.item`s that point at it and at a photo each, and the `social.grain.photo`s.
Nothing in a lexicon says which collection an at-uri points into, so HUD writes down how a
collection is drawn as data. That's a view (`place.hud.view`, with its lexicon in `schemas/`).

A view names the collection it draws. For a page of records (`list`) and for one record (`record`)
it gives the [joins](#joins), a [summary](#summaries), a [head](#page-heads) and a
[layout](#layouts-and-components).

## Joins

The server runs a view's joins first. Each join leaves its result on every record at
`joins.<as>`. There are a few kinds:

- `ref` joins the record an at-uri or strongRef names.
- `each` joins the records an array's elements name.
- `backlinks` joins the records of the same repository that point back at the record, ordered.
- `counts` says how many records across the network point at the record, by collection and path
  (a post's likes, reposts and replies, a gallery's favorites). It reads them from a backlink index.
- [Query joins](#query-joins) call a related query.

A `ref`, `each` or `backlinks` join can have joins of its own, three deep at most.

## Summaries

The summary is the tool's text. It names a noun, each record's label and a detail count, as
"3 galleries by alice: Coast (12 photos), …".

## Page heads

A web page that draws a tree needs a title, a description and a picture for search engines and
link previews. A mode's `head` says them, read against the mode's scope as the tree is:

```json
"head": {
  "title": { "$join": [{ "$": "response.gallery.title" }, " by ",
             { "$": ["response.gallery.creator.displayName", "response.gallery.creator.handle"] }, " on Grain"] },
  "description": { "$first": [{ "$": "response.gallery.description" },
                   { "$join": ["A photo gallery by @", { "$": "response.gallery.creator.handle" }, " on Grain."] }] },
  "image": { "$": "response.gallery.items.0.fullsize" },
  "type": "article",
  "canonical": { "$join": ["/profile/", { "$": "response.gallery.creator.handle" },
                 "/gallery/", { "$rkey": "response.gallery.uri" }] },
  "noindex": { "$": "response.gallery.labels" },
  "jsonLd": { "@context": "https://schema.org", "@type": "SocialMediaPosting",
              "image": { "$each": [{ "$": "response.gallery.items" }, { "contentUrl": { "$": "fullsize" } }] } }
}
```

Each field is a template, as an [Action's record](#action) is. So a field can be a literal, a
binding, `$join`, `$first`, `$rkey` or `$root`. A field that reads nothing is left out, never an
error. That's how a gallery with no description gets one written for it, and one with no labels
stays indexable.

| Field | Once read |
| --- | --- |
| `title` | Text, on one line, 120 characters at most |
| `description` | Text, on one line, 300 characters at most |
| `image` | A blob or an https URL on the view's origins, sent as an absolute https URL |
| `imageAlt` | Text, on one line, 420 characters at most |
| `type` | A literal `website`, `article` or `profile` (Open Graph's `og:type`) |
| `canonical` | A path on the app's own site, starting with `/`, percent-encoded, 512 characters at most. One that would leave the site (`//host`) is left out |
| `noindex` | `true`, or a list with something in it (an account's or a record's labels) |
| `jsonLd` | schema.org structured data, an object of templates, 32 KiB at most as JSON |

In `jsonLd`, `{"$each": [array, template]}` reads the template against each of the array's
elements, 50 at most, with `$root` reaching the mode's scope. An object whose templates all read
nothing is left out with them, so a gallery with no place has no `Place` with no name.

The tree carries it as `_meta.ui.head`, a trusted view's alone. A view given inline can say a head,
and HUD checks it, but its head never reaches the tree. The page writes the head's text into HTML,
so it escapes it, and `<` in `jsonLd` too. What a page says where its view's head says nothing is
its app's ([the operator's views](#the-operators-views)).

### The hero picture

A page's largest paint is usually its first big picture, so a page should load that one first and
the rest as they near the screen. Every tree a view draws names it as `_meta.ui.hero`, the `src` of the first
picture it draws large, in drawing order. That's an `Image` not drawn small (`avatar`, `face`,
`icon` and `thumb` are small), the first picture of a `Gallery`, `Slides` or `Covers`, or a
`Profile`'s banner, else its avatar. A `List` that scrolls sideways (`strip` or `shelf`) draws
its items small, so nothing in it is the hero. So a Grain feed's hero is its first card's first
photo (past the stories over it and the photographer's face), and a gallery's is its first photo.

The web renderer draws the hero with `loading="eager"` and `fetchpriority="high"`. The pictures
first on the screen by their place load at once too: an `Image` and a `Gallery`'s first picture,
at the tree's top, in a list's first item, in the pane shown. Beside a hero they load with
`fetchpriority="low"`, so a gallery's author's face doesn't slow its first photo. In a tree with no
hero they have no priority of their own. A feed's first card is drawn so, its face and first
photo, and its carousel's next photo isn't. A `Covers` waits, but for its hero, since one under a
gallery is far down its page. Every other picture loads lazily. A page drawn on a server should
also preload the hero from its head
(`<link rel="preload" as="image" href="…" fetchpriority="high">`), so the browser fetches it before
it reaches the `<img>`. Where the hero is a gallery photo with its sizes, the tree says them too
(`_meta.ui.heroSrcset`). Then the preload gives them as `imagesrcset`, with `imagesizes` the `area`
the page gives `Tree`, so the browser takes the same size for both. The renderer's
`heroPreload(ui, area)` gives the link's attributes so. A tree with no picture drawn large has no
hero.

## Layouts and components

A layout is a tree of components from a fixed catalog (Stack, Split, Header, Text, Image, List,
Covers, Tree, Chain, Gallery, Player, Map, Document, Embed, FeedContext, Stat, Fields, Action and the
rest).
Each prop is a literal or a binding, `{"$": "value.title"}`, which is a path into the data. The
path `"."` is the data itself (as a tag in a list of tags). A key `@name` takes the element of an
array whose `$type` ends in `#name`, as an array of a union holds one of each kind:
`response.preferences.@photoMetadataPref.includeExif`.

### Image and Gallery

`Image` draws one picture and `Gallery` several. A picture with a `size` (an avatar, a face, a
profile's own, an app's icon) draws a placeholder where its account has none. One without a size is
left out where it has no source.

Two flags draw a photo as a photo app does. `bleed: true` takes it past the padding of what holds it,
to the edges of the tile, screen or list row, with square corners. `showAlt: true` marks it ALT where
it has alt text, and a tap shows that text over it: white, centered both ways on a 60% black scrim,
scrolling when longer than the photo. A tap on it hides it. Grain's feed and gallery draw their
photos so, and their authors' names as `Link`s with `style: "name"`, in the text's own colour, bold.
What bleeds (a picture or `Map` with `bleed`, and `Covers` as `tiles`, which always reach the sides)
and is first on its screen meets the bar above too, its screen keeping no padding over it: Grain's
place opens on its map, and its camera's and hashtag's feeds on their tiles, flush under the bar.

An `Image` with an `href`, as a Link's, opens that when tapped rather than what holds it, its alt
read aloud. Grain's authors' pictures open their profiles so (`"href": {"$": "creator.did"}`), and
the rest of the card but its photos still opens the gallery. A carousel's tap opens nothing (with
`zoom`, a gallery's own screen, it opens the lightbox), since a tap on a feed's photo opens nothing
in Grain's apps either. A Link with `style: "muted"` is drawn as muted text on
one line, cut with an ellipsis: a gallery's location, which opens that place's feed. Where a param of
its `open` reads nothing (a gallery with no place to open), it is its words alone.

A `Gallery` with `like`, the label of an Action in the same List item as it (or, in none, the view's
own), runs that Action on a double-tap on a photo where it isn't done yet, and never undoes it, a
heart bursting where the tap was, as a `Slides`' `like` does. A tap that opens the lightbox then waits
a moment to be sure it isn't one, and a tap that opens nothing still opens nothing. Grain's feed cards
and gallery pages name their ♡ so (`"like": "Favorite"`), as Grain's apps favorite a gallery on a
double-tap, and a comment's own ♡ under a gallery, in its own List item, is never run by it.

A `Gallery`'s `info` is each photo's own lines of words, read from its item: each line's `parts`
(each a binding, with a `prefix` or `suffix`) joined by its `join`, a part reading nothing left out
and a line of none dropped. A part with `omitRepeated` is left out where the next part read starts
with its first word, so a camera's make goes where its model names it. In rows or a stack, a photo
with any has an ⓘ in its bottom-left corner, mirroring ALT, that shows them over it. Opening one
closes the other. A carousel draws the lines of the photo showing under it instead, small and muted,
and swaps them as it's swiped. It keeps room for as many lines as the most any photo has, so its
height holds between photos with info, and a photo with none draws nothing there. Grain's feed and
gallery show each photo's camera so: its model (after its make where the model doesn't name it), its
lens, and its focal length, aperture, exposure and ISO.

A stack or a carousel draws each photo the full width, so a phone needn't load a photo as wide as a
desktop does. Its `srcset` names the sizes each photo comes in, each a binding into the photo and how
many pixels wide that URL is. Grain's gallery names its thumbnail (`thumb`, 1,000 pixels wide, ~100
KB for a photo measured) and its full size (`fullsize`, 2,000 pixels wide, ~900 KB):

```json
"srcset": [{ "src": { "$": "thumb" }, "width": 1000 }, { "src": { "$": "fullsize" }, "width": 2000 }]
```

Each photo's item says them as an `<img>`'s srcset. The web renderer draws it with sizes made from
the `area` the page gives `Tree`, how wide the page draws the tree's main area, written as an
`<img>`'s sizes (the screen's width where it gives none). A picture the full width of the tree takes
the area as it is, and one in a grid's tile the area shared among the grid's columns
([Laying out by width](#laying-out-by-width)). A lazy picture's sizes start with `auto`, so a
browser that knows it takes the width the picture is laid out at. Grain gives each screen's column,
so a wide profile gives `(min-width: 601px) min(935px, 100vw - 245px), 100vw`. A 390-pixel phone
at 2x then takes the thumbnail and one at 3x the full size, as does a desktop at 2x. A carousel
draws the photo it shows and the next alone, and each further one once the one before it is shown,
so a gallery of 20 loads 2 photos before it's swiped. Near the screen, it fetches that next photo
ahead too, at the width it's drawn at, since a browser may leave a lazy one off the screen in the
carousel's strip until it's swiped.

### Laying out by width

| Part | In a narrow box | In a wide box |
| --- | --- | --- |
| `List` grid, `Covers` | as many across as fit at `min` | at most `columns` across, sharing the line |
| `Split` | its two children one under the other, in their order | side by side, the aside at its narrowest |
| `Profile`, `Header` | the picture over the words | the picture beside them |
| `Split` from 32rem | a large picture 80 pixels | a large picture in its aside up to 150 |
| `Panes` from 36rem | one pane: no row | one pane's row too, each icon with its word |

A part lays out by the box it's given, never by the screen. So one tree draws right in an MCP
App's frame, a workspace tile, Grain's column and a phone. The web draws each branch in CSS (grid
tracks and wrapping flex lines), so a page drawn on a server is what the browser shows once
hydrated. HUDKit and Android measure the width they're offered.

`min` and a `Split`'s `main` and `aside` are sizes the host sets, `sm`, `md` or `lg` (the web's
6rem, 10rem and 15rem, the native kits' 96, 160 and 240 points). A grid's `columns` (1 to 6) is the
most it draws across, however wide its box is. Grain's profile draws its galleries
`{ "style": "tiles", "min": "sm", "columns": 3 }`, so three across from a 320-pixel phone to a
1200-pixel screen. A `Split` with `"side": "start"` takes its first child as the aside (a profile's
picture beside its name, counts and bio). Its children are never hidden or moved, so a narrow box
draws the aside first there too. A grid without `min` keeps its own narrowest tile (14rem, a
cover card 9.5rem, a tile 7.5rem and three a line at least).

### How wide a view is drawn

A view's top-level `measure` says how wide it would be drawn where its host can give it the room.
`content` (the default) is the host's reading width, `wide` a wider one (a profile's grid of
pictures) and `full` all the room the host has for a view. The tree says `wide` and `full` as
`_meta.ui.measure`. A view drawn inside another (an embed) takes the room it's given.

One view may draw some answers wider than others. Its `measureWhen` lists 1 to 8 cases, each a
`when` (a path in the answer's scope, as a `Stack`'s) and a `measure`. The first case whose path
holds something decides, else `measure` does. HUD decides it as it answers, so the page is drawn
at that width from its first paint. Grain's feed view is `wide` for a camera's, a place's or a
hashtag's galleries (`params.camera`, `params.location`, `params.tag`) and the reading width for
its home feeds.

A screen drawn in a tab's root's place, as a `Tabs` strip draws its choice there, keeps the
root's measure rather than its own, so choosing a tab never changes the screen's width. Grain's
pinned camera, chosen in Home's strip, is drawn at Home's reading width, while the same feed
opened from Explore is wide. The shell keeps it as the strip swaps the call. Where a URL is drawn
in a root's place (`swappedTab`), the server answers that tab's own root call too, for its
measure, so the page it draws is the one the browser hydrates. A root the account's data chooses
([A tab's root from the account's data](#a-tabs-root-from-the-accounts-data)) is drawn at its own
measure, and the strip's choices keep it: where a camera is the first feed someone pinned, their
Home is wide, Recent chosen in its strip too.

A part inside a wide view may keep the reading width: a `Stack` with `"measure": "content"` is
drawn no wider than the host's reading width (the web's `--hud-reading-width`, 37.5rem unless the
host sets it, or the native kits' 600 points), centred in a wider box, and as wide as its box where
that's narrower. Grain's profile holds its header so (its picture, name, counts and Follow, a
compact block) over a grid the screen's whole width.

The host decides how wide each is. Grain's web app draws `content` 600 pixels wide and `wide` all
its 935 right of its sidebar (less where the screen is narrower), centred where `content` is, so its
sidebar never moves. The MCP App never asks its host for
room by itself. Where the host offers full screen, it shows an Expand button over a `wide` or `full`
view, and asks only when it's clicked. The workspace draws every view in its tile alike.

### Stories

`Slides` shows pictures one at a time, as a photo app shows an account's stories. Bars over the
picture fill over `seconds` each, from when its picture has loaded (or failed and shows its
placeholder), so a slow picture keeps its time. The next two pictures are fetched ahead, so a tap
shows them at once. A tap on the right goes on and on the left back, and holding pauses. Each
item's `call`, in a bundled view alone, is a procedure called once that picture first shows.
Grain's stories mark themselves watched so (`social.grain.story.markViewed`). Its children
are drawn over each picture, at the end of its top row, with that picture's item as their scope:
Grain's are a ⋯ with Delete story on one's own and Report on others', and the picture waits while
it's open. With no pictures, `Slides` still draws its screen, its `empty` words in the middle and
its children under them, drawn with the view's scope. Grain's says "No stories right now", and on
one's own Add to your story under it posts a new story (`social.grain.story`), as Grain's + does.

An `open` query's `compose` opens its screen at a form: `true` for its first `Compose`, or one's
`label` (as `"New gallery"`). HUD marks that one `open` in the tree, and the renderers open its form
by themselves once the tree is first drawn in a browser or an app and is the one in front (`active`),
once in that tree. A story pager's page read ahead beside the one shown waits. The server draws it
shut, as the browser hydrates it, and a tree drawn again (a story deleted) stays as left.
Only a `Compose` drawn as the screen itself opens, never one over an item (a List's, a picture's)
nor a Menu's row. So a story screen with pictures opens nothing, and one with none opens its Add.
A photo form (`form: "photo"`) whose photos field has `camera` then goes straight to the camera
where there is one. The web can open a phone's camera only while the tap that opened the screen
still counts as the person's, and otherwise its form waits on Camera. An `open` query's `unless`, a
path in the scope, drops its `compose` where it holds something. Grain's Your story opens one's
stories so (`"compose": true, "unless": "stories"`, its row's `stories` one's own): with none, the
new story's camera, and with some, the stories, as any other page.

`compose` is a one-time request, not part of where the app is. A client opens the form once, as the
call opens its screen. The screen it keeps is the call without `compose`: in its history, its URLs,
its memory of screens drawn and its saved navigation. So going back or forward to that screen,
loading the page again or choosing its tab again never opens the form again. The web shell keeps a
screen's last tree with its `open` mark taken off (the renderer's `unopened`). HUDKit opens a form
once per screen in that screen's memory, and keeps no navigation across launches. The Android kit
does the same (`composeOpensAtOnce`), and an app's story pager draws a page that opens at its form
as that form alone (`Drawn.openedForm`, `OpenedForm`), as HUDKit's.

In a pager of a List's `pages` (Grain's stories strip), an item whose call opens at a form (Your
story's `compose`, with none) is a page only of the pager it opens itself: tapping someone else's
story leaves one's own out. With stories of one's own its call has no `compose` (`unless`), so it
is a page as any other, the first, and swiping back from the first other person's reaches it, as a
photo app does. Only the page tapped opens its form, and only until it's left. Where it does (Your
story with none), the web shell draws no stories, just that form over the screen under them, as
the frame's action does, and the form closing, sent or not, closes them, as a photo app's Your
story goes to the camera and back. The web shell draws every other page with its mark taken off
(`unopened`), so the history it keeps for a pager holds its calls without `compose` too. HUDKit's
`ViewContext` has `opensForms` for an app's own pager to say the same, and `Drawn.opensAtForm` with
`OpenedForm` for it to draw the page tapped as its form alone, as the web shell does. A `Slides`
page with no pictures stays when it's swiped to, its words and Add shown, rather than run on to the
next page.

An `open` query's `at` asks the view to show that first, and `Slides` with `start` (a path in each
item) begins at the item holding it there. A story picked from a profile's Stories opens the
archive at that story so (`"at": { "$": "uri" }`, `"start": "uri"`).

`Slides` with `reverse` draws its items last first, so an archive answered newest first plays
oldest first, as stories do. With `href` (a path in each item, as an Image's), each picture is the
screen of that record, and the app's address follows the picture shown. Grain's story route
(`/profile/{actor}/story/{rkey}`) says `"pager": true`, so its screen opens in the story pager
wherever it's opened from: the Home strip, a profile's avatar, the archive or a link. The web
shell keeps the URL at the story shown, replaced in place as it moves within and between people,
so Back leaves the pager, and closing it goes back to where it was opened. The route's `under`
(`/profile/{actor}`) is the screen under a story whose URL is loaded directly. The server draws the
pager over that profile, its head the story's, and the browser's history becomes the tab's root,
the profile and the story, so closing it or Back lands on the profile. On a desktop the pager is
drawn as Instagram draws stories: a dark window, the wordmark top-left and ✕ top-right, the story
in a 9:16 column in the middle, and the people beside it small and dimmed, a click going to them.
Phones stay full screen.

An `open` query with `sheet: true` opens its screen as a sheet over what's open: on the web, as
wide as the column, or over a pager (a story, full screen) a phone's column in the middle of the
window, over the picture. A Link, an Action or a Compose with an icon over a `Slides` picture is
drawn as a Bar's, its icon alone, and an Action done in its colour, as a Bar's is. Each Grain story
has 💬 there, opening its comments (`social.grain.comment.getThread`, the `grain-comments` view) in
a sheet over the story, and ♡, favoriting the story (a `social.grain.favorite` of its at-uri, its
`viewer.fav` the one already made), red once it is. A `Slides` with `like`, the label of an Action
among a picture's own, runs that Action on a double-tap on the picture where it isn't done yet, and
never undoes it, a heart bursting where the tap was. A tap then waits a moment to be sure it isn't
one. Grain's stories name their ♡ so (`"like": "Favorite"`), as Grain's apps favorite a story on a
double-tap. A List with `"open": false` opens nothing when an item is clicked, its children's own
links and buttons still theirs: a comment there, or under a gallery, opens nothing itself, its
author, reply and ⋯ what they open.

A `List` with `style: "strip"` is one row that scrolls sideways, and an `Image` with `ring` (a path,
as a Stack's `when`) is ringed in the accent where its scope holds something there. One with
`plus` (a path too) has a small + in the accent at its corner. Grain's feeds draw who has stories
over them so, each ringed while it has some unwatched, your own first, as Your story, with its +.

A `List` with `pages: true` opens an item as one page of a pager of them all, full screen over the
app. A sideways swipe slides the page off as the one beside it comes in, and a drag down closes it.
A page's `Slides` running past its last picture goes on to the next page, and closes the pager
after the last, and tapping back on its first goes to the page before. Pages either side are read
ahead, their first pictures fetched, and wait to run and mark anything watched until they're
shown. On a desktop, the arrows beside it, ← and → and Escape do the same. Grain's stories strip is
such a list.

### Menu

`Menu` is a ⋯ button whose children are a menu's rows: Actions, Links and Composes, each its label.
An Action may ask first (`confirm: "Block this account?"`), in a bundled view too, and take
`tone: "danger"`, drawn in the danger colour. A Compose may call a procedure in place of `writes`
(`call`, a bundled view's alone): the form's values are set on its input by their names, over the
template's own defaults. Grain's profile has Mute or Unmute, Block and Report there, and its gallery
Report, each report a form calling `com.atproto.moderation.createReport` on Grain's AppView.

A Stack among a menu's rows gives its rows where its `mine`, `others`, `when` or `unless` holds,
so a menu can offer Delete on one's own gallery and Report on someone else's. An Action with
`leave: true` closes the screen it's on once it succeeds, and the screen below is read again. One
with `reload: true` reads its own screen again. A template's `{"$rkey": path}` is the record key
of the at-uri at that path. An Action's question is asked as an alert over everything, and
answered, the menu it came from closes. Grain's gallery has Edit gallery and Delete gallery there,
the second asked first, deleting what `social.grain.gallery.getDeletionPlan` plans (see Action),
its photos, comments and favorites with it. Each comment has a ⋯ too: Delete comment on one's own
(reloading the gallery), Report on others'.

A Link with `share`, an https address its `href` value ends, shares that address rather than
opening anything: the system's share sheet, else the clipboard. Grain's profile has Share profile
atop its menu, its page on grain.social (`"share": "https://grain.social/profile/"`, `href` its
handle), on one's own profile too.

A Link with `copy` copies text rather than opening anything: `copy` and then its `href` value, put
on the clipboard. The web says Copied a moment, and an iOS menu's row taps success. Grain's profile
has Copy handle under Share profile (`"copy": "@"`, `href` its handle), so it copies `@handle` as
Grain's iOS app does.

A Link's `fragment`, a path to a DID, opens its `href` (an https address with no fragment of its
own) with that DID as its fragment, then `+` and the signed-in person's DID. That's how Germ asks
an app to complete its `messageMeUrl`. A Stack's `where`, as a List's, draws it only where its scope
holds at each path what the path paired with it holds, or the literal of an `{"$is": …}`. Grain's
AppView reads an account's `com.germnetwork.declaration` record into its profile's `messageMe`, so
Grain's profile has Message on Germ under Follow. It's there, signed in, where `showButtonTo` is
`everyone`, and where it's `usersIFollow`, only for those the account follows.

### Search

`Search` is a field whose words fill one param (`param`, as `q`) of the query its `open` names.
Searching opens that query with them. Where that query is the one drawn now, searching again draws
its answer in place, as a tab does. `value` binds the words searched already, which the field
shows. Grain's Explore has one, and each of its results views has one over Tabs of Galleries and
People.

### Tabs and Bar

`Tabs` draws a few queries over the one drawn now, and choosing one draws it in place. Its tabs are
`items`, or one for each element of an array in the data (`from`), labelled by a path in it
(`label`) and opening `open` with params read from it, those `where` keeps. A `where` pairs a path
in the element with a path in the scope or with a literal (`{"$is": "feed"}`), either in
`{"$not": …}` to keep the elements holding anything else. In place of `open`,
`opens` (1 to 4 `{ where?, open }`) opens each element by the first whose `where` it matches, and
one with no `where` matches any. An open's param `{"$after": [value, "camera:"]}` is what the value
holds after that prefix, and an element whose value doesn't start so opens nothing there. `items`
stand in when the data holds no array. Tabs draw only when one of them is the query drawn now, and
there are two or more. `style: "strip"` draws them as a feed app's feeds, a line of words that
scrolls sideways, the one drawn now underlined. A strip's tabs swap the screen in place, which is
a tab's root alone, so it draws only at the root of the host's navigation stack: the renderers take
`root` (`Tree`'s prop, HUDKit's `stackRoot` environment value, Android's `LocalStackRoot`), true
unless the host says otherwise, and a host with a stack gives false to each screen pushed over its
root. A place's feed opened from Explore and pinned is one of the person's feeds, but pushed, it
draws no strip. The server draws with the same `root` the browser hydrates with.

Signed in, Grain's feeds are a strip of the feeds the person pinned
(`social.grain.actor.getPreferences`), or Recent, Following and For You where they pinned none. A
pinned feed opens itself, and a pinned camera, place or hashtag (`camera:Fuji X100V`) its feed of
galleries, so the strip is over those feeds too. Signed out, Recent is the one feed there is, and
no strip is drawn.

Choosing a tab marks it at once. An app's clients (Grain's `next/` shell and iOS app) also keep the
screen. They keep drawing the tree they have until the tab's call answers, and once it has run
150 ms (`SKELETON_DELAY`), they tell the tree it's `pending`. Its page list (the `List`, `Covers`
or `Gallery` of the query's items, which HUD marks `page`) then draws as a skeleton of what it
holds, and the rest stays as it is. So Grain's feeds strip and stories strip don't move while its
feed changes. The new tree is drawn over the old one, and its nodes that are the same stay mounted
with their pictures loaded. A `Search` answering in place does the same. HUD's own clients (the
workspace, its iOS app and the MCP App's view) draw the tab's call afresh.

`Bar` is the screen's top bar: its title and buttons beside it. Its `title` is the screen's, its
words one after another, each a string or a binding (`["Followers"]`, `["#", { "$": "params.tag" }]`),
and it has none where one of them resolves to nothing. The app draws it in its bar, as it draws its
screens' titles. Its children are Links, Actions, Composes and Menus, each drawn as its icon alone
with its label read aloud. A Link takes an `icon` for it (`settings`, `plus` and a few more). A Bar
is gated as a Stack is (`when`, `mine` and the rest), and an app with no bar draws it where it
stands, its title a heading at the start of its row and its buttons at the end. A web app with a
bar of its own draws the tree twice from the same props: `Tree` with `bar: "apart"` where the screen
is, which leaves the Bar out, and `bar: "only"` in its bar, which draws the Bar's buttons alone
(`barOf` finds it, first through the Stacks at the top). A page the server draws then has the
buttons where they stay, and hydrating it moves nothing. Each of Grain's
pushed screens names itself there (Followers, a gallery's title, a camera, `#film`). Its feeds have
a + there that opens New gallery (on a phone alone: beside the rail or sidebar, its Create is it,
as [The frame](#the-frame) says) and a gear that opens My feeds, and one's own profile a gear that
opens Settings.

### While a screen loads

A skeleton is a resolved tree's shape with its words and pictures left out. Its Stacks, Rows and
Lists stay (each list's first few items), and each leaf is drawn as a grey shape the size of what
will be there. That's bars of a text's length on its lines, a circle or block for a picture, a
gallery's frame and a grid for covers. The renderer makes it from the tree itself (`skeletonOf` in
`web/renderer`, `Skeleton.of` in HUDKit), so every view has one with nothing written for it. A
`Bar` with buttons stays as their count and draws nothing. So an app knows from the start whether
the screen's bar will hold buttons, and Grain's desktop frame keeps that bar's room while it loads.

An app's clients keep each screen's last skeleton (`rememberSkeleton`), named by the tool, the
method (or app domain) and the names of the call's params, so one gallery's screen stands for
another's. While a screen loads, they draw its skeleton (`recallSkeleton`) from 150 ms on, so a
load quicker than that draws nothing in between. A screen never drawn before gets a generic one,
rows of a face beside two lines. The skeletons hold no content. The web keeps them in
`localStorage` (`hud-skeletons`) and iOS in `UserDefaults`, so they're there on the next launch
too ([memory](memory.md#renderer)). HUD's own clients draw a spinner.

An iOS app on HUDKit can keep each screen's last tree whole as well (`LastTree`). Grain's does, so
a screen opened again draws that tree at once while its call is made afresh, then draws the answer
in its place. Since a tree holds what people posted, it's kept in memory alone, named by the
viewer's DID and the whole call, and drawn for 10 minutes at most. The app lets an account's trees
go once it writes (`create_record`, `delete_record`, `apply_writes` or `call_procedure`), and all
of them as anyone signs in or out ([memory](memory.md#renderer)). HUD's web renderer keeps no trees.

### Panes

`Panes` shows one of its `Pane` children at a time, chosen by a row of icons over them (`grid`,
`heart`, `clock` and a few more), the chosen one underlined, one width each in the row's middle. A
pane's Covers with `select` shows Select at the right end of the row. A Pane is gated as a Stack
is, and one with nothing to show isn't drawn. With one pane there's no row, and nothing to swipe.

With more, the panes lie side by side and page: a finger swipes from one to the next, the pane
following it, and a click on an icon scrolls to its pane. The underline follows the swipe, from
one icon to the next, and the panes are as tall as the one shown, between two as tall as both
blended by how far the swipe is, so a short pane leaves no room under it. A mostly vertical drag
scrolls the page. While a pane's Covers picks, the panes and the icons hold still. All of this
happens in the host, since every pane is in the tree. The web pages with CSS scroll snapping, so a
trackpad's two-finger swipe pages too, and the icon row follows the strip's scroll. A click scrolls
at once where motion is reduced. As the server draws them, and with no script, the first pane alone
shows and nothing scrolls: the others are drawn but folded away, opened once the page is mounted.
HUDKit pages with a paging horizontal `ScrollView`, as grain-ios's profile does, and Android with
a `HorizontalPager`.

Grain's profile ends in Panes: its galleries for anyone, and on one's own its favorites and its
stories, each read by a query join with `when: "mine"`, so those calls are made on one's own page
alone. A query join's `when` is a path in the main scope, and the join is called only where it
holds something. `unless` is the other way, called only where its path holds nothing.

### Faces

`Faces` draws a few accounts' faces, small and overlapping, then words: `lead`, the first two
names, and how many more in `countNoun`'s words. A click opens `open`. Grain's profile has one on
someone else's page, "Followed by alice, bob and 3 others you follow", from a join of
`social.grain.graph.getKnownFollowers` with `when: "me"` and `unless: "mine"`, opening the whole
list.

With `style: "pile"`, `Faces` draws the faces alone at an avatar's size, the first `max` (5 by
default) and +N past them, each opening its account (`href`, read from each item). On both
platforms the first face is on top, each ringed 2 points out in the page's colour, so its edge
cuts cleanly into the next face. With
`expand: true` there's a way to list them all, each with its face, name and `handle`. The web
draws a chevron after the pile that swaps it for that list in place. iOS draws +N as a button
that opens the list in a sheet, as Grain's iOS app does, so a pile of `max` or fewer has none.
Grain's notifications draw who did something so, one face or a group's.

### Map

```json
{ "component": "Map", "props": { "items": [{ "cell": { "$root": "params.location" } }],
  "cell": { "$": "cell" }, "bleed": true, "pins": false } }
```

`Map` draws a map with a pin per item, in the accent. A pin's place is `cell`, an H3 cell index, or
`lat` and `lng` in degrees, and a view gives one or the other. The server turns a cell into its
centre's coordinates, so the clients only get numbers. A cell that isn't one is the view's error,
and an item with no place has no pin. `label` names a pin, `count` makes it bigger as it grows (a
place's galleries), and a pin opens `open` as a List's items do.

`height: "short"` (the default, 200 points) is a page's header and stays still. `"tall"` (400 points)
can be moved and zoomed. With `zoom` (1, the world, to 18, a street) the map centres on its pins at
that zoom. Without it, the map fits its pins but comes no closer than a city (zoom 11). `bleed` works
as an Image's. `"pins": false` draws no pins: the map is still placed by them, centred or fitted
as it would be, a plain map of where they are.

The web draws it with Leaflet over OpenStreetMap's raster tiles, which are plain pictures, so the
view still fetches nothing. Leaflet is ~43 KB gzipped, loaded the first time a map draws (the MCP
view, a single file, carries it inline). iOS draws it with MapKit's `MKMapView`, which gathers pins
that would overlap into one showing how many places it holds (a tap zooms into it), so ~1,000 pins
stay quick. Android draws it with MapLibre (maplibre-compose) over the Protomaps vector basemap from
`tiles.grain.social`, gathering pins the same way, and a tall map moves only once tapped, so a
scrolling screen keeps its drags. Grain's place page (a feed with a `location`) has the map above as
its header, one literal item holding the place's cell, with no pin, as Grain's web heads a place. A
`Stack` with `"gap": "none"` sets it against the place's galleries under it (a Stack's `gap` is
`none`, `xs`, `sm`, `md` or `lg`, `md` where a view gives none). Grain's Locations (`getLocations`
with `pins: true`, every place it has, ~1,000 measured, at ~80 bytes each) has a tall one, each pin
sized by its galleries and opening them.

### Among a list's items

A Stack with `at` among a List's children isn't part of each item. It's drawn once, with the
List's own scope, after that many items, and on the first page alone. A List with
`style: "shelf"` is one row of cards that scrolls sideways, each one width, its parts centred. Grain's
feed has "Suggested for you" after its fifth gallery: a shelf of the accounts
`social.grain.actor.getSuggestedFollows` suggests (a query join when signed in), each card a face,
a name, two lines of bio and Follow.

A List's `shown`, in a bundled view, is a procedure called once as the signed-in person when the
list is first shown. Grain's notifications mark themselves seen so
(`social.grain.notification.updateSeen`).

A List's or a Covers' `where` keeps the items it matches and `limit` draws at most that many of
them. HUD filters them as it resolves the tree, so every client draws what's left. Grain's gallery
draws "More galleries from @handle" as Covers of the author's newest seven,
`"where": { "uri": { "$not": "response.gallery.uri" } }` and `"limit": 6`, so six others show
whether the gallery drawn is among the seven or not, as Grain's web does.

A List with `style: "chips"` draws each item as a filled pill that opens it, side by side and
wrapping, under its title as a small capital label. A `Text` in a chip is small and strong, on one
line. Its `more`, `{ "label", "open" }`, is one pill more after the items, in the accent colour on
no fill, drawn only where `limit` left items out. Grain's Explore draws its top ten cameras and
places so, each ending in "See all →" where there are more:

```json
{ "component": "List", "props": { "title": "Cameras", "style": "chips",
    "items": { "$": "joins.cameras.cameras" }, "limit": 10, "open": { … },
    "more": { "label": "See all →", "open": { "query": "social.grain.gallery.getCameras" } } },
  "children": [{ "component": "Text", "props": { "value": { "$": "camera" } } }] }
```

### Grouping

```json
{ "as": "group", "by": ["reason", "galleryUri", "storyUri"], "time": "createdAt", "hours": 48,
  "only": { "reason": ["gallery-favorite", "story-favorite", "comment-favorite", "follow"] },
  "distinct": "author.did" }
```

A List's `group` draws several items as one, as Grain groups the favorites of one gallery. An item
joins the first group before it whose first item holds the same at every `by` path and whose
`time` is less than `hours` from its own. An item with nothing at `time`, or none of `only`'s values
at its path, is a group of its own. Where an item's value at `distinct` is in its group already,
it's left out, so someone who favorited twice counts once. Grouping comes after `where`, `needs`,
`mine`, `others`, `distinct` and `limit`.

Each group draws as its first item, with `as` holding `{ items, count, others }` (the group's items
in order, how many, and how many past the first where there are more). Every item is a group of
at least itself, so a row can draw `group.items` as a pile and say "and 3 others" with a `Text`
bound to `group.others`. A `Text` with `countNoun` (`["other", "others"]`) writes a number with its
noun, the singular after 1. HUD groups each page on its own, so a group that runs across a page
break draws as two rows. Grain's apps group across pages, since they hold every page they've read.

Grain's notifications are a List grouped so, each row as Grain draws one. An `Icon` with
`style: "glyph"` draws its reason's glyph alone in a column before it, a heart in the heart's
colour for a favorite and the rest in the accent, picked from the reason by `names` and `tints`
(each value's glyph and tint). Under it go who did it (a `Faces` pile), their name, what they did
and when, then the comment, what a reply replies to (a `Text` with `style: "quote"`, on one line
behind a rule) and the gallery's title. The gallery or story's picture (an `Image` with
`size: "thumb"`) sits at the row's end. A row opens its gallery, its story in its account's archive,
or a follow's follower.

### Toggle

`Toggle` is a settings switch: a `label`, an `about` line under it, and `on`, a binding to whether
it is on now, with `default` where the data holds none (a setting never set). Its `call`, in a
bundled view alone, is the procedure a flip sends, its input a template with `{"$on": true}` where
the new state goes. The switch moves at once and flips back if the call fails. Once it lands the
view is read again, since the other switches' calls were made from the settings as they were.
Grain's settings page has a switch for each of `social.grain.actor.getPreferences`' upload and
notification settings, each calling `social.grain.actor.setPreference` with that whole kind.

### Choice

`Choice` is a setting of one of a few values, the sibling of `Toggle`: a `label`, an `about` line,
`options` (2 to 6 `{ label, value }`, each value a string), and `on`, a binding to the value chosen
now, with `default` (one of the values) where the data holds none of them. Its `call`, in a bundled
view alone, is the procedure a choice sends, `{"$on": true}` in its input where the value goes. Of
2 or 3 options it's drawn as a segmented control, of more as rows to pick from. It shows the choice
at once, goes back if the call fails, and reads the view again once it lands, as a Toggle does.
Grain's settings page has one for its theme (`social.grain.actor.defs#themePref`) and, for each
kind of notification, one for whom it's from (everyone or people you follow).

### Pinned feeds

Grain's camera, place and hashtag feeds have Pin feed where that feed isn't pinned, and Unpin feed
where it is, signed in, each in the screen's bar: Pin with the `pin` icon, Unpin with `pinned`, the
pin filled. Each draws nothing where its `$with` or `$without` would change nothing, and calls
`social.grain.actor.setPreference` with the whole `pinnedFeedsPref`. Pin adds the feed at the end
of those pinned (or of Grain's three, where none are), as Grain's apps
write it (`{ "id": "camera:Fuji X100V", "label": "Fuji X100V", "type": "camera", "path":
"/camera/Fuji X100V" }`). Unpin takes it out. An Action with a `call` and `reload` isn't kept as
done, since the view read again shows what it did, and the same call can come round again.

A view's scope holds the `at` it was opened with, so a view can draw a part of itself alone: a
Stack whose `where` holds it (`{ "at": { "$is": "feeds" } }`). The gear in Grain's feeds opens its
settings at `feeds` (`"at": "feeds"`), which draw My feeds and nothing else. That's a row for each
feed pinned (Grain's three where none are), with Move up but on the first, Move down but on the
last, and Unpin. Each sends the whole preference with that feed moved or gone. Grain's settings
have a row that opens My feeds too.

### Pages and the host's own

An `open` can also be `{ "url": "https://…" }`, a page the host opens in its browser. In a bundled
view it can be `{ "host": "signOut" }` too, which the host app does itself by signing the account
out. A host that doesn't do it leaves out the List item or Link that opens it, so a Grain tile in an
MCP host or the workspace has no Sign out. Grain's own clients (its web shell and iOS app, in
grain's repository) sign out so.

A bundled view can place `Accounts` too: the accounts the host app is signed in to, which the host
draws from what it keeps. Each is a row of its picture, its name over its handle, the one in use
ticked. A tap on another switches to it, and Add account under them signs in to one more. The
host reads each row from the frame's `account.picture` call, made as that account (its `name` and
`handle` paths, [the frame](#the-frame)). Where the host keeps no accounts, as an MCP host or the
workspace, the node's children are drawn in its place, as a `Stack`'s. Grain's settings give it the
account's own row, from the view's data. Switching, adding and signing out each draw the app anew
as the account then in use, so nothing of the one before shows (its screens remembered, what was
read ahead, its badge counts, an open form). Signing out leaves the others signed in, the one
before in use. The web shell keeps the accounts (`Sessions`, [the frame](#the-frame)), and HUDKit
and the Android kit draw the node from the accounts their app gives them (`ViewContext.accounts`).

Grain's settings page is an index, as Grain's own settings are. First come its accounts
(`Accounts`, else who's signed in). Then a row for each of its pages, each the settings opened at
its own `at`: Appearance (the theme chosen beside it), Account (the handle and DID, then Delete
account, a row), Notifications, Moderation (muted and blocked accounts), Feeds (My feeds) and
Privacy (upload defaults). A List with `chevrons` ends each row that opens something with a
chevron, as these do. Then Grain's policies, its own [pages](#pages-of-the-apps-own), and Sign
out. Delete account is an Action whose `deletes` repeats ([Action](#action)).

### Clamped text

| Prop on the tree | Holds |
| --- | --- |
| `clamp` | about the most lines shown before more, as the layout gives it |
| `shownRuns` | a `Text`'s or `RichText`'s runs cut to fit `clamp`, an ellipsis after them |
| `shownBlocks` | a markdown `RichText`'s blocks cut to fit `clamp` |

A `Text` or `RichText` with `clamp` is cut on the server, so a page drawn on a server and the
apps cut it in the same place and nothing moves when a browser hydrates the page. A line holds
44 characters, about what body text fills in a phone's 390-point column less what wrapping at
words leaves at a line's end. A line break ends a line, Han, kana, Hangul and emoji count two
characters each, and the text is counted in graphemes, never cut inside one. Text longer than its
budget is cut at the last word that fits, an ellipsis after it, and sent as `shownRuns` beside its
whole `runs`. Text that fits gets nothing. A link, mention or tag the cut falls in is left out
whole, unless it is the first run, whose words are cut and whose target is kept.

Markdown is cut by the same budget. Each block costs its lines: a paragraph its words, a heading
one more, a code block its lines and one, a table its rows and one, a picture its height across
the column, a list or quote its blocks. A margin between blocks costs one more. Blocks are kept
whole while they fit, then the next is cut where it can be: a paragraph at a word, a code block
or table to its first lines or rows, a list to its first items, a quote to its first blocks. A
heading or picture that doesn't fit is left out, and a first block nothing of which fits is shown
whole.

The clients draw the cut with a button under it, "Show more" (a `Text`'s, "more"), which draws
the whole. Nothing is measured. A `Text` is also held to its `clamp` lines while closed, so in a
column narrower than a phone's (a shelf's card) it ends in an ellipsis there. A shelf's card
opens its item itself, so it offers no button.

### Document

`Document` draws a long-form post's body. It draws Leaflet's pages of blocks
(`pub.leaflet.content`) or markdown (`at.markpub.markdown`), and otherwise the post's plain text.

### Embed

`Embed` draws a Bluesky post's embed as Bluesky does, in its AppView form or its record's form. It
handles these:

- images or a gallery
- a link card
- a video (played as Bluesky's HLS, or from the blob proxy)
- a quoted post with its own embed one level down (in a record's form, fetched from the AppView)
- a feed, list, starter pack or labeler card
- media with a quote

The bundled Bluesky feeds, timeline and thread draw every post's embed with it.

### FeedContext

`FeedContext` draws what a Bluesky feed item's post comes with, as the Bluesky app does. That's
"Reposted by" or "Pinned". For a reply it draws the thread's root, "View full thread" and the
parent above the reply, joined by a thread line. Where those aren't drawn, it shows "Replied to …".

### Tree and Chain

`Tree` draws items and, nested under each, the items at a path within it (a thread's `replies`). It
goes six levels deep by default. `Chain` walks from an object along a path (a thread's `parent`) and
draws what it passes, oldest first.

### Action

`Action` is a button that writes as the signed-in account, through `create_record` or
`delete_record`. It either holds a record to create or binds a uri to delete. A record's values can
be literals, bindings, `{"$now": true}`, `{"$strongRef": "<path>"}` (the `{ uri, cid }` of a
record), `{"$root": "<path>"}` (the view's own scope) or `{"$first": [values]}` (the first of 2 to 4
that resolves).

A record or a call's input can join strings too (`{"$join": ["camera:", { "$": "params.camera" }]}`,
2 to 8 of them) and edit an array read from the data. `{"$with": [array, key, element]}` adds the
element at its end, `{"$without": [array, key, value]}` takes out the elements whose `key` (a path
in each) holds the value, and `{"$move": [array, key, value, by]}` moves the one whose key holds it
`by` places (-1 one earlier). An edit that would change nothing (the element there already, none to
take out, a move past an end) resolves to nothing, so its button isn't drawn.

A bundled view's Action can delete what a query plans (`deletes`): `{ method, service, params }`, a
query of the service, its params a template as a call's input. Pressed, HUD asks the query as the
account, through its PDS, for the deletes of one `com.atproto.repo.applyWrites` (`{ writes: [{
collection, rkey }] }`, at most 200), then commits them in the account's own repository at once,
all or none, and calls the app's `refresh` with them, as after any write. A plan the app refuses,
one naming a collection HUD doesn't write or delete, or a commit the PDS refuses deletes nothing
and says why. The query's lexicon must answer `writes`. The clients press it as an Action's `call`:
the tree draws it as one, and `call_procedure` knows it a trusted view's deletion. Grain's gallery
is deleted so, the plan its AppView's, so what goes with it (its items, the photos no other gallery
of the account's places, their EXIF, the account's favorite of it and comments on it) is decided
in one place. A person's whole account takes more:

- `repeat: true` asks again until a plan comes back empty, so an account's data goes a part at a
  time and a run cut short carries on. The tree marks the call `repeat`, and the clients call it
  again while its answer's `output.done` is false, the button reading "Deleting… N records" as
  each answer's `output.deleted` adds up. HUD deletes so only for the operator's own clients: a
  workspace page, HUD's own app, or the operator's web app (its client document at
  `<HUD_PUBLIC_URL>/client-metadata.json`), never another MCP client the person connected.
- `collections` (32 at most) names the collections its deletes may reach. Sign-in asks to delete
  those no view writes (`repo:<collection>?action=delete`). A plan naming a collection sign-in
  doesn't ask to delete deletes none of that plan, and is never done: it stops, saying "Some
  records can't be deleted here yet" and naming those collections. Grain's sign-in leaves its
  groups' collections out, as groups don't work yet, so nobody is asked again to consent for them.
  An account with records in them keeps those, and is told so.
- `then` is a procedure called once nothing is left (without `repeat`, once the plan is
  committed), as the account, its input literal JSON but `{"$did": true}`, their DID.
- The Action's `handle`, with `confirm`, binds the account's handle, which the person types before
  the button goes on. Its `signOut: true` signs the account out once it's done, and where the host
  doesn't sign out, the Action isn't drawn.

HUD reads `repeat`, `collections` and `then` from the view, never from the client. Grain's Delete
account:

```json
{ "component": "Action", "props": {
    "label": "Delete account", "tone": "danger", "style": "row",
    "confirm": "Delete your Grain account?\n\nThis removes all your Grain galleries, …",
    "handle": { "$": "me.handle" },
    "deletes": {
      "method": "social.grain.server.getAccountDeletionPlan",
      "service": "did:web:grain.social#grain_appview",
      "repeat": true,
      "collections": ["social.grain.actor.profile", "social.grain.comment", "…"],
      "then": { "method": "social.grain.server.deleteAccount",
                "service": "did:web:grain.social#grain_appview",
                "input": { "did": { "$did": true } } } },
    "signOut": true } }
```

An Action is drawn compact by default, as a count beside it. `style: "button"` draws it as a
button of its own, as a profile's Follow. `style: "row"` draws it as a row of a `List` with
`style: "rows"`: the whole width, reaching the edges the rows reach, with their padding and their
words' size, its label from the start, `tone: "danger"` in the danger colour. Right after a List of
rows, or another row Action, it draws the line between rows above it and so joins them, so a
`Stack` with `gap: "none"` holding both makes one group. Grain's Settings put Delete account so,
after Sign out, as iOS's Settings put a destructive row last. Its question, its count of records
gone and what went wrong are a button's.

The bundled Bluesky feeds and thread have Like and Repost on every card. Grain's galleries,
comments and stories have Favorite (`social.grain.favorite`, with `viewer.fav` the one made).

### Picking covers

A `Covers` with `select` (a bundled view's alone) lets a person pick some covers and act on them at
once. It names its button (`label`, Select by default), what it does (`action`, Delete), what one
and several are called (`noun`), what the question adds (`confirm`), a `tone`, and a `call`, a
procedure as an Action's, its input read from each item (`{"rkey": {"$rkey": "uri"}}`), or a
`deletes`, a deletion plan's query as an Action's, its params read from each item. With `mine`, a
path in the scope, it's offered only where that holds the signed-in person's DID. An item whose
input can't be read can't be picked. Select sits at the right end of the row of the Panes the
Covers is in, else on a line of its own over them. Picking, a bar says how many are picked and
offers the action. Asked once (Delete 3 galleries?), it's done for each, one after another, each
plan asked once the one before is committed and read back, and the view is drawn again. Those
that failed stay picked, with what went wrong. Your own Grain page's galleries can be picked and
deleted so (`social.grain.gallery.getDeletionPlan`).

### Compose

`Compose` is a button that opens a form to write in: a post, a reply, a gallery, a comment or an
edit of a profile. It names three things:

- `fields`, what the form asks. A text field suggests accounts as @ is typed and marks its links,
  #tags and @mentions as they're typed. There are also a line, photos, languages, labels, a choice
  (such as who may reply), a place and a link card. Each photo is uploaded as it's added, through
  `place.hud.uploadBlob`, with its alt text and, for Grain, its camera's EXIF. A text, line or
  photos field's `value`, a binding the server reads, is what the form opens holding: a profile's
  name, or its avatar, shown and kept unless another is picked. A text or line's `value` may join
  words too (`{"$join": ["@", { "$": "author.handle" }, " "]}`): Grain's replies open holding the
  mention of whom they answer, so the mention is written as a facet and notifies them. A photos field with `round` draws
  its pictures round, as an avatar. One of a single photo, not round, draws it large, as a story
  shows it. A photos field with `camera` offers Camera beside the library: on iOS the device's
  camera, on the web a file picker with `capture` on a phone. Where there's no camera (a
  simulator, a desktop), picking is all there is. A place with `from`, a photos field, is filled
  with the place its first photo was taken at, from the photo's GPS, while none is picked. A photos
  field's `exif` and a place's `locate` may be bindings to an account's preference, on unless it
  holds false: Grain's New gallery and Add to your story keep to its upload defaults
  (`@photoMetadataPref`'s `includeExif` and `includeLocation`), as Grain's apps do.
- `given`, values it holds already, such as a reply's root and parent, or the record key of the
  gallery an edit replaces (`{"$rkey": "response.gallery.uri"}`).
- `writes`, a template (`hud_core::compose`) that the values fill into the records `apply_writes`
  writes at once. It can say `{"$value": name}`, `{"$each": …}` and `{"$facets": "<field>"}`,
  which makes a field's text into `app.bsky.richtext.facet`s with each handle resolved to its DID.
  A write with `update` replaces one record: its record key such as `self`, or a value holding one
  (`{"$value": "rkey"}`). HUD reads the record from the account's PDS first, `{"$stored": "<path>"}`
  reads it (an avatar's blob ref), and the fields the template names are set over it. A field left
  empty is taken out, and the rest (a gallery's place and labels) are kept. Where there's no
  record yet, it's created.

A text or line field is held to the lexicon of the record it's written into. HUD finds the record
property whose whole value is the field (`{"$value": "title"}`) and reads its `maxGraphemes` and
`maxLength` in the bundled lexicon (`hud_core::compose::limit`). A lexicon's `maxLength` counts
UTF-8 bytes, so a field gets both limits: `max` in graphemes and `maxBytes` in bytes. A Grain
gallery's title is 100 bytes, so 60 letters with accents and emoji can already be past it. A
comment is 300 graphemes and 3000 bytes. Every client counts both. Once what's left of the nearer
limit is within 10, or a fifth of that limit if that's more, it says how much is left. Past either
limit, it says how much is over in red, and the form won't send. A view's own `max`
only narrows the lexicon's. The view check refuses a `max` over the lexicon's graphemes or bytes. A
field no lexicon limits (a report's reason, a record whose lexicon isn't bundled) needs a `max` of
its own.

Once it's sent, the view is drawn again.

With `form: "photo"`, the form is a photo app's review of one photo, as Grain's new story is. Its
first field is photos of one. Once picked or taken, the photo is drawn edge to edge, and a place
field from it is a chip over the photo's foot. Grain's Add to your story is one, its photo field
with `camera`.

With `style: "field"`, the button is a field to write in, the whole width. It holds its first text
or line field's placeholder, else its label, as an empty text field holds its placeholder, and
opens the form. A Compose with `for`, another Compose's label, opens that one's form: its fields,
given values and writes are written once, and its draft is the same. It's drawn as its own
`style`, holding its own label, and is found among the nodes drawn in the same scope, never one of
a List's items. Grain's gallery has one under its comments
(`{ "for": "Comment", "label": "Add a comment…", "style": "field" }`), as Grain's apps and Instagram
have, so a comment is started where the comments are as well as by the comment icon beside the
favorites.

Signed out, a Compose draws nothing, or its count alone. With `signIn`, words such as "Sign in to
comment", it draws those instead, where the app can sign someone in (the web renderer's
`onsignin`, HUDKit's and Android's `onSignIn`), and they start signing in. The web shell signs in
so, and Grain's iOS app.

The bundled Bluesky thread has Reply and Quote on every post. `closed`, a binding that's true where
the author turned replies off, draws Reply as its count alone. Your own Bluesky page has New post.
Grain's galleries have Comment, each comment has Reply (`social.grain.comment`), and your own Grain
page has New gallery and Edit profile (`social.grain.actor.profile`, its avatar, name and bio).
Your own gallery's ⋯ has Edit gallery (its title and description, `social.grain.gallery`).

A #tag in a post opens a search for it in the app it's read in, as that app's page view's `tag`
says. For Bluesky that's `app.bsky.feed.searchPosts`, drawn by `views/bsky-search.json`. For Grain
it's the hashtag feed.

### What an item opens

The `open` prop says what clicking an item of a `List`, `Covers`, `Tree` or `Chain` opens. It can
be a record, by a binding to its at-uri. It can also be a query:

```
{ "query": "<NSID>", "params": { … }, "service"?: "did:…#fragment" }
```

The values of its params are literal or bound to the item. The bundled Bluesky feeds and timeline
open a post as its thread (`app.bsky.feed.getPostThread`).

On the web, a touch is a tap only if it stays put on something still. A touch that moved more than
10 px, or came down while what holds a `List` or `Covers` was still scrolling (a tap that stops a
fling), opens nothing in it, the item's own links and buttons included. A phone's browser can end
either as a click on whatever scrolled under the finger. A scroller is still scrolling until the
browser says it came to rest (`scrollend`), or until it hasn't moved for 100 ms where the browser
doesn't say, so a tap as soon as a glide stops opens. A mouse's clicks are left as they are.

## Query views

A view of a query's answers names its `method` instead of a collection. It also names the `service`
it calls by default, and one mode, `query`. That mode says where the answer's array of items and its
cursor are. It has a summary over the items, and a layout whose scope is
`{ method, service, params, response, items, cursor, joins }`.

An answer that's one thing (a thread) has no items. Its summary reads the scope instead. The
summary's `by` names the author, and its count is bound to an array. The count counts that array
and, with `children`, the arrays nested in it (`Thread: "…" by alice.example: 12 replies.`).

### Newer items

A list whose newest items come first can name each item's key in `latest`, a path within each item
(`"latest": "post.uri"`). HUD then puts `_meta.ui.latest` in the tree. It holds the same call with
no cursor (`call`), the items drawn by their keys (`items`, each `{ key }`), and the summary's
plural noun (`noun`, "posts"). Where the method takes a `limit`, that call asks for 2, within what
its lexicon allows and no more than the tile's own `limit`. That's the newest item and one more, so
a post pinned first (`includePins`) doesn't hide a newer one.

Something newer came when that call's tree has a key the drawn ones lack. So a pinned post at the
top of an author feed doesn't count, since it was drawn too. The bundled timeline, author feed,
custom feed (`app.bsky.feed.getFeed`, For You and Discover among them), Grain's feeds (Recent, For
you, Following and an account's galleries), and knotless's feed and notifications name a key. A
custom feed picks its top posts afresh, so a check often finds one the tile lacks, as it does in
Bluesky's app, which checks its feeds the same way. What the clients do with it is on
[the workspace page](workspace.md#newer-items).

## Query joins

Any mode may also join a few related queries, so one tile draws the answer with what goes with it.
That's a **query join**, in the mode's `join`:

```
{ "as", "query": "<NSID>", "params": { … }, "service"?: "did:…#fragment", "say"?: … }
```

### When it's called

HUD calls a query join once on the whole answer (a query's, or a page of records), never on each
record. It runs with all of a mode's joins at once, each within 3 s. A query view's join that reads
nothing of the answer (only its `params`, or who asked, `me`) starts with the query's own call, once
HUD has made the handles in its at-uri params DIDs. The rest run after the answer. It's called as
the person asking. Signed in, it goes through their PDS, proxied to its own service. Signed out, it
goes straight to the service, as `query` calls do.

The answer lands at `joins.<as>` (a page's, a record's own or a query answer's). It's null when the
call fails, runs out of time, or answers what its lexicon doesn't allow (HUD logs that).

HUD keeps a query's answer a few seconds for the person who asked it, as `query` calls do
([kept answers](internals.md#kept-answers)). A join that needs what's there now says `"fresh": true`.
HUD then calls it each time and keeps none of its answers. A query view's `query` mode may say
`fresh` for its own call too.

### Params

A query join's params are literals, bindings or `{"$root": …}` into the main scope alone. They
never read a join's result. The main scope is a query view's `params`, `response` and `at` (what
it shows first), a page's `did`, `handle` and `records`, and also a record's `value`.

A param can also be `{"$each": [array, path]}`. That's an array of the value at `path` in each
element of `array` there, in order, each once, at most 50 (`{"$each": ["records", "uri"]}` is every
record's uri). HUD asks with no more of them than the method's lexicon takes for that param (its
`maxLength`), the first. A binding that doesn't resolve, or an `$each` that finds nothing, skips the
call.

HUD checks the literal params against the method's lexicon as the view loads (a problem is the
view's error), and checks all of them before each call.

### Service and limits

A query join calls the query view's own service unless it names one. In a records mode it names one,
unless its method has a bundled view. A mode has at most 6 query joins, and they join nothing
further. An inline view's joins are held to the same limits.

`say` adds a few words to the tool's text. It reports how many `count` finds in the answer, or the
first line of `label` (`… README: knotless keeps a git…; latest release: 0.15.0.`).

### Pages

A page more (a cursor) keeps the first page's joins. The exception is a join that reads the page,
which runs on every page: a records page's that reads its `records`, or a query view's that reads
its `response`. A List of a records page's such join (`{"$root": "joins.<as>…"}`) is the page's.
Such a view's pages are no longer than its `pageSize`, so one call takes a page whole.

### Bundled query joins

The bundled views use query joins for these:

- a knotless repository's README (collapsed past about 20 lines) and latest release
- a Bluesky profile's latest 5 posts, and its feeds
- a standard.site post's replies on Bluesky, where it links a post (`bskyPostRef`)
- the posts Bluesky notifications of likes and reposts are about
- a Grain gallery's comments
- a Grain account's upload defaults (`social.grain.actor.getPreferences`), for its feeds' New
  gallery and its stories' Add to your story
- the [app pages](app-pages.md)

## Bundled views

`list_records`, `get_record` and `query` take a view inline (`view`). Otherwise they use the bundled
one for the collection or method, and otherwise they draw generically. [The playground](playground.md)
starts from any bundled view and draws an inline one as you write it.

| View | What it draws |
| --- | --- |
| `views/bsky-feed.json`, `views/bsky-author-feed.json`, `views/bsky-timeline.json` | The AppView's feeds, each reply with what it replies to |
| `views/bsky-feed-generators.json` | Feeds themselves (their names, makers and likes) |
| `views/bsky-thread.json` | A post's thread. Its parents, the post, and its replies as a tree |
| `views/bsky-profile.json` | An account's profile, with its latest posts and feeds |
| `views/bsky-notifications.json` | Your Bluesky notifications: who did what, the post it's about |
| `views/plyr-list.json` | plyr.fm albums and playlists |
| `views/plyr-likes.json` | plyr.fm likes, as a playlist |
| `views/plyr-tracks.json` | plyr.fm tracks an artist uploaded, to play |
| `views/plyr-top-tracks.json`, `views/plyr-latest-tracks.json` | plyr.fm's most liked tracks over a period, and its newest, to play |
| `views/standard-document.json` | Blog posts (standard.site documents) |
| `views/standard-publication.json` | A blog with its posts joined by backlinks |
| `views/knotless-*.json` | [knotless's views](knotless.md) |

A record that a bundled method view draws as its query (its [`records`](#records)) opens as that
query, by `get_record` with no inline view. A Bluesky post opens as its thread, and a repost as the
thread of the post it reposts. With Grain's views served, a Grain gallery opens as `getGallery`
draws it. A knotless repository, check, issue, pull, comment, profile or star opens as knotless's
own views draw it. No
bundled view draws those collections as records, and a collection is never shown as such.

## The operator's views

You can serve apps of your own beside the bundled views. Point `HUD_APPS` at a directory, and HUD
reads it as it starts (`hud serve`, and `hud resolve`, which installs its views as `hud serve`
does). Grain is served so, from grain's repository:

```
<HUD_APPS>/
  grain.social.json       an app: its name, tabs, routes, head, push, refresh, permissions, frame, pages and sign-in
  pages/terms.md          one of its own pages' text, in Markdown
  views/grain-feed.json   a view, named as its id
  lexicons/…              the lexicons its views and push call, at any depth (optional)
```

Each file at the top whose name holds a dot is an app file, named for its app's domain. Other files
there (`package.json`) aren't apps, so the directory can be a client's own. An app file is the one
the app's clients draw, with its `domain`, `name`, `tabs` and `routes`, each tab and route a tool
call, its `head` ([App heads](#app-heads)), its `push` ([Push](#push)), its `refresh`
([Refresh](#refresh)), its `permissions` ([Permission sets](#permission-sets)), its `frame`
([The frame](#the-frame)), its `pages` ([Pages](#pages-of-the-apps-own))
and its `signIn` ([The app's sign-in screen](#the-apps-sign-in-screen)). Its `hud` says which HUD
versions it runs on ([HUD versions](#hud-versions)).
HUD doesn't serve it. Each client bundles its own copy, since they're built from the same
repository as the file. Grain's are its `next/` web shell and `ios/` app, which reach HUD over
`/mcp`.

HUD trusts the operator's views as it trusts its bundled ones. So they may call procedures, join
queries, name origins and do anything else these pages let a bundled view do. That's also why HUD
holds them to what its tests hold the bundled views to, before it serves anything. If any file
falls short, HUD refuses to start and names every problem, each with its file and where in it.
`hud check <dir>` runs the same check without serving ([Checking apps](#checking-apps)).

- Each view parses as a trusted view, and a collection view draws both `list` and `record`.
- Each `call` is a procedure that takes JSON, and its input has the fields its lexicon takes and
  requires.
- Each query join's params are its method's, and it has a service.
- A method view's profile section's params are its method's.
- No two views draw the same collection, method or domain. A collection is in one view's `records`
  at most, and then no collection view draws it.
- Each tab's call, a tab's `guest` and each route's call draw what a view draws. That's `query` of
  a method view's method, `describe_app` of an app page's domain, `get_record` of a collection a
  view draws or opens as its query, or `list_records` of one a collection view draws. A route's
  `tab` is a tab's label. A route's `pager` is `true` or absent, and only a pager's route has an
  `under`: a path starting with `/` that a route has, each of its tokens one of its own path's.
- A tab's `first` is what its lexicon (`schemas/place.hud.tabFirst.json`) describes, with no key it
  doesn't name. Its call is a `query` of a method's NSID, and its `at` and `path` are dotted paths.
- An app's `push` registers and unregisters with procedures that take JSON, each with the fields
  its lexicon takes and requires and `{"$token": true}` in its input. Each of what a notification
  opens names a route's path, and its `when` binds every token of that path.
- An app's `refresh` names a procedure's `method` (an NSID) and the `service` it's of, and nothing
  else.
- An app's `permissions` is a list of 1 to 8 permission sets, each an `include` (the set's NSID)
  and, where its methods are called at a service, that `service`, and nothing else.
- An app's `head` names its `siteName`, and its texts are 1 to 300 characters, its `image` an
  https URL and its `twitter` an account as `@name`.
- An app's `frame` is what its lexicon (`schemas/place.hud.frame.json`) describes, with no key it
  doesn't name at any level. Its `destinations` is `tabs`. Its action's, items' and aside's calls
  draw what a view draws, and its picture's call is a `query` of a method's NSID. The picture's
  `tab` is a tab's label and its `at` a dotted path. Each icon is one of `catalog::FRAME_ICONS`.
- Each of the frame's account items has a `call` with a `label` and an `icon`, or a `host`
  (`signOut` or `signIn`, at most one of each), never both. Only a `signIn` item has an `about`. Each
  link's `href` is a path starting with `/` (but not `//`) or an https URL. `sizes.wide` is at
  least `sizes.content`, and `bands.sidebar` is wider than `bands.rail`.
- An app's `pages` are 64 at most, each what its lexicon (`schemas/place.hud.page.json`)
  describes, with no key it doesn't name. Each `path` is a plain path (`/` and segments of `a` to
  `z`, `0` to `9`, `-`, `_` and `.`, with no query or token) that no other page, no tab's `path`
  and no route's path (its tokens any segment) has. Each `markdown` is a `.md` file's path,
  relative to the app file's directory and never climbing out of it, and the file is there.
- An app's `signIn` is what its lexicon (`schemas/place.hud.signIn.json`) describes, with no key it
  doesn't name at any level. Each link in its `text` and `legal` goes to a path starting with `/`
  (but not `//`) or an https URL. Its typeahead's `url` is an https origin, with no path, query or
  fragment. Its `params` is an object of strings, numbers and booleans, and its paths are dotted,
  no segment empty.

HUD checks the methods against the lexicons in the directory's `lexicons/` and those it bundles
(`lexicons/` of HUD's repository), an app's own first ([An app's lexicons](#an-apps-lexicons)).
So an operator's view can only call or join a method one of them has. `just lexicons` keeps a
lexicon for each procedure Grain's views call and its app file pushes with.

An operator's view replaces the bundled view with its id, and any bundled view that draws what it
draws. So a `views/bsky-feed.json` in `HUD_APPS` is the Bluesky feed HUD serves. With
`HUD_WORKSPACE=off`, HUD serves the operator's views alone, with no bundled view beside them, so an
operator's view can't lean on a bundled one there (a query join naming a bundled view's service).
The scope HUD asks accounts for is what the served views write, upload and call
([what HUD asks for](sign-in.md#what-hud-asks-for)), through the permission sets their app files
name, if any.

### Checking apps

`hud check <dir>` loads a directory of apps exactly as `hud serve` loads `HUD_APPS`, and serves
nothing. It reads `HUD_WORKSPACE` as `hud serve` does, so check with `HUD_WORKSPACE=off` if you
serve the apps alone. It prints each problem on a line of its own, its file and then where in it,
and exits 1 if there's any:

```sh
$ HUD_WORKSPACE=off hud check next
next/views/grain-feed.json: query.layout.children[2].props.gap: must be one of none, xs, sm, md, lg
next/grain.social.json: app.routes[3].call: no view draws "social.grain.feed.getCameras"
hud check: 2 problems, as HUD 0.2.0 loads next
```

Run it with the HUD you deploy against, in the app's own checks, before the app ships. A HUD newer
or older than that one may hold the apps to more or less.

For an editor, HUD publishes the JSON Schemas of an app file and a view in its repository's
`schemas/json/` (`hud schema app` and `hud schema view` print them). Name them in a file's
`$schema`, and an editor completes keys, components and props, and marks a key HUD doesn't know:

```json
{
  "$schema": "https://knotless.dev/chadtmiller.com/hud/raw/v0.2.0/schemas/json/view.json",
  "method": "social.grain.unspecced.getCameras",
  …
}
```

Name the release you deploy against (its tag, `v<version>`), so the schema matches that HUD.
`main` names the newest.

A schema says a file's shape alone. What its calls draw, the lexicons it calls and its paths are
`hud check`'s to find. HUD makes the view's schema from the component catalog and the app file's
from its own lexicons of the frame, pages, sign-in screen and a tab's `first`, so `just
json-schemas` writes them again after a change to either, and a test fails until it does.

### HUD versions

An app file's `hud` names the HUD versions the app runs on, as a semver requirement:

```json
{ "domain": "grain.social", "name": "Grain", "hud": ">=0.2.0", … }
```

A HUD older than the app needs refuses it with that alone (`app.hud: the app needs HUD >=0.2.0, and
this HUD is 0.1.0: run a newer HUD`), since the rest of the app is written for a newer HUD. A HUD the
app runs on goes on to check the rest. HUD's version is its release's, the same as `@hud/renderer`,
`@hud/shell`, HUDKit and hudkit, and `hud check` says it. Leave `hud` out and any HUD checks the
app.

### Old builds and new views

A view changes on the server for every client at once, but an app's build in someone's hands keeps
the renderer it was built with, its kit. A kit is HUD's renderer on a platform: HUDKit on iOS,
hudkit on Android, `@hud/renderer` on the web. So each kit says its version as it calls, and HUD
fits each tree to the kit that draws it.

| Caller | Says | Drawn for |
| --- | --- | --- |
| HUDKit, hudkit or the web shell, on `/mcp` | `_meta`'s `io.modelcontextprotocol/clientCapabilities`, `extensions["place.hud/kit"]`: `{ platform, version }` | its version, the web's this HUD's |
| HUDKit's workspace client, by `callTool` | its input's `kit`, the same | its version |
| An MCP host drawing HUD's view (MCP Apps' `io.modelcontextprotocol/ui` capability, or any `initialize`-era host) | nothing more | this HUD's version |
| The workspace's page and the playground | nothing more | this HUD's version |
| Any other call | nothing | the oldest kit, 0.2.0 |

A kit's version is its build's, HUD's one version, which knope bumps in every package at once
([versions](sdk.md#versions)). The kits name themselves in `io.modelcontextprotocol/clientInfo` too
(`hud-kit-ios`, `hud-kit-android`, `hud-web`), for the logs, and HUD logs each tool call's kit
([what HUD logs](observability.md)).

A view gates a part on the kit with a Stack's, Pane's or Bar's `when` or `unless`, given
`{"$kit": requirement}`, a semver requirement, in place of a path:

```json
{ "component": "Stack", "children": [
  { "component": "Stack", "props": { "when": { "$kit": ">=0.3.0" } }, "children": [ … the new way … ] },
  { "component": "Stack", "props": { "unless": { "$kit": ">=0.3.0" } }, "children": [ … the old way … ] }
] }
```

HUD resolves the gate before it sends the tree, so a kit never gets a part it's gated out of.
`hud check` refuses a requirement semver can't read.

Any node can also give a `fallback`, a node drawn in its place by a kit that doesn't know its
component:

```json
{ "component": "Gauge", "props": { … }, "fallback": { "component": "Text", "props": { "value": { "$": "value" } } } }
```

Each catalog component and prop knows the HUD version it arrived in, its `since` in
`describe_collection`'s catalog, absent for what 0.2.0 has. Where a component is newer than the kit,
HUD sends its children in its place, drawn as a Stack, else its fallback, else nothing. A kit
handed a component it doesn't know, as one its platform doesn't draw yet, does the same in a release
build. A debug build shows a box saying the component isn't drawn there yet, so you notice. A prop a
kit doesn't know, it ignores.

An app file can name the oldest kit its builds in people's hands still use:

```json
{ "domain": "grain.social", "name": "Grain", "kits": { "oldest": "0.2.0" }, … }
```

Then `hud check` warns of each component or prop in the operator's views newer than that kit with
no kit gate around it, or, for a component, no fallback of its own. It's a warning, never a refusal.
With several apps, the oldest of theirs counts. `oldest` is a HUD version from 0.2.0.

### Optional keys

HUD refuses a key it doesn't know anywhere in a view, so a typo never slips through. A view written
for a newer HUD can still run on an older one, a key at a time. Write the key as `?key`, and HUD
reads it as `key` where it knows it. Where HUD finds a problem in it (a prop the component doesn't
have, a word it doesn't know, a key it doesn't name), it leaves the key out and logs a warning
instead of refusing to start:

```json
{ "component": "Stack", "props": { "?gap": "none" }, "children": [ … ] }
```

On a HUD with no `none` gap, that Stack draws with its default gap. A problem anywhere else still
refuses the view, and so does what leaving the key out breaks (a required prop gone). Giving a key
both ways (`gap` and `?gap`) is refused too. `hud check` prints the warnings, each naming the key's
file and where it is. App files have no optional keys, because their clients read them too.

### An app's lexicons

An app can ship the lexicons its views and push call, in `lexicons/` beside its views, at any depth
(Grain's `lexicons/social/grain/…` as they are). Each `.json` file there is a lexicon document,
named by its `id`. HUD checks the views against an app's lexicon in place of a bundled one of its
NSID and reads it as it serves (a call's input, a service's answer), since the views were written
against it. So HUD never refuses an app over a lexicon it doesn't bundle, or bundles at another
version. A file that isn't a lexicon, a second file of one NSID and one of HUD's own (`place.hud.*`)
are refused.

### A tab's root from the account's data

A tab's `call` is its root, the same for everyone. Signed in, its `first` chooses the root from the
account's data instead: the screen of the first item, of a list a query answers, whose path is one
of the app's screens. Grain's Home opens the first feed the person pinned, in the order they set in
My feeds:

```json
"first": {
  "call": { "name": "query", "args": { "method": "social.grain.actor.getPreferences",
            "service": "did:web:grain.social#grain_appview", "params": {} } },
  "at": "preferences.@pinnedFeedsPref.items",
  "path": "path",
  "after": "social.grain.actor.setPreference"
}
```

- `call` is a `query` of a method's NSID, made as the account.
- `at` is a dotted path to the list in its answer (in a query's `response`). A segment `@name` is
  the element of a list whose `$type` is `name` or ends `#name`, as the app's `scheme` reads one.
- `path` is a dotted path, in each item, to a path of the app's own site (`/feeds/following`,
  `/camera/Fuji X100V`). The item's screen is that path's by the app's routes, and at the tab's own
  path it's the tab's `call`. An item whose path has no route is passed over, so Grain's Groups, a
  feed the next grain.social doesn't draw, is never its Home.
- `after` is a procedure after which the root is chosen again.

Where nothing listed has a screen, or the query fails, the tab's `call` stands, and signed out it
draws its `guest`. Grain's Home has Recent as both, so it opens Recent where someone pinned
nothing, as Grain's own apps do.

The web shell's server chooses each tab's root for every page it draws (`rootsOf`), and the page
carries them, so `/` is the chosen feed from its first paint, with no redirect and nothing swapped
once hydrated. The tab's URL stays its own whichever screen it opens. Home is `/` for a camera's,
a place's or a hashtag's feed too, drawn as Home's root with its strip and no back. A tab's root is
at the tab's own URL, so a redirect to the feed's own path would be named `/` again once drawn. That
path opens the feed as Home's root too, while it's Home's root, and as its route says once it isn't.

After `after`, the browser chooses the roots again. A tab not on show takes its new root at once.
The tab on show takes it as it's chosen again, or as its own URL is gone back to, so the screens
over its root (My feeds among them) stay where they are. A history entry at a tab's own URL draws
the root chosen now, so a page loaded again after a reorder shows the new first feed. HUDKit reads
`first` too (`TabFirst`), and Grain's iOS app chooses Home's root as it starts and after `after`.
The Android kit reads it too (`TabFirst`), and Grain's Android app draws the app file's tabs along
the foot, each its own stack, choosing Home's root the same way.

### App heads

An app file's `head` is what a page of the app says in its HTML head where its view's
[head](#page-heads) says nothing. Grain's:

```json
"head": {
  "siteName": "Grain",
  "title": "Grain: photo sharing on the AT Protocol",
  "description": "Grain is a photo sharing app built on the AT Protocol. …",
  "image": "https://grain.social/og-default.jpg",
  "imageAlt": "Grain: photo sharing on the AT Protocol"
}
```

`siteName` is the site's name (`og:site_name`). `title`, `description`, `image` and `imageAlt` stand
in for a page whose tree has none of them, and `twitter` names the app's X account
(`twitter:site`). Grain's `next/` web app reads its copy of the file, as it reads its tabs and
routes.

### Push

An app file's `push` says how the app's clients register a device for push notifications with the
app's own server, and what a tapped notification opens. Grain's registers with Grain's AppView,
which sends the pushes itself:

```json
"push": {
  "register": {
    "method": "social.grain.notification.registerPush",
    "service": "did:web:grain.social#grain_appview",
    "input": { "serviceDid": "did:web:grain.social", "token": { "$token": true },
               "platform": { "$platform": true }, "appId": { "$appId": true } }
  },
  "unregister": { "method": "social.grain.notification.unregisterPush", "…": "the same" },
  "open": [
    { "when": { "uri": "at://{actor}/social.grain.gallery/{rkey}" },
      "path": "/profile/{actor}/gallery/{rkey}" },
    { "when": { "did": "{actor}" }, "path": "/profile/{actor}" }
  ]
}
```

`register` and `unregister` are calls of `call_procedure` as the signed-in account. The client
stamps three bindings in their input: `$token` (the device's push token: APNs's as hex on iOS,
FCM's on Android), `$appId` (the app's bundle or application id) and `$platform` (`ios` or
`android`). HUD sends them as it sends a trusted view's call
([procedures](sign-in.md#procedures)), so the app's server gets them through the account's PDS.

HUDKit does this on iOS and Android. Once someone's signed in, it asks to send notifications, and
with leave registers the device's token. Before they sign out, or switch accounts, it unregisters
the token as them, so the device stops getting the account's pushes. On Android the app hands
HUDKit's `Push` a `Device` that asks Android's leave and its push service's token (Grain's, FCM's),
and the tokens that service rotates, and draws the messages itself: HUDKit takes no push SDK.

`open` maps a tapped notification to one of the app's routes. Each entry's `when` holds patterns of
the notification's fields, written with a route's tokens. The first entry whose every field matches
fills its `path`, and the client opens that path as it opens the route. A token alone takes a
whole field (`{actor}`), and in a longer pattern one segment between slashes. A notification no
entry matches opens the app as it was.

### Refresh

An app file's `refresh` names the procedure of the app's own server that reads records the account
just wrote back from the account's PDS. HUD writes straight to the PDS, and the app's server would
otherwise hear of the write only when the network brings it, often seconds later. Grain's:

```json
"refresh": {
  "method": "social.grain.sync.indexRecords",
  "service": "did:web:grain.social#grain_appview"
}
```

After every write through HUD that lands (`create_record`, `apply_writes`, `delete_record`, a
view's update, and a deletion plan's commit), HUD calls each app's `refresh` whose own collections it wrote, those the app's
views write, with `{"uris": [...]}` (at most 25 a call), the records it created, changed or deleted. It calls
it as the account, through their PDS, before the write answers, so what the views read next shows
the write. A refresh that fails is logged, and the write stands. HUD bundles no lexicon for it, so
an app may name one it doesn't have.

### Permission sets

An app file's `permissions` names the [permission sets](sign-in.md#permission-sets) sign-in asks
for in place of the permissions its views' collections and methods would each take. Grain's:

```json
"permissions": [
  { "include": "social.grain.authFull", "service": "did:web:grain.social#grain_appview" }
]
```

The set is a lexicon the app publishes (`type: permission-set`), listing its `repo` collections
and the `rpc` methods it calls, each with `inheritAud: true`. Its `service` is the audience those
methods take, so HUD asks for `include:social.grain.authFull?aud=did:web:grain.social%23grain_appview`.
A set may only list NSIDs under its own namespace (`social.grain.` for Grain's), so HUD asks for
what the views do outside it, and their pictures, directly.

A set's contents are the app's to keep up. As HUD starts, it resolves each set and logs what a
view writes, deletes or calls that the set doesn't grant. Grain's `next/check-apps.mjs` checks the
same against its own copy of the set.

### The frame

An app file's `frame` says how the app's clients draw the frame around its screens. That's the
navigation, the app's one primary action, the account's area, links at the foot and an aside.
Grain's:

```json
"frame": {
  "destinations": "tabs",
  "action": {
    "label": "Create",
    "icon": "imagePlus",
    "call": { "name": "query", "args": { "method": "social.grain.feed.getFeed",
              "params": { "feed": "at://did:web:grain.social/social.grain.feed.generator/foryou" },
              "compose": "New gallery" } }
  },
  "account": {
    "picture": {
      "tab": "Profile",
      "call": { "name": "query", "args": { "method": "social.grain.actor.getProfile",
                "service": "did:web:grain.social#grain_appview", "params": { "actor": "me" } } },
      "at": "avatar",
      "name": "displayName",
      "handle": "handle"
    },
    "items": [
      { "label": "Settings", "icon": "settings",
        "call": { "name": "query", "args": { "method": "social.grain.actor.getPreferences" } } },
      { "host": "signOut", "label": "Log out", "icon": "logOut" },
      { "host": "signIn", "label": "Sign in", "icon": "logIn", "about": "Share your photography" }
    ]
  },
  "links": [
    { "label": "Terms", "href": "/support/terms" },
    { "label": "Privacy", "href": "/support/privacy" },
    { "label": "Copyright", "href": "/support/copyright" },
    { "label": "Guidelines", "href": "/support/community-guidelines" },
    { "label": "Child Safety", "href": "/support/child-safety" },
    { "label": "AT Protocol", "href": "https://atproto.com" }
  ],
  "sizes": { "content": 600, "wide": 935 }
}
```

Leave `frame` out and nothing changes. Each field is optional too.

- `destinations` is `tabs`, the app's own tabs (label, icon, call and badge). They're one list,
  drawn as a bottom bar, a rail or a sidebar by the window's width.
- `action` is the app's primary action, drawn only to someone signed in. It has a `label` (1 to 40
  characters), an `icon` and a `call`. A `query` call with `compose` opens its form over the screen
  you're on, with no new screen and no history entry. Any other call opens as a screen on the tab
  on show.
- `account` is the account's area. Its `picture` reads the account's picture from a query's answer
  (`call`, at the dotted path `at`), and the tab named by `tab` shows it in place of its icon. The
  server reads it for each page, so the picture is there from the first paint. Its `name` and
  `handle`, dotted paths in the same answer, name the account in its row among the accounts (a
  view's [Accounts](#pages-and-the-hosts-own)), the call made as each account in turn. Its
  `items` (8 at most) are screens of the app's, each a `label`, `icon` and `call` shown signed in.
  An item can be one the host draws instead. That's `signOut`, shown signed in, or `signIn`, shown
  signed out with its `about` line over it.
- `links` (12 at most) are a `label` and an `href` each, drawn at the navigation's foot.
- `aside` is a screen drawn right of the column (`call`), `width` pixels wide (200 to 480, 320 by
  default).
- `sizes` are the widths of the column a view's [measure](#how-wide-a-view-is-drawn) asks for, in
  CSS pixels. `content` is 600 by default (320 to 1600) and `wide` 935 (up to 2400). A `full` view
  takes the column to the window's edge.
- `bands` are the window widths where the navigation changes. `rail` is 600 by default and
  `sidebar` 1200 (each 320 to 4000).

The web shell (`@hud/shell`, in `web/shell`) draws it, and draws an app with no `frame` with every
default. Under `bands.rail` the destinations are a bottom bar, and the action is left to the
screen's own Bar. From there to under `bands.sidebar` they're a rail of icons, each label its
tooltip. From `bands.sidebar` they're a labelled sidebar. In both, Search follows the first
destination where the app has a `search`, the account's screens follow the destinations, and the
action is a filled button under them. Log out and the links sit at the foot, and the picture
shows on its tab. Signed out, Sign in sits at the foot with its `about` line. The rail leaves the
links out. Where the action's `compose` names a form, a screen's Bar button for that form (a
`Compose` of that label, as Grain's feeds' + for New gallery) is hidden in the rail and the
sidebar, signed in, since the action beside it opens the same form. Under `bands.rail` it shows.
The renderer marks a Bar's `Compose` with its label (`data-bar-form`) for this, and other Bar
buttons, such as the feeds' gear, stay. The shell decides all of this in CSS from the window's
width, so the page the server draws is the page the browser hydrates. A host may draw the
navigation at bands of its own, over the frame's.

Each destination is a stack of screens. Choosing one shows its root, as its link says, and lets
go of the screens left over it. Choosing it again at its root reads it again. A screen that is a
destination's own, such as a link to your own profile or its URL, opens as that destination
rather than as a copy pushed over another, on the server as in the browser. A screen opened
over the same screen isn't pushed again, and one opened from another destination starts from that
destination's root. A screen's back arrow is the browser's back where the entry before is the
screen under it. Otherwise, as for a search opened from another destination, it steps up in place
of the entry on show, so the browser's back still goes where it went. A step back is taken once
from each entry, so a pager of pages closes to the screen it was opened over even when asked to
close twice at once, such as a story running out as ✕ is tapped. A screen under the one on top, and
a pager's pages beside the one in front, are `inert`: out of reach of the keyboard and of screen
readers. A screen under the one on top that has never shown, such as a destination's root under a
page loaded at a screen over it, is drawn only once it shows, so loading the page never draws a
screen nobody sees. On a phone, the links that show a while are read ahead, but only once the page
has loaded and the browser is idle, two calls at a time, and never a link on a screen out of
reach. Focus follows the screen on top, as a native stack's does. A screen opened from a link or
button takes it at its title, and the screen gone back to gets it back where it was left. Signed
out, forms aren't offered: a `Compose` with a count shows as that count. An `Action` that creates
or deletes a record (a ♡, a Follow) goes to sign in when it's pressed, as Grain's web asks, rather
than failing.

A screen whose tree has a `next` pages as you scroll, as HUDKit's and the Android kit's lists do.
Its foot is a Load more button, and once the page has hydrated, the shell loads the next page itself
as that foot comes within a screen of the screen's own scroll (an `IntersectionObserver`, `auto` on
the renderer's `LoadMore`). Each page appends to the tree's page list (a `List`, `Covers`,
`Gallery` or `Player`) below what's in view, so the scroll doesn't move, and the list lets go of
items far from view as it grows ([Memory](memory.md)). It loads one page at a time, and only on the
screen in front (not one under another, under a pager or in a tab not on show, nor while its call
is made again). A page that fails shows its error with Try again and loads nothing more until it's
pressed. Where the browser asks to save data (`navigator.connection.saveData`), the button alone
pages. The button stays in every case, for the keyboard, screen readers and a page drawn with no
script. A `Messages` conversation loads its earlier messages by its own button at its top.

A screen whose own `Tabs` strip selects it and offers a destination's root too is that root's
swap, as choosing it in the strip makes it. Grain's Following, Recent or a pinned feed, each a
choice of Home's strip, are like this. Its URL is drawn as that destination's root level, with its
strip and no back arrow, by the server as by the browser, whatever its route's tab. The shell needs
no list of such routes: the answer's strip says so. One the strip doesn't select, such as a camera
that isn't pinned, opens over its route's tab as any screen does.

Pressing the action makes its call in the background (read ahead as the button is hovered or
pressed). Where the answer has a `Compose` marked `open`, the shell draws a tree of that form alone
over the screen on show (`Tree`'s `form`): the same modal any `Compose` opens, with no button and
nothing else of the screen it came from. Its writes are the account's, as any screen's are, so every
screen is read again as it shows. Once sent, the shell opens the screen of the first record it made
that one of the app's routes names, over the tab on show. For Grain's New gallery, that's the new
gallery, by `/profile/{actor}/gallery/{rkey}`, whose call names
`at://{actor}/social.grain.gallery/{rkey}`. Where no route names one, the screen on show is read
again. Cancelled, the form closes and nothing moves. A call whose answer has no such form (signed
out, an error, a view without one) opens as a screen on the tab on show.

The column is `sizes.content` wide at most, and a `wide` view takes all the room right of the
navigation, up to `sizes.wide`. The shell draws the aside right of the column only where the
window holds the navigation, the screen's measure and the aside. It never draws one beside a
`full` view.

The shell is a Svelte package beside the renderer. Its host gives it the app file, its router's
history (`Navigation`: the entry on show's state, a way to make one, and when the page is
entered), where its server takes the pages' calls, uploads, sign-in, sign-out and switching
accounts (`Host`), and what its server read for the page with `@hud/shell/server` (`screenAt`,
`signInScreen`, `frameData`, `lookHead`). Grain's `next/` is such a host, on SvelteKit.

The host's server keeps its sessions at HUD with `@hud/shell/server`'s `Sessions`, given HUD's
address, the app's origin, its name, its callback's path and the secret its cookies are sealed
with. Its `request` makes each request's `Hud`, the way to HUD as the account in use, which answers
the endpoints the host routes to it (`signIn`, `callback`, `signOut`, `use`, `mcp`, `upload`). It
signs in as an MCP client of HUD, a backend for frontend: only the server holds the tokens. A
browser keeps up to five accounts, each its own HUD session and tokens, in one sealed HttpOnly
cookie (AES-256-GCM): five seal to under 1.7 KB, so nothing is kept on the server and a restart
signs no one out. Signing in again while signed in adds an account, since each sign-in names its
account afresh on the app's sign-in screen. Signing in to one kept already takes its new tokens and
revokes the old. Signing out revokes the account in use at HUD and leaves the rest. Switching is to
an account the browser signed in to alone. A row's name, handle and picture are read with that
account's own tokens and kept in the server's memory a while, never in the cookie.

HUDKit and the Android kit don't read the frame yet. HUDKit will draw it as a `TabView` with
`.sidebarAdaptable`, the destinations its tabs and the action and account in its sidebar or
toolbar. Android will draw it with `NavigationSuiteScaffold`, a bar, a rail or a drawer by the
window's size class. Both will open the action the same way: its call made in the background, its
form alone as a sheet over the screen on show, and no screen pushed.

### Pages of the app's own

An app file's `pages` are the app's own static pages, such as its terms and its privacy policy,
each written in Markdown in a file beside the app file. Grain's:

```json
"pages": [
  { "path": "/support/terms", "title": "Terms and Conditions",
    "description": "The terms of using Grain, the photo sharing app built on the AT Protocol.",
    "markdown": "pages/terms.md" },
  { "path": "/support/privacy", "title": "Privacy Policy", "…": "and so on" }
]
```

Leave `pages` out and nothing changes.

- `path` is the page's path on the app's site, as `/support/terms`.
- `title` (up to 80 characters) is its screen's title, and its HTML head's, as `<title> - <app's
  name>`.
- `description` (optional, up to 300 characters) is what its head says of it, for a search result or
  a link's preview.
- `markdown` is its text's file, relative to the app file's directory: GitHub's Markdown (GFM),
  read as a `RichText` of `gfm` reads it, so headings, lists, tables and the rest.

HUD reads each file as it starts and refuses to start where one isn't there. `describe_app` with
`page` (the page's path) answers the page: its Markdown as data and, drawn, its title in the
screen's `Bar` over its text, with its head (`title`, `description`, and `canonical`, its path).
In a page's text, and nowhere else, a link to a path of the app's own (`/support/privacy`) opens it
on the app's site, `https://<domain>/support/privacy`, and a `mailto:` link writes mail. Any other
link opens a page (http or https) or nothing, as in any Markdown HUD draws.

A client draws each page as a screen of its path, as if it were a route whose call is that
`describe_app`. The web shell tries the pages before the routes (`routesOf`), so a page opens by
its link and by its URL, over the tab on show (from a link) or Home (loaded), with the browser's
back and forward. The server draws it with its head, for search engines to index, and the browser
hydrates it as drawn. A footer link whose `href` is a path opens its screen in the app, and so does
a link in a screen's text to the app's own site (this origin, or its domain's, as a page links
one): where no route has its path, the browser goes there.

HUDKit makes each page a route the same way (`Route.all`), so an app built on it opens a page's
path in the app, drawn by its `RichText`, and its text's mail links open the mail app. A link to
the app's own site reaches the app's `onOpenLink`, which opens it by `Route.screen` where a route
has its path. The Android kit reads an app file's routes the same way (`Route`), so Grain's Android
app opens grain.social links as their screens. It doesn't make pages routes yet.

### The app's sign-in screen

An app file's `signIn` is the app's own sign-in screen: what it says, and where it finds accounts
as a handle is typed. Its clients draw it in place of HUD's sign-in page, in the app's own look.
Grain's, with its web app's words:

```json
"signIn": {
  "title": "Log in with your atmosphere account",
  "text": "[What is an atmosphere account?](https://atmosphereaccount.com/)",
  "placeholder": "e.g. user.bsky.social",
  "legal": "By signing in you agree to our [Terms](/support/terms), [Privacy Policy](/support/privacy), and [Community Guidelines](/support/community-guidelines).",
  "create": { "text": "Don't have an account?", "label": "Create one" },
  "typeahead": {
    "url": "https://typeahead.waow.tech", "method": "tech.waow.typeahead.searchActors",
    "param": "q", "params": { "limit": 5 }, "items": "actors",
    "did": "did", "handle": "handle", "name": "displayName",
    "avatar": "avatar", "avatarFallback": "avatarFallback"
  }
}
```

Leave `signIn` out and the app's clients send people to HUD's sign-in page.

- `title` is the screen's heading, `text` a line under it, `placeholder` what the handle's field
  holds while it's empty, and `legal` a line under the form. In `text` and `legal`, Markdown's
  `[label](href)` is a link, to a path of the app's own site or an https URL.
- `create`, where given, offers making an account: its `text` and a button, its `label`. HUD makes
  it at its sign-up PDS ([creating an account](sign-in.md#creating-an-account)).
- `typeahead`, where given, is who matches what's typed: a public query at an XRPC host of its own,
  called by the client directly, as no one, never through HUD or a PDS. Its fields are a Compose
  text field's `suggest`'s, with `url` for the host: `GET <url>/xrpc/<method>?<param>=<typed>`
  with its `params`, the accounts at `items` in the answer, and each one's `did`, `handle`, `name`,
  `avatar` and `avatarFallback` at those paths in it. A picture is drawn from `avatar`, falling back
  to `avatarFallback` where that fails to load, and only from an https URL. It's asked from two
  letters typed (a leading `@` dropped), a moment after typing stops. typeahead.waow.tech finds any
  atproto account, not only those an app's appview has seen, so someone new to Grain finds
  themselves.

With a `signIn`, HUD sends that app's web clients straight on to the account's server, the handle
typed their `login_hint`, with no page of HUD's between
([the OAuth flow](sign-in.md#the-oauth-flow)). A refusal comes back to the client to show.

The web shell draws the screen at the host's sign-in path (Grain's `/auth/signin?back=…`), in the
frame over no tab, server-rendered and hydrated alike at every width (`signInScreen`, `SignIn`):
the heading and its line, the field, the `legal` line, Cancel (back where it came from) and Sign
in, and `create`. Signed in, it's Settings' Add account. As a handle is typed, whoever matches
drops down under the field, each with their picture, handle and name. The arrows choose one, and
Enter or a click picks it, filling in the handle and signing in at once. Escape closes the list.
The form posts to the host's server (`Hud.signIn`), which asks HUD to start signing in itself.
Where HUD goes on to the account's server, the browser goes there. Where HUD sends it back refused,
the screen is drawn again with the handle and why. A refusal at the account's server comes back
through the callback to the screen the same way. Without JavaScript, it's a form like any other.

HUDKit reads the same section (`SignInPlan(app:)`, its `Typeahead`'s `search`, and `linked` for
the lines' links), and an app built on it draws its own native screen from it. Grain's iOS app
draws it as grain-ios's sign-in: the same words over its photo, the typeahead asked 200 ms after
typing stops, a hardware keyboard's arrows and Return choosing and picking, then HUD's sign-in
with the handle as its `login_hint`, or `prompt=create` for its Create one. The Android kit reads
it too (`SignInPlan`), and Grain's Android app draws the same screen, then signs in through HUD in
an Auth Tab where the browser has them, else a Custom Tab, sent back to its own
`<application ID>:/oauth/callback`, which HUD's app client takes.

### Grain's views

Grain's views are an operator's. Its app file and views live in grain's repository, and HUD's tests
load a copy as an operator's (`crates/hud-core/src/testdata/grain/apps`). The pages here use them as
examples.

| View | What it draws |
| --- | --- |
| `grain-feed` | The feeds of galleries from Grain's AppView, each as Grain's card: who and where, the first photo, Favorite and comments, its camera, title and description. The feeds the person pinned are a strip over them, cameras, places and hashtags among them. The home feeds have who has stories under that, and a + for New gallery and a gear for My feeds in the bar. A camera's, a place's and a hashtag's feed is wide, its galleries three across, with a pin in the bar that pins or unpins it, and a place's a map of it over its galleries |
| `grain-stories`, `grain-story-archive` | An account's stories of the last day, each marked watched as it shows, and every story it posted |
| `grain-mutes`, `grain-blocks` | The accounts you muted and blocked on Grain, each undone in place |
| `grain-settings` | Your Grain settings, in Grain's order: the account and Sign out, theme, My feeds, notifications, muted and blocked accounts, upload defaults, then Grain's import and its policies, its own pages. Opened at `feeds`, My feeds alone: the feeds pinned, to move and unpin |
| `grain-gallery-view` | One gallery as that card with all its photos, then its comments and more of the photographer's galleries |
| `grain-explore` | Grain's Explore (`getLocations`): a search, its top cameras and places, each opening its galleries and with a See all, over the newest galleries. With `pins: true` it's Grain's Locations, every place on a map over the top places' cards |
| `grain-cameras` | Grain's Cameras (`getCameras`): its top cameras as cards, each with its photos' count, opening its galleries |
| `grain-search`, `grain-search-people` | Grain's galleries and accounts matching a search, under the field to search again |
| `grain-followers`, `grain-following`, `grain-known-followers` | Who follows an account on Grain, whom it follows, and those of its followers you follow |
| `grain-notifications` | Your Grain notifications: who did what, the comment or gallery it's about, [grouped](#grouping) as Grain groups them |

## Trust and origins

HUD holds a view to its shape strictly. An invalid view is the tool's error, with every problem
named along with where it is, so the model can fix it.

Only bundled views and [the operator's](#the-operators-views) are trusted. A view names `origins`,
the https origins whose media URLs its bindings may load (plyr.fm keeps some audio and art off the
PDS, and the AppView keeps its images on `cdn.bsky.app`), and `thumbnails`, URL prefixes on them
rewritten to a smaller picture's. A trusted view may name any origin. A view given inline may name
only origins some trusted view names, so it can draw the AppView's pictures too, and anything else
it loads goes through blob refs. The UI resource's CSP allows exactly the trusted views' origins,
beside the server's own origin, the image CDN's (`HUD_IMAGE_CDN`), and Bluesky's video service and
CDN, for posts' videos. So an inline view never widens it.
Its one fetch besides the server is a `Map`'s tiles: the Protomaps basemap of OpenStreetMap's data,
vector tiles from `https://tiles.grain.social`, which serves them openly with no key. They're drawn in
its light or dark flavour, as the page is.
No code names Bluesky, Grain, plyr.fm, standard.site or knotless, but one: the map's tiles
come from `tiles.grain.social` (`catalog::MAP_TILES`), a basemap HUD's operator runs, as no open
one serves dark vector tiles without a key.

A result says whether its view is trusted (`_meta.ui.trusted`). A trusted view's actions run on one
click. Any other view's actions ask the person to confirm, showing the record first.

## Feed interactions

Only a trusted view may report feed interactions:

```
"interactions": { "feed": <binding>, "item": <path>, "feedContext"?: <path>, "reqId"?: <path> }
```

The feed is bound in the query's scope, and the rest are paths within each item. HUD resolves them
into the tree. `_meta.ui.report` is the feed, and each item's `report` is what the feed is told of
it.

Only a trusted view may have an `Action` with `interaction`
(`{ event: "app.bsky.feed.defs#requestMore" | "…#requestLess" }`). That asks the feed for more or
less like the item. The bundled feed view (`app.bsky.feed.getFeed`) does both, with More like this
and Less like this on every card.

## Apps and profile sections

A bundled view also names its app (`"app": "Bluesky"`, one line). That's the name an account's
profile gives the domain behind the view's NSID. The view may add a section to accounts' profiles
(`profile`).

A method view's profile section is `{ "title", "params" }`. It calls the view's query with those
params, each a literal or `{"$actor": "did"}` (the account's DID). It shows where the account holds
any collection of the query's domain.

| View | Title | Shows |
| --- | --- | --- |
| `bsky-author-feed` | "Bluesky" | The account's 3 latest posts without replies |
| `grain-feed` (an operator's) | "Grain" | The account's 3 latest galleries |
| `knotless-actor-repos` | "knotless" | The account's repositories |

A collection view's profile section is `{ "title", "limit" }` (1 to 10, 3 by default). It shows
that collection's newest records, drawn by the view's list layout, where the account holds the
collection. standard.site's blog posts ("Blog") and plyr.fm's tracks, albums, playlists and likes have one.

### Activity

A collection view may also name its records' activity (`"activity": "Posted"`). That's a short
past-tense verb, 20 characters at most, for where its list's summary labels a record by its own
words. standard.site's documents have "Published", plyr.fm's playlists "Made" and its tracks "Uploaded".

## Records

A bundled method view may name the records it draws as its query (`records`, 1 to 8 of
`{ "collection", "params", "at"?, "activity"? }`). Opening a record of that collection by its at-uri
(`get_record`, with no inline view) then answers exactly as `query` answers the view's method with
`params`, as the same caller. That includes `_meta.ui`, text, `next` and all. `at`, a binding into
the record too, is what the answer shows first where it shows one thing at a time, as an `open`'s
`at` is.

Each param is a literal or a binding into the record as a join reads one, `{ uri, cid, did, value }`.
HUD reads the record from its repository only where a param reads its `value` (or `cid`).
Otherwise the record is just its at-uri, with its repository named by DID. If a binding finds
nothing, the record can't be read, or the query doesn't answer, HUD draws the record as before,
generically.

`activity` is `{ "verb", "noun": [one, many], "label"?: binding }`. It's what making one of these
records counts as in a profile's recent activity, as a collection view's activity is.

A collection is named by one bundled view at most, and drawn by no collection view. The tests hold
each entry's params to the method's lexicon, and each binding to the record's lexicon. An inline
view names none of these.

| Records | Drawn as |
| --- | --- |
| Bluesky's posts | Threads, by `uri`, activity "Posted" |
| Bluesky's reposts | Threads, by the subject's uri |
| Grain's galleries (an operator's view) | Activity "Posted" |
| Grain's stories (an operator's view) | Their account's archive (`getArchive`, by the record's `did`), at the story |
| knotless's repositories and checks | `getRepo` (repositories have activity "Created") |
| knotless's issues, pulls and comments | `getThread` (issues and pulls have activity "Opened") |
| knotless's profiles | `getProfile`, by the record's `did` |
| knotless's stars | `getActorStars`, by the record's `did` |

A knotless release names its repository by key, not at-uri, so nothing routes it and it draws
generically.

## Launch

A bundled method view may also offer places to go in its app (`launch`, 1 to 4 of
`{ "title", "params"? }`). Each param is a literal or `{"$me": "did" | "handle"}`, the person signed
in. These are the app's entry points. An app's page (`describe_app`) and the
[workspace's](workspace.md) New tile list them, with their params made the person's.

Signed out, an app's page leaves out the entries that name the person, and those whose view's query
needs an account (its `signIn`). Each title says what it shows, and the tile's header says whose.

| App | Entries |
| --- | --- |
| Bluesky | Posts and Saved feeds (`bsky-author-feed`, `bsky-feed-generators`) · Discover (`bsky-feed`, Bluesky's whats-hot feed) · Notifications (`bsky-notifications`) · Following (`bsky-timeline`) |
| Grain (an operator's) | For you, Following, Recent and Galleries (`grain-feed`) · Explore (`grain-explore`) · Notifications (`grain-notifications`) |
| knotless | Repositories, Activity, Everyone's activity and Notifications |