cozyclay 3.1.6 → 3.2.0

package/dist/cozyclay-package.json

@@ -1 +1 @@
-{"payload":"{\"distribution\":\"npm\",\"package\":\"cozyclay\",\"version\":\"3.1.6\",\"repository\":\"NomaDamas/CozyClay\",\"content_sha256\":\"d7b44cfa152ddb449c4e1445adeb8e3ae0a176e8eab6d431c7d9103ee12c25fc\"}","signature":"ruWnt+cS82Ajp7uv+w9ZiHLcqY5lCSNKER2sVtiLV+jnhGAzpPw1/KuZazg9lwFucoycs99uTwY8s+e5A3WQDw=="}
+{"payload":"{\"distribution\":\"npm\",\"package\":\"cozyclay\",\"version\":\"3.2.0\",\"repository\":\"NomaDamas/CozyClay\",\"content_sha256\":\"6b804a847783301703e2a3b5f6b7df24949f4ec67afe0e0757342f15a57730b2\"}","signature":"kb5TnT8Rn5B5fOkGXZqgfujX5ADiLTS6LDq+SMZbBAxzeZWYmFC0ogOVS1BFyRC/hjsHI7M2YrM9i/wcSTZ7Cw=="}

package/dist/index.html

@@ -46,7 +46,7 @@
         "applicationCategory": "DesignApplication",
         "applicationSubCategory": "3D previsualization",
         "operatingSystem": "Any (Chromium-based browser)",
-        "softwareVersion": "3.1.6",
+        "softwareVersion": "3.2.0",
         "description": "CozyClay is an open-source, browser-based 3D staging studio. Block a scene, pose characters, sequence motion prompts on a timeline, and preview generated motion in one local workspace that handles like the Unity Editor.",
         "image": "https://cozyclay.org/media/cozyclay-truck-demo-poster.jpg",
         "screenshot": "https://cozyclay.org/media/cozyclay-truck-demo-poster.jpg",

package/dist/workflow/index.html

@@ -8,11 +8,11 @@
     <meta name="theme-color" content="#101116" />
     <meta name="description" content="CozyClay visual workflow builder" />
     <title>CozyClay Workflow</title>
-    <script type="module" crossorigin src="/assets/workflow-DJwOUzqJ.js"></script>
+    <script type="module" crossorigin src="/assets/workflow-Dg9jCKOq.js"></script>
     <link rel="modulepreload" crossorigin href="/assets/rolldown-runtime-hePW80VL.js">
-    <link rel="modulepreload" crossorigin href="/assets/task-board-CkLZGPkv.js">
+    <link rel="modulepreload" crossorigin href="/assets/task-board-5PKn7ZaA.js">
     <link rel="modulepreload" crossorigin href="/assets/fflate.module-KbGj5-H6.js">
-    <link rel="modulepreload" crossorigin href="/assets/scene-asset-sync-t45pWCyq.js">
+    <link rel="modulepreload" crossorigin href="/assets/scene-asset-sync-LeI3eSnO.js">
     <link rel="stylesheet" crossorigin href="/assets/scene-asset-sync-BEjjhNEo.css">
     <link rel="stylesheet" crossorigin href="/assets/workflow-DRdwoDBT.css">
   </head>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cozyclay",
-  "version": "3.1.6",
+  "version": "3.2.0",
   "description": "Open source previs software in the browser: block a scene, pose characters, author camera moves and cuts, then take the same shots to an AI video model.",
   "scripts": {
     "dev": "node tools/dev-full.mjs --host 127.0.0.1 --port 5180",
@@ -75,6 +75,7 @@
     "eslint": "^10.12.0",
     "eslint-plugin-react-hooks": "^7.1.1",
     "globals": "^17.13.0",
+    "jpeg-js": "0.4.4",
     "knip": "^6.41.0",
     "mediabunny": "^1.55.2",
     "posthog-js": "^1.418.12",

package/src/App.jsx

@@ -140,7 +140,7 @@ import {
 	pathMetrics,
 	strokeToPathPoints,
 } from "./object-path.js";
-import { carriedPointAt, sceneObjectsAt } from "./object-travel.js"; import { objectTracksOf } from "./motion3/object-tracks.js"; import { ViewGhosts } from "./view-ghosts.jsx"; import { DraftGhost } from "./draft-ghost.jsx"; import { SculptSketch } from "./sculpt-sketch.jsx";
+import { carriedPointAt, sceneObjectsAt } from "./object-travel.js"; import { objectTracksOf } from "./motion3/object-tracks.js"; import { ViewGhosts } from "./view-ghosts.jsx"; import { DraftGhost } from "./draft-ghost.jsx"; import { SculptSketch } from "./sculpt-sketch.jsx"; import { PhysicsOverlayLayer } from "./physics-overlay.jsx"; import { syncPhysicsOverlays } from "./physics-overlay.js";
 import { routeOwnerFor } from "./route-owner.js";
 import {
 	exportFailureCode,
@@ -2874,7 +2874,7 @@ export default function App() {
 		// pass is the recorder's stand-in for the useFrame the preview gets.
 		// Riding characters move with their object first, then the props.
 		syncCarriers();
-		propSyncRef.current?.();
+		propSyncRef.current?.(); syncPhysicsOverlays(frame);
 		const sampled = sampleAt(context?.playbackScene ?? playbackScene, shotAtFrame(context?.shots ?? shots, frame), frame);
 		const framing = sampled.camera ?? context?.framing;
 		const cam = shotCamRef.current;
@@ -2959,7 +2959,7 @@ export default function App() {
 			look.current.pitch = cameraSnapshot.pitch;
 			propFrameRef.current = propFrame;
 			syncCarriers();
-			propSyncRef.current?.();
+			propSyncRef.current?.(); syncPhysicsOverlays();
 		}
 	}
 
@@ -3657,7 +3657,7 @@ export default function App() {
 				const point = new THREE.Vector3(); bone.getWorldPosition(point);
 				return point.toArray();
 			},
-			committedIkEdits, waypoints,
+			committedIkEdits, waypoints, rigs, characters, // rigs/characters: every cast member (QA reads a second rig)
 			// Scene props as the stage sees them, for QA that places a box and
 			// waits for its transform to land before fitting to it.
 			objects: sceneObjects,
@@ -4762,7 +4762,7 @@ export default function App() {
 									/>
 								</ObjectCarrier>
 							))}
-							<ViewGhosts rig={rigs[activeChar.id]} take={motion} frame={tlFrame} objects={sceneObjects} propTake={{ frameCount: tlFrameCount, fps: tlFps, objectTracks }} /><DraftGhost rigs={rigs} objects={sceneObjects} /><SculptSketch objects={sceneObjects} />
+							<ViewGhosts rig={rigs[activeChar.id]} take={motion} frame={tlFrame} objects={sceneObjects} propTake={{ frameCount: tlFrameCount, fps: tlFps, objectTracks }} /><DraftGhost rigs={rigs} objects={sceneObjects} /><SculptSketch objects={sceneObjects} /><PhysicsOverlayLayer rig={rigs[activeChar.id]} take={motion} objects={sceneObjects} />
 
 							{/* Selection marker: XYZ tripod + ring on the picked cast
 							    member; the X/Z arrows drag it across the deck. */}

package/src/commands/index.js

@@ -17,8 +17,9 @@ import * as exporting from "./export.js";
 import * as ai from "./ai.js";
 import * as stage from "./stage.js";
 import * as kits from "./kits.js";
+import * as physics from "./physics.js";
 
-export const COMMAND_MODULES = Object.freeze({ shot, cast, motion, motion3, objects, kits, view, scene, project, export: exporting, ai, stage });
+export const COMMAND_MODULES = Object.freeze({ shot, cast, motion, motion3, physics, objects, kits, view, scene, project, export: exporting, ai, stage });
 
 export function commandDeclarations(modules = COMMAND_MODULES) {
 	return Object.values(modules).flatMap(module => module.declarations.map(declaration => ({

package/src/commands/physics.js

@@ -0,0 +1,21 @@
+// motion.physicsOverlay: the physics overlay's viewer setting (physics-overlay-settings.js), the agent's door to the
+// motion controls' Physics box. Transient: never saved, never undone.
+import { describePhysicsOverlay, setPhysicsOverlay } from "../physics-overlay-settings.js";
+
+const flag = description => ({ type: "boolean", description });
+
+export const declarations = Object.freeze([
+	{ id: "motion.physicsOverlay", label: "Physics overlay", kind: "transient",
+		input: { type: "object", required: [], additionalProperties: false, properties: {
+			com: flag("the centre of mass: a 4 cm ball with a line down to the ground, green inside the feet, red past the balance limit (what QA calls BALANCE), grey off the ground"),
+			support: flag("the support polygon: the outline of the soles on the ground"),
+			arc: flag("per air run: the hips' path (white, dashed) and the gravity parabola through the same takeoff and landing (orange); far apart is a FLOAT"),
+			trail: flag("the last 24 frames of each spring object's tip"),
+			all: flag("every part at once, before the named ones; { all: false } turns the overlay off"),
+		} },
+		description: "Draw the physics QA measures over the active character's installed take, in the editor views and in captures, contact sheets and exports (capture_frame, verify_result frames, export.shotVideo) until it is turned off: com, support, arc and trail (see each field). Updated every frame, the same in scrub, playback and export. No field turns every part on; { all: false } turns it off. Turn it on before a screenshot to see why QA reports BALANCE or FLOAT. A viewer setting: off by default, never saved or undone." },
+]);
+
+export function register(registry) {
+	registry.register({ ...declarations[0], available: () => true, run: args => ({ affectedIds: [], summary: describePhysicsOverlay(setPhysicsOverlay(args)) }) });
+}

package/src/domains/motion.js

@@ -12,10 +12,7 @@ import {
 	ikKeyframes,
 	ikRemoveKeyframe,
 	ikSeedTargets,
-	clampIkTargetToFloor,
-	solveIk,
 	MID_TRACKS,
-	solveMidJoint,
 	solveEffectorSwing,
 	ikPlantFeet,
 	solveHipsTranslateToFloor,
@@ -35,7 +32,7 @@ import { ko } from "../locale.js";
 import { isProxyFigure } from "../scenes.js";
 import { refuseRigOnly } from "../character-kind.js";
 import { DEFAULT_POSE, restoreBindPositions, applyPose, applyHipsOffset } from "../poses.js";
-import { bakeIkDragKey, bakeIkDragRange, chainsChangedBy, ikDragRecord, ikDragTouch } from "../motion/ik-drag.js";
+import { bakeIkDragKey, bakeIkDragRange, chainsChangedBy, clampDragTarget, ikDragRecord, ikDragTouch, solveDragTarget } from "../motion/ik-drag.js";
 import { ikKeyJson, ikTrackKeyFromJson } from "../motion/ik-key-json.js";
 import { chooseIkEntryPose } from "../ik-camera.js";
 import { applyRangePin, captureRangePinTarget, normalizeRangePin, rangePinTargetWorld, rangePinTracks, removeRangePinKeys } from "../motion/range-pin.js";
@@ -741,7 +738,7 @@ export function useMotion(appContext) {
 	// chain toward the target; mid joints reposition the elbow/knee with both
 	// ends pinned (the handle snaps to the clamped position); FK joints swing
 	// toward the pointer. The solved pose stays a preview until Apply.
-	function ikSolve(kind, trackId, targetWorld) {
+	function ikSolve(kind, trackId, targetWorld, input = null) {
 		if (ikDragRef.current && ikDragRef.current.characterId !== appContext.shared.activeChar.id) return;
 		const state = appContext.shared.ikStateRef.current;
 		const ikChains = state.chains;
@@ -762,14 +759,15 @@ export function useMotion(appContext) {
 			ikDragRef.current = { frame: appContext.shared.tlFrame, ids: new Set(pending?.ids ?? []) };
 		}
 		ikDragRef.current = Object.assign(ikDragRecord(ikDragRef.current, appContext.shared.tlFrame), { characterId: appContext.shared.activeChar.id });
-		const touch = (id) => ikDragTouch(appContext.shared.ikStateRef.current, ikDragRef.current, id);
+		const touch = (id) => ikDragTouch(appContext.shared.ikStateRef.current, ikDragRef.current, id), activeId = appContext.shared.activeChar.id;
+		const clamp = () => clampDragTarget({ kind, trackId, targetWorld, bodyContact, chains: ikChains, record: ikDragRef.current, bypass: input?.bypass, open: () => ({ rigs: appContext.shared.rigs, activeId, cast: appContext.shared.characters, allow: domain.layer(activeId).take?.source?.spec?.checks?.allow, notify: appContext.notify }) });
 		if (kind === "chain") {
 			const chain = appContext.shared.ikStateRef.current.chains?.get(trackId);
 			if (!chain) return;
 			touch(trackId);
-			const clampedTarget = bodyContact ? clampIkTargetToFloor(trackId, targetWorld, 0, ikChains?.get(trackId)?.contactHeights ?? ikChains?.values().next().value?.contactHeights) : targetWorld;
+			const clampedTarget = clamp();
 			appContext.shared.ikStateRef.current.targets.set(trackId, clampedTarget.clone());
-			solveIk(chain, clampedTarget);
+			solveDragTarget(kind, chain, clampedTarget);
 			return;
 		}
 		if (kind === "mid") {
@@ -778,7 +776,7 @@ export function useMotion(appContext) {
 			const chain = midDef ? appContext.shared.ikStateRef.current.chains?.get(midDef.chain) : null;
 			if (!chain) return;
 			touch(chain.track.id);
-			solveMidJoint(chain, bodyContact ? clampIkTargetToFloor(trackId, targetWorld, 0, chain.contactHeights) : targetWorld);
+			solveDragTarget(kind, chain, clamp());
 			return;
 		}
 		// Effector swing: the rotation ring on a focused hand/foot. Rotates

package/src/motion/center-of-mass.js

@@ -1,20 +1,14 @@
 import * as THREE from "three";
 import { findBone } from "./ik.js";
+import { SEGMENT_FRACTIONS } from "../motion3/qa/com.js";
 
 // Body segment masses and the centre of mass of a posed Mixamo rig. Read-only:
 // motion verification and the support diagnostics measure with it.
 
 /**
- * Segment mass fractions of total body mass, from Dempster's cadaver study
- * (Dempster, W.T., "Space Requirements of the Seated Operator", WADC TR
- * 55-159, 1955), in the tabulation popularised by Winter, "Biomechanics and
- * Motor Control of Human Movement". The trunk (0.497) is split into pelvis
- * (0.142) and thorax+abdomen (0.355); distal pairs are merged because their
- * combined centroid still lands near the segment midpoint and Mixamo's hand
- * and toe bones are too short to place reliably:
- *
- *   head+neck 0.081 · trunk 0.497 · upper arm 0.028 · forearm 0.016 +
- *   hand 0.006 = 0.022 · thigh 0.100 · shank 0.0465 + foot 0.0145 = 0.061
+ * Segment mass fractions of total body mass (Dempster, via Winter), on Mixamo
+ * bone names. The table itself lives with motion3 QA (motion3/qa/com.js
+ * SEGMENT_FRACTIONS), which measures balance on the same segments.
  *
  * Each entry names the two Mixamo bones whose MIDPOINT carries the fraction.
  * Dempster's true centres of mass sit ~43% down each segment rather than at
@@ -24,19 +18,7 @@ import { findBone } from "./ik.js";
  *
  * The fractions sum to 1, so the weighted average below is a true CoM.
  */
-export const SEGMENT_MASSES = [
-	{ id: "pelvis", start: "mixamorigHips", end: "mixamorigSpine1", mass: 0.142 },
-	{ id: "torso", start: "mixamorigSpine1", end: "mixamorigNeck", mass: 0.355 },
-	{ id: "head", start: "mixamorigNeck", end: "mixamorigHead", mass: 0.081 },
-	{ id: "leftUpperArm", start: "mixamorigLeftArm", end: "mixamorigLeftForeArm", mass: 0.028 },
-	{ id: "leftForeArmHand", start: "mixamorigLeftForeArm", end: "mixamorigLeftHand", mass: 0.022 },
-	{ id: "rightUpperArm", start: "mixamorigRightArm", end: "mixamorigRightForeArm", mass: 0.028 },
-	{ id: "rightForeArmHand", start: "mixamorigRightForeArm", end: "mixamorigRightHand", mass: 0.022 },
-	{ id: "leftThigh", start: "mixamorigLeftUpLeg", end: "mixamorigLeftLeg", mass: 0.100 },
-	{ id: "leftShankFoot", start: "mixamorigLeftLeg", end: "mixamorigLeftFoot", mass: 0.061 },
-	{ id: "rightThigh", start: "mixamorigRightUpLeg", end: "mixamorigRightLeg", mass: 0.100 },
-	{ id: "rightShankFoot", start: "mixamorigRightLeg", end: "mixamorigRightFoot", mass: 0.061 },
-];
+export const SEGMENT_MASSES = SEGMENT_FRACTIONS.map(({ id, start, end, mass }) => ({ id, start: `mixamorig${start}`, end: `mixamorig${end}`, mass }));
 
 /**
  * World-space centre of mass of the rig's CURRENT pose: the mass-weighted

package/src/motion/contact-project.js

@@ -0,0 +1,143 @@
+import * as THREE from "three";
+import { closestPointsSegmentSegment } from "./fix-collisions.js";
+
+/**
+ * Contact projection for a Studio IK drag: the dragged target is moved out of
+ * the OTHER characters' capsules before the chain solves toward it, so a hand
+ * pushed into someone's chest stops on the chest instead of going through.
+ *
+ * One-sided by design: the blockers never move (the other character is never
+ * pushed; what they do is their own take). Fixed pass count, fixed order
+ * (probe capsules in the order given, blockers in the order given, the first
+ * deepest pair wins a tie), no clock, no randomness: the same target, the same
+ * blockers and the same `lastGood` give the same result.
+ *
+ * KEEP THE SIDE. The plain escape normal (probe point minus blocker point)
+ * flips once a deep target crosses the blocker's axis and then pushes the hand
+ * out of the BACK of the body. The escape keeps the side the hand came from:
+ * when the normal points away from `lastGood` (the last clean target of this
+ * drag), the push goes toward `lastGood` instead. Of the escape rules tried in
+ * the research prototype this was the only one that never tunnelled.
+ */
+
+const EPS = 1e-9;
+
+/** Push distance along unit `dir` that takes point `w` (relative to the
+ * blocker point) to distance `reach` from it: the far root of |w + t dir| = reach. */
+function exitDistance(w, dir, reach) {
+	const along = w.dot(dir);
+	const inside = w.lengthSq() - reach * reach;
+	return -along + Math.sqrt(Math.max(0, along * along - inside));
+}
+
+/**
+ * @param {object} options
+ * @param {Array<{id:string,a:THREE.Vector3,b:THREE.Vector3,radius:number}>} options.blockers
+ *   the other characters' capsules, built once per drag; never moved
+ * @param {number|((probeId:string, blockerId:string) => number|null)} [options.allow]
+ *   depth (m) a probe may go into a blocker: a number for every pair, or a
+ *   lookup (null = 0) for an intended touch (spec.checks.allow person entries)
+ * @param {number} [options.margin]  how far outside the surface a pushed target lands
+ * @param {number} [options.passes] fixed number of probe/push passes
+ * @param {number} [options.maxSteps] cap on the sweep's substeps per event
+ */
+export function createContactProjector({ blockers = [], allow = 0, margin = 0.004, passes = 4, maxSteps = 32 } = {}) {
+	// sweep spacing: no substep longer than the thinnest blocker's radius
+	const thinnest = Math.max(0.005, Math.min(...blockers.map((b) => b.radius)));
+	const allowed = typeof allow === "function" ? (p, b) => Math.max(0, allow(p, b) ?? 0) : () => Math.max(0, allow ?? 0);
+	const onProbe = new THREE.Vector3(), onBlocker = new THREE.Vector3(), w = new THREE.Vector3(), dir = new THREE.Vector3(), side = new THREE.Vector3();
+	const best = { depth: 0, reach: 0, probe: new THREE.Vector3(), blocker: new THREE.Vector3() };
+
+	/** The deepest probe/blocker pair past its allowance, written into `best`; false when none. */
+	function deepest(capsules) {
+		best.depth = 0;
+		for (const capsule of capsules) {
+			for (const blocker of blockers) {
+				const reach = capsule.radius + blocker.radius - allowed(capsule.id, blocker.id);
+				const dist = Math.sqrt(closestPointsSegmentSegment(capsule.a, capsule.b, blocker.a, blocker.b, onProbe, onBlocker));
+				if (reach - dist <= best.depth) continue;
+				best.depth = reach - dist;
+				best.reach = reach;
+				best.probe.copy(onProbe);
+				best.blocker.copy(onBlocker);
+			}
+		}
+		return best.depth > 0;
+	}
+
+	/**
+	 * SWEEP. A clean endpoint is not enough: one pointer event can carry the
+	 * limb clean across a thin blocker (a forearm, a hand). Walk from the
+	 * handle as displayed (`from.at`) to the target in equal substeps no
+	 * longer than the thinnest blocker's radius (at most `maxSteps`; a longer
+	 * jump gets longer substeps) and stop at the first substep that touches
+	 * after a clean one. Returns that substep (the keep-the-side push then runs
+	 * there, with the clean substep before it as the side), `{ at: null }`
+	 * when the target is clean and so was the way there, or null when the path
+	 * never got clean (the limb as displayed is in contact, e.g. the drag
+	 * opened touching, and a start in contact only stops once clean).
+	 *
+	 * The start is judged on the limb AS DISPLAYED (`from.capsules`), not by
+	 * solving toward lastGood again: the drag's solve does not land its handle
+	 * on the target in one call, so a second solve toward the same clean
+	 * target moves the limb on, into the blocker it had stopped short of, and
+	 * the whole crossing then read as a start in contact allowed to leave.
+	 */
+	function firstTouch(target, probe, from) {
+		const steps = Math.min(maxSteps, Math.max(1, Math.ceil(from.at.distanceTo(target) / thinnest)));
+		let wasClean = !deepest(from.capsules);
+		const clean = from.at.clone();
+		for (let k = 1; k <= steps; k++) {
+			const at = k === steps ? target.clone() : from.at.clone().lerp(target, k / steps);
+			if (!deepest(probe(at))) {
+				wasClean = true;
+				clean.copy(at);
+			} else if (wasClean) return { at, clean };
+		}
+		return wasClean ? { at: null, clean } : null;
+	}
+
+	/**
+	 * Move `target` out of the blockers.
+	 * @param {THREE.Vector3} target  the dragged point (not mutated)
+	 * @param {(candidate:THREE.Vector3) => Array<{id:string,a:THREE.Vector3,b:THREE.Vector3,radius:number}>} probe
+	 *   the dragged limb's capsules when its handle sits at `candidate`
+	 * @param {THREE.Vector3|null} lastGood  the last clean target of this drag (the side to keep)
+	 * @param {{at:THREE.Vector3, capsules:Array}|null} [from]  the handle and the limb's
+	 *   capsules as displayed when the event began: where the sweep starts
+	 *   (default: lastGood, with the limb probed there)
+	 * @returns {{ target: THREE.Vector3, contact: boolean, depth: number }}
+	 *   `contact` = a push happened; `depth` = what is left after the last pass (0 = clean)
+	 */
+	function project(target, probe, lastGood = null, from = null) {
+		let out = target.clone();
+		let contact = false;
+		if (!blockers.length) return { target: out, contact, depth: 0 };
+		const hit = lastGood ? firstTouch(out, probe, from ?? { at: lastGood, capsules: probe(lastGood) }) : null;
+		if (hit && !hit.at) return { target: out, contact, depth: 0 };
+		if (hit) out = hit.at;
+		const keep = hit?.clean ?? lastGood;
+		for (let pass = 0; pass < passes; pass++) {
+			if (!deepest(probe(out))) return { target: out, contact, depth: 0 };
+			contact = true;
+			w.subVectors(best.probe, best.blocker);
+			dir.copy(w);
+			if (keep) {
+				side.subVectors(keep, best.blocker);
+				// a normal pointing away from the side the hand came from is the
+				// far side of the body: escape toward lastGood instead
+				if (side.lengthSq() > EPS && (dir.lengthSq() <= EPS || dir.dot(side) < 0)) dir.copy(side);
+			}
+			if (dir.lengthSq() <= EPS) dir.set(0, 1, 0);
+			dir.normalize();
+			out.addScaledVector(dir, exitDistance(w, dir, best.reach + margin));
+		}
+		const left = deepest(probe(out)) ? best.depth : 0;
+		// the passes did not get the probed (displayed) limb out: fall back to
+		// the last clean substep of the sweep, on the near side
+		if (left > 0 && hit) return { target: hit.clean.clone(), contact: true, depth: 0 };
+		return { target: out, contact, depth: left };
+	}
+
+	return { project };
+}

package/src/motion/fix-collisions.js

@@ -287,7 +287,7 @@ function restPairOverlaps(rig, radii = null) {
 /** Closest points between two segments (Ericson, Real-Time Collision
  * Detection — the textbook segment/segment distance). Writes into outA/outB
  * and returns the squared distance. */
-function closestPointsSegmentSegment(p1, q1, p2, q2, outA, outB) {
+export function closestPointsSegmentSegment(p1, q1, p2, q2, outA, outB) {
 	const d1 = q1.clone().sub(p1);
 	const d2 = q2.clone().sub(p2);
 	const r = p1.clone().sub(p2);

package/src/motion/ik-drag.js

@@ -1,4 +1,10 @@
-import { createIkState, ikBakeKeyframe, ikTouch } from "./ik.js";
+import * as THREE from "three";
+import { clampIkTargetToFloor, createIkState, ikBakeKeyframe, ikTouch, MID_TRACKS, solveIk, solveMidJoint } from "./ik.js";
+import { buildCollisionCapsules } from "./fix-collisions.js";
+import { blockerCharacterId, characterBlockers } from "./collision-blockers.js";
+import { createContactProjector } from "./contact-project.js";
+import { allowance } from "../motion3/qa/checks.js";
+import { ko } from "../locale.js";
 
 /**
  * Per-drag bookkeeping for manual IK drags over a loaded motion.
@@ -16,6 +22,92 @@ export function ikDragRecord(current, frame) {
 	return current && current.frame === frame ? current : { frame, ids: new Set() };
 }
 
+// Told once per drag, the first time the projection moves the handle.
+const contactHint = () => ko("Stopped at the other character's body. Hold Alt while dragging to pass through",
+	"다른 인물의 몸에 닿아 멈췄어요. Alt를 누른 채 드래그하면 통과해요", "已停在另一个角色的身体上。按住 Alt 拖动即可穿过");
+// Studio capsule id -> the motion3 QA part an allow entry names (qa/geometry.js CAPSULES).
+const QA_PART = { UpperArm: "uarm", ForeArm: "farm", Hand: "hand", Thigh: "thigh", Shin: "shin", Foot: "foot" };
+const qaPart = (capsuleId) => capsuleId.replace(/^(left|right)(\w+)$/, (_, side, part) => `${QA_PART[part] ?? part}_${side[0]}`);
+
+/** The contact side of a drag, built once when it opens: the other cast members'
+ * capsules as they stand now (they do not move during a drag), the dragged
+ * chain's own capsules (upper arm, forearm, hand / thigh, shin, foot; no
+ * fingers) and the active take's person allowances (spec.checks.allow
+ * `{ part, object: "person:<id>", depth }`, read as QA reads them). */
+function openDragContact(kind, chain, { rigs, activeId, cast = null, allow = null, notify = null }) {
+	const blockers = characterBlockers(rigs, activeId, { characterIds: cast });
+	const own = blockers.length ? buildCollisionCapsules(chain.rig) : null;
+	if (!own) return null;
+	const capsules = [...own.values()].filter((c) => c.def.movable?.chain === chain.track.id && !c.def.handId && !c.def.optional);
+	const allowFor = (probeId, blockerId) => allowance(allow, qaPart(probeId), `person:${blockerCharacterId(blockerId)}`);
+	const reads = capsules.map((c) => ({ id: c.def.id, start: c.bones[0], end: c.bones[1] ?? c.bones[0], radius: c.radius, a: c.a.clone(), b: c.b.clone() }));
+	const contact = {
+		projector: createContactProjector({ blockers, allow: allowFor }),
+		pose: null, // this event's starting locals, set by clampDragTarget
+		// the limb's capsules as the drag will DISPLAY them with its handle at
+		// `candidate`: the drag's own solve, from this event's starting pose
+		probe: (candidate) => {
+			restorePose(chain, contact.pose);
+			solveDragTarget(kind, chain, candidate);
+			return contact.shown();
+		},
+		// the limb's capsules as they stand (the pose on screen at event start)
+		shown: () => {
+			for (const read of reads) { read.start.getWorldPosition(read.a); read.end.getWorldPosition(read.b); }
+			return reads;
+		},
+		handle: chain.bones[kind === "mid" ? 1 : 2],
+		lastGood: chain.bones[kind === "mid" ? 1 : 2].getWorldPosition(new THREE.Vector3()),
+		notify,
+	};
+	return contact;
+}
+
+function restorePose(chain, pose) {
+	chain.bones.forEach((bone, i) => bone.quaternion.copy(pose[i]));
+	chain.bones[0].updateMatrixWorld(true);
+}
+
+/** The solve a chain or mid drag applies toward its handle (domains/motion.js
+ * ikSolve). The contact probe runs this same call from the same starting pose,
+ * so the pose it checks is exactly the pose the drag displays. (A probe on a
+ * different solve, e.g. exactHinge, lands the elbow and hand elsewhere from a
+ * bent pose and passed targets whose displayed limb sat inside the other body.) */
+export function solveDragTarget(kind, chain, target) {
+	if (kind === "mid") solveMidJoint(chain, target);
+	else solveIk(chain, target);
+}
+
+/**
+ * Where a chain or mid drag may put its handle: on the floor with Body contact,
+ * then out of the other characters (contact-project.js). `open()` returns
+ * `{ rigs, activeId, cast, allow }` and is read once, on the first event of the
+ * drag (`record` keeps the result). `bypass` (Alt held) skips the contact
+ * projection for that event and leaves the side to keep untouched.
+ */
+export function clampDragTarget({ kind, trackId, targetWorld, bodyContact, chains, record = null, open = null, bypass = false }) {
+	const chain = chains?.get(kind === "mid" ? MID_TRACKS.find((t) => t.id === trackId)?.chain : trackId);
+	const heights = chain?.contactHeights ?? chains?.values().next().value?.contactHeights;
+	const floored = bodyContact ? clampIkTargetToFloor(trackId, targetWorld, 0, heights) : targetWorld;
+	if (!chain || !record || !open || (kind !== "chain" && kind !== "mid")) return floored;
+	if (record.contact === undefined) record.contact = openDragContact(kind, chain, open());
+	const contact = record.contact;
+	if (!contact || bypass) return floored;
+	// every probe starts from this event's pose, and the limb goes back to it
+	// so the caller's solveDragTarget starts there too
+	contact.pose = chain.bones.map((bone) => bone.quaternion.clone());
+	// the sweep starts from the limb as displayed, not from a re-solve toward lastGood
+	const from = { at: contact.handle.getWorldPosition(new THREE.Vector3()), capsules: contact.shown() };
+	const { target, depth } = contact.projector.project(floored, contact.probe, contact.lastGood, from);
+	restorePose(chain, contact.pose);
+	if (depth === 0) contact.lastGood = target.clone();
+	if (!target.equals(floored) && !contact.told) {
+		contact.told = true;
+		contact.notify?.(contactHint());
+	}
+	return target;
+}
+
 /** Mark `id` as written by this drag and touch it into the live layer. */
 export function ikDragTouch(ikState, record, id) {
 	ikTouch(ikState, id);

package/src/motion/timeline.css

@@ -1427,3 +1427,15 @@
 .v2-sequencer .objmo .sg { position: absolute; inset: 0; }
 .v2-sequencer .objmo .sg-head { padding: 3px 10px 2px; }
 .v2-sequencer .objmo .sg-body { min-height: 36px; margin: 0 0 6px; }
+
+/* The motion controls' Physics box (physics-toggle.jsx) */
+.v2-sequencer .tl-btn.physics {
+	display: inline-flex;
+	align-items: center;
+	gap: 4px;
+	cursor: pointer;
+}
+
+.v2-sequencer .tl-btn.physics input {
+	margin: 0;
+}

package/src/motion/timeline.jsx

@@ -10,7 +10,7 @@ import { insertPathMark, pathMarks, pathMetrics, pathProgressAt, MAX_PATH_LEAN }
 import { NumberField } from "../ui.jsx";
 import { flatTiming, timingIsFlat, envelopeDrag, insertCut, removeCut, CUT_MIN_GAP } from "../speed-envelope.js";
 import { checkShotAgainstPreset, presetById } from "../model-presets.js";
-import { TakeSegmentClips, TakeSegmentTools } from "./take-segments.jsx"; import { BeatBoard } from "./beat-board.jsx";
+import { TakeSegmentClips, TakeSegmentTools } from "./take-segments.jsx"; import { BeatBoard } from "./beat-board.jsx"; import { PhysicsToggle } from "../physics-toggle.jsx";
 import "./timeline.css";
 export { timelineTake } from "./take-segments.jsx";
 
@@ -1708,7 +1708,7 @@ export default function Timeline({
 						</div>
 						{onClearMotion && (
 							<div className="tl-head-group tl-motion-tools" role="group" aria-label={ko("Motion controls", "모션 컨트롤")}>
-								{motion?.segments && motionTools && <TakeSegmentTools motion={motion} frame={frame} />}
+								{motion?.segments && motionTools && <TakeSegmentTools motion={motion} frame={frame} />}{motionTools && <PhysicsToggle />}
 								<button
 									type="button"
 									className="tl-btn clear"

package/src/motion3/compile-job.js

@@ -65,8 +65,9 @@ export function runCompileJob({ model, scene, spec: asked, probes: sentProbes, c
 	// ms.repair: the whole repair's wall time, so a sweep that repairs every variant shows what it costs
 	const r = fixed.result, label = fixed.spec?.label ?? null, ms = fixed.repair ? { ...r.ms, repair: Math.round(performance.now() - t0) } : r.ms;
 	const take = bake ? bakeTake(sk, r.out, { position: bake.position, yaw: bake.yaw }, { spec: r.stored, prompt: ("prompt" in bake ? bake.prompt : label) ?? "" }) : undefined;
-	// a person anchor's joints ride with the take, so its saved source compiles the same without the others' takes (people.js)
-	const people = take && keptPeople(scene, [r.expanded, r.stored]);
+	// a person anchor's joints (and the bodies fix.person pushed an arm out of) ride with the take, so its saved source
+	// compiles the same without the others' takes (people.js)
+	const people = take && keptPeople(scene, [r.expanded, r.stored], r.out);
 	if (people) take.people = people;
 	return { stored: r.stored, qa: r.qa, observations: r.observations, used: r.used, fixed: r.fixed, search: r.search, timeline: r.timeline,
 		...(r.probes ? { probes: r.probes } : {}), ...(r.notes || corrected.length ? { notes: [...corrected, ...(r.notes ?? [])] } : {}), ms, frameCount: r.out.frameCount, label,

package/src/motion3/compiler/compile.js

@@ -20,7 +20,7 @@
 // ctx = { sk, scene: { objects: { id: { pos, R, half, ancestors } } } }; out.ctx.scene keeps the scene (object-pose.js)
 import { add, sub, scale, norm, len, dot, apply, axisRot } from "./math.js";
 import { isCarried, isFollow, hingePose, movesRecord, compose, relative } from "../carried.js";
-import { isFree, freePoseAt } from "../free-motion.js";
+import { isFree, freeSwungAt } from "../free-motion.js";
 import { groupsOf } from "../scene.js";
 import { pose, SIDES } from "./pose.js";
 import { graspAnchor } from "./socket-grip.js";
@@ -46,7 +46,7 @@ const REACH_SLACK = 0.02;
 
 /**
  * Scene boxes by frame. A body moves with its own spec.objects entry or its nearest group's (a
- * switch entry moves nothing; hinge: turned; free (C17): where its keys and falls put it, under the time map `mapOf()`;
+ * switch entry moves nothing; hinge: turned; free (C17): where its keys and falls put it, under the time map `mapOf()`, swung by its spring;
  * carry and follow: left at its scene pose and marked `carried` with the moving id). `obstacles` drops the carried
  * ones: QA, refs and object anchors read a carry where it rides (object-pose.js objectPoseAt, qa/object-checks.js);
  * a follow entry rides the body and is no obstacle.
@@ -63,7 +63,7 @@ function objectTracks(spec, scene, baked, mapOf = () => undefined) {
 			const mover = [id, ...(o.ancestors ?? [])].find(k => movesRecord(spec.objects?.[k])), entry = spec.objects?.[mover];
 			if (!entry) out[id] = o;
 			else if (isCarried(entry) || isFollow(entry)) out[id] = { ...o, carried: mover };
-			else if (isFree(entry)) out[id] = { ...o, ...compose(freePoseAt({ spec, scene, timeMap: map }, mover, f), relative(scene.objects[mover] ?? groupsOf(scene)[mover], o)) };
+			else if (isFree(entry)) out[id] = { ...o, ...compose(freeSwungAt({ spec, scene, timeMap: map }, mover, f), relative(scene.objects[mover] ?? groupsOf(scene)[mover], o)) };
 			else out[id] = { ...o, ...hingePose(entry, o, baked, f) };
 		}
 		cache.set(f, out);