Skip to content

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.

feat(rig-doctor): add a zero-network, browser-only Engine QA partial grade

nirholas62ea70a173cc
diff --git a/src/engine-qa-client.js b/src/engine-qa-client.js
new file mode 100644
index 000000000..fe650b793
--- /dev/null
+++ b/src/engine-qa-client.js
@@ -0,0 +1,285 @@
+// Engine QA, computed entirely in the browser: zero network, zero upload.
+//
+// Rig Doctor's whole privacy claim ("No bytes are sent to any server... works
+// with the network disconnected") rules out posting a visitor's file to
+// /api/3d/engine-qa for the full server-side grade (api/_lib/engine-qa.js),
+// which needs Node-only dependencies (gltf-transform's NodeIO, the manifold
+// print pipeline) anyway. This module grades the three checks that are pure
+// math over bytes already in memory: draw calls, material count, and texel
+// density. It shares its thresholds and verdict logic with the server grader
+// via api/_lib/engine-qa-core.js, so the two can never disagree on a verdict.
+//
+// What it deliberately does NOT grade (returned as `skip`, never fabricated):
+// triangleBudget needs a real LOD chain, which needs real decimation work
+// (meshoptimizer), heavy enough that even the server gates
+// it behind its own rate limit. Rig Doctor's own offer to
+// build one is an explicit, visible upload: see
+// rig-doctor-page.js's `requestFullEngineQa`.
+// collider needs the manifold/watertight analyzer, which is a
+// server-only dependency chain (api/_lib/print/*). Same
+// explicit-upload offer covers this.
+//
+// Parses the raw GLB with rig-report.js's own byte-level reader rather than a
+// second JSON/BIN parser, so the two analyses of the same file can never
+// disagree about where the chunks are.
+
+import { readGlbJson } from './rig-report.js';
+import {
+ ENGINE_QA_VERSION,
+ ENGINE_QA_THRESHOLDS,
+ worstVerdict,
+ verdictFromBand,
+} from '../api/_lib/engine-qa-core.js';
+
+const MODE_TRIANGLES = 4;
+const COMPONENT_FLOAT = 5126;
+const INDEX_READERS = {
+ 5121: (dv, o) => dv.getUint8(o),
+ 5123: (dv, o) => dv.getUint16(o, true),
+ 5125: (dv, o) => dv.getUint32(o, true),
+};
+
+function sliceBin(buffer, jsonBytes) {
+ const c1Offset = 20 + jsonBytes;
+ if (c1Offset + 8 > buffer.byteLength) return null;
+ const view = new DataView(buffer);
+ const c1Len = view.getUint32(c1Offset, true);
+ return new Uint8Array(buffer, c1Offset + 8, c1Len);
+}
+
+// Only FLOAT VEC2/VEC3 accessors (positions and UVs are FLOAT in every mesh
+// this needs to measure); anything else, including quantized attributes,
+// returns null so the caller skips that primitive's area contribution rather
+// than misreading it.
+function readFloatAccessor(json, bin, accessorIndex, numComponents) {
+ const accessor = json.accessors?.[accessorIndex];
+ if (!accessor || accessor.sparse || accessor.componentType !== COMPONENT_FLOAT) return null;
+ if (typeof accessor.bufferView !== 'number' || !bin) return null;
+ const view = json.bufferViews?.[accessor.bufferView];
+ if (!view) return null;
+ const stride = view.byteStride || numComponents * 4;
+ const base = (view.byteOffset || 0) + (accessor.byteOffset || 0);
+ if (base + stride * Math.max(0, accessor.count - 1) + numComponents * 4 > bin.byteLength) return null;
+ const dv = new DataView(bin.buffer, bin.byteOffset + base);
+ return {
+ count: accessor.count,
+ get(i, out) {
+ const o = i * stride;
+ for (let c = 0; c < numComponents; c++) out[c] = dv.getFloat32(o + c * 4, true);
+ return out;
+ },
+ };
+}
+
+function readIndexAccessor(json, bin, accessorIndex) {
+ const accessor = json.accessors?.[accessorIndex];
+ if (!accessor || accessor.sparse) return null;
+ const reader = INDEX_READERS[accessor.componentType];
+ if (!reader || typeof accessor.bufferView !== 'number' || !bin) return null;
+ const view = json.bufferViews?.[accessor.bufferView];
+ if (!view) return null;
+ const compBytes = accessor.componentType === 5125 ? 4 : accessor.componentType === 5123 ? 2 : 1;
+ const stride = view.byteStride || compBytes;
+ const base = (view.byteOffset || 0) + (accessor.byteOffset || 0);
+ if (base + stride * Math.max(0, accessor.count - 1) + compBytes > bin.byteLength) return null;
+ const dv = new DataView(bin.buffer, bin.byteOffset + base);
+ return { count: accessor.count, get: (i) => reader(dv, i * stride) };
+}
+
+function mat4Identity() {
+ return [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1];
+}
+
+function mat4Multiply(a, b) {
+ const out = new Array(16);
+ for (let col = 0; col < 4; col++) {
+ for (let row = 0; row < 4; row++) {
+ out[col * 4 + row] =
+ a[0 * 4 + row] * b[col * 4 + 0] +
+ a[1 * 4 + row] * b[col * 4 + 1] +
+ a[2 * 4 + row] * b[col * 4 + 2] +
+ a[3 * 4 + row] * b[col * 4 + 3];
+ }
+ }
+ return out;
+}
+
+// Column-major, matching glTF's own convention and api/_lib/engine-qa.js's
+// transformPoint helper, so a mesh graded on both sides never gets two
+// different world-space triangle areas for the same transform.
+function localMatrix(node) {
+ if (Array.isArray(node.matrix) && node.matrix.length === 16) return node.matrix;
+ const [tx, ty, tz] = node.translation || [0, 0, 0];
+ const [x, y, z, w] = node.rotation || [0, 0, 0, 1];
+ const [sx, sy, sz] = node.scale || [1, 1, 1];
+ const r00 = 1 - 2 * (y * y + z * z), r01 = 2 * (x * y - z * w), r02 = 2 * (x * z + y * w);
+ const r10 = 2 * (x * y + z * w), r11 = 1 - 2 * (x * x + z * z), r12 = 2 * (y * z - x * w);
+ const r20 = 2 * (x * z - y * w), r21 = 2 * (y * z + x * w), r22 = 1 - 2 * (x * x + y * y);
+ return [
+ r00 * sx, r10 * sx, r20 * sx, 0,
+ r01 * sy, r11 * sy, r21 * sy, 0,
+ r02 * sz, r12 * sz, r22 * sz, 0,
+ tx, ty, tz, 1,
+ ];
+}
+
+function transformPoint(m, x, y, z) {
+ const w = m[3] * x + m[7] * y + m[11] * z + m[15] || 1;
+ return [
+ (m[0] * x + m[4] * y + m[8] * z + m[12]) / w,
+ (m[1] * x + m[5] * y + m[9] * z + m[13]) / w,
+ (m[2] * x + m[6] * y + m[10] * z + m[14]) / w,
+ ];
+}
+
+function triangleArea(a, b, c) {
+ const abx = b[0] - a[0], aby = b[1] - a[1], abz = b[2] - a[2];
+ const acx = c[0] - a[0], acy = c[1] - a[1], acz = c[2] - a[2];
+ const cx = aby * acz - abz * acy, cy = abz * acx - abx * acz, cz = abx * acy - aby * acx;
+ return 0.5 * Math.sqrt(cx * cx + cy * cy + cz * cz);
+}
+
+function triangleAreaUv(a, b, c) {
+ return Math.abs((b[0] - a[0]) * (c[1] - a[1]) - (c[0] - a[0]) * (b[1] - a[1])) / 2;
+}
+
+function firstTextureRef(material) {
+ if (!material) return null;
+ return (
+ material.pbrMetallicRoughness?.baseColorTexture ??
+ material.normalTexture ??
+ material.pbrMetallicRoughness?.metallicRoughnessTexture ??
+ material.emissiveTexture ??
+ material.occlusionTexture ??
+ null
+ );
+}
+
+// Decode an embedded (bufferView-backed) image to get its pixel size, via the
+// browser's own image decoder: no manual PNG/JPEG header parsing, and it
+// never leaves the tab because the bytes are already local. A `uri`-backed
+// image (external reference) is skipped rather than fetched: fetching it
+// would be this module's only network request, and the one guarantee Rig
+// Doctor makes is that there isn't one.
+async function textureSize(json, bin, textureRef) {
+ const texture = json.textures?.[textureRef?.index];
+ const image = json.images?.[texture?.source];
+ if (!image || typeof image.bufferView !== 'number' || !bin) return null;
+ const view = json.bufferViews?.[image.bufferView];
+ if (!view) return null;
+ const start = (view.byteOffset || 0);
+ const bytes = bin.subarray(start, start + view.byteLength);
+ const blob = new Blob([bytes], { type: image.mimeType || 'image/png' });
+ try {
+ const bitmap = await createImageBitmap(blob);
+ const size = [bitmap.width, bitmap.height];
+ bitmap.close?.();
+ return size;
+ } catch {
+ return null;
+ }
+}
+
+/**
+ * Grade the checks that are pure math over bytes already in memory: draw
+ * calls, material count, and texel density. `triangleBudget` and `collider`
+ * come back `skip` with a reason pointing at the explicit upload path.
+ *
+ * @param {ArrayBuffer} buffer a GLB already read into memory (FileReader result)
+ */
+export async function gradeEngineQaClient(buffer) {
+ const { json, jsonBytes } = readGlbJson(buffer);
+ const bin = sliceBin(buffer, jsonBytes);
+
+ const materialCount = (json.materials || []).length;
+ const textureCount = (json.textures || []).length;
+
+ const sceneIndex = json.scene ?? 0;
+ const rootIndices = json.scenes?.[sceneIndex]?.nodes ?? [];
+ const seen = new Set();
+ let drawCalls = 0;
+ let totalWorldAreaM2 = 0;
+ let totalUvAreaTexels = 0;
+ let anyMeasured = false;
+
+ const visit = async (nodeIndex, parentMatrix) => {
+ if (seen.has(nodeIndex)) return;
+ seen.add(nodeIndex);
+ const node = json.nodes?.[nodeIndex];
+ if (!node) return;
+ const matrix = mat4Multiply(parentMatrix, localMatrix(node));
+
+ if (typeof node.mesh === 'number') {
+ for (const prim of json.meshes?.[node.mesh]?.primitives || []) {
+ if ((prim.mode ?? MODE_TRIANGLES) !== MODE_TRIANGLES) continue;
+ drawCalls += 1;
+
+ const posAcc = prim.attributes?.POSITION;
+ const uvAcc = prim.attributes?.TEXCOORD_0;
+ const material = json.materials?.[prim.material];
+ const textureRef = firstTextureRef(material);
+ if (posAcc == null || uvAcc == null || !textureRef) continue;
+
+ const position = readFloatAccessor(json, bin, posAcc, 3);
+ const uv = readFloatAccessor(json, bin, uvAcc, 2);
+ if (!position || !uv) continue;
+ const size = await textureSize(json, bin, textureRef);
+ if (!size) continue;
+ const [texWidth, texHeight] = size;
+
+ const index = prim.indices != null ? readIndexAccessor(json, bin, prim.indices) : null;
+ const count = index ? index.count : position.count;
+ const p = [0, 0, 0], uvA = [0, 0], uvB = [0, 0], uvC = [0, 0];
+ for (let i = 0; i + 2 < count; i += 3) {
+ const ia = index ? index.get(i) : i;
+ const ib = index ? index.get(i + 1) : i + 1;
+ const ic = index ? index.get(i + 2) : i + 2;
+
+ const a = transformPoint(matrix, ...position.get(ia, p));
+ const b = transformPoint(matrix, ...position.get(ib, p));
+ const c = transformPoint(matrix, ...position.get(ic, p));
+ totalWorldAreaM2 += triangleArea(a, b, c);
+
+ uv.get(ia, uvA);
+ uv.get(ib, uvB);
+ uv.get(ic, uvC);
+ totalUvAreaTexels += triangleAreaUv(uvA, uvB, uvC) * texWidth * texHeight;
+ anyMeasured = true;
+ }
+ }
+ }
+ for (const childIndex of node.children || []) await visit(childIndex, matrix);
+ };
+ for (const rootIndex of rootIndices) await visit(rootIndex, mat4Identity());
+
+ const drawCallsCheck = { value: drawCalls, verdict: verdictFromBand(drawCalls, ENGINE_QA_THRESHOLDS.drawCalls), thresholds: ENGINE_QA_THRESHOLDS.drawCalls };
+ const materialCountCheck = { value: materialCount, verdict: verdictFromBand(materialCount, ENGINE_QA_THRESHOLDS.materialCount), thresholds: ENGINE_QA_THRESHOLDS.materialCount };
+
+ let texelDensityCheck;
+ if (anyMeasured && totalWorldAreaM2 > 0) {
+ const pxPerMeter = Math.round(Math.sqrt(totalUvAreaTexels / totalWorldAreaM2));
+ const { minPxPerMeter, maxPxPerMeter } = ENGINE_QA_THRESHOLDS.texelDensity;
+ const verdict = pxPerMeter < minPxPerMeter ? 'fail' : pxPerMeter > maxPxPerMeter ? 'warn' : 'pass';
+ texelDensityCheck = { value: pxPerMeter, verdict, thresholds: ENGINE_QA_THRESHOLDS.texelDensity };
+ } else {
+ texelDensityCheck = { value: null, verdict: 'skip', reason: 'no UV-mapped texture found to measure' };
+ }
+
+ const checks = {
+ drawCalls: drawCallsCheck,
+ materialCount: materialCountCheck,
+ texelDensity: texelDensityCheck,
+ triangleBudget: { value: null, verdict: 'skip', reason: 'requires building a real LOD chain; use "Check LOD & collider fitness" to run it' },
+ collider: { value: null, verdict: 'skip', reason: 'requires the server-side manifold analyzer; use "Check LOD & collider fitness" to run it' },
+ };
+
+ return {
+ version: ENGINE_QA_VERSION,
+ overall: worstVerdict(Object.values(checks).map((c) => c.verdict)),
+ materialCount,
+ textureCount,
+ drawCalls,
+ partial: true,
+ checks,
+ };
+}
diff --git a/tests/engine-qa-client.test.js b/tests/engine-qa-client.test.js
new file mode 100644
index 000000000..71cc1efb7
--- /dev/null
+++ b/tests/engine-qa-client.test.js
@@ -0,0 +1,140 @@
+// src/engine-qa-client.js: the browser-only partial grade Rig Doctor runs
+// with zero network. There is no real browser in this suite, so the one
+// browser-only primitive it needs (createImageBitmap) is polyfilled with a
+// real PNG decode (sharp), exactly like tests/engine-qa.test.js polyfills the
+// bytes for the server-side grader. Everything else, including the GLB
+// parsing and the matrix/area math, is the real module, unmodified.
+import { describe, it, expect, beforeAll } from 'vitest';
+import { Document, NodeIO } from '@gltf-transform/core';
+import { gradeEngineQaClient } from '../src/engine-qa-client.js';
+
+function cubeMesh(size) {
+ const h = size / 2;
+ const positions = [
+ -h, -h, -h, h, -h, -h, h, h, -h, -h, h, -h,
+ -h, -h, h, h, -h, h, h, h, h, -h, h, h,
+ ];
+ const faces = [
+ [0, 2, 1], [0, 3, 2], [4, 5, 6], [4, 6, 7],
+ [0, 1, 5], [0, 5, 4], [3, 7, 6], [3, 6, 2],
+ [0, 4, 7], [0, 7, 3], [1, 2, 6], [1, 6, 5],
+ ];
+ return { positions, indices: faces.flat() };
+}
+
+function planeMesh(width, depth) {
+ const hw = width / 2, hd = depth / 2;
+ return {
+ positions: [-hw, 0, -hd, hw, 0, -hd, hw, 0, hd, -hw, 0, hd],
+ indices: [0, 2, 1, 0, 3, 2],
+ uv: [0, 0, 1, 0, 1, 1, 0, 1],
+ };
+}
+
+let pngCache = new Map();
+async function pngBuffer(width, height) {
+ const key = `${width}x${height}`;
+ if (!pngCache.has(key)) {
+ const sharp = (await import('sharp')).default;
+ pngCache.set(key, sharp({ create: { width, height, channels: 4, background: { r: 128, g: 128, b: 128, alpha: 1 } } }).png().toBuffer());
+ }
+ return pngCache.get(key);
+}
+
+async function buildGlbArrayBuffer(parts) {
+ const doc = new Document();
+ const buffer = doc.createBuffer();
+ const scene = doc.createScene('scene');
+ const materials = new Map();
+ const textures = new Map();
+
+ for (const [i, part] of parts.entries()) {
+ const position = doc.createAccessor().setType('VEC3').setArray(new Float32Array(part.positions)).setBuffer(buffer);
+ const index = doc.createAccessor().setType('SCALAR').setArray(new Uint32Array(part.indices)).setBuffer(buffer);
+ const prim = doc.createPrimitive().setAttribute('POSITION', position).setIndices(index);
+
+ if (part.uv) {
+ const uv = doc.createAccessor().setType('VEC2').setArray(new Float32Array(part.uv)).setBuffer(buffer);
+ prim.setAttribute('TEXCOORD_0', uv);
+ }
+
+ const materialKey = part.materialKey ?? `material-${i}`;
+ if (!materials.has(materialKey)) {
+ const material = doc.createMaterial(materialKey);
+ if (part.textureSize) {
+ const textureKey = `${materialKey}:${part.textureSize.join('x')}`;
+ if (!textures.has(textureKey)) {
+ const [w, h] = part.textureSize;
+ const image = await pngBuffer(w, h);
+ textures.set(textureKey, doc.createTexture(textureKey).setMimeType('image/png').setImage(new Uint8Array(image)));
+ }
+ material.setBaseColorTexture(textures.get(textureKey));
+ }
+ materials.set(materialKey, material);
+ }
+ prim.setMaterial(materials.get(materialKey));
+
+ const mesh = doc.createMesh(`mesh-${i}`).addPrimitive(prim);
+ const node = doc.createNode(`node-${i}`).setMesh(mesh);
+ scene.addChild(node);
+ }
+
+ const bytes = await new NodeIO().writeBinary(doc);
+ return bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength);
+}
+
+beforeAll(() => {
+ // eslint-disable-next-line no-undef
+ globalThis.createImageBitmap = async (blob) => {
+ const sharp = (await import('sharp')).default;
+ const buf = Buffer.from(await blob.arrayBuffer());
+ const meta = await sharp(buf).metadata();
+ return { width: meta.width, height: meta.height, close() {} };
+ };
+});
+
+describe('gradeEngineQaClient', () => {
+ it('grades draw calls and material count from real GLB bytes with no texture', async () => {
+ const buffer = await buildGlbArrayBuffer([{ ...cubeMesh(0.4) }]);
+ const report = await gradeEngineQaClient(buffer);
+
+ expect(report.partial).toBe(true);
+ expect(report.drawCalls).toBe(1);
+ expect(report.materialCount).toBe(1);
+ expect(report.checks.drawCalls.verdict).toBe('pass');
+ expect(report.checks.materialCount.verdict).toBe('pass');
+ });
+
+ it('counts one draw call per node+primitive and flags the warn band', async () => {
+ const parts = Array.from({ length: 25 }, () => ({ ...cubeMesh(0.1) }));
+ const buffer = await buildGlbArrayBuffer(parts);
+ const report = await gradeEngineQaClient(buffer);
+
+ expect(report.drawCalls).toBe(25);
+ expect(report.checks.drawCalls.verdict).toBe('warn');
+ });
+
+ it('skips texel density when nothing is UV-mapped to a texture', async () => {
+ const buffer = await buildGlbArrayBuffer([{ ...cubeMesh(0.4) }]);
+ const report = await gradeEngineQaClient(buffer);
+ expect(report.checks.texelDensity.verdict).toBe('skip');
+ expect(report.checks.texelDensity.value).toBeNull();
+ });
+
+ it('measures texel density from real UV + decoded-image data, matching the closed form', async () => {
+ const buffer = await buildGlbArrayBuffer([{ ...planeMesh(1, 1), textureSize: [512, 512] }]);
+ const report = await gradeEngineQaClient(buffer);
+ // sqrt(512*512 / (1*1)) = 512
+ expect(report.checks.texelDensity.value).toBeCloseTo(512, 0);
+ expect(report.checks.texelDensity.verdict).toBe('pass');
+ });
+
+ it('always skips triangleBudget and collider with an actionable reason, matching the explicit-upload design', async () => {
+ const buffer = await buildGlbArrayBuffer([{ ...cubeMesh(0.4) }]);
+ const report = await gradeEngineQaClient(buffer);
+ expect(report.checks.triangleBudget.verdict).toBe('skip');
+ expect(report.checks.collider.verdict).toBe('skip');
+ expect(report.checks.triangleBudget.reason).toMatch(/LOD/);
+ expect(report.checks.collider.reason).toMatch(/manifold/);
+ });
+});