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
// 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 };
}