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
/**
* Branding lock — fails if forbidden partner brand names appear in
* user-facing surfaces of the three.ws codebase.
*
* Scope and exemptions are documented inline below and in
* ./branding-allowlist.json. This test deliberately uses only `node:fs`
* and `node:path` so it adds no new dependencies.
*/
import { describe, test, expect } from 'vitest';
import { readFileSync, readdirSync, statSync, existsSync } from 'node:fs';
import { join, relative, sep } from 'node:path';
import { fileURLToPath } from 'node:url';
const REPO_ROOT = fileURLToPath(new URL('..', import.meta.url));
const ALLOWLIST_PATH = join(REPO_ROOT, 'tests', 'branding-allowlist.json');
/** @type {Array<{ pattern: string, file: string, reason: string }>} */
const allowlist = JSON.parse(readFileSync(ALLOWLIST_PATH, 'utf8'));
// Module-level read cache — each file is read exactly once across all test cases.
const _fileCache = new Map();
function cachedRead(absPath) {
if (!_fileCache.has(absPath)) _fileCache.set(absPath, readFileSync(absPath, 'utf8'));
return _fileCache.get(absPath);
}
// ── Forbidden strings ───────────────────────────────────────────────────────
//
// Each entry: { id, regex, label }
// - id — stable identifier used by allowlist + test naming
// - regex — case-insensitive matcher
// - label — human-readable brand
//
// "RPM" is special-cased below (only flagged near avatar/selfie).
const FORBIDDEN = [
{ id: 'avaturn', regex: /avaturn/i, label: 'Avaturn' },
{
id: 'character-studio',
regex: /character\s*studio/i,
label: 'Character Studio',
},
{
id: 'ready-player-me',
regex: /ready\s*player\s*me|readyplayer\.me/i,
label: 'Ready Player Me',
},
];
// ── Path scoping ────────────────────────────────────────────────────────────
const SKIP_DIR_NAMES = new Set([
'node_modules',
'dist',
'dist-lib',
'tests',
'migrations',
'.git',
]);
/**
* Return true if a repo-relative path should be excluded entirely
* regardless of which scope it would otherwise match.
*/
function isHardSkipped(relPath) {
const parts = relPath.split(sep);
for (const part of parts) {
if (SKIP_DIR_NAMES.has(part)) return true;
}
// avatar-sdk has its own dist subtree to skip.
if (relPath.startsWith(`avatar-sdk${sep}dist${sep}`)) return true;
// docs/audit/* are internal engineering audit + remediation logs that by
// nature quote the exact brand strings they are cataloguing for removal.
// They are not user-facing product copy, so they are out of scope.
if (relPath.startsWith(`docs${sep}audit${sep}`)) return true;
// public/internal/* are headless automation harnesses (noindex,nofollow),
// driven only by server-side puppeteer — the browser twins of the api/_lib
// headless helpers that are already out of scope. They carry vendor SDK
// identifiers and result-channel globals as code, never product copy that a
// user reads, so they are out of scope on the same grounds.
if (relPath.startsWith(`public${sep}internal${sep}`)) return true;
return false;
}
/**
* Walk a directory recursively, yielding absolute file paths that pass
* the optional `match` predicate and are not hard-skipped.
*/
function* walk(absDir, match) {
if (!existsSync(absDir)) return;
let entries;
try {
entries = readdirSync(absDir, { withFileTypes: true });
} catch {
return;
}
for (const ent of entries) {
const abs = join(absDir, ent.name);
const rel = relative(REPO_ROOT, abs);
if (isHardSkipped(rel)) continue;
if (ent.isDirectory()) {
yield* walk(abs, match);
} else if (ent.isFile()) {
if (!match || match(abs, rel)) yield abs;
}
}
}
/**
* Collect all in-scope files for the branding scan.
* Scope (per spec):
* - pages/**\/*.html (bundled top-level pages, formerly at repo root)
* - public/**\/*.html
* - docs/**\/*.md
* - public/docs/**\/*.md
* - avatar-sdk/README.md
* - avatar-sdk/types/**\/*.d.ts
* - src/**\/*.js (JSDoc on exported symbols only — handled specially)
* - README.md
*/
function collectScopedFiles() {
const files = [];
// 1. pages/**/*.html — bundled top-level pages
for (const abs of walk(
join(REPO_ROOT, 'pages'),
(_a, rel) => rel.endsWith('.html'),
)) {
files.push({ abs, kind: 'html' });
}
// 2. public/**/*.html
for (const abs of walk(
join(REPO_ROOT, 'public'),
(_a, rel) => rel.endsWith('.html'),
)) {
files.push({ abs, kind: 'html' });
}
// 3. docs/**/*.md
// docs/ALL.md is a read-only generated concatenation of every other doc
// (scripts/combine-docs.mjs). Its sources are each already in scope, so
// scanning it too would double every finding and force brittle parallel
// allowlist entries that silently drift on each regeneration. Skip it.
for (const abs of walk(
join(REPO_ROOT, 'docs'),
(_a, rel) => rel.endsWith('.md') && rel !== join('docs', 'ALL.md'),
)) {
files.push({ abs, kind: 'md' });
}
// 4. public/docs/**/*.md
for (const abs of walk(
join(REPO_ROOT, 'public', 'docs'),
(_a, rel) => rel.endsWith('.md'),
)) {
files.push({ abs, kind: 'md' });
}
// 5. avatar-sdk/README.md
const sdkReadme = join(REPO_ROOT, 'avatar-sdk', 'README.md');
if (existsSync(sdkReadme)) files.push({ abs: sdkReadme, kind: 'md' });
// 6. avatar-sdk/types/**/*.d.ts
for (const abs of walk(
join(REPO_ROOT, 'avatar-sdk', 'types'),
(_a, rel) => rel.endsWith('.d.ts'),
)) {
files.push({ abs, kind: 'dts' });
}
// 7. src/**/*.js (JSDoc on exports — scanned via separate path)
for (const abs of walk(
join(REPO_ROOT, 'src'),
(_a, rel) => rel.endsWith('.js'),
)) {
files.push({ abs, kind: 'src-js' });
}
// 8. Top-level README
for (const rel of ['README.md']) {
const abs = join(REPO_ROOT, rel);
if (existsSync(abs)) files.push({ abs, kind: 'readme' });
}
return files;
}
// ── Special-case helpers ────────────────────────────────────────────────────
/**
* Extract the line ranges inside a JS source that belong to a JSDoc block
* immediately followed by an `export class|function|const` (or `export
* default class|function`) declaration.
*
* "Immediately followed" means: between the JSDoc's closing `*\/` and the
* `export` keyword there is ONLY whitespace — no line comments, no other
* code. We scan structurally (not with one greedy regex) to avoid the
* non-greedy backtracking trap where a single JSDoc could be paired with
* a far-away export, swallowing intermediate code.
*
* Returns an array of { startLine, endLine } 1-based inclusive ranges
* covering only the JSDoc bodies themselves.
*/
function findExportedJSDocRanges(source) {
// Precompute cumulative byte offsets per line for O(log n) char→line lookup.
// Without this, source.slice(0, idx).split('\n').length is O(n) per call,
// making the whole function O(n * jsdocCount) — too slow on large src/ files.
const lineOffsets = [0];
for (let k = 0; k < source.length; k++) {
if (source[k] === '\n') lineOffsets.push(k + 1);
}
function charToLine(idx) {
let lo = 0, hi = lineOffsets.length - 1;
while (lo < hi) {
const mid = (lo + hi + 1) >> 1;
if (lineOffsets[mid] <= idx) lo = mid;
else hi = mid - 1;
}
return lo + 1;
}
const ranges = [];
const openRe = /\/\*\*/g;
let om;
while ((om = openRe.exec(source)) !== null) {
const openIdx = om.index;
const closeIdx = source.indexOf('*/', openIdx + 3);
if (closeIdx === -1) break;
const afterClose = closeIdx + 2;
// Inspect whitespace-only run after the closing */.
let i = afterClose;
while (i < source.length && /\s/.test(source[i])) i++;
const tail = source.slice(i, i + 80);
if (
/^export\s+(?:default\s+)?(?:async\s+)?(?:class|function|const|let|var)\b/.test(
tail,
)
) {
ranges.push({ startLine: charToLine(openIdx), endLine: charToLine(afterClose) });
}
// Continue scanning *after* this JSDoc's close so we don't overlap.
openRe.lastIndex = afterClose;
}
return ranges;
}
/**
* For src/**\/*.js — return only the lines that live inside a JSDoc block
* directly preceding an exported symbol. Returns an array of
* { lineNo, text } pairs.
*/
function getExportedJSDocLines(absPath) {
const source = cachedRead(absPath);
const lines = source.split('\n');
const ranges = findExportedJSDocRanges(source);
const out = [];
for (const { startLine, endLine } of ranges) {
for (let n = startLine; n <= endLine; n++) {
out.push({ lineNo: n, text: lines[n - 1] ?? '' });
}
}
return out;
}
/**
* Detect fenced code blocks (``` ... ```) in a markdown source. Returns
* a Set of 1-based line numbers that sit inside a fence.
*/
function fencedCodeLines(text) {
const inside = new Set();
const lines = text.split('\n');
let open = false;
for (let i = 0; i < lines.length; i++) {
if (/^```/.test(lines[i].trim())) {
open = !open;
continue; // the fence line itself is not "inside"
}
if (open) inside.add(i + 1);
}
return inside;
}
// ── Allowlist matching ──────────────────────────────────────────────────────
/**
* Return true if a hit is excused by an allowlist entry. An entry
* matches when:
* - entry.file is "*" OR is a suffix of the repo-relative path, AND
* - the offending line contains entry.pattern as a literal substring
* (case-sensitive — the patterns in the allowlist are literal code).
*
* Pattern matching is intentionally substring-based: the allowlist holds
* literal code fragments like `source: 'avaturn'` or `from '@avaturn/sdk'`.
*/
function isAllowed(relPath, lineText) {
for (const entry of allowlist) {
const fileMatches =
entry.file === '*' ||
relPath === entry.file ||
relPath.endsWith(entry.file);
if (!fileMatches) continue;
if (lineText.includes(entry.pattern)) return true;
}
return false;
}
// ── Core scanner ────────────────────────────────────────────────────────────
/**
* Returns all hits across the in-scope files for a given forbidden
* pattern. RPM gets special handling via the optional `extraGate`.
*/
function scanForPattern(forbidden, files, extraGate) {
const hits = [];
for (const f of files) {
const relPath = relative(REPO_ROOT, f.abs);
const text = cachedRead(f.abs);
const allLines = text.split('\n');
// For src JS files, restrict to JSDoc-on-exports lines.
let candidateLines;
if (f.kind === 'src-js') {
candidateLines = getExportedJSDocLines(f.abs);
} else {
candidateLines = allLines.map((text, i) => ({
lineNo: i + 1,
text,
}));
}
// Pre-compute fenced code line set for md/readme files so the
// extraGate can use it.
const fenced =
f.kind === 'md' || f.kind === 'readme'
? fencedCodeLines(text)
: null;
for (const { lineNo, text: line } of candidateLines) {
if (!forbidden.regex.test(line)) continue;
// Optional gate (used by RPM heuristic).
if (extraGate && !extraGate({ relPath, line, fenced, lineNo })) {
continue;
}
if (isAllowed(relPath, line)) continue;
hits.push({ file: relPath, line: lineNo, text: line.trim() });
}
}
return hits;
}
// ── Test cases ──────────────────────────────────────────────────────────────
describe('three.ws branding lock', () => {
const files = collectScopedFiles();
// The scanner walks every user-facing file end-to-end for each brand. On a
// large monorepo (hundreds of HTML/JS/MD files in scope) that comfortably
// exceeds the default 20s vitest timeout — bump per-test to 5 minutes so
// CI doesn't false-fail on perfectly clean trees.
const SCAN_TIMEOUT_MS = 5 * 60 * 1000;
for (const forbidden of FORBIDDEN) {
test(`no "${forbidden.label}" in user-facing files`, () => {
const hits = scanForPattern(forbidden, files);
if (hits.length > 0) {
const formatted = hits
.map(
(h) =>
` ${h.file}:${h.line}\n ${h.text}`,
)
.join('\n');
throw new Error(
`Forbidden brand "${forbidden.label}" found in ${hits.length} user-facing location(s):\n${formatted}\n\nReplace with three.ws-branded language, or add a documented exemption to tests/branding-allowlist.json.`,
);
}
expect(hits).toEqual([]);
}, SCAN_TIMEOUT_MS);
}
test('no "RPM" referring to Ready Player Me (heuristic: near avatar/selfie)', () => {
const RPM_LINE = /\bRPM\b/;
const NEARBY = /avatar|selfie/i;
const hits = [];
for (const f of files) {
const relPath = relative(REPO_ROOT, f.abs);
const text = cachedRead(f.abs);
const allLines = text.split('\n');
const candidateLines =
f.kind === 'src-js'
? getExportedJSDocLines(f.abs)
: allLines.map((t, i) => ({ lineNo: i + 1, text: t }));
for (const { lineNo, text: line } of candidateLines) {
if (!RPM_LINE.test(line)) continue;
// Window: the line itself plus the two surrounding lines.
const ctxStart = Math.max(0, lineNo - 2);
const ctxEnd = Math.min(allLines.length, lineNo + 1);
const ctx = allLines.slice(ctxStart, ctxEnd).join(' ');
if (!NEARBY.test(ctx)) continue;
if (isAllowed(relPath, line)) continue;
hits.push({ file: relPath, line: lineNo, text: line.trim() });
}
}
if (hits.length > 0) {
const formatted = hits
.map((h) => ` ${h.file}:${h.line}\n ${h.text}`)
.join('\n');
throw new Error(
`Found "RPM" near avatar/selfie context in ${hits.length} location(s) — assume Ready Player Me:\n${formatted}`,
);
}
expect(hits).toEqual([]);
}, SCAN_TIMEOUT_MS);
});