cozyclay 2.1.1 → 3.0.1

package/src/stage-characters.jsx

@@ -1,14 +1,12 @@
-import { memo, useEffect, useMemo, useRef, useState } from "react";
+import { memo, useEffect, useLayoutEffect, useMemo, useRef } from "react";
+import { useFBX } from "@react-three/drei";
 import { useThree } from "@react-three/fiber";
-import { Line, useFBX } from "@react-three/drei";
 import * as THREE from "three";
 import { SkeletonUtils } from "three/examples/jsm/Addons.js";
 import { ProxyFigure } from "./proxy-figure.jsx";
 import { isProxyFigure } from "./scenes.js";
 import { applyPartColours } from "./part-colours.js";
 import { applyHipsOffset, applyPose, primeBindPose } from "./poses.js";
-import { TRAIL_TRACKS, falloffWeight, jointTrailPoints, trailEditRange } from "./motion-trail.js";
-import { pickTrailPoint } from "./trail-pick.js";
 import { REST_BONES } from "./stage-startup-defaults.js";
 
 // Memoized: unchanged cast members skip re-rendering on every playhead tick.
@@ -28,19 +26,11 @@ const RiggedCharacter = memo(function RiggedCharacter({ url, position, rot, tint
 		// inside rig space: playback.js derives prep.scale from the bind pose,
 		// so a scaled bone hierarchy would be measured as a different rig.
 		clone.scale.setScalar(0.01 * scale);
-		// The joint shells (Alpha_Joints / Beta_Joints — elbows, knees, the
-		// exoskeleton bands) render in a darkened shade of the body tint so
-		// the segments read as separate pieces.
-		// The shipped clay is intentionally pale, but the stage deck is pale too.
-		// Lift neither with emissive nor a second light; a small value drop keeps
-		// the same authored hue while restoring silhouette contrast in the editor.
-		const bodyTint = new THREE.Color(tint).multiplyScalar(0.9);
-		const jointTint = bodyTint.clone().multiplyScalar(0.62);
 		clone.traverse((child) => {
 			if (child.isMesh) {
-				// warm clay reads as a maquette; cold grey reads as a broken render
+				// warm clay reads as a maquette; cold grey reads as a broken render.
+				// Its colour is the tint, set below in place.
 				child.material = new THREE.MeshStandardMaterial({
-					color: /_Joints$/i.test(child.name) ? jointTint : bodyTint,
 					// A slightly tighter highlight gives the clay enough form to read
 					// at blocking distance without turning it into shiny plastic.
 					roughness: 0.66,
@@ -59,7 +49,24 @@ const RiggedCharacter = memo(function RiggedCharacter({ url, position, rot, tint
 		// below runs immediately after and would otherwise be baked into "rest".
 		primeBindPose(clone);
 		return clone;
-	}, [fbx, tint, partColoursEnabled, partColoursMode]);
+	}, [fbx, partColoursEnabled, partColoursMode]);
+
+	// The tint recolours the clay in place, before the next frame. It must not rebuild the clone: a colour
+	// picker streams a value every drag frame, and a new clone re-binds the rig (playback, IK, contact radii).
+	// The joint shells (Alpha_Joints / Beta_Joints — elbows, knees, the exoskeleton bands) take a darkened
+	// shade of the body tint so the segments read as separate pieces. The shipped clay is intentionally pale,
+	// but the stage deck is pale too: a small value drop keeps the authored hue and restores silhouette
+	// contrast in the editor. Part colours paint the vertices themselves and keep their white material.
+	const invalidate = useThree((state) => state.invalidate);
+	useLayoutEffect(() => {
+		if (partColoursEnabled) return;
+		const bodyTint = new THREE.Color(tint).multiplyScalar(0.9);
+		const jointTint = bodyTint.clone().multiplyScalar(0.62);
+		model.traverse((child) => {
+			if (child.isMesh) child.material.color.copy(/_Joints$/i.test(child.name) ? jointTint : bodyTint);
+		});
+		invalidate();
+	}, [model, tint, partColoursEnabled, invalidate]);
 
 	// A new stature (a fresh extraction on this character) must not rebuild the
 	// clone — that would drop the rig the playback effects hold. Only the world
@@ -99,204 +106,3 @@ const RiggedCharacter = memo(function RiggedCharacter({ url, position, rot, tint
 		</group>
 	);
 });
-
-/* ------------------------- IK-mode motion trails --------------------------
- * World-space trajectory polylines of the loaded take: the selected track,
- * or all tracks when the user asks for an overview. The whole clip is
- * drawn as a faint line; while a grab is active the falloff window is
- * re-drawn on top as a bright highlight. Grabbing any point of a line starts
- * a drag on a camera-facing plane through the grab point; the caller deforms
- * the take (motion-trail.js falloff math) so the preview updates live. */
-export const MotionTrails = memo(function MotionTrails({ motion, rig = null, baseY, charScale, ikFocus, activeTrackId = null, falloffFrames, playheadFrame, pendingEdit, enabled, visible = true, onDragStart, onDragPreview, onDragEnd }) {
-	const { camera, gl, invalidate } = useThree();
-	const [drag, setDrag] = useState(null);
-	const callbacksRef = useRef({ onDragStart, onDragPreview, onDragEnd });
-	callbacksRef.current = { onDragStart, onDragPreview, onDragEnd };
-	const toTriples = (flat) => {
-		const out = [];
-		for (let index = 0; index + 2 < flat.length; index += 3) out.push([flat[index], flat[index + 1], flat[index + 2]]);
-		return out;
-	};
-	// Every trail track (root + IK endpoints + head) in its handle colour,
-	// sampled where playback renders each bone on this rig (not the clip's
-	// own joints, which sit 4-15 cm off the body), so draw and pick agree.
-	const tracks = useMemo(
-		() => TRAIL_TRACKS.map((track) => {
-			const flat = jointTrailPoints(motion, track.joint, { baseY, scale: charScale, rig });
-			return flat ? { ...track, flat, points: toTriples(flat) } : null;
-		}).filter(Boolean),
-		// eslint-disable-next-line react-hooks/exhaustive-deps
-		[motion, rig, baseY, charScale],
-	);
-	const trackById = (id) => tracks.find((track) => track.id === id) ?? null;
-	const focusTrack = activeTrackId ? tracks.find((track) => track.id === activeTrackId)?.id ?? null : null;
-	const visibleTracks = focusTrack ? tracks.filter((track) => track.id === focusTrack) : tracks;
-	// The falloff window rides whichever line is being (or was last) grabbed.
-	const highlightCandidate = drag ?? pendingEdit;
-	const highlight = highlightCandidate && (!focusTrack || highlightCandidate.track === focusTrack) ? highlightCandidate : null;
-	const highlightPoints = useMemo(() => {
-		if (!highlight || !motion?.frames) return null;
-		const flat = trackById(highlight.track)?.flat ?? trackById("hips")?.flat;
-		if (!flat) return null;
-		const { startFrame, endFrame } = trailEditRange(motion.frames, highlight.grabFrame, falloffFrames);
-		const out = [];
-		for (let frame = startFrame; frame < endFrame; frame += 1) {
-			out.push([flat[frame * 3], flat[frame * 3 + 1], flat[frame * 3 + 2]]);
-		}
-		return out.length > 1 ? out : null;
-		// eslint-disable-next-line react-hooks/exhaustive-deps
-	}, [highlight, motion, tracks, falloffFrames]);
-
-	// Manual capture-phase picking instead of r3f pointer handlers: handlers on
-	// a drei Line make react-three-fiber raycast the fat-line shader geometry on
-	// EVERY pointermove for hover bookkeeping, which is exactly the IK-mode lag.
-	// A single pointerdown listener that measures point-to-ray distance against
-	// the cached trail arrays costs nothing while the mouse merely moves.
-	const pickRef = useRef(null);
-	pickRef.current = { tracks: visibleTracks, enabled, falloffFrames, playheadFrame };
-	// Line2 instances for in-place geometry rewrites during a drag.
-	const lineRefs = useRef({});
-	const highlightRef = useRef(null);
-	useEffect(() => {
-		const dom = gl.domElement;
-		const raycaster = new THREE.Raycaster();
-		const hit = new THREE.Vector3();
-		const down = (event) => {
-			const pick = pickRef.current;
-			if (!pick?.enabled || event.button !== 0) return;
-			const rect = dom.getBoundingClientRect();
-			const ndc = new THREE.Vector2(
-				((event.clientX - rect.left) / rect.width) * 2 - 1,
-				-((event.clientY - rect.top) / rect.height) * 2 + 1,
-			);
-			raycaster.setFromCamera(ndc, camera);
-			const { origin, direction } = raycaster.ray;
-			const picked = pickTrailPoint({
-				tracks: pick.tracks,
-				playheadFrame: pick.playheadFrame,
-				falloffFrames: pick.falloffFrames,
-				rayOrigin: origin,
-				rayDirection: direction,
-				maxDistance: 0.2,
-			});
-			if (!picked) return;
-			const { track, grabFrame } = picked;
-			// The grab wins over the camera controls listening in the bubble phase.
-			event.stopPropagation();
-			event.preventDefault();
-			const flat = pick.tracks.find((candidate) => candidate.id === track)?.flat;
-			if (!flat) return;
-			const start = new THREE.Vector3(flat[grabFrame * 3], flat[grabFrame * 3 + 1], flat[grabFrame * 3 + 2]);
-			const normal = camera.getWorldDirection(new THREE.Vector3()).negate();
-			const plane = new THREE.Plane().setFromNormalAndCoplanarPoint(normal, start);
-			setDrag({ track, grabFrame });
-			callbacksRef.current.onDragStart?.({ track, grabFrame });
-			// The drag never touches React state: per rAF the grabbed line and the
-			// falloff highlight are rewritten in place on their Line2 geometries,
-			// and onDragPreview poses the rig imperatively. Re-rendering the whole
-			// app per pointermove is exactly the drag lag this avoids; the real
-			// commit (setMotion + pending edit) happens once, on pointerup.
-			const frames = flat.length / 3;
-			const { startFrame, endFrame } = trailEditRange(frames, grabFrame, pickRef.current.falloffFrames);
-			const deformedFlat = new Float32Array(flat);
-			const windowFlat = new Float32Array((endFrame - startFrame) * 3);
-			let lastDelta = null;
-			let queued = null;
-			let rafId = 0;
-			const applyPreview = (delta) => {
-				for (let frame = startFrame; frame < endFrame; frame += 1) {
-					const weight = falloffWeight(frame - grabFrame, pickRef.current.falloffFrames);
-					deformedFlat[frame * 3] = flat[frame * 3] + delta.x * weight;
-					deformedFlat[frame * 3 + 1] = flat[frame * 3 + 1] + delta.y * weight;
-					deformedFlat[frame * 3 + 2] = flat[frame * 3 + 2] + delta.z * weight;
-				}
-				windowFlat.set(deformedFlat.subarray(startFrame * 3, endFrame * 3));
-				lineRefs.current[track]?.geometry?.setPositions(deformedFlat);
-				highlightRef.current?.geometry?.setPositions(windowFlat);
-				callbacksRef.current.onDragPreview?.({ track, grabFrame, delta });
-				invalidate();
-			};
-			const flush = () => {
-				rafId = 0;
-				if (queued) applyPreview(queued);
-				queued = null;
-			};
-			const move = (pointerEvent) => {
-				const moveRect = dom.getBoundingClientRect();
-				const moveNdc = new THREE.Vector2(
-					((pointerEvent.clientX - moveRect.left) / moveRect.width) * 2 - 1,
-					-((pointerEvent.clientY - moveRect.top) / moveRect.height) * 2 + 1,
-				);
-				raycaster.setFromCamera(moveNdc, camera);
-				if (!raycaster.ray.intersectPlane(plane, hit)) return;
-				lastDelta = { x: hit.x - start.x, y: hit.y - start.y, z: hit.z - start.z };
-				queued = lastDelta;
-				if (!rafId) rafId = requestAnimationFrame(flush);
-			};
-			const up = () => {
-				window.removeEventListener("pointermove", move);
-				window.removeEventListener("pointerup", up);
-				if (rafId) cancelAnimationFrame(rafId);
-				if (queued) applyPreview(queued);
-				setDrag(null);
-				callbacksRef.current.onDragEnd?.({ track, grabFrame, delta: lastDelta });
-			};
-			window.addEventListener("pointermove", move);
-			window.addEventListener("pointerup", up);
-		};
-		dom.addEventListener("pointerdown", down, true);
-		return () => dom.removeEventListener("pointerdown", down, true);
-		// eslint-disable-next-line react-hooks/exhaustive-deps
-	}, [gl, camera]);
-
-	if (!tracks.length) return null;
-	// depthTest off + high renderOrder: the trails read through the character
-	// and the floor instead of vanishing into them. Every part rides its own
-	// IK-handle colour; the focused part draws thicker.
-	return (
-		<group
-			visible={visible}
-			renderOrder={900}
-			userData={{ editorOverlay: true }}
-			ref={(group) => {
-				// QA-only escape hatch (same spirit as window.__cozyclay): lets
-				// headless perf probes toggle the trails without a rebuild.
-				if (typeof window !== "undefined") {
-					window.__cozyclayTrails = group;
-					window.__cozyclayVisibleTrailTracks = visibleTracks.map((track) => track.id);
-				}
-			}}
-		>
-			{visibleTracks.map((track) => track.points.length > 1 && (
-				<Line
-					key={track.id}
-					ref={(line) => {
-						if (line) lineRefs.current[track.id] = line;
-						else delete lineRefs.current[track.id];
-					}}
-					points={track.points}
-					color={track.color}
-					lineWidth={track.id === focusTrack ? 4 : 2.5}
-					depthTest={false}
-					transparent
-					opacity={track.id === focusTrack ? 1 : 0.85}
-				/>
-			))}
-			{highlightPoints && (
-				<Line ref={highlightRef} points={highlightPoints} color={drag ? "#3dff7a" : "#ff8c42"} lineWidth={5} depthTest={false} />
-			)}
-		</group>
-	);
-}, (previous, next) => (
-	previous.motion === next.motion &&
-	previous.rig === next.rig &&
-	previous.baseY === next.baseY &&
-	previous.charScale === next.charScale &&
-	previous.ikFocus === next.ikFocus &&
-	previous.activeTrackId === next.activeTrackId &&
-	previous.falloffFrames === next.falloffFrames &&
-	previous.playheadFrame === next.playheadFrame &&
-	previous.pendingEdit === next.pendingEdit &&
-	previous.enabled === next.enabled &&
-	previous.visible === next.visible
-));

package/src/stage-editor-gizmos.jsx

@@ -4,6 +4,7 @@ import { Line, Text } from "@react-three/drei";
 import * as THREE from "three";
 import { GIZMO_LAYER } from "./dualview.jsx";
 import { craneHeightAt, prepareRailBend, railPoint } from "./camera-follow.js";
+import { floorDragStart } from "./rail-dot-drag.js";
 import { insertPathMark, MARK_GAP, MAX_PATH_LEAN, MAX_PATH_MARKS, MAX_PATH_POINTS, nearestPathFraction, pathCurve, pathMarkFractions, pathMarks, pathPointAtFraction } from "./object-path.js";
 
 /**
@@ -261,8 +262,7 @@ export function CameraRailScenePreview({ points, cumLen, length, crane }) {
  * The crane's height marks as grabbable dots on the lifted curve. Click a
  * dot to select it; the selected dot grows a 3-axis gizmo — Y sets the
  * mark's height, X/Z bend the camera path itself by moving the drawn rail
- * control point nearest the mark. A free drag on the dot rides a
- * camera-facing vertical plane (height, plus arc slide for interior marks),
+ * control point nearest the mark. A free drag moves the dot over the floor, bending the rail (rail-dot-drag.js);
  * Shift-drag slides along the arc at a fixed height, double-click the curve
  * adds a mark and Delete removes a non-endpoint. Dots live on GIZMO_LAYER, so the
  * recording never sees them.
@@ -958,8 +958,8 @@ export function CraneHandles({ rail, crane, controlPoints, selectedIndex, enable
 			event.preventDefault();
 			const index = hit.object.userData.craneIndex;
 			s.onSelect(index);
-			dragRef.current = { index, slide: event.shiftKey, recorded: false };
-			setDragInfo({ kind: event.shiftKey ? "slide" : "free" });
+			dragRef.current = floorDragStart(s, index, raycaster.ray, event.shiftKey) ?? { index, slide: event.shiftKey, recorded: false };
+			setDragInfo(dragRef.current.axis ? { kind: "bend", t0: dragRef.current.t0, radius: dragRef.current.radius } : { kind: event.shiftKey ? "slide" : "free" });
 			invalidate();
 		};
 		const onMove = (event) => {
@@ -982,8 +982,8 @@ export function CraneHandles({ rail, crane, controlPoints, selectedIndex, enable
 					const height = Math.max(0.1, Math.min(12, drag.startHeight + travel));
 					s.onChangePoints(points.map((entry, i) => (i === drag.index ? { ...entry, height } : entry)), { dragging: true });
 				} else if (drag.startControls && drag.bendWeights && s.onChangeRail) {
-					const dx = drag.axis === "x" ? travel : 0;
-					const dz = drag.axis === "z" ? travel : 0;
+					const dx = drag.axis === "x" ? travel : drag.axis === "floor" ? world.x : 0;
+					const dz = drag.axis === "z" ? travel : drag.axis === "floor" ? world.z : 0;
 					const moved = drag.startControls.map((entry, i) => (drag.bendWeights[i] > 0
 						? { ...entry, x: entry.x + dx * drag.bendWeights[i], z: entry.z + dz * drag.bendWeights[i] }
 						: entry));

package/src/stage-environment.js

@@ -0,0 +1,93 @@
+// The stage look's environment light (stage.lighting.envLight): a sky-and-ground
+// map built from the look's own colours, so clay and kit materials take the sky's
+// tint and a soft fill from every direction instead of a flat two-colour
+// hemisphere. The upper half grades from `sky` at the horizon to `skyTop`
+// overhead (the same easing as the background, stage-sky.jsx), the lower half is
+// the ground bounce (hemiGround), and a glow sits around the key's direction (the
+// sun, the moon). Pure arithmetic in linear RGB, so the tests read the pixels;
+// stage-sky.jsx prefilters the map with PMREMGenerator and sets it as
+// scene.environment.
+//
+// Brightness: the sky half is scaled to carry the hemisphere's sky light (hemiSky)
+// in total, and stageLook() hands the hemisphere's
+// share to the map as envLight rises (0 = hemisphere only, the studio look;
+// 1 = the map alone at the same level; 2 = twice as bright).
+
+export const ENV_WIDTH = 128;
+export const ENV_HEIGHT = 64;
+// How much the key's glow adds under crisp shadows, as a share of the sky's own
+// light on a surface facing it, and its spread (1 - cos of the angle where it falls to 1/e, ~24 deg).
+const SUN_SHARE = 0.8;
+const SUN_SPREAD = 0.085;
+// Below the horizon the ground takes over across this band (degrees).
+const HORIZON_BAND = 8;
+
+const toLinear = (c) => (c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4);
+/** "#rrggbb" to linear RGB 0..1. */
+export const linearRgb = (hex) => [1, 3, 5].map((i) => toLinear(parseInt(hex.slice(i, i + 2), 16) / 255));
+export const luminance = ([r, g, b]) => 0.2126 * r + 0.7152 * g + 0.0722 * b;
+const mix = (a, b, t) => a.map((value, i) => value + (b[i] - value) * t);
+const scale = (a, k) => a.map((value) => value * k);
+const round = (a) => a.map((value) => Number(value.toFixed(5)));
+
+// The sky's easing by elevation (degrees): 0 at and below the horizon, 1 from 60 deg up.
+const skyBlend = (elevation) => (elevation <= 0 ? 0 : 1 - (1 - Math.min(1, elevation / 60)) ** 2);
+
+/**
+ * What the map is made of, in linear RGB, or null when envLight is 0. `lighting`
+ * and `keyLight` are normalized (stage-lighting.js); `sky` is the horizon colour
+ * the look resolved (the theme grey when lighting.sky is null).
+ */
+export function environmentSpec(lighting, keyLight, sky) {
+	if (!(lighting.envLight > 0)) return null;
+	const horizon = linearRgb(sky), zenith = linearRgb(lighting.skyTop ?? sky), skyLight = linearRgb(lighting.hemiSky);
+	// The sky half's mean luminance over its solid angle, so the sky can be scaled
+	// to carry hemiSky's light in total whatever its colours: a sky brighter at the
+	// horizon then lights the sides of a figure more and its top less.
+	let weighted = 0, weights = 0;
+	for (let step = 0; step < 90; step++) {
+		const elevation = step + 0.5, cos = Math.cos((elevation * Math.PI) / 180);
+		weighted += luminance(mix(horizon, zenith, skyBlend(elevation))) * cos;
+		weights += cos;
+	}
+	const mean = weighted / weights, target = luminance(skyLight);
+	// A black sky has no shape to keep: the sky half is then hemiSky itself.
+	const [low, high] = mean > 1e-6 ? [scale(horizon, target / mean), scale(zenith, target / mean)] : [skyLight, skyLight];
+	const length = Math.hypot(keyLight.x, keyLight.y, keyLight.z) || 1, key = linearRgb(keyLight.color ?? "#ffffff");
+	// A soft-shadowed look is a hazy or overcast sky: its sun is a fainter glow.
+	const keyLuma = luminance(key) || 1, share = SUN_SHARE * (1 - 0.6 * lighting.shadowSoftness);
+	return {
+		horizon: round(low), zenith: round(high), ground: round(linearRgb(lighting.hemiGround)),
+		sun: { direction: round([keyLight.x / length, keyLight.y / length, keyLight.z / length]),
+			// peak radiance: the glow integrates to ~2*pi*spread, so this adds `share` of the sky's light toward it
+			color: round(scale(key, (share * target) / (2 * SUN_SPREAD) / keyLuma)) },
+	};
+}
+
+/** Radiance (linear RGB) of the map in a unit direction [x, y, z] (y up). */
+export function environmentRadiance(spec, [x, y, z]) {
+	const elevation = (Math.asin(Math.max(-1, Math.min(1, y))) * 180) / Math.PI;
+	const skyAt = mix(spec.horizon, spec.zenith, skyBlend(elevation));
+	const base = elevation >= 0 ? skyAt : mix(spec.horizon, spec.ground, Math.min(1, -elevation / HORIZON_BAND));
+	const [sx, sy, sz] = spec.sun.direction, cos = x * sx + y * sy + z * sz;
+	const glow = Math.exp((cos - 1) / SUN_SPREAD);
+	return base.map((value, i) => value + spec.sun.color[i] * glow);
+}
+
+/**
+ * The equirectangular map as RGBA floats, rows from straight down (row 0) to
+ * straight up, columns around the horizon the way three samples an
+ * equirectangular texture (u = atan2(z, x) / 2pi + 0.5).
+ */
+export function environmentPixels(spec, width = ENV_WIDTH, height = ENV_HEIGHT) {
+	const data = new Float32Array(width * height * 4);
+	for (let row = 0; row < height; row++) {
+		const elevation = ((row + 0.5) / height - 0.5) * Math.PI, cosEl = Math.cos(elevation), y = Math.sin(elevation);
+		for (let column = 0; column < width; column++) {
+			const azimuth = ((column + 0.5) / width - 0.5) * 2 * Math.PI;
+			const radiance = environmentRadiance(spec, [Math.cos(azimuth) * cosEl, y, Math.sin(azimuth) * cosEl]);
+			data.set([...radiance, 1], (row * width + column) * 4);
+		}
+	}
+	return data;
+}

package/src/stage-hdr-builtins.js

@@ -0,0 +1,107 @@
+// The built-in HDR environments (stage-hdr.js HDR_BUILTINS), drawn as
+// equirectangular radiance maps in linear RGB: a night street, an overcast
+// field and a photo studio. Pure arithmetic and an integer hash, so a map is
+// the same on every machine and the tests read its pixels. Rows run from
+// straight down (row 0) to straight up, columns around the horizon the way
+// three samples an equirectangular texture: azimuth 0 is +x, +90 is +z (toward
+// the default camera), -90 is -z.
+
+const D = Math.PI / 180;
+const clamp01 = (value) => Math.max(0, Math.min(1, value));
+const smooth = (value) => { const t = clamp01(value); return t * t * (3 - 2 * t); };
+const mix = (a, b, t) => a.map((value, i) => value + (b[i] - value) * t);
+const add = (out, colour, weight) => { if (weight > 0) for (let i = 0; i < 3; i++) out[i] += colour[i] * weight; };
+/** A 0..1 integer hash of two integers and a seed: windows, rooflines and trees. */
+function hash(a, b, seed) {
+	let h = Math.imul(a, 0x27d4eb2d) ^ Math.imul(b, 0x165667b1) ^ Math.imul(seed, 0x9e3779b1);
+	h = Math.imul(h ^ (h >>> 15), 0x85ebca6b);
+	h = Math.imul(h ^ (h >>> 13), 0xc2b2ae35);
+	return ((h ^ (h >>> 16)) >>> 0) / 4294967296;
+}
+/** Smooth 0..1 value noise around the horizon: `knots` hashed values, eased between, wrapping at azimuth +-180. */
+const noise = (az, knots, seed) => {
+	const x = ((az + 180) / 360) * knots, i = Math.floor(x), t = smooth(x - i);
+	return hash(i % knots, 0, seed) * (1 - t) + hash((i + 1) % knots, 0, seed) * t;
+};
+const unit = (az, el) => [Math.cos(el * D) * Math.cos(az * D), Math.sin(el * D), Math.cos(el * D) * Math.sin(az * D)];
+/** A round light of peak radiance 1 at `centre`, falling to 1/e `radius` degrees off it. */
+const spot = (dir, centre, radius) => Math.exp((dir[0] * centre[0] + dir[1] * centre[1] + dir[2] * centre[2] - 1) / (1 - Math.cos(radius * D)));
+/** Signed azimuth difference in degrees, -180..180. */
+const azDelta = (az, centre) => ((((az - centre + 180) % 360) + 360) % 360) - 180;
+/** A soft-edged panel in azimuth/elevation (degrees): 1 inside, 0 outside, `edge` wide. */
+const panel = (az, el, { az: a, el: e, w, h, edge = 1.5 }) => smooth((w - Math.abs(azDelta(az, a)) * Math.cos(e * D)) / edge) * smooth((h - Math.abs(el - e)) / edge);
+
+const NIGHT = { lampA: unit(42.5, 11.6), lampB: unit(-140.5, 12.8), moon: unit(-60, 48) };
+function nightStreet(az, el, dir) {
+	const out = el >= 0 ? mix([0.03, 0.028, 0.042], [0.004, 0.006, 0.016], Math.sqrt(el / 90)) : [0.006, 0.006, 0.0075];
+	if (el >= 0) {
+		// A skyline of blocks 5..14 degrees wide and 3..16 tall, with lit windows.
+		const block = Math.floor((az + 180) / 9), roof = 3 + 13 * hash(block, 1, 7) * (0.5 + 0.5 * hash(block, 2, 7));
+		if (el < roof) {
+			out.splice(0, 3, 0.007, 0.007, 0.01);
+			const column = Math.floor((az + 180) / 1.1), row = Math.floor(el / 1.5), lit = hash(column, row, 11);
+			const inside = Math.abs(((az + 180) / 1.1) % 1 - 0.5) < 0.28 && Math.abs((el / 1.5) % 1 - 0.5) < 0.24;
+			if (inside && lit < 0.3) add(out, lit < 0.2 ? [0.42, 0.3, 0.15] : [0.2, 0.22, 0.28], 1);
+		}
+		add(out, [3.2, 3.4, 3.8], spot(dir, NIGHT.moon, 0.45));
+		add(out, [0.03, 0.035, 0.05], spot(dir, NIGHT.moon, 9));
+	} else {
+		// Wet asphalt: a warm pool under each lamp and a streak reflecting it.
+		for (const [lamp, az0] of [[NIGHT.lampA, 42.5], [NIGHT.lampB, -140.5]]) {
+			const across = azDelta(az, az0), pool = Math.exp(-(across * across) / (2 * 22 * 22)) * smooth((-el - 2) / 10) * Math.exp(-Math.max(0, -el - 18) / 18);
+			add(out, [0.09, 0.05, 0.018], pool);
+			add(out, [0.6, 0.33, 0.1], Math.exp(-(across * across) / 4) * smooth((-el) / 2) * Math.exp(el / 10) * (lamp === NIGHT.lampA ? 1 : 0.8));
+		}
+	}
+	add(out, [70, 38, 12], spot(dir, NIGHT.lampA, 1.3));
+	add(out, [55, 30, 9.5], spot(dir, NIGHT.lampB, 1.3));
+	add(out, [0.9, 0.5, 0.17], spot(dir, NIGHT.lampA, 5) + 0.8 * spot(dir, NIGHT.lampB, 5));
+	return out;
+}
+
+const OVERCAST = { sun: unit(-118, 40) };
+function overcastField(az, el, dir) {
+	if (el < 0) {
+		// A green field, hazier toward the horizon.
+		const out = mix([0.13, 0.155, 0.1], [0.085, 0.125, 0.045], smooth(-el / 25));
+		add(out, [0.012, 0.015, 0.004], hash(Math.floor((az + 180) * 2), Math.floor(-el * 2), 3) - 0.5);
+		return out;
+	}
+	// The overcast sky is three times brighter overhead than at the horizon.
+	const out = [0.8, 0.83, 0.88].map((value) => value * (1 + 2 * Math.sin(el * D)) / 3);
+	add(out, [0.9, 0.85, 0.74], spot(dir, OVERCAST.sun, 14));
+	// A tree line: two octaves of smooth value noise around the horizon, 0.5..3 degrees tall.
+	const crown = 0.5 + 1.8 * noise(az, 52, 5) + 0.7 * noise(az, 225, 6);
+	if (el < crown) return mix(out, [0.032, 0.046, 0.028], smooth((crown - el) / 0.25));
+	return out;
+}
+
+const STUDIO = { keyCentre: unit(130.6, 23.5), key: { az: 130.6, el: 23.5, w: 16, h: 12 }, strip: { az: 13, el: 15, w: 4, h: 22 }, rim: { az: -84, el: 19, w: 10, h: 14 } };
+function studioSoftbox(az, el, dir) {
+	const out = el >= 0 ? [0.018, 0.018, 0.02] : mix([0.032, 0.032, 0.034], [0.022, 0.022, 0.024], smooth(-el / 60));
+	// The softbox is a touch brighter at its centre, like a real diffuser.
+	add(out, [5, 4.9, 4.7], panel(az, el, STUDIO.key) * (0.92 + 0.08 * spot(dir, STUDIO.keyCentre, 8)));
+	add(out, [2.2, 2.3, 2.5], panel(az, el, STUDIO.strip));
+	add(out, [2, 2, 2], panel(az, el, STUDIO.rim));
+	add(out, [0.5, 0.5, 0.5], smooth((el - 66) / 6));
+	return out;
+}
+
+const DRAW = { "builtin:night-street": nightStreet, "builtin:overcast-field": overcastField, "builtin:studio-softbox": studioSoftbox };
+export const BUILTIN_WIDTH = 1024;
+export const BUILTIN_HEIGHT = 512;
+
+/** A built-in map as RGBA floats (linear radiance), or null for an unknown id. */
+export function builtinEnvironmentPixels(id, width = BUILTIN_WIDTH, height = BUILTIN_HEIGHT) {
+	const draw = DRAW[id];
+	if (!draw) return null;
+	const data = new Float32Array(width * height * 4);
+	for (let row = 0; row < height; row++) {
+		const el = ((row + 0.5) / height - 0.5) * 180;
+		for (let column = 0; column < width; column++) {
+			const az = ((column + 0.5) / width - 0.5) * 360, radiance = draw(az, el, unit(az, el));
+			data.set([Math.max(0, radiance[0]), Math.max(0, radiance[1]), Math.max(0, radiance[2]), 1], (row * width + column) * 4);
+		}
+	}
+	return data;
+}

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