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

chadtmiller.com/hud

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

0
0
1809 lines · 116.2 KB Raw History

title: Views section: HUD order: 3 summary: "How HUD draws a collection or a query's answer: joins, summaries, layouts, query joins and the bundled views."

A lexicon describes one record, but a gallery is three. There's a social.grain.gallery, the social.grain.gallery.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:

  • ref joins the record an at-uri or strongRef names.
  • each joins the records an array's elements name.
  • backlinks joins the records of the same repository that point back at the record, ordered.
  • counts says how many records across the network point at the record, by collection and path (a post's likes, reposts and replies, a gallery's favorites). It reads them from a backlink index.
  • Query joins 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.

FieldOnce read
titleText, on one line, 120 characters at most
descriptionText, on one line, 300 characters at most
imageA blob or an https URL on the view's origins, sent as an absolute https URL
imageAltText, on one line, 420 characters at most
typeA literal website, article or profile (Open Graph's og:type)
canonicalA 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
noindextrue, or a list with something in it (an account's or a record's labels)
jsonLdschema.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

PartIn a narrow boxIn a wide box
List grid, Coversas many across as fit at minat most columns across, sharing the line
Splitits two children one under the other, in their orderside by side, the aside at its narrowest
Profile, Headerthe picture over the wordsthe picture beside them
Split from 32rema large picture 80 pixelsa large picture in its aside up to 150
Panes from 36remone pane: no rowone 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 treeHolds
clampabout the most lines shown before more, as the layout gives it
shownRunsa Text's or RichText's runs cut to fit clamp, an ellipsis after them
shownBlocksa markdown RichText's blocks cut to fit clamp

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

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

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

Document

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

Embed

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

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

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

FeedContext

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

Tree and Chain

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

Action

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

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

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

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

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

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

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

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

Picking covers

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

Compose

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

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

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

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

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

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

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

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

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

What an item opens

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

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

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

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

Query views

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

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

Newer items

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

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

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.

ViewWhat it draws
views/bsky-feed.json, views/bsky-author-feed.json, views/bsky-timeline.jsonThe AppView's feeds, each reply with what it replies to
views/bsky-feed-generators.jsonFeeds themselves (their names, makers and likes)
views/bsky-thread.jsonA post's thread. Its parents, the post, and its replies as a tree
views/bsky-profile.jsonAn account's profile, with its latest posts and feeds
views/bsky-notifications.jsonYour Bluesky notifications: who did what, the post it's about
views/plyr-list.jsonplyr.fm albums and playlists
views/plyr-likes.jsonplyr.fm likes, as a playlist
views/plyr-tracks.jsonplyr.fm tracks an artist uploaded, to play
views/plyr-top-tracks.json, views/plyr-latest-tracks.jsonplyr.fm's most liked tracks over a period, and its newest, to play
views/standard-document.jsonBlog posts (standard.site documents)
views/standard-publication.jsonA blog with its posts joined by backlinks
views/knotless-*.jsonknotless'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 list and record.
  • Each call is a procedure that takes JSON, and its input has the fields its lexicon takes and requires.
  • Each query join's params are its method's, and it has a service.
  • A method view's profile section's params are its method's.
  • No two views draw the same collection, method or domain. A collection is in one view's records at most, and then no collection view draws it.
  • Each tab's call, a tab's guest and each route's call draw what a view draws. That's query of a method view's method, describe_app of an app page's domain, get_record of a collection a view draws or opens as its query, or list_records of one a collection view draws. A route's tab is a tab's label. A route's pager is true or absent, and only a pager's route has an under: a path starting with / that a route has, each of its tokens one of its own path's.
  • A tab's first is what its lexicon (schemas/place.hud.tabFirst.json) describes, with no key it doesn't name. Its call is a query of a method's NSID, and its at and path are dotted paths.
  • An app's push registers and unregisters with procedures that take JSON, each with the fields its lexicon takes and requires and {"$token": true} in its input. Each of what a notification opens names a route's path, and its when binds every token of that path.
  • An app's refresh names a procedure's method (an NSID) and the service it's of, and nothing else.
  • An app's permissions is a list of 1 to 8 permission sets, each an include (the set's NSID) and, where its methods are called at a service, that service, and nothing else.
  • An app's head names its siteName, and its texts are 1 to 300 characters, its image an https URL and its twitter an account as @name.
  • An app's frame is what its lexicon (schemas/place.hud.frame.json) describes, with no key it doesn't name at any level. Its destinations is tabs. Its action's, items' and aside's calls draw what a view draws, and its picture's call is a query of a method's NSID. The picture's tab is a tab's label and its at a dotted path. Each icon is one of catalog::FRAME_ICONS.
  • Each of the frame's account items has a call with a label and an icon, or a host (signOut or signIn, at most one of each), never both. Only a signIn item has an about. Each link's href is a path starting with / (but not //) or an https URL. sizes.wide is at least sizes.content, and bands.sidebar is wider than bands.rail.
  • An app's pages are 64 at most, each what its lexicon (schemas/place.hud.page.json) describes, with no key it doesn't name. Each path is a plain path (/ and segments of a to z, 0 to 9, -, _ and ., with no query or token) that no other page, no tab's path and no route's path (its tokens any segment) has. Each markdown is a .md file's path, relative to the app file's directory and never climbing out of it, and the file is there.
  • An app's signIn is what its lexicon (schemas/place.hud.signIn.json) describes, with no key it doesn't name at any level. Each link in its text and legal goes to a path starting with / (but not //) or an https URL. Its typeahead's url is an https origin, with no path, query or fragment. Its params is an object of strings, numbers and booleans, and its paths are dotted, no segment empty.

HUD checks the methods against the lexicons in the directory's lexicons/ and those it bundles (lexicons/ of HUD's repository), an app's own first (An app's lexicons). 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.

CallerSaysDrawn 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 callToolits input's kit, the sameits version
An MCP host drawing HUD's view (MCP Apps' io.modelcontextprotocol/ui capability, or any initialize-era host)nothing morethis HUD's version
The workspace's page and the playgroundnothing morethis HUD's version
Any other callnothingthe 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"
}
  • call is a query of a method's NSID, made as the account.
  • at is a dotted path to the list in its answer (in a query's response). A segment @name is the element of a list whose $type is name or ends #name, as the app's scheme reads one.
  • path is a dotted path, in each item, to a path of the app's own site (/feeds/following, /camera/Fuji X100V). The item's screen is that path's by the app's routes, and at the tab's own path it's the tab's call. An item whose path has no route is passed over, so Grain's Groups, a feed the next grain.social doesn't draw, is never its Home.
  • after is a procedure after which the root is chosen again.

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

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

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

App heads

An app file's head is what a page of the app says in its HTML head where its view's head 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.

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

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

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

A screen whose tree has a next pages as you scroll, as HUDKit's and the Android kit's lists do. Its foot is a Load more button, and once the page has hydrated, the shell loads the next page itself as that foot comes within a screen of the screen's own scroll (an IntersectionObserver, auto on the renderer's LoadMore). Each page appends to the tree's page list (a List, Covers, Gallery or Player) below what's in view, so the scroll doesn't move, and the list lets go of items far from view as it grows (Memory). 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.

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

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

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

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

The app's sign-in screen

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

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

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

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

With a signIn, HUD sends that app's web clients straight on to the account's server, the handle typed their login_hint, with no page of HUD's between (the OAuth flow). 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.

ViewWhat it draws
grain-feedThe 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-archiveAn account's stories of the last day, each marked watched as it shows, and every story it posted
grain-mutes, grain-blocksThe accounts you muted and blocked on Grain, each undone in place
grain-settingsYour 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-viewOne gallery as that card with all its photos, then its comments and more of the photographer's galleries
grain-exploreGrain'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-camerasGrain's Cameras (getCameras): its top cameras as cards, each with its photos' count, opening its galleries
grain-search, grain-search-peopleGrain's galleries and accounts matching a search, under the field to search again
grain-followers, grain-following, grain-known-followersWho follows an account on Grain, whom it follows, and those of its followers you follow
grain-notificationsYour 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.

ViewTitleShows
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.

RecordsDrawn as
Bluesky's postsThreads, by uri, activity "Posted"
Bluesky's repostsThreads, 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 checksgetRepo (repositories have activity "Created")
knotless's issues, pulls and commentsgetThread (issues and pulls have activity "Opened")
knotless's profilesgetProfile, by the record's did
knotless's starsgetActorStars, 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.

AppEntries
BlueskyPosts 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)
knotlessRepositories, Activity, Everyone's activity and Notifications