From 35a8bbba50687bd0a68599e1d18566428fbd2f9a Mon Sep 17 00:00:00 2001
From: AlexZ005 <alexz005.info@gmail.com>
Date: Thu, 1 Oct 2026 00:24:04 +0300
Subject: [PATCH 1/5] [feat] perf probe: the roadmap-31 performance table for
 the seven games

- scripts/perf-games.cjs: per game, a fresh page installs the game's modules from their
  real zips, loads its real .tpscene through the Games-tab path (importSessionZip +
  requestLoadSession) from the scenes repo at a git ref (PERF_SCENES_REF, default
  preview-1-17) or a directory, presses Play and the game's own HUD Play/Start, then
  measures 10 s at CPU throttle x4: draw calls + triangles per display frame (every
  render() pass summed), geometries/textures, a texture-MB estimate, lights and
  shadow-casting lights/meshes, meshes/instanced/unculled, p50/p95/p99 frame ms and the
  heap delta. Markdown + JSON into after-31/31-perf/.
- --vr walks a fake XR session's left stick forward the whole window (fakeXR.cjs);
  --profile adds CDP CPU self-time and allocation sampling (collected objects included)
  per function, top 30 each.
- Baseline on 1.17 (Radeon 890M): Waves p50 700 ms, Dungeon Realms ~10 MB/s heap churn,
  Football 336 calls + 7 lights, Jam Room 910 calls.

No behaviour change (a script), so no counterfactual; the table is the artefact.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 scripts/perf-games.cjs | 419 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 419 insertions(+)
 create mode 100644 scripts/perf-games.cjs

diff --git a/scripts/perf-games.cjs b/scripts/perf-games.cjs
new file mode 100644
index 00000000..01300c51
--- /dev/null
+++ b/scripts/perf-games.cjs
@@ -0,0 +1,419 @@
+#!/usr/bin/env node
+// 31-perf P0 — THE PERF PROBE: the roadmap-31 Performance-protocol table for the seven
+// Games-tab games, measured the same way every time so a before/after means something.
+//
+//   node scripts/perf-games.cjs [--label baseline-1.17] [--only waves,football] [--vr]
+//                               [--seconds 10] [--throttle 4] [--out <dir>]
+//
+// Per game, on a FRESH page against a running dev server (APP_URL, default this lane's
+// https://theprototype.app:5263/):
+//   1 install the game's modules from their REAL zips (the sibling modules checkout, or
+//     PERF_MODULES_DIR), through the Modules manager's own zip input
+//   2 load the game's REAL .tpscene through the Games-tab path (`importSessionZip` +
+//     `requestLoadSession`, what `sceneTemplates.loadRemoteScene` runs) — read from the
+//     scenes repo at a git REF (PERF_SCENES_REF, default `preview-1-17`: the games as 1.17
+//     ships them) or a directory (PERF_SCENES_DIR)
+//   3 press the real Play button, then the game's own HUD Play/Start button when it has one
+//     (else the shell is set to `playing`), and with `--vr` a fake XR session walks the left
+//     stick forward the whole time (tests/e2e/fakeXR.cjs — the real per-frame VR path)
+//   4 settle 2 s, then CPU-throttle x4 (CDP `Emulation.setCPUThrottlingRate`) for the
+//     measured window and record: every render() call's draw calls + triangles (summed per
+//     display frame), every rAF frame's duration, and the JS heap before/after
+//   5 read the scene: geometries/textures (renderer.info.memory), a texture-MB estimate
+//     (unique textures, w*h*4 x 4/3 for mips), lights, shadow-casting lights, shadow-casting
+//     meshes, meshes / instanced meshes / meshes with frustumCulled off, shader programs
+//
+// Writes `perf-<label>.md` + `perf-<label>.json` into --out (default
+// /home/deck/.code/lanes-30/after-31/31-perf). Run it under `e2e-slot --exclusive`: the
+// frame times are the whole point, and a second browser on the machine is noise.
+//
+// Budget column = the planner's Quest target: <= 150 draw calls, <= 300k triangles,
+// <= 2 real-time lights, shadows off in Interact.
+const path = require('path');
+const fs = require('fs');
+const { execFileSync } = require('child_process');
+const h = require('../tests/e2e/helpers.cjs');
+const fx = require('../tests/e2e/fakeXR.cjs');
+
+const argv = process.argv.slice(2);
+const arg = (name, fallback) => {
+	const i = argv.indexOf('--' + name);
+	return i >= 0 && argv[i + 1] && !argv[i + 1].startsWith('--') ? argv[i + 1] : fallback;
+};
+const flag = (name) => argv.includes('--' + name);
+
+const LABEL = arg('label', 'run');
+const SECONDS = Number(arg('seconds', '10'));
+const THROTTLE = Number(arg('throttle', '4'));
+const VR = flag('vr');
+const PROFILE = flag('profile');
+const OUT = arg('out', '/home/deck/.code/lanes-30/after-31/31-perf');
+const ONLY = (arg('only', '') || '').split(',').filter(Boolean);
+const ROOT = path.resolve(__dirname, '../..');
+const SCENES_REF = process.env.PERF_SCENES_REF || 'preview-1-17';
+const SCENES_DIR = process.env.PERF_SCENES_DIR || null;
+const SCENES_REPO = process.env.PERF_SCENES_REPO || [path.join(ROOT, 'scenes'), path.join(ROOT, 'theprototype.app-scenes')].find((p) => fs.existsSync(p));
+const MODULES_DIR = process.env.PERF_MODULES_DIR || null;
+
+const BUDGET = { calls: 150, triangles: 300000, lights: 2 };
+
+/** read a file of the scenes repo: a directory override, else `git show REF:path` */
+function sceneFile(rel) {
+	if (SCENES_DIR) {
+		const p = path.join(SCENES_DIR, rel);
+		return fs.existsSync(p) ? fs.readFileSync(p) : null;
+	}
+	if (!SCENES_REPO) return null;
+	try {
+		return execFileSync('git', ['-C', SCENES_REPO, 'show', SCENES_REF + ':' + rel], { maxBuffer: 256 * 1024 * 1024 });
+	} catch {
+		return null;
+	}
+}
+
+/** @param {string} id */
+function zipFor(id) {
+	const p = MODULES_DIR ? path.join(MODULES_DIR, id + '.zip') : h.moduleZipPath(id);
+	return fs.existsSync(p) ? p : null;
+}
+
+async function installZip(page, id, file) {
+	await page.evaluate(() => window.__stores.modulesOpen.set(true));
+	await page.waitForTimeout(400);
+	await page.getByRole('tab', { name: /^User/ }).click();
+	await page.waitForTimeout(200);
+	await page.locator('#install-module-zip').setInputFiles({ name: id + '.zip', mimeType: 'application/zip', buffer: fs.readFileSync(file) });
+	const t0 = Date.now();
+	while (Date.now() - t0 < 30000) {
+		const ids = await page.evaluate(() => window.__stores.moduleSDK.loadedModules.map((m) => m.id));
+		if (ids.includes(id)) break;
+		await page.waitForTimeout(250);
+	}
+	await page.evaluate(() => window.__stores.modulesOpen.set(false));
+	await page.waitForTimeout(300);
+}
+
+/** In-page: start the recorder (render wrapper + rAF frame times). */
+function startRecorder() {
+	const s = window.__stores;
+	let r;
+	s.globalRenderer.subscribe((v) => (r = v))();
+	const rec = { calls: 0, triangles: 0, renders: 0, frames: [], last: 0, on: true, heap0: performance.memory?.usedJSHeapSize ?? null };
+	const inner = r.render;
+	r.render = function (...a) {
+		const out = inner.apply(this, a);
+		const i = this.info?.render;
+		if (rec.on && i) {
+			rec.calls += i.calls;
+			rec.triangles += i.triangles;
+			rec.renders++;
+		}
+		return out;
+	};
+	const tick = (t) => {
+		if (!rec.on) return;
+		if (rec.last) rec.frames.push(t - rec.last);
+		rec.last = t;
+		requestAnimationFrame(tick);
+	};
+	requestAnimationFrame(tick);
+	rec.stop = () => {
+		rec.on = false;
+		r.render = inner;
+	};
+	window.__perfRec = rec;
+}
+
+/** In-page: stop the recorder and read the scene. */
+function readScene() {
+	const s = window.__stores;
+	const rec = window.__perfRec;
+	rec.stop();
+	let r;
+	s.globalRenderer.subscribe((v) => (r = v))();
+	let scene;
+	s.globalScene?.subscribe?.((v) => (scene = v))();
+	if (!scene) {
+		let g;
+		s.objectsGroup.subscribe((v) => (g = v))();
+		scene = g;
+		while (scene?.parent) scene = scene.parent;
+	}
+	const frames = rec.frames.slice().sort((a, b) => a - b);
+	const pct = (q) => (frames.length ? frames[Math.min(frames.length - 1, Math.max(0, Math.ceil(q * frames.length) - 1))] : null);
+	const n = rec.frames.length || 1;
+	let lights = 0,
+		shadowLights = 0,
+		meshes = 0,
+		instanced = 0,
+		instances = 0,
+		unculled = 0,
+		castMeshes = 0,
+		points = 0,
+		objects = 0,
+		skinned = 0;
+	const textures = new Set();
+	scene?.traverseVisible?.((o) => {
+		objects++;
+		if (o.isLight && !o.isAmbientLight && !o.isHemisphereLight) {
+			lights++;
+			if (o.castShadow && r.shadowMap.enabled) shadowLights++;
+		}
+		if (o.isMesh || o.isPoints || o.isLine || o.isSprite) {
+			if (o.isMesh) meshes++;
+			if (o.isPoints) points++;
+			if (o.isSkinnedMesh) skinned++;
+			if (o.isInstancedMesh) {
+				instanced++;
+				instances += o.count;
+			}
+			if (o.frustumCulled === false) unculled++;
+			if (o.isMesh && o.castShadow && r.shadowMap.enabled) castMeshes++;
+			const mats = Array.isArray(o.material) ? o.material : [o.material];
+			for (const m of mats) {
+				if (!m) continue;
+				for (const k in m) if (m[k]?.isTexture) textures.add(m[k]);
+				for (const k in m.uniforms ?? {}) if (m.uniforms[k]?.value?.isTexture) textures.add(m.uniforms[k].value);
+			}
+		}
+	});
+	if (scene?.background?.isTexture) textures.add(scene.background);
+	if (scene?.environment?.isTexture) textures.add(scene.environment);
+	let bytes = 0;
+	for (const t of textures) {
+		const img = t.image;
+		const one = Array.isArray(img) ? img[0] : img;
+		const w = one?.naturalWidth || one?.videoWidth || one?.width || 0;
+		const h = one?.naturalHeight || one?.videoHeight || one?.height || 0;
+		const faces = Array.isArray(img) ? img.length : 1;
+		bytes += w * h * 4 * faces * (t.generateMipmaps === false ? 1 : 4 / 3);
+	}
+	let state = null;
+	s.gameState?.gameState?.subscribe((v) => (state = v?.state ?? null))();
+	return {
+		frames: rec.frames.length,
+		seconds: rec.frames.reduce((a, b) => a + b, 0) / 1000,
+		p50: pct(0.5),
+		p95: pct(0.95),
+		p99: pct(0.99),
+		max: frames[frames.length - 1] ?? null,
+		calls: Math.round(rec.calls / n),
+		triangles: Math.round(rec.triangles / n),
+		rendersPerFrame: Math.round((rec.renders / n) * 10) / 10,
+		geometries: r.info.memory.geometries,
+		textures: r.info.memory.textures,
+		sceneTextures: textures.size,
+		textureMB: Math.round((bytes / 1048576) * 10) / 10,
+		programs: r.info.programs?.length ?? null,
+		lights,
+		shadowLights,
+		castMeshes,
+		shadowMap: r.shadowMap.enabled,
+		objects,
+		meshes,
+		instanced,
+		instances,
+		unculled,
+		points,
+		skinned,
+		pixelRatio: r.getPixelRatio(),
+		heapMB: performance.memory ? Math.round((performance.memory.usedJSHeapSize / 1048576) * 10) / 10 : null,
+		heapDeltaMB: performance.memory && rec.heap0 != null ? Math.round(((performance.memory.usedJSHeapSize - rec.heap0) / 1048576) * 10) / 10 : null,
+		state
+	};
+}
+
+async function probeGame(browser, game) {
+	const bytes = sceneFile(game.scene);
+	if (!bytes) return { slug: game.slug, skipped: 'no scene at ' + (SCENES_DIR || SCENES_REF) + ':' + game.scene };
+	const missing = (game.modules || []).filter((m) => !zipFor(m.id)).map((m) => m.id);
+	if (missing.length) return { slug: game.slug, skipped: 'no zip for ' + missing.join(', ') };
+
+	const peer = await h.setupPage(browser, game.slug, { context: { viewport: { width: 1280, height: 720 } } });
+	const page = peer.page;
+	try {
+		for (const m of game.modules || []) await installZip(page, m.id, zipFor(m.id));
+		await page.evaluate(async (arr) => {
+			const s = window.__stores;
+			const payload = await s.sessions.importSessionZip(new Uint8Array(arr).buffer);
+			if (payload) await s.sessions.requestLoadSession(payload.id);
+		}, Array.from(bytes));
+		await page.waitForTimeout(3000);
+		if (VR) {
+			await fx.install(page);
+			await fx.installSpace(page, { head: [0, 1.6, 0] });
+		}
+		await page.locator('#play-button').click({ timeout: 10000 }).catch(() => page.evaluate(() => window.__stores.isLocked.set(true)));
+		await page.waitForTimeout(1500);
+		const start = page.locator('#hud-layer button', { hasText: /^\W*(Play|Start)\b/i }).first();
+		let started = 'hud';
+		if (await start.count()) await start.click({ timeout: 3000 }).catch(() => (started = 'hud-click-failed'));
+		else started = 'none';
+		await page.waitForTimeout(500);
+		const state = await page.evaluate(() => {
+			let v;
+			window.__stores.gameState.gameState.subscribe((x) => (v = x))();
+			return v?.state ?? null;
+		});
+		if (state === 'menu') {
+			await page.evaluate(() => window.__stores.gameState.setGameState('playing'));
+			started = started === 'hud' ? 'hud+shell' : 'shell';
+		}
+		if (VR) await fx.stick(page, 'left', 0, -1);
+		await page.waitForTimeout(2000);
+		const cdp = await page.context().newCDPSession(page);
+		await cdp.send('Emulation.setCPUThrottlingRate', { rate: THROTTLE });
+		if (PROFILE) {
+			await cdp.send('Profiler.enable');
+			await cdp.send('Profiler.setSamplingInterval', { interval: 250 });
+			await cdp.send('HeapProfiler.enable');
+			await cdp.send('HeapProfiler.startSampling', { samplingInterval: 4096, includeObjectsCollectedByMajorGC: true, includeObjectsCollectedByMinorGC: true });
+			await cdp.send('Profiler.start');
+		}
+		await page.evaluate(startRecorder);
+		await page.waitForTimeout(SECONDS * 1000);
+		/** @type {any} */
+		let profile = null;
+		if (PROFILE) {
+			const cpu = (await cdp.send('Profiler.stop')).profile;
+			const heap = (await cdp.send('HeapProfiler.stopSampling')).profile;
+			profile = { cpu: topSelf(cpu), alloc: topAlloc(heap, SECONDS) };
+		}
+		await cdp.send('Emulation.setCPUThrottlingRate', { rate: 1 });
+		const m = await page.evaluate(readScene);
+		if (profile) m.profile = profile;
+		const errors = h.pageErrors ? h.pageErrors(peer).length : 0;
+		return { slug: game.slug, title: game.title, modules: (game.modules || []).map((x) => x.id), started, pageErrors: errors, ...m };
+	} catch (e) {
+		return { slug: game.slug, error: String(e?.message ?? e).split('\n')[0] };
+	} finally {
+		await page.context().close().catch(() => {});
+	}
+}
+
+/** where a frame is: `fn url:line`, the url trimmed to its path under the app */
+function site(cf) {
+	const url = (cf.url || '').replace(/^https?:\/\/[^/]+/, '').replace(/\?.*$/, '');
+	return (cf.functionName || '(anon)') + ' ' + (url || '(native)') + ':' + (cf.lineNumber + 1);
+}
+
+/** CPU self time per function, top 30, ms over the window (throttled time) */
+function topSelf(p) {
+	const byId = new Map(p.nodes.map((n) => [n.id, n]));
+	const self = new Map();
+	for (let i = 0; i < p.samples.length; i++) {
+		const n = byId.get(p.samples[i]);
+		const dt = (p.timeDeltas[i + 1] ?? p.timeDeltas[i] ?? 0) / 1000;
+		self.set(n.id, (self.get(n.id) ?? 0) + dt);
+	}
+	const agg = new Map();
+	let total = 0;
+	for (const [id, ms] of self) {
+		const k = site(byId.get(id).callFrame);
+		agg.set(k, (agg.get(k) ?? 0) + ms);
+		total += ms;
+	}
+	return {
+		totalMs: Math.round(total),
+		top: [...agg].sort((a, b) => b[1] - a[1]).slice(0, 30).map(([k, ms]) => ({ site: k, ms: Math.round(ms * 10) / 10, pct: Math.round((ms / total) * 1000) / 10 }))
+	};
+}
+
+/** sampled allocation (bytes allocated and still sampled at stop) per function, top 30, KB/s */
+function topAlloc(p, seconds) {
+	const agg = new Map();
+	let total = 0;
+	const walk = (n) => {
+		if (n.selfSize) {
+			const k = site(n.callFrame);
+			agg.set(k, (agg.get(k) ?? 0) + n.selfSize);
+			total += n.selfSize;
+		}
+		for (const c of n.children || []) walk(c);
+	};
+	walk(p.head);
+	return {
+		totalKBps: Math.round(total / 1024 / seconds),
+		top: [...agg].sort((a, b) => b[1] - a[1]).slice(0, 30).map(([k, b]) => ({ site: k, KBps: Math.round((b / 1024 / seconds) * 10) / 10 }))
+	};
+}
+
+function fmt(v, d = 0) {
+	return v == null ? '—' : typeof v === 'number' ? v.toFixed(d) : String(v);
+}
+const over = (v, cap) => (v != null && v > cap ? ' ⚠' : '');
+
+function table(rows) {
+	const head =
+		'| game | calls/frame | tris/frame | geos | tex (MB) | lights (shadow) | cast meshes | meshes / inst / unculled | p50 ms | p95 ms | p99 ms | heap Δ MB | started |\n' +
+		'|---|---:|---:|---:|---:|---:|---:|---|---:|---:|---:|---:|---|';
+	const lines = rows.map((r) =>
+		r.skipped || r.error
+			? `| ${r.slug} | ${r.skipped ? 'SKIP: ' + r.skipped : 'ERROR: ' + r.error} |||||||||||| |`
+			: `| ${r.slug} | ${fmt(r.calls)}${over(r.calls, BUDGET.calls)} | ${fmt(r.triangles)}${over(r.triangles, BUDGET.triangles)} | ${fmt(r.geometries)} | ${fmt(r.textures)} (${fmt(r.textureMB, 1)}) | ${fmt(r.lights)}${over(r.lights, BUDGET.lights)} (${fmt(r.shadowLights)}) | ${fmt(r.castMeshes)} | ${fmt(r.meshes)} / ${fmt(r.instanced)} / ${fmt(r.unculled)} | ${fmt(r.p50, 1)} | ${fmt(r.p95, 1)} | ${fmt(r.p99, 1)} | ${fmt(r.heapDeltaMB, 1)} | ${r.started}${r.state ? ' → ' + r.state : ''} |`
+	);
+	return head + '\n' + lines.join('\n');
+}
+
+(async () => {
+	const index = JSON.parse((sceneFile('index.json') || '{}').toString());
+	let games = (index.games || []).map((g) => ({ slug: g.slug, title: g.title, scene: g.scene, modules: g.modules || [] }));
+	if (ONLY.length) games = games.filter((g) => ONLY.includes(g.slug));
+	if (!games.length) {
+		console.error('no games found (scenes ' + (SCENES_DIR || SCENES_REPO + '@' + SCENES_REF) + ')');
+		process.exit(2);
+	}
+	const browser = await h.launch({ args: [...h.GPU_ARGS, '--enable-precise-memory-info'] });
+	const version = await (async () => {
+		const p = await h.setupPage(browser, 'gpu');
+		const v = await p.page.evaluate(() => {
+			let r;
+			window.__stores.globalRenderer.subscribe((x) => (r = x))();
+			const gl = r.getContext();
+			const ext = gl.getExtension('WEBGL_debug_renderer_info');
+			return { gpu: ext ? gl.getParameter(ext.UNMASKED_RENDERER_WEBGL) : gl.getParameter(gl.RENDERER), app: window.__stores.version?.APP_VERSION ?? null };
+		});
+		await p.page.context().close();
+		return v;
+	})();
+	console.log('GPU: ' + version.gpu);
+	const rows = [];
+	for (const g of games) {
+		const t0 = Date.now();
+		const r = await probeGame(browser, g);
+		rows.push(r);
+		console.log(`${g.slug}: ${r.skipped ? 'SKIP ' + r.skipped : r.error ? 'ERROR ' + r.error : `${r.calls} calls, ${r.triangles} tris, p50 ${fmt(r.p50, 1)} p95 ${fmt(r.p95, 1)} ms`} (${Math.round((Date.now() - t0) / 1000)}s)`);
+	}
+	await browser.close();
+	const meta = {
+		label: LABEL,
+		at: new Date().toISOString(),
+		app: h.URL,
+		gpu: version.gpu,
+		scenes: SCENES_DIR || SCENES_REF,
+		seconds: SECONDS,
+		cpuThrottle: THROTTLE,
+		vr: VR,
+		viewport: '1280x720',
+		budget: BUDGET
+	};
+	const md =
+		`## perf-games — ${LABEL}${VR ? ' (VR-emulated, walking)' : ''}\n\n` +
+		`${meta.at} · ${meta.app} · GPU: ${meta.gpu} · scenes ${meta.scenes} · ${SECONDS} s of Play at CPU x${THROTTLE} · 1280x720\n` +
+		`Quest budget: ≤ ${BUDGET.calls} calls, ≤ ${BUDGET.triangles / 1000}k tris, ≤ ${BUDGET.lights} lights (⚠ = over). calls/tris are per display frame, every render() pass summed (shadow pass included).\n\n` +
+		table(rows) +
+		'\n';
+	fs.mkdirSync(OUT, { recursive: true });
+	let prof = '';
+	for (const r of rows.filter((r) => r.profile)) {
+		prof += `\n### ${r.slug} — CPU self time (${r.profile.cpu.totalMs} ms sampled)\n\n` + r.profile.cpu.top.map((t) => `- ${t.pct}% ${t.ms} ms — ${t.site}`).join('\n') + '\n';
+		prof += `\n### ${r.slug} — sampled allocation incl. collected (${r.profile.alloc.totalKBps} KB/s)\n\n` + r.profile.alloc.top.map((t) => `- ${t.KBps} KB/s — ${t.site}`).join('\n') + '\n';
+	}
+	fs.writeFileSync(path.join(OUT, `perf-${LABEL}.md`), md + prof);
+	fs.writeFileSync(path.join(OUT, `perf-${LABEL}.json`), JSON.stringify({ meta, rows }, null, 2));
+	console.log('\n' + md);
+	console.log('wrote ' + path.join(OUT, `perf-${LABEL}.{md,json}`));
+})().catch((e) => {
+	console.error(e);
+	process.exit(1);
+});

From 9e7ac25ccd16a5ef9a67e3a507b6a2db94bbcfed Mon Sep 17 00:00:00 2001
From: AlexZ005 <alexz005.info@gmail.com>
Date: Thu, 1 Oct 2026 01:14:10 +0300
Subject: [PATCH 2/5] [fix] core stutter: five per-frame costs the perf probe
 found (P1)

Measured with scripts/perf-games.cjs --profile (desktop, CPU x4, Radeon 890M), 1.17 ->
this commit: Waves p50 699.9 -> 16.7 ms, Dungeon Realms p99 116.7 -> 16.8 ms and heap
churn +97 MB/10 s -> none, Football p50 49.9 -> 33.4 ms.

- ModuleContent.svelte: rows (each carrying its THREE group) lived in a deep $state and
  `use:rowMenu={row}` made svelte deep_read the action parameter - the WHOLE scene graph
  through `parent`, every typed-array index, on every refresh (1 s + every pokeScene),
  mounted in every mode incl. VR. 88% of Waves' CPU, ~200 MB/s garbage; Dungeon Realms'
  1 Hz hitch. $state.raw, and the 1 s catch-up skips a hidden list.
- dungeonPlay.dungeonData: a whole-scene getObjectByName per frame from the walker,
  flier and VR walk in EVERY game (a miss walks everything). Hit cached + re-validated by
  parent chain, miss remembered 250 ms; walkable() stops allocating arrays per call.
- flowRuntime: resolveInputs / evalNode input() scanned every edge and, per edge, every
  node (O(consumers x edges x nodes) per tick). Indexed per graph array (nodeById,
  edgesInto), rebuilt only when a graph changes.
- moveSmoothing: a watching peer searched the tree per eased body and pokeScene'd (every
  $objectsGroup subscriber) EVERY frame while a remote physics stream eased. The ease keeps
  its object; the UI hears the motion at 10 Hz and once on landing.
- VRObjectsPanel: always mounted, and rebuilt its row list on every scene poke while
  closed. Only while open.
- perf-games.cjs: --profile names the nearest app frame calling the heaviest functions;
  --vr measures with post/AO off (the headset's direct render), documented as one eye.

Suite perf-stutter (new), one counterfactual guard per fix - with the five fixes reverted:
  deep-reads 0 -> 9 getter reads; edge reads 401 -> 20451; dungeon traversals 1/1 ->
  100/100; eased frames <=1 search + <=1 poke -> 59 + 30; closed-panel rebuilds 0 -> 8.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 scripts/perf-games.cjs                    |  59 ++++++-
 src/components/menu/ModuleContent.svelte  |  18 +-
 src/components/play/VRObjectsPanel.svelte |   5 +-
 src/lib/dungeonPlay.js                    |  51 +++++-
 src/lib/flowRuntime.js                    |  89 +++++++---
 src/lib/moveSmoothing.js                  |  27 ++-
 tests/e2e/perf-stutter.test.cjs           | 195 ++++++++++++++++++++++
 7 files changed, 396 insertions(+), 48 deletions(-)
 create mode 100644 tests/e2e/perf-stutter.test.cjs

diff --git a/scripts/perf-games.cjs b/scripts/perf-games.cjs
index 01300c51..b4d01ff0 100644
--- a/scripts/perf-games.cjs
+++ b/scripts/perf-games.cjs
@@ -15,7 +15,9 @@
 //     ships them) or a directory (PERF_SCENES_DIR)
 //   3 press the real Play button, then the game's own HUD Play/Start button when it has one
 //     (else the shell is set to `playing`), and with `--vr` a fake XR session walks the left
-//     stick forward the whole time (tests/e2e/fakeXR.cjs — the real per-frame VR path)
+//     stick forward the whole time (tests/e2e/fakeXR.cjs — the real per-frame VR path) with
+//     the post stack + AO off, the nearest desktop analogue of a headset's direct render (a
+//     fake session cannot present, so it is still ONE eye at 1280x720 — not a Quest number)
 //   4 settle 2 s, then CPU-throttle x4 (CDP `Emulation.setCPUThrottlingRate`) for the
 //     measured window and record: every render() call's draw calls + triangles (summed per
 //     display frame), every rAF frame's duration, and the JS heap before/after
@@ -190,6 +192,10 @@ function readScene() {
 	}
 	let state = null;
 	s.gameState?.gameState?.subscribe((v) => (state = v?.state ?? null))();
+	// 31-perf: what LOD and the governor were doing (absent on a build without them)
+	const lod = s.lod?.lodStats?.() ?? null;
+	let quality = null;
+	s.qualityGovernor?.qualityState?.subscribe((v) => (quality = v?.level ?? null))();
 	return {
 		frames: rec.frames.length,
 		seconds: rec.frames.reduce((a, b) => a + b, 0) / 1000,
@@ -219,6 +225,9 @@ function readScene() {
 		pixelRatio: r.getPixelRatio(),
 		heapMB: performance.memory ? Math.round((performance.memory.usedJSHeapSize / 1048576) * 10) / 10 : null,
 		heapDeltaMB: performance.memory && rec.heap0 != null ? Math.round(((performance.memory.usedJSHeapSize - rec.heap0) / 1048576) * 10) / 10 : null,
+		lodMeshes: lod ? lod.entries : null,
+		lodCoarse: lod ? lod.drawnCoarse : null,
+		quality,
 		state
 	};
 }
@@ -242,6 +251,14 @@ async function probeGame(browser, game) {
 		if (VR) {
 			await fx.install(page);
 			await fx.installSpace(page, { head: [0, 1.6, 0] });
+			// a headset never runs the desktop post stack (Outline renders XR direct), and a
+			// fake session cannot present — so the nearest desktop analogue of the XR render is
+			// the same scene with post + AO off and a direct frame (A8's no-composite path)
+			await page.evaluate(() => {
+				const s = window.__stores;
+				s.viewMode.set('shaded');
+				s.viewportOverrides.setRenderLayer('post', false);
+			});
 		}
 		await page.locator('#play-button').click({ timeout: 10000 }).catch(() => page.evaluate(() => window.__stores.isLocked.set(true)));
 		await page.waitForTimeout(1500);
@@ -313,9 +330,38 @@ function topSelf(p) {
 		agg.set(k, (agg.get(k) ?? 0) + ms);
 		total += ms;
 	}
+	// WHO CALLS the heaviest functions: for the top 6, the nearest ancestor frame that is
+	// app code (src/ or a module blob) — a svelte runtime or three frame on its own says
+	// what is slow, never why it runs
+	const parent = new Map();
+	for (const n of p.nodes) for (const c of n.children || []) parent.set(c, n.id);
+	const top = [...agg].sort((a, b) => b[1] - a[1]).slice(0, 30);
+	const heavy = new Set(top.slice(0, 6).map(([k]) => k));
+	const callers = new Map();
+	for (const [id, ms] of self) {
+		const k = site(byId.get(id).callFrame);
+		if (!heavy.has(k)) continue;
+		let up = parent.get(id);
+		let found = null;
+		/** @type {string[]} */
+		const chain = [];
+		while (up != null) {
+			const cf = byId.get(up).callFrame;
+			if (/\/src\/|^blob:/.test(cf.url || '')) {
+				found = site(cf);
+				break;
+			}
+			if (cf.functionName !== byId.get(id).callFrame.functionName && chain.length < 4) chain.push(cf.functionName || '(anon)');
+			up = parent.get(up);
+		}
+		if (!found) found = 'no app frame; via ' + (chain.join(' < ') || '-');
+		const key = k + ' <- ' + found;
+		callers.set(key, (callers.get(key) ?? 0) + ms);
+	}
 	return {
 		totalMs: Math.round(total),
-		top: [...agg].sort((a, b) => b[1] - a[1]).slice(0, 30).map(([k, ms]) => ({ site: k, ms: Math.round(ms * 10) / 10, pct: Math.round((ms / total) * 1000) / 10 }))
+		top: top.map(([k, ms]) => ({ site: k, ms: Math.round(ms * 10) / 10, pct: Math.round((ms / total) * 1000) / 10 })),
+		callers: [...callers].sort((a, b) => b[1] - a[1]).slice(0, 20).map(([k, ms]) => ({ site: k, ms: Math.round(ms * 10) / 10 }))
 	};
 }
 
@@ -345,12 +391,12 @@ const over = (v, cap) => (v != null && v > cap ? ' ⚠' : '');
 
 function table(rows) {
 	const head =
-		'| game | calls/frame | tris/frame | geos | tex (MB) | lights (shadow) | cast meshes | meshes / inst / unculled | p50 ms | p95 ms | p99 ms | heap Δ MB | started |\n' +
-		'|---|---:|---:|---:|---:|---:|---:|---|---:|---:|---:|---:|---|';
+		'| game | calls/frame | tris/frame | geos | tex (MB) | lights (shadow) | cast meshes | meshes / inst / unculled | LOD (coarse) | quality | p50 ms | p95 ms | p99 ms | heap Δ MB | started |\n' +
+		'|---|---:|---:|---:|---:|---:|---:|---|---:|---:|---:|---:|---:|---:|---|';
 	const lines = rows.map((r) =>
 		r.skipped || r.error
-			? `| ${r.slug} | ${r.skipped ? 'SKIP: ' + r.skipped : 'ERROR: ' + r.error} |||||||||||| |`
-			: `| ${r.slug} | ${fmt(r.calls)}${over(r.calls, BUDGET.calls)} | ${fmt(r.triangles)}${over(r.triangles, BUDGET.triangles)} | ${fmt(r.geometries)} | ${fmt(r.textures)} (${fmt(r.textureMB, 1)}) | ${fmt(r.lights)}${over(r.lights, BUDGET.lights)} (${fmt(r.shadowLights)}) | ${fmt(r.castMeshes)} | ${fmt(r.meshes)} / ${fmt(r.instanced)} / ${fmt(r.unculled)} | ${fmt(r.p50, 1)} | ${fmt(r.p95, 1)} | ${fmt(r.p99, 1)} | ${fmt(r.heapDeltaMB, 1)} | ${r.started}${r.state ? ' → ' + r.state : ''} |`
+			? `| ${r.slug} | ${r.skipped ? 'SKIP: ' + r.skipped : 'ERROR: ' + r.error} |||||||||||||| |`
+			: `| ${r.slug} | ${fmt(r.calls)}${over(r.calls, BUDGET.calls)} | ${fmt(r.triangles)}${over(r.triangles, BUDGET.triangles)} | ${fmt(r.geometries)} | ${fmt(r.textures)} (${fmt(r.textureMB, 1)}) | ${fmt(r.lights)}${over(r.lights, BUDGET.lights)} (${fmt(r.shadowLights)}) | ${fmt(r.castMeshes)} | ${fmt(r.meshes)} / ${fmt(r.instanced)} / ${fmt(r.unculled)} | ${fmt(r.lodMeshes)} (${fmt(r.lodCoarse)}) | ${fmt(r.quality)} | ${fmt(r.p50, 1)} | ${fmt(r.p95, 1)} | ${fmt(r.p99, 1)} | ${fmt(r.heapDeltaMB, 1)} | ${r.started}${r.state ? ' → ' + r.state : ''} |`
 	);
 	return head + '\n' + lines.join('\n');
 }
@@ -407,6 +453,7 @@ function table(rows) {
 	let prof = '';
 	for (const r of rows.filter((r) => r.profile)) {
 		prof += `\n### ${r.slug} — CPU self time (${r.profile.cpu.totalMs} ms sampled)\n\n` + r.profile.cpu.top.map((t) => `- ${t.pct}% ${t.ms} ms — ${t.site}`).join('\n') + '\n';
+		prof += `\n### ${r.slug} — who calls the heaviest (nearest app frame)\n\n` + r.profile.cpu.callers.map((t) => `- ${t.ms} ms — ${t.site}`).join('\n') + '\n';
 		prof += `\n### ${r.slug} — sampled allocation incl. collected (${r.profile.alloc.totalKBps} KB/s)\n\n` + r.profile.alloc.top.map((t) => `- ${t.KBps} KB/s — ${t.site}`).join('\n') + '\n';
 	}
 	fs.writeFileSync(path.join(OUT, `perf-${LABEL}.md`), md + prof);
diff --git a/src/components/menu/ModuleContent.svelte b/src/components/menu/ModuleContent.svelte
index 8a4964cd..6aef6e10 100644
--- a/src/components/menu/ModuleContent.svelte
+++ b/src/components/menu/ModuleContent.svelte
@@ -23,13 +23,19 @@
 	import { safeStorage } from '$lib/safeStorage';
 	import ContextMenu from '../ContextMenu.svelte';
 
+	// RAW, never a deep $state (31-perf P1): each row carries its THREE group (`row.object`),
+	// and `use:rowMenu={row}` makes svelte `deep_read` an action's parameter whenever it is a
+	// state proxy — which walked the ENTIRE scene graph through `object.parent`, every typed
+	// array index included, on every refresh (1 s + every pokeScene). MEASURED on the Waves
+	// template: 88% of the frame's CPU and ~200 MB/s of garbage (p50 700 ms at CPU x4).
+	// The rows are rebuilt whole by refresh(), so a raw array loses no reactivity.
 	/** @type {any[]} */
-	let rows = $state([]);
+	let rows = $state.raw([]);
 	let open = $state(safeStorage.getItem('objects:moduleContent') !== 'closed');
 	/** @type {Record<string, boolean>} */
 	let expanded = $state({});
 	/** @type {{x: number, y: number, row: any} | null} */
-	let menu = $state(null);
+	let menu = $state.raw(null);
 
 	function refresh() {
 		rows = moduleContentRows(get(globalScene));
@@ -40,7 +46,13 @@
 		refresh();
 	});
 	$effect(() => {
-		const timer = setInterval(refresh, 1000);
+		// the 1 s catch-up is for a list someone can SEE: hidden (object list closed, play
+		// mode), the pokes above still keep it right, and a module's own clock can wait
+		const timer = setInterval(() => {
+			const shown = document.getElementById('module-content');
+			if (rows.length && shown && shown.offsetParent === null) return;
+			refresh();
+		}, 1000);
 		return () => clearInterval(timer);
 	});
 
diff --git a/src/components/play/VRObjectsPanel.svelte b/src/components/play/VRObjectsPanel.svelte
index 6f370cb9..e60052e8 100644
--- a/src/components/play/VRObjectsPanel.svelte
+++ b/src/components/play/VRObjectsPanel.svelte
@@ -40,7 +40,10 @@
 
 	$: topLevel = ($objectsGroup?.children ?? []) as any[]
 	// 215: flattened rows — expanded groups inline their children (indented)
-	$: visibleRows = flattenPanelRows(topLevel, $vrPanelExpanded)
+	// 31-perf P1: only while the panel is OPEN. This component is always mounted (desktop
+	// included) and every pokeScene re-ran the flatten and the row map for a panel nobody
+	// could see — at physics rates in a game
+	$: visibleRows = $vrObjectsPanelOpen ? flattenPanelRows(topLevel, $vrPanelExpanded) : []
 	$: maxScroll = Math.max(0, visibleRows.length - ROWS)
 	// the stick moves a ROW CURSOR (109.4); the page scrolls to keep it visible
 	$: cursor = Math.min(Math.max(0, $vrPanelCursor), Math.max(0, visibleRows.length - 1))
diff --git a/src/lib/dungeonPlay.js b/src/lib/dungeonPlay.js
index b9302fbd..c95947ba 100644
--- a/src/lib/dungeonPlay.js
+++ b/src/lib/dungeonPlay.js
@@ -3,9 +3,45 @@
 // ({grid, width, height, minX, minY, rooms, floorValue}). Pure math — the
 // module owns the data, players/VR/minimap consume it here.
 
+// 31-perf P1: the walker, the flier, the VR walk and the minimap each asked this EVERY
+// FRAME, and `getObjectByName` is a whole-scene traversal — in every game, dungeon or not
+// (a miss walks everything). A hit is cached and re-validated by walking UP its parents
+// (a few steps) to the scene it was asked about; a miss is remembered for MISS_MS, so a
+// scene with no dungeon pays one traversal four times a second instead of per frame.
+const MISS_MS = 250;
+/** @type {any} */ let cachedGroup = null;
+/** @type {any} */ let missScene = null;
+let missAt = -Infinity;
+
+/** @param {any} object @param {any} scene */
+function attachedTo(object, scene) {
+	let o = object;
+	while (o?.parent) o = o.parent;
+	return o === scene;
+}
+
 /** @param {any} scene @returns {any | null} the module's play payload */
 export function dungeonData(scene) {
-	return scene?.getObjectByName('dungeon-module')?.userData?.play ?? null;
+	if (!scene) return null;
+	if (cachedGroup && cachedGroup.name === 'dungeon-module' && attachedTo(cachedGroup, scene)) return cachedGroup.userData?.play ?? null;
+	cachedGroup = null;
+	const now = typeof performance !== 'undefined' ? performance.now() : Date.now();
+	if (missScene === scene && now - missAt < MISS_MS) return null;
+	const found = scene.getObjectByName?.('dungeon-module') ?? null;
+	if (found) {
+		cachedGroup = found;
+		missScene = null;
+		return found.userData?.play ?? null;
+	}
+	missScene = scene;
+	missAt = now;
+	return null;
+}
+
+/** Forget the cached lookup (a test swapping dungeons within the miss window). */
+export function forgetDungeonData() {
+	cachedGroup = null;
+	missScene = null;
 }
 
 /** Can a circle of radius r stand at (x, z)?
@@ -13,14 +49,11 @@ export function dungeonData(scene) {
 export function walkable(data, x, z, r = 0.3) {
 	if (!data) return true;
 	const { grid, width, height, minX, minY, floorValue } = data;
-	for (const [ox, oz] of [
-		[-r, -r],
-		[r, -r],
-		[-r, r],
-		[r, r]
-	]) {
-		const cx = Math.floor(x + ox - minX);
-		const cz = Math.floor(z + oz - minY);
+	// the four corners of the circle's box, without an array of arrays per call (this runs
+	// twice per walking frame)
+	for (let i = 0; i < 4; i++) {
+		const cx = Math.floor(x + (i & 1 ? r : -r) - minX);
+		const cz = Math.floor(z + (i & 2 ? r : -r) - minY);
 		if (cx < 0 || cz < 0 || cx >= width || cz >= height) return false;
 		if (grid[cz * width + cx] !== floorValue) return false;
 	}
diff --git a/src/lib/flowRuntime.js b/src/lib/flowRuntime.js
index 81bdbecf..efb63631 100644
--- a/src/lib/flowRuntime.js
+++ b/src/lib/flowRuntime.js
@@ -249,7 +249,7 @@ function moduleTriggerInfo(node, ctx) {
  * @param {string} id @returns {{stamp: number, age: number} | null}
  */
 export function nodeTriggerStamp(id) {
-	const node = nodes.find((n) => n.id === id);
+	const node = nodeById(nodes, id);
 	if (!node) return null;
 	return moduleTriggerInfo(node, { triggers: get(flowTriggers) });
 }
@@ -397,6 +397,49 @@ let possessRef = null;
 
 let started = false;
 
+// 31-perf P1: ID INDEXES over the tick's node/edge arrays. Every consumer node resolved its
+// named inputs by scanning EVERY edge and, per wired edge, EVERY node (`resolveInputs`,
+// evalNode's `input()`), so a tick cost O(consumers x edges x nodes) — the second-biggest
+// CPU line in Football after the render itself. The arrays are rebuilt only when a graph
+// changes (the flowGraphs subscriber below), so an index keyed on the ARRAY is built once
+// per graph edit; the length check is a guard against an array somebody pushed onto.
+/** @type {WeakMap<any[], {n: number, map: Map<string, any>}>} */
+const nodeIndex = new WeakMap();
+/** @type {WeakMap<any[], {n: number, map: Map<string, any[]>}>} */
+const edgeIndex = new WeakMap();
+/** @param {any[]} list @param {string} id */
+function nodeById(list, id) {
+	let entry = nodeIndex.get(list);
+	if (!entry || entry.n !== list.length) {
+		const map = new Map();
+		for (const n of list) if (n && !map.has(n.id)) map.set(n.id, n);
+		entry = { n: list.length, map };
+		nodeIndex.set(list, entry);
+	}
+	const hit = entry.map.get(id);
+	// an id changed in place (never done, but cheap to refuse): fall back to the scan
+	return hit && hit.id === id ? hit : list.find((n) => n.id === id);
+}
+/** The edges INTO `id`, in array order. @param {any[]} list @param {string} id @returns {any[]} */
+function edgesInto(list, id) {
+	let entry = edgeIndex.get(list);
+	if (!entry || entry.n !== list.length) {
+		/** @type {Map<string, any[]>} */
+		const map = new Map();
+		for (const e of list) {
+			if (!e) continue;
+			const bucket = map.get(e.target);
+			if (bucket) bucket.push(e);
+			else map.set(e.target, [e]);
+		}
+		entry = { n: list.length, map };
+		edgeIndex.set(list, entry);
+	}
+	return entry.map.get(id) ?? NO_EDGES;
+}
+/** @type {any[]} */
+const NO_EDGES = [];
+
 /** @type {any[]} */ let nodes = [];
 /** @type {any[]} */ let edges = [];
 /** @type {any} */ let sceneObjects = null;
@@ -1543,7 +1586,7 @@ const SEQUENCE_STEPS = ['step1', 'step2', 'step3', 'step4'];
  * @param {any} edge @param {any} ctx @param {Set<string>} seen @returns {number|null}
  */
 function stampOfSource(edge, ctx, seen) {
-	const source = nodes.find((n) => n.id === edge.source);
+	const source = nodeById(nodes, edge.source);
 	if (source && SCHEDULED_TYPES.includes(source.type))
 		return scheduledFireAt(source, edge.sourceHandle, ctx, seen);
 	return ctx?.triggers?.[edge.source]?.lastT ?? null;
@@ -1726,7 +1769,7 @@ function restoreBase(object, base) {
 // animation/color source -> objectselector node with a selected scene object
 /** @param {any} edge */
 function targetUuidOf(edge) {
-	const target = nodes.find((n) => n.id === edge.target);
+	const target = nodeById(nodes, edge.target);
 	if (target?.type !== 'objectselector') return null;
 	const selected = target.data?.selected;
 	if (!selected || selected === '-None-') return null;
@@ -1744,7 +1787,7 @@ function implicitOwnerOf(node) {
 	if (!graph || graph === SCENE_GRAPH) return null;
 	if (muted.includes(graph)) return null;
 	const wired = edges.some(
-		(e) => e.source === node.id && nodes.find((n) => n.id === e.target)?.type === 'objectselector'
+		(e) => e.source === node.id && nodeById(nodes, e.target)?.type === 'objectselector'
 	);
 	return wired ? null : graph;
 }
@@ -1752,7 +1795,7 @@ function implicitOwnerOf(node) {
 function applyColors() {
 	if (!sceneObjects) return;
 	edges.forEach((edge) => {
-		const source = nodes.find((n) => n.id === edge.source);
+		const source = nodeById(nodes, edge.source);
 		if (!source) return;
 		const uuid = targetUuidOf(edge);
 		if (!uuid) return;
@@ -1999,10 +2042,10 @@ function evalNodeBody(node, allNodes, allEdges, time, seen, ctx) {
 	const d = node.data || {};
 	/** a named input handle's value, falling back to a manual param @param {string} handle @param {any} fallback */
 	const input = (handle, fallback) => {
-		const edge = allEdges.find((e) => e.target === node.id && e.targetHandle === handle);
+		const edge = edgesInto(allEdges, node.id).find((e) => e.targetHandle === handle);
 		if (edge) {
 			const value = unwrapHandle(
-				evalNode(allNodes.find((n) => n.id === edge.source), allNodes, allEdges, time, seen, ctx),
+				evalNode(nodeById(allNodes, edge.source), allNodes, allEdges, time, seen, ctx),
 				edge
 			);
 			if (value !== undefined) return value;
@@ -2215,10 +2258,10 @@ function evalNodeBody(node, allNodes, allEdges, time, seen, ctx) {
 		case 'timer': {
 			// delay line: re-evaluate the wired input at a clock-shifted time
 			const delay = num(d.delay ?? 1);
-			const edge = allEdges.find((e) => e.target === node.id && e.targetHandle === 'a');
+			const edge = edgesInto(allEdges, node.id).find((e) => e.targetHandle === 'a');
 			if (edge) {
 				const v = evalNode(
-					allNodes.find((n) => n.id === edge.source),
+					nodeById(allNodes, edge.source),
 					allNodes,
 					allEdges,
 					time - delay,
@@ -2516,10 +2559,10 @@ function evalNodeBody(node, allNodes, allEdges, time, seen, ctx) {
  */
 export function resolveInputs(node, allNodes, allEdges, time, ctx = null) {
 	const data = { ...(node.data || {}) };
-	allEdges.forEach((edge) => {
-		if (edge.target !== node.id || !edge.targetHandle) return;
-		const source = allNodes.find((n) => n.id === edge.source);
-		if (!source) return;
+	for (const edge of edgesInto(allEdges, node.id)) {
+		if (!edge.targetHandle) continue;
+		const source = nodeById(allNodes, edge.source);
+		if (!source) continue;
 		// A1: a module value node is a third kind of source — without this a module
 		// value could never reach a consumer's named input, only a card readout
 		if (
@@ -2527,10 +2570,10 @@ export function resolveInputs(node, allNodes, allEdges, time, ctx = null) {
 			!sourceValueTypes.includes(source.type) &&
 			!moduleValueNodes[source.type]
 		)
-			return;
+			continue;
 		const value = unwrapHandle(evalNode(source, allNodes, allEdges, time, new Set(), ctx), edge);
 		if (value !== undefined) data[edge.targetHandle] = value;
-	});
+	}
 	return data;
 }
 
@@ -2607,7 +2650,7 @@ export function applyNodeTrigger(nodeId, t, replicate = true, sourceHandle = nul
 		edges.forEach((edge) => {
 			if (edge.source !== nodeId) return;
 			if (sourceHandle !== null && (edge.sourceHandle ?? null) !== sourceHandle) return;
-			const target = nodes.find((n) => n.id === edge.target);
+			const target = nodeById(nodes, edge.target);
 			if (!target) return;
 			const handle = edge.targetHandle ?? null;
 			if (target.type === 'counter') {
@@ -2689,7 +2732,7 @@ function reachesObjectSelector(startId, uuid) {
 		const cur = stack.pop();
 		for (const edge of edges) {
 			if (edge.source !== cur || seen.has(edge.target)) continue;
-			const target = nodes.find((n) => n.id === edge.target);
+			const target = nodeById(nodes, edge.target);
 			// an Object Selector is a sink — check its target, don't traverse past it
 			if (target?.type === 'objectselector') {
 				if (target.data?.selected === uuid) return true;
@@ -3209,7 +3252,7 @@ function runTick(now) {
 		const bucket = nextInputs[target] ?? (nextInputs[target] = {});
 		edges.forEach((e) => {
 			if (e.target !== embed.id || !e.targetHandle) return;
-			const src = nodes.find((n) => n.id === e.source);
+			const src = nodeById(nodes, e.source);
 			if (!src) return;
 			const v = unwrapHandle(evalNode(src, nodes, edges, time, new Set(), ctx), e);
 			if (v !== undefined) bucket[e.targetHandle] = v;
@@ -3244,7 +3287,7 @@ function runTick(now) {
 		!dormant(node);
 	if (sceneObjects) {
 		edges.forEach((edge) => {
-			const source = nodes.find((n) => n.id === edge.source);
+			const source = nodeById(nodes, edge.source);
 			if (!source || !isEffectNode(source)) return;
 			const uuid = targetUuidOf(edge);
 			if (!uuid) return;
@@ -3300,7 +3343,7 @@ function runTick(now) {
 	/** @type {{node: any, uuid: string, trigger?: number|null}[]} */
 	const soundPairs = [];
 	edges.forEach((edge) => {
-		const source = nodes.find((n) => n.id === edge.source);
+		const source = nodeById(nodes, edge.source);
 		if (source?.type !== 'sound') return;
 		const uuid = targetUuidOf(edge);
 		// resolve input-driven volume/radius (133) without touching soundRuntime
@@ -3333,7 +3376,7 @@ function runTick(now) {
 	/** @type {{node: any, uuid: string}[]} */
 	const particlePairs = [];
 	edges.forEach((edge) => {
-		const source = nodes.find((n) => n.id === edge.source);
+		const source = nodeById(nodes, edge.source);
 		if (source?.type !== 'particle') return;
 		const uuid = targetUuidOf(edge);
 		if (uuid) particlePairs.push({ node: { ...source, data: resolveInputs(source, nodes, edges, time, ctx) }, uuid });
@@ -3350,7 +3393,7 @@ function runTick(now) {
 	/** @type {{node: any, uuid: string}[]} */
 	const animPairs = [];
 	edges.forEach((edge) => {
-		const source = nodes.find((n) => n.id === edge.source);
+		const source = nodeById(nodes, edge.source);
 		if (source?.type !== 'playanim') return;
 		const uuid = targetUuidOf(edge);
 		if (uuid) animPairs.push({ node: { ...source, data: resolveInputs(source, nodes, edges, time, ctx) }, uuid });
@@ -3369,7 +3412,7 @@ function runTick(now) {
 	const physicsPairs = [];
 	const PHYSICS_ACTIONS = ['impulse', 'setvelocity', 'joint'];
 	edges.forEach((edge) => {
-		const source = nodes.find((n) => n.id === edge.source);
+		const source = nodeById(nodes, edge.source);
 		if (!source || !PHYSICS_ACTIONS.includes(source.type)) return;
 		const uuid = targetUuidOf(edge);
 		if (uuid)
diff --git a/src/lib/moveSmoothing.js b/src/lib/moveSmoothing.js
index 7601d08e..d6ca0835 100644
--- a/src/lib/moveSmoothing.js
+++ b/src/lib/moveSmoothing.js
@@ -32,7 +32,7 @@ import { objectsGroup, pokeScene } from '../stores/sceneStore';
 // snaps exactly as before, so nothing outside a live stream changes.
 
 /** @typedef {{from: {pos: THREE.Vector3, quat: THREE.Quaternion},
- *   to: {pos: THREE.Vector3, quat: THREE.Quaternion}, t0: number, dur: number}} Ease */
+ *   to: {pos: THREE.Vector3, quat: THREE.Quaternion}, t0: number, dur: number, object?: any}} Ease */
 /** @type {Map<string, Ease>} */
 const eases = new Map();
 /** @type {Map<string, {last: number, interval: number}>} */
@@ -84,7 +84,8 @@ export function noteRemoteMove(uuid, object, before) {
 		from: { pos: before.pos.clone(), quat: before.quat.clone() },
 		to: { pos: object.position.clone(), quat: object.quaternion.clone() },
 		t0: now,
-		dur: interval
+		dur: interval,
+		object
 	});
 	// rewind: the ease starts where the eye last saw it
 	object.position.copy(before.pos);
@@ -113,12 +114,23 @@ export function noteRemoteMove(uuid, object, before) {
 
 /** Per frame, from Scene's useTask. Writes the exact target pose on the last
  * step, so an interrupted or finished ease never leaves the object short. */
+// 31-perf P1: this ran on EVERY watching peer, every frame a remote body moved — a
+// whole-tree `getObjectByProperty` per eased body plus a full pokeScene, which re-runs
+// every $objectsGroup subscriber in the app (~30 components) at the display rate. A pose
+// write is not a tree change: the ease keeps its object (re-found only if it left the
+// tree) and the UI hears about the motion at POKE_MS, plus once when the last ease lands.
+const POKE_MS = 100;
+let lastPokeAt = 0;
+
 export function tickMoveSmoothing() {
 	if (eases.size === 0) return;
-	const group = get(objectsGroup);
 	const now = performance.now();
-	for (const [uuid, ease] of [...eases.entries()]) {
-		const object = group?.getObjectByProperty('uuid', uuid);
+	for (const [uuid, ease] of eases) {
+		let object = ease.object;
+		if (!object?.parent) {
+			object = get(objectsGroup)?.getObjectByProperty('uuid', uuid);
+			ease.object = object;
+		}
 		if (!object) {
 			eases.delete(uuid);
 			continue;
@@ -133,7 +145,10 @@ export function tickMoveSmoothing() {
 		object.position.lerpVectors(ease.from.pos, ease.to.pos, t);
 		object.quaternion.slerpQuaternions(ease.from.quat, ease.to.quat, t);
 	}
-	pokeScene();
+	if (eases.size === 0 || now - lastPokeAt >= POKE_MS) {
+		lastPokeAt = now;
+		pokeScene();
+	}
 }
 
 /** the sim stopped, the peer left, the scene changed — land everything at once */
diff --git a/tests/e2e/perf-stutter.test.cjs b/tests/e2e/perf-stutter.test.cjs
new file mode 100644
index 00000000..f9b7cff0
--- /dev/null
+++ b/tests/e2e/perf-stutter.test.cjs
@@ -0,0 +1,195 @@
+// 31-perf P1 — THE CORE STUTTER GUARDS. The seven-game probe (scripts/perf-games.cjs
+// --profile) found where 1.17's frames went; each check below is a COUNTERFACTUAL that goes
+// red with its fix reverted (the numbers in the messages are the reverted readings):
+//   a) the object list's "Module content" rows never deep-read a module group — svelte's
+//      deep_read of a $state proxy walked the whole scene graph through `parent` on every
+//      refresh: 88% of Waves' CPU, the 1 Hz hitch in Dungeon Realms
+//   b) the flow runtime resolves a node's inputs through an index, not a scan of every edge
+//   c) the walker's dungeon lookup is cached, hit AND miss, instead of a per-frame traversal
+//   d) easing a remote physics stream neither searches the tree nor pokes the whole UI every
+//      frame (a watching peer ran both at the display rate)
+//   e) the closed VR objects panel does not rebuild its rows on a scene poke
+//
+// Run: APP_URL=https://theprototype.app:5263/ npm run e2e -- perf-stutter
+const h = require('./helpers.cjs');
+
+h.run(async () => {
+	const browser = await h.launch({ args: h.GPU_ARGS });
+	const A = await h.setupPage(browser, 'A', { context: { viewport: { width: 1280, height: 720 } } });
+	const page = A.page;
+	await page.evaluate(() => {
+		window.read = (store) => {
+			let v;
+			store.subscribe((x) => (v = x))();
+			return v;
+		};
+	});
+
+	// ---- the guards ------------------------------------------------------------
+	const deep = await page.evaluate(async () => {
+		const s = window.__stores;
+		window.__deepReads = 0;
+		await s.moduleSDK.initModules([
+			{
+				id: 'deepprobe',
+				name: 'Deep-read probe',
+				version: '1.0.0',
+				description: 'a module group carrying a getter-counting probe',
+				register(api) {
+					const THREE = api.THREE;
+					class Probe {
+						get touched() {
+							window.__deepReads++;
+							return 1;
+						}
+					}
+					const group = new THREE.Group();
+					group.name = 'deepprobe-group';
+					const child = new THREE.Mesh(new THREE.BoxGeometry(), new THREE.MeshBasicMaterial());
+					child.name = 'deepprobe-child';
+					child.userData.probe = new Probe();
+					group.add(child);
+					api.scene().add(group);
+					api.registerInteractiveGroup('deepprobe-group');
+				}
+			}
+		]);
+		// the rows re-derive on every poke and once a second: give them several refreshes
+		for (let i = 0; i < 6; i++) {
+			s.pokeScene();
+			await new Promise((r) => setTimeout(r, 350));
+		}
+		const listed = !!document.querySelector('.module-content-row[data-group="deepprobe-group"]');
+		const reads = window.__deepReads;
+		s.moduleSDK.deactivateModule('deepprobe');
+		return { listed, reads };
+	});
+	h.check(deep.listed, '0 (premise) the probe group is listed in the object list\'s Module content');
+	h.check(deep.reads === 0, '1 COUNTERFACTUAL GUARD: refreshing the Module content rows never deep-reads a module group (' + deep.reads + ' getter reads; a deep $state walks the scene graph)');
+
+	const index = await page.evaluate(() => {
+		const s = window.__stores;
+		const nodes = [];
+		const edges = [];
+		for (let i = 0; i < 200; i++) nodes.push({ id: 'n' + i, type: 'number', data: { value: i } });
+		for (let i = 0; i < 400; i++) edges.push({ id: 'e' + i, source: 'n' + (i % 200), target: 'n' + ((i * 7) % 200), targetHandle: 'value' });
+		const consumer = { id: 'consumer', type: 'mathop', data: {} };
+		nodes.push(consumer);
+		edges.push({ id: 'ein', source: 'n3', target: 'consumer', targetHandle: 'a' });
+		let reads = 0;
+		const counted = new Proxy(edges, {
+			get(target, key, recv) {
+				if (typeof key === 'string' && /^\d+$/.test(key)) reads++;
+				return Reflect.get(target, key, recv);
+			}
+		});
+		for (let i = 0; i < 50; i++) s.flowRuntime.resolveInputs(consumer, nodes, counted, 0, null);
+		const data = s.flowRuntime.resolveInputs(consumer, nodes, counted, 0, null);
+		return { reads, edges: edges.length, a: data.a };
+	});
+	h.check(index.a === 3, '2 (premise) the wired input still resolves through the index (a = ' + index.a + ')');
+	h.check(index.reads <= index.edges + 10, '3 COUNTERFACTUAL GUARD: 51 resolutions read the edge list ONCE (' + index.reads + ' element reads for ' + index.edges + ' edges; a per-call scan reads ~' + index.edges * 51 + ')');
+
+	const dungeon = await page.evaluate(() => {
+		const s = window.__stores;
+		const THREE = s.THREE;
+		const scene = new THREE.Scene();
+		let lookups = 0;
+		const inner = scene.getObjectByName.bind(scene);
+		scene.getObjectByName = (name) => (lookups++, inner(name));
+		s.dungeonPlay.forgetDungeonData?.();
+		for (let i = 0; i < 100; i++) s.dungeonPlay.dungeonData(scene);
+		const missLookups = lookups;
+		const g = new THREE.Group();
+		g.name = 'dungeon-module';
+		g.userData.play = { grid: [1], width: 1, height: 1, minX: 0, minY: 0, floorValue: 1 };
+		scene.add(g);
+		s.dungeonPlay.forgetDungeonData?.();
+		lookups = 0;
+		let found = 0;
+		for (let i = 0; i < 100; i++) if (s.dungeonPlay.dungeonData(scene)) found++;
+		const hitLookups = lookups;
+		scene.remove(g);
+		const gone = s.dungeonPlay.dungeonData(scene);
+		s.dungeonPlay.forgetDungeonData?.();
+		return { missLookups, hitLookups, found, gone };
+	});
+	h.check(dungeon.found === 100 && dungeon.gone === null, '4 (premise) the raster is found every call, and forgotten when its group leaves the scene');
+	h.check(dungeon.hitLookups === 1 && dungeon.missLookups === 1, '5 COUNTERFACTUAL GUARD: 100 walker frames cost ONE scene traversal, hit or miss (' + dungeon.hitLookups + ' / ' + dungeon.missLookups + '; per-frame was 100 / 100)');
+
+	const ease = await page.evaluate(async () => {
+		const s = window.__stores;
+		const THREE = s.THREE;
+		const group = read(s.objectsGroup);
+		const box = new THREE.Mesh(new THREE.BoxGeometry(), new THREE.MeshBasicMaterial());
+		box.name = 'ease-box';
+		box.userData.physics = { mode: 'dynamic', mass: 1 };
+		group.add(box);
+		const ms = s.moveSmoothing;
+		const move = (x) => {
+			const before = { pos: box.position.clone(), quat: box.quaternion.clone() };
+			box.position.set(x, 0, 0);
+			return ms.noteRemoteMove(box.uuid, box, before);
+		};
+		move(0.1);
+		const easing = move(0.2); // the second inside 400 ms is a STREAM
+		let lookups = 0;
+		const inner = group.getObjectByProperty.bind(group);
+		group.getObjectByProperty = (...a) => (lookups++, inner(...a));
+		let revisions = 0;
+		const off = s.sceneRevision.subscribe(() => revisions++);
+		revisions = 0;
+		// 30 "frames" inside one poke window, each followed by a microtask turn so a poke
+		// flushes as it would between real frames (pokeScene coalesces per microtask)
+		for (let i = 0; i < 30; i++) {
+			ms.tickMoveSmoothing();
+			await Promise.resolve();
+		}
+		off();
+		group.getObjectByProperty = inner;
+		ms.clearMoveSmoothing?.();
+		group.remove(box);
+		return { easing, lookups, revisions };
+	});
+	h.check(ease.easing === true, '6 (premise) two moves inside 400 ms ease as a stream');
+	// a subscriber reacting to the one allowed poke may search the tree itself: count at most one per poke
+	h.check(ease.revisions <= 1 && ease.lookups <= ease.revisions, '7 COUNTERFACTUAL GUARD: 30 eased frames did ' + ease.lookups + ' tree searches and ' + ease.revisions + ' scene pokes (per frame was 30+ / 30)');
+
+
+	const panel = await page.evaluate(async () => {
+		const s = window.__stores;
+		const THREE = s.THREE;
+		const g = read(s.objectsGroup);
+		// a top-level object whose `type` counts reads made from inside flattenPanelRows only
+		// (every other list in the app reads `type` too)
+		window.__flatReads = 0;
+		const m = new THREE.Mesh(new THREE.BoxGeometry(), new THREE.MeshBasicMaterial());
+		m.name = 'panel-probe';
+		Object.defineProperty(m, 'type', {
+			configurable: true,
+			get() {
+				if (/flattenPanelRows/.test(new Error().stack || '')) window.__flatReads++;
+				return 'Mesh';
+			}
+		});
+		g.add(m);
+		for (let i = 0; i < 8; i++) {
+			s.pokeScene();
+			await new Promise((r) => setTimeout(r, 30));
+		}
+		const closedReads = window.__flatReads;
+		s.vrObjectsPanelOpen.set(true);
+		await new Promise((r) => setTimeout(r, 200));
+		const openReads = window.__flatReads - closedReads;
+		const openAction = read(s.vrControls.vrPanelCursorAction);
+		s.vrObjectsPanelOpen.set(false);
+		g.remove(m);
+		s.pokeScene();
+		return { closedReads, openReads, openAction };
+	});
+	h.check(panel.openReads > 0 && typeof panel.openAction === 'string', '(premise) opened, the VR objects panel lists the scene at once (' + panel.openReads + ' reads, ' + panel.openAction + ')');
+	h.check(panel.closedReads === 0, 'COUNTERFACTUAL GUARD: 8 scene pokes rebuilt the CLOSED VR objects panel ' + panel.closedReads + ' times (was once per poke)');
+
+	h.check(h.pageErrors(A).length === 0, 'no page errors (' + JSON.stringify(h.pageErrors(A)) + ')');
+	await h.finish(browser);
+});

From 72906a7ae6634590dac585eafbb4e1aaac78a332 Mon Sep 17 00:00:00 2001
From: AlexZ005 <alexz005.info@gmail.com>
Date: Thu, 1 Oct 2026 01:14:24 +0300
Subject: [PATCH 3/5] [feat] automatic levels of detail, and api.lod (P2, K4)

- src/lib/lod.js: dense meshes (>= 3000 tris) in objectsGroup and under the module world
  root get meshoptimizer-simplified levels (ratios 0.5 / 0.25 / 0.1), built ONCE per asset
  in the existing decimation worker (keyed by a content signature, so fifty placements of
  one pack piece or ten parses of one GLB share one set). THE TREE IS NEVER TOUCHED: the
  swap happens in scene.onBeforeRender / onAfterRender, inside renderer.render() only, so
  every serializer, picking, BVH, physics hull and mesh tool sees the source geometry.
  Distances are in world RADII of the mesh with a hysteresis band; a `lodBias` store pulls
  them in (the quality governor writes it in P3). A geometry swap or an in-place edit
  stands the entry down at once and rebuilds after it has held still 1.5 s. Skinned
  meshes, morph targets and (in auto mode) instanced meshes are left alone;
  `userData.lod = false` opts a mesh out. LOCAL, never replicated.
- src/lib/lodCore.js: the pure rule (pickLevel with hysteresis, levelsToBuild,
  normalizeLodOptions, lodBiasFor, geometrySignature) - vitest.
- decimateCore: an optional per-job `errorCap` (absent = the import gate's 0.05,
  byte-identical); a far LOD level asks for the count, not a surface error.
- api.lod(object, {ratios, distances, minTriangles}) -> {meshes, ready, remove}, journalled.
- Settings > "Simplify distant models" (lodEnabled, LOCAL, default on); App boots it and
  the debug hook gains `lod` (the three tails 219/219/219).

Suite lod (new, 20 checks): levels built (9024 -> 4511 -> 2256 -> 902), the frame's
triangles from 400 m drop 18110 -> 1866 and a middle distance draws a middle level, the
mesh holds its source geometry after a render and toJSON writes only it, a geometry swap
draws whole at once, twins share one cache entry, the bias pulls the edge in, api.lod on
scene-root module content + teardown on deactivate.
COUNTERFACTUAL in-suite: with LOD switched off the far render draws the full 18110.
vitest lodCore (14): hysteresis both ways, radii not metres, bias, floors, signature.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 src/App.svelte                      |  10 +-
 src/components/menu/Settings.svelte |   5 +
 src/lib/decimateCore.js             |  10 +-
 src/lib/lod.js                      | 558 ++++++++++++++++++++++++++++
 src/lib/lodCore.js                  | 149 ++++++++
 src/lib/moduleSDK.js                |  21 ++
 tests/e2e/lod.test.cjs              | 215 +++++++++++
 tests/unit/lodCore.test.js          | 111 ++++++
 8 files changed, 1073 insertions(+), 6 deletions(-)
 create mode 100644 src/lib/lod.js
 create mode 100644 src/lib/lodCore.js
 create mode 100644 tests/e2e/lod.test.cjs
 create mode 100644 tests/unit/lodCore.test.js

diff --git a/src/App.svelte b/src/App.svelte
index 089775f0..5ddbb5af 100644
--- a/src/App.svelte
+++ b/src/App.svelte
@@ -33,6 +33,7 @@
   // budget meter. `renderer.info` had exactly one reader before this (the VR plate).
   import StatsOverlay from './components/menu/StatsOverlay.svelte'
   import { startSceneMetrics, budgetSummary } from './lib/sceneBudget'
+  import { startLod } from './lib/lod'
   import PlayReticle from './components/play/PlayReticle.svelte'
   import TouchPlayControls from './components/play/TouchPlayControls.svelte'
   import DrawToolbar from './components/menu/DrawToolbar.svelte'
@@ -134,6 +135,8 @@ import { startMusicToolbox } from './lib/musicToolbox'
     // it keeps measuring while the canvas is remounting — which is exactly when a
     // report about the app freezing tends to be written.
     startSceneMetrics()
+    // 31-perf P2: automatic levels of detail (a render-time swap; see lod.js)
+    startLod()
     // …and the numbers ride the bundle, so a report carries them (audit H4 + roadmap
     // 26 section 3's last row).
     registerDiagnosticsSection('scene-budget', () => budgetSummary())
@@ -485,9 +488,10 @@ import { startMusicToolbox } from './lib/musicToolbox'
 			import('./lib/gameKit'),
 			import('./lib/moduleWorld'),
 			import('./lib/playSpawn'),
-			import('./lib/packRefs')
-      ]).then(([sceneStore, appStore, flowStore, meshEdit, vrControls, autosave, voiceChat, audioEngineLib, musicClockLib, audioDevicesLib, audioPatchLib, vrPatchLib, musicToolboxLib, micCaptureLib, annotationsHandler, flowRuntime, history, materialsHandler, objectActions, commandsHandler, moduleSDK, drawModeLib, pathCapture, lockControl, prefabsLib, physics, jointsLib, possessLib, handModelsLib, terrainSculptLib, userModulesLib, environmentLib, sceneMusicLib, animatedImports, fileHandler, fileWindowsLib, sceneBounds, cameraClip, ping, sessionsLib, geometryEdit, lightParams, shadowDefaultsLib, paletteLib, viewModeLib, inputRuntimeLib, shortcutsLib, themesLib, vrRadialMenu, vrPaletteLib, vrWindowPosesLib, vrKeyboardLib, faceEditLib, meshToolParamsLib, avatarModelLib, explorerLib, bottomDock, explorerDrop, assetShare, soundRuntime, dungeonPlay, sceneAssetsLib, THREE, GLTFExporterModule, snappingLib, flowSocketsLib, networkQualityLib, packsLib, customNodesLib, nodesHandlerLib, nodeCatalogLib, objectMenuLib, animationPreviewLib, aiProvidersLib, aiToolsLib, aiAssistantLib, meshProvidersLib, meshJobsLib, flowGraphsLib, objectFlowLib, peerServerLib, cloudHooksLib, cloudPluginLib, connectionStateLib, peerApprovalLib, particleRuntimeLib, particleActionsLib, particlePresetsLib, versionLib, whatsNewLib, confirmDialogLib, scenePhysicsLib, playInteractLib, moveSmoothingLib, knockLib, playSettingsLib, colliderSpecLib, colliderHelpersLib, colliderEditLib, editSessionLib, trackpadNavLib, vrSleeveLib, gridSettingsLib, viewPrefsLib, cameraBookmarksLib, cameraObjectsLib, cameraHelpersLib, onionSkinLib, cameraPreviewLib, addObjectsLib, cameraPipLib, inputDeviceLib, sceneTemplatesLib, bvhPickingLib, multiTransformLib, objectOriginLib, moduleGalleryLib, uvEditorLib, uvUnwrapLib, meshTopologyLib, meshBudgetLib, proportionalLib, proportionalRingLib, scenePickLib, snapEngineLib, meshPivotLib, selectionPrefsLib, editOverlaysLib, objectPermissionsLib, scenePostLib, postEffectsLib, viewportOverridesLib, postprocessingModule, shaderBackendsLib, shaderGraphLib, shaderSyncLib, shaderTexturesLib, shaderCatalogLib, unitsLib, postBackendsLib, workspaceLib, editResumeLib, moduleRequirementsLib, hudDocsLib, hudSyncLib, idbLib, hudKindsLib, hudImagesLib, gameStateLib, gameSyncLib, hudActionsLib, moduleNodeIOLib, moduleToolboxesLib, splineTubeLib, splineToolLib, splineEditLib, terrainCarveLib, flattenActionsLib, hudViewportDragLib, gamepadPrefsLib, charControllerLib, hudRichTextLib, moduleHudKindsLib, hudMinimapLib, hudArrangeLib, gamePresenceLib, levelsLib, peerVarsLib, projectManifestLib, projectFileLib, transientObjectsLib, spawnerLib, triggerSyncLib, saveNameLib, sceneIdentityLib, importDuplicatesLib, peerScenesLib, sharedLibraryLib, transferLedgerLib, explorerViewLib, filePreviewLib, saveAsLib, windowTabsLib, colocationLib, colocationCalibrateLib, colocationPresenceLib, xrAnchorsLib, colocationAnchorsLib, colocationNudgeLib, mountedVolumesLib, storageUsageLib, scenePrivacyLib, touchControlsLib, playModeLib, objectListNavLib, inviteLinksLib, helperLayerLib, explorerClipboardLib, lookPresenceLib, postGraphsLib, postGraphPresetsLib, materialSharingLib, diagnosticsLib, wireValidateLib, wireErrorsLib, safeStorageLib, sceneBudgetLib, overloadGuardLib, qualityGovernorLib, importBudgetLib, importGateLib, decimateLib, playCursorLib, gameStorageLib, gameKitLib, moduleWorldLib, playSpawnLib, packRefsLib]) => {
-        window.__stores = { ...sceneStore, ...appStore, ...flowStore, meshEdit, vrControls, autosave, voiceChat, audioEngine: audioEngineLib, musicClock: musicClockLib, audioDevices: audioDevicesLib, audioPatch: audioPatchLib, vrPatch: vrPatchLib, musicToolbox: musicToolboxLib, micCapture: micCaptureLib, annotationsHandler, flowRuntime, history, materialsHandler, objectActions, commandsHandler, moduleSDK, drawMode: drawModeLib, pathCapture, lockControl, prefabs: prefabsLib, physics, joints: jointsLib, possess: possessLib, handModels: handModelsLib, terrainSculpt: terrainSculptLib, userModules: userModulesLib, environment: environmentLib, sceneMusic: sceneMusicLib, animatedImports, fileHandler, fileWindows: fileWindowsLib, sceneBounds, cameraClip, ping, sessions: sessionsLib, geometryEdit, lightParams, shadowDefaults: shadowDefaultsLib, palette: paletteLib, viewModeCtl: viewModeLib, inputRuntime: inputRuntimeLib, shortcutsRegistry: shortcutsLib, themes: themesLib, vrRadialMenu, vrPalette: vrPaletteLib, vrWindowPoses: vrWindowPosesLib, vrKeyboard: vrKeyboardLib, faceEdit: faceEditLib, meshToolParams: meshToolParamsLib, avatarModel: avatarModelLib, explorer: explorerLib, bottomDock, explorerDrop, assetShare, soundRuntime, dungeonPlay, sceneAssets: sceneAssetsLib, THREE, GLTFExporterModule, snapping: snappingLib, flowSockets: flowSocketsLib, networkQuality: networkQualityLib, packs: packsLib, customNodes: customNodesLib, nodesHandler: nodesHandlerLib, nodeCatalog: nodeCatalogLib, objectMenu: objectMenuLib, animationPreview: animationPreviewLib, aiProviders: aiProvidersLib, aiTools: aiToolsLib, aiAssistant: aiAssistantLib, meshProviders: meshProvidersLib, meshJobs: meshJobsLib, flowGraphsCtl: flowGraphsLib, objectFlow: objectFlowLib, peerServer: peerServerLib, cloudHooks: cloudHooksLib, cloudPlugin: cloudPluginLib, connectionState: connectionStateLib, peerApproval: peerApprovalLib, particleRuntime: particleRuntimeLib, particleActions: particleActionsLib, particlePresets: particlePresetsLib, version: versionLib, whatsNew: whatsNewLib, confirmDialog: confirmDialogLib, scenePhysics: scenePhysicsLib, playInteract: playInteractLib, moveSmoothing: moveSmoothingLib, knock: knockLib, playSettings: playSettingsLib, colliderSpec: colliderSpecLib, colliderHelpers: colliderHelpersLib, colliderEdit: colliderEditLib, editSession: editSessionLib, trackpadNav: trackpadNavLib, vrSleeve: vrSleeveLib, gridSettings: gridSettingsLib, viewPrefs: viewPrefsLib, cameraBookmarks: cameraBookmarksLib, cameraObjects: cameraObjectsLib, cameraHelpers: cameraHelpersLib, onionSkin: onionSkinLib, cameraPreview: cameraPreviewLib, addObjects: addObjectsLib, cameraPip: cameraPipLib, inputDevice: inputDeviceLib, sceneTemplates: sceneTemplatesLib, bvhPicking: bvhPickingLib, multiTransform: multiTransformLib, objectOrigin: objectOriginLib, moduleGallery: moduleGalleryLib, uvEditor: uvEditorLib, uvUnwrap: uvUnwrapLib, meshTopology: meshTopologyLib, meshBudget: meshBudgetLib, proportional: proportionalLib, proportionalRing: proportionalRingLib, scenePick: scenePickLib, snapEngine: snapEngineLib, meshPivot: meshPivotLib, selectionPrefs: selectionPrefsLib, editOverlays: editOverlaysLib, objectPermissions: objectPermissionsLib, scenePost: scenePostLib, postEffects: postEffectsLib, viewportOverrides: viewportOverridesLib, postprocessing: postprocessingModule, shaderBackends: shaderBackendsLib, shaderGraph: shaderGraphLib, shaderSync: shaderSyncLib, shaderTextures: shaderTexturesLib, shaderCatalog: shaderCatalogLib, units: unitsLib, postBackends: postBackendsLib, workspace: workspaceLib, editResume: editResumeLib, moduleRequirements: moduleRequirementsLib, hudDocs: hudDocsLib, hudSync: hudSyncLib, idb: idbLib, hudKinds: hudKindsLib, hudImages: hudImagesLib, gameState: gameStateLib, gameSync: gameSyncLib, hudActions: hudActionsLib, moduleNodeIO: moduleNodeIOLib, moduleToolboxes: moduleToolboxesLib, splineTube: splineTubeLib, splineTool: splineToolLib, splineEdit: splineEditLib, terrainCarve: terrainCarveLib, flattenActions: flattenActionsLib, hudViewportDrag: hudViewportDragLib, gamepadPrefs: gamepadPrefsLib, charController: charControllerLib, hudRichText: hudRichTextLib, moduleHudKinds: moduleHudKindsLib, hudMinimap: hudMinimapLib, hudArrange: hudArrangeLib, gamePresence: gamePresenceLib, levels: levelsLib, peerVars: peerVarsLib, projectManifest: projectManifestLib, projectFile: projectFileLib, transientObjects: transientObjectsLib, spawner: spawnerLib, triggerSync: triggerSyncLib, saveName: saveNameLib, sceneIdentity: sceneIdentityLib, importDuplicates: importDuplicatesLib, peerScenes: peerScenesLib, sharedLibrary: sharedLibraryLib, transferLedger: transferLedgerLib, explorerView: explorerViewLib, filePreview: filePreviewLib, saveAs: saveAsLib, windowTabs: windowTabsLib, colocation: colocationLib, colocationCalibrate: colocationCalibrateLib, colocationPresence: colocationPresenceLib, xrAnchors: xrAnchorsLib, colocationAnchors: colocationAnchorsLib, colocationNudge: colocationNudgeLib, mountedVolumes: mountedVolumesLib, storageUsage: storageUsageLib, scenePrivacy: scenePrivacyLib, touchControls: touchControlsLib, playMode: playModeLib, objectListNav: objectListNavLib, inviteLinks: inviteLinksLib, helperLayer: helperLayerLib, explorerClipboard: explorerClipboardLib, lookPresence: lookPresenceLib, postGraphs: postGraphsLib, postGraphPresets: postGraphPresetsLib, materialSharing: materialSharingLib, diagnostics: diagnosticsLib, wireValidate: wireValidateLib, wireErrors: wireErrorsLib, safeStorage: safeStorageLib, sceneBudget: sceneBudgetLib, overloadGuard: overloadGuardLib, qualityGovernor: qualityGovernorLib, importBudget: importBudgetLib, importGate: importGateLib, decimate: decimateLib, playCursor: playCursorLib, gameStorage: gameStorageLib, gameKit: gameKitLib, moduleWorld: moduleWorldLib, playSpawn: playSpawnLib, packRefs: packRefsLib }
+			import('./lib/packRefs'),
+			import('./lib/lod')
+      ]).then(([sceneStore, appStore, flowStore, meshEdit, vrControls, autosave, voiceChat, audioEngineLib, musicClockLib, audioDevicesLib, audioPatchLib, vrPatchLib, musicToolboxLib, micCaptureLib, annotationsHandler, flowRuntime, history, materialsHandler, objectActions, commandsHandler, moduleSDK, drawModeLib, pathCapture, lockControl, prefabsLib, physics, jointsLib, possessLib, handModelsLib, terrainSculptLib, userModulesLib, environmentLib, sceneMusicLib, animatedImports, fileHandler, fileWindowsLib, sceneBounds, cameraClip, ping, sessionsLib, geometryEdit, lightParams, shadowDefaultsLib, paletteLib, viewModeLib, inputRuntimeLib, shortcutsLib, themesLib, vrRadialMenu, vrPaletteLib, vrWindowPosesLib, vrKeyboardLib, faceEditLib, meshToolParamsLib, avatarModelLib, explorerLib, bottomDock, explorerDrop, assetShare, soundRuntime, dungeonPlay, sceneAssetsLib, THREE, GLTFExporterModule, snappingLib, flowSocketsLib, networkQualityLib, packsLib, customNodesLib, nodesHandlerLib, nodeCatalogLib, objectMenuLib, animationPreviewLib, aiProvidersLib, aiToolsLib, aiAssistantLib, meshProvidersLib, meshJobsLib, flowGraphsLib, objectFlowLib, peerServerLib, cloudHooksLib, cloudPluginLib, connectionStateLib, peerApprovalLib, particleRuntimeLib, particleActionsLib, particlePresetsLib, versionLib, whatsNewLib, confirmDialogLib, scenePhysicsLib, playInteractLib, moveSmoothingLib, knockLib, playSettingsLib, colliderSpecLib, colliderHelpersLib, colliderEditLib, editSessionLib, trackpadNavLib, vrSleeveLib, gridSettingsLib, viewPrefsLib, cameraBookmarksLib, cameraObjectsLib, cameraHelpersLib, onionSkinLib, cameraPreviewLib, addObjectsLib, cameraPipLib, inputDeviceLib, sceneTemplatesLib, bvhPickingLib, multiTransformLib, objectOriginLib, moduleGalleryLib, uvEditorLib, uvUnwrapLib, meshTopologyLib, meshBudgetLib, proportionalLib, proportionalRingLib, scenePickLib, snapEngineLib, meshPivotLib, selectionPrefsLib, editOverlaysLib, objectPermissionsLib, scenePostLib, postEffectsLib, viewportOverridesLib, postprocessingModule, shaderBackendsLib, shaderGraphLib, shaderSyncLib, shaderTexturesLib, shaderCatalogLib, unitsLib, postBackendsLib, workspaceLib, editResumeLib, moduleRequirementsLib, hudDocsLib, hudSyncLib, idbLib, hudKindsLib, hudImagesLib, gameStateLib, gameSyncLib, hudActionsLib, moduleNodeIOLib, moduleToolboxesLib, splineTubeLib, splineToolLib, splineEditLib, terrainCarveLib, flattenActionsLib, hudViewportDragLib, gamepadPrefsLib, charControllerLib, hudRichTextLib, moduleHudKindsLib, hudMinimapLib, hudArrangeLib, gamePresenceLib, levelsLib, peerVarsLib, projectManifestLib, projectFileLib, transientObjectsLib, spawnerLib, triggerSyncLib, saveNameLib, sceneIdentityLib, importDuplicatesLib, peerScenesLib, sharedLibraryLib, transferLedgerLib, explorerViewLib, filePreviewLib, saveAsLib, windowTabsLib, colocationLib, colocationCalibrateLib, colocationPresenceLib, xrAnchorsLib, colocationAnchorsLib, colocationNudgeLib, mountedVolumesLib, storageUsageLib, scenePrivacyLib, touchControlsLib, playModeLib, objectListNavLib, inviteLinksLib, helperLayerLib, explorerClipboardLib, lookPresenceLib, postGraphsLib, postGraphPresetsLib, materialSharingLib, diagnosticsLib, wireValidateLib, wireErrorsLib, safeStorageLib, sceneBudgetLib, overloadGuardLib, qualityGovernorLib, importBudgetLib, importGateLib, decimateLib, playCursorLib, gameStorageLib, gameKitLib, moduleWorldLib, playSpawnLib, packRefsLib, lodLib]) => {
+        window.__stores = { ...sceneStore, ...appStore, ...flowStore, meshEdit, vrControls, autosave, voiceChat, audioEngine: audioEngineLib, musicClock: musicClockLib, audioDevices: audioDevicesLib, audioPatch: audioPatchLib, vrPatch: vrPatchLib, musicToolbox: musicToolboxLib, micCapture: micCaptureLib, annotationsHandler, flowRuntime, history, materialsHandler, objectActions, commandsHandler, moduleSDK, drawMode: drawModeLib, pathCapture, lockControl, prefabs: prefabsLib, physics, joints: jointsLib, possess: possessLib, handModels: handModelsLib, terrainSculpt: terrainSculptLib, userModules: userModulesLib, environment: environmentLib, sceneMusic: sceneMusicLib, animatedImports, fileHandler, fileWindows: fileWindowsLib, sceneBounds, cameraClip, ping, sessions: sessionsLib, geometryEdit, lightParams, shadowDefaults: shadowDefaultsLib, palette: paletteLib, viewModeCtl: viewModeLib, inputRuntime: inputRuntimeLib, shortcutsRegistry: shortcutsLib, themes: themesLib, vrRadialMenu, vrPalette: vrPaletteLib, vrWindowPoses: vrWindowPosesLib, vrKeyboard: vrKeyboardLib, faceEdit: faceEditLib, meshToolParams: meshToolParamsLib, avatarModel: avatarModelLib, explorer: explorerLib, bottomDock, explorerDrop, assetShare, soundRuntime, dungeonPlay, sceneAssets: sceneAssetsLib, THREE, GLTFExporterModule, snapping: snappingLib, flowSockets: flowSocketsLib, networkQuality: networkQualityLib, packs: packsLib, customNodes: customNodesLib, nodesHandler: nodesHandlerLib, nodeCatalog: nodeCatalogLib, objectMenu: objectMenuLib, animationPreview: animationPreviewLib, aiProviders: aiProvidersLib, aiTools: aiToolsLib, aiAssistant: aiAssistantLib, meshProviders: meshProvidersLib, meshJobs: meshJobsLib, flowGraphsCtl: flowGraphsLib, objectFlow: objectFlowLib, peerServer: peerServerLib, cloudHooks: cloudHooksLib, cloudPlugin: cloudPluginLib, connectionState: connectionStateLib, peerApproval: peerApprovalLib, particleRuntime: particleRuntimeLib, particleActions: particleActionsLib, particlePresets: particlePresetsLib, version: versionLib, whatsNew: whatsNewLib, confirmDialog: confirmDialogLib, scenePhysics: scenePhysicsLib, playInteract: playInteractLib, moveSmoothing: moveSmoothingLib, knock: knockLib, playSettings: playSettingsLib, colliderSpec: colliderSpecLib, colliderHelpers: colliderHelpersLib, colliderEdit: colliderEditLib, editSession: editSessionLib, trackpadNav: trackpadNavLib, vrSleeve: vrSleeveLib, gridSettings: gridSettingsLib, viewPrefs: viewPrefsLib, cameraBookmarks: cameraBookmarksLib, cameraObjects: cameraObjectsLib, cameraHelpers: cameraHelpersLib, onionSkin: onionSkinLib, cameraPreview: cameraPreviewLib, addObjects: addObjectsLib, cameraPip: cameraPipLib, inputDevice: inputDeviceLib, sceneTemplates: sceneTemplatesLib, bvhPicking: bvhPickingLib, multiTransform: multiTransformLib, objectOrigin: objectOriginLib, moduleGallery: moduleGalleryLib, uvEditor: uvEditorLib, uvUnwrap: uvUnwrapLib, meshTopology: meshTopologyLib, meshBudget: meshBudgetLib, proportional: proportionalLib, proportionalRing: proportionalRingLib, scenePick: scenePickLib, snapEngine: snapEngineLib, meshPivot: meshPivotLib, selectionPrefs: selectionPrefsLib, editOverlays: editOverlaysLib, objectPermissions: objectPermissionsLib, scenePost: scenePostLib, postEffects: postEffectsLib, viewportOverrides: viewportOverridesLib, postprocessing: postprocessingModule, shaderBackends: shaderBackendsLib, shaderGraph: shaderGraphLib, shaderSync: shaderSyncLib, shaderTextures: shaderTexturesLib, shaderCatalog: shaderCatalogLib, units: unitsLib, postBackends: postBackendsLib, workspace: workspaceLib, editResume: editResumeLib, moduleRequirements: moduleRequirementsLib, hudDocs: hudDocsLib, hudSync: hudSyncLib, idb: idbLib, hudKinds: hudKindsLib, hudImages: hudImagesLib, gameState: gameStateLib, gameSync: gameSyncLib, hudActions: hudActionsLib, moduleNodeIO: moduleNodeIOLib, moduleToolboxes: moduleToolboxesLib, splineTube: splineTubeLib, splineTool: splineToolLib, splineEdit: splineEditLib, terrainCarve: terrainCarveLib, flattenActions: flattenActionsLib, hudViewportDrag: hudViewportDragLib, gamepadPrefs: gamepadPrefsLib, charController: charControllerLib, hudRichText: hudRichTextLib, moduleHudKinds: moduleHudKindsLib, hudMinimap: hudMinimapLib, hudArrange: hudArrangeLib, gamePresence: gamePresenceLib, levels: levelsLib, peerVars: peerVarsLib, projectManifest: projectManifestLib, projectFile: projectFileLib, transientObjects: transientObjectsLib, spawner: spawnerLib, triggerSync: triggerSyncLib, saveName: saveNameLib, sceneIdentity: sceneIdentityLib, importDuplicates: importDuplicatesLib, peerScenes: peerScenesLib, sharedLibrary: sharedLibraryLib, transferLedger: transferLedgerLib, explorerView: explorerViewLib, filePreview: filePreviewLib, saveAs: saveAsLib, windowTabs: windowTabsLib, colocation: colocationLib, colocationCalibrate: colocationCalibrateLib, colocationPresence: colocationPresenceLib, xrAnchors: xrAnchorsLib, colocationAnchors: colocationAnchorsLib, colocationNudge: colocationNudgeLib, mountedVolumes: mountedVolumesLib, storageUsage: storageUsageLib, scenePrivacy: scenePrivacyLib, touchControls: touchControlsLib, playMode: playModeLib, objectListNav: objectListNavLib, inviteLinks: inviteLinksLib, helperLayer: helperLayerLib, explorerClipboard: explorerClipboardLib, lookPresence: lookPresenceLib, postGraphs: postGraphsLib, postGraphPresets: postGraphPresetsLib, materialSharing: materialSharingLib, diagnostics: diagnosticsLib, wireValidate: wireValidateLib, wireErrors: wireErrorsLib, safeStorage: safeStorageLib, sceneBudget: sceneBudgetLib, overloadGuard: overloadGuardLib, qualityGovernor: qualityGovernorLib, importBudget: importBudgetLib, importGate: importGateLib, decimate: decimateLib, playCursor: playCursorLib, gameStorage: gameStorageLib, gameKit: gameKitLib, moduleWorld: moduleWorldLib, playSpawn: playSpawnLib, packRefs: packRefsLib, lod: lodLib }
       })
     }
   })
diff --git a/src/components/menu/Settings.svelte b/src/components/menu/Settings.svelte
index be5b89b2..11581476 100644
--- a/src/components/menu/Settings.svelte
+++ b/src/components/menu/Settings.svelte
@@ -30,6 +30,7 @@
 	import { spatialVoice } from '$lib/voiceChat';
 	import { shadowQuality } from '$lib/lightParams';
 	import { autoQuality } from '$lib/qualityGovernor';
+	import { lodEnabled } from '$lib/lod';
 	import { myHandModel, setMyHandModel } from '$lib/handModels';
 	import { explorerItems } from '$lib/explorer';
 	import { pingColor, pingSound } from '$lib/ping';
@@ -1053,6 +1054,10 @@
 						<svelte:fragment slot="control"><Checkbox id="auto-quality" bind:checked={$autoQuality} /></svelte:fragment>
 						When a heavy scene cannot keep 30 frames a second on THIS machine, drop shadows, then resolution, then effects, one step at a time, and give each back when frames recover. Never changes the scene for anyone else; the chip beside the object count says when it is active
 					</SettingRow>
+					<SettingRow name="Simplify distant models">
+						<svelte:fragment slot="control"><Checkbox id="lod-enabled" bind:checked={$lodEnabled} /></svelte:fragment>
+						Draw a lighter version of a dense model (a few thousand triangles or more) when it is far from you, built once per model on THIS machine. Nothing in the scene changes — the full model is what is saved, sent and edited
+					</SettingRow>
 					<SettingRow name="Simulation controls">
 						<svelte:fragment slot="control"><Checkbox bind:checked={$showSimControls} /></svelte:fragment>
 						Show the physics transport (play/pause/stop/reset) at bottom-right. Off by default to avoid confusion with the main play button; the P key still starts/stops the simulation
diff --git a/src/lib/decimateCore.js b/src/lib/decimateCore.js
index 70bbcd5e..fa3da0a9 100644
--- a/src/lib/decimateCore.js
+++ b/src/lib/decimateCore.js
@@ -20,7 +20,7 @@
  * @typedef {{key: string, positions: Float32Array, normals?: Float32Array | null,
  *   uvs?: Float32Array | null, colors?: Float32Array | null, colorSize?: number,
  *   index?: Uint32Array | null, groups?: {start: number, count: number, materialIndex?: number}[],
- *   target: number}} MeshIn
+ *   target: number, errorCap?: number}} MeshIn
  * @typedef {{key: string, positions: Float32Array, normals: Float32Array | null,
  *   uvs: Float32Array | null, colors: Float32Array | null, colorSize: number, index: Uint32Array,
  *   groups: {start: number, count: number, materialIndex?: number}[], triangles: number,
@@ -144,6 +144,10 @@ export function simplifyMesh(simplifier, mesh) {
 	const groups = mesh.groups?.length ? mesh.groups : [{ start: 0, count: index.length }];
 	const multi = groups.length > 1;
 	const ratio = before > 0 ? Math.min(1, Math.max(0, mesh.target / before)) : 1;
+	// 31-perf: a LOD level asks for its own error ceiling (a far level may go as far as the
+	// count asks); absent = the import gate's ERROR_CAP, byte-identical
+	const cap = Number(mesh.errorCap);
+	const errorCap = Number.isFinite(cap) && cap > 0 ? cap : ERROR_CAP;
 	/** @type {Uint32Array[]} */
 	const pieces = [];
 	/** @type {{start: number, count: number, materialIndex?: number}[]} */
@@ -158,8 +162,8 @@ export function simplifyMesh(simplifier, mesh) {
 		const flags = multi ? ['LockBorder'] : [];
 		/** @type {[Uint32Array, number]} */
 		const [out, err] = attrs
-			? simplifier.simplifyWithAttributes(slice, positions, 3, attrs, stride, weights, null, Math.min(targetCount, slice.length), ERROR_CAP, flags)
-			: simplifier.simplify(slice, positions, 3, Math.min(targetCount, slice.length), ERROR_CAP, flags);
+			? simplifier.simplifyWithAttributes(slice, positions, 3, attrs, stride, weights, null, Math.min(targetCount, slice.length), errorCap, flags)
+			: simplifier.simplify(slice, positions, 3, Math.min(targetCount, slice.length), errorCap, flags);
 		pieces.push(out);
 		outGroups.push({ start: at, count: out.length, ...(group.materialIndex !== undefined ? { materialIndex: group.materialIndex } : {}) });
 		at += out.length;
diff --git a/src/lib/lod.js b/src/lib/lod.js
new file mode 100644
index 00000000..526aad44
--- /dev/null
+++ b/src/lib/lod.js
@@ -0,0 +1,558 @@
+import * as THREE from 'three';
+import { writable, get } from 'svelte/store';
+import { globalScene, objectsGroup } from '../stores/sceneStore';
+import { safeStorage } from './safeStorage';
+import {
+	DEFAULT_LOD,
+	EXPLICIT_MIN_TRIANGLES,
+	normalizeLodOptions,
+	levelsToBuild,
+	pickLevel,
+	geometrySignature
+} from './lodCore';
+
+// 31-perf P2 — AUTOMATIC LEVELS OF DETAIL, WITHOUT TOUCHING THE TREE.
+//
+// THE DESIGN DECISION, and why it is not a THREE.LOD: objectsGroup IS the replicated
+// document (golden rule 5). Wrapping a loaded model in a LOD node would change what every
+// serializer writes (sendObjects, GLTF save, autosave, sessions, undo), what the object
+// list shows, what a flow's Object Selector resolves and what the mesh tools edit — five
+// paths to keep consistent for a feature that is a fact about THIS screen. So the tree is
+// left alone and the swap happens only while the renderer is drawing:
+//   scene.onBeforeRender  -> for each registered mesh, pick a level by distance and put
+//                            that level's geometry on the mesh
+//   scene.onAfterRender   -> put the source geometry back
+// three calls both inside `renderer.render()` (after updateMatrixWorld, before culling),
+// so every render pass of a frame — the shadow map, the composer's scene pass, N8AO, an XR
+// eye pair — draws the level, while EVERYTHING ELSE (picking, BVH, physics hulls, the mesh
+// tools, every serializer, a peer message landing between frames) only ever sees the
+// source geometry. The swap is two property writes per mesh per render call.
+//
+// LEVELS are meshoptimizer-simplified in the existing decimation Worker (decimateWorker.js
+// — the same simplifier the import gate uses, already a dependency), built ONCE per asset:
+// keyed by a content signature, so fifty placements of one pack piece or ten parses of one
+// enemy GLB share one set. A mesh whose geometry is swapped (meshgeo, an undo) or edited
+// in place (sculpt bumps the position version) stops swapping at once and is rebuilt only
+// after it has been stable for a while — a stroke in progress never pays for a rebuild.
+//
+// WHAT IS LEFT ALONE: skinned meshes and morph targets (the simplifier cannot carry
+// weights/deltas), instanced meshes in AUTO mode (one centre for instances spread across a
+// dungeon means nothing), and anything under `minTriangles`. A module can still ask for
+// any of its own meshes through `api.lod(object, opts)`.
+//
+// LOCAL, like every quality decision: nothing here replicates, saves or undoes. The
+// `lodEnabled` pref (default ON) is the opt-out; the quality governor's `lodBias` pulls the
+// switch distances in as it steps down (P3).
+
+/** @typedef {import('./lodCore').LodOptions} LodOptions */
+/**
+ * @typedef {{mesh: any, source: any, version: number, sig: string, opts: LodOptions,
+ *   edges: number[], levels: any[] | null, current: number, explicit: boolean,
+ *   stableSince: number, owner: any}} LodEntry
+ */
+
+/** The opt-out. LOCAL, default ON. */
+export const lodEnabled = writable(safeStorage.getItem('lodEnabled') !== 'false');
+let lodEnabledSeen = false;
+lodEnabled.subscribe((on) => {
+	if (!lodEnabledSeen) {
+		lodEnabledSeen = true;
+		return;
+	}
+	safeStorage.setItem('lodEnabled', on ? 'true' : 'false');
+});
+
+/** The multiplier on every switch distance (< 1 = coarser sooner). Written by the quality
+ * governor (P3); a plain number store so this module never imports it. */
+export const lodBias = writable(1);
+
+/** How long a mesh's geometry must stand still before its levels are (re)built. */
+const STABLE_MS = 1500;
+/** How often the auto scan walks the scene. Cheap (a traversal), and it catches module
+ * content that has no store to poke. */
+const SCAN_MS = 2000;
+
+/** @type {Map<any, LodEntry>} */
+const entries = new Map();
+/** @type {Map<string, {levels: Promise<any[]|null>, value: any[]|null, refs: number, ratios: number[]}>} */
+const cache = new Map();
+/** meshes swapped in the render pass now in progress: [mesh, source] pairs */
+/** @type {any[]} */
+const swapped = [];
+let renderDepth = 0;
+/** @type {any} */
+let hookedScene = null;
+/** @type {any} */
+let prevBefore = null;
+/** @type {any} */
+let prevAfter = null;
+/** @type {ReturnType<typeof setInterval> | null} */
+let scanTimer = null;
+let enabled = true;
+let bias = 1;
+const stats = { entries: 0, drawnCoarse: 0, trianglesSaved: 0, builds: 0, lastBuildMs: 0 };
+
+function now() {
+	return typeof performance !== 'undefined' ? performance.now() : Date.now();
+}
+
+/** @param {any} g */
+function trianglesOf(g) {
+	if (!g) return 0;
+	if (g.index) return Math.floor(g.index.count / 3);
+	const p = g.attributes?.position;
+	return p ? Math.floor(p.count / 3) : 0;
+}
+
+/** Why a mesh cannot take levels, '' when it can. @param {any} mesh @param {boolean} explicit */
+function whyNot(mesh, explicit) {
+	if (!mesh?.isMesh || !mesh.geometry?.attributes?.position) return 'not a mesh';
+	if (mesh.isSkinnedMesh) return 'skinned';
+	if (mesh.isInstancedMesh && !explicit) return 'instanced';
+	const morph = mesh.geometry.morphAttributes;
+	if (morph && Object.keys(morph).some((k) => morph[k]?.length)) return 'morph targets';
+	if (mesh.userData?.lod === false) return 'opted out';
+	return '';
+}
+
+// ---- the worker ------------------------------------------------------------------------
+
+/** @type {Worker | null} */
+let worker = null;
+/** @type {ReturnType<typeof setTimeout> | null} */
+let workerIdle = null;
+let nextJob = 1;
+/** @type {Map<number, {resolve: (v: any) => void, reject: (e: any) => void}>} */
+const pending = new Map();
+/** The seam a test (or a module-less build) can replace. @returns {Worker} */
+let makeWorker = () => new Worker(new URL('./decimateWorker.js', import.meta.url), { type: 'module' });
+
+function ensureWorker() {
+	if (workerIdle) clearTimeout(workerIdle);
+	workerIdle = null;
+	if (worker) return worker;
+	worker = makeWorker();
+	worker.onmessage = (event) => {
+		const job = pending.get(event.data?.id);
+		if (!job) return;
+		pending.delete(event.data.id);
+		if (event.data.error) job.reject(new Error(event.data.error));
+		else job.resolve(event.data.results ?? []);
+		if (!pending.size) {
+			// the simplifier's wasm heap grows to the biggest mesh it saw: let it go when idle
+			workerIdle = setTimeout(() => {
+				worker?.terminate();
+				worker = null;
+			}, 10000);
+		}
+	};
+	worker.onerror = (event) => {
+		for (const job of pending.values()) job.reject(new Error(event?.message || 'LOD worker failed'));
+		pending.clear();
+		worker?.terminate();
+		worker = null;
+	};
+	return worker;
+}
+
+/** @param {any} attribute @param {number} size */
+function floatsOf(attribute, size) {
+	if (!attribute) return null;
+	const count = attribute.count;
+	const out = new Float32Array(count * size);
+	if (!attribute.isInterleavedBufferAttribute && !attribute.normalized && attribute.array instanceof Float32Array && attribute.itemSize === size) {
+		out.set(attribute.array.subarray(0, count * size));
+		return out;
+	}
+	for (let i = 0; i < count; i++) for (let c = 0; c < size; c++) out[i * size + c] = attribute.getComponent(i, c);
+	return out;
+}
+
+/**
+ * Simplify `geometry` once per kept ratio, in the worker. Resolves the level geometries
+ * (coarse last), or null when nothing useful came back.
+ * @param {any} geometry @param {number[]} ratios @returns {Promise<any[]|null>}
+ */
+function buildLevels(geometry, ratios) {
+	const before = trianglesOf(geometry);
+	const g = geometry;
+	const color = g.attributes.color;
+	/** @type {any[]} */
+	const jobs = [];
+	/** @type {ArrayBuffer[]} */
+	const transfer = [];
+	ratios.forEach((ratio, i) => {
+		const job = {
+			key: String(i),
+			positions: floatsOf(g.attributes.position, 3),
+			normals: floatsOf(g.attributes.normal, 3),
+			uvs: floatsOf(g.attributes.uv, 2),
+			colors: color ? floatsOf(color, color.itemSize) : null,
+			colorSize: color?.itemSize ?? 3,
+			index: g.index ? Uint32Array.from(g.index.array.subarray(0, g.index.count)) : null,
+			groups: (g.groups ?? []).map((/** @type {any} */ gr) => ({ start: gr.start, count: gr.count, materialIndex: gr.materialIndex })),
+			target: Math.max(3, Math.floor(before * ratio)),
+			// a far level is judged by its silhouette, not its surface: let the simplifier go
+			// as far as the count asks (the import gate caps error at 5%; a LOD must not)
+			errorCap: 1
+		};
+		for (const key of ['positions', 'normals', 'uvs', 'colors', 'index']) {
+			const array = /** @type {any} */ (job)[key];
+			if (array?.buffer && !transfer.includes(array.buffer)) transfer.push(array.buffer);
+		}
+		jobs.push(job);
+	});
+	const id = nextJob++;
+	const started = now();
+	return new Promise((resolve, reject) => {
+		pending.set(id, { resolve, reject });
+		try {
+			ensureWorker().postMessage({ id, meshes: jobs }, transfer);
+		} catch (error) {
+			pending.delete(id);
+			reject(error);
+		}
+	}).then((/** @type {any} */ results) => {
+		stats.builds++;
+		stats.lastBuildMs = Math.round(now() - started);
+		/** @type {any[]} */
+		const levels = [];
+		let previous = before;
+		for (const r of results.sort((/** @type {any} */ a, /** @type {any} */ b) => Number(a.key) - Number(b.key))) {
+			const tris = r.index.length / 3;
+			// the simplifier could not get meaningfully coarser (locked group borders, a
+			// mesh already minimal): a level that saves nothing is only a pop
+			if (tris > previous * 0.9) continue;
+			const level = new THREE.BufferGeometry();
+			level.name = (geometry.name || 'geometry') + ' LOD' + (levels.length + 1);
+			level.setAttribute('position', new THREE.BufferAttribute(r.positions, 3));
+			if (r.normals) level.setAttribute('normal', new THREE.BufferAttribute(r.normals, 3));
+			if (r.uvs) level.setAttribute('uv', new THREE.BufferAttribute(r.uvs, 2));
+			if (r.colors) level.setAttribute('color', new THREE.BufferAttribute(r.colors, r.colorSize));
+			level.setIndex(new THREE.BufferAttribute(r.index, 1));
+			for (const group of r.groups ?? []) level.addGroup(group.start, group.count, group.materialIndex ?? 0);
+			if (r.recomputeNormals || !r.normals) level.computeVertexNormals();
+			level.computeBoundingBox();
+			level.computeBoundingSphere();
+			level.userData = { lodLevel: levels.length + 1, lodOf: geometry.uuid };
+			levels.push(level);
+			previous = tris;
+		}
+		return levels.length ? levels : null;
+	});
+}
+
+// ---- the registry -------------------------------------------------------------------------
+
+/** @param {LodEntry} entry */
+function release(entry) {
+	const c = cache.get(entry.sig);
+	if (!c) return;
+	c.refs--;
+	if (c.refs <= 0) {
+		cache.delete(entry.sig);
+		for (const level of c.value ?? []) level.dispose();
+	}
+}
+
+/**
+ * Start (or restart) an entry's levels for its current source geometry.
+ * @param {LodEntry} entry
+ */
+function requestLevels(entry) {
+	const geometry = entry.mesh.geometry;
+	const tris = trianglesOf(geometry);
+	const kept = levelsToBuild(tris, entry.opts);
+	entry.source = geometry;
+	entry.version = geometry.attributes.position.version;
+	entry.levels = null;
+	entry.current = 0;
+	entry.edges = kept.map((i) => entry.opts.distances[i]);
+	if (!kept.length) {
+		entry.sig = '';
+		return;
+	}
+	const ratios = kept.map((i) => entry.opts.ratios[i]);
+	const sig = geometrySignature(geometry.attributes.position.array, geometry.index?.count ?? 0) + '|' + ratios.join(',');
+	entry.sig = sig;
+	/** @type {any} */
+	let c = cache.get(sig);
+	if (!c) {
+		/** @type {any} */
+		const fresh = { levels: null, value: null, refs: 0, ratios };
+		fresh.levels = buildLevels(geometry, ratios)
+			.then((levels) => {
+				fresh.value = levels;
+				return levels;
+			})
+			.catch(() => null);
+		cache.set(sig, fresh);
+		c = fresh;
+	}
+	c.refs++;
+	const mine = sig;
+	c.levels.then((/** @type {any[]|null} */ levels) => {
+		// the mesh may have moved on (a new geometry, unregistered) while the worker ran
+		if (entries.get(entry.mesh) !== entry || entry.sig !== mine || !levels) return;
+		// a level the simplifier dropped leaves its distance unpaired: keep edges aligned
+		entry.levels = levels;
+		entry.edges = entry.edges.slice(0, levels.length);
+	});
+}
+
+/**
+ * Register one mesh. @param {any} mesh @param {Partial<LodOptions>} opts
+ * @param {boolean} explicit @param {any} owner @returns {boolean}
+ */
+function registerMesh(mesh, opts, explicit, owner) {
+	if (whyNot(mesh, explicit)) return false;
+	const o = normalizeLodOptions({ ...(explicit ? { minTriangles: EXPLICIT_MIN_TRIANGLES } : {}), ...opts });
+	if (trianglesOf(mesh.geometry) < o.minTriangles || !o.ratios.length) return false;
+	const existing = entries.get(mesh);
+	if (existing) {
+		// explicit wins over auto; an auto rescan never downgrades an explicit entry
+		if (existing.explicit && !explicit) return true;
+		if (!explicit) return true;
+		unregisterMesh(mesh);
+	}
+	/** @type {LodEntry} */
+	const entry = {
+		mesh,
+		source: null,
+		version: -1,
+		sig: '',
+		opts: o,
+		edges: [],
+		levels: null,
+		current: 0,
+		explicit,
+		stableSince: now(),
+		owner
+	};
+	entries.set(mesh, entry);
+	requestLevels(entry);
+	stats.entries = entries.size;
+	return true;
+}
+
+/** @param {any} mesh */
+function unregisterMesh(mesh) {
+	const entry = entries.get(mesh);
+	if (!entry) return;
+	entries.delete(mesh);
+	release(entry);
+	stats.entries = entries.size;
+}
+
+/**
+ * Levels for every eligible mesh under `object` — the `api.lod` seam. Options are
+ * `{ratios?, distances?, minTriangles?}` (see lodCore.DEFAULT_LOD). Returns a handle whose
+ * `remove()` gives the meshes their plain geometry back for good, and `ready` resolves once
+ * every level has been built (or failed).
+ * @param {any} object @param {Partial<LodOptions>} [opts] @param {any} [owner]
+ */
+export function lodObject(object, opts = {}, owner = null) {
+	/** @type {any[]} */
+	const meshes = [];
+	object?.traverse?.((/** @type {any} */ o) => {
+		if (registerMesh(o, opts, true, owner)) meshes.push(o);
+	});
+	installHooks();
+	const ready = Promise.all(meshes.map((m) => cache.get(entries.get(m)?.sig ?? '')?.levels ?? null)).then(() => meshes.length);
+	return {
+		meshes: meshes.length,
+		ready,
+		remove() {
+			for (const m of meshes) if (entries.get(m)?.owner === owner) unregisterMesh(m);
+		}
+	};
+}
+
+/** Drop every entry a module owns (its teardown journal). @param {any} owner */
+export function releaseOwner(owner) {
+	for (const [mesh, entry] of [...entries]) if (entry.explicit && entry.owner === owner) unregisterMesh(mesh);
+}
+
+// ---- the swap -----------------------------------------------------------------------------
+
+function restoreSwapped() {
+	for (let i = 0; i < swapped.length; i += 2) swapped[i].geometry = swapped[i + 1];
+	swapped.length = 0;
+}
+
+/**
+ * scene.onBeforeRender: put each registered mesh's level on it for this render call.
+ * Allocation-free — it runs once per render pass, several times a frame.
+ * @param {any} renderer @param {any} scene @param {any} camera
+ */
+function beforeRender(renderer, scene, camera) {
+	prevBefore?.(renderer, scene, camera);
+	if (renderDepth++ > 0) return; // a nested render (a probe inside a pass) keeps the outer swap
+	restoreSwapped(); // a render that threw last time left a swap behind: never keep it
+	stats.drawnCoarse = 0;
+	stats.trianglesSaved = 0;
+	if (!enabled || !entries.size || !camera?.matrixWorld) return;
+	const ce = camera.matrixWorld.elements;
+	const cx = ce[12];
+	const cy = ce[13];
+	const cz = ce[14];
+	const t = now();
+	for (const entry of entries.values()) {
+		const mesh = entry.mesh;
+		const geometry = mesh.geometry;
+		if (geometry !== entry.source || geometry.attributes.position.version !== entry.version) {
+			// swapped (meshgeo, undo) or edited in place (sculpt): stand down now, rebuild once
+			// it has held still — a stroke in progress must not rebuild every frame
+			if (entry.levels || entry.sig) {
+				release(entry);
+				entry.levels = null;
+				entry.sig = '';
+				entry.source = geometry;
+				entry.version = geometry.attributes.position.version;
+				entry.stableSince = t;
+			} else if (geometry !== entry.source || geometry.attributes.position.version !== entry.version) {
+				entry.source = geometry;
+				entry.version = geometry.attributes.position.version;
+				entry.stableSince = t;
+			}
+			continue;
+		}
+		if (!entry.levels) {
+			if (!entry.sig && t - entry.stableSince > STABLE_MS && trianglesOf(geometry) >= entry.opts.minTriangles) requestLevels(entry);
+			continue;
+		}
+		if (!mesh.visible) continue;
+		const sphere = geometry.boundingSphere ?? (geometry.computeBoundingSphere(), geometry.boundingSphere);
+		if (!sphere) continue;
+		const e = mesh.matrixWorld.elements;
+		const sx = sphere.center.x;
+		const sy = sphere.center.y;
+		const sz = sphere.center.z;
+		const wx = e[0] * sx + e[4] * sy + e[8] * sz + e[12];
+		const wy = e[1] * sx + e[5] * sy + e[9] * sz + e[13];
+		const wz = e[2] * sx + e[6] * sy + e[10] * sz + e[14];
+		const scale = Math.sqrt(Math.max(e[0] * e[0] + e[1] * e[1] + e[2] * e[2], e[4] * e[4] + e[5] * e[5] + e[6] * e[6], e[8] * e[8] + e[9] * e[9] + e[10] * e[10]));
+		const radius = sphere.radius * scale;
+		const dx = wx - cx;
+		const dy = wy - cy;
+		const dz = wz - cz;
+		const level = pickLevel(Math.sqrt(dx * dx + dy * dy + dz * dz), radius, entry.edges, bias, entry.current, entry.opts.hysteresis);
+		entry.current = level;
+		if (level > 0) {
+			const low = entry.levels[level - 1];
+			swapped.push(mesh, geometry);
+			mesh.geometry = low;
+			stats.drawnCoarse++;
+			stats.trianglesSaved += trianglesOf(geometry) - trianglesOf(low);
+		}
+	}
+}
+
+/** scene.onAfterRender: every mesh gets its source geometry back. @param {any[]} args */
+function afterRender(...args) {
+	if (--renderDepth > 0) return;
+	renderDepth = 0;
+	restoreSwapped();
+	prevAfter?.(...args);
+}
+
+function installHooks() {
+	const scene = get(globalScene);
+	if (!scene || hookedScene === scene) return;
+	if (hookedScene) uninstallHooks();
+	prevBefore = scene.onBeforeRender && scene.onBeforeRender !== THREE.Object3D.prototype.onBeforeRender ? scene.onBeforeRender : null;
+	prevAfter = scene.onAfterRender && scene.onAfterRender !== THREE.Object3D.prototype.onAfterRender ? scene.onAfterRender : null;
+	scene.onBeforeRender = beforeRender;
+	scene.onAfterRender = afterRender;
+	hookedScene = scene;
+}
+
+function uninstallHooks() {
+	restoreSwapped();
+	if (!hookedScene) return;
+	if (hookedScene.onBeforeRender === beforeRender) hookedScene.onBeforeRender = prevBefore ?? THREE.Object3D.prototype.onBeforeRender;
+	if (hookedScene.onAfterRender === afterRender) hookedScene.onAfterRender = prevAfter ?? THREE.Object3D.prototype.onAfterRender;
+	hookedScene = null;
+	prevBefore = null;
+	prevAfter = null;
+	renderDepth = 0;
+}
+
+// ---- the auto scan ------------------------------------------------------------------------
+
+/** Walk objectsGroup + the module world root: register dense meshes, forget departed ones.
+ * Exported for the suite. */
+export function scanForLod() {
+	installHooks();
+	const scene = get(globalScene);
+	const group = get(objectsGroup);
+	/** @type {Set<any>} */
+	const seen = new Set();
+	if (enabled) {
+		const visit = (/** @type {any} */ root) =>
+			root?.traverse?.((/** @type {any} */ o) => {
+				if (!o.isMesh) return;
+				seen.add(o);
+				if (!entries.has(o)) registerMesh(o, {}, false, null);
+			});
+		visit(group);
+		visit(scene?.getObjectByName?.('module-world-root'));
+	}
+	// an auto entry whose mesh left the scene is dropped; an explicit one stays until its
+	// owner says so (a module may park content off-scene and put it back)
+	for (const [mesh, entry] of [...entries]) {
+		if (entry.explicit) continue;
+		if (!seen.has(mesh)) unregisterMesh(mesh);
+	}
+}
+
+/** Start the scan + hooks (App boot). Idempotent. */
+export function startLod() {
+	if (scanTimer || typeof window === 'undefined') return;
+	scanTimer = setInterval(scanForLod, SCAN_MS);
+	globalScene.subscribe(() => installHooks());
+	scanForLod();
+}
+
+lodEnabled.subscribe((on) => {
+	enabled = on;
+	if (!on) restoreSwapped();
+});
+lodBias.subscribe((b) => {
+	bias = Number.isFinite(b) && b > 0 ? b : 1;
+});
+
+/** For the probe, the suite and the stats plate. */
+export function lodStats() {
+	return {
+		...stats,
+		enabled,
+		bias,
+		cached: cache.size,
+		meshes: [...entries.values()].map((e) => ({
+			name: e.mesh.name,
+			uuid: e.mesh.uuid,
+			explicit: e.explicit,
+			triangles: trianglesOf(e.source ?? e.mesh.geometry),
+			levels: e.levels?.map((l) => trianglesOf(l)) ?? null,
+			edges: e.edges,
+			current: e.current
+		}))
+	};
+}
+
+/** TEST-ONLY seams. */
+export const lodForTest = {
+	/** @param {() => Worker} factory */
+	setWorkerFactory(factory) {
+		makeWorker = factory;
+	},
+	/** @param {any} mesh @param {Partial<LodOptions>} [opts] */
+	register: (mesh, opts = {}) => registerMesh(mesh, opts, false, null),
+	unregister: unregisterMesh,
+	defaults: DEFAULT_LOD,
+	reset() {
+		for (const mesh of [...entries.keys()]) unregisterMesh(mesh);
+		restoreSwapped();
+	}
+};
diff --git a/src/lib/lodCore.js b/src/lib/lodCore.js
new file mode 100644
index 00000000..31db2cec
--- /dev/null
+++ b/src/lib/lodCore.js
@@ -0,0 +1,149 @@
+// 31-perf P2 — THE LOD RULE. PURE and import-free: which level a mesh draws at a given
+// distance, which simplified levels are worth building for a mesh of N triangles, and how
+// the adaptive quality level leans on both. The runtime (`lod.js`) owns the geometry, the
+// worker and the render-time swap; this file is only arithmetic, so vitest drives every
+// threshold with invented numbers.
+//
+// DISTANCE IS MEASURED IN RADII. A level switches at `distance / radius > d[i]`, where the
+// radius is the mesh's WORLD bounding sphere: a 1 m enemy and a 20 m statue both keep full
+// detail while they fill the same share of the view, which is what a triangle budget cares
+// about. (Screen-projected size would add the FOV; a headset's ~100 degree eye and the
+// desktop's 40-50 degree lens differ by ~2x, which the quality bias covers in practice.)
+//
+// HYSTERESIS: a mesh standing on a switch distance would flip every frame as a head bobs —
+// a visible pop each time. Going DOWN a level (coarser) needs the distance past the edge;
+// coming back UP needs it back inside the edge by `hysteresis` of it.
+
+/** @typedef {{ratios: number[], distances: number[], minTriangles: number, hysteresis: number, floorTriangles: number}} LodOptions */
+
+/** @type {LodOptions} */
+export const DEFAULT_LOD = Object.freeze({
+	/** share of the source triangles each coarser level keeps */
+	ratios: [0.5, 0.25, 0.1],
+	/** distance / world radius at which level i+1 takes over from level i */
+	distances: [8, 20, 50],
+	/** auto LOD only considers a mesh at least this dense (explicit `api.lod` passes its own) */
+	minTriangles: 3000,
+	/** a level must come back inside its edge by this share of it before detail returns */
+	hysteresis: 0.12,
+	/** no level is built below this many triangles — past it a silhouette falls apart */
+	floorTriangles: 120
+});
+
+/** The minimum an EXPLICIT `api.lod(object)` asks of a mesh: the module said so, but a
+ * 12-triangle box has nothing to take away. */
+export const EXPLICIT_MIN_TRIANGLES = 300;
+
+/**
+ * Normalise caller options onto the defaults: finite, positive, strictly decreasing ratios
+ * and strictly increasing distances, the two arrays trimmed to the same length.
+ * @param {Partial<LodOptions>} [opts] @returns {LodOptions}
+ */
+export function normalizeLodOptions(opts = {}) {
+	const ratios = (Array.isArray(opts.ratios) ? opts.ratios : DEFAULT_LOD.ratios)
+		.map(Number)
+		.filter((r) => Number.isFinite(r) && r > 0 && r < 1);
+	const distances = (Array.isArray(opts.distances) ? opts.distances : DEFAULT_LOD.distances)
+		.map(Number)
+		.filter((d) => Number.isFinite(d) && d > 0);
+	/** @type {number[]} */
+	const r = [];
+	for (const v of ratios) if (!r.length || v < r[r.length - 1]) r.push(v);
+	/** @type {number[]} */
+	const d = [];
+	for (const v of distances) if (!d.length || v > d[d.length - 1]) d.push(v);
+	// a level with no distance can never be chosen; a distance with no level has nothing to show
+	const n = Math.min(r.length, d.length);
+	const num = (/** @type {any} */ v, /** @type {number} */ fallback) => (Number.isFinite(Number(v)) && Number(v) >= 0 ? Number(v) : fallback);
+	return {
+		ratios: r.slice(0, n),
+		distances: d.slice(0, n),
+		minTriangles: num(opts.minTriangles, DEFAULT_LOD.minTriangles),
+		hysteresis: Math.min(0.5, num(opts.hysteresis, DEFAULT_LOD.hysteresis)),
+		floorTriangles: num(opts.floorTriangles, DEFAULT_LOD.floorTriangles)
+	};
+}
+
+/**
+ * Which coarser levels to BUILD for a mesh of `triangles`: each kept ratio must leave at
+ * least `floorTriangles` and be meaningfully coarser (<= 80%) than the level before it,
+ * or the level costs memory and a pop for nothing. Returns the kept indices into
+ * `opts.ratios` (so distances stay paired with their ratio).
+ * @param {number} triangles @param {LodOptions} opts @returns {number[]}
+ */
+export function levelsToBuild(triangles, opts) {
+	/** @type {number[]} */
+	const keep = [];
+	let previous = triangles;
+	opts.ratios.forEach((ratio, i) => {
+		const target = Math.floor(triangles * ratio);
+		if (target < opts.floorTriangles) return;
+		if (target > previous * 0.8) return;
+		keep.push(i);
+		previous = target;
+	});
+	return keep;
+}
+
+/**
+ * The level to draw: 0 = the source, i = the i-th built level. `edges[i]` is where level
+ * i+1 takes over (already paired to what was built), `bias` scales every edge (< 1 =
+ * coarser sooner), `current` is last frame's pick for the hysteresis band.
+ * @param {number} distance world distance camera -> mesh centre
+ * @param {number} radius world bounding radius (> 0)
+ * @param {number[]} edges ascending, in radii
+ * @param {number} bias
+ * @param {number} current
+ * @param {number} hysteresis
+ * @returns {number}
+ */
+export function pickLevel(distance, radius, edges, bias, current, hysteresis) {
+	if (!edges.length || !(radius > 0) || !Number.isFinite(distance)) return 0;
+	const x = distance / radius;
+	const b = bias > 0 && Number.isFinite(bias) ? bias : 1;
+	let level = 0;
+	for (let i = 0; i < edges.length; i++) {
+		const edge = edges[i] * b;
+		// crossing to a coarser level needs the full edge; staying coarse holds until the
+		// distance is back inside the edge by the band
+		const threshold = current > i ? edge * (1 - hysteresis) : edge;
+		if (x > threshold) level = i + 1;
+		else break;
+	}
+	return level;
+}
+
+/**
+ * How far the adaptive quality leans on LOD: 1 at full quality, and each governor step
+ * pulls the switch distances in. A step taken for FILL (resolution) or DRAW CALLS
+ * (shadows) is also a device that is struggling in general, so triangles go with them.
+ * Clamped at 0.35 so the nearest object always keeps real detail.
+ * @param {number} level the governor level (0 = full) @param {number} [extra] a caller's
+ *   own multiplier (the per-game Quality setting) @returns {number}
+ */
+export function lodBiasFor(level, extra = 1) {
+	const l = Math.max(0, Math.floor(Number(level) || 0));
+	const e = Number.isFinite(Number(extra)) && Number(extra) > 0 ? Number(extra) : 1;
+	return Math.max(0.35, Math.min(2, Math.pow(0.85, l) * e));
+}
+
+/**
+ * A content signature for a geometry: two parses of the same asset (two placements of one
+ * pack piece, a module that loads its GLB per enemy) share one set of levels. Counts plus a
+ * strided sample of the position floats, FNV-1a over their bits — collisions would need the
+ * same vertex count, index count and 64 sampled coordinates.
+ * @param {ArrayLike<number>} positions @param {number} indexCount @returns {string}
+ */
+export function geometrySignature(positions, indexCount) {
+	const n = positions.length;
+	let h = 0x811c9dc5;
+	const f = new Float32Array(1);
+	const u = new Uint32Array(f.buffer);
+	const step = Math.max(1, Math.floor(n / 64));
+	for (let i = 0; i < n; i += step) {
+		f[0] = positions[i];
+		h ^= u[0];
+		h = Math.imul(h, 0x01000193) >>> 0;
+	}
+	return n + ':' + indexCount + ':' + h.toString(36);
+}
diff --git a/src/lib/moduleSDK.js b/src/lib/moduleSDK.js
index 9eacc612..4ecaa697 100644
--- a/src/lib/moduleSDK.js
+++ b/src/lib/moduleSDK.js
@@ -51,6 +51,7 @@ export { moduleContentDebug } from './moduleContent';
 import { safeStorage } from './safeStorage';
 // 30 P4: api.storage — a LEAF (safeStorage only), shared with the Store Value flow node
 import { makeModuleStorage } from './gameStorage';
+import { lodObject } from './lod'; // 31-perf K4 (a leaf: three + stores)
 // 30b (vr-play) C5: the game sound set and game music — LEAVES (svelte/store, audioEngine,
 // safeStorage, sessionClock, sceneStore), so static edges close no cycle
 import { isGameSound, playGameSound } from './gameSfx';
@@ -1322,6 +1323,26 @@ function makeApi(moduleId, moduleName = moduleId) {
 				showToast(`"${moduleName}" hit its 256 KB storage limit on this device — that value was not saved.`);
 			}
 		}),
+		/**
+		 * 31-perf K4: LEVELS OF DETAIL for the module's own geometry (auto LOD already covers
+		 * dense meshes in objectsGroup and under the module world root). Every mesh under
+		 * `object` with at least 300 triangles gets meshoptimizer-simplified levels, built ONCE
+		 * per asset in a worker and drawn by distance — a RENDER-TIME swap, so the mesh keeps
+		 * its geometry for everything else (picking, physics, your own code). `opts`:
+		 * `{ratios?: number[], distances?: number[], minTriangles?: number}` — ratios are the
+		 * share of triangles each level keeps (default [0.5, 0.25, 0.1]), distances are in
+		 * world RADII of the mesh where each level takes over (default [8, 20, 50]); the quality
+		 * level pulls the distances in on a struggling device. Returns `{meshes, ready, remove}`;
+		 * LOCAL, never replicated, and released when the module is disabled. Skinned meshes and
+		 * morph targets are skipped (the simplifier cannot carry weights). Set
+		 * `mesh.userData.lod = false` on a mesh to keep it out of auto LOD.
+		 * @param {any} object @param {{ratios?: number[], distances?: number[], minTriangles?: number}} [opts]
+		 */
+		lod(object, opts = {}) {
+			const handle = lodObject(object, opts, moduleId);
+			onDispose(() => handle.remove());
+			return handle;
+		},
 		peerVars: {
 			/** Write MY OWN row. @param {string} name @param {number} value */
 			setMine(name, value) {
diff --git a/tests/e2e/lod.test.cjs b/tests/e2e/lod.test.cjs
new file mode 100644
index 00000000..822de5b3
--- /dev/null
+++ b/tests/e2e/lod.test.cjs
@@ -0,0 +1,215 @@
+// 31-perf P2 — AUTOMATIC LEVELS OF DETAIL (src/lib/lod.js; the rule is lodCore.js, unit-tested
+// in tests/unit/lodCore.test.js). This suite proves the WIRING on a live page:
+//   1 a dense mesh in objectsGroup is picked up by the auto scan and its levels are built in
+//     the decimation worker (meshoptimizer), once
+//   2 THE REPORT'S PROPERTY: rendered from far away the frame's triangles DROP; up close they
+//     are the source's — measured from renderer.info around a real render() call
+//   3 the tree is untouched: outside a render the mesh holds its SOURCE geometry, and toJSON
+//     (what every serializer writes) carries the full vertex count
+//   4 COUNTERFACTUAL: with LOD switched off the far render draws every triangle
+//   5 a geometry swap (a meshgeo / an undo) stands the entry down at once — the new geometry
+//     draws whole, never a stale level of the old one
+//   6 one asset, one set of levels: a second mesh sharing the content reuses the cache
+//   7 the quality bias: a governor step pulls the switch distance in
+//   8 api.lod on module content (scene-root, not objectsGroup) + teardown on deactivate
+
+// Run: APP_URL=https://theprototype.app:5263/ npm run e2e -- lod
+const h = require('./helpers.cjs');
+
+h.run(async () => {
+	const browser = await h.launch({ args: h.GPU_ARGS });
+	const A = await h.setupPage(browser, 'A', { context: { viewport: { width: 1280, height: 720 } } });
+	const page = A.page;
+
+	// in-page helpers: a dense sphere, a manual render from an explicit camera distance
+	await page.evaluate(() => {
+		const s = window.__stores;
+		const read = (store) => {
+			let v;
+			store.subscribe((x) => (v = x))();
+			return v;
+		};
+		window.__lodt = {
+			read,
+			/** a dense mesh in objectsGroup (a loaded model's shape: one indexed mesh) */
+			addDense(name, detail = 48, at = [0, 1, 0]) {
+				const THREE = s.THREE;
+				const geometry = new THREE.SphereGeometry(1, detail * 2, detail);
+				const mesh = new THREE.Mesh(geometry, new THREE.MeshStandardMaterial({ color: 0x88aa44 }));
+				mesh.name = name;
+				mesh.position.set(...at);
+				read(s.objectsGroup).add(mesh);
+				s.pokeScene?.();
+				return { uuid: mesh.uuid, tris: geometry.index.count / 3 };
+			},
+			mesh(name) {
+				return read(s.objectsGroup).getObjectByName(name);
+			},
+			/** render the real scene from `dist` metres in front of `target` and read the
+			 * triangles that ONE render() drew (shadow pass included) */
+			renderFrom(dist, target = [0, 1, 0]) {
+				const THREE = s.THREE;
+				const r = read(s.globalRenderer);
+				const scene = read(s.globalScene);
+				const cam = new THREE.PerspectiveCamera(50, 16 / 9, 0.1, 5000);
+				cam.position.set(target[0], target[1], target[2] + dist);
+				cam.lookAt(...target);
+				cam.updateMatrixWorld(true);
+				const auto = r.info.autoReset;
+				r.info.autoReset = true;
+				r.render(scene, cam);
+				const tris = r.info.render.triangles;
+				r.info.autoReset = auto;
+				return tris;
+			}
+		};
+	});
+	const stats = () => page.evaluate(() => window.__stores.lod.lodStats());
+	const lodOf = async (name) => (await stats()).meshes.find((m) => m.name === name) ?? null;
+
+	// ---- 1 the auto scan picks the dense mesh up and builds its levels ------------------------
+	const dense = await page.evaluate(() => window.__lodt.addDense('LOD dense', 48));
+	h.check(dense.tris > 3000, '1.0 (premise) the mesh is dense enough for auto LOD (' + dense.tris + ' tris)');
+	await page.evaluate(() => window.__stores.lod.scanForLod());
+	await h.eventually(() => lodOf('LOD dense'), (m) => !!m && Array.isArray(m.levels) && m.levels.length >= 2, '1.1 the auto scan registered it and the worker built its levels', 20000);
+	const entry = await lodOf('LOD dense');
+	h.check(entry.levels[0] < entry.triangles * 0.6 && entry.levels[entry.levels.length - 1] < entry.triangles * 0.2, '1.2 each level is really coarser: ' + entry.triangles + ' -> ' + entry.levels.join(' -> '));
+	const small = await page.evaluate(() => {
+		const s = window.__stores;
+		const THREE = s.THREE;
+		const m = new THREE.Mesh(new THREE.BoxGeometry(1, 1, 1), new THREE.MeshStandardMaterial());
+		m.name = 'LOD small box';
+		window.__lodt.read(s.objectsGroup).add(m);
+		s.lod.scanForLod();
+		return s.lod.lodStats().meshes.some((e) => e.name === 'LOD small box');
+	});
+	h.check(!small, '1.3 a 12-triangle box is left alone (under minTriangles)');
+
+	// ---- 2 far away the frame's triangles drop; near, they are the source's -------------------
+	const near = await page.evaluate(() => window.__lodt.renderFrom(3));
+	const far = await page.evaluate(() => window.__lodt.renderFrom(400));
+	h.check(near >= dense.tris, '2.1 up close the render draws the full mesh (' + near + ' >= ' + dense.tris + ')');
+	h.check(far < near - dense.tris * 0.8, '2.2 THE PROPERTY: from 400 m the frame draws the LOW level (' + far + ' tris vs ' + near + ' near)');
+	const mid = await page.evaluate(() => window.__lodt.renderFrom(12));
+	h.check(mid < near && mid > far, '2.3 a middle distance draws a middle level (' + far + ' < ' + mid + ' < ' + near + ')');
+
+	// ---- 3 the tree is untouched ----------------------------------------------------------------
+	const tree = await page.evaluate(() => {
+		const m = window.__lodt.mesh('LOD dense');
+		window.__lodt.renderFrom(400);
+		const json = m.toJSON();
+		const levels = window.__stores.lod.lodStats().meshes.find((e) => e.name === 'LOD dense');
+		return {
+			tris: m.geometry.index.count / 3,
+			levelTag: m.geometry.userData?.lodLevel ?? null,
+			jsonGeometry: json.object.geometry,
+			sourceUuid: m.geometry.uuid,
+			jsonGeometries: json.geometries.map((g) => g.type),
+			hasLevels: !!levels?.levels?.length
+		};
+	});
+	h.check(tree.tris === dense.tris && tree.levelTag === null, '3.1 after a far render the mesh holds its SOURCE geometry again (' + tree.tris + ' tris)');
+	h.check(tree.hasLevels && tree.jsonGeometry === tree.sourceUuid && tree.jsonGeometries.join() === 'SphereGeometry', '3.2 toJSON writes the SOURCE geometry and nothing else (' + tree.jsonGeometries.join() + ') — no serializer can see a level');
+
+	// ---- 4 counterfactual: LOD off -> the far render draws every triangle ------------------------
+	const off = await page.evaluate(() => {
+		const s = window.__stores;
+		s.lod.lodEnabled.set(false);
+		const t = window.__lodt.renderFrom(400);
+		s.lod.lodEnabled.set(true);
+		return { t, stored: localStorage.getItem('lodEnabled') };
+	});
+	h.check(off.t >= dense.tris, '4.1 COUNTERFACTUAL: with LOD switched off the far render draws the full mesh (' + off.t + ')');
+	h.check(off.stored === 'true', '4.2 the opt-out is a LOCAL pref, written back on (lodEnabled=' + off.stored + ')');
+
+	// ---- 5 a geometry swap stands the entry down at once ----------------------------------------
+	const swap = await page.evaluate(() => {
+		const s = window.__stores;
+		const THREE = s.THREE;
+		const m = window.__lodt.mesh('LOD dense');
+		m.geometry = new THREE.SphereGeometry(1, 64, 32);
+		const fresh = m.geometry.index.count / 3;
+		const t = window.__lodt.renderFrom(400);
+		return { fresh, t, still: m.geometry.index.count / 3 };
+	});
+	h.check(swap.t >= swap.fresh && swap.still === swap.fresh, '5.1 a swapped geometry draws WHOLE on the next frame — never a stale level of the old one (' + swap.t + ' >= ' + swap.fresh + ')');
+	await h.eventually(
+		async () => {
+			await page.evaluate(() => window.__lodt.renderFrom(400)); // the swap check runs per render
+			return lodOf('LOD dense');
+		},
+		(m) => !!m && m.triangles === swap.fresh && Array.isArray(m.levels) && m.levels.length >= 1,
+		'5.2 once it has held still, the new geometry gets levels of its own',
+		15000
+	);
+
+	// ---- 6 one asset, one set of levels ----------------------------------------------------------
+	const shared = await page.evaluate(async () => {
+		const s = window.__stores;
+		const before = s.lod.lodStats().cached;
+		const a = window.__lodt.addDense('LOD twin A', 40, [5, 1, 0]);
+		const b = window.__lodt.addDense('LOD twin B', 40, [-5, 1, 0]);
+		s.lod.scanForLod();
+		await new Promise((r) => setTimeout(r, 3000));
+		const st = s.lod.lodStats();
+		return { before, after: st.cached, twins: st.meshes.filter((m) => m.name.startsWith('LOD twin')).map((m) => !!m.levels), a: a.tris, b: b.tris };
+	});
+	h.check(shared.twins.length === 2 && shared.twins.every(Boolean), '6.1 both placements have levels');
+	h.check(shared.after === shared.before + 1, '6.2 the two placements of one asset share ONE cached set (cache ' + shared.before + ' -> ' + shared.after + ')');
+
+	// ---- 7 the quality bias pulls the switch distance in -----------------------------------------
+	const bias = await page.evaluate(() => {
+		const s = window.__stores;
+		const edge0 = s.lod.lodStats().meshes.find((m) => m.name === 'LOD twin A').edges[0];
+		const at = (edge0 - 1) * 1; // just inside level 0's edge at bias 1 (radius 1)
+		const full = window.__lodt.renderFrom(at, [5, 1, 0]);
+		s.lod.lodBias.set(0.5);
+		const biased = window.__lodt.renderFrom(at, [5, 1, 0]);
+		s.lod.lodBias.set(1);
+		return { edge0, at, full, biased };
+	});
+	h.check(bias.biased < bias.full, '7.1 at ' + bias.at + ' radii a bias of 0.5 already draws a coarser level (' + bias.full + ' -> ' + bias.biased + ')');
+
+	// ---- 8 api.lod on module content + teardown; api.quality's shape -----------------------------
+	const mod = await page.evaluate(async () => {
+		const s = window.__stores;
+		const out = {};
+		await s.moduleSDK.initModules([
+			{
+				id: 'lodtest',
+				name: 'LOD test',
+				version: '1.0.0',
+				description: 'api.lod',
+				register(api) {
+					const THREE = api.THREE;
+					const group = new THREE.Group();
+					group.name = 'lodtest-content';
+					const m = new THREE.Mesh(new THREE.SphereGeometry(1, 40, 20), new THREE.MeshStandardMaterial());
+					m.name = 'lodtest-ball';
+					m.position.set(0, 1, -30);
+					group.add(m);
+					api.scene().add(group);
+					const handle = api.lod(group, { ratios: [0.3], distances: [4] });
+					out.meshes = handle.meshes;
+					out.readyIsPromise = typeof handle.ready?.then === 'function';
+				}
+			}
+		]);
+		await new Promise((r) => setTimeout(r, 2500));
+		out.registered = s.lod.lodStats().meshes.find((m) => m.name === 'lodtest-ball') ?? null;
+		const r = window.__lodt;
+		// the module's ball is at z -30 at scene root: render from 60 m in front of it
+		out.far = r.renderFrom(60, [0, 1, -30]);
+		s.moduleSDK.deactivateModule('lodtest');
+		out.afterDeactivate = s.lod.lodStats().meshes.some((m) => m.name === 'lodtest-ball');
+		return out;
+	});
+	h.check(mod.meshes === 1 && mod.readyIsPromise, '8.1 api.lod(group) registers the module mesh and returns {meshes, ready, remove}');
+	h.check(!!mod.registered && mod.registered.explicit && Array.isArray(mod.registered.levels) && mod.registered.levels.length === 1, '8.2 the module mesh (scene-root, not objectsGroup) got its explicit level: ' + JSON.stringify(mod.registered));
+	h.check(mod.afterDeactivate === false, '8.5 deactivating the module drops its LOD entries (the teardown journal)');
+
+
+	h.check(h.pageErrors(A).length === 0, 'no page errors (' + JSON.stringify(h.pageErrors(A)) + ')');
+
+	await h.finish(browser);
+});
diff --git a/tests/unit/lodCore.test.js b/tests/unit/lodCore.test.js
new file mode 100644
index 00000000..2444175c
--- /dev/null
+++ b/tests/unit/lodCore.test.js
@@ -0,0 +1,111 @@
+// 31-perf P2 — the LOD rule (src/lib/lodCore.js), pure: level selection with hysteresis,
+// which levels are worth building, option normalisation, the quality bias, the signature.
+import { describe, it, expect } from 'vitest';
+import {
+	DEFAULT_LOD,
+	normalizeLodOptions,
+	levelsToBuild,
+	pickLevel,
+	lodBiasFor,
+	geometrySignature
+} from '../../src/lib/lodCore.js';
+
+describe('pickLevel', () => {
+	const edges = [8, 20, 50];
+	it('draws the source up close and each level past its edge (distance in radii)', () => {
+		expect(pickLevel(5, 1, edges, 1, 0, 0.12)).toBe(0);
+		expect(pickLevel(8.01, 1, edges, 1, 0, 0.12)).toBe(1);
+		expect(pickLevel(25, 1, edges, 1, 0, 0.12)).toBe(2);
+		expect(pickLevel(500, 1, edges, 1, 0, 0.12)).toBe(3);
+	});
+	it('measures in RADII: a 10 m statue at 50 m is as close as a 1 m crate at 5 m', () => {
+		expect(pickLevel(50, 10, edges, 1, 0, 0.12)).toBe(pickLevel(5, 1, edges, 1, 0, 0.12));
+		expect(pickLevel(100, 10, edges, 1, 0, 0.12)).toBe(1);
+	});
+	it('HYSTERESIS: a coarse level holds until the distance is back inside its edge by the band', () => {
+		// at 7.5 radii a mesh that was already coarse stays coarse (7.5 > 8 * 0.88 = 7.04)…
+		expect(pickLevel(7.5, 1, edges, 1, 1, 0.12)).toBe(1);
+		// …while one coming from full detail stays full (7.5 < 8)
+		expect(pickLevel(7.5, 1, edges, 1, 0, 0.12)).toBe(0);
+		// and inside the band, detail returns
+		expect(pickLevel(7, 1, edges, 1, 1, 0.12)).toBe(0);
+		// the band applies per edge: level 2 held at 19 radii, dropped to 1 at 17
+		expect(pickLevel(19, 1, edges, 1, 2, 0.12)).toBe(2);
+		expect(pickLevel(17, 1, edges, 1, 2, 0.12)).toBe(1);
+	});
+	it('the BIAS pulls every edge in (a struggling device goes coarse sooner)', () => {
+		expect(pickLevel(6, 1, edges, 1, 0, 0)).toBe(0);
+		expect(pickLevel(6, 1, edges, 0.5, 0, 0)).toBe(1);
+		expect(pickLevel(12, 1, edges, 0.5, 0, 0)).toBe(2);
+	});
+	it('degenerate input never throws and never goes coarse', () => {
+		expect(pickLevel(100, 0, edges, 1, 0, 0.1)).toBe(0);
+		expect(pickLevel(NaN, 1, edges, 1, 0, 0.1)).toBe(0);
+		expect(pickLevel(100, 1, [], 1, 0, 0.1)).toBe(0);
+		expect(pickLevel(100, 1, edges, 0, 0, 0.1)).toBe(3); // a nonsense bias reads as 1
+	});
+});
+
+describe('levelsToBuild', () => {
+	const opts = normalizeLodOptions({});
+	it('builds every default level for a dense mesh', () => {
+		expect(levelsToBuild(20000, opts)).toEqual([0, 1, 2]);
+	});
+	it('drops a level that would fall under the floor', () => {
+		// 1000 tris: 500, 250 kept; 100 < 120 floor dropped
+		expect(levelsToBuild(1000, opts)).toEqual([0, 1]);
+		expect(levelsToBuild(200, opts)).toEqual([]);
+	});
+	it('drops a level that is not meaningfully coarser than the one before', () => {
+		const o = normalizeLodOptions({ ratios: [0.5, 0.45, 0.1], distances: [5, 10, 20] });
+		expect(levelsToBuild(10000, o)).toEqual([0, 2]);
+	});
+});
+
+describe('normalizeLodOptions', () => {
+	it('defaults', () => {
+		const o = normalizeLodOptions();
+		expect(o.ratios).toEqual(DEFAULT_LOD.ratios);
+		expect(o.distances).toEqual(DEFAULT_LOD.distances);
+		expect(o.minTriangles).toBe(DEFAULT_LOD.minTriangles);
+	});
+	it('keeps only finite, strictly monotone values and pairs the two arrays', () => {
+		const o = normalizeLodOptions(/** @type {any} */ ({ ratios: [0.6, 'x', 1.4, 0.3, 0.3, 0.1], distances: [4, 4, 10] }));
+		expect(o.ratios).toEqual([0.6, 0.3]);
+		expect(o.distances).toEqual([4, 10]);
+	});
+	it('clamps hysteresis and accepts minTriangles 0', () => {
+		expect(normalizeLodOptions({ hysteresis: 3 }).hysteresis).toBe(0.5);
+		expect(normalizeLodOptions({ minTriangles: 0 }).minTriangles).toBe(0);
+		expect(normalizeLodOptions({ minTriangles: -4 }).minTriangles).toBe(DEFAULT_LOD.minTriangles);
+	});
+});
+
+describe('lodBiasFor', () => {
+	it('is 1 at full quality and falls with each governor step, never below 0.35', () => {
+		expect(lodBiasFor(0)).toBe(1);
+		expect(lodBiasFor(1)).toBeCloseTo(0.85);
+		expect(lodBiasFor(3)).toBeLessThan(lodBiasFor(2));
+		expect(lodBiasFor(40)).toBe(0.35);
+	});
+	it('takes a caller multiplier (the per-game Quality setting)', () => {
+		expect(lodBiasFor(0, 0.5)).toBe(0.5);
+		expect(lodBiasFor(0, 1.5)).toBe(1.5);
+		expect(lodBiasFor(0, 9)).toBe(2);
+		expect(lodBiasFor(0, -1)).toBe(1);
+	});
+});
+
+describe('geometrySignature', () => {
+	it('two parses of the same asset agree; different content does not', () => {
+		const a = new Float32Array(3000).map((_, i) => Math.sin(i));
+		const b = Float32Array.from(a);
+		const c = Float32Array.from(a);
+		c[1500] += 0.01; // not necessarily sampled: the counts still separate most assets
+		expect(geometrySignature(a, 900)).toBe(geometrySignature(b, 900));
+		expect(geometrySignature(a, 900)).not.toBe(geometrySignature(a, 903));
+		const d = Float32Array.from(a);
+		d[0] += 1;
+		expect(geometrySignature(a, 900)).not.toBe(geometrySignature(d, 900));
+	});
+});

From aac14ea10f6fd825ad0a7fd8e4539d6e383a8a55 Mon Sep 17 00:00:00 2001
From: AlexZ005 <alexz005.info@gmail.com>
Date: Thu, 1 Oct 2026 01:14:41 +0300
Subject: [PATCH 4/5] [feat] quality in the headset: the governor runs in XR,
 and api.quality (P3, K4)

Until now the adaptive quality governor never ran in VR: its frames came from
sceneBudget's window rAF, which an immersive session suspends, so a Quest sat at full
quality however badly it judged.
- FRAMES: the XR session's own requestAnimationFrame (a second callback beside three's)
  feeds every frame interval, deciding every 250 ms.
- THRESHOLDS from the headset's refresh rate (xrThresholds: over = 1.3 budgets, under =
  1.12 budgets; 72 Hz -> 18.1 / 15.6 ms), re-read on frameratechange, through a new
  governor.setThresholds(). The static VR pair (13.9 / 11.1) could never recover at 72 Hz:
  a healthy frame reads 13.9.
- ENTRY FLOOR: auto mode enters a session at level 1 (shadows off, the Quest budget) and
  holds it as a recovery floor (governor.setFloor) for the session; exit gives the level
  back. The opt-out holds: with auto quality off nothing changes a level.
- RESOLUTION: an XR framebuffer's size is fixed at entry and three already runs maximum
  foveation, so the scale the session needed is applied to the NEXT entry
  (xrScaleAfter -> setFramebufferScaleFactor at sessionend).
- LOD: every published level sets lod.lodBias = 0.85^level (floor 0.35).
- api.quality = {level (getter, 0 best), max, labels, vr, onChange(fn) -> off}; the
  listener fires on level CHANGES only and is released with the module.
- A headset is always "heavy" (governed); the sampler's last reading is a desktop one.
MERGE NOTE (31-game-shell edits the same file): their applyGameQuality pin must win over
the entry floor - `if (gameForcedLevel !== null) return` at the top of startXRQuality's
floor block. Hunks were kept apart from theirs (decideNow / after autoQuality.subscribe).

perf-governor section 6b (8 checks): a session starts at level 1 with shadows off even on
a light scene, judges by 72 Hz, missed XR frames take the next step and pull the LOD bias
in, on-time frames recover to the floor and never past it, exit restores level 0 and the
desktop thresholds, the next-entry scale is kept. COUNTERFACTUAL in-suite: with auto quality
off a session changes no level. vitest: the 72 Hz counterfactual (static pair stuck at
level 1, xrThresholds recovers), missed-frame step + recovery, scale rule.
lod suite 8.3/8.4: api.quality's shape and onChange hearing 2 then 0.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 src/lib/moduleSDK.js               |  39 ++++++++++
 src/lib/qualityGovernor.js         | 115 +++++++++++++++++++++++++++++
 src/lib/qualityGovernorCore.js     |  57 +++++++++++++-
 tests/e2e/lod.test.cjs             |  13 +++-
 tests/e2e/perf-governor.test.cjs   |  48 ++++++++++++
 tests/unit/qualityGovernor.test.js |  61 +++++++++++++++
 6 files changed, 329 insertions(+), 4 deletions(-)

diff --git a/src/lib/moduleSDK.js b/src/lib/moduleSDK.js
index 4ecaa697..89380732 100644
--- a/src/lib/moduleSDK.js
+++ b/src/lib/moduleSDK.js
@@ -52,6 +52,7 @@ import { safeStorage } from './safeStorage';
 // 30 P4: api.storage — a LEAF (safeStorage only), shared with the Store Value flow node
 import { makeModuleStorage } from './gameStorage';
 import { lodObject } from './lod'; // 31-perf K4 (a leaf: three + stores)
+import { qualityState, xrQualityDebug } from './qualityGovernor'; // 31-perf K4 (a leaf)
 // 30b (vr-play) C5: the game sound set and game music — LEAVES (svelte/store, audioEngine,
 // safeStorage, sessionClock, sceneStore), so static edges close no cycle
 import { isGameSound, playGameSound } from './gameSfx';
@@ -1343,6 +1344,44 @@ function makeApi(moduleId, moduleName = moduleId) {
 			onDispose(() => handle.remove());
 			return handle;
 		},
+		/**
+		 * 31-perf K4: the ADAPTIVE QUALITY LEVEL on this device, so a module can cut its own
+		 * effects/particles/draw distance when the frame rate cannot hold. `level` is 0 (best)
+		 * … `max` (every step taken); a headset session starts at 1 (shadows off) in auto mode
+		 * and a game's Quality setting can pin it. `labels` names the steps in force.
+		 * `onChange(fn)` calls `fn(level, {max, labels, reason, vr})` on every level CHANGE and
+		 * returns `off()` (also released when the module is disabled). LOCAL: a fact about this
+		 * machine right now — never make it change shared state.
+		 */
+		quality: {
+			get level() {
+				return get(qualityState).level;
+			},
+			get max() {
+				return get(qualityState).max;
+			},
+			get labels() {
+				return get(qualityState).labels.slice();
+			},
+			get vr() {
+				return xrQualityDebug().active;
+			},
+			/** @param {(level: number, info: {max: number, labels: string[], reason: string, vr: boolean}) => void} fn */
+			onChange(fn) {
+				let last = get(qualityState).level;
+				const off = qualityState.subscribe((q) => {
+					if (q.level === last) return;
+					last = q.level;
+					try {
+						fn(q.level, { max: q.max, labels: q.labels.slice(), reason: q.reason, vr: xrQualityDebug().active });
+					} catch (error) {
+						console.log('module quality listener failed', error);
+					}
+				});
+				onDispose(off);
+				return off;
+			}
+		},
 		peerVars: {
 			/** Write MY OWN row. @param {string} name @param {number} value */
 			setMine(name, value) {
diff --git a/src/lib/qualityGovernor.js b/src/lib/qualityGovernor.js
index f70913cc..3d70ec72 100644
--- a/src/lib/qualityGovernor.js
+++ b/src/lib/qualityGovernor.js
@@ -17,6 +17,10 @@ import {
 import { renderPaused } from './overloadGuard';
 import { sceneBatchOpen } from '../stores/sceneStore';
 import { safeStorage } from './safeStorage';
+import { xrThresholds, XR_START_LEVEL, xrScaleAfter } from './qualityGovernorCore';
+import { globalRenderer } from '../stores/sceneStore';
+import { lodBias } from './lod';
+import { lodBiasFor } from './lodCore';
 
 // 26-D (roadmap 26 section 4, Stage 1) — ADAPTIVE QUALITY: THE WIRING.
 //
@@ -75,6 +79,9 @@ const DECIDE_EVERY_MS = 250;
 export const RELEASE_SNOOZE_MS = 60000;
 
 const governor = createGovernor();
+/** 31-perf P3: the live XR session, as far as quality is concerned.
+ * @type {{active: boolean, session: any, hz: number, last: number, raised: boolean, before: number, minScale: number, nextScale: number}} */
+const xr = { active: false, session: null, hz: 72, last: 0, raised: false, before: 0, minScale: 1, nextScale: 1 };
 let lastDecideAt = 0;
 let wasHidden = false;
 let pinned = false;
@@ -101,6 +108,10 @@ function publish(level, reason) {
 	}
 	if (level === 0) qualityBaseline.set(null);
 	qualityOverrides.set(overridesAt(level));
+	// 31-perf P2/P3: every step also pulls the LOD switch distances in (a struggling device
+	// struggles with triangles too); lod.js reads the bias, never this module
+	lodBias.set(lodBiasFor(level));
+	if (xr.active && overridesAt(level).dprScale < xr.minScale) xr.minScale = overridesAt(level).dprScale;
 	lastReason = reason;
 	qualityState.set({
 		level,
@@ -116,6 +127,11 @@ function publish(level, reason) {
 /** The profile and heaviness the core needs, read off the last sample. */
 function context() {
 	const metrics = get(sceneMetrics);
+	// 31-perf P3: inside an XR session the sampler's window-rAF loop is asleep, so its last
+	// reading is a DESKTOP one from before entry. The session itself is the evidence: VR, and
+	// always worth governing — a missed headset frame is judder, not a slow chart, and the
+	// light-scene exemption (26-G's ruling) exists for a desktop that is merely slow
+	if (xr.active) return { metrics, profile: /** @type {'desktop'|'vr'} */ ('vr'), heavy: true };
 	const profile = metrics?.profile === 'vr' ? 'vr' : 'desktop';
 	return { metrics, profile: /** @type {'desktop'|'vr'} */ (profile), heavy: isHeavy(metrics, profile, get(qualityBaseline)) };
 }
@@ -240,3 +256,102 @@ export const governorForTest = {
 
 registerFrameObserver(noteFrameForQuality);
 registerLongTaskObserver(() => governor.noteLongTask(now()));
+
+// ---- 31-perf P3: THE HEADSET -------------------------------------------------------------
+//
+// Until now the governor never ran in VR: its frames come from sceneBudget's window rAF, which
+// an immersive session suspends, so a Quest sat at full quality however badly it judged. Now:
+//   · FRAMES: the session's own requestAnimationFrame (a second callback beside three's, which
+//     the WebXR spec allows) feeds every frame interval, and decides every 250 ms
+//   · THRESHOLDS: from the headset's refresh rate (xrThresholds: 72 / 90 / 120 Hz), updated on
+//     `frameratechange` — see the core for why the static VR pair could never recover
+//   · START: auto mode enters a session at XR_START_LEVEL (shadows off — the Quest budget) and
+//     gives the level it found back on exit; a lower level reached in the headset is kept
+//     only if it is still needed (the ordinary recovery walks it back)
+//   · RESOLUTION: an XR framebuffer's size is fixed at entry, so the scale a session needed is
+//     applied to the NEXT entry (xrScaleAfter) — three already runs maximum foveation
+// The opt-out holds: with auto quality off, none of this changes a level.
+// MERGE NOTE (31-game-shell): a game's pinned Quality preset must win over the entry floor.
+
+/** @param {any} r */
+function hookXR(r) {
+	if (!r?.xr || r.__qualityXR) return;
+	r.__qualityXR = true;
+	r.xr.addEventListener?.('sessionstart', () => startXRQuality(r.xr.getSession?.()));
+	r.xr.addEventListener?.('sessionend', () => endXRQuality(r));
+}
+globalRenderer.subscribe((r) => hookXR(r));
+
+/** A session began: judge by its rate, feed its frames, take the entry floor.
+ * Exported for the suite (a headless page cannot present). @param {any} session @param {number} [hzOverride] */
+export function startXRQuality(session, hzOverride) {
+	if (xr.active && xr.session === session) return;
+	xr.active = true;
+	xr.session = session ?? null;
+	xr.last = 0;
+	xr.minScale = 1;
+	xr.hz = Number(hzOverride ?? session?.frameRate) || 72;
+	governor.setThresholds(xrThresholds(xr.hz));
+	governor.forget();
+	session?.addEventListener?.('frameratechange', () => {
+		xr.hz = Number(session.frameRate) || xr.hz;
+		governor.setThresholds(xrThresholds(xr.hz));
+		governor.forget();
+	});
+	xr.raised = false;
+	xr.before = governor.level();
+	if (get(autoQuality)) {
+		// the floor HOLDS for the session: recovery must not switch shadows back on because
+		// frames were fine without them — that is the flap the floor exists to prevent
+		governor.setFloor(XR_START_LEVEL);
+		if (governor.level() < XR_START_LEVEL) {
+			governor.setLevel(XR_START_LEVEL, now());
+			xr.raised = true;
+			publish(XR_START_LEVEL, 'headset: shadows off');
+		}
+	}
+	const loop = (/** @type {number} */ t) => {
+		if (!xr.active || xr.session !== session) return;
+		session.requestAnimationFrame(loop);
+		if (xr.last) noteXRFrame(t - xr.last, t);
+		xr.last = t;
+	};
+	session?.requestAnimationFrame?.(loop);
+}
+
+/** One XR frame interval. Exported for the suite. @param {number} ms @param {number} [t] */
+export function noteXRFrame(ms, t = now()) {
+	if (!xr.active) return;
+	governor.noteFrame(ms, t);
+	if (t - lastDecideAt < DECIDE_EVERY_MS) return;
+	lastDecideAt = t;
+	decideNow(t);
+}
+
+/** The session ended: desktop thresholds, the entry floor handed back, and the resolution
+ * the headset needed saved for the next entry. Exported for the suite. @param {any} [r] */
+export function endXRQuality(r = get(globalRenderer)) {
+	if (!xr.active) return;
+	xr.active = false;
+	xr.session = null;
+	governor.setThresholds(null);
+	governor.setFloor(0);
+	governor.forget();
+	xr.nextScale = xrScaleAfter(xr.minScale);
+	try {
+		// three refuses this while presenting; sessionend fires after it has stopped
+		r?.xr?.setFramebufferScaleFactor?.(xr.nextScale);
+	} catch {
+		/* a renderer without XR */
+	}
+	if (xr.raised && get(autoQuality)) {
+		governor.setLevel(xr.before, now());
+		publish(xr.before, 'left the headset');
+	}
+	xr.raised = false;
+}
+
+/** For the suite and the stats plate. */
+export function xrQualityDebug() {
+	return { active: xr.active, hz: xr.hz, raised: xr.raised, minScale: xr.minScale, nextScale: xr.nextScale, floor: governor.floor(), thresholds: governor.thresholds(), level: governor.level() };
+}
diff --git a/src/lib/qualityGovernorCore.js b/src/lib/qualityGovernorCore.js
index 2450520d..b7099636 100644
--- a/src/lib/qualityGovernorCore.js
+++ b/src/lib/qualityGovernorCore.js
@@ -80,6 +80,42 @@ export const THRESHOLDS = {
 	vr: { overMs: 13.9, underMs: 11.1 }
 };
 
+/**
+ * 31-perf P3 — THE THRESHOLDS OF A LIVE XR SESSION, from the headset's own refresh rate
+ * (72/80/90/120 on a Quest 3). An XR frame is VSYNC-QUANTISED exactly like the desktop's,
+ * so a session holding its rate reads the budget (13.9 ms at 72 Hz) at every percentile and
+ * a missed frame reads twice it. `overMs` = 1.3 budgets: the p95 only passes it when more
+ * than ~5% of frames were missed — the stutter a player feels. `underMs` = 1.12 budgets:
+ * recovery needs essentially EVERY frame on time for the whole recovery window (a flap is
+ * then caught by the doubling hold, which is what it is for). The static `vr` pair above
+ * would never recover at 72 Hz (a healthy frame reads 13.9, never under 11.1).
+ * @param {number} hz @returns {{overMs: number, underMs: number, hz: number}}
+ */
+export function xrThresholds(hz) {
+	const f = Number(hz) >= 30 && Number(hz) <= 240 ? Number(hz) : 72;
+	const budget = 1000 / f;
+	return { overMs: budget * 1.3, underMs: budget * 1.12, hz: f };
+}
+
+/** The level a headset session starts at in auto mode: step 1 = shadows off, the Quest
+ * budget's rule ("shadows off in Interact") — a shadow pass is a second draw of every
+ * caster, per eye, and a headset has a third of a desktop's frame time. */
+export const XR_START_LEVEL = 1;
+
+/**
+ * The XR framebuffer scale for the NEXT session, from the deepest level the last one needed.
+ * `setPixelRatio` does nothing to an XR framebuffer and three's foveation already defaults to
+ * the maximum (WebXRManager: `foveation = 1.0`), so the resolution half of the ladder can only
+ * act through `setFramebufferScaleFactor` — which three refuses while a session is presenting.
+ * So a session that had to step resolution down leaves the next entry (this tab) at that scale;
+ * a session that never did gives full scale back. Never below 0.5.
+ * @param {number} dprScale the smallest dprScale in force during the session @returns {number}
+ */
+export function xrScaleAfter(dprScale) {
+	const d = Number(dprScale);
+	return Number.isFinite(d) && d > 0 && d < 1 ? Math.max(0.5, d) : 1;
+}
+
 export const TIMING = {
 	/** p95 over this much recent time decides "overloaded" */
 	triggerWindowMs: 2000,
@@ -135,6 +171,11 @@ export function createGovernor(opts = {}) {
 	let lastDownAt = -Infinity;
 	let recoverHoldMs = timing.recoverWindowMs;
 	let settleUntil = -Infinity;
+	/** 31-perf P3: a live XR session's thresholds (xrThresholds), null = the profile's
+	 * @type {{overMs: number, underMs: number} | null} */
+	let thresholdOverride = null;
+	/** 31-perf P3: recovery never walks below this (a headset's entry floor) */
+	let floor = 0;
 
 	function trim(/** @type {number} */ now) {
 		// keep enough for the LONGEST window any decision reads — the recovery hold grows
@@ -199,7 +240,7 @@ export function createGovernor(opts = {}) {
 		 */
 		decide(now, ctx) {
 			trim(now);
-			const t = THRESHOLDS[ctx.profile === 'vr' ? 'vr' : 'desktop'];
+			const t = thresholdOverride ?? THRESHOLDS[ctx.profile === 'vr' ? 'vr' : 'desktop'];
 			const p95 = p95Over(now, timing.triggerWindowMs);
 			const tasks = longTasks.filter((at) => at >= now - timing.longTaskWindowMs).length;
 			const overloaded = (p95 != null && p95 > t.overMs) || tasks > timing.longTasksOver;
@@ -211,7 +252,7 @@ export function createGovernor(opts = {}) {
 				change(level + 1, now);
 				return { level, moved: 'up', reason: p95 != null && p95 > t.overMs ? 'frames' : 'long tasks', p95 };
 			}
-			if (level > 0 && !ctx.pinned && since >= recoverHoldMs) {
+			if (level > floor && !ctx.pinned && since >= recoverHoldMs) {
 				// the scene is no longer heavy: a light scene is never governed, so give it back
 				if (!ctx.heavy) {
 					change(level - 1, now);
@@ -231,6 +272,18 @@ export function createGovernor(opts = {}) {
 			if (next !== level) change(next, now);
 			return level;
 		},
+		/** 31-perf P3: judge against these (an XR session's rate) until cleared with null.
+		 * @param {{overMs: number, underMs: number} | null} t */
+		setThresholds(t) {
+			thresholdOverride = t && Number.isFinite(t.overMs) && Number.isFinite(t.underMs) ? { overMs: t.overMs, underMs: t.underMs } : null;
+		},
+		thresholds: () => thresholdOverride,
+		/** 31-perf P3: the lowest level RECOVERY may reach (setLevel is not bound by it — the
+		 * chip's "restore full quality" still means it). @param {number} n */
+		setFloor(n) {
+			floor = Math.max(0, Math.min(MAX_LEVEL, Math.floor(Number(n)) || 0));
+		},
+		floor: () => floor,
 		level: () => level,
 		recoverHoldMs: () => recoverHoldMs
 	};
diff --git a/tests/e2e/lod.test.cjs b/tests/e2e/lod.test.cjs
index 822de5b3..001b4bac 100644
--- a/tests/e2e/lod.test.cjs
+++ b/tests/e2e/lod.test.cjs
@@ -11,7 +11,8 @@
 //     draws whole, never a stale level of the old one
 //   6 one asset, one set of levels: a second mesh sharing the content reuses the cache
 //   7 the quality bias: a governor step pulls the switch distance in
-//   8 api.lod on module content (scene-root, not objectsGroup) + teardown on deactivate
+//   8 api.lod on module content (scene-root, not objectsGroup) + teardown on deactivate,
+//     and api.quality's shape (level, max, onChange -> off)
 
 // Run: APP_URL=https://theprototype.app:5263/ npm run e2e -- lod
 const h = require('./helpers.cjs');
@@ -179,7 +180,7 @@ h.run(async () => {
 				id: 'lodtest',
 				name: 'LOD test',
 				version: '1.0.0',
-				description: 'api.lod',
+				description: 'api.lod + api.quality',
 				register(api) {
 					const THREE = api.THREE;
 					const group = new THREE.Group();
@@ -192,6 +193,9 @@ h.run(async () => {
 					const handle = api.lod(group, { ratios: [0.3], distances: [4] });
 					out.meshes = handle.meshes;
 					out.readyIsPromise = typeof handle.ready?.then === 'function';
+					out.q = { level: api.quality.level, max: api.quality.max, hasOnChange: typeof api.quality.onChange === 'function' };
+					window.__lodq = [];
+					out.off = typeof api.quality.onChange((level) => window.__lodq.push(level));
 				}
 			}
 		]);
@@ -200,12 +204,17 @@ h.run(async () => {
 		const r = window.__lodt;
 		// the module's ball is at z -30 at scene root: render from 60 m in front of it
 		out.far = r.renderFrom(60, [0, 1, -30]);
+		s.qualityGovernor.governorForTest.setLevel(2);
+		s.qualityGovernor.governorForTest.setLevel(0);
+		out.changes = window.__lodq.slice();
 		s.moduleSDK.deactivateModule('lodtest');
 		out.afterDeactivate = s.lod.lodStats().meshes.some((m) => m.name === 'lodtest-ball');
 		return out;
 	});
 	h.check(mod.meshes === 1 && mod.readyIsPromise, '8.1 api.lod(group) registers the module mesh and returns {meshes, ready, remove}');
 	h.check(!!mod.registered && mod.registered.explicit && Array.isArray(mod.registered.levels) && mod.registered.levels.length === 1, '8.2 the module mesh (scene-root, not objectsGroup) got its explicit level: ' + JSON.stringify(mod.registered));
+	h.check(mod.q.level === 0 && mod.q.max >= 9 && mod.q.hasOnChange && mod.off === 'function', '8.3 api.quality: level 0 (best), max ' + mod.q.max + ', onChange returns off()');
+	h.check(JSON.stringify(mod.changes) === '[2,0]', '8.4 api.quality.onChange heard the level move 2 then back to 0: ' + JSON.stringify(mod.changes));
 	h.check(mod.afterDeactivate === false, '8.5 deactivating the module drops its LOD entries (the teardown journal)');
 
 
diff --git a/tests/e2e/perf-governor.test.cjs b/tests/e2e/perf-governor.test.cjs
index cabb9997..d0700eb3 100644
--- a/tests/e2e/perf-governor.test.cjs
+++ b/tests/e2e/perf-governor.test.cjs
@@ -319,6 +319,54 @@ h.run(async () => {
 	h.check(gap.stillLevel === 0, 'a light scene receiving objects is not a quality step, only a drain');
 	h.check(gapAfter === 0, 'the drain ends, the gap ends');
 
+	// ---- 6b. 31-perf P3: THE HEADSET ------------------------------------------------------
+	// A headless page cannot present WebXR, so the session is driven through the same three
+	// entry points the sessionstart/end listeners and the session's own rAF call.
+	const vr = await A.page.evaluate(() => {
+		const s = window.__stores;
+		const q = s.qualityGovernor;
+		const g = window.__gov;
+		q.governorForTest.reset();
+		q.setAutoQuality(true);
+		g.metrics({ objects: 12, meshes: 12, triangles: 144, calls: 24 }); // a LIGHT scene: VR governs anyway
+		q.startXRQuality(null, 72);
+		const entered = { ...q.xrQualityDebug(), shadowsOff: g.read(q.qualityOverrides).shadowsOff, reason: g.read(q.qualityState).reason, bias: s.lod.lodStats().bias };
+		// 3 s at 72 Hz with every 5th frame missed (27.8 ms)
+		let t = (g.clock += 1000);
+		for (let i = 0; i < 220; i++) {
+			const ms = i % 5 === 0 ? 27.8 : 13.9;
+			t += ms;
+			q.noteXRFrame(ms, t);
+		}
+		const judged = { ...q.xrQualityDebug(), dpr: g.read(q.qualityOverrides).dprScale, bias: s.lod.lodStats().bias };
+		// then 25 s of on-time frames: recovery walks back down, but never below the floor
+		for (let i = 0; i < 1800; i++) {
+			t += 13.9;
+			q.noteXRFrame(13.9, t);
+		}
+		const recovered = { ...q.xrQualityDebug(), shadowsOff: g.read(q.qualityOverrides).shadowsOff };
+		g.clock = t;
+		q.endXRQuality();
+		const left = { ...q.xrQualityDebug(), shadowsOff: g.read(q.qualityOverrides).shadowsOff };
+		// COUNTERFACTUAL: with the opt-out the headset changes nothing
+		q.setAutoQuality(false);
+		q.startXRQuality(null, 90);
+		const optedOut = q.xrQualityDebug();
+		q.endXRQuality();
+		q.setAutoQuality(true);
+		localStorage.removeItem('autoQuality');
+		q.governorForTest.reset();
+		return { entered, judged, recovered, left, optedOut };
+	});
+	h.check(vr.entered.active && vr.entered.level === 1 && vr.entered.shadowsOff === true && /headset/.test(vr.entered.reason), `a headset session starts at level 1 — shadows off — even on a light scene (${JSON.stringify(vr.entered)})`);
+	h.check(Math.abs(vr.entered.thresholds.overMs - 18.06) < 0.1 && Math.abs(vr.entered.thresholds.underMs - 15.56) < 0.1, `it judges by the headset's own 72 Hz (${JSON.stringify(vr.entered.thresholds)})`);
+	h.check(vr.entered.bias < 1, `…and the LOD bias follows the level (${vr.entered.bias})`);
+	h.check(vr.judged.level >= 2 && vr.judged.dpr < 1 && vr.judged.bias < vr.entered.bias, `missed XR frames take the next step, fed by the session's frames (${JSON.stringify(vr.judged)})`);
+	h.check(vr.recovered.level === 1 && vr.recovered.shadowsOff === true, `on-time frames walk back down — to the floor, never past it: shadows stay off (${JSON.stringify(vr.recovered)})`);
+	h.check(!vr.left.active && vr.left.level === 0 && vr.left.shadowsOff === false && vr.left.thresholds === null, `leaving the headset gives the entry level back and the desktop thresholds (${JSON.stringify(vr.left)})`);
+	h.check(vr.left.nextScale < 1 && vr.left.nextScale >= 0.5, `the resolution the session needed is kept for the next entry (framebuffer scale ${vr.left.nextScale})`);
+	h.check(vr.optedOut.level === 0 && vr.optedOut.floor === 0 && Math.abs(vr.optedOut.thresholds.overMs - 14.44) < 0.1, `COUNTERFACTUAL: with auto quality off a headset changes no level (still judges 90 Hz): ${JSON.stringify(vr.optedOut)}`);
+
 	// ---- 7. end to end on real frames --------------------------------------------------
 	const real = await A.page.evaluate(async () => {
 		const s = window.__stores;
diff --git a/tests/unit/qualityGovernor.test.js b/tests/unit/qualityGovernor.test.js
index 45508121..699b821b 100644
--- a/tests/unit/qualityGovernor.test.js
+++ b/tests/unit/qualityGovernor.test.js
@@ -190,3 +190,64 @@ describe('drawGapFor (the ingest rule)', () => {
 		expect(drawGapFor({ ...base, engaged: true, draining: false })).toBe(0);
 	});
 });
+
+// 31-perf P3 — the headset: thresholds from the refresh rate, the override seam, and the
+// framebuffer scale handed to the next entry.
+import { xrThresholds, xrScaleAfter, XR_START_LEVEL } from '../../src/lib/qualityGovernorCore.js';
+
+describe('31-perf: XR thresholds', () => {
+	it('come from the refresh rate: a missed frame is over, an on-time session recovers', () => {
+		const t72 = xrThresholds(72);
+		expect(t72.overMs).toBeCloseTo(18.06, 1);
+		expect(t72.underMs).toBeCloseTo(15.56, 1);
+		// a healthy 72 Hz session reads 13.9 at every percentile: that must count as calm,
+		// which the static VR pair (under 11.1) never could
+		expect(1000 / 72).toBeLessThan(t72.underMs);
+		expect(1000 / 72).toBeLessThan(xrThresholds(72).overMs);
+		// one missed frame reads twice the budget: over
+		expect((2 * 1000) / 72).toBeGreaterThan(t72.overMs);
+		expect(xrThresholds(90).overMs).toBeCloseTo(14.44, 1);
+		expect(xrThresholds(0).hz).toBe(72); // nonsense falls back to 72
+	});
+	it('a governor judged by them steps on missed frames and recovers on on-time ones', () => {
+		const g = createGovernor();
+		g.setThresholds(xrThresholds(72));
+		let t = 1000;
+		// 3 s of frames where every 5th is missed (27.8 ms): p95 = 27.8 > 18
+		for (let i = 0; i < 180; i++) {
+			const ms = i % 5 === 0 ? 27.8 : 13.9;
+			t += ms;
+			g.noteFrame(ms, t);
+		}
+		expect(g.decide(t, { profile: 'vr', heavy: true }).moved).toBe('up');
+		// then on-time frames for the recovery window: back down
+		for (let i = 0; i < 1200; i++) {
+			t += 13.9;
+			g.noteFrame(13.9, t);
+		}
+		expect(g.decide(t, { profile: 'vr', heavy: true }).moved).toBe('down');
+	});
+	it('COUNTERFACTUAL: without the override, a healthy 72 Hz session could never recover', () => {
+		const g = createGovernor();
+		let t = 1000;
+		g.setLevel(1, t);
+		t += 700;
+		for (let i = 0; i < 1200; i++) {
+			t += 13.9;
+			g.noteFrame(13.9, t);
+		}
+		// the static vr pair (underMs 11.1) reads 13.9 as NOT calm: stuck at level 1
+		expect(g.decide(t, { profile: 'vr', heavy: true }).moved).toBe(null);
+		g.setThresholds(xrThresholds(72));
+		expect(g.decide(t, { profile: 'vr', heavy: true }).moved).toBe('down');
+		g.setThresholds(null);
+		expect(g.thresholds()).toBe(null);
+	});
+	it('the entry floor is the shadows step, and the next entry gets the scale this one needed', () => {
+		expect(GOVERNOR_STEPS[XR_START_LEVEL - 1].key).toBe('shadows');
+		expect(xrScaleAfter(1)).toBe(1);
+		expect(xrScaleAfter(0.72)).toBe(0.72);
+		expect(xrScaleAfter(0.3)).toBe(0.5);
+		expect(xrScaleAfter(NaN)).toBe(1);
+	});
+});

From 7a949d39ae09321547e76e58fe34d2f176476778 Mon Sep 17 00:00:00 2001
From: AlexZ005 <alexz005.info@gmail.com>
Date: Thu, 1 Oct 2026 01:40:44 +0300
Subject: [PATCH 5/5] [docs] MODULES.md: performance - api.quality, api.lod,
 the Quest budget, the probe (P4)

- api.quality / api.lod with a worked example (cut your own effects on onChange; levels
  for dense module geometry; userData.lod = false opts a mesh out).
- The Quest budget (<= 150 calls, <= 300k tris, <= 2 lights shadows off, no per-frame
  allocations) and how to measure a game with scripts/perf-games.cjs.
- The four lessons this round measured: no THREE object inside a Svelte $state (the deep
  read was 88% of a game's frame), no per-frame whole-scene lookups, no per-frame
  allocation, lights/shadow casters/transmission are draw calls.

Before/after (all seven games, desktop + VR-emulated) is in the lane handover and
after-31/31-perf/perf-{baseline-1.17,after-31,vr-baseline-1.17,vr-after-31}.md.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 MODULES.md | 55 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 55 insertions(+)

diff --git a/MODULES.md b/MODULES.md
index dd2c3444..2a484139 100644
--- a/MODULES.md
+++ b/MODULES.md
@@ -481,6 +481,61 @@ if (api.storage) {
 Feature-detect it; on an older app write the SAME key yourself
 (`localStorage['tp:mod:<id>:<key>'] = JSON.stringify(value)`) so progress carries over.
 
+### Performance: quality level, LOD, budgets (1.18, roadmap 31)
+
+```js
+// The adaptive quality level on THIS device: 0 = best ... api.quality.max (every step taken).
+// A headset session starts at 1 (shadows off) in auto mode; a game's Quality setting can pin it.
+if (api.quality) {
+	const apply = (level) => {
+		particles.maxCount = level >= 3 ? 40 : 200;   // cut YOUR effects, not shared state
+		torchLights.forEach((l, i) => (l.visible = i < (level >= 1 ? 2 : 6)));
+	};
+	apply(api.quality.level);
+	const off = api.quality.onChange((level, { labels, vr }) => apply(level)); // released on disable
+}
+
+// Levels of detail for your own dense geometry (auto LOD already covers dense meshes in the
+// shared scene and under the module world root). Built ONCE per asset in a worker
+// (meshoptimizer), drawn by distance through a render-time swap: the mesh keeps its full
+// geometry for picking, physics and your code. Distances are in the mesh's world RADII.
+if (api.lod) {
+	const lod = api.lod(enemyFigure, { ratios: [0.5, 0.2], distances: [6, 18] });
+	lod.ready.then((n) => console.log(n, "meshes have levels")); // lod.remove() undoes it
+}
+mesh.userData.lod = false; // keep one mesh out of auto LOD
+```
+
+Both are LOCAL (a fact about this machine) — never let them change replicated state, or two
+peers on different hardware disagree about the game. Skinned meshes and morph targets get no
+levels (the simplifier cannot carry weights): pre-decimate those offline.
+
+**The Quest budget** (roadmap 31, the planner's target for a scene in Interact/Play on a Quest 3):
+**<= 150 draw calls, <= 300k triangles visible, <= 2 real-time lights with shadows off, no
+per-frame allocations in the hot path.** Measure your game with the probe, the same way every time:
+
+```bash
+# dev server running; run it under the exclusive slot (frame times are the point)
+APP_URL=https://theprototype.app:5173/ ~/.local/bin/e2e-slot --exclusive -- \
+  node scripts/perf-games.cjs --label mine --only waves [--vr] [--profile]
+```
+
+It prints draw calls + triangles per frame (every render pass summed), geometries, textures and
+an MB estimate, lights (+ shadow casters), meshes / instanced / unculled, the LOD and quality
+state, and p50/p95/p99 frame ms at CPU throttle x4; `--profile` adds CPU self-time, the nearest
+app frame calling the heaviest functions, and allocation per function (garbage included).
+The things 1.18's round found, in the order they cost:
+
+- **Never keep a THREE object inside Svelte `$state`** (or pass one through an action parameter
+  that is a state proxy): Svelte deep-reads a proxy, which walks the whole scene graph through
+  `parent` — typed arrays included. Use `$state.raw`. This one line was 88% of a game's frame.
+- **No whole-scene lookups per frame** — `scene.getObjectByName` is a traversal; find once, keep
+  the reference, re-find when it leaves the scene.
+- **No allocation per frame**: reuse vectors/arrays; a `[a, b].map(...)` in a frame task is
+  garbage 60-90 times a second, and GC pauses are the stutter you feel in a headset.
+- **Lights and shadow casters are draw calls**: each shadow-casting light draws every caster
+  again; transmission (glass) renders the scene an extra time per camera, per eye.
+
 ### Game feel: sound, music, haptics, effects, banners (1.17, roadmap 30b)
 
 Everything here is LOCAL to the device it runs on — broadcast your own op