cozyclay 2.1.1 → 3.0.0

package/src/object-gizmo-parts.js

@@ -0,0 +1,115 @@
+import * as THREE from "three";
+import { objectSize } from "./scene-objects.js";
+
+// The ObjectGizmo's fixed parts: handle layout, sizes, colours and the two
+// placement rules (where the gizmo stands, and which way its rings face).
+export 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 */
+export 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. */
+export 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" },
+];
+export const PLANE_OFFSET = 0.26; // where the square sits along each of its two axes
+export const PLANE_SIZE = 0.2;
+export const ARROW_LEN = 0.62;
+export const SHAFT_R = 0.016;
+export const TIP_R = 0.05;
+export const TIP_LEN = 0.14;
+export 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.
+ */
+export 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.) */
+export 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). */
+export const ACTIVE_COLOR = "#ffd23d";
+export const RING_TUBE = 0.022;
+export const BOX_SIZE = 0.09; // scale-mode axis knobs
+export 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. */
+export const PICK_SHAFT_R = 0.09;
+export const PICK_TUBE_R = 0.07;
+export 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 */
+export 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 */
+export 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.
+ */
+export 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 },
+];
+export const CORNER_BOX = 0.085;
+export 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.
+export const GROUND = new THREE.Plane(new THREE.Vector3(0, 1, 0), 0);
+/** Where the gizmo stands: on the pose a take draws the object at (`held.pose`, held-object-edit.jsx), else at the authored centre. */
+export function gizmoOrigin(object, held, out) {
+	return held?.pose ? out.fromArray(held.pose.centre) : out.set(object.x, gizmoHeight(object), object.z);
+}
+
+/** The rotation the handles take: the drawn object's own axes while a held-object drag edits it in rotate mode, else none (world axes). */
+export function gizmoTurn(held, mode) {
+	return mode === "rotate" && held?.editable ? held.pose.quat : null;
+}

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