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.

5.8 KB
Raw Blame
// GLB container surgery: the step that lets three.js parse an avatar in Node.
//
// The renderer strips every image out of a glTF before GLTFLoader sees it,
// because the loader's texture path needs a DOM. These tests hold the contract
// that makes the re-attach step possible: images come out intact, materials
// keep an index marker, and the repacked container is still a valid GLB.

import { describe, it, expect } from 'vitest';
import { readFileSync } from 'node:fs';
import { fileURLToPath } from 'node:url';
import { parseGlb, packGlb, extractImages, stripImages } from '../src/glb.js';

const ROOT = fileURLToPath(new URL('../../../', import.meta.url));
const AVATAR = `${ROOT}public/avatars/default.glb`;

function readAvatar() {
	const buf = readFileSync(AVATAR);
	return buf.buffer.slice(buf.byteOffset, buf.byteOffset + buf.byteLength);
}

describe('parseGlb', () => {
	it('splits a real avatar into JSON and BIN chunks', () => {
		const { json, bin } = parseGlb(readAvatar());
		expect(json.asset.version).toBe('2.0');
		expect(json.meshes.length).toBeGreaterThan(0);
		expect(bin.byteLength).toBeGreaterThan(0);
	});

	it('refuses anything that is not a GLB', () => {
		const notGlb = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12]).buffer;
		expect(() => parseGlb(notGlb)).toThrow(/not a GLB/);
	});
});

describe('packGlb', () => {
	it('round-trips a parsed container', () => {
		const original = parseGlb(readAvatar());
		const repacked = parseGlb(packGlb(original.json, original.bin));
		expect(repacked.json.meshes.length).toBe(original.json.meshes.length);
		expect(repacked.bin.byteLength).toBe(original.bin.byteLength);
	});

	it('pads the JSON chunk with spaces, as the spec requires', () => {
		const packed = packGlb({ asset: { version: '2.0' }, x: 'pad' }, null);
		const bytes = new Uint8Array(packed);
		const length = new DataView(packed).getUint32(12, true);
		// Every byte of a chunk beyond the JSON text must be 0x20, never 0x00.
		const text = new TextDecoder().decode(bytes.subarray(20, 20 + length));
		expect(text.trimEnd()).toBe(JSON.stringify({ asset: { version: '2.0' }, x: 'pad' }));
		expect(text.slice(text.trimEnd().length)).toMatch(/^ *$/);
	});

	it('keeps a bin-less container valid', () => {
		const { json } = parseGlb(packGlb({ asset: { version: '2.0' } }, null));
		expect(json.asset.version).toBe('2.0');
	});
});

describe('extractImages', () => {
	it('lifts every embedded texture out of the binary chunk', () => {
		const { json, bin } = parseGlb(readAvatar());
		const images = extractImages(json, bin);
		expect(images.size).toBe(json.images.length);
		for (const [, image] of images) {
			expect(image.bytes.byteLength).toBeGreaterThan(0);
			expect(image.mimeType).toMatch(/^image\//);
		}
	});

	it('decodes data-URI images', () => {
		const png = Buffer.from('89504e470d0a1a0a', 'hex').toString('base64');
		const images = extractImages({ images: [{ uri: `data:image/png;base64,${png}` }] }, null);
		expect(images.get(0).mimeType).toBe('image/png');
		expect(images.get(0).bytes.length).toBe(8);
	});

	it('skips images that live behind an external URI', () => {
		const images = extractImages({ images: [{ uri: 'skin.png' }] }, null);
		expect(images.size).toBe(0);
	});
});

describe('stripImages', () => {
	it('removes every image, texture and sampler', () => {
		const { json } = parseGlb(readAvatar());
		const { json: stripped } = stripImages(json);
		expect(stripped.images).toBeUndefined();
		expect(stripped.textures).toBeUndefined();
		expect(stripped.samplers).toBeUndefined();
		for (const material of stripped.materials) {
			expect(material.pbrMetallicRoughness?.baseColorTexture).toBeUndefined();
			expect(material.normalTexture).toBeUndefined();
		}
	});

	it('marks each material with its index so textures can be re-attached', () => {
		const { json } = parseGlb(readAvatar());
		const { json: stripped } = stripImages(json);
		stripped.materials.forEach((material, index) => {
			expect(material.extras.__twsMaterial).toBe(index);
		});
	});

	it('records what each material was using', () => {
		const { json } = parseGlb(readAvatar());
		const { bindings } = stripImages(json);
		expect(bindings.size).toBe(json.materials.length);
		const textured = [...bindings.values()].filter((b) => b.baseColor);
		expect(textured.length).toBeGreaterThan(0);
		for (const binding of textured) {
			expect(typeof binding.baseColor.image).toBe('number');
			expect(['repeat', 'clamp', 'mirror']).toContain(binding.baseColor.wrapS);
		}
	});

	it('does not mutate the source JSON', () => {
		const { json } = parseGlb(readAvatar());
		const before = json.images.length;
		stripImages(json);
		expect(json.images.length).toBe(before);
		expect(json.materials[0].extras?.__twsMaterial).toBeUndefined();
	});

	it('drops extensions whose decoders this renderer does not ship', () => {
		const { json: stripped } = stripImages({
			extensionsUsed: ['KHR_texture_basisu', 'EXT_meshopt_compression'],
			materials: [],
		});
		expect(stripped.extensionsUsed).toEqual(['EXT_meshopt_compression']);
	});
});

describe('stripImages with EXT_texture_webp', () => {
	it('binds the WebP payload a texture declares in its extension', () => {
		// The texture names its image only inside EXT_texture_webp, as every
		// gltf-transform WebP export does; reading `source` alone left the
		// material untextured (bare white) on the CPU lane.
		const json = {
			asset: { version: '2.0' },
			images: [{ mimeType: 'image/png' }, { mimeType: 'image/webp' }],
			textures: [{ source: 0, extensions: { EXT_texture_webp: { source: 1 } } }, { extensions: { EXT_texture_webp: { source: 1 } } }],
			materials: [
				{ pbrMetallicRoughness: { baseColorTexture: { index: 0 } } },
				{ pbrMetallicRoughness: { baseColorTexture: { index: 1 } } },
			],
		};
		const { bindings } = stripImages(json);
		expect(bindings.get(0).baseColor.image).toBe(1);
		expect(bindings.get(1).baseColor.image).toBe(1);
	});
});