cozyclay 2.1.0 → 3.0.0

package/src/imported-mesh.jsx

@@ -0,0 +1,103 @@
+/**
+ * An imported model: the cached GLB cloned per instance, fitted to the
+ * record's stored height and stood on y = 0. A grey box stands in while the
+ * file loads (or if it is gone).
+ */
+import { useEffect, useMemo, useState } from "react";
+import * as THREE from "three";
+import { subscribeToMeshScene } from "./scene-mesh-cache.js";
+import { cloneMeshGraph } from "./mesh-graph-clone.js";
+
+/** The placeholder tint for a model that has not arrived: blockout grey. */
+const MISSING_MESH = "#c2c6c8";
+
+/** The parsed GLB for an `assetId`, or null while it loads (or forever, if
+ * the blob is gone). The cached graph is the FILE's own pivot and materials;
+ * each instance clones, then fits to the stored height. */
+function useMeshScene(assetId) {
+	const [scene, setScene] = useState(null);
+	useEffect(() => {
+		setScene(null);
+		if (!assetId) return undefined;
+		return subscribeToMeshScene(assetId, setScene);
+	}, [assetId]);
+	return scene;
+}
+
+function disposeOwnedMaterials(root) {
+	if (!root) return;
+	root.traverse((node) => {
+		if (!node.isMesh || !(node.userData?.clayOwned || node.userData?.instanceOwned)) return;
+		const materials = Array.isArray(node.material) ? node.material : [node.material];
+		for (const material of materials) material?.dispose?.();
+	});
+}
+
+/**
+ * Clone the cached graph, scale so its bbox height equals the stored
+ * `object.height`, and sit the underside on y = 0. The import heuristic
+ * already wrote that height — this pass must not re-guess it.
+ *
+ * Skinned graphs go through `cloneMeshGraph` so a Mixamo-as-statue keeps
+ * its bind pose. Clay replaces materials on THIS clone only, so a second
+ * instance of the same file can keep the textures from the disk. Every clone
+ * owns its materials, so auto-color tints and opacity fades never leak.
+ */
+function instantiateMesh(source, object) {
+	const root = cloneMeshGraph(source);
+	root.updateMatrixWorld(true);
+	const box = new THREE.Box3().setFromObject(root);
+	const size = box.getSize(new THREE.Vector3());
+	const targetHeight = Number(object.height);
+	if (Number.isFinite(targetHeight) && targetHeight > 0 && size.y > 1e-8) {
+		root.scale.multiplyScalar(targetHeight / size.y);
+		root.updateMatrixWorld(true);
+		box.setFromObject(root);
+	}
+	if (Number.isFinite(box.min.y)) root.position.y -= box.min.y;
+	const clay = object.clay === true;
+	const clayColor = object.autoColor ?? object.color ?? "#c4b8a8";
+	root.traverse((node) => {
+		if (node.isLight || node.isCamera) {
+			node.visible = false;
+			return;
+		}
+		if (!node.isMesh) return;
+		node.castShadow = true;
+		node.receiveShadow = true;
+		if (clay) {
+			const make = () => new THREE.MeshStandardMaterial({ color: clayColor, roughness: 0.9, metalness: 0 });
+			for (const material of Array.isArray(node.material) ? node.material : [node.material]) material?.dispose?.();
+			node.material = Array.isArray(node.material) ? node.material.map(() => make()) : make();
+			node.userData.clayOwned = true;
+			return;
+		}
+		if (!object.autoColor || !node.material) return;
+		// cloneMeshGraph already gave this instance its own materials.
+		for (const material of Array.isArray(node.material) ? node.material : [node.material]) {
+			if (material.color) material.color.set(object.autoColor);
+		}
+	});
+	return root;
+}
+
+export function ImportedMesh({ object }) {
+	const source = useMeshScene(object.assetId);
+	const root = useMemo(
+		() => (source ? instantiateMesh(source, object) : null),
+		[source, object.height, object.clay, object.autoColor, object.color],
+	);
+	useEffect(() => () => disposeOwnedMaterials(root), [root]);
+	if (!root) {
+		const width = object.footprint?.width ?? 1;
+		const depth = object.footprint?.depth ?? 1;
+		const height = object.height ?? 1;
+		return (
+			<mesh position={[0, height / 2, 0]} castShadow receiveShadow>
+				<boxGeometry args={[width, height, depth]} />
+				<meshStandardMaterial color={MISSING_MESH} roughness={0.92} metalness={0} />
+			</mesh>
+		);
+	}
+	return <primitive object={root} />;
+}

package/src/kits/held.js

@@ -0,0 +1,84 @@
+// Hand-held kits with no skill of their own: a baseball bat, a ball, a sword and a pistol. Each
+// answers the prop its root rides (props) besides the spec.objects carry entry, so the agent
+// pastes both. Positions are in the kit root's frame (metres, each part record's base pivot).
+// A fist holds a bar across the palm: the bar runs along the palm's l axis (toward the thumb side)
+// and sits on the palm side of the finger middles, which is -n for the right hand.
+
+const RIGHT_FINGERS = ["RightHandIndex2", "RightHandMiddle2"];
+/** The bar's centre in a right fist, from the finger middles (d, l, n), m. */
+const FIST = [0, 0, -0.015];
+const along = (k, from = FIST) => [from[0], +(from[1] + k).toFixed(4), from[2]];
+
+// A baseball bat along +Y from the knob (y 0) to the end cap (y 0.84): radius by height (m), a
+// smooth taper from the 27 mm handle to the 67 mm barrel drawn as short frustums.
+const BAT_PROFILE = [[0.012, 0.0122], [0.3, 0.0135], [0.36, 0.016], [0.41, 0.0195], [0.46, 0.024], [0.51, 0.0285], [0.56, 0.0318], [0.61, 0.0332], [0.825, 0.0335]];
+const WOOD = "#c99b5e";
+const batParts = () => [
+	{ id: "knob", shape: "blob", size: [0.052, 0.018, 0.052], position: [0, 0.009, 0], roundness: 0, color: "#a8784a" },
+	...BAT_PROFILE.slice(1).map(([y, r], i) => {
+		const [y0, r0] = BAT_PROFILE[i];
+		return { id: `seg-${i}`, shape: "cylinder", size: [2 * r, +(y - y0).toFixed(4), 2 * r], position: [0, +((y + y0) / 2).toFixed(4), 0], taper: +(-(1 - r0 / r)).toFixed(4), color: WOOD };
+	}),
+	{ id: "cap", shape: "blob", size: [0.067, 0.03, 0.067], position: [0, 0.825, 0], roundness: 0, color: WOOD },
+];
+// The batting grip of the baseball swing fixture (test/motion3/fixtures/bat-swing.mjs): the bat
+// runs along u in the palm frame, the right hand 14 cm above the knob, the left hand's point `low`.
+const BAT_AXIS = [0, 0.5, 0.866], onBat = k => BAT_AXIS.map(c => +(c * k).toFixed(4));
+
+export const bat = {
+	label: "Baseball bat", prop: "batGrip",
+	description: "0.84 m wooden baseball bat (knob, handle, taper, barrel, end cap) held in the right hand 14 cm above the knob, with a motion-trail effect on the barrel",
+	props: { batGrip: { hand: "r", origin: RIGHT_FINGERS, points: { low: onBat(-0.085), knob: onBat(-0.14), tip: onBat(0.7) } } },
+	carry: { prop: "batGrip", at: onBat(-0.14), along: BAT_AXIS },
+	parts: [
+		{ role: "body", kind: "sculpt", at: [0, 0, 0], recipe: { version: 1, parts: batParts() } },
+		{ role: "trail", kind: "effect", at: [0, 0.69, 0], effect: { preset: "trail", width: 0.3 } },
+	],
+};
+
+export const ball = {
+	label: "Baseball", prop: "ballGrip",
+	description: "7.4 cm baseball held in the right fingers",
+	props: { ballGrip: { hand: "r", origin: RIGHT_FINGERS, points: { centre: [0, 0, -0.035] } } },
+	carry: { prop: "ballGrip", at: [0, 0, -0.035], along: [0, 1, 0] },
+	parts: [{ role: "body", kind: "sphere", at: [0, -0.037, 0], scale: [0.074, 0.074, 0.074], color: "#f1ede3" }],
+};
+
+const STEEL = "#c9ced3", BRASS = "#a8874f";
+export const sword = {
+	label: "Sword", prop: "swordGrip",
+	description: "1 m one-handed sword (pommel, grip, guard, blade) held in the right fist at the grip, with a motion-trail effect on the blade",
+	props: { swordGrip: { hand: "r", origin: RIGHT_FINGERS, points: { tip: along(0.87) } } },
+	carry: { prop: "swordGrip", at: FIST, along: [0, 1, 0] },
+	parts: [
+		{ role: "body", kind: "sculpt", at: [0, -0.125, 0], recipe: { version: 1, parts: [
+			{ id: "pommel", shape: "blob", size: [0.042, 0.035, 0.042], position: [0, 0.0175, 0], roundness: 0.2, color: BRASS },
+			{ id: "grip", shape: "cylinder", size: [0.028, 0.17, 0.024], position: [0, 0.12, 0], color: "#4a3326" },
+			{ id: "guard", shape: "box", size: [0.2, 0.024, 0.032], position: [0, 0.217, 0], roundness: 0.3, color: BRASS },
+			{ id: "blade", shape: "box", size: [0.044, 0.68, 0.0065], position: [0, 0.569, 0], roundness: 0.1, color: STEEL },
+			{ id: "tip", shape: "cylinder", size: [0.044, 0.09, 0.0065], position: [0, 0.954, 0], taper: 1, color: STEEL }] } },
+		{ role: "trail", kind: "effect", at: [0, 0.5, 0], effect: { preset: "trail", width: 0.6 } },
+	],
+};
+
+// The barrel points along the palm's d axis (forward out of the fist), the grip runs along l.
+// The flash and its light are showOnlyInTake: hidden in a static scene, shown only on frames a take's muzzle_vis is on.
+const MUZZLE = [0.155, 0.08, 0];
+export const pistol = {
+	label: "Pistol", prop: "gunGrip",
+	description: "19 cm pistol held in the right fist, with a muzzle-flash glow and light at the muzzle that show only on frames its muzzle_vis channel is above 0.5",
+	props: { gunGrip: { hand: "r", origin: ["RightHand", "RightHandMiddle1"], points: { muzzle: MUZZLE } } },
+	carry: { prop: "gunGrip", at: [0, 0, 0], along: [0, 1, 0] },
+	parts: [
+		{ role: "body", kind: "sculpt", at: [0, -0.065, 0], recipe: { version: 1, parts: [
+			{ id: "grip", shape: "box", size: [0.03, 0.11, 0.028], position: [-0.008, 0.055, 0], rotation: [0, 0, 12], roundness: 0.3, color: "#2f3236" },
+			{ id: "frame", shape: "box", size: [0.17, 0.028, 0.026], position: [0.055, 0.118, 0], roundness: 0.2, color: "#2f3236" },
+			{ id: "slide", shape: "box", size: [0.19, 0.032, 0.028], position: [0.06, 0.145, 0], roundness: 0.2, color: "#3d4247" },
+			{ id: "guard", shape: "torus", size: [0.045, 0.035, 0.007], position: [0.035, 0.095, 0], color: "#2f3236" },
+			{ id: "trigger", shape: "box", size: [0.006, 0.018, 0.006], position: [0.03, 0.095, 0], roundness: 0.3, color: "#1f2124" }] } },
+		{ role: "flash", kind: "sphere", at: [MUZZLE[0] + 0.025, MUZZLE[1] - 0.015, 0], scale: [0.05, 0.03, 0.03], color: "#ffe08a",
+			glow: { color: "#ffc04a", intensity: 8, halo: 2.5 }, switch: { visible: "muzzle_vis" }, showOnlyInTake: true },
+		{ role: "light", kind: "point-light", at: [MUZZLE[0] + 0.04, MUZZLE[1], 0], light: { type: "point", color: "#ffd27a", intensity: 4, range: 6, flicker: 0, shadow: false },
+			switch: { visible: "muzzle_vis" }, showOnlyInTake: true },
+	],
+};

package/src/kits/index.js

@@ -0,0 +1,70 @@
+// Kits (docs/motion-api-v3.1.md C15): ready-made, correctly scaled props built as a group, an
+// Empty root plus parts. The root is the grip: carried with the entry `bind` names (at/along pin
+// it to the prop origin), it puts every part where the hand holds it. Parts are ordinary records
+// (sculpts, primitives, effects, lights) parented to the root; a part that glows, burns or lights
+// up carries the switch entry a take uses to show it (`switch`). The exhale kit rides no hand: its
+// root's entry is a follow (C16).
+//   buildKit(kit, existing, { name?, position? }) -> { records, rootId, parts: { role: id }, bind, props?, use? } | { error }
+import { Euler, Matrix4, Quaternion, Vector3 } from "three";
+import { createSceneObject, createSculptObject, normalizeSceneObject, EMPTY_KIND } from "../scene-objects.js";
+import { cigarette, lighter, exhale } from "./smoking.js";
+import { bat, ball, sword, pistol } from "./held.js";
+
+const KITS = { cigarette, lighter, exhale, bat, ball, sword, pistol };
+export const KIT_NAMES = Object.keys(KITS);
+const DEG = Math.PI / 180;
+
+/** inspect_studio { scope: "catalogue" } kits: name, roles, the prop the root rides (or the point it follows) and one line. */
+export const KIT_CATALOGUE = KIT_NAMES.map(kit => ({ kit, parts: KITS[kit].parts.map(p => p.role), ...(KITS[kit].prop ? { prop: KITS[kit].prop } : { follow: KITS[kit].carry.follow }),
+	description: KITS[kit].description }));
+
+const uniqueName = (base, existing) => {
+	const names = new Set(existing.map(o => o.name));
+	let name = base;
+	for (let n = 2; names.has(name); n += 1) name = `${base} ${n}`;
+	return name;
+};
+
+/** A fresh record of the part's kind (null when this build has no such kind). */
+function freshPart(part, existing, name) {
+	if (part.kind === "sculpt") return createSculptObject({ recipe: part.recipe, name }, existing).object ?? null;
+	return createSceneObject(part.kind, existing);
+}
+
+const scratch = { pos: new Vector3(), quat: new Quaternion(), scale: new Vector3(), euler: new Euler() };
+
+/** The world pose of a root-frame part as record fields: position, XYZ Euler degrees, scale. */
+function placed(rootMatrix, part) {
+	const local = new Matrix4().compose(new Vector3(...part.at), new Quaternion().setFromEuler(new Euler(...(part.rot ?? [0, 0, 0]).map(v => v * DEG), "XYZ")), new Vector3(1, 1, 1));
+	new Matrix4().multiplyMatrices(rootMatrix, local).decompose(scratch.pos, scratch.quat, scratch.scale);
+	scratch.euler.setFromQuaternion(scratch.quat, "XYZ");
+	const round = v => Math.round(v * 1e5) / 1e5, [sx, sy, sz] = part.scale ?? [1, 1, 1];
+	return { x: round(scratch.pos.x), y: round(scratch.pos.y), z: round(scratch.pos.z), rotX: round(scratch.euler.x / DEG), rot: round(scratch.euler.y / DEG), rotZ: round(scratch.euler.z / DEG),
+		scaleX: sx, scaleY: sy, scaleZ: sz };
+}
+
+/**
+ * The records of kit `kit` (the root first), placed at `position` ({ x, y, z, rot }: the root,
+ * world m and yaw degrees; y is lifted so no part's base is under the floor), with ids and names
+ * unique against `existing`.
+ */
+export function buildKit(kit, existing = [], { name, position = {} } = {}) {
+	const def = KITS[kit];
+	if (!def) return { error: `kit "${kit}" is not a kit (kits: ${KIT_NAMES.join(", ")})` };
+	const yaw = Number(position.rot) || 0, lift = Math.max(0, ...def.parts.map(p => -p.at[1]));
+	const rootName = uniqueName(typeof name === "string" && name.trim() ? name.trim() : def.label, existing);
+	const root = normalizeSceneObject({ ...createSceneObject(EMPTY_KIND, existing, { x: position.x, z: position.z, rot: yaw }), name: rootName, y: Math.max(lift, Number(position.y) || 0) });
+	const rootMatrix = new Matrix4().compose(new Vector3(root.x, root.y, root.z), new Quaternion().setFromEuler(new Euler(0, yaw * DEG, 0, "XYZ")), new Vector3(1, 1, 1));
+	const records = [root], parts = {}, bind = { [root.id]: def.carry }, skipped = [];
+	for (const part of def.parts) {
+		const all = [...existing, ...records], partName = uniqueName(`${rootName} ${part.role}`, all), fresh = freshPart(part, all, partName);
+		const record = fresh && normalizeSceneObject({ ...fresh, ...placed(rootMatrix, part), name: partName, parent: root.id,
+			...(part.color ? { color: part.color } : {}), ...(part.glow ? { glow: part.glow } : {}), ...(part.effect ? { effect: part.effect } : {}), ...(part.light ? { light: part.light } : {}),
+			...(part.showOnlyInTake ? { showOnlyInTake: true } : {}) });
+		if (!record) { skipped.push(part.role); continue; }
+		records.push(record);
+		parts[part.role] = record.id;
+		if (part.switch) bind[record.id] = part.switch;
+	}
+	return { records, rootId: root.id, parts, bind, ...(def.props ? { props: def.props } : {}), ...(def.skill ? { skill: def.skill } : {}), ...(skipped.length ? { skipped } : {}) };
+}

package/src/kits/smoking.js

@@ -0,0 +1,57 @@
+// The smoking kits: a cigarette and a lighter sized and gripped like the smokeCigarette props, so
+// the carried kit sits exactly in the fingers (src/motion3/skills/smoke.js props cig, lighter).
+// Part positions are in the kit root's frame (metres), the base pivot of each part record; the
+// root rides the prop origin with at [0, 0, 0] and the `along` below (docs/motion-api-v3.1.md C15).
+//   cigarette: root between RightHandIndex2 and RightHandMiddle2; +Y runs along the palm normal
+//              from the filter (y -0.026, prop point filter) to the tip (y 0.058, prop point tip):
+//              8.4 cm x 7.8 mm.
+//   lighter:   root between LeftHand and LeftHandMiddle1; +Y toward the thumb side; the flame sits
+//              on the hood at the prop point flame [0.01, 0.036, 0] (d, l, n).
+//   exhale:    no hand: the root follows the mouth (C16), its +Y along the face, so the puff part
+//              needs no placing; smokeCigarette args.kit.exhale shows it while the exhale channel is on.
+// The lit parts (ember, flame, their lights, the tip smoke, the puff) are showOnlyInTake: a static
+// scene draws none of them; a take that binds them (args.kit) shows them on its channels' frames.
+
+const PAPER = "#f3efe6", FILTER = "#d48a4c", ASH = "#4a3a33";
+const D = 0.0078, FILTER_LEN = 0.022, LEN = 0.084, TIP = 0.058;
+
+export const cigarette = {
+	label: "Cigarette", prop: "cig", skill: "smokeCigarette",
+	description: "8.4 cm cigarette held between the right index and middle fingers (smokeCigarette prop cig): paper and filter, a glowing ember with its faint light, and tip smoke (these three show only while a take drives them: smokeCigarette args.kit)",
+	carry: { prop: "cig", at: [0, 0, 0], along: [0, 0, 1], visible: "cig_vis" },
+	parts: [
+		{ role: "body", kind: "sculpt", at: [0, TIP - LEN, 0], recipe: { version: 1, parts: [
+			{ id: "filter", shape: "cylinder", size: [D, FILTER_LEN, D], position: [0, FILTER_LEN / 2, 0], color: FILTER },
+			{ id: "paper", shape: "cylinder", size: [D, LEN - FILTER_LEN - 0.004, D], position: [0, (LEN + FILTER_LEN - 0.004) / 2, 0], color: PAPER }] } },
+		// the burning end: a 1 cm ash sphere at the tip that glows (its level follows the drag)
+		{ role: "ember", kind: "sphere", at: [0, TIP - 0.009, 0], scale: [0.01, 0.01, 0.01], color: ASH,
+			glow: { color: "#ff5a1e", intensity: 5, halo: 3.5 }, switch: { visible: "ember_vis", level: "ember" }, showOnlyInTake: true },
+		// a glow lights nothing: the faint warm light on the fingers and the face, brighter on a drag
+		{ role: "light", kind: "point-light", at: [0, TIP + 0.004, 0], light: { type: "point", color: "#ff6a2a", intensity: 0.04, range: 1.2, flicker: 0.2, shadow: false },
+			switch: { visible: "ember_vis", level: "ember" }, showOnlyInTake: true },
+		{ role: "smoke", kind: "effect", at: [0, TIP + 0.002, 0], effect: { preset: "smoke" }, switch: { visible: "ember_vis" }, showOnlyInTake: true },
+	],
+};
+
+export const lighter = {
+	label: "Lighter", prop: "lighter", skill: "smokeCigarette",
+	description: "7.5 cm disposable lighter held in the left fist (smokeCigarette prop lighter): body and hood, a glowing flame and its flickering light (shown only while a take drives them: smokeCigarette args.kit)",
+	carry: { prop: "lighter", at: [0, 0, 0], along: [0, 1, 0], visible: "lit_vis" },
+	parts: [
+		{ role: "body", kind: "sculpt", at: [0.01, -0.062, 0], recipe: { version: 1, parts: [
+			{ id: "body", shape: "box", size: [0.025, 0.075, 0.013], position: [0, 0.0375, 0], roundness: 0.5, color: "#c4372f" },
+			{ id: "hood", shape: "box", size: [0.024, 0.013, 0.012], position: [0, 0.0815, 0], roundness: 0.25, color: "#aeb4b9" },
+			{ id: "wheel", shape: "cylinder", size: [0.009, 0.006, 0.009], position: [-0.006, 0.0815, 0], rotation: [90, 0, 0], color: "#6d7378" }] } },
+		{ role: "flame", kind: "sphere", at: [0.01, 0.027, 0], scale: [0.011, 0.028, 0.011], color: "#ffcf73",
+			glow: { color: "#ff9a3c", intensity: 6, halo: 1.6 }, switch: { visible: "flame_vis" }, showOnlyInTake: true },
+		{ role: "light", kind: "point-light", at: [0.01, 0.045, 0], light: { type: "point", color: "#ffb35c", intensity: 0.5, range: 4, flicker: 0.6, shadow: false },
+			switch: { visible: "flame_vis" }, showOnlyInTake: true },
+	],
+};
+
+export const exhale = {
+	label: "Exhale", skill: "smokeCigarette",
+	description: "a breath of smoke from the mouth: its root follows landmark:mouth facing forward (no placing); smokeCigarette args.kit.exhale shows it while breathing out (never in a static scene)",
+	carry: { follow: "landmark:mouth", aim: "face", visible: "exhale" },
+	parts: [{ role: "puff", kind: "effect", at: [0, 0, 0], effect: { preset: "exhale" }, showOnlyInTake: true }],
+};

package/src/light-blockers.js

@@ -0,0 +1,93 @@
+/**
+ * A practical light inside a record that casts shadows lights almost nothing.
+ *
+ * A shadow-casting light renders the set's depth from where it sits. Inside a
+ * solid record (a lamp light placed in its pole or in an unglowing bulb) the
+ * record's own faces fill that depth map in every direction, so the light only
+ * reaches the set through shadow-map leaks: thin streaks on the ground, and a
+ * brighter light changes nothing the agent can measure (session 1e3d1adc).
+ *
+ * `blockedLights` finds each light that renders a shadow and sits inside such
+ * a record, from the authored records, and `withLightWarnings` reports it in
+ * the receipt of the edit that placed, switched or moved either of them, beside
+ * the shadow-cap warning. A record with `glow` is self-lit and casts no shadow
+ * (object-glow.js), so a light inside a glowing bulb is not blocked.
+ *
+ * Pure: no three.js, so the command bus and Node tests read the same rule.
+ */
+
+import { practicalShadows, withShadowCapWarnings } from "./object-look.js";
+import { isEffectivelyHidden } from "./object-hidden.js";
+
+/** Renderers whose meshes cast shadows (props.jsx, set-pieces.jsx, sculpts, imported meshes).
+ * A plane and a cutout are cards: nothing can be inside them. */
+const CASTERS = new Set(["cube", "sphere", "capsule", "cylinder", "cone", "car", "chair", "small-plane", "sculpt", "mesh"]);
+const DEG = Math.PI / 180;
+const EPS = 1e-6;
+const MAX_WARNINGS = 4;
+
+/** `p` (world) in the record's own unscaled frame: the inverse of T · Rx · Ry · Rz · S
+ * (three.js "XYZ" Euler, the order SceneObject draws a record with). */
+function toLocal(object, p) {
+	let x = p.x - (object.x ?? 0), y = p.y - (object.y ?? 0), z = p.z - (object.z ?? 0);
+	const turn = (angle, a, b) => {
+		const c = Math.cos(angle * DEG), s = Math.sin(angle * DEG);
+		return [a * c + b * s, b * c - a * s];
+	};
+	[y, z] = turn(object.rotX ?? 0, y, z);
+	[z, x] = turn(object.rot ?? 0, z, x);
+	[x, y] = turn(object.rotZ ?? 0, x, y);
+	return { x: x / (object.scaleX || 1), y: y / (object.scaleY || 1), z: z / (object.scaleZ || 1) };
+}
+
+/** True when the local point is inside the record's drawn shape: the primitives
+ * exactly (built base on the floor, centred on x/z), anything else by its box. */
+function insideShape(object, { x, y, z }) {
+	const halfW = (object.footprint?.width ?? 0) / 2, halfD = (object.footprint?.depth ?? 0) / 2, height = object.height ?? 0;
+	if (!(halfW > EPS && halfD > EPS && height > EPS) || y <= EPS || y >= height - EPS) return false;
+	const u = x / halfW, w = z / halfD, ring = u * u + w * w;
+	if (object.renderer === "sphere") return ring + ((2 * y) / height - 1) ** 2 < 1 - EPS;
+	if (object.renderer === "cylinder") return ring < 1 - EPS;
+	if (object.renderer === "cone") return ring < (1 - y / height) ** 2 - EPS;
+	if (object.renderer === "capsule") {
+		const off = Math.max(0, halfW - y, y - (height - halfW)) / halfW;
+		return ring + off * off < 1 - EPS;
+	}
+	return Math.abs(u) < 1 - EPS && Math.abs(w) < 1 - EPS;
+}
+
+/** Records drawn with shadow-casting meshes where their numbers say: shown, not
+ * glowing, not riding a character (an attached record's numbers are in its bone's frame). */
+function casters(objects) {
+	return objects.filter((object) => CASTERS.has(object?.renderer) && !object.glow && !object.attach && !isEffectivelyHidden(object, objects));
+}
+
+/** [{ light, by }] for every light that renders a shadow from inside a shadow-casting record. */
+export function blockedLights(objects = []) {
+	const casting = new Set(practicalShadows(objects).casting);
+	const solids = casters(objects);
+	const out = [];
+	for (const light of objects) {
+		if (!casting.has(light?.id) || light.attach) continue;
+		const at = { x: light.x ?? 0, y: light.y ?? 0, z: light.z ?? 0 };
+		const by = solids.find((object) => object.id !== light.id && insideShape(object, toLocal(object, at)));
+		if (by) out.push({ light, by });
+	}
+	return out;
+}
+
+const label = (object) => (object.name && object.name !== object.id ? `${object.name.slice(0, 24)} (${object.id})` : object.id);
+
+function blockedWarning({ light, by }) {
+	const message = [...`Blocked: inside ${label(by)}, which casts shadows, so it lights almost nothing. Move it out or set shadow false.`];
+	return { code: "LIGHT_BLOCKED", id: light.id, message: message.length > 120 ? `${message.slice(0, 119).join("")}…` : message.join("") };
+}
+
+/** A command result with the shadow-cap warnings and a LIGHT_BLOCKED warning
+ * per blocked light whose light or blocker the edit touched (`affectedIds`). */
+export function withLightWarnings(result, objects) {
+	const capped = withShadowCapWarnings(result, objects);
+	const ids = result?.affectedIds ?? [];
+	const blocked = blockedLights(objects).filter(({ light, by }) => ids.includes(light.id) || ids.includes(by.id)).slice(0, MAX_WARNINGS).map(blockedWarning);
+	return blocked.length ? { ...capped, warnings: [...(capped.warnings ?? []), ...blocked] } : capped;
+}

package/src/motion/beat-board-model.js

@@ -0,0 +1,84 @@
+// The beat board's content (beat-board.jsx), from the agent's newest draft (agent-progress.js): each beat of the
+// draft's timeline as a block over its frames, with what QA found in it. A QA group (other than GOAL) whose frames
+// overlap the block is an issue there; a goal measured at a frame inside it is met or missed there. A block with a
+// missed goal reads "goal", else one with issues reads "issue", else "clean". Every issue also draws its own frame
+// span and every goal a mark at its frame, so where QA objects shows inside a long block. Beats that overlap each
+// other (two hands' skills at once) take separate rows, at most MAX_ROWS.
+// Pure: no React, no DOM.
+import { ko } from "../locale.js";
+
+const MAX_ROWS = 3;
+
+const LABELS = {
+	walk: ["Walk", "걷기"], walkTo: ["Walk", "걷기"], keys: ["Keys", "키 포즈"], standIdle: ["Stand", "서 있기"],
+	sitInSeat: ["Sit", "앉기"], exitCar: ["Exit car", "차에서 내리기"], reachGrip: ["Reach and grip", "뻗어 잡기"],
+	smokeCigarette: ["Smoke", "담배"],
+};
+
+/** A short, readable name for a beat (the timeline's skill or generator name). */
+export function beatLabel(beat) {
+	const pair = LABELS[beat];
+	return pair ? ko(pair[0], pair[1]) : String(beat ?? "");
+}
+
+const overlaps = (a0, a1, b0, b1) => a0 <= b1 && b0 <= a1;
+
+/** True when the take on the timeline is still the draft as compiled: same length, one segment, untrimmed, 1x. */
+export function takeIsDraft(motion, draft) {
+	const segments = motion?.segments;
+	if (!draft || !segments?.length || motion.frames !== draft.frames || segments.length !== 1) return false;
+	const [only] = segments;
+	return only.speed === 1 && only.timelineStart === 0 && only.timelineEnd === draft.frames - 1;
+}
+
+/**
+ * beatBoardModel(draft, motion) -> null (nothing to show) or
+ * { mode: "draft" | "installed", n, total, ok, blocks: [{ key, beat, label, src, f0, f1, row, rows, issues, groups,
+ *   goals, missed, state, events }], spans: [{ f0, f1, text }] (each issue), marks: [{ f, ok, text }] (each goal) }.
+ * mode "draft": the newest draft is not installed. mode "installed": it is, and the timeline's take is still that draft
+ * (takeIsDraft); a take retimed or trimmed since shows nothing, its frames no longer match the beats.
+ */
+export function beatBoardModel(draft, motion) {
+	if (!draft?.timeline?.length) return null;
+	const mode = draft.installed ? "installed" : "draft";
+	if (mode === "installed" && !takeIsDraft(motion, draft)) return null;
+	const groups = (draft.qa?.groups ?? []).filter(g => g.kind !== "GOAL");
+	const goals = (draft.qa?.goals ?? []).filter(g => Number.isFinite(g.at));
+	const rowEnds = [];
+	const blocks = draft.timeline.map((b, index) => {
+		const [f0, f1] = b.f;
+		const inGroups = groups.filter(g => overlaps(f0, f1, g.first ?? 0, g.last ?? g.first ?? 0));
+		const inGoals = goals.filter(g => g.at >= f0 && g.at <= f1);
+		const missed = inGoals.filter(g => !g.ok).length;
+		let row = rowEnds.findIndex(end => end < f0);
+		if (row < 0) row = Math.min(rowEnds.length, MAX_ROWS - 1);
+		rowEnds[row] = Math.max(rowEnds[row] ?? -1, f1);
+		return {
+			key: `${b.src}:${index}`, beat: b.beat, label: beatLabel(b.beat), src: b.src, f0, f1, row,
+			issues: inGroups.length, groups: inGroups, goals: inGoals, missed,
+			state: missed ? "goal" : inGroups.length ? "issue" : "clean", events: b.events ?? [],
+		};
+	});
+	const rows = Math.max(1, rowEnds.length);
+	for (const block of blocks) block.rows = rows;
+	const spans = groups.map(g => ({ f0: g.first ?? 0, f1: g.last ?? g.first ?? 0, text: `${g.kind} ${g.subject}` })).sort((a, b) => a.f0 - b.f0);
+	const marks = goals.map(g => ({ f: g.at, ok: !!g.ok, text: goalText(g) })).sort((a, b) => a.f - b.f);
+	return { mode, n: draft.n, total: draft.qa?.total ?? 0, ok: !!draft.qa?.ok, blocks, spans, marks };
+}
+
+/** One goal as a line: "✓ name 1.2 cm (≤ 2 cm)"; a distance in metres reads in cm. */
+export function goalText(g) {
+	const cm = v => `${Math.round(v * 1000) / 10} cm`;
+	const upper = g.kind === "near" || g.kind === "still"; // a distance bound from above; the others are minimums
+	const value = Number.isFinite(g.value) ? (upper ? cm(g.value) : `${Math.round(g.value * 1000) / 1000}`) : "";
+	const need = Number.isFinite(g.need) ? (upper ? ` (≤ ${cm(g.need)})` : ` (≥ ${g.need})`) : "";
+	return `${g.ok ? "✓" : "✗"} ${g.name}${value ? ` ${value}${need}` : ""}`;
+}
+
+/** The tooltip of a block: its name and frames, then each issue and goal on its own line. */
+export function blockTitle(block) {
+	const head = `${block.label} · ${ko("frames", "프레임")} ${block.f0}–${block.f1}`;
+	const issues = block.groups.map(g => `⚠ ${g.kind} ${g.subject} (${ko("frames", "프레임")} ${g.first}–${g.last})`);
+	const events = block.events.map(e => `${e.event} ${e.object} f${e.f}`);
+	return [head, ...issues, ...block.goals.map(goalText), ...events].join("\n");
+}

package/src/motion/beat-board.css

@@ -0,0 +1,124 @@
+/* The beat board (beat-board.jsx) on the Full-Body lane's Body row: one block per beat of the agent's newest draft.
+   State colours: clean --ok, issues amber, a missed goal --danger. A draft not installed yet draws dashed. */
+.tl-beat-board {
+	--beat-issue: #d4891a;
+	--beat-inset: var(--tl-clip-inset, 7px);
+	--beat-clip-h: calc(var(--tl-track-row-height, 38px) - var(--beat-inset) * 2);
+	position: absolute;
+	left: 0;
+	right: 0;
+	top: 0;
+	/* overlapping beats stack below the Body row's clip, one full clip height each */
+	height: calc(var(--beat-inset) + var(--beat-rows, 1) * (var(--beat-clip-h) + 2px));
+	pointer-events: none;
+	z-index: 3;
+}
+
+.tl-beat {
+	--beat-c: var(--ok, #4fbf7a);
+	position: absolute;
+	top: calc(var(--beat-inset) + var(--beat-row, 0) * (var(--beat-clip-h) + 2px));
+	height: var(--beat-clip-h);
+	left: calc(var(--tl-f-start) * 100% + 1px);
+	width: max(6px, calc((var(--tl-f-end) - var(--tl-f-start)) * 100% - 2px));
+	box-sizing: border-box;
+	display: flex;
+	align-items: center;
+	gap: 6px;
+	min-width: 0;
+	margin: 0;
+	padding: 0 6px 0 7px;
+	overflow: hidden;
+	border: 0;
+	border-left: 3px solid var(--beat-c);
+	border-radius: var(--r-1, 4px);
+	background: color-mix(in srgb, var(--beat-c) 20%, var(--surface-bar, #121214));
+	color: var(--text-1, #e4e4e7);
+	font: 500 var(--tl-font-secondary, 11px) var(--sans, system-ui), sans-serif;
+	white-space: nowrap;
+	text-align: left;
+	cursor: pointer;
+	pointer-events: auto;
+}
+
+.tl-beat.issue { --beat-c: var(--beat-issue); }
+.tl-beat.goal { --beat-c: var(--danger, #e5484d); }
+.tl-beat:hover,
+.tl-beat.current { background: color-mix(in srgb, var(--beat-c) 32%, var(--surface-bar, #121214)); }
+.tl-beat:focus-visible { outline: 2px solid var(--select, #e8a33d); outline-offset: 1px; }
+
+.tl-beat-board.draft .tl-beat {
+	border-left-style: dashed;
+	box-shadow: inset 0 0 0 1px color-mix(in srgb, var(--beat-c) 55%, transparent);
+}
+
+.tl-beat-label {
+	min-width: 0;
+	overflow: hidden;
+	text-overflow: ellipsis;
+}
+
+.tl-beat-state {
+	margin-left: auto;
+	flex: none;
+	color: var(--beat-c);
+	font-family: var(--mono, 'JetBrains Mono'), monospace;
+	font-variant-numeric: tabular-nums;
+	font-weight: 600;
+}
+
+/* Each issue's frames as a bar, each goal as a mark at its frame, along the row's bottom edge (over the blocks). */
+.tl-beat-span {
+	position: absolute;
+	bottom: -2px;
+	left: calc(var(--tl-f-start) * 100%);
+	width: max(3px, calc((var(--tl-f-end) - var(--tl-f-start)) * 100%));
+	height: 3px;
+	border-radius: 2px;
+	background: var(--beat-issue);
+	opacity: 0.85;
+	pointer-events: auto;
+}
+
+.tl-beat-mark {
+	position: absolute;
+	bottom: -4px;
+	left: calc(var(--tl-f) * 100% - 4px);
+	width: 8px;
+	height: 8px;
+	box-sizing: border-box;
+	border: 2px solid var(--surface-bar, #121214);
+	border-radius: 50%;
+	background: var(--danger, #e5484d);
+	pointer-events: auto;
+}
+.tl-beat-mark.met { background: var(--ok, #4fbf7a); }
+
+/* The draft's name and QA total, at the right, below the blocks. */
+.tl-beat-head {
+	position: absolute;
+	top: calc(100% + 6px);
+	right: 8px;
+	padding: 2px 9px;
+	border-radius: 999px;
+	background: color-mix(in srgb, var(--beat-issue) 18%, var(--surface-panel, #151517));
+	color: var(--text-1, #e4e4e7);
+	font: 600 var(--tl-font-secondary, 11px) var(--mono, 'JetBrains Mono'), monospace;
+	font-variant-numeric: tabular-nums;
+	white-space: nowrap;
+	pointer-events: auto;
+}
+.tl-beat-head.ok { background: color-mix(in srgb, var(--ok, #4fbf7a) 20%, var(--surface-panel, #151517)); }
+
+/* Under a draft the older installed take dims and stops taking clicks. */
+.v2-sequencer .tl-lane:has(> .tl-beat-board.draft) .tl-motion-clip {
+	opacity: 0.35;
+	pointer-events: none;
+}
+
+/* Under the beats the take's own label gives way to them. */
+.v2-sequencer .tl-lane:has(> .tl-beat-board) .tl-motion-clip-label { visibility: hidden; }
+
+@media (prefers-reduced-motion: no-preference) {
+	.tl-beat { transition: background-color 120ms ease; }
+}