~ 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
218 lines · 8.9 KB Raw History
// The workspace's shapes, read from what HUD's lexicons
// (schemas/place.hud.*) give: a canvas and a tile as the page
// draws them, out of their views and the records they hold; and how a
// canvas's tiles stand as columns on its strip.

import type * as HudDefs from './lexicons/place/hud/defs.defs.ts';

/** Someone, by DID and, where known, handle. */
export type Actor = { did: string; handle?: string };

/** Someone as the workspace says them, wherever: `@handle`, else their DID. The Handle atom draws it; a label or a sentence says it with this. */
export const handleText = (did: string, handle?: string | null) => (handle ? `@${handle.replace(/^@/, '')}` : did);

/** A canvas's member's handle, by DID, where the canvas knows it. */
export const memberHandle = (canvas: Pick<Canvas, 'members'>, did: string) => canvas.members.find((member) => member.did === did)?.handle ?? null;

/** A canvas's member as said, by DID: `@handle` where the canvas knows it. */
export const memberText = (canvas: Pick<Canvas, 'members'>, did: string) => handleText(did, memberHandle(canvas, did));

export type TileEvent = HudDefs.TileEvent;
export type PresenceEvent = HudDefs.PresenceEvent;
export type CanvasesEvent = HudDefs.CanvasesEvent;

export type Role = 'owner' | 'editor' | 'viewer';

export type Width = 'third' | 'half' | 'two-thirds' | 'full';

/** Each width, its share of the strip's visible width, and how it is said. */
export const WIDTHS: { width: Width; share: number; label: string }[] = [
	{ width: 'third', share: 1 / 3, label: '1/3' },
	{ width: 'half', share: 1 / 2, label: '1/2' },
	{ width: 'two-thirds', share: 2 / 3, label: '2/3' },
	{ width: 'full', share: 1, label: 'Full' }
];

/** The most tiles a column stacks. */
export const STACK = 3;

/** A width the server named, or a third for one this page does not know. */
export const widthOf = (width: string | undefined): (typeof WIDTHS)[number] => WIDTHS.find((w) => w.width === width) ?? WIDTHS[0];

const isObject = (value: unknown): value is Record<string, unknown> => typeof value === 'object' && value !== null && !Array.isArray(value);
const string = (value: unknown) => (typeof value === 'string' ? value : '');
const role = (value: unknown): Role => (value === 'owner' || value === 'editor' ? value : 'viewer');

/** Someone a canvas is shared with; until they accept, `pending`. */
export type Member = { did: string; handle: string | null; role: Role; pending: boolean; invitedBy: string | null };

/** A canvas as listed: its name, its owner and members, this person's role in it, who invited them while it is an invitation, and how many tiles it holds. */
export type Canvas = { id: string; name: string; owner: string; role: Role; invitedBy: string | null; members: Member[]; tiles: number; updatedAt: string };

export function canvasOf(view: HudDefs.CanvasView): Canvas {
	const record = isObject(view.record) ? view.record : {};
	return {
		id: view.key,
		name: string(record.name) || 'Untitled canvas',
		owner: view.owner,
		role: role(view.viewer?.role),
		invitedBy: view.viewer?.invitedBy ?? null,
		members: (view.members ?? []).map((member) => ({
			did: member.did,
			handle: member.handle ?? null,
			role: role(member.role),
			pending: member.pending === true,
			invitedBy: member.invitedBy ?? null
		})),
		tiles: view.tileCount ?? 0,
		updatedAt: string(record.updatedAt)
	};
}

/** A tile as the page draws it, out of its record: its tool and arguments, title, place, width, stack, who added it, and what it was opened from. */
export type Tile = {
	id: string;
	tool: string;
	arguments: Record<string, unknown>;
	title: string;
	/** A decimal number as text: compared as numbers. */
	order: string;
	width: Width;
	stack: string | null;
	by: 'person' | 'agent';
	author: string;
	from: string | null;
	/** The icon of the app whose data it shows, from HUD's /icon/<domain>; none where it names no NSID. */
	icon: string | null;
	at: string;
};

/** The arguments a record holds: as an object, or as JSON text where they hold a number a record cannot. */
function argumentsOf(record: Record<string, unknown>): Record<string, unknown> {
	if (isObject(record.arguments)) return record.arguments;
	if (typeof record.argumentsJson === 'string') {
		try {
			const parsed: unknown = JSON.parse(record.argumentsJson);
			if (isObject(parsed)) return parsed;
		} catch {
			// None to read: an empty call.
		}
	}
	return {};
}

export function tileOf(view: HudDefs.TileView): Tile {
	const record = isObject(view.record) ? view.record : {};
	return {
		id: view.key,
		tool: string(record.tool),
		arguments: argumentsOf(record),
		title: string(record.title),
		order: string(record.order) || '0',
		width: widthOf(string(record.width)).width,
		stack: string(record.stack) || null,
		by: record.by === 'agent' ? 'agent' : 'person',
		author: view.author,
		from: string(record.from) || null,
		icon: view.icon ?? null,
		at: string(record.createdAt)
	};
}

/** A launcher: a column of this page alone, right of the column `after` (a column's key), until something is picked in it. */
export type Launcher = { key: string; after: string | null };

/** What a column holds, from the top: tiles, or a launcher alone. */
export type Slot = { kind: 'tile'; key: string; tile: Tile } | { kind: 'launcher'; key: string };

/** A column: its key (its head's id, or its launcher's key), its width, and what it holds. */
export type Column = { key: string; width: Width; slots: Slot[] };

/** The strip's columns: each head in order with the tiles stacked under it
 * (a tile stacked under one not here heads its own), then each launcher
 * right of the column it was opened beside. */
export function columns(tiles: Tile[], launchers: Launcher[]): Column[] {
	const ids = new Set(tiles.map((tile) => tile.id));
	const byOrder = [...tiles].sort((a, b) => Number(a.order) - Number(b.order));
	const heads = byOrder.filter((tile) => !tile.stack || !ids.has(tile.stack));
	const found: Column[] = heads.map((head) => ({
		key: head.id,
		width: widthOf(head.width).width,
		slots: [head, ...byOrder.filter((tile) => tile.stack === head.id)].map((tile) => ({ kind: 'tile', key: tile.id, tile }))
	}));
	for (const launcher of launchers) {
		const at = launcher.after === null ? 0 : found.findIndex((column) => column.key === launcher.after) + 1 || found.length;
		found.splice(at, 0, { key: launcher.key, width: 'third', slots: [{ kind: 'launcher', key: launcher.key }] });
	}
	return found;
}

/** Whether `id` was opened from `ancestor`, at once or through other tiles of `tiles`. */
export function descends(tiles: Map<string, Tile>, id: string, ancestor: string): boolean {
	let at = tiles.get(id)?.from;
	for (let hops = 0; at && hops < 64; hops++) {
		if (at === ancestor) return true;
		at = tiles.get(at)?.from;
	}
	return false;
}

/** The tiles of the strip joined into chains, each tile its chain's colour
 * (1 to 6) and how it joins the one it was opened from: in its stack, the
 * column on its left, or further left past columns of its source's
 * descendants alone. `kept` holds each tile's colour from before, so a
 * chain keeps its colour as it grows. */
export function chains(strip: Column[], kept: Map<string, number>): { colour: Map<string, number>; link: Map<string, 'stack' | 'left' | 'run'> } {
	const tiles = new Map<string, Tile>();
	const where = new Map<string, number>();
	strip.forEach((column, at) => {
		for (const slot of column.slots) {
			if (slot.kind !== 'tile') continue;
			tiles.set(slot.key, slot.tile);
			where.set(slot.key, at);
		}
	});
	const up = new Map<string, string>([...tiles.keys()].map((id) => [id, id]));
	const find = (id: string): string => {
		const parent = up.get(id) ?? id;
		if (parent === id) return id;
		const root = find(parent);
		up.set(id, root);
		return root;
	};
	const link = new Map<string, 'stack' | 'left' | 'run'>();
	for (const [id, tile] of tiles) {
		const source = tile.from;
		const from = source ? where.get(source) : undefined;
		const at = where.get(id) ?? 0;
		if (!source || from === undefined || from > at) continue;
		const between = strip.slice(from + 1, at);
		const kind =
			from === at
				? 'stack'
				: from === at - 1
					? 'left'
					: between.every((column) => column.slots.some((slot) => slot.kind === 'tile' && descends(tiles, slot.key, source)))
						? 'run'
						: null;
		if (!kind) continue;
		up.set(find(id), find(source));
		link.set(id, kind);
	}
	const groups = new Map<string, string[]>();
	for (const id of tiles.keys()) groups.set(find(id), [...(groups.get(find(id)) ?? []), id]);
	const colour = new Map<string, number>();
	const used = new Set<number>();
	const chained = [...groups.values()].filter((ids) => ids.length > 1).sort((a, b) => b.length - a.length);
	for (const ids of chained) {
		let pick = ids.map((id) => kept.get(id)).find((c) => c !== undefined && !used.has(c));
		for (let c = 1; pick === undefined && c <= 6; c++) if (!used.has(c)) pick = c;
		pick ??= (used.size % 6) + 1;
		used.add(pick);
		for (const id of ids) {
			colour.set(id, pick);
			kept.set(id, pick);
		}
	}
	return { colour, link };
}