Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

10.6 KB
Raw Blame
// Pure rules for the desktop widgets: the catalog, the desktop grid and its
// first-fit placement, stored-layout validation, number and time formatting,
// sparkline geometry, weather codes and the month grid. No DOM, unit tested in
// tests/desktop-widgets.test.js.

/** Pixel size of one grid unit and the gap between widgets. */
export const UNIT = 168;
export const GAP = 14;
export const STEP = UNIT + GAP;

/** Widget sizes in grid units. */
export const SIZES = {
	s: { w: 1, h: 1, label: 'Small' },
	m: { w: 2, h: 1, label: 'Medium' },
	l: { w: 2, h: 2, label: 'Large' },
};

/**
 * Every widget a visitor can add. `sizes` lists the sizes the widget renders
 * well at, the first being its default. `feeds` names the live sources it reads
 * (see data.js), so the board can say where the numbers come from.
 */
export const CATALOG = [
	{ type: 'three', title: '$THREE', desc: 'Live price, 24h change and a 24 hour chart', sizes: ['m', 's', 'l'], feeds: ['token', 'history'], app: 'trenches' },
	{ type: 'weather', title: 'Weather', desc: 'Current conditions and the next hours where you are', sizes: ['m', 's', 'l'], feeds: ['weather'], app: 'weather' },
	{ type: 'clock', title: 'Clock', desc: 'Analog clock with your local time and date', sizes: ['s', 'm'], feeds: [], app: 'clock' },
	{ type: 'calendar', title: 'Calendar', desc: 'This month at a glance', sizes: ['l', 'm'], feeds: [] },
	{ type: 'agents', title: 'New agents', desc: 'The newest agents on three.ws', sizes: ['m', 'l'], feeds: ['agents'], app: 'discover' },
	{ type: 'pulse', title: 'Pulse', desc: 'Live wallet moves by agents', sizes: ['l', 'm'], feeds: ['pulse'], app: 'pulse' },
	{ type: 'launches', title: 'Launches', desc: 'Coins agents launched through three.ws', sizes: ['l', 'm'], feeds: ['launches'], app: 'launcher' },
	{ type: 'platform', title: 'Platform', desc: 'Agents, launches and strategies right now', sizes: ['m', 's'], feeds: ['stats'] },
	{ type: 'news', title: 'Headlines', desc: 'Top crypto headlines from the three.ws news desk', sizes: ['l', 'm'], feeds: ['news'], app: 'page:/markets/news' },
	{ type: 'system', title: 'System', desc: 'Battery, network, memory and storage of this device', sizes: ['m', 's'], feeds: [] },
	{ type: 'note', title: 'Sticky note', desc: 'A note that stays on your desktop', sizes: ['s', 'm', 'l'], feeds: [] },
];

export const catalogItem = (type) => CATALOG.find((c) => c.type === type) || null;

/** The widgets a fresh desktop starts with. */
export const DEFAULT_LAYOUT = [
	{ type: 'three', size: 'm' },
	{ type: 'weather', size: 'm' },
	{ type: 'clock', size: 's' },
	{ type: 'platform', size: 's' },
	{ type: 'pulse', size: 'l' },
];

/** How many grid columns and rows fit a work area of the given pixel size. */
export function gridFor(width, height) {
	return {
		cols: Math.max(0, Math.floor((width + GAP) / STEP)),
		rows: Math.max(0, Math.floor((height + GAP) / STEP)),
	};
}

const sizeOf = (w) => SIZES[w.size] || SIZES.s;
const hits = (a, b) => a.col < b.col + b.w && b.col < a.col + a.w && a.row < b.row + b.h && b.row < a.row + a.h;
const box = (w) => ({ col: w.col, row: w.row, ...sizeOf(w) });

/** True when a widget at (col,row) fits the grid and overlaps none of `others`. */
export function fits(widget, col, row, others, grid) {
	const s = sizeOf(widget);
	if (col < 0 || row < 0 || col + s.w > grid.cols || row + s.h > grid.rows) return false;
	const me = { col, row, w: s.w, h: s.h };
	return !others.some((o) => o.id !== widget.id && hits(me, box(o)));
}

/**
 * First free cell for `widget`. Columns count from the right edge of the work
 * area (column 0 is rightmost) so widgets fill in from the right and leave the
 * desktop icons on the left alone. Scans column by column, top to bottom.
 * Returns null when the grid is full.
 */
export function firstFit(widget, others, grid) {
	for (let col = 0; col < grid.cols; col++) {
		for (let row = 0; row < grid.rows; row++) if (fits(widget, col, row, others, grid)) return { col, row };
	}
	return null;
}

/**
 * Validate a stored layout: drop unknown types and bad sizes, give every widget
 * an id, and re-place anything that no longer fits (a smaller window, a moved
 * neighbour). Widgets that cannot fit at all are kept with `hidden: true` so
 * they come back when there is room again.
 */
export function settle(raw, grid) {
	const list = Array.isArray(raw) ? raw : [];
	const out = [];
	let n = 0;
	for (const r of list) {
		if (!r || typeof r !== 'object') continue;
		const item = catalogItem(r.type);
		if (!item) continue;
		const size = item.sizes.includes(r.size) ? r.size : item.sizes[0];
		const id = typeof r.id === 'string' && /^[\w-]{1,40}$/.test(r.id) && !out.some((o) => o.id === r.id) ? r.id : `w${Date.now().toString(36)}${n++}`;
		const w = { id, type: r.type, size, col: Number.isInteger(r.col) ? r.col : -1, row: Number.isInteger(r.row) ? r.row : -1 };
		if (r.data && typeof r.data === 'object') w.data = r.data;
		const placed = out.filter((o) => !o.hidden);
		if (!fits(w, w.col, w.row, placed, grid)) {
			const at = firstFit(w, placed, grid);
			if (at) Object.assign(w, at);
			else w.hidden = true;
		}
		out.push(w);
	}
	return out;
}

/** Nearest grid cell to a pixel offset measured from the top-right of the work area. */
export function cellAt(dxFromRight, dyFromTop) {
	return { col: Math.max(0, Math.round(dxFromRight / STEP)), row: Math.max(0, Math.round(dyFromTop / STEP)) };
}

/** Pixel box of a widget, `right`/`top` offsets from the work area's top-right. */
export function pixelBox(w) {
	const s = sizeOf(w);
	return { right: w.col * STEP, top: w.row * STEP, width: s.w * UNIT + (s.w - 1) * GAP, height: s.h * UNIT + (s.h - 1) * GAP };
}

// ---------- formatting ----------

/** USD price with enough significant digits for sub-cent tokens. */
export function fmtPrice(v) {
	const n = Number(v);
	if (!Number.isFinite(n) || n < 0) return '';
	if (n === 0) return '$0.00';
	if (n >= 1) return `$${n.toLocaleString('en-US', { minimumFractionDigits: 2, maximumFractionDigits: 2 })}`;
	const digits = Math.min(10, Math.max(2, 2 - Math.floor(Math.log10(n))));
	return `$${n.toFixed(digits)}`;
}

/** 1234 -> 1.2K, 502446 -> 502K, 1.5e6 -> 1.5M. */
export function fmtCompact(v, prefix = '') {
	const n = Number(v);
	if (!Number.isFinite(n)) return '';
	const abs = Math.abs(n);
	const unit = abs >= 1e9 ? [1e9, 'B'] : abs >= 1e6 ? [1e6, 'M'] : abs >= 1e3 ? [1e3, 'K'] : [1, ''];
	const x = n / unit[0];
	const s = unit[0] === 1 ? String(Math.round(x)) : x.toFixed(Math.abs(x) >= 100 ? 0 : 1).replace(/\.0$/, '');
	return `${prefix}${s}${unit[1]}`;
}

/** Signed percent: +3.2%, -0.4%, 0.0%. */
export function fmtPct(v) {
	if (v == null || v === '') return '';
	const n = Number(v);
	if (!Number.isFinite(n)) return '';
	return `${n > 0 ? '+' : ''}${n.toFixed(Math.abs(n) >= 100 ? 0 : 1)}%`;
}

/** Compact age: now, 4m, 3h, 2d. */
export function relTime(ts, now = Date.now()) {
	const t = typeof ts === 'number' ? ts : Date.parse(ts);
	if (!Number.isFinite(t)) return '';
	const s = Math.max(0, (now - t) / 1000);
	if (s < 45) return 'now';
	if (s < 3600) return `${Math.round(s / 60)}m`;
	if (s < 86400) return `${Math.round(s / 3600)}h`;
	return `${Math.round(s / 86400)}d`;
}

/**
 * SVG path data for a sparkline through `values`, fitted to w x h with a small
 * vertical pad. Returns { line, area } ('' when there are fewer than 2 points).
 */
export function sparkPath(values, w, h, pad = 2) {
	const v = (values || []).map(Number).filter(Number.isFinite);
	if (v.length < 2) return { line: '', area: '' };
	const lo = Math.min(...v);
	const hi = Math.max(...v);
	const span = hi - lo || 1;
	const pts = v.map((x, i) => [(i / (v.length - 1)) * w, pad + (1 - (x - lo) / span) * (h - pad * 2)]);
	const line = pts.map(([x, y], i) => `${i ? 'L' : 'M'}${x.toFixed(1)} ${y.toFixed(1)}`).join('');
	return { line, area: `${line}L${w} ${h}L0 ${h}Z` };
}

// ---------- weather ----------

const WMO = [
	[[0], 'Clear', 'sun'],
	[[1], 'Mostly clear', 'sun'],
	[[2], 'Partly cloudy', 'partly'],
	[[3], 'Overcast', 'cloud'],
	[[45, 48], 'Fog', 'fog'],
	[[51, 53, 55, 56, 57], 'Drizzle', 'rain'],
	[[61, 63, 66, 80, 81], 'Rain', 'rain'],
	[[65, 67, 82], 'Heavy rain', 'rain'],
	[[71, 73, 75, 77, 85, 86], 'Snow', 'snow'],
	[[95, 96, 99], 'Thunderstorm', 'storm'],
];

/** Open-Meteo WMO weather code to a label and an icon key. Night swaps sun for moon. */
export function weatherInfo(code, isDay = true) {
	const hit = WMO.find(([codes]) => codes.includes(Number(code)));
	const [, label, icon] = hit || [null, 'Unknown', 'cloud'];
	return { label, icon: !isDay && icon === 'sun' ? 'moon' : !isDay && icon === 'partly' ? 'partly-night' : icon };
}

/** A readable city from an IANA time zone: "America/New_York" -> "New York". */
export function tzCity(tz) {
	const last = String(tz || '').split('/').pop() || '';
	if (!last || /^(UTC|GMT|Etc)/i.test(last) || /[+-]\d/.test(last)) return '';
	return last.replace(/_/g, ' ');
}

/** Fahrenheit for the few regions that use it, Celsius everywhere else. */
export function usesFahrenheit(locale) {
	return /-(US|LR|MM|BS|BZ|KY|PW)\b/i.test(String(locale || ''));
}

// ---------- calendar ----------

/**
 * The 6x7 day grid for the month containing `date`, weeks starting on
 * `weekStart` (0 Sunday, 1 Monday). Each cell: { y, m, d, inMonth, today }.
 */
export function monthGrid(date, weekStart = 0, today = new Date()) {
	const first = new Date(date.getFullYear(), date.getMonth(), 1);
	const lead = (first.getDay() - weekStart + 7) % 7;
	const start = new Date(first.getFullYear(), first.getMonth(), 1 - lead);
	const cells = [];
	for (let i = 0; i < 42; i++) {
		const d = new Date(start.getFullYear(), start.getMonth(), start.getDate() + i);
		cells.push({
			y: d.getFullYear(),
			m: d.getMonth(),
			d: d.getDate(),
			inMonth: d.getMonth() === first.getMonth(),
			today: d.getFullYear() === today.getFullYear() && d.getMonth() === today.getMonth() && d.getDate() === today.getDate(),
		});
	}
	return cells;
}

/** First day of the week for a locale (1 Monday for most of the world, 0 Sunday for a few). */
export function weekStartFor(locale) {
	try {
		const info = new Intl.Locale(locale);
		const wi = info.getWeekInfo?.() || info.weekInfo;
		if (wi && Number.isInteger(wi.firstDay)) return wi.firstDay % 7;
	} catch {
		/* older engines */
	}
	return /-(US|CA|JP|BR|IL|PH|MX|KR|TW|IN|ZA|SA|AU)\b/i.test(String(locale || '')) ? 0 : 1;
}

// ---------- system ----------

/** "1.2 GB" style byte formatting. */
export function fmtBytes(b) {
	const n = Number(b);
	if (!Number.isFinite(n) || n < 0) return '';
	const u = ['B', 'KB', 'MB', 'GB', 'TB'];
	let i = 0;
	let x = n;
	while (x >= 1024 && i < u.length - 1) {
		x /= 1024;
		i++;
	}
	return `${x.toFixed(x >= 10 || i === 0 ? 0 : 1)} ${u[i]}`;
}