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
// <engine-qa>: the real-time-engine fitness grade, rendered.
//
// One custom element shared by /viewer and Rig Doctor, same split of
// responsibility as <sim-readiness> (public/sim-readiness-panel.js): this
// element owns presentation only, the caller decides where the report comes
// from and drives it through four methods.
//
// el.loading() a grade is on the way
// el.showReport(report, meta) a report from gradeEngineQa() or
// gradeEngineQaClient(): any verdict
// el.ungraded({ onGrade }) no grade for these bytes yet, offer one
// el.failed(message, { onRetry }) the lookup itself failed
//
// `report.partial` (set by the browser-only src/engine-qa-client.js grader)
// marks a report whose triangleBudget and collider checks are `skip`:
// Rig Doctor's file never left the tab to get this far, and those two checks
// need the server's LOD builder and manifold analyzer. When `meta.onUpgrade`
// is supplied, the panel renders an explicit "Check LOD & collider fitness"
// action in their place, naming the upload plainly, rather than silently
// posting the file or silently hiding the two checks the visitor came for.
//
// Shadow DOM for the same reason <sim-readiness> uses it: two hosts, two
// completely different cascades, one element that must never drift.
//
// Spec: specs/ENGINE_QA.md. Guide: /docs/engine-qa.
const VERDICTS = {
pass: { label: 'Engine ready', glyph: '✓', tone: 'good', lead: 'Draw calls, materials, and texel density all sit inside the real-time budget.' },
warn: { label: 'Needs tuning', glyph: '⚠', tone: 'warn', lead: 'Nothing here breaks on import, but at least one check is past the comfortable range for a 60fps target.' },
fail: { label: 'Will stutter', glyph: '✕', tone: 'bad', lead: 'At least one check is past the band a real-time engine can absorb without dropping frames or splitting batches.' },
skip: { label: 'Engine QA', glyph: '◇', tone: 'dim', lead: 'Nothing measurable yet.' },
};
const CSS = `
:host { position: relative; display: inline-block; font: inherit; --eq-good: #34c76d; --eq-near: #6ea8fe; --eq-warn: #f0b429; --eq-bad: #ff5656; --eq-dim: #9aa3b2; }
:host([hidden]) { display: none; }
* { box-sizing: border-box; }
.badge {
display: inline-flex; align-items: center; gap: 6px;
appearance: none; cursor: pointer; font: inherit;
font-size: 11.5px; font-weight: 700; letter-spacing: .01em; line-height: 1;
border-radius: 999px; padding: 5px 10px; white-space: nowrap;
color: var(--eq-dim); background: rgba(127, 140, 160, .12);
border: 1px solid rgba(127, 140, 160, .28);
transition: background .15s ease, border-color .15s ease, transform .06s ease, color .15s ease;
}
.badge:hover { background: rgba(127, 140, 160, .2); }
.badge:active { transform: translateY(1px); }
.badge:focus-visible { outline: 2px solid currentColor; outline-offset: 2px; }
.badge[disabled] { cursor: default; }
.badge[disabled]:hover { background: rgba(127, 140, 160, .12); }
.badge .glyph { font-size: 12px; line-height: 1; }
.badge .caret { font-size: 9px; opacity: .7; transition: transform .18s ease; }
.badge[aria-expanded="true"] .caret { transform: rotate(180deg); }
.badge.good { color: var(--eq-good); background: rgba(52, 199, 109, .13); border-color: rgba(52, 199, 109, .36); }
.badge.good:hover { background: rgba(52, 199, 109, .22); }
.badge.warn { color: var(--eq-warn); background: rgba(240, 180, 41, .13); border-color: rgba(240, 180, 41, .38); }
.badge.warn:hover { background: rgba(240, 180, 41, .22); }
.badge.bad { color: var(--eq-bad); background: rgba(255, 86, 86, .13); border-color: rgba(255, 86, 86, .36); }
.badge.bad:hover { background: rgba(255, 86, 86, .22); }
.skeleton {
display: inline-block; width: 128px; height: 23px; border-radius: 999px;
background: linear-gradient(90deg, rgba(127,140,160,.10) 25%, rgba(127,140,160,.22) 50%, rgba(127,140,160,.10) 75%);
background-size: 240% 100%; animation: sweep 1.25s ease-in-out infinite;
}
@keyframes sweep { from { background-position: 120% 0; } to { background-position: -120% 0; } }
.panel {
position: fixed; top: 0; left: 0; z-index: 2147483000;
margin: 0; inset: auto; overflow: auto;
width: max-content; min-width: 250px; max-width: min(480px, calc(100vw - 24px));
max-height: 60vh; overflow-y: auto; overscroll-behavior: contain;
border: 1px solid rgba(127, 140, 160, .28); border-radius: 12px;
background: #12141a; color: #e8eaf0;
padding: 12px 13px; font-size: 12.5px; line-height: 1.5; text-align: left;
opacity: 0; transform: translateY(-4px); transition: opacity .18s ease, transform .18s ease;
}
.panel[hidden] { display: none; }
.panel.open { opacity: 1; transform: translateY(0); }
.panel { box-shadow: 0 12px 34px rgba(0, 0, 0, .38); }
.panel[popover] { display: none; border-width: 1px; padding: 12px 13px; }
.panel[popover]:popover-open { display: block; }
.panel[popover]::backdrop { background: transparent; }
.panel.fallback { position: absolute; top: calc(100% + 8px); left: 0; }
:host([align="end"]) .panel.fallback { left: auto; right: 0; }
@media (prefers-reduced-motion: reduce) {
.panel { transition: none; }
.skeleton { animation: none; }
}
@media (prefers-color-scheme: light) {
.panel { background: #fff; color: #14161c; border-color: rgba(20, 22, 28, .16); box-shadow: 0 8px 28px rgba(20, 22, 28, .12); }
}
:host([data-theme="light"]) .panel { background: #fff; color: #14161c; border-color: rgba(20, 22, 28, .16); box-shadow: 0 8px 28px rgba(20, 22, 28, .12); }
:host([data-theme="light"]) .badge { color: #5b6470; background: rgba(20, 22, 28, .06); border-color: rgba(20, 22, 28, .16); }
:host([data-theme="light"]) .badge.good { color: #157f45; background: rgba(52, 199, 109, .14); border-color: rgba(52, 199, 109, .4); }
:host([data-theme="light"]) .badge.warn { color: #8a5d00; background: rgba(240, 180, 41, .18); border-color: rgba(240, 180, 41, .45); }
:host([data-theme="light"]) .badge.bad { color: #b3231f; background: rgba(255, 86, 86, .14); border-color: rgba(255, 86, 86, .4); }
:host([data-theme="light"]) { --eq-dim: #6b7280; --eq-warn: #8a5d00; }
:host([data-theme="dark"]) .panel { background: #12141a; color: #e8eaf0; border-color: rgba(127, 140, 160, .28); box-shadow: 0 12px 34px rgba(0, 0, 0, .38); }
:host([data-theme="dark"]) { --eq-dim: #9aa3b2; --eq-warn: #f0b429; }
.lead { margin: 0 0 10px; }
h3 { margin: 12px 0 5px; font-size: 10.5px; font-weight: 700; letter-spacing: .07em; text-transform: uppercase; color: var(--eq-dim); }
h3:first-of-type { margin-top: 0; }
p.note { margin: 2px 0 0; color: var(--eq-dim); }
dl { display: grid; grid-template-columns: minmax(0, 1fr) auto; gap: 3px 12px; margin: 0; }
dt { color: var(--eq-dim); min-width: 0; }
dd { margin: 0; text-align: right; font-variant-numeric: tabular-nums; white-space: nowrap; }
dd.good { color: var(--eq-good); }
dd.warn { color: var(--eq-warn); }
dd.bad { color: var(--eq-bad); }
.lod-row { display: grid; grid-template-columns: minmax(0, 1fr) auto; gap: 2px 12px; padding: 3px 0; border-top: 1px solid rgba(127, 140, 160, .14); }
.lod-row:first-child { border-top: 0; }
.foot { display: flex; flex-wrap: wrap; align-items: center; gap: 8px; margin-top: 12px; padding-top: 9px; border-top: 1px solid rgba(127, 140, 160, .2); color: var(--eq-dim); font-size: 11px; }
.foot .spacer { flex: 1 1 auto; }
button.link, a.link {
appearance: none; border: 0; background: none; padding: 0; cursor: pointer;
font: inherit; font-size: 11px; color: inherit; text-decoration: underline;
text-underline-offset: 2px; transition: color .15s ease;
}
button.link:hover, a.link:hover { color: var(--eq-near); }
button.link:focus-visible, a.link:focus-visible { outline: 2px solid currentColor; outline-offset: 2px; border-radius: 3px; }
button.link[disabled] { cursor: progress; opacity: .7; }
.action {
appearance: none; cursor: pointer; font: inherit; font-size: 11.5px; font-weight: 600;
color: inherit; background: rgba(110, 168, 254, .16); border: 1px solid rgba(110, 168, 254, .42);
border-radius: 8px; padding: 5px 10px; margin: 6px 0 0;
transition: background .15s ease, transform .06s ease;
display: inline-flex; align-items: center; gap: 6px;
}
.action:hover { background: rgba(110, 168, 254, .28); }
.action:active { transform: translateY(1px); }
.action:focus-visible { outline: 2px solid currentColor; outline-offset: 2px; }
.action[disabled] { opacity: .6; cursor: progress; }
.row { display: inline-flex; align-items: center; flex-wrap: wrap; gap: 2px; }
`;
function dl(rows) {
return rows.length
? `<dl>${rows.map(([k, val, cls]) => `<dt>${k}</dt><dd${cls ? ` class="${cls}"` : ''}>${val}</dd>`).join('')}</dl>`
: '';
}
class EngineQaCard extends HTMLElement {
constructor() {
super();
this._report = null;
this._meta = {};
this._open = false;
this.attachShadow({ mode: 'open' });
const style = document.createElement('style');
style.textContent = CSS;
this._head = document.createElement('div');
this._panel = document.createElement('div');
this._panel.className = 'panel';
this._panel.hidden = true;
this._popover = typeof this._panel.showPopover === 'function';
if (this._popover) this._panel.setAttribute('popover', 'manual');
else this._panel.classList.add('fallback');
this.shadowRoot.append(style, this._head, this._panel);
}
connectedCallback() {
this._followTheme();
if (!this._head.hasChildNodes()) this.loading();
}
_followTheme() {
const root = document.documentElement;
const sync = () => {
const theme = root.getAttribute('data-theme');
if (theme === 'light' || theme === 'dark') this.setAttribute('data-theme', theme);
else this.removeAttribute('data-theme');
};
sync();
if (this._themeObserver) return;
this._themeObserver = new MutationObserver(sync);
this._themeObserver.observe(root, { attributes: true, attributeFilter: ['data-theme'] });
}
/** A grade is on the way. Occupies exactly the badge's footprint. */
loading() {
this._report = null;
this._collapse();
this._head.innerHTML = '<span class="skeleton" role="status" aria-label="Checking real-time-engine fitness"></span>';
this._panel.innerHTML = '';
this.hidden = false;
}
/**
* Render a report from gradeEngineQa() (full) or gradeEngineQaClient() (partial).
* @param {object} report
* @param {{ gradedAt?: string, sourceUrl?: string, stlUrl?: string, onUpgrade?: Function, onDownloadStl?: Function }} [meta]
*/
showReport(report, meta = {}) {
if (!report || !report.checks) {
this.failed('That grade could not be read.', meta);
return;
}
this._report = report;
this._meta = meta;
const v = VERDICTS[report.overall] || VERDICTS.skip;
this._head.innerHTML = '';
const badge = document.createElement('button');
badge.type = 'button';
badge.className = `badge ${v.tone === 'dim' ? '' : v.tone}`;
badge.setAttribute('aria-expanded', 'false');
badge.innerHTML = `<span class="glyph" aria-hidden="true">${v.glyph}</span><span>${v.label}</span><span class="caret" aria-hidden="true">▾</span>`;
badge.title = 'Engine QA: draw calls, materials, texel density, LOD budget, and collider fitness';
badge.addEventListener('click', () => this._toggle());
this._head.append(badge);
this._badge = badge;
this._panel.innerHTML = this._panelHtml(report, v);
this._wirePanel();
this.hidden = false;
}
/** No grade exists for these bytes yet. An offer, never an error. */
ungraded({ onGrade } = {}) {
this._report = null;
this._collapse();
this._panel.innerHTML = '';
this._head.innerHTML = '';
const badge = document.createElement('button');
badge.type = 'button';
badge.className = 'badge';
badge.innerHTML = '<span class="glyph" aria-hidden="true">◇</span><span>Check engine fitness</span>';
badge.title = 'Measure draw calls, materials, texel density, LOD budget, and collider fitness';
if (typeof onGrade === 'function') {
badge.addEventListener('click', () => {
this.loading();
onGrade();
});
} else {
badge.disabled = true;
}
this._head.append(badge);
this.hidden = false;
}
/** The lookup itself failed. Says what happened and offers the retry. */
failed(message, { onRetry } = {}) {
this._report = null;
this._collapse();
this._panel.innerHTML = '';
this._head.innerHTML = '';
const wrap = document.createElement('span');
wrap.className = 'row';
const badge = document.createElement('button');
badge.type = 'button';
badge.className = 'badge bad';
badge.disabled = true;
badge.innerHTML = '<span class="glyph" aria-hidden="true">⚠</span><span>Grade unavailable</span>';
badge.title = message || 'The engine QA grade could not be fetched.';
wrap.append(badge);
if (typeof onRetry === 'function') {
const retry = document.createElement('button');
retry.type = 'button';
retry.className = 'action';
retry.textContent = 'Try again';
retry.addEventListener('click', () => {
this.loading();
onRetry();
});
wrap.append(retry);
}
this._head.append(wrap);
this.hidden = false;
}
disconnectedCallback() {
this._unbind();
this._themeObserver?.disconnect();
this._themeObserver = null;
}
_bind() {
if (this._bound) return;
this._bound = () => this._place();
window.addEventListener('scroll', this._bound, { passive: true, capture: true });
window.addEventListener('resize', this._bound, { passive: true });
this._onKey = (e) => { if (e.key === 'Escape' && this._open) { this._collapse(); this._badge?.focus(); } };
document.addEventListener('keydown', this._onKey);
this._onAway = (e) => {
if (!this._open) return;
const path = e.composedPath();
if (path.includes(this._panel) || path.includes(this._badge)) return;
this._collapse();
};
document.addEventListener('pointerdown', this._onAway, true);
}
_unbind() {
if (this._bound) {
window.removeEventListener('scroll', this._bound, { capture: true });
window.removeEventListener('resize', this._bound);
this._bound = null;
}
if (this._onKey) {
document.removeEventListener('keydown', this._onKey);
this._onKey = null;
}
if (this._onAway) {
document.removeEventListener('pointerdown', this._onAway, true);
this._onAway = null;
}
}
_place() {
if (!this._open || !this._badge || !this._popover) return;
const anchor = this._badge.getBoundingClientRect();
const gap = 8;
const margin = 12;
const box = this._panel.getBoundingClientRect();
const preferEnd = this.getAttribute('align') === 'end';
let left = preferEnd ? anchor.right - box.width : anchor.left;
left = Math.min(left, window.innerWidth - box.width - margin);
left = Math.max(margin, left);
const below = window.innerHeight - anchor.bottom - gap - margin;
const above = anchor.top - gap - margin;
const flip = below < box.height && above > below;
const top = flip
? Math.max(margin, anchor.top - gap - box.height)
: Math.min(anchor.bottom + gap, window.innerHeight - box.height - margin);
this._panel.style.left = `${Math.round(left)}px`;
this._panel.style.top = `${Math.round(Math.max(margin, top))}px`;
this._panel.style.maxHeight = `${Math.round(Math.max(160, (flip ? above : below)))}px`;
}
_show() {
if (this._popover) {
this._panel.hidden = false;
try { this._panel.showPopover(); return; } catch { /* already open */ }
}
this._panel.hidden = false;
}
_hide() {
if (this._popover) {
try { this._panel.hidePopover(); } catch { /* already closed */ }
}
this._panel.hidden = true;
}
_collapse() {
this._open = false;
this._panel.classList.remove('open');
this._hide();
this._badge?.setAttribute('aria-expanded', 'false');
this._unbind();
}
_toggle() {
this._open = !this._open;
this._badge.setAttribute('aria-expanded', this._open ? 'true' : 'false');
if (this._open) {
this._show();
this._place();
this._bind();
requestAnimationFrame(() => {
this._panel.classList.add('open');
this._place();
});
} else {
this._panel.classList.remove('open');
this._hide();
this._unbind();
}
}
_verdictCls(v) {
return v === 'fail' ? 'bad' : v === 'warn' ? 'warn' : v === 'pass' ? 'good' : '';
}
_panelHtml(r, v) {
const c = r.checks;
const core = [
['Draw calls', `${c.drawCalls.value} (good ≤${c.drawCalls.thresholds.good}, warn ≤${c.drawCalls.thresholds.warn})`, this._verdictCls(c.drawCalls.verdict)],
['Materials', `${c.materialCount.value} (good ≤${c.materialCount.thresholds.good}, warn ≤${c.materialCount.thresholds.warn})`, this._verdictCls(c.materialCount.verdict)],
];
if (r.textureCount != null) core.push(['Textures', String(r.textureCount), '']);
if (c.texelDensity.verdict !== 'skip') {
core.push(['Texel density', `${c.texelDensity.value} px/m`, this._verdictCls(c.texelDensity.verdict)]);
}
// The two checks that skip for structurally different reasons: Rig Doctor
// skips both at once (the file never left the tab, so neither a LOD build
// nor the manifold analyzer ran). A URL-graded model (viewer.html) already
// has a real collider verdict; only the LOD chain is opt-in there, because
// building one is real decimation work worth its own click. Either way, a
// single `onUpgrade` callback re-grades whatever is still missing, so one
// button covers one or both, labeled by whichever the host supplies.
const canUpgrade = typeof this._meta.onUpgrade === 'function';
const lodSkip = c.triangleBudget.verdict === 'skip';
const colliderSkip = c.collider.verdict === 'skip';
let lodHtml = '';
if (Array.isArray(c.triangleBudget.value)) {
lodHtml = `<h3>LOD triangle budget</h3>${c.triangleBudget.value
.map((l) => `<div class="lod-row"><span>${l.name}</span><span class="${this._verdictCls(l.verdict)}">${l.triangleCount.toLocaleString()} / ${l.budget.toLocaleString()}</span></div>`)
.join('')}${c.triangleBudget.monotonicDecrease === false ? '<p class="note">Levels are not strictly decreasing.</p>' : ''}`;
} else if (lodSkip && !canUpgrade) {
lodHtml = `<h3>LOD triangle budget</h3><p class="note">${c.triangleBudget.reason || 'No LOD chain supplied.'}</p>`;
}
let colliderHtml = '';
if (c.collider.value) {
const cv = c.collider.value;
colliderHtml = `<h3>Collider fitness</h3>${dl([
['Watertight', cv.watertight ? 'yes' : 'no', cv.watertight ? 'good' : 'bad'],
['Shells', String(cv.shells), ''],
['Triangles', `${cv.triangleCount.toLocaleString()} / ${cv.budget.toLocaleString()}`, this._verdictCls(c.collider.verdict)],
])}${c.collider.reason ? `<p class="note">${c.collider.reason}</p>` : ''}`;
} else if (colliderSkip && !canUpgrade) {
colliderHtml = `<h3>Collider fitness</h3><p class="note">${c.collider.reason || 'Not measured.'}</p>`;
}
const upgradeHtml = (lodSkip || colliderSkip) && canUpgrade
? `<h3>${lodSkip && colliderSkip ? 'LOD budget & collider fitness' : lodSkip ? 'LOD triangle budget' : 'Collider fitness'}</h3>
<p class="note">${lodSkip && colliderSkip ? 'Not measured yet: this needs a real LOD build and the server’s manifold analyzer.' : lodSkip ? 'No LOD chain graded yet: this needs a real LOD build.' : 'Not measured yet: this needs the server’s manifold analyzer.'}</p>
<button type="button" class="action" data-upgrade>${this._meta.upgradeLabel || 'Check LOD & collider fitness'}</button>`
: '';
const stlHtml = r.checks.collider?.value?.watertight
? (this._meta.stlUrl
? `<a class="link" href="${this._meta.stlUrl}" target="_blank" rel="noopener">Download STL</a>`
: typeof this._meta.onDownloadStl === 'function'
? `<button class="link" type="button" data-stl>Download STL</button>`
: '')
: '';
const when = this._meta.gradedAt ? new Date(this._meta.gradedAt) : null;
const stamp = when && !Number.isNaN(when.valueOf())
? `Graded ${when.toLocaleDateString(undefined, { year: 'numeric', month: 'short', day: 'numeric' })}`
: r.partial ? 'Graded in your browser' : 'Graded on three.ws';
return `
<p class="lead">${v.lead}</p>
${dl(core)}
${lodHtml}
${colliderHtml}
${upgradeHtml}
<div class="foot">
<span>${stamp}</span>
<span class="spacer"></span>
${stlHtml}
<button class="link" type="button" data-copy>Copy JSON</button>
<a class="link" href="/docs/engine-qa" target="_blank" rel="noopener">What this means</a>
</div>`;
}
_wirePanel() {
const copy = this._panel.querySelector('[data-copy]');
if (copy) {
copy.addEventListener('click', async () => {
const text = JSON.stringify(this._report, null, 2);
try {
await navigator.clipboard.writeText(text);
copy.textContent = 'Copied';
} catch {
copy.textContent = 'Press ⌘C to copy';
const ta = document.createElement('textarea');
ta.value = text;
ta.style.position = 'fixed';
ta.style.opacity = '0';
document.body.append(ta);
ta.select();
try { document.execCommand('copy'); copy.textContent = 'Copied'; } catch { /* the selection is still there to copy by hand */ }
ta.remove();
}
setTimeout(() => { copy.textContent = 'Copy JSON'; }, 2000);
});
}
const upgrade = this._panel.querySelector('[data-upgrade]');
if (upgrade && typeof this._meta.onUpgrade === 'function') {
upgrade.addEventListener('click', () => {
upgrade.disabled = true;
upgrade.textContent = 'Checking…';
this._meta.onUpgrade();
});
}
const stl = this._panel.querySelector('[data-stl]');
if (stl && typeof this._meta.onDownloadStl === 'function') {
stl.addEventListener('click', () => {
stl.disabled = true;
const label = stl.textContent;
stl.textContent = 'Preparing…';
Promise.resolve(this._meta.onDownloadStl()).finally(() => {
stl.disabled = false;
stl.textContent = label;
});
});
}
}
}
if (!customElements.get('engine-qa')) customElements.define('engine-qa', EngineQaCard);
export { EngineQaCard, VERDICTS };