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
/**
* i18n markup integrity, unit tests.
*
* Locale values harvested from `data-i18n-html` elements are raw markup, and the
* runtime puts them back through innerHTML. That makes an HTML entity load-bearing
* source syntax rather than typography: a model that "helpfully" decodes
* `<code><agent-3d></code>` into `<code><agent-3d></code>` has not changed a
* character, it has turned a printed code sample into a live custom element that
* instantiates a 3D avatar in the middle of the docs.
*
* Two properties keep that from shipping, and this file pins both:
* 1. the masker hides entities from the model the same way it hides tags and
* glossary terms, so a round trip is byte-identical;
* 2. lint fails on markup drift (a tag the source never had, or one it lost)
* while staying silent on cosmetic entities like `&` and `—`,
* which decode to the same glyph the reader sees either way.
*/
import { describe, expect, it } from 'vitest';
import { buildMasker, lintLocale, markupDrift, tagSignature } from '../scripts/lib/i18n-shared.mjs';
import { configError, isFatalAuthFailure } from '../scripts/i18n-translate.mjs';
const masker = buildMasker(['$THREE', 'three.ws', 'x402']);
const roundTrip = (text, translate = (s) => s) => {
const { masked, tokens } = masker.mask(text);
return masker.unmask(translate(masked), tokens);
};
describe('buildMasker', () => {
it('hides entities from the model and restores them byte-for-byte', () => {
const src = '<50<span class="unit">KB</span>';
const { masked } = masker.mask(src);
expect(masked).not.toContain('<');
expect(masked).not.toContain('<span');
expect(roundTrip(src)).toBe(src);
});
it('survives a translation that rewrites everything around the sentinels', () => {
const src = 'Drop <code><agent-3d></code> into any page on three.ws';
const out = roundTrip(src, (m) => m.replace('Drop', 'Füge').replace('into any page on', 'in jede Seite auf'));
expect(out).toContain('<agent-3d>');
expect(out).toContain('three.ws');
expect(markupDrift(src, out)).toBe(false);
});
it('keeps a nested run intact when a tag wraps a placeholder', () => {
const src = '<a href="{{url}}" title="R&D">{{count}} agents</a>';
expect(roundTrip(src)).toBe(src);
});
it('masks numeric entities as well as named ones', () => {
const src = 'It's live — 'now'';
expect(masker.mask(src).masked).not.toContain('&');
expect(roundTrip(src)).toBe(src);
});
it('leaves a bare ampersand alone', () => {
expect(roundTrip('Buy & sell')).toBe('Buy & sell');
});
});
describe('tagSignature', () => {
it('ignores the order tags appear in', () => {
expect(tagSignature('<b>a</b><i>c</i>')).toBe(tagSignature('<i>c</i><b>a</b>'));
});
it('does not count an escaped tag as a tag', () => {
expect(tagSignature('<agent-3d>')).toBe('');
});
});
describe('markupDrift', () => {
it('catches an escaped tag that got decoded into a live element', () => {
expect(markupDrift('<code><agent-3d></code>', '<code><agent-3d></code>')).toBe(true);
});
it('catches a tag the translation invented', () => {
expect(markupDrift('Ship fast', 'Ship <b>fast</b>')).toBe(true);
});
it('catches a tag the translation dropped', () => {
expect(markupDrift('Ship <b>fast</b>', 'Ship fast')).toBe(true);
});
it('allows cosmetic entities to decode', () => {
expect(markupDrift('Buy & sell — today', 'Buy & sell - today')).toBe(false);
});
it('allows the copy around the markup to change completely', () => {
expect(markupDrift('<strong>Fast</strong> by default', '<strong>Schnell</strong> von Haus aus')).toBe(false);
});
});
describe('lintLocale', () => {
const source = { sdk: { snippet: 'Drop <code><agent-3d></code> in', amp: 'Buy & sell' } };
it('reports markup drift', () => {
const problems = lintLocale(source, { sdk: { snippet: 'Setze <code><agent-3d></code> ein', amp: 'Buy & sell' } }, { code: 'de' });
expect(problems).toHaveLength(1);
expect(problems[0]).toContain('[de] markup drift in sdk.snippet:');
});
it('formats the problem so --repair can parse the key back out', () => {
// repairLocale() recovers the failing key with /… in ([^:]+):/, so the
// message must keep `<key>:` immediately after the rule name or repair
// silently reports "nothing to repair" on a locale full of drift.
const [problem] = lintLocale(source, { sdk: { snippet: 'Setze <code><agent-3d></code> ein', amp: 'ok' } }, { code: 'de' });
expect(/(?:glossary term dropped|placeholder drift|markup drift) in ([^:]+):/.exec(problem)?.[1]).toBe(
'sdk.snippet',
);
});
it('passes a translation that kept its markup', () => {
const problems = lintLocale(source, { sdk: { snippet: 'Setze <code><agent-3d></code> ein', amp: 'Kaufen & verkaufen' } }, { code: 'de' });
expect(problems).toEqual([]);
});
});
/**
* The English fallback is the pipeline's graceful path for a value a model
* cannot render as valid JSON. Applied to a credential failure it is a
* catastrophe instead: the failure repeats identically on every key, so a whole
* catalog is rewritten into English while lint stays green and the run exits 0.
* That has now happened three ways in this repo (no .env, no gcloud token, and
* a token revoked mid-run by a Workspace reauth policy), so the classifier that
* separates the two is pinned here.
*/
describe('isFatalAuthFailure', () => {
it('is fatal when the backend is not configured at all', () => {
expect(isFatalAuthFailure(configError('GOOGLE_CLOUD_PROJECT not set'))).toBe(true);
});
it('is fatal on a 401, which is what a revoked token looks like mid-run', () => {
expect(isFatalAuthFailure(Object.assign(new Error('vertex 401'), { status: 401 }))).toBe(true);
});
it('is fatal on a 403', () => {
expect(isFatalAuthFailure(Object.assign(new Error('vertex 403'), { status: 403 }))).toBe(true);
});
// Regression: a spent OpenRouter balance answers every call `402 Insufficient
// credits`. Classified as retryable, that walked the halve-and-retry path down
// to single keys and baked English into 198 of them, exiting 0. A payment wall
// belongs to the account, not to the string, so splitting can never help.
it('is fatal on a 402, which is a spent balance and not a bad string', () => {
expect(
isFatalAuthFailure(
Object.assign(new Error('openrouter 402: Insufficient credits'), { status: 402 }),
),
).toBe(true);
});
it('is NOT fatal on a rate limit, which retry and backoff do handle', () => {
expect(isFatalAuthFailure(Object.assign(new Error('429'), { status: 429 }))).toBe(false);
});
// Regression: a free tier that hits its daily cap answers 429 forever. Once
// the backoff budget is spent that is an exhausted quota, not one bad string,
// so callBackendWithRetry stamps isQuotaExhausted. Left retryable, the
// halve-and-retry path walked every key the run had left down to a single
// key and baked English over each one, then exited as if it had worked.
it('is fatal once a rate limit has outlived its whole backoff budget', () => {
expect(
isFatalAuthFailure(
Object.assign(new Error('groq 429: rate limit'), { status: 429, isQuotaExhausted: true }),
),
).toBe(true);
});
it('is NOT fatal on a server error or a bad model reply', () => {
expect(isFatalAuthFailure(Object.assign(new Error('500'), { status: 500 }))).toBe(false);
expect(isFatalAuthFailure(new Error('no JSON object in response'))).toBe(false);
});
// Regression, 2026-09-09: the three.ws proxy's own free-tier chain went down
// and answered every request `502 {"error":"upstream_error","status":403}`
// and then `503 {"error":"provider_unavailable"}`. A single 5xx is a hiccup
// worth retrying, which is the case above; one that outlives the whole
// backoff budget is a downed gateway, and the run walked the Arabic catalog
// baking English one key at a time. Same rule as the 429 directly above it.
it('is fatal once a server error has outlived its whole backoff budget', () => {
for (const status of [500, 502, 503, 504]) {
expect(
isFatalAuthFailure(
Object.assign(new Error(`threews ${status}`), { status, isQuotaExhausted: true }),
),
).toBe(true);
}
});
it('tolerates a missing error object', () => {
expect(isFatalAuthFailure(undefined)).toBe(false);
});
});