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.

87.9 KB
Raw Blame
// AR Studio (/ar/studio) — a live multi-model AR scene through your camera.
//
// The gap this closes: every AR surface before it was single-model and one-way.
// /ar generates a model THEN hands off to the native viewer (one model, exits
// the page); /irl walks ONE owned avatar; the WebXR session anchors exactly one
// group. The studio is the standalone surface where all three asks land:
//
//   · place ANY number of models/avatars into one live camera view,
//   · pull in ANY model — your forge creations, the community feed, a pasted
//     GLB URL, or a ?src= deep link,
//   · forge a brand-new model from a prompt WITHOUT leaving the camera — the
//     generation runs behind the live view and the result drops into the room.
//
// Rendering modes, best-first (same ladder as /irl, minus GPS/pins machinery):
//   · WebXR immersive-ar (Android Chrome): hit-test reticle, one XRAnchor per
//     placed model (src/ar/multi-place.js), dom-overlay HUD stays usable.
//   · getUserMedia passthrough (iOS Safari + everywhere else with a camera):
//     transparent WebGL over the live feed, gyro world-lock look, tap/drag/
//     pinch/twist gestures on the floor plane.
//   · plain 3D preview (no camera / desktop): grid floor, drag-look — the same
//     scene, still fully arrangeable, plus a QR handoff to a phone.
//
// Scene state (model sources + floor transforms) persists in localStorage and
// round-trips through ?src= links, so a desktop arrangement reopens on a phone.

import {
	AnimationMixer, Box3, CanvasTexture, Color, DirectionalLight, Fog, GridHelper, Group,
	HemisphereLight, Mesh, MeshBasicMaterial, PerspectiveCamera, PlaneGeometry,
	Raycaster, RingGeometry, Scene, Vector2, Vector3, WebGLRenderer,
} from 'three';
import { clone as cloneSkinnedScene } from 'three/addons/utils/SkeletonUtils.js';
import { applyCinematicDefaults, detectQualityTier, loadEnvironment } from './shared/cinematic-render.js';

import { EstimatedLighting } from '../packages/ar-studio/src/studio/estimated-lighting.js';
import {
	generateRoomCode, localToShared, normalizeRoomCode, roomKeyForCode,
	roomShareUrl, sharedToLocal,
} from '../packages/ar-studio/src/studio/coords.js';
import { StudioNet } from './ar/studio-net.js';
import { MultiPlaceSession } from '../packages/ar-studio/src/studio/multi-place.js';
import { canUseQuickLook, openQuickLook } from './ar/quick-look.js';
import { canUseSceneViewer, openSceneViewer } from './ar/scene-viewer.js';
import { glbBlobToUsdzBlob } from './usdz-pipeline.js';
import { forgeStageNarration } from './shared/forge-frames.js';
import { cardTitleFromPrompt } from './model-lib.js';
import {
	createPinchState, pinchEnd, pinchMove, pinchStart, touchDist,
	PINCH_SCALE_MAX, PINCH_SCALE_MIN,
} from '../packages/ar-studio/src/studio/pinch.js';
import {
	deserializeScene, fitTransform, MAX_PLACEMENTS, normalizeGlbUrl,
	parseSrcParams, roomLightFromPixels, sceneFromHashParam, serializeScene,
	SPAWN_DISTANCE_M, spawnPointInFront, studioSceneUrl, studioShareUrl,
	touchAngle, twistDelta,
} from '../packages/ar-studio/src/studio/scene-math.js';
import { renderQRToSVG } from './erc8004/qr.js';
import { deriveVerticalFovDeg, DEFAULT_DIAG_FOV_DEG } from './irl/camera-fov.js';
import { createLoadQueue, loadGLTF } from './irl/load-queue.js';
import { mountPinIdle } from './irl/pin-idle.js';
import { clampPitch, isFiniteReading, resolveLockYaw, screenPitchDeg } from './irl/sensor-fusion.js';
import { captureComposite, shareOrDownload } from './irl/share-frame.js';
import { createLogger } from './shared/log.js';

const log = createLogger('ar-studio');

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

/** Canonical studio page; the base every share link and QR is built against. */
const STUDIO_BASE_URL = 'https://three.ws/ar/studio';
const SCENE_KEY = 'twx_ar_studio_scene_v1';
// Shared with /ar (AR Forge) on purpose: a model forged on either page shows up
// in the other's recents — one history, two doors.
const RECENT_KEY = 'twx_ar_forge_recent';
const POLL_MS = 3000;
const MAX_POLL_MS = 300000;
const EYE_HEIGHT_M = 1.55;
const PITCH_MIN = -1.25;
const PITCH_MAX = 1.35;

// Same anonymous forge identity as /forge and /creations — scopes the "Yours"
// tray tab and attributes in-studio generations to this browser's gallery.
const CLIENT_ID = (() => {
	const KEY = 'forge:cid';
	try {
		let id = localStorage.getItem(KEY);
		if (!id) {
			id = crypto?.randomUUID?.() || `c-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
			localStorage.setItem(KEY, id);
		}
		return id;
	} catch {
		return `c-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
	}
})();

// ── DOM ───────────────────────────────────────────────────────────────────────
const videoEl = $('ars-video');
const canvas = $('ars-canvas');
const hud = $('ars-hud');
const statusEl = $('ars-status');
const countEl = $('ars-count');
const cameraBtn = $('ars-camera-btn');
const xrBtn = $('ars-xr-btn');
const addBtn = $('ars-add-btn');
const clearBtn = $('ars-clear-btn');
const photoBtn = $('ars-photo-btn');
const qrBtn = $('ars-qr-btn');
const forgeForm = $('ars-forge-form');
const forgeInput = $('ars-forge-input');
const forgeGo = $('ars-forge-go');
const forgeChip = $('ars-forge-chip');
const selbar = $('ars-selbar');
const selName = $('ars-sel-name');
const tray = $('ars-tray');
const trayBody = $('ars-tray-body');
const trayClose = $('ars-tray-close');
const emptyEl = $('ars-empty');
const qrModal = $('ars-qr-modal');
const roomBtn = $('ars-room-btn');
const roomModal = $('ars-room-modal');

if (!canvas || !hud) {
	throw new Error('AR Studio: page skeleton missing');
}

// ── Renderer / scene ─────────────────────────────────────────────────────────
const renderer = new WebGLRenderer({
	canvas, alpha: true, antialias: true, preserveDrawingBuffer: true,
});
renderer.setSize(window.innerWidth, window.innerHeight);
renderer.setClearColor(0x000000, 0);
// Filmic tone mapping + correct sRGB output + soft shadows: the shared bar
// every viewer on the platform now matches (src/shared/cinematic-render.js).
const qualityTier = detectQualityTier();
applyCinematicDefaults(renderer, { tier: qualityTier });

const scene = new Scene();
const camera = new PerspectiveCamera(58, window.innerWidth / window.innerHeight, 0.02, 200);
camera.position.set(0, EYE_HEIGHT_M, 0);

// Real HDRI IBL (studio preset) so forge materials (metal, glass, emissive)
// read correctly against a real room; falls back to the procedural
// RoomEnvironment on fetch failure or mobile tier.
loadEnvironment(renderer, scene, qualityTier === 'mobile' ? null : 'studio').catch((err) => {
	log.warn('environment map failed', err);
});

const HEMI_BASE = 1.0;
const SUN_BASE = 1.15;
const hemi = new HemisphereLight(0xffffff, 0x444455, HEMI_BASE);
scene.add(hemi);
const sun = new DirectionalLight(0xffffff, SUN_BASE);
sun.position.set(2.5, 6, 3);
scene.add(sun);

// Preview-mode floor: a calm grid that hides the moment the camera feed becomes
// the ground truth. The ray plane is the invisible tap/drag target either way.
const grid = new GridHelper(24, 48, 0x3a3f52, 0x23273a);
grid.position.y = 0.001;
grid.material.transparent = true;
grid.material.opacity = 0.75;
// Distance fog fades the far lines out instead of letting a flat grid viewed at
// a shallow angle collapse into a moire band across the horizon. It starts well
// beyond any placement, so it never touches a model, and it is removed the
// moment the real room becomes the backdrop.
const previewFog = new Fog(0x06070a, 5, 17);
scene.fog = previewFog;
scene.add(grid);
const rayPlane = new Mesh(
	new PlaneGeometry(80, 80),
	new MeshBasicMaterial({ visible: false, side: 2 }),
);
rayPlane.rotation.x = -Math.PI / 2;
scene.add(rayPlane);

// Selection ring — one reusable marker parked under the selected model.
const selRing = new Mesh(
	new RingGeometry(0.3, 0.34, 48).rotateX(-Math.PI / 2),
	new MeshBasicMaterial({ color: 0x8b7cf8, transparent: true, opacity: 0.85, depthTest: false }),
);
selRing.renderOrder = 998;
selRing.visible = false;
scene.add(selRing);

// Shared radial-gradient contact-shadow texture for fallback-mode placements.
const shadowTex = (() => {
	try {
		const size = 128;
		const cnv = document.createElement('canvas');
		cnv.width = cnv.height = size;
		const ctx = cnv.getContext('2d');
		const g = ctx.createRadialGradient(size / 2, size / 2, 0, size / 2, size / 2, size / 2);
		g.addColorStop(0, 'rgba(0,0,0,0.40)');
		g.addColorStop(0.55, 'rgba(0,0,0,0.18)');
		g.addColorStop(1, 'rgba(0,0,0,0)');
		ctx.fillStyle = g;
		ctx.fillRect(0, 0, size, size);
		return new CanvasTexture(cnv);
	} catch {
		return null;
	}
})();

const reducedMotion = (() => {
	try {
		return !!window.matchMedia?.('(prefers-reduced-motion: reduce)').matches;
	} catch {
		return false;
	}
})();

// ── Camera look (yaw/pitch; gyro on mobile, drag anywhere) ───────────────────
let cameraYaw = 0;
let cameraPitch = -0.24;
// Once the viewer aims the camera themselves (drag-look, gyro, passthrough),
// their aim is the truth and the studio stops reframing for them.
let userLooked = false;

// Desktop and phone preview have no room to look at, so a model dropped on the
// floor lands below the eyeline and reads as "nothing happened". Aim the view at
// what is actually in the scene.
function framePreview() {
	if (arActive || xrSession || userLooked || !placements.length) return;
	let sx = 0;
	let sz = 0;
	let sh = 0;
	for (const p of placements) {
		sx += p.group.position.x;
		sz += p.group.position.z;
		sh += (p.height || 0.4) * (p.group.userData._targetScale ?? 1);
	}
	const n = placements.length;
	const cx = sx / n;
	const cz = sz / n;
	const centre = (sh / n) * 0.5;
	const dist = Math.hypot(cx - camera.position.x, cz - camera.position.z);
	if (!(dist > 0.05)) return;
	cameraYaw = Math.atan2(cx - camera.position.x, -(cz - camera.position.z));
	cameraPitch = clampPitch(-Math.atan2(camera.position.y - centre, dist), PITCH_MIN, PITCH_MAX);
}

function applyCameraLook() {
	camera.rotation.set(0, 0, 0);
	camera.rotateY(cameraYaw);
	camera.rotateX(cameraPitch);
}
applyCameraLook();

// ── State ─────────────────────────────────────────────────────────────────────
/**
 * @typedef {object} Placement
 * @property {string} id
 * @property {string} src
 * @property {string} title
 * @property {Group}  group     Outer group at the floor point (y=0).
 * @property {Mesh|null} shadow
 * @property {AnimationMixer|null} mixer
 * @property {number} yaw
 * @property {number} baseRadius  Footprint radius for the selection ring.
 * @property {number} spawnT      Spawn scale-in progress 0→1.
 */
/** @type {Placement[]} */
const placements = [];
/** @type {Placement|null} */
let selected = null;
let arActive = false;
let mediaStream = null;
let arTransitioning = false;
let xrSession = null;
let estimatedLight = null;
let arTrackW = 0;
let arTrackH = 0;
let statusTimer = null;
let undoItems = null;

// ── Shared-room networking (purely additive; null = single-player) ────────────
/** @type {import('./ar/studio-net.js').StudioNet|null} */
let net = null;
let roomCode = '';
/** netId → placement, for reconciling remote models against local ones. */
const netModelsById = new Map();
let roomPresence = { count: 1, names: [] };

// A placement I control: single-player models (no ownerId) and my own room
// models. Others' room models are visible + live but not editable by me (the
// server owner-gates edits too — this is the local UX guard).
function isMine(p) {
	return !p.ownerId || p.ownerId === CLIENT_ID;
}

// True once a freshly-joined room's initial model burst has settled, so per-model
// "someone added…" cues fire only for genuinely new activity, not the join sync.
let roomSyncSettled = false;

// A soft two-note chime for room arrivals — a small "someone's here" cue that
// makes collaboration feel alive. WebAudio only, unlocked inside the create/join
// user gesture; silent (never throws) where audio is blocked or reduced-motion.
let _audioCtx = null;
function unlockAudio() {
	try {
		if (!_audioCtx) _audioCtx = new (window.AudioContext || window.webkitAudioContext)();
		if (_audioCtx.state === 'suspended') _audioCtx.resume();
	} catch { _audioCtx = null; }
}
function chime() {
	if (reducedMotion || !_audioCtx) return;
	try {
		const now = _audioCtx.currentTime;
		for (const [i, freq] of [587.33, 880].entries()) { // D5 → A5
			const osc = _audioCtx.createOscillator();
			const gain = _audioCtx.createGain();
			osc.type = 'sine';
			osc.frequency.value = freq;
			const t = now + i * 0.11;
			gain.gain.setValueAtTime(0, t);
			gain.gain.linearRampToValueAtTime(0.08, t + 0.02);
			gain.gain.exponentialRampToValueAtTime(0.0001, t + 0.28);
			osc.connect(gain).connect(_audioCtx.destination);
			osc.start(t);
			osc.stop(t + 0.3);
		}
	} catch { /* audio is a bonus, never a failure path */ }
}

// Template cache: one load per GLB source no matter how many copies are placed.
/** @type {Map<string, Promise<{ gltf: any, skinned: boolean, fit: { scale: number, yOffset: number }, radius: number }>>} */
const templates = new Map();
// Resolved templates, synchronously readable — an XR `select` handler can't
// await, so it places only sources that have already finished loading.
const tplReady = new Map();
const loadQueue = createLoadQueue({
	run: (src) => loadGLTF(src),
	maxActive: 3,
});

// ── Status line ───────────────────────────────────────────────────────────────
function setStatus(msg, { warn = false, sticky = false, actionLabel = '', onAction = null } = {}) {
	if (!statusEl) return;
	clearTimeout(statusTimer);
	statusEl.innerHTML = '';
	if (!msg) {
		statusEl.hidden = true;
		return;
	}
	statusEl.hidden = false;
	statusEl.classList.toggle('is-warn', warn);
	const span = document.createElement('span');
	span.textContent = msg;
	statusEl.appendChild(span);
	if (actionLabel && onAction) {
		const btn = document.createElement('button');
		btn.type = 'button';
		btn.className = 'ars-status-action';
		btn.textContent = actionLabel;
		btn.addEventListener('click', () => {
			setStatus(null);
			onAction();
		});
		statusEl.appendChild(btn);
	}
	if (!sticky) statusTimer = setTimeout(() => { statusEl.hidden = true; }, 5000);
}

function updateCount() {
	if (!countEl) return;
	const n = placements.length;
	updatePresencePill(); // owns the count-pill text (folds in room presence)
	if (clearBtn) clearBtn.hidden = n === 0;
	if (emptyEl) emptyEl.hidden = n > 0;
	if (photoBtn) photoBtn.disabled = n === 0;
}

// A placement's LOGICAL scale — the size the user chose, independent of the
// spawn-in animation. While a model is easing in (spawnT < 1) group.scale.x is
// a fraction of the target; reading it then would persist ~0 and clamp the
// model to SCALE_MIN on the next load. Post-spawn, group.scale.x IS the truth
// (pinch writes it directly), so it wins.
function logicalScale(p) {
	if (p.spawnT < 1) return p.group.userData._targetScale ?? 1;
	return p.group.scale.x;
}

// ── Scene persistence ─────────────────────────────────────────────────────────
// Only MY models persist to localStorage — never another participant's room
// models, which would otherwise reappear as mine on a later solo visit.
function saveScene() {
	try {
		localStorage.setItem(SCENE_KEY, serializeScene(placements.filter(isMine).map((p) => ({
			src: p.src,
			title: p.title,
			x: p.group.position.x,
			z: p.group.position.z,
			yaw: p.yaw,
			scale: logicalScale(p),
		}))));
	} catch {}
}

// ── Selection ─────────────────────────────────────────────────────────────────
function select(p) {
	selected = p;
	if (!selbar) return;
	if (!p) {
		selbar.hidden = true;
		selRing.visible = false;
		return;
	}
	selbar.hidden = false;
	if (selName) selName.textContent = p.title || 'Model';
	selRing.visible = true;
	positionSelRing();
}

function positionSelRing() {
	if (!selected) return;
	const p = selected;
	selRing.position.set(p.group.position.x, p.group.position.y + 0.006, p.group.position.z);
	const r = Math.max(0.24, p.baseRadius * p.group.scale.x * 1.15);
	selRing.scale.setScalar(r / 0.34);
}

// ── Model loading + placement ─────────────────────────────────────────────────
function loadTemplate(src) {
	let t = templates.get(src);
	if (!t) {
		t = loadQueue.request(src).then((gltf) => {
			let skinned = false;
			gltf.scene.traverse((o) => { if (o.isSkinnedMesh) skinned = true; });
			const box = new Box3().setFromObject(gltf.scene);
			const fit = fitTransform(
				{ min: { x: box.min.x, y: box.min.y, z: box.min.z }, max: { x: box.max.x, y: box.max.y, z: box.max.z } },
				{ skinned },
			);
			const radius = Math.max(
				(box.max.x - box.min.x) * fit.scale,
				(box.max.z - box.min.z) * fit.scale,
			) / 2;
			const height = (box.max.y - box.min.y) * fit.scale;
			return {
				gltf, skinned, fit,
				radius: Number.isFinite(radius) ? radius : 0.3,
				height: Number.isFinite(height) ? height : 0.75,
			};
		});
		templates.set(src, t);
		t.then((tpl) => tplReady.set(src, tpl))
			.catch(() => templates.delete(src)); // a failed load is retryable
	}
	return t;
}

// Instantiate a template into a floor-ready group. Cloned per placement so ten
// copies of one crate are ten independent models; SkeletonUtils handles skinned
// avatars (plain .clone() breaks bone bindings).
function instantiate(tpl, src) {
	const inner = cloneSkinnedScene(tpl.gltf.scene);
	inner.scale.setScalar(tpl.fit.scale);
	inner.position.y = tpl.fit.yOffset;
	const group = new Group();
	group.add(inner);
	let mixer = null;
	if (tpl.gltf.animations?.length) {
		mixer = new AnimationMixer(inner);
		mixer.clipAction(tpl.gltf.animations[0]).play();
	}
	// A humanoid with no baked clips gets the universal idle retargeted onto its
	// rig (same pipeline as /irl pins) — never a bind-pose T-pose statue. Async
	// and best-effort: props and undriveable rigs resolve null and stay static.
	let idlePromise = null;
	if (!mixer && tpl.skinned) {
		idlePromise = mountPinIdle(inner, { avatarUrl: src }).catch(() => null);
	}
	return { group, mixer, idlePromise };
}

function makeShadow(radius) {
	if (!shadowTex) return null;
	const d = Math.max(0.4, radius * 2.4);
	const mesh = new Mesh(
		new PlaneGeometry(d, d).rotateX(-Math.PI / 2),
		new MeshBasicMaterial({ map: shadowTex, transparent: true, opacity: 0.85, depthWrite: false }),
	);
	mesh.renderOrder = 1;
	return mesh;
}

// Spread same-spot spawns into a small ring so "add, add, add" reads as a
// lineup instead of a z-fighting pile.
function nudgeSpawn(pt) {
	let { x, z } = pt;
	for (let attempt = 0; attempt < 8; attempt++) {
		const clash = placements.some((p) =>
			Math.hypot(p.group.position.x - x, p.group.position.z - z) < 0.45);
		if (!clash) break;
		const a = attempt * 2.399963; // golden angle
		x = pt.x + Math.cos(a) * 0.55 * (1 + attempt * 0.18);
		z = pt.z + Math.sin(a) * 0.55 * (1 + attempt * 0.18);
	}
	return { x, z };
}

/**
 * Add a model to the scene. Loads (or reuses) the template, drops it on the
 * floor in front of the camera (or at the given transform on restore), selects
 * it, and persists. Resolves with the placement or null on failure.
 */
async function addModel({ src, title = '' }, {
	x = null, z = null, yaw = null, scale = null, announce = true, persist = true,
	remote = false, netId = null, ownerId = null,
} = {}) {
	const url = normalizeGlbUrl(src);
	if (!url) {
		setStatus('That link is not a loadable https GLB.', { warn: true });
		return null;
	}
	if (placements.length >= MAX_PLACEMENTS) {
		setStatus(`Scene is full (${MAX_PLACEMENTS} models). Remove one to add more.`, { warn: true });
		return null;
	}
	if (announce) setStatus(`Loading ${title || 'model'}…`, { sticky: true });
	let tpl;
	try {
		tpl = await loadTemplate(url);
	} catch (err) {
		log.warn('model load failed', url, err);
		setStatus(`Couldn't load ${title || 'that model'} — the file may be gone.`, {
			warn: true, actionLabel: 'Retry', onAction: () => addModel({ src: url, title }),
		});
		return null;
	}

	const { group, mixer, idlePromise } = instantiate(tpl, url);
	let px = x, pz = z;
	if (px === null || pz === null) {
		// Tall models (avatars, statues) land further back so they don't fill
		// the frame the moment they appear.
		const dist = Math.max(SPAWN_DISTANCE_M, (tpl.height || 0) * 1.15);
		const fwd = camera.getWorldDirection(new Vector3());
		const spot = nudgeSpawn(spawnPointInFront(camera.position, fwd, dist));
		px = spot.x;
		pz = spot.z;
	}
	group.position.set(px, 0, pz);
	const yawV = yaw ?? Math.atan2(camera.position.x - px, camera.position.z - pz);
	group.rotation.y = yawV;
	if (scale) group.scale.setScalar(Math.min(PINCH_SCALE_MAX, Math.max(PINCH_SCALE_MIN, scale)));
	scene.add(group);

	const shadow = makeShadow(tpl.radius);
	if (shadow) {
		shadow.position.set(px, 0.004, pz);
		shadow.scale.setScalar(group.scale.x);
		shadow.visible = !xrSession; // XR session draws its own anchored shadows
		scene.add(shadow);
	}

	const placement = {
		id: `p-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 7)}`,
		src: url,
		title: String(title || '').slice(0, 120),
		group,
		shadow,
		mixer,
		idle: null,
		yaw: yawV,
		baseRadius: tpl.radius,
		spawnT: reducedMotion ? 1 : 0,
		height: tpl.height || 0,
		// Room fields: netId is the shared-scene id (null until broadcast); ownerId
		// null = single-player / mine. Set for remote models so isMine() gates edits.
		netId: netId || null,
		ownerId: remote ? ownerId : null,
		remote,
		_lastNetSend: 0,
	};
	idlePromise?.then((mgr) => {
		if (!mgr) return;
		// Removed before the idle clip arrived → release the manager, not leak it.
		if (placements.includes(placement)) placement.idle = mgr;
		else mgr.detach();
	});
	group.userData._targetScale = group.scale.x;
	if (!reducedMotion) group.scale.setScalar(0.001);
	placements.push(placement);
	if (placement.netId) netModelsById.set(placement.netId, placement);
	if (!remote) armedSrc = { src: url, title: placement.title };
	updateCount();
	if (!remote) select(placement);
	if (!remote) framePreview();
	if (persist) saveScene();

	// Broadcast a locally-added model to the shared room (once): mint a wire id,
	// tag the placement with it, and send its shared-frame transform. Remote adds
	// (reconciled from the room) never re-broadcast.
	if (!remote && net && net.status === 'online') {
		const wireId = `m${Date.now().toString(36)}${Math.random().toString(36).slice(2, 6)}`.slice(0, 40);
		placement.netId = wireId;
		placement.ownerId = CLIENT_ID;
		netModelsById.set(wireId, placement);
		net.spawn(placementWire(placement, wireId));
	}

	if (announce) {
		setStatus(remote
			? `${title || 'A model'} was added by someone in the room.`
			: 'Placed. Drag to move, pinch to resize, twist to rotate.');
	}
	return placement;
}

// A placement's transform in the shared logical frame (for the wire).
function placementShared(p) {
	return localToShared({
		x: p.group.position.x,
		z: p.group.position.z,
		yaw: p.yaw,
		scale: logicalScale(p),
		height: p.height || 0,
	});
}

// The full spawn payload for the wire: source + title + shared-frame transform.
function placementWire(p, wireId) {
	return { id: wireId, src: p.src, title: p.title, ...placementShared(p) };
}

// Broadcast a transform change for one of MY room models, throttled to ~12 Hz so
// a drag doesn't flood the socket. No-op single-player or for others' models.
function netBroadcastTransform(p) {
	if (!net || net.status !== 'online' || !p.netId || !isMine(p)) return;
	const now = Date.now();
	if (now - (p._lastNetSend || 0) < 80) return;
	p._lastNetSend = now;
	const s = placementShared(p);
	net.update(p.netId, { relEast: s.relEast, relNorth: s.relNorth, yawDeg: s.yawDeg, scale: s.scale });
}

// Apply a shared-frame transform from the room to a placement's local group.
function applySharedTransform(p, m) {
	const l = sharedToLocal(m);
	p.group.position.set(l.x, 0, l.z);
	p.yaw = l.yaw;
	p.group.rotation.y = l.yaw;
	p.group.scale.setScalar(l.scale);
	p.group.userData._targetScale = l.scale;
	p.spawnT = 1; // an update is not a spawn — no scale-in pop
	if (p.shadow) {
		p.shadow.position.set(l.x, 0.004, l.z);
		p.shadow.scale.setScalar(l.scale);
	}
	if (selected === p) positionSelRing();
}

// Reconcile the full shared model list against local placements: add models that
// appeared (others' or my own from a prior session), drop REMOTE ones that left,
// and refresh others' transforms. My own live models are authored locally — never
// overwritten by their own echo.
function reconcileRemoteModels(models) {
	const serverIds = new Set(models.map((m) => m.id));
	// Remove remote placements that vanished from the room (owner deleted / reaped).
	for (const p of [...placements]) {
		if (p.remote && p.netId && !serverIds.has(p.netId)) {
			removePlacement(p, { persist: false, broadcast: false });
		}
	}
	let freshFromOthers = 0;
	for (const m of models) {
		const existing = netModelsById.get(m.id);
		if (existing) {
			if (!isMine(existing)) applySharedTransform(existing, m);
			continue;
		}
		// New to me: reconcile it in. Mark mine when the server says I own it (a
		// rejoin) so I keep control; otherwise it's someone else's, view-only.
		const local = sharedToLocal(m);
		const mine = !!m.mine || m.ownerId === CLIENT_ID;
		if (!mine) freshFromOthers++;
		addModel({ src: m.src, title: m.title }, {
			x: local.x, z: local.z, yaw: local.yaw, scale: local.scale,
			remote: true, netId: m.id, ownerId: mine ? CLIENT_ID : m.ownerId,
			announce: false, persist: false,
		});
	}
	updateCount();
	// After the join burst settles, a new model from someone else is live activity
	// worth surfacing — but never during the initial sync (that would spam N toasts).
	if (roomSyncSettled && freshFromOthers > 0) {
		setStatus(freshFromOthers === 1 ? 'Someone added a model to the room.' : `${freshFromOthers} models were added to the room.`);
	}
	roomSyncSettled = true;
}

// A single model changed (per-field delta) or was removed. Refresh others' live;
// ignore echoes of my own.
function applyRemoteModelChange(m) {
	const p = netModelsById.get(m.id);
	if (!p) return;
	if (m.removed) {
		if (p.remote) removePlacement(p, { persist: false, broadcast: false });
		return;
	}
	if (!isMine(p)) applySharedTransform(p, m);
}

// ── Room lifecycle ────────────────────────────────────────────────────────────
function updatePresencePill() {
	if (!countEl) return;
	// The count pill doubles as the presence indicator when in a room.
	const n = placements.length;
	if (net && net.status === 'online' && roomPresence.count > 1) {
		countEl.textContent = `${roomPresence.count} here · ${n} ${n === 1 ? 'model' : 'models'}`;
		countEl.hidden = false;
	} else {
		countEl.textContent = n === 1 ? '1 model' : `${n} models`;
		countEl.hidden = n === 0;
	}
}

function wireNet(n) {
	n.on('status', ({ status }) => {
		if (status === 'online') {
			setStatus(`Shared room ${roomCode} is live — edits sync to everyone here.`);
			document.body.classList.add('is-room');
		} else if (status === 'connecting') {
			setStatus(`Joining room ${roomCode}…`, { sticky: true });
		} else if (status === 'unavailable' || status === 'failed') {
			setStatus('Shared rooms are offline right now — you can still build solo.', { warn: true });
			leaveRoom({ silent: true });
		} else if (status === 'offline') {
			setStatus('Reconnecting to the room…', { sticky: true });
		}
		updateRoomButton();
	});
	n.on('models', (models) => reconcileRemoteModels(models));
	n.on('model', (m) => applyRemoteModelChange(m));
	n.on('presence', (p) => {
		const prev = roomPresence.count;
		roomPresence = p;
		updatePresencePill();
		if (roomModal && !roomModal.hidden) renderRoomModal();
		// Ambient life: announce a real arrival/departure (not the initial join, and
		// not our own presence appearing). Makes a shared room feel inhabited.
		if (prev > 0 && p.count > prev) {
			setStatus(p.count === 2 ? 'Someone joined — you’re building together now.' : 'Someone else joined the room.');
			chime();
		} else if (prev > 1 && p.count < prev && p.count >= 1) {
			setStatus(p.count === 1 ? 'You’re on your own in the room now.' : 'Someone left the room.');
		}
	});
	n.on('reject', (msg) => {
		const why = msg?.reason === 'room_full' ? 'the room is full'
			: msg?.reason === 'owner_full' ? 'you have the max models in this room'
			: 'the room declined it';
		setStatus(`Couldn't share that model — ${why}.`, { warn: true });
	});
}

// Push every model I ALREADY have into a freshly joined room, so a solo scene
// becomes the shared starting point instead of vanishing.
function seedRoomWithLocalScene() {
	if (!net || net.status !== 'online') return;
	for (const p of placements) {
		if (p.netId) continue; // already shared
		const wireId = `m${Date.now().toString(36)}${Math.random().toString(36).slice(2, 6)}`.slice(0, 40);
		p.netId = wireId;
		p.ownerId = CLIENT_ID;
		p.remote = false;
		netModelsById.set(wireId, p);
		net.spawn(placementWire(p, wireId));
	}
}

let _roomHeartbeat = null;

// seed=true pushes my current scene into the room as its starting point — right
// for CREATE (I'm the first one there). JOIN never seeds: entering a room means
// entering ITS shared scene, so my solo models stay local (private) and can't
// duplicate the server's authoritative copies on a refresh-rejoin.
async function joinRoom(code, { seed = false } = {}) {
	const norm = normalizeRoomCode(code);
	if (!norm) {
		setStatus('That room code looks off — check the 6 characters and try again.', { warn: true });
		return;
	}
	leaveRoom({ silent: true });
	roomSyncSettled = false; // the join's model burst must not fire "added" cues
	roomCode = norm;
	net = new StudioNet({
		roomKey: roomKeyForCode(norm),
		clientId: CLIENT_ID,
		name: '',
	});
	wireNet(net);
	const joining = net;
	await joining.connect();
	// A failed connect fires status 'failed' synchronously, and the handler above
	// calls leaveRoom() which nulls `net`, so read through the local handle and
	// re-check identity rather than dereferencing a module field that may be gone.
	if (net === joining && joining.status === 'online') {
		if (seed) seedRoomWithLocalScene();
		_roomHeartbeat = setInterval(() => net?.heartbeat(), 15000);
		try {
			const url = new URL(location.href);
			url.searchParams.set('room', norm);
			history.replaceState(null, '', url);
		} catch {}
	}
	updateRoomButton();
}

function createRoom() {
	// Creating a room shares my current scene as its starting point. Returning the
	// promise is load-bearing: the caller awaits it before rendering the live panel
	// and copying the invite link, and dropping it here made both run against a
	// still-connecting room.
	return joinRoom(generateRoomCode(), { seed: true });
}

function leaveRoom({ silent = false } = {}) {
	if (_roomHeartbeat) { clearInterval(_roomHeartbeat); _roomHeartbeat = null; }
	if (net) {
		try { net.destroy(); } catch {}
		net = null;
	}
	// Remote models leave with the room; my own stay as a local scene.
	for (const p of [...placements]) {
		if (p.remote && !isMine(p)) removePlacement(p, { persist: false, broadcast: false });
		else { p.netId = null; p.remote = false; }
	}
	netModelsById.clear();
	roomCode = '';
	roomPresence = { count: 1, names: [] };
	document.body.classList.remove('is-room');
	try {
		const url = new URL(location.href);
		url.searchParams.delete('room');
		history.replaceState(null, '', url);
	} catch {}
	updatePresencePill();
	updateRoomButton();
	if (!silent) setStatus('Left the shared room. Your models are still here.');
}

// ── Room modal UI ─────────────────────────────────────────────────────────────
function updateRoomButton() {
	if (!roomBtn) return;
	const live = !!net && (net.status === 'online' || net.status === 'connecting');
	roomBtn.classList.toggle('is-active', live);
	// Two labels rather than one rewritten string. The idle one carries the page's
	// data-i18n binding, so writing the room code straight onto the button (what
	// this used to do) replaced the visitor's translated "Share live" with English
	// the first time the room state changed. Swapping which span is hidden leaves
	// the translated label untouched.
	const idleLabel = $('ars-room-label');
	const codeLabel = $('ars-room-code-label');
	if (idleLabel) idleLabel.hidden = live;
	if (codeLabel) {
		codeLabel.hidden = !live;
		codeLabel.textContent = live ? `👥 ${roomCode || 'Room'}` : '';
	}
	// Keep the live modal panel in sync if it's open.
	if (roomModal && !roomModal.hidden) renderRoomModal();
}

function renderRoomModal() {
	const idle = $('ars-room-idle');
	const liveEl = $('ars-room-live');
	const online = !!net && net.status === 'online';
	if (idle) idle.hidden = online;
	if (liveEl) liveEl.hidden = !online;
	if (online) {
		const codeEl = $('ars-room-code');
		if (codeEl) codeEl.textContent = roomCode;
		const pres = $('ars-room-presence');
		if (pres) {
			pres.textContent = roomPresence.count > 1
				? `${roomPresence.count} people are building here.`
				: "You're the only one here yet — share the code to invite someone.";
		}
		const box = $('ars-room-qr');
		if (box) {
			try {
				box.innerHTML = renderQRToSVG(roomShareUrl(STUDIO_BASE_URL, roomCode), {
					scale: 5, margin: 2, dark: '#0b0b0b', light: '#ffffff',
				});
			} catch { box.textContent = roomShareUrl(STUDIO_BASE_URL, roomCode); }
		}
	}
}

function openRoomModal() {
	if (!roomModal) return;
	roomModal.hidden = false;
	renderRoomModal();
	(net && net.status === 'online' ? $('ars-room-copy') : $('ars-room-create'))?.focus?.();
}

function closeRoomModal() {
	if (!roomModal) return;
	const hadFocus = roomModal.contains(document.activeElement);
	roomModal.hidden = true;
	if (hadFocus) restoreFocus(roomBtn);
}

// Unlock the arrival chime inside a real user gesture (the same tap that opens
// the room flow) so it can play later without an autoplay-policy warning.
roomBtn?.addEventListener('click', () => { unlockAudio(); openRoomModal(); });
$('ars-room-close')?.addEventListener('click', closeRoomModal);
roomModal?.addEventListener('click', (e) => { if (e.target === roomModal) closeRoomModal(); });

$('ars-room-create')?.addEventListener('click', async () => {
	unlockAudio();
	await createRoom();
	renderRoomModal();
	// One-tap invite: put the join link on the clipboard immediately (still inside
	// this click's user activation) so hosting a room is create → paste, not
	// create → find button → copy. Best-effort; the Copy button remains as backup.
	if (net && net.status === 'online' && navigator.clipboard?.writeText) {
		try {
			await navigator.clipboard.writeText(roomShareUrl(`${location.origin}/ar/studio`, roomCode));
			setStatus(`Room ${roomCode} is live — invite link copied. Paste it to a friend.`);
		} catch { /* clipboard blocked — the Copy button below still works */ }
	}
});

$('ars-room-join-form')?.addEventListener('submit', async (e) => {
	e.preventDefault();
	unlockAudio();
	const input = $('ars-room-join-input');
	const code = normalizeRoomCode(input?.value);
	if (!code) {
		setStatus('That room code looks off — check the 6 characters.', { warn: true });
		input?.focus?.();
		return;
	}
	await joinRoom(code);
	renderRoomModal();
});

$('ars-room-copy')?.addEventListener('click', () => {
	const url = roomShareUrl(`${location.origin}/ar/studio`, roomCode);
	const btn = $('ars-room-copy');
	const done = () => {
		if (!btn) return;
		const old = btn.textContent;
		btn.textContent = 'Link copied ✓';
		setTimeout(() => { btn.textContent = old; }, 1600);
	};
	if (navigator.share) {
		navigator.share({ title: 'Build with me in AR Studio', text: `Join my AR Studio room: ${roomCode}`, url }).catch(() => {});
	} else if (navigator.clipboard) {
		navigator.clipboard.writeText(url).then(done).catch(() => window.prompt('Copy this invite link:', url));
	} else {
		window.prompt('Copy this invite link:', url);
	}
});

$('ars-room-leave')?.addEventListener('click', () => {
	leaveRoom();
	renderRoomModal();
});

function removePlacement(p, { persist = true, broadcast = true } = {}) {
	const i = placements.indexOf(p);
	if (i === -1) return;
	placements.splice(i, 1);
	if (p.netId) {
		netModelsById.delete(p.netId);
		// Tell the room, unless this removal CAME from the room (reconcile) or it's
		// not mine to remove (the server would reject it anyway).
		if (broadcast && net && net.status === 'online' && isMine(p)) net.remove(p.netId);
	}
	p.idle?.detach();
	p.idle = null;
	xrSession?.release(p.group);
	scene.remove(p.group);
	if (p.shadow) {
		scene.remove(p.shadow);
		p.shadow.geometry?.dispose();
		p.shadow.material?.dispose();
	}
	// Geometry/materials belong to the shared template — other copies (and
	// future adds of the same source) still use them, so nothing is disposed.
	// SkeletonUtils.clone shares geometry between copies; only the shadow above
	// is per-placement.
	if (selected === p) select(placements[placements.length - 1] ?? null);
	updateCount();
	if (persist) saveScene();
}

// ── Restore + deep links ──────────────────────────────────────────────────────
let armedSrc = null; // { src, title } — what an XR reticle tap places

async function restoreScene({ skipLocal = false } = {}) {
	const params = new URLSearchParams(location.search);
	const linked = parseSrcParams(params);

	// A #s= hash is a FULL shared arrangement (models + transforms) — it opens
	// like a document, replacing the working scene rather than merging into it.
	// skipLocal (arriving via a ?room= link) means the shared ROOM is the source
	// of truth, so we don't also restore the local/hash scene (which would
	// duplicate the server's authoritative copies).
	const sharedScene = skipLocal ? [] : sceneFromHashParam(
		new URLSearchParams(location.hash.replace(/^#/, '')).get('s'),
	);

	let items = sharedScene;
	if (!items.length && !skipLocal) {
		try {
			items = deserializeScene(localStorage.getItem(SCENE_KEY));
		} catch {}
	}

	for (const it of items) {
		await addModel({ src: it.src, title: it.title }, {
			x: it.x, z: it.z, yaw: it.yaw, scale: it.scale, announce: false, persist: false,
		});
	}
	// Deep-linked models land in front of the camera, skipping ones already
	// restored at an arranged spot.
	const have = new Set(placements.map((p) => p.src));
	for (const it of linked) {
		if (have.has(it.src)) continue;
		await addModel(it, { announce: false });
	}
	if (placements.length) {
		select(placements[placements.length - 1]);
		if (sharedScene.length) {
			setStatus('Shared scene loaded, exactly as arranged. Clear to start fresh.');
		} else {
			setStatus(linked.length ? 'Models loaded — tap the camera to see them in your space.' : 'Your scene is back.');
		}
	}
	saveScene();

	const forgePrompt = (params.get('forge') || '').trim();
	if (forgePrompt.length >= 3 && forgeInput) {
		forgeInput.value = forgePrompt;
		startForge(forgePrompt);
	}
}

// ── Camera passthrough ────────────────────────────────────────────────────────
function applyCameraFov() {
	const track = mediaStream?.getVideoTracks?.()[0];
	if (track) {
		const s = track.getSettings?.() ?? {};
		if (Number.isFinite(s.width) && s.width > 0) arTrackW = s.width;
		if (Number.isFinite(s.height) && s.height > 0) arTrackH = s.height;
	}
	if (!arActive || !(arTrackW > 0) || !(arTrackH > 0)) return;
	camera.fov = deriveVerticalFovDeg({
		trackWidth: arTrackW,
		trackHeight: arTrackH,
		viewWidth: window.innerWidth,
		viewHeight: window.innerHeight,
		diagFovDeg: DEFAULT_DIAG_FOV_DEG,
	});
	camera.updateProjectionMatrix();
}

// ── Ambient light matching ────────────────────────────────────────────────────
// Sample the live camera feed's mean luminance every couple of seconds and
// ease the scene lights toward it, so a model placed in a dim bedroom doesn't
// glow like it's under studio lights (and one on a sunny balcony isn't muddy).
let lightTimer = null;
const roomTint = new Color(); // reused scratch — no per-sample allocation
const lightProbe = (() => {
	try {
		const cnv = document.createElement('canvas');
		cnv.width = cnv.height = 16;
		return { cnv, ctx: cnv.getContext('2d', { willReadFrequently: true }) };
	} catch {
		return null;
	}
})();

// Passthrough (iOS / no-WebXR) has no lighting-estimation API, so we read the
// room ourselves: mean brightness AND mean colour of the camera feed. Brightness
// drives light intensity (a dim room dims the model); colour drives a gentle
// white-balance tint (a warm-lamp room warms the model's whites, a daylight room
// cools them) so the model belongs to the room instead of glowing neutral on it.
function sampleCameraLight() {
	if (!arActive || !lightProbe?.ctx || !videoEl?.videoWidth) return;
	let data;
	try {
		lightProbe.ctx.drawImage(videoEl, 0, 0, 16, 16);
		data = lightProbe.ctx.getImageData(0, 0, 16, 16).data;
	} catch {
		return; // frame not readable yet — try again next tick
	}
	// Pure read (tested in studio-scene.test.js); ease the result onto the lights
	// so it adapts over a couple of seconds instead of popping frame to frame.
	const { intensity, tint } = roomLightFromPixels(data);
	hemi.intensity += (intensity * HEMI_BASE - hemi.intensity) * 0.4;
	sun.intensity += (intensity * SUN_BASE - sun.intensity) * 0.4;
	roomTint.setRGB(tint.r, tint.g, tint.b);
	hemi.color.lerp(roomTint, 0.4);
	sun.color.lerp(roomTint, 0.4);
}

function startLightMatching() {
	if (lightTimer || !lightProbe) return;
	lightTimer = setInterval(sampleCameraLight, 2000);
	sampleCameraLight();
}

function stopLightMatching() {
	clearInterval(lightTimer);
	lightTimer = null;
	hemi.intensity = HEMI_BASE;
	sun.intensity = SUN_BASE;
	hemi.color.setHex(0xffffff);
	sun.color.setHex(0xffffff);
}

async function startCamera() {
	if (arTransitioning || arActive || xrSession) return;
	if (!navigator.mediaDevices?.getUserMedia) {
		setStatus('This browser can’t open the camera — the 3D preview still works.', { warn: true });
		return;
	}
	arTransitioning = true;
	try {
		setStatus('Starting camera…', { sticky: true });
		try {
			mediaStream = await navigator.mediaDevices.getUserMedia({
				video: { facingMode: { ideal: 'environment' } },
				audio: false,
			});
		} catch (err) {
			if (err?.name === 'NotAllowedError') {
				setStatus('Camera permission is blocked. Allow it in your browser settings, then try again.', {
					warn: true, sticky: true, actionLabel: 'Try again', onAction: startCamera,
				});
			} else {
				setStatus(`The camera didn’t start (${err?.message ?? err}).`, {
					warn: true, actionLabel: 'Try again', onAction: startCamera,
				});
			}
			return;
		}
		if (videoEl) videoEl.srcObject = mediaStream;
		arActive = true;
		document.body.classList.add('is-ar');
		cameraBtn?.classList.add('is-active');
		cameraBtn?.setAttribute('aria-pressed', 'true');
		grid.visible = false;
		scene.fog = null;
		userLooked = true;
		videoEl?.play?.().catch(() => {});
		applyCameraFov();
		startLightMatching();
		await startGyro();
		setStatus('Camera on — your models are in the room. Look around.');
	} finally {
		arTransitioning = false;
	}
}

function stopCamera() {
	if (mediaStream) {
		mediaStream.getTracks().forEach((t) => { try { t.stop(); } catch {} });
		mediaStream = null;
	}
	if (videoEl) videoEl.srcObject = null;
	arActive = false;
	stopLightMatching();
	document.body.classList.remove('is-ar');
	cameraBtn?.classList.remove('is-active');
	cameraBtn?.setAttribute('aria-pressed', 'false');
	grid.visible = true;
	scene.fog = previewFog;
	userLooked = false;
	camera.fov = 58;
	camera.updateProjectionMatrix();
	gyroBase = null;
	arTrackW = 0;
	arTrackH = 0;
}

cameraBtn?.addEventListener('click', () => {
	if (arTransitioning || xrSession) return;
	if (arActive) {
		stopCamera();
		setStatus('Camera off — preview mode.');
	} else {
		startCamera();
	}
});
if (!navigator.mediaDevices?.getUserMedia && cameraBtn) {
	cameraBtn.disabled = true;
	cameraBtn.setAttribute('aria-disabled', 'true');
}

// ── Gyro look (relative world-lock; no GPS, no compass persistence) ──────────
let gyroBase = null; // { alpha, beta, yaw, pitch }
let lastDevAlpha = 0;
let lastDevBeta = 90;
let lastDevGamma = 0;
let hasAbsoluteEventStream = false;

function currentScreenAngle() {
	try {
		const a = screen.orientation?.angle;
		if (Number.isFinite(a)) return a;
	} catch {}
	return Number(window.orientation) || 0;
}

function onDeviceOrientation(e) {
	if (isFiniteReading(e.alpha, e.beta)) {
		lastDevAlpha = e.alpha;
		lastDevBeta = e.beta;
		if (Number.isFinite(e.gamma)) lastDevGamma = e.gamma;
	}
	if (!arActive || !gyroBase) return;
	const b = screenPitchDeg(lastDevBeta, lastDevGamma, currentScreenAngle());
	const nextYaw = resolveLockYaw({
		useAbsolute: false,
		prevYaw: cameraYaw,
		alpha: lastDevAlpha,
		baseAlpha: gyroBase.alpha,
		baseYaw: gyroBase.yaw,
		compassHeading: null,
	});
	const nextPitch = clampPitch(
		gyroBase.pitch - (b - gyroBase.beta) * (Math.PI / 180),
		PITCH_MIN, PITCH_MAX,
	);
	if (Number.isFinite(nextYaw)) cameraYaw = nextYaw;
	if (Number.isFinite(nextPitch)) cameraPitch = nextPitch;
}

window.addEventListener('deviceorientationabsolute', (e) => {
	hasAbsoluteEventStream = true;
	onDeviceOrientation(e);
}, true);
window.addEventListener('deviceorientation', (e) => {
	if (hasAbsoluteEventStream) return;
	onDeviceOrientation(e);
}, true);

async function startGyro() {
	// iOS 13+ gates DeviceOrientationEvent behind a user-gesture permission; the
	// camera button tap we are inside satisfies it.
	try {
		if (typeof DeviceOrientationEvent !== 'undefined'
			&& typeof DeviceOrientationEvent.requestPermission === 'function') {
			const state = await DeviceOrientationEvent.requestPermission();
			if (state !== 'granted') {
				setStatus('Motion access is off — drag to look around instead.', { warn: true });
				return;
			}
		}
	} catch {
		return; // declined prompt → drag-look still works
	}
	gyroBase = {
		alpha: lastDevAlpha,
		beta: screenPitchDeg(lastDevBeta, lastDevGamma, currentScreenAngle()),
		yaw: cameraYaw,
		pitch: cameraPitch,
	};
}

// ── Pointer gestures (fallback + camera modes; XR has its own) ───────────────
const raycaster = new Raycaster();
const ndc = new Vector2();
let pointerDown = null; // { x, y, placement|null, moved }
const pinch = createPinchState();
let pinchEndedAt = -Infinity;
let twist = null; // { startAngle, baseYaw, placement }

function placementAt(clientX, clientY) {
	ndc.set((clientX / window.innerWidth) * 2 - 1, -(clientY / window.innerHeight) * 2 + 1);
	raycaster.setFromCamera(ndc, camera);
	const groups = placements.map((p) => p.group);
	if (!groups.length) return null;
	const hits = raycaster.intersectObjects(groups, true);
	if (!hits.length) return null;
	let obj = hits[0].object;
	while (obj) {
		const found = placements.find((p) => p.group === obj);
		if (found) return found;
		obj = obj.parent;
	}
	return null;
}

function floorPointAt(clientX, clientY) {
	ndc.set((clientX / window.innerWidth) * 2 - 1, -(clientY / window.innerHeight) * 2 + 1);
	raycaster.setFromCamera(ndc, camera);
	const hits = raycaster.intersectObject(rayPlane);
	return hits.length ? hits[0].point : null;
}

canvas.addEventListener('pointerdown', (e) => {
	if (xrSession) return;
	if (pinch.active || performance.now() - pinchEndedAt < 350) return;
	pointerDown = {
		x: e.clientX, y: e.clientY,
		placement: placementAt(e.clientX, e.clientY),
		lookYaw: cameraYaw, lookPitch: cameraPitch,
		moved: false,
	};
});

canvas.addEventListener('pointermove', (e) => {
	if (!pointerDown || xrSession) return;
	if (pinch.active) return;
	const dx = e.clientX - pointerDown.x;
	const dy = e.clientY - pointerDown.y;
	if (Math.hypot(dx, dy) > 6) pointerDown.moved = true;
	if (!pointerDown.moved) return;

	if (pointerDown.placement && isMine(pointerDown.placement)) {
		// Drag a model along the floor (only models I own in a shared room).
		const pt = floorPointAt(e.clientX, e.clientY);
		if (!pt) return;
		const p = pointerDown.placement;
		p.group.position.x = pt.x;
		p.group.position.z = pt.z;
		if (p.shadow) p.shadow.position.set(pt.x, 0.004, pt.z);
		if (selected === p) positionSelRing();
		netBroadcastTransform(p);
	} else if (!pointerDown.placement && !(arActive && gyroBase)) {
		// Drag-look: only when the gyro isn't already steering the view.
		userLooked = true;
		cameraYaw = pointerDown.lookYaw + dx * 0.0042;
		cameraPitch = clampPitch(pointerDown.lookPitch + dy * 0.0032, PITCH_MIN, PITCH_MAX);
	}
});

function endPointer(e) {
	if (!pointerDown || xrSession) return;
	const wasTap = !pointerDown.moved
		&& Math.hypot(e.clientX - pointerDown.x, e.clientY - pointerDown.y) <= 8
		&& !pinch.active && performance.now() - pinchEndedAt >= 350;
	if (wasTap) {
		select(pointerDown.placement); // null = deselect
	} else if (pointerDown.placement && pointerDown.moved && isMine(pointerDown.placement)) {
		pointerDown.placement._lastNetSend = 0; // force the settle broadcast through
		netBroadcastTransform(pointerDown.placement);
		saveScene();
		setStatus(null);
	}
	pointerDown = null;
}
canvas.addEventListener('pointerup', endPointer);
canvas.addEventListener('pointercancel', () => { pointerDown = null; });

// Two-finger pinch = scale, twist = rotate — on the selected (or last) model I own.
function gestureTarget() {
	const t = selected ?? placements[placements.length - 1] ?? null;
	return t && isMine(t) ? t : null;
}

canvas.addEventListener('touchstart', (e) => {
	if (xrSession || e.touches.length !== 2) return;
	const target = gestureTarget();
	if (!target) return;
	pointerDown = null; // the pair owns the gesture; no drag/tap
	pinchStart(pinch, touchDist(e.touches), target.group.scale.x);
	twist = { startAngle: touchAngle(e.touches), baseYaw: target.yaw, placement: target };
}, { passive: true });

canvas.addEventListener('touchmove', (e) => {
	if (xrSession || e.touches.length !== 2) return;
	const target = twist?.placement;
	if (!target) return;
	const s = pinchMove(pinch, touchDist(e.touches));
	if (s != null) {
		target.group.scale.setScalar(s);
		target.shadow?.scale.setScalar(s);
		if (selected === target) positionSelRing();
	}
	target.yaw = twist.baseYaw + twistDelta(twist.startAngle, touchAngle(e.touches));
	target.group.rotation.y = target.yaw;
	netBroadcastTransform(target);
}, { passive: true });

canvas.addEventListener('touchend', () => {
	const s = pinchEnd(pinch);
	const target = twist?.placement;
	if (s != null) {
		pinchEndedAt = performance.now();
		saveScene();
	}
	if (target) { target._lastNetSend = 0; netBroadcastTransform(target); }
	twist = null;
}, { passive: true });

// ── Selection toolbar ─────────────────────────────────────────────────────────
selbar?.addEventListener('click', (e) => {
	const btn = e.target.closest('[data-act]');
	if (!btn || !selected) return;
	const act = btn.dataset.act;
	if (act === 'rotate') {
		if (!isMine(selected)) { setStatus('That model belongs to someone else in the room.', { warn: true }); return; }
		selected.yaw += Math.PI / 4;
		selected.group.rotation.y = selected.yaw;
		selected._lastNetSend = 0;
		netBroadcastTransform(selected);
		saveScene();
	} else if (act === 'duplicate') {
		addModel({ src: selected.src, title: selected.title }, {
			yaw: selected.yaw, scale: logicalScale(selected),
		});
	} else if (act === 'remove') {
		if (!isMine(selected)) { setStatus('That model belongs to someone else in the room.', { warn: true }); return; }
		const removed = selected;
		removePlacement(removed);
		setStatus('Removed.', {
			actionLabel: 'Undo',
			onAction: () => addModel({ src: removed.src, title: removed.title }, {
				x: removed.group.position.x, z: removed.group.position.z,
				yaw: removed.yaw, scale: logicalScale(removed),
			}),
		});
	}
});

clearBtn?.addEventListener('click', () => {
	if (!placements.length) return;
	undoItems = placements.map((p) => ({
		src: p.src, title: p.title,
		x: p.group.position.x, z: p.group.position.z,
		yaw: p.yaw, scale: logicalScale(p),
	}));
	for (const p of [...placements]) removePlacement(p, { persist: false });
	saveScene();
	setStatus('Scene cleared.', {
		actionLabel: 'Undo',
		onAction: async () => {
			const items = undoItems ?? [];
			undoItems = null;
			for (const it of items) {
				await addModel({ src: it.src, title: it.title }, {
					x: it.x, z: it.z, yaw: it.yaw, scale: it.scale, announce: false,
				});
			}
		},
	});
});

// ── Forge without leaving the camera ─────────────────────────────────────────
let forgeBusy = false;
let forgeSeq = 0;

function forgeChipState(state, label) {
	if (!forgeChip) return;
	forgeChip.dataset.state = state;
	forgeChip.hidden = state === 'idle';
	const text = forgeChip.querySelector('.ars-chip-label');
	if (text) text.textContent = label || '';
}

async function startForge(prompt) {
	prompt = String(prompt || '').trim();
	if (prompt.length < 3 || forgeBusy) return;
	forgeBusy = true;
	const seq = ++forgeSeq;
	if (forgeGo) forgeGo.disabled = true;
	const t0 = Date.now();
	// Real ETA + cold-start signal from the initial /api/forge response (see
	// api/_lib/forge-lane-health.js#coldStartFor). No poll response repeats
	// these fields, so they're captured once here and folded into every later
	// forgeStageNarration() call via the shared eta_seconds/cold_start contract.
	let etaSeconds = null;
	let coldStart = false;
	let coldSeconds = null;
	let laneBackend = null;
	// The last status the pipeline actually reported, so the repaint timer never
	// claims a stage the worker has not entered.
	let liveStatus = 'queued';
	forgeChipState('working', 'Sending your prompt to the forge…');
	const setStage = (status) => {
		if (!forgeChip) return;
		const elapsedS = (Date.now() - t0) / 1000;
		const remaining = etaSeconds != null ? Math.max(0, Math.round(etaSeconds - elapsedS)) : null;
		// The cold-start budget counts down from the real spin-up seconds the API
		// reported, so the line shrinks against the clock instead of repeating.
		const coldLeft = coldSeconds != null ? Math.max(0, Math.round(coldSeconds - elapsedS)) : null;
		const narration = forgeStageNarration({
			status,
			eta_seconds: remaining ?? undefined,
			backend: laneBackend ?? undefined,
			cold_start: coldStart && status !== 'done',
			cold_seconds: coldLeft ?? undefined,
		});
		const label = forgeChip.querySelector('.ars-chip-label');
		const el = forgeChip.querySelector('.ars-chip-elapsed');
		if (label) label.textContent = narration;
		if (el) el.textContent = `${Math.round(elapsedS)}s`;
	};
	const elapsed = setInterval(() => {
		if (forgeChip?.dataset.state === 'working') setStage(liveStatus);
	}, 1000);

	try {
		const res = await fetch('/api/forge', {
			method: 'POST',
			headers: { 'content-type': 'application/json', 'x-forge-client': CLIENT_ID },
			body: JSON.stringify({ prompt, backend: 'nvidia' }),
		});
		const data = await res.json().catch(() => ({}));
		if (res.status === 503 || data.error === 'unconfigured') {
			throw new Error('The generator is offline right now. Try again in a few minutes.');
		}
		if (res.status === 429 || data.error === 'rate_limited') {
			const secs = Number(data.retry_after) > 0 ? Math.ceil(Number(data.retry_after)) : 15;
			throw new Error(data.message || `The forge is busy — try again in about ${secs}s.`);
		}
		if (!res.ok) throw new Error(data.message || `The generator returned ${res.status}.`);
		if (Number(data.eta_seconds) > 0) etaSeconds = Math.round(Number(data.eta_seconds));
		coldStart = Boolean(data.cold_start);
		if (Number(data.cold_start_seconds) > 0) coldSeconds = Math.round(Number(data.cold_start_seconds));
		if (typeof data.backend === 'string' && data.backend) laneBackend = data.backend;

		let done = data;
		if (!(data.status === 'done' && data.glb_url)) {
			if (!data.job_id) throw new Error('The forge did not accept the job. Try again.');
			setStage('queued');
			done = await pollForge(data.job_id, seq, (d) => {
				if (typeof d.status === 'string' && d.status) liveStatus = d.status;
				// A worker that answers "running" is up, so the boot is genuinely over.
				if (d.status === 'running') coldStart = false;
				if (typeof d.backend === 'string' && d.backend) laneBackend = d.backend;
				setStage(liveStatus);
			});
		}
		if (!done || seq !== forgeSeq) return;
		rememberForge(prompt, done.glb_url);
		forgeChipState('idle');
		if (forgeInput) forgeInput.value = '';
		await addModel({ src: done.glb_url, title: prompt }, { announce: false });
		setStatus('Forged and placed. Pinch to resize, drag to move.');
	} catch (err) {
		if (seq === forgeSeq) {
			forgeChipState('error', (err && err.message) || 'Generation failed.');
			setTimeout(() => {
				if (forgeChip?.dataset.state === 'error') forgeChipState('idle');
			}, 6000);
		}
	} finally {
		clearInterval(elapsed);
		if (seq === forgeSeq) {
			forgeBusy = false;
			if (forgeGo) forgeGo.disabled = false;
		}
	}
}

async function pollForge(jobId, seq, onUpdate) {
	const deadline = Date.now() + MAX_POLL_MS;
	for (;;) {
		if (seq !== forgeSeq) return null;
		if (Date.now() > deadline) throw new Error('Generation timed out. Try a simpler, single-object prompt.');
		await new Promise((r) => setTimeout(r, POLL_MS));
		if (seq !== forgeSeq) return null;
		const res = await fetch(`/api/forge?job=${encodeURIComponent(jobId)}`, {
			headers: { 'x-forge-client': CLIENT_ID },
		});
		const data = await res.json().catch(() => ({}));
		if (typeof onUpdate === 'function') onUpdate(data);
		if (data.status === 'done' && data.glb_url) return data;
		if (data.status === 'failed') throw new Error(data.error || 'Generation failed. Try rephrasing the prompt.');
	}
}

function readRecent() {
	try {
		const v = JSON.parse(localStorage.getItem(RECENT_KEY) || '[]');
		return Array.isArray(v)
			? v.filter((e) => e && normalizeGlbUrl(e.glb) && e.prompt)
			: [];
	} catch {
		return [];
	}
}

function rememberForge(prompt, glb) {
	try {
		const list = readRecent().filter((e) => e.glb !== glb);
		list.unshift({ prompt: String(prompt).slice(0, 200), glb, ts: Date.now() });
		localStorage.setItem(RECENT_KEY, JSON.stringify(list.slice(0, 8)));
	} catch {}
}

forgeForm?.addEventListener('submit', (e) => {
	e.preventDefault();
	startForge(forgeInput?.value);
});

// ── Model tray ────────────────────────────────────────────────────────────────
let trayTab = 'recent';
const trayCache = new Map(); // tab → items

// Closing a dialog must hand the keyboard back to whatever opened it; dropping
// focus on <body> strands a keyboard user at the top of the document with the
// scene they were just editing behind them.
function restoreFocus(el) {
	if (el && document.contains(el) && !el.hidden) el.focus?.();
}

function openTray(tab = trayTab) {
	if (!tray) return;
	tray.hidden = false;
	addBtn?.setAttribute('aria-expanded', 'true');
	setTrayTab(tab);
	trayClose?.focus?.();
}

function closeTray() {
	if (!tray) return;
	const wasOpen = !tray.hidden;
	tray.hidden = true;
	addBtn?.setAttribute('aria-expanded', 'false');
	if (wasOpen && tray.contains(document.activeElement)) restoreFocus(addBtn);
}

function closeQrModal() {
	if (!qrModal) return;
	const hadFocus = qrModal.contains(document.activeElement);
	qrModal.hidden = true;
	if (hadFocus) restoreFocus(qrBtn);
}

addBtn?.addEventListener('click', () => (tray?.hidden ? openTray() : closeTray()));
trayClose?.addEventListener('click', closeTray);
tray?.addEventListener('click', (e) => {
	if (e.target === tray) closeTray();
});
document.addEventListener('keydown', (e) => {
	if (e.key === 'Escape') {
		if (tray && !tray.hidden) closeTray();
		else if (roomModal && !roomModal.hidden) closeRoomModal();
		else if (qrModal && !qrModal.hidden) closeQrModal();
		else select(null);
	}
});

// ── Desktop keyboard controls ─────────────────────────────────────────────────
// Arrows nudge the selected model camera-relative (Shift = fine), R rotates,
// D duplicates, Delete removes — the mouse never has to leave the scene.
document.addEventListener('keydown', (e) => {
	if (e.target.closest?.('input, textarea, select')) return;
	if ((tray && !tray.hidden) || (qrModal && !qrModal.hidden) || xrSession) return;
	if (!selected) return;
	// Keyboard edits act on the selected model — only if it's mine in a room.
	const editable = isMine(selected);

	const key = e.key;
	if (key.startsWith('Arrow')) {
		if (!editable) return;
		e.preventDefault();
		const step = e.shiftKey ? 0.02 : 0.1;
		const fwd = camera.getWorldDirection(new Vector3());
		fwd.y = 0;
		if (fwd.lengthSq() < 1e-6) fwd.set(0, 0, -1);
		fwd.normalize();
		const right = new Vector3(-fwd.z, 0, fwd.x);
		const move = key === 'ArrowUp' ? fwd
			: key === 'ArrowDown' ? fwd.negate()
			: key === 'ArrowLeft' ? right.negate()
			: right;
		selected.group.position.addScaledVector(move, step);
		selected.shadow?.position.set(selected.group.position.x, 0.004, selected.group.position.z);
		positionSelRing();
		netBroadcastTransform(selected);
		saveScene();
	} else if (key === 'r' || key === 'R') {
		if (!editable) return;
		selected.yaw += Math.PI / 4;
		selected.group.rotation.y = selected.yaw;
		selected._lastNetSend = 0;
		netBroadcastTransform(selected);
		saveScene();
	} else if (key === 'd' || key === 'D') {
		e.preventDefault();
		addModel({ src: selected.src, title: selected.title }, {
			yaw: selected.yaw, scale: logicalScale(selected),
		});
	} else if (key === 'Delete' || key === 'Backspace') {
		if (!editable) return;
		e.preventDefault();
		const removed = selected;
		removePlacement(removed);
		setStatus('Removed.', {
			actionLabel: 'Undo',
			onAction: () => addModel({ src: removed.src, title: removed.title }, {
				x: removed.group.position.x, z: removed.group.position.z,
				yaw: removed.yaw, scale: logicalScale(removed),
			}),
		});
	}
});

const trayTabs = [...(tray?.querySelectorAll('[data-tab]') || [])];
trayTabs.forEach((btn) => {
	btn.addEventListener('click', () => setTrayTab(btn.dataset.tab));
});

// A role="tablist" owes the keyboard the arrow-key contract: Left/Right (and
// Home/End) move between tabs and select as they go, with a roving tabindex so
// Tab enters the strip once and then leaves it for the panel.
tray?.querySelector('.ars-tabs')?.addEventListener('keydown', (e) => {
	const i = trayTabs.indexOf(document.activeElement);
	if (i === -1) return;
	const last = trayTabs.length - 1;
	const next = e.key === 'ArrowRight' ? (i === last ? 0 : i + 1)
		: e.key === 'ArrowLeft' ? (i === 0 ? last : i - 1)
		: e.key === 'Home' ? 0
		: e.key === 'End' ? last
		: -1;
	if (next === -1) return;
	e.preventDefault();
	setTrayTab(trayTabs[next].dataset.tab);
	trayTabs[next].focus();
});

// Mark which way the tab strip can still scroll so the CSS edge fade points at
// the hidden tabs instead of guessing (see .ars-tabs[data-scroll] in the page).
const tabStrip = tray?.querySelector('.ars-tabs');
function updateTabScrollHints() {
	if (!tabStrip) return;
	const slack = tabStrip.scrollWidth - tabStrip.clientWidth;
	const hints = [];
	if (slack > 2 && tabStrip.scrollLeft > 2) hints.push('start');
	if (slack > 2 && tabStrip.scrollLeft < slack - 2) hints.push('end');
	tabStrip.dataset.scroll = hints.join(' ');
}
tabStrip?.addEventListener('scroll', updateTabScrollHints, { passive: true });
window.addEventListener('resize', updateTabScrollHints);

function setTrayTab(tab) {
	trayTab = tab;
	trayTabs.forEach((b) => {
		const on = b.dataset.tab === tab;
		b.classList.toggle('is-active', on);
		b.setAttribute('aria-selected', String(on));
		b.tabIndex = on ? 0 : -1;
		if (on) {
			trayBody?.setAttribute('aria-labelledby', b.id);
			b.scrollIntoView?.({ block: 'nearest', inline: 'nearest' });
		}
	});
	updateTabScrollHints();
	renderTray();
}

function trayItemHTML(it) {
	const img = it.poster
		? `<img src="${esc(it.poster)}" alt="" loading="lazy" />`
		: '<span class="ars-item-cube" aria-hidden="true">◆</span>';
	// A forge row's "title" is the prompt it was generated from, and a refined
	// or image-derived prompt is a multi-clause spec. Cards get the first
	// clause; the whole prompt stays reachable as the tooltip.
	const label = cardTitleFromPrompt(it.title);
	const full = String(it.title || '').trim();
	return `
		<li class="ars-item">
			<button type="button" class="ars-item-add" data-src="${esc(it.src)}" data-title="${esc(label)}"
				${full ? `title="${esc(full)}"` : ''}
				aria-label="Add ${esc(label)} to your space">
				<span class="ars-item-thumb">${img}</span>
				<span class="ars-item-title">${esc(label)}</span>
				<span class="ars-item-cta">Add</span>
			</button>
		</li>`;
}

async function fetchTrayItems(tab) {
	if (trayCache.has(tab)) return trayCache.get(tab);
	let items = [];
	if (tab === 'recent') {
		items = readRecent().map((e) => ({ src: e.glb, title: e.prompt, poster: '' }));
	} else if (tab === 'objects') {
		// The CC0 object library (/objects). The full manifest is a few hundred
		// small records; fetch it once so the tab's filter box runs client-side
		// with no further requests.
		const res = await fetch('/api/objects/library');
		if (!res.ok) throw new Error(`objects ${res.status}`);
		const data = await res.json();
		items = (data.objects || [])
			.map((o) => ({
				src: o.url || '',
				title: o.label || o.name || '',
				poster: o.thumb || '',
				keywords: `${o.label || o.name || ''} ${(o.categories || []).join(' ')}`.toLowerCase(),
			}))
			.filter((o) => normalizeGlbUrl(o.src));
	} else {
		const qs = tab === 'community' ? '?scope=community&limit=24' : '?limit=24';
		const res = await fetch(`/api/forge-gallery${qs}`, {
			headers: tab === 'yours' ? { 'x-forge-client': CLIENT_ID } : {},
		});
		if (!res.ok) throw new Error(`gallery ${res.status}`);
		const data = await res.json();
		items = (data.creations || [])
			.map((c) => ({
				src: c.glb_url || c.glbUrl || '',
				title: c.prompt || c.title || '',
				poster: c.preview_image_url || c.previewImageUrl || '',
			}))
			.filter((c) => normalizeGlbUrl(c.src));
	}
	trayCache.set(tab, items);
	return items;
}


// "From a photo": SAM 3D Objects (POST /api/forge-scene-objects) turns one photo
// into a single GLB with a named node per object, laid out like the photo. The
// scene lands in the room as one model. The endpoint answers 503
// backend_unconfigured until the GPU worker is deployed, and the tab says so.
const PHOTO_POLL_MS = 4000;
const PHOTO_MAX_POLLS = 150;
let photoJobRunning = false;

async function runPhotoScene(imageUrl, ui) {
	const res = await fetch('/api/forge-scene-objects', {
		method: 'POST',
		credentials: 'include',
		headers: { 'content-type': 'application/json', 'x-forge-client': CLIENT_ID },
		body: JSON.stringify({ image_url: imageUrl }),
	});
	const start = await res.json().catch(() => ({}));
	if (!res.ok) throw new Error(start.message || start.error_description || `Request failed (${res.status}).`);
	ui.progress(`Reading the photo: ${start.objects?.length || 'some'} object(s) found. Rebuilding in 3D…`);
	for (let i = 0; i < PHOTO_MAX_POLLS; i++) {
		await new Promise((r) => setTimeout(r, PHOTO_POLL_MS));
		const poll = await fetch(`/api/forge-scene-objects?job=${encodeURIComponent(start.job_id)}`, { credentials: 'include' });
		const body = await poll.json().catch(() => ({}));
		if (!poll.ok) throw new Error(body.message || `Status check failed (${poll.status}).`);
		if (body.status === 'failed' || body.error) throw new Error(body.error || 'The reconstruction failed.');
		if (body.result_url) return body;
	}
	throw new Error('The reconstruction is taking too long. Try again in a few minutes.');
}

function renderPhotoTab() {
	trayBody.innerHTML = `
		<form class="ars-link-form" id="ars-photo-form">
			<label class="ars-link-label" for="ars-photo-input">Paste a photo link</label>
			<div class="ars-link-row">
				<input id="ars-photo-input" type="url" inputmode="url" required
					placeholder="https://example.com/desk.jpg" />
				<button type="submit" class="ars-btn ars-btn-primary" id="ars-photo-go">Build scene</button>
			</div>
			<p class="ars-link-hint">Every object SAM 3D finds in the photo becomes a 3D object, laid out the way it sits in the picture. Takes a couple of minutes.</p>
			<div id="ars-photo-state" role="status" aria-live="polite"></div>
		</form>`;
	const form = $('ars-photo-form');
	const state = $('ars-photo-state');
	const go = $('ars-photo-go');
	form?.addEventListener('submit', async (e) => {
		e.preventDefault();
		if (photoJobRunning) return;
		const url = String($('ars-photo-input')?.value || '').trim();
		if (!/^https:\/\//i.test(url)) {
			state.innerHTML = '<p class="ars-photo-error">That needs to be a public https link to a photo.</p>';
			return;
		}
		photoJobRunning = true;
		go.disabled = true;
		const ui = {
			progress: (msg) => {
				state.innerHTML = '<div class="ars-photo-progress"><span class="ars-spinner" aria-hidden="true"></span><span></span></div>';
				state.querySelector('span:last-child').textContent = msg;
			},
		};
		ui.progress('Finding the objects in your photo…');
		try {
			const done = await runPhotoScene(url, ui);
			closeTray();
			await addModel({ src: done.result_url, title: 'Photo scene' });
		} catch (err) {
			state.innerHTML = '<p class="ars-photo-error"></p>';
			state.firstChild.textContent = err.message;
		} finally {
			photoJobRunning = false;
			go.disabled = false;
		}
	});
}

async function renderTray() {
	if (!trayBody) return;
	const tab = trayTab;

	if (tab === 'link') {
		trayBody.innerHTML = `
			<form class="ars-link-form" id="ars-link-form">
				<label class="ars-link-label" for="ars-link-input">Paste a GLB link</label>
				<div class="ars-link-row">
					<input id="ars-link-input" type="url" inputmode="url" required
						placeholder="https://example.com/model.glb" />
					<button type="submit" class="ars-btn ars-btn-primary">Add</button>
				</div>
				<p class="ars-link-hint">Any https .glb works — a forge result, a viewer share link's src, or your own hosting.</p>
			</form>`;
		const form = $('ars-link-form');
		form?.addEventListener('submit', (e) => {
			e.preventDefault();
			const input = $('ars-link-input');
			const url = normalizeGlbUrl(input?.value);
			if (!url) {
				setStatus('That link is not a loadable https GLB.', { warn: true });
				return;
			}
			closeTray();
			addModel({ src: url, title: url.split('/').pop()?.replace(/\.glb.*$/i, '') || 'Linked model' });
		});
		return;
	}

	if (tab === 'photo') {
		renderPhotoTab();
		return;
	}

	trayBody.innerHTML = '<div class="ars-tray-loading"><span class="ars-spinner" aria-hidden="true"></span> Loading models…</div>';
	let items;
	try {
		items = await fetchTrayItems(tab);
	} catch (err) {
		log.warn('tray fetch failed', tab, err);
		if (trayTab !== tab) return;
		trayBody.innerHTML = `
			<div class="ars-tray-empty">
				<p>Couldn’t load models right now.</p>
				<button type="button" class="ars-btn" id="ars-tray-retry">Retry</button>
			</div>`;
		$('ars-tray-retry')?.addEventListener('click', () => {
			trayCache.delete(tab);
			renderTray();
		});
		return;
	}
	if (trayTab !== tab) return;

	if (!items.length) {
		const copy = {
			recent: 'Nothing forged on this device yet. Type a prompt below and your first model appears here.',
			yours: 'No saved creations yet. Forge something here or in the <a href="/forge">Forge studio</a> and it lands in this tab.',
			community: 'The community feed is quiet right now. Check back in a bit.',
			objects: 'The <a href="/objects">object library</a> is unreachable right now. Check back in a bit.',
		}[tab] || 'Nothing here yet.';
		trayBody.innerHTML = `
			<div class="ars-tray-empty">
				<p>${copy}</p>
				<button type="button" class="ars-btn ars-btn-primary" id="ars-tray-forge">Forge a model</button>
			</div>`;
		$('ars-tray-forge')?.addEventListener('click', () => {
			closeTray();
			forgeInput?.focus();
		});
		return;
	}
	if (tab === 'objects') {
		renderObjectsTray(items);
		return;
	}
	trayBody.innerHTML = `<ul class="ars-item-list">${items.map(trayItemHTML).join('')}</ul>`;
	wireTrayAdds();
}

function wireTrayAdds() {
	trayBody.querySelectorAll('.ars-item-add').forEach((btn) => {
		btn.addEventListener('click', () => {
			closeTray();
			addModel({ src: btn.dataset.src, title: btn.dataset.title });
		});
	});
	// A poster that 404s or times out would otherwise leave a broken-image glyph
	// in the grid. Fall back to the same cube mark a poster-less item already
	// uses, so a flaky thumbnail host never makes the tray look broken.
	trayBody.querySelectorAll('.ars-item-thumb img').forEach((img) => {
		img.addEventListener('error', () => {
			const slot = img.parentElement;
			if (!slot) return;
			slot.textContent = '';
			const cube = document.createElement('span');
			cube.className = 'ars-item-cube';
			cube.setAttribute('aria-hidden', 'true');
			cube.textContent = '◆';
			slot.appendChild(cube);
		}, { once: true });
	});
}

// The object library is ~500 CC0 props, too many to scroll blind, so this tab
// filters over name + category and renders matches in slices.
const OBJECTS_SLICE = 60;
function renderObjectsTray(items) {
	trayBody.innerHTML = `
		<div class="ars-objects-head">
			<div class="ars-link-row">
				<input id="ars-objects-search" type="search" autocomplete="off"
					placeholder="Search ${items.length} CC0 props…"
					aria-label="Search the object library" />
			</div>
			<p class="ars-link-hint">Free CC0 props from the <a href="/objects">object library</a>. Tap one to place it in your space.</p>
		</div>
		<ul class="ars-item-list" id="ars-objects-list"></ul>
		<div class="ars-objects-more" id="ars-objects-more"></div>`;
	const list = $('ars-objects-list');
	const more = $('ars-objects-more');
	const input = $('ars-objects-search');
	let shown = OBJECTS_SLICE;
	const paint = () => {
		const q = (input?.value || '').trim().toLowerCase();
		const matches = q ? items.filter((o) => o.keywords.includes(q)) : items;
		list.innerHTML = matches.slice(0, shown).map(trayItemHTML).join('');
		wireTrayAdds();
		if (matches.length > shown) {
			more.innerHTML = `<button type="button" class="ars-btn" id="ars-objects-show-more">Show ${Math.min(OBJECTS_SLICE, matches.length - shown)} more (${matches.length - shown} left)</button>`;
			$('ars-objects-show-more')?.addEventListener('click', () => {
				shown += OBJECTS_SLICE;
				paint();
			});
		} else {
			more.innerHTML = matches.length ? '' : '<p class="ars-link-hint">No props match that search.</p>';
		}
	};
	input?.addEventListener('input', () => {
		shown = OBJECTS_SLICE;
		paint();
	});
	paint();
}

// ── Entering AR ──────────────────────────────────────────────────────────────
// Three device classes, three genuinely different experiences, and only one of
// them is WebXR. An iPhone has no immersive-ar session, and until this existed
// it was offered nothing but the camera-passthrough composite: the model floats
// convincingly in a screenshot and not at all in the hand, because there is no
// plane detection, no real scale and nothing occluding it. Every iPhone already
// ships ARKit through AR Quick Look, which is what /avatars/:id/ar has always
// used, so the studio now hands one model to it the same way.
//
// 'webxr' keeps the whole multi-model scene in the page and stays first.
/** @type {'webxr'|'quicklook'|'sceneviewer'|'none'} */
let arMode = 'none';

async function resolveArMode() {
	try {
		if (await MultiPlaceSession.isSupported()) return 'webxr';
	} catch {
		// A throwing support probe is just "not webxr".
	}
	if (canUseQuickLook()) return 'quicklook';
	if (canUseSceneViewer()) return 'sceneviewer';
	return 'none';
}

resolveArMode().then((mode) => {
	arMode = mode;
	if (!xrBtn || mode === 'none') return;
	xrBtn.hidden = false;
	const label = xrBtn.querySelector('.ars-ar-label');
	if (mode === 'webxr') {
		if (label) label.textContent = 'Immersive';
		xrBtn.setAttribute('aria-label', 'Enter immersive AR');
	} else {
		// Do not promise an immersive session to a device that has none.
		if (label) {
			label.textContent = 'Place in AR';
			label.setAttribute('data-i18n', 'ar_studio.place_in_ar');
		}
		xrBtn.setAttribute('aria-label', 'Open this in your device AR viewer and place it in your real space');
	}
});

// The device's own AR viewer, for one model. Quick Look reads USDZ rather than
// glTF, so the GLB is converted here on the device (a real conversion through
// three's USDZExporter, the same pipeline /avatars/:id/ar uses) and handed over
// as a blob. A couple of silent seconds after a tap reads as a dead button, so
// every stage reports.
let nativeArBusy = false;
let nativeArObjectUrl = null;

async function placeNative(placement) {
	const target = placement || selected || placements[placements.length - 1];
	if (!target) {
		setStatus('Add a model first, then place it in your space.', { warn: true });
		return;
	}
	if (nativeArBusy) return;
	nativeArBusy = true;
	xrBtn?.setAttribute('aria-busy', 'true');
	try {
		if (canUseQuickLook()) {
			setStatus('Fetching the model…', { sticky: true });
			const res = await fetch(target.src);
			if (!res.ok) throw new Error(`model fetch ${res.status}`);
			const glbBlob = await res.blob();
			setStatus('Preparing it for AR…', { sticky: true });
			const usdzBlob = await glbBlobToUsdzBlob(glbBlob);
			if (nativeArObjectUrl) URL.revokeObjectURL(nativeArObjectUrl);
			nativeArObjectUrl = URL.createObjectURL(usdzBlob);
			setStatus('Opening AR…', { sticky: true });
			openQuickLook(nativeArObjectUrl);
		} else if (canUseSceneViewer()) {
			setStatus('Opening AR…', { sticky: true });
			openSceneViewer(target.src, { title: target.title || '', link: location.href });
		} else {
			setStatus('This device has no AR viewer. Open this scene on a phone to place it in a room.', {
				warn: true, actionLabel: 'Show QR', onAction: () => qrBtn?.click(),
			});
			return;
		}
		setStatus('Point at the floor, then drag to place it.');
	} catch (err) {
		setStatus(`Could not open AR for this model (${err?.message || err}).`, {
			warn: true, actionLabel: 'Try again', onAction: () => placeNative(target),
		});
	} finally {
		nativeArBusy = false;
		xrBtn?.removeAttribute('aria-busy');
	}
}

window.addEventListener('pagehide', () => {
	if (nativeArObjectUrl) URL.revokeObjectURL(nativeArObjectUrl);
});

xrBtn?.addEventListener('click', async () => {
	// Anything that is not WebXR goes to the platform's own viewer instead.
	if (arMode !== 'webxr') {
		placeNative();
		return;
	}
	if (xrSession) {
		xrSession.end();
		return;
	}
	if (arTransitioning) return;
	arTransitioning = true;
	try {
		if (arActive) stopCamera(); // the immersive session owns the rear camera
		const session = new MultiPlaceSession({
			renderer,
			scene,
			camera,
			domOverlayRoot: hud,
			getArmedContent: () => {
				const src = armedSrc?.src ?? placements[placements.length - 1]?.src;
				if (!src) {
					setStatus('Pick a model first — Add or forge one, then tap the floor.', { warn: true });
					return null;
				}
				// An XR select can't await: only an already-resolved template places.
				const tpl = tplReady.get(src);
				if (!tpl) {
					loadTemplate(src);
					setStatus('Model is still loading — one moment, then tap again.', { sticky: true });
					return null;
				}
				const { group, mixer, idlePromise } = instantiate(tpl, src);
				const placement = {
					id: `p-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 7)}`,
					src,
					title: armedSrc?.title || '',
					group,
					shadow: null,
					mixer,
					idle: null,
					yaw: 0,
					baseRadius: tpl.radius,
					spawnT: 1,
				};
				idlePromise?.then((mgr) => {
					if (!mgr) return;
					if (placements.includes(placement)) placement.idle = mgr;
					else mgr.detach();
				});
				placements.push(placement);
				updateCount();
				return group;
			},
			onPlaced: (group) => {
				const p = placements.find((x) => x.group === group);
				if (p) {
					p.yaw = 0;
					select(null); // the ring is a fallback-mode affordance
				}
				saveScene();
				setStatus(`Placed ${xrSession?.placedCount ?? ''} — tap another spot to add one more.`);
			},
			getScaleTarget: () => placements[placements.length - 1]?.group ?? null,
			onScale: (s, { final }) => {
				if (final) saveScene();
			},
			onHit: (has) => {
				document.body.classList.toggle('xr-has-floor', has);
			},
			onTracking: (ok) => {
				if (!ok) setStatus('Tracking lost — move to a brighter spot with more texture.', { warn: true, sticky: true });
				else setStatus(null);
			},
			onFrame: (dt) => {
				for (const p of placements) {
					p.mixer?.update(dt);
					p.idle?.update(dt);
				}
			},
			onEnd: () => {
				xrSession = null;
				estimatedLight?.dispose();
				estimatedLight = null;
				document.body.classList.remove('is-xr', 'xr-has-floor');
				xrBtn.classList.remove('is-active');
				xrBtn.setAttribute('aria-pressed', 'false');
				// Ground anything the session placed mid-air back onto the floor
				// plane so the fallback layout stays coherent, then resume our loop.
				for (const p of placements) {
					p.group.position.y = 0;
					if (p.shadow) {
						p.shadow.visible = true;
						p.shadow.position.set(p.group.position.x, 0.004, p.group.position.z);
					}
				}
				grid.visible = true;
				if (!arActive) scene.fog = previewFog;
				saveScene();
				startLoop();
				setStatus('Back to the studio view.');
			},
		});
		stopLoop();
		await session.start();
		xrSession = session;
		// Real-world lighting + reflections: replaces the baked hemi/sun with the
		// room's actual light the moment the device starts estimating it. Created
		// after start() so the addon's sessionstart listener requests the probe.
		estimatedLight = new EstimatedLighting({
			renderer,
			scene,
			baseLights: [hemi, sun],
			onChange: (on) => {
				if (on) setStatus('Lit by your room — reflections and shadows match the real light.');
			},
		});
		estimatedLight.start();
		document.body.classList.add('is-xr');
		grid.visible = false;
		scene.fog = null;
		selRing.visible = false;
		for (const p of placements) {
			if (p.shadow) p.shadow.visible = false;
		}
		xrBtn.classList.add('is-active');
		xrBtn.setAttribute('aria-pressed', 'true');
		setStatus('Point at the floor, then tap to place. Every tap adds another model.');
	} catch (err) {
		log.warn('XR session failed', err);
		estimatedLight?.dispose();
		estimatedLight = null;
		startLoop();
		setStatus('Couldn’t start immersive AR on this device. Camera mode still works.', { warn: true });
	} finally {
		arTransitioning = false;
	}
});

// ── Photo + QR handoff ────────────────────────────────────────────────────────
photoBtn?.addEventListener('click', async () => {
	renderer.render(scene, camera); // fresh pixels under preserveDrawingBuffer
	const blob = await captureComposite({ canvas, video: videoEl, isAR: arActive });
	if (!blob) {
		setStatus('Couldn’t capture the frame.', { warn: true });
		return;
	}
	await shareOrDownload(blob, { filename: 'three-ws-ar-studio.png', title: 'AR Studio · three.ws' });
});

qrBtn?.addEventListener('click', () => {
	if (!qrModal) return;
	const url = studioSceneUrl(STUDIO_BASE_URL, placements.map((p) => ({
		src: p.src,
		title: p.title,
		x: p.group.position.x,
		z: p.group.position.z,
		yaw: p.yaw,
		scale: logicalScale(p),
	})));
	const box = $('ars-qr-box');
	if (box) {
		try {
			box.innerHTML = renderQRToSVG(url, { scale: 6, margin: 2, dark: '#0b0b0b', light: '#ffffff' });
		} catch {
			// Arrangement hash too dense for the encoder → a models-only QR still
			// beats a wall of text (the full link below keeps the arrangement).
			try {
				box.innerHTML = renderQRToSVG(studioShareUrl(STUDIO_BASE_URL, placements), {
					scale: 6, margin: 2, dark: '#0b0b0b', light: '#ffffff',
				});
			} catch {
				box.textContent = url;
			}
		}
	}
	const link = $('ars-qr-link');
	if (link) {
		link.href = url;
		link.textContent = url.length > 64 ? `${url.slice(0, 61)}…` : url;
	}
	qrModal.hidden = false;
	// aria-modal="true" is a promise that focus is inside the dialog; leaving it
	// on the trigger reads the HUD behind instead of the QR code.
	$('ars-qr-close')?.focus?.();
});
$('ars-qr-close')?.addEventListener('click', closeQrModal);
qrModal?.addEventListener('click', (e) => {
	if (e.target === qrModal) closeQrModal();
});

// ── Render loop ───────────────────────────────────────────────────────────────
let rafId = null;
let prevT = 0;

function tick(t) {
	rafId = requestAnimationFrame(tick);
	const dt = prevT ? Math.min(0.1, (t - prevT) / 1000) : 0.016;
	prevT = t;

	for (const p of placements) {
		p.mixer?.update(dt);
		p.idle?.update(dt);
		if (p.spawnT < 1) {
			p.spawnT = Math.min(1, p.spawnT + dt * 3.2);
			const e = 1 - (1 - p.spawnT) ** 3; // ease-out cubic
			const target = p.group.userData._targetScale ?? 1;
			p.group.scale.setScalar(Math.max(0.001, target * e));
			p.shadow?.scale.setScalar(Math.max(0.001, target * e));
		}
	}
	if (selected) positionSelRing();
	applyCameraLook();
	renderer.render(scene, camera);
}

function startLoop() {
	if (rafId === null) {
		prevT = 0;
		rafId = requestAnimationFrame(tick);
	}
}

function stopLoop() {
	if (rafId !== null) {
		cancelAnimationFrame(rafId);
		rafId = null;
	}
}

// ── Resize / lifecycle ────────────────────────────────────────────────────────
window.addEventListener('resize', () => {
	renderer.setSize(window.innerWidth, window.innerHeight);
	camera.aspect = window.innerWidth / window.innerHeight;
	camera.updateProjectionMatrix();
	applyCameraFov();
});

window.addEventListener('pagehide', () => {
	stopCamera();
	xrSession?.end();
	net?.destroy();
});

// ── Boot ──────────────────────────────────────────────────────────────────────
updateCount();
updateRoomButton();
startLoop();
{
	let bootRoom = '';
	try { bootRoom = normalizeRoomCode(new URLSearchParams(location.search).get('room') || ''); } catch {}
	// Arriving via a ?room= link: the shared room is the scene, so skip the local
	// restore and join straight in (no seed — I'm entering someone else's room).
	restoreScene({ skipLocal: !!bootRoom }).then(() => {
		if (bootRoom) joinRoom(bootRoom);
	});
}

// Read-only introspection hook, enabled only with ?e2e=1 — used by the shared-
// room sync test to observe remote model transforms. Never present in normal use.
try {
	if (new URLSearchParams(location.search).has('e2e')) {
		window.__arsDebug = {
			count: () => placements.length,
			netStatus: () => net?.status ?? 'none',
			netIds: () => placements.map((p) => p.netId),
			remoteX: () => {
				const p = placements.find((x) => x.remote && !isMine(x));
				return p ? p.group.position.x : null;
			},
		};
	}
} catch {}

// Mobile: lead with the camera (one tap, inside a user gesture via the empty
// state CTA). Desktop: preview + QR chip.
const isTouch = window.matchMedia?.('(pointer: coarse)').matches;
if (!isTouch && qrBtn) qrBtn.hidden = false;
$('ars-empty-camera')?.addEventListener('click', startCamera);
$('ars-empty-add')?.addEventListener('click', () => openTray('community'));
$('ars-empty-forge')?.addEventListener('click', () => forgeInput?.focus());