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.

7.1 KB
Raw Blame
/**
 * `@three-ws/portal`: any website as a walkable 3D world.
 *
 * Three things live here, and they are deliberately separable:
 *
 *   the layout       a pure function from a page's structure to a world
 *                    (./layout.js). No network, no DOM, no three.js. It runs
 *                    identically in a browser, in Node, in a worker, and on
 *                    three.ws itself, which is why a shared link always opens
 *                    the same city the sharer walked.
 *   the client       thin wrappers over the public Portal API, which does the
 *                    fetching, the robots.txt check and the caching for you.
 *   the embed        one call that puts a live, walkable world in your page.
 *
 * Nothing here needs a key, an account, or a wallet.
 *
 * @example
 * import { fetchWorld, mountPortal } from '@three-ws/portal';
 * const { world } = await fetchWorld('example.com');
 * mountPortal(document.querySelector('#stage'), { url: 'example.com' });
 */

export * from './layout.js';

/** The public Portal API. Point this at a self-hosted three.ws to use your own. */
export const PORTAL_API = 'https://three.ws/api/portal';
export const PORTAL_PAGE = 'https://three.ws/portal';

/** Everything the client throws, with the API's own machine-readable code. */
export class PortalError extends Error {
	constructor(code, message, status) {
		super(message);
		this.name = 'PortalError';
		this.code = code;
		this.status = status;
	}
}

function endpointFor(url, { endpoint = PORTAL_API, ...params } = {}) {
	const query = new URLSearchParams({ url: String(url || '') });
	for (const [k, v] of Object.entries(params)) {
		if (v !== undefined && v !== null && k !== 'fetch' && k !== 'signal') query.set(k, String(v));
	}
	return `${endpoint}?${query}`;
}

/**
 * Build (or read from cache) the world for a page.
 * @param {string} url any address: `example.com`, `https://example.com/docs`
 * @param {{ endpoint?: string, include?: 'world'|'outline'|'both', fetch?: typeof fetch, signal?: AbortSignal }} [opts]
 * @returns {Promise<{ world: object, outline?: object, cached: boolean, stale: boolean }>}
 */
export async function fetchWorld(url, opts = {}) {
	const impl = opts.fetch || globalThis.fetch;
	if (!impl) throw new PortalError('no_fetch', 'No fetch implementation available. Pass one as opts.fetch.', 0);
	const res = await impl(endpointFor(url, opts), {
		headers: { accept: 'application/json' },
		signal: opts.signal,
	});
	const body = await res.json().catch(() => null);
	if (!res.ok || !body?.world) {
		throw new PortalError(
			body?.error || `http_${res.status}`,
			body?.error_description || `Portal could not build a world from ${url}.`,
			res.status,
		);
	}
	return { world: body.world, outline: body.outline, cached: !!body.cached, stale: !!body.stale };
}

/**
 * Read a page's structure without building a world: the heading spine, the
 * weight of each section, and where it links. Cheaper over the wire than a
 * world, and the right call when you want to compare pages rather than walk one.
 * @param {string} url
 * @param {{ endpoint?: string, fetch?: typeof fetch, signal?: AbortSignal }} [opts]
 * @returns {Promise<{ outline: object, cached: boolean, stale: boolean }>}
 */
export async function fetchOutline(url, opts = {}) {
	const impl = opts.fetch || globalThis.fetch;
	if (!impl) throw new PortalError('no_fetch', 'No fetch implementation available. Pass one as opts.fetch.', 0);
	const res = await impl(endpointFor(url, { ...opts, include: 'outline' }), {
		headers: { accept: 'application/json' },
		signal: opts.signal,
	});
	const body = await res.json().catch(() => null);
	if (!res.ok || !body?.outline) {
		throw new PortalError(
			body?.error || `http_${res.status}`,
			body?.error_description || `Portal could not read ${url}.`,
			res.status,
		);
	}
	return { outline: body.outline, cached: !!body.cached, stale: !!body.stale };
}

/**
 * The same world as a glTF binary, ready for Blender, Unity, AR, or any viewer.
 * @param {string} url
 * @param {{ endpoint?: string, fetch?: typeof fetch, signal?: AbortSignal }} [opts]
 * @returns {Promise<ArrayBuffer>}
 */
export async function fetchWorldGlb(url, opts = {}) {
	const impl = opts.fetch || globalThis.fetch;
	if (!impl) throw new PortalError('no_fetch', 'No fetch implementation available. Pass one as opts.fetch.', 0);
	const res = await impl(endpointFor(url, { ...opts, format: 'glb' }), { signal: opts.signal });
	if (!res.ok) {
		const body = await res.json().catch(() => null);
		throw new PortalError(body?.error || `http_${res.status}`, body?.error_description || 'Portal could not export that world.', res.status);
	}
	return res.arrayBuffer();
}

/** The iframe snippet that puts a walkable world on a page, as a string. */
export function embedSnippet(url, { height = 520, page = PORTAL_PAGE, title } = {}) {
	const src = `${page}?url=${encodeURIComponent(url)}&embed=1`;
	const label = title || `Walk ${url} in 3D`;
	return `<iframe src="${src}" width="100%" height="${height}" style="border:0;border-radius:14px" loading="lazy" title="${label}"></iframe>`;
}

/**
 * Mount a live, walkable world into an element.
 *
 * It embeds the hosted renderer rather than shipping a second copy of it: the
 * renderer is a WebGL app with an avatar, a clip library and a rig retargeter
 * behind it, and a stale duplicate of that inside an npm package would be worse
 * for everyone than an iframe that is always current.
 *
 * @param {Element} element where to mount
 * @param {{ url: string, height?: number|string, page?: string, title?: string }} opts
 * @returns {HTMLIFrameElement}
 */
export function mountPortal(element, { url, height = 520, page = PORTAL_PAGE, title } = {}) {
	if (!element || typeof element.append !== 'function') {
		throw new PortalError('bad_target', 'mountPortal needs an element to mount into.', 0);
	}
	if (!url) throw new PortalError('bad_url', 'mountPortal needs a url to explore.', 0);
	const doc = element.ownerDocument || globalThis.document;
	const frame = doc.createElement('iframe');
	frame.src = `${page}?url=${encodeURIComponent(url)}&embed=1`;
	frame.width = '100%';
	frame.height = String(height);
	frame.loading = 'lazy';
	frame.title = title || `Walk ${url} in 3D`;
	frame.style.border = '0';
	frame.style.borderRadius = '14px';
	frame.allow = 'fullscreen';
	element.append(frame);
	return frame;
}

/**
 * A compact, human-readable summary of a world: what the page turned into.
 * Used by the CLI and the MCP tool, and useful in any dashboard.
 * @param {object} world
 */
export function describeWorld(world) {
	const districts = world.buildings.map((b) => ({
		name: b.label,
		height: b.h,
		words: b.words,
		doors: world.doors.filter((d) => d.buildingId === b.id).length,
	}));
	return {
		host: world.meta.host,
		title: world.meta.title,
		sections: world.meta.sections,
		words: world.meta.words,
		doors: world.doors.length,
		internalDoors: world.doors.filter((d) => d.internal).length,
		billboards: world.props.filter((p) => p.kind === 'billboard').length,
		monoliths: world.props.filter((p) => p.kind === 'monolith').length,
		radius: world.ground.radius,
		palette: world.palette,
		tallest: districts.slice().sort((a, b) => b.height - a.height)[0] || null,
		districts,
	};
}