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
// Live verification of a queue item: the facts, not the phrasing.
//
// A post that is well written and wrong is worse than no post. This module
// checks every declared claim against the thing it cites, at the moment of
// review:
//
// page the live page, rendered in a real browser, contains the text
// file a repo file contains the text or matches the pattern
// module a repo module's export has the stated length or value
// github-issue an issue has the stated state and label
// github-issues a repository has at least N issues matching state and label
// proof the item's filmed scenario read the fact off the screen,
// waited for the text, or got the answer from the server
//
// It also resolves every link in the copy, confirms every @mention is a real,
// public account, and spellchecks the prose. The CLI runs it before the editor
// (editor.js) and records the result; production re-checks links right before
// a post goes out (linkChecks).
import { existsSync, readFileSync } from 'node:fs';
import { resolve } from 'node:path';
import { pathToFileURL } from 'node:url';
import { mentionsIn } from './editorial.js';
import { urlRe, urlsIn } from './quality.js';
import { factCheck, factNumber, factRules, loadProof, runScenario } from './reel.js';
const UA = 'three.ws editorial verifier (+https://three.ws)';
const normalize = (text) => String(text || '').replace(/\s+/g, ' ').trim().toLowerCase();
export function itemTexts(item) {
return [item.kind === 'article' ? item.article?.title : null, ...(item.posts || []).map((post) => post.text)].filter(Boolean);
}
export function linksIn(texts) {
const links = new Set();
for (const text of texts) for (const match of urlsIn(text)) links.add(/^https?:/i.test(match) ? match : `https://${match}`);
return [...links].map((link) => link.replace(/[).,;:!?]+$/, ''));
}
async function fetchWithTimeout(url, init = {}, ms = 20_000) {
const controller = new AbortController();
const timer = setTimeout(() => controller.abort(), ms);
try {
return await fetch(url, { redirect: 'follow', ...init, headers: { 'user-agent': UA, ...(init.headers || {}) }, signal: controller.signal });
} finally {
clearTimeout(timer);
}
}
// npm answers 403 to every non-browser user agent on a package page, so a post
// linking a package we publish could never pass the link check. The registry is
// the authoritative record of whether that package page exists, and it answers
// any client, so an npm package link is resolved there instead.
export function linkProbeUrl(url) {
const match = /^https?:\/\/(?:www\.)?npmjs\.com\/package\/((?:@[^/]+\/)?[^/?#]+)/i.exec(url);
return match ? `https://registry.npmjs.org/${match[1].replace('/', '%2F')}` : url;
}
// Links must answer 2xx after redirects. Runs in production too, right before
// a post is sent, because a page can break between review and publish.
export async function linkChecks(texts) {
const checks = [];
for (const url of linksIn(texts)) {
try {
const probe = linkProbeUrl(url);
const response = await fetchWithTimeout(probe);
const ok = response.status >= 200 && response.status < 300;
const via = probe !== url ? ` via the npm registry` : response.url !== url ? ` via ${response.url}` : '';
checks.push({ kind: 'link', target: url, ok, detail: ok ? `HTTP ${response.status}${via}` : `HTTP ${response.status}${via}` });
} catch (err) {
checks.push({ kind: 'link', target: url, ok: false, detail: `unreachable: ${err.message}` });
}
}
return checks;
}
// Whether this machine can run the browser the checks need. A missing system
// library fails every page check, probe and scenario at once, and a review
// that ran anyway would record those failures against the posts.
export function describeBrowserError(message) {
const text = String(message || '');
const missing = /error while loading shared libraries: ([^:\s]+)/.exec(text)?.[1];
if (missing) return `the browser cannot start: ${missing} is missing on this machine. Install the system libraries with \`npx playwright install-deps chromium\` and run it again`;
if (/Executable doesn't exist/i.test(text)) return 'the browser is not installed on this machine. Install it with `npx playwright install chromium` and run it again';
return `the browser cannot start: ${text.split('\n')[0]}`;
}
// A machine with no colour emoji font Chromium can use draws every emoji as an
// empty box, and a reel filmed there shows the product broken where it is not.
// Debian's Noto Color Emoji is a bitmap font this Chromium skips, so the fix is
// the outline (COLRv1) build of the same font.
export const EMOJI_FONT_FIX = 'install the COLRv1 build of Noto Color Emoji: curl -sSL -o ~/.local/share/fonts/Noto-COLRv1.ttf --create-dirs https://raw.githubusercontent.com/googlefonts/noto-emoji/main/2D/fonts/Noto-COLRv1.ttf && fc-cache -f';
// Draws an emoji and counts the pixels that carry colour. A box or a missing
// glyph is grey or empty; a drawn emoji is mostly colour.
export async function emojiRendersInColor(page, text = '\u{1F44B}') {
return page.evaluate((glyph) => {
const canvas = document.createElement('canvas');
canvas.width = canvas.height = 64;
const context = canvas.getContext('2d');
context.font = '48px sans-serif';
context.textBaseline = 'top';
context.fillText(glyph, 4, 4);
const { data } = context.getImageData(0, 0, 64, 64);
let coloured = 0;
for (let i = 0; i < data.length; i += 4) {
if (data[i + 3] > 128 && Math.max(data[i], data[i + 1], data[i + 2]) - Math.min(data[i], data[i + 1], data[i + 2]) > 60) coloured++;
}
return coloured > 100;
}, text);
}
export async function browserProblem() {
let browser;
try {
const { chromium } = await import('playwright');
browser = await chromium.launch();
const page = await browser.newPage();
if (!(await emojiRendersInColor(page))) return `the browser draws emoji as empty boxes on this machine, so reels would show the product broken; ${EMOJI_FONT_FIX}`;
return null;
} catch (err) {
return describeBrowserError(err?.message || err);
} finally {
await browser?.close().catch(() => {});
}
}
export function createPageReader() {
let browser = null;
const cache = new Map();
return {
async text(url) {
if (cache.has(url)) return cache.get(url);
if (!browser) {
const { chromium } = await import('playwright');
browser = await chromium.launch();
}
const page = await browser.newPage({ userAgent: UA });
try {
const response = await page.goto(url, { waitUntil: 'networkidle', timeout: 60_000 }).catch(() => null);
const status = response?.status() ?? 0;
// Client-rendered pages (AWS Builder Center, most SPAs) can still be
// empty at network idle. Wait until the text stops growing, so a
// claim is never failed by a page that had not finished rendering.
await page
.waitForFunction(
() => {
const length = document.body.innerText.length;
const previous = window.__verifyLength || 0;
window.__verifyLength = length;
return length > 200 && length === previous;
},
null,
{ polling: 1000, timeout: 30_000 },
)
.catch(() => {});
// A page can answer before its body has mounted; an empty body is
// a failed check, not a crash of the whole review.
const text = await page.evaluate(() => document.body?.innerText || document.documentElement?.innerText || '');
// The page without its shell. A claim check matches against the
// whole body, correctly, because that is what a reader sees; but
// a fact harvested for an announcement must come from the surface
// itself, and the site's mega-menu puts three hundred lines of
// other products' copy above every page's own first word.
const main = await page.evaluate(() => document.querySelector('main')?.innerText || '');
if (!text.trim()) return { status, text: '', raw: '', main: '' };
// `text` is normalized for substring checks; `raw` keeps the line
// breaks and casing the announcement brief harvests facts from.
const result = { status, text: normalize(text), raw: text, main };
cache.set(url, result);
return result;
} finally {
await page.close();
}
},
async close() {
if (browser) await browser.close();
},
};
}
async function github(path) {
const headers = { accept: 'application/vnd.github+json' };
const token = process.env.GITHUB_TOKEN || process.env.GH_TOKEN;
if (token) headers.authorization = `Bearer ${token}`;
const response = await fetchWithTimeout(`https://api.github.com/${path}`, { headers });
if (!response.ok) throw new Error(`GitHub ${path} answered HTTP ${response.status}`);
return response.json();
}
const hasLabel = (issue, label) => !label || issue.labels.some((row) => row.name.toLowerCase() === label.toLowerCase());
async function evidenceCheck(evidence, { root, pages, item }) {
const target = evidence.url || evidence.path || evidence.fact || evidence.saw || evidence.responded || (evidence.repo ? `${evidence.repo}${evidence.number ? `#${evidence.number}` : ''}` : '');
const base = { kind: `evidence:${evidence.type}`, target };
switch (evidence.type) {
case 'page': {
const { status, text } = await pages.text(evidence.url);
if (status < 200 || status >= 300) return { ...base, ok: false, detail: `page answered HTTP ${status}` };
const found = text.includes(normalize(evidence.contains));
return { ...base, ok: found, detail: found ? `live page shows "${evidence.contains}"` : `live page does not show "${evidence.contains}"` };
}
case 'file': {
const path = resolve(root, evidence.path);
if (!existsSync(path)) return { ...base, ok: false, detail: 'file is missing' };
const body = readFileSync(path, 'utf8');
const found = evidence.matches ? new RegExp(evidence.matches, 'm').test(body) : body.includes(evidence.contains);
return { ...base, ok: found, detail: found ? 'file supports the claim' : `file does not contain ${evidence.matches ? `/${evidence.matches}/` : `"${evidence.contains}"`}` };
}
case 'module': {
const module = await import(pathToFileURL(resolve(root, evidence.path)).href);
const value = module[evidence.export];
if (value === undefined) return { ...base, ok: false, detail: `export ${evidence.export} is missing` };
if ('length' in evidence) {
const ok = value?.length === evidence.length;
return { ...base, ok, detail: `${evidence.export} has ${value?.length} entries; the claim needs ${evidence.length}` };
}
const ok = JSON.stringify(value) === JSON.stringify(evidence.equals);
return { ...base, ok, detail: ok ? `${evidence.export} matches` : `${evidence.export} is ${JSON.stringify(value)}` };
}
case 'github-issue': {
const issue = await github(`repos/${evidence.repo}/issues/${evidence.number}`);
const stateOk = !evidence.state || issue.state === evidence.state;
const labelOk = hasLabel(issue, evidence.label);
return { ...base, ok: stateOk && labelOk, detail: `#${evidence.number} is ${issue.state}${evidence.label ? `, ${labelOk ? 'has' : 'lacks'} label "${evidence.label}"` : ''}` };
}
case 'proof':
return { ...base, ...factCheck(evidence, loadProof(root, item.id)) };
case 'github-issues': {
const params = new URLSearchParams({ state: evidence.state || 'open', per_page: '100' });
if (evidence.label) params.set('labels', evidence.label);
const issues = (await github(`repos/${evidence.repo}/issues?${params}`)).filter((row) => !row.pull_request);
const min = evidence.min ?? 1;
return { ...base, ok: issues.length >= min, detail: `${issues.length} ${evidence.state || 'open'} issue(s)${evidence.label ? ` labelled "${evidence.label}"` : ''}; the claim needs ${min}` };
}
default:
return { ...base, ok: false, detail: `unknown evidence type ${evidence.type}` };
}
}
async function mentionChecks(texts, env) {
const handles = mentionsIn(texts.join('\n'));
if (!handles.length) return [];
if (!(env.X_API_KEY && env.X_API_SECRET)) {
return handles.map((handle) => ({ kind: 'mention', target: handle, ok: false, detail: 'X_API_KEY and X_API_SECRET are needed to confirm the account exists' }));
}
const { TwitterApi } = await import('twitter-api-v2');
const client = await new TwitterApi({ appKey: env.X_API_KEY, appSecret: env.X_API_SECRET }).appLogin();
const checks = [];
for (const handle of handles) {
try {
const { data, errors } = await client.v2.userByUsername(handle.slice(1), { 'user.fields': ['name', 'protected', 'verified_type'] });
if (!data) checks.push({ kind: 'mention', target: handle, ok: false, detail: errors?.[0]?.detail || 'account not found' });
else if (data.protected) checks.push({ kind: 'mention', target: handle, ok: false, detail: `${data.name} is a protected account` });
else checks.push({ kind: 'mention', target: handle, ok: true, detail: `${data.name}${data.verified_type && data.verified_type !== 'none' ? ` (${data.verified_type} verified)` : ''}` });
} catch (err) {
checks.push({ kind: 'mention', target: handle, ok: false, detail: `lookup failed: ${err.message}` });
}
}
return checks;
}
async function spellingChecks(item, texts, glossary) {
const { spellCheckDocument } = await import('cspell-lib');
const handles = mentionsIn(texts.join('\n')).map((handle) => handle.slice(1));
const prose = texts.join('\n').replace(urlRe('gi'), ' ').replace(/\$THREE\b/g, ' ');
const altTexts = (item.posts || []).flatMap((post) => (post.media || []).map((media) => media.alt)).filter(Boolean);
const result = await spellCheckDocument(
{ uri: 'file:///x-content.txt', text: [prose, ...altTexts].join('\n'), languageId: 'plaintext', locale: 'en-US,en-GB' },
{ generateSuggestions: true, noConfigSearch: true },
{ words: [...glossary, ...handles], ignoreWords: [] },
);
const seen = new Set();
return result.issues
.filter((issue) => !seen.has(issue.text.toLowerCase()) && seen.add(issue.text.toLowerCase()))
.map((issue) => ({
kind: 'spelling',
target: issue.text,
ok: false,
detail: issue.suggestions?.length ? `did you mean ${issue.suggestions.slice(0, 3).map((s) => (typeof s === 'string' ? s : s.word)).join(', ')}?` : 'not a known word; add it to the queue glossary if it is correct',
}));
}
// ── Feature probes ──────────────────────────────────────────────────────────
// A claim check proves the page says something. A probe proves the feature
// does it. Every item headed for approval declares at least one, in `probes`:
//
// api fetch a URL; expect a status, text, or a JSON value. Cheap and
// dependency-free, so it runs at review AND seconds before posting.
// browser drive the live page in a real browser: goto, click, expect text.
// command run a repo test that exercises the exact behavior the post claims
// (e.g. `node --test packages/three-token-mcp/test/burn-policy.test.mjs`).
// scenario run the item's filmed scenario again, without filming, and hold
// what it reads today against what the reel shows (reel.js).
// Browser, command and scenario probes need a browser and a checkout, so they
// run at review time only; the production pre-flight runs the api probes.
const jsonPath = (value, path) => String(path).split('.').reduce((node, key) => (node == null ? node : node[key]), value);
async function apiProbe(probe) {
const response = await fetchWithTimeout(probe.url, {
method: probe.method || 'GET',
headers: probe.body ? { 'content-type': 'application/json' } : {},
body: probe.body ? JSON.stringify(probe.body) : undefined,
}, probe.timeoutMs || 20_000);
const expect = probe.expect || {};
const statusOk = expect.status ? response.status === expect.status : response.ok;
if (!statusOk) return { ok: false, detail: `HTTP ${response.status}` };
const body = await response.text();
if (expect.contains && !body.includes(expect.contains)) return { ok: false, detail: `response does not contain "${expect.contains}"` };
if (expect.json) {
let parsed;
try {
parsed = JSON.parse(body);
} catch {
return { ok: false, detail: 'response is not JSON' };
}
const value = jsonPath(parsed, expect.json.path);
if ('equals' in expect.json && JSON.stringify(value) !== JSON.stringify(expect.json.equals)) return { ok: false, detail: `${expect.json.path} is ${JSON.stringify(value)}` };
if (expect.json.exists && value === undefined) return { ok: false, detail: `${expect.json.path} is missing` };
if ('min' in expect.json && !(Number(value?.length ?? value) >= expect.json.min)) return { ok: false, detail: `${expect.json.path} is ${JSON.stringify(value)}; needs at least ${expect.json.min}` };
}
return { ok: true, detail: `HTTP ${response.status}, expectations met` };
}
async function browserProbe(probe) {
const { chromium } = await import('playwright');
const browser = await chromium.launch();
try {
const page = await browser.newPage({ userAgent: UA });
for (const step of probe.steps || []) {
if (step.goto) await page.goto(step.goto, { waitUntil: 'networkidle', timeout: 60_000 });
else if (step.click) await page.getByText(step.click, { exact: false }).first().click({ timeout: 20_000 });
else if (step.expect) await page.getByText(step.expect, { exact: false }).first().waitFor({ timeout: step.timeoutMs || 45_000 });
}
return { ok: true, detail: `${(probe.steps || []).length} steps passed` };
} catch (err) {
return { ok: false, detail: err.message.split('\n')[0] };
} finally {
await browser.close();
}
}
async function commandProbe(probe, root) {
const { spawnSync } = await import('node:child_process');
const [command, ...args] = probe.argv || [];
if (!command) return { ok: false, detail: 'command probe has no argv' };
const run = spawnSync(command, args, { cwd: root, encoding: 'utf8', timeout: probe.timeoutMs || 180_000 });
if (run.status === 0) return { ok: true, detail: 'exit 0' };
const tail = `${run.stdout || ''}${run.stderr || ''}`.trim().split('\n').slice(-3).join(' | ');
return { ok: false, detail: `exit ${run.status ?? run.signal}: ${tail}` };
}
// The feature still works, and the post is still true of it. A fact the copy
// states exactly has to read today what the reel was filmed showing; a fact it
// states as a floor has to stay at or above it (factRules). A count that broke
// either is a stale post, and the fix is to film it again.
export function factDrift(item, proof, facts) {
const problems = [];
for (const [name, rule] of Object.entries(factRules(item))) {
const filmed = proof?.facts?.[name];
const live = facts[name];
if (rule.exact && live !== filmed) problems.push(`${name} is now "${live}", the reel shows "${filmed}"`);
if (Number.isFinite(rule.min) && !(factNumber(live) >= rule.min)) problems.push(`${name} is now "${live}", under the floor of ${rule.min} the post claims`);
}
return problems;
}
async function scenarioProbe(item, root) {
const proof = loadProof(root, item.id);
const run = await runScenario(item.scenario, { film: false, root });
if (!run.passed) {
const failed = run.steps.find((step) => !step.ok);
return { ok: false, detail: `step ${failed.index} (${failed.kind} ${failed.target}): ${failed.detail}` };
}
const drift = factDrift(item, proof, run.facts);
if (drift.length) return { ok: false, detail: `${drift.join('; ')}; prove it again` };
const read = Object.entries(run.facts).map(([name, value]) => `${name} ${value}`).join(', ');
return { ok: true, detail: `${run.steps.length} steps passed against the live product${read ? `, every claimed fact still holds (${read})` : ''}` };
}
// `where` is 'review' (every probe) or 'publish' (api probes only).
export async function probeChecks(item, { root, where = 'review' }) {
const checks = [];
for (const probe of item.probes || []) {
if (where === 'publish' && probe.type !== 'api') continue;
const label = probe.name || probe.url || (probe.argv || []).join(' ') || (probe.type === 'scenario' ? 'the filmed scenario' : '');
try {
let result;
if (probe.type === 'api') result = await apiProbe(probe);
else if (probe.type === 'browser') result = await browserProbe(probe);
else if (probe.type === 'command') result = await commandProbe(probe, root);
else if (probe.type === 'scenario') result = await scenarioProbe(item, root);
else result = { ok: false, detail: `unknown probe type ${probe.type}` };
checks.push({ kind: `probe:${probe.type}`, target: label, ...result });
} catch (err) {
checks.push({ kind: `probe:${probe.type}`, target: label, ok: false, detail: err.message });
}
}
return checks;
}
export async function verifyItem(item, { root, glossary = [], env = process.env }) {
// An Article's body is copy too: its words are spell-checked and its links
// resolved, the same as a post's.
const { articleLinks, articleProse } = await import('./queue.js');
const body = articleProse(root, item, { inlineCode: false });
const texts = [...itemTexts(item), ...(body ? [body] : []), ...articleLinks(root, item)];
const pages = createPageReader();
const checks = [];
try {
for (const claim of item.claims || []) {
for (const evidence of claim.evidence || []) {
try {
checks.push({ claim: claim.says, ...(await evidenceCheck(evidence, { root, pages, item })) });
} catch (err) {
checks.push({ claim: claim.says, kind: `evidence:${evidence.type}`, target: evidence.url || evidence.path || evidence.repo, ok: false, detail: err.message });
}
}
}
} finally {
await pages.close();
}
if (!item.probes?.length) {
checks.push({ kind: 'probe', target: item.id, ok: false, detail: 'no feature probe declared; add one to `probes` that proves the feature works, not just that its page loads' });
}
checks.push(...(await probeChecks(item, { root, where: 'review' })));
checks.push(...(await linkChecks(texts)));
checks.push(...(await mentionChecks(texts, env)));
checks.push(...(await spellingChecks(item, texts, glossary)));
return { ok: checks.every((check) => check.ok), checks };
}