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.

docs(avatar-stream): give the A3S package a README, and cover the captcha fallback

nirholas371834e30220
diff --git a/packages/avatar-stream/README.md b/packages/avatar-stream/README.md
new file mode 100644
index 000000000..3b0afe702
--- /dev/null
+++ b/packages/avatar-stream/README.md
@@ -0,0 +1,205 @@
+<p align="center">
+ <a href="https://three.ws"><img src="https://three.ws/three-ws-mcp-icon.svg" width="72" height="72" alt="three.ws" /></a>
+</p>
+
+<h1 align="center">@three-ws/avatar-stream</h1>
+
+<p align="center"><strong>Progressive 3D over plain HTTP. The first 50 KB is already a complete, skinned avatar.</strong></p>
+
+<p align="center">
+ <a href="https://www.npmjs.com/package/@three-ws/avatar-stream"><img alt="npm" src="https://img.shields.io/npm/v/@three-ws/avatar-stream?logo=npm&color=cb3837"></a>
+ <img alt="license" src="https://img.shields.io/npm/l/@three-ws/avatar-stream?color=3b82f6">
+ <img alt="node" src="https://img.shields.io/node/v/@three-ws/avatar-stream?color=339933&logo=node.js">
+</p>
+
+<p align="center">
+ <a href="#install">Install</a> ·
+ <a href="#quick-start">Quick start</a> ·
+ <a href="#cli">CLI</a> ·
+ <a href="#api">API</a> ·
+ <a href="#how-it-works">How it works</a> ·
+ <a href="https://three.ws/stream">Live demo</a>
+</p>
+
+---
+
+A GLB is atomic: nothing renders until the last byte lands. On a slow connection
+that is several seconds of blank frame on every embed, and it is the first thing
+a visitor sees.
+
+`@three-ws/avatar-stream` repacks a GLB into an **A3S** stream: nested layers
+ordered so that any byte-prefix of the file is a complete, skinned, spec-valid
+avatar. One ranged request puts a posed character on screen; everything after it
+refines the mesh already rendering, in place.
+
+No custom server. No WebSocket. No new codec. Just a file, ordered intelligently,
+served with the `Range` header every CDN has supported since 1997.
+
+```
+michelle.glb 829.8 KB -> first frame at 16,597 ms on slow 3G
+michelle.a3s 54.7 KB -> first frame at 1,094 ms on slow 3G 15.2x faster
+```
+
+## Install
+
+```sh
+npm install @three-ws/avatar-stream
+```
+
+The browser entry (`.` and `./three`) has zero dependencies. Packing pulls in
+`@gltf-transform/*`, `meshoptimizer`, `draco3dgltf`, and `sharp`, all declared as
+optional peers so a front-end bundle never sees them.
+
+## Quick start
+
+### Pack
+
+```sh
+npx @three-ws/avatar-stream pack avatar.glb -o avatar.a3s
+```
+
+```
+packed avatar.glb -> avatar.a3s in 281 ms
+
+ source 829.8 KB
+ container 1629.2 KB
+ base layer 50.8 KB (6.1% of source, 842 of 28106 triangles)
+
+ level kind triangles bytes cumulative
+ 0 base 842 50.8 KB 54.7 KB
+ 1 patch 2810 557.3 KB 612.0 KB
+ 2 patch 8430 220.2 KB 832.2 KB
+ 3 patch 28106 797.0 KB 1629.2 KB
+```
+
+### Render progressively
+
+```js
+import * as THREE from 'three';
+import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
+import { A3SPlayer } from '@three-ws/avatar-stream/three';
+
+const player = await A3SPlayer.load('/avatars/michelle.a3s', {
+ THREE,
+ GLTFLoader,
+ onLayer: (l) => console.log(`level ${l.level}: ${l.triangleCount} triangles`),
+});
+
+scene.add(player.scene); // already skinned, posed, and framed
+await player.refine(); // detail arrives without disturbing camera or pose
+```
+
+`load()` resolves as soon as the coarse avatar is renderable, after exactly one
+HTTP request. `refine()` walks the remaining layers, mutating the geometry that
+is already on screen.
+
+### Serve it
+
+Any static host works, because an A3S file is a static file:
+
+```
+GET /avatars/michelle.a3s
+Range: bytes=0-56035
+```
+
+`three.ws` also packs on demand at
+[`/api/avatar-stream?src=/avatars/michelle.glb`](https://three.ws/api/avatar-stream?src=/avatars/michelle.glb&format=json),
+which serves `206 Partial Content` and will hand you the layer table as JSON with
+`&format=json`.
+
+## CLI
+
+```sh
+a3s pack <input.glb> [-o out.a3s] [--levels 0.03,0.1,0.3,1] [--base-texture 64] [--json]
+a3s inspect <file.a3s|url> [--json]
+a3s verify <file.a3s|url> [--deep] [--json]
+a3s extract <file.a3s|url> [-o preview.glb]
+a3s bench <input.glb> [--connection slow-3g|fast-3g|4g] [--json]
+```
+
+`verify --deep` replays every layer headlessly and proves the refined surface
+matches the source triangle for triangle, with no renderer involved.
+
+`extract` writes layer 0 out as a standalone GLB. It opens in Blender, in the
+Khronos validator, in any glTF viewer, because it is not a custom blob:
+
+```sh
+a3s extract avatar.a3s -o preview.glb # 50.8 KB, 842 triangles, fully rigged
+```
+
+## API
+
+### `@three-ws/avatar-stream` (isomorphic, no dependencies)
+
+| Export | Purpose |
+|---|---|
+| `A3SStream.open(target, options)` | Open a URL, bytes, or custom source. One request to a renderable base layer. |
+| `stream.base` | Layer 0 as a `Uint8Array`. A complete GLB. |
+| `stream.layer(level, { verify })` | Fetch one refinement layer. |
+| `stream.layers({ verify })` | Async iterator over the refinement layers. |
+| `httpSource(url, { fetch, headers })` | Range-request byte source. Handles hosts that ignore `Range`. |
+| `decodePreamble` / `decodeHeader` / `encodeContainer` | The container format itself. |
+
+### `@three-ws/avatar-stream/three`
+
+| Export | Purpose |
+|---|---|
+| `A3SPlayer.load(target, { THREE, GLTFLoader, onLayer })` | Open a stream and parse layer 0 into a scene. |
+| `player.refine(options)` | Apply every remaining layer, coarse to fine. |
+| `applyPrimitivePatch` / `applyTexturePatch` | The primitives, if you drive refinement yourself. |
+
+`three` and `GLTFLoader` are injected, never imported, so this package pins no
+renderer version and never ships a second copy of three into your bundle.
+
+### `@three-ws/avatar-stream/node`
+
+| Export | Purpose |
+|---|---|
+| `pack(glbBytes, options)` | GLB to A3S. Returns `{ container, header, stats }`. |
+| `reconstruct(target, options)` | Replay a stream into plain typed arrays, no GPU. |
+| `triangleFingerprint(positions, indices)` | Order-independent surface fingerprint, for tests. |
+
+## How it works
+
+Edge-collapse simplification has a useful property: simplify a mesh
+*successively*, finest to coarsest, and the vertices surviving at each level are a
+strict subset of those at the level below. The levels nest.
+
+So the packer ranks every vertex by the coarsest level it reaches, sorts the
+vertex buffer by that rank, and level *k*'s vertices become exactly the first
+*V(k)* entries. A refinement layer only ever appends vertices the client lacks. It
+never rewrites a byte already sent.
+
+Skinning survives untouched, because a simplifier emits a new index buffer over
+the vertex array it was handed, carrying `JOINTS_0` and `WEIGHTS_0` along with it.
+That is why the 842-triangle base layer is already bound to all 65 joints.
+
+Animation clips are deliberately excluded from layer 0. On a rigged character the
+keyframe data often outweighs the mesh several times over, and it is the one part
+invisible in the first frame. Clips arrive in the first patch as a geometry-free
+companion GLB whose tracks bind by node name.
+
+The wire format is specified in
+[`specs/AVATAR_STREAM.md`](https://github.com/nirholas/three.ws/blob/main/specs/AVATAR_STREAM.md)
+and is CC0. Independent implementations are welcome.
+
+## Measured on the three.ws avatar corpus
+
+Base layer as a share of source, across 17 production avatars:
+
+| Avatar | Source | Base layer | Share | Triangles |
+|---|---|---|---|---|
+| `pumpfun-pill-cupsey-static` | 1641 KB | 67 KB | 4.1% | 1336 of 44544 |
+| `parametric-base` | 4244 KB | 234 KB | 5.5% | 902 of 27676 |
+| `michelle` | 830 KB | 51 KB | 6.1% | 842 of 28106 |
+| `xbot` | 781 KB | 48 KB | 6.1% | 1472 of 49112 |
+| `studio` | 1796 KB | 154 KB | 8.6% | 1349 of 15817 |
+| `brainstem` | 3120 KB | 404 KB | 12.9% | 6813 of 61666 |
+| `realistic-male` | 1206 KB | 202 KB | 16.8% | 587 of 10677 |
+
+Every base layer in that corpus passes Khronos glTF validation with zero errors,
+and every stream replays to a surface identical to its source.
+
+## License
+
+Apache-2.0
diff --git a/tests/privy-captcha.test.js b/tests/privy-captcha.test.js
new file mode 100644
index 000000000..967484cb4
--- /dev/null
+++ b/tests/privy-captcha.test.js
@@ -0,0 +1,146 @@
+// Privy answers passwordless/init and siwe/init with HTTP 401
+// `invalid_credentials` when the app requires a CAPTCHA and the request carries
+// no token. That message reads as "your email or wallet is wrong", so people
+// went and reset a password that was never the problem.
+//
+// The cause was a probe that could not tell two answers apart: reading the app
+// config returned `null` both for "this app needs no CAPTCHA" and for "we could
+// not read the config", so a flaky network silently became a wrong-credentials
+// error at the end of the flow. These tests pin that the three outcomes stay
+// three, that a failed read retries once at the moment of use, and that the
+// messages a person actually reads say what happened.
+import { describe, it, expect, vi } from 'vitest';
+import {
+ fetchCaptchaConfig,
+ makeCaptchaResolver,
+ captchaRequirement,
+ signInMessage,
+ CAPTCHA_UNAVAILABLE,
+ CAPTCHA_UNKNOWN_MESSAGE,
+} from '../src/auth/privy-captcha.js';
+
+const APP = 'app-abc123';
+const ok = (body) => ({ ok: true, json: async () => body });
+
+describe('fetchCaptchaConfig', () => {
+ it('returns the Turnstile config when the app requires one', async () => {
+ const fetchImpl = vi.fn(async () => ok({
+ captcha_enabled: true,
+ captcha_site_key: 't:0xSITEKEY',
+ enabled_captcha_provider: 'turnstile',
+ }));
+ const cfg = await fetchCaptchaConfig(APP, { fetchImpl });
+ // Privy prefixes Turnstile site keys with "t:"; Turnstile itself rejects it.
+ expect(cfg).toEqual({ siteKey: '0xSITEKEY', apiUrl: 'https://auth.privy.io' });
+ });
+
+ it('honours a custom auth domain, which serves every auth endpoint', async () => {
+ const fetchImpl = vi.fn(async () => ok({
+ captcha_enabled: true,
+ captcha_site_key: 't:k',
+ custom_api_url: 'https://auth.example.com',
+ }));
+ expect((await fetchCaptchaConfig(APP, { fetchImpl })).apiUrl).toBe('https://auth.example.com');
+ });
+
+ it('returns null when the app genuinely has no CAPTCHA', async () => {
+ const fetchImpl = vi.fn(async () => ok({ captcha_enabled: false }));
+ expect(await fetchCaptchaConfig(APP, { fetchImpl })).toBeNull();
+ });
+
+ it('returns null for a provider this flow has no token for', async () => {
+ const fetchImpl = vi.fn(async () => ok({
+ captcha_enabled: true,
+ captcha_site_key: 't:k',
+ enabled_captcha_provider: 'hcaptcha',
+ }));
+ expect(await fetchCaptchaConfig(APP, { fetchImpl })).toBeNull();
+ });
+
+ it('reports a failed read as UNAVAILABLE, never as "no CAPTCHA"', async () => {
+ // This is the whole bug: collapsing these two into null is what turned a
+ // network blip into "invalid_credentials" at the end of sign-in.
+ const httpError = vi.fn(async () => ({ ok: false, status: 503, json: async () => ({}) }));
+ expect(await fetchCaptchaConfig(APP, { fetchImpl: httpError })).toBe(CAPTCHA_UNAVAILABLE);
+
+ const threw = vi.fn(async () => { throw new Error('network down'); });
+ expect(await fetchCaptchaConfig(APP, { fetchImpl: threw })).toBe(CAPTCHA_UNAVAILABLE);
+ });
+
+ it('bounds the read, so a hung config host cannot stall the login form', async () => {
+ let seen = null;
+ await fetchCaptchaConfig(APP, {
+ timeoutMs: 1234,
+ fetchImpl: async (_url, init) => { seen = init; return ok({ captcha_enabled: false }); },
+ });
+ expect(seen.signal).toBeInstanceOf(AbortSignal);
+ expect(seen.headers['privy-app-id']).toBe(APP);
+ });
+});
+
+describe('makeCaptchaResolver', () => {
+ it('caches a good answer instead of re-asking on every click', async () => {
+ const fetchImpl = vi.fn(async () => ok({ captcha_enabled: false }));
+ const resolve = makeCaptchaResolver(APP, { fetchImpl });
+ expect(await resolve()).toBeNull();
+ expect(await resolve()).toBeNull();
+ expect(fetchImpl).toHaveBeenCalledTimes(1);
+ });
+
+ it('retries once at the moment of use after a failed page-load probe', async () => {
+ // Without this, one blip during page load broke sign-in for the entire
+ // page view, and the visitor's only fix was a reload nobody suggested.
+ let calls = 0;
+ const fetchImpl = vi.fn(async () => {
+ calls += 1;
+ if (calls === 1) throw new Error('network down');
+ return ok({ captcha_enabled: true, captcha_site_key: 't:k' });
+ });
+ const resolve = makeCaptchaResolver(APP, { fetchImpl });
+ expect(await resolve()).toEqual({ siteKey: 'k', apiUrl: 'https://auth.privy.io' });
+ expect(fetchImpl).toHaveBeenCalledTimes(2);
+ });
+
+ it('still reports UNAVAILABLE when the retry fails too', async () => {
+ const fetchImpl = vi.fn(async () => { throw new Error('still down'); });
+ const resolve = makeCaptchaResolver(APP, { fetchImpl });
+ expect(await resolve()).toBe(CAPTCHA_UNAVAILABLE);
+ });
+});
+
+describe('captchaRequirement', () => {
+ it('maps each outcome to the action the sign-in flow should take', () => {
+ expect(captchaRequirement({ siteKey: 'k' })).toBe('required');
+ expect(captchaRequirement(null)).toBe('none');
+ expect(captchaRequirement(CAPTCHA_UNAVAILABLE)).toBe('unknown');
+ });
+});
+
+describe('signInMessage', () => {
+ it('never leaves the visitor with a raw invalid_credentials', () => {
+ const msg = signInMessage(new Error('Request failed: invalid_credentials'), 'fallback');
+ expect(msg).not.toMatch(/invalid_credentials/);
+ expect(msg).toMatch(/human-verification|try again/i);
+ });
+
+ it('names a timeout as a timeout', () => {
+ const err = new Error('signal timed out');
+ err.name = 'TimeoutError';
+ expect(signInMessage(err, 'fallback')).toMatch(/did not respond in time/);
+ });
+
+ it('passes a real, readable error through untouched', () => {
+ expect(signInMessage(new Error('Enter the code from your email.'), 'fallback'))
+ .toBe('Enter the code from your email.');
+ });
+
+ it('falls back when the error says nothing at all', () => {
+ expect(signInMessage(new Error(''), 'Wallet sign-in failed.')).toBe('Wallet sign-in failed.');
+ expect(signInMessage(undefined, 'Wallet sign-in failed.')).toBe('Wallet sign-in failed.');
+ });
+
+ it('offers a sentence for the unknown-requirement case, not a symbol', () => {
+ expect(CAPTCHA_UNKNOWN_MESSAGE).toMatch(/CAPTCHA/);
+ expect(CAPTCHA_UNKNOWN_MESSAGE).toMatch(/try again/i);
+ });
+});