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
<script lang="ts">
import {
App,
applyDocumentTheme,
applyHostFonts,
applyHostStyleVariables,
type McpUiHostContext
} from '@modelcontextprotocol/ext-apps';
import { AudioHost, LinkButton, Loading, LoadMore, type ActionHandler, type UiInteractionHandler, type UiToolHandler } from '@hud/renderer';
import { onMount } from 'svelte';
import { version } from '../package.json';
import { CLICKTHROUGH, Interactions, SEEN } from '@hud/shared/interactions';
import Result from '@hud/shared/Result.svelte';
import NowPlayingBar from './NowPlayingBar.svelte';
import {
ACTION_TOOLS,
acted,
answered,
append,
loadingLabel,
feedOf,
methodOf,
nextPage,
ownsPaging,
pageOf,
read,
sent,
text,
viewer,
type Call,
type Entry,
type ToolResult,
type Viewer
} from '@hud/shared/result';
// The view the host shows for HUD's record tools. The host's own tool
// call arrives as input then result; each click calls another tool
// through the host and pushes its result on a back stack. While a call is
// out the view says what is coming, and when one fails, what went wrong:
// the frame is never blank. A tree's actions (Like, Mark read) write
// through the host too, as create_record, delete_record or
// call_procedure; the host signs in when the server asks it to. A
// conversation loads its earlier messages at its own top (`paging`), and
// reads itself again once a message is sent (`reload`). One player, its
// <audio> here, plays what a view's
// player plays, so music goes on as one moves about the view; a bar at its
// foot shows it, away from the view it plays from. Each step of the back
// stack is an origin of its own: its depth and its call.
let app: App | undefined;
const player = new AudioHost();
/** The views shown, oldest first; the last is on screen. Held as read,
* never deeply reactive: a step changes by being replaced. */
let stack: Entry[] = $state.raw([]);
/** What is loading in place of the view, if anything. */
let pending: string | null = $state(loadingLabel(undefined));
/** The state of "Load more" at the foot of the list on screen. */
let more: { loading: boolean; error: string | null } = $state({ loading: false, error: null });
/** The host's own call, as far as its input and context tell it. */
let hostCall: Call | null = null;
/** Counts navigations, so a call answered after the view moved on is dropped. */
let generation = 0;
/** What the host said of itself, as `ui/initialize` and its changes tell it. */
let host: McpUiHostContext = $state({});
/** The account the latest result was made for: none when signed out. */
let signedIn: Viewer | null = $state(null);
const top = $derived(stack.at(-1));
/** Where the music of the view on screen comes from. */
const origin = $derived(JSON.stringify([stack.length - 1, top?.call ?? null]));
const page = $derived(top ? pageOf(top.view) : null);
const method = $derived(top ? methodOf(top.view) : null);
const following = $derived(top ? nextPage(top) : null);
const canBack = $derived(stack.length > 1 || (pending !== null && stack.length > 0));
const canPopOut = $derived(host.availableDisplayModes?.includes('pip') === true && host.displayMode !== 'pip');
/** A view that would be drawn wide (`_meta.ui.measure`) offers to be shown full screen, where the host can: asked only when the person clicks, never by itself. */
const canExpand = $derived(
pending === null && top?.view.renderer === 'tree' && top.view.ui.measure !== undefined && host.availableDisplayModes?.includes('fullscreen') === true && host.displayMode !== 'fullscreen'
);
const showBar = $derived(canBack || signedIn !== null || canExpand || (pending === null && (page || method)));
const errorText = (error: unknown) => (error instanceof Error ? error.message : String(error));
/** Note who a result was made for. A failure says nothing of it: the
* server answers some without a session's details. */
function noteViewer(result: ToolResult) {
if (!result.isError) signedIn = viewer(result);
}
/** Take the host's context, whole or the part that changed: its theme,
* its style variables and fonts, and the display modes it offers. */
function hostContext(context: McpUiHostContext) {
host = { ...host, ...context };
if (context.theme) applyDocumentTheme(context.theme);
if (context.styles?.variables) applyHostStyleVariables(context.styles.variables);
if (context.styles?.css?.fonts) applyHostFonts(context.styles.css.fonts);
}
/** Ask the host to show the view picture-in-picture, as a player wants. */
async function popOut() {
if (!app) return;
const { mode } = await app.requestDisplayMode({ mode: 'pip' });
host = { ...host, displayMode: mode };
}
/** Ask the host to show the view full screen, as Expand asks. */
async function expand() {
if (!app) return;
const { mode } = await app.requestDisplayMode({ mode: 'fullscreen' });
host = { ...host, displayMode: mode };
}
/** Show a result as the one view, as for the host's own call. */
function reset(result: ToolResult, call: Call | null) {
generation += 1;
noteViewer(result);
stack = [{ view: read(result), call }];
pending = null;
more = { loading: false, error: null };
}
/** Call a tool through the host and push what it answers, or, `replace`
* (a tab chosen), put it in place of the view on screen. What the view
* on screen told its feed goes first. */
async function go(name: string, args: Record<string, unknown>, replace = false) {
if (!app) return;
void feedback.flush();
const current = ++generation;
const call = { name, args };
pending = loadingLabel(name);
more = { loading: false, error: null };
let entry: Entry;
try {
const result: ToolResult = await app.callServerTool({ name, arguments: $state.snapshot(args) });
noteViewer(result);
entry = { view: read(result), call };
} catch (error) {
entry = { view: { renderer: 'error', message: errorText(error) }, call };
}
if (current !== generation) return;
stack = replace ? [...stack.slice(0, -1), entry] : [...stack, entry];
pending = null;
window.scrollTo(0, 0);
}
/** Go back a view, or stop waiting for the one coming. */
function back() {
void feedback.flush();
generation += 1;
more = { loading: false, error: null };
if (pending !== null) pending = null;
else if (stack.length > 1) stack = stack.slice(0, -1);
}
/** Make the call that failed again, in its place. */
function retry(call: Call) {
stack = stack.slice(0, -1);
void go(call.name, call.args);
}
async function loadMore() {
const entry = stack.at(-1);
const call = entry && nextPage(entry);
if (!app || !entry || !call) return;
const current = generation;
more = { loading: true, error: null };
try {
// The arguments may hold the page's own state (a view object): a
// snapshot is what can cross to the host.
const result: ToolResult = await app.callServerTool({ name: call.name, arguments: $state.snapshot(call.args) });
noteViewer(result);
const next = read(result);
if (current !== generation) return;
if (next.renderer === 'error') more = { loading: false, error: next.message };
else {
const grown = append(entry.view, next);
if (grown) stack = stack.map((step) => (step === entry ? { ...entry, view: grown } : step));
more = { loading: false, error: grown ? null : 'The next page is not of this list.' };
}
} catch (error) {
if (current === generation) more = { loading: false, error: errorText(error) };
}
}
/** The view on screen's call made again, what it answers drawn in its
* place (a conversation, read again once a message is sent); a failure
* throws with the server's words. */
async function reload() {
const entry = stack.at(-1);
const call = entry?.call;
if (!app || !entry || !call) return;
const current = ++generation;
const result: ToolResult = await app.callServerTool({ name: call.name, arguments: $state.snapshot(call.args) });
noteViewer(result);
const view = read(result);
if (current !== generation) return;
if (view.renderer === 'error') throw new Error(view.message);
stack = stack.map((step) => (step === entry ? { view, call } : step));
more = { loading: false, error: null };
}
/** Earlier messages, asked for at a conversation's top rather than after it. */
const paging = $derived(top && following && ownsPaging(top) ? { load: () => void loadMore(), loading: more.loading, error: more.error } : null);
const openActor = (actor: string) => void go('describe_repo', { actor });
/** Open a call, as a tree's item (`item`, the report its feed is told of) names it; from a reported feed, the feed hears the post was opened. */
function openCall(call: Call, item: unknown) {
const to = feed;
const opened = to?.signedIn && item !== null ? to.of(CLICKTHROUGH, item) : null;
if (to && opened) feedback.add(to.feed, opened);
void go(call.name, call.args);
}
/** A tab chosen: its call drawn in place of the view on screen, never on top of it. */
const replaceCall = (call: Call) => void go(call.name, call.args, true);
const openLink = (url: string) => void app?.openLink({ url });
/** A view's action, as create_record, delete_record or call_procedure
* through the host: what it made or answered, or the failure in the
* server's words. */
const act: ActionHandler = async (kind, args) => {
if (!app) throw new Error('The view is not connected to its host.');
const result: ToolResult = await app.callServerTool({ name: ACTION_TOOLS[kind], arguments: $state.snapshot(args) as Record<string, unknown> });
noteViewer(result);
return acted(kind, result);
};
/** One of HUD's tools a view's form calls, through the host: its
* structured answer. The view uploads nothing (no `onupload`), so a form
* here has no photos. */
const tool: UiToolHandler = async (name, args) => {
if (!app) throw new Error('The view is not connected to its host.');
const result: ToolResult = await app.callServerTool({ name, arguments: $state.snapshot(args) as Record<string, unknown> });
noteViewer(result);
return answered(result);
};
/** Tells feeds what is done with them, through the host. */
const feedback = new Interactions(
async (feed, interactions) => {
if (!app) throw new Error('The view is not connected to its host.');
const result: ToolResult = await app.callServerTool({ name: 'send_interactions', arguments: { feed, interactions } });
if (result.isError) throw new Error(text(result) || 'send_interactions failed.');
return sent(result);
},
(message) => void app?.sendLog({ level: 'debug', data: message })
);
/** The posts each view has told its feed were seen, so coming back to it
* does not tell it again. */
const seen = new WeakMap<Entry, Set<string>>();
const feed = $derived(top ? feedOf(top.view) : null);
/** For the view on screen, when it reports to a feed: an item seen. */
const onseen = $derived.by(() => {
const entry = top;
const to = feed;
if (!entry || !to?.signedIn) return undefined;
return (item: unknown) => {
const found = to.of(SEEN, item);
if (!found) return;
const told = seen.get(entry) ?? new Set<string>();
seen.set(entry, told);
if (told.has(found.item)) return;
told.add(found.item);
feedback.add(to.feed, found);
};
});
/** For the view on screen, when it reports to a feed: "more like this"
* and "less like this", sent at once. */
const interact: UiInteractionHandler | undefined = $derived.by(() => {
const to = feed;
if (!to) return undefined;
return async (event: string, item: unknown) => {
const found = to.of(event, item);
if (!found) throw new Error('This item names no post to tell the feed of.');
await feedback.now(to.feed, found);
};
});
onMount(() => {
const instance = new App(
{ name: 'hud', version },
{ availableDisplayModes: ['inline', 'pip', 'fullscreen'] },
{ autoResize: true }
);
instance.ontoolinput = ({ arguments: args }) => {
void feedback.flush();
const name = instance.getHostContext()?.toolInfo?.tool.name;
hostCall = name && args ? { name, args } : null;
generation += 1;
stack = [];
pending = loadingLabel(name);
};
instance.ontoolresult = (result) => reset(result, hostCall);
instance.ontoolcancelled = ({ reason }) => {
if (stack.length === 0) {
reset({ isError: true, content: [{ type: 'text', text: reason ?? 'The tool call was cancelled.' }] }, hostCall);
}
};
instance.onhostcontextchanged = hostContext;
instance.onteardown = async () => {
await feedback.flush();
return {};
};
const hidden = () => {
if (document.visibilityState === 'hidden') void feedback.flush();
};
document.addEventListener('visibilitychange', hidden);
app = instance;
instance
.connect()
.then(() => {
const context = instance.getHostContext();
if (context) hostContext(context);
})
.catch((error: unknown) => {
if (stack.length === 0) reset({ isError: true, content: [{ type: 'text', text: `Could not reach the host: ${errorText(error)}` }] }, null);
});
return () => {
document.removeEventListener('visibilitychange', hidden);
void instance.close();
};
});
</script>
<main aria-busy={pending !== null}>
{#if showBar}
<nav class="bar">
{#if canBack}
<button type="button" class="back" onclick={back} aria-label={pending !== null ? 'Cancel' : 'Back'}>
<span aria-hidden="true">‹</span>
{pending !== null ? 'Cancel' : 'Back'}
</button>
{/if}
{#if pending === null && page}
{@const did = page.did}
<span class="crumb">
<LinkButton onclick={() => openActor(did)} title={did}>{page.handle ? `@${page.handle}` : did}</LinkButton>
<span class="sep" aria-hidden="true">/</span>
<span class="collection">{page.collection}</span>
</span>
{:else if pending === null && method}
<span class="crumb"><span class="collection">{method}</span></span>
{/if}
{#if signedIn}
<span class="viewer" title={signedIn.did}>Signed in as {signedIn.handle ? `@${signedIn.handle}` : signedIn.did}</span>
{/if}
{#if canExpand}
<button type="button" class="back expand" onclick={() => void expand()}>Expand</button>
{/if}
</nav>
{/if}
<!-- Drawn afresh for another call or depth, never for a page more, which grows the list in place. -->
{#key origin}
{#if pending !== null || !top}
<Loading label={pending ?? loadingLabel(undefined)} />
{:else}
<Result
entry={top}
onaction={act}
oncall={openCall}
onreplace={replaceCall}
onopenlink={openLink}
oninteraction={interact}
{onseen}
onpopout={canPopOut ? () => void popOut() : undefined}
onretry={retry}
{player}
playerOrigin={origin}
{paging}
onreload={top.call ? reload : undefined}
ontool={tool}
/>
{/if}
{/key}
{#if pending === null && following && !paging}
<LoadMore onload={loadMore} loading={more.loading} error={more.error} />
{/if}
{#if player.origin !== origin}<NowPlayingBar {player} />{/if}
<audio preload="none" {@attach player.attach}></audio>
</main>
<style>
main {
display: flex;
flex-direction: column;
gap: var(--hud-space-3);
padding: var(--hud-space-3);
}
.bar {
display: flex;
flex-wrap: wrap;
align-items: center;
gap: var(--hud-space-2) var(--hud-space-3);
min-height: 2rem;
font-size: var(--font-text-sm-size);
}
.back {
display: inline-flex;
align-items: center;
gap: var(--hud-space-1);
padding: var(--hud-space-1) var(--hud-space-3) var(--hud-space-1) var(--hud-space-2);
border: var(--border-width-regular) solid var(--color-border-primary);
border-radius: var(--border-radius-full);
background: var(--color-background-primary);
color: var(--color-text-primary);
font: inherit;
cursor: pointer;
}
.back:hover {
background: var(--color-background-secondary);
}
.back span {
font-size: 1.25em;
line-height: 1;
}
.crumb {
display: flex;
flex-wrap: wrap;
align-items: baseline;
gap: 0 var(--hud-space-1);
min-width: 0;
}
.sep {
color: var(--color-text-tertiary);
}
.collection {
color: var(--color-text-secondary);
font-family: var(--font-mono);
font-size: 0.92em;
overflow-wrap: anywhere;
}
.viewer {
margin-left: auto;
color: var(--color-text-secondary);
font-size: var(--font-text-xs-size);
overflow-wrap: anywhere;
}
</style>