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
/**
* capture-tutorial-media.mjs
*
* Turns the `figure:` directives written inside docs/tutorials/*.md into real
* captured media, and records what it captured in public/tutorial-media.json.
*
* Why this exists: 68 tutorials shipped with zero images. Every honest way to
* fix that is a capture pipeline, because the only images we are allowed to
* publish are ones the platform actually produced. Nothing here draws, mocks,
* or stock-sources an image: a page figure is a real Chromium screenshot of the
* real deployed page, and a model figure is a real render returned by our own
* /api/render/glb endpoint.
*
* ── Author syntax (plain markdown, no custom parser) ─────────────────────────
* A figure is an ordinary markdown image whose src uses the `figure:` scheme,
* so an unprocessed file still reads correctly in any markdown viewer:
*
* 
* 
* 
*
* Kinds:
* page:<path> screenshot of https://three.ws<path> in a real browser
* img:<path> an image already committed under public/, adopted as a figure
* glb:<path> PNG returned by GET /api/render/glb?glbUrl=…
* live:<path> an interactive <model-viewer>, mounted at runtime. No capture
* happens here; it is listed in the manifest so the checker can
* confirm the GLB itself resolves.
*
* Options ride along as query params on the directive:
* page: w, h (viewport, default 1280x760), sel (clip to a CSS selector),
* full=1 (full-page), settle (ms to wait after load, default 3500),
* theme (dark|light, default dark)
* glb: w, h (default 1200x900), bg (default transparent)
* live: orbit (camera-orbit string passed to <model-viewer>)
*
* ── Usage ────────────────────────────────────────────────────────────────────
* npm run tutorials:media capture anything missing
* npm run tutorials:media -- --force re-capture everything
* npm run tutorials:media -- --check capture nothing; exit 1 on a gap
* npm run tutorials:media -- --only embed-in-30-seconds
* BASE_URL=http://localhost:3000 npm run tutorials:media
*
* Output: public/docs/img/<collection>/<slug>/<name>-<hash>.webp plus a manifest
* carrying intrinsic width/height and a blurred inline placeholder, so the page
* reserves the exact box before the byte arrives and never shifts layout.
*/
import { chromium } from 'playwright';
import sharp from 'sharp';
import { readFileSync, writeFileSync, readdirSync, mkdirSync, existsSync, rmSync } from 'node:fs';
import { execFileSync } from 'node:child_process';
import { createHash } from 'node:crypto';
import { resolve, dirname } from 'node:path';
import { fileURLToPath } from 'node:url';
const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
const BASE_URL = (process.env.BASE_URL || 'https://three.ws').replace(/\/$/, '');
// Where a reader goes when they click through a figure. This is deliberately
// NOT the capture base: figures are usually shot against a local server running
// the commit being shipped, and a doorway into localhost is a dead link.
const SITE_URL = (process.env.SITE_URL || 'https://three.ws').replace(/\/$/, '');
const MANIFEST = resolve(ROOT, 'public/tutorial-media.json');
// Every markdown collection whose figures this script captures. Both viewers
// (pages/tutorial.html and pages/recipe.html) load the same tutorial-figures.js
// and read the same manifest, so a collection is just a directory plus the
// folder its assets land in. Adding a third is one more row.
const COLLECTIONS = [
{ name: 'tutorials', dir: resolve(ROOT, 'docs/tutorials'), img: 'docs/img/tutorials' },
{ name: 'cookbook', dir: resolve(ROOT, 'docs/cookbook'), img: 'docs/img/cookbook' },
];
const argv = process.argv.slice(2);
const has = (name) => argv.includes(`--${name}`);
const opt = (name, fallback) => {
const i = argv.indexOf(`--${name}`);
return i !== -1 && argv[i + 1] ? argv[i + 1] : fallback;
};
const FORCE = has('force');
const CHECK_ONLY = has('check');
const ONLY = opt('only', '');
const QUALITY = Math.max(40, Math.min(100, Number(opt('quality', 82)) || 82));
const FIGURE_RE = /!\[([^\]]*)\]\((figure:[^)\s]+)\)/g;
const KINDS = new Set(['page', 'glb', 'live', 'img']);
// ── Parse ────────────────────────────────────────────────────────────────────
/** Split `figure:page:/forge?sel=.x` into its kind, target and options. */
function parseDirective(raw) {
const body = raw.slice('figure:'.length);
const colon = body.indexOf(':');
if (colon === -1) return { error: 'a figure needs a kind, as in figure:page:/create' };
const kind = body.slice(0, colon);
if (!KINDS.has(kind)) return { error: `unknown figure kind "${kind}" (use page, glb, img or live)` };
const rest = body.slice(colon + 1);
const q = rest.indexOf('?');
const target = q === -1 ? rest : rest.slice(0, q);
const params = new URLSearchParams(q === -1 ? '' : rest.slice(q + 1));
if (!target.startsWith('/')) return { error: `figure target must be a site-absolute path, got "${target}"` };
return { kind, target, params };
}
function collectDirectives() {
const found = [];
const problems = [];
for (const collection of COLLECTIONS) {
if (!existsSync(collection.dir)) continue;
const files = readdirSync(collection.dir)
.filter((f) => f.endsWith('.md'))
.filter((f) => !ONLY || f === `${ONLY}.md`);
for (const file of files) {
const slug = file.replace(/\.md$/, '');
const md = readFileSync(resolve(collection.dir, file), 'utf8');
for (const match of md.matchAll(FIGURE_RE)) {
const [, alt, raw] = match;
const parsed = parseDirective(raw);
if (parsed.error) {
problems.push(`${file}: ${parsed.error}`);
continue;
}
if (!alt.trim()) {
problems.push(`${file}: ${raw} has an empty caption. Every figure needs one, for the caption and the alt text.`);
continue;
}
found.push({ collection: collection.name, img: collection.img, slug, alt: alt.trim(), raw, ...parsed });
}
}
}
return { found, problems };
}
/** A short, stable name so a re-run overwrites rather than accumulates. */
function assetName(entry) {
const stem =
entry.target
.replace(/^\//, '')
.replace(/\.[a-z0-9]+$/i, '')
.replace(/[^a-z0-9]+/gi, '-')
.replace(/^-+|-+$/g, '')
.toLowerCase()
.slice(0, 40) || 'root';
const hash = createHash('sha256').update(entry.raw).digest('hex').slice(0, 8);
return `${entry.kind}-${stem}-${hash}`;
}
// ── Capture ──────────────────────────────────────────────────────────────────
async function capturePage(browser, entry) {
const width = Math.max(320, Math.min(1920, Number(entry.params.get('w')) || 1280));
const height = Math.max(240, Math.min(1600, Number(entry.params.get('h')) || 760));
const settle = Math.max(0, Number(entry.params.get('settle')) || 3500);
const selector = entry.params.get('sel');
const fullPage = entry.params.get('full') === '1';
const theme = entry.params.get('theme') === 'light' ? 'light' : 'dark';
const context = await browser.newContext({
viewport: { width, height },
deviceScaleFactor: 2,
colorScheme: theme,
reducedMotion: 'reduce',
});
// The site reads its theme from localStorage before first paint, so setting
// it as an init script is the only way to capture the light theme honestly.
await context.addInitScript(`try{localStorage.setItem('twx_theme',${JSON.stringify(theme)})}catch(e){}`);
// Floating chrome is not the UI a tutorial is teaching, and most of it
// rotates its contents per visit, so leaving it in makes every re-capture a
// spurious diff. Hiding it with a stylesheet installed before first paint
// beats removing the nodes after load: the i18n switcher and the corner
// stack both mount asynchronously, after any fixed settle has elapsed, so a
// removal pass races them and loses on the slower pages.
await context.addInitScript(`(function(){
var css = '#cookie-banner,.cookie-banner,[data-role="consent"],.newsletter-toast,'
+ '#tws-corner-stack,.twx-i18n-fab,lang-switcher,.walk-c2w-fx,.nav-skip,'
+ '.tour-overlay,.tour-spotlight,.tour-bubble'
+ '{display:none !important}';
function put(){ var s=document.createElement('style'); s.textContent=css; (document.head||document.documentElement).appendChild(s); }
if (document.head) put(); else document.addEventListener('DOMContentLoaded', put);
})();`);
// Every first-run coach tour on the platform gates on `tour:<id>:done`, and a
// capture browser is always a first visit, so every figure of a touring page
// would otherwise be a photo of the tour instead of the feature. Answering
// "already seen" is what a returning reader's browser says, and it suppresses
// the tour before it mounts rather than racing to remove it afterwards.
await context.addInitScript(`(function(){
try {
var real = localStorage.getItem.bind(localStorage);
localStorage.getItem = function(key){ return /^tour:.*:done$/.test(key) ? '1' : real(key); };
} catch (e) {}
})();`);
const page = await context.newPage();
try {
const url = `${BASE_URL}${entry.target}`;
const res = await page.goto(url, { waitUntil: 'domcontentloaded', timeout: 45000 });
if (res && res.status() >= 400) throw new Error(`${url} returned HTTP ${res.status()}`);
await page.waitForTimeout(settle);
// The stylesheet above covers the chrome we know by name. Anything else
// still pinned to a viewport corner at capture time is chrome too.
await page.evaluate(() => {
for (const el of document.querySelectorAll('body > *')) {
if (getComputedStyle(el).position !== 'fixed') continue;
const r = el.getBoundingClientRect();
if (r.width > 0 && r.width < 420 && r.bottom > window.innerHeight - 220) el.remove();
}
});
await page.waitForTimeout(400);
// A page driving a render loop never reaches the idle state the default
// screenshot path waits for, so a 3D figure times out at exactly the
// moment it looks best. Freezing CSS animations and giving the shot a
// real budget is what makes the WebGL surfaces capturable at all.
const shotOpts = { type: 'png', animations: 'disabled', timeout: 120000 };
let shot;
if (selector) {
const el = await page.waitForSelector(selector, { timeout: 15000, state: 'visible' });
shot = await el.screenshot(shotOpts);
} else {
shot = await page.screenshot({ ...shotOpts, fullPage });
}
return shot;
} finally {
await context.close();
}
}
/**
* Adopt an image that already lives in public/ into the figure system.
*
* Some real platform output is a file before it is ever a URL: a still rendered
* from a model a recipe generated, committed alongside that recipe. Those bytes
* are as real as a fresh capture, and without this kind the only way to show one
* is a bare markdown <img> with no caption, no placeholder and no lightbox. This
* gives it the same figure treatment as everything else.
*
* It reads from disk only. A missing file is a hard failure, never a silent gap.
*/
async function captureLocalImage(entry) {
const path = resolve(ROOT, 'public', entry.target.replace(/^\//, ''));
if (!existsSync(path)) {
throw new Error(`no such image in public/: ${entry.target}`);
}
const buf = readFileSync(path);
if (buf.length < 100) throw new Error(`${entry.target} is ${buf.length} bytes, which is not an image`);
return buf;
}
async function captureGlb(entry) {
const width = Math.max(64, Math.min(2048, Number(entry.params.get('w')) || 1200));
const height = Math.max(64, Math.min(2048, Number(entry.params.get('h')) || 900));
const background = entry.params.get('bg') || 'transparent';
// The renderer fetches the mesh server-side, so the GLB has to be reachable
// from outside this machine. Capturing against a local server is normal here;
// pointing the renderer at that local URL is not, and it 400s.
const glbUrl = `${SITE_URL}${entry.target}`;
const url = `${BASE_URL}/api/render/glb?glbUrl=${encodeURIComponent(glbUrl)}&width=${width}&height=${height}&background=${encodeURIComponent(background)}`;
const res = await fetch(url, { signal: AbortSignal.timeout(120000) });
if (!res.ok) {
const detail = await res.text().catch(() => '');
throw new Error(`render/glb returned HTTP ${res.status} for ${entry.target} ${detail.slice(0, 200)}`);
}
const buf = Buffer.from(await res.arrayBuffer());
if (buf.length < 1000) throw new Error(`render/glb returned ${buf.length} bytes for ${entry.target}, which is not an image`);
return buf;
}
/** Confirm a live figure's model actually resolves, so the page never mounts a dead viewer. */
async function verifyLive(entry) {
const url = `${BASE_URL}${entry.target}`;
const res = await fetch(url, { method: 'GET', headers: { range: 'bytes=0-64' }, signal: AbortSignal.timeout(30000) });
if (!res.ok) throw new Error(`${url} returned HTTP ${res.status}`);
return null;
}
/** Encode to webp, and derive the inline placeholder that holds the layout. */
async function encode(png, outPath) {
const image = sharp(png);
const meta = await image.metadata();
// Retina captures are 2x; publish at half so the intrinsic size matches the
// CSS box and the browser still has the denser pixels to sample from.
const width = meta.width || 1200;
const height = meta.height || 800;
await sharp(png).webp({ quality: QUALITY, effort: 5 }).toFile(outPath);
const placeholder = await sharp(png)
.resize(20, null, { fit: 'inside' })
.blur(1.2)
.webp({ quality: 40 })
.toBuffer();
return {
width,
height,
placeholder: `data:image/webp;base64,${placeholder.toString('base64')}`,
};
}
/** The revision the captures were taken from, or null outside a git checkout. */
function headCommit() {
try {
return execFileSync('git', ['rev-parse', 'HEAD'], { cwd: ROOT, encoding: 'utf8' }).trim() || null;
} catch {
return null;
}
}
// ── Run ──────────────────────────────────────────────────────────────────────
async function main() {
const { found, problems } = collectDirectives();
if (problems.length) {
for (const p of problems) console.error(` bad figure ${p}`);
console.error(`\ncapture-tutorial-media: ${problems.length} malformed figure directive(s). Fix the markdown.`);
process.exit(1);
}
const previous = existsSync(MANIFEST) ? JSON.parse(readFileSync(MANIFEST, 'utf8')) : { figures: {} };
const prevFigures = previous.figures || {};
// One entry per unique directive: the same figure may be reused across
// tutorials and must not be captured, or stored, twice.
const byDirective = new Map();
for (const entry of found) {
if (!byDirective.has(entry.raw)) byDirective.set(entry.raw, { ...entry, slugs: new Set() });
byDirective.get(entry.raw).slugs.add(entry.slug);
}
const entries = [...byDirective.values()];
console.log(`capture-tutorial-media: ${entries.length} figure(s) across ${new Set(found.map((f) => f.slug)).size} document(s), base ${BASE_URL}`);
if (CHECK_ONLY) {
const missing = entries.filter((e) => e.kind !== 'live' && !prevFigures[e.raw]);
const orphaned = entries.filter((e) => {
const rec = prevFigures[e.raw];
return rec && rec.src && !existsSync(resolve(ROOT, 'public', rec.src.replace(/^\//, '')));
});
for (const e of missing) console.error(` uncaptured ${e.raw} (in ${[...e.slugs].join(', ')})`);
for (const e of orphaned) console.error(` file gone ${e.raw} (in ${[...e.slugs].join(', ')})`);
if (missing.length || orphaned.length) {
console.error('\ncapture-tutorial-media --check failed. Run `npm run tutorials:media` to capture the gaps.');
process.exit(1);
}
console.log('capture-tutorial-media: every figure has its media. OK');
return;
}
let browser = null;
const needsBrowser = entries.some((e) => e.kind === 'page' && (FORCE || !prevFigures[e.raw]));
if (needsBrowser) browser = await chromium.launch({ args: ['--no-sandbox', '--disable-dev-shm-usage'] });
// A scoped run (--only) sees just one document's directives, and a run where
// some captures fail sees fewer still. Writing `figures` fresh would then
// publish a manifest missing every figure this run did not look at, and the
// prune below would delete their files. Carry the prior manifest forward and
// let this run overwrite only what it actually re-captured.
const partialRun = Boolean(ONLY);
const figures = partialRun ? { ...prevFigures } : {};
let captured = 0;
let reused = 0;
const failures = [];
try {
for (const entry of entries) {
const slugs = [...entry.slugs].sort();
const name = assetName(entry);
const rel = `${entry.img}/${slugs[0]}/${name}.webp`;
const outPath = resolve(ROOT, 'public', rel);
const prior = prevFigures[entry.raw];
if (entry.kind === 'live') {
try {
await verifyLive(entry);
figures[entry.raw] = {
kind: 'live',
model: entry.target,
orbit: entry.params.get('orbit') || null,
source: `${SITE_URL}${entry.target}`,
collection: entry.collection,
docs: slugs,
};
console.log(` live ${entry.target}`);
} catch (err) {
failures.push(`${entry.raw}: ${err.message}`);
}
continue;
}
if (!FORCE && prior && prior.src && existsSync(resolve(ROOT, 'public', prior.src.replace(/^\//, '')))) {
figures[entry.raw] = { ...prior, collection: entry.collection, docs: slugs };
reused += 1;
continue;
}
try {
const png =
entry.kind === 'page'
? await capturePage(browser, entry)
: entry.kind === 'img'
? await captureLocalImage(entry)
: await captureGlb(entry);
mkdirSync(dirname(outPath), { recursive: true });
const { width, height, placeholder } = await encode(png, outPath);
figures[entry.raw] = {
kind: entry.kind,
src: `/${rel}`,
width,
height,
placeholder,
source: `${SITE_URL}${entry.target}`,
collection: entry.collection,
docs: slugs,
};
captured += 1;
console.log(` wrote /${rel} ${width}x${height}`);
} catch (err) {
failures.push(`${entry.raw}: ${err.message}`);
console.error(` FAIL ${entry.raw}\n ${err.message}`);
}
}
} finally {
if (browser) await browser.close();
}
// Drop assets whose directive no longer exists, so the folder tracks the
// markdown instead of growing forever. Only a full sweep may prune: a scoped
// run has not read the directives that justify the other files, so to it
// every one of them looks orphaned.
if (!partialRun && !failures.length) {
const live = new Set(Object.values(figures).map((f) => f.src).filter(Boolean));
for (const rec of Object.values(prevFigures)) {
if (!rec.src || live.has(rec.src)) continue;
const stale = resolve(ROOT, 'public', rec.src.replace(/^\//, ''));
if (existsSync(stale)) {
rmSync(stale);
console.log(` pruned /${rec.src.replace(/^\//, '')}`);
}
}
} else if (failures.length) {
console.log(' skipped pruning: this run had failures, so an absent figure may just be one that did not capture.');
}
const payload = {
$comment: 'GENERATED by scripts/capture-tutorial-media.mjs. Do not edit; run `npm run tutorials:media`.',
base: BASE_URL,
site: SITE_URL,
// The commit the product was on when these figures were shot. A figure is
// only honest about a screen that existed at a known revision, so the
// manifest carries that revision instead of leaving readers to guess.
commit: headCommit(),
capturedAt: new Date().toISOString(),
figures: Object.fromEntries(Object.entries(figures).sort(([a], [b]) => a.localeCompare(b))),
};
mkdirSync(dirname(MANIFEST), { recursive: true });
writeFileSync(MANIFEST, `${JSON.stringify(payload, null, '\t')}\n`);
console.log(`capture-tutorial-media: ${captured} captured, ${reused} reused, ${Object.keys(figures).length} in manifest`);
if (failures.length) {
console.error(`\ncapture-tutorial-media: ${failures.length} figure(s) failed:`);
for (const f of failures) console.error(` ${f}`);
process.exit(1);
}
}
main().catch((err) => {
console.error(`capture-tutorial-media: ${err.stack || err.message}`);
process.exit(1);
});