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.

12.8 KB
Raw Blame
// Atlas: the site-wide Cmd+K palette.
//
// Three things are worth pinning here, and they are the three things that fail
// silently rather than loudly:
//
//   1. RANKING. A palette that returns the wrong page first is not "broken" in
//      any way a smoke test notices. It just quietly wastes everyone's time. The
//      orderings below are the ones a person would call obviously right, so a
//      scoring tweak that breaks one of them shows up as a red test rather than
//      as a slow drift in usefulness.
//   2. THE INTENT GATE. Every intent step points at a real route. The whole
//      point of generating the index at build time is that an onboarding path
//      can never dead-end on a 404, so the gate itself needs a test proving it
//      actually rejects a bad target.
//   3. COVERAGE. atlas.js is dead code unless something injects it into the
//      built pages, which is exactly how it shipped the first time: committed,
//      complete, and loaded by nothing.

import { describe, it, expect } from 'vitest';
import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
import { resolve } from 'node:path';
import { execFileSync } from 'node:child_process';

import { rankPages, rankIntents, highlight, normalize, tokenize } from '../public/atlas/score.js';
import { shouldInject, injectInto, ATLAS_TAG } from '../scripts/inject-atlas.mjs';

const root = resolve(import.meta.dirname, '..');
const index = JSON.parse(readFileSync(resolve(root, 'public/atlas-index.json'), 'utf8'));

/**
 * Every `document.addEventListener('keydown', …)` call in a source file, with
 * its handler body and whether it asked for the capture phase. Depth-aware so a
 * handler containing its own parens and commas is read whole.
 * @param {string} src
 * @returns {Array<{ body: string, capture: boolean }>}
 */
function keydownRegistrations(src) {
	const out = [];
	const OPEN = "document.addEventListener(";
	for (let i = src.indexOf(OPEN); i !== -1; i = src.indexOf(OPEN, i + 1)) {
		let depth = 0;
		let end = -1;
		for (let j = i + OPEN.length - 1; j < src.length; j++) {
			const ch = src[j];
			if (ch === '(') depth++;
			else if (ch === ')') {
				depth--;
				if (depth === 0) { end = j; break; }
			}
		}
		if (end === -1) continue;
		const args = src.slice(i + OPEN.length, end);
		if (!/^\s*'keydown'/.test(args)) continue;
		out.push({ body: args, capture: /,\s*true\s*,?\s*$/.test(args) });
	}
	return out;
}

/** First result's path for a query, which is the only rank most people ever see. */
const top = (q) => rankPages(q, index.pages)[0]?.page[0];
const paths = (q, n = 5) => rankPages(q, index.pages).slice(0, n).map((r) => r.page[0]);

describe('atlas index', () => {
	it('never offers a route that no longer exists', () => {
		// Only ONE direction of drift can reach a visitor. A page added to
		// data/pages.json but not yet in the committed index self-heals: `prebuild`
		// regenerates the index on every build, so it is current by the time
		// anything ships. A page DELETED from data/pages.json while a stale index
		// still lists it is the harmful direction, because search then sends people
		// to a 404. Assert only that direction, which is also the only one that is
		// not racy while several agents are adding pages to this worktree.
		const routes = new Set(
			JSON.parse(readFileSync(resolve(root, 'data/pages.json'), 'utf8')).sections.flatMap((s) =>
				(s.pages || []).map((p) => p.path),
			),
		);
		const orphans = index.pages.map((p) => p[0]).filter((path) => !routes.has(path));
		expect(orphans, 'regenerate with: node scripts/build-atlas-index.mjs').toEqual([]);
	});

	it('carries every section and a plausible number of pages', () => {
		expect(index.sections.length).toBeGreaterThanOrEqual(10);
		expect(index.pageCount).toBe(index.pages.length);
		expect(index.pageCount).toBeGreaterThan(500);
		for (const page of index.pages) {
			expect(page[0].startsWith('/')).toBe(true);
			expect(page[1].length).toBeGreaterThan(0);
			expect(typeof page[3]).toBe('string');
		}
	});

	it('never lists the same route twice', () => {
		const seen = new Set(index.pages.map((p) => p[0]));
		expect(seen.size).toBe(index.pages.length);
	});
});

describe('the intent catalog gate', () => {
	const known = new Set(index.pages.map((p) => p[0]));
	// Targets the generator allows that are not pages: API endpoints and static
	// machine files. Kept in sync with NON_PAGE_TARGETS in the generator.
	const allowed = new Set(['/docs/start-here', '/api/status', '/llms.txt']);

	it('points every step at a route that exists', () => {
		for (const intent of index.intents) {
			for (const step of intent.steps) {
				if (!step.to || /^https?:\/\//.test(step.to)) continue;
				expect(
					known.has(step.to) || allowed.has(step.to),
					`intent "${intent.id}" points at ${step.to}, which is not a route`,
				).toBe(true);
			}
		}
	});

	it('gives every intent trigger phrases and a first destination', () => {
		for (const intent of index.intents) {
			expect(intent.match.length, `intent "${intent.id}" is unreachable`).toBeGreaterThan(0);
			expect(intent.steps.length).toBeGreaterThan(0);
			expect(intent.steps.some((s) => s.to), `intent "${intent.id}" goes nowhere`).toBe(true);
		}
	});

	it('FAILS the build when a step points at a route that does not exist', () => {
		// The gate is the entire reason the index is generated instead of fetched
		// at runtime. Run the REAL generator against a deliberately broken catalog:
		// a gate nobody has ever watched fail is a gate nobody knows works.
		const catalog = JSON.parse(readFileSync(resolve(root, 'data/atlas-intents.json'), 'utf8'));
		catalog.intents[0].steps[0].to = '/this-route-was-never-built';

		const scratch = resolve(root, 'node_modules/.cache/atlas');
		mkdirSync(scratch, { recursive: true });
		const brokenCatalog = resolve(scratch, 'intents.json');
		writeFileSync(brokenCatalog, JSON.stringify(catalog));

		let exitCode = 0;
		let stderr = '';
		try {
			execFileSync('node', [resolve(root, 'scripts/build-atlas-index.mjs')], {
				cwd: root,
				encoding: 'utf8',
				env: {
					...process.env,
					ATLAS_INTENTS: brokenCatalog,
					// Never let the failing run touch the committed index.
					ATLAS_OUT: resolve(scratch, 'index.json'),
				},
			});
		} catch (e) {
			exitCode = e.status;
			stderr = String(e.stderr || '');
		}
		expect(exitCode).toBe(1);
		expect(stderr).toContain('/this-route-was-never-built');
		expect(stderr).toContain('not a route in data/pages.json');
	});
});

describe('page ranking', () => {
	it('puts the canonical route above the docs that describe it', () => {
		// The failure this guards: typing a product name and getting its
		// documentation instead of the product.
		expect(top('x402')).toBe('/x402');
		expect(top('marketplace')).toBe('/marketplace');
		expect(top('status')).toBe('/status');
	});

	it('resolves an exact path typed straight into the box', () => {
		expect(top('/atlas')).toBe('/atlas');
		expect(top('/pricing')).toBe('/pricing');
	});

	it('requires every term to match, so extra words narrow instead of widen', () => {
		const broad = rankPages('agent', index.pages, { limit: 400 }).length;
		const narrow = rankPages('agent wallet', index.pages, { limit: 400 }).length;
		expect(narrow).toBeLessThan(broad);
		expect(narrow).toBeGreaterThan(0);
		for (const { page } of rankPages('agent wallet', index.pages, { limit: 400 })) {
			const hay = `${page[0]} ${page[1]} ${page[2]}`.toLowerCase();
			expect(hay).toContain('wallet');
		}
	});

	it('recovers from a typo without letting fuzzy matches outrank real ones', () => {
		expect(paths('marketplce', 3)).toContain('/marketplace');
		// A real substring hit must still win outright over any subsequence hit.
		const ranked = rankPages('gallery', index.pages);
		expect(ranked[0].page[0]).toBe('/gallery');
	});

	it('returns nothing for a query that matches nothing, rather than noise', () => {
		expect(rankPages('zzzqqxwv', index.pages)).toHaveLength(0);
	});

	it('is fast enough to run on every keystroke', () => {
		const started = performance.now();
		for (let i = 0; i < 20; i++) rankPages('agent wallet', index.pages, { limit: 400 });
		// 20 full passes over the whole route table. Generous ceiling: the point is
		// to catch an accidental O(n^2), not to benchmark the machine.
		expect(performance.now() - started).toBeLessThan(1500);
	});
});

describe('intent ranking', () => {
	it('surfaces the task shortcut for the words a newcomer actually types', () => {
		expect(rankIntents('get started', index.intents)[0].intent.id).toBe('first-time');
		expect(rankIntents('launch a coin', index.intents)[0].intent.id).toBe('launch-coin');
		expect(rankIntents('embed', index.intents)[0].intent.id).toBe('embed-on-site');
		expect(rankIntents('is it down', index.intents)[0].intent.id).toBe('status');
	});

	it('handles a question phrased around a trigger phrase', () => {
		expect(rankIntents('how do i get paid', index.intents)[0].intent.id).toBe('get-paid');
	});

	it('stays silent on a single letter and on an unrelated query', () => {
		expect(rankIntents('a', index.intents)).toHaveLength(0);
		expect(rankIntents('quaternion skinning', index.intents)).toHaveLength(0);
	});
});

describe('highlighting', () => {
	it('marks the typed run and leaves the rest alone', () => {
		const runs = highlight('Agent Wallet', 'wallet');
		expect(runs.map((r) => r.t).join('')).toBe('Agent Wallet');
		expect(runs.filter((r) => r.hit).map((r) => r.t)).toEqual(['Wallet']);
	});

	it('merges overlapping term hits instead of nesting them', () => {
		const runs = highlight('agentic', 'agent agentic');
		expect(runs.filter((r) => r.hit)).toHaveLength(1);
		expect(runs.find((r) => r.hit).t).toBe('agentic');
	});

	it('never drops or duplicates a character', () => {
		for (const page of index.pages.slice(0, 200)) {
			expect(highlight(page[1], 'a e i').map((r) => r.t).join('')).toBe(page[1]);
		}
	});

	it('folds accents so an unaccented query still matches', () => {
		expect(normalize('Café')).toBe('cafe');
		expect(tokenize('x402 / Studio')).toEqual(['x402', 'studio']);
	});
});

describe('injection coverage', () => {
	it('adds the palette to an ordinary page exactly once', () => {
		const page = '<html><head></head><body><h1>hi</h1></body></html>';
		const once = injectInto(page);
		expect(once).toContain(ATLAS_TAG);
		expect(injectInto(once)).toBe(once);
	});

	it('still lands on a page with no closing body tag', () => {
		expect(injectInto('<div>fragment-less page</div>')).toContain(ATLAS_TAG);
	});

	it('refuses embeds and the nav/footer fragments', () => {
		// Embeds run inside third-party pages: taking their Cmd+K is hostile.
		// nav.html/footer.html are assigned via innerHTML, where a script tag
		// renders as visible text.
		for (const f of ['widget.html', 'embed.html', 'avatar-embed.html', 'nav.html', 'footer.html']) {
			expect(shouldInject(`dist/${f}`), `${f} must not get the palette`).toBe(false);
		}
		for (const f of ['index.html', 'atlas.html', 'status.html', 'docs/mcp.html']) {
			expect(shouldInject(`dist/${f}`), `${f} should get the palette`).toBe(true);
		}
	});

	it('leaves "/" to the page and keeps Cmd+K for itself', () => {
		// Atlas used to claim "/" in the CAPTURE phase, which beat every page
		// listener no matter when it registered. ~20 pages bind "/" to focus their
		// own search or address field (/airdrops even prints "Press / to focus"
		// under its form), and all of them were dead on arrival. "/" now listens in
		// the bubble phase so a page that handled it leaves defaultPrevented set
		// and Atlas stands down; Cmd+K stays in capture because it belongs to
		// Atlas everywhere.
		const src = readFileSync(resolve(root, 'public/atlas.js'), 'utf8');
		const calls = keydownRegistrations(src);
		expect(calls.length, 'atlas registers exactly two keydown listeners').toBe(2);
		const slash = calls.find((c) => c.body.includes("e.key !== '/'") || c.body.includes("e.key === '/'"));
		const cmdK = calls.find((c) => /e\.key (!==|===) 'k'/.test(c.body));
		expect(slash, 'a "/" keydown listener').toBeTruthy();
		expect(cmdK, 'a Cmd+K keydown listener').toBeTruthy();
		expect(slash.capture, '"/" must NOT be captured, or page shortcuts never fire').toBe(false);
		expect(cmdK.capture, 'Cmd+K stays in the capture phase').toBe(true);
		expect(slash.body, '"/" handler must yield to a page that already handled it').toContain('defaultPrevented');
	});

	it('is wired into the build, not just available to it', () => {
		// The first release of Atlas was complete and loaded by nothing. This test
		// is the reason that cannot happen twice.
		const pkg = JSON.parse(readFileSync(resolve(root, 'package.json'), 'utf8'));
		expect(pkg.scripts.build).toContain('inject-atlas.mjs');
		expect(pkg.scripts.prebuild).toContain('build-atlas-index.mjs');
		const vite = readFileSync(resolve(root, 'vite.config.js'), 'utf8');
		expect(vite).toContain("name: 'three-ws-atlas'");
		expect(vite).toContain("'/atlas': resolve(root, 'pages/atlas.html')");
	});
});