cozyclay 2.1.1 → 3.0.1

package/src/stage-hdr-library.js

@@ -0,0 +1,70 @@
+// The HDR environments the stage can use: the built-ins and every environment
+// file loaded into this browser's asset store. The Light panel lists them and
+// inspect_studio { scope: "catalogue" } answers them as `environments`, so the
+// agent, which cannot upload a file, can pick a map the user already loaded and
+// aim it. Loading a file goes through here too: checked, decoded once, stored
+// under its content address and remembered decoded.
+import { declaredHdrSize, HDR_BUILTINS, HDR_MAX_BYTES, hdrFileProblem, hdrIdForBytes, isHdrAssetId, sniffHdrType } from "./stage-hdr.js";
+import { getAsset, listAssetIds, openAssetDb, putAsset } from "./scene-assets.js";
+import { decodeEnvironment } from "./stage-hdr-image.js";
+import { rememberHdrMap } from "./stage-hdr-map.js";
+
+const listeners = new Set();
+const builtins = HDR_BUILTINS.map(({ id, name, brightest, note }) => ({ id, name, source: "builtin", brightest, note }));
+let files = [], catalogue = Object.freeze([...builtins]);
+
+function publish(next) {
+	files = next;
+	catalogue = Object.freeze([...builtins, ...files.map(({ id, name, width, height, megabytes, brightest }) => ({
+		id, name, source: "file", ...(width ? { size: `${width}x${height}` } : {}), megabytes, ...(brightest ? { brightest } : {}),
+	}))]);
+	for (const listener of listeners) listener();
+}
+
+/** Every environment, built-ins first: { id, name, source: "builtin" | "file", brightest?, note?, size?, megabytes? }. */
+export const hdrEnvironmentCatalogue = () => catalogue;
+export function subscribeHdrLibrary(listener) {
+	listeners.add(listener);
+	return () => listeners.delete(listener);
+}
+
+/** Re-read the stored environment files' names and sizes. Without IndexedDB the list is the built-ins. */
+export async function refreshHdrLibrary() {
+	let db = null;
+	try {
+		db = await openAssetDb();
+		const ids = (await listAssetIds(db)).filter(isHdrAssetId);
+		const records = (await Promise.all(ids.map((id) => getAsset(db, id)))).filter(Boolean);
+		publish(records.map(({ id, name, width, height, brightest, bytes }) => ({ id, name: name || id, width, height, brightest, megabytes: Number((bytes.byteLength / 1048576).toFixed(2)) }))
+			.sort((a, b) => a.name.localeCompare(b.name)));
+	} catch {
+		publish([]);
+	} finally {
+		db?.close?.();
+	}
+}
+
+/**
+ * Load one environment file the user picked: at most HDR_MAX_BYTES (32 MB) and
+ * HDR_MAX_PIXELS, decoded before it is stored so a broken file never reaches
+ * the store. Answers { id, name }; throws with a sentence for the user.
+ */
+export async function importHdrFile(file) {
+	const early = file.size > HDR_MAX_BYTES ? hdrFileProblem(file.size, null, null) : null;
+	if (early) throw new Error(early);
+	const buffer = await file.arrayBuffer(), bytes = new Uint8Array(buffer), type = sniffHdrType(bytes), size = declaredHdrSize(type, bytes);
+	const problem = hdrFileProblem(bytes.length, type, size);
+	if (problem) throw new Error(problem);
+	let map;
+	try { map = await decodeEnvironment({ type, bytes: buffer }); }
+	catch (error) { throw new Error(`that file could not be decoded (${error.message})`, { cause: error }); }
+	const id = await hdrIdForBytes(bytes), db = await openAssetDb();
+	try {
+		await putAsset(db, { id, type, bytes: buffer, name: file.name || id, ...(size ?? { width: map.width, height: map.height }), brightest: map.brightest });
+	} finally {
+		db.close();
+	}
+	rememberHdrMap(id, map);
+	await refreshHdrLibrary();
+	return { id, name: file.name || id };
+}

package/src/stage-hdr-map.js

@@ -0,0 +1,94 @@
+// The stage's HDR environment maps as textures, decoded once per session and
+// shared by every scene that names them. A built-in map is drawn on first use,
+// synchronously, so a look that names one renders it in the same frame; a
+// loaded file is read from the asset store and decoded off the render path,
+// and the stage keeps its own sky light until it lands (or if it never does).
+// stage-sky.jsx prefilters the texture with PMREMGenerator for the light and
+// draws it as the background.
+import { useEffect, useSyncExternalStore } from "react";
+import * as THREE from "three";
+import { isBuiltinHdrId, isHdrAssetId } from "./stage-hdr.js";
+import { BUILTIN_HEIGHT, BUILTIN_WIDTH, builtinEnvironmentPixels } from "./stage-hdr-builtins.js";
+import { analyzedMap, decodeEnvironment, halfMapFromFloats } from "./stage-hdr-image.js";
+import { getAsset, openAssetDb } from "./scene-assets.js";
+
+// Decoded files kept besides the built-ins; an older one is disposed (three
+// uploads it again if a scene still draws it).
+const KEPT_FILES = 3;
+// A stored file that fails to load is tried again a few times (5 s apart), then left failed until a reload.
+const RETRIES = 3;
+const entries = new Map(), listeners = new Set(), failures = new Map();
+const notify = () => { for (const listener of listeners) listener(); };
+const subscribe = (listener) => { listeners.add(listener); return () => listeners.delete(listener); };
+
+function textureOf({ width, height, data }) {
+	const texture = new THREE.DataTexture(data, width, height, THREE.RGBAFormat, THREE.HalfFloatType);
+	texture.mapping = THREE.EquirectangularReflectionMapping;
+	texture.colorSpace = THREE.LinearSRGBColorSpace;
+	texture.magFilter = THREE.LinearFilter;
+	texture.minFilter = THREE.LinearFilter;
+	texture.needsUpdate = true;
+	return texture;
+}
+
+function store(id, map) {
+	const entry = Object.freeze({ id, width: map.width, height: map.height, horizon: map.horizon, brightest: map.brightest, texture: textureOf(map) });
+	entries.set(id, entry);
+	const files = [...entries.values()].filter((row) => row.texture && isHdrAssetId(row.id));
+	for (const stale of files.slice(0, Math.max(0, files.length - KEPT_FILES))) {
+		entries.delete(stale.id);
+		stale.texture.dispose();
+	}
+	return entry;
+}
+
+/** What the cache holds for an id: a ready map, a pending or failed load, or null. Draws a built-in on first ask. */
+function snapshot(id) {
+	if (!id) return null;
+	if (!entries.has(id) && isBuiltinHdrId(id)) store(id, analyzedMap(halfMapFromFloats(BUILTIN_WIDTH, BUILTIN_HEIGHT, builtinEnvironmentPixels(id))));
+	return entries.get(id) ?? null;
+}
+
+/** Start reading and decoding a stored file once. A failed load is forgotten after a while so a later ask retries. */
+function request(id) {
+	if (!isHdrAssetId(id) || entries.has(id)) return;
+	const pending = Object.freeze({ id, pending: true });
+	entries.set(id, pending);
+	(async () => {
+		const db = await openAssetDb();
+		try {
+			const record = await getAsset(db, id);
+			if (!record) throw new Error("it is not in this browser's asset store");
+			return await decodeEnvironment(record);
+		} finally { db.close(); }
+	})().then((map) => {
+		if (entries.get(id) === pending) store(id, map);
+	}, (error) => {
+		console.warn(`[cozyclay] could not load HDR environment ${id}: ${error.message}`);
+		if (entries.get(id) !== pending) return;
+		const failed = Object.freeze({ id, failed: error.message }), count = (failures.get(id) ?? 0) + 1;
+		entries.set(id, failed);
+		failures.set(id, count);
+		if (count < RETRIES) setTimeout(() => { if (entries.get(id) === failed) { entries.delete(id); notify(); } }, 5000);
+	}).finally(notify);
+}
+
+/** Warm the cache with a map the importer already decoded. */
+export function rememberHdrMap(id, map) {
+	failures.delete(id);
+	store(id, map);
+	notify();
+}
+
+/** The ready map for an id ({ texture, horizon, brightest, width, height }), or null while it loads or when it cannot. */
+export function readyHdrMap(id) {
+	const entry = snapshot(id);
+	return entry?.texture ? entry : null;
+}
+
+/** React: the ready map for `id`, loading it when needed; re-renders when it lands. */
+export function useHdrMap(id) {
+	const entry = useSyncExternalStore(subscribe, () => snapshot(id));
+	useEffect(() => { request(id); }, [id, entry]);
+	return entry?.texture ? entry : null;
+}

package/src/stage-hdr.js

@@ -0,0 +1,130 @@
+// HDR environments for the stage look: the stage.lighting.hdr* fields, the
+// built-in maps the Studio generates itself, and the records of the .hdr / .exr
+// / equirectangular picture files a user loads. A loaded file lives in the
+// shared asset store (scene-assets.js) under an `hdr-` id derived from its bytes,
+// exactly like a picture or a model, so it travels in a saved project and
+// survives a reload. Pure data and arithmetic, no three.js: the scene document,
+// the tests and the agent sidecar load it.
+
+/** Content-addressed prefix of a stored environment file. */
+const HDR_ID_PREFIX = "hdr-";
+const HDR_ID = /^hdr-[0-9a-f]{32}$/;
+/** The file ceiling: the same 32 MB a project file decodes an embedded asset against (scene-assets.js ASSET_MAX_SOURCE_BYTES). */
+export const HDR_MAX_BYTES = 32 * 1024 * 1024;
+/** Decoded size ceiling for float maps (half floats: 8 bytes a pixel while decoding). */
+export const HDR_MAX_PIXELS = 4096 * 4096;
+/** Stored MIME types: Radiance RGBE, OpenEXR, and an LDR equirectangular picture. */
+const HDR_TYPES = Object.freeze(["image/vnd.radiance", "image/x-exr", "image/png", "image/jpeg"]);
+
+/**
+ * The maps the Studio draws itself (stage-hdr-builtins.js), so the agent has
+ * real environments without a file. `brightest` is the direction of the map's
+ * brightest light at hdrRotation 0, as a world vector (y up, +z toward the
+ * default camera); hdrRotation turns it about +y.
+ */
+export const HDR_BUILTINS = Object.freeze([
+	{ id: "builtin:night-street", name: "Night street", ko: "밤거리", brightest: [0.72, 0.2, 0.66],
+		note: "dark blue night sky, a building skyline with lit windows, two warm sodium street lamps (front right and back left) pooling light on wet asphalt, a dim moon" },
+	{ id: "builtin:overcast-field", name: "Overcast field", ko: "흐린 들판", brightest: [-0.35, 0.66, -0.67],
+		note: "bright soft grey overcast sky (brighter overhead), a faint sun glow behind the clouds back left, a distant tree line and a green field" },
+	{ id: "builtin:studio-softbox", name: "Studio softbox", ko: "스튜디오 소프트박스", brightest: [-0.6, 0.4, 0.7],
+		note: "dark grey photo studio: a large white softbox front left, a tall strip light right, a soft overhead panel and a rim panel behind" },
+].map((entry) => Object.freeze({ ...entry, brightest: Object.freeze(entry.brightest) })));
+const BUILTIN_IDS = new Set(HDR_BUILTINS.map((entry) => entry.id));
+
+export const isHdrAssetId = (value) => typeof value === "string" && HDR_ID.test(value);
+export const isBuiltinHdrId = (value) => BUILTIN_IDS.has(value);
+/** What stage.lighting.hdr may hold: a built-in name or a stored file's id. */
+export const isHdrEnvironmentId = (value) => isBuiltinHdrId(value) || isHdrAssetId(value);
+
+const finite = (value) => typeof value === "number" && Number.isFinite(value);
+/** Degrees into [-180, 180): 180 wraps to -180, like the other yaw fields. */
+export const wrapDegrees = (value) => ((((value + 180) % 360) + 360) % 360) - 180;
+
+/** The four HDR fields of stage.lighting, present and in range: no map is the default. */
+export function normalizeHdrFields(source = {}) {
+	return {
+		hdr: isHdrEnvironmentId(source.hdr) ? source.hdr : null,
+		hdrRotation: finite(source.hdrRotation) ? Number(wrapDegrees(source.hdrRotation).toFixed(3)) : 0,
+		hdrIntensity: finite(source.hdrIntensity) ? Math.max(0, Math.min(4, source.hdrIntensity)) : 1,
+		hdrBackground: typeof source.hdrBackground === "boolean" ? source.hdrBackground : true,
+	};
+}
+export const HDR_FIELDS = Object.freeze(Object.keys(normalizeHdrFields()));
+
+/* ------------------------------------------------------------ files ---- */
+
+const ascii = (bytes, start, length) => String.fromCharCode(...bytes.subarray(start, Math.min(bytes.length, start + length)));
+
+/** The stored MIME type of an environment file from its first bytes, or null. */
+export function sniffHdrType(bytes) {
+	if (ascii(bytes, 0, 10) === "#?RADIANCE" || ascii(bytes, 0, 6) === "#?RGBE") return "image/vnd.radiance";
+	if (bytes[0] === 0x76 && bytes[1] === 0x2f && bytes[2] === 0x31 && bytes[3] === 0x01) return "image/x-exr";
+	if (bytes[0] === 0x89 && ascii(bytes, 1, 3) === "PNG") return "image/png";
+	if (bytes[0] === 0xff && bytes[1] === 0xd8 && bytes[2] === 0xff) return "image/jpeg";
+	return null;
+}
+
+/** Width and height from a Radiance header ("-Y 512 +X 1024"), or null. */
+function radianceSize(bytes) {
+	const match = /\n\s*-Y\s+(\d+)\s+\+X\s+(\d+)\s*\n/.exec(ascii(bytes, 0, 8192));
+	return match ? { width: Number(match[2]), height: Number(match[1]) } : null;
+}
+
+/** Width and height from an OpenEXR header's dataWindow attribute, or null. */
+function exrSize(bytes) {
+	const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+	const text = (at) => { let end = at; while (end < bytes.length && bytes[end] !== 0) end++; return [ascii(bytes, at, end - at), end + 1]; };
+	let at = 8;
+	while (at < Math.min(bytes.length, 65536)) {
+		const [name, afterName] = text(at);
+		if (!name) return null;
+		const [, afterType] = text(afterName);
+		const size = view.getInt32(afterType, true), value = afterType + 4;
+		if (name === "dataWindow" && size === 16) {
+			const [xMin, yMin, xMax, yMax] = [0, 4, 8, 12].map((offset) => view.getInt32(value + offset, true));
+			return { width: xMax - xMin + 1, height: yMax - yMin + 1 };
+		}
+		at = value + size;
+	}
+	return null;
+}
+
+/** The pixel size a float map declares before it is decoded (null for a picture). */
+export function declaredHdrSize(type, bytes) {
+	try { return type === "image/vnd.radiance" ? radianceSize(bytes) : type === "image/x-exr" ? exrSize(bytes) : null; }
+	catch { return null; }
+}
+
+/** Why an environment file cannot be loaded, as a sentence for the user, or null when it can. */
+export function hdrFileProblem(byteLength, type, size) {
+	if (byteLength > HDR_MAX_BYTES) return `that file is ${(byteLength / 1048576).toFixed(1)} MB; an HDR environment can be at most ${HDR_MAX_BYTES / 1048576} MB`;
+	if (!type) return "that file is not an HDR environment CozyClay can load (Radiance .hdr, OpenEXR .exr, or an equirectangular .png / .jpg)";
+	if ((type === "image/vnd.radiance" || type === "image/x-exr") && !size) return "that HDR file has no readable image size";
+	if (size && size.width * size.height > HDR_MAX_PIXELS) return `that HDR is ${size.width} x ${size.height}; the limit is ${HDR_MAX_PIXELS / 1048576} megapixels (4096 x 4096)`;
+	return null;
+}
+
+async function sha256Hex(bytes, subtle) {
+	if (!subtle?.digest) throw new Error("SubtleCrypto is unavailable — a secure context is required to load an HDR");
+	const digest = await subtle.digest("SHA-256", bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength));
+	return Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+
+/** The id these bytes are stored under: `hdr-` and the first 128 bits of their SHA-256. */
+export async function hdrIdForBytes(bytes, subtle = globalThis.crypto?.subtle) {
+	const view = bytes instanceof ArrayBuffer ? new Uint8Array(bytes) : bytes;
+	return `${HDR_ID_PREFIX}${(await sha256Hex(view, subtle)).slice(0, 32)}`;
+}
+
+const direction = (value) => Array.isArray(value) && value.length === 3 && value.every(finite) ? value.map((v) => Number(v.toFixed(2))) : null;
+/** A stored environment record repaired, or null to drop it (scene-assets.js normalizeAsset). */
+export function normalizeHdrAsset(record, bytes) {
+	if (!isHdrAssetId(record?.id) || typeof record.type !== "string" || !HDR_TYPES.includes(record.type.toLowerCase())) return null;
+	const width = Math.round(Number(record.width)), height = Math.round(Number(record.height)), brightest = direction(record.brightest);
+	return {
+		id: record.id, type: record.type.toLowerCase(), bytes, name: typeof record.name === "string" ? record.name : "",
+		...(width > 0 && height > 0 ? { width, height } : {}),
+		...(brightest ? { brightest } : {}),
+	};
+}

package/src/stage-lighting.js

@@ -0,0 +1,149 @@
+// The stage look: the key light the user grabs plus stage.lighting (sky, fog,
+// ambient, fill, exposure, shadow softness, environment light, ambient
+// occlusion) and the recipes that set them in one action. Pure data and arithmetic — no three.js or React — so the scene
+// document, the command layer, the tests and the agent sidecar can all load it.
+// The renderer reads it through stageLook() (room.jsx, stage-sky.jsx).
+import { elementByPath } from "./studio-elements.js";
+import { GRID_BACKGROUND, GRID_FOG, stageBackground } from "./grid-view.js";
+import { environmentSpec } from "./stage-environment.js";
+import { HDR_FIELDS, normalizeHdrFields } from "./stage-hdr.js";
+
+export const LIGHTING_PRESETS = Object.freeze(["studio", "day", "overcast", "golden", "dusk", "night", "interior", "stage"]);
+
+const HEX = /^#[0-9a-fA-F]{6}$/;
+const plain = (value) => !!value && typeof value === "object" && !Array.isArray(value);
+const color = (value, fallback) => (typeof value === "string" && HEX.test(value) ? value : fallback);
+const limits = (path) => elementByPath(path);
+const finite = (value, fallback, { min, max }) => (typeof value === "number" && Number.isFinite(value) ? Math.max(min, Math.min(max, value)) : fallback);
+
+// The tuned rig: these values render the stage exactly as it looked before the
+// look was authorable, so a stage saved earlier (no lighting, no key colour)
+// renders unchanged.
+const DEFAULT_KEY_LIGHT = Object.freeze({ x: 6, y: 9, z: 4, intensity: 1.12, warmth: 0.5, color: null });
+// envLight and ao are 0 in the studio look: no environment map, no occlusion pass.
+// No look names an HDR environment (stage-hdr.js); the user or the agent picks one.
+const DEFAULT_LIGHTING = Object.freeze({ preset: "studio", sky: null, skyTop: null, ambient: 1, hemiSky: "#ffffff", hemiGround: "#5a5d64", fill: 1, fog: 0, exposure: 1, shadowSoftness: 0, envLight: 0, ao: 0, ...normalizeHdrFields() });
+const LIGHTING_NUMBERS = ["fill", "fog", "exposure", "shadowSoftness", "envLight", "ao"];
+
+/** Clamp a stored key light back into the stage's usable envelope. `color`
+ * (a #rrggbb or null) overrides the warmth slider when set. */
+export function createKeyLight(value) {
+	const source = plain(value) ? value : {};
+	const key = Object.fromEntries(["x", "y", "z", "intensity", "warmth"].map((axis) => [axis, finite(source[axis], DEFAULT_KEY_LIGHT[axis], limits(`stage.keyLight.${axis}`))]));
+	return { ...key, color: color(source.color, null) };
+}
+
+/** stage.lighting with every field present and in range; anything missing or
+ * malformed falls back to the studio look. */
+export function normalizeLighting(value) {
+	const source = plain(value) ? value : {};
+	const number = (key) => finite(source[key], DEFAULT_LIGHTING[key], limits(`stage.lighting.${key}`));
+	return {
+		preset: LIGHTING_PRESETS.includes(source.preset) ? source.preset : DEFAULT_LIGHTING.preset,
+		sky: color(source.sky, null),
+		skyTop: color(source.skyTop, null),
+		ambient: number("ambient"),
+		hemiSky: color(source.hemiSky, DEFAULT_LIGHTING.hemiSky),
+		hemiGround: color(source.hemiGround, DEFAULT_LIGHTING.hemiGround),
+		...Object.fromEntries(LIGHTING_NUMBERS.map((key) => [key, number(key)])),
+		...normalizeHdrFields(source),
+	};
+}
+
+// Each recipe is a complete look: every lighting field plus the key's colour,
+// brightness and place (the sun, the moon, the lamp). Key positions are metres
+// around the stage centre; a low y is a low sun. Tuned by eye on the clay
+// figure through the shot camera, so treat them as starting points to tweak.
+const recipe = (lighting, keyLight) => Object.freeze({ lighting: Object.freeze({ ...DEFAULT_LIGHTING, ...lighting }), keyLight: Object.freeze(keyLight) });
+export const LIGHTING_RECIPES = Object.freeze({
+	studio: recipe({}, { ...DEFAULT_KEY_LIGHT }),
+	day: recipe({ sky: "#bcd2e8", skyTop: "#4f86c6", ambient: 1.15, hemiSky: "#c4dcff", hemiGround: "#6b6253", fill: 0.7, fog: 0.12, shadowSoftness: 0.15, envLight: 1, ao: 0.8 },
+		{ x: 5, y: 14, z: 7, intensity: 2.1, color: "#fff3df" }),
+	overcast: recipe({ sky: "#c2c7ce", skyTop: "#8f97a3", ambient: 1.9, hemiSky: "#e3e8ef", hemiGround: "#5c5f64", fill: 1.2, fog: 0.3, exposure: 1.05, shadowSoftness: 1, envLight: 1, ao: 1 },
+		{ x: 2, y: 14, z: 3, intensity: 0.55, color: "#e8ecf2" }),
+	golden: recipe({ sky: "#f0a868", skyTop: "#6a8cc0", ambient: 0.75, hemiSky: "#9fb3d6", hemiGround: "#6e5136", fill: 0.45, fog: 0.3, shadowSoftness: 0.35, envLight: 1, ao: 0.8 },
+		{ x: 9, y: 3.2, z: 4, intensity: 1.9, color: "#ffad5c" }),
+	dusk: recipe({ sky: "#8a6f8c", skyTop: "#18223f", ambient: 0.8, hemiSky: "#5b6c9c", hemiGround: "#29242e", fill: 0.35, fog: 0.4, shadowSoftness: 0.6, envLight: 1, ao: 0.8 },
+		{ x: -9, y: 1.8, z: -4, intensity: 0.7, color: "#ff9466" }),
+	night: recipe({ sky: "#0b1426", skyTop: "#020408", ambient: 0.6, hemiSky: "#34507f", hemiGround: "#0a0c12", fill: 0.25, fog: 0.45, shadowSoftness: 0.75, envLight: 1, ao: 0.8 },
+		{ x: -6, y: 6.5, z: 0.5, intensity: 0.6, color: "#9db6e6" }),
+	interior: recipe({ sky: "#2b2621", ambient: 0.7, hemiSky: "#ffe2bf", hemiGround: "#3d3128", fill: 0.55, fog: 0.35, shadowSoftness: 0.55, envLight: 1, ao: 0.9 },
+		{ x: 2, y: 4.5, z: 2.5, intensity: 1.35, color: "#ffd29c" }),
+	stage: recipe({ sky: "#000000", ambient: 0, hemiSky: "#000000", hemiGround: "#000000", fill: 0, fog: 0.7, shadowSoftness: 0.2, ao: 0.6 },
+		{ x: 1.5, y: 9, z: 3, intensity: 2.6, color: "#fff0d8" }),
+});
+
+/** What stage.applyLighting { keep } may hold back from the recipe. "lighting.hdr"
+ * keeps the HDR environment with its rotation, intensity and backdrop switch. */
+export const LIGHTING_KEEP_PATHS = Object.freeze(["keyLight.position", "keyLight.intensity", "keyLight.color",
+	...["sky", "skyTop", "ambient", "hemiSky", "hemiGround", "fill", "fog", "exposure", "shadowSoftness", "envLight", "ao", "hdr"].map((key) => `lighting.${key}`)]);
+
+/** The stage's { lighting, keyLight } after one recipe: every field written
+ * from it except the `keep` paths, which stay as they are. Studio also resets
+ * warmth, so it renders the tuned rig exactly; other recipes set a key colour,
+ * which overrides warmth. */
+export function applyLightingRecipe(stage, preset, keep = []) {
+	const chosen = LIGHTING_RECIPES[preset];
+	if (!chosen) throw new Error(`Unknown lighting preset: ${preset}`);
+	const before = { lighting: normalizeLighting(stage?.lighting), keyLight: createKeyLight(stage?.keyLight) };
+	const lighting = { ...chosen.lighting, preset };
+	for (const path of keep) if (path.startsWith("lighting.")) lighting[path.slice(9)] = before.lighting[path.slice(9)];
+	if (keep.includes("lighting.hdr")) for (const key of HDR_FIELDS) lighting[key] = before.lighting[key];
+	const keyLight = { ...before.keyLight, ...chosen.keyLight };
+	if (keep.includes("keyLight.position")) Object.assign(keyLight, { x: before.keyLight.x, y: before.keyLight.y, z: before.keyLight.z });
+	if (keep.includes("keyLight.intensity")) keyLight.intensity = before.keyLight.intensity;
+	if (keep.includes("keyLight.color")) Object.assign(keyLight, { color: before.keyLight.color, warmth: before.keyLight.warmth });
+	return { lighting: normalizeLighting(lighting), keyLight: createKeyLight(keyLight) };
+}
+
+// Linear fog, in metres from the camera. With fog 0 the viewport keeps its
+// tuned 18..54 m horizon fade and exports their 55..95 m one (stage-capture.jsx);
+// haze pulls both in together, reaching 2..14 m at fog 1 (a black-void pool of
+// light under the stage recipe). The squared falloff makes small values a
+// distant haze rather than a jump.
+export function hazeRange(fog) {
+	const far = (1 - fog) ** 2;
+	return { near: 2 + 53 * far, far: 14 + 81 * far };
+}
+
+/**
+ * Everything the renderer needs for one look, as plain colours and numbers.
+ * A null sky keeps the UI theme's studio stage — its grey, its deck and its
+ * ground bounce — so the default renders exactly as before under both themes;
+ * the grid view's neutral rig applies only then. An explicit sky makes the look
+ * theme-independent: what the shot camera exports is the same for every user,
+ * and so does an HDR backdrop (stage.lighting.hdr with hdrBackground).
+ */
+export function stageLook({ lighting, keyLight, theme = "dark", grid = false }) {
+	const normalized = normalizeLighting(lighting), key = createKeyLight(keyLight);
+	// An HDR backdrop is no UI theme's stage either: a null sky under it is the dark stage's grey.
+	const l = normalized.sky === null && normalized.hdr && normalized.hdrBackground ? { ...normalized, sky: stageBackground("dark") } : normalized;
+	const themed = l.sky === null, neutral = grid && themed, lightTheme = themed && theme === "light";
+	const sky = themed ? (grid ? GRID_BACKGROUND : stageBackground(theme)) : l.sky;
+	const haze = hazeRange(l.fog), base = neutral ? GRID_FOG : { near: 18, far: 54 };
+	const dim = key.intensity / 1.12, lift = Math.min(1, 0.35 + 0.65 * dim);
+	// The environment map takes over the hemisphere's share as envLight rises (stage-environment.js).
+	const skyLight = 0.9 * lift * l.ambient, hemiShare = Math.max(0, 1 - l.envLight);
+	return {
+		sky, skyTop: l.skyTop,
+		fog: { color: sky, near: Math.min(base.near, haze.near), far: Math.min(base.far, haze.far) },
+		// Exports keep their own far horizon until haze asks for a nearer one.
+		captureFog: l.fog > 0 ? haze : null,
+		hemi: { sky: neutral ? "#ffffff" : l.hemiSky, ground: neutral ? "#3a3d42" : lightTheme ? "#d6d8de" : l.hemiGround, intensity: skyLight * hemiShare },
+		// three's IBL irradiance is pi x the map, a hemisphere's is its colour x intensity: the 1/pi matches them.
+		env: environmentSpec(l, key, sky), envIntensity: (skyLight * l.envLight) / Math.PI,
+		// An HDR environment replaces that map once it has loaded (stage-sky.jsx): its light is
+		// the file's radiance x hdrIntensity x envLight, its backdrop the file x hdrIntensity.
+		hdr: l.hdr ? { id: l.hdr, rotation: l.hdrRotation, intensity: l.hdrIntensity, background: l.hdrBackground, envIntensity: l.envLight * l.hdrIntensity } : null,
+		ao: l.ao,
+		ambient: (neutral ? 0.34 : lightTheme ? 0.32 : 0.18) * lift * l.ambient,
+		fill: 0.36 * dim * l.fill, rim: 0.22 * dim * l.fill,
+		exposure: l.exposure,
+		// shadow.radius in shadow-map texels (2048 over 28 m: ~1.4 cm each); 1 is the tuned hard
+		// edge. A wider kernel reaches the surface's own depth on curved clay and
+		// cross-hatches it, so the normal offset grows with it (metres).
+		shadowRadius: 1 + l.shadowSoftness * 7,
+		shadowNormalBias: 0.02 + l.shadowSoftness * 0.08,
+		lightDeck: lightTheme,
+	};
+}

package/src/stage-occlusion.js

@@ -0,0 +1,210 @@
+// Ambient occlusion for the stage look (stage.lighting.ao): contact darkening
+// where a body meets the floor or a prop, and in creases (an armpit, the back of
+// a knee in a squat). Screen space, because the bodies are skinned and move: a
+// baked aoMap cannot follow a skinned mesh, and contact blobs under the feet
+// miss every crease.
+//
+// One hook on the scene (scene.onAfterRender) runs it after each draw of the
+// stage through a perspective camera, so every path gets it with no code of its
+// own: the viewport panes, the shot preview card, capture_frame, contact sheets
+// and video export (stage-capture.jsx renders the same scene into its target).
+// A draw with an override material (the outline prepass, the depth and normal
+// plates) is left alone, and so is the orthographic plan.
+//
+// Per draw, at half resolution past 960 px wide: a depth-only prepass of the
+// opaque set, the occlusion within AO_RADIUS of each pixel from SAMPLES samples
+// (how far each sample's direction rises above the surface the depth holds,
+// weighted toward the near ones and faded with the fog), a depth-aware 5x5
+// blur, then a multiply over the frame just drawn. The prepass reuses the
+// shadow maps the draw already made. On an Apple M4 Pro it adds about 0.4 ms of
+// GPU time to a 1920x1080 export frame.
+import * as THREE from "three";
+import { FullScreenQuad } from "three/examples/jsm/postprocessing/Pass.js";
+import { GIZMO_LAYER, POSER_LAYER } from "./dualview.jsx";
+
+const AO_RADIUS = 0.4;
+const SAMPLES = 16;
+// A sample whose direction rises less than this cosine above the normal is the
+// same surface (floor noise at grazing angles), not an occluder.
+const BIAS = 0.15;
+// Occlusion to darkening, tuned by eye on the clay figure (a squat's creases, feet on the deck).
+const GAIN = 3;
+// Size buckets kept alive at once (the main pane, the preview card, the exports).
+const CACHED_SIZES = 4;
+
+const VERTEX = "varying vec2 vUv;\nvoid main() { vUv = uv; gl_Position = vec4(position.xy, 0.0, 1.0); }";
+const OCCLUSION = `
+uniform sampler2D tDepth;
+uniform mat4 projection;
+uniform mat4 inverseProjection;
+uniform vec2 size;
+uniform vec2 fog;
+varying vec2 vUv;
+vec3 viewAt(vec2 uv, float depth) {
+	vec4 p = inverseProjection * vec4(vec3(uv, depth) * 2.0 - 1.0, 1.0);
+	return p.xyz / p.w;
+}
+vec3 viewAt(vec2 uv) { return viewAt(uv, texture2D(tDepth, uv).x); }
+void main() {
+	float depth = texture2D(tDepth, vUv).x;
+	if (depth >= 1.0) { gl_FragColor = vec4(1.0); return; }
+	vec3 p = viewAt(vUv, depth);
+	// The normal of the surface the depth buffer holds (each axis from the nearer
+	// neighbour, so an edge does not bend it): flat facets of the low-poly clay
+	// then occlude nothing of their own, whatever their smoothed shading normal says.
+	vec2 texel = 1.0 / size;
+	vec3 right = viewAt(vUv + vec2(texel.x, 0.0)) - p, left = p - viewAt(vUv - vec2(texel.x, 0.0));
+	vec3 up = viewAt(vUv + vec2(0.0, texel.y)) - p, down = p - viewAt(vUv - vec2(0.0, texel.y));
+	vec3 n = normalize(cross(abs(right.z) < abs(left.z) ? right : left, abs(up.z) < abs(down.z) ? up : down));
+	float reach = min(${AO_RADIUS.toFixed(2)} * projection[1][1] * 0.5 * size.y / -p.z, size.y * 0.2);
+	float fade = 1.0 - smoothstep(fog.x, fog.y, -p.z);
+	if (reach < 1.0 || fade <= 0.0) { gl_FragColor = vec4(1.0); return; }
+	float spin = 6.2831853 * fract(52.9829189 * fract(dot(gl_FragCoord.xy, vec2(0.06711056, 0.00583715))));
+	// A weighted mean over the samples near the surface (weight falls to 0 at RADIUS),
+	// so an occluder close by counts fully however small it is on screen.
+	float occlusion = 0.0, weights = 0.25;
+	for (int i = 0; i < ${SAMPLES}; i++) {
+		float angle = float(i) * 2.39996323 + spin;
+		// snapped to a texel centre, so the depth read and the position rebuilt from it agree
+		vec2 uv = (floor((vUv + vec2(cos(angle), sin(angle)) * ((float(i) + 0.5) / ${SAMPLES}.0) * reach / size) * size) + 0.5) / size;
+		vec3 v = viewAt(uv) - p;
+		float distance = length(v), weight = pow(max(0.0, 1.0 - distance / ${AO_RADIUS.toFixed(2)}), 2.0);
+		occlusion += max(dot(v, n) / max(distance, 1e-4) - ${BIAS.toFixed(2)}, 0.0) * weight;
+		weights += weight;
+	}
+	float ao = clamp(1.0 - ${GAIN.toFixed(2)} * occlusion / (weights * ${(1 - BIAS).toFixed(2)}), 0.0, 1.0);
+	gl_FragColor = vec4(vec3(mix(1.0, ao, fade)), 1.0);
+}`;
+const BLUR = `
+#include <packing>
+uniform sampler2D tOcclusion;
+uniform sampler2D tDepth;
+uniform vec2 size;
+uniform vec2 clip;
+varying vec2 vUv;
+float viewZ(vec2 uv) { return perspectiveDepthToViewZ(texture2D(tDepth, uv).x, clip.x, clip.y); }
+void main() {
+	float z = viewZ(vUv), total = 0.0, weights = 0.0;
+	for (int x = -2; x <= 2; x++) for (int y = -2; y <= 2; y++) {
+		vec2 uv = vUv + vec2(float(x), float(y)) / size;
+		float weight = 1.0 - smoothstep(0.02, 0.06, abs(viewZ(uv) - z) / -z);
+		total += texture2D(tOcclusion, uv).r * weight;
+		weights += weight;
+	}
+	gl_FragColor = vec4(vec3(total / max(weights, 1e-4)), 1.0);
+}`;
+const COMPOSITE = `
+uniform sampler2D tOcclusion;
+uniform float strength;
+varying vec2 vUv;
+void main() { gl_FragColor = vec4(vec3(mix(1.0, texture2D(tOcclusion, vUv).r, strength)), 1.0); }`;
+
+const pass = (fragmentShader, uniforms, extra = {}) => new THREE.ShaderMaterial({ vertexShader: VERTEX, fragmentShader, uniforms, depthTest: false, depthWrite: false, ...extra });
+const target = (width, height, filter, depth = false) => new THREE.WebGLRenderTarget(width, height, {
+	minFilter: filter, magFilter: filter, depthBuffer: depth, generateMipmaps: false,
+	...(depth ? { depthTexture: Object.assign(new THREE.DepthTexture(width, height, THREE.UnsignedIntType), { minFilter: THREE.NearestFilter, magFilter: THREE.NearestFilter }) } : {}),
+});
+// What the prepass leaves out: light rather than surface (glow halos, smoke,
+// see-through and faded parts, ghosts), picture cards whose alpha a solid
+// depth pass would ignore, lines and points.
+const seeThrough = (material) => [material].flat().some((m) => m && (m.transparent || m.depthWrite === false));
+const leftOut = (node) => node.userData?.beautyOnly || node.userData?.cutoutTexture !== undefined || node.isSprite || node.isPoints || node.isLine || (node.isMesh && seeThrough(node.material));
+
+/**
+ * Put the occlusion pass on `scene`. `settings.strength` (0..1) is read at each
+ * draw, so a slider changes it without rebuilding anything. Answers a function
+ * that takes the hook off and frees the targets.
+ */
+export function installOcclusion(scene, settings) {
+	// Depth is all the pass reads: the prepass writes no colour at all.
+	const depthOnly = new THREE.MeshBasicMaterial({ side: THREE.DoubleSide, colorWrite: false });
+	const occlusion = pass(OCCLUSION, { tDepth: { value: null }, projection: { value: new THREE.Matrix4() }, inverseProjection: { value: new THREE.Matrix4() }, size: { value: new THREE.Vector2() }, fog: { value: new THREE.Vector2() } });
+	const blur = pass(BLUR, { tOcclusion: { value: null }, tDepth: { value: null }, size: { value: new THREE.Vector2() }, clip: { value: new THREE.Vector2() } });
+	const composite = pass(COMPOSITE, { tOcclusion: { value: null }, strength: { value: 1 } }, {
+		blending: THREE.CustomBlending, blendEquation: THREE.AddEquation, blendSrc: THREE.ZeroFactor, blendDst: THREE.SrcColorFactor,
+		blendSrcAlpha: THREE.ZeroFactor, blendDstAlpha: THREE.OneFactor, toneMapped: false,
+	});
+	const quad = new FullScreenQuad(), sizes = new Map(), viewport = new THREE.Vector4(), scissor = new THREE.Vector4();
+	let running = false;
+	const targetsFor = (width, height) => {
+		const key = `${width}x${height}`;
+		let set = sizes.get(key);
+		if (set) sizes.delete(key);
+		else set = { prepass: target(width, height, THREE.NearestFilter, true), raw: target(width, height, THREE.NearestFilter), smooth: target(width, height, THREE.LinearFilter) };
+		sizes.set(key, set);
+		if (sizes.size > CACHED_SIZES) {
+			const [oldest, stale] = sizes.entries().next().value;
+			sizes.delete(oldest);
+			for (const t of Object.values(stale)) { t.depthTexture?.dispose(); t.dispose(); }
+		}
+		return set;
+	};
+	scene.onAfterRender = (renderer, _scene, camera) => {
+		if (running || scene.overrideMaterial || !camera?.isPerspectiveCamera || !(settings.strength > 0)) return;
+		running = true;
+		const output = renderer.getRenderTarget(), autoClear = renderer.autoClear, background = scene.background, mask = camera.layers.mask;
+		const shadows = renderer.shadowMap, shadowAuto = shadows.autoUpdate, shadowNeeds = shadows.needsUpdate;
+		renderer.getViewport(viewport);
+		renderer.getScissor(scissor);
+		const pixels = renderer.getCurrentViewport(new THREE.Vector4()), half = pixels.z > 960 ? 0.5 : 1;
+		const width = Math.max(1, Math.round(pixels.z * half)), height = Math.max(1, Math.round(pixels.w * half));
+		const { prepass, raw, smooth } = targetsFor(width, height), hidden = [];
+		try {
+			scene.traverse((node) => { if (node.visible && leftOut(node)) { hidden.push(node); node.visible = false; } });
+			scene.background = null;
+			scene.overrideMaterial = depthOnly;
+			camera.layers.disable(GIZMO_LAYER);
+			camera.layers.disable(POSER_LAYER);
+			shadows.autoUpdate = false;
+			renderer.autoClear = true;
+			renderer.setRenderTarget(prepass);
+			renderer.render(scene, camera);
+			for (const node of hidden.splice(0)) node.visible = true;
+			scene.background = background;
+			scene.overrideMaterial = null;
+			camera.layers.mask = mask;
+			const u = occlusion.uniforms, b = blur.uniforms, fog = scene.fog;
+			u.tDepth.value = b.tDepth.value = prepass.depthTexture;
+			u.projection.value.copy(camera.projectionMatrix);
+			u.inverseProjection.value.copy(camera.projectionMatrixInverse);
+			u.size.value.set(width, height);
+			u.fog.value.set(fog?.near ?? 1e5, fog?.far ?? 2e5);
+			renderer.setRenderTarget(raw);
+			quad.material = occlusion;
+			quad.render(renderer);
+			b.tOcclusion.value = raw.texture;
+			b.size.value.set(width, height);
+			b.clip.value.set(camera.near, camera.far);
+			renderer.setRenderTarget(smooth);
+			quad.material = blur;
+			quad.render(renderer);
+			composite.uniforms.tOcclusion.value = smooth.texture;
+			composite.uniforms.strength.value = Math.min(1, settings.strength);
+			renderer.setRenderTarget(output);
+			// The canvas takes back the pane's own viewport (setRenderTarget(null) floors it, the draw rounded it).
+			if (output === null) {
+				renderer.setViewport(viewport);
+				renderer.setScissor(scissor);
+			}
+			renderer.autoClear = false;
+			quad.material = composite;
+			quad.render(renderer);
+		} finally {
+			for (const node of hidden) node.visible = true;
+			if (renderer.getRenderTarget() !== output) renderer.setRenderTarget(output);
+			scene.background = background;
+			scene.overrideMaterial = null;
+			camera.layers.mask = mask;
+			shadows.autoUpdate = shadowAuto;
+			shadows.needsUpdate = shadowNeeds;
+			renderer.autoClear = autoClear;
+			running = false;
+		}
+	};
+	return () => {
+		delete scene.onAfterRender;
+		for (const set of sizes.values()) for (const t of Object.values(set)) { t.depthTexture?.dispose(); t.dispose(); }
+		for (const material of [depthOnly, occlusion, blur, composite]) material.dispose();
+		quad.dispose();
+	};
+}