cozyclay 2.1.0 → 3.0.0

package/src/stage-hdr-image.js

@@ -0,0 +1,116 @@
+// Environment files to the half-float equirectangular maps the stage renders
+// (stage-hdr-map.js): a Radiance .hdr through three's HDRLoader (the r180+ name
+// of RGBELoader), an OpenEXR through EXRLoader (loaded on first use), and an LDR
+// .png / .jpg through the browser's own decoder. Every map comes out the same
+// way: RGBA half floats in linear light, rows from straight down (row 0) to
+// straight up, at most HDR_MAX_WIDTH wide (a box filter by a whole factor), plus
+// its horizon colour (the deck fades into it) and its brightest direction (the
+// agent aims hdrRotation with it). No DOM at import, so Node tests decode too.
+import { DataUtils } from "three";
+import { HDRLoader } from "three/examples/jsm/loaders/HDRLoader.js";
+
+/** Widest map kept: the background's sharpness against the GPU memory of its cube and PMREM. */
+export const HDR_MAX_WIDTH = 2048;
+const fromHalf = DataUtils.fromHalfFloat;
+const toHalf = DataUtils.toHalfFloat;
+
+/** RGBA floats (rows bottom-up) as a half-float map. */
+export function halfMapFromFloats(width, height, floats) {
+	const data = new Uint16Array(floats.length);
+	for (let i = 0; i < floats.length; i++) data[i] = toHalf(floats[i]);
+	return { width, height, data };
+}
+
+/**
+ * A decoded image as a map: rows flipped bottom-up when the source runs top-down,
+ * and box-filtered by the smallest whole factor that fits maxWidth.
+ */
+export function fitMap({ width, height, data, topDown = false }, maxWidth = HDR_MAX_WIDTH) {
+	const factor = Math.max(1, Math.ceil(width / maxWidth));
+	if (factor === 1 && !topDown) return { width, height, data };
+	const w = Math.floor(width / factor), h = Math.max(1, Math.floor(height / factor)), out = new Uint16Array(w * h * 4);
+	const sourceRow = (row) => (topDown ? height - 1 - row : row);
+	if (factor === 1) {
+		for (let row = 0; row < h; row++) out.set(data.subarray(sourceRow(row) * width * 4, (sourceRow(row) + 1) * width * 4), row * width * 4);
+		return { width: w, height: h, data: out };
+	}
+	const sum = new Float64Array(4), area = factor * factor;
+	for (let row = 0; row < h; row++) {
+		for (let column = 0; column < w; column++) {
+			sum.fill(0);
+			for (let dy = 0; dy < factor; dy++) {
+				const base = (sourceRow(row * factor + dy) * width + column * factor) * 4;
+				for (let i = 0; i < factor * 4; i++) sum[i & 3] += fromHalf(data[base + i]);
+			}
+			for (let channel = 0; channel < 4; channel++) out[(row * w + column) * 4 + channel] = toHalf(sum[channel] / area);
+		}
+	}
+	return { width: w, height: h, data: out };
+}
+
+/** Mean linear RGB of the band within 3 degrees of the horizon. */
+export function mapHorizon({ width, height, data }) {
+	const band = Math.max(1, Math.round((3 / 180) * height)), first = Math.max(0, Math.floor(height / 2) - band), last = Math.min(height, Math.ceil(height / 2) + band);
+	const sum = [0, 0, 0];
+	for (let row = first; row < last; row++) for (let i = row * width * 4; i < (row + 1) * width * 4; i += 4) for (let c = 0; c < 3; c++) sum[c] += fromHalf(data[i + c]);
+	return sum.map((value) => Number((value / ((last - first) * width)).toFixed(5)));
+}
+
+/**
+ * World direction [x, y, z] of the map's brightest light (y up, azimuth 0 = +x,
+ * 90 = +z), rounded: the solid-angle-weighted mean direction of every texel
+ * within 10% of the peak, so a flat sun disc or a softbox reads at its centre.
+ */
+export function mapBrightest({ width, height, data }) {
+	const luma = new Float32Array(width * height);
+	let peak = 0;
+	for (let i = 0; i < luma.length; i++) peak = Math.max(peak, (luma[i] = 0.2126 * fromHalf(data[i * 4]) + 0.7152 * fromHalf(data[i * 4 + 1]) + 0.0722 * fromHalf(data[i * 4 + 2])));
+	const sum = [0, 0, 0];
+	for (let i = 0; i < luma.length; i++) {
+		if (luma[i] < 0.9 * peak) continue;
+		const az = (((i % width) + 0.5) / width - 0.5) * 2 * Math.PI, el = ((Math.floor(i / width) + 0.5) / height - 0.5) * Math.PI, cos = Math.cos(el);
+		sum[0] += cos * cos * Math.cos(az);
+		sum[1] += cos * Math.sin(el);
+		sum[2] += cos * cos * Math.sin(az);
+	}
+	const length = Math.hypot(...sum) || 1;
+	return sum.map((value) => Number((value / length).toFixed(2)) || 0);
+}
+
+/** A map with its analysis, as the map cache stores it. */
+export const analyzedMap = (map) => ({ ...map, horizon: mapHorizon(map), brightest: mapBrightest(map) });
+
+/** A Radiance RGBE file (ArrayBuffer) as a fitted map. Throws on a malformed file. */
+export function decodeRadiance(buffer) {
+	const { width, height, data } = new HDRLoader().parse(buffer);
+	return analyzedMap(fitMap({ width, height, data, topDown: true }));
+}
+
+async function decodeExr(buffer) {
+	const { EXRLoader } = await import("three/examples/jsm/loaders/EXRLoader.js");
+	const { width, height, data } = new EXRLoader().parse(buffer);
+	return analyzedMap(fitMap({ width, height, data }));
+}
+
+const SRGB_TO_LINEAR = Array.from({ length: 256 }, (_, i) => { const c = i / 255; return toHalf(c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4); });
+/** An LDR equirectangular picture through the browser's decoder, scaled to fit, in linear light. */
+async function decodePicture(buffer, type) {
+	const bitmap = await createImageBitmap(new Blob([buffer], { type }));
+	try {
+		const width = Math.min(HDR_MAX_WIDTH, bitmap.width), height = Math.max(1, Math.round((bitmap.height * width) / bitmap.width));
+		const canvas = new OffscreenCanvas(width, height), context = canvas.getContext("2d");
+		context.drawImage(bitmap, 0, 0, width, height);
+		const pixels = context.getImageData(0, 0, width, height).data, data = new Uint16Array(pixels.length);
+		for (let i = 0; i < pixels.length; i++) data[i] = (i & 3) === 3 ? toHalf(1) : SRGB_TO_LINEAR[pixels[i]];
+		return analyzedMap(fitMap({ width, height, data, topDown: true }));
+	} finally {
+		bitmap.close?.();
+	}
+}
+
+/** A stored environment record (stage-hdr.js normalizeHdrAsset) decoded to a map with its analysis. */
+export function decodeEnvironment({ type, bytes }) {
+	if (type === "image/vnd.radiance") return Promise.resolve().then(() => decodeRadiance(bytes));
+	if (type === "image/x-exr") return decodeExr(bytes);
+	return decodePicture(bytes, type);
+}

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,
+	};
+}