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
feat(ops): drive the selfie flow in a browser and catch a truncated asset before users do
nirholas5000f8a6bafe
diff --git a/.gitignore b/.gitignoreindex 033060cfc..8b842a6b8 100644--- a/.gitignore+++ b/.gitignore@@ -616,3 +616,4 @@ public/_payload-check/# Atomic-write scratch files from scripts/i18n-translate.mjspublic/locales/*.tmp-*+scripts/.selfie-verify/diff --git a/docs/ops/gcp-production.md b/docs/ops/gcp-production.mdindex 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 theserving hostname without either widening the bucket policy to match orredirecting 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 headerdiff --git a/package.json b/package.jsonindex 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.mjsnew file mode 100644index 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.mjsnew file mode 100644index 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}`);