chadtmiller.com/hud
A remote MCP server that shows atproto records as interactive UI inside MCP Apps hosts
@hud/shell 0.5.0 Latest 5 packages
0
0
// The workspace's acceptance flows, in order, as alice and then bob use
// it: signing in, an app's page from the launcher, a thread opened beside
// its source, what a reload keeps, an agent's tile over MCP, a canvas
// shared to a viewer, and opening what is open already: written
// otherwise, or on another canvas.
import { expect, mcpCall, mcpToken, signIn, test, who, world } from './pages.mjs';
test.describe.configure({ mode: 'serial' });
/** @type {import('@playwright/test').BrowserContext} */
let context;
/** @type {import('@playwright/test').Page} */
let page;
test.beforeAll(async ({ browser }) => {
context = await browser.newContext();
page = await context.newPage();
});
test.afterAll(() => context?.close());
/** The strip on screen. */
const strip = (p = page) => p.getByRole('main', { name: 'Columns' });
/** A tile on the strip on screen, by its title. */
const tile = (title, p = page) => strip(p).getByRole('article', { name: title, exact: true });
/** A tile on the strip on screen, by its id. */
const tileById = (id, p = page) => strip(p).locator(`article[data-tile="${id}"]`);
/** The tiles' ids on the strip on screen, left to right, and each column's width. */
const columns = (p = page) =>
strip(p)
.locator('[data-column]')
.evaluateAll((all) =>
all.map((c) => ({
tiles: [...c.querySelectorAll('article[data-tile]')].map((t) => t.getAttribute('data-tile')),
width: c.querySelector('.width')?.textContent?.trim() ?? null,
})),
);
/** What HUD makes of a call, in a title: an NSID, a DID, an at-uri or a TID. */
const technical = /\b[a-z]+\.[a-z]+\.[a-z.]+\b|did:|at:\/\/|\b(?=[a-z2-7]*[2-7])[a-z2-7]{13}\b/;
/** The tiles the flows open, by id. */
let pageId = '';
let postsId = '';
/** A posts tile's link to alice's first post, as a reply of hers names it. */
const firstPost = (posts) => posts.getByRole('button', { name: world.posts[0], exact: true }).first();
const tabs = (p = page) => p.getByRole('tablist', { name: 'Canvases' }).getByRole('tab');
const launcher = (p = page) => strip(p).getByRole('region', { name: 'Open' });
/** Add a tile to a canvas as the page does, its answer. */
const addTile = (canvas, tool, args, title) =>
page.evaluate(
async (body) => {
const res = await fetch('/xrpc/place.hud.addTile', {
method: 'POST',
credentials: 'same-origin',
headers: { 'Content-Type': 'application/json', 'X-HUD': '1' },
body: JSON.stringify(body),
});
return res.json();
},
{ canvas, tool, arguments: args, title },
);
test('signing in as alice lands on the workspace, one tab and a launcher', async () => {
await signIn(page, 'alice');
await expect(tabs()).toHaveCount(1);
await expect(launcher()).toHaveCount(1);
await expect(launcher().getByText('Alice', { exact: true })).toBeVisible();
});
test('an app picked in the launcher turns its column into its page, its details a click away', async () => {
// Your apps: Bluesky, the one alice's repository holds.
await launcher().getByRole('listbox', { name: 'Your apps' }).getByRole('option', { name: 'Bluesky' }).click();
await expect(launcher()).toHaveCount(0);
const app = strip().locator('article[data-tile]');
await expect(app).toHaveCount(1);
pageId = await app.getAttribute('data-tile');
expect((await columns()).map((c) => c.tiles)).toEqual([[pageId]]);
// Where to go in it. (Bluesky's AppView knows no account of this world's: the profile and posts it draws stay empty.)
await expect(app.getByRole('button', { name: 'Open app.bsky.feed.getTimeline' })).toBeVisible();
// Its header: a title as people read it, and whose it is, never a DID; the call is in its details.
const head = app.locator(':scope > header');
await expect(head.getByRole('heading')).not.toHaveText(technical);
await expect(head).not.toContainText('did:', { useInnerText: true });
await head.locator('summary[aria-label="Details"]').click();
const details = head.locator('details[open]');
await expect(details).toContainText('"domain": "bsky.app"');
await expect(details).toContainText(who.alice.did);
await expect(details.getByRole('button', { name: 'Copy call' })).toBeVisible();
await page.keyboard.press('Escape');
await expect(details).toHaveCount(0);
});
test('a thread opened from a posts tile lands right of its source', async () => {
// Alice's posts as her repository holds them, a column of their own, moved left of Bluesky's page. The launcher offers her posts as Bluesky's AppView has them, which knows no account of this world's, and never a collection: they are put on the canvas by their call, as the page does.
const canvas = await tabs().first().getAttribute('data-tab');
const added = await addTile(canvas, 'list_records', { actor: who.alice.did, collection: 'app.bsky.feed.post' });
postsId = added.tile.key;
const posts = tileById(postsId);
await expect(posts.getByText('Hello from the harness')).toBeVisible();
await posts.locator(':scope > header').getByRole('heading').click();
await expect(posts).toHaveClass(/\bfocused\b/);
await page.keyboard.press('Shift+ArrowLeft');
await expect.poll(async () => (await columns()).map((c) => c.tiles[0])).toEqual([postsId, pageId]);
await firstPost(posts).click();
await expect.poll(async () => (await columns()).length).toBe(3);
const [, thread] = await columns();
expect(thread.tiles).toHaveLength(1);
const opened = tileById(thread.tiles[0]);
await expect(opened.locator(':scope > header').getByRole('heading')).not.toHaveText(technical);
// It says where it came from by its source's title (its name begins with the "·" drawn before it).
await expect(opened.getByRole('button', { name: new RegExp(`from ${await posts.getAttribute('aria-label')}$`) })).toBeVisible();
expect((await columns()).map((c) => c.tiles[0])).toEqual([postsId, thread.tiles[0], pageId]);
});
test('a reload keeps the columns’ order and widths, and the open tabs', async () => {
const posts = tileById(postsId);
const width = posts.getByRole('button', { name: /^Width / });
const before = await width.textContent();
const saved = page.waitForResponse((r) => r.url().endsWith('/xrpc/place.hud.setTileWidth'));
// Its controls show on hover.
await posts.hover();
await width.click();
await expect(width).not.toHaveText(before);
expect((await saved).ok()).toBe(true);
const kept = await columns();
const open = await tabs().evaluateAll((all) => all.map((t) => t.dataset.tab));
await page.reload();
await expect(tileById(postsId)).toBeVisible();
await expect.poll(() => columns()).toEqual(kept);
expect(await tabs().evaluateAll((all) => all.map((t) => t.dataset.tab))).toEqual(open);
});
test('opening a tile that is open already brings its column into view, adding none', async () => {
const size = page.viewportSize();
// A phone's width: one column in view at a time.
await page.setViewportSize({ width: 420, height: 800 });
try {
const before = await columns();
const [, thread] = before;
const opened = tileById(thread.tiles[0]);
const posts = tileById(postsId);
await strip().evaluate((main) => {
const box = [main, ...main.querySelectorAll('*')].find((e) => e.scrollWidth > e.clientWidth + 1 && getComputedStyle(e).overflowX !== 'visible');
box?.scrollTo({ left: 0, behavior: 'instant' });
});
await expect(posts).toBeInViewport({ ratio: 0.9 });
await expect(opened).not.toBeInViewport({ ratio: 0.5 });
await firstPost(posts).click();
await expect(opened).toBeInViewport({ ratio: 0.9 });
expect(await columns()).toEqual(before);
} finally {
if (size) await page.setViewportSize(size);
}
});
/** The canvas the agent adds to, and then alice shares. */
let board = '';
test('a tile an agent adds over MCP to a second canvas badges its tab ✦ 1', async () => {
await page.getByRole('banner').locator('summary[aria-label="Canvases"]').click();
await page.getByRole('menuitem', { name: /New canvas/ }).click();
await expect(tabs()).toHaveCount(2);
// A new canvas opens with its name field focused, ready to type.
const name = tabs().nth(1).getByRole('textbox', { name: 'Canvas name' });
await expect(name).toBeFocused();
await name.fill('Agent board');
await name.press('Enter');
const tab = tabs().filter({ hasText: 'Agent board' });
await expect(tab).toHaveAttribute('aria-selected', 'true');
board = await tab.getAttribute('data-tab');
// Back on the first canvas: the second's tab is out of sight.
await tabs().first().click();
await expect(tabs().first()).toHaveAttribute('aria-selected', 'true');
const token = await mcpToken(context, 'alice');
const result = await mcpCall(token, 'canvas_add', {
canvas: board,
tool: 'get_record',
arguments: { uri: world.posts[0] },
title: 'The first post',
});
expect(result.isError ?? false, JSON.stringify(result)).toBe(false);
await expect(tab.locator('.agent')).toHaveText('1');
await expect(tab.locator('.agent')).toHaveAttribute('title', 'An agent added 1 tile');
});
test('shared with bob as a viewer: he accepts, alice sees him there, and he cannot add', async ({ browser }) => {
await tabs().filter({ hasText: 'Agent board' }).click();
await expect(tile('The first post')).toBeVisible();
await page.getByRole('button', { name: 'Share' }).click();
const dialog = page.getByRole('dialog', { name: /Agent board/ });
await dialog.getByLabel('Handle to invite').fill(who.bob.did);
await dialog.getByLabel('Role', { exact: true }).selectOption('viewer');
await dialog.getByRole('button', { name: 'Invite' }).click();
await expect(dialog.getByText('Invited, not yet joined')).toBeVisible();
await expect(dialog.getByLabel(/^Role of /).last()).toHaveValue('viewer');
await dialog.getByRole('button', { name: 'Done' }).click();
const bobs = await browser.newContext();
try {
const bob = await bobs.newPage();
await signIn(bob, 'bob');
await bob.getByRole('banner').locator('summary[aria-label="Canvases"]').click();
await expect(bob.getByText(/invited you to “Agent board” · can view/)).toBeVisible();
await bob.getByRole('button', { name: 'Accept' }).click();
const shared = tabs(bob).filter({ hasText: 'Agent board' });
await expect(shared).toHaveAttribute('aria-selected', 'true');
await expect(tile('The first post', bob)).toBeVisible();
// Alice sees bob on the canvas: his face on its tab.
await expect(tabs().filter({ hasText: 'Agent board' }).getByRole('img', { name: `Here now: @${who.bob.handle}` })).toBeVisible();
// Read-only for bob: nothing on the page changes the canvas.
await expect(strip(bob).getByRole('button', { name: 'New tile' })).toHaveCount(0);
await expect(tile('The first post', bob).getByRole('button', { name: 'Close' })).toHaveCount(0);
await expect(tile('The first post', bob).getByRole('button', { name: /^Width / })).toHaveCount(0);
// And the server refuses his adds.
const refused = await bob.evaluate(
async ({ canvas, uri }) => {
const res = await fetch('/xrpc/place.hud.addTile', {
method: 'POST',
credentials: 'same-origin',
headers: { 'Content-Type': 'application/json', 'X-HUD': '1' },
body: JSON.stringify({ canvas, tool: 'get_record', arguments: { uri } }),
});
return { status: res.status, body: await res.json().catch(() => null) };
},
{ canvas: board, uri: world.posts[1] },
);
expect(refused.status, JSON.stringify(refused.body)).toBe(403);
} finally {
await bobs.close();
}
});
test('a new canvas’s name is typed in its tab straight away', async () => {
await page.getByRole('banner').locator('summary[aria-label="Canvases"]').click();
await page.getByRole('menuitem', { name: /New canvas/ }).click();
// The + menu's New canvas opens its tab's name field, focused, to type into.
const name = page.getByRole('tablist', { name: 'Canvases' }).getByRole('textbox', { name: 'Canvas name' });
await expect(name).toBeFocused();
await page.keyboard.type('Typed at once');
await page.keyboard.press('Enter');
await expect(tabs().filter({ hasText: 'Typed at once' })).toHaveAttribute('aria-selected', 'true');
});
/** A tile whose one link names alice as `href`: by handle or by DID. */
const linkTo = (href, label) => ({
uri: `at://${who.alice.did}/app.bsky.actor.profile/self`,
view: {
$type: 'place.hud.view',
collection: 'app.bsky.actor.profile',
description: 'A link to alice',
record: { layout: { component: 'Link', props: { href, label } } },
},
});
test('a link naming by handle what a tile shows by DID brings that tile into view, adding none', async () => {
await tabs().first().click();
await expect(tabs().first()).toHaveAttribute('aria-selected', 'true');
const canvas = await tabs().first().getAttribute('data-tab');
const profile = await addTile(canvas, 'describe_repo', { actor: who.alice.did }, 'Alice by DID');
expect(profile.existing).toBeUndefined();
await addTile(canvas, 'get_record', linkTo(who.alice.handle, 'Alice by handle'), 'Handle link');
// Gone to on the strip's map: a column far from view draws nothing.
await page.getByRole('navigation', { name: 'Strip map' }).getByRole('button', { name: 'Handle link' }).click();
const link = tile('Handle link').getByRole('button', { name: 'Alice by handle' });
await expect(link).toBeVisible();
await expect(tileById(profile.tile.key)).not.toHaveClass(/\bfocused\b/);
const before = await columns();
const asked = page.waitForResponse((r) => r.url().endsWith('/xrpc/place.hud.addTile'));
await link.click();
expect(await (await asked).json()).toMatchObject({ existing: true, tile: { key: profile.tile.key } });
await expect(tileById(profile.tile.key)).toBeInViewport({ ratio: 0.5 });
await expect(tileById(profile.tile.key)).toHaveClass(/\bfocused\b/);
expect(await columns()).toEqual(before);
});
test('opening on a new canvas what another canvas shows adds it here, and stays here', async () => {
const first = await tabs().first().getAttribute('data-tab');
const count = async (canvas) =>
(await page.evaluate(async (c) => (await fetch(`/xrpc/place.hud.getCanvas?canvas=${c}`)).json(), canvas)).tiles.length;
const onFirst = await count(first);
// A canvas of its own, a link to alice's profile, which the first canvas shows ('Alice by DID').
await page.getByRole('banner').locator('summary[aria-label="Canvases"]').click();
await page.getByRole('menuitem', { name: /New canvas/ }).click();
const name = page.getByRole('tablist', { name: 'Canvases' }).getByRole('textbox', { name: 'Canvas name' });
await expect(name).toBeFocused();
await page.keyboard.type('Elsewhere');
await page.keyboard.press('Enter');
const here = tabs().filter({ hasText: 'Elsewhere' });
await expect(here).toHaveAttribute('aria-selected', 'true');
const canvas = await here.getAttribute('data-tab');
await addTile(canvas, 'get_record', linkTo(who.alice.did, 'Alice by DID link'), 'DID link');
const link = tile('DID link').getByRole('button', { name: 'Alice by DID link' });
await expect(link).toBeVisible();
await link.click();
await expect.poll(() => count(canvas)).toBe(2);
await expect(here).toHaveAttribute('aria-selected', 'true');
await expect(strip().locator('article[data-tile]')).toHaveCount(2);
expect(await count(first)).toBe(onFirst);
});