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.

73.6 KB
Raw Blame
// /pose — the three.ws Animation Studio. A Three.js scene with a posable rig
// (the built-in primitive mannequin OR a loaded rigged GLB avatar — including
// the user's own three.ws avatars), orbit camera, ground + grid, and a control
// panel for posing (FK gizmos + sliders and drag-IK), presets, lighting, props,
// and PNG export. Task 2 layers a keyframe timeline on top of this foundation.

import {
	ACESFilmicToneMapping,
	AmbientLight,
	Box3,
	BoxGeometry,
	CircleGeometry,
	Color,
	CylinderGeometry,
	DirectionalLight,
	GridHelper,
	Group,
	HemisphereLight,
	Mesh,
	MeshBasicMaterial,
	MeshStandardMaterial,
	VSMShadowMap,
	PerspectiveCamera,
	Plane,
	PMREMGenerator,
	Quaternion,
	Raycaster,
	Scene,
	ShadowMaterial,
	SphereGeometry,
	Vector2,
	Vector3,
	WebGLRenderer,
} from 'three';
import { RoomEnvironment } from 'three/addons/environments/RoomEnvironment.js';
import { OrbitControls } from 'three/examples/jsm/controls/OrbitControls.js';
import { TransformControls } from 'three/examples/jsm/controls/TransformControls.js';
import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
import { GLTFExporter } from 'three/addons/exporters/GLTFExporter.js';

import { getDecoders } from './viewer/internal.js';
import {
	CANONICAL_LABELS,
	MannequinRig,
	makeGltfRig,
	poseFromMannequinPreset,
} from './pose-rig.js';
import { PRESETS, getPresetsByGroup, getPresetById } from './pose-presets.js';
import { decodePoseFromLocation } from './pose-share.js';
import { AvatarGalleryPicker } from './avatar-gallery-picker.js';
import {
	createDocument,
	upsertKeyframe,
	removeKeyframe,
	moveKeyframe,
	setKeyframeEasing,
	clampKeyframesToDuration,
	sampleAtTime,
	bakeClip,
	serializeClip,
	clonePose,
	posesEqual,
	EASINGS,
	DEFAULT_EASING,
} from './pose-animation.js';
import { PoseLibrary } from './pose-library.js';
import { AnimationLibrary } from './animation-library.js';
import { putSceneHandoff } from './shared/scene-handoff.js';
import { isSafeQueryModelUrl } from './shared/safe-model-url.js';
import { log } from './shared/log.js';

// ─── DOM helpers ────────────────────────────────────────────────────────
const $ = (sel) => document.querySelector(sel);
const el = (tag, attrs = {}, children = []) => {
	const node = document.createElement(tag);
	for (const [k, v] of Object.entries(attrs)) {
		if (k === 'class') node.className = v;
		else if (k === 'text') node.textContent = v;
		else if (k.startsWith('on') && typeof v === 'function')
			node.addEventListener(k.slice(2), v);
		else if (v !== false && v != null) node.setAttribute(k, v);
	}
	for (const child of children) {
		if (child == null) continue;
		node.appendChild(typeof child === 'string' ? document.createTextNode(child) : child);
	}
	return node;
};

// ─── Floor props ────────────────────────────────────────────────────────
const FLOOR_PROPS = {
	none: { label: 'None', build: null },
	chair: {
		label: 'Chair',
		build: () => {
			const g = new Group();
			const wood = new MeshStandardMaterial({ color: '#8b6f47', roughness: 0.8 });
			const seat = new Mesh(new BoxGeometry(0.46, 0.05, 0.46), wood);
			seat.position.y = 0.45;
			seat.castShadow = true;
			seat.receiveShadow = true;
			g.add(seat);
			const legGeom = new BoxGeometry(0.05, 0.45, 0.05);
			for (const [x, z] of [
				[+0.19, +0.19],
				[+0.19, -0.19],
				[-0.19, +0.19],
				[-0.19, -0.19],
			]) {
				const leg = new Mesh(legGeom, wood);
				leg.position.set(x, 0.225, z);
				leg.castShadow = true;
				leg.receiveShadow = true;
				g.add(leg);
			}
			const back = new Mesh(new BoxGeometry(0.46, 0.55, 0.04), wood);
			back.position.set(0, 0.75, -0.22);
			back.castShadow = true;
			back.receiveShadow = true;
			g.add(back);
			return g;
		},
	},
	stool: {
		label: 'Stool',
		build: () => {
			const g = new Group();
			const mat = new MeshStandardMaterial({ color: '#3f3f46', roughness: 0.6 });
			const top = new Mesh(new CylinderGeometry(0.22, 0.22, 0.05, 24), mat);
			top.position.y = 0.45;
			top.castShadow = true;
			top.receiveShadow = true;
			g.add(top);
			const post = new Mesh(new CylinderGeometry(0.04, 0.04, 0.42, 14), mat);
			post.position.y = 0.21;
			post.castShadow = true;
			g.add(post);
			const base = new Mesh(new CylinderGeometry(0.18, 0.2, 0.03, 24), mat);
			base.position.y = 0.015;
			base.receiveShadow = true;
			g.add(base);
			return g;
		},
	},
	cube: {
		label: 'Cube',
		build: () => {
			const g = new Group();
			const mat = new MeshStandardMaterial({ color: '#ef4444', roughness: 0.7 });
			const box = new Mesh(new BoxGeometry(0.5, 0.5, 0.5), mat);
			box.position.y = 0.25;
			box.castShadow = true;
			box.receiveShadow = true;
			g.add(box);
			return g;
		},
	},
	ball: {
		label: 'Ball',
		build: () => {
			const g = new Group();
			const mat = new MeshStandardMaterial({ color: '#facc15', roughness: 0.5 });
			const ball = new Mesh(new SphereGeometry(0.18, 24, 16), mat);
			ball.position.y = 0.18;
			ball.castShadow = true;
			ball.receiveShadow = true;
			g.add(ball);
			return g;
		},
	},
	plinth: {
		label: 'Plinth',
		build: () => {
			const g = new Group();
			const mat = new MeshStandardMaterial({ color: '#a8a29e', roughness: 0.85 });
			const box = new Mesh(new BoxGeometry(0.7, 0.8, 0.7), mat);
			box.position.y = 0.4;
			box.castShadow = true;
			box.receiveShadow = true;
			g.add(box);
			return g;
		},
	},
};

// Shared IK target-handle assets (cloned per handle for per-instance opacity).
const handleGeom = new SphereGeometry(0.045, 16, 12);
const handleMat = new MeshBasicMaterial({
	color: '#22d3ee',
	transparent: true,
	opacity: 0.9,
	depthTest: false,
});

// ─── Scene setup ────────────────────────────────────────────────────────
function setupScene(canvas, hudStatus) {
	const scene = new Scene();
	scene.background = new Color('#0b0b10');

	const camera = new PerspectiveCamera(45, 1, 0.05, 100);
	camera.position.set(2.2, 1.65, 3.0);

	const renderer = new WebGLRenderer({
		canvas,
		antialias: true,
		preserveDrawingBuffer: true, // needed for toDataURL screenshots / thumbnails
	});
	renderer.setPixelRatio(Math.min(window.devicePixelRatio || 1, 2));
	renderer.shadowMap.enabled = true;
	// PCFSoftShadowMap is deprecated in three.js and silently downgrades to hard
	// PCFShadowMap at runtime, warning on every boot; VSMShadowMap is the
	// supported soft-shadow type.
	renderer.shadowMap.type = VSMShadowMap;
	// Filmic response + image-based lighting, matching the IRL/avatar-sdk render
	// stack — PBR materials read flat and plasticky under bare analytic lights.
	renderer.toneMapping = ACESFilmicToneMapping;
	renderer.toneMappingExposure = 1.1;

	const pmrem = new PMREMGenerator(renderer);
	scene.environment = pmrem.fromScene(new RoomEnvironment(), 0.04).texture;

	const controls = new OrbitControls(camera, canvas);
	controls.enableDamping = true;
	controls.dampingFactor = 0.08;
	controls.minDistance = 0.6;
	controls.maxDistance = 12;
	controls.maxPolarAngle = Math.PI * 0.96;
	controls.target.set(0, 0.95, 0);

	// Rotation gizmo for the selected bone (FK posing). Newer three exposes the
	// visual via getHelper(); the control instance carries the interaction.
	const gizmo = new TransformControls(camera, canvas);
	gizmo.setMode('rotate');
	gizmo.setSpace('local');
	gizmo.setSize(0.8);
	gizmo.visible = false;
	gizmo.enabled = false;
	scene.add(gizmo.getHelper());
	// Suspend orbit while a gizmo drag is in progress.
	gizmo.addEventListener('dragging-changed', (e) => {
		controls.enabled = !e.value;
	});

	// The RoomEnvironment IBL above now supplies the ambient base, so the fill
	// lights step down from their pre-IBL values (hemi 0.55 / ambient 0.18) to
	// keep overall exposure where it was — the key stays the shadow-caster.
	const hemi = new HemisphereLight('#f1f5f9', '#0a0a0f', 0.4);
	scene.add(hemi);
	const ambient = new AmbientLight('#ffffff', 0.1);
	scene.add(ambient);

	const key = new DirectionalLight('#ffffff', 1.4);
	key.position.set(3, 5, 2.5);
	key.castShadow = true;
	key.shadow.mapSize.set(2048, 2048);
	key.shadow.camera.near = 0.5;
	key.shadow.camera.far = 18;
	key.shadow.camera.left = -3.5;
	key.shadow.camera.right = 3.5;
	key.shadow.camera.top = 4;
	key.shadow.camera.bottom = -1;
	key.shadow.bias = -0.0008;
	scene.add(key);

	const fill = new DirectionalLight('#9bb1ff', 0.35);
	fill.position.set(-2.5, 2, -2);
	scene.add(fill);

	const ground = new Mesh(new CircleGeometry(12, 64), new ShadowMaterial({ opacity: 0.35 }));
	ground.rotation.x = -Math.PI / 2;
	ground.position.y = 0;
	ground.receiveShadow = true;
	scene.add(ground);

	const grid = new GridHelper(8, 32, 0x2a2a35, 0x1a1a22);
	grid.position.y = 0.001;
	scene.add(grid);

	const propLayer = new Group();
	scene.add(propLayer);

	// Layer that holds draggable IK target handles (kept out of the rig so it
	// survives a rig swap and never exports into a GLB).
	const ikLayer = new Group();
	scene.add(ikLayer);

	function resize() {
		const w = canvas.clientWidth;
		const h = canvas.clientHeight;
		renderer.setSize(w, h, false);
		camera.aspect = w / Math.max(1, h);
		camera.updateProjectionMatrix();
	}
	window.addEventListener('resize', resize);
	// The shared nav injects asynchronously and the stage flexes with the page
	// shell, so track the canvas box directly rather than relying on window
	// resize alone — keeps the render crisp at every breakpoint.
	if (typeof ResizeObserver !== 'undefined') {
		new ResizeObserver(resize).observe(canvas);
	}
	resize();

	function setStatus(text, kind = 'info') {
		if (!hudStatus) return;
		hudStatus.textContent = text;
		hudStatus.dataset.kind = kind;
	}

	return {
		scene,
		camera,
		renderer,
		controls,
		gizmo,
		key,
		hemi,
		ambient,
		propLayer,
		ikLayer,
		setStatus,
	};
}

// ─── State ──────────────────────────────────────────────────────────────
const state = {
	rig: null, // current Rig (MannequinRig | GltfRig)
	selectedBone: null, // canonical bone key
	poseMode: 'fk', // 'fk' (gizmo + sliders) | 'ik' (drag end-effectors)
	avatar: null, // { id, name } when a GLB is loaded, else null
	loadingAvatar: false,
	prop: 'none',
	propGroup: null,
	keyLight: null,
	keyAzimuth: 0.9,
	keyElevation: 0.95,
	keyDistance: 5.8,
	ikHandles: new Map(), // effectorKey → Mesh
	draggingIK: null, // { effectorKey, plane }
	anim: null, // timeline controller handle (set on boot)
	animLibrary: null, // AnimationLibrary (preset gallery) handle (set on boot)
};

// Studio handle exposed for later tasks (save/library/monetize) to share the
// rig, scene, and the current animation document without re-importing internals.
export const studio = {
	get rig() {
		return state.rig;
	},
	get scene() {
		return state.ctx?.scene || null;
	},
	get camera() {
		return state.ctx?.camera || null;
	},
	get renderer() {
		return state.ctx?.renderer || null;
	},
	get avatar() {
		return state.avatar;
	},
	// ── Animation handoff API (Task 4/5/6) ───────────────────────────────────
	get document() {
		return state.anim?.doc || null;
	},
	/** Bake the current document to a THREE.AnimationClip (canonical bone names). */
	bake() {
		return state.anim ? state.anim.bake() : null;
	},
	/** The documented clip-JSON ({ name, duration, tracks }). */
	serializeClip() {
		return state.anim ? state.anim.serialize() : null;
	},
	/** PNG data URL of the current viewport (reuses the screenshot pipeline). */
	captureThumbnail() {
		return state.anim ? state.anim.captureThumbnail() : null;
	},
};

// ─── App boot ───────────────────────────────────────────────────────────
function boot() {
	const canvas = $('#pose-canvas');
	const hudStatus = $('#pose-status');
	if (!canvas) {
		log.error('[pose] missing #pose-canvas');
		return;
	}

	const ctx = setupScene(canvas, hudStatus);
	state.ctx = ctx;
	const { scene, camera, renderer, controls, gizmo, key, propLayer, ikLayer, setStatus } = ctx;
	state.keyLight = key;

	// Timeline controller — assigned near the end of boot once its DOM refs
	// exist. Declared here so mountRig() (called during boot, before the
	// assignment) can safely reference it via optional chaining.
	let timeline = null;

	// Panel DOM refs (resolved up-front: mountRig() renders into them on boot).
	const sliderHost = $('#pose-controls-host');
	const selectionLabel = $('#pose-selection-label');
	const boneListHost = $('#pose-joint-picker');
	const boneSearch = $('#pose-bone-search');

	// ── Rig lifecycle ────────────────────────────────────────────────────
	function mountRig(rig) {
		// Tear down the previous rig.
		if (state.rig) {
			gizmo.detach();
			scene.remove(state.rig.root);
			state.rig.dispose?.();
		}
		state.rig = rig;
		scene.add(rig.root);
		state.selectedBone = null;
		clearIKHandles();
		buildIKHandles();
		applyPoseMode();
		renderControlsPanel();
		renderBoneList();
		updateSelectionLabel();
		timeline?.onRigChanged();
		state.animLibrary?.onRigChanged();
	}

	const mannequinRig = new MannequinRig({ build: 'male', color: '#d4d4d8' });
	mountRig(mannequinRig);
	state.avatar = null;

	// A pose handed over from elsewhere (the homepage demo's "Open full studio"
	// link / share URL) wins; otherwise pick a reasonable starting pose so the
	// figure looks alive on load.
	const sharedPose = decodePoseFromLocation();
	if (sharedPose) {
		state.rig.applyPose(sharedPose);
	} else {
		const intro = getPresetById('contrapposto');
		if (intro) state.rig.applyPose(poseFromMannequinPreset(intro.pose));
	}

	// ── Render loop ──────────────────────────────────────────────────────
	let lastFrameMs = performance.now();
	function tick() {
		requestAnimationFrame(tick);
		const now = performance.now();
		const dt = Math.min((now - lastFrameMs) / 1000, 0.1); // cap to avoid tab-switch jumps
		lastFrameMs = now;
		controls.update();
		// A preset preview owns the figure while it runs; the keyframe timeline
		// yields so the two never fight over bone transforms.
		if (state.animLibrary?.isPreviewing()) state.animLibrary.update(dt);
		else timeline?.update(dt);
		if (state.poseMode === 'ik' && !state.draggingIK) syncIKHandles();
		renderer.render(scene, camera);
	}
	tick();

	// ── Camera framing ───────────────────────────────────────────────────
	function frameObject(object) {
		object.updateMatrixWorld(true);
		const box = new Box3().setFromObject(object);
		if (box.isEmpty()) return;
		const size = box.getSize(new Vector3());
		const center = box.getCenter(new Vector3());
		// Drop the rig so its feet rest on the ground plane.
		object.position.y -= box.min.y;
		const height = Math.max(0.5, size.y);
		controls.target.set(0, height * 0.55, 0);
		const dist = height * 2.2;
		camera.position.set(dist * 0.6, height * 0.8, dist);
		controls.minDistance = height * 0.4;
		controls.maxDistance = height * 8;
		controls.update();
	}

	// ── Raycast selection (FK) ─────────────────────────────────────────────
	const raycaster = new Raycaster();
	const ndc = new Vector2();
	const _v = new Vector3();

	function toNDC(clientX, clientY) {
		const rect = canvas.getBoundingClientRect();
		ndc.x = ((clientX - rect.left) / rect.width) * 2 - 1;
		ndc.y = -((clientY - rect.top) / rect.height) * 2 + 1;
		return ndc;
	}

	// Pick a bone from a screen position. Mannequin: raycast tagged meshes. GLB:
	// raycast the skinned mesh to confirm the click is on the figure, then pick
	// the posable bone whose projected position is nearest the cursor.
	function pickBoneAt(clientX, clientY) {
		const rig = state.rig;
		raycaster.setFromCamera(toNDC(clientX, clientY), camera);
		if (rig.kind === 'mannequin') {
			const hits = raycaster.intersectObjects(rig.getSelectableMeshes(), false);
			if (!hits.length) return null;
			return rig.boneFromHit(hits[0].object);
		}
		// GLB: require a hit on the mesh so empty-space clicks deselect.
		const meshes = rig.skinnedMeshes?.length ? rig.skinnedMeshes : rig.getSelectableMeshes();
		const hits = raycaster.intersectObjects(meshes, true);
		if (!hits.length) return null;
		const rect = canvas.getBoundingClientRect();
		const px = clientX - rect.left;
		const py = clientY - rect.top;
		let best = null;
		let bestDist = Infinity;
		for (const { key, node } of rig.getBones()) {
			node.getWorldPosition(_v).project(camera);
			const sx = (_v.x * 0.5 + 0.5) * rect.width;
			const sy = (-_v.y * 0.5 + 0.5) * rect.height;
			const d = Math.hypot(sx - px, sy - py);
			if (d < bestDist) {
				bestDist = d;
				best = key;
			}
		}
		return bestDist < 80 ? best : null;
	}

	function selectBone(key) {
		state.selectedBone = key;
		if (state.poseMode === 'fk') attachGizmo();
		renderControlsPanel();
		renderBoneList();
		updateSelectionLabel();
	}

	canvas.addEventListener('pointerdown', (ev) => {
		if (ev.button !== 0) return;
		if (gizmo.dragging) return; // gizmo owns this drag
		if (state.poseMode === 'ik' && tryStartIKDrag(ev)) {
			ev.preventDefault();
			return;
		}
		const bone = pickBoneAt(ev.clientX, ev.clientY);
		if (bone) selectBone(bone);
	});

	canvas.addEventListener('pointermove', (ev) => {
		if (!state.draggingIK) return;
		const hit = intersectDragPlane(ev.clientX, ev.clientY, state.draggingIK.plane);
		if (!hit) return;
		state.rig.solveIK(state.draggingIK.effectorKey, hit);
		const handle = state.ikHandles.get(state.draggingIK.effectorKey);
		if (handle) handle.position.copy(hit);
		if (state.selectedBone) renderControlsPanel();
	});

	function endIKDrag(ev) {
		if (!state.draggingIK) return;
		try {
			canvas.releasePointerCapture(ev.pointerId);
		} catch {}
		state.draggingIK = null;
		controls.enabled = true;
		syncIKHandles();
		commitEdit();
	}
	canvas.addEventListener('pointerup', endIKDrag);
	canvas.addEventListener('pointercancel', endIKDrag);

	// Gizmo rotations should refresh the slider readout live.
	gizmo.addEventListener('objectChange', () => {
		if (state.selectedBone) renderControlsPanel();
	});
	// A gizmo drag is one undoable edit: snapshot on grab, commit on release.
	gizmo.addEventListener('mouseDown', beginEdit);
	gizmo.addEventListener('mouseUp', commitEdit);

	// ── Pose history (undo / redo) ───────────────────────────────────────────
	// A bounded stack of canonical pose snapshots. Discrete actions (preset,
	// reset, mirror, paste, import) call recordHistory() before mutating;
	// continuous gestures (gizmo, IK drag, FK slider) bracket themselves with
	// beginEdit()/commitEdit() so the whole drag collapses to a single step.
	const HISTORY_LIMIT = 100;
	const history = { undo: [], redo: [], pending: null };

	function pushUndo(before) {
		history.undo.push(before);
		if (history.undo.length > HISTORY_LIMIT) history.undo.shift();
		history.redo.length = 0;
		updateHistoryButtons();
	}
	function recordHistory() {
		pushUndo(state.rig.getPose());
	}
	function beginEdit() {
		if (!history.pending) history.pending = state.rig.getPose();
	}
	function commitEdit() {
		const before = history.pending;
		history.pending = null;
		if (before && !posesEqual(before, state.rig.getPose())) pushUndo(before);
	}
	function restorePose(pose) {
		state.rig.applyPose(pose);
		if (state.poseMode === 'fk') attachGizmo();
		else syncIKHandles();
		renderControlsPanel();
	}
	function undoPose() {
		if (!history.undo.length) return setStatus('Nothing to undo.');
		history.redo.push(state.rig.getPose());
		if (history.redo.length > HISTORY_LIMIT) history.redo.shift();
		restorePose(history.undo.pop());
		updateHistoryButtons();
		setStatus('Undo.');
	}
	function redoPose() {
		if (!history.redo.length) return setStatus('Nothing to redo.');
		history.undo.push(state.rig.getPose());
		restorePose(history.redo.pop());
		updateHistoryButtons();
		setStatus('Redo.');
	}
	function updateHistoryButtons() {
		const u = $('#pose-undo');
		const r = $('#pose-redo');
		if (u) u.disabled = !history.undo.length;
		if (r) r.disabled = !history.redo.length;
	}

	// ── Mirror / copy / paste ────────────────────────────────────────────────
	function mirrorPose() {
		recordHistory();
		state.rig.mirrorPose();
		if (state.poseMode === 'fk') attachGizmo();
		else syncIKHandles();
		renderControlsPanel();
		setStatus('Pose mirrored left ↔ right.');
	}
	function copyPose() {
		state.clipboardPose = clonePose(state.rig.getPose());
		try {
			navigator.clipboard?.writeText(JSON.stringify(state.clipboardPose)).catch(() => {});
		} catch {}
		const pasteBtn = $('#pose-paste');
		if (pasteBtn) pasteBtn.disabled = false;
		setStatus('Pose copied.');
	}
	function pastePose() {
		if (!state.clipboardPose) return setStatus('Copy a pose first.', 'error');
		recordHistory();
		restorePose(state.clipboardPose);
		setStatus('Pose pasted.');
	}

	// ── FK gizmo ───────────────────────────────────────────────────────────
	function attachGizmo() {
		const key = state.selectedBone;
		const node = key && state.rig.getNode(key);
		if (state.poseMode !== 'fk' || !node) {
			gizmo.detach();
			gizmo.enabled = false;
			gizmo.visible = false;
			return;
		}
		gizmo.attach(node);
		gizmo.enabled = true;
		gizmo.visible = true;
	}

	// ── IK target handles ──────────────────────────────────────────────────
	function buildIKHandles() {
		for (const chain of state.rig.getIKChains()) {
			const m = new Mesh(handleGeom, handleMat.clone());
			m.renderOrder = 999;
			m.userData.effectorKey = chain.effectorKey;
			m.visible = false;
			ikLayer.add(m);
			state.ikHandles.set(chain.effectorKey, m);
		}
		syncIKHandles();
	}
	function clearIKHandles() {
		for (const m of state.ikHandles.values()) {
			ikLayer.remove(m);
			m.material?.dispose();
		}
		state.ikHandles.clear();
	}
	function syncIKHandles() {
		for (const [effKey, m] of state.ikHandles) {
			const node = state.rig.getNode(effKey);
			if (node) node.getWorldPosition(m.position);
		}
	}

	function tryStartIKDrag(ev) {
		raycaster.setFromCamera(toNDC(ev.clientX, ev.clientY), camera);
		const handles = [...state.ikHandles.values()].filter((m) => m.visible);
		const hits = raycaster.intersectObjects(handles, false);
		if (!hits.length) return false;
		const handle = hits[0].object;
		const effectorKey = handle.userData.effectorKey;
		// Drag plane: faces the camera, passes through the handle.
		const normal = camera.getWorldDirection(new Vector3()).negate();
		const plane = new Plane().setFromNormalAndCoplanarPoint(normal, handle.position.clone());
		beginEdit();
		state.draggingIK = { effectorKey, plane };
		controls.enabled = false;
		canvas.setPointerCapture(ev.pointerId);
		selectBone(effectorKey);
		return true;
	}

	function intersectDragPlane(clientX, clientY, plane) {
		raycaster.setFromCamera(toNDC(clientX, clientY), camera);
		const pt = new Vector3();
		return raycaster.ray.intersectPlane(plane, pt) ? pt : null;
	}

	function applyPoseMode() {
		const ik = state.poseMode === 'ik';
		for (const m of state.ikHandles.values()) m.visible = ik;
		if (ik) {
			gizmo.detach();
			gizmo.enabled = false;
			gizmo.visible = false;
			syncIKHandles();
		} else {
			attachGizmo();
		}
		document.querySelectorAll('[data-posemode]').forEach((b) => {
			b.setAttribute('aria-pressed', String(b.dataset.posemode === state.poseMode));
		});
		const hasIK = state.rig.getIKChains().length > 0;
		const ikBtn = document.querySelector('[data-posemode="ik"]');
		if (ikBtn) {
			ikBtn.disabled = !hasIK;
			ikBtn.title = hasIK
				? 'IK — drag a hand or foot and the limb solves'
				: 'IK unavailable — this rig has no recognizable limb chains';
		}
	}

	// ── Controls panel (FK sliders for the selected bone) ───────────────────
	function updateSelectionLabel() {
		if (!selectionLabel) return;
		selectionLabel.textContent = state.selectedBone
			? CANONICAL_LABELS[state.selectedBone] || state.selectedBone
			: 'Click a body part';
	}

	function renderControlsPanel() {
		if (!sliderHost) return;
		sliderHost.innerHTML = '';
		const key = state.selectedBone;
		if (!key || !state.rig.hasBone(key)) {
			sliderHost.appendChild(
				el('p', { class: 'pose-hint' }, [
					state.poseMode === 'ik'
						? 'Drag a glowing hand or foot handle to pose the limb with inverse kinematics.'
						: 'Click any body part in the scene, search a bone on the left, or pick a preset to start posing.',
				]),
			);
			return;
		}
		const rot = state.rig.getBoneEuler(key);
		const AXES = [
			['x', 'Bend / Pitch'],
			['y', 'Twist / Yaw'],
			['z', 'Tilt / Roll'],
		];
		for (const [axis, label] of AXES) {
			const value = rot[axis];
			const row = el('div', { class: 'pose-slider-row' }, [
				el('label', {}, [`${label} (${axis.toUpperCase()})`]),
				el('div', { class: 'pose-slider-value', 'data-axis': axis }, [
					`${((value * 180) / Math.PI).toFixed(0)}°`,
				]),
			]);
			const slider = el('input', {
				type: 'range',
				min: '-3.14159',
				max: '3.14159',
				step: '0.01',
				value: String(value),
				'aria-label': `${CANONICAL_LABELS[key] || key} ${label}`,
			});
			slider.addEventListener('pointerdown', beginEdit);
			slider.addEventListener('keydown', beginEdit);
			slider.addEventListener('change', commitEdit);
			slider.addEventListener('input', () => {
				const cur = state.rig.getBoneEuler(key);
				cur[axis] = parseFloat(slider.value);
				state.rig.setBoneEuler(key, cur);
				const next = state.rig.getBoneEuler(key);
				row.querySelector(`.pose-slider-value[data-axis="${axis}"]`).textContent =
					`${((next[axis] * 180) / Math.PI).toFixed(0)}°`;
				slider.value = String(next[axis]);
			});
			row.appendChild(slider);
			sliderHost.appendChild(row);
		}
		const resetBtn = el('button', { class: 'pose-btn pose-btn-ghost', type: 'button' }, [
			'Reset this bone',
		]);
		resetBtn.addEventListener('click', () => {
			recordHistory();
			state.rig.setBoneEuler(key, { x: 0, y: 0, z: 0 });
			renderControlsPanel();
		});
		sliderHost.appendChild(resetBtn);
	}

	// ── Bone list (searchable) ───────────────────────────────────────────────
	function renderBoneList() {
		if (!boneListHost) return;
		const q = (boneSearch?.value || '').trim().toLowerCase();
		boneListHost.innerHTML = '';
		const bones = state.rig
			.getBones()
			.filter(
				({ key, label }) =>
					!q || key.toLowerCase().includes(q) || label.toLowerCase().includes(q),
			);
		if (!bones.length) {
			boneListHost.appendChild(
				el('p', { class: 'pose-hint' }, ['No bones match your search.']),
			);
			return;
		}
		const row = el('div', { class: 'pose-joint-row' }, []);
		for (const { key, label } of bones) {
			const btn = el(
				'button',
				{
					class: 'pose-joint-btn',
					type: 'button',
					'data-bone': key,
					'aria-pressed': String(state.selectedBone === key),
				},
				[label],
			);
			btn.addEventListener('click', () => selectBone(key));
			row.appendChild(btn);
		}
		boneListHost.appendChild(row);
	}
	boneSearch?.addEventListener('input', renderBoneList);

	// ── Preset picker ──────────────────────────────────────────────────────
	const presetHost = $('#pose-presets-host');
	if (presetHost) {
		const grouped = getPresetsByGroup();
		for (const [groupName, presets] of Object.entries(grouped)) {
			if (!presets.length) continue;
			presetHost.appendChild(el('div', { class: 'pose-preset-group' }, [groupName]));
			const wrap = el('div', { class: 'pose-preset-grid' }, []);
			for (const preset of presets) {
				const btn = el(
					'button',
					{ class: 'pose-preset-btn', type: 'button', 'data-preset': preset.id },
					[preset.label],
				);
				btn.addEventListener('click', () => {
					recordHistory();
					state.rig.applyPose(poseFromMannequinPreset(preset.pose));
					if (state.poseMode === 'fk') attachGizmo();
					renderControlsPanel();
					setStatus(`Applied preset: ${preset.label}`);
				});
				wrap.appendChild(btn);
			}
			presetHost.appendChild(wrap);
		}
	}

	// ── Avatar loading ───────────────────────────────────────────────────────
	const gltfLoader = new GLTFLoader();
	let decodersReady = null;
	async function ensureDecoders() {
		if (!decodersReady) {
			decodersReady = getDecoders().then(({ dracoLoader, ktx2Loader, meshoptDecoder }) => {
				gltfLoader
					.setDRACOLoader(dracoLoader)
					.setKTX2Loader(ktx2Loader.detectSupport(renderer))
					.setMeshoptDecoder(meshoptDecoder);
			});
		}
		return decodersReady;
	}

	async function loadAvatarFromUrl(modelUrl, meta = {}) {
		if (!modelUrl) throw new Error('No model URL for this avatar.');
		await ensureDecoders();
		setStatus(`Loading ${meta.name || 'avatar'}…`);
		state.loadingAvatar = true;
		let gltf;
		try {
			gltf = await new Promise((resolve, reject) => {
				gltfLoader.load(
					modelUrl,
					resolve,
					(xhr) => {
						if (xhr.total) {
							const pct = Math.round((xhr.loaded / xhr.total) * 100);
							setStatus(`Loading ${meta.name || 'avatar'}… ${pct}%`);
						}
					},
					reject,
				);
			});
		} finally {
			state.loadingAvatar = false;
		}
		const scn = gltf.scene || gltf.scenes?.[0];
		const rig = scn && makeGltfRig(scn);
		if (!rig) {
			throw new Error(
				'That model has no recognizable humanoid skeleton — pick a rigged avatar.',
			);
		}
		mountRig(rig);
		state.avatar = { id: meta.id || null, name: meta.name || 'Avatar', model_url: modelUrl };
		frameObject(rig.root);
		setMannequinControlsEnabled(false);
		setStatus(`Loaded ${state.avatar.name}. Select a bone to pose, or switch to IK.`);
	}

	async function loadAvatarById(id) {
		setStatus('Resolving avatar…');
		const res = await fetch(`/api/avatars/${encodeURIComponent(id)}`, {
			credentials: 'include',
		});
		if (!res.ok)
			throw new Error(`Couldn't load avatar (${res.status}). It may be private or removed.`);
		const { avatar } = await res.json();
		const url = avatar?.model_url || avatar?.url;
		if (!url) throw new Error('That avatar has no downloadable model.');
		await loadAvatarFromUrl(url, { id: avatar.id, name: avatar.name });
	}

	function switchToMannequin() {
		gizmo.detach();
		mountRig(mannequinRig);
		state.avatar = null;
		controls.target.set(0, 0.95, 0);
		camera.position.set(2.2, 1.65, 3.0);
		controls.update();
		setMannequinControlsEnabled(true);
		updateUrlAvatar(null);
		setStatus('Switched to mannequin.');
	}

	function updateUrlAvatar(id) {
		const url = new URL(window.location.href);
		if (id) url.searchParams.set('avatar', id);
		else url.searchParams.delete('avatar');
		window.history.replaceState({}, '', url);
	}

	function setMannequinControlsEnabled(on) {
		for (const sel of ['#pose-build', '#pose-skin', '#pose-constraints']) {
			const node = $(sel);
			if (node) {
				node.disabled = !on;
				node.closest('.pose-form-row')?.classList.toggle('pose-disabled', !on);
			}
		}
	}

	// Load avatar / mannequin toolbar buttons.
	$('#pose-load-avatar')?.addEventListener('click', () => {
		const signedIn = document.cookie.includes('session') || false;
		const picker = new AvatarGalleryPicker({
			source: signedIn ? 'both' : 'public',
			title: 'Load an avatar to animate',
			ctaLabel: 'Pose this avatar',
			showModes: false,
			onSelect: async (avatar) => {
				picker.close();
				try {
					await loadAvatarFromUrl(avatar.model_url, { id: avatar.id, name: avatar.name });
					updateUrlAvatar(avatar.id);
				} catch (err) {
					setStatus(err.message, 'error');
				}
			},
		});
		picker.openModal();
	});
	$('#pose-use-mannequin')?.addEventListener('click', switchToMannequin);

	// ── Posing-mode toggle (FK / IK) ────────────────────────────────────────
	document.querySelectorAll('[data-posemode]').forEach((btn) => {
		btn.addEventListener('click', () => {
			if (btn.disabled) return;
			state.poseMode = btn.dataset.posemode;
			applyPoseMode();
			renderControlsPanel();
		});
	});

	// ── Top toolbar ──────────────────────────────────────────────────────────

	// Overflow ("More") menu: low-frequency actions (import/export pose JSON,
	// PNG screenshot) collapse behind one trigger so the bar fits laptop
	// widths. The panel is position:fixed and placed from the trigger's rect,
	// because the scrollable top bar would clip an absolutely-positioned child.
	const moreBtn = $('#pose-more');
	const moreMenu = $('#pose-more-menu');
	if (moreBtn && moreMenu) {
		const menuItems = () => [...moreMenu.querySelectorAll('[role="menuitem"]')];
		const openMenu = () => {
			const r = moreBtn.getBoundingClientRect();
			moreMenu.hidden = false;
			moreMenu.style.top = `${Math.round(r.bottom + 6)}px`;
			moreMenu.style.right = `${Math.max(8, Math.round(window.innerWidth - r.right))}px`;
			moreBtn.setAttribute('aria-expanded', 'true');
			menuItems()[0]?.focus();
		};
		const closeMenu = (refocus = false) => {
			if (moreMenu.hidden) return;
			moreMenu.hidden = true;
			moreBtn.setAttribute('aria-expanded', 'false');
			if (refocus) moreBtn.focus();
		};
		moreBtn.addEventListener('click', () => {
			if (moreMenu.hidden) openMenu();
			else closeMenu();
		});
		moreMenu.addEventListener('keydown', (ev) => {
			const list = menuItems();
			const idx = list.indexOf(document.activeElement);
			if (ev.key === 'Escape') {
				closeMenu(true);
			} else if (ev.key === 'ArrowDown') {
				ev.preventDefault();
				list[(idx + 1) % list.length]?.focus();
			} else if (ev.key === 'ArrowUp') {
				ev.preventDefault();
				list[(idx - 1 + list.length) % list.length]?.focus();
			} else if (
				(ev.key === 'Enter' || ev.key === ' ') &&
				document.activeElement?.classList?.contains('file-label')
			) {
				// A <label> doesn't activate its file input from the keyboard.
				ev.preventDefault();
				document.activeElement.querySelector('input[type="file"]')?.click();
			}
		});
		moreMenu.addEventListener('click', (ev) => {
			if (ev.target.closest('[role="menuitem"]')) closeMenu();
		});
		document.addEventListener('pointerdown', (ev) => {
			if (!moreMenu.hidden && !ev.target.closest('#pose-more, #pose-more-menu')) {
				closeMenu();
			}
		});
		window.addEventListener('resize', () => closeMenu());
	}

	$('#pose-reset')?.addEventListener('click', () => {
		recordHistory();
		state.rig.resetPose();
		if (state.poseMode === 'fk') attachGizmo();
		else syncIKHandles();
		setStatus('Pose reset.');
		renderControlsPanel();
	});

	$('#pose-screenshot')?.addEventListener('click', () => {
		renderer.render(scene, camera);
		const url = canvas.toDataURL('image/png');
		const a = document.createElement('a');
		a.href = url;
		a.download = `pose-${Date.now()}.png`;
		document.body.appendChild(a);
		a.click();
		a.remove();
		setStatus('Screenshot saved.');
	});

	$('#pose-export-json')?.addEventListener('click', () => {
		const pose = state.rig.getPose();
		const blob = new Blob([JSON.stringify(pose, null, 2)], { type: 'application/json' });
		const url = URL.createObjectURL(blob);
		const a = document.createElement('a');
		a.href = url;
		a.download = `pose-${Date.now()}.json`;
		document.body.appendChild(a);
		a.click();
		a.remove();
		URL.revokeObjectURL(url);
		setStatus('Pose JSON saved.');
	});

	$('#pose-import-json')?.addEventListener('change', (ev) => {
		const file = ev.target.files?.[0];
		if (!file) return;
		const reader = new FileReader();
		reader.onload = () => {
			try {
				const pose = JSON.parse(String(reader.result));
				recordHistory();
				state.rig.applyPose(pose);
				if (state.poseMode === 'fk') attachGizmo();
				renderControlsPanel();
				setStatus(`Imported pose from ${file.name}.`);
			} catch (err) {
				setStatus(`Import failed: ${err.message}`, 'error');
			}
		};
		reader.readAsText(file);
		ev.target.value = '';
	});

	// ── Settings panel (mannequin-only model controls) ───────────────────────
	$('#pose-build')?.addEventListener('change', (ev) => {
		if (state.rig.kind !== 'mannequin') return;
		state.rig.setBuild(ev.target.value);
		buildIKHandles();
		applyPoseMode();
	});
	$('#pose-skin')?.addEventListener('input', (ev) => {
		if (state.rig.kind === 'mannequin') state.rig.setColor(ev.target.value);
	});
	$('#pose-constraints')?.addEventListener('change', (ev) => {
		if (state.rig.kind !== 'mannequin') return;
		state.rig.setConstraintsEnabled(ev.target.checked);
		setStatus(
			ev.target.checked
				? 'Biological constraints on.'
				: 'Constraints off — full rotation allowed.',
		);
	});

	$('#pose-bg')?.addEventListener('input', (ev) => {
		scene.background = new Color(ev.target.value);
	});
	$('#pose-fov')?.addEventListener('input', (ev) => {
		camera.fov = parseFloat(ev.target.value);
		camera.updateProjectionMatrix();
	});
	$('#pose-grid')?.addEventListener('change', (ev) => {
		scene.traverse((o) => {
			if (o.isGridHelper) o.visible = ev.target.checked;
		});
	});

	function syncKeyLight() {
		const r = state.keyDistance;
		const x = r * Math.cos(state.keyElevation) * Math.sin(state.keyAzimuth);
		const z = r * Math.cos(state.keyElevation) * Math.cos(state.keyAzimuth);
		const y = r * Math.sin(state.keyElevation);
		state.keyLight.position.set(x, y, z);
		state.keyLight.target.position.set(0, 0.9, 0);
		state.keyLight.target.updateMatrixWorld();
	}
	syncKeyLight();
	$('#pose-light-azimuth')?.addEventListener('input', (ev) => {
		state.keyAzimuth = (parseFloat(ev.target.value) / 180) * Math.PI;
		syncKeyLight();
	});
	$('#pose-light-elevation')?.addEventListener('input', (ev) => {
		state.keyElevation = (parseFloat(ev.target.value) / 180) * Math.PI;
		syncKeyLight();
	});
	$('#pose-light-intensity')?.addEventListener('input', (ev) => {
		state.keyLight.intensity = parseFloat(ev.target.value);
	});

	// ── Floor props ────────────────────────────────────────────────────────
	const propHost = $('#pose-prop-host');
	if (propHost) {
		for (const [id, def] of Object.entries(FLOOR_PROPS)) {
			const btn = el(
				'button',
				{
					class: 'pose-prop-btn',
					type: 'button',
					'data-prop': id,
					'aria-pressed': String(state.prop === id),
				},
				[def.label],
			);
			btn.addEventListener('click', () => {
				state.prop = id;
				if (state.propGroup) {
					state.propGroup.traverse((n) => {
						n.geometry?.dispose();
						if (Array.isArray(n.material)) n.material.forEach((m) => m.dispose());
						else n.material?.dispose();
					});
					state.propGroup = null;
				}
				propLayer.clear();
				if (def.build) {
					const g = def.build();
					propLayer.add(g);
					state.propGroup = g;
				}
				document
					.querySelectorAll('[data-prop]')
					.forEach((b) => b.setAttribute('aria-pressed', String(b.dataset.prop === id)));
			});
			propHost.appendChild(btn);
		}
	}

	// ── Top-toolbar pose actions ─────────────────────────────────────────────
	$('#pose-undo')?.addEventListener('click', undoPose);
	$('#pose-redo')?.addEventListener('click', redoPose);
	$('#pose-mirror')?.addEventListener('click', mirrorPose);
	$('#pose-copy')?.addEventListener('click', copyPose);
	$('#pose-paste')?.addEventListener('click', pastePose);
	updateHistoryButtons();

	// ── Keyboard shortcuts ───────────────────────────────────────────────────
	window.addEventListener('keydown', (ev) => {
		if (ev.target.matches('input, textarea, select')) return;
		const k = ev.key.toLowerCase();
		const mod = ev.ctrlKey || ev.metaKey;
		// Undo / redo — Ctrl/Cmd+Z, Shift+Z or Ctrl+Y to redo.
		if (mod && k === 'z') {
			ev.preventDefault();
			ev.shiftKey ? redoPose() : undoPose();
			return;
		}
		if (mod && k === 'y') {
			ev.preventDefault();
			redoPose();
			return;
		}
		// Remaining shortcuts are single-key (no modifier) so they never clobber
		// browser/OS chords like Ctrl+C.
		if (mod || ev.altKey) return;
		if (k === 'f') {
			state.poseMode = 'fk';
			applyPoseMode();
			renderControlsPanel();
		} else if (k === 'i') {
			const b = document.querySelector('[data-posemode="ik"]');
			if (b && !b.disabled) {
				state.poseMode = 'ik';
				applyPoseMode();
				renderControlsPanel();
			}
		} else if (k === 'r' && state.selectedBone) {
			recordHistory();
			state.rig.setBoneEuler(state.selectedBone, { x: 0, y: 0, z: 0 });
			renderControlsPanel();
		} else if (k === 'm') {
			mirrorPose();
		} else if (k === 'c') {
			copyPose();
		} else if (k === 'v') {
			pastePose();
		} else if (k === 'escape') {
			state.selectedBone = null;
			gizmo.detach();
			renderControlsPanel();
			renderBoneList();
			updateSelectionLabel();
		}
	});

	// ── Animation timeline ───────────────────────────────────────────────────
	// Keyframe recorder: set a pose → drop a keyframe → advance the playhead →
	// re-pose → drop another. The render loop interpolates (slerp) between
	// keyframes and plays the result; export bakes a THREE.AnimationClip.
	timeline = setupTimeline();

	// ── Crash recovery & unsaved-work guard ──────────────────────────────────
	// Posing and keyframing never touch the account until the user explicitly
	// Saves, so a refresh or accidental tab close would lose in-progress work.
	// We snapshot the timeline document to localStorage on a light interval and
	// warn before unload while the current state differs from the last point it
	// was persisted (an account save, or opening a saved clip). On the next boot
	// the draft is offered back — unless an explicit deep-link (?anim=) wins.
	// The recovery offer banner (last session's unsaved work), when showing.
	let recoveryBanner = null;
	// onSupersede fires when a still-pending recovery offer is overtaken by fresh
	// work (the user started posing instead of answering) — dismiss the banner.
	const autosave = setupAutosave({ onSupersede: () => dismissRecoveryPrompt() });

	// ── Animation preset library ─────────────────────────────────────────────
	// A curated gallery of ready-to-apply motion clips. Picking one retargets it
	// onto the loaded rig and plays it live in this same viewport, then offers an
	// animated-GLB export. While a preset previews it drives the figure, so we
	// pause the keyframe timeline and stow the FK gizmo.
	const animLibraryHost = $('#pose-anim-library');
	if (animLibraryHost) {
		const animLibrary = new AnimationLibrary({
			host: animLibraryHost,
			getRig: () => state.rig,
			getAvatarId: () => state.avatar?.id || null,
			setStatus,
			onPreviewStart: () => {
				timeline?.pause?.();
				gizmo.detach();
				gizmo.enabled = false;
				gizmo.visible = false;
			},
			onPreviewStop: () => {
				if (state.poseMode === 'fk' && state.selectedBone) attachGizmo();
				renderControlsPanel();
			},
		});
		state.animLibrary = animLibrary;
		animLibrary.mount();
	}

	function setupTimeline() {
		const doc = createDocument();
		const anim = { doc, playing: false, playhead: 0, selectedId: null };
		state.anim = anim;

		const tl = {
			track: $('#tl-track'),
			lane: $('#tl-lane'),
			ruler: $('#tl-ruler'),
			playhead: $('#tl-playhead'),
			empty: $('#tl-empty'),
			time: $('#tl-time'),
			play: $('#tl-play'),
			stop: $('#tl-stop'),
			start: $('#tl-start'),
			end: $('#tl-end'),
			loop: $('#tl-loop'),
			add: $('#tl-add-key'),
			del: $('#tl-del-key'),
			easing: $('#tl-easing'),
			name: $('#tl-name'),
			duration: $('#tl-duration'),
			fps: $('#tl-fps'),
			exportJson: $('#tl-export-json'),
			exportGlb: $('#tl-export-glb'),
			openScene: $('#tl-open-scene'),
		};
		if (!tl.track) return null; // page without the timeline markup — no-op

		const clamp = (v, lo, hi) => Math.max(lo, Math.min(hi, v));
		const NICE_STEPS = [0.1, 0.2, 0.25, 0.5, 1, 2, 5, 10, 15, 30, 60];
		const pct = (t) => (doc.duration > 0 ? (t / doc.duration) * 100 : 0);
		const xToTime = (clientX) => {
			const rect = tl.track.getBoundingClientRect();
			return clamp((clientX - rect.left) / rect.width, 0, 1) * doc.duration;
		};
		const safeName = () =>
			(doc.name || 'animation')
				.replace(/[^a-z0-9._-]+/gi, '-')
				.replace(/-+/g, '-')
				.replace(/^-|-$/g, '')
				.slice(0, 60) || 'animation';

		// Sync the static control values from the document defaults.
		tl.name.value = doc.name;
		tl.duration.value = String(doc.duration);
		tl.fps.value = String(doc.fps);
		tl.loop.setAttribute('aria-pressed', String(doc.loop));
		tl.track.setAttribute('aria-valuemax', String(doc.duration));

		// ── Preview ────────────────────────────────────────────────────────────
		function applyPreview() {
			if (!doc.keyframes.length || !state.rig) return;
			const pose = sampleAtTime(doc, anim.playhead);
			if (pose) {
				state.rig.applyPose(pose);
				if (state.poseMode === 'ik') syncIKHandles();
			}
		}

		function setPlayhead(t, { render = false } = {}) {
			anim.playhead = clamp(t, 0, doc.duration);
			tl.playhead.style.left = `${pct(anim.playhead)}%`;
			tl.time.innerHTML = `<b>${anim.playhead.toFixed(2)}</b> / ${doc.duration.toFixed(2)}s`;
			tl.track.setAttribute('aria-valuenow', anim.playhead.toFixed(2));
			applyPreview();
			if (render && state.selectedBone) renderControlsPanel();
		}

		// ── Transport ────────────────────────────────────────────────────────────
		function play() {
			if (!doc.keyframes.length) {
				setStatus('Add a keyframe first, then play.', 'error');
				return;
			}
			if (!doc.loop && anim.playhead >= doc.duration - 1e-3) anim.playhead = 0;
			anim.playing = true;
			tl.play.textContent = '⏸';
			tl.play.setAttribute('aria-pressed', 'true');
		}
		function pause() {
			anim.playing = false;
			tl.play.textContent = '▶';
			tl.play.setAttribute('aria-pressed', 'false');
		}
		function toggle() {
			anim.playing ? pause() : play();
		}
		function stop() {
			pause();
			setPlayhead(0, { render: true });
		}

		function advance(dt) {
			if (!anim.playing) return;
			let t = anim.playhead + dt;
			if (t >= doc.duration) {
				if (doc.loop) t = doc.duration > 0 ? t % doc.duration : 0;
				else {
					setPlayhead(doc.duration);
					pause();
					return;
				}
			}
			setPlayhead(t);
		}

		// ── Ruler + keyframes render ─────────────────────────────────────────────
		function niceStep(raw) {
			for (const s of NICE_STEPS) if (s >= raw) return s;
			return NICE_STEPS[NICE_STEPS.length - 1];
		}
		function renderRuler() {
			tl.ruler.innerHTML = '';
			const step = niceStep(doc.duration / 8);
			for (let t = 0; t <= doc.duration + 1e-6; t += step) {
				const left = pct(t);
				tl.ruler.appendChild(el('div', { class: 'tl-tick', style: `left:${left}%` }));
				tl.ruler.appendChild(
					el('div', { class: 'tl-tick-label', style: `left:${left}%` }, [
						`${+t.toFixed(3)}s`,
					]),
				);
			}
		}

		function refreshExportEnabled() {
			const has = doc.keyframes.length > 0;
			tl.exportJson.disabled = !has;
			tl.exportGlb.disabled = !has;
			if (tl.openScene) tl.openScene.disabled = !has;
		}

		function updateSelectionUI() {
			const kf = doc.keyframes.find((k) => k.id === anim.selectedId);
			tl.easing.disabled = !kf;
			tl.del.disabled = !kf;
			if (kf) tl.easing.value = kf.easing;
			tl.lane.querySelectorAll('.tl-key').forEach((d) => {
				d.setAttribute('aria-selected', String(d.dataset.id === anim.selectedId));
			});
		}

		function renderKeyframes() {
			tl.lane.innerHTML = '';
			const isEmpty = !doc.keyframes.length;
			tl.empty.style.display = isEmpty ? 'flex' : 'none';
			// Drives the CSS that hides the ruler while the hint is showing.
			tl.track.dataset.empty = String(isEmpty);
			for (const kf of doc.keyframes) {
				const diamond = el('div', {
					class: 'tl-key',
					'data-id': kf.id,
					tabindex: '0',
					role: 'button',
					'aria-selected': String(kf.id === anim.selectedId),
					'aria-label': `Keyframe at ${kf.time.toFixed(2)} seconds, ${kf.easing}`,
					title: `${kf.time.toFixed(2)}s · ${kf.easing}`,
					style: `left:${pct(kf.time)}%`,
				});
				diamond.addEventListener('pointerdown', (ev) => startKeyDrag(ev, kf, diamond));
				diamond.addEventListener('keydown', (ev) => {
					if (ev.key === 'Delete' || ev.key === 'Backspace') {
						ev.preventDefault();
						select(kf.id);
						deleteSelected();
					} else if (ev.key === 'Enter' || ev.key === ' ') {
						ev.preventDefault();
						select(kf.id);
					}
				});
				tl.lane.appendChild(diamond);
			}
			refreshExportEnabled();
			updateSelectionUI();
		}

		// ── Keyframe ops ──────────────────────────────────────────────────────────
		function select(id) {
			anim.selectedId = id;
			const kf = doc.keyframes.find((k) => k.id === id);
			updateSelectionUI();
			if (kf) setPlayhead(kf.time, { render: true });
		}

		function captureKeyframe() {
			if (!state.rig) return;
			const existed = doc.keyframes.some((k) => Math.abs(k.time - anim.playhead) <= 1e-3);
			const kf = upsertKeyframe(doc, anim.playhead, state.rig.getPose(), DEFAULT_EASING);
			anim.selectedId = kf.id;
			renderKeyframes();
			setStatus(
				existed
					? `Keyframe updated at ${kf.time.toFixed(2)}s.`
					: `Keyframe added at ${kf.time.toFixed(2)}s · ${doc.keyframes.length} total.`,
			);
		}

		function deleteSelected() {
			if (!anim.selectedId) return;
			removeKeyframe(doc, anim.selectedId);
			anim.selectedId = null;
			renderKeyframes();
			applyPreview();
			setStatus('Keyframe deleted.');
		}

		// Drag a keyframe diamond to retime it (and scrub the playhead with it).
		function startKeyDrag(ev, kf, diamond) {
			ev.stopPropagation();
			ev.preventDefault();
			pause();
			select(kf.id);
			diamond.setPointerCapture(ev.pointerId);
			const onMove = (e) => {
				// moveKeyframe re-sorts the list, so live preview (sampleAtTime,
				// which assumes sorted keyframes) stays correct mid-drag.
				moveKeyframe(doc, kf.id, xToTime(e.clientX));
				diamond.style.left = `${pct(kf.time)}%`;
				diamond.title = `${kf.time.toFixed(2)}s · ${kf.easing}`;
				setPlayhead(kf.time);
			};
			const onUp = (e) => {
				diamond.removeEventListener('pointermove', onMove);
				diamond.removeEventListener('pointerup', onUp);
				diamond.removeEventListener('pointercancel', onUp);
				try {
					diamond.releasePointerCapture(e.pointerId);
				} catch {}
				renderKeyframes();
				if (state.selectedBone) renderControlsPanel();
			};
			diamond.addEventListener('pointermove', onMove);
			diamond.addEventListener('pointerup', onUp);
			diamond.addEventListener('pointercancel', onUp);
		}

		// ── Track scrubbing ────────────────────────────────────────────────────────
		let scrubbing = false;
		tl.track.addEventListener('pointerdown', (ev) => {
			if (ev.target.closest('.tl-key')) return; // diamond handles its own drag
			pause();
			scrubbing = true;
			tl.track.setPointerCapture(ev.pointerId);
			setPlayhead(xToTime(ev.clientX), { render: true });
		});
		tl.track.addEventListener('pointermove', (ev) => {
			if (scrubbing) setPlayhead(xToTime(ev.clientX));
		});
		const endScrub = (ev) => {
			if (!scrubbing) return;
			scrubbing = false;
			try {
				tl.track.releasePointerCapture(ev.pointerId);
			} catch {}
			if (state.selectedBone) renderControlsPanel();
		};
		tl.track.addEventListener('pointerup', endScrub);
		tl.track.addEventListener('pointercancel', endScrub);
		tl.track.addEventListener('keydown', (ev) => {
			const stepDt = 1 / clamp(doc.fps || 30, 1, 120);
			if (ev.key === 'ArrowLeft') {
				ev.preventDefault();
				pause();
				setPlayhead(anim.playhead - stepDt, { render: true });
			} else if (ev.key === 'ArrowRight') {
				ev.preventDefault();
				pause();
				setPlayhead(anim.playhead + stepDt, { render: true });
			} else if (ev.key === 'Home') {
				ev.preventDefault();
				setPlayhead(0, { render: true });
			} else if (ev.key === 'End') {
				ev.preventDefault();
				setPlayhead(doc.duration, { render: true });
			}
		});

		// ── Controls ────────────────────────────────────────────────────────────────
		tl.play.addEventListener('click', toggle);
		tl.stop.addEventListener('click', stop);
		tl.start.addEventListener('click', () => {
			pause();
			setPlayhead(0, { render: true });
		});
		tl.end.addEventListener('click', () => {
			pause();
			setPlayhead(doc.duration, { render: true });
		});
		tl.loop.addEventListener('click', () => {
			doc.loop = !doc.loop;
			tl.loop.setAttribute('aria-pressed', String(doc.loop));
			setStatus(`Loop ${doc.loop ? 'on' : 'off'}.`);
		});
		tl.add.addEventListener('click', captureKeyframe);
		tl.del.addEventListener('click', deleteSelected);
		tl.easing.addEventListener('change', () => {
			if (!anim.selectedId) return;
			setKeyframeEasing(doc, anim.selectedId, tl.easing.value);
			applyPreview();
			setStatus(`Easing set to ${tl.easing.value}.`);
		});
		tl.name.addEventListener('input', () => {
			doc.name = tl.name.value.trim() || 'animation';
		});
		tl.duration.addEventListener('change', () => {
			doc.duration = clamp(parseFloat(tl.duration.value) || 4, 0.25, 120);
			tl.duration.value = String(doc.duration);
			tl.track.setAttribute('aria-valuemax', String(doc.duration));
			clampKeyframesToDuration(doc);
			renderRuler();
			renderKeyframes();
			setPlayhead(Math.min(anim.playhead, doc.duration), { render: true });
		});
		tl.fps.addEventListener('change', () => {
			doc.fps = Math.round(clamp(parseFloat(tl.fps.value) || 30, 1, 120));
			tl.fps.value = String(doc.fps);
		});

		// ── Export ────────────────────────────────────────────────────────────────
		function downloadBlob(data, filename, mime) {
			const blob = data instanceof Blob ? data : new Blob([data], { type: mime });
			const url = URL.createObjectURL(blob);
			const a = document.createElement('a');
			a.href = url;
			a.download = filename;
			document.body.appendChild(a);
			a.click();
			a.remove();
			setTimeout(() => URL.revokeObjectURL(url), 1500);
		}
		async function withBusy(btn, label, fn, opts = {}) {
			const original = btn.textContent;
			btn.classList.remove('is-ok', 'is-err');
			btn.classList.add('is-busy');
			btn.textContent = opts.busyText || 'Working…';
			try {
				await fn();
				btn.classList.replace('is-busy', 'is-ok');
				btn.textContent = opts.okText || 'Saved ✓';
				setStatus(opts.doneStatus || `${label} downloaded.`);
			} catch (err) {
				btn.classList.replace('is-busy', 'is-err');
				btn.textContent = 'Failed';
				setStatus(`${label} failed: ${err.message}`, 'error');
			} finally {
				setTimeout(() => {
					btn.classList.remove('is-ok', 'is-err');
					btn.textContent = original;
				}, 2200);
			}
		}

		tl.exportJson.addEventListener('click', () => {
			pause();
			withBusy(tl.exportJson, 'Clip JSON', async () => {
				const json = serializeClip(doc, { resolveBoneName: (k) => k, rootName: 'Hips' });
				downloadBlob(
					JSON.stringify(json, null, 2),
					`${safeName()}.json`,
					'application/json',
				);
			});
		});
		// Bake the keyframe document onto the live rig and serialize the rig
		// (mesh + embedded clip) to a binary GLB. The clip's tracks bind to the
		// rig's ACTUAL node names so the animation plays against this same model
		// when re-imported anywhere (download, or the Scene Studio handoff).
		async function bakeAnimatedGlb() {
			const rig = state.rig;
			const clip = bakeClip(doc, {
				resolveBoneName: (k) => rig.getNode(k)?.name || null,
				rootName: rig.root?.name || '',
			});
			const exporter = new GLTFExporter();
			const buffer = await exporter.parseAsync(rig.root, {
				binary: true,
				animations: [clip],
				embedImages: true,
			});
			return { buffer, clip };
		}

		tl.exportGlb.addEventListener('click', () => {
			pause();
			withBusy(tl.exportGlb, 'Animated GLB', async () => {
				const { buffer } = await bakeAnimatedGlb();
				downloadBlob(buffer, `${safeName()}.glb`, 'model/gltf-binary');
			});
		});

		// Hand the animation to /scene (the three.js editor) as a recordable
		// timeline track. We stash the baked GLB in IndexedDB and navigate —
		// navigating only after the write resolves, so the studio never opens to
		// an empty handoff. Same-tab so a popup blocker can't swallow it.
		tl.openScene?.addEventListener('click', () => {
			pause();
			withBusy(
				tl.openScene,
				'Scene Studio',
				async () => {
					const { buffer, clip } = await bakeAnimatedGlb();
					const label = (state.avatar?.name || doc.name || 'Animation')
						.toString()
						.slice(0, 64);
					await putSceneHandoff({ glb: buffer, name: label, animationName: clip.name });
					window.location.assign('/scene?handoff=1');
				},
				{
					busyText: 'Opening…',
					okText: 'Opening ↗',
					doneStatus: 'Opening Scene Studio — use Render ▸ Video to record.',
				},
			);
		});

		// ── Keyboard (timeline) ──────────────────────────────────────────────────────
		window.addEventListener('keydown', (ev) => {
			if (ev.target.matches('input, textarea, select') || ev.target.closest('.tl-key'))
				return;
			if (ev.key === ' ') {
				ev.preventDefault();
				toggle();
			} else if (ev.key === 'k' || ev.key === 'K') {
				captureKeyframe();
			} else if ((ev.key === 'Delete' || ev.key === 'Backspace') && anim.selectedId) {
				ev.preventDefault();
				deleteSelected();
			} else if (ev.key === 'Home') {
				setPlayhead(0, { render: true });
			} else if (ev.key === 'End') {
				setPlayhead(doc.duration, { render: true });
			}
		});

		// ── Init ────────────────────────────────────────────────────────────────────
		renderRuler();
		renderKeyframes();
		setPlayhead(0);

		// Snapshot the editing document (deep clone) for saving.
		function getDocument() {
			return {
				name: doc.name,
				duration: doc.duration,
				fps: doc.fps,
				loop: doc.loop,
				keyframes: doc.keyframes.map((k) => ({
					id: k.id,
					time: k.time,
					easing: k.easing,
					pose: {
						bones: { ...k.pose.bones },
						rootPosition: { ...(k.pose.rootPosition || { x: 0, y: 0, z: 0 }) },
					},
				})),
			};
		}

		// Replace the editing document (reopening a saved clip). Rebuilds the
		// timeline and applies the first frame so the rig reflects the animation.
		function loadDocument(nd) {
			if (!nd) return;
			pause();
			doc.name = nd.name || 'animation';
			doc.duration = clamp(Number(nd.duration) || 4, 0.25, 120);
			doc.fps = Math.round(clamp(Number(nd.fps) || 30, 1, 240));
			doc.loop = nd.loop !== false;
			doc.keyframes = (nd.keyframes || [])
				.map((k, i) => ({
					id: typeof k.id === 'string' && k.id ? k.id : `kf_load_${i}`,
					time: clamp(Number(k.time) || 0, 0, doc.duration),
					easing: EASINGS[k.easing] ? k.easing : DEFAULT_EASING,
					pose:
						k.pose && k.pose.bones
							? {
									bones: { ...k.pose.bones },
									rootPosition: k.pose.rootPosition || { x: 0, y: 0, z: 0 },
								}
							: { bones: {} },
				}))
				.sort((a, b) => a.time - b.time);
			anim.selectedId = null;
			tl.name.value = doc.name;
			tl.duration.value = String(doc.duration);
			tl.fps.value = String(doc.fps);
			tl.loop.setAttribute('aria-pressed', String(doc.loop));
			tl.track.setAttribute('aria-valuemax', String(doc.duration));
			renderRuler();
			renderKeyframes();
			setPlayhead(0, { render: true });
		}

		return {
			update: advance,
			pause,
			onRigChanged: () => {
				if (doc.keyframes.length) applyPreview();
			},
			bake: () => bakeClip(doc, { resolveBoneName: (k) => k, rootName: 'Hips' }),
			serialize: () => serializeClip(doc, { resolveBoneName: (k) => k, rootName: 'Hips' }),
			// Bake the live rig (mesh + embedded clip) to a self-contained binary
			// GLB — the sellable artifact for a marketplace listing.
			bakeArtifact: () => bakeAnimatedGlb(),
			captureThumbnail: () => {
				renderer.render(scene, camera);
				return renderer.domElement.toDataURL('image/png');
			},
			getDocument,
			loadDocument,
			keyframeCount: () => doc.keyframes.length,
		};
	}

	// Local crash-recovery for in-progress timeline work. Returns null when the
	// page has no timeline (the studio markup is absent) so callers no-op safely.
	function setupAutosave({ onSupersede } = {}) {
		if (!timeline) return null;
		const DRAFT_KEY = 'pose-studio:draft:v2';
		// savedBaseline = the document JSON at the last persisted point (account
		// save or open). lastDraftJson tracks what we last wrote to localStorage so
		// the interval skips redundant writes.
		let savedBaseline = JSON.stringify(timeline.getDocument());
		let lastDraftJson = null;
		// True while a recovered draft is being OFFERED but not yet applied. The
		// timeline is empty in that window, so without this guard the periodic
		// persistDraft() would clear the on-disk draft out from under the prompt
		// (a reload before the user chooses would then lose the work).
		let restorePending = false;

		const currentJson = () => JSON.stringify(timeline.getDocument());

		const readDraft = () => {
			try {
				return JSON.parse(localStorage.getItem(DRAFT_KEY) || 'null');
			} catch {
				return null;
			}
		};
		const clearDraft = () => {
			try {
				localStorage.removeItem(DRAFT_KEY);
			} catch {
				/* storage blocked — nothing to clear */
			}
		};

		function hasUnsavedWork() {
			const doc = timeline.getDocument();
			return doc.keyframes.length > 0 && currentJson() !== savedBaseline;
		}

		function persistDraft() {
			// While a recovered draft is being offered, leave it on disk, unless the
			// user has started fresh keyframe work without answering, in which case
			// the offer is superseded and this new work takes over the draft slot.
			if (restorePending) {
				if (!timeline.getDocument().keyframes.length) return;
				restorePending = false;
				onSupersede?.();
			}
			const cur = currentJson();
			if (cur === lastDraftJson) return;
			lastDraftJson = cur;
			const doc = timeline.getDocument();
			// Only stash genuine, not-yet-saved work — never an empty doc or a
			// document that already matches the persisted baseline.
			if (!doc.keyframes.length || cur === savedBaseline) {
				clearDraft();
				return;
			}
			try {
				localStorage.setItem(
					DRAFT_KEY,
					JSON.stringify({ doc, savedAt: Date.now(), avatarId: state.avatar?.id || null }),
				);
			} catch {
				/* quota / private mode — recovery simply unavailable this session */
			}
		}

		// Called when the document reaches a persisted state (saved to the account
		// or freshly opened from it): reset the baseline and drop the local draft.
		function markSaved() {
			savedBaseline = currentJson();
			lastDraftJson = null;
			clearDraft();
		}

		// Read (without applying) the previous session's unsaved draft, if any.
		// Boot uses this to OFFER recovery rather than silently applying keyframes
		// onto whatever rig happens to be loaded — auto-applying a pose made on a
		// different avatar contorts the mannequin and gives no way back to a clean
		// figure. Returns { doc, count, savedAt, avatarId } or null.
		function peekDraft() {
			const saved = readDraft();
			const count = saved?.doc?.keyframes?.length || 0;
			if (!count) return null;
			// Freeze the on-disk draft until the offer is resolved (see restorePending).
			restorePending = true;
			return { doc: saved.doc, count, savedAt: saved.savedAt || null, avatarId: saved.avatarId || null };
		}

		// Apply a peeked draft's timeline to the live rig. Restored work stays
		// "unsaved" (it isn't in the account yet), so the unload guard keeps
		// protecting it until the user Saves.
		function applyDraft(doc) {
			restorePending = false;
			if (!doc) return;
			timeline.loadDocument(doc);
			lastDraftJson = currentJson();
		}

		function discardDraft() {
			restorePending = false;
			clearDraft();
		}

		const interval = setInterval(persistDraft, 1500);
		document.addEventListener('visibilitychange', () => {
			if (document.hidden) persistDraft();
		});
		window.addEventListener('beforeunload', (ev) => {
			persistDraft();
			if (hasUnsavedWork()) {
				ev.preventDefault();
				ev.returnValue = '';
			}
		});
		window.addEventListener('pagehide', () => clearInterval(interval));

		return { markSaved, peekDraft, applyDraft, discardDraft, hasUnsavedWork };
	}

	// ── Account: save + "My animations" library ──────────────────────────────
	const library = new PoseLibrary({
		getDocument: () => timeline.getDocument(),
		loadDocument: (d) => {
			timeline.loadDocument(d);
			autosave?.markSaved();
		},
		onSaved: () => autosave?.markSaved(),
		serializeClip: () => timeline.serialize(),
		bakeArtifact: () => timeline.bakeArtifact(),
		captureThumbnail: () => timeline.captureThumbnail(),
		keyframeCount: () => timeline.keyframeCount(),
		currentAvatarId: () => state.avatar?.id || null,
		currentAvatarName: () => state.avatar?.name || null,
		loadAvatarById: (id) => loadAvatarById(id),
		switchToMannequin: () => switchToMannequin(),
		setStatus: (m, k) => setStatus(m, k),
	});
	state.library = library;
	library.mount();

	// ── Boot: honor ?avatar=, ?src= and ?anim= ───────────────────────────────
	const _params = new URL(window.location.href).searchParams;
	const requestedAvatar = _params.get('avatar');
	// ?src=<glb url> loads a model straight off its URL (the /viewer "Animate"
	// funnel). Same trusted-host gate as every other model-URL query param.
	const rawSrc = _params.get('src') || '';
	const requestedSrc = isSafeQueryModelUrl(rawSrc) ? rawSrc : '';
	const requestedAnim = _params.get('anim');
	// ?spell=<word> — fingerspell the word in ASL on arrival (shareable link).
	const requestedSpell = (_params.get('spell') || '').slice(0, 40);

	// An explicit ?anim=, ?spell= or model deep-link wins over any recovered
	// draft; otherwise we OFFER back last session's unsaved work (see boot tail).
	const hasDeepLink = requestedAvatar || requestedSrc || requestedAnim || requestedSpell;
	const pendingDraft = !hasDeepLink ? autosave?.peekDraft() : null;

	// Offer the previous session's unsaved work as an explicit choice instead of
	// silently applying it. Keeps the clean default figure on screen until the
	// user opts in; Restore reloads the avatar the pose was made on, then applies
	// the keyframes; Discard drops the local draft for good.
	function showRecoveryPrompt(draft) {
		const canvasWrap = document.getElementById('pose-canvas')?.parentElement || document.body;
		dismissRecoveryPrompt();

		const when = draft.savedAt ? new Date(draft.savedAt).toLocaleTimeString() : 'a previous session';

		const restore = async () => {
			dismissRecoveryPrompt();
			setStatus('Restoring your animation…');
			// Reload the avatar the draft was posed on so the keyframes land on the
			// same rig (a pose made on a rigged avatar looks wrong on the mannequin).
			// Apply the timeline regardless of whether that avatar still resolves.
			if (draft.avatarId && draft.avatarId !== state.avatar?.id) {
				try {
					await loadAvatarById(draft.avatarId);
				} catch (err) {
					log.warn('[pose] recovery avatar reload failed:', err?.message);
					setStatus(`Original avatar unavailable (${err?.message || 'removed'}); restoring onto the mannequin.`, 'error');
				}
			}
			autosave.applyDraft(draft.doc);
			setStatus(
				`Recovered your unsaved animation. ${draft.count} keyframe${draft.count === 1 ? '' : 's'} from ${when}. Save it to keep it.`,
			);
		};
		const discard = () => {
			dismissRecoveryPrompt();
			autosave.discardDraft();
			setStatus('Ready. Click a body part to pose, or load an avatar.');
		};

		recoveryBanner = el('div', { id: 'pose-recovery', role: 'status', 'aria-live': 'polite' }, [
			el('div', { class: 'pose-recovery-body' }, [
				el('div', { class: 'pose-recovery-icon', 'aria-hidden': 'true' }, ['↺']),
				el('div', { class: 'pose-recovery-copy' }, [
					el('strong', {}, ['Unsaved animation found']),
					el('span', {}, [
						`${draft.count} keyframe${draft.count === 1 ? '' : 's'} from ${when}. Restore it or start fresh.`,
					]),
				]),
			]),
			el('div', { class: 'pose-recovery-actions' }, [
				el('button', { class: 'pose-btn pose-btn-ghost', type: 'button', onclick: discard }, ['Discard']),
				el('button', { class: 'pose-btn pose-btn-primary', type: 'button', onclick: restore }, ['Restore']),
			]),
		]);
		canvasWrap.appendChild(recoveryBanner);
	}

	function dismissRecoveryPrompt() {
		recoveryBanner?.remove();
		recoveryBanner = null;
	}

	// A 36-char UUID is a saved community clip (PoseLibrary.openById); anything
	// else is a built-in preset name from the animation library (AnimationLibrary
	// .openByName). The /animations gallery deep-links into both.
	const openRequestedAnim = (id) => {
		const isApiId = /^[0-9a-f-]{36}$/i.test(id);
		const p = isApiId
			? library.openById(id)
			: state.animLibrary
				? state.animLibrary.openByName(id)
				: Promise.reject(new Error('animation library unavailable'));
		return p.catch((err) => {
			setStatus(`Could not load animation: ${err?.message || 'unknown error'}`, 'error');
		});
	};
	const openRequestedExtras = () => {
		if (requestedAnim) openRequestedAnim(requestedAnim);
		else if (requestedSpell) state.animLibrary?.spellWord(requestedSpell);
	};

	if (requestedAvatar) {
		loadAvatarById(requestedAvatar).catch((err) => {
			setStatus(`${err.message} Showing the mannequin instead.`, 'error');
			switchToMannequin();
		}).then(() => openRequestedExtras());
	} else if (requestedSrc) {
		// /viewer funnel: animate a freshly generated GLB by URL. A model with no
		// humanoid skeleton can't be posed; say so and fall back to the mannequin.
		// (Mannequin first: switchToMannequin writes its own status line, and the
		// error explaining WHY has to be the one left visible.)
		loadAvatarFromUrl(requestedSrc, { name: _params.get('title') || 'Imported model' })
			.catch((err) => {
				switchToMannequin();
				setStatus(`${err?.message || 'Could not load that model.'} Showing the mannequin instead.`, 'error');
			})
			.then(() => openRequestedExtras());
	} else if (requestedAnim || requestedSpell) {
		// Deep-linked to an animation with no avatar chosen (the /animations
		// gallery "Open in Studio" path). Presets need a rigged figure to play on,
		// so auto-load one of the built-in avatars — varied by clip so the gallery
		// doesn't feel like it only ships one character — then play the clip live.
		const model = pickDeepLinkAvatar(requestedAnim || requestedSpell);
		setStatus(`Loading ${model.name} to preview this animation…`);
		loadAvatarFromUrl(model.url, { name: model.name })
			.catch((err) => {
				log.warn('[pose] deep-link avatar load failed:', err?.message);
				switchToMannequin();
			})
			.then(() => openRequestedExtras());
	} else if (rawSrc) {
		// A ?src= deep-link that failed the trusted-host gate: say why instead of
		// silently opening an empty studio.
		setStatus('That model link is not from a trusted host. Pick an avatar instead.', 'error');
	} else if (pendingDraft) {
		setStatus('Ready. Click a body part to pose, or load an avatar.');
		showRecoveryPrompt(pendingDraft);
	} else {
		setStatus('Ready. Click a body part to pose, or load an avatar.');
	}
}

// Built-in rigged avatars that retarget the full canonical clip library cleanly
// (verified 52/52 canonical bones). Used when a visitor deep-links straight to
// an animation without picking an avatar — the clip needs a body to play on.
const DEEP_LINK_AVATARS = [
	{ url: '/avatars/cz.glb', name: 'CZ' },
	{ url: '/avatars/michelle.glb', name: 'Michelle' },
	{ url: '/avatars/realistic-female.glb', name: 'Ada' },
	{ url: '/avatars/realistic-male.glb', name: 'Max' },
	{ url: '/avatars/xbot.glb', name: 'X Bot' },
	{ url: '/avatars/selfie-girl.glb', name: 'Nova' },
];

// Deterministic pick from the clip id, so the same animation always previews on
// the same avatar (a shared link looks identical for everyone) while different
// animations spread across the roster.
function pickDeepLinkAvatar(animId) {
	let hash = 0;
	for (let i = 0; i < animId.length; i++) hash = (hash * 31 + animId.charCodeAt(i)) >>> 0;
	return DEEP_LINK_AVATARS[hash % DEEP_LINK_AVATARS.length];
}

document.addEventListener('DOMContentLoaded', boot);