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.

39.1 KB
Raw Blame
/**
 * Avatar customizer — /avatars/:id/edit
 *
 * Live-preview outfit + accessory editor for an avatar's owner. Picks render
 * client-side via AccessoryManager so feedback is instant; on Save we PATCH
 * /api/avatars/:id with the resulting appearance JSON and the server bakes a
 * canonical GLB (see api/_lib/bake.js).
 *
 * UX model — mirrors Ready Player Me's wardrobe:
 *   • Hover a tile → that item is applied to the 3D stage immediately (preview).
 *   • Mouseleave    → revert to the committed state.
 *   • Click         → commit. Stays applied. Chip appears in the chip bar.
 *   • Chip ×        → quick-remove without hunting through tabs.
 *   • Search box    → filters the active tab's tiles by name.
 *
 * Architecture mirrors avatar-page.js — same look-and-feel, owner-gated by the
 * presence of `avatar.owner_id` in the API response (the avatars endpoint
 * strips owner_id for non-owners via stripOwnerFor).
 */

import { TalkScene } from './voice/talk-scene.js';
import { AccessoryManager } from './agent-accessories.js';
import { uploadAvatarSnapshot } from './voice/avatar-snapshot.js';
import { IdleAnimation } from './idle-animation.js';
import { renderSculptPanel } from './avatar-sculpt.js';
import { applyProportionsToRoot, captureProportionRest, normalizeProportions, proportionsEqual } from './avatar-proportions.js';
import { canonicalBoneNodesFromObject } from './animation-retarget.js';
import { sanitizeSculptDoc, sculptEqual } from './avatar-sculpt-doc.js';
import { applySculptToRoot, clearSculpt } from './avatar-sculpt-brush.js';
import { renderWardrobePanel } from './avatar-wardrobe.js';
import { GarmentCloset, renderClosetSection } from './garment-closet.js';
import { renderRigPanel } from './avatar-rig.js';
import { createWalkPanel } from './avatar-walk-panel.js';
import { apiFetch } from './api.js';
import { playAs } from './game/play-handoff.js';
import { log } from './shared/log.js';

// ── Routing ────────────────────────────────────────────────────────────

const segments = location.pathname.split('/').filter(Boolean);
// `/avatars/:id/edit` in prod, `?id=:id` in dev.
const fromPath =
	segments[0] === 'avatars' && segments[2] === 'edit' ? segments[1] : null;
const editParams = new URLSearchParams(location.search);
const fromQuery = editParams.get('id');
const avatarId = fromPath || fromQuery || '';

// When arriving from the gallery "Equip" button, pre-apply the selected
// accessory GLB once the scene is ready. Supports hat, glasses, earrings kinds
// via ?equip-kind=hat|glasses|earrings (defaults to hat).
const equipGlb = editParams.get('equip-glb') || '';
const equipName = editParams.get('equip-name') || 'Gallery accessory';
const equipBone = editParams.get('equip-bone') || 'Head';
const equipKind = ['glasses', 'earrings'].includes(editParams.get('equip-kind') || '')
	? editParams.get('equip-kind')
	: 'hat';

// The standalone /avatar-edit landing is retired (creation-consolidation C4):
// the customizer is an in-flow step of an avatar, not a destination. The bare
// path 301s to /avatars in vercel.json; the legacy ?id= form still renders here
// so old links and bookmarks keep working, and gets rewritten to the canonical
// /avatars/:id/edit URL in place — replaceState, not a navigation, so nothing
// reloads and the equip handoff params survive.
if (fromQuery && !fromPath && typeof history.replaceState === 'function') {
	const rest = new URLSearchParams(editParams);
	rest.delete('id');
	const qs = rest.toString();
	history.replaceState(
		{},
		'',
		`/avatars/${encodeURIComponent(fromQuery)}/edit${qs ? `?${qs}` : ''}`,
	);
}

const $ = (id) => document.getElementById(id);
const esc = (s) =>
	String(s ?? '').replace(
		/[&<>"']/g,
		(c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[c],
	);

// ── State ──────────────────────────────────────────────────────────────

let avatar = null;
let presets = []; // from /accessories/presets.json
let presetsById = new Map();
let scene = null;
let accessoryManager = null;
// Canonical bone → live node for the mounted rig, resolved once at boot so the
// proportion sliders never re-walk the skeleton mid-drag.
let boneNodes = new Map();
let idle = null;
let idleDispose = null;
let walkPreview = null;

// Appearance state — `current` reflects what the server has, `working` is what
// the UI has committed (locally) and will save. We're dirty when they differ.
// `previewedId` is what's *temporarily* applied on hover, never persisted.
let currentAppearance = null;
let workingAppearance = { outfit: null, accessories: [], morphs: {}, colors: {}, hidden: [], garments: [] };
// Additive-wardrobe controller (catalog garments skinned onto this avatar's
// skeleton at runtime). Created once the scene root exists.
let closet = null;
let previewedId = null;

// Monotonic token guards async preset loads from out-of-order arrivals when
// the user hover-skims many tiles. Only the latest hover applies its result.
let previewToken = 0;

// Serializes every accessoryManager mutation so two GLB loads can't race for
// the same single-slot kind (the manager's slot-clear is synchronous at call
// entry; without serialization, two in-flight loads can both attach). Commits
// run unconditionally; hovers/leaves token-skip if they were superseded by the
// time they reach the head of the chain.
let opQueue = Promise.resolve();
function queueOp(fn) {
	const next = opQueue.then(fn).catch((err) => {
		log.warn('[avatar-edit] queued op failed:', err);
	});
	opQueue = next;
	return next;
}

let searchQuery = '';

// Tab definitions: which preset kind goes on which tab.
const TABS = [
	{ id: 'wardrobe', label: 'Wardrobe', kinds: [], wardrobe: true },
	{ id: 'hat', label: 'Hats', kinds: ['hat'], emoji: '🎩', single: true },
	{ id: 'glasses', label: 'Glasses', kinds: ['glasses'], emoji: '🕶️', single: true },
	{ id: 'earrings', label: 'Earrings', kinds: ['earrings'], emoji: '💎', single: false },
	{ id: 'sculpt', label: 'Sculpt', kinds: [], emoji: '✨', single: true, sculpt: true },
	{ id: 'rig', label: 'Animate', kinds: [], emoji: '🦴', rig: true },
	{ id: 'walk', label: 'Walk', kinds: [], emoji: '🚶', walk: true },
];
const KIND_EMOJI = {
	outfit: '👕',
	hat: '🎩',
	glasses: '🕶️',
	earrings: '💎',
};
const KIND_LABEL = {
	outfit: 'Outfit',
	hat: 'Hat',
	glasses: 'Glasses',
	earrings: 'Earrings',
};
let activeTab = 'wardrobe';

// ── Init ───────────────────────────────────────────────────────────────

if (!avatarId) {
	$('ae-shell').innerHTML = `<div class="ae-error">No avatar specified.</div>`;
} else {
	init().catch((err) => {
		log.error('[avatar-edit] init', err);
		$('ae-shell').innerHTML = `<div class="ae-error">${esc(err.message || 'Failed to load')}</div>`;
	});
}

async function init() {
	avatar = await fetchAvatar(avatarId);
	if (!avatar.owner_id) {
		// owner_id is stripped from the API response for non-owners.
		$('ae-shell').innerHTML = `<div class="ae-error">You don't own this avatar.</div>`;
		return;
	}
	if (!avatar.model_url) {
		$('ae-shell').innerHTML = `<div class="ae-error">This avatar has no GLB to customize.</div>`;
		return;
	}

	$('ae-title').textContent = `Customize · ${avatar.name}`;
	$('ae-back').href = `/avatars/${encodeURIComponent(avatar.id)}`;
	// Owner is editing → surface the agent-wallet panel (create / manage) inline.
	const actions = $('ae-actions');
	if (actions) {
		if (customElements.get('avatar-actions')) actions.avatar = avatar;
		else actions.setAttribute('avatar-id', avatar.id);
	}
	// This avatar already has a baked GLB, so it's playable right now — light up
	// the handoff into /play.
	$('ae-play').disabled = false;

	currentAppearance = normalizeAppearance(avatar.appearance);
	workingAppearance = clone(currentAppearance);

	// Boot the 3D stage in parallel with the presets fetch. The wardrobe panel
	// renders as soon as presets arrive so the user can browse while the GLB
	// streams in. Hover/click interactions gate on accessoryManager being
	// ready — until then they set a "loading" status.
	const scenePromise = bootScene();

	presets = await fetchPresets();
	presetsById = new Map(presets.map((p) => [p.id, p]));

	renderTabs();
	renderChips();
	renderActivePanel();
	bindHeader();

	await scenePromise;

	// Gallery equip: pre-apply the accessory GLB from the query param and dirty
	// the state so the Save button activates. A toast tells the user what happened.
	if (equipGlb && accessoryManager) {
		const syntheticPreset = {
			id: `gallery:${btoa(equipGlb).replace(/[^a-z0-9]/gi, '').slice(0, 32)}`,
			kind: equipKind,
			name: equipName,
			glbUrl: equipGlb,
			attachBone: equipBone,
		};
		await queueOp(() => accessoryManager.applyPreset(syntheticPreset));
		if (!workingAppearance.accessories.includes(syntheticPreset.id)) {
			workingAppearance = {
				...workingAppearance,
				accessories: [...workingAppearance.accessories, syntheticPreset.id],
			};
		}
		updateDirtyState();
		renderActivePanel();
		showEquipToast(equipName);
	}
}

function showEquipToast(name) {
	const toast = document.createElement('div');
	toast.className = 'ae-equip-toast';
	toast.textContent = `"${name}" added — save to keep it on your avatar.`;
	document.body.appendChild(toast);
	requestAnimationFrame(() => toast.classList.add('is-visible'));
	setTimeout(() => {
		toast.classList.remove('is-visible');
		toast.addEventListener('transitionend', () => toast.remove(), { once: true });
	}, 4500);
}

/**
 * Push the working skeleton-space build onto the live rig and re-measure the
 * clip stack so root motion matches the new hip height (see
 * src/avatar-proportions.js). No-op before the scene mounts.
 */
function applyProportions() {
	if (!scene?.root) return;
	applyProportionsToRoot(scene.root, workingAppearance.proportions, { boneMap: boneNodes });
	scene.getEmoteController()?.remeasureRig?.();
	// The walk preview owns a second AnimationManager on the same rig, so it has
	// its own stale hip scale to fix.
	walkPreview?.remeasureProportions();
}

/**
 * Replay `workingAppearance.sculpt` onto the live mesh.
 *
 * Called wherever the whole appearance is restored (boot, draft restore, undo,
 * revert) rather than folded into applyProportions(), which fires on every
 * slider frame: rewriting a 15k-vertex delta array 60 times a second would be
 * wasted work, and it would stamp on a free-sculpt stroke that is mid-drag.
 */
function applySculpt() {
	if (!scene?.root) return;
	if (workingAppearance.sculpt) applySculptToRoot(scene.root, workingAppearance.sculpt);
	else clearSculpt(scene.root);
}

async function bootScene() {
	// IMPORTANT: load the BASE GLB, not the baked one. The customizer applies
	// appearance on the client; loading the already-baked URL would stack
	// outfits.
	scene = new TalkScene();
	try {
		await scene.mount({
			container: $('ae-stage'),
			glbUrl: avatar.base_model_url || avatar.model_url,
		});
		$('ae-loading')?.remove();

		// Capture the bind-pose skeleton before anything animates it, every
		// proportion edit is applied from this rest state, so a capture taken
		// mid-clip would bake that frame in as "rest" and the body would drift.
		boneNodes = canonicalBoneNodesFromObject(scene.root);
		captureProportionRest(scene.root, { boneMap: boneNodes });
		applyProportions();
		applySculpt();

		accessoryManager = new AccessoryManager({
			content: scene.root,
			invalidate: () => {},
		});
		await accessoryManager.hydrateFromAppearance(currentAppearance);

		// Additive wardrobe: re-attach saved catalog garments onto the live
		// skeleton. Unknown/retired garments degrade to "not worn" inside
		// hydrate rather than failing the whole boot.
		const baseUrl = avatar.base_model_url || avatar.model_url || '';
		closet = new GarmentCloset({
			getRoot: () => scene?.root || null,
			getWorking: () => workingAppearance,
			// The parametric base ships a baked UV region mask, giving worn
			// garments pixel-exact skin occlusion. Other bodies use bone-cull.
			regionMaskUrl: baseUrl.includes('parametric-base')
				? '/avatars/parametric-base.regions.png'
				: null,
			onDirty: () => updateDirtyState(),
			onChanged: () => renderChips(),
		});
		// Racks render as soon as the closet exists — the catalog browse must not
		// wait behind re-downloading a saved outfit (hydrate below marks tiles
		// worn as each piece lands, via onChanged re-renders).
		renderActivePanel();
		await closet.hydrate(currentAppearance.garments);

		// Ambient idle layer — breathing, micro-saccades, blink, weight shift.
		// Static preview here (no AgentProtocol); IdleAnimation's no-op stub
		// covers the SPEAK / LOOK_AT subscriptions. Seeded by avatar id so two
		// previews on the same page don't sync up.
		idle = new IdleAnimation({
			getRoot: () => scene.root,
			seed: avatar.id || 'avatar-edit',
		});
		idleDispose = scene.addOnTick((dt) => idle.update(dt));
	} catch (err) {
		const loadingEl = $('ae-loading');
		if (loadingEl) loadingEl.textContent = `Could not load GLB: ${err.message}`;
		// The tabs still rendered — user can browse the catalog, just no live
		// 3D preview. Save is still gated on dirty state below.
	}
}

// ── API ────────────────────────────────────────────────────────────────

async function fetchAvatar(id) {
	const r = await fetch(`/api/avatars/${encodeURIComponent(id)}`, { credentials: 'include' });
	if (!r.ok) {
		const j = await r.json().catch(() => ({}));
		throw new Error(j.error_description || `Avatar not found (${r.status})`);
	}
	return (await r.json()).avatar;
}

async function fetchPresets() {
	const r = await fetch('/accessories/presets.json');
	if (!r.ok) throw new Error(`Could not load presets (${r.status})`);
	return r.json();
}

async function saveAppearance() {
	setStatus('spin', 'Saving and baking…');
	// apiFetch, not raw fetch: mutations need the single-use CSRF token it
	// auto-carries; a raw PATCH 403s against api/_lib/csrf.js enforcement.
	const r = await apiFetch(`/api/avatars/${encodeURIComponent(avatar.id)}`, {
		method: 'PATCH',
		credentials: 'include',
		headers: { 'content-type': 'application/json' },
		body: JSON.stringify({ appearance: collapseAppearance(workingAppearance) }),
	});
	if (!r.ok) {
		const j = await r.json().catch(() => ({}));
		throw new Error(j.error_description || `Save failed (${r.status})`);
	}
	const updated = (await r.json()).avatar;
	avatar = updated;
	currentAppearance = normalizeAppearance(updated.appearance);
	workingAppearance = clone(currentAppearance);
	if (updated.bake_error) {
		setStatus('err', `Saved, but bake failed: ${updated.bake_error}`);
	} else if (updated.baked) {
		setStatus('ok', 'Saved · baked GLB ready');
	} else {
		setStatus('ok', 'Saved');
	}
	updateDirtyState();

	// Best-effort: snapshot the current frame and upload as the avatar's
	// thumbnail. Auto-tagging runs server-side as part of the call. We don't
	// await this on the critical Save path — if it fails the user already sees
	// "Saved" and the existing OG fallback still serves a card.
	queueMicrotask(async () => {
		try {
			await uploadAvatarSnapshot({ avatarId: avatar.id, scene });
		} catch (err) {
			log.warn('[avatar-edit] snapshot upload failed:', err?.message);
		}
	});
}

// ── Rendering ──────────────────────────────────────────────────────────

function renderTabs() {
	const el = $('ae-tabs');
	el.innerHTML = TABS.map(
		(t) => `
			<button class="ae-tab${t.id === activeTab ? ' active' : ''}" data-tab="${t.id}" role="tab">
				${t.label}
			</button>
		`,
	).join('');
	el.querySelectorAll('.ae-tab').forEach((btn) => {
		btn.addEventListener('click', () => {
			activeTab = btn.dataset.tab;
			searchQuery = '';
			el.querySelectorAll('.ae-tab').forEach((b) => b.classList.toggle('active', b === btn));
			renderActivePanel();
		});
	});
}

/**
 * The stage handed to the sculpt panel's free-sculpt brush. Returning null
 * (no scene yet) simply means the Free Sculpt group is not rendered, which is
 * the correct outcome: a brush with no canvas is a dead control.
 *
 * `setPaused` freezes clip playback AND the procedural idle. The brush caches
 * the skinned world positions of every vertex at pointer-down, so a breathing
 * chest under a live drag would make every stroke after the first land a few
 * millimetres off the pixel the user aimed at.
 */
let idleChannelsBeforeSculpt = null;

function sculptViewport() {
	if (!scene?.camera || !scene?.renderer?.domElement) return null;
	return {
		camera: scene.camera,
		domElement: scene.renderer.domElement,
		controls: scene.controls || null,
		setPaused: (paused) => {
			scene.setRigPaused?.(paused);
			if (!idle) return;
			if (paused) {
				idleChannelsBeforeSculpt = idleChannelsBeforeSculpt || idle.getChannels?.() || null;
				idle.setChannels({ breathing: false, saccade: false, blink: false, weightShift: false });
			} else if (idleChannelsBeforeSculpt) {
				idle.setChannels(idleChannelsBeforeSculpt);
				idleChannelsBeforeSculpt = null;
			}
		},
	};
}

function renderActivePanel() {
	const tab = TABS.find((t) => t.id === activeTab);
	const panel = $('ae-panel');

	// Leaving the Walk tab tears down locomotion and restores the static stage.
	// Idempotent, so it's safe to call on every render regardless of source tab.
	if (activeTab !== 'walk') exitWalkMode();

	if (tab.walk) {
		renderWalkPanel(panel);
		return;
	}

	// Wardrobe tab: recolour + show/hide the avatar's own garment layers. Shares
	// the studio's layer engine (src/avatar-wardrobe.js); changes apply live via
	// the AccessoryManager and persist in appearance.colors / appearance.hidden.
	if (tab.wardrobe) {
		renderWardrobePanel({
			container: panel,
			root: scene?.root || null,
			working: workingAppearance,
			applyLayers: (layers) => accessoryManager?.applyLayers(layers),
			onDirty: () => {
				renderChips();
				updateDirtyState();
			},
		});
		// The closet (additive catalog garments) renders beneath the layer
		// cards. It exists even for models with no built-in layers — being able
		// to ADD a garment is exactly what a layerless avatar needs.
		const closetMount = document.createElement('div');
		closetMount.id = 'ae-closet';
		panel.appendChild(closetMount);
		if (closet) {
			renderClosetSection({ container: closetMount, closet });
		} else {
			closetMount.innerHTML = '<div class="gc-loading">Closet opens when the avatar finishes loading…</div>';
		}
		return;
	}

	// Sculpt tab gets its own UI — morph sliders, not a tile grid. The face-
	// capture modal lives inside that module, so the avatar-edit shell doesn't
	// need to know anything about MediaPipe loading or webcam plumbing.


	if (tab.sculpt) {
		if (!scene?.root) {
			panel.innerHTML = `<div class="ae-empty">Waiting for avatar to load…</div>`;
			return;
		}
		renderSculptPanel({
			container: panel,
			root: scene.root,
			working: workingAppearance,
			viewport: sculptViewport(),
			onDirty: () => {
				renderChips();
				updateDirtyState();
			},
			// A proportion edit moves the hips, which invalidates the hip-track
			// rescale every loaded clip was retargeted with. Re-measure or the
			// walk preview foot-slides on the new legs.
			onRigChanged: () => {
				scene?.getEmoteController()?.remeasureRig?.();
				walkPreview?.remeasureProportions();
			},
		});
		return;
	}

	// Animate tab: rig status + one-click auto-rig. Turns a static mesh into an
	// animation-ready avatar via the regenerate(mode:'rerig') backend. Rigging is
	// non-destructive — it mints a new sibling avatar — so on success we hand the
	// owner straight into that new avatar's editor.
	if (tab.rig) {
		renderRigPanel({
			container: panel,
			avatar,
			onRigged: (newAvatar) => {
				if (!newAvatar?.id) return;
				location.href = `/avatars/${encodeURIComponent(newAvatar.id)}/edit`;
			},
		});
		return;
	}

	const q = searchQuery.trim().toLowerCase();
	const items = presets.filter(
		(p) => tab.kinds.includes(p.kind) && (!q || p.name.toLowerCase().includes(q)),
	);

	const searchHtml = `
		<div class="ae-search-wrap">
			<input class="ae-search" id="ae-search" type="search"
			       placeholder="Search ${esc(tab.label.toLowerCase())}…"
			       value="${esc(searchQuery)}" autocomplete="off" />
		</div>`;

	if (items.length === 0 && q) {
		panel.innerHTML = searchHtml + `<div class="ae-empty">No matches for “${esc(searchQuery)}”.</div>`;
		bindSearch();
		return;
	}

	// Render a "None" tile first (only when no search is active) so users can
	// clear the current pick without scrolling. Hidden during search to avoid
	// the confusing "None" matching every empty query.
	const tiles = [];
	if (!q) {
		tiles.push(`
			<button class="ae-tile ae-tile-none${tileSelected(tab, null) ? ' selected' : ''}"
			        type="button" data-id="" data-kind="${tab.id}">
				<div class="ae-tile-preview" aria-hidden="true">∅</div>
				<div class="ae-tile-name">None</div>
				<div class="ae-tile-kind">remove</div>
			</button>
		`);
	}
	for (const p of items) {
		const previewing = previewedId === p.id;
		const selected = tileSelected(tab, p.id);
		tiles.push(`
			<button class="ae-tile${selected ? ' selected' : ''}${previewing ? ' previewing' : ''}"
			        type="button" data-id="${esc(p.id)}" data-kind="${tab.id}">
				<div class="ae-tile-preview" aria-hidden="true">
					${tilePreviewMarkup(p)}
				</div>
				<div class="ae-tile-name">${esc(p.name)}</div>
				<div class="ae-tile-kind">${esc(KIND_LABEL[p.kind] || p.kind)}</div>
			</button>
		`);
	}

	panel.innerHTML = searchHtml + `<div class="ae-grid">${tiles.join('')}</div>`;
	bindSearch();
	bindTiles(panel, tab);
}

// ── Walk preview ─────────────────────────────────────────────────────────

// The panel itself lives in src/avatar-walk-panel.js so Avatar Studio mounts
// the identical control. This editor supplies the scene, the ambient-idle
// pause/resume hooks, and the draft handoff into /walk.
function getWalkPreview() {
	if (walkPreview) return walkPreview;
	if (!scene?.root) return null;
	walkPreview = createWalkPanel({
		getScene: () => scene,
		getStageEl: () => $('ae-stage'),
		// The editor's ambient idle layer writes bone rotations every frame; pause
		// it while a retargeted walk clip owns the skeleton, resume on exit.
		pauseAmbient: () => {
			if (idleDispose) {
				idleDispose();
				idleDispose = null;
			}
		},
		resumeAmbient: () => {
			if (idle && scene && !idleDispose) {
				idleDispose = scene.addOnTick((dt) => idle.update(dt));
			}
		},
		openWalkUrl: buildWalkDraftUrl,
	});
	return walkPreview;
}

function renderWalkPanel(panel) {
	const preview = getWalkPreview();
	if (!preview) {
		panel.innerHTML = `<div class="ae-empty">Waiting for avatar to load...</div>`;
		return;
	}
	preview.render(panel);
}

function exitWalkMode() {
	walkPreview?.exit();
}

// Mint an unguessable draft id and stash the *current* (unsaved) look so the
// walk page renders exactly what's on the editor stage, not the last save.
async function buildWalkDraftUrl(env) {
	const draftId = (crypto.randomUUID?.() || `${Date.now()}-${Math.random()}`)
		.replace(/[^a-z0-9]/gi, '')
		.slice(0, 40);
	const r = await apiFetch(`/api/avatars/draft/${encodeURIComponent(draftId)}`, {
		method: 'PUT',
		headers: { 'content-type': 'application/json' },
		body: JSON.stringify({
			avatar_id: avatar.id,
			appearance: collapseAppearance(workingAppearance),
		}),
	});
	if (!r.ok) {
		const j = await r.json().catch(() => ({}));
		throw new Error(j.error_description || `Could not save draft (${r.status})`);
	}
	return `/walk?avatar=${encodeURIComponent(draftId)}&preview=true&env=${encodeURIComponent(env)}`;
}

function tilePreviewMarkup(preset) {
	const emoji = KIND_EMOJI[preset.kind] || '◇';
	if (!preset.thumbnail) return emoji;
	// Render the emoji underneath as a graceful fallback. The <img> sits on
	// top when it loads; if the file 404s, onerror strips the <img> and the
	// emoji is what the user sees. Avoids broken-image icons while the
	// thumbnail pipeline catches up to the presets.json declarations.
	return `
		<span style="position:absolute;inset:0;display:flex;align-items:center;justify-content:center;">${emoji}</span>
		<img src="${esc(preset.thumbnail)}" alt="" loading="lazy"
		     style="position:absolute;inset:0;"
		     data-fallback="remove" />
	`;
}

function bindSearch() {
	const input = $('ae-search');
	if (!input) return;
	input.addEventListener('input', (e) => {
		searchQuery = e.target.value;
		renderActivePanel();
		// Re-focus to keep typing fluid after the re-render.
		const next = $('ae-search');
		if (next) {
			next.focus();
			next.setSelectionRange(searchQuery.length, searchQuery.length);
		}
	});
}

function bindTiles(panel, tab) {
	panel.querySelectorAll('.ae-tile').forEach((btn) => {
		const presetId = btn.dataset.id;
		btn.addEventListener('click', () => onTileClick(tab, presetId));
		// Hover-to-try-on lives only on real items (not the "None" tile —
		// removing on hover and re-applying on leave would just churn for no
		// information value).
		if (!presetId) return;
		btn.addEventListener('mouseenter', () => onTileHover(tab, presetId));
		btn.addEventListener('mouseleave', () => onTileLeave());
		// Touch / keyboard analogs: focus previews, blur reverts.
		btn.addEventListener('focus', () => onTileHover(tab, presetId));
		btn.addEventListener('blur', () => onTileLeave());
	});
}

function renderChips() {
	const el = $('ae-chips');
	const picks = [];
	if (workingAppearance.outfit) picks.push(workingAppearance.outfit);
	for (const id of workingAppearance.accessories) picks.push(id);

	el.innerHTML = picks
		.map((id) => {
			const p = presetsById.get(id);
			if (!p) return '';
			return `
				<span class="ae-chip" data-id="${esc(id)}">
					<span class="ae-chip-kind">${esc(KIND_LABEL[p.kind] || p.kind)}</span>
					<span>${esc(p.name)}</span>
					<button type="button" aria-label="Remove ${esc(p.name)}" data-remove="${esc(id)}">×</button>
				</span>
			`;
		})
		.join('');

	el.querySelectorAll('button[data-remove]').forEach((btn) => {
		btn.addEventListener('click', async () => {
			await removeCommitted(btn.dataset.remove);
		});
	});
}

function tileSelected(tab, presetId) {
	if (tab.kinds.includes('outfit')) {
		return presetId
			? workingAppearance.outfit === presetId
			: !workingAppearance.outfit;
	}
	// Accessory kinds (hat/glasses/earrings) live in the accessories array.
	const matching = workingAppearance.accessories.filter((id) => {
		const preset = presetsById.get(id);
		return preset && tab.kinds.includes(preset.kind);
	});
	if (!presetId) return matching.length === 0;
	return matching.includes(presetId);
}

// ── Hover preview ──────────────────────────────────────────────────────

function onTileHover(tab, presetId) {
	// Already committed in this slot — hovering is a no-op (it's literally what
	// the stage is showing already).
	if (isCommitted(presetId)) {
		previewedId = null;
		return;
	}
	if (previewedId === presetId) return;

	previewedId = presetId;
	highlightPreviewingTile(presetId);

	const myToken = ++previewToken;
	const preset = presetsById.get(presetId);
	if (!preset) return;

	// Before the GLB streams in, we can't render a live preview. Show a hint
	// in the status bar so the hover isn't silently inert.
	if (!accessoryManager) {
		setStatus('', `${preset.name} · waiting for avatar to load…`);
		return;
	}

	queueOp(async () => {
		// If another hover/leave/click bumped the token before our turn, skip.
		if (myToken !== previewToken) return;
		// For single-slot kinds the manager boots whatever's currently in that
		// slot — exactly the preview behavior we want. Earrings layer on top.
		await accessoryManager.applyPreset(preset);
		if (myToken === previewToken) {
			setStatus('', `Previewing ${preset.name} · click to keep`);
		}
	});
}

function onTileLeave() {
	if (!previewedId) return;
	const leavingId = previewedId;
	previewedId = null;
	const myToken = ++previewToken;
	highlightPreviewingTile(null);

	if (isCommitted(leavingId)) {
		setStatusForDirtyState();
		return;
	}

	const preset = presetsById.get(leavingId);
	if (!preset) {
		setStatusForDirtyState();
		return;
	}

	queueOp(async () => {
		if (myToken !== previewToken) return;
		if (!accessoryManager) {
			setStatusForDirtyState();
			return;
		}
		// Take the preview off.
		accessoryManager.removePreset(leavingId);
		// If we displaced a committed single-slot item to show the preview, put
		// it back. (Earrings are layered, not displaced, so nothing to restore.)
		if (preset.kind !== 'earrings') {
			const committedInSlot = committedIdForKind(preset.kind);
			if (committedInSlot && committedInSlot !== leavingId) {
				const restore = presetsById.get(committedInSlot);
				if (restore) await accessoryManager.applyPreset(restore);
			}
		}
		if (myToken === previewToken) setStatusForDirtyState();
	});
}

function highlightPreviewingTile(id) {
	document.querySelectorAll('.ae-tile.previewing').forEach((el) => el.classList.remove('previewing'));
	if (!id) return;
	const el = document.querySelector(`.ae-tile[data-id="${cssEscape(id)}"]`);
	el?.classList.add('previewing');
}

function cssEscape(s) {
	return String(s).replace(/["\\]/g, '\\$&');
}

function isCommitted(presetId) {
	if (!presetId) return false;
	return (
		workingAppearance.outfit === presetId ||
		workingAppearance.accessories.includes(presetId)
	);
}

function committedIdForKind(kind) {
	if (kind === 'outfit') return workingAppearance.outfit || null;
	for (const id of workingAppearance.accessories) {
		const p = presetsById.get(id);
		if (p && p.kind === kind) return id;
	}
	return null;
}

// ── Commit / remove ────────────────────────────────────────────────────

async function onTileClick(tab, presetId) {
	// A click commits the current hover state. The item may already be on the
	// stage from a hover, or we may be clicking without hovering (touch /
	// keyboard). Either way, route through the queue and run unconditionally:
	// commits should never be token-skipped.
	previewedId = null;
	previewToken++;

	await queueOp(async () => {
		if (tab.kinds.includes('outfit')) {
			await applyOutfit(presetId || null);
		} else {
			await applyAccessory(tab, presetId || null);
		}
	});
	renderActivePanel();
	renderChips();
	updateDirtyState();
}

async function removeCommitted(id) {
	const preset = presetsById.get(id);
	if (!preset) return;
	previewedId = null;
	previewToken++;
	await queueOp(async () => {
		accessoryManager?.removePreset(id);
	});
	if (workingAppearance.outfit === id) {
		workingAppearance.outfit = null;
	} else {
		workingAppearance.accessories = workingAppearance.accessories.filter((a) => a !== id);
	}
	renderActivePanel();
	renderChips();
	updateDirtyState();
}

async function applyOutfit(presetId) {
	// Manager's single-slot logic handles removal of the previous outfit when
	// applyPreset() is called for a new one. Only do an explicit remove when
	// the new pick is null (the "None" tile).
	if (!presetId) {
		if (workingAppearance.outfit) accessoryManager?.removePreset(workingAppearance.outfit);
		workingAppearance.outfit = null;
		return;
	}
	const preset = presetsById.get(presetId);
	if (!preset) return;
	if (accessoryManager) await accessoryManager.applyPreset(preset);
	workingAppearance.outfit = presetId;
}

async function applyAccessory(tab, presetId) {
	// Earrings (and any future non-single kinds) allow multiples — toggle on
	// repeat-click. Single-slot kinds (hat, glasses) just replace.
	const inSlot = workingAppearance.accessories.filter((id) => {
		const p = presetsById.get(id);
		return p && tab.kinds.includes(p.kind);
	});

	if (!presetId) {
		for (const id of inSlot) {
			accessoryManager?.removePreset(id);
			workingAppearance.accessories = workingAppearance.accessories.filter((a) => a !== id);
		}
		return;
	}

	if (tab.single) {
		for (const id of inSlot) {
			if (id === presetId) continue; // about to re-apply same id — manager dedupes
			accessoryManager?.removePreset(id);
			workingAppearance.accessories = workingAppearance.accessories.filter((a) => a !== id);
		}
		const preset = presetsById.get(presetId);
		if (preset && accessoryManager) await accessoryManager.applyPreset(preset);
		if (!workingAppearance.accessories.includes(presetId)) {
			workingAppearance.accessories.push(presetId);
		}
		return;
	}

	// Non-single (earrings): clicking an already-applied preset removes it.
	if (inSlot.includes(presetId)) {
		accessoryManager?.removePreset(presetId);
		workingAppearance.accessories = workingAppearance.accessories.filter((a) => a !== presetId);
		return;
	}
	const preset = presetsById.get(presetId);
	if (preset && accessoryManager) await accessoryManager.applyPreset(preset);
	if (!workingAppearance.accessories.includes(presetId)) {
		workingAppearance.accessories.push(presetId);
	}
}

// ── Header / status ────────────────────────────────────────────────────

function bindHeader() {
	// Jump into /play as this avatar. If there are unsaved appearance edits, bake
	// them first so the world shows the look the user actually sees here, then hand
	// off the canonical avatar id (peers resolve it to the freshly-baked GLB).
	$('ae-play').addEventListener('click', async () => {
		$('ae-play').disabled = true;
		try {
			if (!$('ae-save').disabled) {
				setStatus('spin', 'Saving your look before you play…');
				await saveAppearance();
				renderChips();
				renderActivePanel();
				updateDirtyState();
			}
			setStatus('spin', 'Entering /play…');
			await playAs({ id: avatar.id, name: avatar.name, dest: '/play' });
		} catch (err) {
			setStatus('err', err.message);
			$('ae-play').disabled = false;
		}
	});
	$('ae-save').addEventListener('click', async () => {
		$('ae-save').disabled = true;
		$('ae-reset').disabled = true;
		try {
			await saveAppearance();
			renderChips();
			renderActivePanel();
		} catch (err) {
			setStatus('err', err.message);
		} finally {
			updateDirtyState();
		}
	});
	$('ae-reset').addEventListener('click', async () => {
		// Roll the live preview back to the saved appearance.
		previewedId = null;
		previewToken++;
		await queueOp(async () => {
			const wasIds = [
				workingAppearance.outfit,
				...workingAppearance.accessories,
			].filter(Boolean);
			if (accessoryManager) {
				for (const id of wasIds) accessoryManager.removePreset(id);
			}
			workingAppearance = clone(currentAppearance);
			applyProportions();
			applySculpt();
			if (accessoryManager) await accessoryManager.hydrateFromAppearance(workingAppearance);
			if (closet) {
				closet.clear();
				await closet.hydrate(workingAppearance.garments);
			}
		});
		renderChips();
		renderActivePanel();
		updateDirtyState();
		setStatus('', 'Reverted to last saved.');
	});
}

function updateDirtyState() {
	const dirty = !appearanceEquals(workingAppearance, currentAppearance);
	$('ae-save').disabled = !dirty;
	$('ae-reset').disabled = !dirty;
	setStatusForDirtyState();
}

function setStatusForDirtyState() {
	const dirty = !appearanceEquals(workingAppearance, currentAppearance);
	if (!dirty) {
		setStatus('', 'Hover any item to try it on. Click to keep.');
	} else {
		setStatus('', 'Unsaved changes.');
	}
}

function setStatus(kind, text) {
	const el = $('ae-status');
	el.className = `ae-status${kind ? ' ' + kind : ''}`;
	el.innerHTML = kind === 'spin' ? `<span class="spin"></span>${esc(text)}` : esc(text);
}

// ── Helpers ────────────────────────────────────────────────────────────

function normalizeAppearance(a) {
	if (!a) return { outfit: null, accessories: [], morphs: {}, colors: {}, hidden: [], garments: [], proportions: {} };
	return {
		outfit: a.outfit || null,
		accessories: Array.isArray(a.accessories) ? [...a.accessories] : [],
		morphs: a.morphs && typeof a.morphs === 'object' ? { ...a.morphs } : {},
		// Garment-layer state (recolour + show/hide) is owned by the studio but
		// must survive an edit here — hydrate re-applies it and collapse re-sends
		// it, so editing accessories never silently strips a studio look.
		colors: a.colors && typeof a.colors === 'object' ? { ...a.colors } : {},
		hidden: Array.isArray(a.hidden) ? [...a.hidden] : [],
		// Additive catalog garments worn by this avatar ({slot, id} refs).
		garments: Array.isArray(a.garments)
			? a.garments.filter((g) => g && g.slot && g.id).map((g) => ({ slot: g.slot, id: g.id }))
			: [],
		// Skeleton-space build (src/avatar-proportions.js). Normalized on the way
		// in so an out-of-range or hand-edited record can never drive the rig.
		proportions: normalizeProportions(a.proportions),
		sculpt: sanitizeSculptDoc(a.sculpt),
	};
}

// Drop empty fields before PATCHing so we send the smallest valid JSON and so
// "no customization" rows have appearance = null (matches isBakeable() check).
function collapseAppearance(a) {
	const out = {};
	if (a.outfit) out.outfit = a.outfit;
	if (a.accessories?.length) out.accessories = [...a.accessories];
	if (a.morphs && Object.keys(a.morphs).length) out.morphs = { ...a.morphs };
	if (a.colors && Object.keys(a.colors).length) out.colors = { ...a.colors };
	if (a.hidden?.length) out.hidden = [...a.hidden];
	if (a.garments?.length) out.garments = a.garments.map((g) => ({ slot: g.slot, id: g.id }));
	const proportions = normalizeProportions(a.proportions);
	if (Object.keys(proportions).length) out.proportions = proportions;
	const sculpt = sanitizeSculptDoc(a.sculpt);
	if (sculpt) out.sculpt = sculpt;
	return Object.keys(out).length ? out : null;
}

function clone(o) {
	return JSON.parse(JSON.stringify(o));
}

function appearanceEquals(a, b) {
	if ((a?.outfit || null) !== (b?.outfit || null)) return false;
	const sa = new Set(a?.accessories || []);
	const sb = new Set(b?.accessories || []);
	if (sa.size !== sb.size) return false;
	for (const v of sa) if (!sb.has(v)) return false;
	const ka = Object.keys(a?.morphs || {});
	const kb = Object.keys(b?.morphs || {});
	if (ka.length !== kb.length) return false;
	for (const k of ka) if ((a.morphs[k] || 0) !== (b?.morphs?.[k] || 0)) return false;
	const ca = Object.keys(a?.colors || {});
	const cb = Object.keys(b?.colors || {});
	if (ca.length !== cb.length) return false;
	for (const k of ca) if ((a.colors[k] || null) !== (b?.colors?.[k] || null)) return false;
	const ha = new Set(a?.hidden || []);
	const hb = new Set(b?.hidden || []);
	if (ha.size !== hb.size) return false;
	for (const v of ha) if (!hb.has(v)) return false;
	const ga = new Set((a?.garments || []).map((g) => `${g.slot}/${g.id}`));
	const gb = new Set((b?.garments || []).map((g) => `${g.slot}/${g.id}`));
	if (ga.size !== gb.size) return false;
	for (const v of ga) if (!gb.has(v)) return false;
	if (!proportionsEqual(a?.proportions, b?.proportions)) return false;
	if (!sculptEqual(a?.sculpt, b?.sculpt)) return false;
	return true;
}