cozyclay 2.1.1 → 3.0.1

package/src/object-gizmo.jsx

@@ -3,15 +3,11 @@ import { useFrame, useThree } from "@react-three/fiber";
 import * as THREE from "three";
 import { GIZMO_LAYER, SHOT_ASPECT, fitAspect } from "./dualview.jsx";
 import { HANDLE_PROXY_FLAG, claimsPress } from "./gizmo-claim.js";
-import {
-	CUTOUT_KIND,
-	objectSize,
-	rotatePatch,
-	scalePatch,
-	screenRotatePatch,
-	translatePatch,
-	wrapAngle,
-} from "./scene-objects.js";
+import { CUTOUT_KIND, rotatePatch, scalePatch, screenRotatePatch, translatePatch, wrapAngle } from "./scene-objects.js";
+import { dragTravel, dragTurn } from "./held-object-pose.js";
+import { HeldTrail } from "./held-object-edit.jsx";
+import { ACTIVE_COLOR, ARROW_LEN, AXES, AXIS_VECTORS, BOX_SIZE, CARD_CORNERS, CENTRE_BOX, CORNER_BOX, FAR_HALF_ALPHA, GROUND, PICK_CENTRE_R, PICK_CORNER_R, PICK_SHAFT_R, PICK_TUBE_R,
+	PLANES, PLANE_OFFSET, PLANE_SIZE, RING_R, RING_TUBE, SCREEN_RING_R, SCREEN_SCALE, SHAFT_R, TIP_LEN, TIP_R, gizmoOrigin, gizmoTurn, handleKey } from "./object-gizmo-parts.js";
 
 /**
  * The transform gizmo for the selected scene object — the thing every 3D tool
@@ -46,109 +42,8 @@ import {
  * space and decomposed back into the same channels (screenRotatePatch).
  */
 
-const AXES = [
-	{ axis: "x", dir: new THREE.Vector3(1, 0, 0), color: "#ff5340" },
-	{ axis: "y", dir: new THREE.Vector3(0, 1, 0), color: "#54e05c" },
-	{ axis: "z", dir: new THREE.Vector3(0, 0, 1), color: "#3d8bff" },
-];
-/** the same three directions, addressable by the record's axis key */
-const AXIS_VECTORS = { x: AXES[0].dir, y: AXES[1].dir, z: AXES[2].dir };
-/** Move-tool plane handles. Unity colours each square after the axis it LOCKS,
- * so the blue square (z locked) slides in xy. `normal` is the pinned axis. */
-const PLANES = [
-	{ id: "xz", axes: ["x", "z"], normal: "y", color: "#54e05c" },
-	{ id: "xy", axes: ["x", "y"], normal: "z", color: "#3d8bff" },
-	{ id: "yz", axes: ["y", "z"], normal: "x", color: "#ff5340" },
-];
-const PLANE_OFFSET = 0.26; // where the square sits along each of its two axes
-const PLANE_SIZE = 0.2;
-const ARROW_LEN = 0.62;
-const SHAFT_R = 0.016;
-const TIP_R = 0.05;
-const TIP_LEN = 0.14;
-const RING_R = 0.52;
-/**
- * The axis rings are drawn as two half-tori instead of one full torus. A full
- * ring is misleading: the half facing away from the camera is pixel-identical
- * to the near half, so a drag started on the far side reads backwards.
- * Depth-sorting the ring against the object would only help when the object
- * is big enough to occlude the far half — the gizmo sits at the object's
- * centre and the ring is only 0.52 m across, so for the small props a
- * blocking tool is full of, the far half projects outside the silhouette and
- * stays ambiguous. Fading it instead (FAR_HALF_ALPHA vs the near half's
- * 0.95) is unambiguous at every object size and camera angle. Only the drawn
- * halves fade — the pick proxy stays one full invisible torus per ring.
- */
-const FAR_HALF_ALPHA = 0.28;
-/** the outer screen-space ring: larger than the axis rings (RING_R) so it
- * encloses them from every angle, and far enough out that its pick band
- * [0.61, 0.75] clears the axis rings' [0.45, 0.59] — the two can never fight
- * for a grab. (§3.3: "a larger circle enclosing the sphere, drawn flat to
- * the viewer" — rotates about the view axis.) */
-const SCREEN_RING_R = 0.68;
-/** Unity's yellow for the handle being dragged — and, after release, for the
- * last-dragged one, until the selection or the tool changes (§3.1). */
-const ACTIVE_COLOR = "#ffd23d";
-const RING_TUBE = 0.022;
-const BOX_SIZE = 0.09; // scale-mode axis knobs
-const CENTRE_BOX = 0.11; // uniform-scale knob at the pivot
-/** Pick proxies. A drawn 1.6 cm shaft is ~3 screen pixels — nothing anyone can
- * reliably grab — so hit testing runs against invisible fat volumes around each
- * arrow, ring and knob, the way every DCC gizmo does it. */
-const PICK_SHAFT_R = 0.09;
-const PICK_TUBE_R = 0.07;
-const PICK_CENTRE_R = 0.16;
-/** metres of gizmo per metre of camera distance: keeps it a constant size on
- * screen whether the object is at the lens or across the room */
-const SCREEN_SCALE = 0.16;
-
-/** the object's own centre height, where the gizmo sits */
-function gizmoHeight(object) {
-	return (object.y ?? 0) + Math.max(objectSize(object).height / 2, 0.25);
-}
-
-/** the handles-Map key a pick entry was registered under — the same
- * expression __gizmoPick reports, so highlights and QA hooks agree on handle
- * identity */
-function handleKey(entry) {
-	if (entry.corner) return `corner:${entry.corner.id}`;
-	return entry.axis ?? (entry.plane ? `plane:${entry.plane.id}` : "centre");
-}
-
-/**
- * The four corners of a cutout card, in the card's own local space.
- *
- * A standee is a picture, and a picture is resized by its corners — grabbing
- * one and pulling is the gesture everybody already has for "make this bigger",
- * and unlike an axis knob it says which way is bigger without reading a label.
- * `sx`/`sy` are which way each corner lies from the centre, so the drag can
- * measure travel along the diagonal that corner actually points down.
- */
-const CARD_CORNERS = [
-	{ id: "tr", sx: 1, sy: 1 },
-	{ id: "tl", sx: -1, sy: 1 },
-	{ id: "br", sx: 1, sy: -1 },
-	{ id: "bl", sx: -1, sy: -1 },
-];
-const CORNER_BOX = 0.085;
-const PICK_CORNER_R = 0.13;
-
-/**
- * Screen-space ring result: the object rotated `deltaDeg` about the world
- * `viewAxis`, written back as all three Euler channels in one patch. The
- * stored channels are Euler degrees per world axis, so the drag-start
- * orientation is composed with the delta in quaternion space and decomposed
- * again in the same order the renderer uses — exact for any start
- * orientation, where a single-channel approximation would drift. Snap
- * quantizes the accumulated delta to the same 5° grid the axis rings snap
- * their start+delta to (start values are always on the grid themselves).
- */
-
-// Path authoring intersects presses with the set floor, exactly where a
-// dropped pin will live.
-const GROUND = new THREE.Plane(new THREE.Vector3(0, 1, 0), 0);
 
-export default function ObjectGizmo({ object, objects = [], mode = "move", snap = true, enabled, pickOnly = false, paneRef, camRef, shotAspect = SHOT_ASPECT, onChange, onSelect, onGroundClick, onDragStart, onDragEnd, claimPointer }) {
+export default function ObjectGizmo({ object, objects = [], mode = "move", snap = true, enabled, pickOnly = false, paneRef, camRef, shotAspect = SHOT_ASPECT, onChange, onSelect, onGroundClick, onDragStart, onDragEnd, claimPointer, held = null }) {
 	const { gl, scene } = useThree();
 	// shotAspect null = the camera fills the pane (the editor working view):
 	// pointer mapping uses the pane rect itself instead of a letterboxed
@@ -174,7 +69,10 @@ export default function ObjectGizmo({ object, objects = [], mode = "move", snap
 	const hoverRef = useRef(null); // last hovered key: pointer moves that keep it skip the re-render
 	const dragRef = useRef(null);
 	const stateRef = useRef(null);
-	stateRef.current = { object, objects, mode, snap, onChange, onSelect, onGroundClick, onDragStart, onDragEnd, claimPointer };
+	// `held` (held-object-edit.jsx): the object is drawn by a compiled take. The
+	// gizmo stands on that drawn pose, and while a hand holds the object a move
+	// or rotate drag edits its motion through `held` instead of the record.
+	stateRef.current = { object, objects, mode, snap, onChange, onSelect, onGroundClick, onDragStart, onDragEnd, claimPointer, held };
 	const tools = useMemo(
 		() => ({
 			raycaster: new THREE.Raycaster(),
@@ -347,6 +245,7 @@ export default function ObjectGizmo({ object, objects = [], mode = "move", snap
 				// the moment the pointer crosses the ring's ±180° seam.
 				drag.turned += wrapAngle(((angle - drag.lastAngle) * 180) / Math.PI);
 				drag.lastAngle = angle;
+				if (drag.held) return void stateRef.current.held?.rotate(drag.dir, dragTurn(drag.turned, snapping ? 5 : 0));
 				if (drag.axis === "screen") {
 					// The screen ring spins about the view axis: compose the
 					// delta onto the drag-start orientation in quaternion space
@@ -399,6 +298,7 @@ export default function ObjectGizmo({ object, objects = [], mode = "move", snap
 				return;
 			}
 			tools.delta.subVectors(tools.hit, drag.hitStart);
+			if (drag.held) return void stateRef.current.held?.move(dragTravel(tools.delta, drag.planeAxes ? drag.planeAxes.map((axis) => AXIS_VECTORS[axis]) : [drag.dir], snapping ? 0.05 : 0));
 			if (drag.planeAxes) {
 				// Plane handle: two axes travel, the third is pinned. This is what
 				// replaced body-dragging — the XZ square is how a set gets dressed.
@@ -438,7 +338,8 @@ export default function ObjectGizmo({ object, objects = [], mode = "move", snap
 			const end = stateRef.current.onDragEnd;
 			const token = drag.token;
 			teardownDrag();
-			if (token != null && end) end(token, { commit });
+			if (drag.held) stateRef.current.held?.end(commit);
+			else if (token != null && end) end(token, { commit });
 		};
 
 		/** pointerup and pointercancel both commit: the travel already applied
@@ -482,7 +383,8 @@ export default function ObjectGizmo({ object, objects = [], mode = "move", snap
 			// (a jump of however far the car has driven). The pivot, and the yaw
 			// the card's corners are seen at, are the shown ones.
 			const live = stateRef.current.objects.find((entry) => entry.id === shown.id) ?? shown;
-			tools.origin.set(shown.x, gizmoHeight(shown), shown.z);
+			const heldEdit = stateRef.current.held;
+			gizmoOrigin(shown, heldEdit, tools.origin);
 			camera.getWorldDirection(tools.eye);
 			let plane;
 			let drag;
@@ -491,7 +393,9 @@ export default function ObjectGizmo({ object, objects = [], mode = "move", snap
 				// pivot. The screen ring has no axis of its own: it spins
 				// about the camera's own forward, so its plane is the
 				// camera-facing plane through the pivot.
-				const spinDir = axis === "screen" ? tools.eye : dir;
+				// A held object turns about its own axes (its rings are drawn turned too).
+				const turn = gizmoTurn(heldEdit, kind);
+				const spinDir = axis === "screen" ? tools.eye : turn ? dir.clone().applyQuaternion(new THREE.Quaternion(...turn)) : dir;
 				plane = new THREE.Plane().setFromNormalAndCoplanarPoint(spinDir, tools.origin.clone());
 				const hit = new THREE.Vector3();
 				if (!tools.raycaster.ray.intersectPlane(plane, hit)) return false;
@@ -577,12 +481,14 @@ export default function ObjectGizmo({ object, objects = [], mode = "move", snap
 			// (§6.1). The `cancel` handed over is teardown-only — the
 			// coordinator owns the close, and a close attempted from inside it
 			// is inert because the token is retired first (§5.2).
-			const token = stateRef.current.onDragStart?.({
+			// A held-object drag edits the motion, not the record: no scene transaction.
+			const heldDrag = Boolean(heldEdit?.editable && (kind === "rotate" || (!heldEdit.hinge && (kind === "move" || kind === "plane"))) && heldEdit.begin());
+			const token = heldDrag ? undefined : stateRef.current.onDragStart?.({
 				owner: "gizmo",
 				cancel: teardownDrag,
 			});
 			const corner = kind === "corner" ? dir : null;
-			dragRef.current = { ...drag, id: live.id, axis, plane, corner, start: { ...live }, token };
+			dragRef.current = { ...drag, id: live.id, axis, plane, corner, start: { ...live }, token, held: heldDrag };
 			// the grabbed handle turns yellow now and stays yellow after
 			// release, until the selection or the tool changes (§3.1)
 			setActiveHandle(handleKey({ axis, plane, corner }));
@@ -593,7 +499,7 @@ export default function ObjectGizmo({ object, objects = [], mode = "move", snap
 			// Only a real transaction gets the extra lifecycle edges: blur and
 			// Escape would otherwise change mid-drag behaviour for callers that
 			// pass no transaction props (the byte-for-byte fallback path).
-			if (token != null) {
+			if (token != null || heldDrag) {
 				window.addEventListener("blur", onBlur);
 				window.addEventListener("keydown", onKeyDown, true);
 			}
@@ -753,7 +659,7 @@ export default function ObjectGizmo({ object, objects = [], mode = "move", snap
 		const camera = camRef?.current;
 		if (!root || !camera || !object) return;
 		camera.getWorldPosition(tools.camPos);
-		tools.origin.set(object.x, gizmoHeight(object), object.z);
+		gizmoOrigin(object, held, tools.origin);
 		root.scale.setScalar(Math.max(0.35, tools.camPos.distanceTo(tools.origin) * SCREEN_SCALE));
 		if (mode !== "rotate") return;
 		// The rotate rings are view-dependent, so their orientation is frame
@@ -764,6 +670,14 @@ export default function ObjectGizmo({ object, objects = [], mode = "move", snap
 		camera.getWorldDirection(tools.eye);
 		const screen = screenRingRef.current;
 		if (screen) screen.quaternion.copy(camera.quaternion);
+		// Turned rings (a held object's own axes): the near/far split and the
+		// billboard are worked out in the gizmo's own frame.
+		const turn = gizmoTurn(held, mode);
+		if (turn) {
+			const unturn = new THREE.Quaternion(...turn).invert();
+			tools.eye.applyQuaternion(unturn);
+			screen?.quaternion.premultiply(unturn);
+		}
 		for (const { axis, u, v } of ringBases) {
 			const ring = ringGroupsRef.current[axis];
 			if (!ring) continue;
@@ -855,8 +769,9 @@ export default function ObjectGizmo({ object, objects = [], mode = "move", snap
 	const screenHovered = hoveredHandle === "screen";
 	const centreActive = activeHandle === "centre";
 	const centreHovered = hoveredHandle === "centre";
-	return (
-		<group ref={rootRef} position={[object.x, gizmoHeight(object), object.z]} renderOrder={999}>
+	return (<>
+		<HeldTrail trail={held?.trail ?? null} />
+		<group ref={rootRef} position={gizmoOrigin(object, held, new THREE.Vector3()).toArray()} quaternion={gizmoTurn(held, mode) ?? [0, 0, 0, 1]} renderOrder={999}>
 			{AXES.map(({ axis, dir, color }) => {
 				const quat = new THREE.Quaternion().setFromUnitVectors(new THREE.Vector3(0, 1, 0), dir);
 				// The handle under a drag — and, after release, the last one —
@@ -1033,5 +948,5 @@ export default function ObjectGizmo({ object, objects = [], mode = "move", snap
 				</>
 			)}
 		</group>
-	);
+	</>);
 }

package/src/object-glow.js

@@ -0,0 +1,139 @@
+/**
+ * Glow: a record that gives off light of its own, drawn in one pass.
+ *
+ * There is no post-processing anywhere (the viewport, the shot preview,
+ * capture_frame, contact sheets and the video export all render the scene with
+ * one gl.render), so a bloom pass would have to be bolted onto every path.
+ * Instead a glow is two single-pass parts, both on the default layer:
+ *   - an emissive colour on every material the record draws, which no stage
+ *     light can darken, and
+ *   - an additive, camera-facing halo sprite centred on the record, `halo` ×
+ *     the record's radius. It writes no depth, casts no shadow and is never
+ *     raycast, so it cannot occlude, shadow or be picked.
+ * Both scale with `gain` (the take's level, times a light's flicker).
+ * A glowing record is self-lit, so its meshes cast no shadow while it glows: a
+ * practical light placed inside a glowing bulb or flame lights the set instead
+ * of being shut in by the bulb's own faces (light-blockers.js).
+ *
+ * State is kept per group in a WeakMap, never in `userData` (React replaces a
+ * group's userData on every render). Removing the glow restores each
+ * material's own emissive and drops the halo.
+ */
+
+import * as THREE from "three";
+
+/** Halo brightness per unit of glow intensity. */
+const HALO_GAIN = 0.2;
+/** Radius used for a record with no size of its own (a light, an Empty), metres. */
+const POINT_RADIUS = 0.02;
+const noRaycast = () => {};
+const glowStates = new WeakMap();
+
+/** True while the group carries a glow that a later frame may have to remove. */
+export function hasGlow(group) {
+	return glowStates.has(group);
+}
+
+let haloMap = null;
+/** A white disc whose alpha is a bright core over a long soft tail. */
+function haloTexture() {
+	if (haloMap) return haloMap;
+	const size = 64;
+	const data = new Uint8Array(size * size * 4);
+	for (let y = 0; y < size; y += 1) {
+		for (let x = 0; x < size; x += 1) {
+			const r = Math.hypot(x + 0.5 - size / 2, y + 0.5 - size / 2) / (size / 2);
+			const tail = r >= 1 ? 0 : (1 - r) ** 1.6;
+			const alpha = Math.min(1, 0.7 * Math.exp(-((r / 0.25) ** 2)) + 0.5 * tail);
+			data.set([255, 255, 255, Math.round(alpha * 255)], (y * size + x) * 4);
+		}
+	}
+	haloMap = new THREE.DataTexture(data, size, size);
+	haloMap.magFilter = THREE.LinearFilter;
+	haloMap.minFilter = THREE.LinearFilter;
+	haloMap.needsUpdate = true;
+	return haloMap;
+}
+
+function makeHalo() {
+	const material = new THREE.SpriteMaterial({ map: haloTexture(), blending: THREE.AdditiveBlending, transparent: true, depthWrite: false, fog: false });
+	const halo = new THREE.Sprite(material);
+	halo.userData.glowHalo = true;
+	// Beauty render only: the ink prepass and the depth/normal passes draw with
+	// an override material, which would turn the soft halo into a solid quad.
+	halo.userData.beautyOnly = true;
+	halo.raycast = noRaycast;
+	halo.castShadow = false;
+	halo.receiveShadow = false;
+	halo.renderOrder = 2;
+	return halo;
+}
+
+/** Each mesh the record draws on the default layer, and each of its lit
+ * materials (editor markers and the halo itself are left alone). */
+function forEachGlowMesh(group, visitMesh, visitMaterial) {
+	group.traverse((node) => {
+		if (!node.isMesh || !node.layers.isEnabled(0)) return;
+		visitMesh(node);
+		for (const material of Array.isArray(node.material) ? node.material : [node.material]) {
+			if (material?.emissive?.isColor) visitMaterial(material);
+		}
+	});
+}
+
+function clearGlow(group, state) {
+	for (const [material, base] of state.bases) {
+		material.emissive.copy(base.emissive);
+		material.emissiveIntensity = base.intensity;
+	}
+	for (const mesh of state.shadowless) mesh.castShadow = true;
+	state.halo.removeFromParent();
+	state.halo.material.dispose();
+	glowStates.delete(group);
+}
+
+/** The record's centre (local) and its radius (world): half its largest
+ * extent, so a sphere's radius is exact; a record with no size (a light, an
+ * Empty) counts as POINT_RADIUS. Size comes from the record, the same numbers
+ * the selection cage and the plan use. */
+function recordSphere(object, scale) {
+	const width = (object.footprint?.width ?? 0) * Math.abs(scale.x);
+	const height = (object.height ?? 0) * Math.abs(scale.y);
+	const depth = (object.footprint?.depth ?? 0) * Math.abs(scale.z);
+	const radius = Math.max(width, height, depth) / 2;
+	return { centreY: (object.height ?? 0) / 2, radius: radius > 0 ? radius : POINT_RADIUS };
+}
+
+/** Apply, update or remove the record's glow for this frame. */
+export function placeObjectGlow(group, object, gain) {
+	const glow = object.glow;
+	let state = glowStates.get(group);
+	if (!glow) {
+		if (state) clearGlow(group, state);
+		return;
+	}
+	if (!state) {
+		state = { halo: makeHalo(), bases: new Map(), shadowless: new Set() };
+		glowStates.set(group, state);
+	}
+	if (state.halo.parent !== group) group.add(state.halo);
+	const strength = glow.intensity * gain;
+	forEachGlowMesh(group, (mesh) => {
+		// a mesh rebuilt while glowing (a new kind, a loaded file) casts again until this pass
+		if (!mesh.castShadow) return;
+		mesh.castShadow = false;
+		state.shadowless.add(mesh);
+	}, (material) => {
+		if (!state.bases.has(material)) state.bases.set(material, { emissive: material.emissive.clone(), intensity: material.emissiveIntensity });
+		material.emissive.set(glow.color);
+		material.emissiveIntensity = strength;
+	});
+	const { centreY, radius } = recordSphere(object, group.scale);
+	const size = 2 * radius * glow.halo * gain;
+	const halo = state.halo;
+	halo.visible = size > 0 && strength > 0;
+	halo.position.set(0, centreY, 0);
+	// The sprite inherits the record's scale; divide it out so the halo stays round.
+	halo.scale.set(size / (Math.abs(group.scale.x) || 1), size / (Math.abs(group.scale.y) || 1), 1);
+	halo.material.color.set(glow.color).multiplyScalar(HALO_GAIN * strength);
+}

package/src/object-hidden.js

@@ -0,0 +1,33 @@
+// Effective visibility of a scene record through its parents and its carrying
+// character. Pure and dependency-free, so the renderers, the agent commands and
+// the effects can share it; scene-objects.js re-exports it.
+
+/** True when this record, a parent above it, or a character carrying any of
+ *  those records is hidden. A cycle in parent links ends the walk. When the
+ *  id is in `objects`, that stored record is what the walk reads, so a display
+ *  copy cannot disagree with the authored flag. Nothing in the lists is changed. */
+export function isEffectivelyHidden(entity, objects = [], characters = []) {
+	if (!entity || typeof entity !== "object") return false;
+	const byId = new Map();
+	for (const object of objects) {
+		if (object && typeof object.id === "string") byId.set(object.id, object);
+	}
+	const characterHidden = (id) => characters.some((item) => item && typeof item === "object" && item.id === id && item.hidden === true);
+	const seen = new Set();
+	let current = entity;
+	while (current && typeof current === "object") {
+		const id = typeof current.id === "string" ? current.id : null;
+		if (id) {
+			if (seen.has(id)) break;
+			seen.add(id);
+			if (byId.has(id)) current = byId.get(id);
+		}
+		if (current.hidden === true) return true;
+		const characterId = current.attach && typeof current.attach.characterId === "string" ? current.attach.characterId : null;
+		if (characterId && characterHidden(characterId)) return true;
+		const parentId = typeof current.parent === "string" ? current.parent : null;
+		if (!parentId) break;
+		current = byId.get(parentId) ?? null;
+	}
+	return false;
+}

package/src/object-look.js

@@ -0,0 +1,196 @@
+/**
+ * Practical lights and glow: the record fields, their defaults and clamps, and
+ * the per-frame numbers the renderer reads (flicker, take level, shadow cap).
+ *
+ * Pure on purpose: no three.js and no React, so the agent sidecar, the record
+ * normalizer and Node tests all read the same rules.
+ *
+ * A light is a record with renderer "light". It is created from one of two
+ * catalogue kinds, `point-light` and `spot-light`, which differ only in the
+ * `light.type` they start with. Like an Empty it has no size: no collision, no
+ * surface, no footprint on the plan.
+ *
+ * `glow` can sit on any record. It makes the record's materials emissive and
+ * adds a camera-facing additive halo, so an ember or a bulb reads as a light
+ * source in the shot render without any post-processing pass.
+ */
+
+import { normalizeObjectColor } from "./object-colors.js";
+
+export const LIGHT_KIND = "light";
+
+/** three.js intensity per authored unit. Authored values are candela-like
+ * (decay 2: lighter flame 0.3-0.6, candle 0.3, desk lamp 5, street lamp 40).
+ * The scale is tuned against the default stage key (directional, 1.12) so a
+ * street lamp's pool at 4 m reads about as bright as half the key, and a
+ * lighter 25 cm from a face lifts it to roughly the key. */
+export const LIGHT_INTENSITY_SCALE = 0.35;
+
+/** At most this many practical lights render shadows (each point shadow is six
+ * extra depth passes). The rest still light the scene and are reported. */
+export const PRACTICAL_SHADOW_CAP = 2;
+
+const LIGHT_DEFAULTS = Object.freeze({
+	point: Object.freeze({ type: "point", color: "#ffc787", intensity: 5, range: 0, angle: 30, softness: 0.3, shadow: false, flicker: 0, aim: null }),
+	spot: Object.freeze({ type: "spot", color: "#ffe0b2", intensity: 40, range: 0, angle: 30, softness: 0.3, shadow: true, flicker: 0, aim: null }),
+});
+const GLOW_DEFAULTS = Object.freeze({ color: "#ff9a3c", intensity: 4, halo: 1.5 });
+
+const LIGHT_SIZE = { footprint: { width: 0, depth: 0 }, height: 0 };
+/** The record entry every light normalizes through. */
+const LIGHT_ENTRY = Object.freeze({ kind: LIGHT_KIND, label: "Light", group: "Lights", ...LIGHT_SIZE, color: "#ffd38a" });
+/** The two creatable kinds: the add menu and the agent catalogue list these.
+ * `placeY` is where a fresh one hangs, so it lights something on arrival. */
+export const LIGHT_MENU_ENTRIES = Object.freeze([
+	Object.freeze({ kind: "point-light", renderer: LIGHT_KIND, label: "Point light", group: "Lights", ...LIGHT_SIZE, color: "#ffc787", placeY: 1.5, light: LIGHT_DEFAULTS.point }),
+	Object.freeze({ kind: "spot-light", renderer: LIGHT_KIND, label: "Spot light", group: "Lights", ...LIGHT_SIZE, color: "#ffe0b2", placeY: 3, light: LIGHT_DEFAULTS.spot }),
+]);
+
+/** The library entry for a light kind or the light renderer, or null. */
+export function lightLibraryEntry(kind) {
+	if (kind === LIGHT_KIND) return LIGHT_ENTRY;
+	return LIGHT_MENU_ENTRIES.find((entry) => entry.kind === kind) ?? null;
+}
+
+const clamp = (value, min, max) => Math.min(max, Math.max(min, value));
+const finite = (value, fallback, min, max) => {
+	const n = typeof value === "number" || typeof value === "string" ? Number(value) : NaN;
+	return Number.isFinite(n) ? clamp(n, min, max) : fallback;
+};
+const hex = (value, fallback) => normalizeObjectColor(value) ?? fallback;
+const point = (value) => {
+	if (!value || typeof value !== "object") return null;
+	const out = { x: Number(value.x), y: Number(value.y), z: Number(value.z) };
+	return Object.values(out).every(Number.isFinite) ? out : null;
+};
+
+/** A stored or requested light repaired into the full record. `type` falls back
+ * to `typeHint` (the kind it was created as), then to "point". */
+export function normalizeObjectLight(value, typeHint = "point") {
+	const source = value && typeof value === "object" && !Array.isArray(value) ? value : {};
+	const type = source.type === "spot" || source.type === "point" ? source.type : typeHint === "spot" ? "spot" : "point";
+	const base = LIGHT_DEFAULTS[type];
+	return {
+		type,
+		color: hex(source.color, base.color),
+		intensity: finite(source.intensity, base.intensity, 0, 1000),
+		range: finite(source.range, base.range, 0, 100),
+		angle: finite(source.angle, base.angle, 1, 89),
+		softness: finite(source.softness, base.softness, 0, 1),
+		shadow: typeof source.shadow === "boolean" ? source.shadow : base.shadow,
+		flicker: finite(source.flicker, base.flicker, 0, 1),
+		aim: point(source.aim),
+	};
+}
+
+/** A glow repaired into `{ color, intensity, halo }`, or null for none. */
+export function normalizeObjectGlow(value) {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+	return {
+		color: hex(value.color, GLOW_DEFAULTS.color),
+		intensity: finite(value.intensity, GLOW_DEFAULTS.intensity, 0, 20),
+		halo: finite(value.halo, GLOW_DEFAULTS.halo, 0, 4),
+	};
+}
+
+/** The light/glow fields a normalized record carries. A light renderer always
+ * has a light; any record keeps a glow only when it has one, so records written
+ * before glow existed come back byte-for-byte unchanged. */
+export function objectLookFields(record, entry) {
+	const out = {};
+	if ((entry.renderer ?? entry.kind) === LIGHT_KIND) out.light = normalizeObjectLight(record.light, record.light?.type ?? entry.light?.type);
+	const glow = normalizeObjectGlow(record.glow);
+	if (glow) out.glow = glow;
+	// A kit part a take switches on (a muzzle flash and its light) stays hidden without one (object-travel.js trackShown).
+	if (record.showOnlyInTake === true) out.showOnlyInTake = true;
+	return out;
+}
+
+/** The light/glow part of an object.update patch: each field merges over the
+ * record's own and is repaired; `glow: null` removes the glow. Only changes are
+ * returned. A light on a record that is not a light is ignored. */
+export function objectLookPatch(object, patch) {
+	const update = {};
+	if (patch?.light && typeof patch.light === "object" && object.renderer === LIGHT_KIND) {
+		const next = normalizeObjectLight({ ...object.light, ...patch.light }, object.light?.type);
+		if (JSON.stringify(next) !== JSON.stringify(object.light)) update.light = next;
+	}
+	if (patch?.glow !== undefined) {
+		const next = patch.glow === null ? null : normalizeObjectGlow({ ...(object.glow ?? {}), ...patch.glow });
+		if (JSON.stringify(next) !== JSON.stringify(object.glow ?? null)) update.glow = next;
+	}
+	return update;
+}
+
+/** 32-bit FNV-1a of the record id: the flicker's seed. */
+function seedOf(id) {
+	let hash = 0x811c9dc5;
+	for (const char of String(id)) {
+		hash ^= char.codePointAt(0);
+		hash = Math.imul(hash, 0x01000193) >>> 0;
+	}
+	return hash;
+}
+
+/** Lattice value in [-1, 1] for an integer cell of a seeded stream. */
+function lattice(seed, cell) {
+	let h = Math.imul(seed ^ Math.imul(cell, 0x27d4eb2d), 0x165667b1) >>> 0;
+	h = Math.imul(h ^ (h >>> 15), 0x85ebca6b) >>> 0;
+	h = Math.imul(h ^ (h >>> 13), 0xc2b2ae35) >>> 0;
+	return ((h ^ (h >>> 16)) >>> 0) / 0x7fffffff - 1;
+}
+
+/** Smooth value noise in [-1, 1] at time `t` (cells of 1). */
+function noise(seed, t) {
+	const cell = Math.floor(t);
+	const f = t - cell;
+	const s = f * f * (3 - 2 * f);
+	return lattice(seed, cell) * (1 - s) + lattice(seed, cell + 1) * s;
+}
+
+/**
+ * The flicker multiplier of a light at `frame`: a pure function of the id, the
+ * frame and the amount, so scrubbing, playback and export see the same value.
+ * 0 is steady (exactly 1); 0.3 wavers like a candle; 0.6 jumps like a lighter.
+ */
+export function flickerAt(id, frame, amount, fps = 24) {
+	const depth = finite(amount, 0, 0, 1);
+	if (!(depth > 0)) return 1;
+	const seed = seedOf(id);
+	const t = (Number(frame) || 0) / (fps > 0 ? fps : 24);
+	const n = 0.55 * noise(seed, t * 7) + 0.3 * noise(seed ^ 0x9e3779b9, t * 15) + 0.15 * noise(seed ^ 0x7f4a7c15, t * 31);
+	return Math.max(0, 1 + depth * 0.65 * n);
+}
+
+/**
+ * Which shown lights that ask for a shadow get one: the first
+ * PRACTICAL_SHADOW_CAP in record order. `capped` lists the rest by id.
+ * `isHidden(record)` drops records the stage does not draw.
+ */
+export function practicalShadows(objects, isHidden = (object) => object?.hidden === true) {
+	const asking = (objects ?? []).filter((object) => object?.renderer === LIGHT_KIND && object.light?.shadow === true && !isHidden(object));
+	return { casting: asking.slice(0, PRACTICAL_SHADOW_CAP).map((object) => object.id), capped: asking.slice(PRACTICAL_SHADOW_CAP).map((object) => object.id) };
+}
+
+/** The records as the stage draws them: lights past the shadow cap render with
+ * `shadow: false` and `shadowCapped: true`. The same array when none is capped. */
+export function capPracticalShadows(objects) {
+	const capped = new Set(practicalShadows(objects).capped);
+	if (!capped.size) return objects;
+	return objects.map((object) => (capped.has(object.id) ? { ...object, light: { ...object.light, shadow: false }, shadowCapped: true } : object));
+}
+
+/** Receipt warnings, one per light that asked for a shadow but is past the cap,
+ * limited to `ids` when given (the records an edit touched). */
+function shadowCapWarnings(objects, ids = null, isHidden = undefined) {
+	const { casting, capped } = practicalShadows(objects, isHidden);
+	return capped.filter((id) => !ids || ids.includes(id)).slice(0, 4).map((id) => ({ code: "SHADOW_CAP", id,
+		message: `Renders without a shadow: only ${PRACTICAL_SHADOW_CAP} lights cast shadows (${casting.join(", ")}).`.slice(0, 120) }));
+}
+
+/** A command result with the shadow-cap warnings for the records it touched
+ * appended, so a receipt says when a requested shadow is not drawn. */
+export function withShadowCapWarnings(result, objects) {
+	const warnings = shadowCapWarnings(objects, result?.affectedIds ?? []);
+	return warnings.length ? { ...result, warnings: [...(result.warnings ?? []), ...warnings] } : result;
+}

package/src/object-size.js

@@ -0,0 +1,10 @@
+// A leaf module: the motion compiler's scene reader (motion3/scene.js) needs an object's size without
+// scene-objects.js, which imports three; the agent sidecar reaches motion3 through motion.describe and must not.
+/** The object's world size along each axis, for the gizmo and the plan board. */
+export function objectSize(object) {
+	return {
+		width: (object.footprint?.width ?? 1) * (object.scaleX ?? 1),
+		height: (object.height ?? 1) * (object.scaleY ?? 1),
+		depth: (object.footprint?.depth ?? 1) * (object.scaleZ ?? 1),
+	};
+}