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.

20.7 KB
Raw Blame
// Multi-format export layered onto the forge result viewer.
//
// The download button always offers the source GLB instantly. This module adds
// a format menu beside it. Most formats convert the live model in the browser
// with three.js exporters, so there is no worker, no queue and no upload:
//   • OBJ  : universal geometry for DCC tools (geometry + UVs, no materials)
//   • STL  : solid geometry for 3D printing (binary)
//   • PLY  : vertex data for scanning/point-cloud tools (binary)
//   • USDZ : textured AR asset for iPhone / Vision Pro
//
// Two formats have no browser exporter and are converted by the remesh worker
// (POST /api/forge-remesh with operation:"convert"), which authors them from
// the source GLB and hands back a storage URL:
//   • FBX  : rigged interchange for Unity / Unreal / Maya (keeps the skeleton)
//   • 3MF  : modern manufacturing package for slicers and print services
//
// The worker already backed both formats and the optimize panel already
// exposed all seven; this menu offered only the five it could do client-side,
// so the download button and the optimize panel disagreed about what the
// platform supports. A server format is a real job, so it reports queued
// progress and can fail with a message rather than resolving instantly.
//
// three.js and the exporters load lazily on first use; the parsed scene is
// cached per model URL so switching formats doesn't re-download the GLB.
// Like the stylize/optimize panels, this module injects its own markup and
// styles and only needs the result panel's download anchor to exist.

import { copyReadme3d, describeResult } from './readme-3d-copy.js';
import { createLogger } from './shared/log.js';
import { creationIdFromGlbUrl, mountSlicerMenuItems } from './slicer-handoff.js';
import { mountCraftcloudMenuItem } from './craftcloud-print.js';

const log = createLogger('forge-export');

const download = document.getElementById('download');
const resultPanel = document.getElementById('state-result');

if (download && resultPanel) {
	const FORMATS = [
		{
			id: 'glb',
			label: 'GLB',
			blurb: 'Source format — textures embedded. Works everywhere glTF does.',
			ext: 'glb',
		},
		{
			id: 'obj',
			label: 'OBJ',
			blurb: 'Universal geometry + UVs for Blender, Maya, C4D. Materials not included.',
			ext: 'obj',
			mime: 'text/plain',
		},
		{
			id: 'stl',
			label: 'STL',
			blurb: 'Solid geometry for 3D printing and CAD. Binary, compact.',
			ext: 'stl',
			mime: 'model/stl',
		},
		{
			id: 'ply',
			label: 'PLY',
			blurb: 'Vertex-level data for scanning and point-cloud tools. Binary.',
			ext: 'ply',
			mime: 'application/octet-stream',
		},
		{
			id: 'usdz',
			label: 'USDZ',
			blurb: 'Textured AR asset — opens directly on iPhone and Vision Pro.',
			ext: 'usdz',
			mime: 'model/vnd.usdz+zip',
		},
		{
			id: 'readme',
			label: 'GitHub README 3D',
			tag: 'README',
			blurb: 'Copy as GitHub README 3D: paste into any README or issue and GitHub renders it as an interactive 3D model.',
			ext: 'md',
			readme: true,
		},
		{
			id: 'fbx',
			label: 'FBX',
			blurb: 'Rigged interchange for Unity, Unreal and Maya. Keeps the skeleton. Converted on the server.',
			ext: 'fbx',
			server: true,
		},
		{
			id: '3mf',
			label: '3MF',
			blurb: 'Manufacturing package for slicers and print services. Converted on the server.',
			ext: '3mf',
			server: true,
		},
	];

	// ---- markup ------------------------------------------------------------

	const style = document.createElement('style');
	style.textContent = `
		.export-split { position: relative; display: inline-flex; align-items: stretch; }
		.export-caret {
			display: inline-flex; align-items: center; justify-content: center;
			margin-left: 1px; padding: 0 0.55rem;
			border: 1px solid var(--border, rgba(255,255,255,0.14));
			border-radius: 0 8px 8px 0; background: var(--surface-2, rgba(255,255,255,0.05));
			color: inherit; cursor: pointer;
			transition: background 0.15s ease, border-color 0.15s ease;
		}
		.export-caret:hover, .export-caret:focus-visible { background: var(--surface-3, rgba(255,255,255,0.1)); }
		.export-caret:focus-visible { outline: 2px solid var(--accent, #7c6cff); outline-offset: 2px; }
		.export-caret svg { width: 12px; height: 12px; transition: transform 0.18s ease; }
		.export-caret[aria-expanded="true"] svg { transform: rotate(180deg); }
		.export-split > a { border-top-right-radius: 0 !important; border-bottom-right-radius: 0 !important; }
		.export-menu {
			position: absolute; right: 0; bottom: calc(100% + 8px); z-index: 40;
			/* Width is capped to the viewport as a first line of defence; the menu
			   is anchored to the button's right edge, which is itself inset, so
			   clampIntoView() below does the rest once the real geometry is known. */
			width: min(290px, calc(100vw - 1.5rem)); padding: 0.35rem;
			/* Set by clampIntoView() when right-anchoring would put the left edge
			   off-screen. Zero is the ordinary desktop case. */
			transform: translateX(var(--export-menu-shift, 0px));
			border: 1px solid var(--border, rgba(255,255,255,0.14));
			border-radius: 12px;
			background: var(--surface-1, #16161d);
			box-shadow: 0 16px 40px rgba(0,0,0,0.45);
			opacity: 0; pointer-events: none;
			transition: opacity 0.16s ease, transform 0.16s ease;
		}
		.export-menu { transform: translate(var(--export-menu-shift, 0px), 6px); }
		.export-menu.is-open {
			opacity: 1; pointer-events: auto;
			transform: translate(var(--export-menu-shift, 0px), 0);
		}
		.export-item {
			display: flex; align-items: baseline; gap: 0.65rem; width: 100%;
			padding: 0.55rem 0.7rem; border: 0; border-radius: 8px;
			background: transparent; color: inherit; text-align: left; cursor: pointer;
			transition: background 0.12s ease;
		}
		.export-item:hover, .export-item:focus-visible { background: var(--surface-3, rgba(255,255,255,0.08)); }
		.export-item:focus-visible { outline: 2px solid var(--accent, #7c6cff); outline-offset: -2px; }
		.export-item[aria-disabled="true"] { opacity: 0.55; cursor: progress; }
		.export-item .fmt { font-weight: 600; font-size: 0.86rem; min-width: 3.2em; letter-spacing: 0.02em; }
		.export-item .blurb { flex: 1; font-size: 0.78rem; opacity: 0.72; line-height: 1.35; }
		.export-item .status { font-size: 0.74rem; min-width: 5.5em; text-align: right; opacity: 0.85; }
		.export-item .status.is-error { color: var(--danger, #ff6b6b); }
		/* A server format's status can carry a whole sentence (a converter error,
		   or the download-again link). The five client-side formats still resolve
		   in a word, so the column only grows when it has something to say. */
		.export-item .status:has(.export-again), .export-item .status.is-error { min-width: 9em; }
		.export-item .export-again { color: inherit; text-decoration: underline; text-underline-offset: 2px; }
		.export-item .export-again:hover, .export-item .export-again:focus-visible { opacity: 1; text-decoration-thickness: 2px; }
		.export-menu-footer {
			margin-top: 0.3rem; padding: 0.5rem 0.6rem 0.3rem;
			border-top: 1px solid var(--border, rgba(255,255,255,0.1));
			font-size: 0.72rem; line-height: 1.4; opacity: 0.7;
		}
		.export-menu-footer a { color: inherit; text-decoration: underline; text-underline-offset: 2px; }
		.export-menu-footer a:hover, .export-menu-footer a:focus-visible { opacity: 1; }
		.export-menu-footer a:focus-visible { outline: 2px solid var(--accent, #7c6cff); outline-offset: 1px; }
		.export-spinner {
			display: inline-block; width: 0.85em; height: 0.85em; vertical-align: -0.1em;
			border: 2px solid currentColor; border-right-color: transparent;
			border-radius: 50%; animation: export-spin 0.7s linear infinite;
		}
		@keyframes export-spin { to { transform: rotate(360deg); } }
		@media (prefers-reduced-motion: reduce) {
			.export-menu { transition: none; }
			.export-caret svg { transition: none; }
			.export-spinner { animation-duration: 1.5s; }
		}
	`;
	document.head.appendChild(style);

	const split = document.createElement('div');
	split.className = 'export-split';
	download.parentNode.insertBefore(split, download);
	split.appendChild(download);

	const caret = document.createElement('button');
	caret.type = 'button';
	caret.className = 'export-caret';
	caret.setAttribute('aria-haspopup', 'menu');
	caret.setAttribute('aria-expanded', 'false');
	caret.setAttribute('aria-label', 'More download formats');
	caret.title = 'More formats, or open in a 3D-printing slicer';
	caret.innerHTML =
		'<svg viewBox="0 0 12 12" fill="none" aria-hidden="true"><path d="M2 4.5 6 8.5 10 4.5" stroke="currentColor" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round"/></svg>';
	split.appendChild(caret);

	const menu = document.createElement('div');
	menu.className = 'export-menu';
	menu.setAttribute('role', 'menu');
	menu.setAttribute('aria-label', 'Download format');
	split.appendChild(menu);

	const itemStatus = new Map();
	for (const f of FORMATS) {
		const item = document.createElement('button');
		item.type = 'button';
		item.className = 'export-item';
		item.setAttribute('role', 'menuitem');
		item.dataset.format = f.id;
		item.innerHTML = `
			<span class="fmt">${f.tag || `.${f.ext}`}</span>
			<span class="blurb">${f.blurb}</span>
			<span class="status" aria-live="polite"></span>
		`;
		item.addEventListener('click', () => onPick(f, item));
		menu.appendChild(item);
		itemStatus.set(f.id, item.querySelector('.status'));
	}

	// Slicer handoff rows (OrcaSlicer, Bambu Studio). They download the stored
	// creation from /api/slicer/<id>/model.stl, so they appear only for a model
	// that has a creation id, and say so when the viewer shows an unsaved edit.
	const slicerItems = mountSlicerMenuItems(menu, {
		isLocalEdit: () => (download.getAttribute('href') || '').startsWith('blob:'),
	});

	// "Get it printed": live Craftcloud prices for this model, buyer pays
	// Craftcloud directly. Shown once a model is ready, same gating as the
	// slicer rows above.
	const craftcloudItem = mountCraftcloudMenuItem(menu);

	// How this file was made: the mesh pipeline behind every export, credited
	// right where a technical visitor would look for it.
	const footer = document.createElement('div');
	footer.className = 'export-menu-footer';
	footer.innerHTML =
		'How this file was made: meshes are decoded and optimized with ' +
		'<a href="/open-source#area-formats" rel="noopener">meshoptimizer and glTF-Transform</a>.';
	menu.appendChild(footer);

	// ---- menu behavior -------------------------------------------------------

	// The menu is right-anchored to the split button, which sits inset from the
	// page edge. On a narrow viewport that puts its LEFT edge off-screen (at
	// 320px the format names sat at x=-46 and were simply unreadable) without
	// ever overflowing the document, so no scrollbar appeared to hint at it.
	// Measure once per open and slide it back inside the gutter.
	const VIEWPORT_GUTTER_PX = 12;
	function clampIntoView() {
		menu.style.removeProperty('--export-menu-shift');
		const left = menu.getBoundingClientRect().left;
		if (left < VIEWPORT_GUTTER_PX) {
			menu.style.setProperty('--export-menu-shift', `${Math.ceil(VIEWPORT_GUTTER_PX - left)}px`);
		}
	}

	function setOpen(open) {
		// Clamp BEFORE the class flips so the menu animates in already in place,
		// rather than sliding sideways after the user can see it.
		if (open) clampIntoView();
		menu.classList.toggle('is-open', open);
		caret.setAttribute('aria-expanded', String(open));
		if (open) menu.querySelector('.export-item')?.focus();
	}

	// A resize or an orientation change invalidates the measurement.
	addEventListener('resize', () => {
		if (menu.classList.contains('is-open')) clampIntoView();
	});
	const isOpen = () => menu.classList.contains('is-open');

	caret.addEventListener('click', () => setOpen(!isOpen()));
	document.addEventListener('click', (e) => {
		if (isOpen() && !split.contains(e.target)) setOpen(false);
	});
	split.addEventListener('keydown', (e) => {
		if (!isOpen()) return;
		const items = [...menu.querySelectorAll('.export-item:not([hidden])')];
		const idx = items.indexOf(document.activeElement);
		if (e.key === 'Escape') {
			setOpen(false);
			caret.focus();
		} else if (e.key === 'ArrowDown') {
			e.preventDefault();
			items[(idx + 1) % items.length]?.focus();
		} else if (e.key === 'ArrowUp') {
			e.preventDefault();
			items[(idx - 1 + items.length) % items.length]?.focus();
		}
	});

	// ---- conversion ----------------------------------------------------------

	let three = null; // { THREE, GLTFLoader, exporters... } cached after first load
	async function loadThree() {
		if (three) return three;
		const [THREE, gltf, draco, obj, stl, ply, usdz] = await Promise.all([
			import('three'),
			import('three/addons/loaders/GLTFLoader.js'),
			import('three/addons/loaders/DRACOLoader.js'),
			import('three/addons/exporters/OBJExporter.js'),
			import('three/addons/exporters/STLExporter.js'),
			import('three/addons/exporters/PLYExporter.js'),
			import('three/addons/exporters/USDZExporter.js'),
		]);
		three = {
			THREE,
			GLTFLoader: gltf.GLTFLoader,
			DRACOLoader: draco.DRACOLoader,
			OBJExporter: obj.OBJExporter,
			STLExporter: stl.STLExporter,
			PLYExporter: ply.PLYExporter,
			USDZExporter: usdz.USDZExporter,
		};
		return three;
	}

	// Parsed-scene cache: one fetch+parse per model URL no matter how many
	// formats the user exports.
	let sceneCache = { url: null, scene: null };
	async function loadScene(url) {
		if (sceneCache.url === url && sceneCache.scene) return sceneCache.scene;
		const t = await loadThree();
		const loader = new t.GLTFLoader();
		const dracoLoader = new t.DRACOLoader();
		dracoLoader.setDecoderPath('/three/draco/gltf/');
		loader.setDRACOLoader(dracoLoader);
		const gltf = await loader.loadAsync(url);
		sceneCache = { url, scene: gltf.scene };
		return gltf.scene;
	}

	function baseName() {
		const attr = download.getAttribute('download') || 'forge.glb';
		return attr.replace(/\.glb$/i, '') || 'forge';
	}

	function saveBlob(data, mime, filename) {
		const blob = data instanceof Blob ? data : new Blob([data], { type: mime });
		const a = document.createElement('a');
		a.href = URL.createObjectURL(blob);
		a.download = filename;
		document.body.appendChild(a);
		a.click();
		a.remove();
		setTimeout(() => URL.revokeObjectURL(a.href), 30_000);
	}

	async function convert(format, scene) {
		const t = await loadThree();
		switch (format.id) {
			case 'obj':
				return new t.OBJExporter().parse(scene);
			case 'stl':
				return new t.STLExporter().parse(scene, { binary: true });
			case 'ply':
				return await new Promise((resolve, reject) => {
					try {
						new t.PLYExporter().parse(scene, resolve, { binary: true });
					} catch (err) {
						reject(err);
					}
				});
			case 'usdz':
				return await new t.USDZExporter().parseAsync(scene);
			default:
				throw new Error(`unknown export format: ${format.id}`);
		}
	}

	// ---- server conversion (FBX, 3MF) ----------------------------------------

	// Poll cadence and ceiling for a worker conversion. A convert job does no
	// geometry work, so it lands in seconds on a warm worker; the ceiling exists
	// for a cold start, which is the slow case worth waiting through rather than
	// failing the user out of.
	const CONVERT_POLL_MS = 2_500;
	const CONVERT_TIMEOUT_MS = 180_000;

	// Aborts an in-flight poll when a new generation replaces the model, so a
	// stale conversion can never write its result over the new one's status.
	let convertEpoch = 0;

	async function convertOnServer(format, sourceUrl, onProgress) {
		const epoch = convertEpoch;
		const res = await fetch('/api/forge-remesh', {
			method: 'POST',
			headers: { 'content-type': 'application/json' },
			body: JSON.stringify({
				mesh_url: sourceUrl,
				operation: 'convert',
				output_format: format.id,
			}),
		});
		const started = await res.json().catch(() => ({}));
		if (!res.ok || !started.job_id) {
			throw new Error(started.message || started.error || `the converter returned ${res.status}`);
		}
		const deadline = Date.now() + CONVERT_TIMEOUT_MS;
		while (Date.now() < deadline) {
			if (epoch !== convertEpoch) return null; // a new model replaced this one
			await new Promise((r) => setTimeout(r, CONVERT_POLL_MS));
			if (epoch !== convertEpoch) return null;
			const pollRes = await fetch(`/api/forge-remesh?job=${encodeURIComponent(started.job_id)}`, {
				headers: { accept: 'application/json' },
			});
			const data = await pollRes.json().catch(() => ({}));
			if (!pollRes.ok) throw new Error(data.message || `the converter returned ${pollRes.status}`);
			if (data.status === 'done' && data.result_url) return data.result_url;
			if (data.status === 'failed') throw new Error(data.error || 'the conversion failed');
			onProgress(data.status === 'running' ? 'converting' : 'queued');
		}
		throw new Error('the conversion timed out');
	}

	const busy = new Set();
	async function onPick(format, item) {
		if (format.id === 'glb') {
			// The source GLB needs no conversion — hand off to the primary anchor.
			setOpen(false);
			download.click();
			return;
		}
		if (busy.has(format.id)) return;
		const url = download.getAttribute('href');
		if (!url) return;
		const status = itemStatus.get(format.id);
		// A server conversion fetches its source over the network, and an
		// in-browser mesh edit only exists as a blob in this tab. Say so rather
		// than silently converting the unedited model.
		if (format.server && url.startsWith('blob:')) {
			status.textContent = 'converts the saved model only: reset your mesh edits, or pick OBJ, STL or PLY';
			status.classList.add('is-error');
			return;
		}
		busy.add(format.id);
		item.setAttribute('aria-disabled', 'true');
		status.classList.remove('is-error');
		const spin = (label) => {
			status.innerHTML = `<span class="export-spinner" aria-hidden="true"></span> ${label}`;
		};
		spin('converting');
		try {
			if (format.readme) {
				// A conversion runs on the server against the saved model URL, so an
				// unsaved in-browser edit (a blob:) cannot be converted.
				const result = await copyReadme3d(url, { name: baseName() });
				status.textContent = describeResult(result);
				setTimeout(() => {
					if (status.textContent.endsWith('KB')) status.textContent = '';
				}, 6000);
				return;
			}
			if (format.server) {
				const resultUrl = await convertOnServer(format, url, spin);
				// Null means a new generation superseded this model mid-conversion;
				// the status was already cleared for the new one, so say nothing.
				if (resultUrl === null) return;
				// The artifact lives in Cloud Storage, a different origin, so the
				// anchor's `download` attribute is ignored and the browser decides
				// from the response instead. It is served as an octet-stream, which
				// downloads rather than navigates. The link stays on screen after
				// the click so a blocked or missed download is still recoverable
				// without re-running the whole conversion.
				triggerDownload(resultUrl);
				status.innerHTML =
					`<a class="export-again" href="${resultUrl}" download="${baseName()}.${format.ext}">saved ✓ (download again)</a>`;
				setTimeout(() => {
					if (status.querySelector('.export-again')) status.textContent = '';
				}, 60_000);
				return;
			}
			const scene = await loadScene(url);
			const data = await convert(format, scene);
			saveBlob(data, format.mime, `${baseName()}.${format.ext}`);
			status.textContent = 'saved ✓';
			setTimeout(() => {
				if (status.textContent === 'saved ✓') status.textContent = '';
			}, 4000);
		} catch (err) {
			log.error(format.id, err);
			// Say what went wrong. "failed" alone sent people re-clicking a button
			// that was never going to work; a converter that is down and a mesh it
			// cannot read need different responses from the user.
			const why = (format.server || format.readme) && err?.message ? `failed: ${err.message}` : 'failed, retry';
			status.textContent = why.length > 90 ? `${why.slice(0, 87)}…` : why;
			status.classList.add('is-error');
		} finally {
			busy.delete(format.id);
			item.removeAttribute('aria-disabled');
		}
	}

	// Same-tab anchor click. Kept separate from saveBlob because there is no blob
	// here: the bytes never enter the page, so nothing needs revoking.
	function triggerDownload(url) {
		const a = document.createElement('a');
		a.href = url;
		a.download = '';
		a.rel = 'noopener';
		document.body.appendChild(a);
		a.click();
		a.remove();
	}

	// A new generation invalidates the parsed-scene cache (the href changes, but
	// clearing eagerly also frees the old scene graph for GC).
	document.addEventListener('forge:model-ready', (e) => {
		sceneCache = { url: null, scene: null };
		slicerItems.setCreation(e.detail?.creationId || creationIdFromGlbUrl(e.detail?.glbUrl));
		craftcloudItem.setCreation(e.detail?.creationId || creationIdFromGlbUrl(e.detail?.glbUrl), e.detail?.glbUrl || null);
		// Retire any conversion still polling for the previous model.
		convertEpoch += 1;
		for (const status of itemStatus.values()) {
			status.textContent = '';
			status.classList.remove('is-error');
		}
	});
}