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.

99.1 KB
Raw Blame
// AR Studio: a live, multi-model AR scene through the device camera.
//
// Every other web-AR drop-in places exactly one model and hands off to a native
// viewer. This one keeps the whole scene in your page: place any number of
// models, arrange them by hand, generate new ones from a prompt without leaving
// the camera, share the arrangement as a link or a QR code, and build in the
// same room as someone else in real time.
//
// Rendering ladder, best first: every device gets the richest path it can:
//
//   1. WebXR immersive-ar (Android Chrome, headsets): a hit-test reticle that
//      stays armed for the whole session, one XRAnchor per placed model,
//      real-world lighting estimation, and depth occlusion so a model hides
//      behind your couch instead of painting over it.
//   2. Camera passthrough (iOS Safari, and anywhere else with a camera):
//      transparent WebGL over the live feed, gyro world-lock, and room-light
//      matching sampled from the actual video frames.
//   3. Preview (desktop, no camera): the same scene on a grid floor with
//      drag-look and a QR hand-off to a phone.
//
// The scene persists to localStorage and round-trips through the URL, so an
// arrangement composed on a laptop reopens exactly on a phone.
//
// Ported and generalized from the three.ws AR Studio (Apache-2.0).

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

import { resolveConfig } from '../config.js';
import { createLogger } from '../log.js';
import { renderQRToSVG } from '../qr.js';
import { createForgeClient } from '../forge/client.js';
import { resolveSources } from '../sources/index.js';
import { rememberRecent } from '../sources/recents.js';
import { buildArLaunchUrl } from '../ar-launch.js';

import { applyCinematicDefaults, detectQualityTier, loadEnvironment } from './render.js';
import { buildUI, el } from './ui.js';
import { EstimatedLighting } from './estimated-lighting.js';
import { MultiPlaceSession } from './multi-place.js';
import { createLoadQueue } from './load-queue.js';
import { sharedGLTFLoader } from './loaders.js';
import { mountIdle } from './idle.js';
import { captureComposite, shareOrDownload, shareUrlOrCopy } from './capture.js';
import {
	arCapability, isQuickLookReady, placeInYourSpace, prepareNativeAr, releaseQuickLook,
} from './native-ar.js';
import { deriveVerticalFovDeg, DEFAULT_DIAG_FOV_DEG } from './camera-fov.js';
import { clampPitch, isFiniteReading, resolveLockYaw, screenPitchDeg } from './sensor-fusion.js';
import {
	createPinchState, pinchEnd, pinchMove, pinchStart, touchDist,
	PINCH_SCALE_MAX, PINCH_SCALE_MIN,
} from './pinch.js';
import {
	deserializeScene, fitTransform, MAX_PLACEMENTS, normalizeGlbUrl, roomLightFromPixels,
	sceneFromHashParam, serializeScene, SPAWN_DISTANCE_M, spawnPointInFront,
	studioSceneUrl, studioShareUrl, touchAngle, twistDelta,
} from './scene-math.js';
import {
	generateRoomCode, localToShared, normalizeRoomCode, roomKeyForCode, roomShareUrl, sharedToLocal,
} from './coords.js';
import { StudioNet } from './net.js';

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

const EYE_HEIGHT_M = 1.55;
const PITCH_MIN = -1.25;
const PITCH_MAX = 1.35;
const HEMI_BASE = 1.0;
const SUN_BASE = 1.15;
const LIST_SLICE = 60;

/** One live studio. Prefer `createArStudio()` over constructing this directly. */
export class ArStudio {
	/**
	 * @param {HTMLElement} host  Where the studio mounts.
	 * @param {object} [options]  See src/config.js for every field.
	 */
	constructor(host, options = {}) {
		if (!host) throw new Error('ar-studio: a host element is required');
		this.host = host;
		this.config = resolveConfig(options);
		this.clientId = readClientId(this.config.persistKey);
		this.sources = resolveSources(this.config.assets, this.config);
		this._listeners = new Map();
		this._destroyed = false;

		this.ui = buildUI(host, this.config);
		if (this.config.fullscreen ?? (host === document.body)) this.ui.root.classList.add('is-fullscreen');

		this._initScene();
		this._initState();
		this._wireUI();
		this._boot();
	}

	// ── Events ────────────────────────────────────────────────────────────────

	/**
	 * Subscribe to a studio event. Returns an unsubscribe function.
	 * Events: `add` `remove` `select` `clear` `generate` `generate-error`
	 * `camera` `xr` `room` `share`.
	 */
	on(event, fn) {
		if (!this._listeners.has(event)) this._listeners.set(event, new Set());
		this._listeners.get(event).add(fn);
		return () => this.off(event, fn);
	}

	off(event, fn) {
		this._listeners.get(event)?.delete(fn);
	}

	_emit(event, detail = {}) {
		for (const fn of this._listeners.get(event) || []) {
			try { fn(detail); } catch (err) { log.warn(`${event} listener error`, err); }
		}
		try { this.config.onEvent?.(event, detail); } catch (err) { log.warn('onEvent error', err); }
		try {
			this.ui.root.dispatchEvent(new CustomEvent(`ar-studio:${event}`, { detail, bubbles: true }));
		} catch { /* no CustomEvent in this host */ }
	}

	// ── Scene ─────────────────────────────────────────────────────────────────

	_initScene() {
		this.renderer = new WebGLRenderer({
			canvas: this.ui.canvas, alpha: true, antialias: true, preserveDrawingBuffer: true,
		});
		this.renderer.setClearColor(0x000000, 0);
		this.qualityTier = detectQualityTier();
		applyCinematicDefaults(this.renderer, { tier: this.qualityTier });

		this.scene = new Scene();
		this.camera = new PerspectiveCamera(58, 1, 0.02, 200);
		this.camera.position.set(0, EYE_HEIGHT_M, 0);
		this.cameraYaw = 0;
		// Tilted down enough that the floor, and anything standing on it, is in
		// frame before the viewer touches anything.
		this.cameraPitch = -0.24;

		const preset = this.qualityTier === 'mobile' ? null : (this.config.lighting?.preset ?? 'studio');
		loadEnvironment(this.renderer, this.scene, preset, { urls: this.config.lighting?.urls })
			.catch((err) => log.warn('environment map failed', err));

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

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

		this.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 }),
		);
		if (this.config.branding?.accent) {
			try { this.selRing.material.color.set(this.config.branding.accent); } catch { /* keep default */ }
		}
		this.selRing.renderOrder = 998;
		this.selRing.visible = false;
		this.scene.add(this.selRing);

		this.shadowTex = makeShadowTexture();
		this.reducedMotion = prefersReducedMotion();
		this._applyCameraLook();
	}

	_initState() {
		/** @type {Array<object>} */
		this.placements = [];
		this.selected = null;
		this.arActive = false;
		this.mediaStream = null;
		this.arTransitioning = false;
		this.xrSession = null;
		this.estimatedLight = null;
		/** 'webxr' | 'quicklook' | 'sceneviewer' | 'none', resolved at boot. */
		this.arMode = 'none';
		/** True while the device's own AR viewer has the stage we stood down for. */
		this._cameraYielded = false;
		this._cameraWasOn = false;
		this._onArReturn = null;
		this._nativeArBusy = false;
		/** The hand-off the AR sheet's button will fire, once it is prepared. */
		this._arHandoff = null;
		this._arTarget = null;
		/** Bumped on every sheet open and target change so a slow, stale
		 *  conversion can never enable the button for the wrong model. */
		this._arToken = 0;
		this._arWarmTimer = null;
		/** Set when a conversion failed and the sheet's button is a retry. */
		this._arRetry = null;
		/** USDZ cache keys this studio created, so destroy() frees only its own. */
		this._arKeys = new Set();
		this.arTrackW = 0;
		this.arTrackH = 0;

		this._statusTimer = null;
		this._armed = null;
		this._templates = new Map();
		this._templatesReady = new Map();
		this._trayCache = new Map();
		this._trayTab = this.sources[0]?.id || 'link';
		this._loadQueue = createLoadQueue({ run: (src) => sharedGLTFLoader().loadAsync(src), maxActive: 3 });
		this._maxPlacements = Math.min(Number(this.config.maxPlacements) || MAX_PLACEMENTS, MAX_PLACEMENTS);

		this.net = null;
		this.roomCode = '';
		this._netModels = new Map();
		this._presence = { count: 1, names: [] };
		this._roomSynced = false;
		this._roomHeartbeat = null;

		this.forge = this.config.generate?.enabled === false ? null : createForgeClient({
			endpoint: this.config.generate.endpoint,
			kind: this.config.generate.kind,
			tier: this.config.generate.tier,
			timeoutMs: this.config.generate.timeoutMs,
			pollMs: this.config.generate.pollMs,
			headers: this.config.generate.headers,
		});
		this._forgeSeq = 0;
		this._forgeBusy = false;

		this.gyroBase = null;
		this._devAlpha = 0;
		this._devBeta = 90;
		this._devGamma = 0;
		this._absoluteOrientation = false;
		this._raycaster = new Raycaster();
		this._ndc = new Vector2();
		this._pointer = null;
		this._userLooked = false;
		this._pinch = createPinchState();
		this._pinchEndedAt = -Infinity;
		this._twist = null;
		this._rafId = null;
		this._prevT = 0;
		this._lightTimer = null;
		this._roomTint = new Color();
		this._lightProbe = makeLightProbe();
		this._recentKey = `${this.config.persistKey}:recent`;
		this.config.recentKey = this._recentKey;
	}

	// ── Wiring ────────────────────────────────────────────────────────────────

	_wireUI() {
		const u = this.ui;
		const bind = (node, type, fn, opts) => {
			if (!node) return;
			node.addEventListener(type, fn, opts);
		};

		bind(u.cameraBtn, 'click', () => {
			if (this.arTransitioning || this.xrSession) return;
			if (this.arActive) {
				this._stopCamera();
				this._setStatus('Camera off: preview mode.');
			} else {
				this._startCamera();
			}
		});
		if (!navigator.mediaDevices?.getUserMedia && u.cameraBtn) {
			u.cameraBtn.disabled = true;
			u.cameraBtn.setAttribute('aria-disabled', 'true');
			u.cameraBtn.title = 'This browser cannot open a camera';
		}

		bind(u.xrBtn, 'click', () => this._enterAR());
		bind(u.addBtn, 'click', () => (u.tray.hidden ? this._openTray() : this._closeTray()));
		bind(u.trayClose, 'click', () => this._closeTray());
		bind(u.tray, 'click', (e) => { if (e.target === u.tray) this._closeTray(); });
		bind(u.emptyAdd, 'click', () => this._openTray());
		bind(u.emptyCamera, 'click', () => this._startCamera());
		bind(u.emptyForge, 'click', () => u.forgeInput?.focus());

		bind(u.forgeForm, 'submit', (e) => {
			e.preventDefault();
			this._startForge(u.forgeInput?.value);
		});

		bind(u.clearBtn, 'click', () => this._clearWithUndo());
		bind(u.photoBtn, 'click', () => this._capturePhoto());
		bind(u.qrBtn, 'click', () => this._openQr());
		bind(u.qrClose, 'click', () => this._closeQr());
		bind(u.qrModal, 'click', (e) => { if (e.target === u.qrModal) this._closeQr(); });

		bind(u.arClose, 'click', () => this._closeArSheet());
		bind(u.arModal, 'click', (e) => { if (e.target === u.arModal) this._closeArSheet(); });
		bind(u.arGo, 'click', () => this._onArGo());
		bind(u.arXr, 'click', () => { this._closeArSheet(); this._toggleXR(); });
		bind(u.arQr, 'click', () => { this._closeArSheet(); this._openQr(); });
		bind(u.arPicker, 'click', (e) => {
			const chip = e.target.closest('[data-ar-id]');
			if (!chip) return;
			const next = this.placements.find((pl) => pl.id === chip.dataset.arId);
			if (next) this._showArTarget(next);
		});

		bind(u.selbar, 'click', (e) => this._onSelbarClick(e));

		bind(u.roomBtn, 'click', () => this._openRoomModal());
		bind(u.roomClose, 'click', () => this._closeRoomModal());
		bind(u.roomModal, 'click', (e) => { if (e.target === u.roomModal) this._closeRoomModal(); });
		bind(u.roomCreate, 'click', () => this._createRoomFromUI());
		bind(u.roomJoinForm, 'submit', (e) => {
			e.preventDefault();
			this._joinRoomFromUI();
		});
		bind(u.roomCopy, 'click', () => this._copyRoomInvite());
		bind(u.roomLeave, 'click', () => {
			this._leaveRoom();
			this._renderRoomModal();
		});

		// Canvas gestures
		const c = u.canvas;
		bind(c, 'pointerdown', (e) => this._onPointerDown(e));
		bind(c, 'pointermove', (e) => this._onPointerMove(e));
		bind(c, 'pointerup', (e) => this._onPointerUp(e));
		bind(c, 'pointercancel', () => { this._pointer = null; });
		bind(c, 'touchstart', (e) => this._onTouchStart(e), { passive: true });
		bind(c, 'touchmove', (e) => this._onTouchMove(e), { passive: true });
		bind(c, 'touchend', () => this._onTouchEnd(), { passive: true });

		this._onKeyDown = this._onKeyDown.bind(this);
		document.addEventListener('keydown', this._onKeyDown);

		this._onOrientationAbsolute = (e) => { this._absoluteOrientation = true; this._onDeviceOrientation(e); };
		this._onOrientation = (e) => { if (!this._absoluteOrientation) this._onDeviceOrientation(e); };
		window.addEventListener('deviceorientationabsolute', this._onOrientationAbsolute, true);
		window.addEventListener('deviceorientation', this._onOrientation, true);

		this._onResize = () => this._resize();
		window.addEventListener('resize', this._onResize);
		this._onPageHide = () => {
			this._stopCamera();
			this.xrSession?.end();
			this.net?.destroy();
		};
		window.addEventListener('pagehide', this._onPageHide);

		// The host element can resize without the window doing so (a flex layout,
		// a drawer opening), and a stale drawing buffer looks like a broken canvas.
		if (typeof ResizeObserver !== 'undefined') {
			this._ro = new ResizeObserver(() => this._resize());
			this._ro.observe(u.root);
		}

		this._wireTrayTabs();
	}

	_boot() {
		this._resize();
		this._updateCount();
		this._updateRoomButton();
		this._startLoop();

		// One AR button, labelled for what this device will actually do. An iPhone
		// has no WebXR, but it has ARKit through Quick Look, and offering it the
		// camera-passthrough approximation instead would be strictly worse: the
		// native viewer gets real plane detection, real scale and real occlusion.
		arCapability().then((cap) => {
			this.arMode = cap;
			const btn = this.ui.xrBtn;
			if (!btn || cap === 'none') return;
			btn.hidden = false;
			const label = btn.querySelector('.ars-ar-label');
			if (cap === 'webxr') {
				if (label) label.textContent = 'Immersive AR';
				btn.setAttribute('aria-label', 'Enter immersive augmented reality and place models on real surfaces');
			} else {
				if (label) label.textContent = 'Place in your space';
				btn.setAttribute('aria-label', 'Open this in your device AR viewer and place it in your real space');
			}
		});
		// Desktop leads with the QR hand-off; a phone is already the target device.
		const coarse = window.matchMedia?.('(pointer: coarse)').matches;
		if (!coarse && this.ui.qrBtn) this.ui.qrBtn.hidden = false;

		const bootRoom = normalizeRoomCode(this.config.urlRoom || '');
		this._restoreScene({ skipLocal: !!bootRoom }).then(() => {
			if (bootRoom) this._joinRoom(bootRoom);
			if (this.config.urlPrompt && this.config.urlPrompt.length >= 3 && this.ui.forgeInput) {
				this.ui.forgeInput.value = this.config.urlPrompt;
				this._startForge(this.config.urlPrompt);
			}
		});
	}

	// ── Status + counters ─────────────────────────────────────────────────────

	_setStatus(message, { warn = false, sticky = false, actionLabel = '', onAction = null } = {}) {
		const node = this.ui.status;
		if (!node) return;
		clearTimeout(this._statusTimer);
		node.textContent = '';
		if (!message) {
			node.hidden = true;
			return;
		}
		node.hidden = false;
		node.classList.toggle('is-warn', warn);
		node.appendChild(el('span', { text: message }));
		if (actionLabel && onAction) {
			node.appendChild(el('button', {
				type: 'button', class: 'ars-status-action', text: actionLabel,
				onclick: () => { this._setStatus(null); onAction(); },
			}));
		}
		if (!sticky) this._statusTimer = setTimeout(() => { node.hidden = true; }, 5200);
	}

	_updateCount() {
		const n = this.placements.length;
		const { count, clearBtn, empty, photoBtn } = this.ui;
		if (count) {
			if (this.net && this.net.status === 'online' && this._presence.count > 1) {
				count.textContent = `${this._presence.count} here · ${n} ${n === 1 ? 'model' : 'models'}`;
				count.hidden = false;
			} else {
				count.textContent = n === 1 ? '1 model' : `${n} models`;
				count.hidden = n === 0;
			}
		}
		if (clearBtn) clearBtn.hidden = n === 0;
		if (empty) empty.hidden = n > 0;
		if (photoBtn) photoBtn.disabled = n === 0;
	}

	// ── Placements ────────────────────────────────────────────────────────────

	// A placement's LOGICAL scale: the size the user chose, independent of the
	// spawn-in animation. While a model eases in, group.scale is a fraction of the
	// target, and persisting that would clamp it to the minimum on the next load.
	_logicalScale(p) {
		if (p.spawnT < 1) return p.group.userData._targetScale ?? 1;
		return p.group.scale.x;
	}

	_saveScene() {
		if (this.config.persist === false) return;
		try {
			localStorage.setItem(this.config.persistKey, serializeScene(
				this.placements.filter((p) => this._isMine(p)).map((p) => ({
					src: p.src,
					title: p.title,
					x: p.group.position.x,
					z: p.group.position.z,
					yaw: p.yaw,
					scale: this._logicalScale(p),
				})),
			));
		} catch {
			// Storage full or blocked: the live scene is unaffected.
		}
	}

	_select(p) {
		this.selected = p;
		const { selbar, selName } = this.ui;
		if (!selbar) return;
		if (!p) {
			selbar.hidden = true;
			this.selRing.visible = false;
			this._emit('select', { placement: null });
			return;
		}
		selbar.hidden = false;
		if (selName) selName.textContent = p.title || 'Model';
		this.selRing.visible = !this.xrSession;
		this._positionSelRing();
		this._warmQuickLook();
		this._emit('select', { placement: publicPlacement(p, this) });
	}

	_positionSelRing() {
		const p = this.selected;
		if (!p) return;
		this.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);
		this.selRing.scale.setScalar(r / 0.34);
	}

	// One load per GLB source no matter how many copies are placed.
	_loadTemplate(src) {
		let tpl = this._templates.get(src);
		if (!tpl) {
			tpl = this._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,
				};
			});
			this._templates.set(src, tpl);
			tpl.then((t) => this._templatesReady.set(src, t))
				.catch(() => this._templates.delete(src)); // a failed load stays retryable
		}
		return tpl;
	}

	// Cloned per placement so ten copies of one crate are ten independent models.
	// SkeletonUtils handles skinned characters; a plain .clone() breaks bone binding.
	_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 clip gets the universal idle retargeted onto its
		// own rig: never a bind-pose statue. Best-effort and async: props and
		// undriveable rigs resolve null and stay static.
		let idlePromise = null;
		if (!mixer && tpl.skinned && this.config.animations?.enabled !== false) {
			idlePromise = mountIdle(inner, {
				manifestUrl: this.config.animations?.manifestUrl,
				clip: this.config.animations?.clip,
				sourceUrl: src,
			}).catch(() => null);
		}
		return { group, mixer, idlePromise };
	}

	_makeShadow(radius) {
		if (!this.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: this.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
	// line-up instead of a z-fighting pile.
	_nudgeSpawn(pt) {
		let { x, z } = pt;
		for (let attempt = 0; attempt < 8; attempt++) {
			const clash = this.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 };
	}

	async _addModel({ src, title = '', poster = '' } = {}, {
		x = null, z = null, yaw = null, scale = null, announce = true, persist = true,
		remote = false, netId = null, ownerId = null,
	} = {}) {
		const url = normalizeGlbUrl(src);
		if (!url) {
			this._setStatus('That link is not a loadable https GLB.', { warn: true });
			return null;
		}
		if (this.placements.length >= this._maxPlacements) {
			this._setStatus(`Scene is full (${this._maxPlacements} models). Remove one to add more.`, { warn: true });
			return null;
		}
		if (announce) this._setStatus(`Loading ${title || 'model'}…`, { sticky: true });

		let tpl;
		try {
			tpl = await this._loadTemplate(url);
		} catch (err) {
			log.warn('model load failed', url, err);
			this._setStatus(`Couldn't load ${title || 'that model'}: the file may be gone or blocked by CORS.`, {
				warn: true, actionLabel: 'Retry', onAction: () => this._addModel({ src: url, title }),
			});
			return null;
		}

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

		const shadow = this._makeShadow(tpl.radius);
		if (shadow) {
			shadow.position.set(px, 0.004, pz);
			shadow.scale.setScalar(group.scale.x);
			shadow.visible = !this.xrSession; // the XR session draws its own anchored shadows
			this.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, 160),
			poster,
			group,
			shadow,
			mixer,
			idle: null,
			yaw: yawV,
			baseRadius: tpl.radius,
			height: tpl.height || 0,
			spawnT: this.reducedMotion ? 1 : 0,
			netId: netId || null,
			ownerId: remote ? ownerId : null,
			remote,
			_lastNetSend: 0,
		};
		idlePromise?.then((mgr) => {
			if (!mgr) return;
			// Removed before the clip arrived: release the manager rather than leak it.
			if (this.placements.includes(placement)) placement.idle = mgr;
			else mgr.detach();
		});
		group.userData._targetScale = group.scale.x;
		if (!this.reducedMotion) group.scale.setScalar(0.001);

		this.placements.push(placement);
		if (placement.netId) this._netModels.set(placement.netId, placement);
		if (!remote) this._armed = { src: url, title: placement.title };
		this._updateCount();
		if (!remote) this._select(placement);
		if (persist) this._saveScene();

		// Broadcast a locally-added model to the shared room exactly once.
		if (!remote && this.net && this.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 = this.clientId;
			this._netModels.set(wireId, placement);
			this.net.spawn(this._placementWire(placement, wireId));
		}

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

	_removePlacement(p, { persist = true, broadcast = true } = {}) {
		const i = this.placements.indexOf(p);
		if (i === -1) return;
		this.placements.splice(i, 1);
		if (p.netId) {
			this._netModels.delete(p.netId);
			if (broadcast && this.net?.status === 'online' && this._isMine(p)) this.net.remove(p.netId);
		}
		p.idle?.detach();
		p.idle = null;
		this.xrSession?.release(p.group);
		this.scene.remove(p.group);
		if (p.shadow) {
			this.scene.remove(p.shadow);
			p.shadow.geometry?.dispose();
			p.shadow.material?.dispose();
		}
		// Geometry and materials belong to the shared template: other copies still
		// use them, so only the per-placement shadow above is disposed.
		if (this.selected === p) this._select(this.placements[this.placements.length - 1] ?? null);
		releaseQuickLook(this._arCacheKey(p));
		this._arKeys.delete(this._arCacheKey(p));
		// The sheet may be listing a model that no longer exists.
		if (this.ui.arModal && !this.ui.arModal.hidden) {
			this._showArTarget(this._arTarget === p ? this._arDefaultTarget() : this._arTarget);
		}
		this._updateCount();
		if (persist) this._saveScene();
		this._emit('remove', { src: p.src, title: p.title });
	}

	_clearWithUndo() {
		if (!this.placements.length) return;
		const items = this.getScene();
		for (const p of [...this.placements]) this._removePlacement(p, { persist: false });
		this._saveScene();
		this._emit('clear', { items });
		this._setStatus('Scene cleared.', {
			actionLabel: 'Undo',
			onAction: async () => {
				for (const it of items) {
					await this._addModel({ src: it.src, title: it.title }, {
						x: it.x, z: it.z, yaw: it.yaw, scale: it.scale, announce: false,
					});
				}
			},
		});
	}

	_onSelbarClick(e) {
		const btn = e.target.closest('[data-act]');
		const p = this.selected;
		if (!btn || !p) return;
		const act = btn.dataset.act;
		if ((act === 'rotate' || act === 'remove') && !this._isMine(p)) {
			this._setStatus('That model belongs to someone else in the room.', { warn: true });
			return;
		}
		if (act === 'rotate') {
			p.yaw += Math.PI / 4;
			p.group.rotation.y = p.yaw;
			p._lastNetSend = 0;
			this._netBroadcastTransform(p);
			this._saveScene();
		} else if (act === 'duplicate') {
			this._addModel({ src: p.src, title: p.title }, { yaw: p.yaw, scale: this._logicalScale(p) });
		} else if (act === 'remove') {
			this._removePlacement(p);
			this._setStatus('Removed.', {
				actionLabel: 'Undo',
				onAction: () => this._addModel({ src: p.src, title: p.title }, {
					x: p.group.position.x, z: p.group.position.z, yaw: p.yaw, scale: this._logicalScale(p),
				}),
			});
		}
	}

	// ── Restore + deep links ──────────────────────────────────────────────────

	async _restoreScene({ skipLocal = false } = {}) {
		// A `#s=` hash is a full shared arrangement: it opens like a document,
		// replacing the working scene rather than merging into it.
		const hashParams = new URLSearchParams(String(location.hash || '').replace(/^#/, ''));
		const shared = skipLocal ? [] : sceneFromHashParam(hashParams.get('s'));

		let items = shared;
		if (!items.length && !skipLocal && this.config.persist !== false) {
			try { items = deserializeScene(localStorage.getItem(this.config.persistKey)); } catch { items = []; }
		}
		for (const it of items) {
			await this._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 any already
		// restored at an arranged spot.
		const have = new Set(this.placements.map((p) => p.src));
		for (const it of this.config.urlModels || []) {
			if (have.has(it.src)) continue;
			await this._addModel(it, { announce: false });
		}
		if (this.placements.length) {
			this._select(this.placements[this.placements.length - 1]);
			if (shared.length) this._setStatus('Shared scene loaded, exactly as arranged. Clear to start fresh.');
			else this._setStatus(this.config.urlModels?.length ? 'Models loaded: turn on the camera to see them in your space.' : 'Your scene is back.');
		}
		this._saveScene();
	}

	// ── Camera passthrough ────────────────────────────────────────────────────

	_applyCameraFov() {
		const track = this.mediaStream?.getVideoTracks?.()[0];
		if (track) {
			const s = track.getSettings?.() ?? {};
			if (Number.isFinite(s.width) && s.width > 0) this.arTrackW = s.width;
			if (Number.isFinite(s.height) && s.height > 0) this.arTrackH = s.height;
		}
		if (!this.arActive || !(this.arTrackW > 0) || !(this.arTrackH > 0)) return;
		const { width, height } = this._viewportSize();
		this.camera.fov = deriveVerticalFovDeg({
			trackWidth: this.arTrackW,
			trackHeight: this.arTrackH,
			viewWidth: width,
			viewHeight: height,
			diagFovDeg: DEFAULT_DIAG_FOV_DEG,
		});
		this.camera.updateProjectionMatrix();
	}

	// Passthrough has no lighting-estimation API, so the room is read from the
	// video itself: mean brightness drives intensity, mean colour drives a gentle
	// white balance. A model in a dim bedroom stops glowing like a studio shot.
	_sampleCameraLight() {
		const probe = this._lightProbe;
		const video = this.ui.video;
		if (!this.arActive || !probe?.ctx || !video?.videoWidth) return;
		let data;
		try {
			probe.ctx.drawImage(video, 0, 0, 16, 16);
			data = probe.ctx.getImageData(0, 0, 16, 16).data;
		} catch {
			return; // frame not readable yet
		}
		const { intensity, tint } = roomLightFromPixels(data);
		this.hemi.intensity += (intensity * HEMI_BASE - this.hemi.intensity) * 0.4;
		this.sun.intensity += (intensity * SUN_BASE - this.sun.intensity) * 0.4;
		this._roomTint.setRGB(tint.r, tint.g, tint.b);
		this.hemi.color.lerp(this._roomTint, 0.4);
		this.sun.color.lerp(this._roomTint, 0.4);
	}

	_startLightMatching() {
		if (this._lightTimer || !this._lightProbe) return;
		this._lightTimer = setInterval(() => this._sampleCameraLight(), 2000);
		this._sampleCameraLight();
	}

	_stopLightMatching() {
		clearInterval(this._lightTimer);
		this._lightTimer = null;
		this.hemi.intensity = HEMI_BASE;
		this.sun.intensity = SUN_BASE;
		this.hemi.color.setHex(0xffffff);
		this.sun.color.setHex(0xffffff);
	}

	async _startCamera() {
		if (this.arTransitioning || this.arActive || this.xrSession) return;
		if (!navigator.mediaDevices?.getUserMedia) {
			this._setStatus('This browser cannot open the camera: the 3D preview still works.', { warn: true });
			return;
		}
		this.arTransitioning = true;
		try {
			this._setStatus('Starting camera…', { sticky: true });
			try {
				this.mediaStream = await navigator.mediaDevices.getUserMedia({
					video: { facingMode: { ideal: 'environment' } },
					audio: false,
				});
			} catch (err) {
				if (err?.name === 'NotAllowedError') {
					this._setStatus('Camera permission is blocked. Allow it in your browser settings, then try again.', {
						warn: true, sticky: true, actionLabel: 'Try again', onAction: () => this._startCamera(),
					});
				} else {
					this._setStatus(`The camera did not start (${err?.message ?? err}).`, {
						warn: true, actionLabel: 'Try again', onAction: () => this._startCamera(),
					});
				}
				return;
			}
			const { video, root, cameraBtn } = this.ui;
			if (video) video.srcObject = this.mediaStream;
			this.arActive = true;
			root.classList.add('is-ar');
			cameraBtn?.classList.add('is-active');
			cameraBtn?.setAttribute('aria-pressed', 'true');
			this.grid.visible = false;
			this.scene.fog = null;
			this._userLooked = true;
			video?.play?.().catch(() => { /* autoplay policy: the srcObject still renders */ });
			this._applyCameraFov();
			this._startLightMatching();
			await this._startGyro();
			// Be honest about what this view is. Passthrough is a phone's gyroscope
			// over a camera feed: it turns with you, but it has no plane detection
			// and no positional tracking, so walking around does not hold a model
			// to a spot on the real floor. Reading that as broken tracking is
			// exactly the wrong conclusion to leave someone with when the device
			// has a real AR viewer one tap away.
			if (this.arMode === 'quicklook' || this.arMode === 'sceneviewer') {
				this._setStatus('Camera on. This preview turns with your phone; to lock a model to your real floor, place it in AR.', {
					actionLabel: 'Place in AR', onAction: () => this._openArSheet(),
				});
			} else {
				this._setStatus('Camera on: your models are in the room. Look around.');
			}
			this._emit('camera', { active: true });
		} finally {
			this.arTransitioning = false;
		}
	}

	_stopCamera() {
		if (this.mediaStream) {
			this.mediaStream.getTracks().forEach((t) => { try { t.stop(); } catch { /* already stopped */ } });
			this.mediaStream = null;
		}
		const { video, root, cameraBtn } = this.ui;
		if (video) video.srcObject = null;
		const was = this.arActive;
		this.arActive = false;
		this._stopLightMatching();
		root?.classList.remove('is-ar');
		cameraBtn?.classList.remove('is-active');
		cameraBtn?.setAttribute('aria-pressed', 'false');
		this.grid.visible = !this.xrSession;
		if (!this.xrSession) this.scene.fog = this._fog;
		this.camera.fov = 58;
		this.camera.updateProjectionMatrix();
		this.gyroBase = null;
		this._userLooked = false;
		this.arTrackW = 0;
		this.arTrackH = 0;
		if (was) this._emit('camera', { active: false });
		this._framePreview();
	}

	/**
	 * Hand the rear camera to the device's own AR viewer, and take it back after.
	 *
	 * The camera is a single-client resource on a phone. Leave the page's
	 * `getUserMedia` stream running and Quick Look starts ARKit against a camera
	 * another process is already holding: the model appears, and then world
	 * tracking and plane detection never converge, so it drifts with the phone
	 * instead of settling on the floor. It looks exactly like a broken anchor and
	 * it is not one. The immersive WebXR path has always released the camera for
	 * the same reason; the native hand-off has to as well.
	 *
	 * Synchronous on purpose: it runs in the same tick as the tap that opens the
	 * viewer, and an `await` in front of it costs the user gesture Safari needs.
	 */
	_yieldCameraToNativeAr() {
		if (this._cameraYielded) return;
		this._cameraYielded = true;
		this._cameraWasOn = this.arActive;
		this._stopCamera();
		// Nothing on this page is visible under the AR viewer, and a WebGL loop
		// still running at 60fps behind it is competing with ARKit for the same
		// GPU and the same thermal budget on a device that is about to do plane
		// detection. Stop drawing until the person comes back.
		this._stopLoop();
		// Quick Look presents over the page rather than navigating away, so the
		// return is a visibility change, not a load. `focus` is the backstop for
		// the iOS versions that never mark the page hidden underneath it.
		this._onArReturn = () => {
			if (typeof document !== 'undefined' && document.visibilityState !== 'visible') return;
			this._reclaimCameraAfterNativeAr();
		};
		document.addEventListener('visibilitychange', this._onArReturn);
		window.addEventListener('focus', this._onArReturn);
	}

	/** Restart the passthrough the person had running before AR took the camera. */
	_reclaimCameraAfterNativeAr() {
		if (!this._cameraYielded) return;
		this._cameraYielded = false;
		if (this._onArReturn) {
			document.removeEventListener('visibilitychange', this._onArReturn);
			window.removeEventListener('focus', this._onArReturn);
			this._onArReturn = null;
		}
		if (this._destroyed || this.xrSession) return;
		this._startLoop();
		if (this.arActive || !this._cameraWasOn) return;
		this._cameraWasOn = false;
		// Permission is already granted for this page, so this normally resolves
		// without a prompt. When a browser insists on a fresh gesture, _startCamera
		// puts a "Try again" action in the status line rather than failing silently.
		this._startCamera().catch((err) => log.warn('camera did not come back after AR', err));
	}

	_screenAngle() {
		try {
			const a = screen.orientation?.angle;
			if (Number.isFinite(a)) return a;
		} catch { /* older browsers */ }
		return Number(window.orientation) || 0;
	}

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

	async _startGyro() {
		// iOS 13+ gates DeviceOrientationEvent behind a user-gesture permission; the
		// camera tap we are inside satisfies it.
		try {
			if (typeof DeviceOrientationEvent !== 'undefined' && typeof DeviceOrientationEvent.requestPermission === 'function') {
				const state = await DeviceOrientationEvent.requestPermission();
				if (state !== 'granted') {
					this._setStatus('Motion access is off: drag to look around instead.', { warn: true });
					return;
				}
			}
		} catch {
			return; // declined prompt: drag-look still works
		}
		this.gyroBase = {
			alpha: this._devAlpha,
			beta: screenPitchDeg(this._devBeta, this._devGamma, this._screenAngle()),
			yaw: this.cameraYaw,
			pitch: this.cameraPitch,
		};
	}
	// ── Pointer + touch gestures (XR has its own) ─────────────────────────────

	_viewportSize() {
		const r = this.ui.root.getBoundingClientRect();
		return {
			width: Math.max(1, Math.round(r.width || window.innerWidth)),
			height: Math.max(1, Math.round(r.height || window.innerHeight)),
			left: r.left,
			top: r.top,
		};
	}

	_setNdc(clientX, clientY) {
		const v = this._viewportSize();
		this._ndc.set(((clientX - v.left) / v.width) * 2 - 1, -((clientY - v.top) / v.height) * 2 + 1);
	}

	_placementAt(clientX, clientY) {
		if (!this.placements.length) return null;
		this._setNdc(clientX, clientY);
		this._raycaster.setFromCamera(this._ndc, this.camera);
		const hits = this._raycaster.intersectObjects(this.placements.map((p) => p.group), true);
		if (!hits.length) return null;
		let obj = hits[0].object;
		while (obj) {
			const found = this.placements.find((p) => p.group === obj);
			if (found) return found;
			obj = obj.parent;
		}
		return null;
	}

	_floorPointAt(clientX, clientY) {
		this._setNdc(clientX, clientY);
		this._raycaster.setFromCamera(this._ndc, this.camera);
		const hits = this._raycaster.intersectObject(this.rayPlane);
		return hits.length ? hits[0].point : null;
	}

	_onPointerDown(e) {
		if (this.xrSession) return;
		if (this._pinch.active || performance.now() - this._pinchEndedAt < 350) return;
		this._pointer = {
			x: e.clientX,
			y: e.clientY,
			placement: this._placementAt(e.clientX, e.clientY),
			lookYaw: this.cameraYaw,
			lookPitch: this.cameraPitch,
			moved: false,
		};
	}

	_onPointerMove(e) {
		const down = this._pointer;
		if (!down || this.xrSession || this._pinch.active) return;
		const dx = e.clientX - down.x;
		const dy = e.clientY - down.y;
		if (Math.hypot(dx, dy) > 6) down.moved = true;
		if (!down.moved) return;

		if (down.placement && this._isMine(down.placement)) {
			// Drag a model along the floor.
			const pt = this._floorPointAt(e.clientX, e.clientY);
			if (!pt) return;
			const p = down.placement;
			p.group.position.x = pt.x;
			p.group.position.z = pt.z;
			p.shadow?.position.set(pt.x, 0.004, pt.z);
			if (this.selected === p) this._positionSelRing();
			this._netBroadcastTransform(p);
		} else if (!down.placement && !(this.arActive && this.gyroBase)) {
			// Drag-look, but only when the gyro is not already steering the view.
			this._userLooked = true;
			this.cameraYaw = down.lookYaw + dx * 0.0042;
			this.cameraPitch = clampPitch(down.lookPitch + dy * 0.0032, PITCH_MIN, PITCH_MAX);
		}
	}

	_onPointerUp(e) {
		const down = this._pointer;
		if (!down || this.xrSession) return;
		const wasTap = !down.moved
			&& Math.hypot(e.clientX - down.x, e.clientY - down.y) <= 8
			&& !this._pinch.active
			&& performance.now() - this._pinchEndedAt >= 350;
		if (wasTap) {
			this._select(down.placement); // null deselects
		} else if (down.placement && down.moved && this._isMine(down.placement)) {
			down.placement._lastNetSend = 0; // force the settle broadcast through
			this._netBroadcastTransform(down.placement);
			this._saveScene();
			this._setStatus(null);
		}
		this._pointer = null;
	}

	/** Two fingers: pinch resizes, twist rotates: on the selected (or last) model. */
	_gestureTarget() {
		const t = this.selected ?? this.placements[this.placements.length - 1] ?? null;
		return t && this._isMine(t) ? t : null;
	}

	_onTouchStart(e) {
		if (this.xrSession || e.touches.length !== 2) return;
		const target = this._gestureTarget();
		if (!target) return;
		this._pointer = null; // the pair owns the gesture: no drag, no tap
		pinchStart(this._pinch, touchDist(e.touches), target.group.scale.x);
		this._twist = { startAngle: touchAngle(e.touches), baseYaw: target.yaw, placement: target };
	}

	_onTouchMove(e) {
		if (this.xrSession || e.touches.length !== 2) return;
		const target = this._twist?.placement;
		if (!target) return;
		const s = pinchMove(this._pinch, touchDist(e.touches));
		if (s != null) {
			target.group.scale.setScalar(s);
			target.group.userData._targetScale = s;
			target.shadow?.scale.setScalar(s);
			if (this.selected === target) this._positionSelRing();
		}
		target.yaw = this._twist.baseYaw + twistDelta(this._twist.startAngle, touchAngle(e.touches));
		target.group.rotation.y = target.yaw;
		this._netBroadcastTransform(target);
	}

	_onTouchEnd() {
		this._warmQuickLook();
		const s = pinchEnd(this._pinch);
		const target = this._twist?.placement;
		if (s != null) {
			this._pinchEndedAt = performance.now();
			this._saveScene();
		}
		if (target) {
			target._lastNetSend = 0;
			this._netBroadcastTransform(target);
		}
		this._twist = null;
	}

	// ── Keyboard ──────────────────────────────────────────────────────────────
	// Arrows nudge the selected model camera-relative (Shift for fine), R rotates,
	// D duplicates, Delete removes, Escape closes whatever is open. The mouse
	// never has to leave the scene.

	_onKeyDown(e) {
		if (this._destroyed) return;
		if (!this.ui.root.isConnected) return;
		if (e.target.closest?.('input, textarea, select')) {
			if (e.key === 'Escape') e.target.blur();
			return;
		}
		if (e.key === 'Escape') {
			if (!this.ui.tray.hidden) this._closeTray();
			else if (!this.ui.roomModal.hidden) this._closeRoomModal();
			else if (!this.ui.arModal.hidden) this._closeArSheet();
			else if (!this.ui.qrModal.hidden) this._closeQr();
			else this._select(null);
			return;
		}
		if (!this.ui.tray.hidden || !this.ui.qrModal.hidden || !this.ui.arModal.hidden
			|| !this.ui.roomModal.hidden || this.xrSession) return;
		const p = this.selected;
		if (!p) return;
		const editable = this._isMine(p);

		if (e.key.startsWith('Arrow')) {
			if (!editable) return;
			e.preventDefault();
			const step = e.shiftKey ? 0.02 : 0.1;
			const fwd = this.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 = e.key === 'ArrowUp' ? fwd
				: e.key === 'ArrowDown' ? fwd.negate()
					: e.key === 'ArrowLeft' ? right.negate()
						: right;
			p.group.position.addScaledVector(move, step);
			p.shadow?.position.set(p.group.position.x, 0.004, p.group.position.z);
			this._positionSelRing();
			this._netBroadcastTransform(p);
			this._saveScene();
		} else if (e.key === 'r' || e.key === 'R') {
			if (!editable) return;
			p.yaw += Math.PI / 4;
			p.group.rotation.y = p.yaw;
			p._lastNetSend = 0;
			this._netBroadcastTransform(p);
			this._saveScene();
		} else if (e.key === 'd' || e.key === 'D') {
			e.preventDefault();
			this._addModel({ src: p.src, title: p.title }, { yaw: p.yaw, scale: this._logicalScale(p) });
		} else if (e.key === 'Delete' || e.key === 'Backspace') {
			if (!editable) return;
			e.preventDefault();
			this._removePlacement(p);
			this._setStatus('Removed.', {
				actionLabel: 'Undo',
				onAction: () => this._addModel({ src: p.src, title: p.title }, {
					x: p.group.position.x, z: p.group.position.z, yaw: p.yaw, scale: this._logicalScale(p),
				}),
			});
		}
	}

	// ── Model tray ────────────────────────────────────────────────────────────

	_wireTrayTabs() {
		const strip = this.ui.trayTabs;
		if (!strip) return;
		for (const [i, source] of this.sources.entries()) {
			const btn = el('button', {
				type: 'button',
				class: 'ars-tab',
				role: 'tab',
				id: `ars-tab-${i}-${source.id}`,
				'aria-selected': String(i === 0),
				tabindex: i === 0 ? '0' : '-1',
				'data-tab': source.id,
				text: source.label || source.id,
			});
			btn.addEventListener('click', () => this._setTrayTab(source.id));
			strip.appendChild(btn);
		}
		// A role="tablist" owes the keyboard the arrow-key contract.
		strip.addEventListener('keydown', (e) => {
			const tabs = [...strip.querySelectorAll('.ars-tab')];
			const i = tabs.indexOf(document.activeElement);
			if (i === -1) return;
			const last = tabs.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();
			this._setTrayTab(tabs[next].dataset.tab);
			tabs[next].focus();
		});
	}

	_openTray(tab = this._trayTab) {
		const { tray, addBtn, trayClose } = this.ui;
		if (!tray) return;
		this._lastFocus = document.activeElement;
		tray.hidden = false;
		addBtn?.setAttribute('aria-expanded', 'true');
		this._setTrayTab(tab);
		trayClose?.focus?.();
	}

	_closeTray() {
		const { tray, addBtn } = this.ui;
		if (!tray || tray.hidden) return;
		const hadFocus = tray.contains(document.activeElement);
		tray.hidden = true;
		addBtn?.setAttribute('aria-expanded', 'false');
		if (hadFocus) this._restoreFocus(addBtn);
	}

	// 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.
	_restoreFocus(fallback) {
		const target = this._lastFocus && document.contains(this._lastFocus) && !this._lastFocus.hidden
			? this._lastFocus
			: fallback;
		target?.focus?.();
		this._lastFocus = null;
	}

	_setTrayTab(tab) {
		this._trayTab = tab;
		const tabs = [...(this.ui.trayTabs?.querySelectorAll('.ars-tab') || [])];
		for (const b of tabs) {
			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) {
				this.ui.trayBody?.setAttribute('aria-labelledby', b.id);
				b.scrollIntoView?.({ block: 'nearest', inline: 'nearest' });
			}
		}
		this._renderTray();
	}

	async _renderTray() {
		const body = this.ui.trayBody;
		if (!body) return;
		const tab = this._trayTab;
		const source = this.sources.find((s) => s.id === tab);
		if (!source) return;
		if (source.kind === 'link' || source.id === 'link') {
			this._renderLinkTab(body);
			return;
		}

		body.textContent = '';
		body.appendChild(el('div', { class: 'ars-tray-loading' }, [
			el('span', { class: 'ars-spinner', 'aria-hidden': 'true' }), 'Loading models…',
		]));

		let items;
		try {
			// `live` sources (recents) change as you work, so they are never cached.
			if (!source.live && this._trayCache.has(tab)) items = this._trayCache.get(tab);
			else {
				items = await source.list();
				if (!source.live) this._trayCache.set(tab, items);
			}
		} catch (err) {
			log.warn('source failed', tab, err);
			if (this._trayTab !== tab) return;
			body.textContent = '';
			body.appendChild(el('div', { class: 'ars-tray-empty' }, [
				el('p', { text: `Couldn't load ${source.label || 'these models'} right now.` }),
				el('button', {
					type: 'button', class: 'ars-btn', text: 'Retry',
					onclick: () => { this._trayCache.delete(tab); this._renderTray(); },
				}),
			]));
			return;
		}
		if (this._trayTab !== tab) return;

		if (!items.length) {
			body.textContent = '';
			body.appendChild(el('div', { class: 'ars-tray-empty' }, [
				el('p', { text: source.emptyCopy || 'Nothing here yet.' }),
				this.forge
					? el('button', {
						type: 'button', class: 'ars-btn ars-btn-primary', text: 'Generate a model',
						onclick: () => { this._closeTray(); this.ui.forgeInput?.focus(); },
					})
					: null,
			]));
			return;
		}
		this._renderList(body, source, items);
	}

	_renderList(body, source, items) {
		body.textContent = '';
		const searchable = source.searchable ?? items.length > 24;
		let shown = LIST_SLICE;
		let search = null;

		if (searchable) {
			search = el('input', {
				class: 'ars-search', type: 'search', autocomplete: 'off',
				placeholder: `Search ${items.length} models…`,
				'aria-label': `Search ${source.label || 'models'}`,
			});
			body.appendChild(search);
		}
		if (source.hint) body.appendChild(el('p', { class: 'ars-hint', text: source.hint }));

		const list = el('ul', { class: 'ars-item-list' });
		const more = el('div', { class: 'ars-more' });
		body.appendChild(list);
		body.appendChild(more);

		const paint = () => {
			const q = (search?.value || '').trim().toLowerCase();
			const matches = q ? items.filter((o) => (o.keywords || o.title || '').toLowerCase().includes(q)) : items;
			list.textContent = '';
			for (const item of matches.slice(0, shown)) list.appendChild(this._trayItem(item));
			more.textContent = '';
			if (matches.length > shown) {
				const left = matches.length - shown;
				more.appendChild(el('button', {
					type: 'button', class: 'ars-btn',
					text: `Show ${Math.min(LIST_SLICE, left)} more (${left} left)`,
					onclick: () => { shown += LIST_SLICE; paint(); },
				}));
			} else if (!matches.length) {
				more.appendChild(el('p', { class: 'ars-hint', text: 'Nothing matches that search.' }));
			}
		};
		search?.addEventListener('input', () => { shown = LIST_SLICE; paint(); });
		paint();
	}

	_trayItem(item) {
		const label = item.title || 'Model';
		const thumb = el('span', { class: 'ars-item-thumb' });
		if (item.poster) {
			const img = el('img', { src: item.poster, alt: '', loading: 'lazy', decoding: 'async' });
			// A thumbnail that 404s would otherwise leave a broken-image glyph in the
			// grid, which makes the whole tray look broken.
			img.addEventListener('error', () => {
				thumb.textContent = '';
				thumb.appendChild(el('span', { class: 'ars-item-cube', 'aria-hidden': 'true', text: '◆' }));
			}, { once: true });
			thumb.appendChild(img);
		} else {
			thumb.appendChild(el('span', { class: 'ars-item-cube', 'aria-hidden': 'true', text: '◆' }));
		}
		const btn = el('button', {
			type: 'button', class: 'ars-item-add',
			title: item.title || '',
			'aria-label': `Add ${label} to your space`,
			onclick: () => {
				this._closeTray();
				this._addModel({ src: item.src, title: label, poster: item.poster });
			},
		}, [
			thumb,
			el('span', { class: 'ars-item-title', text: label }),
			el('span', { class: 'ars-item-cta', text: 'Add' }),
		]);
		return el('li', { class: 'ars-item' }, [btn]);
	}

	_renderLinkTab(body) {
		body.textContent = '';
		const input = el('input', {
			class: 'ars-search', type: 'url', inputmode: 'url', required: true,
			placeholder: 'https://example.com/model.glb', 'aria-label': 'GLB model URL',
		});
		const form = el('form', {}, [
			el('label', { class: 'ars-hint', for: '', text: 'Paste a link to any .glb model' }),
			el('div', { class: 'ars-link-row' }, [input, el('button', { type: 'submit', class: 'ars-btn ars-btn-primary', text: 'Add' })]),
			el('p', { class: 'ars-hint', text: 'Any https .glb works, as long as the host allows cross-origin requests.' }),
		]);
		form.addEventListener('submit', (e) => {
			e.preventDefault();
			const url = normalizeGlbUrl(input.value);
			if (!url) {
				this._setStatus('That link is not a loadable https GLB.', { warn: true });
				input.focus();
				return;
			}
			this._closeTray();
			this._addModel({ src: url, title: filenameLabel(url) });
		});
		body.appendChild(form);
	}

	// ── Generation ────────────────────────────────────────────────────────────

	_forgeChip(state, label = '', elapsedS = null) {
		const chip = this.ui.chip;
		if (!chip) return;
		chip.dataset.state = state;
		chip.hidden = state === 'idle';
		const text = chip.querySelector('.ars-chip-label');
		const time = chip.querySelector('.ars-chip-elapsed');
		if (text) text.textContent = label;
		if (time) time.textContent = elapsedS == null ? '' : `${Math.round(elapsedS)}s`;
	}

	async _startForge(rawPrompt) {
		const prompt = String(rawPrompt || '').trim();
		if (!this.forge || prompt.length < 3 || this._forgeBusy) return null;
		this._forgeBusy = true;
		const seq = ++this._forgeSeq;
		if (this.ui.forgeGo) this.ui.forgeGo.disabled = true;
		const started = Date.now();
		this._forgeChip('working', 'Sending your prompt…', 0);
		const ticker = setInterval(() => {
			if (this.ui.chip?.dataset.state === 'working') {
				const label = this.ui.chip.querySelector('.ars-chip-label')?.textContent || '';
				this._forgeChip('working', label, (Date.now() - started) / 1000);
			}
		}, 1000);

		try {
			const model = await this.forge.generate(prompt, {
				onProgress: (s) => {
					if (seq !== this._forgeSeq) return;
					this._forgeChip('working', s.message, s.elapsedMs / 1000);
				},
			});
			if (seq !== this._forgeSeq) return null;
			rememberRecent({ src: model.src, title: model.prompt, poster: model.poster }, this._recentKey);
			this._trayCache.delete('recent');
			this._forgeChip('idle');
			if (this.ui.forgeInput) this.ui.forgeInput.value = '';
			await this._addModel({ src: model.src, title: model.title, poster: model.poster }, { announce: false });
			this._setStatus('Generated and placed. Pinch to resize, drag to move.');
			this._emit('generate', { model });
			return model;
		} catch (err) {
			if (seq === this._forgeSeq) {
				this._forgeChip('error', err?.message || 'Generation failed.');
				setTimeout(() => {
					if (this.ui.chip?.dataset.state === 'error') this._forgeChip('idle');
				}, 6500);
			}
			this._emit('generate-error', { error: err, prompt });
			return null;
		} finally {
			clearInterval(ticker);
			if (seq === this._forgeSeq) {
				this._forgeBusy = false;
				if (this.ui.forgeGo) this.ui.forgeGo.disabled = false;
			}
		}
	}

	// ── Entering AR ───────────────────────────────────────────────────────────

	/**
	 * Take this device into AR by its best available path. WebXR keeps the whole
	 * scene in the page; everything else hands one model to the platform's own AR
	 * viewer, which is the only way to get real ARKit / ARCore placement there.
	 */
	_enterAR() {
		// Immersive AR keeps the whole arrangement in the page, so a device that
		// has it goes straight in: an extra sheet in front of a one-tap experience
		// is friction, not polish. Everywhere else the hand-off is not instant and
		// not obvious, and the sheet is what makes it both.
		if (this.arMode === 'webxr') return this._toggleXR();
		this._openArSheet();
		return Promise.resolve();
	}

	// ── The AR hand-off sheet ─────────────────────────────────────────────────

	/**
	 * Cache identity for one placement's USDZ. The scale is in the key because it
	 * is baked into the export: someone who pinches a chair to half size and taps
	 * AR must get the half-size chair, not the cached full-size one.
	 */
	_arCacheKey(p) {
		return `${p.src}|${p.group.scale.x.toFixed(3)}`;
	}

	/**
	 * The USDZ bytes for one placement.
	 *
	 * Exported from the copy already standing in the scene, so there is no second
	 * download and Quick Look receives the pose and the size on screen. A model
	 * the exporter chokes on falls back to a clean conversion of the original
	 * file rather than failing the tap.
	 */
	async _targetUsdz(p) {
		const { objectToUsdzBlob, glbUrlToUsdzBlob } = await import('./usdz.js');
		try {
			return await objectToUsdzBlob(p.group);
		} catch (err) {
			log.warn('live-scene USDZ export failed, refetching the source', err);
			return glbUrlToUsdzBlob(p.src);
		}
	}

	/**
	 * A picture of the model the sheet is about to send, rendered from the model
	 * itself.
	 *
	 * A catalogue poster would be easier, but half the ways a model reaches this
	 * studio (a pasted URL, a generation still warming its thumbnail) have no
	 * poster at all, and a 200px empty box with a placeholder glyph in it is the
	 * kind of detail that makes a product feel unfinished. This renders the real
	 * thing, at the size and in the pose it is standing in the scene, off-screen
	 * into a render target so the live canvas never flickers.
	 *
	 * Best-effort by design: a context loss or a stubbed WebGL implementation
	 * returns null and the sheet falls back to its glyph.
	 *
	 * @param {object} p     The placement to portray
	 * @param {number} [size] Square edge, in device pixels
	 * @returns {string|null} a data: URL
	 */
	_renderArPreview(p, size = 384) {
		// An immersive session owns the renderer and its frame buffer; borrowing it
		// for a thumbnail mid-session is not worth a dropped XR frame.
		if (this.xrSession) return null;
		let target = null;
		try {
			const model = cloneSkinnedScene(p.group);
			model.position.set(0, 0, 0);
			model.rotation.set(0, 0, 0);
			model.updateMatrixWorld(true);

			const box = new Box3().setFromObject(model);
			if (box.isEmpty()) return null;
			const center = box.getCenter(new Vector3());
			const radius = Math.max(box.getSize(new Vector3()).length() / 2, 0.01);

			const scene = new Scene();
			scene.add(model);
			// Lit brighter than the room is: this is a product shot of the model,
			// not a preview of the scene's lighting, and dark props read as a
			// silhouette at anything subtler.
			scene.add(new HemisphereLight(0xffffff, 0x3a3a48, 3.4));
			const key = new DirectionalLight(0xffffff, 3.6);
			key.position.set(1.4, 2.2, 1.8);
			const fill = new DirectionalLight(0xdfe4ff, 1.5);
			fill.position.set(-1.6, 0.9, -1.2);
			scene.add(key, fill);

			const fov = 32;
			const cam = new PerspectiveCamera(fov, 1, radius / 100, radius * 100);
			// Three-quarter view from slightly above: the angle a product shot uses,
			// and the one that reads as a solid object rather than a flat card.
			const dist = (radius / Math.sin((fov * Math.PI) / 360)) * 1.06;
			cam.position.set(center.x + dist * 0.62, center.y + dist * 0.42, center.z + dist * 0.66);
			cam.lookAt(center);

			target = new WebGLRenderTarget(size, size, { depthBuffer: true });
			const prevTarget = this.renderer.getRenderTarget();
			this.renderer.setRenderTarget(target);
			this.renderer.clear();
			this.renderer.render(scene, cam);
			const pixels = new Uint8Array(size * size * 4);
			this.renderer.readRenderTargetPixels(target, 0, 0, size, size, pixels);
			this.renderer.setRenderTarget(prevTarget);

			const canvas = document.createElement('canvas');
			canvas.width = size;
			canvas.height = size;
			const ctx = canvas.getContext('2d');
			const image = ctx.createImageData(size, size);
			// WebGL reads bottom-up; a canvas is top-down.
			const stride = size * 4;
			for (let row = 0; row < size; row++) {
				image.data.set(pixels.subarray((size - 1 - row) * stride, (size - row) * stride), row * stride);
			}
			ctx.putImageData(image, 0, 0);
			return canvas.toDataURL('image/png');
		} catch (err) {
			log.warn('AR preview render failed', err);
			return null;
		} finally {
			target?.dispose();
		}
	}

	/** Which model the AR button would send right now. */
	_arDefaultTarget() {
		return this.selected || this.placements[this.placements.length - 1] || null;
	}

	/**
	 * Convert the likely AR target ahead of the tap, so the tap is instant.
	 *
	 * This is the whole reason Quick Look works here rather than appearing to do
	 * nothing: Safari opens `rel="ar"` only while the page holds user activation,
	 * and a conversion started inside the tap handler outlives it. Warming is
	 * debounced because a pinch changes the cache key on every frame.
	 */
	_warmQuickLook() {
		if (this._destroyed || this.arMode !== 'quicklook') return;
		clearTimeout(this._arWarmTimer);
		this._arWarmTimer = setTimeout(() => {
			if (this._destroyed) return;
			const target = this._arDefaultTarget();
			if (!target) return;
			const key = this._arCacheKey(target);
			if (isQuickLookReady(key)) return;
			this._arKeys.add(key);
			prepareNativeAr(
				{ src: target.src, title: target.title, key, build: () => this._targetUsdz(target) },
			).catch((err) => {
				// A warm-up failure is not the user's problem yet: the sheet retries
				// the same conversion in front of them, with a real error and a
				// retry button, if they ever ask for it.
				log.warn('AR warm-up failed', err);
			});
		}, 900);
	}

	/**
	 * Open the sheet that hands one model to the device's AR viewer.
	 * @param {object} [placement] Defaults to the selected model, then the last one.
	 */
	_openArSheet(placement) {
		const u = this.ui;
		if (!u.arModal) return;
		this._lastFocus = document.activeElement;
		u.arModal.hidden = false;
		this._showArTarget(placement || this._arDefaultTarget());
		// aria-modal is a promise that focus is inside the dialog.
		(u.arGo.hidden || u.arGo.disabled ? u.arClose : u.arGo)?.focus?.();
		this._emit('ar-sheet', { open: true });
	}

	_closeArSheet() {
		const { arModal, xrBtn } = this.ui;
		if (!arModal || arModal.hidden) return;
		const hadFocus = arModal.contains(document.activeElement);
		arModal.hidden = true;
		this._arToken++; // abandon any conversion still in flight for this sheet
		if (hadFocus) this._restoreFocus(xrBtn);
		this._emit('ar-sheet', { open: false });
	}

	_setArStatus(message, { state = '' } = {}) {
		const node = this.ui.arStatus;
		if (!node) return;
		node.textContent = '';
		node.classList.toggle('is-error', state === 'error');
		node.classList.toggle('is-ready', state === 'ready');
		if (!message) return;
		if (state === 'busy') node.appendChild(el('span', { class: 'ars-spinner', 'aria-hidden': 'true' }));
		node.appendChild(el('span', { text: message }));
	}

	/** Render the sheet for one target and start preparing it. */
	_showArTarget(target) {
		const u = this.ui;
		if (!u.arModal || u.arModal.hidden) return;
		this._arToken++;
		this._arHandoff = null;
		this._arTarget = target || null;

		const goLabel = u.arGo.querySelector('.ars-ar-go-label');
		this._arRetry = null;
		u.arXr.hidden = this.arMode !== 'webxr';
		u.arQr.hidden = true;
		u.arPicker.hidden = true;
		u.arPicker.textContent = '';

		if (!target) {
			u.arThumb.textContent = '🪄';
			u.arName.textContent = 'Nothing to place yet';
			u.arHint.textContent = 'Add a model to the scene and it can stand on your real floor at its real size.';
			this._setArStatus(null);
			u.arGo.hidden = false;
			u.arGo.disabled = false;
			u.arGo.removeAttribute('aria-busy');
			if (goLabel) goLabel.textContent = 'Browse models';
			// The hexagon means "place this"; there is nothing to place yet.
			u.arGo.querySelector('.ars-ar-go-icon').hidden = true;
			return;
		}

		u.arThumb.textContent = '◆';
		const preview = this._renderArPreview(target) || target.poster;
		if (preview) {
			const img = el('img', { src: preview, alt: '' });
			// A poster that 404s would leave a broken-image glyph in the sheet.
			img.addEventListener('error', () => { u.arThumb.textContent = '◆'; }, { once: true });
			u.arThumb.textContent = '';
			u.arThumb.appendChild(img);
		}
		u.arName.textContent = target.title || 'Model';

		if (this.placements.length > 1) {
			u.arPicker.hidden = false;
			for (const p of this.placements) {
				u.arPicker.appendChild(el('button', {
					type: 'button', class: 'ars-ar-chip', 'data-ar-id': p.id,
					'aria-pressed': p === target ? 'true' : 'false',
					text: p.title || 'Model',
				}));
			}
		}

		if (this.arMode === 'none') {
			u.arHint.textContent = 'AR needs a phone. Open this scene on your iPhone or Android and the model stands on your real floor.';
			this._setArStatus(null);
			u.arGo.hidden = true;
			u.arQr.hidden = false;
			return;
		}

		u.arHint.textContent = 'Point your device at a flat surface, then drag to place it. It arrives at real size.';
		u.arGo.hidden = false;
		u.arGo.querySelector('.ars-ar-go-icon').hidden = false;
		if (goLabel) goLabel.textContent = 'Place in your space';
		this._prepareArTarget(target);
	}

	/**
	 * Get the hand-off ready before the person taps for it.
	 *
	 * Scene Viewer needs nothing prepared, so it enables straight away. Quick
	 * Look needs a USDZ, which is why the button says so while it converts
	 * instead of sitting there looking broken for two seconds.
	 */
	async _prepareArTarget(target) {
		const u = this.ui;
		const token = this._arToken;
		const key = this._arCacheKey(target);
		const warm = this.arMode !== 'quicklook' || isQuickLookReady(key);

		if (!warm) {
			u.arGo.disabled = true;
			u.arGo.setAttribute('aria-busy', 'true');
			this._setArStatus('Preparing it for AR…', { state: 'busy' });
		}
		this._arKeys.add(key);
		try {
			const handoff = await prepareNativeAr({
				src: target.src, title: target.title, key, build: () => this._targetUsdz(target),
			}, { fallbackUrl: this.config.shareBaseUrl });
			if (token !== this._arToken || this._destroyed) return;
			this._arHandoff = handoff;
			u.arGo.disabled = false;
			u.arGo.removeAttribute('aria-busy');
			this._setArStatus(warm ? null : 'Ready.', { state: 'ready' });
			// Put the thumb back on the button that is now armed, but never steal
			// focus from a control the person moved to while they waited.
			const idle = document.activeElement === document.body || document.activeElement === u.arModal;
			if (!warm && idle) u.arGo.focus?.();
		} catch (err) {
			if (token !== this._arToken || this._destroyed) return;
			log.warn('AR preparation failed', err);
			u.arGo.disabled = true;
			u.arGo.removeAttribute('aria-busy');
			this._setArStatus(`Could not prepare this model for AR (${err?.message || err}).`, { state: 'error' });
			// The primary button stays the primary action: it just becomes the
			// retry, rather than leaving a dead button and a second one to hunt for.
			this._arRetry = target;
			u.arGo.disabled = false;
			u.arGo.querySelector('.ars-ar-go-label').textContent = 'Try again';
			u.arGo.querySelector('.ars-ar-go-icon').hidden = true;
			this._emit('native-ar-error', { error: err, src: target.src });
		}
	}

	/**
	 * The tap that opens AR.
	 *
	 * Everything expensive already happened, so this is deliberately synchronous
	 * from the click through to the anchor activation: put an `await` in front of
	 * `open()` and iOS drops the user gesture and silently refuses to open Quick
	 * Look.
	 */
	_onArGo() {
		if (!this._arTarget) {
			this._closeArSheet();
			this._openTray();
			return;
		}
		if (this._arRetry) {
			this._showArTarget(this._arRetry);
			return;
		}
		const handoff = this._arHandoff;
		if (!handoff) return;
		const { src, title } = this._arTarget;
		this._yieldCameraToNativeAr();
		try {
			handoff.open();
		} catch (err) {
			log.warn('native AR failed to open', err);
			this._setArStatus(`Could not open AR (${err?.message || err}).`, { state: 'error' });
			this._emit('native-ar-error', { error: err, src });
			return;
		}
		this._emit('native-ar', { src, title, viewer: handoff.viewer });
		this._closeArSheet();
		this._setStatus('Point at the floor, then drag to place it.');
	}

	/**
	 * Open one model in the device's native AR viewer. On iOS the GLB is
	 * converted to USDZ on the device first, which is why this reports progress:
	 * a couple of silent seconds after a tap reads as a dead button.
	 *
	 * @param {object} [placement] Defaults to the selected model, then the last one.
	 */
	async _placeNative(placement) {
		const target = placement || this.selected || this.placements[this.placements.length - 1];
		if (!target) {
			this._setStatus('Add a model first, then place it in your space.', { warn: true });
			return null;
		}
		if (this._nativeArBusy) return null;
		this._nativeArBusy = true;
		const btn = this.ui.xrBtn;
		btn?.setAttribute('aria-busy', 'true');

		this._arKeys.add(this._arCacheKey(target));
		const STAGES = {
			download: 'Fetching the model…',
			parse: 'Reading the model…',
			convert: 'Preparing it for AR…',
			open: 'Opening AR…',
		};
		this._setStatus(STAGES.download, { sticky: true });
		if (this.arMode === 'quicklook' || this.arMode === 'sceneviewer') this._yieldCameraToNativeAr();
		try {
			const opened = await placeInYourSpace(
				{
					src: target.src,
					title: target.title,
					key: this._arCacheKey(target),
					build: () => this._targetUsdz(target),
				},
				{
					onProgress: (stage) => this._setStatus(STAGES[stage] || 'Preparing AR…', { sticky: true }),
					fallbackUrl: this.config.shareBaseUrl,
				},
			);
			if (opened === 'none') {
				this._setStatus('This device has no AR viewer. Open this scene on a phone instead.', {
					warn: true, actionLabel: 'Show QR', onAction: () => this._openQr(),
				});
			} else {
				this._setStatus('Point at the floor, then drag to place it.');
			}
			this._emit('native-ar', { src: target.src, title: target.title, viewer: opened });
			return opened;
		} catch (err) {
			log.warn('native AR failed', err);
			this._setStatus(`Could not open AR for this model (${err?.message || err}).`, {
				warn: true, actionLabel: 'Try again', onAction: () => this._placeNative(target),
			});
			this._emit('native-ar-error', { error: err, src: target.src });
			return null;
		} finally {
			this._nativeArBusy = false;
			btn?.removeAttribute('aria-busy');
		}
	}

	// ── WebXR immersive session ───────────────────────────────────────────────

	async _toggleXR() {
		if (this.xrSession) {
			this.xrSession.end();
			return;
		}
		if (this.arTransitioning) return;
		this.arTransitioning = true;
		try {
			if (this.arActive) this._stopCamera(); // the immersive session owns the rear camera
			const session = new MultiPlaceSession({
				renderer: this.renderer,
				scene: this.scene,
				camera: this.camera,
				domOverlayRoot: this.ui.hud,
				getArmedContent: () => this._armedContent(),
				onPlaced: (group) => {
					const p = this.placements.find((x) => x.group === group);
					if (p) {
						p.yaw = 0;
						this._select(null); // the ring is a fallback-mode affordance
					}
					this._saveScene();
					this._setStatus(`Placed ${this.xrSession?.placedCount ?? ''}: tap another spot to add one more.`);
				},
				getScaleTarget: () => this.placements[this.placements.length - 1]?.group ?? null,
				onScale: (s, { final }) => { if (final) this._saveScene(); },
				onHit: (has) => this.ui.root.classList.toggle('xr-has-floor', has),
				onTracking: (ok) => {
					if (!ok) this._setStatus('Tracking lost: move to a brighter spot with more texture.', { warn: true, sticky: true });
					else this._setStatus(null);
				},
				onFrame: (dt) => {
					for (const p of this.placements) {
						p.mixer?.update(dt);
						p.idle?.update(dt);
					}
				},
				onEnd: () => this._onXREnd(),
			});
			this._stopLoop();
			await session.start();
			this.xrSession = session;
			// Real-world lighting and reflections: created after start() so the
			// addon's sessionstart listener requests the light probe.
			this.estimatedLight = new EstimatedLighting({
				renderer: this.renderer,
				scene: this.scene,
				baseLights: [this.hemi, this.sun],
				onChange: (on) => {
					if (on) this._setStatus('Lit by your room: reflections and shadows match the real light.');
				},
			});
			this.estimatedLight.start();
			this.ui.root.classList.add('is-xr');
			this.grid.visible = false;
			this.scene.fog = null;
			this.selRing.visible = false;
			for (const p of this.placements) if (p.shadow) p.shadow.visible = false;
			this.ui.xrBtn?.classList.add('is-active');
			this.ui.xrBtn?.setAttribute('aria-pressed', 'true');
			this._setStatus('Point at the floor, then tap to place. Every tap adds another model.');
			this._emit('xr', { active: true });
		} catch (err) {
			log.warn('XR session failed', err);
			this.estimatedLight?.dispose();
			this.estimatedLight = null;
			this._startLoop();
			this._setStatus('Could not start immersive AR on this device. Camera mode still works.', { warn: true });
		} finally {
			this.arTransitioning = false;
		}
	}

	/** What the next reticle tap places. An XR select cannot await, so only an
	 *  already-resolved template is placeable. */
	_armedContent() {
		const src = this._armed?.src ?? this.placements[this.placements.length - 1]?.src;
		if (!src) {
			this._setStatus('Pick a model first: Add or generate one, then tap the floor.', { warn: true });
			return null;
		}
		const tpl = this._templatesReady.get(src);
		if (!tpl) {
			this._loadTemplate(src);
			this._setStatus('Model is still loading: one moment, then tap again.', { sticky: true });
			return null;
		}
		const { group, mixer, idlePromise } = this._instantiate(tpl, src);
		const placement = {
			id: `p-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 7)}`,
			src,
			title: this._armed?.title || '',
			poster: '',
			group,
			shadow: null,
			mixer,
			idle: null,
			yaw: 0,
			baseRadius: tpl.radius,
			height: tpl.height || 0,
			spawnT: 1,
			netId: null,
			ownerId: null,
			remote: false,
			_lastNetSend: 0,
		};
		idlePromise?.then((mgr) => {
			if (!mgr) return;
			if (this.placements.includes(placement)) placement.idle = mgr;
			else mgr.detach();
		});
		this.placements.push(placement);
		this._updateCount();
		this._emit('add', { placement: publicPlacement(placement, this), remote: false });
		return group;
	}

	_onXREnd() {
		this.xrSession = null;
		this.estimatedLight?.dispose();
		this.estimatedLight = null;
		this.ui.root.classList.remove('is-xr', 'xr-has-floor');
		this.ui.xrBtn?.classList.remove('is-active');
		this.ui.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 own loop.
		for (const p of this.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);
			}
		}
		this.grid.visible = !this.arActive;
		if (!this.arActive) this.scene.fog = this._fog;
		this._saveScene();
		this._startLoop();
		this._setStatus('Back to the studio view.');
		this._emit('xr', { active: false });
	}

	// ── Photo + QR ────────────────────────────────────────────────────────────

	async _capturePhoto() {
		this.renderer.render(this.scene, this.camera); // fresh pixels under preserveDrawingBuffer
		const blob = await captureComposite({ canvas: this.ui.canvas, video: this.ui.video, isAR: this.arActive });
		if (!blob) {
			this._setStatus('Could not capture the frame.', { warn: true });
			return;
		}
		try {
			const how = await shareOrDownload(blob, {
				filename: 'ar-studio.png',
				title: this.config.branding?.title || 'AR Studio',
			});
			this._setStatus(how === 'shared' ? 'Shared.' : 'Saved to your downloads.');
		} catch (err) {
			if (err?.name !== 'AbortError') this._setStatus('Could not share that photo.', { warn: true });
		}
	}

	_openQr() {
		const { qrModal, qrBox, qrLink } = this.ui;
		if (!qrModal) return;
		this._lastFocus = document.activeElement;
		const url = this.shareUrl();
		if (qrBox) {
			try {
				qrBox.innerHTML = renderQRToSVG(url, { scale: 6, margin: 2, dark: '#0b0b0b', light: '#ffffff' });
			} catch {
				// The arrangement hash can outgrow the encoder; a models-only QR still
				// beats a wall of text, and the full link below keeps the arrangement.
				try {
					qrBox.innerHTML = renderQRToSVG(studioShareUrl(this.config.shareBaseUrl, this.getScene()), {
						scale: 6, margin: 2, dark: '#0b0b0b', light: '#ffffff',
					});
				} catch {
					qrBox.textContent = url;
				}
			}
		}
		if (qrLink) {
			qrLink.href = url;
			qrLink.textContent = url.length > 72 ? `${url.slice(0, 69)}…` : url;
		}
		qrModal.hidden = false;
		// aria-modal is a promise that focus is inside the dialog.
		this.ui.qrClose?.focus?.();
		this._emit('share', { url });
	}

	_closeQr() {
		const { qrModal, qrBtn } = this.ui;
		if (!qrModal || qrModal.hidden) return;
		const hadFocus = qrModal.contains(document.activeElement);
		qrModal.hidden = true;
		if (hadFocus) this._restoreFocus(qrBtn);
	}

	// ── Shared rooms ──────────────────────────────────────────────────────────

	// A model I control: single-player models (no ownerId) and my own room models.
	// Other people's room models stay visible and live but are not mine to edit
	// the server owner-gates too, so this is the local half of the same rule.
	_isMine(p) {
		return !p.ownerId || p.ownerId === this.clientId;
	}

	_placementShared(p) {
		return localToShared({
			x: p.group.position.x,
			z: p.group.position.z,
			yaw: p.yaw,
			scale: this._logicalScale(p),
			height: p.height || 0,
		});
	}

	_placementWire(p, wireId) {
		return { id: wireId, src: p.src, title: p.title, ...this._placementShared(p) };
	}

	// Throttled to ~12 Hz so a drag does not flood the socket.
	_netBroadcastTransform(p) {
		if (!this.net || this.net.status !== 'online' || !p.netId || !this._isMine(p)) return;
		const now = Date.now();
		if (now - (p._lastNetSend || 0) < 80) return;
		p._lastNetSend = now;
		const s = this._placementShared(p);
		this.net.update(p.netId, { relEast: s.relEast, relNorth: s.relNorth, yawDeg: s.yawDeg, scale: s.scale });
	}

	_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 (this.selected === p) this._positionSelRing();
	}

	// Reconcile the room's full model list against local placements: add what
	// appeared, drop remote ones that left, refresh other people's transforms. My
	// own live models are authored locally and never overwritten by their echo.
	_reconcileRemoteModels(models) {
		const serverIds = new Set(models.map((m) => m.id));
		for (const p of [...this.placements]) {
			if (p.remote && p.netId && !serverIds.has(p.netId)) {
				this._removePlacement(p, { persist: false, broadcast: false });
			}
		}
		let fresh = 0;
		for (const m of models) {
			const existing = this._netModels.get(m.id);
			if (existing) {
				if (!this._isMine(existing)) this._applySharedTransform(existing, m);
				continue;
			}
			const local = sharedToLocal(m);
			const mine = !!m.mine || m.ownerId === this.clientId;
			if (!mine) fresh++;
			this._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 ? this.clientId : m.ownerId,
				announce: false, persist: false,
			});
		}
		this._updateCount();
		// After the join burst settles, a new model from someone else is live
		// activity worth surfacing: but never during the initial sync.
		if (this._roomSynced && fresh > 0) {
			this._setStatus(fresh === 1 ? 'Someone added a model to the room.' : `${fresh} models were added to the room.`);
		}
		this._roomSynced = true;
	}

	_applyRemoteModelChange(m) {
		const p = this._netModels.get(m.id);
		if (!p) return;
		if (m.removed) {
			if (p.remote) this._removePlacement(p, { persist: false, broadcast: false });
			return;
		}
		if (!this._isMine(p)) this._applySharedTransform(p, m);
	}

	_wireNet(net) {
		net.on('status', ({ status }) => {
			if (status === 'online') {
				this._setStatus(`Shared room ${this.roomCode} is live: edits sync to everyone here.`);
				this.ui.root.classList.add('is-room');
			} else if (status === 'connecting') {
				this._setStatus(`Joining room ${this.roomCode}…`, { sticky: true });
			} else if (status === 'unavailable' || status === 'failed') {
				this._setStatus('Shared rooms are offline right now: you can still build solo.', { warn: true });
				this._leaveRoom({ silent: true });
			} else if (status === 'offline') {
				this._setStatus('Reconnecting to the room…', { sticky: true });
			}
			this._updateRoomButton();
			this._emit('room', { status, code: this.roomCode });
		});
		net.on('models', (models) => this._reconcileRemoteModels(models));
		net.on('model', (m) => this._applyRemoteModelChange(m));
		net.on('presence', (p) => {
			const prev = this._presence.count;
			this._presence = p;
			this._updateCount();
			if (!this.ui.roomModal.hidden) this._renderRoomModal();
			if (prev > 0 && p.count > prev) {
				this._setStatus(p.count === 2 ? "Someone joined: you're building together now." : 'Someone else joined the room.');
			} else if (prev > 1 && p.count < prev && p.count >= 1) {
				this._setStatus(p.count === 1 ? "You're on your own in the room now." : 'Someone left the room.');
			}
		});
		net.on('reject', (msg) => {
			const why = msg?.reason === 'room_full' ? 'the room is full'
				: msg?.reason === 'owner_full' ? 'you have the maximum models in this room'
					: 'the room declined it';
			this._setStatus(`Couldn't share that model: ${why}.`, { warn: true });
		});
	}

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

	// seed=true is right for CREATE (I am the first one there). JOIN never seeds:
	// entering a room means entering ITS scene, so my solo models stay local and
	// cannot duplicate the server's authoritative copies on a rejoin.
	async _joinRoom(code, { seed = false } = {}) {
		const norm = normalizeRoomCode(code);
		if (!norm) {
			this._setStatus('That room code looks off: check the 6 characters and try again.', { warn: true });
			return;
		}
		this._leaveRoom({ silent: true });
		this._roomSynced = false;
		this.roomCode = norm;
		const net = new StudioNet({
			roomKey: roomKeyForCode(norm),
			clientId: this.clientId,
			name: '',
			url: this.config.rooms?.server || '',
		});
		this.net = net;
		this._wireNet(net);
		await net.connect();
		// A failed connect fires status 'failed' synchronously and the handler nulls
		// `this.net`, so re-check identity rather than dereferencing a dead field.
		if (this.net === net && net.status === 'online') {
			if (seed) this._seedRoom();
			this._roomHeartbeat = setInterval(() => this.net?.heartbeat(), 15000);
			try {
				const url = new URL(location.href);
				url.searchParams.set('room', norm);
				history.replaceState(null, '', url);
			} catch { /* history is unavailable in some embeds */ }
		}
		this._updateRoomButton();
	}

	_createRoom() {
		return this._joinRoom(generateRoomCode(), { seed: true });
	}

	_leaveRoom({ silent = false } = {}) {
		if (this._roomHeartbeat) {
			clearInterval(this._roomHeartbeat);
			this._roomHeartbeat = null;
		}
		if (this.net) {
			try { this.net.destroy(); } catch { /* already destroyed */ }
			this.net = null;
		}
		// Remote models leave with the room; my own stay as a local scene.
		for (const p of [...this.placements]) {
			if (p.remote && !this._isMine(p)) this._removePlacement(p, { persist: false, broadcast: false });
			else { p.netId = null; p.remote = false; }
		}
		this._netModels.clear();
		this.roomCode = '';
		this._presence = { count: 1, names: [] };
		this.ui.root.classList.remove('is-room');
		try {
			const url = new URL(location.href);
			url.searchParams.delete('room');
			history.replaceState(null, '', url);
		} catch { /* history unavailable */ }
		this._updateCount();
		this._updateRoomButton();
		if (!silent) this._setStatus('Left the shared room. Your models are still here.');
	}

	_updateRoomButton() {
		const btn = this.ui.roomBtn;
		if (!btn) return;
		const live = !!this.net && (this.net.status === 'online' || this.net.status === 'connecting');
		btn.classList.toggle('is-active', live);
		// Two labels rather than one rewritten string, so a host that translated the
		// idle label does not lose it the first time the room state changes.
		const idle = btn.querySelector('.ars-room-label');
		const code = btn.querySelector('.ars-room-code-label');
		if (idle) idle.hidden = live;
		if (code) {
			code.hidden = !live;
			code.textContent = live ? (this.roomCode || 'Room') : '';
		}
		if (!this.ui.roomModal.hidden) this._renderRoomModal();
	}

	_renderRoomModal() {
		const online = !!this.net && this.net.status === 'online';
		const { roomIdle, roomLive, roomCode, roomPresence, roomQr } = this.ui;
		if (roomIdle) roomIdle.hidden = online;
		if (roomLive) roomLive.hidden = !online;
		if (!online) return;
		if (roomCode) roomCode.textContent = this.roomCode;
		if (roomPresence) {
			roomPresence.textContent = this._presence.count > 1
				? `${this._presence.count} people are building here.`
				: 'You are the only one here yet: share the code to invite someone.';
		}
		if (roomQr) {
			const url = roomShareUrl(this.config.shareBaseUrl, this.roomCode);
			try {
				roomQr.innerHTML = renderQRToSVG(url, { scale: 5, margin: 2, dark: '#0b0b0b', light: '#ffffff' });
			} catch {
				roomQr.textContent = url;
			}
		}
	}

	_openRoomModal() {
		const m = this.ui.roomModal;
		if (!m) return;
		this._lastFocus = document.activeElement;
		m.hidden = false;
		this._renderRoomModal();
		(this.net?.status === 'online' ? this.ui.roomCopy : this.ui.roomCreate)?.focus?.();
	}

	_closeRoomModal() {
		const m = this.ui.roomModal;
		if (!m || m.hidden) return;
		const hadFocus = m.contains(document.activeElement);
		m.hidden = true;
		if (hadFocus) this._restoreFocus(this.ui.roomBtn);
	}

	async _createRoomFromUI() {
		await this._createRoom();
		this._renderRoomModal();
		// One-tap invite: put the join link on the clipboard immediately, still
		// inside this click's user activation, so hosting is create → paste.
		if (this.net?.status === 'online' && navigator.clipboard?.writeText) {
			try {
				await navigator.clipboard.writeText(roomShareUrl(this.config.shareBaseUrl, this.roomCode));
				this._setStatus(`Room ${this.roomCode} is live: invite link copied. Paste it to a friend.`);
			} catch { /* clipboard blocked: the Copy button is still there */ }
		}
	}

	async _joinRoomFromUI() {
		const input = this.ui.roomJoinInput;
		const code = normalizeRoomCode(input?.value);
		if (!code) {
			this._setStatus('That room code looks off: check the 6 characters.', { warn: true });
			input?.focus?.();
			return;
		}
		await this._joinRoom(code);
		this._renderRoomModal();
	}

	async _copyRoomInvite() {
		const url = roomShareUrl(this.config.shareBaseUrl, this.roomCode);
		const btn = this.ui.roomCopy;
		try {
			const how = await shareUrlOrCopy(url, {
				title: 'Build with me in AR',
				text: `Join my AR Studio room: ${this.roomCode}`,
			});
			if (btn) {
				const old = btn.textContent;
				btn.textContent = how === 'shared' ? 'Shared ✓' : 'Link copied ✓';
				setTimeout(() => { btn.textContent = old; }, 1600);
			}
		} catch (err) {
			if (err?.name !== 'AbortError') window.prompt('Copy this invite link:', url);
		}
	}

	// ── Render loop ───────────────────────────────────────────────────────────

	// Desktop preview has no gyro and no real room to look at, so a model dropped
	// on the floor lands below the eyeline and reads as "nothing happened". Tilt
	// the view down to actually frame what is in the scene: but only until the
	// viewer takes the camera themselves, after which their aim is the truth.
	_framePreview() {
		if (this.arActive || this.xrSession || this._userLooked || !this.placements.length) return;
		let sx = 0;
		let sz = 0;
		let sh = 0;
		for (const p of this.placements) {
			sx += p.group.position.x;
			sz += p.group.position.z;
			sh += (p.height || 0.4) * (p.group.userData._targetScale ?? 1);
		}
		const n = this.placements.length;
		const cx = sx / n;
		const cz = sz / n;
		const centre = (sh / n) * 0.5;
		const dist = Math.hypot(cx - this.camera.position.x, cz - this.camera.position.z);
		if (!(dist > 0.05)) return;
		this.cameraYaw = Math.atan2(cx - this.camera.position.x, -(cz - this.camera.position.z));
		this.cameraPitch = clampPitch(-Math.atan2(this.camera.position.y - centre, dist), PITCH_MIN, PITCH_MAX);
	}

	_applyCameraLook() {
		this.camera.rotation.set(0, 0, 0);
		this.camera.rotateY(this.cameraYaw);
		this.camera.rotateX(this.cameraPitch);
	}

	_tick(t) {
		this._rafId = requestAnimationFrame((next) => this._tick(next));
		const dt = this._prevT ? Math.min(0.1, (t - this._prevT) / 1000) : 0.016;
		this._prevT = t;

		for (const p of this.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 (this.selected) this._positionSelRing();
		this._applyCameraLook();
		this.renderer.render(this.scene, this.camera);
	}

	_startLoop() {
		if (this._rafId === null) {
			this._prevT = 0;
			this._rafId = requestAnimationFrame((t) => this._tick(t));
		}
	}

	_stopLoop() {
		if (this._rafId !== null) {
			cancelAnimationFrame(this._rafId);
			this._rafId = null;
		}
	}

	_resize() {
		const { width, height } = this._viewportSize();
		this.renderer.setSize(width, height, false);
		this.camera.aspect = width / height;
		this.camera.updateProjectionMatrix();
		this._applyCameraFov();
	}

	// ── Public API ────────────────────────────────────────────────────────────

	/**
	 * Add a model to the scene.
	 * @param {{src: string, title?: string, poster?: string}} model
	 * @param {object} [opts] `x` `z` `yaw` `scale` `announce` `persist`
	 * @returns {Promise<object|null>} the placement, or null when it could not load
	 */
	addModel(model, opts) {
		return this._addModel(model, opts);
	}

	/** Remove every model. Returns what was removed, so a host can offer its own undo. */
	clear() {
		const items = this.getScene();
		for (const p of [...this.placements]) this._removePlacement(p, { persist: false });
		this._saveScene();
		this._emit('clear', { items });
		return items;
	}

	/** The current arrangement as plain data: `[{ src, title, x, z, yaw, scale }]`. */
	getScene() {
		return this.placements.map((p) => ({
			src: p.src,
			title: p.title,
			x: p.group.position.x,
			z: p.group.position.z,
			yaw: p.yaw,
			scale: this._logicalScale(p),
		}));
	}

	/** Replace the scene with an arrangement in the shape `getScene()` returns. */
	async setScene(items) {
		this.clear();
		for (const it of Array.isArray(items) ? items : []) {
			await this._addModel({ src: it.src, title: it.title }, {
				x: it.x, z: it.z, yaw: it.yaw, scale: it.scale, announce: false, persist: false,
			});
		}
		this._saveScene();
	}

	/** A link that reopens this exact arrangement, models and transforms included. */
	shareUrl() {
		return studioSceneUrl(this.config.shareBaseUrl, this.getScene());
	}

	/** Generate a model from a prompt and drop it into the scene. */
	generate(prompt) {
		return this._startForge(prompt);
	}

	/** Hand one model to the device's own AR viewer (Quick Look / Scene Viewer). */
	viewInYourSpace(src, title = '') {
		const url = normalizeGlbUrl(src);
		if (!url) return '';
		const launch = buildArLaunchUrl(this.config.origin, url, title, { endpoint: this.config.arLaunchUrl });
		window.open(launch, '_blank', 'noopener');
		return launch;
	}

	/** Turn the camera passthrough on. Call it from a user gesture (iOS requires one). */
	startCamera() { return this._startCamera(); }

	/** Turn the camera passthrough off. */
	stopCamera() { this._stopCamera(); }

	/** Enter or leave the immersive WebXR session. */
	toggleImmersive() { return this._toggleXR(); }

	/**
	 * Take this device into AR by its best path: the immersive session where
	 * WebXR exists, otherwise the platform's own AR viewer.
	 */
	enterAR() { return this._enterAR(); }

	/**
	 * Open one model in the device's native AR viewer (Quick Look on iOS, Scene
	 * Viewer on Android). Defaults to the selected model.
	 * @param {object} [placement]
	 */
	placeInYourSpace(placement) { return this._placeNative(placement); }

	/**
	 * Open the AR hand-off sheet: the screen that prepares one model and then
	 * opens the device's own AR viewer from a single tap.
	 * @param {object} [placement] Defaults to the selected model, then the last one.
	 */
	openArSheet(placement) { this._openArSheet(placement); }

	/** Close the AR hand-off sheet. */
	closeArSheet() { this._closeArSheet(); }

	/** Open a shared room (a new one when `code` is omitted). Returns the code. */
	async openRoom(code) {
		if (code) await this._joinRoom(code);
		else await this._createRoom();
		return this.roomCode;
	}

	/** Leave the shared room, keeping your own models. */
	leaveRoom() { this._leaveRoom(); }

	/** Tear the studio down: camera, socket, listeners, GPU context, DOM. */
	destroy() {
		if (this._destroyed) return;
		this._destroyed = true;
		this._stopLoop();
		this._stopCamera();
		this.xrSession?.end();
		this.net?.destroy();
		if (this._roomHeartbeat) clearInterval(this._roomHeartbeat);
		clearTimeout(this._statusTimer);
		clearTimeout(this._arWarmTimer);
		// Only this studio's own conversions: a second studio on the page may be
		// sharing the cache and still needs its entries.
		for (const key of this._arKeys) releaseQuickLook(key);
		this._arKeys.clear();
		clearInterval(this._lightTimer);
		document.removeEventListener('keydown', this._onKeyDown);
		window.removeEventListener('deviceorientationabsolute', this._onOrientationAbsolute, true);
		window.removeEventListener('deviceorientation', this._onOrientation, true);
		window.removeEventListener('resize', this._onResize);
		window.removeEventListener('pagehide', this._onPageHide);
		if (this._onArReturn) {
			document.removeEventListener('visibilitychange', this._onArReturn);
			window.removeEventListener('focus', this._onArReturn);
			this._onArReturn = null;
		}
		this._ro?.disconnect();
		for (const p of [...this.placements]) this._removePlacement(p, { persist: false, broadcast: false });
		this.shadowTex?.dispose();
		this.selRing.geometry.dispose();
		this.selRing.material.dispose();
		this.renderer.dispose();
		this.ui.root.remove();
		this._listeners.clear();
	}
}

// ── Module-private helpers ───────────────────────────────────────────────────

function prefersReducedMotion() {
	try {
		return !!window.matchMedia?.('(prefers-reduced-motion: reduce)').matches;
	} catch {
		return false;
	}
}

function makeShadowTexture() {
	try {
		const size = 128;
		const cnv = document.createElement('canvas');
		cnv.width = size;
		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;
	}
}

function makeLightProbe() {
	try {
		const cnv = document.createElement('canvas');
		cnv.width = 16;
		cnv.height = 16;
		return { cnv, ctx: cnv.getContext('2d', { willReadFrequently: true }) };
	} catch {
		return null;
	}
}

/** A stable per-browser id. It decides who owns which model in a shared room. */
function readClientId(scope) {
	const key = `${scope || 'ar-studio'}:client`;
	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)}`;
	}
}

/** A readable label from a model URL: `alarm_clock_01.glb` → `Alarm clock 01`. */
function filenameLabel(url) {
	const base = String(url).split('?')[0].split('/').pop() || 'Model';
	const stem = base.replace(/\.(glb|gltf)$/i, '').replace(/[_-]+/g, ' ').trim();
	return stem ? stem.charAt(0).toUpperCase() + stem.slice(1) : 'Linked model';
}

/** The shape a placement takes when it leaves the studio in an event. */
function publicPlacement(p, studio) {
	return {
		id: p.id,
		src: p.src,
		title: p.title,
		x: p.group.position.x,
		z: p.group.position.z,
		yaw: p.yaw,
		scale: studio._logicalScale(p),
		mine: studio._isMine(p),
	};
}