cozyclay 2.0.2 → 2.1.0

package/src/scene-objects.js

@@ -21,6 +21,7 @@ import { Euler, Quaternion } from "three";
 import { createObjectPath, translateObjectPath } from "./object-path.js";
 import { elementByPath } from "./studio-elements.js";
 import { MESH_DEFAULT_HEIGHT, MESH_HEIGHT_MIN } from "./scene-mesh.js";
+import { normalizeSculptRecipe, sculptStandingBox } from "./sculpt-recipe.js";
 
 export const DEFAULT_SCENE_OBJECTS = [];
 /** The persistence contract (plan §8.1): the version lives in the key AND in
@@ -96,9 +97,9 @@ export const OBJECT_COLORS = [
 /** How many hand-mixed colours the inspector remembers. Six is one palette
  * row: enough to keep a scene's custom tints reachable, short enough that the
  * popover never turns into a second, unruly palette. */
-export const RECENT_OBJECT_COLORS_MAX = 6;
+const RECENT_OBJECT_COLORS_MAX = 6;
 /** Session memory of hand-mixed tints; versioned like every other key here. */
-export const RECENT_OBJECT_COLORS_KEY = "cozyclay.objectColors.recent";
+const RECENT_OBJECT_COLORS_KEY = "cozyclay.objectColors.recent";
 
 const HEX_SHORT = /^#?([0-9a-f]{3})$/i;
 const HEX_LONG = /^#?([0-9a-f]{6})$/i;
@@ -209,13 +210,67 @@ const MESH_ENTRY = {
 	color: "#c49a6c",
 };
 
+/**
+ * A sculpt is a clay prop built from a recipe of soft parts (sculpt-recipe.js):
+ * data an agent writes from a reference image, never code. Like a mesh its size
+ * is per-instance, but it is MEASURED from the recipe rather than stored as a
+ * fact, so a record can never disagree with the parts it draws.
+ */
+export const SCULPT_KIND = "sculpt";
+const SCULPT_ENTRY = {
+	kind: SCULPT_KIND,
+	label: "Sculpt",
+	group: "Sculpts",
+	footprint: { width: 1, depth: 1 },
+	height: 1,
+	color: "#c2c6c8",
+};
+
+/**
+ * An empty is a pure grouping node: a transform and a place in the hierarchy,
+ * with nothing to draw (Unity's Create Empty, Blender's Empty). It exists so a
+ * multi-part assembly can have one top-level handle — move it, turn it, give it
+ * a route — without any of the parts having to stand in for it.
+ *
+ * Its size is zero on purpose. Every consumer that reads geometry (blockers,
+ * drop surfaces, ground sampling, support rise, fits, the plan footprint) goes
+ * through `footprint` × `height`, so a zero box makes the empty invisible to
+ * all of them without a per-consumer special case; the few that would
+ * misread a zero box as a point (dropToSurfacePatch) check `isEmptyObject`.
+ * It is creatable from the menu, so it lives beside the library entries rather
+ * than being import-only.
+ */
+export const EMPTY_KIND = "empty";
+/** Editor-only marker size in metres: the axes cross drawn for an empty, and
+ * the side of the invisible volume that makes it clickable. */
+export const EMPTY_MARKER_SIZE = 0.3;
+const EMPTY_ENTRY = {
+	kind: EMPTY_KIND,
+	label: "Empty",
+	group: "Primitives",
+	footprint: { width: 0, depth: 0 },
+	height: 0,
+	color: "#ffffff",
+};
+
+/** True for a record that is only a node: no mesh, no collision, no surface. */
+export function isEmptyObject(object) {
+	return object?.renderer === EMPTY_KIND;
+}
+
+/** The catalogue grouped for the create menu: the library plus the empty,
+ * which is creatable but has no footprint to satisfy the library's contract. */
+export const OBJECT_MENU_ENTRIES = Object.freeze([EMPTY_ENTRY, ...OBJECT_LIBRARY]);
+
 /** Every kind that can exist in a scene: the catalogue you can create from,
  * plus the kinds that arrive by import and so are deliberately absent from the
  * "Add object" menu (a cutout without an image, a mesh without a GLB, has
  * nothing to draw). */
-export function objectLibraryEntry(kind) {
+function objectLibraryEntry(kind) {
 	if (kind === CUTOUT_KIND) return CUTOUT_ENTRY;
 	if (kind === MESH_KIND) return MESH_ENTRY;
+	if (kind === SCULPT_KIND) return SCULPT_ENTRY;
+	if (kind === EMPTY_KIND) return EMPTY_ENTRY;
 	return OBJECT_LIBRARY.find((entry) => entry.kind === kind) ?? null;
 }
 
@@ -231,9 +286,9 @@ const cutoutHeight = (value) => Math.max(CUTOUT_HEIGHT_MIN, value);
 const cutoutAspect = (value) => clamp(value, CUTOUT_ASPECT_MIN, CUTOUT_ASPECT_MAX);
 
 /** How far a card may be pulled off the picture's own proportions. */
-export const CUTOUT_STRETCH_MIN = 0.1;
-export const CUTOUT_STRETCH_MAX = 10;
-export const cutoutStretch = (value) => {
+const CUTOUT_STRETCH_MIN = 0.1;
+const CUTOUT_STRETCH_MAX = 10;
+const cutoutStretch = (value) => {
 	const n = Number(value);
 	return Number.isFinite(n) ? clamp(n, CUTOUT_STRETCH_MIN, CUTOUT_STRETCH_MAX) : 1;
 };
@@ -255,8 +310,6 @@ export function cutoutFootprint(height, aspect, stretch = 1) {
 	};
 }
 
-/* ----------------------------------------------------- attachment ---- */
-
 /**
  * The frames a prop can be pinned to on a character. These are the APP's IK
  * track ids — the same names the rig panel and the animation tracks speak —
@@ -332,7 +385,7 @@ export function sceneObjectIdFromHierarchy(hierarchyId) {
 export function createSceneObject(kind, existing = [], placement = {}) {
 	// Cutouts and meshes come from an import, never from the catalogue:
 	// without an asset id the record has nothing to draw.
-	if (kind === CUTOUT_KIND || kind === MESH_KIND) return null;
+	if (kind === CUTOUT_KIND || kind === MESH_KIND || kind === SCULPT_KIND) return null;
 	const entry = objectLibraryEntry(kind);
 	if (!entry) return null;
 	const names = new Set(existing.map((object) => object.name));
@@ -510,6 +563,52 @@ export function duplicateMeshOptions(object) {
 	return { assetId: object.assetId, height: object.height, footprint: object.footprint, name: object.name, clay: object.clay === true };
 }
 
+/**
+ * A fresh sculpt from a recipe. Returns `{ object }` or `{ error }` with the
+ * recipe's own refusal, so a caller (the agent above all) hears why a recipe
+ * cannot be drawn instead of getting a silent null.
+ */
+export function createSculptObject({ recipe, name = "" } = {}, existing = [], placement = {}) {
+	const normalized = normalizeSculptRecipe(recipe);
+	if (!normalized.ok) return { error: normalized.error };
+	const { footprint, height } = sculptStandingBox(normalized.recipe);
+	const base = typeof name === "string" && name.trim() ? name.trim() : SCULPT_ENTRY.label;
+	const names = new Set(existing.map((object) => object.name));
+	let displayName = base;
+	for (let n = 2; names.has(displayName); n += 1) displayName = `${base} ${n}`;
+	const ids = new Set(existing.map((object) => object.id));
+	let id = SCULPT_KIND;
+	for (let n = 2; ids.has(id); n += 1) id = `${SCULPT_KIND}-${n}`;
+	return {
+		object: {
+			id,
+			name: displayName,
+			renderer: SCULPT_KIND,
+			x: TRANSFORM_LIMITS.x(Number(placement.x) || 0),
+			y: TRANSFORM_LIMITS.y(Number(placement.y) || 0),
+			z: TRANSFORM_LIMITS.z(Number(placement.z) || 0),
+			rot: wrapAngle(Number(placement.rot) || 0),
+			rotX: 0,
+			rotZ: 0,
+			scaleX: 1,
+			scaleY: 1,
+			scaleZ: 1,
+			path: null,
+			color: SCULPT_ENTRY.color,
+			parent: null,
+			attach: null,
+			hidden: false,
+			recipe: normalized.recipe,
+			footprint,
+			height,
+		},
+	};
+}
+
+export function duplicateSculptOptions(object) {
+	return { recipe: object.recipe, name: object.name };
+}
+
 /** Every writable transform channel and the rule that keeps it in the room. */
 const TRANSFORM_LIMITS = {
 	x: (value) => clamp(value, OBJECT_POSITION_LIMITS.min.x, OBJECT_POSITION_LIMITS.max.x),
@@ -523,6 +622,16 @@ const TRANSFORM_LIMITS = {
 	scaleZ: (value) => clamp(value, OBJECT_SCALE_LIMITS.min.z, OBJECT_SCALE_LIMITS.max.z),
 };
 
+/** The patch keys updateSceneObject reads for this object; any other key is
+ * silently ignored there, so callers that must not be silent check against this. */
+export function objectPatchFields(object) {
+	const fields = [...Object.keys(TRANSFORM_LIMITS), "name", "color", "hidden", "opacity", "path"];
+	if (object?.renderer === CUTOUT_KIND) fields.push("assetId", "sourceAssetId", "matteAssetId", "matteScale", "height", "aspect", "width", "stretch");
+	if (object?.renderer === MESH_KIND) fields.push("clay", "assetId", "height");
+	if (object?.renderer === SCULPT_KIND) fields.push("recipe");
+	return fields;
+}
+
 /** Every object that hangs off `id`, at any depth. A cycle cannot form because
  * setParent refuses one, but the seen-set keeps this total even if data is
  * hand-edited into a loop. */
@@ -574,13 +683,117 @@ export function isEffectivelyHidden(entity, objects = [], characters = []) {
 	return false;
 }
 
+/** Float dust (6e-17 where 0 belongs) is snapped away, and everything else is
+ * kept to 1e-9: fine enough that hundreds of small gizmo steps cannot drift a
+ * carried child visibly, coarse enough that stored values stay readable. */
+const tidy = (value) => {
+	const rounded = Math.round(value * 1e9) / 1e9;
+	return rounded === 0 ? 0 : rounded;
+};
+export const tidyAngle = (deg) => tidy(wrapAngle(tidy(deg)));
+
+const orientationOf = (record) =>
+	new Quaternion().setFromEuler(new Euler((record.rotX ?? 0) * DEG, (record.rot ?? 0) * DEG, (record.rotZ ?? 0) * DEG, EULER_ORDER));
+
+/** The Euler triple (degrees, XYZ) for an orientation that stays closest to
+ * `near`. Every orientation has two XYZ triples — (x, y, z) and
+ * (x+180, 180−y, z+180) — and a bare setFromQuaternion always answers with the
+ * one whose Y is within ±90. Taking that blindly would turn a plain yaw of 170
+ * into "rotX 180, rot −10, rotZ 180": the same pose, but the bird's-eye board
+ * and the inspector read `rot` as the yaw. The nearer triple keeps a flat
+ * object flat across every turn. */
+function eulerNear(quaternion, near) {
+	const e = new Euler().setFromQuaternion(quaternion, EULER_ORDER);
+	const here = [near.rotX ?? 0, near.rot ?? 0, near.rotZ ?? 0];
+	const candidates = [
+		[e.x / DEG, e.y / DEG, e.z / DEG],
+		[e.x / DEG + 180, 180 - e.y / DEG, e.z / DEG + 180],
+	].map((triple) => triple.map(tidyAngle));
+	const distance = (triple) => triple.reduce((sum, value, i) => sum + Math.abs(wrapAngle(value - here[i])), 0);
+	const [rotX, rot, rotZ] = distance(candidates[1]) < distance(candidates[0]) ? candidates[1] : candidates[0];
+	return { rotX, rot, rotZ };
+}
+
+/**
+ * The rigid motion that takes a pose to another: where its pivot was and is,
+ * and the turn Δ = q_after · q_before⁻¹ between the two orientations (XYZ
+ * Eulers, the renderer's order). Anything riding the pose goes to
+ * `to + Δ·(p − from)` and turns by Δ on the spot. Returns null when the
+ * orientation did not change — a pure move stays a plain translation.
+ *
+ * `yaw` is the part of Δ that turns about the vertical (swing-twist about +Y,
+ * degrees). A character only has a yaw, so it takes this and nothing more: the
+ * pitch or roll of what it is grouped under moves its position and leaves its
+ * facing alone.
+ *
+ * @returns {{ quaternion: Quaternion, matrix: number[], yaw: number, from: object, to: object } | null}
+ */
+export function rigidMotionBetween(before, after) {
+	if ((before.rotX ?? 0) === (after.rotX ?? 0) && (before.rot ?? 0) === (after.rot ?? 0) && (before.rotZ ?? 0) === (after.rotZ ?? 0)) return null;
+	const quaternion = orientationOf(after).multiply(orientationOf(before).invert());
+	if (quaternion.w < 0) quaternion.set(-quaternion.x, -quaternion.y, -quaternion.z, -quaternion.w);
+	if (quaternion.w > 1 - 1e-15) return null;
+	const { x, y, z, w } = quaternion;
+	return {
+		quaternion,
+		// row-major 3x3 of Δ
+		matrix: [
+			1 - 2 * (y * y + z * z), 2 * (x * y - z * w), 2 * (x * z + y * w),
+			2 * (x * y + z * w), 1 - 2 * (x * x + z * z), 2 * (y * z - x * w),
+			2 * (x * z - y * w), 2 * (y * z + x * w), 1 - 2 * (x * x + y * y),
+		],
+		yaw: tidyAngle((2 * Math.atan2(y, w)) / DEG),
+		from: { x: before.x ?? 0, y: before.y ?? 0, z: before.z ?? 0 },
+		to: { x: after.x ?? 0, y: after.y ?? 0, z: after.z ?? 0 },
+	};
+}
+
+/** A point carried by a rigid motion from `rigidMotionBetween`. */
+export function carryPointByMotion(point, motion) {
+	const { matrix: m, from, to } = motion;
+	const dx = point.x - from.x;
+	const dy = (point.y ?? 0) - from.y;
+	const dz = point.z - from.z;
+	return {
+		x: tidy(to.x + m[0] * dx + m[1] * dy + m[2] * dz),
+		y: tidy(to.y + m[3] * dx + m[4] * dy + m[5] * dz),
+		z: tidy(to.z + m[6] * dx + m[7] * dy + m[8] * dz),
+	};
+}
+
+/** Descendants that turn with a rotating parent: everything under it except
+ * records riding a character (their numbers are bone-local, so they follow the
+ * bone, not the parent) and whatever hangs below such a record. */
+function descendantsThatTurn(objects, id) {
+	const out = new Set();
+	let frontier = [id];
+	while (frontier.length) {
+		const next = [];
+		for (const object of objects) {
+			if (!object.parent || !frontier.includes(object.parent) || object.id === id || out.has(object.id) || object.attach) continue;
+			out.add(object.id);
+			next.push(object.id);
+		}
+		frontier = next;
+	}
+	return out;
+}
+
 export function updateSceneObject(objects, id, patch) {
 	let changed = false;
 	const target = objects.find((object) => object.id === id);
-	// A parent carries its children: the group is dragged, nudged and dropped as
-	// one body. Only translation rides along — rotating or scaling a group would
-	// have to orbit and rescale every child about the parent's origin, which is a
-	// different feature and is deliberately not pretended at here.
+	// A parent carries its children: the group is dragged, nudged, turned and
+	// dropped as one body. Translation shifts every descendant by the same
+	// delta. Rotation turns the group rigidly about the parent's pivot: each
+	// descendant orbits it by Δ = q_new · q_old⁻¹ and composes Δ onto its own
+	// orientation, so every child keeps its pose relative to the parent. A
+	// child's travel route is NOT turned with it: the route is a road in the
+	// world, and a parent's turn turns the bodies (their orientation and the
+	// authored position they orbit), never the road they would drive. A move and a turn in one patch is both at once,
+	// about the pivot's old and new place. Scale is NOT carried — rescaling a
+	// group would have to resize every child about the parent, a different
+	// feature. Records riding a character (`attach`) hold bone-local numbers and
+	// are left alone by the turn, and so is everything below them.
 	const carried = target ? descendantsOf(objects, id) : [];
 	const delta = { x: 0, y: 0, z: 0 };
 	if (target) {
@@ -593,10 +806,43 @@ export function updateSceneObject(objects, id, patch) {
 	}
 	const moving = new Set(carried.map((object) => object.id));
 	const shifts = delta.x || delta.y || delta.z;
+	let turn = null;
+	let turning = null;
+	if (target && !target.attach && carried.length) {
+		const after = { x: (target.x ?? 0) + delta.x, y: (target.y ?? 0) + delta.y, z: (target.z ?? 0) + delta.z };
+		for (const key of ["rotX", "rot", "rotZ"]) {
+			const value = patch[key] === undefined ? NaN : Number(patch[key]);
+			after[key] = Number.isFinite(value) ? TRANSFORM_LIMITS[key](value) : (target[key] ?? 0);
+		}
+		turn = rigidMotionBetween(target, after);
+		if (turn) turning = descendantsThatTurn(objects, id);
+	}
 
 	const next = objects.map((object) => {
 		if (object.id !== id) {
-			if (!shifts || !moving.has(object.id)) return object;
+			if ((!shifts && !turn) || !moving.has(object.id)) return object;
+			if (turn && turning.has(object.id)) {
+				const update = {};
+				const orbit = carryPointByMotion({ x: object.x, y: object.y, z: object.z }, turn);
+				for (const axis of ["x", "y", "z"]) {
+					const bounded = TRANSFORM_LIMITS[axis](orbit[axis]);
+					if (bounded !== (object[axis] ?? 0)) update[axis] = bounded;
+				}
+				const orientation = new Quaternion().multiplyQuaternions(turn.quaternion, orientationOf(object));
+				const euler = eulerNear(orientation, object);
+				for (const key of ["rotX", "rot", "rotZ"]) {
+					if (euler[key] !== (object[key] ?? 0)) update[key] = euler[key];
+				}
+				// A move in the same edit still carries the road along, unturned.
+				if (object.path && shifts) {
+					const moved = translateObjectPath(object.path, delta);
+					if (JSON.stringify(moved ?? null) !== JSON.stringify(object.path ?? null)) update.path = moved;
+				}
+				if (!Object.keys(update).length) return object;
+				changed = true;
+				return { ...object, ...update };
+			}
+			if (!shifts) return object;
 			const update = {};
 			const carriedDelta = { x: 0, y: 0, z: 0 };
 			for (const axis of ["x", "y", "z"]) {
@@ -629,6 +875,10 @@ export function updateSceneObject(objects, id, patch) {
 			update[key] = patch[key];
 		}
 		if (typeof patch.hidden === "boolean" && patch.hidden !== (object.hidden === true)) update.hidden = patch.hidden;
+		if (patch.opacity !== undefined && Number.isFinite(Number(patch.opacity))) {
+			const opacity = objectOpacity(patch.opacity);
+			if (opacity !== objectOpacity(object.opacity)) update.opacity = opacity;
+		}
 		// The travel path is authored geometry, not a bounded transform: it is
 		// normalized by createObjectPath (which repairs or refuses it) and set
 		// wholesale, with null clearing it back to a standing object.
@@ -704,6 +954,15 @@ export function updateSceneObject(objects, id, patch) {
 				}
 			}
 		}
+		// A recipe that cannot be drawn leaves the sculpt as it was; the command
+		// layer (object.sculpt) is where the refusal is reported.
+		if (object.renderer === SCULPT_KIND && patch.recipe !== undefined) {
+			const normalized = normalizeSculptRecipe(patch.recipe);
+			if (normalized.ok && JSON.stringify(normalized.recipe) !== JSON.stringify(object.recipe)) {
+				update.recipe = normalized.recipe;
+				Object.assign(update, sculptStandingBox(normalized.recipe));
+			}
+		}
 		if (!Object.keys(update).length) return object;
 		changed = true;
 		return { ...object, ...update };
@@ -788,8 +1047,34 @@ export function removeSceneObject(objects, id) {
 	// is an editing convenience and never an owner of the parts.
 	return next.map((object) => (object.parent === id ? { ...object, parent: null } : object));
 }
-/* -------------------------------------------------- persistence ---- */
 
+/**
+ * Wrap `id` in a new Empty: the Empty takes the object's place in the tree
+ * (its parent, its position) and the object becomes its child. One pure edit,
+ * so the caller can publish it as ONE history entry.
+ *
+ * Returns `{ objects, emptyId }`, or null when the object is unknown or is
+ * carried by a character (its numbers are local to a bone frame, so an Empty
+ * "at its position" would sit at a fictional place — detach first).
+ *
+ * Rotation is not copied: the Empty starts unturned, because a group node
+ * should be a clean handle, and the children keep their world transforms
+ * (grouping moves nothing on screen).
+ */
+export function groupUnderNewEmpty(objects, id) {
+	const target = objects.find((object) => object.id === id);
+	if (!target || target.attach) return null;
+	const created = createSceneObject(EMPTY_KIND, objects, { x: target.x, z: target.z });
+	if (!created) return null;
+	const names = new Set(objects.map((object) => object.name));
+	const base = `${target.name} Group`;
+	let name = base;
+	for (let n = 2; names.has(name); n += 1) name = `${base} ${n}`;
+	const empty = { ...created, name, y: TRANSFORM_LIMITS.y(target.y ?? 0), parent: target.parent ?? null };
+	// The Empty goes in just before the object, so the Outliner row keeps its place.
+	const next = objects.flatMap((object) => (object.id === id ? [empty, { ...object, parent: empty.id }] : [object]));
+	return { objects: next, emptyId: empty.id };
+}
 /**
  * Repair one stored record into a live record, or return null to drop it.
  * Storage is never trusted: `footprint`/`height` are rebuilt from the
@@ -798,6 +1083,14 @@ export function removeSceneObject(objects, id) {
  * `renderer` (or a record without an id) has nothing to render or address,
  * so it is dropped rather than half-restored (plan §8.2).
  */
+const OBJECT_OPACITY_MIN = 0.05;
+
+/** 1 = solid. Clamped above zero so a see-through object never becomes an invisible, unpickable one. */
+function objectOpacity(value) {
+	const n = Number(value);
+	return Number.isFinite(n) ? Math.min(1, Math.max(OBJECT_OPACITY_MIN, n)) : 1;
+}
+
 export function normalizeSceneObject(record) {
 	if (!record || typeof record !== "object" || Array.isArray(record)) return null;
 	const entry = objectLibraryEntry(record.renderer);
@@ -808,6 +1101,9 @@ export function normalizeSceneObject(record) {
 	// rule an unknown renderer already gets.
 	const isCutout = entry.kind === CUTOUT_KIND;
 	const isMesh = entry.kind === MESH_KIND;
+	const sculpt = entry.kind === SCULPT_KIND ? normalizeSculptRecipe(record.recipe) : null;
+	// Same rule as a cutout without its picture: nothing to draw, so dropped.
+	if (sculpt && !sculpt.ok) return null;
 	if (isCutout && (typeof record.assetId !== "string" || !record.assetId)) return null;
 	if (isMesh && (typeof record.assetId !== "string" || !record.assetId)) return null;
 	// Defensive import fallback, not a migration: hand-authored or external
@@ -855,6 +1151,8 @@ export function normalizeSceneObject(record) {
 		// all, and null is exactly what it meant: world-anchored.
 		attach: normalizeSceneAttach(record.attach) ?? null,
 		hidden: record.hidden === true,
+		// Absent means solid, so documents written before see-through objects are unchanged.
+		...(objectOpacity(record.opacity) < 1 ? { opacity: objectOpacity(record.opacity) } : {}),
 		// Library kinds take their size from the library — a stored footprint is
 		// stale data, not a fact. Cutouts and meshes are the exceptions: their
 		// size IS per-instance. A cutout rebuilds the footprint from height and
@@ -880,6 +1178,8 @@ export function normalizeSceneObject(record) {
 					),
 					height: cutoutHeight(pick(record.height, CUTOUT_DEFAULT_HEIGHT)),
 				}
+			: sculpt
+				? { recipe: sculpt.recipe, ...sculptStandingBox(sculpt.recipe) }
 			: isMesh
 				? {
 						assetId: record.assetId,
@@ -945,8 +1245,6 @@ export function loadScene(raw) {
 	return { status: "valid", objects, dropped };
 }
 
-/* ------------------------------------------------------------- gizmo ---- */
-
 /** The three world axes the gizmo drags along, and the record field each one
  * rotates / scales. */
 const WORLD_AXES = ["x", "y", "z"];
@@ -1025,8 +1323,6 @@ export function objectSize(object) {
 		depth: (object.footprint?.depth ?? 1) * (object.scaleZ ?? 1),
 	};
 }
-/* -------------------------------------------------- drop-to-surface ---- */
-
 /** The tolerance that keeps an edge-abutting footprint from counting as
  * overlap: a strict `<` against `max - EPS` makes a 0.5 - 0.5 touch false. */
 const OVERLAP_EPS = 1e-4;
@@ -1078,9 +1374,13 @@ export function objectFootprintBounds(object) {
  * clamped here: the y clamp stays in updateSceneObject, the single owner.
  */
 export function dropToSurfacePatch(object, others, characters = []) {
+	// An empty has no base to rest on and no extent to rest with: dropping it
+	// would carry a whole assembly to wherever a zero-size point happens to sit.
+	if (isEmptyObject(object)) return null;
 	const self = objectFootprintBounds(object);
 	let highestTop = 0;
 	for (const other of others) {
+		if (isEmptyObject(other)) continue;
 		if (isEffectivelyHidden(other, others, characters)) continue;
 		const bounds = objectFootprintBounds(other);
 		if (self.minX >= bounds.maxX - OVERLAP_EPS || bounds.minX >= self.maxX - OVERLAP_EPS) continue;

package/src/scenes.js

@@ -13,21 +13,22 @@ import { wrapAngle } from "./scene-objects.js";
 import { LEGACY_FRAME_FPS, TIMELINE_FRAME_FPS, toTimelineFrame } from "./timeline-fps.js";
 
 const CHARACTER_POSITION_LIMITS = elementByPath("character.position");
-const CHARACTER_ROTATION_LIMITS = elementByPath("character.rot");
 const CHARACTER_SCALE_LIMITS = elementByPath("character.scale");
 const KEY_LIGHT_LIMITS = Object.fromEntries(["x", "y", "z", "intensity", "warmth"].map((axis) => [axis, elementByPath(`stage.keyLight.${axis}`)]));
 
-export const SCENES_VERSION = 4;
-export const SCENES_STORAGE_KEY = "cozyclay.scenes.v4";
-export const SCENES_QUARANTINE_KEY = "cozyclay.scenes.v4.quarantine";
-export const PREVIOUS_SCENES_STORAGE_KEY = "cozyclay.scenes.v3";
-export const V2_SCENES_STORAGE_KEY = "cozyclay.scenes.v2";
-export const V1_SCENES_STORAGE_KEY = "cozyclay.scenes.v1";
+export const SCENES_VERSION = 5;
+export const SCENES_STORAGE_KEY = "cozyclay.scenes.v5";
+export const SCENES_QUARANTINE_KEY = "cozyclay.scenes.v5.quarantine";
+export const PREVIOUS_SCENES_STORAGE_KEY = "cozyclay.scenes.v4";
+const V3_SCENES_STORAGE_KEY = "cozyclay.scenes.v3";
+const V2_SCENES_STORAGE_KEY = "cozyclay.scenes.v2";
+const V1_SCENES_STORAGE_KEY = "cozyclay.scenes.v1";
 export const LEGACY_SCENE_STORAGE_KEY = "cozyclay.scene.v1";
 /** Newest-first fallback chain: a user arriving from any older build still
  * finds their scenes, and the reader migrates whatever body it lands on. */
 export const LEGACY_SCENES_STORAGE_KEYS = Object.freeze([
 	PREVIOUS_SCENES_STORAGE_KEY,
+	V3_SCENES_STORAGE_KEY,
 	V2_SCENES_STORAGE_KEY,
 	V1_SCENES_STORAGE_KEY,
 ]);
@@ -38,10 +39,20 @@ export { LEGACY_FRAME_FPS, TIMELINE_FRAME_FPS, toTimelineFrame };
  * file stem and the wire `source.rig` value sent to ARDY. */
 export const CHARACTER_MODEL_IDS = Object.freeze(["y-bot-tpose", "x-bot-tpose"]);
 export const DEFAULT_CHARACTER_MODEL = "y-bot-tpose";
+/** A rig-free capsule stand-in for blocking. It has no FBX and is never sent
+ * to ARDY, so it extends the accepted kinds without joining
+ * CHARACTER_MODEL_IDS. */
+export const PROXY_FIGURE_MODEL = "proxy-figure";
+export const CHARACTER_KIND_IDS = Object.freeze([...CHARACTER_MODEL_IDS, PROXY_FIGURE_MODEL]);
+export const POSTURES = Object.freeze(["stand", "sit", "lie"]);
+
+export function isProxyFigure(character) {
+	return character?.model === PROXY_FIGURE_MODEL;
+}
 export const DEFAULT_SUBJECT_ONE = "a young woman in a tan coat";
 export const DEFAULT_SUBJECT_TWO = "a man in a dark coat";
 
-export const DEFAULT_SCENE_STAGE = Object.freeze({
+const DEFAULT_SCENE_STAGE = Object.freeze({
 	characters: Object.freeze([
 		Object.freeze({ id: "char-a", model: DEFAULT_CHARACTER_MODEL, x: 0, z: 0, rot: 0, hidden: false, pose: null, subject: DEFAULT_SUBJECT_ONE }),
 	]),
@@ -153,7 +164,8 @@ export function createCharacterEntry(source = null, index = 0) {
 	const s = plainObject(source) ? source : {};
 	return {
 		id: typeof s.id === "string" && s.id ? s.id : `char-${index + 1}`,
-		model: CHARACTER_MODEL_IDS.includes(s.model) ? s.model : DEFAULT_CHARACTER_MODEL,
+		model: CHARACTER_KIND_IDS.includes(s.model) ? s.model : DEFAULT_CHARACTER_MODEL,
+		posture: POSTURES.includes(s.posture) ? s.posture : "stand",
 		x: Math.max(CHARACTER_POSITION_LIMITS.min.x, Math.min(CHARACTER_POSITION_LIMITS.max.x, finiteOr(s.x, 0))),
 		// Lift is bounded by the deck and the shared room headroom, so every
 		// writer (inspector field, viewport gizmo, load path) shares one envelope.
@@ -161,6 +173,10 @@ export function createCharacterEntry(source = null, index = 0) {
 		z: Math.max(CHARACTER_POSITION_LIMITS.min.z, Math.min(CHARACTER_POSITION_LIMITS.max.z, finiteOr(s.z, 0))),
 		rot: wrapAngle(finiteOr(s.rot, 0)),
 		hidden: s.hidden === true,
+		// The scene object this character is grouped under, or null. A grouped
+		// character rides its object's travel path the way grouped parts do; its
+		// own x/y/z stay world numbers at the object's authored pose.
+		parent: typeof s.parent === "string" && s.parent ? s.parent : null,
 		// User-picked body tint; null means "model default" (y-bot clay, x-bot
 		// whiter clay) so the entry survives future default tweaks.
 		tint: typeof s.tint === "string" && /^#[0-9a-fA-F]{6}$/.test(s.tint) ? s.tint : null,
@@ -180,6 +196,10 @@ export function createCharacterEntry(source = null, index = 0) {
 		// re-fetch and decode it on the next session.
 		layer: normalizeLayer(s.layer),
 		motionRef: normalizeMotionRef(s.motionRef),
+		// The Pose-mode / IK edits on this character's layer (encoded keys, range
+		// pins and their residuals). The motion domain owns them while the scene
+		// is open; this is what the saved scene carries so a reload keeps them.
+		ikEdits: normalizeIkEdits(s.ikEdits),
 	};
 }
 
@@ -189,6 +209,15 @@ const MOTION_ID_RE = /^[0-9a-f]{64}$/i;
 // in the project's embedded motions) and/or by location (url: a bridge run,
 // which is what pre-motionId documents carry). Either one alone is a valid
 // ref; the restore path prefers the embedded bytes when both are present.
+function normalizeIkEdits(value) {
+	if (!plainObject(value)) return null;
+	const rows = (list, valid) => (Array.isArray(list) ? list.filter(valid).map((entry) => cloneValue(entry)) : []);
+	const keys = rows(value.keys, (row) => plainObject(row) && Number.isFinite(row.frame) && plainObject(row.tracks));
+	const pins = rows(value.pins, (pin) => plainObject(pin) && typeof pin.id === "string");
+	const pinResiduals = rows(value.pinResiduals, (row) => Array.isArray(row) && typeof row[0] === "string");
+	return keys.length || pins.length ? { keys, pins, pinResiduals } : null;
+}
+
 function normalizeMotionRef(ref) {
 	if (!plainObject(ref)) return null;
 	const motionId = typeof ref.motionId === "string" && MOTION_ID_RE.test(ref.motionId) ? ref.motionId.toLowerCase() : null;
@@ -491,11 +520,31 @@ export function readSceneDocument(raw, legacyRaw = null) {
 	// Anything below v4 was authored while the timeline ran at 20 fps. The
 	// fallback stage (a v1 global cast) rides the same conversion, applied
 	// once, inside repairScene — whichever stage that scene ends up with.
+	// v4 → v5 needs no step of its own: every cast member passes through
+	// createCharacterEntry, which fills the missing posture with "stand".
 	const legacyClock = payload.version < 4;
 	const repaired = repairDocument(payload, createSceneStage(payload.stage), legacyClock);
 	return { status: migrating ? "migrated" : "valid", ...repaired };
 }
 
+/** Lift a scene document that skipped the storage reader (a project file, a
+ * playground preset) onto SCENES_VERSION: v3 and older move their frames onto
+ * the 24 fps clock, v4 and older gain a standing posture per cast member. */
+export function migrateScenesDocument(source) {
+	if (!Number.isInteger(source.version) || source.version >= SCENES_VERSION) return source;
+	const legacyClock = source.version < 4;
+	return {
+		...source,
+		version: SCENES_VERSION,
+		scenes: source.scenes.map((scene) => {
+			const stage = legacyClock ? migrateStageFrames(scene.stage) : scene.stage;
+			return { ...scene, stage: plainObject(stage) && Array.isArray(stage.characters)
+				? { ...stage, characters: stage.characters.map((entry) => (plainObject(entry) && !POSTURES.includes(entry.posture) ? { ...entry, posture: "stand" } : entry)) }
+				: stage };
+		}),
+	};
+}
+
 export function serializeSceneDocument(document) {
 	return JSON.stringify({ version: SCENES_VERSION, activeSceneId: document.activeSceneId, scenes: document.scenes });
 }