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.7 KB
Raw Blame
#!/usr/bin/env node
// capture-guide-shots.mjs — capture every tutorial screenshot from the real,
// running product.
//
// Tutorial media on three.ws is never hand-cropped and never mocked. Each
// picture in docs/tutorials/*.md is declared as a "shot" in data/guide-shots.json
// (which page, which element, which controls to point at) and produced by this
// script driving the live site in a real browser. Re-running it after a UI
// change regenerates every picture, so the guides cannot drift away from the
// product they document.
//
// Usage:
//   node scripts/capture-guide-shots.mjs                     # capture all, against production
//   node scripts/capture-guide-shots.mjs --base http://localhost:3000
//   node scripts/capture-guide-shots.mjs --only forge-compose,create-hub
//   node scripts/capture-guide-shots.mjs --list
//
// Writes PNGs to public/docs/img/guides/ and a per-shot result report to
// data/guide-shots.capture.json. Exits non-zero if any shot failed, so a
// selector that no longer exists is a loud failure rather than a stale picture.

import { chromium } from 'playwright';
import { readFileSync, writeFileSync, mkdirSync, statSync } from 'node:fs';
import { dirname, join, resolve } from 'node:path';
import { fileURLToPath } from 'node:url';

const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
const MANIFEST = join(ROOT, 'data', 'guide-shots.json');
const REPORT = join(ROOT, 'data', 'guide-shots.capture.json');
const OUT_DIR = join(ROOT, 'public', 'docs', 'img', 'guides');

// ── args ─────────────────────────────────────────────────────────────────────

function arg(name, fallback = null) {
	const i = process.argv.indexOf(`--${name}`);
	return i > -1 && process.argv[i + 1] ? process.argv[i + 1] : fallback;
}
const BASE = (arg('base', 'https://three.ws')).replace(/\/+$/, '');
const ONLY = arg('only') ? new Set(arg('only').split(',').map(s => s.trim())) : null;
const LIST = process.argv.includes('--list');

// ── the frame: what a capture must never contain ─────────────────────────────
// Site chrome that follows the user around (the onboarding pill, the corner
// stack, discovery cards, an in-progress tour) is real product, but it is not
// what any given guide step is about, and it moves between runs. Suppressing it
// keeps a shot about its subject and keeps re-captures byte-stable.

const SUPPRESS_CSS = `
  #page-loading,
  #tws-corner-stack,
  .twg-root, .twg-modal-overlay,
  .tws-disc-card, .tws-disc-new,
  .tour-overlay, .tour-bubble, .tour-spotlight,
  [data-tws-capture-hide] { display: none !important; }
  *, *::before, *::after {
    transition: none !important;
    animation-duration: 0s !important;
    animation-delay: 0s !important;
    caret-color: transparent !important;
  }
  html { scrollbar-width: none !important; }
  ::-webkit-scrollbar { display: none !important; }
`;

// ── annotation: numbered callouts drawn over the live page ───────────────────
// Rendered into the page itself (not composited afterwards) so the pins sit in
// the same pixel space as the UI they point at, at whatever the real layout is.

const ANNOTATE = (callouts) => {
  const ACCENT = '#7c5cff';
  document.querySelectorAll('[data-tws-callout]').forEach(n => n.remove());
  const missing = [];
  const layer = document.createElement('div');
  layer.setAttribute('data-tws-callout', 'layer');
  Object.assign(layer.style, {
    position: 'absolute', inset: '0', pointerEvents: 'none', zIndex: '2147483000',
  });
  document.body.appendChild(layer);

  callouts.forEach((c, i) => {
    const el = document.querySelector(c.selector);
    if (!el) { missing.push(c.selector); return; }
    const r = el.getBoundingClientRect();
    if (!r.width || !r.height) { missing.push(c.selector); return; }
    const top = r.top + window.scrollY;
    const left = r.left + window.scrollX;

    const ring = document.createElement('div');
    Object.assign(ring.style, {
      position: 'absolute',
      top: (top - 4) + 'px', left: (left - 4) + 'px',
      width: (r.width + 8) + 'px', height: (r.height + 8) + 'px',
      border: '2px solid ' + ACCENT,
      borderRadius: (parseFloat(getComputedStyle(el).borderRadius) || 8) + 6 + 'px',
      boxShadow: '0 0 0 4px rgba(124,92,255,0.22), 0 0 22px rgba(124,92,255,0.38)',
      pointerEvents: 'none',
    });
    layer.appendChild(ring);

    const pin = document.createElement('div');
    pin.textContent = String(c.n || i + 1);
    // Nudge the pin inside the viewport when the target hugs the left edge.
    const pinLeft = Math.max(4, left - 15);
    Object.assign(pin.style, {
      position: 'absolute',
      top: (top - 15) + 'px', left: pinLeft + 'px',
      width: '30px', height: '30px', borderRadius: '999px',
      background: ACCENT, color: '#fff',
      font: '700 15px/30px Inter, system-ui, sans-serif',
      textAlign: 'center',
      boxShadow: '0 2px 10px rgba(0,0,0,0.45), 0 0 0 3px rgba(10,10,14,0.85)',
      pointerEvents: 'none',
    });
    layer.appendChild(pin);
  });
  return missing;
};

// Freeze anything still moving. A three.ws page is full of live media: a
// model-viewer orbits by default, videos loop, canvases redraw. Playwright waits
// for the capture target to hold still, so an un-frozen 3D viewer never settles
// and the shot times out instead of failing honestly.
const FREEZE = () => {
  document.querySelectorAll('model-viewer').forEach(mv => {
    mv.removeAttribute('auto-rotate');
    try { mv.pause?.(); } catch {}
  });
  document.querySelectorAll('video').forEach(v => { try { v.pause(); } catch {} });
};

// A transparent, absolutely-positioned rect used as the screenshot target. Using
// an element (rather than a raw clip box) keeps padding unambiguous: Playwright
// scrolls it into view and captures exactly its bounds.
const FRAME = ({ selector, pad }) => {
  document.getElementById('tws-capture-frame')?.remove();
  const el = document.querySelector(selector);
  if (!el) return null;
  const r = el.getBoundingClientRect();
  if (!r.width || !r.height) return null;
  const docW = Math.max(document.documentElement.scrollWidth, window.innerWidth);
  const docH = Math.max(document.documentElement.scrollHeight, window.innerHeight);
  const x = Math.max(0, r.left + window.scrollX - pad);
  const y = Math.max(0, r.top + window.scrollY - pad);
  const w = Math.min(docW - x, r.width + pad * 2);
  const h = Math.min(docH - y, r.height + pad * 2);
  return { x: Math.round(x), y: Math.round(y), w: Math.round(w), h: Math.round(h) };
};

// ── prep steps: drive the UI into the state a guide step describes ────────────

async function runPrep(page, prep) {
	for (const step of prep) {
		if (step.click) {
			const loc = page.locator(step.click).first();
			await loc.waitFor({ state: 'visible', timeout: 15000 });
			await loc.click({ timeout: 15000 });
		}
		if (step.fill) {
			const loc = page.locator(step.fill.selector).first();
			await loc.waitFor({ state: 'visible', timeout: 15000 });
			await loc.fill(step.fill.value, { timeout: 15000 });
		}
		if (step.scrollTo) {
			await page.locator(step.scrollTo).first()
				.scrollIntoViewIfNeeded({ timeout: 15000 });
		}
		// waitFor lets a shot depend on real work finishing (a generation
		// completing, a model loading) instead of a guessed sleep, so a picture
		// captioned "your finished model" actually contains one.
		if (step.waitFor) {
			await page.locator(step.waitFor).first()
				.waitFor({ state: 'visible', timeout: step.timeout ?? 240000 });
		}
		if (step.wait) await page.waitForTimeout(step.wait);
	}
}

// ── main ─────────────────────────────────────────────────────────────────────

const manifest = JSON.parse(readFileSync(MANIFEST, 'utf8'));
const defaults = manifest.defaults || {};
const shots = manifest.shots.filter(s => !ONLY || ONLY.has(s.id));

const tutorialsOf = s => (s.placements || []).map(p => p.tutorial);

if (LIST) {
	for (const s of manifest.shots) {
		console.log(`${s.id.padEnd(24)} ${s.url.padEnd(16)} -> ${tutorialsOf(s).join(', ')}`);
	}
	const covered = new Set(manifest.shots.flatMap(tutorialsOf));
	console.log(`\n${manifest.shots.length} shots, ${covered.size} tutorials covered`);
	process.exit(0);
}

if (!shots.length) {
	console.error('No shots matched. Use --list to see available ids.');
	process.exit(1);
}

mkdirSync(OUT_DIR, { recursive: true });
console.log(`Capturing ${shots.length} shot(s) against ${BASE}\n`);

const browser = await chromium.launch({
	args: ['--use-gl=angle', '--use-angle=swiftshader', '--enable-unsafe-swiftshader',
		'--hide-scrollbars', '--force-color-profile=srgb'],
});

const results = [];

for (const shot of shots) {
	const started = Date.now();
	const viewport = shot.viewport || defaults.viewport || { width: 1440, height: 900 };
	const settle = shot.settle ?? defaults.settle ?? 3500;
	const outPath = join(OUT_DIR, `${shot.id}.png`);
	const rel = `/docs/img/guides/${shot.id}.png`;

	// A fresh context per shot: no cookie, storage, or tour state carries over,
	// so every capture is what a first-time visitor actually sees.
	const ctx = await browser.newContext({
		viewport,
		deviceScaleFactor: shot.scale ?? defaults.scale ?? 2,
		colorScheme: 'dark',
		reducedMotion: 'reduce',
		userAgent: defaults.userAgent,
	});
	const page = await ctx.newPage();
	const consoleErrors = [];
	page.on('pageerror', e => consoleErrors.push(String(e.message).slice(0, 200)));

	try {
		const res = await page.goto(BASE + shot.url, {
			waitUntil: 'domcontentloaded', timeout: 60000,
		});
		const status = res?.status() ?? 0;
		if (status >= 400) throw new Error(`HTTP ${status} for ${shot.url}`);

		await page.addStyleTag({ content: SUPPRESS_CSS });
		await page.waitForTimeout(settle);
		try { await page.evaluate(() => document.fonts?.ready); } catch {}

		if (shot.prep?.length) {
			await runPrep(page, shot.prep);
			await page.waitForTimeout(shot.prepSettle ?? 900);
		}

		// Re-apply after prep: a click can mount fresh chrome.
		await page.addStyleTag({ content: SUPPRESS_CSS });
		await page.evaluate(FREEZE);

		let missing = [];
		if (shot.callouts?.length) {
			missing = await page.evaluate(ANNOTATE, shot.callouts);
		}
		if (missing.length) {
			throw new Error(`callout target(s) not found: ${missing.join(', ')}`);
		}

		let dims = null;
		if (shot.clip) {
			dims = await page.evaluate(FRAME, { selector: shot.clip, pad: shot.pad ?? 20 });
			if (!dims) throw new Error(`clip target not found or zero-size: ${shot.clip}`);
			// A document-coordinate clip rather than an element screenshot: these
			// pages stream content in, so waiting for an element's box to hold
			// still can never succeed on a page that is legitimately alive.
			await page.screenshot({
				path: outPath, timeout: 90000, animations: 'disabled', fullPage: true,
				clip: { x: dims.x, y: dims.y, width: dims.w, height: dims.h },
			});
		} else {
			await page.screenshot({
				path: outPath, timeout: 90000, animations: 'disabled',
				fullPage: !!shot.fullPage,
			});
			dims = { w: viewport.width, h: viewport.height };
		}

		const bytes = statSync(outPath).size;
		if (bytes < 2048) throw new Error(`suspiciously small image (${bytes} bytes)`);

		results.push({
			id: shot.id, tutorials: tutorialsOf(shot), url: shot.url, path: rel,
			ok: true, bytes, width: dims.w, height: dims.h,
			ms: Date.now() - started, pageErrors: consoleErrors.slice(0, 3),
		});
		console.log(`  ok   ${shot.id.padEnd(30)} ${String(Math.round(bytes / 1024)).padStart(5)} KB  ${dims.w}x${dims.h}`);
	} catch (err) {
		results.push({
			id: shot.id, tutorials: tutorialsOf(shot), url: shot.url, path: rel,
			ok: false, error: String(err.message).slice(0, 300), ms: Date.now() - started,
		});
		console.log(`  FAIL ${shot.id.padEnd(30)} ${String(err.message).slice(0, 90)}`);
	} finally {
		await ctx.close();
	}
}

await browser.close();

const failed = results.filter(r => !r.ok);
// Captured captions echo page copy, and the repo bans em/en dashes in
// committed bytes, so scrub them at the boundary.
writeFileSync(REPORT, JSON.stringify({
	base: BASE,
	shots: results.length,
	failed: failed.length,
	results,
}, null, '\t').replace(/ [\u2013\u2014] /g, ': ').replace(/[\u2013\u2014]/g, '-') + '\n');

console.log(`\n${results.length - failed.length}/${results.length} captured -> public/docs/img/guides/`);
console.log(`report: data/guide-shots.capture.json`);
if (failed.length) {
	console.error(`\n${failed.length} shot(s) failed:`);
	for (const f of failed) console.error(`  ${f.id}: ${f.error}`);
	process.exit(1);
}