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.

6.3 KB
Raw Blame
// One loader for the <model-viewer> custom element.
//
// Five pickers used to inject the Google-hosted script with no `onerror`, so
// on a network that blocks ajax.googleapis.com (corporate proxies, some
// regions, aggressive blockers) the element never upgraded and every
// <model-viewer> sat as an inert empty box with no message. This module tries
// each CDN in turn, resolves once the element is defined, and rejects with a
// user-readable error when every host fails, so a caller can show a poster
// image or a "3D preview unavailable" state instead of nothing.
//
// The same version is served from three independent CDNs; any one of them is
// the whole library, so the first that loads wins and the rest are never hit.
// Google's own ajax.googleapis.com mirror is not in the chain: it never
// published 4.4.0, so that rung would only ever 404.

const VERSION = '4.4.0';
const SOURCES = [
	`https://cdn.jsdelivr.net/npm/@google/model-viewer@${VERSION}/dist/model-viewer.min.js`,
	`https://cdnjs.cloudflare.com/ajax/libs/model-viewer/${VERSION}/model-viewer.min.js`,
	`https://unpkg.com/@google/model-viewer@${VERSION}/dist/model-viewer.min.js`,
];
// A script that neither loads nor errors (a black-holed CDN) is treated as
// failed after this long, so the chain moves on instead of waiting forever.
const PER_SOURCE_TIMEOUT_MS = 12_000;

let _pending = null;
let _defineGuarded = false;

// model-viewer auto-loads Draco and KTX2 but leaves the meshopt decoder unset,
// and every server-baked avatar and Forge GLB ships EXT_meshopt_compression, so
// without it the viewer throws "setMeshoptDecoder must be called before loading
// compressed files" and the model never renders. The decoder config is captured
// when a load starts, so it is set inside define(), before any element upgrades.
// Same-origin copy, vendored by scripts/vendor-meshopt-decoder.mjs (the same
// file public/model-viewer-meshopt.js points classic-script pages at).
const MESHOPT_DECODER_URL = '/vendor/meshopt_decoder.js';

function registerMeshopt(ctor) {
	if (!ctor || ctor.meshoptDecoderLocation) return;
	try {
		ctor.meshoptDecoderLocation = MESHOPT_DECODER_URL;
	} catch {
		/* read-only in some future build: the model-viewer default stands */
	}
}

// The chain abandons a source after PER_SOURCE_TIMEOUT_MS, but removing a
// <script> does not cancel a fetch already in flight: a slow first CDN can
// still execute after a later one defined the element, and that second
// customElements.define('model-viewer', ...) throws an uncaught
// NotSupportedError ("the name model-viewer has already been used with this
// registry") onto the page console. Every source here serves the identical
// library, so the first definition wins and a duplicate is a no-op. Scoped to
// this one element name so a genuine double-define anywhere else still throws.
function guardDuplicateDefine() {
	if (_defineGuarded || typeof customElements === 'undefined') return;
	_defineGuarded = true;
	const nativeDefine = customElements.define;
	customElements.define = function (name, ctor, options) {
		if (name === 'model-viewer') {
			if (customElements.get(name)) return undefined;
			registerMeshopt(ctor);
		}
		return nativeDefine.call(this, name, ctor, options);
	};
}

function loadScript(src) {
	return new Promise((resolve, reject) => {
		const s = document.createElement('script');
		s.type = 'module';
		s.src = src;
		s.crossOrigin = 'anonymous';
		const timer = setTimeout(() => {
			s.remove();
			reject(new Error(`timed out loading ${src}`));
		}, PER_SOURCE_TIMEOUT_MS);
		s.onload = () => {
			clearTimeout(timer);
			resolve();
		};
		s.onerror = () => {
			clearTimeout(timer);
			s.remove();
			reject(new Error(`failed to load ${src}`));
		};
		document.head.appendChild(s);
	});
}

/**
 * Resolve once `customElements.get('model-viewer')` is defined. Safe to call
 * from many components at once: one load is shared. A failure is remembered
 * only for the duration of the attempt, so a later call (a retry button) tries
 * the chain again.
 *
 * @returns {Promise<void>}
 */
export function ensureModelViewer() {
	if (typeof customElements !== 'undefined' && customElements.get('model-viewer')) {
		registerMeshopt(customElements.get('model-viewer'));
		return Promise.resolve();
	}
	if (_pending) return _pending;
	guardDuplicateDefine();
	_pending = (async () => {
		let lastErr;
		for (const src of SOURCES) {
			// An abandoned source can still land while the next one is being
			// picked; if it did, the chain is already done.
			if (customElements.get('model-viewer')) return;
			try {
				await loadScript(src);
				if (customElements.get('model-viewer')) return;
				await customElements.whenDefined('model-viewer');
				return;
			} catch (err) {
				lastErr = err;
			}
		}
		document.documentElement.dispatchEvent(new CustomEvent('model-viewer:unavailable', { bubbles: false }));
		throw Object.assign(new Error('The 3D viewer could not be loaded. Check your connection or ad blocker and try again.'), {
			code: 'model_viewer_unavailable',
			cause: lastErr,
		});
	})().finally(() => {
		_pending = null;
	});
	return _pending;
}

/**
 * Fire-and-forget variant for pickers that render <model-viewer> tags eagerly:
 * on failure every viewer in `root` gets a visible fallback (its `poster`
 * image if set, else a short caption) rather than staying blank.
 *
 * @param {ParentNode} [root=document]
 */
export function ensureModelViewerOrFallback(root = document) {
	return ensureModelViewer().catch((err) => {
		for (const mv of root.querySelectorAll('model-viewer')) {
			if (mv.dataset.mvFallback) continue;
			mv.dataset.mvFallback = '1';
			const poster = mv.getAttribute('poster');
			const box = document.createElement('div');
			box.className = 'mv-fallback';
			box.setAttribute('role', 'img');
			box.setAttribute('aria-label', mv.getAttribute('alt') || '3D preview unavailable');
			box.style.cssText = 'display:flex;align-items:center;justify-content:center;width:100%;height:100%;min-height:120px;font:500 12px/1.4 system-ui,sans-serif;color:#9aa4b2;text-align:center;padding:8px;box-sizing:border-box;';
			if (poster) {
				box.style.background = `center / cover no-repeat url("${poster}")`;
				box.textContent = '';
			} else {
				box.textContent = '3D preview unavailable';
			}
			mv.replaceWith(box);
		}
		console.warn('[model-viewer]', err?.message || err);
	});
}