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.

18.5 KB
Raw Blame
// Pure geometry, search and persistence helpers for the three.ws desktop shell.
// No DOM access here so every rule can be unit-tested (tests/desktop-layout.test.js).

export const MIN_W = 320;
export const MIN_H = 220;
export const SNAP_EDGE = 10;
export const MAX_WINDOWS = 8;
export const STATE_VERSION = 1;

/** The usable region for windows: below the menu bar, above the dock. */
export function workArea(vw, vh, menuH, dockH) {
	return { x: 0, y: menuH, w: vw, h: Math.max(MIN_H, vh - menuH - dockH) };
}

/** Keep a window reachable: its title bar must stay inside the work area. */
export function clampRect(rect, area) {
	const w = Math.min(Math.max(rect.w, MIN_W), area.w);
	const h = Math.min(Math.max(rect.h, MIN_H), area.h);
	const grab = 96;
	const x = Math.min(Math.max(rect.x, area.x - w + grab), area.x + area.w - grab);
	const y = Math.min(Math.max(rect.y, area.y), area.y + area.h - 36);
	return { x: Math.round(x), y: Math.round(y), w: Math.round(w), h: Math.round(h) };
}

/** How far from a corner (along either edge) a drag snaps to a quarter instead of a half. */
export const SNAP_CORNER = 96;

/** Which snap zone, if any, the pointer is in while dragging a window. */
export function snapZone(px, py, area) {
	const atL = px <= area.x + SNAP_EDGE;
	const atR = px >= area.x + area.w - SNAP_EDGE;
	const atT = py <= area.y + SNAP_EDGE;
	const nearT = py <= area.y + SNAP_CORNER;
	const nearB = py >= area.y + area.h - SNAP_CORNER;
	const nearL = px <= area.x + SNAP_CORNER;
	const nearR = px >= area.x + area.w - SNAP_CORNER;
	if (atL && nearT) return 'tl';
	if (atL && nearB) return 'bl';
	if (atR && nearT) return 'tr';
	if (atR && nearB) return 'br';
	if (atT && nearL) return 'tl';
	if (atT && nearR) return 'tr';
	if (atT) return 'max';
	if (atL) return 'left';
	if (atR) return 'right';
	return null;
}

/** Edge and corner snap targets as fractions of the work area: [x, y, w, h]. */
const SNAP_FRACTIONS = {
	max: [0, 0, 1, 1],
	left: [0, 0, 0.5, 1],
	right: [0.5, 0, 0.5, 1],
	tl: [0, 0, 0.5, 0.5],
	tr: [0.5, 0, 0.5, 0.5],
	bl: [0, 0.5, 0.5, 0.5],
	br: [0.5, 0.5, 0.5, 0.5],
};

export function snapRect(zone, area) {
	const f = SNAP_FRACTIONS[zone];
	return f ? fractionRect(f, area) : null;
}

/**
 * A fractional [x, y, w, h] cell resolved to pixels. Both edges are rounded
 * from the area origin, so neighbouring cells share an edge exactly and a
 * layout always tiles the work area with no gap or overlap.
 */
export function fractionRect([fx, fy, fw, fh], area) {
	const x0 = Math.round(area.x + fx * area.w);
	const y0 = Math.round(area.y + fy * area.h);
	const x1 = Math.round(area.x + (fx + fw) * area.w);
	const y1 = Math.round(area.y + (fy + fh) * area.h);
	return { x: x0, y: y0, w: x1 - x0, h: y1 - y0 };
}

/**
 * The Snap layouts flyout (hover the maximize button). Each layout is a set of
 * zones; picking a zone places the window there and offers the other open
 * windows for the zones that are left (Snap assist).
 */
export const SNAP_LAYOUTS = [
	{ id: 'halves', label: 'Two columns', zones: [[0, 0, 0.5, 1], [0.5, 0, 0.5, 1]] },
	{ id: 'wide-left', label: 'Wide and narrow', zones: [[0, 0, 2 / 3, 1], [2 / 3, 0, 1 / 3, 1]] },
	{ id: 'thirds', label: 'Three columns', zones: [[0, 0, 1 / 3, 1], [1 / 3, 0, 1 / 3, 1], [2 / 3, 0, 1 / 3, 1]] },
	{ id: 'main-stack', label: 'Main and stack', zones: [[0, 0, 0.5, 1], [0.5, 0, 0.5, 0.5], [0.5, 0.5, 0.5, 0.5]] },
	{ id: 'quarters', label: 'Four quarters', zones: [[0, 0, 0.5, 0.5], [0.5, 0, 0.5, 0.5], [0, 0.5, 0.5, 0.5], [0.5, 0.5, 0.5, 0.5]] },
	{ id: 'focus', label: 'Centre focus', zones: [[0, 0, 0.25, 1], [0.25, 0, 0.5, 1], [0.75, 0, 0.25, 1]] },
];

/** Pixel rect for zone `zone` of layout `layoutId`, or null if either is unknown. */
export function layoutZoneRect(layoutId, zone, area) {
	const l = SNAP_LAYOUTS.find((x) => x.id === layoutId);
	const f = l?.zones[zone];
	return f ? fractionRect(f, area) : null;
}

/** Layouts that need more width than the screen has are not offered. */
export function snapLayoutsFor(area) {
	return SNAP_LAYOUTS.filter((l) => l.zones.every(([, , fw]) => fw * area.w >= MIN_W));
}

/**
 * Dock magnification: the scale of an item whose centre is `dist` px from the
 * pointer. A cosine falloff gives the smooth bulge of a real dock (peak `max`
 * at the pointer, 1 at `range` and beyond). Mirrors the curve the macOS web
 * recreations use, without a spring library.
 */
export function dockScale(dist, max = 1.6, range = 150) {
	const d = Math.abs(dist);
	if (!Number.isFinite(d) || d >= range) return 1;
	return 1 + (max - 1) * (Math.cos((Math.PI * d) / range) + 1) / 2;
}

/** Staggered placement for the nth open window so new ones never sit exactly on top. */
export function cascadeRect(n, area, want) {
	const w = Math.min(want.w, area.w - 24);
	const h = Math.min(want.h, area.h - 24);
	const step = 28;
	const slots = Math.max(1, Math.floor(Math.min(area.w - w, area.h - h) / step));
	const k = n % slots;
	const x = area.x + Math.max(12, Math.floor((area.w - w) / 2) - Math.floor((slots * step) / 4)) + k * step;
	const y = area.y + 14 + k * step;
	return clampRect({ x, y, w, h }, area);
}

/** Apply a pointer delta to a rect for one of the eight resize handles. */
export function resizeRect(start, handle, dx, dy, area) {
	let { x, y, w, h } = start;
	if (handle.includes('e')) w = start.w + dx;
	if (handle.includes('s')) h = start.h + dy;
	if (handle.includes('w')) {
		w = start.w - dx;
		x = start.x + dx;
	}
	if (handle.includes('n')) {
		h = start.h - dy;
		y = start.y + dy;
	}
	if (w < MIN_W) {
		if (handle.includes('w')) x -= MIN_W - w;
		w = MIN_W;
	}
	if (h < MIN_H) {
		if (handle.includes('n')) y -= MIN_H - h;
		h = MIN_H;
	}
	if (y < area.y) {
		if (handle.includes('n')) h -= area.y - y;
		y = area.y;
	}
	return { x: Math.round(x), y: Math.round(y), w: Math.round(w), h: Math.round(h) };
}

/** A path is framable as a window only when it is a same-origin absolute path. */
export function isInternalPath(href) {
	return typeof href === 'string' && /^\/(?!\/)/.test(href) && !/[\u0000-\u001f\\]/.test(href);
}

/** Strip the site suffix pages put in <title> so a window title stays short. */
export function cleanTitle(raw, fallback) {
	const t = String(raw || '')
		.replace(/\s*[·|\u2013\u2014-]\s*three\.ws.*$/i, '')
		.replace(/^three\.ws\s*[·|\u2013\u2014-]\s*/i, '')
		.trim();
	return t || fallback;
}

/**
 * Rank launchable items for a query. Title prefix beats word prefix beats
 * keyword beats substring beats description. Empty query keeps input order.
 */
export function rankItems(query, items) {
	const q = String(query || '').trim().toLowerCase();
	if (!q) return items.slice();
	const scored = [];
	items.forEach((it, i) => {
		const title = String(it.title || '').toLowerCase();
		const kw = (it.keywords || []).map((k) => String(k).toLowerCase());
		const desc = String(it.desc || '').toLowerCase();
		let s = 0;
		if (title === q) s = 100;
		else if (title.startsWith(q)) s = 80;
		else if (title.split(/[\s/\-_.]+/).some((w) => w.startsWith(q))) s = 60;
		else if (kw.some((k) => k.startsWith(q))) s = 50;
		else if (title.includes(q)) s = 40;
		else if (kw.some((k) => k.includes(q))) s = 30;
		else if (desc.includes(q)) s = 10;
		if (s) scored.push({ it, s, i });
	});
	scored.sort((a, b) => b.s - a.s || a.i - b.i);
	return scored.map((r) => r.it);
}

/** `?app=forge` (or `#app=forge`) opens that app on load. */
export function deepLinkApp(search, hash) {
	const fromQuery = new URLSearchParams(search || '').get('app');
	if (fromQuery) return fromQuery.toLowerCase();
	const m = /^#app=([a-z0-9-]+)$/i.exec(hash || '');
	return m ? m[1].toLowerCase() : null;
}

const num = (v) => typeof v === 'number' && Number.isFinite(v);

/**
 * Validate persisted desktop state. Anything malformed, from an older version
 * or naming an unknown app is dropped, so a corrupt blob can never brick boot.
 */
export const PAGE_PREFIX = 'page:';

/** Any same-origin page can be launched as a window; its id carries its path. */
export function pageAppId(path) {
	return `${PAGE_PREFIX}${path}`;
}

export function pagePathOf(id) {
	if (typeof id !== 'string' || !id.startsWith(PAGE_PREFIX)) return null;
	const p = id.slice(PAGE_PREFIX.length);
	return isInternalPath(p) ? p : null;
}

export function sanitizeState(raw, knownIds) {
	const empty = { windows: [], focus: null };
	let data = raw;
	if (typeof raw === 'string') {
		try {
			data = JSON.parse(raw);
		} catch {
			return empty;
		}
	}
	if (!data || data.v !== STATE_VERSION || !Array.isArray(data.windows)) return empty;
	const seen = new Set();
	const windows = [];
	for (const w of data.windows) {
		if (!w || typeof w.app !== 'string' || !(knownIds.has(w.app) || pagePathOf(w.app)) || seen.has(w.app)) continue;
		if (![w.x, w.y, w.w, w.h].every(num)) continue;
		seen.add(w.app);
		windows.push({
			app: w.app,
			x: w.x,
			y: w.y,
			w: w.w,
			h: w.h,
			max: w.max === true,
			min: w.min === true,
			path: isInternalPath(w.path) ? w.path : null,
		});
		if (windows.length >= MAX_WINDOWS) break;
	}
	const focus = typeof data.focus === 'string' && seen.has(data.focus) ? data.focus : null;
	return { windows, focus };
}

// ---------------------------------------------------------------------------
// Desktop icon grid, rubber-band selection and preferences
// ---------------------------------------------------------------------------

export const ICON_SIZES = {
	small: { w: 76, h: 84, tile: 36 },
	medium: { w: 92, h: 100, tile: 44 },
	large: { w: 112, h: 120, tile: 56 },
};
export const ACCENTS = ['#8b5cf6', '#3b91d8', '#ad6eca', '#e5484d', '#f08a24', '#2fb67c', '#d6409f'];
/** How the visitor arrives at `/`: as an avatar walking to the desk, or straight at the desktop. */
export const START_MODES = ['world', 'desktop'];
export const MODES = ['dark', 'light', 'auto'];
/**
 * Desktop styles, each a whole shell skin: Fluent is the Windows 11
 * Mica shell, Aqua puts a menu bar on top and a magnifying dock at the bottom
 * with traffic-light window controls, Classic is bevelled 9x chrome with a
 * labelled taskbar. `menuH` and `dockH` are the bars the work area avoids.
 */
export const STYLES = {
	// Fluent's taskbar is a floating island: 48px tall with a 7px margin all round.
	fluent: { label: 'Fluent', menuH: 0, dockH: 62 },
	aqua: { label: 'Aqua', menuH: 28, dockH: 84 },
	classic: { label: 'Classic', menuH: 0, dockH: 40 },
};
export const PREFS_VERSION = 1;
export const DEFAULT_PREFS = {
	wall: 'bubbles',
	accent: ACCENTS[0],
	mode: 'dark',
	iconSize: 'medium',
	clock24: false,
	taskbarAlign: 'center',
	name: '',
	avatarHue: 262,
	startIn: 'world',
	sound: true,
	style: 'fluent',
	brightness: 100,
	volume: 70,
	nightLight: false,
	dnd: false,
	saver: false,
};

const pct = (v, lo, fallback) => (Number.isFinite(v) ? Math.round(Math.min(100, Math.max(lo, v))) : fallback);

/** Normalise a rectangle given two corner points (any drag direction). */
export function marqueeRect(ax, ay, bx, by) {
	return { x: Math.min(ax, bx), y: Math.min(ay, by), w: Math.abs(ax - bx), h: Math.abs(ay - by) };
}

export function rectsIntersect(a, b) {
	return a.x < b.x + b.w && a.x + a.w > b.x && a.y < b.y + b.h && a.y + a.h > b.y;
}

/** Ids of every icon whose cell overlaps the marquee. */
export function iconsInRect(rect, items, cell, origin = { x: 0, y: 0 }) {
	return items
		.filter((it) =>
			rectsIntersect(rect, { x: origin.x + it.col * cell.w, y: origin.y + it.row * cell.h, w: cell.w, h: cell.h }),
		)
		.map((it) => it.id);
}

/** Grid dimensions that fit a desktop area (always at least 1x1). */
export function gridSize(areaW, areaH, cell) {
	return { cols: Math.max(1, Math.floor(areaW / cell.w)), rows: Math.max(1, Math.floor(areaH / cell.h)) };
}

export function cellAt(px, py, cell, grid, origin = { x: 0, y: 0 }) {
	const col = Math.min(grid.cols - 1, Math.max(0, Math.floor((px - origin.x) / cell.w)));
	const row = Math.min(grid.rows - 1, Math.max(0, Math.floor((py - origin.y) / cell.h)));
	return { col, row };
}

const key = (c, r) => `${c},${r}`;

/** The free cell closest to (col,row), scanning outward; null when the grid is full. */
export function nearestFreeCell(col, row, grid, taken) {
	let best = null;
	let bestD = Infinity;
	for (let c = 0; c < grid.cols; c++) {
		for (let r = 0; r < grid.rows; r++) {
			if (taken.has(key(c, r))) continue;
			const d = (c - col) ** 2 + (r - row) ** 2;
			if (d < bestD || (d === bestD && best && (c < best.col || (c === best.col && r < best.row)))) {
				best = { col: c, row: r };
				bestD = d;
			}
		}
	}
	return best;
}

/** Column-major auto arrange: top to bottom, then the next column (Windows order). */
export function arrangeIcons(ids, grid) {
	return ids.map((id, i) => ({ id, col: Math.floor(i / grid.rows), row: i % grid.rows }));
}

/**
 * Move the selected icons by a cell delta. Every icon lands on a free cell,
 * nearest to where it was dropped; icons that are not moving keep their cell.
 */
export function moveIcons(items, movingIds, dCol, dRow, grid) {
	const moving = new Set(movingIds);
	const taken = new Set(items.filter((it) => !moving.has(it.id)).map((it) => key(it.col, it.row)));
	const placed = new Map();
	const order = items
		.filter((it) => moving.has(it.id))
		.sort((a, b) => a.col - b.col || a.row - b.row);
	for (const it of order) {
		const wantC = Math.min(grid.cols - 1, Math.max(0, it.col + dCol));
		const wantR = Math.min(grid.rows - 1, Math.max(0, it.row + dRow));
		const free = nearestFreeCell(wantC, wantR, grid, taken) || { col: it.col, row: it.row };
		taken.add(key(free.col, free.row));
		placed.set(it.id, free);
	}
	return items.map((it) => (placed.has(it.id) ? { ...it, ...placed.get(it.id) } : it));
}

/**
 * Re-seat icons after the grid changed size (window resize, icon size change):
 * keep cells that still fit, move the rest to the nearest free cell.
 */
export function reflowIcons(items, grid) {
	const taken = new Set();
	const out = [];
	const overflow = [];
	for (const it of items) {
		if (it.col < grid.cols && it.row < grid.rows && !taken.has(key(it.col, it.row))) {
			taken.add(key(it.col, it.row));
			out.push(it);
		} else overflow.push(it);
	}
	for (const it of overflow) {
		const free = nearestFreeCell(Math.min(it.col, grid.cols - 1), Math.min(it.row, grid.rows - 1), grid, taken);
		if (!free) continue; // more icons than cells: the extras stay reachable from Start
		taken.add(key(free.col, free.row));
		out.push({ ...it, ...free });
	}
	const order = new Map(items.map((it, i) => [it.id, i]));
	return out.sort((a, b) => order.get(a.id) - order.get(b.id));
}

/** Add icons that are missing (new defaults, new shortcuts) into free cells. */
export function addIcons(items, ids, grid) {
	const have = new Set(items.map((it) => it.id));
	const taken = new Set(items.map((it) => key(it.col, it.row)));
	const out = items.slice();
	for (const id of ids) {
		if (have.has(id)) continue;
		const free = nearestFreeCell(0, 0, grid, taken);
		if (!free) break;
		taken.add(key(free.col, free.row));
		out.push({ id, ...free });
	}
	return out;
}

/** Validate persisted icon placement. Unknown ids and duplicate cells are dropped. */
export function sanitizeIcons(raw, isKnown) {
	if (!Array.isArray(raw)) return [];
	const seenId = new Set();
	const seenCell = new Set();
	const out = [];
	for (const it of raw) {
		if (!it || typeof it.id !== 'string' || !isKnown(it.id) || seenId.has(it.id)) continue;
		if (!Number.isInteger(it.col) || !Number.isInteger(it.row) || it.col < 0 || it.row < 0) continue;
		if (seenCell.has(key(it.col, it.row))) continue;
		seenId.add(it.id);
		seenCell.add(key(it.col, it.row));
		out.push({ id: it.id, col: it.col, row: it.row });
	}
	return out;
}

/** Validate persisted preferences, falling back per field so one bad value never resets the rest. */
export function sanitizePrefs(raw, wallpaperIds) {
	let data = raw;
	if (typeof raw === 'string') {
		try {
			data = JSON.parse(raw);
		} catch {
			data = null;
		}
	}
	const d = data && typeof data === 'object' ? data : {};
	const name = typeof d.name === 'string' ? d.name.replace(/[\u0000-\u001f<>]/g, '').trim().slice(0, 40) : '';
	const hue = Number.isFinite(d.avatarHue) ? Math.round(((d.avatarHue % 360) + 360) % 360) : DEFAULT_PREFS.avatarHue;
	return {
		wall: wallpaperIds.includes(d.wall) ? d.wall : DEFAULT_PREFS.wall,
		accent: /^#[0-9a-f]{6}$/i.test(d.accent || '') ? d.accent.toLowerCase() : DEFAULT_PREFS.accent,
		mode: MODES.includes(d.mode) ? d.mode : DEFAULT_PREFS.mode,
		iconSize: d.iconSize in ICON_SIZES ? d.iconSize : DEFAULT_PREFS.iconSize,
		clock24: d.clock24 === true,
		taskbarAlign: d.taskbarAlign === 'left' ? 'left' : 'center',
		name,
		avatarHue: hue,
		startIn: START_MODES.includes(d.startIn) ? d.startIn : DEFAULT_PREFS.startIn,
		sound: d.sound !== false,
		style: Object.hasOwn(STYLES, d.style) ? d.style : DEFAULT_PREFS.style,
		brightness: pct(d.brightness, 30, DEFAULT_PREFS.brightness),
		volume: pct(d.volume, 0, DEFAULT_PREFS.volume),
		nightLight: d.nightLight === true,
		dnd: d.dnd === true,
		saver: d.saver === true,
	};
}

/** Initials for the profile avatar. */
export function initialsOf(name) {
	const parts = String(name || '')
		.trim()
		.split(/\s+/)
		.filter(Boolean);
	if (!parts.length) return '?';
	return (parts[0][0] + (parts.length > 1 ? parts[parts.length - 1][0] : '')).toUpperCase();
}

/** Bytes of localStorage used by keys with the given prefix (UTF-16, as browsers count). */
export function storageBytes(entries, prefix) {
	let n = 0;
	for (const [k, v] of entries) if (k.startsWith(prefix)) n += (k.length + String(v).length) * 2;
	return n;
}

export function formatBytes(n) {
	if (n < 1024) return `${n} B`;
	if (n < 1024 * 1024) return `${(n / 1024).toFixed(1)} KB`;
	return `${(n / 1024 / 1024).toFixed(2)} MB`;
}

export const EXPORT_PREFIX = 'tws:';
export const EXPORT_MAX_BYTES = 2 * 1024 * 1024;
/** Keys a session export may restore. Anything else in an imported file is ignored. */
export const EXPORT_KEYS = ['tws:desktop', 'tws:prefs', 'tws:icons', 'tws:recent', 'tws:notes', 'tws:welcomed', 'tws:wall'];

export function parseSessionImport(text) {
	if (typeof text !== 'string' || text.length > EXPORT_MAX_BYTES) return { ok: false, error: 'That file is too large to be a desktop session.' };
	let data;
	try {
		data = JSON.parse(text);
	} catch {
		return { ok: false, error: 'That file is not valid JSON.' };
	}
	if (!data || data.kind !== 'three.ws-desktop-session' || data.v !== 1 || typeof data.items !== 'object' || !data.items) {
		return { ok: false, error: 'That file is not a three.ws desktop session export.' };
	}
	const items = {};
	for (const k of EXPORT_KEYS) if (typeof data.items[k] === 'string') items[k] = data.items[k];
	if (!Object.keys(items).length) return { ok: false, error: 'The export contains no desktop data.' };
	return { ok: true, items };
}