chadtmiller.com/hud
A remote MCP server that shows atproto records as interactive UI inside MCP Apps hosts
place.hud.hudkit 0.3.0 Latest 5 packages
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.items that point at it and at a photo each, and the social.grain.photos.
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, a summary, a head and a
layout.
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:
refjoins the record an at-uri or strongRef names.eachjoins the records an array's elements name.backlinksjoins the records of the same repository that point back at the record, ordered.countssays 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 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:
"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 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 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 Links 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):
"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). 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) 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 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). 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). 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
{ "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:
{ "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
{ "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). 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), 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, and Sign
out. Delete account is an Action whose deletes repeats (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: trueasks 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 callrepeat, and the clients call it again while its answer'soutput.doneis false, the button reading "Deleting… N records" as each answer'soutput.deletedadds 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.thenis a procedure called once nothing is left (withoutrepeat, once the plan is committed), as the account, its input literal JSON but{"$did": true}, their DID.- The Action's
handle, withconfirm, binds the account's handle, which the person types before the button goes on. ItssignOut: truesigns 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:
{ "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, throughplace.hud.uploadBlob, with its alt text and, for Grain, its camera's EXIF. A text, line or photos field'svalue, 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'svaluemay 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 withrounddraws its pictures round, as an avatar. One of a single photo, not round, draws it large, as a story shows it. A photos field withcameraoffers Camera beside the library: on iOS the device's camera, on the web a file picker withcaptureon a phone. Where there's no camera (a simulator, a desktop), picking is all there is. A place withfrom, 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'sexifand a place'slocatemay 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'sincludeExifandincludeLocation), 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 recordsapply_writeswrites at once. It can say{"$value": name},{"$each": …}and{"$facets": "<field>"}, which makes a field's text intoapp.bsky.richtext.facets with each handle resolved to its DID. A write withupdatereplaces one record: its record key such asself, 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.
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). 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
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
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 |
A record that a bundled method view draws as its query (its 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), its push (Push), its refresh
(Refresh), its permissions (Permission sets), its frame
(The frame), its pages (Pages)
and its signIn (The app's sign-in screen). Its hud says which HUD
versions it runs on (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).
- Each view parses as a trusted view, and a collection view draws both
listandrecord. - Each
callis 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
recordsat most, and then no collection view draws it. - Each tab's call, a tab's
guestand each route's call draw what a view draws. That'squeryof a method view's method,describe_appof an app page's domain,get_recordof a collection a view draws or opens as its query, orlist_recordsof one a collection view draws. A route'stabis a tab's label. A route'spageristrueor absent, and only a pager's route has anunder: a path starting with/that a route has, each of its tokens one of its own path's. - A tab's
firstis what its lexicon (schemas/place.hud.tabFirst.json) describes, with no key it doesn't name. Its call is aqueryof a method's NSID, and itsatandpathare dotted paths. - An app's
pushregisters 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 itswhenbinds every token of that path. - An app's
refreshnames a procedure'smethod(an NSID) and theserviceit's of, and nothing else. - An app's
permissionsis a list of 1 to 8 permission sets, each aninclude(the set's NSID) and, where its methods are called at a service, thatservice, and nothing else. - An app's
headnames itssiteName, and its texts are 1 to 300 characters, itsimagean https URL and itstwitteran account as@name. - An app's
frameis what its lexicon (schemas/place.hud.frame.json) describes, with no key it doesn't name at any level. Itsdestinationsistabs. Its action's, items' and aside's calls draw what a view draws, and its picture's call is aqueryof a method's NSID. The picture'stabis a tab's label and itsata dotted path. Each icon is one ofcatalog::FRAME_ICONS. - Each of the frame's account items has a
callwith alabeland anicon, or ahost(signOutorsignIn, at most one of each), never both. Only asignInitem has anabout. Each link'shrefis a path starting with/(but not//) or an https URL.sizes.wideis at leastsizes.content, andbands.sidebaris wider thanbands.rail. - An app's
pagesare 64 at most, each what its lexicon (schemas/place.hud.page.json) describes, with no key it doesn't name. Eachpathis a plain path (/and segments ofatoz,0to9,-,_and., with no query or token) that no other page, no tab'spathand no route's path (its tokens any segment) has. Eachmarkdownis a.mdfile's path, relative to the app file's directory and never climbing out of it, and the file is there. - An app's
signInis what its lexicon (schemas/place.hud.signIn.json) describes, with no key it doesn't name at any level. Each link in itstextandlegalgoes to a path starting with/(but not//) or an https URL. Its typeahead'surlis an https origin, with no path, query or fragment. Itsparamsis 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).
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), 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:
$ 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:
{
"$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:
{ "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). 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).
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:
{ "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:
{ "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:
{ "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:
{ "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:
"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"
}
callis aqueryof a method's NSID, made as the account.atis a dotted path to the list in its answer (in a query'sresponse). A segment@nameis the element of a list whose$typeisnameor ends#name, as the app'sschemereads one.pathis 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'scall. 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.afteris 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 says nothing. Grain's:
"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:
"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), 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:
"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 asks
for in place of the permissions its views' collections and methods would each take. Grain's:
"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:
"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.
destinationsistabs, 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.actionis the app's primary action, drawn only to someone signed in. It has alabel(1 to 40 characters), aniconand acall. Aquerycall withcomposeopens 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.accountis the account's area. Itspicturereads the account's picture from a query's answer (call, at the dotted pathat), and the tab named bytabshows it in place of its icon. The server reads it for each page, so the picture is there from the first paint. Itsnameandhandle, dotted paths in the same answer, name the account in its row among the accounts (a view's Accounts), the call made as each account in turn. Itsitems(8 at most) are screens of the app's, each alabel,iconandcallshown signed in. An item can be one the host draws instead. That'ssignOut, shown signed in, orsignIn, shown signed out with itsaboutline over it.links(12 at most) are alabeland anhrefeach, drawn at the navigation's foot.asideis a screen drawn right of the column (call),widthpixels wide (200 to 480, 320 by default).sizesare the widths of the column a view's measure asks for, in CSS pixels.contentis 600 by default (320 to 1600) andwide935 (up to 2400). Afullview takes the column to the window's edge.bandsare the window widths where the navigation changes.railis 600 by default andsidebar1200 (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). 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:
"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.
pathis 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.markdownis its text's file, relative to the app file's directory: GitHub's Markdown (GFM), read as aRichTextofgfmreads 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:
"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.
titleis the screen's heading,texta line under it,placeholderwhat the handle's field holds while it's empty, andlegala line under the form. Intextandlegal, 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: itstextand a button, itslabel. HUD makes it at its sign-up PDS (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'ssuggest's, withurlfor the host:GET <url>/xrpc/<method>?<param>=<typed>with itsparams, the accounts atitemsin the answer, and each one'sdid,handle,name,avatarandavatarFallbackat those paths in it. A picture is drawn fromavatar, falling back toavatarFallbackwhere 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). 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 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 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 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 |