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.

16.2 KB
Raw Blame
#!/usr/bin/env node
// announce-rank.mjs - rank every shipped surface that has never been announced.
//
// docs/announcement-coverage.md established the backlog by hand: 400+ shipped
// surfaces, fewer than 50 ever posted about. That audit is prose, so it cannot
// be queried, scored, or advanced. Nothing in it records which feature already
// has media, which has a draft, or which one was cleared to post. Announcing
// autonomously needs state, so this script rebuilds the backlog as data.
//
// It re-derives the inventory from its real sources on every run (data/pages.json,
// packages/*, workers/*, services/*), reads the announced/passing/never status
// out of the coverage audit's tables, scores what is left, and writes the ledger
// to data/announcements.json. A surface that shipped after the audit was written
// is absent from those tables and is therefore treated as never announced, which
// is the correct default and the reason this is re-derived rather than stored.
//
// ── The score ────────────────────────────────────────────────────────────────
// Weights come from data/x-archive/analysis/trythreews-engagement.json, which
// measured 158 of our own posts. They are not taste. Median engagement lift by
// signal, from that report:
//
//   token / $THREE topic      13.3x     mentions a partner account   4.5x
//   has an image               2.3x     text only                    0.875x
//   100-179 chars              3.0x     280-499 chars                4.75x
//   1-99 chars                 0.83x    has a video                  0.71x
//
// So the score rewards a surface that (a) can carry a real screenshot or motion
// loop, (b) touches $THREE or the agent economy, (c) legitimately names a
// partner we can tag, and (d) is genuinely new rather than a variation on
// something already posted. Depth signals (a doc, a README, backing API
// handlers) act as a proxy for "there is enough here to write 280 characters
// about and link proof for".
//
// Liveness is a hard gate, not a weight: announcing a dead surface is worse
// than not announcing it. --probe fetches every candidate and records the
// result; without it the last probe recorded in the ledger is reused.
//
// ── Usage ────────────────────────────────────────────────────────────────────
//   node scripts/announce-rank.mjs                 # rank from the cached probe
//   node scripts/announce-rank.mjs --probe         # re-check every surface live
//   node scripts/announce-rank.mjs --top 25        # show the top N
//   node scripts/announce-rank.mjs --json          # machine-readable
//   node scripts/announce-rank.mjs --write         # update data/announcements.json
//
// Wired as `npm run announce:rank`. It never posts anything.

import { readFileSync, writeFileSync, existsSync, readdirSync } from 'node:fs';
import { resolve, dirname, join } from 'node:path';
import { fileURLToPath } from 'node:url';

import { slugFor } from '../api/_lib/announce/plan.js';

const root = resolve(dirname(fileURLToPath(import.meta.url)), '..');
const LEDGER = join(root, 'data/announcements.json');
const COVERAGE = join(root, 'docs/announcement-coverage.md');
const SITE = 'https://three.ws';

const argv = process.argv.slice(2);
const flag = (n) => argv.includes(n);
const arg = (n, d) => {
	const i = argv.indexOf(n);
	return i >= 0 && argv[i + 1] ? argv[i + 1] : d;
};
const doProbe = flag('--probe');
const asJson = flag('--json');
const doWrite = flag('--write');
const topN = Number(arg('--top', 30));

// Descriptions are copied verbatim out of package.json and pages.json, and a
// lot of them carry an em-dash. They are the raw material an announcement gets
// drafted from, so the glyph is normalized here rather than caught later in
// every draft: the house style bans it everywhere, this file included.
const DASHES = new RegExp('\\s*[\\u2014\\u2013]\\s*', 'g');
const clean = (text) => String(text || '').replace(DASHES, ', ').trim();

// --- inventory --------------------------------------------------------------

// Sections of data/pages.json that hold product surfaces. 'learn' and 'blog'
// are content (348 docs pages and 39 posts); announcing each one individually
// would drown the real features. 'legal' is boilerplate.
const PRODUCT_SECTIONS = new Set(['main', 'build', 'labs', 'crypto', 'agent-tools', 'account', 'machine']);

// A product surface does not always live in a product section. Five pages
// filed under 'learn' carry `showcase: true`, and every one of them is a
// product rather than a document: /awesome, /3d, /crypto, /crypto-api and
// /docs/world. Skipping their section wholesale is what kept them out of this
// ledger, and therefore out of the calendar, the factory and the queue, since
// the ledger was first built. `showcase` is already the flag pages.json uses
// for "put this in front of someone", so it is the admission rule here: a
// content page carrying it is inventory, a content page without it is content.
const inInventory = (section, page) => PRODUCT_SECTIONS.has(section.id) || page.showcase === true;

function pageInventory() {
	const { sections } = JSON.parse(readFileSync(join(root, 'data/pages.json'), 'utf8'));
	const out = [];
	for (const section of sections) {
		for (const page of section.pages) {
			if (page.indexable === false) continue;
			if (!inInventory(section, page)) continue;
			out.push({
				key: page.path,
				kind: 'page',
				section: section.id,
					title: clean(page.title),
				description: clean(page.description),
				added: page.added || null,
				sitemapPriority: typeof page.priority === 'number' ? page.priority : 0.5,
				showcase: Boolean(page.showcase),
				url: page.path,
			});
		}
	}
	return out;
}

function dirInventory(base, kind, keyPrefix) {
	const dir = join(root, base);
	if (!existsSync(dir)) return [];
	const out = [];
	for (const name of readdirSync(dir, { withFileTypes: true })) {
		if (!name.isDirectory()) continue;
		const pkgPath = join(dir, name.name, 'package.json');
		let title = `${keyPrefix}${name.name}`;
		let description = '';
		if (existsSync(pkgPath)) {
			try {
				const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
				if (pkg.private === true && kind === 'package') continue;
				title = pkg.name || title;
				description = clean(pkg.description);
			} catch { /* an unparseable package.json still leaves a real directory */ }
		}
		if (!description && existsSync(join(dir, name.name, 'README.md'))) {
			const readme = readFileSync(join(dir, name.name, 'README.md'), 'utf8');
			const line = readme.split('\n').find((l) => l.trim() && !l.startsWith('#'));
			description = clean(line).slice(0, 240);
		}
		out.push({
			key: kind === 'package' ? title : `${base}/${name.name}`,
			kind,
			section: kind,
			title,
			description,
			added: null,
			sitemapPriority: kind === 'package' ? 0.6 : 0.4,
			showcase: false,
			url: null,
			dir: `${base}/${name.name}`,
		});
	}
	return out;
}

// Whether a surface actually moves, read back from the only thing that knows:
// the capture, which shoots two frames a second apart and records `animated`
// in the media manifest. No description can answer it, because a curated list
// of animation tools is described entirely in words about motion and sits
// perfectly still. A surface nobody has photographed yet is left free to try a
// loop; one that was photographed and held still stops being offered one.
function motionVerdicts() {
	const path = join(root, 'public/announce/media-manifest.json');
	if (!existsSync(path)) return new Map();
	const manifest = JSON.parse(readFileSync(path, 'utf8'));
	const shots = Array.isArray(manifest.shots) ? manifest.shots : Object.values(manifest.shots || {});
	return new Map(shots.filter((shot) => shot && shot.id).map((shot) => [shot.id, shot.animated !== false]));
}

// --- announced status, read out of the coverage audit ------------------------

// Every inventory table in the audit has an "Announced" column, but not at the
// same index (pages carry Added, packages carry What it is). Reading the header
// row for the column position keeps this working when a table gains a column.
function coverageStatus() {
	const status = new Map();
	if (!existsSync(COVERAGE)) return status;
	let announcedIdx = -1;
	let postIdx = -1;
	for (const line of readFileSync(COVERAGE, 'utf8').split('\n')) {
		if (!line.startsWith('|')) continue;
		const cells = line.split('|').slice(1, -1).map((c) => c.trim());
		const header = cells.findIndex((c) => /^announced$/i.test(c));
		if (header >= 0) {
			announcedIdx = header;
			postIdx = cells.findIndex((c) => /post/i.test(c));
			continue;
		}
		if (announcedIdx < 0 || !cells[0]) continue;
		const key = cells[0].replace(/^`|`$/g, '').trim();
		const verdict = (cells[announcedIdx] || '').toLowerCase();
		if (!/^(yes|no|passing)$/.test(verdict)) continue;
		const post = postIdx >= 0 ? cells[postIdx] || '' : '';
		const links = [...post.matchAll(/\((https:\/\/x\.com\/[^)]+)\)/g)].map((m) => m[1]);
		status.set(key, { state: verdict === 'yes' ? 'announced' : verdict, posts: links });
	}
	return status;
}

// The audit closes with a hand-picked shortlist of the surfaces most worth
// posting. Reading it back gives the score a novelty signal that a description
// string cannot supply: "nothing else on the timeline is like this".
function curatedShortlist() {
	const picks = new Map();
	if (!existsSync(COVERAGE)) return picks;
	const body = readFileSync(COVERAGE, 'utf8');
	const start = body.indexOf('## Strongest unannounced candidates');
	if (start < 0) return picks;
	for (const line of body.slice(start).split('\n')) {
		if (!line.startsWith('| `')) continue;
		const cells = line.split('|').slice(1, -1).map((c) => c.trim());
		const why = cells[1] || '';
		for (const m of cells[0].matchAll(/`([^`]+)`/g)) picks.set(m[1], why);
	}
	return picks;
}

// --- scoring ----------------------------------------------------------------

const TOKEN_RE = /\$THREE|\btoken\b|\bcoin\b|\bx402\b|\bwallet\b|\bUSDC\b|on-chain|onchain|\bmint\b|\btrading\b|\bpump\.fun\b/i;
const PARTNERS = [
	[/\bMCP\b|Model Context Protocol/i, '@AnthropicAI'],
	[/\bSolana\b/i, '@solana'],
	[/watsonx|\bGranite\b|\bIBM\b/i, '@IBM'],
	[/pump\.fun/i, '@pumpfun'],
	[/\bNVIDIA\b|\bTRELLIS\b|\bNemotron\b/i, '@nvidia'],
	[/\bOpenAI\b|ChatGPT/i, '@OpenAI'],
	[/Hugging Face/i, '@huggingface'],
];
// Surfaces whose product IS a moving picture. The engagement report says an
// image carries 2.3x and text-only drags, so the ability to produce a real
// frame is worth more than any prose signal here.
const VISUAL_RE = /\b3D\b|avatar|animation|motion|mocap|render|scene|world|walk|camera|\bAR\b|garment|wardrobe|gallery|studio|viewer|visuali[sz]|map|chart|live|watch/i;

function scoreSurface(rec, curated) {
	const text = `${rec.title} ${rec.description}`;
	const signals = {};

	// Reach: what we already decided this surface is worth in the sitemap.
	signals.reach = Math.round(rec.sitemapPriority * 20);

	// Visual: can this produce a frame worth 2.3x, or a motion loop?
	signals.visual = rec.showcase ? 25 : VISUAL_RE.test(text) ? 14 : 0;

	// Token topic carried the highest measured lift of any topic we posted.
	signals.token = TOKEN_RE.test(text) ? 18 : 0;

	// A partner we can legitimately tag. Only counts when the surface really
	// runs on them; a tag we cannot justify is a lie, not a lift.
	const partner = PARTNERS.find(([re]) => re.test(text));
	signals.partner = partner ? 12 : 0;
	rec.partner = partner ? partner[1] : null;

	// Novelty: on the audit's hand-picked shortlist.
	const why = curated.get(rec.key);
	signals.novelty = why ? 20 : 0;
	rec.curatedWhy = why || null;

	// Depth: enough substance to write 280 characters and link proof.
	let depth = 0;
	const slug = rec.key.replace(/^[/@]/, '').replace(/[/@]/g, '-');
	if (existsSync(join(root, `docs/${slug}.md`))) depth += 8;
	if (rec.dir && existsSync(join(root, rec.dir, 'README.md'))) depth += 6;
	if (rec.description.length > 120) depth += 5;
	signals.depth = depth;

	rec.signals = signals;
	rec.score = Object.values(signals).reduce((a, b) => a + b, 0);
	return rec;
}

// --- liveness ---------------------------------------------------------------

async function probe(rec) {
	if (!rec.url) return { ok: true, reason: 'not a route' };
	try {
		const res = await fetch(`${SITE}${rec.url}`, { redirect: 'follow', signal: AbortSignal.timeout(25000) });
		const body = await res.text();
		return { ok: res.status === 200 && body.length > 4000, status: res.status, bytes: body.length };
	} catch (err) {
		return { ok: false, status: 0, error: String(err.message || err) };
	}
}

// --- main -------------------------------------------------------------------

const previous = existsSync(LEDGER) ? JSON.parse(readFileSync(LEDGER, 'utf8')) : { entries: [] };
const priorByKey = new Map((previous.entries || []).map((e) => [e.key, e]));

const status = coverageStatus();
const curated = curatedShortlist();
const verdicts = motionVerdicts();
const inventory = [
	...pageInventory(),
	...dirInventory('packages', 'package', '@three-ws/'),
	...dirInventory('workers', 'worker', 'workers/'),
	...dirInventory('services', 'service', 'services/'),
];

for (const rec of inventory) {
	const known = status.get(rec.key) || status.get(rec.title) || null;
	rec.coverage = known ? known.state : 'no';
	rec.posts = known ? known.posts : [];
	// A pack advances through: backlog -> media -> drafted -> approved -> posted.
	// Only this script writes 'backlog'; the later states are set by the pack
	// tooling and by the owner, so they survive a rerun.
	const prior = priorByKey.get(rec.key);
	rec.stage = prior && prior.stage && prior.stage !== 'backlog' ? prior.stage : 'backlog';
	if (prior && prior.media) rec.media = prior.media;
	if (prior && prior.pack) rec.pack = prior.pack;
	rec.live = prior && prior.live ? prior.live : null;
	const shot = `${slugFor(rec.key)}-hero`;
	if (verdicts.has(shot)) rec.moves = verdicts.get(shot);
	scoreSurface(rec, curated);
}

if (doProbe) {
	const candidates = inventory.filter((r) => r.coverage === 'no' && r.url);
	const queue = [...candidates];
	const workers = Array.from({ length: 8 }, async () => {
		while (queue.length) {
			const rec = queue.shift();
			rec.live = { ...(await probe(rec)), checkedAt: new Date().toISOString().slice(0, 10) };
		}
	});
	await Promise.all(workers);
	const dead = candidates.filter((r) => r.live && !r.live.ok);
	if (!asJson) console.error(`probed ${candidates.length} routes, ${dead.length} not announceable`);
}

const ranked = inventory
	.filter((r) => r.coverage === 'no')
	.filter((r) => !r.live || r.live.ok)
	.sort((a, b) => b.score - a.score || a.key.localeCompare(b.key));

if (doWrite) {
	const ledger = {
		$comment:
			'Announcement ledger. Regenerate with `npm run announce:rank -- --write`. Inventory and score are re-derived from data/pages.json, packages/, workers/, services/ and docs/announcement-coverage.md on every run; stage, media and pack are carried forward because the pack tooling and the owner own those.',
		generatedAt: new Date().toISOString(),
		weightsFrom: 'data/x-archive/analysis/trythreews-engagement.json',
		totals: {
			surfaces: inventory.length,
			announced: inventory.filter((r) => r.coverage === 'announced').length,
			passing: inventory.filter((r) => r.coverage === 'passing').length,
			never: inventory.filter((r) => r.coverage === 'no').length,
		},
		entries: inventory.sort((a, b) => b.score - a.score || a.key.localeCompare(b.key)),
	};
	writeFileSync(LEDGER, `${JSON.stringify(ledger, null, '\t')}\n`);
	if (!asJson) console.error(`wrote ${LEDGER}`);
}

if (asJson) {
	console.log(JSON.stringify({ ranked: ranked.slice(0, topN) }, null, 2));
} else {
	const never = inventory.filter((r) => r.coverage === 'no').length;
	console.log(`${inventory.length} shipped surfaces, ${never} never announced. Top ${Math.min(topN, ranked.length)}:\n`);
	console.log(`${'#'.padStart(3)}  ${'score'.padStart(5)}  ${'surface'.padEnd(34)} ${'kind'.padEnd(8)} signals`);
	ranked.slice(0, topN).forEach((r, i) => {
		const sig = Object.entries(r.signals)
			.filter(([, v]) => v > 0)
			.map(([k, v]) => `${k}:${v}`)
			.join(' ');
		console.log(`${String(i + 1).padStart(3)}  ${String(r.score).padStart(5)}  ${r.key.padEnd(34)} ${r.kind.padEnd(8)} ${sig}`);
	});
}