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
// Shared Vercel legacy-routes matcher: the single offline model of what
// server/index.mjs does at runtime.
//
// server/index.mjs is production: it reads vercel.json's `routes` array on boot,
// splits it at the {handle:"filesystem"} marker, walks phase 1 with first-match
// semantics, then serves either an api/** handler (Vercel filesystem semantics)
// or a static file, falling back to the post-filesystem rules. Two audits need
// to predict that offline (scripts/verify-routes.mjs for catalog pages,
// scripts/audit-route-shadowing.mjs for api/** handlers). Both import this
// module so there is exactly one matcher to keep in sync with the server.
//
// Kept deliberately parallel to server/index.mjs; when the server's routing
// changes, change it here in the same commit.
import { existsSync, readdirSync, statSync } from 'node:fs';
import path from 'node:path';
// ---------------------------------------------------------------------------
// Route table (server/index.mjs: "vercel.json route table, split at the marker")
// ---------------------------------------------------------------------------
/**
* Split a vercel.json `routes` array into the two phases the server uses.
* Each compiled rule keeps its original index so audits can name the offender.
*/
export function loadRouteTable(vercelConfig) {
const routes = vercelConfig.routes || [];
const fsIndex = routes.findIndex((r) => r.handle === 'filesystem');
const compile = (r, index) => {
let re = null;
try {
re = new RegExp(`^${r.src}$`);
} catch {
re = null;
}
return { ...r, index, re };
};
const slice = (from, to) =>
routes
.slice(from, to)
.map((r, i) => compile(r, from + i))
.filter((r) => r.src && r.re);
return {
routes,
fsIndex,
phase1Routes: slice(0, fsIndex === -1 ? routes.length : fsIndex),
postFsRoutes: fsIndex === -1 ? [] : slice(fsIndex + 1, routes.length),
};
}
/** "$1"-style capture substitution used by dest and header values. */
export function substitute(template, match) {
return String(template).replace(/\$(\d+)/g, (_, n) => match?.[Number(n)] ?? '');
}
export const isExternalDest = (dest) => /^https?:\/\//.test(dest || '');
// `has[].value` patterns may carry a leading Perl-style `(?i)` inline flag,
// which native RegExp rejects as an invalid group.
const hasValueCache = new Map();
function compileHasValue(value) {
let re = hasValueCache.get(value);
if (!re) {
const caseInsensitive = value.startsWith('(?i)');
re = new RegExp(caseInsensitive ? value.slice(4) : value, caseInsensitive ? 'i' : undefined);
hasValueCache.set(value, re);
}
return re;
}
/**
* Vercel `has` conditions gate a rule to the requests carrying the query param,
* header, cookie or host it names. A plain request satisfies none of them, so
* modeling a default GET means those rules are skipped, which is exactly what
* production does for that same request.
*/
export function hasMatches(route, req, url) {
if (!route.has) return true;
for (const cond of route.has) {
let val;
if (cond.type === 'query') val = url.searchParams.get(cond.key);
else if (cond.type === 'header') val = req.headers?.[cond.key.toLowerCase()];
else if (cond.type === 'cookie') {
const raw = req.headers?.cookie || '';
const m = raw.match(new RegExp(`(?:^|;\\s*)${cond.key}=([^;]*)`));
val = m ? decodeURIComponent(m[1]) : undefined;
} else if (cond.type === 'host') val = req.headers?.host;
else continue;
if (val == null) return false;
if (cond.value !== undefined && !compileHasValue(cond.value).test(val)) return false;
}
return true;
}
// ---------------------------------------------------------------------------
// api/** filesystem resolution (server/index.mjs: resolveApi + dispatchApi)
// ---------------------------------------------------------------------------
const dirCache = new Map();
function listDir(dir) {
let entries = dirCache.get(dir);
if (!entries) {
entries = readdirSync(dir, { withFileTypes: true });
dirCache.set(dir, entries);
}
return entries;
}
/** Names starting with `_` or `.` are never routable. */
export const isRoutable = (name) => !name.startsWith('_') && !name.startsWith('.');
/**
* Precedence per segment: exact file > exact dir > [param].js > [param]/ >
* [...catchall].js.
*/
export function resolveApi(dir, segments, params = {}) {
if (segments.length === 0) {
const index = path.join(dir, 'index.js');
return existsSync(index) ? { file: index, params } : null;
}
const [head, ...rest] = segments;
if (rest.length === 0) {
const exact = path.join(dir, `${head}.js`);
if (existsSync(exact)) return { file: exact, params };
}
const exactDir = path.join(dir, head);
if (existsSync(exactDir) && statSync(exactDir).isDirectory()) {
const hit = resolveApi(exactDir, rest, params);
if (hit) return hit;
}
const entries = listDir(dir);
if (rest.length === 0) {
for (const e of entries) {
if (!e.isFile() || !isRoutable(e.name)) continue;
if (e.name.startsWith('[') && e.name.endsWith('].js') && !e.name.startsWith('[...')) {
const name = e.name.slice(1, -4);
return { file: path.join(dir, e.name), params: { ...params, [name]: head } };
}
}
}
for (const e of entries) {
if (!e.isDirectory() || !isRoutable(e.name)) continue;
if (e.name.startsWith('[') && e.name.endsWith(']') && !e.name.startsWith('[...')) {
const name = e.name.slice(1, -1);
const hit = resolveApi(path.join(dir, e.name), rest, { ...params, [name]: head });
if (hit) return hit;
}
}
for (const e of entries) {
if (!e.isFile()) continue;
if (e.name.startsWith('[...') && e.name.endsWith('].js')) {
const name = e.name.slice(4, -4);
return {
file: path.join(dir, e.name),
params: { ...params, [name]: [head, ...rest].join('/') },
};
}
}
return null;
}
/**
* Resolve an `/api/...` pathname to the handler file that would run, applying
* the same segment sanitising the server does (a `.js` suffix on a dest is
* stripped; `_`/`.`-prefixed, empty, `..` and separator-smuggling segments are
* rejected outright).
*/
export function resolveApiPath(apiRoot, pathname) {
const apiPath = pathname.endsWith('.js') ? pathname.slice(0, -3) : pathname;
let segments;
try {
segments = apiPath.slice(5).split('/').filter(Boolean).map(decodeURIComponent);
} catch {
return null;
}
if (
segments.length === 0 ||
segments.some((s) => !isRoutable(s) || s === '..' || s.includes('/') || s.includes('\\'))
)
return null;
const hit = resolveApi(apiRoot, segments, {});
if (hit && !hit.file.startsWith(apiRoot + path.sep)) return null;
return hit;
}
// ---------------------------------------------------------------------------
// Phase 1 walk (server/index.mjs: the external-dest proxy + the phase-1 loop)
// ---------------------------------------------------------------------------
/**
* Walk the pre-filesystem rules with first-match semantics.
*
* `continue` rules only layer headers on. The first non-continue rule decides:
* an absolute dest proxies the request out, a `status` without a `dest` ends it
* (that is how every redirect in this table is expressed: status + a Location
* header), and a `dest` rewrites the path and ends the phase. A non-continue
* rule with neither keeps the walk going.
*
* @returns {{outcome:'proxy'|'status'|'rewrite'|'passthrough', path:string,
* headers:Record<string,string>, extraQuery:Record<string,string>,
* status:number|null, rule:object|null}}
*/
export function walkPhase1(phase1Routes, pathname, req, url) {
const headers = {};
const extraQuery = {};
for (const route of phase1Routes) {
const m = route.re.exec(pathname);
if (!m) continue;
if (!hasMatches(route, req, url)) continue;
if (route.headers) {
for (const [k, v] of Object.entries(route.headers)) headers[k] = substitute(v, m);
}
if (route.continue) continue;
if (route.dest && isExternalDest(route.dest)) {
return {
outcome: 'proxy',
path: substitute(route.dest, m),
headers,
extraQuery,
status: route.status ?? null,
rule: route,
};
}
if (route.status && !route.dest) {
return { outcome: 'status', path: pathname, headers, extraQuery, status: route.status, rule: route };
}
if (route.dest) {
const dest = substitute(route.dest, m);
const qIdx = dest.indexOf('?');
if (qIdx !== -1) {
for (const [k, v] of new URLSearchParams(dest.slice(qIdx + 1))) extraQuery[k] = v;
}
return {
outcome: 'rewrite',
path: qIdx === -1 ? dest : dest.slice(0, qIdx),
headers,
extraQuery,
status: route.status ?? null,
rule: route,
};
}
}
return { outcome: 'passthrough', path: pathname, headers, extraQuery, status: null, rule: null };
}
// ---------------------------------------------------------------------------
// Full request resolution
// ---------------------------------------------------------------------------
/**
* Predict what production serves for a request.
*
* @param {object} table loadRouteTable() result
* @param {string} pathname request path (no query)
* @param {object} [opts]
* @param {string} [opts.apiRoot] absolute path to api/ (enables handler resolution)
* @param {(p:string)=>boolean} [opts.fileServes] does the static filesystem serve this path?
* @param {string} [opts.method] default 'GET'
* @param {object} [opts.headers] request headers (drives `has` host/header rules)
* @param {string} [opts.search] raw query string, e.g. '?id=1'
* @returns {{outcome:string, status?:number, file?:string, dest?:string,
* to?:string, rule?:object|null, headers?:object}}
* outcome: 'handler' | 'api-missing' | 'file' | 'redirect' | 'status' |
* 'external' | 'notfound'
*/
export function resolveRequest(table, pathname, opts = {}) {
const {
apiRoot = null,
fileServes = () => false,
method = 'GET',
headers: reqHeaders = { host: 'three.ws' },
search = '',
collapseTrailingSlash = true,
} = opts;
const url = new URL(pathname + search, 'http://internal');
const req = { method, headers: reqHeaders, url: pathname + search };
// The trailing-slash collapse runs ahead of the route table for page URLs.
if (
collapseTrailingSlash &&
(method === 'GET' || method === 'HEAD') &&
pathname.length > 1 &&
pathname.endsWith('/') &&
!pathname.startsWith('/api/')
) {
return { outcome: 'redirect', status: 301, to: pathname.replace(/\/+$/, '') || '/' };
}
const phase1 = walkPhase1(table.phase1Routes, url.pathname, req, url);
if (phase1.outcome === 'proxy')
return { outcome: 'external', status: 200, to: phase1.path, rule: phase1.rule };
if (phase1.outcome === 'status') {
const location = phase1.rule?.headers?.Location || phase1.rule?.headers?.location;
if (location)
return {
outcome: 'redirect',
status: phase1.status,
to: substitute(location, phase1.rule.re.exec(url.pathname)),
rule: phase1.rule,
};
return { outcome: 'status', status: phase1.status, rule: phase1.rule };
}
const currentPath = phase1.path;
if (currentPath.startsWith('/api/')) {
if (!apiRoot) return { outcome: 'handler', dest: currentPath, rule: phase1.rule };
const hit = resolveApiPath(apiRoot, currentPath);
if (hit)
return { outcome: 'handler', file: hit.file, dest: currentPath, rule: phase1.rule, params: hit.params };
return { outcome: 'api-missing', status: 404, dest: currentPath, rule: phase1.rule };
}
if (method === 'GET' || method === 'HEAD') {
if (fileServes(currentPath))
return { outcome: 'file', status: phase1.status || 200, dest: currentPath, rule: phase1.rule };
}
for (const route of table.postFsRoutes) {
const m = route.re.exec(currentPath);
if (!m) continue;
if (!hasMatches(route, req, url)) continue;
if (route.dest) {
const dest = substitute(route.dest, m);
if (fileServes(dest))
return { outcome: 'notfound', status: route.status || 404, dest, rule: route };
}
if (route.status) return { outcome: 'notfound', status: route.status, dest: route.dest, rule: route };
}
return { outcome: 'notfound', status: 404, dest: '(implicit)' };
}