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
// An app, as its app file (<domain>.json) gives it to its clients: its
// name, its look (theme.ts), its page head's defaults (head.ts), its tabs,
// each tab a tool call (`call`) drawn as the root of its own nav stack, its
// routes, the URL each screen has (routes.ts), and its frame (frame.ts).
// HUD checks the file as it loads it (docs/views.md, "The operator's
// views"); a client bundles its own copy. Signed out, a tab draws `guest`
// instead: another call, or "call" for the same one; a tab without it asks
// to sign in. A tab's `wordmark` is its screen's title in place of its
// label, drawn as the app's logo (Grain's "grain" over its feeds); its
// `path` its URL at its root, where that is not its call's route (Grain's
// home, `/`); its `badge`, signed in, a count on its icon: a call (`call`)
// and where in its answer the count is (`count`, a dotted path, in a
// query's `response`); its `first`, signed in, where its root is chosen
// from the account's data: the first of a list's items that names a
// screen of the app's (Grain's Home, the first of the feeds the person
// pinned). Its `scheme`, signed in, where the account chose
// light or dark (theme.ts). Its `search`, the search the frame's
// navigation opens: a people typeahead (`typeahead`, a call its `params`
// are given `q` in), and the URLs, by its routes, of the results for a
// text (`results`, its `{q}`) and of a person (`person`, its `{actor}`).
// Its `pages`, its own pages (its terms, its privacy policy), each a path
// whose screen is HUD's `describe_app` of that page: its Markdown, which
// HUD read from the file the page names as it loaded the app file. Its
// `signIn`, its own sign-in screen (SignIn.svelte): what it says, and
// where it finds accounts as a handle is typed (typeahead.ts).
import type { Call } from '@hud/shared/result';
import type { IconName, UiNode, UiTabsProps, UiTree } from '@hud/renderer';
import type { Frame } from './frame';
import type { AppHead } from './head';
import { callOf, Names, pathOf, same, type Route } from './routes';
import type { Look, Scheme } from './theme';
export type Badge = { call: Call; count: string };
export type Search = { typeahead: Call; results: string; person: string };
/** A public query matching accounts to what is typed, at an XRPC host of its own: its paths are dotted, in its answer (`items`) and in each item. */
export type Typeahead = { url: string; method: string; param: string; params?: Record<string, string | number | boolean>; items: string; did: string; handle: string; name?: string; avatar?: string; avatarFallback?: string };
/** The app's own sign-in screen: its heading, a line under it and one under the form (their links Markdown's `[label](href)`), the field's placeholder, making an account, and the typeahead. */
export type SignInPlan = { title: string; text?: string; placeholder?: string; legal?: string; create?: { text?: string; label: string }; typeahead?: Typeahead };
/**
* Where a tab's root is chosen from the account's data, signed in: a query
* (`call`), the list in its answer (`at`, a path as `at` reads one), where
* in each of its items a path of the app's is (`path`, dotted), and the
* procedure after which it is read again (`after`).
*/
export type First = { call: Call; at: string; path: string; after?: string };
export type Tab = { label: string; icon: IconName; call: Call; guest?: Call | 'call'; wordmark?: string; path?: string; badge?: Badge; first?: First };
export type Page = { path: string; title: string; description?: string; markdown: string };
export type App = { domain: string; name: string; look?: Look; head: AppHead; scheme?: Scheme; search?: Search; signIn?: SignInPlan; tabs: Tab[]; routes: Route[]; pages?: Page[]; frame?: Frame };
/** The call whose answer is one of the app's own pages: HUD's `describe_app` of it, by its path. */
export const pageCall = (app: App, page: Page): Call => ({ name: 'describe_app', args: { domain: app.domain, page: page.path } });
const routed = new WeakMap<App, Route[]>();
/** Every screen of the app's with a URL: its pages, each a route of its path (tried first, as no route has a page's path), then its routes. */
export function routesOf(app: App): Route[] {
let all = routed.get(app);
if (!all) routed.set(app, (all = [...(app.pages ?? []).map((page) => ({ path: page.path, call: pageCall(app, page) })), ...app.routes]));
return all;
}
/** How wide a screen is drawn, as its view's `measure` asks: the frame's column (content), all its room right of the navigation (wide), or that to the window's edge (full). */
export type Measure = 'content' | 'wide' | 'full';
/** A screen's measure, as its tree says it; content where it says none. */
export const measureOf = (ui: UiTree | null | undefined): Measure => ui?.measure ?? 'content';
/** The call a tab draws, signed in or not; null where it needs an account. */
export function tabCall(tab: Tab, signedIn: boolean): Call | null {
if (signedIn || tab.guest === 'call') return tab.call;
return tab.guest ?? null;
}
/** A tab's URL at its root. */
export const tabPath = (app: App, tab: Tab, names: Names) => tab.path ?? pathOf(tab.call, routesOf(app), names) ?? '/';
/** Whether a path (with its query string) is a tab's own URL, `own`: the same, or with a query a link added (`?utm_source=`) where the tab's has none. */
export const isTabPath = (own: string, pathname: string, search: string) => own === pathname + search || (!own.includes('?') && own === pathname);
/** The origin a listed path is read against: a path of the app's own, never another site's (`//host`, `/\host`). */
const OWN = 'https://app.invalid';
/**
* The root a tab's `first` chooses from what its query answered: the
* screen of the first item whose path has one, the tab's own URL its
* `call` (Grain's Recent, pinned as `/` by older apps), any other by the
* app's routes; null where none has (nothing listed, or nothing the app
* draws, as Grain's Groups is not).
*/
export async function chosenRoot(app: App, tab: Tab, answer: unknown, resolve: (actor: string) => Promise<string>): Promise<Call | null> {
const first = tab.first;
const items = first ? at(answer, first.at) : null;
if (!first || !Array.isArray(items)) return null;
const own = tabPath(app, tab, new Names());
for (const item of items) {
const path = at(item, first.path);
const url = typeof path === 'string' && path.startsWith('/') ? new URL(path, OWN) : null;
if (url?.origin !== OWN) continue;
if (isTabPath(own, url.pathname, url.search)) return tab.call;
const found = await callOf(url.pathname, url.search, routesOf(app), resolve);
if (found) return found.call;
}
return null;
}
/**
* Each tab's root: its call, signed in or not (`tabCall`); signed in, a
* tab with `first` the screen its query's answer chooses (`chosenRoot`),
* its call where the query fails (`ask` answers its data, or null) or
* chooses none. Made for each page, so a list the person reordered is
* what the next page's tab opens.
*/
export async function rootsOf(app: App, signedIn: boolean, ask: (call: Call) => Promise<unknown>, resolve: (actor: string) => Promise<string>): Promise<(Call | null)[]> {
return Promise.all(
app.tabs.map(async (tab) => {
const own = tabCall(tab, signedIn);
if (!signedIn || !tab.first) return own;
return (await chosenRoot(app, tab, await ask(tab.first.call), resolve)) ?? own;
})
);
}
/** A tree's first `Tabs` strip, depth first through its children; null where it has none. */
function stripOf(node: UiNode): UiTabsProps | null {
if (node.c === 'Tabs') return node.p as UiTabsProps;
for (const child of node.k ?? []) {
const found = stripOf(child);
if (found) return found;
}
return null;
}
/** Whether a screen's tree has a `Tabs` strip that offers the screen itself (its item `selected`): a feed of Home's strip, as Grain's pinned ones. */
export const inStrip = (ui: UiTree): boolean => (stripOf(ui.root)?.items ?? []).some((item) => item.selected);
/**
* The tab a screen is the root of, in its root's place: where the screen's
* tree has a `Tabs` strip that offers the screen itself (`inStrip`) and a
* tab's root call (`roots`, `rootsOf`'s) beside it, that tab (Grain's
* Following, or a pinned feed, a choice of Home's strip); else -1.
* Choosing a strip's tab draws its call in the root's place (Stack's
* `swap`), so a URL of one is drawn so too, by the server as by the
* browser: the tab's root level, its strip shown and no back. A screen
* once there that its strip no longer offers (a feed unpinned) is a
* screen pushed over the root again (Stack's `unswapped`).
*/
export function swappedTab(roots: (Call | null)[], ui: UiTree): number {
if (!inStrip(ui)) return -1;
const items = stripOf(ui.root)?.items ?? [];
const offered = items.flatMap((item) => (item.open && 'call' in item.open ? [item.open.call] : []));
return roots.findIndex((own) => own !== null && offered.some((call) => same(call, own)));
}
/** What is at a dotted path in an answer: in a query's `response`, else in the answer itself; a key `@name` is the element of an array whose `$type` is `name` or ends `#name`. */
export function at(answer: unknown, path: string): unknown {
const data = answer as Record<string, unknown> | null;
let found: unknown = data && typeof data === 'object' && 'response' in data ? data.response : data;
for (const key of path.split('.')) {
if (key.startsWith('@') && Array.isArray(found)) {
const name = key.slice(1);
found = found.find((item) => {
const type = (item as { $type?: unknown } | null)?.$type;
return typeof type === 'string' && (type === name || type.endsWith(`#${name}`));
});
} else found = typeof found === 'object' && found !== null ? (found as Record<string, unknown>)[key] : undefined;
}
return found;
}