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.

feat(marketing): script the product demo capture on a reusable staging library

nirholasb593f20956ee
diff --git a/scripts/lib/demo-stage.mjs b/scripts/lib/demo-stage.mjs
new file mode 100644
index 000000000..0765ac147
--- /dev/null
+++ b/scripts/lib/demo-stage.mjs
@@ -0,0 +1,616 @@
+/**
+ * The stage a product demo is filmed on: a desktop browser, a visible mouse, an
+ * on-screen caption track, and a narrator.
+ *
+ * Where the Seeker recordings (solana-mobile/scripts/lib/seeker-panel.mjs) step
+ * frames one at a time to reproduce a phone panel exactly, this films the
+ * desktop site in REAL TIME with Playwright's own recorder. A product demo is
+ * watched for its motion: the 3D scenes streaming in, a model spinning under
+ * the cursor, a marketplace grid settling after a search. Stepped frames freeze
+ * all of that, and the pages here run WebGL on nearly every route.
+ *
+ * Nothing on screen is staged. The pointer overlay is a listener: it follows
+ * real mousemove and mousedown events dispatched into the page by Playwright,
+ * the same way a screen recorder draws the host cursor over a real session. It
+ * reports the interaction, it never stands in for one.
+ *
+ * The narration is spoken by the platform's own TTS endpoint (/api/tts/speak),
+ * so a demo of three.ws is narrated by three.ws.
+ */
+import { spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, writeFileSync, readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+
+export const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..');
+export const AUTH_STATE = path.join(ROOT, '.auth/audit-state.json');
+
+/* 1920x1080 at density 1: the frame every player, every social card, and every
+ conference screen expects, and the viewport this site's desktop layout was
+ designed against. */
+export const STAGE = { width: 1920, height: 1080 };
+export const FPS = 30;
+
+export const sleep = (ms) => new Promise((r) => setTimeout(r, Math.max(0, ms)));
+
+const easeInOutCubic = (x) => (x < 0.5 ? 4 * x * x * x : 1 - Math.pow(-2 * x + 2, 3) / 2);
+const easeOutCubic = (x) => 1 - Math.pow(1 - x, 3);
+
+/**
+ * Chromium flags for a recording.
+ *
+ * `--disable-dev-shm-usage` is not optional in a container: Docker gives
+ * /dev/shm 64 MB and these pages are enormous (the marketplace document is
+ * 23k px tall with live model-viewer instances), so the renderer either crashes
+ * or crawls, which reads on camera as the site being slow. `--hide-scrollbars`
+ * removes the headless scrollbar without changing the layout width, and the
+ * font flags keep type rendering identical between runs.
+ */
+export function launchOptions() {
+ return {
+ args: [
+ '--disable-dev-shm-usage',
+ '--hide-scrollbars',
+ '--force-color-profile=srgb',
+ '--font-render-hinting=none',
+ '--autoplay-policy=no-user-gesture-required',
+ ],
+ };
+}
+
+/** The desktop browser context a demo is filmed in. */
+export function contextOptions({ authed = false, videoDir = null } = {}) {
+ if (authed && !existsSync(AUTH_STATE)) {
+ throw new Error(`--authed needs ${path.relative(ROOT, AUTH_STATE)}; mint it with: npm run audit:web:login`);
+ }
+ return {
+ viewport: STAGE,
+ deviceScaleFactor: 1,
+ colorScheme: 'dark',
+ locale: 'en-US',
+ timezoneId: 'UTC',
+ reducedMotion: 'no-preference',
+ ...(videoDir ? { recordVideo: { dir: videoDir, size: STAGE } } : {}),
+ ...(authed ? { storageState: AUTH_STATE } : {}),
+ };
+}
+
+/**
+ * The overlay, installed into every document (first load and every client-side
+ * navigation alike). Three pieces, all `pointer-events:none` so none of them
+ * can intercept an interaction:
+ *
+ * cursor an arrow that follows real pointer events, with a click ring
+ * caption the lower third, carrying the same words the narrator speaks
+ * chapter a full-frame title card between sections
+ */
+export function installOverlay() {
+ const ID = '__demo_stage';
+ if (window.__demoStage && document.getElementById(ID)?.isConnected) return;
+
+ const build = () => {
+ const host = document.body || document.documentElement;
+ if (!host) return null;
+ let root = document.getElementById(ID);
+ if (root && root.isConnected) return root;
+ root = document.createElement('div');
+ root.id = ID;
+ root.setAttribute('aria-hidden', 'true');
+ root.style.cssText = 'position:fixed;inset:0;z-index:2147483647;pointer-events:none;'
+ + 'font-family:Inter,ui-sans-serif,system-ui,-apple-system,"Segoe UI",Roboto,sans-serif;';
+
+ const style = document.createElement('style');
+ style.textContent = `
+#${ID} .ds-cursor{position:absolute;left:0;top:0;width:26px;height:34px;opacity:0;
+ transform:translate(-2px,-2px);filter:drop-shadow(0 2px 6px rgba(0,0,0,.55));will-change:transform}
+#${ID} .ds-ring{position:absolute;left:0;top:0;width:12px;height:12px;margin:-6px 0 0 -6px;border-radius:50%;
+ border:2px solid rgba(255,255,255,.95);opacity:0;will-change:transform,opacity}
+#${ID} .ds-ring.ds-fire{animation:ds-pop .5s cubic-bezier(.2,.7,.3,1) forwards}
+@keyframes ds-pop{0%{opacity:.9;transform:scale(.5)}100%{opacity:0;transform:scale(4.6)}}
+#${ID} .ds-cap{position:absolute;left:50%;bottom:74px;transform:translateX(-50%) translateY(14px);
+ max-width:1180px;box-sizing:border-box;padding:16px 28px 18px;border-radius:18px;opacity:0;
+ background:rgba(9,9,20,.86);border:1px solid rgba(255,255,255,.14);backdrop-filter:blur(14px);
+ box-shadow:0 24px 60px rgba(0,0,0,.5);transition:opacity .32s ease,transform .32s ease}
+#${ID} .ds-cap.ds-on{opacity:1;transform:translateX(-50%) translateY(0)}
+#${ID} .ds-kick{display:block;font-size:13px;letter-spacing:.16em;text-transform:uppercase;
+ color:#8b7bff;font-weight:700;margin-bottom:7px}
+#${ID} .ds-text{display:block;font-size:25px;line-height:1.38;color:#f2f3ff;font-weight:500}
+#${ID} .ds-chap{position:absolute;inset:0;display:flex;flex-direction:column;align-items:center;
+ justify-content:center;gap:18px;background:rgba(6,6,14,.93);opacity:0;transition:opacity .5s ease;text-align:center}
+#${ID} .ds-chap.ds-on{opacity:1}
+#${ID} .ds-chap-n{font-size:15px;letter-spacing:.34em;text-transform:uppercase;color:#8b7bff;font-weight:700}
+#${ID} .ds-chap-t{font-size:78px;line-height:1.06;font-weight:800;color:#fff;letter-spacing:-.02em;max-width:1200px}
+#${ID} .ds-chap-s{font-size:24px;color:#b9bad6;max-width:900px;line-height:1.5}
+#${ID} .ds-badge{position:absolute;right:34px;top:28px;display:flex;align-items:center;gap:9px;
+ padding:9px 15px;border-radius:999px;background:rgba(9,9,20,.72);border:1px solid rgba(255,255,255,.13);
+ color:#e8e9ff;font-size:15px;font-weight:600;letter-spacing:.01em;opacity:0;transition:opacity .4s ease}
+#${ID} .ds-badge.ds-on{opacity:1}
+#${ID} .ds-dot{width:8px;height:8px;border-radius:50%;background:#5ee6a8;box-shadow:0 0 10px #5ee6a8}`;
+
+ const cursor = document.createElement('div');
+ cursor.className = 'ds-cursor';
+ cursor.innerHTML = '<svg viewBox="0 0 26 34" xmlns="http://www.w3.org/2000/svg">'
+ + '<path d="M2 1.6 L2 26.4 L8.3 20.6 L12.4 30.6 L16.6 28.8 L12.6 19.1 L21.2 18.4 Z" '
+ + 'fill="#ffffff" stroke="rgba(10,10,20,.85)" stroke-width="1.6" stroke-linejoin="round"/></svg>';
+
+ const ring = document.createElement('div');
+ ring.className = 'ds-ring';
+
+ const cap = document.createElement('div');
+ cap.className = 'ds-cap';
+ cap.innerHTML = '<span class="ds-kick"></span><span class="ds-text"></span>';
+
+ const chap = document.createElement('div');
+ chap.className = 'ds-chap';
+ chap.innerHTML = '<span class="ds-chap-n"></span><span class="ds-chap-t"></span><span class="ds-chap-s"></span>';
+
+ const badge = document.createElement('div');
+ badge.className = 'ds-badge';
+ badge.innerHTML = '<span class="ds-dot"></span><span class="ds-badge-t"></span>';
+
+ root.append(style, chap, cap, badge, cursor, ring);
+ host.appendChild(root);
+ return root;
+ };
+
+ const at = { x: window.innerWidth / 2, y: window.innerHeight / 2 };
+ const place = () => {
+ const root = document.getElementById(ID);
+ if (!root) return;
+ const cursor = root.querySelector('.ds-cursor');
+ const ring = root.querySelector('.ds-ring');
+ cursor.style.transform = `translate(${at.x - 2}px, ${at.y - 2}px)`;
+ ring.style.transform = `translate(${at.x}px, ${at.y}px)`;
+ };
+
+ /* Capture phase, so a page that stops propagation on its own handlers still
+ moves the cursor: what is drawn is exactly where the real pointer is. */
+ window.addEventListener('mousemove', (e) => {
+ at.x = e.clientX;
+ at.y = e.clientY;
+ const root = build();
+ if (!root) return;
+ root.querySelector('.ds-cursor').style.opacity = '1';
+ place();
+ }, { capture: true, passive: true });
+
+ window.addEventListener('mousedown', () => {
+ const root = build();
+ if (!root) return;
+ const ring = root.querySelector('.ds-ring');
+ ring.classList.remove('ds-fire');
+ void ring.offsetWidth;
+ ring.classList.add('ds-fire');
+ }, { capture: true, passive: true });
+
+ window.__demoStage = {
+ ensure() { build(); place(); },
+ cursor(on) {
+ const root = build();
+ if (root) root.querySelector('.ds-cursor').style.opacity = on ? '1' : '0';
+ },
+ caption(text, kicker) {
+ const root = build();
+ if (!root) return;
+ const el = root.querySelector('.ds-cap');
+ if (!text) { el.classList.remove('ds-on'); return; }
+ el.querySelector('.ds-kick').textContent = kicker || '';
+ el.querySelector('.ds-text').textContent = text;
+ el.classList.add('ds-on');
+ },
+ badge(text) {
+ const root = build();
+ if (!root) return;
+ const el = root.querySelector('.ds-badge');
+ if (!text) { el.classList.remove('ds-on'); return; }
+ el.querySelector('.ds-badge-t').textContent = text;
+ el.classList.add('ds-on');
+ },
+ chapter(n, title, subtitle) {
+ const root = build();
+ if (!root) return;
+ const el = root.querySelector('.ds-chap');
+ if (!title) { el.classList.remove('ds-on'); return; }
+ el.querySelector('.ds-chap-n').textContent = n || '';
+ el.querySelector('.ds-chap-t').textContent = title;
+ el.querySelector('.ds-chap-s').textContent = subtitle || '';
+ el.classList.add('ds-on');
+ },
+ };
+
+ if (document.readyState === 'loading') document.addEventListener('DOMContentLoaded', build, { once: true });
+ else build();
+}
+
+/**
+ * A mouse that behaves like a hand on a demo machine: it bows its path, speeds
+ * up in the middle, decelerates into the target, and pauses a beat before it
+ * clicks. Every method dispatches real input; nothing here is a synthetic
+ * event, so a click that lands on nothing fails the same way a person's would.
+ */
+export class Presenter {
+ constructor(page, { log = () => {}, seed = 11 } = {}) {
+ this.page = page;
+ this.log = log;
+ this.x = STAGE.width / 2;
+ this.y = STAGE.height * 0.62;
+ this.arc = 1;
+ let a = seed >>> 0;
+ this.rand = () => {
+ a |= 0; a = (a + 0x6D2B79F5) | 0;
+ let t = Math.imul(a ^ (a >>> 15), 1 | a);
+ t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+ return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+ };
+ }
+
+ jitter(px) { return (this.rand() * 2 - 1) * px; }
+
+ /** Re-install the overlay after a navigation and put the cursor back. */
+ async ready() {
+ await this.page.evaluate(installOverlay).catch(() => {});
+ await this.page.mouse.move(this.x, this.y);
+ }
+
+ async moveTo(x, y, { ms } = {}) {
+ const from = { x: this.x, y: this.y };
+ const dist = Math.hypot(x - from.x, y - from.y);
+ if (dist < 1) return;
+ const dur = ms ?? Math.min(1150, 260 + dist * 0.62);
+ const steps = Math.max(8, Math.round(dur / 12));
+ const bow = Math.min(70, dist * 0.13) * this.arc;
+ this.arc *= -1;
+ const mid = {
+ x: (from.x + x) / 2 + ((y - from.y) / dist) * bow,
+ y: (from.y + y) / 2 - ((x - from.x) / dist) * bow,
+ };
+ for (let i = 1; i <= steps; i += 1) {
+ const t = easeInOutCubic(i / steps);
+ const u = 1 - t;
+ const px = u * u * from.x + 2 * u * t * mid.x + t * t * x;
+ const py = u * u * from.y + 2 * u * t * mid.y + t * t * y;
+ await this.page.mouse.move(px, py);
+ await sleep(dur / steps);
+ }
+ this.x = x;
+ this.y = y;
+ await this.page.mouse.move(x, y);
+ }
+
+ /** Where on an element a person would actually aim: near the middle, not on it. */
+ async pointOn(selector, { scroll = true } = {}) {
+ const el = this.locate(selector);
+ await el.waitFor({ state: 'visible', timeout: 20_000 });
+ if (scroll) await this.bringIntoView(selector);
+ const box = await el.boundingBox();
+ if (!box) throw new Error(`${selector} has no box to aim at`);
+ return {
+ x: box.x + box.width / 2 + this.jitter(Math.min(box.width * 0.16, 26)),
+ y: box.y + box.height / 2 + this.jitter(Math.min(box.height * 0.18, 8)),
+ };
+ }
+
+ locate(selector) {
+ return typeof selector === 'string' ? this.page.locator(selector).first() : selector.first();
+ }
+
+ async hover(selector, { hold = 700 } = {}) {
+ const { x, y } = await this.pointOn(selector);
+ await this.moveTo(x, y);
+ await sleep(hold);
+ }
+
+ async click(selector, { before = 240, after = 900, expect = null, expectTimeout = 30_000 } = {}) {
+ const { x, y } = await this.pointOn(selector);
+ await this.moveTo(x, y);
+ await sleep(before);
+ await this.page.mouse.down();
+ await sleep(70);
+ await this.page.mouse.up();
+ await sleep(after);
+ if (expect) await this.page.locator(expect).first().waitFor({ state: 'visible', timeout: expectTimeout });
+ }
+
+ /** Click something only if this build of the page renders it. */
+ async clickIfPresent(selector, opts = {}) {
+ const el = this.locate(selector);
+ if (!(await el.count())) return false;
+ if (!(await el.isVisible().catch(() => false))) return false;
+ await this.click(selector, opts);
+ return true;
+ }
+
+ /** Type at a human cadence, slowing at spaces and punctuation the way people do. */
+ async type(selector, text, { cps = 15, settle = 700, clear = true } = {}) {
+ await this.click(selector, { after: 220 });
+ if (clear) {
+ await this.page.keyboard.press('ControlOrMeta+a').catch(() => {});
+ await this.page.keyboard.press('Backspace').catch(() => {});
+ }
+ const base = 1000 / cps;
+ for (const ch of text) {
+ await this.page.keyboard.type(ch);
+ let ms = base * (0.7 + this.rand() * 0.75);
+ if (ch === ' ') ms *= 1.3;
+ if (',.!?'.includes(ch)) ms *= 2;
+ await sleep(ms);
+ }
+ await sleep(settle);
+ }
+
+ async scrollState() {
+ return this.page.evaluate(() => ({
+ y: window.scrollY,
+ max: Math.max(0, document.documentElement.scrollHeight - window.innerHeight),
+ }));
+ }
+
+ /**
+ * Read down the page with the wheel, the way someone scans a page they are
+ * showing you: several notches, easing in and out, with the cursor sitting
+ * where a hand would rest.
+ */
+ async readDown(dy, { ms = 1400 } = {}) {
+ const { y: y0, max } = await this.scrollState();
+ const target = Math.max(0, Math.min(max, y0 + dy));
+ const delta = target - y0;
+ if (Math.abs(delta) < 4) return y0;
+ const steps = Math.max(10, Math.round(ms / 34));
+ let done = 0;
+ for (let i = 1; i <= steps; i += 1) {
+ const want = delta * easeInOutCubic(i / steps);
+ const step = want - done;
+ done = want;
+ await this.page.mouse.wheel(0, step);
+ await sleep(ms / steps);
+ }
+ await sleep(180);
+ return (await this.scrollState()).y;
+ }
+
+ /** Walk the whole page top to bottom in reading-sized bites. */
+ async readThrough({ budgetMs = 6000, bite = 620, pause = 520 } = {}) {
+ const started = Date.now();
+ for (let i = 0; i < 14; i += 1) {
+ if (Date.now() - started > budgetMs) break;
+ const before = (await this.scrollState()).y;
+ const after = await this.readDown(bite, { ms: 1100 });
+ if (Math.abs(after - before) < 6) break;
+ await sleep(pause);
+ }
+ }
+
+ async toTop({ ms = 900 } = {}) {
+ const { y } = await this.scrollState();
+ if (y < 8) return;
+ await this.readDown(-y, { ms });
+ }
+
+ /** Put an element in the comfortable middle band of the frame. */
+ async bringIntoView(selector, { top = 140, bottom = 260 } = {}) {
+ const el = this.locate(selector);
+ const pinned = await el.evaluate((node) => {
+ for (let n = node; n && n !== document.documentElement; n = n.parentElement) {
+ const pos = getComputedStyle(n).position;
+ if (pos === 'fixed' || pos === 'sticky') return true;
+ }
+ return false;
+ }).catch(() => false);
+ if (pinned) return;
+ const box = await el.boundingBox();
+ if (!box) return;
+ if (box.y >= top && box.y + box.height <= STAGE.height - bottom) return;
+ await this.readDown(box.y + box.height / 2 - STAGE.height * 0.42, { ms: 1000 });
+ }
+
+ /** Turn a 3D viewer by dragging it, because that is how a person turns one. */
+ async dragAcross(selector, { dx = 320, dy = 0, ms = 1300 } = {}) {
+ await this.bringIntoView(selector);
+ const box = await this.locate(selector).boundingBox();
+ if (!box) throw new Error(`${selector} has no box to drag`);
+ const x0 = box.x + box.width * 0.5 - dx / 2;
+ const y0 = box.y + Math.min(box.height * 0.55, box.height - 30) - dy / 2;
+ await this.moveTo(x0, y0);
+ await sleep(200);
+ await this.page.mouse.down();
+ const steps = Math.max(12, Math.round(ms / 16));
+ for (let i = 1; i <= steps; i += 1) {
+ const t = easeInOutCubic(i / steps);
+ await this.page.mouse.move(x0 + dx * t, y0 + dy * t);
+ await sleep(ms / steps);
+ }
+ await this.page.mouse.up();
+ this.x = x0 + dx;
+ this.y = y0 + dy;
+ await sleep(320);
+ }
+
+ /** Drag a range input from wherever it sits to a fraction of its track. */
+ async slideTo(selector, fraction, { ms = 1100 } = {}) {
+ const box = await this.locate(selector).boundingBox();
+ if (!box) throw new Error(`${selector} has no box to slide`);
+ const y = box.y + box.height / 2;
+ const from = await this.locate(selector).evaluate((el) => {
+ const min = Number(el.min || 0);
+ const max = Number(el.max || 100);
+ return max === min ? 0 : (Number(el.value) - min) / (max - min);
+ });
+ const x0 = box.x + box.width * from;
+ const x1 = box.x + box.width * Math.max(0, Math.min(1, fraction));
+ await this.moveTo(x0, y);
+ await this.page.mouse.down();
+ const steps = Math.max(10, Math.round(ms / 18));
+ for (let i = 1; i <= steps; i += 1) {
+ await this.page.mouse.move(x0 + (x1 - x0) * easeOutCubic(i / steps), y);
+ await sleep(ms / steps);
+ }
+ await this.page.mouse.up();
+ this.x = x1;
+ this.y = y;
+ await sleep(300);
+ }
+
+ async showCursor(on) {
+ await this.page.evaluate((v) => window.__demoStage?.cursor(v), on).catch(() => {});
+ }
+
+ async caption(text, kicker) {
+ await this.page.evaluate(([t, k]) => window.__demoStage?.caption(t, k), [text, kicker]).catch(() => {});
+ }
+
+ async badge(text) {
+ await this.page.evaluate((t) => window.__demoStage?.badge(t), text).catch(() => {});
+ }
+
+ async chapter(n, title, subtitle) {
+ await this.page.evaluate(([a, b, c]) => window.__demoStage?.chapter(a, b, c), [n, title, subtitle]).catch(() => {});
+ }
+}
+
+/* ── narration ──────────────────────────────────────────────────────────── */
+
+export function ffprobeDuration(file) {
+ const r = spawnSync('ffprobe', ['-v', 'error', '-show_entries', 'format=duration',
+ '-of', 'default=noprint_wrappers=1:nokey=1', file], { encoding: 'utf8' });
+ if (r.status !== 0) throw new Error(`ffprobe failed on ${file}: ${r.stderr || r.status}`);
+ return Math.round(Number(r.stdout.trim()) * 1000);
+}
+
+export function ffmpeg(argv, { quiet = true } = {}) {
+ const r = spawnSync('ffmpeg', ['-hide_banner', '-loglevel', quiet ? 'error' : 'info', '-y', ...argv],
+ { stdio: quiet ? ['ignore', 'ignore', 'inherit'] : 'inherit' });
+ if (r.error || r.status !== 0) throw new Error(`ffmpeg failed (${r.status ?? r.error?.message})`);
+}
+
+/**
+ * The voice of the demo, synthesized by the platform's own TTS lane.
+ *
+ * Clips are cached on the text, so a rerun of a tour whose script has not
+ * changed costs no synthesis at all, and a section re-recorded on its own gets
+ * exactly the audio the full run would have given it.
+ */
+export class Narrator {
+ constructor({ origin, dir, voice = 'nova', log = () => {}, enabled = true }) {
+ this.origin = origin;
+ this.dir = dir;
+ this.voice = voice;
+ this.log = log;
+ this.enabled = enabled;
+ this.clips = [];
+ this.t0 = 0;
+ mkdirSync(dir, { recursive: true });
+ }
+
+ /** A fresh timeline: called when a section's recording starts. */
+ open(t0) {
+ this.clips = [];
+ this.t0 = t0;
+ }
+
+ async synth(text) {
+ const key = createHash('sha1').update(`${this.voice}\u0000${text}`).digest('hex').slice(0, 20);
+ const file = path.join(this.dir, `${key}.wav`);
+ if (!existsSync(file)) {
+ const res = await fetch(`${this.origin}/api/tts/speak`, {
+ method: 'POST',
+ headers: { 'content-type': 'application/json' },
+ body: JSON.stringify({ text, voice: this.voice, format: 'wav' }),
+ });
+ if (!res.ok) throw new Error(`TTS ${res.status}: ${(await res.text()).slice(0, 200)}`);
+ const buf = Buffer.from(await res.arrayBuffer());
+ if (buf.length < 1024) throw new Error(`TTS returned ${buf.length} bytes for "${text.slice(0, 40)}"`);
+ writeFileSync(file, buf);
+ }
+ return { file, ms: ffprobeDuration(file) };
+ }
+
+ /**
+ * Show a line and start speaking it. Returns the wall-clock time the line
+ * finishes, so the caller can act underneath it and then wait out the rest.
+ */
+ async say(presenter, text, { kicker = '', caption = true } = {}) {
+ if (caption) await presenter.caption(text, kicker);
+ if (!this.enabled) return Date.now() + Math.min(9000, 900 + text.length * 46);
+ const { file, ms } = await this.synth(text);
+ this.clips.push({ at: Math.max(0, Date.now() - this.t0), file, ms });
+ return Date.now() + ms;
+ }
+
+ /** Hold until the current line has finished, plus a beat to breathe. */
+ async settle(until, { tail = 420 } = {}) {
+ await sleep(until - Date.now() + tail);
+ }
+
+ /**
+ * Lay every clip on a single track at the offset it was spoken at.
+ *
+ * Clips never overlap (each line is waited out before the next one starts),
+ * so the track is an exact concatenation of silence and speech rather than
+ * a mix, which keeps it sample accurate over an hour-long tour.
+ */
+ buildTrack(out, totalMs) {
+ if (!this.clips.length) return null;
+ const work = path.join(this.dir, `.track-${createHash('sha1').update(out).digest('hex').slice(0, 8)}`);
+ mkdirSync(work, { recursive: true });
+ const parts = [];
+ let cursor = 0;
+ let silences = 0;
+ const silence = (ms) => {
+ if (ms < 12) return;
+ const f = path.join(work, `sil-${silences++}.wav`);
+ ffmpeg(['-f', 'lavfi', '-t', (ms / 1000).toFixed(3),
+ '-i', 'anullsrc=r=44100:cl=mono', '-c:a', 'pcm_s16le', f]);
+ parts.push(f);
+ cursor += ms;
+ };
+ for (const clip of this.clips) {
+ silence(clip.at - cursor);
+ parts.push(clip.file);
+ cursor += clip.ms;
+ }
+ silence(Math.max(0, totalMs - cursor));
+ const list = path.join(work, 'list.txt');
+ writeFileSync(list, parts.map((p) => `file '${p.replace(/'/g, "'\\''")}'`).join('\n'));
+ ffmpeg(['-f', 'concat', '-safe', '0', '-i', list, '-c:a', 'pcm_s16le', '-ar', '44100', '-ac', '1', out]);
+ return out;
+ }
+}
+
+/* ── encoding ───────────────────────────────────────────────────────────── */
+
+/** Playwright's webm plus the narration track, muxed into a shareable mp4. */
+export function encodeSection({ webm, audio, out, fps = FPS, crf = 22 }) {
+ const argv = ['-i', webm];
+ if (audio) argv.push('-i', audio);
+ argv.push(
+ '-map', '0:v:0',
+ ...(audio ? ['-map', '1:a:0', '-c:a', 'aac', '-b:a', '128k', '-ar', '48000'] : []),
+ '-vf', `fps=${fps},format=yuv420p`,
+ '-c:v', 'libx264', '-crf', String(crf), '-preset', 'medium',
+ '-profile:v', 'high', '-level', '4.2', '-movflags', '+faststart',
+ out,
+ );
+ ffmpeg(argv);
+ return out;
+}
+
+/** Join the chapters into one film. Every part was encoded identically. */
+export function concatParts(parts, out, work) {
+ mkdirSync(work, { recursive: true });
+ const list = path.join(work, 'chapters.txt');
+ writeFileSync(list, parts.map((p) => `file '${p.replace(/'/g, "'\\''")}'`).join('\n'));
+ ffmpeg(['-f', 'concat', '-safe', '0', '-i', list, '-c', 'copy', '-movflags', '+faststart', out]);
+ return out;
+}
+
+export function mediaInfo(file) {
+ const r = spawnSync('ffprobe', ['-v', 'error', '-show_entries', 'format=duration,size',
+ '-of', 'default=noprint_wrappers=1', file], { encoding: 'utf8' });
+ const map = Object.fromEntries(r.stdout.trim().split('\n').map((l) => l.split('=')));
+ return { seconds: Number(map.duration || 0), bytes: Number(map.size || 0) };
+}
+
+export function readJson(file) {
+ return JSON.parse(readFileSync(file, 'utf8'));
+}
diff --git a/scripts/make-product-demo.mjs b/scripts/make-product-demo.mjs
new file mode 100644
index 000000000..21850551b
--- /dev/null
+++ b/scripts/make-product-demo.mjs
@@ -0,0 +1,431 @@
+#!/usr/bin/env node
+/**
+ * Films a person demoing three.ws, feature by feature, on the live site.
+ *
+ * The route is not hand-maintained: it is the same curriculum the in-product
+ * Feature Tour walks (public/tour/curriculum.json, generated from
+ * data/pages.json by scripts/build-tour.mjs), so a page that ships tomorrow is
+ * one `npm run build:tour` away from being in the video, and the narration is
+ * the page's own plain-language description rather than marketing invented
+ * here. Chapters are the curriculum's sections.
+ *
+ * Every stop is the real page on the real origin. The flagship surfaces get a
+ * hand-written act: the marketplace is really searched, an agent's model is
+ * really turned with a drag, the agent really answers the message that is typed
+ * to it, the forge really switches lanes. Every other stop is visited and read
+ * through the way a presenter scrolls a page they are showing you. If a page is
+ * broken, that shows up as a skipped stop in the run report instead of a pretty
+ * lie in the film.
+ *
+ * The voice is the platform's own TTS lane (/api/tts/speak, free NVIDIA Magpie),
+ * so three.ws narrates three.ws. Captions carry the same words.
+ *
+ * Usage:
+ * npm run demo:video # every feature, all chapters
+ * npm run demo:video -- --route=highlights # the short cut, ~23 stops
+ * npm run demo:video -- --sections=build,crypto --authed
+ * npm run demo:video -- --dry-run # print the route and exit
+ *
+ * Flags:
+ * --route=full|highlights|quick which stops (default full: every feature)
+ * --sections=a,b only these chapters (default: all, in order)
+ * --limit=n first n stops per chapter, for a smoke test
+ * --authed replay .auth/audit-state.json (signed-in surfaces)
+ * --origin= film a dev server instead of https://three.ws
+ * --out= output directory (default marketing/product-demo)
+ * --voice= TTS voice id (default nova)
+ * --no-voice caption-only, no narration track
+ * --reuse keep chapter mp4s that already exist
+ * --strict a failed stop fails the run
+ * --crf= x264 quality (default 22; lower is bigger)
+ * --dry-run print the plan, record nothing
+ */
+import { chromium } from 'playwright';
+import { existsSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import {
+ ROOT, STAGE, FPS, Presenter, Narrator, installOverlay, launchOptions, contextOptions,
+ encodeSection, concatParts, mediaInfo, readJson, sleep,
+} from './lib/demo-stage.mjs';
+
+const args = Object.fromEntries(process.argv.slice(2).map((a) => {
+ const m = a.match(/^--([^=]+)(?:=(.*))?$/);
+ return m ? [m[1], m[2] ?? true] : [a, true];
+}));
+const ORIGIN = String(args.origin || 'https://three.ws').replace(/\/$/, '');
+const OUT = path.resolve(ROOT, String(args.out || 'marketing/product-demo'));
+const WORK = path.join(OUT, '.raw');
+const VOICE = String(args.voice || 'nova');
+const CRF = Number(args.crf || 22);
+const STRICT = Boolean(args.strict);
+const LIMIT = args.limit ? Number(args.limit) : Infinity;
+const log = (...m) => console.log('[demo]', ...m);
+
+/* ── the script ─────────────────────────────────────────────────────────── */
+
+const curriculum = readJson(path.join(ROOT, 'public/tour/curriculum.json'));
+
+const OPENING = 'This is three dot w s, the 3D agent layer of the internet. Over the next few chapters '
+ + 'I am going to walk the whole platform with you, feature by feature, on the live site. Everything you '
+ + 'are about to see is the real product answering in real time.';
+const CLOSING = 'That is the whole platform: build a body, give it a brain, put it to work, and let it '
+ + 'hold its own wallet. Everything in this film is live at three dot w s right now.';
+
+/* A caption is read, narration is heard, and neither wants a raw slug. */
+const say = (text) => String(text || '')
+ .replace(/three\.ws/gi, 'three dot w s')
+ .replace(/\bx402\b/gi, 'x four oh two')
+ .replace(/\bERC-8004\b/gi, 'E R C 8004')
+ /* build-tour.mjs writes the page descriptions with colons where the source
+ copy had a dash, which a synthesizer reads as a full stop mid-clause. */
+ .replace(/(\w):\s+(?=[a-z])/g, '$1, ')
+ .replace(/\s+/g, ' ')
+ .trim();
+
+/** The stop's own description, with the guide's lead-in sentence removed. */
+function describe(stop) {
+ const n = String(stop.narration || '');
+ const i = n.indexOf(stop.title);
+ const rest = i >= 0 ? n.slice(i + stop.title.length) : n;
+ return rest.replace(/^[.?!,:;\s]+/, '').trim();
+}
+
+/** A quick stop gets one sentence; a highlight gets the whole line. */
+function lineFor(stop) {
+ const desc = describe(stop);
+ if (stop.highlight) return `${stop.title}. ${desc}`.slice(0, 320);
+ const first = desc.split(/(?<=[.!?:])\s+/)[0] || desc;
+ const short = first.length > 108 ? `${first.slice(0, 105).replace(/[\s,;:]+\S*$/, '')}.` : first;
+ return `${stop.title}. ${short}`;
+}
+
+/* ── acts ───────────────────────────────────────────────────────────────── */
+
+/*
+ * A hand-written act for a flagship surface. Each one is a real interaction
+ * with the real page: nothing here fakes a result, and a selector that has gone
+ * missing surfaces as a skipped stop rather than a still frame.
+ */
+const ACTS = {
+ '/': async (p) => {
+ await p.hover('.nav-trigger:has-text("Build")', { hold: 1300 });
+ await p.hover('.nav-trigger:has-text("Discover")', { hold: 1300 });
+ await p.page.keyboard.press('Escape').catch(() => {});
+ await p.readDown(700, { ms: 1500 });
+ await p.type('#hero-forge-input', 'a brass astrolabe on a walnut stand', { cps: 17, settle: 900 });
+ await p.readThrough({ budgetMs: 5000 });
+ },
+
+ '/what-is': async (p) => { await p.readThrough({ budgetMs: 7000 }); },
+
+ '/discover': async (p) => {
+ await p.type('input[placeholder*="Search by name"]', 'agent', { cps: 13, settle: 1400 });
+ await p.clickIfPresent('button.tws-lc-chip:has-text("All agents")', { after: 1600 });
+ await p.readDown(760, { ms: 1500 });
+ },
+
+ '/marketplace': async (p) => {
+ await p.type('#market-search', 'knight', { cps: 12, settle: 1600 });
+ await p.clickIfPresent('button.market-chip:has-text("Avatars")', { after: 1800 });
+ await p.readDown(820, { ms: 1600 });
+ await p.hover('#market-grid a.title.card-profile-link', { hold: 900 });
+ },
+
+ '/create-agent': async (p) => {
+ await p.readThrough({ budgetMs: 6000 });
+ },
+
+ '/create/prompt': async (p) => {
+ await p.type('#prompt', 'a medieval knight in battered steel plate, weathered red cloak', { cps: 16, settle: 900 });
+ const fired = await p.clickIfPresent('#generate-btn', { after: 2200 });
+ if (!fired) return;
+ /* The real pipeline, at its real pace. The film watches the progress the
+ page reports for as long as the budget allows and then moves on; the
+ build keeps running on the server either way. */
+ const deadline = Date.now() + 42_000;
+ while (Date.now() < deadline) {
+ if (await p.page.locator('.step[data-step="done"].active').isVisible().catch(() => false)) break;
+ if (await p.page.locator('#build-error.show').isVisible().catch(() => false)) break;
+ await sleep(700);
+ }
+ if (await p.page.locator('#done-model').isVisible().catch(() => false)) {
+ await sleep(2500);
+ await p.dragAcross('#done-model', { dx: 260, ms: 1300 });
+ }
+ },
+
+ '/forge': async (p) => {
+ await p.type('#prompt', 'a worn leather armchair, studio lit', { cps: 16, settle: 700 });
+ await p.clickIfPresent('#tab-image', { after: 1500 });
+ await p.clickIfPresent('#tab-sketch', { after: 1500 });
+ await p.clickIfPresent('#tab-text', { after: 1200 });
+ await p.readDown(900, { ms: 1600 });
+ await p.clickIfPresent('button.showcase-sort-btn:has-text("Top this week")', { after: 1800 });
+ },
+
+ '/pose': async (p) => {
+ await p.dragAcross('#pose-canvas', { dx: 320, ms: 1400 });
+ await p.clickIfPresent('button.mode-btn:has-text("IK")', { after: 1200 });
+ await p.type('#pose-bone-search', 'arm', { cps: 10, settle: 1200 });
+ },
+
+ '/playground': async (p) => {
+ await p.dragAcross('#viewer', { dx: 340, ms: 1400 });
+ await p.clickIfPresent('button.pill:has-text("Midnight")', { after: 1400 });
+ await p.clickIfPresent('button.pill:has-text("Warm")', { after: 1400 });
+ await p.clickIfPresent('#copy-embed', { after: 1400 });
+ },
+
+ '/brain': async (p) => {
+ await p.type('#brDescribeInput', 'a sharp crypto trader who speaks in plain English', { cps: 16, settle: 900 });
+ await p.clickIfPresent('#brBuildPersonaBtn', { after: 3200 });
+ await p.clickIfPresent('button.br-tab:has-text("Playground")', { after: 2000 });
+ },
+
+ '/chat': async (p) => {
+ const box = 'textarea[placeholder*="Type a message"]';
+ if (!(await p.page.locator(box).count())) return;
+ await p.type(box, 'What can you build for me?', { cps: 15, settle: 500 });
+ await p.page.keyboard.press('Enter');
+ await p.page.waitForTimeout(1200);
+ for (let i = 0; i < 22; i += 1) {
+ const answered = await p.page.evaluate(() => document.body.innerText.length).catch(() => 0);
+ if (answered > 1200) break;
+ await sleep(700);
+ }
+ await sleep(3500);
+ },
+
+ '/agents': async (p) => {
+ await p.type('#ag-search', 'trader', { cps: 12, settle: 1500 });
+ await p.readDown(700, { ms: 1400 });
+ },
+
+ '/pay': async (p) => {
+ await p.clickIfPresent('button.chain-tab:has-text("BNB")', { after: 1500 });
+ await p.clickIfPresent('button.chain-tab:has-text("Solana")', { after: 1500 });
+ await p.type('#prompt', 'validate https://example.com', { cps: 16, settle: 900 });
+ await p.readThrough({ budgetMs: 4000 });
+ },
+
+ '/launch': async (p) => { await p.readThrough({ budgetMs: 7000 }); },
+
+ '/markets': async (p) => {
+ await p.readDown(900, { ms: 1600 });
+ await p.clickIfPresent('button.nw-star', { after: 1200 });
+ await p.readDown(1100, { ms: 1700 });
+ },
+
+ '/holo': async (p) => {
+ await p.clickIfPresent('button.hs-chip:has-text("$THREE")', { after: 1400 });
+ await p.slideTo('#peelRange', 0.72, { ms: 1500 });
+ await p.slideTo('#peelRange', 0.12, { ms: 1200 });
+ },
+
+ '/labs': async (p) => {
+ await p.clickIfPresent('button.labs-filter:has-text("x402")', { after: 1600 });
+ await p.clickIfPresent('button.labs-filter:has-text("All")', { after: 1200 });
+ await p.readDown(820, { ms: 1600 });
+ },
+
+ '/diorama': async (p) => {
+ await p.clickIfPresent('button.dio-chip', { after: 1600 });
+ await p.type('#compose-input', 'a cliffside lighthouse in a storm', { cps: 16, settle: 900 });
+ await p.readDown(600, { ms: 1400 });
+ },
+
+ '/walk': async (p) => {
+ await p.readDown(760, { ms: 1500 });
+ await p.clickIfPresent('#wl-copy', { after: 1400 });
+ await p.readThrough({ budgetMs: 4500 });
+ },
+
+ '/profile': async (p) => { await p.readThrough({ budgetMs: 6000 }); },
+};
+
+/**
+ * Every other stop: arrive, let the page come alive, and read down it the way a
+ * presenter scrolls a page they are showing you, pausing on whatever the
+ * curriculum says the page is about.
+ */
+async function genericAct(p, stop) {
+ const target = (stop.targets || [])[0];
+ if (target) {
+ const el = p.page.locator(target).first();
+ if (await el.count().catch(() => 0) && await el.isVisible().catch(() => false)) {
+ await p.hover(target, { hold: 700 }).catch(() => {});
+ }
+ }
+ await p.readThrough({ budgetMs: stop.highlight ? 7000 : 3400, bite: 640, pause: 380 });
+}
+
+/* ── route ──────────────────────────────────────────────────────────────── */
+
+const ROUTE = String(args.route || 'full');
+/* The curriculum carries every stop once, with the onboarding track repeating
+ pages the sections already hold; the film visits each feature exactly once. */
+function routeStops() {
+ const stops = curriculum.stops.filter((s) => s.section !== 'onboarding');
+ if (ROUTE === 'full') return stops;
+ if (ROUTE === 'highlights') return stops.filter((s) => s.highlight);
+ throw new Error(`unknown --route=${ROUTE}; use full or highlights`);
+}
+
+const wantSections = args.sections
+ ? String(args.sections).split(',').map((s) => s.trim()).filter(Boolean)
+ : null;
+
+const chapters = [];
+for (const section of curriculum.sections) {
+ if (section.id === 'onboarding') continue;
+ if (wantSections && !wantSections.includes(section.id)) continue;
+ const stops = routeStops().filter((s) => s.section === section.id).slice(0, LIMIT);
+ if (stops.length) chapters.push({ ...section, stops });
+}
+if (!chapters.length) throw new Error('the route selected no stops');
+
+const totalStops = chapters.reduce((n, c) => n + c.stops.length, 0);
+log(`route ${ROUTE}: ${totalStops} stops across ${chapters.length} chapters against ${ORIGIN}`);
+for (const c of chapters) log(` ${c.title.padEnd(12)} ${String(c.stops.length).padStart(3)} stops`);
+
+if (args['dry-run']) {
+ for (const c of chapters) {
+ console.log(`\n## ${c.title}`);
+ for (const s of c.stops) console.log(` ${s.highlight ? '*' : ' '} ${s.path.padEnd(34)} ${lineFor(s)}`);
+ }
+ process.exit(0);
+}
+
+/* ── filming ────────────────────────────────────────────────────────────── */
+
+mkdirSync(OUT, { recursive: true });
+mkdirSync(WORK, { recursive: true });
+const voiceDir = path.join(WORK, 'voice');
+const narrator = new Narrator({ origin: ORIGIN, dir: voiceDir, voice: VOICE, log, enabled: !args['no-voice'] });
+
+const skipped = [];
+const parts = [];
+const browser = await chromium.launch(launchOptions());
+
+try {
+ for (const [ci, chapter] of chapters.entries()) {
+ const out = path.join(OUT, `three-ws-demo-${String(ci + 1).padStart(2, '0')}-${chapter.id}.mp4`);
+ if (args.reuse && existsSync(out)) {
+ log(`chapter ${chapter.title}: reusing ${path.basename(out)}`);
+ parts.push(out);
+ continue;
+ }
+
+ const videoDir = path.join(WORK, `video-${chapter.id}`);
+ rmSync(videoDir, { recursive: true, force: true });
+ mkdirSync(videoDir, { recursive: true });
+
+ const ctx = await browser.newContext(contextOptions({ authed: Boolean(args.authed), videoDir }));
+ ctx.setDefaultTimeout(45_000);
+ await ctx.addInitScript(installOverlay);
+ const page = await ctx.newPage();
+ const t0 = Date.now();
+ narrator.open(t0);
+ const p = new Presenter(page, { log });
+
+ log(`chapter ${ci + 1}/${chapters.length}: ${chapter.title} (${chapter.stops.length} stops)`);
+
+ /* Open on the chapter's first page so the title card sits over the real
+ product rather than over a blank tab. */
+ const first = chapter.stops[0];
+ await page.goto(`${ORIGIN}${first.path}`, { waitUntil: 'domcontentloaded', timeout: 60_000 }).catch(() => {});
+ await page.waitForTimeout(2600);
+ await p.ready();
+ await p.chapter(`Chapter ${ci + 1}`, chapter.title, say(chapter.intro).slice(0, 190));
+ if (ci === 0) {
+ const until = await narrator.say(p, say(OPENING), { kicker: 'three.ws' });
+ await narrator.settle(until);
+ } else {
+ await sleep(3000);
+ }
+ await p.chapter('', '', '');
+ await sleep(700);
+
+ for (const [si, stop] of chapter.stops.entries()) {
+ const at = `${si + 1}/${chapter.stops.length}`;
+ try {
+ if (new URL(page.url()).pathname !== stop.path) {
+ await page.goto(`${ORIGIN}${stop.path}`, { waitUntil: 'domcontentloaded', timeout: 45_000 });
+ }
+ await p.ready();
+ await p.badge(`three.ws${stop.path === '/' ? '' : stop.path}`);
+ /* The line starts while the page is still settling, so the film
+ never sits in silence waiting for a 3D scene to stream in. */
+ const until = await narrator.say(p, say(lineFor(stop)), { kicker: chapter.title });
+ await page.waitForLoadState('load', { timeout: 20_000 }).catch(() => {});
+ await sleep(stop.highlight ? 1800 : 900);
+ await p.ready();
+ const act = ACTS[stop.path] || ((ctxp) => genericAct(ctxp, stop));
+ await act(p, stop);
+ await narrator.settle(until);
+ log(` ${at} ${stop.path}`);
+ } catch (err) {
+ const why = String(err.message).split('\n')[0].slice(0, 140);
+ skipped.push({ chapter: chapter.id, path: stop.path, why });
+ log(` ${at} ${stop.path} SKIPPED: ${why}`);
+ if (STRICT) throw err;
+ }
+ }
+
+ if (ci === chapters.length - 1) {
+ await p.caption('', '');
+ await p.chapter('three.ws', 'Build one yourself', 'three.ws');
+ const until = await narrator.say(p, say(CLOSING), { kicker: '' });
+ await narrator.settle(until, { tail: 1200 });
+ }
+
+ const spanMs = Date.now() - t0;
+ await ctx.close();
+ const webm = await page.video().path();
+ log(` chapter recorded in ${(spanMs / 1000).toFixed(0)}s, encoding`);
+ const audio = narrator.buildTrack(path.join(WORK, `audio-${chapter.id}.wav`), spanMs);
+ encodeSection({ webm, audio, out, fps: FPS, crf: CRF });
+ rmSync(videoDir, { recursive: true, force: true });
+ const info = mediaInfo(out);
+ log(` wrote ${path.relative(ROOT, out)} (${info.seconds.toFixed(0)}s, ${(info.bytes / 1e6).toFixed(0)} MB)`);
+ parts.push(out);
+ }
+} finally {
+ await browser.close();
+}
+
+const full = path.join(OUT, 'three-ws-demo.mp4');
+if (parts.length > 1) {
+ concatParts(parts, full, WORK);
+ log(`wrote ${path.relative(ROOT, full)}`);
+} else if (parts.length === 1) {
+ log(`single chapter: ${path.relative(ROOT, parts[0])}`);
+}
+
+const film = existsSync(full) ? full : parts[0];
+const info = film ? mediaInfo(film) : { seconds: 0, bytes: 0 };
+const manifest = {
+ generatedAt: new Date().toISOString(),
+ origin: ORIGIN,
+ route: ROUTE,
+ authed: Boolean(args.authed),
+ voice: args['no-voice'] ? null : VOICE,
+ stage: `${STAGE.width}x${STAGE.height}@${FPS}`,
+ stops: totalStops,
+ recorded: totalStops - skipped.length,
+ seconds: Math.round(info.seconds),
+ bytes: info.bytes,
+ film: film ? path.relative(ROOT, film) : null,
+ chapters: parts.map((f, i) => ({
+ id: chapters[i].id,
+ title: chapters[i].title,
+ file: path.relative(ROOT, f),
+ seconds: Math.round(mediaInfo(f).seconds),
+ })),
+ skipped,
+};
+writeFileSync(path.join(OUT, 'demo-manifest.json'), `${JSON.stringify(manifest, null, '\t')}\n`);
+
+log(`${manifest.recorded}/${totalStops} stops recorded, ${skipped.length} skipped`);
+if (skipped.length) for (const s of skipped) log(` skipped ${s.path}: ${s.why}`);
+log(`film: ${manifest.film} (${Math.round(info.seconds / 60)}m ${Math.round(info.seconds % 60)}s, ${(info.bytes / 1e6).toFixed(0)} MB)`);