chadtmiller.com/hud
A remote MCP server that shows atproto records as interactive UI inside MCP Apps hosts
place.hud.hudkit 0.3.1 Latest 5 packages
0
0
# Working on HUD
For every agent working here: CLAUDE.md is this file, imported. What HUD
is and how it is run is in `README.md` and the pages in `docs/`.
## Layout
- `crates/hud-core`: everything that is not HTTP: configuration, the
outbound client and its address filter, identity resolution, lexicons,
PDS reads, XRPC queries (`xrpc.rs`: services, params and answers checked
against lexicons), blob-ref rewriting, the audio blob cache, views
(their validation, the component catalog, the join engine, summaries),
the kit each tree is fitted to (`kit.rs`: the renderer's version a
client says, a view's gates on it, what stands for a component newer
than it, and `hud check`'s warnings for an app's oldest kit),
the tools, the three that write (`writes.rs`, a text's facets made by
`richtext.rs`, a composer's writes template filled by `compose.rs`),
a link's card (`cards.rs`) and places (`places.rs`) for a composer, the
procedures a trusted
view calls (`procedures.rs`), the operator's apps and views
(`operator.rs`, `HUD_APPS`, checked as the bundled views' tests check
them, with the lexicons they ship and the HUD versions they run on),
the JSON Schemas of an app file and a view (`schema.rs`), the
workspace's canvases
(`canvas/`: the engine, each person's tabs and live stream, placement on
the strip of columns in `strip.rs`, the `Store` trait and its file
backend, the space backend in `space.rs`, with `HUD_SPACES=on`, the
tools), apps' icons (`icons.rs`: favicons, kept on disk), the
workspace's themes (`theme.rs`: HUD's, people's `place.hud.theme`
records, their contrast check, and each person's choice of one), what
HUD keeps of a person and its deletion (`account.rs`), the
space client (`space.rs`: `com.atproto.space.*` as the account), the
scope sign-in asks for (`scope.rs`: atproto's permissions, built from
the trusted views, through the permission sets their app files name,
and whether a sign-in is behind them), and
sign-in (`oauth/`: the MCP authorization
server in `issuer.rs`, the atproto OAuth client in `client.rs`, sessions
on disk in `store.rs`, MCP sessions and the workspace's web sessions
alike, and their offline tests against a fake PDS in `tests.rs`, its
spaces and the space backend's tests in `tests/spaces.rs`).
- `crates/hud-server`: the HTTP surface: `POST /mcp` (and its sign-in
challenges), `GET /blob/{did}/{cid}`, `GET /_health`, the terms, privacy
policy and guidelines, `GET /{terms,privacy,guidelines}` (`policies.rs`,
each page's HTML in `policies/`), HUD's icon, `/favicon.svg`, the
playground, `/playground` (`playground.rs`), HUD's methods,
`/xrpc/place.hud.*` (`xrpc.rs`, its tests through the router in
`xrpc/tests.rs`: the playground's and `searchActors` anyone's, the
workspace's with sign-in on alone), and apps' icons, `/icon/{domain}`
(`icon.rs`); and with sign-in
on `/oauth/*` and `/.well-known/oauth-*` (`oauth.rs`, with the sign-in
page MCP clients see), the workspace's page, `/workspace` (where `/`
goes; signed out, the landing), the sign-in
dialog's app logos, `/workspace/atmo/*` (`crates/hud-server/atmo/`),
the landing's picture, `/workspace/hero/*` (`crates/hud-server/hero/`,
made by `just hero`), and its sign-in, switching and sign-out,
`/workspace/{signin,switch,signout}`, its sessions' cookies
`hud_session` and `hud_accounts` (`workspace.rs`); with `HUD_WEB`, the
operator's web app's pages, `/`, the icons and every request no route
takes, handed on and streamed back (`web.rs`, its tests against a fake
app in `web/tests.rs`); its
`build.rs` embeds `web/dist/index.html`, `web/dist/workspace.html`,
`web/dist/playground.html` and `web/dist/favicon.svg`.
- `crates/hud`: the binary, `hud serve`; `hud resolve`, which gives a
recorded answer its `_meta.ui`, for the harnesses; `hud check <dir>`,
which loads a directory of apps as `hud serve` loads `HUD_APPS`,
naming every problem; and `hud schema app|view`.
- `web/renderer` (`@hud/renderer`): the renderers as Svelte components,
with no dependency on MCP, so another app can reuse them, drawn on a
server (`svelte/server`) as in the browser: nothing touches a browser's
globals as it loads or draws, nothing is kept on a server, and the
browser's first drawing is the server's (`Tree`'s `now`, dates fixed
until mounted). Its server test, `web/renderer/test/ssr.mjs` (`cd web &&
npm run ssr`), draws Grain's trees in `web/renderer/test/trees` (made by
`just ssr-data`, `harness/ssr/data.mjs`) in Node and hydrates them in
happy-dom.
- `web/renderer`, `web/shell` and `web/shared` are HUD's web packages,
published (`docs/sdk.md`): each package's `src` built by `svelte-package`
into its `dist` (`cd web && npm run package`), which its exports name;
inside `web/` they resolve to `src` by the `@hud/source` condition
(`vite.config.ts`, `tsconfig.json`, the server tests' builds). Code in
`web/` imports one by its name (`@hud/shared/result`), never by a path
into it.
- `web/shell` (`@hud/shell`): an app drawn as a web app from its app
file (`docs/views.md`, "The frame"): `Shell`, its frame (the tabs as a
bar, a rail or a sidebar by the window's width, decided in CSS,
`frame.ts`) and each tab's nav stack of tool results drawn with the
renderer, server-rendered and hydrated as the renderer is; and
`@hud/shell/server`, what an app's server reads for a page, and its
sessions at HUD (`session.ts`: the browser's accounts, sealed in a
cookie, `seal.ts`, `accounts.ts`; signing in as HUD's MCP client,
`oauth.ts`). Its host gives it its router and routes its endpoints
(Grain's `next/`). Its
server test, `web/shell/test/ssr.mjs` (in `npm run ssr`), draws a sample
app at three widths and hydrates it; `npm run unit` its unit tests.
- `web/src`: the view, which talks to its host through
`@modelcontextprotocol/ext-apps` and draws with the renderer.
- `web/workspace`: the workspace's page, which calls its own server's
`/xrpc/place.hud.*` and draws with the renderer, and the playground's
(`web/playground.html`, `Playground.svelte`), built of the same
components: a view written beside what it draws (`previewView`);
`web/shared` (`@hud/shared`), what it, the view and the shell share:
reading a tool result (`result.ts`), a person's interactions
(`interactions.ts`) and `Result.svelte`; `web/public/favicon.svg`,
HUD's icon, which Vite copies into `web/dist` as it is.
- `web/dev`: a dev host for the view (`just dev`), against `just serve`.
- `lexicons/`: the bundled lexicons, written by `just lexicons`; never
edited by hand. `schemas/`: our own lexicons (`place.hud.*`:
the records, the workspace's methods, `defs`, and `ui`, the resolved
tree a result's `_meta.ui` holds, which `hud_core::ui::check` holds the
resolver's trees to in its tests), written by hand, embedded beside
them; `just lexicons` never touches it. `schemas/json/`: the JSON
Schemas of an app file and a view (`hud_core::schema`), no lexicons,
written by `just json-schemas` and held current by a test.
- `harness/`: checks beside cargo's, each a node script whose header says
what it checks and how to run it, run by the Justfile: `lexicons.mjs`,
`answers.mjs` and `schemas.mjs` (`just lex`), `layers.mjs`, `contrast.mjs` and
`docs.mjs` (`just lint`), `look.mjs` (`just look`), `scroll.mjs` (`just scroll`, a long
feed scrolled, page in `harness/scroll/`), `gallery.mjs` (`just
gallery`: every drawing HUD makes as a tile, side by side, from the
answers in `harness/gallery/` given their trees by `just
gallery-data`; the iOS app draws the same file, Debug builds' Settings →
Development → Gallery). `cd harness && npm ci` once. Against a PDS of
HUD's own: `pds.mjs` (the reference PDS and PLC, alice, bob and carol),
the e2e world over it (`e2e/world.mjs`, `just e2e`), and the same kept
running with a browser at it, and with `--ios` the app on a simulator,
to try by hand (`local.mjs`, `just local`). HUD is served there at
`hud.harness.internal` with a certificate of the checkout's own
authority (`tls.mjs`, kept in `.local/tls/`), which a simulator is told
to trust. Each takes the spaces alpha with HUD_DEV_ENV
(`harness/spaces`; `just e2e-spaces`, `just local --spaces`), where HUD
keeps canvases in people's spaces. `just local-setup` once per checkout
and Mac: the packages, the authority, and that hostname in /etc/hosts.
- `views/`: the bundled views, one JSON file per view, named as its id,
each a `place.hud.view` document; embedded by hud-core and
checked by its tests. An operator's views (`HUD_APPS`) replace or add
to them at startup, held to the same checks (`view::trusted_problems`,
`view::conflicts`).
- `docs/`: the docs, one page per topic, each fact in one page, written
and checked (`harness/docs.mjs`) as `docs/_style.md` asks, which says
which page owns what; `README.md` points at them. A change to a tool, a
default or a mechanism changes the page that owns it.
- `themes/`: HUD's own themes, one JSON file per theme, named as its
key, each a `place.hud.defs#theme`: light and dark, HUD's own look,
with no palette, and the rest each a palette; embedded by hud-core,
checked by its tests, and handed to the page and the iOS app by
`getWorkspace`, so no client keeps a copy. People's are records in
their own repositories (`place.hud.theme`), held to the same contrast.
- `ios/`: the iOS app. `ios/HUDKit`, a Swift package: the renderer in
SwiftUI, a port of `web/renderer` (`Tree/` draws the tree the server
resolved, `Embed/` its embeds), what `web/shared/src/result.ts` and
`interactions.ts` do
(`Data/`), the client that calls the tools over `/mcp`, an operator's
app file's routes and push for an app built on HUDKit (`Data/Routes.swift`,
`Data/Push.swift`: the device registered as its `push` says, a tapped
notification opened as a route), and the
workspace's client and model (`Workspace/`: its XRPC methods and event
stream as the signed-in account, by Bearer, and its theme,
`Theme.swift`); its tests in `Tests/`. A palette reaches the views
through `Support/Surface.swift` (`.hudTheme`, and `HUDColor`, a role's
colour or the native one): a colour a palette names is never a system
colour in a view.
`ios/App`, the app around it: signed in, the workspace (canvases as
tabs, a strip of columns, one a screen on a phone, each tile a tool
call), Home and Settings (accounts, theme) sheets over it; signed
out, signing in by handle; its icon in `App/Assets.xcassets`, the same as the favicon,
square, as iOS masks it. `ios/project.yml` makes the Xcode project
(`just ios`; the project is gitignored); `just ios-test` runs HUDKit's
tests.
- `android/`: the Android app, a Gradle project. `android/hudkit`
(`place.hud.kit`): the renderer in Jetpack Compose, a port of
`ios/HUDKit` as that is of `web/renderer`: `tree/` draws the tree the
server resolved (`TreeView.kt`'s `ResolvedNode`, a component a
function), `parts/` and `embed/` its pieces, `data/` what
`web/shared/src/result.ts` does, `support/` the surfaces by role
(`Surface.kt`'s `HudColors`, a palette's colour or Material's), type,
icons (`Glyphs.kt`, the web's own paths) and pictures (Coil); its
tests in `src/test`, on the JVM under Robolectric, reading iOS's
fixtures. `android/app`, the app around it: for now the gallery, the
sample tiles of `just gallery-data` a debug build carries (`just
android <entry>`; `just android-test` runs hudkit's tests).
A new crate goes in `crates/<name>`, named as its directory, with its
versions in the root `Cargo.toml`'s `[workspace.dependencies]`.
## Versioning
HUD has one version, its SDK's: the crates', the web packages',
HUDKit's and hudkit's (`knope.toml` names every file that holds it). A
pull that changes what an app built on HUD sees (a component, a prop,
what a tree draws, a tool's shape) adds a change file under
`.changeset/`, as `knope document-change` writes one: `default: patch`,
`minor` or `major` in its front matter, then a heading and a line for
the app's authors. `release-pull.yml`, asked for at main, turns them
into the version and CHANGELOG.md in a `Release <version>` pull;
`release.yml`, asked for at main once that lands, publishes every
package. Never bump a version by hand. `docs/sdk.md` has the rest.
## Rules
- Cargo through rustup: `rustup run stable cargo` (the Justfile's `cargo`).
Node is the version `.node-version` names; `cd web && npm ci` once.
- `just check` is what a change must pass: rustfmt, clippy with warnings
denied, the tests under `just cov`'s gate, svelte-check, the renderer's
server test (`npm run ssr`), `just lint` and `just lex`. The runner
(runner.knotless.dev) runs the same on pushes to main and pulls into it
(`.knotless/workflows/`): `check`, `test` and `web` as the merge queue's
pre-flights, `lexicons`, `docs`, `e2e` (`just e2e`) and `e2e-spaces`
(`just e2e-spaces`). `main` takes pulls only through the merge queue, each
once review.knotless.dev has reviewed its head, and each push to it
deploys hud.place (`deploy`, on ci.knotless.dev). A workflow's shared
steps are pinned in `.knotless/uses.lock` (`knotless workflow pin`).
- `just cov` fails under 100% of lines or functions, workspace-wide: a
line no test runs is a case nobody checked, so test it with what a
consumer would notice, never lower the gate or hide code from it. Where
no test can sensibly reach a line, write it so the path does not exist:
`cargo fmt` can put a `?` on a line of its own, which counts as a line
never run (bind the value first), and since Rust 1.100 coverage counts
the closing `}` of an `if` with no `else` as the path where the
condition is false, and each match arm on its own. The `hud` binary
counts too: its tests run it (`CARGO_BIN_EXE_hud`), and stop `hud
serve` by SIGTERM so its profile is written.
- A lexicon in `schemas/` follows the Lexicon Style Guide
(https://atproto.com/guides/lexinomicon) and passes `just lex`: goat's
lint (less the warnings `harness/lexicons.mjs` keeps, each with why),
`knownValues` not `enum`, objects in arrays, open unions, a description
on every `main` saying whether it needs auth, a `maxLength` on every
string without a format people write, accounts by DID; and only grows
from main's once published. Every answer the server's tests receive is
held to its method's lexicon (`harness/answers.mjs`), so a method's
tests call it through the router (`xrpc/tests.rs`'s `ask`).
- The server keeps no database: caches only, in memory, and the lexicon,
audio blob and apps' icon caches on disk under `HUD_CACHE_DIR`; and,
with sign-in on, sign-ins under `HUD_DATA_DIR/oauth/`
(`hud_core::oauth`), the workspace's canvases and each person's
index of them and their tabs under `HUD_DATA_DIR/canvas/` (`hud_core::canvas`),
and each person's theme under `HUD_DATA_DIR/theme/` (`hud_core::theme`),
each file mode 0600 and written whole; with `HUD_SPACES=on`, a canvas
its owner alone is in goes in their own space instead. The one
database is the operators' copy of the log, with `HUD_LOGS=on`:
`HUD_DATA_DIR/logs.db` (`hud_core::logs`), SQLite, mode 0600, holding
the lines stderr has and nothing more, so never a token, a query's
secret, a header or a body; read by `HUD_OPERATOR_DIDS` alone. Lines
are logged through `hud_core::telemetry` (`docs/observability.md`),
every outbound call through `hud_core::net`. Never log a
token, or keep one of HUD's own (a web session's cookie too) but as its
SHA-256. The `query` tool calls queries alone, never a
procedure; a caller goes through `xrpc::Caller`, as no one or as the
signed-in account through its PDS, the one place they differ. Writes
go through `create_record`, `apply_writes` and `delete_record` alone, as
the account, to its own repository, each record checked against its
lexicon first (its `{"$facets": key}` fields made the text's facets
before), and a composer's pictures through `place.hud.uploadBlob` alone,
to the account's PDS, never logged; but a
procedure a trusted view calls (`Action`'s `call`, `Messages`' `send`),
or an operator's app file registers a device for push with (its `push`),
through `call_procedure` (`hud_core::procedures`) alone, the view's,
sent through the account's PDS only if a trusted view or app file calls
that method of that service, its input checked against its lexicon first, neither
input nor answer logged; what a trusted view's `deletes` plans (an
`Action`'s), through `call_procedure` alone too, its query asked as the
account only if a trusted view deletes by it, its deletes committed in
one `applyWrites` of the account's own repository, each of a
collection the scope asks to write or delete (`Hud::delete_planned`);
and
the canvases' records through `hud_core::space`, as the account, to its
own repo in its own spaces, each checked against its lexicon
(`schemas/`) first. The space scope stays one constant
(`config::SPACE_SCOPE`), never asked for by default.
- A tool that needs an account answers `Refusal::SignIn` without one,
which `/mcp` turns into the HTTP 401 challenge, never a tool error. No
OAuth or MCP SDK crates: sign-in is built on the `atproto` crate's
`jose` and `keys`.
- Anything a DID document, lexicon or service says is untrusted. Outbound
requests go through hud-core's client, which refuses non-public
addresses, but for the operator's own web app (`HUD_WEB`), its origin
the operator's, reached through a client of its own for it alone
(`net::Web`); a service's answer is checked against its query's lexicon;
lexicon `description`s reach the view only, as plain text, never a
tool's `content`, description or `structuredContent`
(`describe_collection` and `describe_method` strip them).
- A tool's text `content` is a short summary a person could read; its data
is `structuredContent`; what only the view needs is `_meta`.
- The view loads nothing but its own inline code, and images and audio
from the server's blob proxy, and public records' images from the image
CDN (`HUD_IMAGE_CDN`), and public posts' videos from Bluesky's video
service and CDN (HLS); it reaches the server only through its host's
tool calls. No `fetch` from the view but a `Map`'s vector tiles, from
`catalog::MAP_TILES` alone (in the CSP's `connectDomains`).
- `blobs::rewrite` is told whether what it rewrites was read where anyone
can (`Visibility::Public`: `com.atproto.repo.*`, the AppView) or not
(`Private`: a space, a service's answer to the account): a private
record's blobs never get a CDN URL.
- The workspace's page reaches its own server alone, its XRPC methods as
its web session; their procedures by the cookie carry `X-HUD: 1`, and
the server takes them from its own `Origin` only. A HUD access token as
`Bearer` calls them too, as an app of the person's would. A canvas tile
names a read tool and its arguments, never a result: the page calls the
tool (`callTool`) to draw it. Tiles are placed on the server
(`canvas::strip`), so a person and an agent place them alike.
- A change to a tool, its shapes or the view's renderers changes both
sides in one change.
- Views are data. No code names a collection a bundled view draws: a
record type gets its own drawing by a view in `views/`, written with the
catalog's components, not by a renderer of its own. Where a query draws
a record richer (a post's thread), the record opens as that query: its
method view names the collection in `records`, and no collection view
draws it. Collections themselves are never shown: a profile shows apps,
sections and activity, never a list of collections.
- A tile is one thing. A view draws what belongs to its subject in
itself, by a join: a post's replies, a gallery's photos and comments,
an issue's conversation. It opens a new tile (`open`) only for another
thing: another record, account, feed or app.
- An account opens where it is read: a name in a bundled view's drawing
opens their page in that view's app (`ui::Ctx::people`), else their
profile across apps (`describe_repo`), which a tile's @handle opens
too. A view names an account by `href`, never by an app's own query.
- Only the bundled views and the operator's (`HUD_APPS`,
`hud_core::operator`) are trusted, and HUD refuses to start unless the
operator's pass what the bundled views' tests hold them to, through
the same code. Every read of them goes through `view::bundled()`, the
bundled views as the operator's replace and add to them. No HUD code
names an operator's app. A view given inline is checked exactly
as a bundled one is, but may name only `origins` a trusted view names
(so it never widens the CSP), and its description reaches no tool
description or instructions. A
result says which it is (`_meta.ui.trusted`): the view asks the person
to confirm an untrusted view's `Action` before it writes.
- Views are resolved on the server: a view's layout is read against its
data in `hud-core/src/ui/` into `_meta.ui`, a tree the clients only draw
(no client binds a view or fetches for one). The component catalog
lives in four places that change together: the Rust constant
(`hud-core/src/catalog.rs`), which validates layouts and is what
`describe_collection` and `describe_method` hand a model, with the
resolver (`hud-core/src/ui/`) that reads it into the tree; and the three
that draw the tree, `web/renderer` (`src/tree/`), `ios/HUDKit`
(`Tree/`) and `android/hudkit` (`tree/`). A component or prop added to
the catalog says the version it arrives in (`since`): a build of an
older kit is sent its children, its fallback or nothing in its place
(`hud-core/src/kit.rs`). A look is the platform's own,
but the surfaces are one: a grey canvas, a tile's body lighter in front
of it, a card in a tile that body's colour inside a hairline (iOS's
`HUDKit/Support/Surface.swift`, Android's `support/Surface.kt`).
## Web pages
The workspace (`web/workspace`) follows knotless's web practices
(`~/code/knotless/web/AGENTS.md`, its `ui` skill):
- **Layers:** components live in `web/workspace/lib/{atoms,molecules,
organisms,templates}`; each uses its own layer and those below, never
one above (`harness/layers.mjs`, in `just lint`). Pages in
`web/workspace/*.svelte` fill the template; modules in `lib/` (state,
the stream, `xrpc.ts`) belong to no layer.
- **Tokens:** every value in its CSS is a token from
`web/workspace/tokens.css` (knotless's, by the same names), a colour by
its role, never its hue, as `light-dark()`; add one there when none
fits. The renderer's MCP Apps host variables are set from them in
`app.css`, so tiles and chrome are one look, and a theme's palette
(`lib/theme.ts`) is written over them, so it colours both. Every text
colour reads at 4.5:1 in light, dark and every palette:
`harness/contrast.mjs` checks the pairs `harness/contrast.json` names in
light and dark, and `hud_core::theme::problems` its `PAIRS` in a
palette; a new colour that is text goes in the first, and in the
palette and the second if a theme colours it.
- **Icons:** Lucide's, through `lib/icons.ts`, one per thing, the same
everywhere; an icon without its word has an `aria-label`. An app's
icon is its favicon (`AppIcon`, HUD's `/icon/<domain>`), its kind's
Lucide icon where it has none.
- **Data:** the page reaches only its own server's XRPC methods, typed
by `npm run lex` (gitignored `lib/lexicons`), through `lib/xrpc.ts`.
- **Words and menus:** sentence case, labels without a full stop, empty
states that say what is empty where the rows would be, one primary
button a view; a menu that opens is a `<details class="popover">`, a
sheet on a phone.
- **Memory:** what a page holds follows what is on screen
(`docs/memory.md`). A tile keeps its answer as read (`$state.raw`, a page more
replacing it, never mutating it) and draws it only while `live`; a
component's state a person changes (a like, a reveal) is kept with
`remembered` (renderer `view/remember.svelte.ts`), as it is unmounted
and drawn again; a long list goes through `ListWindow`
(`view/window.ts`); a picture drawn small takes `source(…, 'small')`,
a blob's `thumb` or a URL by the view's `thumbnails`, and `Picture`
falls back once to a blob's `proxy`; media load nothing until played. A server cache
is a `cache::Ttl`, bounded by entries and bytes, its share of
`HUD_CACHE_MEMORY_BYTES`. Check a change with `just memory`, and one
to a long list's drawing with `just scroll` (no long tasks while
scrolling, p95 frame under 20 ms, no blank frames).
- **Looking:** `just look <name> [--set …] [--events …] [--click …]
[--press …]` draws the workspace from `web/dist` in front of
`harness/look/` (no PDS, no server: each answer given its `_meta.ui` by
`hud resolve`) into `target/look`. Look at every
state you touch, desktop light and phone dark, and have the pictures
critiqued by an agent that did not write them.
## atproto's primitives
DIDs, handles, NSIDs, record keys, CIDs and DID documents' services come
from the `atproto` crate (knotless.dev/chadtmiller.com/atproto), published
to that repository's Cargo registry, which `.cargo/config.toml` names. A
primitive HUD needs that the crate lacks goes there first, as a new version.