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.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
#!/usr/bin/env node
// build-tour-atlas.mjs: publish data/tour-atlas.json to public/tour/atlas.json,
// which the /tour/atlas page fetches, and verify the atlas still describes the
// tour that actually exists.
//
// data/ is source and is never served, so the page cannot read the manifest
// directly. This mirrors the guards registry (scripts/build-guards.mjs) and the
// page index: the generated copy is committed so a clean checkout renders the
// page with no build step.
//
// node scripts/build-tour-atlas.mjs write public/tour/atlas.json
// node scripts/build-tour-atlas.mjs --check verify, write nothing, exit 1 on drift
//
// --check is the gate (`npm run audit:tour-atlas`) and it enforces four things:
//
// 1. the published copy matches the source byte for byte,
// 2. every curriculum stop has an atlas entry and vice versa, so a page added
// to data/pages.json cannot land in the tour without ever being looked at,
// 3. every screenshot the manifest references exists on disk, and
// 4. no stop's spotlight anchor has rotted (anchor.state === 'missing') and no
// stop's page is unreachable.
//
// Point 4 is the one that pays for the rest. The guided tour resolves its
// anchors with CSS selectors against pages other people redesign; before this
// existed, a redesign silently downgraded the stop to a whole-page dim and
// nothing anywhere noticed. Re-run `npm run tour:atlas` to refresh the capture,
// then fix whatever it reports.
import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
import path from 'node:path';
import { fileURLToPath } from 'node:url';
const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
const SRC = path.join(root, 'data/tour-atlas.json');
const OUT = path.join(root, 'public/tour/atlas.json');
const CURRICULUM = path.join(root, 'public/tour/curriculum.json');
const PUBLIC_DIR = path.join(root, 'public');
const PAGES_INDEX = path.join(root, 'data/pages.json');
const PAGE_HTML = path.join(root, 'pages/tour-atlas.html');
/** The exact bytes public/tour/atlas.json must contain for a given manifest. */
export function renderPublicAtlas(manifest) {
return `${JSON.stringify(manifest, null, '\t')}\n`;
}
/**
* The manifest summary, derived from the stops it describes.
*
* This lives here rather than in the capture script because both sides need it:
* the capture writes it, and --check re-derives it to prove the committed
* numbers still describe the committed stops. A summary that drifted from its
* stops is not cosmetic, the page prints it as a headline stat ("264 stops")
* directly above a grid that renders a different number.
*/
export function summarizeStops(stops) {
const resolved = stops.filter((s) => s.anchor?.state === 'resolved');
return {
total: stops.length,
anchored: resolved.length,
missingAnchor: stops.filter((s) => s.anchor?.state === 'missing').length,
// A curated anchor points at the feature the narration is about. A
// fallback anchor points at whatever heading the page happens to have, so
// the count is the size of the "this stop deserves a real anchor" backlog.
curatedAnchor: resolved.filter((s) => s.anchor.source === 'curriculum').length,
fallbackAnchor: resolved.filter((s) => s.anchor.source === 'fallback').length,
navScopedAnchor: resolved.filter((s) => s.anchor.scope === 'nav').length,
unreachable: stops.filter((s) => s.status >= 400 || s.status === 0).length,
withConsoleErrors: stops.filter((s) => s.consoleErrors > 0).length,
captured: stops.filter((s) => Boolean(s.media)).length,
};
}
/**
* Every "<n> stops" claim in a blob of copy, as numbers.
*
* The page and its page-index entry both advertise the size of the atlas, and
* that number is copied verbatim into the meta description, the OG and Twitter
* cards, the JSON-LD block, the OG image URL (where the space is "+"), the
* curriculum narration, llms.txt, the sitemap and the changelog. It was written
* once, by hand, and was wrong by 78 stops for a month because nothing checked
* it. Reading the claims back out is what lets the gate below check them.
*/
export function stopCountClaims(text) {
return [...String(text ?? '').matchAll(/\b(\d+)[\s+]stops\b/g)].map((m) => Number(m[1]));
}
/**
* The copy that advertises the atlas, checked against the atlas itself.
* `sources` is a list of { label, text } so the caller owns the file reads.
*/
export function stopCountProblems(total, sources) {
const problems = [];
for (const { label, text } of sources) {
for (const claimed of new Set(stopCountClaims(text))) {
if (claimed !== total) {
problems.push(
`${label} advertises "${claimed} stops" but the atlas has ${total}. ` +
`Update the copy to ${total}.`,
);
}
}
}
return problems;
}
/**
* Every reason the committed atlas would be lying, as plain strings.
* Pure so tests can drive it with fixtures instead of the real files.
*/
export function atlasProblems(manifest, curriculum, mediaExists) {
const problems = [];
if (!manifest || !Array.isArray(manifest.stops) || !manifest.stops.length) {
return ['data/tour-atlas.json has no stops. Run `npm run tour:atlas` to capture the tour.'];
}
const atlasIds = new Set(manifest.stops.map((s) => s.id));
const tourIds = new Set(curriculum.stops.map((s) => s.id));
for (const stop of curriculum.stops) {
if (!atlasIds.has(stop.id)) {
problems.push(
`tour stop "${stop.id}" (${stop.path}) has no atlas entry. Run: npm run tour:atlas -- --only ${stop.id}`,
);
}
}
for (const stop of manifest.stops) {
if (!tourIds.has(stop.id)) {
problems.push(`atlas entry "${stop.id}" is not in the curriculum any more. Re-run: npm run tour:atlas`);
}
}
// A stop's index is its position in the curriculum, and the page prints it as
// the stop number on every card and in the lightbox ("stop 12 of 263"). A
// partial capture used to merge freshly numbered stops with stops numbered
// against an older curriculum, which shipped duplicate and skipped numbers.
const order = new Map(curriculum.stops.map((s, i) => [s.id, i]));
const misnumbered = manifest.stops.filter((s) => order.has(s.id) && s.index !== order.get(s.id));
if (misnumbered.length) {
problems.push(
`${misnumbered.length} atlas stop(s) carry a stale index, so /tour/atlas renders duplicate stop ` +
`numbers and an out-of-order grid (first: "${misnumbered[0].id}" is numbered ` +
`${misnumbered[0].index} but sits at ${order.get(misnumbered[0].id)}). Re-run: npm run tour:atlas`,
);
}
// The headline stats on /tour/atlas come straight from summary, so a summary
// that no longer describes the stops is a visible lie on the page.
const expected = summarizeStops(manifest.stops);
const drifted = Object.keys(expected).filter((k) => manifest.summary?.[k] !== expected[k]);
if (drifted.length) {
problems.push(
`the atlas summary no longer matches its stops (${drifted
.map((k) => `${k}: ${manifest.summary?.[k]} should be ${expected[k]}`)
.join(', ')}). Re-run: npm run tour:atlas`,
);
}
for (const stop of manifest.stops) {
if (stop.status === 0 || stop.status >= 400) {
problems.push(
`tour stop "${stop.id}" points at ${stop.path}, which answered ${stop.status || 'nothing'}. ` +
`Fix the page or drop the stop from scripts/build-tour.mjs.`,
);
continue;
}
if (stop.anchor?.state === 'missing') {
problems.push(
`tour stop "${stop.id}" (${stop.path}) has no working spotlight anchor, so the guide dims the ` +
`whole page instead of pointing at anything. Give it a selector in scripts/build-tour.mjs (TARGETS).`,
);
}
for (const key of ['hero', 'thumb', 'mobile']) {
const media = stop.media?.[key];
if (media && !mediaExists(media.url)) {
problems.push(`tour stop "${stop.id}" references ${media.url}, which is not on disk.`);
}
}
}
return problems;
}
function main() {
const check = process.argv.includes('--check');
if (!existsSync(SRC)) {
console.error(
'data/tour-atlas.json is missing. Capture the tour first: npm run tour:atlas',
);
process.exit(1);
}
const manifest = JSON.parse(readFileSync(SRC, 'utf8'));
const curriculum = JSON.parse(readFileSync(CURRICULUM, 'utf8'));
const body = renderPublicAtlas(manifest);
if (!check) {
mkdirSync(path.dirname(OUT), { recursive: true });
writeFileSync(OUT, body);
const s = manifest.summary;
console.log(
`build-tour-atlas: wrote public/tour/atlas.json (${s.total} stops, ${s.captured} screenshots, ` +
`${s.curatedAnchor} curated anchors).`,
);
return;
}
const problems = [];
if (!existsSync(OUT)) {
problems.push('public/tour/atlas.json is missing. Run: npm run build:tour-atlas');
} else if (readFileSync(OUT, 'utf8') !== body) {
problems.push(
'public/tour/atlas.json is stale: it does not match data/tour-atlas.json. Run: npm run build:tour-atlas',
);
}
problems.push(
...atlasProblems(manifest, curriculum, (url) => existsSync(path.join(PUBLIC_DIR, url.replace(/^\//, '')))),
);
// The headline number in the page's own marketing copy is the one claim on
// this surface that no other check could see, because it lives in meta tags
// and a JSON string rather than in the manifest.
const pageEntry = JSON.parse(readFileSync(PAGES_INDEX, 'utf8'))
.sections.flatMap((s) => s.pages)
.find((p) => p.path === '/tour/atlas');
problems.push(
...stopCountProblems(manifest.stops.length, [
{ label: 'data/pages.json /tour/atlas', text: pageEntry?.description ?? '' },
{ label: 'pages/tour-atlas.html', text: readFileSync(PAGE_HTML, 'utf8') },
]),
);
if (problems.length) {
console.error(`audit:tour-atlas found ${problems.length} problem(s):\n`);
for (const p of problems) console.error(` - ${p}`);
process.exit(1);
}
const s = manifest.summary;
console.log(
`audit:tour-atlas: ${s.total} stops, all anchored and photographed ` +
`(${s.curatedAnchor} curated, ${s.fallbackAnchor} generic).`,
);
}
// Only run when invoked directly, so tests can import the pure helpers above.
if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
main();
}