~ 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
451 lines · 16.0 KB Raw History
<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>