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
feat(engine-qa): add the <engine-qa> panel component, shared by viewer and Rig Doctor
nirholas2599cd4ae677
diff --git a/public/engine-qa-panel.js b/public/engine-qa-panel.jsnew file mode 100644index 000000000..0d5f7e10a--- /dev/null+++ b/public/engine-qa-panel.js@@ -0,0 +1,496 @@+// <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)]);+ }++ const needsUpgrade = r.partial === true && c.triangleBudget.verdict === 'skip' && 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 (c.triangleBudget.verdict === 'skip' && !needsUpgrade) {+ 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 (c.collider.verdict === 'skip' && !needsUpgrade) {+ colliderHtml = `<h3>Collider fitness</h3><p class="note">${c.collider.reason || 'Not measured.'}</p>`;+ }++ const upgradeHtml = needsUpgrade && typeof this._meta.onUpgrade === 'function'+ ? `<h3>LOD budget & collider fitness</h3><p class="note">Not measured yet: this needs a real LOD build and the server's manifold analyzer.</p><button type="button" class="action" data-upgrade>Check LOD & collider fitness (uploads this file)</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 };