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

chadtmiller.com/hud

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

0
0
164 lines · 13.8 KB Raw History

title: Workspace section: HUD order: 7 summary: HUD's own page of canvases, where a person and their agents lay out tiles of read calls.

With sign-in on, /workspace is a page of HUD's own. It holds tabs of canvases. Each canvas is a strip of full-height columns, left to right, and each column is a tile or a stack of up to three.

A tile is a read tool's call (describe_repo, describe_app, describe_collection, describe_method, list_records, get_record or query). HUD draws it with the same renderers as the view and marks it with its app's icon. An app's page gets its own icon and is titled with the app's name by default.

Signing in to the workspace

Signed out, /workspace is HUD's landing page, and / sends a browser there (unless HUD_WEB names a web app, whose home / is, as the web app's pages say). Its Sign in opens the page's own dialog (and /workspace?signin opens it at once), where a person signs in with their handle or DID. As they type, the dialog suggests accounts from place.hud.searchActors (details: the workspace's methods). The page sends the handle to POST /workspace/signin as JSON ({"handle": "alice.bsky.social"}). HUD answers {"url": …}, the authorization page of the account's server, and the page goes there. If the handle isn't one or names no account, HUD answers 400 with {"error": "InvalidRequest", "message": …}, and the message is written for the person. It's the same atproto sign-in and comes back at the same /oauth/callback (details: sign-in).

The dialog's "Create one" (and the landing page's "Create an account") sends {"create": true} instead. HUD answers {"url": …}, the sign-up page of the sign-up PDS's authorization server (details: creating an account). If that server can't be used, HUD answers 502 with the same error shape. The dialog links to HUD's /terms, /privacy and /guidelines.

HUD keeps a web session and gives the browser its cookie, hud_session (HttpOnly; Secure; SameSite=Lax, 30 days). The cookie is good for the workspace only and never works as a token on /mcp. The page's icon is HUD's, /favicon.svg. The apps' logos that run past in the dialog are HUD's own copies, at /workspace/atmo/<name>. The landing's picture of the workspace, /workspace/hero/workspace-themes.webp, shows it in each of HUD's themes in turn. Where a browser asks for less motion, it shows workspace-light.webp or workspace-dark.webp, in the page's scheme. just hero makes all three again.

Several accounts

A browser stays signed in to up to four accounts besides the one in use. HUD keeps their session cookies in a second cookie, hud_accounts (the same attributes and 30 days), joined with ~, the one used last first. Signing in while signed in puts the session in use at the front of hud_accounts. If that makes five, HUD ends the one used least lately. Another session of the account just signed in to ends too, so each account is there once.

getWorkspace lists the others that are still live in accounts, by DID and verified handle (for the web session only). POST /workspace/switch with {"did": …} makes that account's session the one in use, and the one that was in use goes to the front of the others. A DID the browser holds no live session of gets 400.

POST /workspace/signout ends the session in use and revokes its atproto refresh token. The browser goes on as the account it used last, if it holds one, and is signed out otherwise. HUD answers {}, and the page reloads itself.

The page alone sends these three POSTs. Each needs X-HUD: 1 and the server's own Origin, else 403. HUD keeps every cookie as its SHA-256 only and never logs one.

Deleting your data

A person deletes everything HUD keeps of theirs from the account menu on the web ("Delete your HUD data") or from Settings in the iOS app. The dialog first lists what goes (getAccountData) and asks them to type their handle. Then deleteAccountData deletes, as the methods do one at a time:

  • The canvases they own, for everyone in them, and with HUD_SPACES=on every workspace space of theirs their sign-in reaches.
  • Their place in others' canvases, after the tiles they put there, so every page in them is told.
  • Their invitations, their tabs and their index of canvases.
  • The place.hud.theme records in their own repository, deleted as delete_record does, and their choice of theme.

Only then does every session of theirs end, on the web in any browser, in MCP clients and in the app, each with its atproto refresh token revoked. A browser goes on as its next account, as sign-out leaves it. If something can't be deleted, HUD answers UpstreamFailure with what it was, signs nobody out, and calling again carries on. The person's atproto account, and what other apps keep in it, stay.

Canvases

A person has any number of canvases. Each has a name, an owner and members.

The owner invites people by handle or DID (resolved, with the handle verified) as editors or viewers. Editors change the tiles, and viewers read them. An invitation shows in the invitee's list until they open it or decline it. The owner renames and deletes the canvas, changes roles and removes members. A member can leave.

LimitValue
Canvases per owner50 at most
Members per canvas20 at most
Tiles per canvas200 at most, the oldest going first

The first use makes a person's first canvas, "My canvas" (its id derived from their DID). HUD moves into it the one canvas they had before there were many.

Tabs

The canvases a person has open are their tabs, in their order, with one of them current. Closing a tab puts the canvas away and keeps it. The last open tab is never closed.

A canvas that's made, or an invitation that's opened, opens as the last tab. A canvas that's deleted, left or removed from leaves the tabs.

Placing tiles

The server places tiles, so a person and an agent place them alike. Each tile has these fields:

FieldWhat it holds
orderA decimal number as text ("3", "2.5"), ascending. A column head's order is on the strip, and a stacked tile's is within its stack.
widththird, half, two-thirds or full. By default half for documents and galleries, else third.
stackFor a stacked tile, the head it's under.

HUD puts a new tile in the first place that applies:

  1. With stack, at the end of that column (three tiles at most).
  2. With from, right after the run of columns from from that holds only what was opened from it. In Following | A | B, A's child goes between A and B.
  3. With after, right after that column.
  4. Otherwise at the end.

A move gives the moved tile a number between its new neighbours' numbers, so it's the only tile rewritten. Where two neighbours leave no room (some fifty halvings in one place), HUD numbers that line 1, 2, 3… again. When a column's head is taken off, the next tile in its stack heads it.

Canonical calls

HUD keeps each call canonical:

  • It sorts the keys and drops empty values.
  • A query that names no service gets the one its bundled view calls.
  • It lowercases an app page's domain.
  • It names accounts by DID where the call names them by handle. That covers a query's at-uri and at-identifier params (as its lexicon declares them), get_record's uri, and the actor of list_records, describe_repo and describe_app. A handle that doesn't resolve stays as given.

Adding a call that's already on that canvas (addTile, canvas_add) adds nothing. HUD answers with that tile and existing: true, and the workspace brings it into view. Opening from a tile, the launcher or the palette looks only on the canvas on screen. The palette's open tiles go to their own canvases.

Agents

Any MCP client signed in as a member fills the same canvases the pages show. canvas_add runs a read tool once as the account to check it works. Then it places a tile for it, holding the tool and its arguments and never the result, since the page calls the tool to draw it. Every page with that canvas open shows the tile at once, marked as the agent's and with its author.

ToolWhat it does
canvas_addChecks a read call and places a tile for it
canvas_listLists tiles in strip order, with widths and stacks
canvas_placePlaces a tile beside another tile, and sets a width
canvas_removeTakes a tile off
canvas_createMakes a canvas

Each takes canvas, an id or a name. By default it's the person's current canvas (the one last opened in the workspace, else "My canvas"). So you can ask Claude, signed in to HUD, to "put my For You feed on my HUD canvas", or "on the Coast trip canvas".

A tile opened from another keeps that tile's id (from). Taking a tile off leaves the tiles opened from it as they are.

Newer items

A tile drawing a list newest first (a tree with latest, see query views) checks for newer items while it's drawn and the page is in view. It checks once a minute, and again as it comes back into view if its last read or check was 30 s or more ago. It stops once it finds some.

Then its refresh button shows without a hover, with a dot. Scrolled down, a "New posts" button also sits over the top of its body, and it goes to the top and reads the tile again. HUD never puts newer items in above what a person is reading. Ten such tiles on screen make about ten small calls a minute.

The iOS app checks the same way while a column is on screen and the app is active. It shows the button over the column's top, and pulling down still reads the column again. The MCP App view doesn't check.

Music

Music a tile plays keeps going as a person moves about. The page plays it in one <audio> of its own, through scrolling, switching tabs, putting a canvas away, and refreshing or closing the tile.

A mini player sits in the tab bar, and across the foot of the screen on a phone. It shows the track, plays, pauses and skips it, goes back to its tile while that's open, and stops it. Media keys and the lock screen work it too. The MCP App view does the same within itself, as you go from a playlist to an artist and back.

Themes

A person draws the workspace in a theme of their choosing, from the palette menu in the tab bar or the palette's "Choose a theme". By default it follows the system's light or dark. The choices are:

  • HUD's own light or dark.
  • One of HUD's palettes: Frost and Paper (light), Amber, Blueprint, Dusk and Phosphor (dark).
  • A theme someone made.

HUD's themes are data, themes/<key>.json, embedded in the server. Each is a place.hud.defs#theme: its name, its scheme and, but for light and dark, its palette, each colour named for what it colours.

People make their own as knotless's themes are made. "New theme" starts from another theme and changes its colours, the editor drawn in them as they change. It publishes a place.hud.theme record in the person's own repository, written as create_record writes and deleted as delete_record does. "Browse everyone's themes" lists one account's or everyone's, the repositories holding them found by the relay (HUD_RELAY).

Every text in a palette reads at 4.5:1 or better on what it's drawn on. The tests hold HUD's palettes to it, and a person's must meet it to be made or chosen (hud_core::theme::problems). The editor names each pair that falls short as it's made.

HUD keeps the choice on the server, copying a person's theme as it was when chosen. So it follows the person to every page and app they're signed in to, each told as it changes, and a theme changed or deleted later leaves them as they were. A page also keeps what it drew last, so it opens in it. The iOS app chooses among the same themes, and themes are made on the web.

Where canvases live

By default canvases live on the server, in <HUD_DATA_DIR>/canvas/ (see how it works).

With HUD_SPACES=on, a canvas that only its owner is in lives in a personal space on the owner's own PDS, which only they read. Its address is at://<owner>/space/place.hud.workspace/<canvas id>. The canvas info is a place.hud.canvas record keyed self, and each tile is a place.hud.tile record keyed by its id (schemas/).

HUD decides where a person's canvases go once per sign-in. They go to the person's space if all of these hold:

  • Their PDS says it serves spaces (describeServer's spacesAlpha).
  • Their sign-in was granted the space permission.
  • Listing their workspace spaces works.

Otherwise they go on the server. The first time, HUD moves their canvases on the server that are theirs alone into spaces, keeping each file aside as <id>.json.moved.

HUD writes a tile's places and widths a second after the last change. A failed write is tried again with the next change. Three failures in a row put the person's canvases back on the server for the rest of that sign-in.

A canvas shared with anyone stays on the server (and HUD deletes its space). Deleting a canvas deletes its space. Every canvas the methods and canvas_list give says where it is, as storage: { kind: "space", uri } or { kind: "file", reason? }. The reason says why it isn't in a space, such as sign in again … for a sign-in made before the scope asked for spaces.

Turning spaces on

For a PDS to grant that permission, the space type place.hud.workspace must resolve as a lexicon. That takes two things:

  • Its document, schemas/place.hud.workspace.json, as a com.atproto.lexicon.schema record keyed by the NSID in the publisher's repository.
  • A DNS TXT record _lexicon.hud.place holding did=<the publisher's DID>.

Until then a PDS refuses the whole sign-in (invalid_scope), which is why HUD_SPACES is off by default. Once both are in place, turn it on, and each person signs in again.

The workspace's XRPC methods and event stream are on the workspace API page.