--- title: Views section: HUD order: 3 summary: "How HUD draws a collection or a query's answer: joins, summaries, layouts, query joins and the bundled views." --- A lexicon describes one record, but a gallery is three. There's a `social.grain.gallery`, the `social.grain.gallery.item`s that point at it and at a photo each, and the `social.grain.photo`s. Nothing in a lexicon says which collection an at-uri points into, so HUD writes down how a collection is drawn as data. That's a view (`place.hud.view`, with its lexicon in `schemas/`). A view names the collection it draws. For a page of records (`list`) and for one record (`record`) it gives the [joins](#joins), a [summary](#summaries), a [head](#page-heads) and a [layout](#layouts-and-components). ## Joins The server runs a view's joins first. Each join leaves its result on every record at `joins.`. There are a few kinds: - `ref` joins the record an at-uri or strongRef names. - `each` joins the records an array's elements name. - `backlinks` joins the records of the same repository that point back at the record, ordered. - `counts` says how many records across the network point at the record, by collection and path (a post's likes, reposts and replies, a gallery's favorites). It reads them from a backlink index. - [Query joins](#query-joins) call a related query. A `ref`, `each` or `backlinks` join can have joins of its own, three deep at most. ## Summaries The summary is the tool's text. It names a noun, each record's label and a detail count, as "3 galleries by alice: Coast (12 photos), …". ## Page heads A web page that draws a tree needs a title, a description and a picture for search engines and link previews. A mode's `head` says them, read against the mode's scope as the tree is: ```json "head": { "title": { "$join": [{ "$": "response.gallery.title" }, " by ", { "$": ["response.gallery.creator.displayName", "response.gallery.creator.handle"] }, " on Grain"] }, "description": { "$first": [{ "$": "response.gallery.description" }, { "$join": ["A photo gallery by @", { "$": "response.gallery.creator.handle" }, " on Grain."] }] }, "image": { "$": "response.gallery.items.0.fullsize" }, "type": "article", "canonical": { "$join": ["/profile/", { "$": "response.gallery.creator.handle" }, "/gallery/", { "$rkey": "response.gallery.uri" }] }, "noindex": { "$": "response.gallery.labels" }, "jsonLd": { "@context": "https://schema.org", "@type": "SocialMediaPosting", "image": { "$each": [{ "$": "response.gallery.items" }, { "contentUrl": { "$": "fullsize" } }] } } } ``` Each field is a template, as an [Action's record](#action) is. So a field can be a literal, a binding, `$join`, `$first`, `$rkey` or `$root`. A field that reads nothing is left out, never an error. That's how a gallery with no description gets one written for it, and one with no labels stays indexable. | Field | Once read | | --- | --- | | `title` | Text, on one line, 120 characters at most | | `description` | Text, on one line, 300 characters at most | | `image` | A blob or an https URL on the view's origins, sent as an absolute https URL | | `imageAlt` | Text, on one line, 420 characters at most | | `type` | A literal `website`, `article` or `profile` (Open Graph's `og:type`) | | `canonical` | A path on the app's own site, starting with `/`, percent-encoded, 512 characters at most. One that would leave the site (`//host`) is left out | | `noindex` | `true`, or a list with something in it (an account's or a record's labels) | | `jsonLd` | schema.org structured data, an object of templates, 32 KiB at most as JSON | In `jsonLd`, `{"$each": [array, template]}` reads the template against each of the array's elements, 50 at most, with `$root` reaching the mode's scope. An object whose templates all read nothing is left out with them, so a gallery with no place has no `Place` with no name. The tree carries it as `_meta.ui.head`, a trusted view's alone. A view given inline can say a head, and HUD checks it, but its head never reaches the tree. The page writes the head's text into HTML, so it escapes it, and `<` in `jsonLd` too. What a page says where its view's head says nothing is its app's ([the operator's views](#the-operators-views)). ### The hero picture A page's largest paint is usually its first big picture, so a page should load that one first and the rest as they near the screen. Every tree a view draws names it as `_meta.ui.hero`, the `src` of the first picture it draws large, in drawing order. That's an `Image` not drawn small (`avatar`, `face`, `icon` and `thumb` are small), the first picture of a `Gallery`, `Slides` or `Covers`, or a `Profile`'s banner, else its avatar. A `List` that scrolls sideways (`strip` or `shelf`) draws its items small, so nothing in it is the hero. So a Grain feed's hero is its first card's first photo (past the stories over it and the photographer's face), and a gallery's is its first photo. The web renderer draws the hero with `loading="eager"` and `fetchpriority="high"`. The pictures first on the screen by their place load at once too: an `Image` and a `Gallery`'s first picture, at the tree's top, in a list's first item, in the pane shown. Beside a hero they load with `fetchpriority="low"`, so a gallery's author's face doesn't slow its first photo. In a tree with no hero they have no priority of their own. A feed's first card is drawn so, its face and first photo, and its carousel's next photo isn't. A `Covers` waits, but for its hero, since one under a gallery is far down its page. Every other picture loads lazily. A page drawn on a server should also preload the hero from its head (``), so the browser fetches it before it reaches the ``. Where the hero is a gallery photo with its sizes, the tree says them too (`_meta.ui.heroSrcset`). Then the preload gives them as `imagesrcset`, with `imagesizes` the `area` the page gives `Tree`, so the browser takes the same size for both. The renderer's `heroPreload(ui, area)` gives the link's attributes so. A tree with no picture drawn large has no hero. ## Layouts and components A layout is a tree of components from a fixed catalog (Stack, Split, Header, Text, Image, List, Covers, Tree, Chain, Gallery, Player, Map, Document, Embed, FeedContext, Stat, Fields, Action and the rest). Each prop is a literal or a binding, `{"$": "value.title"}`, which is a path into the data. The path `"."` is the data itself (as a tag in a list of tags). A key `@name` takes the element of an array whose `$type` ends in `#name`, as an array of a union holds one of each kind: `response.preferences.@photoMetadataPref.includeExif`. ### Image and Gallery `Image` draws one picture and `Gallery` several. A picture with a `size` (an avatar, a face, a profile's own, an app's icon) draws a placeholder where its account has none. One without a size is left out where it has no source. Two flags draw a photo as a photo app does. `bleed: true` takes it past the padding of what holds it, to the edges of the tile, screen or list row, with square corners. `showAlt: true` marks it ALT where it has alt text, and a tap shows that text over it: white, centered both ways on a 60% black scrim, scrolling when longer than the photo. A tap on it hides it. Grain's feed and gallery draw their photos so, and their authors' names as `Link`s with `style: "name"`, in the text's own colour, bold. What bleeds (a picture or `Map` with `bleed`, and `Covers` as `tiles`, which always reach the sides) and is first on its screen meets the bar above too, its screen keeping no padding over it: Grain's place opens on its map, and its camera's and hashtag's feeds on their tiles, flush under the bar. An `Image` with an `href`, as a Link's, opens that when tapped rather than what holds it, its alt read aloud. Grain's authors' pictures open their profiles so (`"href": {"$": "creator.did"}`), and the rest of the card but its photos still opens the gallery. A carousel's tap opens nothing (with `zoom`, a gallery's own screen, it opens the lightbox), since a tap on a feed's photo opens nothing in Grain's apps either. A Link with `style: "muted"` is drawn as muted text on one line, cut with an ellipsis: a gallery's location, which opens that place's feed. Where a param of its `open` reads nothing (a gallery with no place to open), it is its words alone. A `Gallery` with `like`, the label of an Action in the same List item as it (or, in none, the view's own), runs that Action on a double-tap on a photo where it isn't done yet, and never undoes it, a heart bursting where the tap was, as a `Slides`' `like` does. A tap that opens the lightbox then waits a moment to be sure it isn't one, and a tap that opens nothing still opens nothing. Grain's feed cards and gallery pages name their ♡ so (`"like": "Favorite"`), as Grain's apps favorite a gallery on a double-tap, and a comment's own ♡ under a gallery, in its own List item, is never run by it. A `Gallery`'s `info` is each photo's own lines of words, read from its item: each line's `parts` (each a binding, with a `prefix` or `suffix`) joined by its `join`, a part reading nothing left out and a line of none dropped. A part with `omitRepeated` is left out where the next part read starts with its first word, so a camera's make goes where its model names it. In rows or a stack, a photo with any has an ⓘ in its bottom-left corner, mirroring ALT, that shows them over it. Opening one closes the other. A carousel draws the lines of the photo showing under it instead, small and muted, and swaps them as it's swiped. It keeps room for as many lines as the most any photo has, so its height holds between photos with info, and a photo with none draws nothing there. Grain's feed and gallery show each photo's camera so: its model (after its make where the model doesn't name it), its lens, and its focal length, aperture, exposure and ISO. A stack or a carousel draws each photo the full width, so a phone needn't load a photo as wide as a desktop does. Its `srcset` names the sizes each photo comes in, each a binding into the photo and how many pixels wide that URL is. Grain's gallery names its thumbnail (`thumb`, 1,000 pixels wide, ~100 KB for a photo measured) and its full size (`fullsize`, 2,000 pixels wide, ~900 KB): ```json "srcset": [{ "src": { "$": "thumb" }, "width": 1000 }, { "src": { "$": "fullsize" }, "width": 2000 }] ``` Each photo's item says them as an ``'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 ``'s sizes (the screen's width where it gives none). A picture the full width of the tree takes the area as it is, and one in a grid's tile the area shared among the grid's columns ([Laying out by width](#laying-out-by-width)). A lazy picture's sizes start with `auto`, so a browser that knows it takes the width the picture is laid out at. Grain gives each screen's column, so a wide profile gives `(min-width: 601px) min(935px, 100vw - 245px), 100vw`. A 390-pixel phone at 2x then takes the thumbnail and one at 3x the full size, as does a desktop at 2x. A carousel draws the photo it shows and the next alone, and each further one once the one before it is shown, so a gallery of 20 loads 2 photos before it's swiped. Near the screen, it fetches that next photo ahead too, at the width it's drawn at, since a browser may leave a lazy one off the screen in the carousel's strip until it's swiped. ### Laying out by width | Part | In a narrow box | In a wide box | | --- | --- | --- | | `List` grid, `Covers` | as many across as fit at `min` | at most `columns` across, sharing the line | | `Split` | its two children one under the other, in their order | side by side, the aside at its narrowest | | `Profile`, `Header` | the picture over the words | the picture beside them | | `Split` from 32rem | a large picture 80 pixels | a large picture in its aside up to 150 | | `Panes` from 36rem | one pane: no row | one pane's row too, each icon with its word | A part lays out by the box it's given, never by the screen. So one tree draws right in an MCP App's frame, a workspace tile, Grain's column and a phone. The web draws each branch in CSS (grid tracks and wrapping flex lines), so a page drawn on a server is what the browser shows once hydrated. HUDKit and Android measure the width they're offered. `min` and a `Split`'s `main` and `aside` are sizes the host sets, `sm`, `md` or `lg` (the web's 6rem, 10rem and 15rem, the native kits' 96, 160 and 240 points). A grid's `columns` (1 to 6) is the most it draws across, however wide its box is. Grain's profile draws its galleries `{ "style": "tiles", "min": "sm", "columns": 3 }`, so three across from a 320-pixel phone to a 1200-pixel screen. A `Split` with `"side": "start"` takes its first child as the aside (a profile's picture beside its name, counts and bio). Its children are never hidden or moved, so a narrow box draws the aside first there too. A grid without `min` keeps its own narrowest tile (14rem, a cover card 9.5rem, a tile 7.5rem and three a line at least). ### How wide a view is drawn A view's top-level `measure` says how wide it would be drawn where its host can give it the room. `content` (the default) is the host's reading width, `wide` a wider one (a profile's grid of pictures) and `full` all the room the host has for a view. The tree says `wide` and `full` as `_meta.ui.measure`. A view drawn inside another (an embed) takes the room it's given. One view may draw some answers wider than others. Its `measureWhen` lists 1 to 8 cases, each a `when` (a path in the answer's scope, as a `Stack`'s) and a `measure`. The first case whose path holds something decides, else `measure` does. HUD decides it as it answers, so the page is drawn at that width from its first paint. Grain's feed view is `wide` for a camera's, a place's or a hashtag's galleries (`params.camera`, `params.location`, `params.tag`) and the reading width for its home feeds. A screen drawn in a tab's root's place, as a `Tabs` strip draws its choice there, keeps the root's measure rather than its own, so choosing a tab never changes the screen's width. Grain's pinned camera, chosen in Home's strip, is drawn at Home's reading width, while the same feed opened from Explore is wide. The shell keeps it as the strip swaps the call. Where a URL is drawn in a root's place (`swappedTab`), the server answers that tab's own root call too, for its measure, so the page it draws is the one the browser hydrates. A root the account's data chooses ([A tab's root from the account's data](#a-tabs-root-from-the-accounts-data)) is drawn at its own measure, and the strip's choices keep it: where a camera is the first feed someone pinned, their Home is wide, Recent chosen in its strip too. A part inside a wide view may keep the reading width: a `Stack` with `"measure": "content"` is drawn no wider than the host's reading width (the web's `--hud-reading-width`, 37.5rem unless the host sets it, or the native kits' 600 points), centred in a wider box, and as wide as its box where that's narrower. Grain's profile holds its header so (its picture, name, counts and Follow, a compact block) over a grid the screen's whole width. The host decides how wide each is. Grain's web app draws `content` 600 pixels wide and `wide` all its 935 right of its sidebar (less where the screen is narrower), centred where `content` is, so its sidebar never moves. The MCP App never asks its host for room by itself. Where the host offers full screen, it shows an Expand button over a `wide` or `full` view, and asks only when it's clicked. The workspace draws every view in its tile alike. ### Stories `Slides` shows pictures one at a time, as a photo app shows an account's stories. Bars over the picture fill over `seconds` each, from when its picture has loaded (or failed and shows its placeholder), so a slow picture keeps its time. The next two pictures are fetched ahead, so a tap shows them at once. A tap on the right goes on and on the left back, and holding pauses. Each item's `call`, in a bundled view alone, is a procedure called once that picture first shows. Grain's stories mark themselves watched so (`social.grain.story.markViewed`). Its children are drawn over each picture, at the end of its top row, with that picture's item as their scope: Grain's are a ⋯ with Delete story on one's own and Report on others', and the picture waits while it's open. With no pictures, `Slides` still draws its screen, its `empty` words in the middle and its children under them, drawn with the view's scope. Grain's says "No stories right now", and on one's own Add to your story under it posts a new story (`social.grain.story`), as Grain's + does. An `open` query's `compose` opens its screen at a form: `true` for its first `Compose`, or one's `label` (as `"New gallery"`). HUD marks that one `open` in the tree, and the renderers open its form by themselves once the tree is first drawn in a browser or an app and is the one in front (`active`), once in that tree. A story pager's page read ahead beside the one shown waits. The server draws it shut, as the browser hydrates it, and a tree drawn again (a story deleted) stays as left. Only a `Compose` drawn as the screen itself opens, never one over an item (a List's, a picture's) nor a Menu's row. So a story screen with pictures opens nothing, and one with none opens its Add. A photo form (`form: "photo"`) whose photos field has `camera` then goes straight to the camera where there is one. The web can open a phone's camera only while the tap that opened the screen still counts as the person's, and otherwise its form waits on Camera. An `open` query's `unless`, a path in the scope, drops its `compose` where it holds something. Grain's Your story opens one's stories so (`"compose": true, "unless": "stories"`, its row's `stories` one's own): with none, the new story's camera, and with some, the stories, as any other page. `compose` is a one-time request, not part of where the app is. A client opens the form once, as the call opens its screen. The screen it keeps is the call without `compose`: in its history, its URLs, its memory of screens drawn and its saved navigation. So going back or forward to that screen, loading the page again or choosing its tab again never opens the form again. The web shell keeps a screen's last tree with its `open` mark taken off (the renderer's `unopened`). HUDKit opens a form once per screen in that screen's memory, and keeps no navigation across launches. The Android kit does the same (`composeOpensAtOnce`), and an app's story pager draws a page that opens at its form as that form alone (`Drawn.openedForm`, `OpenedForm`), as HUDKit's. In a pager of a List's `pages` (Grain's stories strip), an item whose call opens at a form (Your story's `compose`, with none) is a page only of the pager it opens itself: tapping someone else's story leaves one's own out. With stories of one's own its call has no `compose` (`unless`), so it is a page as any other, the first, and swiping back from the first other person's reaches it, as a photo app does. Only the page tapped opens its form, and only until it's left. Where it does (Your story with none), the web shell draws no stories, just that form over the screen under them, as the frame's action does, and the form closing, sent or not, closes them, as a photo app's Your story goes to the camera and back. The web shell draws every other page with its mark taken off (`unopened`), so the history it keeps for a pager holds its calls without `compose` too. HUDKit's `ViewContext` has `opensForms` for an app's own pager to say the same, and `Drawn.opensAtForm` with `OpenedForm` for it to draw the page tapped as its form alone, as the web shell does. A `Slides` page with no pictures stays when it's swiped to, its words and Add shown, rather than run on to the next page. An `open` query's `at` asks the view to show that first, and `Slides` with `start` (a path in each item) begins at the item holding it there. A story picked from a profile's Stories opens the archive at that story so (`"at": { "$": "uri" }`, `"start": "uri"`). `Slides` with `reverse` draws its items last first, so an archive answered newest first plays oldest first, as stories do. With `href` (a path in each item, as an Image's), each picture is the screen of that record, and the app's address follows the picture shown. Grain's story route (`/profile/{actor}/story/{rkey}`) says `"pager": true`, so its screen opens in the story pager wherever it's opened from: the Home strip, a profile's avatar, the archive or a link. The web shell keeps the URL at the story shown, replaced in place as it moves within and between people, so Back leaves the pager, and closing it goes back to where it was opened. The route's `under` (`/profile/{actor}`) is the screen under a story whose URL is loaded directly. The server draws the pager over that profile, its head the story's, and the browser's history becomes the tab's root, the profile and the story, so closing it or Back lands on the profile. On a desktop the pager is drawn as Instagram draws stories: a dark window, the wordmark top-left and ✕ top-right, the story in a 9:16 column in the middle, and the people beside it small and dimmed, a click going to them. Phones stay full screen. An `open` query with `sheet: true` opens its screen as a sheet over what's open: on the web, as wide as the column, or over a pager (a story, full screen) a phone's column in the middle of the window, over the picture. A Link, an Action or a Compose with an icon over a `Slides` picture is drawn as a Bar's, its icon alone, and an Action done in its colour, as a Bar's is. Each Grain story has 💬 there, opening its comments (`social.grain.comment.getThread`, the `grain-comments` view) in a sheet over the story, and ♡, favoriting the story (a `social.grain.favorite` of its at-uri, its `viewer.fav` the one already made), red once it is. A `Slides` with `like`, the label of an Action among a picture's own, runs that Action on a double-tap on the picture where it isn't done yet, and never undoes it, a heart bursting where the tap was. A tap then waits a moment to be sure it isn't one. Grain's stories name their ♡ so (`"like": "Favorite"`), as Grain's apps favorite a story on a double-tap. A List with `"open": false` opens nothing when an item is clicked, its children's own links and buttons still theirs: a comment there, or under a gallery, opens nothing itself, its author, reply and ⋯ what they open. A `List` with `style: "strip"` is one row that scrolls sideways, and an `Image` with `ring` (a path, as a Stack's `when`) is ringed in the accent where its scope holds something there. One with `plus` (a path too) has a small + in the accent at its corner. Grain's feeds draw who has stories over them so, each ringed while it has some unwatched, your own first, as Your story, with its +. A `List` with `pages: true` opens an item as one page of a pager of them all, full screen over the app. A sideways swipe slides the page off as the one beside it comes in, and a drag down closes it. A page's `Slides` running past its last picture goes on to the next page, and closes the pager after the last, and tapping back on its first goes to the page before. Pages either side are read ahead, their first pictures fetched, and wait to run and mark anything watched until they're shown. On a desktop, the arrows beside it, ← and → and Escape do the same. Grain's stories strip is such a list. ### Menu `Menu` is a ⋯ button whose children are a menu's rows: Actions, Links and Composes, each its label. An Action may ask first (`confirm: "Block this account?"`), in a bundled view too, and take `tone: "danger"`, drawn in the danger colour. A Compose may call a procedure in place of `writes` (`call`, a bundled view's alone): the form's values are set on its input by their names, over the template's own defaults. Grain's profile has Mute or Unmute, Block and Report there, and its gallery Report, each report a form calling `com.atproto.moderation.createReport` on Grain's AppView. A Stack among a menu's rows gives its rows where its `mine`, `others`, `when` or `unless` holds, so a menu can offer Delete on one's own gallery and Report on someone else's. An Action with `leave: true` closes the screen it's on once it succeeds, and the screen below is read again. One with `reload: true` reads its own screen again. A template's `{"$rkey": path}` is the record key of the at-uri at that path. An Action's question is asked as an alert over everything, and answered, the menu it came from closes. Grain's gallery has Edit gallery and Delete gallery there, the second asked first, deleting what `social.grain.gallery.getDeletionPlan` plans (see Action), its photos, comments and favorites with it. Each comment has a ⋯ too: Delete comment on one's own (reloading the gallery), Report on others'. A Link with `share`, an https address its `href` value ends, shares that address rather than opening anything: the system's share sheet, else the clipboard. Grain's profile has Share profile atop its menu, its page on grain.social (`"share": "https://grain.social/profile/"`, `href` its handle), on one's own profile too. A Link with `copy` copies text rather than opening anything: `copy` and then its `href` value, put on the clipboard. The web says Copied a moment, and an iOS menu's row taps success. Grain's profile has Copy handle under Share profile (`"copy": "@"`, `href` its handle), so it copies `@handle` as Grain's iOS app does. A Link's `fragment`, a path to a DID, opens its `href` (an https address with no fragment of its own) with that DID as its fragment, then `+` and the signed-in person's DID. That's how Germ asks an app to complete its `messageMeUrl`. A Stack's `where`, as a List's, draws it only where its scope holds at each path what the path paired with it holds, or the literal of an `{"$is": …}`. Grain's AppView reads an account's `com.germnetwork.declaration` record into its profile's `messageMe`, so Grain's profile has Message on Germ under Follow. It's there, signed in, where `showButtonTo` is `everyone`, and where it's `usersIFollow`, only for those the account follows. ### Search `Search` is a field whose words fill one param (`param`, as `q`) of the query its `open` names. Searching opens that query with them. Where that query is the one drawn now, searching again draws its answer in place, as a tab does. `value` binds the words searched already, which the field shows. Grain's Explore has one, and each of its results views has one over Tabs of Galleries and People. ### Tabs and Bar `Tabs` draws a few queries over the one drawn now, and choosing one draws it in place. Its tabs are `items`, or one for each element of an array in the data (`from`), labelled by a path in it (`label`) and opening `open` with params read from it, those `where` keeps. A `where` pairs a path in the element with a path in the scope or with a literal (`{"$is": "feed"}`), either in `{"$not": …}` to keep the elements holding anything else. In place of `open`, `opens` (1 to 4 `{ where?, open }`) opens each element by the first whose `where` it matches, and one with no `where` matches any. An open's param `{"$after": [value, "camera:"]}` is what the value holds after that prefix, and an element whose value doesn't start so opens nothing there. `items` stand in when the data holds no array. Tabs draw only when one of them is the query drawn now, and there are two or more. `style: "strip"` draws them as a feed app's feeds, a line of words that scrolls sideways, the one drawn now underlined. A strip's tabs swap the screen in place, which is a tab's root alone, so it draws only at the root of the host's navigation stack: the renderers take `root` (`Tree`'s prop, HUDKit's `stackRoot` environment value, Android's `LocalStackRoot`), true unless the host says otherwise, and a host with a stack gives false to each screen pushed over its root. A place's feed opened from Explore and pinned is one of the person's feeds, but pushed, it draws no strip. The server draws with the same `root` the browser hydrates with. Signed in, Grain's feeds are a strip of the feeds the person pinned (`social.grain.actor.getPreferences`), or Recent, Following and For You where they pinned none. A pinned feed opens itself, and a pinned camera, place or hashtag (`camera:Fuji X100V`) its feed of galleries, so the strip is over those feeds too. Signed out, Recent is the one feed there is, and no strip is drawn. Choosing a tab marks it at once. An app's clients (Grain's `next/` shell and iOS app) also keep the screen. They keep drawing the tree they have until the tab's call answers, and once it has run 150 ms (`SKELETON_DELAY`), they tell the tree it's `pending`. Its page list (the `List`, `Covers` or `Gallery` of the query's items, which HUD marks `page`) then draws as a skeleton of what it holds, and the rest stays as it is. So Grain's feeds strip and stories strip don't move while its feed changes. The new tree is drawn over the old one, and its nodes that are the same stay mounted with their pictures loaded. A `Search` answering in place does the same. HUD's own clients (the workspace, its iOS app and the MCP App's view) draw the tab's call afresh. `Bar` is the screen's top bar: its title and buttons beside it. Its `title` is the screen's, its words one after another, each a string or a binding (`["Followers"]`, `["#", { "$": "params.tag" }]`), and it has none where one of them resolves to nothing. The app draws it in its bar, as it draws its screens' titles. Its children are Links, Actions, Composes and Menus, each drawn as its icon alone with its label read aloud. A Link takes an `icon` for it (`settings`, `plus` and a few more). A Bar is gated as a Stack is (`when`, `mine` and the rest), and an app with no bar draws it where it stands, its title a heading at the start of its row and its buttons at the end. A web app with a bar of its own draws the tree twice from the same props: `Tree` with `bar: "apart"` where the screen is, which leaves the Bar out, and `bar: "only"` in its bar, which draws the Bar's buttons alone (`barOf` finds it, first through the Stacks at the top). A page the server draws then has the buttons where they stay, and hydrating it moves nothing. Each of Grain's pushed screens names itself there (Followers, a gallery's title, a camera, `#film`). Its feeds have a + there that opens New gallery (on a phone alone: beside the rail or sidebar, its Create is it, as [The frame](#the-frame) says) and a gear that opens My feeds, and one's own profile a gear that opens Settings. ### While a screen loads A skeleton is a resolved tree's shape with its words and pictures left out. Its Stacks, Rows and Lists stay (each list's first few items), and each leaf is drawn as a grey shape the size of what will be there. That's bars of a text's length on its lines, a circle or block for a picture, a gallery's frame and a grid for covers. The renderer makes it from the tree itself (`skeletonOf` in `web/renderer`, `Skeleton.of` in HUDKit), so every view has one with nothing written for it. A `Bar` with buttons stays as their count and draws nothing. So an app knows from the start whether the screen's bar will hold buttons, and Grain's desktop frame keeps that bar's room while it loads. An app's clients keep each screen's last skeleton (`rememberSkeleton`), named by the tool, the method (or app domain) and the names of the call's params, so one gallery's screen stands for another's. While a screen loads, they draw its skeleton (`recallSkeleton`) from 150 ms on, so a load quicker than that draws nothing in between. A screen never drawn before gets a generic one, rows of a face beside two lines. The skeletons hold no content. The web keeps them in `localStorage` (`hud-skeletons`) and iOS in `UserDefaults`, so they're there on the next launch too ([memory](memory.md#renderer)). HUD's own clients draw a spinner. An iOS app on HUDKit can keep each screen's last tree whole as well (`LastTree`). Grain's does, so a screen opened again draws that tree at once while its call is made afresh, then draws the answer in its place. Since a tree holds what people posted, it's kept in memory alone, named by the viewer's DID and the whole call, and drawn for 10 minutes at most. The app lets an account's trees go once it writes (`create_record`, `delete_record`, `apply_writes` or `call_procedure`), and all of them as anyone signs in or out ([memory](memory.md#renderer)). HUD's web renderer keeps no trees. ### Panes `Panes` shows one of its `Pane` children at a time, chosen by a row of icons over them (`grid`, `heart`, `clock` and a few more), the chosen one underlined, one width each in the row's middle. A pane's Covers with `select` shows Select at the right end of the row. A Pane is gated as a Stack is, and one with nothing to show isn't drawn. With one pane there's no row, and nothing to swipe. With more, the panes lie side by side and page: a finger swipes from one to the next, the pane following it, and a click on an icon scrolls to its pane. The underline follows the swipe, from one icon to the next, and the panes are as tall as the one shown, between two as tall as both blended by how far the swipe is, so a short pane leaves no room under it. A mostly vertical drag scrolls the page. While a pane's Covers picks, the panes and the icons hold still. All of this happens in the host, since every pane is in the tree. The web pages with CSS scroll snapping, so a trackpad's two-finger swipe pages too, and the icon row follows the strip's scroll. A click scrolls at once where motion is reduced. As the server draws them, and with no script, the first pane alone shows and nothing scrolls: the others are drawn but folded away, opened once the page is mounted. HUDKit pages with a paging horizontal `ScrollView`, as grain-ios's profile does, and Android with a `HorizontalPager`. Grain's profile ends in Panes: its galleries for anyone, and on one's own its favorites and its stories, each read by a query join with `when: "mine"`, so those calls are made on one's own page alone. A query join's `when` is a path in the main scope, and the join is called only where it holds something. `unless` is the other way, called only where its path holds nothing. ### Faces `Faces` draws a few accounts' faces, small and overlapping, then words: `lead`, the first two names, and how many more in `countNoun`'s words. A click opens `open`. Grain's profile has one on someone else's page, "Followed by alice, bob and 3 others you follow", from a join of `social.grain.graph.getKnownFollowers` with `when: "me"` and `unless: "mine"`, opening the whole list. With `style: "pile"`, `Faces` draws the faces alone at an avatar's size, the first `max` (5 by default) and +N past them, each opening its account (`href`, read from each item). On both platforms the first face is on top, each ringed 2 points out in the page's colour, so its edge cuts cleanly into the next face. With `expand: true` there's a way to list them all, each with its face, name and `handle`. The web draws a chevron after the pile that swaps it for that list in place. iOS draws +N as a button that opens the list in a sheet, as Grain's iOS app does, so a pile of `max` or fewer has none. Grain's notifications draw who did something so, one face or a group's. ### Map ```json { "component": "Map", "props": { "items": [{ "cell": { "$root": "params.location" } }], "cell": { "$": "cell" }, "bleed": true, "pins": false } } ``` `Map` draws a map with a pin per item, in the accent. A pin's place is `cell`, an H3 cell index, or `lat` and `lng` in degrees, and a view gives one or the other. The server turns a cell into its centre's coordinates, so the clients only get numbers. A cell that isn't one is the view's error, and an item with no place has no pin. `label` names a pin, `count` makes it bigger as it grows (a place's galleries), and a pin opens `open` as a List's items do. `height: "short"` (the default, 200 points) is a page's header and stays still. `"tall"` (400 points) can be moved and zoomed. With `zoom` (1, the world, to 18, a street) the map centres on its pins at that zoom. Without it, the map fits its pins but comes no closer than a city (zoom 11). `bleed` works as an Image's. `"pins": false` draws no pins: the map is still placed by them, centred or fitted as it would be, a plain map of where they are. The web draws it with Leaflet over OpenStreetMap's raster tiles, which are plain pictures, so the view still fetches nothing. Leaflet is ~43 KB gzipped, loaded the first time a map draws (the MCP view, a single file, carries it inline). iOS draws it with MapKit's `MKMapView`, which gathers pins that would overlap into one showing how many places it holds (a tap zooms into it), so ~1,000 pins stay quick. Android draws it with MapLibre (maplibre-compose) over the Protomaps vector basemap from `tiles.grain.social`, gathering pins the same way, and a tall map moves only once tapped, so a scrolling screen keeps its drags. Grain's place page (a feed with a `location`) has the map above as its header, one literal item holding the place's cell, with no pin, as Grain's web heads a place. A `Stack` with `"gap": "none"` sets it against the place's galleries under it (a Stack's `gap` is `none`, `xs`, `sm`, `md` or `lg`, `md` where a view gives none). Grain's Locations (`getLocations` with `pins: true`, every place it has, ~1,000 measured, at ~80 bytes each) has a tall one, each pin sized by its galleries and opening them. ### Among a list's items A Stack with `at` among a List's children isn't part of each item. It's drawn once, with the List's own scope, after that many items, and on the first page alone. A List with `style: "shelf"` is one row of cards that scrolls sideways, each one width, its parts centred. Grain's feed has "Suggested for you" after its fifth gallery: a shelf of the accounts `social.grain.actor.getSuggestedFollows` suggests (a query join when signed in), each card a face, a name, two lines of bio and Follow. A List's `shown`, in a bundled view, is a procedure called once as the signed-in person when the list is first shown. Grain's notifications mark themselves seen so (`social.grain.notification.updateSeen`). A List's or a Covers' `where` keeps the items it matches and `limit` draws at most that many of them. HUD filters them as it resolves the tree, so every client draws what's left. Grain's gallery draws "More galleries from @handle" as Covers of the author's newest seven, `"where": { "uri": { "$not": "response.gallery.uri" } }` and `"limit": 6`, so six others show whether the gallery drawn is among the seven or not, as Grain's web does. A List with `style: "chips"` draws each item as a filled pill that opens it, side by side and wrapping, under its title as a small capital label. A `Text` in a chip is small and strong, on one line. Its `more`, `{ "label", "open" }`, is one pill more after the items, in the accent colour on no fill, drawn only where `limit` left items out. Grain's Explore draws its top ten cameras and places so, each ending in "See all →" where there are more: ```json { "component": "List", "props": { "title": "Cameras", "style": "chips", "items": { "$": "joins.cameras.cameras" }, "limit": 10, "open": { … }, "more": { "label": "See all →", "open": { "query": "social.grain.gallery.getCameras" } } }, "children": [{ "component": "Text", "props": { "value": { "$": "camera" } } }] } ``` ### Grouping ```json { "as": "group", "by": ["reason", "galleryUri", "storyUri"], "time": "createdAt", "hours": 48, "only": { "reason": ["gallery-favorite", "story-favorite", "comment-favorite", "follow"] }, "distinct": "author.did" } ``` A List's `group` draws several items as one, as Grain groups the favorites of one gallery. An item joins the first group before it whose first item holds the same at every `by` path and whose `time` is less than `hours` from its own. An item with nothing at `time`, or none of `only`'s values at its path, is a group of its own. Where an item's value at `distinct` is in its group already, it's left out, so someone who favorited twice counts once. Grouping comes after `where`, `needs`, `mine`, `others`, `distinct` and `limit`. Each group draws as its first item, with `as` holding `{ items, count, others }` (the group's items in order, how many, and how many past the first where there are more). Every item is a group of at least itself, so a row can draw `group.items` as a pile and say "and 3 others" with a `Text` bound to `group.others`. A `Text` with `countNoun` (`["other", "others"]`) writes a number with its noun, the singular after 1. HUD groups each page on its own, so a group that runs across a page break draws as two rows. Grain's apps group across pages, since they hold every page they've read. Grain's notifications are a List grouped so, each row as Grain draws one. An `Icon` with `style: "glyph"` draws its reason's glyph alone in a column before it, a heart in the heart's colour for a favorite and the rest in the accent, picked from the reason by `names` and `tints` (each value's glyph and tint). Under it go who did it (a `Faces` pile), their name, what they did and when, then the comment, what a reply replies to (a `Text` with `style: "quote"`, on one line behind a rule) and the gallery's title. The gallery or story's picture (an `Image` with `size: "thumb"`) sits at the row's end. A row opens its gallery, its story in its account's archive, or a follow's follower. ### Toggle `Toggle` is a settings switch: a `label`, an `about` line under it, and `on`, a binding to whether it is on now, with `default` where the data holds none (a setting never set). Its `call`, in a bundled view alone, is the procedure a flip sends, its input a template with `{"$on": true}` where the new state goes. The switch moves at once and flips back if the call fails. Once it lands the view is read again, since the other switches' calls were made from the settings as they were. Grain's settings page has a switch for each of `social.grain.actor.getPreferences`' upload and notification settings, each calling `social.grain.actor.setPreference` with that whole kind. ### Choice `Choice` is a setting of one of a few values, the sibling of `Toggle`: a `label`, an `about` line, `options` (2 to 6 `{ label, value }`, each value a string), and `on`, a binding to the value chosen now, with `default` (one of the values) where the data holds none of them. Its `call`, in a bundled view alone, is the procedure a choice sends, `{"$on": true}` in its input where the value goes. Of 2 or 3 options it's drawn as a segmented control, of more as rows to pick from. It shows the choice at once, goes back if the call fails, and reads the view again once it lands, as a Toggle does. Grain's settings page has one for its theme (`social.grain.actor.defs#themePref`) and, for each kind of notification, one for whom it's from (everyone or people you follow). ### Pinned feeds Grain's camera, place and hashtag feeds have Pin feed where that feed isn't pinned, and Unpin feed where it is, signed in, each in the screen's bar: Pin with the `pin` icon, Unpin with `pinned`, the pin filled. Each draws nothing where its `$with` or `$without` would change nothing, and calls `social.grain.actor.setPreference` with the whole `pinnedFeedsPref`. Pin adds the feed at the end of those pinned (or of Grain's three, where none are), as Grain's apps write it (`{ "id": "camera:Fuji X100V", "label": "Fuji X100V", "type": "camera", "path": "/camera/Fuji X100V" }`). Unpin takes it out. An Action with a `call` and `reload` isn't kept as done, since the view read again shows what it did, and the same call can come round again. A view's scope holds the `at` it was opened with, so a view can draw a part of itself alone: a Stack whose `where` holds it (`{ "at": { "$is": "feeds" } }`). The gear in Grain's feeds opens its settings at `feeds` (`"at": "feeds"`), which draw My feeds and nothing else. That's a row for each feed pinned (Grain's three where none are), with Move up but on the first, Move down but on the last, and Unpin. Each sends the whole preference with that feed moved or gone. Grain's settings have a row that opens My feeds too. ### Pages and the host's own An `open` can also be `{ "url": "https://…" }`, a page the host opens in its browser. In a bundled view it can be `{ "host": "signOut" }` too, which the host app does itself by signing the account out. A host that doesn't do it leaves out the List item or Link that opens it, so a Grain tile in an MCP host or the workspace has no Sign out. Grain's own clients (its web shell and iOS app, in grain's repository) sign out so. A bundled view can place `Accounts` too: the accounts the host app is signed in to, which the host draws from what it keeps. Each is a row of its picture, its name over its handle, the one in use ticked. A tap on another switches to it, and Add account under them signs in to one more. The host reads each row from the frame's `account.picture` call, made as that account (its `name` and `handle` paths, [the frame](#the-frame)). Where the host keeps no accounts, as an MCP host or the workspace, the node's children are drawn in its place, as a `Stack`'s. Grain's settings give it the account's own row, from the view's data. Switching, adding and signing out each draw the app anew as the account then in use, so nothing of the one before shows (its screens remembered, what was read ahead, its badge counts, an open form). Signing out leaves the others signed in, the one before in use. The web shell keeps the accounts (`Sessions`, [the frame](#the-frame)), and HUDKit and the Android kit draw the node from the accounts their app gives them (`ViewContext.accounts`). Grain's settings page is an index, as Grain's own settings are. First come its accounts (`Accounts`, else who's signed in). Then a row for each of its pages, each the settings opened at its own `at`: Appearance (the theme chosen beside it), Account (the handle and DID, then Delete account, a row), Notifications, Moderation (muted and blocked accounts), Feeds (My feeds) and Privacy (upload defaults). A List with `chevrons` ends each row that opens something with a chevron, as these do. Then Grain's policies, its own [pages](#pages-of-the-apps-own), and Sign out. Delete account is an Action whose `deletes` repeats ([Action](#action)). ### Clamped text | Prop on the tree | Holds | | --- | --- | | `clamp` | about the most lines shown before more, as the layout gives it | | `shownRuns` | a `Text`'s or `RichText`'s runs cut to fit `clamp`, an ellipsis after them | | `shownBlocks` | a markdown `RichText`'s blocks cut to fit `clamp` | A `Text` or `RichText` with `clamp` is cut on the server, so a page drawn on a server and the apps cut it in the same place and nothing moves when a browser hydrates the page. A line holds 44 characters, about what body text fills in a phone's 390-point column less what wrapping at words leaves at a line's end. A line break ends a line, Han, kana, Hangul and emoji count two characters each, and the text is counted in graphemes, never cut inside one. Text longer than its budget is cut at the last word that fits, an ellipsis after it, and sent as `shownRuns` beside its whole `runs`. Text that fits gets nothing. A link, mention or tag the cut falls in is left out whole, unless it is the first run, whose words are cut and whose target is kept. Markdown is cut by the same budget. Each block costs its lines: a paragraph its words, a heading one more, a code block its lines and one, a table its rows and one, a picture its height across the column, a list or quote its blocks. A margin between blocks costs one more. Blocks are kept whole while they fit, then the next is cut where it can be: a paragraph at a word, a code block or table to its first lines or rows, a list to its first items, a quote to its first blocks. A heading or picture that doesn't fit is left out, and a first block nothing of which fits is shown whole. The clients draw the cut with a button under it, "Show more" (a `Text`'s, "more"), which draws the whole. Nothing is measured. A `Text` is also held to its `clamp` lines while closed, so in a column narrower than a phone's (a shelf's card) it ends in an ellipsis there. A shelf's card opens its item itself, so it offers no button. ### Document `Document` draws a long-form post's body. It draws Leaflet's pages of blocks (`pub.leaflet.content`) or markdown (`at.markpub.markdown`), and otherwise the post's plain text. ### Embed `Embed` draws a Bluesky post's embed as Bluesky does, in its AppView form or its record's form. It handles these: - images or a gallery - a link card - a video (played as Bluesky's HLS, or from the blob proxy) - a quoted post with its own embed one level down (in a record's form, fetched from the AppView) - a feed, list, starter pack or labeler card - media with a quote The bundled Bluesky feeds, timeline and thread draw every post's embed with it. ### FeedContext `FeedContext` draws what a Bluesky feed item's post comes with, as the Bluesky app does. That's "Reposted by" or "Pinned". For a reply it draws the thread's root, "View full thread" and the parent above the reply, joined by a thread line. Where those aren't drawn, it shows "Replied to …". ### Tree and Chain `Tree` draws items and, nested under each, the items at a path within it (a thread's `replies`). It goes six levels deep by default. `Chain` walks from an object along a path (a thread's `parent`) and draws what it passes, oldest first. ### Action `Action` is a button that writes as the signed-in account, through `create_record` or `delete_record`. It either holds a record to create or binds a uri to delete. A record's values can be literals, bindings, `{"$now": true}`, `{"$strongRef": ""}` (the `{ uri, cid }` of a record), `{"$root": ""}` (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 `/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:?action=delete`). A plan naming a collection sign-in doesn't ask to delete deletes none of that plan, and is never done: it stops, saying "Some records can't be deleted here yet" and naming those collections. Grain's sign-in leaves its groups' collections out, as groups don't work yet, so nobody is asked again to consent for them. An account with records in them keeps those, and is told so. - `then` is a procedure called once nothing is left (without `repeat`, once the plan is committed), as the account, its input literal JSON but `{"$did": true}`, their DID. - The Action's `handle`, with `confirm`, binds the account's handle, which the person types before the button goes on. Its `signOut: true` signs the account out once it's done, and where the host doesn't sign out, the Action isn't drawn. HUD reads `repeat`, `collections` and `then` from the view, never from the client. Grain's Delete account: ```json { "component": "Action", "props": { "label": "Delete account", "tone": "danger", "style": "row", "confirm": "Delete your Grain account?\n\nThis removes all your Grain galleries, …", "handle": { "$": "me.handle" }, "deletes": { "method": "social.grain.server.getAccountDeletionPlan", "service": "did:web:grain.social#grain_appview", "repeat": true, "collections": ["social.grain.actor.profile", "social.grain.comment", "…"], "then": { "method": "social.grain.server.deleteAccount", "service": "did:web:grain.social#grain_appview", "input": { "did": { "$did": true } } } }, "signOut": true } } ``` An Action is drawn compact by default, as a count beside it. `style: "button"` draws it as a button of its own, as a profile's Follow. `style: "row"` draws it as a row of a `List` with `style: "rows"`: the whole width, reaching the edges the rows reach, with their padding and their words' size, its label from the start, `tone: "danger"` in the danger colour. Right after a List of rows, or another row Action, it draws the line between rows above it and so joins them, so a `Stack` with `gap: "none"` holding both makes one group. Grain's Settings put Delete account so, after Sign out, as iOS's Settings put a destructive row last. Its question, its count of records gone and what went wrong are a button's. The bundled Bluesky feeds and thread have Like and Repost on every card. Grain's galleries, comments and stories have Favorite (`social.grain.favorite`, with `viewer.fav` the one made). ### Picking covers A `Covers` with `select` (a bundled view's alone) lets a person pick some covers and act on them at once. It names its button (`label`, Select by default), what it does (`action`, Delete), what one and several are called (`noun`), what the question adds (`confirm`), a `tone`, and a `call`, a procedure as an Action's, its input read from each item (`{"rkey": {"$rkey": "uri"}}`), or a `deletes`, a deletion plan's query as an Action's, its params read from each item. With `mine`, a path in the scope, it's offered only where that holds the signed-in person's DID. An item whose input can't be read can't be picked. Select sits at the right end of the row of the Panes the Covers is in, else on a line of its own over them. Picking, a bar says how many are picked and offers the action. Asked once (Delete 3 galleries?), it's done for each, one after another, each plan asked once the one before is committed and read back, and the view is drawn again. Those that failed stay picked, with what went wrong. Your own Grain page's galleries can be picked and deleted so (`social.grain.gallery.getDeletionPlan`). ### Compose `Compose` is a button that opens a form to write in: a post, a reply, a gallery, a comment or an edit of a profile. It names three things: - `fields`, what the form asks. A text field suggests accounts as @ is typed and marks its links, #tags and @mentions as they're typed. There are also a line, photos, languages, labels, a choice (such as who may reply), a place and a link card. Each photo is uploaded as it's added, through `place.hud.uploadBlob`, with its alt text and, for Grain, its camera's EXIF. A text, line or photos field's `value`, a binding the server reads, is what the form opens holding: a profile's name, or its avatar, shown and kept unless another is picked. A text or line's `value` may join words too (`{"$join": ["@", { "$": "author.handle" }, " "]}`): Grain's replies open holding the mention of whom they answer, so the mention is written as a facet and notifies them. A photos field with `round` draws its pictures round, as an avatar. One of a single photo, not round, draws it large, as a story shows it. A photos field with `camera` offers Camera beside the library: on iOS the device's camera, on the web a file picker with `capture` on a phone. Where there's no camera (a simulator, a desktop), picking is all there is. A place with `from`, a photos field, is filled with the place its first photo was taken at, from the photo's GPS, while none is picked. A photos field's `exif` and a place's `locate` may be bindings to an account's preference, on unless it holds false: Grain's New gallery and Add to your story keep to its upload defaults (`@photoMetadataPref`'s `includeExif` and `includeLocation`), as Grain's apps do. - `given`, values it holds already, such as a reply's root and parent, or the record key of the gallery an edit replaces (`{"$rkey": "response.gallery.uri"}`). - `writes`, a template (`hud_core::compose`) that the values fill into the records `apply_writes` writes at once. It can say `{"$value": name}`, `{"$each": …}` and `{"$facets": ""}`, which makes a field's text into `app.bsky.richtext.facet`s with each handle resolved to its DID. A write with `update` replaces one record: its record key such as `self`, or a value holding one (`{"$value": "rkey"}`). HUD reads the record from the account's PDS first, `{"$stored": ""}` 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": "", "params": { … }, "service"?: "did:…#fragment" } ``` The values of its params are literal or bound to the item. The bundled Bluesky feeds and timeline open a post as its thread (`app.bsky.feed.getPostThread`). On the web, a touch is a tap only if it stays put on something still. A touch that moved more than 10 px, or came down while what holds a `List` or `Covers` was still scrolling (a tap that stops a fling), opens nothing in it, the item's own links and buttons included. A phone's browser can end either as a click on whatever scrolled under the finger. A scroller is still scrolling until the browser says it came to rest (`scrollend`), or until it hasn't moved for 100 ms where the browser doesn't say, so a tap as soon as a glide stops opens. A mouse's clicks are left as they are. ## Query views A view of a query's answers names its `method` instead of a collection. It also names the `service` it calls by default, and one mode, `query`. That mode says where the answer's array of items and its cursor are. It has a summary over the items, and a layout whose scope is `{ method, service, params, response, items, cursor, joins }`. An answer that's one thing (a thread) has no items. Its summary reads the scope instead. The summary's `by` names the author, and its count is bound to an array. The count counts that array and, with `children`, the arrays nested in it (`Thread: "…" by alice.example: 12 replies.`). ### Newer items A list whose newest items come first can name each item's key in `latest`, a path within each item (`"latest": "post.uri"`). HUD then puts `_meta.ui.latest` in the tree. It holds the same call with no cursor (`call`), the items drawn by their keys (`items`, each `{ key }`), and the summary's plural noun (`noun`, "posts"). Where the method takes a `limit`, that call asks for 2, within what its lexicon allows and no more than the tile's own `limit`. That's the newest item and one more, so a post pinned first (`includePins`) doesn't hide a newer one. Something newer came when that call's tree has a key the drawn ones lack. So a pinned post at the top of an author feed doesn't count, since it was drawn too. The bundled timeline, author feed, custom feed (`app.bsky.feed.getFeed`, For You and Discover among them), Grain's feeds (Recent, For you, Following and an account's galleries), and knotless's feed and notifications name a key. A custom feed picks its top posts afresh, so a check often finds one the tile lacks, as it does in Bluesky's app, which checks its feeds the same way. What the clients do with it is on [the workspace page](workspace.md#newer-items). ## Query joins Any mode may also join a few related queries, so one tile draws the answer with what goes with it. That's a **query join**, in the mode's `join`: ``` { "as", "query": "", "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.` (a page's, a record's own or a query answer's). It's null when the call fails, runs out of time, or answers what its lexicon doesn't allow (HUD logs that). HUD keeps a query's answer a few seconds for the person who asked it, as `query` calls do ([kept answers](internals.md#kept-answers)). A join that needs what's there now says `"fresh": true`. HUD then calls it each time and keeps none of its answers. A query view's `query` mode may say `fresh` for its own call too. ### Params A query join's params are literals, bindings or `{"$root": …}` into the main scope alone. They never read a join's result. The main scope is a query view's `params`, `response` and `at` (what it shows first), a page's `did`, `handle` and `records`, and also a record's `value`. A param can also be `{"$each": [array, path]}`. That's an array of the value at `path` in each element of `array` there, in order, each once, at most 50 (`{"$each": ["records", "uri"]}` is every record's uri). HUD asks with no more of them than the method's lexicon takes for that param (its `maxLength`), the first. A binding that doesn't resolve, or an `$each` that finds nothing, skips the call. HUD checks the literal params against the method's lexicon as the view loads (a problem is the view's error), and checks all of them before each call. ### Service and limits A query join calls the query view's own service unless it names one. In a records mode it names one, unless its method has a bundled view. A mode has at most 6 query joins, and they join nothing further. An inline view's joins are held to the same limits. `say` adds a few words to the tool's text. It reports how many `count` finds in the answer, or the first line of `label` (`… README: knotless keeps a git…; latest release: 0.15.0.`). ### Pages A page more (a cursor) keeps the first page's joins. The exception is a join that reads the page, which runs on every page: a records page's that reads its `records`, or a query view's that reads its `response`. A List of a records page's such join (`{"$root": "joins.…"}`) is the page's. Such a view's pages are no longer than its `pageSize`, so one call takes a page whole. ### Bundled query joins The bundled views use query joins for these: - a knotless repository's README (collapsed past about 20 lines) and latest release - a Bluesky profile's latest 5 posts, and its feeds - a standard.site post's replies on Bluesky, where it links a post (`bskyPostRef`) - the posts Bluesky notifications of likes and reposts are about - a Grain gallery's comments - a Grain account's upload defaults (`social.grain.actor.getPreferences`), for its feeds' New gallery and its stories' Add to your story - the [app pages](app-pages.md) ## Bundled views `list_records`, `get_record` and `query` take a view inline (`view`). Otherwise they use the bundled one for the collection or method, and otherwise they draw generically. [The playground](playground.md) starts from any bundled view and draws an inline one as you write it. | View | What it draws | | --- | --- | | `views/bsky-feed.json`, `views/bsky-author-feed.json`, `views/bsky-timeline.json` | The AppView's feeds, each reply with what it replies to | | `views/bsky-feed-generators.json` | Feeds themselves (their names, makers and likes) | | `views/bsky-thread.json` | A post's thread. Its parents, the post, and its replies as a tree | | `views/bsky-profile.json` | An account's profile, with its latest posts and feeds | | `views/bsky-notifications.json` | Your Bluesky notifications: who did what, the post it's about | | `views/plyr-list.json` | plyr.fm albums and playlists | | `views/plyr-likes.json` | plyr.fm likes, as a playlist | | `views/plyr-tracks.json` | plyr.fm tracks an artist uploaded, to play | | `views/plyr-top-tracks.json`, `views/plyr-latest-tracks.json` | plyr.fm's most liked tracks over a period, and its newest, to play | | `views/standard-document.json` | Blog posts (standard.site documents) | | `views/standard-publication.json` | A blog with its posts joined by backlinks | | `views/knotless-*.json` | [knotless's views](knotless.md) | A record that a bundled method view draws as its query (its [`records`](#records)) opens as that query, by `get_record` with no inline view. A Bluesky post opens as its thread, and a repost as the thread of the post it reposts. With Grain's views served, a Grain gallery opens as `getGallery` draws it. A knotless repository, check, issue, pull, comment, profile or star opens as knotless's own views draw it. No bundled view draws those collections as records, and a collection is never shown as such. ## The operator's views You can serve apps of your own beside the bundled views. Point `HUD_APPS` at a directory, and HUD reads it as it starts (`hud serve`, and `hud resolve`, which installs its views as `hud serve` does). Grain is served so, from grain's repository: ``` / grain.social.json an app: its name, tabs, routes, head, push, refresh, permissions, frame, pages and sign-in pages/terms.md one of its own pages' text, in Markdown views/grain-feed.json a view, named as its id lexicons/… the lexicons its views and push call, at any depth (optional) ``` Each file at the top whose name holds a dot is an app file, named for its app's domain. Other files there (`package.json`) aren't apps, so the directory can be a client's own. An app file is the one the app's clients draw, with its `domain`, `name`, `tabs` and `routes`, each tab and route a tool call, its `head` ([App heads](#app-heads)), its `push` ([Push](#push)), its `refresh` ([Refresh](#refresh)), its `permissions` ([Permission sets](#permission-sets)), its `frame` ([The frame](#the-frame)), its `pages` ([Pages](#pages-of-the-apps-own)) and its `signIn` ([The app's sign-in screen](#the-apps-sign-in-screen)). Its `hud` says which HUD versions it runs on ([HUD versions](#hud-versions)). HUD doesn't serve it. Each client bundles its own copy, since they're built from the same repository as the file. Grain's are its `next/` web shell and `ios/` app, which reach HUD over `/mcp`. HUD trusts the operator's views as it trusts its bundled ones. So they may call procedures, join queries, name origins and do anything else these pages let a bundled view do. That's also why HUD holds them to what its tests hold the bundled views to, before it serves anything. If any file falls short, HUD refuses to start and names every problem, each with its file and where in it. `hud check ` runs the same check without serving ([Checking apps](#checking-apps)). - Each view parses as a trusted view, and a collection view draws both `list` and `record`. - Each `call` is a procedure that takes JSON, and its input has the fields its lexicon takes and requires. - Each query join's params are its method's, and it has a service. - A method view's profile section's params are its method's. - No two views draw the same collection, method or domain. A collection is in one view's `records` at most, and then no collection view draws it. - Each tab's call, a tab's `guest` and each route's call draw what a view draws. That's `query` of a method view's method, `describe_app` of an app page's domain, `get_record` of a collection a view draws or opens as its query, or `list_records` of one a collection view draws. A route's `tab` is a tab's label. A route's `pager` is `true` or absent, and only a pager's route has an `under`: a path starting with `/` that a route has, each of its tokens one of its own path's. - A tab's `first` is what its lexicon (`schemas/place.hud.tabFirst.json`) describes, with no key it doesn't name. Its call is a `query` of a method's NSID, and its `at` and `path` are dotted paths. - An app's `push` registers and unregisters with procedures that take JSON, each with the fields its lexicon takes and requires and `{"$token": true}` in its input. Each of what a notification opens names a route's path, and its `when` binds every token of that path. - An app's `refresh` names a procedure's `method` (an NSID) and the `service` it's of, and nothing else. - An app's `permissions` is a list of 1 to 8 permission sets, each an `include` (the set's NSID) and, where its methods are called at a service, that `service`, and nothing else. - An app's `head` names its `siteName`, and its texts are 1 to 300 characters, its `image` an https URL and its `twitter` an account as `@name`. - An app's `frame` is what its lexicon (`schemas/place.hud.frame.json`) describes, with no key it doesn't name at any level. Its `destinations` is `tabs`. Its action's, items' and aside's calls draw what a view draws, and its picture's call is a `query` of a method's NSID. The picture's `tab` is a tab's label and its `at` a dotted path. Each icon is one of `catalog::FRAME_ICONS`. - Each of the frame's account items has a `call` with a `label` and an `icon`, or a `host` (`signOut` or `signIn`, at most one of each), never both. Only a `signIn` item has an `about`. Each link's `href` is a path starting with `/` (but not `//`) or an https URL. `sizes.wide` is at least `sizes.content`, and `bands.sidebar` is wider than `bands.rail`. - An app's `pages` are 64 at most, each what its lexicon (`schemas/place.hud.page.json`) describes, with no key it doesn't name. Each `path` is a plain path (`/` and segments of `a` to `z`, `0` to `9`, `-`, `_` and `.`, with no query or token) that no other page, no tab's `path` and no route's path (its tokens any segment) has. Each `markdown` is a `.md` file's path, relative to the app file's directory and never climbing out of it, and the file is there. - An app's `signIn` is what its lexicon (`schemas/place.hud.signIn.json`) describes, with no key it doesn't name at any level. Each link in its `text` and `legal` goes to a path starting with `/` (but not `//`) or an https URL. Its typeahead's `url` is an https origin, with no path, query or fragment. Its `params` is an object of strings, numbers and booleans, and its paths are dotted, no segment empty. HUD checks the methods against the lexicons in the directory's `lexicons/` and those it bundles (`lexicons/` of HUD's repository), an app's own first ([An app's lexicons](#an-apps-lexicons)). So an operator's view can only call or join a method one of them has. `just lexicons` keeps a lexicon for each procedure Grain's views call and its app file pushes with. An operator's view replaces the bundled view with its id, and any bundled view that draws what it draws. So a `views/bsky-feed.json` in `HUD_APPS` is the Bluesky feed HUD serves. With `HUD_WORKSPACE=off`, HUD serves the operator's views alone, with no bundled view beside them, so an operator's view can't lean on a bundled one there (a query join naming a bundled view's service). The scope HUD asks accounts for is what the served views write, upload and call ([what HUD asks for](sign-in.md#what-hud-asks-for)), through the permission sets their app files name, if any. ### Checking apps `hud check ` loads a directory of apps exactly as `hud serve` loads `HUD_APPS`, and serves nothing. It reads `HUD_WORKSPACE` as `hud serve` does, so check with `HUD_WORKSPACE=off` if you serve the apps alone. It prints each problem on a line of its own, its file and then where in it, and exits 1 if there's any: ```sh $ HUD_WORKSPACE=off hud check next next/views/grain-feed.json: query.layout.children[2].props.gap: must be one of none, xs, sm, md, lg next/grain.social.json: app.routes[3].call: no view draws "social.grain.feed.getCameras" hud check: 2 problems, as HUD 0.2.0 loads next ``` Run it with the HUD you deploy against, in the app's own checks, before the app ships. A HUD newer or older than that one may hold the apps to more or less. For an editor, HUD publishes the JSON Schemas of an app file and a view in its repository's `schemas/json/` (`hud schema app` and `hud schema view` print them). Name them in a file's `$schema`, and an editor completes keys, components and props, and marks a key HUD doesn't know: ```json { "$schema": "https://knotless.dev/chadtmiller.com/hud/raw/v0.2.0/schemas/json/view.json", "method": "social.grain.unspecced.getCameras", … } ``` Name the release you deploy against (its tag, `v`), so the schema matches that HUD. `main` names the newest. A schema says a file's shape alone. What its calls draw, the lexicons it calls and its paths are `hud check`'s to find. HUD makes the view's schema from the component catalog and the app file's from its own lexicons of the frame, pages, sign-in screen and a tab's `first`, so `just json-schemas` writes them again after a change to either, and a test fails until it does. ### HUD versions An app file's `hud` names the HUD versions the app runs on, as a semver requirement: ```json { "domain": "grain.social", "name": "Grain", "hud": ">=0.2.0", … } ``` A HUD older than the app needs refuses it with that alone (`app.hud: the app needs HUD >=0.2.0, and this HUD is 0.1.0: run a newer HUD`), since the rest of the app is written for a newer HUD. A HUD the app runs on goes on to check the rest. HUD's version is its release's, the same as `@hud/renderer`, `@hud/shell`, HUDKit and hudkit, and `hud check` says it. Leave `hud` out and any HUD checks the app. ### Old builds and new views A view changes on the server for every client at once, but an app's build in someone's hands keeps the renderer it was built with, its kit. A kit is HUD's renderer on a platform: HUDKit on iOS, hudkit on Android, `@hud/renderer` on the web. So each kit says its version as it calls, and HUD fits each tree to the kit that draws it. | Caller | Says | Drawn for | | --- | --- | --- | | HUDKit, hudkit or the web shell, on `/mcp` | `_meta`'s `io.modelcontextprotocol/clientCapabilities`, `extensions["place.hud/kit"]`: `{ platform, version }` | its version, the web's this HUD's | | HUDKit's workspace client, by `callTool` | its input's `kit`, the same | its version | | An MCP host drawing HUD's view (MCP Apps' `io.modelcontextprotocol/ui` capability, or any `initialize`-era host) | nothing more | this HUD's version | | The workspace's page and the playground | nothing more | this HUD's version | | Any other call | nothing | the oldest kit, 0.2.0 | A kit's version is its build's, HUD's one version, which knope bumps in every package at once ([versions](sdk.md#versions)). The kits name themselves in `io.modelcontextprotocol/clientInfo` too (`hud-kit-ios`, `hud-kit-android`, `hud-web`), for the logs, and HUD logs each tool call's kit ([what HUD logs](observability.md)). A view gates a part on the kit with a Stack's, Pane's or Bar's `when` or `unless`, given `{"$kit": requirement}`, a semver requirement, in place of a path: ```json { "component": "Stack", "children": [ { "component": "Stack", "props": { "when": { "$kit": ">=0.3.0" } }, "children": [ … the new way … ] }, { "component": "Stack", "props": { "unless": { "$kit": ">=0.3.0" } }, "children": [ … the old way … ] } ] } ``` HUD resolves the gate before it sends the tree, so a kit never gets a part it's gated out of. `hud check` refuses a requirement semver can't read. Any node can also give a `fallback`, a node drawn in its place by a kit that doesn't know its component: ```json { "component": "Gauge", "props": { … }, "fallback": { "component": "Text", "props": { "value": { "$": "value" } } } } ``` Each catalog component and prop knows the HUD version it arrived in, its `since` in `describe_collection`'s catalog, absent for what 0.2.0 has. Where a component is newer than the kit, HUD sends its children in its place, drawn as a Stack, else its fallback, else nothing. A kit handed a component it doesn't know, as one its platform doesn't draw yet, does the same in a release build. A debug build shows a box saying the component isn't drawn there yet, so you notice. A prop a kit doesn't know, it ignores. An app file can name the oldest kit its builds in people's hands still use: ```json { "domain": "grain.social", "name": "Grain", "kits": { "oldest": "0.2.0" }, … } ``` Then `hud check` warns of each component or prop in the operator's views newer than that kit with no kit gate around it, or, for a component, no fallback of its own. It's a warning, never a refusal. With several apps, the oldest of theirs counts. `oldest` is a HUD version from 0.2.0. ### Optional keys HUD refuses a key it doesn't know anywhere in a view, so a typo never slips through. A view written for a newer HUD can still run on an older one, a key at a time. Write the key as `?key`, and HUD reads it as `key` where it knows it. Where HUD finds a problem in it (a prop the component doesn't have, a word it doesn't know, a key it doesn't name), it leaves the key out and logs a warning instead of refusing to start: ```json { "component": "Stack", "props": { "?gap": "none" }, "children": [ … ] } ``` On a HUD with no `none` gap, that Stack draws with its default gap. A problem anywhere else still refuses the view, and so does what leaving the key out breaks (a required prop gone). Giving a key both ways (`gap` and `?gap`) is refused too. `hud check` prints the warnings, each naming the key's file and where it is. App files have no optional keys, because their clients read them too. ### An app's lexicons An app can ship the lexicons its views and push call, in `lexicons/` beside its views, at any depth (Grain's `lexicons/social/grain/…` as they are). Each `.json` file there is a lexicon document, named by its `id`. HUD checks the views against an app's lexicon in place of a bundled one of its NSID and reads it as it serves (a call's input, a service's answer), since the views were written against it. So HUD never refuses an app over a lexicon it doesn't bundle, or bundles at another version. A file that isn't a lexicon, a second file of one NSID and one of HUD's own (`place.hud.*`) are refused. ### A tab's root from the account's data A tab's `call` is its root, the same for everyone. Signed in, its `first` chooses the root from the account's data instead: the screen of the first item, of a list a query answers, whose path is one of the app's screens. Grain's Home opens the first feed the person pinned, in the order they set in My feeds: ```json "first": { "call": { "name": "query", "args": { "method": "social.grain.actor.getPreferences", "service": "did:web:grain.social#grain_appview", "params": {} } }, "at": "preferences.@pinnedFeedsPref.items", "path": "path", "after": "social.grain.actor.setPreference" } ``` - `call` is a `query` of a method's NSID, made as the account. - `at` is a dotted path to the list in its answer (in a query's `response`). A segment `@name` is the element of a list whose `$type` is `name` or ends `#name`, as the app's `scheme` reads one. - `path` is a dotted path, in each item, to a path of the app's own site (`/feeds/following`, `/camera/Fuji X100V`). The item's screen is that path's by the app's routes, and at the tab's own path it's the tab's `call`. An item whose path has no route is passed over, so Grain's Groups, a feed the next grain.social doesn't draw, is never its Home. - `after` is a procedure after which the root is chosen again. Where nothing listed has a screen, or the query fails, the tab's `call` stands, and signed out it draws its `guest`. Grain's Home has Recent as both, so it opens Recent where someone pinned nothing, as Grain's own apps do. The web shell's server chooses each tab's root for every page it draws (`rootsOf`), and the page carries them, so `/` is the chosen feed from its first paint, with no redirect and nothing swapped once hydrated. The tab's URL stays its own whichever screen it opens. Home is `/` for a camera's, a place's or a hashtag's feed too, drawn as Home's root with its strip and no back. A tab's root is at the tab's own URL, so a redirect to the feed's own path would be named `/` again once drawn. That path opens the feed as Home's root too, while it's Home's root, and as its route says once it isn't. After `after`, the browser chooses the roots again. A tab not on show takes its new root at once. The tab on show takes it as it's chosen again, or as its own URL is gone back to, so the screens over its root (My feeds among them) stay where they are. A history entry at a tab's own URL draws the root chosen now, so a page loaded again after a reorder shows the new first feed. HUDKit reads `first` too (`TabFirst`), and Grain's iOS app chooses Home's root as it starts and after `after`. The Android kit reads it too (`TabFirst`), and Grain's Android app draws the app file's tabs along the foot, each its own stack, choosing Home's root the same way. ### App heads An app file's `head` is what a page of the app says in its HTML head where its view's [head](#page-heads) says nothing. Grain's: ```json "head": { "siteName": "Grain", "title": "Grain: photo sharing on the AT Protocol", "description": "Grain is a photo sharing app built on the AT Protocol. …", "image": "https://grain.social/og-default.jpg", "imageAlt": "Grain: photo sharing on the AT Protocol" } ``` `siteName` is the site's name (`og:site_name`). `title`, `description`, `image` and `imageAlt` stand in for a page whose tree has none of them, and `twitter` names the app's X account (`twitter:site`). Grain's `next/` web app reads its copy of the file, as it reads its tabs and routes. ### Push An app file's `push` says how the app's clients register a device for push notifications with the app's own server, and what a tapped notification opens. Grain's registers with Grain's AppView, which sends the pushes itself: ```json "push": { "register": { "method": "social.grain.notification.registerPush", "service": "did:web:grain.social#grain_appview", "input": { "serviceDid": "did:web:grain.social", "token": { "$token": true }, "platform": { "$platform": true }, "appId": { "$appId": true } } }, "unregister": { "method": "social.grain.notification.unregisterPush", "…": "the same" }, "open": [ { "when": { "uri": "at://{actor}/social.grain.gallery/{rkey}" }, "path": "/profile/{actor}/gallery/{rkey}" }, { "when": { "did": "{actor}" }, "path": "/profile/{actor}" } ] } ``` `register` and `unregister` are calls of `call_procedure` as the signed-in account. The client stamps three bindings in their input: `$token` (the device's push token: APNs's as hex on iOS, FCM's on Android), `$appId` (the app's bundle or application id) and `$platform` (`ios` or `android`). HUD sends them as it sends a trusted view's call ([procedures](sign-in.md#procedures)), so the app's server gets them through the account's PDS. HUDKit does this on iOS and Android. Once someone's signed in, it asks to send notifications, and with leave registers the device's token. Before they sign out, or switch accounts, it unregisters the token as them, so the device stops getting the account's pushes. On Android the app hands HUDKit's `Push` a `Device` that asks Android's leave and its push service's token (Grain's, FCM's), and the tokens that service rotates, and draws the messages itself: HUDKit takes no push SDK. `open` maps a tapped notification to one of the app's routes. Each entry's `when` holds patterns of the notification's fields, written with a route's tokens. The first entry whose every field matches fills its `path`, and the client opens that path as it opens the route. A token alone takes a whole field (`{actor}`), and in a longer pattern one segment between slashes. A notification no entry matches opens the app as it was. ### Refresh An app file's `refresh` names the procedure of the app's own server that reads records the account just wrote back from the account's PDS. HUD writes straight to the PDS, and the app's server would otherwise hear of the write only when the network brings it, often seconds later. Grain's: ```json "refresh": { "method": "social.grain.sync.indexRecords", "service": "did:web:grain.social#grain_appview" } ``` After every write through HUD that lands (`create_record`, `apply_writes`, `delete_record`, a view's update, and a deletion plan's commit), HUD calls each app's `refresh` whose own collections it wrote, those the app's views write, with `{"uris": [...]}` (at most 25 a call), the records it created, changed or deleted. It calls it as the account, through their PDS, before the write answers, so what the views read next shows the write. A refresh that fails is logged, and the write stands. HUD bundles no lexicon for it, so an app may name one it doesn't have. ### Permission sets An app file's `permissions` names the [permission sets](sign-in.md#permission-sets) sign-in asks for in place of the permissions its views' collections and methods would each take. Grain's: ```json "permissions": [ { "include": "social.grain.authFull", "service": "did:web:grain.social#grain_appview" } ] ``` The set is a lexicon the app publishes (`type: permission-set`), listing its `repo` collections and the `rpc` methods it calls, each with `inheritAud: true`. Its `service` is the audience those methods take, so HUD asks for `include:social.grain.authFull?aud=did:web:grain.social%23grain_appview`. A set may only list NSIDs under its own namespace (`social.grain.` for Grain's), so HUD asks for what the views do outside it, and their pictures, directly. A set's contents are the app's to keep up. As HUD starts, it resolves each set and logs what a view writes, deletes or calls that the set doesn't grant. Grain's `next/check-apps.mjs` checks the same against its own copy of the set. ### The frame An app file's `frame` says how the app's clients draw the frame around its screens. That's the navigation, the app's one primary action, the account's area, links at the foot and an aside. Grain's: ```json "frame": { "destinations": "tabs", "action": { "label": "Create", "icon": "imagePlus", "call": { "name": "query", "args": { "method": "social.grain.feed.getFeed", "params": { "feed": "at://did:web:grain.social/social.grain.feed.generator/foryou" }, "compose": "New gallery" } } }, "account": { "picture": { "tab": "Profile", "call": { "name": "query", "args": { "method": "social.grain.actor.getProfile", "service": "did:web:grain.social#grain_appview", "params": { "actor": "me" } } }, "at": "avatar", "name": "displayName", "handle": "handle" }, "items": [ { "label": "Settings", "icon": "settings", "call": { "name": "query", "args": { "method": "social.grain.actor.getPreferences" } } }, { "host": "signOut", "label": "Log out", "icon": "logOut" }, { "host": "signIn", "label": "Sign in", "icon": "logIn", "about": "Share your photography" } ] }, "links": [ { "label": "Terms", "href": "/support/terms" }, { "label": "Privacy", "href": "/support/privacy" }, { "label": "Copyright", "href": "/support/copyright" }, { "label": "Guidelines", "href": "/support/community-guidelines" }, { "label": "Child Safety", "href": "/support/child-safety" }, { "label": "AT Protocol", "href": "https://atproto.com" } ], "sizes": { "content": 600, "wide": 935 } } ``` Leave `frame` out and nothing changes. Each field is optional too. - `destinations` is `tabs`, the app's own tabs (label, icon, call and badge). They're one list, drawn as a bottom bar, a rail or a sidebar by the window's width. - `action` is the app's primary action, drawn only to someone signed in. It has a `label` (1 to 40 characters), an `icon` and a `call`. A `query` call with `compose` opens its form over the screen you're on, with no new screen and no history entry. Any other call opens as a screen on the tab on show. - `account` is the account's area. Its `picture` reads the account's picture from a query's answer (`call`, at the dotted path `at`), and the tab named by `tab` shows it in place of its icon. The server reads it for each page, so the picture is there from the first paint. Its `name` and `handle`, dotted paths in the same answer, name the account in its row among the accounts (a view's [Accounts](#pages-and-the-hosts-own)), the call made as each account in turn. Its `items` (8 at most) are screens of the app's, each a `label`, `icon` and `call` shown signed in. An item can be one the host draws instead. That's `signOut`, shown signed in, or `signIn`, shown signed out with its `about` line over it. - `links` (12 at most) are a `label` and an `href` each, drawn at the navigation's foot. - `aside` is a screen drawn right of the column (`call`), `width` pixels wide (200 to 480, 320 by default). - `sizes` are the widths of the column a view's [measure](#how-wide-a-view-is-drawn) asks for, in CSS pixels. `content` is 600 by default (320 to 1600) and `wide` 935 (up to 2400). A `full` view takes the column to the window's edge. - `bands` are the window widths where the navigation changes. `rail` is 600 by default and `sidebar` 1200 (each 320 to 4000). The web shell (`@hud/shell`, in `web/shell`) draws it, and draws an app with no `frame` with every default. Under `bands.rail` the destinations are a bottom bar, and the action is left to the screen's own Bar. From there to under `bands.sidebar` they're a rail of icons, each label its tooltip. From `bands.sidebar` they're a labelled sidebar. In both, Search follows the first destination where the app has a `search`, the account's screens follow the destinations, and the action is a filled button under them. Log out and the links sit at the foot, and the picture shows on its tab. Signed out, Sign in sits at the foot with its `about` line. The rail leaves the links out. Where the action's `compose` names a form, a screen's Bar button for that form (a `Compose` of that label, as Grain's feeds' + for New gallery) is hidden in the rail and the sidebar, signed in, since the action beside it opens the same form. Under `bands.rail` it shows. The renderer marks a Bar's `Compose` with its label (`data-bar-form`) for this, and other Bar buttons, such as the feeds' gear, stay. The shell decides all of this in CSS from the window's width, so the page the server draws is the page the browser hydrates. A host may draw the navigation at bands of its own, over the frame's. Each destination is a stack of screens. Choosing one shows its root, as its link says, and lets go of the screens left over it. Choosing it again at its root reads it again. A screen that is a destination's own, such as a link to your own profile or its URL, opens as that destination rather than as a copy pushed over another, on the server as in the browser. A screen opened over the same screen isn't pushed again, and one opened from another destination starts from that destination's root. A screen's back arrow is the browser's back where the entry before is the screen under it. Otherwise, as for a search opened from another destination, it steps up in place of the entry on show, so the browser's back still goes where it went. A step back is taken once from each entry, so a pager of pages closes to the screen it was opened over even when asked to close twice at once, such as a story running out as ✕ is tapped. A screen under the one on top, and a pager's pages beside the one in front, are `inert`: out of reach of the keyboard and of screen readers. A screen under the one on top that has never shown, such as a destination's root under a page loaded at a screen over it, is drawn only once it shows, so loading the page never draws a screen nobody sees. On a phone, the links that show a while are read ahead, but only once the page has loaded and the browser is idle, two calls at a time, and never a link on a screen out of reach. Focus follows the screen on top, as a native stack's does. A screen opened from a link or button takes it at its title, and the screen gone back to gets it back where it was left. Signed out, forms aren't offered: a `Compose` with a count shows as that count. An `Action` that creates or deletes a record (a ♡, a Follow) goes to sign in when it's pressed, as Grain's web asks, rather than failing. A screen whose tree has a `next` pages as you scroll, as HUDKit's and the Android kit's lists do. Its foot is a Load more button, and once the page has hydrated, the shell loads the next page itself as that foot comes within a screen of the screen's own scroll (an `IntersectionObserver`, `auto` on the renderer's `LoadMore`). Each page appends to the tree's page list (a `List`, `Covers`, `Gallery` or `Player`) below what's in view, so the scroll doesn't move, and the list lets go of items far from view as it grows ([Memory](memory.md)). It loads one page at a time, and only on the screen in front (not one under another, under a pager or in a tab not on show, nor while its call is made again). A page that fails shows its error with Try again and loads nothing more until it's pressed. Where the browser asks to save data (`navigator.connection.saveData`), the button alone pages. The button stays in every case, for the keyboard, screen readers and a page drawn with no script. A `Messages` conversation loads its earlier messages by its own button at its top. A screen whose own `Tabs` strip selects it and offers a destination's root too is that root's swap, as choosing it in the strip makes it. Grain's Following, Recent or a pinned feed, each a choice of Home's strip, are like this. Its URL is drawn as that destination's root level, with its strip and no back arrow, by the server as by the browser, whatever its route's tab. The shell needs no list of such routes: the answer's strip says so. One the strip doesn't select, such as a camera that isn't pinned, opens over its route's tab as any screen does. Pressing the action makes its call in the background (read ahead as the button is hovered or pressed). Where the answer has a `Compose` marked `open`, the shell draws a tree of that form alone over the screen on show (`Tree`'s `form`): the same modal any `Compose` opens, with no button and nothing else of the screen it came from. Its writes are the account's, as any screen's are, so every screen is read again as it shows. Once sent, the shell opens the screen of the first record it made that one of the app's routes names, over the tab on show. For Grain's New gallery, that's the new gallery, by `/profile/{actor}/gallery/{rkey}`, whose call names `at://{actor}/social.grain.gallery/{rkey}`. Where no route names one, the screen on show is read again. Cancelled, the form closes and nothing moves. A call whose answer has no such form (signed out, an error, a view without one) opens as a screen on the tab on show. The column is `sizes.content` wide at most, and a `wide` view takes all the room right of the navigation, up to `sizes.wide`. The shell draws the aside right of the column only where the window holds the navigation, the screen's measure and the aside. It never draws one beside a `full` view. The shell is a Svelte package beside the renderer. Its host gives it the app file, its router's history (`Navigation`: the entry on show's state, a way to make one, and when the page is entered), where its server takes the pages' calls, uploads, sign-in, sign-out and switching accounts (`Host`), and what its server read for the page with `@hud/shell/server` (`screenAt`, `signInScreen`, `frameData`, `lookHead`). Grain's `next/` is such a host, on SvelteKit. The host's server keeps its sessions at HUD with `@hud/shell/server`'s `Sessions`, given HUD's address, the app's origin, its name, its callback's path and the secret its cookies are sealed with. Its `request` makes each request's `Hud`, the way to HUD as the account in use, which answers the endpoints the host routes to it (`signIn`, `callback`, `signOut`, `use`, `mcp`, `upload`). It signs in as an MCP client of HUD, a backend for frontend: only the server holds the tokens. A browser keeps up to five accounts, each its own HUD session and tokens, in one sealed HttpOnly cookie (AES-256-GCM): five seal to under 1.7 KB, so nothing is kept on the server and a restart signs no one out. Signing in again while signed in adds an account, since each sign-in names its account afresh on the app's sign-in screen. Signing in to one kept already takes its new tokens and revokes the old. Signing out revokes the account in use at HUD and leaves the rest. Switching is to an account the browser signed in to alone. A row's name, handle and picture are read with that account's own tokens and kept in the server's memory a while, never in the cookie. HUDKit and the Android kit don't read the frame yet. HUDKit will draw it as a `TabView` with `.sidebarAdaptable`, the destinations its tabs and the action and account in its sidebar or toolbar. Android will draw it with `NavigationSuiteScaffold`, a bar, a rail or a drawer by the window's size class. Both will open the action the same way: its call made in the background, its form alone as a sheet over the screen on show, and no screen pushed. ### Pages of the app's own An app file's `pages` are the app's own static pages, such as its terms and its privacy policy, each written in Markdown in a file beside the app file. Grain's: ```json "pages": [ { "path": "/support/terms", "title": "Terms and Conditions", "description": "The terms of using Grain, the photo sharing app built on the AT Protocol.", "markdown": "pages/terms.md" }, { "path": "/support/privacy", "title": "Privacy Policy", "…": "and so on" } ] ``` Leave `pages` out and nothing changes. - `path` is the page's path on the app's site, as `/support/terms`. - `title` (up to 80 characters) is its screen's title, and its HTML head's, as ` - <app's name>`. - `description` (optional, up to 300 characters) is what its head says of it, for a search result or a link's preview. - `markdown` is its text's file, relative to the app file's directory: GitHub's Markdown (GFM), read as a `RichText` of `gfm` reads it, so headings, lists, tables and the rest. HUD reads each file as it starts and refuses to start where one isn't there. `describe_app` with `page` (the page's path) answers the page: its Markdown as data and, drawn, its title in the screen's `Bar` over its text, with its head (`title`, `description`, and `canonical`, its path). In a page's text, and nowhere else, a link to a path of the app's own (`/support/privacy`) opens it on the app's site, `https://<domain>/support/privacy`, and a `mailto:` link writes mail. Any other link opens a page (http or https) or nothing, as in any Markdown HUD draws. A client draws each page as a screen of its path, as if it were a route whose call is that `describe_app`. The web shell tries the pages before the routes (`routesOf`), so a page opens by its link and by its URL, over the tab on show (from a link) or Home (loaded), with the browser's back and forward. The server draws it with its head, for search engines to index, and the browser hydrates it as drawn. A footer link whose `href` is a path opens its screen in the app, and so does a link in a screen's text to the app's own site (this origin, or its domain's, as a page links one): where no route has its path, the browser goes there. HUDKit makes each page a route the same way (`Route.all`), so an app built on it opens a page's path in the app, drawn by its `RichText`, and its text's mail links open the mail app. A link to the app's own site reaches the app's `onOpenLink`, which opens it by `Route.screen` where a route has its path. The Android kit reads an app file's routes the same way (`Route`), so Grain's Android app opens grain.social links as their screens. It doesn't make pages routes yet. ### The app's sign-in screen An app file's `signIn` is the app's own sign-in screen: what it says, and where it finds accounts as a handle is typed. Its clients draw it in place of HUD's sign-in page, in the app's own look. Grain's, with its web app's words: ```json "signIn": { "title": "Log in with your atmosphere account", "text": "[What is an atmosphere account?](https://atmosphereaccount.com/)", "placeholder": "e.g. user.bsky.social", "legal": "By signing in you agree to our [Terms](/support/terms), [Privacy Policy](/support/privacy), and [Community Guidelines](/support/community-guidelines).", "create": { "text": "Don't have an account?", "label": "Create one" }, "typeahead": { "url": "https://typeahead.waow.tech", "method": "tech.waow.typeahead.searchActors", "param": "q", "params": { "limit": 5 }, "items": "actors", "did": "did", "handle": "handle", "name": "displayName", "avatar": "avatar", "avatarFallback": "avatarFallback" } } ``` Leave `signIn` out and the app's clients send people to HUD's sign-in page. - `title` is the screen's heading, `text` a line under it, `placeholder` what the handle's field holds while it's empty, and `legal` a line under the form. In `text` and `legal`, Markdown's `[label](href)` is a link, to a path of the app's own site or an https URL. - `create`, where given, offers making an account: its `text` and a button, its `label`. HUD makes it at its sign-up PDS ([creating an account](sign-in.md#creating-an-account)). - `typeahead`, where given, is who matches what's typed: a public query at an XRPC host of its own, called by the client directly, as no one, never through HUD or a PDS. Its fields are a Compose text field's `suggest`'s, with `url` for the host: `GET <url>/xrpc/<method>?<param>=<typed>` with its `params`, the accounts at `items` in the answer, and each one's `did`, `handle`, `name`, `avatar` and `avatarFallback` at those paths in it. A picture is drawn from `avatar`, falling back to `avatarFallback` where that fails to load, and only from an https URL. It's asked from two letters typed (a leading `@` dropped), a moment after typing stops. typeahead.waow.tech finds any atproto account, not only those an app's appview has seen, so someone new to Grain finds themselves. With a `signIn`, HUD sends that app's web clients straight on to the account's server, the handle typed their `login_hint`, with no page of HUD's between ([the OAuth flow](sign-in.md#the-oauth-flow)). A refusal comes back to the client to show. The web shell draws the screen at the host's sign-in path (Grain's `/auth/signin?back=…`), in the frame over no tab, server-rendered and hydrated alike at every width (`signInScreen`, `SignIn`): the heading and its line, the field, the `legal` line, Cancel (back where it came from) and Sign in, and `create`. Signed in, it's Settings' Add account. As a handle is typed, whoever matches drops down under the field, each with their picture, handle and name. The arrows choose one, and Enter or a click picks it, filling in the handle and signing in at once. Escape closes the list. The form posts to the host's server (`Hud.signIn`), which asks HUD to start signing in itself. Where HUD goes on to the account's server, the browser goes there. Where HUD sends it back refused, the screen is drawn again with the handle and why. A refusal at the account's server comes back through the callback to the screen the same way. Without JavaScript, it's a form like any other. HUDKit reads the same section (`SignInPlan(app:)`, its `Typeahead`'s `search`, and `linked` for the lines' links), and an app built on it draws its own native screen from it. Grain's iOS app draws it as grain-ios's sign-in: the same words over its photo, the typeahead asked 200 ms after typing stops, a hardware keyboard's arrows and Return choosing and picking, then HUD's sign-in with the handle as its `login_hint`, or `prompt=create` for its Create one. The Android kit reads it too (`SignInPlan`), and Grain's Android app draws the same screen, then signs in through HUD in an Auth Tab where the browser has them, else a Custom Tab, sent back to its own `<application ID>:/oauth/callback`, which HUD's app client takes. ### Grain's views Grain's views are an operator's. Its app file and views live in grain's repository, and HUD's tests load a copy as an operator's (`crates/hud-core/src/testdata/grain/apps`). The pages here use them as examples. | View | What it draws | | --- | --- | | `grain-feed` | The feeds of galleries from Grain's AppView, each as Grain's card: who and where, the first photo, Favorite and comments, its camera, title and description. The feeds the person pinned are a strip over them, cameras, places and hashtags among them. The home feeds have who has stories under that, and a + for New gallery and a gear for My feeds in the bar. A camera's, a place's and a hashtag's feed is wide, its galleries three across, with a pin in the bar that pins or unpins it, and a place's a map of it over its galleries | | `grain-stories`, `grain-story-archive` | An account's stories of the last day, each marked watched as it shows, and every story it posted | | `grain-mutes`, `grain-blocks` | The accounts you muted and blocked on Grain, each undone in place | | `grain-settings` | Your Grain settings, in Grain's order: the account and Sign out, theme, My feeds, notifications, muted and blocked accounts, upload defaults, then Grain's import and its policies, its own pages. Opened at `feeds`, My feeds alone: the feeds pinned, to move and unpin | | `grain-gallery-view` | One gallery as that card with all its photos, then its comments and more of the photographer's galleries | | `grain-explore` | Grain's Explore (`getLocations`): a search, its top cameras and places, each opening its galleries and with a See all, over the newest galleries. With `pins: true` it's Grain's Locations, every place on a map over the top places' cards | | `grain-cameras` | Grain's Cameras (`getCameras`): its top cameras as cards, each with its photos' count, opening its galleries | | `grain-search`, `grain-search-people` | Grain's galleries and accounts matching a search, under the field to search again | | `grain-followers`, `grain-following`, `grain-known-followers` | Who follows an account on Grain, whom it follows, and those of its followers you follow | | `grain-notifications` | Your Grain notifications: who did what, the comment or gallery it's about, [grouped](#grouping) as Grain groups them | ## Trust and origins HUD holds a view to its shape strictly. An invalid view is the tool's error, with every problem named along with where it is, so the model can fix it. Only bundled views and [the operator's](#the-operators-views) are trusted. A view names `origins`, the https origins whose media URLs its bindings may load (plyr.fm keeps some audio and art off the PDS, and the AppView keeps its images on `cdn.bsky.app`), and `thumbnails`, URL prefixes on them rewritten to a smaller picture's. A trusted view may name any origin. A view given inline may name only origins some trusted view names, so it can draw the AppView's pictures too, and anything else it loads goes through blob refs. The UI resource's CSP allows exactly the trusted views' origins, beside the server's own origin, the image CDN's (`HUD_IMAGE_CDN`), and Bluesky's video service and CDN, for posts' videos. So an inline view never widens it. Its one fetch besides the server is a `Map`'s tiles: the Protomaps basemap of OpenStreetMap's data, vector tiles from `https://tiles.grain.social`, which serves them openly with no key. They're drawn in its light or dark flavour, as the page is. No code names Bluesky, Grain, plyr.fm, standard.site or knotless, but one: the map's tiles come from `tiles.grain.social` (`catalog::MAP_TILES`), a basemap HUD's operator runs, as no open one serves dark vector tiles without a key. A result says whether its view is trusted (`_meta.ui.trusted`). A trusted view's actions run on one click. Any other view's actions ask the person to confirm, showing the record first. ## Feed interactions Only a trusted view may report feed interactions: ``` "interactions": { "feed": <binding>, "item": <path>, "feedContext"?: <path>, "reqId"?: <path> } ``` The feed is bound in the query's scope, and the rest are paths within each item. HUD resolves them into the tree. `_meta.ui.report` is the feed, and each item's `report` is what the feed is told of it. Only a trusted view may have an `Action` with `interaction` (`{ event: "app.bsky.feed.defs#requestMore" | "…#requestLess" }`). That asks the feed for more or less like the item. The bundled feed view (`app.bsky.feed.getFeed`) does both, with More like this and Less like this on every card. ## Apps and profile sections A bundled view also names its app (`"app": "Bluesky"`, one line). That's the name an account's profile gives the domain behind the view's NSID. The view may add a section to accounts' profiles (`profile`). A method view's profile section is `{ "title", "params" }`. It calls the view's query with those params, each a literal or `{"$actor": "did"}` (the account's DID). It shows where the account holds any collection of the query's domain. | View | Title | Shows | | --- | --- | --- | | `bsky-author-feed` | "Bluesky" | The account's 3 latest posts without replies | | `grain-feed` (an operator's) | "Grain" | The account's 3 latest galleries | | `knotless-actor-repos` | "knotless" | The account's repositories | A collection view's profile section is `{ "title", "limit" }` (1 to 10, 3 by default). It shows that collection's newest records, drawn by the view's list layout, where the account holds the collection. standard.site's blog posts ("Blog") and plyr.fm's tracks, albums, playlists and likes have one. ### Activity A collection view may also name its records' activity (`"activity": "Posted"`). That's a short past-tense verb, 20 characters at most, for where its list's summary labels a record by its own words. standard.site's documents have "Published", plyr.fm's playlists "Made" and its tracks "Uploaded". ## Records A bundled method view may name the records it draws as its query (`records`, 1 to 8 of `{ "collection", "params", "at"?, "activity"? }`). Opening a record of that collection by its at-uri (`get_record`, with no inline view) then answers exactly as `query` answers the view's method with `params`, as the same caller. That includes `_meta.ui`, text, `next` and all. `at`, a binding into the record too, is what the answer shows first where it shows one thing at a time, as an `open`'s `at` is. Each param is a literal or a binding into the record as a join reads one, `{ uri, cid, did, value }`. HUD reads the record from its repository only where a param reads its `value` (or `cid`). Otherwise the record is just its at-uri, with its repository named by DID. If a binding finds nothing, the record can't be read, or the query doesn't answer, HUD draws the record as before, generically. `activity` is `{ "verb", "noun": [one, many], "label"?: binding }`. It's what making one of these records counts as in a profile's recent activity, as a collection view's activity is. A collection is named by one bundled view at most, and drawn by no collection view. The tests hold each entry's params to the method's lexicon, and each binding to the record's lexicon. An inline view names none of these. | Records | Drawn as | | --- | --- | | Bluesky's posts | Threads, by `uri`, activity "Posted" | | Bluesky's reposts | Threads, by the subject's uri | | Grain's galleries (an operator's view) | Activity "Posted" | | Grain's stories (an operator's view) | Their account's archive (`getArchive`, by the record's `did`), at the story | | knotless's repositories and checks | `getRepo` (repositories have activity "Created") | | knotless's issues, pulls and comments | `getThread` (issues and pulls have activity "Opened") | | knotless's profiles | `getProfile`, by the record's `did` | | knotless's stars | `getActorStars`, by the record's `did` | A knotless release names its repository by key, not at-uri, so nothing routes it and it draws generically. ## Launch A bundled method view may also offer places to go in its app (`launch`, 1 to 4 of `{ "title", "params"? }`). Each param is a literal or `{"$me": "did" | "handle"}`, the person signed in. These are the app's entry points. An app's page (`describe_app`) and the [workspace's](workspace.md) New tile list them, with their params made the person's. Signed out, an app's page leaves out the entries that name the person, and those whose view's query needs an account (its `signIn`). Each title says what it shows, and the tile's header says whose. | App | Entries | | --- | --- | | Bluesky | Posts and Saved feeds (`bsky-author-feed`, `bsky-feed-generators`) · Discover (`bsky-feed`, Bluesky's whats-hot feed) · Notifications (`bsky-notifications`) · Following (`bsky-timeline`) | | Grain (an operator's) | For you, Following, Recent and Galleries (`grain-feed`) · Explore (`grain-explore`) · Notifications (`grain-notifications`) | | knotless | Repositories, Activity, Everyone's activity and Notifications |