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(ops): drive the selfie flow in a browser and catch a truncated asset before users do

nirholas5000f8a6bafe
diff --git a/.gitignore b/.gitignore
index 033060cfc..8b842a6b8 100644
--- a/.gitignore
+++ b/.gitignore
@@ -616,3 +616,4 @@ public/_payload-check/
# Atomic-write scratch files from scripts/i18n-translate.mjs
public/locales/*.tmp-*
+scripts/.selfie-verify/
diff --git a/docs/ops/gcp-production.md b/docs/ops/gcp-production.md
index 3a2387b59..b73deade4 100644
--- a/docs/ops/gcp-production.md
+++ b/docs/ops/gcp-production.md
@@ -678,6 +678,59 @@ proxy + Memorystore + connector. The `upstash-redis-rest-token` secret and the
serving hostname without either widening the bucket policy to match or
redirecting it here too.
+### A truncated asset can sit in the CDN and hang every browser (2026-09-11)
+
+Cloud CDN held one copy of `/vendor/mediapipe/wasm/vision_wasm_internal.wasm`
+that carried `content-length: 11153617` (the identity length) with a
+brotli-compressed body and no `content-encoding` header. A client that reads
+that response waits forever for eight megabytes that never arrive.
+
+It only reproduced with the exact `Accept-Encoding` a browser sends:
+
+```bash
+# healthy
+curl -s -o /dev/null -w '%{size_download} %{time_total}\n' \
+ -H 'Accept-Encoding: br' https://three.ws/vendor/mediapipe/wasm/vision_wasm_internal.wasm
+
+# the bug: bytes stop arriving, the request never completes
+curl -s -o /dev/null -w '%{size_download} %{time_total}\n' \
+ -H 'Accept-Encoding: gzip, deflate, br, zstd' \
+ https://three.ws/vendor/mediapipe/wasm/vision_wasm_internal.wasm
+```
+
+The Cloud Run origin served the same URL correctly under every encoding, so the
+bad variant was created and cached at the edge, not by the container. A
+cache-busting query string also served correctly, which is how you tell a
+poisoned object from a broken build.
+
+**Symptom at the product level:** `/create/selfie` sat on "Processing your
+face..." indefinitely and never sent the reconstruction request, because the
+capture gates await MediaPipe and MediaPipe's loader has no deadline. Nothing
+errored, nothing retried, and no page check caught it: a page sweep reads HTML,
+not the largest binary on the site.
+
+**Recovery**, one path, not a global purge:
+
+```bash
+gcloud compute url-maps invalidate-cdn-cache three-ws-lb \
+ --path '/vendor/mediapipe/wasm/vision_wasm_internal.wasm' \
+ --project aerial-vehicle-466722-p5
+```
+
+**Detection:** `npm run check:asset-encoding` walks the largest compressible
+files under `public/`, requests each from the live site with a browser's
+`Accept-Encoding`, reads every body to completion, and fails on a length that
+disagrees with the bytes delivered. Run it after a deploy; it is the only check
+that would have caught this.
+
+**Client-side hardening:** `src/shared/mediapipe-assets.js` now prefers our own
+vendored copy unless the origin definitively lacks the file (a probe that
+merely times out no longer sends the runtime to a public CDN), shares one probe
+across all callers, and bounds every vision-model load with
+`withVisionDeadline`. A stalled load now degrades to the unrefined photo after
+15 seconds instead of hanging the flow. `npm run verify:selfie -- --stall-vision`
+reproduces the hostile case end to end.
+
### Client geo header (analytics country column)
`api/_lib/client-geo.js` resolves a visitor's country from an edge geo header
diff --git a/package.json b/package.json
index 1cd2af6cf..7b561e8cb 100644
--- a/package.json
+++ b/package.json
@@ -270,6 +270,7 @@
"audit:web": "node scripts/page-audit.mjs",
"audit:garments": "node scripts/audit-garments.mjs",
"audit:web:login": "node scripts/page-audit.mjs --login",
+ "verify:selfie": "node scripts/verify-selfie-flow.mjs",
"audit:web:provision": "node scripts/provision-audit-account.mjs",
"snapshot:authed": "node scripts/page-snapshot.mjs --authed",
"ui:review": "node scripts/ui-review.mjs",
@@ -389,6 +390,7 @@
"check:evm-rpc": "node --env-file=.env scripts/probe-evm-rpc.mjs --chain 1 --ens",
"awal:pin": "node scripts/update-awal-version.mjs",
"smoke:prod": "node scripts/check-pages.mjs --base https://three.ws",
+ "check:asset-encoding": "node scripts/check-asset-encoding.mjs",
"probe:generation": "node scripts/probe-generation-suite.mjs --base https://three.ws",
"event:watch": "node scripts/event-watch.mjs",
"event:capacity": "node scripts/play-capacity-smoke.mjs",
diff --git a/scripts/check-asset-encoding.mjs b/scripts/check-asset-encoding.mjs
new file mode 100644
index 000000000..aea2d785c
--- /dev/null
+++ b/scripts/check-asset-encoding.mjs
@@ -0,0 +1,133 @@
+#!/usr/bin/env node
+// Catches a static asset whose declared length disagrees with the bytes a
+// browser actually receives.
+//
+// On 2026-09-11 the CDN held a variant of the 11 MB MediaPipe WASM runtime
+// that carried `content-length: 11153617` (the uncompressed size) with a
+// brotli-compressed body and no `content-encoding` header. Every browser that
+// advertises zstd alongside br, which is every current Chrome and Edge, waited
+// forever for eight megabytes that were never coming. curl with a plain
+// `Accept-Encoding: br` saw a perfectly healthy response, and so did every
+// page check we run, because a page check reads HTML, not the largest binary
+// on the site. /create/selfie hung at "Processing your face..." for as long as
+// anyone was willing to wait.
+//
+// npm run check:asset-encoding
+// node scripts/check-asset-encoding.mjs --base https://three.ws --min-bytes=500000
+//
+// What it does: finds the largest compressible files under public/, requests
+// each one from the live site with the exact Accept-Encoding a browser sends,
+// reads the body to completion under a deadline, and fails when the bytes
+// received do not match what the response promised (or when the read never
+// finishes).
+
+import { readdir, stat } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const PUBLIC_DIR = path.join(ROOT, 'public');
+// What a current Chrome sends. The zstd token is the one that shook the bug
+// loose, so it stays in the string verbatim.
+const BROWSER_ACCEPT_ENCODING = 'gzip, deflate, br, zstd';
+const COMPRESSIBLE = new Set(['.wasm', '.js', '.mjs', '.json', '.css', '.svg', '.html', '.txt', '.map']);
+
+// Accepts both `--base=x` and `--base x`, because both forms read naturally on
+// a command line and a silently mis-parsed base URL is a confusing failure.
+const args = new Map();
+for (let i = 0; i < process.argv.length - 2; i++) {
+ const raw = process.argv[i + 2];
+ if (!raw.startsWith('--')) continue;
+ const [key, ...rest] = raw.slice(2).split('=');
+ if (rest.length) { args.set(key, rest.join('=')); continue; }
+ const next = process.argv[i + 3];
+ args.set(key, next && !next.startsWith('--') ? next : 'true');
+}
+
+const base = (args.get('base') || 'https://three.ws').replace(/\/$/, '');
+const minBytes = Number(args.get('min-bytes') || 400_000);
+const limit = Number(args.get('limit') || 12);
+const timeoutMs = Number(args.get('timeout') || 30_000);
+
+async function* walk(dir) {
+ for (const entry of await readdir(dir, { withFileTypes: true })) {
+ const full = path.join(dir, entry.name);
+ if (entry.isDirectory()) yield* walk(full);
+ else if (entry.isFile()) yield full;
+ }
+}
+
+async function candidates() {
+ const found = [];
+ for await (const file of walk(PUBLIC_DIR)) {
+ if (!COMPRESSIBLE.has(path.extname(file).toLowerCase())) continue;
+ const { size } = await stat(file);
+ if (size < minBytes) continue;
+ found.push({ size, url: `${base}/${path.relative(PUBLIC_DIR, file).split(path.sep).join('/')}` });
+ }
+ return found.sort((a, b) => b.size - a.size).slice(0, limit);
+}
+
+async function check({ url, size }) {
+ const started = Date.now();
+ let res;
+ try {
+ res = await fetch(url, {
+ headers: { 'accept-encoding': BROWSER_ACCEPT_ENCODING, 'user-agent': 'three-ws-asset-check' },
+ signal: AbortSignal.timeout(timeoutMs),
+ });
+ } catch (err) {
+ return { url, size, ok: false, reason: `request failed: ${err.name === 'TimeoutError' ? `no response in ${timeoutMs}ms` : err.message}` };
+ }
+ if (!res.ok) return { url, size, ok: false, reason: `HTTP ${res.status}` };
+
+ // Node's fetch decodes content-encoding transparently, so the decoded byte
+ // count is what a browser would end up holding. Reading it to completion is
+ // the whole point: a truncated body only reveals itself here.
+ let received = 0;
+ try {
+ for await (const chunk of res.body) received += chunk.length;
+ } catch (err) {
+ const ms = Date.now() - started;
+ return { url, size, ok: false, reason: `body never finished (${received} of ${size} bytes in ${ms}ms): ${err.message}` };
+ }
+
+ const encoding = res.headers.get('content-encoding');
+ const declared = Number(res.headers.get('content-length') || 0);
+ // An identity response must declare exactly what it sends. A compressed one
+ // declares the compressed length, which is smaller by design.
+ if (!encoding && declared && declared !== received) {
+ return { url, size, ok: false, reason: `content-length ${declared} but ${received} bytes arrived, with no content-encoding` };
+ }
+ // A size difference against the working copy is usually deploy skew (this
+ // worktree is ahead of the running revision), not corruption, so it reports
+ // rather than fails. Corruption shows up above, as a body that never ends.
+ const note = received === size ? null : `live copy is ${received} bytes, this worktree has ${size}`;
+ return { url, size, ok: true, ms: Date.now() - started, encoding: encoding || 'identity', note };
+}
+
+const assets = await candidates();
+if (!assets.length) {
+ console.log(`\n nothing under public/ is both compressible and at least ${minBytes} bytes.\n`);
+ process.exit(0);
+}
+
+console.log(`\n ${assets.length} asset(s) against ${base}, as a browser asks for them\n`);
+const results = [];
+for (const asset of assets) {
+ const result = await check(asset);
+ results.push(result);
+ const name = result.url.replace(base, '');
+ console.log(result.ok
+ ? ` ok ${name} (${(result.size / 1048576).toFixed(1)} MB ${result.encoding}, ${result.ms}ms)`
+ : ` FAIL ${name}\n ${result.reason}`);
+ if (result.note) console.log(` note: ${result.note}`);
+}
+
+const failed = results.filter((r) => !r.ok);
+if (failed.length) {
+ console.error(`\n ${failed.length} asset(s) do not serve cleanly. If the origin is healthy, the CDN is holding a bad copy:\n` +
+ ` gcloud compute url-maps invalidate-cdn-cache three-ws-lb --path '<path>' --project aerial-vehicle-466722-p5\n`);
+ process.exit(1);
+}
+console.log(`\n every asset arrived intact.\n`);
diff --git a/scripts/verify-selfie-flow.mjs b/scripts/verify-selfie-flow.mjs
new file mode 100644
index 000000000..705dcd07f
--- /dev/null
+++ b/scripts/verify-selfie-flow.mjs
@@ -0,0 +1,278 @@
+#!/usr/bin/env node
+// Drives https://three.ws/create/selfie end to end in a real browser: uploads a
+// real photograph into the frontal slot, submits it, and follows the job until
+// the avatar engine returns a GLB or fails. Nothing here calls the API behind
+// the page's back, so the client-side capture gates, the reconstruct call, the
+// poll loop and the viewer all get exercised the way a visitor exercises them.
+//
+// npm run verify:selfie # generates a portrait, runs it
+// npm run verify:selfie -- --photo=me.jpg # uses a photo you already have
+// npm run verify:selfie -- --origin=http://localhost:3000
+// npm run verify:selfie -- --stall-vision # regression: hang MediaPipe's
+// # runtime and prove the pipeline
+// # still submits without it
+//
+// The reconstruct endpoint requires a session, so the run replays the QA
+// storage state at .auth/audit-state.json. Mint it first with
+// `npm run audit:web:login`. Without a photo, one is generated through the
+// platform's own free text-to-image lane (POST /api/v1/ai/image, five free
+// images per day per IP, no payment), because the reconstruction worker's only
+// hard rejection is a frame with no detectable face.
+//
+// Exit codes: 0 the avatar built, 1 the flow broke (the reason is printed and
+// screenshots land in the output directory), 2 the run could not start.
+
+import { chromium } from 'playwright';
+import { mkdir, writeFile, readFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const AUTH_STATE = path.join(ROOT, '.auth', 'audit-state.json');
+const DEFAULT_ORIGIN = 'https://three.ws';
+const PORTRAIT_PROMPT =
+ 'a photorealistic passport-style portrait photograph of a smiling adult person ' +
+ 'facing the camera directly, neutral grey background, even soft studio lighting, ' +
+ 'sharp focus, head and shoulders';
+
+const args = new Map(
+ process.argv.slice(2).map((raw) => {
+ const [key, ...rest] = raw.replace(/^--/, '').split('=');
+ return [key, rest.length ? rest.join('=') : 'true'];
+ })
+);
+
+const origin = (args.get('origin') || DEFAULT_ORIGIN).replace(/\/$/, '');
+const outDir = path.resolve(ROOT, args.get('out') || 'scripts/.selfie-verify');
+const buildTimeoutMs = Number(args.get('timeout') || 10 * 60 * 1000);
+const stallVision = args.get('stall-vision') === 'true';
+
+const log = (msg) => console.log(` ${msg}`);
+function bail (code, msg) {
+ console.error(`\n ${msg}\n`);
+ process.exit(code);
+}
+
+// A generated portrait is a real photograph as far as the pipeline is
+// concerned: the same JPEG bytes a phone would hand it, through the same lane
+// the platform already serves to agents.
+async function generatePortrait () {
+ log('no --photo given, generating one through /api/v1/ai/image');
+ const res = await fetch(`${origin}/api/v1/ai/image`, {
+ method: 'POST',
+ headers: { 'content-type': 'application/json' },
+ body: JSON.stringify({ prompt: PORTRAIT_PROMPT, aspect_ratio: '1:1' }),
+ });
+ const payload = await res.json().catch(() => ({}));
+ if (!res.ok || !payload.url) {
+ bail(2, `the image lane returned ${res.status}: ${JSON.stringify(payload).slice(0, 300)}`);
+ }
+ const image = await fetch(payload.url);
+ if (!image.ok) bail(2, `could not download the generated portrait: ${image.status}`);
+ const file = path.join(outDir, 'portrait.jpg');
+ await writeFile(file, Buffer.from(await image.arrayBuffer()));
+ log(`portrait: ${payload.provider} / ${payload.model} -> ${file}`);
+ return file;
+}
+
+await mkdir(outDir, { recursive: true });
+
+const photo = args.get('photo') ? path.resolve(ROOT, args.get('photo')) : await generatePortrait();
+if (!existsSync(photo)) bail(2, `no such photo: ${photo}`);
+if (!existsSync(AUTH_STATE)) {
+ bail(2, `no QA session at ${AUTH_STATE}. Run: npm run audit:web:login`);
+}
+
+const browser = await chromium.launch({ headless: args.get('headed') !== 'true' });
+const context = await browser.newContext({
+ storageState: AUTH_STATE,
+ viewport: { width: 1280, height: 900 },
+ permissions: [],
+});
+
+// The QA session is minted against production. Running the same flow against a
+// dev server (which proxies /api to production) needs that cookie on the local
+// origin too, or every call is anonymous and reconstruct answers 401.
+if (!origin.includes('three.ws')) {
+ const state = JSON.parse(await readFile(AUTH_STATE, 'utf8'));
+ const session = (state.cookies || []).find((c) => c.name.endsWith('sid'));
+ if (session) {
+ const { hostname } = new URL(origin);
+ await context.addCookies([{
+ name: session.name,
+ value: session.value,
+ domain: hostname,
+ path: '/',
+ secure: true,
+ httpOnly: true,
+ sameSite: 'Lax',
+ }]);
+ log(`replayed ${session.name} onto ${origin}`);
+ }
+}
+
+// Regression harness for the 2026-09-11 stall: with MediaPipe's runtime
+// unreachable the capture gates and the refine pass lose their models, and the
+// pipeline has to submit the unrefined frame instead of waiting forever.
+if (stallVision) {
+ await context.route('**/vision_wasm_internal.wasm', () => {});
+ await context.route('**/*.tflite', () => {});
+ log('vision runtime stalled on purpose (nothing will answer those requests)');
+}
+// The page tells its own story through selfie:* CustomEvents. Recording them
+// from an init script means the run observes the real pipeline rather than
+// guessing from DOM side effects (#build-model ships with a placeholder src,
+// so "an element has a model" is not evidence that anything was built).
+await context.addInitScript(() => {
+ window.__selfieEvents = [];
+ for (const name of ['selfie:photo', 'selfie:quality', 'selfie:preview', 'selfie:submit',
+ 'selfie:build', 'selfie:building', 'selfie:progress', 'selfie:done',
+ 'selfie:build-error', 'selfie:needs-byok']) {
+ document.addEventListener(name, (ev) => {
+ const detail = ev.detail || {};
+ window.__selfieEvents.push({
+ name,
+ at: Date.now(),
+ detail: {
+ ...detail,
+ // A refined frame arrives as a multi-megabyte data URL. Keep the
+ // fact, drop the payload.
+ ...(detail.dataUrl ? { dataUrl: `<${detail.dataUrl.length} bytes>` } : {}),
+ },
+ });
+ });
+ }
+});
+
+const page = await context.newPage();
+
+const consoleErrors = [];
+const failedRequests = [];
+const apiCalls = [];
+page.on('console', (msg) => {
+ if (msg.type() === 'error') consoleErrors.push(msg.text().slice(0, 300));
+});
+page.on('requestfailed', (req) => {
+ failedRequests.push(`${req.method()} ${req.url().slice(0, 160)}: ${req.failure()?.errorText}`);
+});
+page.on('response', async (res) => {
+ const url = res.url();
+ if (!url.includes('/api/avatars/')) return;
+ const entry = { status: res.status(), url: url.replace(origin, '') };
+ if (!res.ok()) entry.body = (await res.text().catch(() => '')).slice(0, 300);
+ apiCalls.push(entry);
+ log(` ${entry.status} ${entry.url}${entry.body ? ` ${entry.body}` : ''}`);
+});
+
+const started = Date.now();
+log(`opening ${origin}/create/selfie`);
+await page.goto(`${origin}/create/selfie`, { waitUntil: 'domcontentloaded', timeout: 60_000 });
+
+const signedIn = await page.evaluate(async () => {
+ const res = await fetch('/api/auth/me', { credentials: 'include' });
+ if (!res.ok) return null;
+ const data = await res.json().catch(() => null);
+ return data?.user?.email || data?.email || (data?.user ? 'session' : null);
+});
+if (!signedIn) {
+ await browser.close();
+ bail(2, 'the saved session is not authenticated at /api/auth/me. Re-run: npm run audit:web:login');
+}
+log(`signed in as ${signedIn}`);
+
+const input = page.locator('input[data-slot-input="frontal"]');
+await input.waitFor({ state: 'attached', timeout: 30_000 });
+await input.setInputFiles(photo);
+log('frontal photo attached, waiting for the capture gates');
+
+const submit = page.locator('#submit-btn');
+await submit.waitFor({ state: 'visible', timeout: 30_000 });
+try {
+ await page.waitForFunction(() => !document.getElementById('submit-btn')?.disabled, null, { timeout: 90_000 });
+} catch {
+ const notice = (await page.locator('#quality-notice .qn-text').textContent().catch(() => '')) || '';
+ await page.screenshot({ path: path.join(outDir, 'gate-blocked.png'), fullPage: true });
+ await browser.close();
+ bail(1, `the capture gates never enabled the submit button. Quality notice: ${notice.trim() || '(none)'}`);
+}
+log('gates passed, submitting');
+await submit.click();
+
+// Wait on the pipeline's own terminal events. selfie:done carries the avatar
+// id the job produced; selfie:build-error carries the message the user is
+// shown. Anything else at the deadline is a stall, and the last progress label
+// says where it stalled.
+const outcome = await page.evaluate(async (timeout) => {
+ const started = Date.now();
+ const events = () => window.__selfieEvents || [];
+ const last = (name) => [...events()].reverse().find((e) => e.name === name);
+ return await new Promise((resolve) => {
+ const timer = setInterval(() => {
+ const done = last('selfie:done');
+ if (done) {
+ clearInterval(timer);
+ resolve({ state: 'built', detail: done.detail?.avatarId || '', ms: Date.now() - started, events: events() });
+ return;
+ }
+ const failed = last('selfie:build-error') || last('selfie:needs-byok');
+ if (failed) {
+ clearInterval(timer);
+ resolve({ state: 'error', detail: failed.detail?.message || failed.name, ms: Date.now() - started, events: events() });
+ return;
+ }
+ if (Date.now() - started > timeout) {
+ clearInterval(timer);
+ // Read what the visitor can actually see. #build-status-text belongs
+ // to the build view and holds "Processing your face..." from the
+ // moment the page loads, so quoting it while the capture step is
+ // still on screen invents a stage the flow never reached.
+ const visibleStep = [...document.querySelectorAll('.step')]
+ .find((el) => el.offsetParent !== null)?.dataset?.step || 'unknown';
+ const onBuildView = visibleStep === 'building';
+ const submitLabel = document.querySelector('#submit-btn .label')?.textContent?.trim()
+ || document.getElementById('submit-btn')?.textContent?.trim();
+ const banner = document.querySelector('.unsupported.show')?.textContent?.trim();
+ const status = onBuildView ? document.getElementById('build-status-text')?.textContent?.trim() : null;
+ const progress = last('selfie:progress');
+ resolve({
+ state: 'timeout',
+ detail: [
+ `step=${visibleStep}`,
+ progress?.detail?.label && `progress="${progress.detail.label}"`,
+ status && `status="${status}"`,
+ submitLabel && `button="${submitLabel}"`,
+ banner && `banner="${banner}"`,
+ ].filter(Boolean).join(' '),
+ ms: Date.now() - started,
+ events: events(),
+ });
+ }
+ }, 1000);
+ });
+}, buildTimeoutMs);
+
+const trail = (outcome.events || []).map((e) => e.name.replace('selfie:', '')).join(' -> ');
+log(`pipeline: ${trail || '(no events fired)'}`);
+const building = (outcome.events || []).find((e) => e.name === 'selfie:building');
+if (building?.detail?.jobId) log(`job: ${building.detail.jobId}`);
+
+const elapsed = ((Date.now() - started) / 1000).toFixed(0);
+await page.screenshot({ path: path.join(outDir, `result-${outcome.state}.png`), fullPage: true });
+await writeFile(
+ path.join(outDir, 'run.json'),
+ JSON.stringify({ origin, photo, outcome, apiCalls, consoleErrors, failedRequests, elapsedSeconds: Number(elapsed) }, null, '\t')
+);
+await browser.close();
+
+console.log('')
+if (consoleErrors.length) console.log(` console errors: ${consoleErrors.length}\n ${consoleErrors.slice(0, 5).join('\n ')}`);
+if (failedRequests.length) console.log(` failed requests: ${failedRequests.length}\n ${failedRequests.slice(0, 5).join('\n ')}`);
+
+if (outcome.state === 'built') {
+ const avatar = outcome.detail ? `${origin}/avatars/${outcome.detail}` : '(no id in the event)';
+ console.log(`\n built in ${elapsed}s: ${avatar}\n evidence in ${outDir}\n`);
+ process.exit(0);
+}
+if (outcome.state === 'error') bail(1, `the flow failed after ${elapsed}s: ${outcome.detail}\n evidence in ${outDir}`);
+bail(1, `no avatar after ${elapsed}s. Last status on screen: ${outcome.detail || '(blank)'}\n evidence in ${outDir}`);