cozyclay 3.1.5 → 3.2.0

package/src/motion3/qa/style.js

@@ -8,9 +8,10 @@
 // QA error, and so is a FLOAT: the body off the ground without falling (floatChecks). A pop is a
 // spike, not a large value: a hard but continuous acceleration (a swing's launch) is style.
 // See docs/motion-api-v3.1.md C13.
-import { add, sub, scale, len, dot, angle } from "../compiler/math.js";
+import { sub, len, dot, angle } from "../compiler/math.js";
 import { CAPSULES, segPoints, sdBox } from "./geometry.js";
 import { groundSole, groundY } from "./ground.js";
+import { balanceAt } from "./com.js";
 
 const SPEED_JOINTS = ["Hips", "Head", "LeftHand", "RightHand", "LeftFoot", "RightFoot", "LeftLeg", "RightLeg", "LeftForeArm", "RightForeArm"];
 const CORE = new Set(["Hips", "Head"]);
@@ -81,28 +82,12 @@ function supported(out, f, supports) {
 }
 
 /**
- * Per frame: null where a declared support carries the body, "air" with no foot on the ground,
- * else the balance margin in metres: how far the centre of mass (hips, spine, head) sits inside
- * the box of the feet on the ground, the floor or an object's top (ground.js; < 0: outside it).
- * While the hips travel every foot counts.
+ * Per frame: null where a declared support carries the body, else balanceAt (com.js): "air" with
+ * no foot on the ground, or { margin, ... } with margin in metres: how far the mass-weighted
+ * centre of mass sits inside the support polygon of the feet on the ground, the floor or an
+ * object's top (ground.js; < 0: outside it).
  */
-function balanceMargins(out, supports = []) {
-	const sk = out.ctx.sk, I = sk.index, F = out.frames;
-	return F.map(({ s }, f) => {
-		if (supported(out, f, supports)) return null;
-		const { P } = s;
-		const moving = f > 0 && f < F.length - 1 && Math.hypot(F[f + 1].s.P[I.Hips][0] - F[f - 1].s.P[I.Hips][0], F[f + 1].s.P[I.Hips][2] - F[f - 1].s.P[I.Hips][2]) / 2 > 0.006;
-		const feet = [];
-		for (const S of ["Left", "Right"]) {
-			const sp = groundSole(out, f, S);
-			if (moving || Math.min(sp.heel[1], sp.ball[1]) < 0.02) feet.push(sp.heel, sp.ball, sp.tip);
-		}
-		if (!feet.length) return "air";
-		const com = scale(["Hips", "Spine1", "Spine2", "Head"].reduce((acc, j) => add(acc, P[I[j]]), [0, 0, 0]), 0.25);
-		const xs = feet.map(p => p[0]), zs = feet.map(p => p[2]);
-		return Math.min(com[0] - Math.min(...xs), Math.max(...xs) - com[0], com[2] - Math.min(...zs), Math.max(...zs) - com[2]);
-	});
-}
+export const balanceFrames = (out, supports = []) => out.frames.map((_, f) => (supported(out, f, supports) ? null : balanceAt(out, f)));
 
 /** True when a hand rests on the ground at frame f: its wrist or knuckles within HAND_DOWN of the ground under them. */
 const HAND_DOWN = 0.06;
@@ -112,7 +97,7 @@ function handDown(out, f) {
 }
 
 /** Runs [a, b] (indexes of out.frames) with both soles 2 cm or more above the ground (ground.js), no hand on it and no declared support. */
-function airRuns(out, supports = []) {
+export function airRuns(out, supports = []) {
 	const n = out.frames.length, runs = [];
 	const air = out.frames.map((_, f) => !supported(out, f, supports)
 		&& ["Left", "Right"].every(S => { const sp = groundSole(out, f, S); return Math.min(sp.heel[1], sp.ball[1]) >= 0.02; }) && !handDown(out, f));
@@ -169,12 +154,10 @@ export function styleChecks(sk, out, checks, L) {
 			if (deg > L.knee) push("KNEE", `${bend[0] === "knee_l" ? "Left" : "Right"} knee bent ${deg.toFixed(0)}deg`, f, deg, L.knee);
 		}
 	});
-	if (on("balance")) balanceMargins(out, checks.supports).forEach((m, f) => {
-		if (m === "air") push("BALANCE", "no foot on the ground", f, 0, 0);
-		else if (m !== null && -m > L.balance) {
-			const com = scale(["Hips", "Spine1", "Spine2", "Head"].reduce((acc, j) => add(acc, out.frames[f].s.P[sk.index[j]]), [0, 0, 0]), 0.25);
-			push("BALANCE", `centre of mass ${com[0].toFixed(2)},${com[2].toFixed(2)} outside the feet`, f, -m, L.balance);
-		}
+	if (on("balance")) balanceFrames(out, checks.supports).forEach((b, f) => {
+		if (b === "air") push("BALANCE", "no foot on the ground", f, 0, 0);
+		// one subject whatever the direction: a lean that swings from ahead to left stays one group; the hint says how far and which way
+		else if (b && -b.margin > L.balance) push("BALANCE", "centre of mass outside the feet", f, -b.margin, L.balance);
 	});
 	return issues;
 }
@@ -192,7 +175,7 @@ export function observeMotion(sk, out, checks = {}) {
 		return [Math.round(arr[at] * k * 100) / 100, at + f0];
 	};
 	const peaks = Object.fromEntries(kinematics(sk, out).map(({ j, v, a }) => [j, { speed: peak(v, fps), accel: peak(a, fps * fps) }]).filter(([, p]) => p.speed[0] >= STILL));
-	const margins = balanceMargins(out, checks.supports), span = test => {
+	const margins = balanceFrames(out, checks.supports).map(b => (b && b !== "air" ? b.margin : b)), span = test => {
 		const fs = margins.map((m, f) => (test(m) ? f + f0 : -1)).filter(f => f >= 0);
 		return fs.length ? [fs[0], fs[fs.length - 1]] : null;
 	}, air = airRuns(out, checks.supports).slice(0, 4).map(([a, b]) => [a + f0, b + f0]);

package/src/motion3/schema/fields.js

@@ -15,8 +15,10 @@ export const ANCHOR_FIELDS = { world: ["p"], body: ["p"], bone: ["bone", "offset
 export const PROP_FIELDS = ["hand", "origin", "points"];
 export const FIT_FIELDS = ["side", "anchor", "effector", "offset", "orient"];
 /** spec.objects[id]: a hinge or a carry (a body or a group id), see C3; carry keys: C14; a switch (any record, C15) moves nothing; a follow (any record, C16) rides a point of the body; a free entry (C17) moves by keys and falls. */
-export const OBJECT_FIELDS = { hinge: ["pivot", "axis", "channel"], carry: ["prop", "at", "along", "visible", "level", "grab", "release", "keys", "fall", "grasp", "mass"], switch: ["visible", "level"],
-	follow: ["follow", "offset", "aim", "visible", "level"], free: ["keys", "fall", "visible", "level"] };
+export const OBJECT_FIELDS = { hinge: ["pivot", "axis", "channel"], carry: ["prop", "at", "along", "visible", "level", "grab", "release", "keys", "fall", "grasp", "mass", "spring"], switch: ["visible", "level"],
+	follow: ["follow", "offset", "aim", "visible", "level"], free: ["keys", "fall", "visible", "level", "spring"] };
+/** spec.objects[id].spring (a carry or a free entry): a damped swing behind its anchor's acceleration, compiler/spring.js. */
+export const SPRING_FIELDS = ["length", "stiffness", "damping"];
 /** One spec.objects[id].fall entry (C17): the frame it starts to fall, what it lands on, how much it bounces, whether it rolls to rest, the velocity it leaves with. */
 export const FALL_FIELDS = ["at", "onto", "bounce", "tumble", "v"];
 /** One spec.objects[id].keys entry (C14): the held object's world pose at frame f; aim (+ roll) in place of rot (C16). */

package/src/motion3/schema/topics.js

@@ -55,7 +55,7 @@ const CARRY = { props: EXAMPLES.objects.props, objects: { cup: EXAMPLES.objects.
 export const NOTES = {
 	essentials: ["types: ? optional, =v default, a..b range, A | B one of, [key]: T map, a|b?: T both, x_l|r each side, (text) meaning.",
 		`A carried object: ${literal(CARRY)}. ${NO_JUMP}`,
-		"motion.describe { topic } or { topic: 'skills', name }: the rest."],
+		"motion.describe { topic } or { topic: 'skills', name }: more."],
 	spec: [UNITS,
 		"frames: an integer, or \"auto\" (the last skill end, generator end or key f, plus 1); the stored spec keeps the number.",
 		"Any number may be { range: [lo, hi] } (int: true for frames): the compiler searches it, QA 0 first, at most search.budget compiles.",
@@ -71,15 +71,18 @@ export const NOTES = {
 		"fits: the hand target moves so the effector (a prop point or the mean of joints), not the wrist, lands on the anchor.",
 		"A fit on a scene body also turns the hand about the forearm into a grip: a thin body (a can, a bar, a handle, a neck) across the palm, else thumb up; never past a comfortable forearm turn. A wrist you turn (wtwist/wflex) wins; fit.orient: false (reachGrip args.orient: false) turns it off.",
 		"reachGrip adds props.<anchor>Grip and its fit. Carry a scene object with objects.<id>.prop (topic objects).",
-		"Do not pin a carried thing on a knuckle point: without at/along it rests in the palm and the fingers close on it (fix.grasp). objects.<id>.grasp names how: power, pinch, hook, palm, spherical (a ball). objects.<id>.mass (kg) weighs on the arm; past one hand QA says LOAD and patches in the other hand."],
-	objects: ["A hinge turns the object (a body or a group) about pivot/axis by the angle channel your keys set (degrees).",
+		"Do not pin a carried thing on a knuckle point: without at/along it rests in the palm and the fingers close on it (fix.grasp). objects.<id>.grasp names how: power, pinch, hook, palm, spherical (a ball). objects.<id>.mass (kg) weighs on the arm; past one hand QA says LOAD and patches in the other hand.",
+		"objects.<id>.spring { length, stiffness, damping } (a carry, keyed included, or a free entry) swings it a beat behind the hand or its keys, then settles: a bag, a lantern. "
+			+ "length (m, default half its longest side) is the string or rod; stiffness (1/s^2) defaults to 9.81 / length, a real pendulum; damping (default 0.5; 1: no overshoot) how soon it stops. "
+			+ "A natural swing: length 0.4..0.6, damping 0.5..0.7. It turns, at most 60 deg about its base, never moves: put the base at the hand with at/along; a still hand leaves it still."],
+	objects: ["A hinge turns the object (a body or a group) about pivot/axis by the angle channel your keys set.",
 		"A carry follows the prop's hand: before grab the scene pose, grab..release in the hand, after release where it was let go, riding a body under it that keys or a hinge move.",
-		"No grab: in hand from frame 0; no release: to the end. No at/along: it rests in the palm, fingers closed on it.",
+		"No at/along: it rests in the palm, fingers closed on it.",
 		"A group (Empty) id moves all its parts; at/along pin a group's root to the palm too (an object.createKit kit). A carried object is an obstacle for the body and the scene.",
-		"A switch { visible?, level? } (no prop, no hinge field) moves nothing: it shows or hides any record (a part, a light, an effect) and sets its level, 0..4 light, glow and effect strength "
+		"A switch { visible?, level? } moves nothing: it shows or hides any record (a part, a light, an effect) and sets its level, 0..4 light, glow and effect strength "
 			+ "(an unkeyed level reads 1). Hiding a group hides its parts. A carry takes level too.",
-		"keys pose a carried object in the world while in hand: pos its base (a group: its root), rot a quaternion [x, y, z, w], "
-			+ "or aim [x, y, z] where its +Y points (a bat's barrel) plus roll degrees about it (none: the roll the arm holds most easily). "
+		"keys pose a carried object in the world while in hand: pos its base (a group: its root), rot a quaternion, "
+			+ "or aim [x, y, z] where its +Y points (a bat's barrel) plus roll degrees about it (none: the easiest roll). "
 			+ `The object leads and the arm follows (elbow, forearm, then the wrist within ${Object.entries(WRIST_LIMITS).map(([k, [lo, hi]]) => `${k} ${lo}..${hi}`).join(", ")} deg; dev + toward the thumb); `
 			+ "a left hand on a prop anchor of it turns with it; "
 			+ `the hand eases in and out over ${KEY_BLEND} frames. REACH "<id>: n cm off its keys" is what the hand could not reach; `
@@ -88,12 +91,12 @@ export const NOTES = {
 			+ "to rest on a stable face, one small bounce (0: none). A carry falls before grab or after release.",
 		"A follow { follow: <ref>, offset?, aim?, visible?, level? } puts any record (an effect, a light, a part) on a body point every frame: "
 			+ "aim sets its +Y (an effect emits along it): up (default), face (forward), a direction or a ref (toward it); offset is metres along its axes after aim. It is no obstacle.",
-		"The editor's motion.keyObject writes one key from a drag (a hinge: its channel key)."],
+		"The editor's motion.keyObject keys a drag (a hinge: its channel)."],
 	checks: ["Each entry adds QA groups: contacts CONTACT, orient ORIENT, below BELOW, clearance CLEARANCE, appear APPEAR; supports mark where a part rests on an object (no FLOAT, no balance there); a foot on an object's top is on the ground without one.",
 		"when: a weight channel (active above 0.99) or [f0, f1]; clearance uses frames.", "Check points take joint:, prop: and anchor: only; goals and probes take every ref (topic refs).",
 		"allow excuses a body part inside an object up to depth; limits override the QA limits. Unnamed entries are named by place, contacts[0].",
 		"Other characters with an installed take are bodies too: PERSON \"<part> x person:<id>\" is a part inside that person; a touch you mean (a push, a hug) is allow { part, object: \"person:<id>\", depth }.",
-		"Speed, acceleration, knee bend and balance are style: measured in output.observations, not judged. Naming speedCore/speedLimb, accCore/accLimb, knee or balance in limits makes it a check (SPEED, ACC, KNEE, BALANCE). observations.near: each hand's and foot's nearest object and gap (< 0 inside), measured, not judged.",
+		"Speed, acceleration, knee bend and balance are style (output.observations), not judged. Naming one in limits checks it: SPEED, ACC, KNEE, BALANCE (mass-weighted centre of mass outside the support polygon of the feet, +8 cm margin). observations.near: each hand's and foot's nearest object and gap (< 0 inside), measured, not judged.",
 		"motion.qa { checks } replaces every check for a re-measure."],
 	goals: ["Exactly one of near (distance <= tol), above (a.y - b.y >= by), moved (an object's base moved at least by from the scene pose; any other point ref, e.g. prop:bat.tip, at least by from where it is at at[0], at: [f0, f1]), still (stays within tol, default 0.01 m, of where moved measures from) or speed (the point reaches by m/s).",
 		"at is an absolute frame or [f0, f1]; mode all (every frame; the default) or any (one frame; speed's default). A failed goal is a GOAL group first in qa.groups and makes qa.ok false.",
@@ -111,7 +114,8 @@ export const NOTES = {
 		"object:<id> takes a body or a group (the box around its parts); in a distance a bare object:<id> means its surface.",
 		"Goals and probes take every kind; spec.checks keep joint:, prop: and anchor:."],
 	fix: [`spec.fix keys: ${FIX_KEYS.join(", ")}; false turns all off. output.fixed reports what each one changed.`,
-		"reach, slide, self and stance are on by default; penetration and retime are opt-in.",
+		"reach, slide, self, stance and person are on by default; penetration and retime are opt-in.",
 		"reach also brings the body to a hand on a world or scene-object anchor the straight arm misses: a lean, a hip shift, lower hips, the feet kept (fixed.reachBody lists each move); farther, place the body. retime is kept only when QA is no worse with it.",
-		"self keeps the arms out of the body on its fitted skin (QA BODY measures the same skin): wrist targets inside it go onto it, elbows turn about the shoulder-wrist line, a hand a little inside is pushed out. A fit's target (the mouth) is never moved; what is left is BODY, with checks.allow { part, object: <body part>, depth } for a contact meant to touch (a hand on a knee)."],
+		"self keeps the arms out of the body on its fitted skin (QA BODY measures the same skin): wrist targets inside it go onto it, elbows turn about the shoulder-wrist line, a hand a little inside is pushed out. A fit's target (the mouth) is never moved; what is left is BODY, with checks.allow { part, object: <body part>, depth } for a contact meant to touch (a hand on a knee).",
+		"person keeps the arms out of the other characters (QA PERSON): the wrist target moves out back the side the hand came from, however deep; an FK arm is left (fixed.person.skipped). A touch you mean: checks.allow { part, object: \"person:<id>\", depth }."],
 };

package/src/motion3/schema/types.js

@@ -5,6 +5,7 @@
 import { REF_KINDS, OBJECT_KEY_FIELDS } from "./fields.js";
 import { CONVENTIONS, GRASPS } from "../compiler/vocab.js";
 import { QA_LIMITS } from "../qa/checks.js";
+import { SPRING } from "../compiler/spring.js";
 import { CAPSULES } from "../qa/geometry.js";
 
 const def = (d, extra) => ({ ...extra, ...(d ? { description: d } : {}) });
@@ -83,23 +84,25 @@ export const FIT_TYPES = {
 	offset: ref("vec3", "world offset, m"), orient: { type: "boolean", description: "false: no grip turn" },
 };
 
-const OBJECT_KEY_TYPES = { f: int(), pos: ref("vec3"), rot: { type: "array", items: { type: "number" }, minItems: 4, maxItems: 4, description: "quat x, y, z, w" },
+const OBJECT_KEY_TYPES = { f: int(), pos: ref("vec3"), rot: { type: "array", items: { type: "number" }, minItems: 4, maxItems: 4, description: "quat xyzw" },
 	aim: ref("vec3", "or rot: +Y dir"), roll: num("deg about aim"), lean: num("aim tilt", { minimum: 0, maximum: 45 }) };
 
 const FALL = { type: "object", properties: { at: int(), onto: str(), bounce: num(null, { default: 0.25, minimum: 0, maximum: 0.6 }), tumble: { type: "boolean" },
 	v: { oneOf: [{ $ref: "#/$defs/vec3" }, { const: "hand" }], description: "m/s" } }, required: ["at"], additionalProperties: false };
 /** A free entry's keys and fall (C17) are a carry's, at any frame: said once, not twice. */
-const AS_CARRY = { description: "as carry; keys at any frame" };
-export const FREE_TYPES = { keys: AS_CARRY, fall: AS_CARRY };
+const AS_CARRY = { description: "as carry, any frame" };
+export const FREE_TYPES = { keys: AS_CARRY, fall: AS_CARRY, spring: AS_CARRY };
+const SPRING_TYPE = { type: "object", properties: Object.fromEntries(Object.entries(SPRING).map(([k, r]) => [k, num(null, { default: r.default, minimum: r.min, maximum: r.max })])),
+	additionalProperties: false };
 
 export const OBJECT_TYPES = {
-	pivot: ref("vec3", "world hinge point"), axis: ref("vec3", "default +Y"), channel: str("angle channel, deg"),
-	prop: str("spec.props name: it rides that hand"), at: ref("vec3", "palm offset [d, l, n]"), along: ref("vec3", "+Y on the palm, fixed"),
-	visible: str("channel: shown > 0.5"), level: str("channel: strength 0..4"), grab: int("hand takes it", { default: 0 }), release: int("let go (else end)"),
+	pivot: ref("vec3", "world"), axis: ref("vec3", "default +Y"), channel: str("angle, deg"),
+	prop: str("spec.props name"), at: ref("vec3", "palm offset [d, l, n]"), along: ref("vec3", "+Y on palm"),
+	visible: str("channel: shown > 0.5"), level: str("channel: 0..4"), grab: int("hand takes it", { default: 0 }), release: int("let go, else end"),
 	keys: { type: "array", items: { type: "object", properties: Object.fromEntries(OBJECT_KEY_FIELDS.map(f => [f, OBJECT_KEY_TYPES[f]])), required: ["f", "pos"], additionalProperties: false },
-		description: "world pose at f; hand follows" },
-	fall: { ...FALL, description: "or a list; topic objects" },
-	grasp: { enum: GRASPS }, mass: num("kg", { minimum: 0.01, maximum: 60 }),
+		description: "world pose; hand follows" },
+	fall: { ...FALL, description: "or a list" },
+	grasp: { enum: GRASPS }, mass: num("kg", { minimum: 0.01, maximum: 60 }), spring: SPRING_TYPE,
 	follow: ref("ref"), offset: ref("vec3"), aim: { oneOf: [{ enum: ["face", "up"] }, { $ref: "#/$defs/vec3" }, { $ref: "#/$defs/ref" }], default: "up" },
 };
 
@@ -144,6 +147,7 @@ export const FIX_TYPES = {
 	retime: bool("speed spikes borrow frames from the neighbouring keys", { default: false }),
 	stance: bool("a standIdle stance in a scene body slides out of it (observations.placed)", { default: true }),
 	grasp: bool("fingers close on what the hand holds; it rests in the hand", { default: true }),
+	person: bool("arms kept out of the other characters (QA PERSON)", { default: true }),
 };
 
 export const REF_DOCS = {

package/src/physics-overlay-settings.js

@@ -0,0 +1,41 @@
+// Which parts of the physics overlay (physics-overlay.js) the viewer wants: the centre of mass, the support
+// polygon, the air runs' arcs and the spring objects' trails. Off by default; a viewer setting like the onion
+// skin's (view-ghosts.js): never saved in the scene, never undone, gone with the session. motion.physicsOverlay
+// (commands/physics.js) and the motion controls' Physics box (physics-toggle.jsx) both set it here.
+import { useSyncExternalStore } from "react";
+
+const PHYSICS_PARTS = Object.freeze(["com", "support", "arc", "trail"]);
+const OFF = Object.freeze({ com: false, support: false, arc: false, trail: false });
+
+let settings = OFF;
+const listeners = new Set();
+
+/** The current setting { com, support, arc, trail } (booleans). */
+export const physicsOverlaySettings = () => settings;
+/** True when any part is on. */
+export const physicsOverlayOn = (value = settings) => PHYSICS_PARTS.some(part => value[part]);
+
+/**
+ * Apply args { all?, com?, support?, arc?, trail? }: `all` sets every part first, then each named part is set;
+ * no field at all turns every part on. Answers the new setting.
+ */
+export function setPhysicsOverlay(args = {}) {
+	const named = PHYSICS_PARTS.filter(part => typeof args[part] === "boolean");
+	const base = typeof args.all === "boolean" ? Object.fromEntries(PHYSICS_PARTS.map(part => [part, args.all])) : named.length ? settings : { com: true, support: true, arc: true, trail: true };
+	const next = Object.freeze({ ...base, ...Object.fromEntries(named.map(part => [part, args[part]])) });
+	if (PHYSICS_PARTS.every(part => next[part] === settings[part])) return settings;
+	settings = next;
+	for (const listener of [...listeners]) listener();
+	return settings;
+}
+
+/** "Physics overlay: centre of mass, support polygon on; arcs, trails off." */
+export function describePhysicsOverlay(value = settings) {
+	const words = { com: "centre of mass", support: "support polygon", arc: "air arcs", trail: "spring trails" };
+	const on = PHYSICS_PARTS.filter(part => value[part]).map(part => words[part]), off = PHYSICS_PARTS.filter(part => !value[part]).map(part => words[part]);
+	if (!on.length) return "Physics overlay off.";
+	return `Physics overlay: ${on.join(", ")} on${off.length ? `; ${off.join(", ")} off` : ""}.`;
+}
+
+const subscribe = listener => { listeners.add(listener); return () => listeners.delete(listener); };
+export const usePhysicsOverlaySettings = () => useSyncExternalStore(subscribe, physicsOverlaySettings, physicsOverlaySettings);

package/src/physics-overlay.js

@@ -0,0 +1,152 @@
+// The physics overlay as three.js objects (motion3/physics-view.js and physics-trail.js give the numbers): the
+// centre of mass as a 4 cm ball with a line down to the ground, the support polygon on the ground, per air run the
+// hips path (white, dashed) against the gravity parabola (orange), and each spring object's tip trail. Lines are
+// thin tubes of a fixed width in metres, so a capture or an export at any size draws them as the viewport does. Every
+// node takes no ray and draws over the body (the centre of mass sits inside it). The body's marks are computed where
+// the take was compiled and ride the character's placement; the trails are world space, as the object tracks are.
+// The viewport (physics-overlay.jsx) and the export path (syncPhysicsOverlays, App's applyExportFrame) pose it for a
+// frame the same way, so scrub, playback and export draw the same overlay.
+import * as THREE from "three";
+import { comAt, supportAt, airArcs } from "./motion3/physics-view.js";
+import { tipTrails, TRAIL_FRAMES } from "./motion3/physics-trail.js";
+
+const PHYSICS_COLORS = Object.freeze({ inside: "#2ee66b", outside: "#ff2d2d", air: "#9aa0a6", supported: "#9aa0a6", support: "#ffd84a", path: "#ffffff", fit: "#ff8a1f", trail: "#3cc8ff" });
+const ORDER = 70, LINE = 0.006, DOT = 0.011, COM_RADIUS = 0.02, LIFT = 0.004;
+const noRay = () => {};
+const UP = new THREE.Vector3(0, 1, 0), a3 = new THREE.Vector3(), b3 = new THREE.Vector3(), d3 = new THREE.Vector3(), m4 = new THREE.Matrix4(), q4 = new THREE.Quaternion(), s3 = new THREE.Vector3();
+const tube = new THREE.CylinderGeometry(1, 1, 1, 8, 1, false), dot = new THREE.SphereGeometry(1, 12, 8);
+
+function claim(node, layer) {
+	node.traverse((n) => { n.layers.set(layer); n.raycast = noRay; n.castShadow = n.receiveShadow = false; n.renderOrder = ORDER; n.frustumCulled = false; });
+	return node;
+}
+const material = (color) => new THREE.MeshBasicMaterial({ color, transparent: true, opacity: 0.95, depthTest: false, depthWrite: false, toneMapped: false, fog: false });
+
+/** A polyline drawn as tube segments (one instance each); dashed draws every other one. */
+class Tubes {
+	constructor(color, capacity, radius = LINE) {
+		this.mesh = new THREE.InstancedMesh(tube, material(color), capacity);
+		this.mesh.count = 0;
+		this.radius = radius;
+	}
+	set(points, { closed = false, dashed = false } = {}) {
+		const n = points.length, segments = closed && n > 2 ? n : n - 1;
+		let count = 0;
+		for (let i = 0; i < segments && count < this.mesh.instanceMatrix.count; i++) {
+			if (dashed && i % 2) continue;
+			a3.fromArray(points[i]); b3.fromArray(points[(i + 1) % n]);
+			const length = d3.subVectors(b3, a3).length();
+			if (length < 1e-6) continue;
+			q4.setFromUnitVectors(UP, d3.divideScalar(length));
+			m4.compose(a3.add(b3).multiplyScalar(0.5), q4, s3.set(this.radius, length, this.radius));
+			this.mesh.setMatrixAt(count++, m4);
+		}
+		this.mesh.count = count;
+		this.mesh.instanceMatrix.needsUpdate = true;
+	}
+	dispose() { this.mesh.material.dispose(); this.mesh.dispose(); }
+}
+
+/** A dot per point (a frame of an arc: their spacing is the speed; a still path is one dot). */
+class Dots extends Tubes {
+	constructor(color, capacity, radius = DOT) {
+		super(color, capacity, radius);
+		this.mesh.geometry = dot;
+	}
+	set(points) {
+		points.forEach((p, i) => this.mesh.setMatrixAt(i, m4.makeScale(this.radius, this.radius, this.radius).setPosition(p[0], p[1], p[2])));
+		this.mesh.count = points.length;
+		this.mesh.instanceMatrix.needsUpdate = true;
+	}
+}
+
+export class PhysicsOverlay {
+	constructor({ layer }) {
+		this.layer = layer;
+		this.object = new THREE.Group();
+		this.object.name = "physics-overlay";
+		this.body = new THREE.Group();
+		this.body.matrixAutoUpdate = false;
+		this.world = new THREE.Group();
+		this.object.add(this.body, this.world);
+		this.ball = new THREE.Mesh(new THREE.SphereGeometry(COM_RADIUS, 20, 14), material(PHYSICS_COLORS.inside));
+		this.drop = new Tubes(PHYSICS_COLORS.inside, 1, LINE * 0.6);
+		this.drop.mesh.material.dispose();
+		this.drop.mesh.material = this.ball.material;
+		this.support = new Tubes(PHYSICS_COLORS.support, 64);
+		this.arcs = new THREE.Group();
+		this.body.add(this.ball, this.drop.mesh, this.support.mesh, this.arcs);
+		this.trails = [];
+		this.arcView = null;
+		this.arcTubes = [];
+		claim(this.object, layer);
+		this.last = null;
+	}
+
+	/** Draw the air arcs of `view` (rebuilt only when the view changes). */
+	setArcs(view) {
+		if (this.arcView === view) return;
+		this.arcView = view;
+		for (const t of this.arcTubes) { this.arcs.remove(t.mesh); t.dispose(); }
+		this.arcTubes = [];
+		for (const arc of view ? airArcs(view) : []) {
+			const path = new Tubes(PHYSICS_COLORS.path, arc.path.length), fit = new Tubes(PHYSICS_COLORS.fit, arc.fit.length);
+			const pathDots = new Dots(PHYSICS_COLORS.path, arc.path.length, DOT * 0.8), fitDots = new Dots(PHYSICS_COLORS.fit, arc.fit.length);
+			path.set(arc.path, { dashed: true });
+			fit.set(arc.fit);
+			pathDots.set(arc.path);
+			fitDots.set(arc.fit);
+			for (const t of [fit, fitDots, path, pathDots]) { this.arcs.add(claim(t.mesh, this.layer)); this.arcTubes.push(t); }
+			// the path over the arc: where the hips stay put, the white dot shows inside the orange one
+			path.mesh.renderOrder = pathDots.mesh.renderOrder = ORDER + 1;
+		}
+	}
+
+	setTrails(trails) {
+		while (this.trails.length < trails.length) {
+			const t = new Tubes(PHYSICS_COLORS.trail, TRAIL_FRAMES, LINE * 0.75);
+			this.world.add(claim(t.mesh, this.layer));
+			this.trails.push(t);
+		}
+		this.trails.forEach((t, i) => { t.mesh.visible = !!trails[i]; if (trails[i]) t.set(trails[i].points); });
+	}
+
+	/**
+	 * Pose the overlay for take frame `frame` of `view` (physics-view.js; null hides it) with parts `settings`
+	 * ({ com, support, arc, trail }). placement: the matrix from where the take was compiled to where the character
+	 * stands now. Answers what it drew (QA hooks read it).
+	 */
+	update({ view, frame, placement, settings }) {
+		const on = !!view && (settings.com || settings.support || settings.arc || settings.trail);
+		this.object.visible = on;
+		if (!on) { this.last = null; return null; }
+		if (placement) { this.body.matrix.copy(placement); this.body.matrixWorldNeedsUpdate = true; }
+		const com = comAt(view, frame), poly = settings.support ? supportAt(view, frame) : [], trails = settings.trail ? tipTrails(view, frame) : [];
+		this.ball.visible = this.drop.mesh.visible = settings.com;
+		if (settings.com) {
+			this.ball.material.color.set(PHYSICS_COLORS[com.state]);
+			this.ball.position.fromArray(com.p);
+			this.drop.set([com.p, [com.p[0], com.ground + LIFT, com.p[2]]]);
+		}
+		this.support.mesh.visible = poly.length > 0;
+		this.support.set(poly.map(([x, y, z]) => [x, y + LIFT, z]), { closed: true });
+		this.arcs.visible = settings.arc;
+		this.setArcs(settings.arc ? view : null);
+		this.setTrails(trails);
+		this.last = { frame: com.frame, com, support: poly, arcs: settings.arc ? airArcs(view).map(({ a, b, float, worst }) => ({ a, b, float, worst })) : [], trails: trails.map(t => ({ id: t.id, points: t.points.length })) };
+		return this.last;
+	}
+
+	dispose() {
+		this.setArcs(null);
+		for (const t of [this.drop, this.support, ...this.trails]) t.dispose();
+		this.ball.geometry.dispose();
+		this.trails = [];
+	}
+}
+
+const live = new Set();
+/** Register a viewport overlay's sync(frame) (physics-overlay.jsx); answers the unregister. */
+export function addPhysicsOverlaySync(sync) { live.add(sync); return () => live.delete(sync); }
+/** Pose every mounted overlay for timeline frame `frame` (the export path, before it renders), or the playhead with null. */
+export function syncPhysicsOverlays(frame = null) { for (const sync of live) sync(frame); }

package/src/physics-overlay.jsx

@@ -0,0 +1,54 @@
+// The physics overlay (physics-overlay.js) over the active character's take v3. It lives on SHOT_LAYER: the shot
+// camera, the editor and pose views draw it, and so do captures, contact sheets and exports (the capture camera
+// drops only GIZMO_LAYER), never the top view. Off by default; motion.physicsOverlay and the motion controls'
+// Physics box turn it on (physics-overlay-settings.js). Every rendered frame poses it for the playhead; the export
+// path poses it for the frame it records (syncPhysicsOverlays), so scrub, playback and export agree.
+import { useEffect, useMemo, useRef } from "react";
+import * as THREE from "three";
+import { useFrame, useThree } from "@react-three/fiber";
+import { SHOT_LAYER } from "./dualview.jsx";
+import { PhysicsOverlay, addPhysicsOverlaySync } from "./physics-overlay.js";
+import { physicsView } from "./motion3/physics-view.js";
+import { isTakeV3 } from "./motion3/playback.js";
+import { playbackFrame } from "./motion/playback-frame-store.js";
+import { physicsOverlayOn, physicsOverlaySettings, usePhysicsOverlaySettings } from "./physics-overlay-settings.js";
+
+const compiled = new THREE.Matrix4(), placement = new THREE.Matrix4();
+
+/** From where `take` was compiled (take.placement) to where the rig's parent (the character's placement) stands now. */
+function placementOf(rig, take) {
+	const at = take.placement?.position ?? [0, 0, 0];
+	compiled.makeRotationY(((take.placement?.yaw ?? 0) * Math.PI) / 180).setPosition(at[0], at[1], at[2]).invert();
+	rig.parent.updateWorldMatrix(true, false);
+	return placement.multiplyMatrices(rig.parent.matrixWorld, compiled);
+}
+
+/** rig: the active character's live rig; take: its installed motion; objects: the authored records. */
+export function PhysicsOverlayLayer({ rig, take, objects }) {
+	const settings = usePhysicsOverlaySettings();
+	const scene = useThree((state) => state.scene), invalidate = useThree((state) => state.invalidate);
+	const overlay = useMemo(() => new PhysicsOverlay({ layer: SHOT_LAYER }), []);
+	const on = physicsOverlayOn(settings) && !!rig && isTakeV3(take);
+	const view = useMemo(() => (on ? physicsView(take, objects) : null), [on, take, objects]);
+	const latest = useRef({});
+	useEffect(() => { latest.current = { rig, take, view }; });
+	useEffect(() => {
+		if (!on) return undefined;
+		scene.add(overlay.object);
+		return () => { scene.remove(overlay.object); };
+	}, [on, scene, overlay]);
+	useEffect(() => () => overlay.dispose(), [overlay]);
+	useEffect(() => { invalidate(); }, [invalidate, settings, view]);
+	const sync = useMemo(() => (frame) => {
+		const { rig: body, take: shown, view: measured } = latest.current;
+		const ready = measured && body?.parent;
+		return overlay.update({ view: ready ? measured : null, frame: frame ?? playbackFrame(), placement: ready ? placementOf(body, shown) : null, settings: physicsOverlaySettings() });
+	}, [overlay]);
+	useEffect(() => {
+		// QA hook: the overlay, what it drew last, and a way to pose it for a frame
+		if (typeof window !== "undefined") window.__cozyclayPhysics = { overlay, sync, drawn: () => overlay.last };
+		return addPhysicsOverlaySync(sync);
+	}, [overlay, sync]);
+	useFrame(() => { sync(null); });
+	return null;
+}

package/src/physics-toggle.jsx

@@ -0,0 +1,20 @@
+// The motion controls' Physics box: the whole physics overlay on or off, through motion.physicsOverlay (the agent's
+// door to the same setting, physics-overlay-settings.js).
+import { ko } from "./locale.js";
+import { useStudioShell } from "./shell/studio-shell-context.js";
+import { physicsOverlayOn, setPhysicsOverlay, usePhysicsOverlaySettings } from "./physics-overlay-settings.js";
+
+export function PhysicsToggle() {
+	const shell = useStudioShell();
+	const on = physicsOverlayOn(usePhysicsOverlaySettings());
+	const toggle = () => (shell?.runStudioAction ? shell.runStudioAction("motion.physicsOverlay", { all: !on }) : setPhysicsOverlay({ all: !on }));
+	return (
+		<label className={"tl-btn ik physics" + (on ? " on" : "")} data-testid="physics-overlay-toggle"
+			title={ko("Physics — draw the centre of mass (green inside the feet, red past the balance limit, grey in the air), the support polygon, the gravity arc of each jump against the hips' path, and spring trails",
+				"물리 — 무게중심(발 안이면 초록, 균형 한계 밖이면 빨강, 공중이면 회색), 지지 다각형, 점프마다 중력 포물선과 엉덩이 궤적, 스프링 궤적을 그립니다",
+				"物理 — 绘制重心（脚内为绿色，超出平衡极限为红色，空中为灰色）、支撑多边形、每次跳跃的重力抛物线与髋部轨迹，以及弹簧轨迹")}>
+			<input type="checkbox" checked={on} onChange={toggle} aria-label={ko("Physics overlay", "물리 오버레이", "物理叠加层")} />
+			{ko("Physics", "물리", "物理")}
+		</label>
+	);
+}

package/src/posestudio.jsx

@@ -405,7 +405,7 @@ export function IkHandles({ chains, fkJoints, ikState, enabled, focus, onFocus,
 				tmp.target.copy(tmp.hit).add(d.offset);
 			}
 			if (Math.hypot(ev.clientX - d.downXY[0], ev.clientY - d.downXY[1]) > CLICK_PX) d.moved = true;
-			solveRef.current?.(d.kind, d.trackId, tmp.target);
+			solveRef.current?.(d.kind, d.trackId, tmp.target, { bypass: ev.altKey });
 		};
 		const onUp = (ev) => {
 			// Detach this drag's listeners but KEEP the handler pair — nulling

package/tools/run-tests.mjs

@@ -1,7 +1,6 @@
 #!/usr/bin/env node
 import { spawn } from "node:child_process";
-import { mkdtempSync, readdirSync, rmSync } from "node:fs";
-import { createRequire } from "node:module";
+import { existsSync, mkdtempSync, readdirSync, readFileSync, rmSync } from "node:fs";
 import { availableParallelism, tmpdir } from "node:os";
 import { join, relative } from "node:path";
 
@@ -14,7 +13,7 @@ if (!process.env.COZYCLAY_AGENT_SESSIONS_DIR) {
 }
 
 const NODE_FILES = [
-	"test/motion3/verify-motion3-core.mjs", "test/motion3/verify-playback-frame-store.mjs", "test/verify-playback-render-isolation.mjs", "test/motion3/verify-motion3-idle.mjs", "test/motion3/verify-motion3-life.mjs", "test/motion3/verify-motion3-headlead.mjs", "test/motion3/verify-motion3-gait.mjs", "test/motion3/verify-motion3-overlap.mjs", "test/motion3/verify-motion3-flip.mjs", "test/motion3/verify-motion3-timing.mjs", "test/motion3/verify-motion3-self.mjs", "test/motion3/verify-motion3-commands.mjs", "test/motion3/verify-motion3-exitcar.mjs", "test/motion3/verify-motion3-agentloop.mjs", "test/motion3/verify-motion3-search.mjs", "test/motion3/verify-motion3-skills.mjs", "test/motion3/verify-motion3-carried.mjs", "test/motion3/verify-motion3-people.mjs", "test/motion3/verify-motion3-hit.mjs", "test/motion3/verify-motion3-socket.mjs", "test/motion3/verify-motion3-shapes.mjs", "test/motion3/verify-motion3-grasp-fields.mjs", "test/motion3/verify-motion3-finger-contact.mjs", "test/motion3/verify-motion3-finger-pose.mjs", "test/motion3/verify-motion3-grasp-qa.mjs", "test/motion3/verify-motion3-load.mjs", "test/motion3/verify-motion3-throw.mjs", "test/motion3/verify-motion3-catch.mjs", "test/motion3/verify-motion3-grasp-hints.mjs", "test/motion3/verify-motion3-reach-human.mjs", "test/motion3/verify-motion3-stance-grasp.mjs", "test/motion3/verify-motion3-grasp-friction.mjs", "test/motion3/verify-motion3-grasp-measure.mjs", "test/motion3/verify-motion3-contracts.mjs", "test/motion3/verify-motion3-describe.mjs", "test/motion3/verify-motion3-timeline.mjs", "test/motion3/verify-motion3-probes.mjs", "test/motion3/verify-motion3-grab.mjs", "test/motion3/verify-motion3-grab-blend.mjs", "test/motion3/verify-motion3-patch.mjs", "test/motion3/verify-motion3-patch-keys.mjs", "test/motion3/verify-motion3-stuck.mjs", "test/motion3/verify-motion3-repair.mjs", "test/motion3/verify-motion3-specstore.mjs", "test/motion3/verify-motion3-visual.mjs", "test/motion3/verify-motion3-goals.mjs", "test/motion3/verify-motion3-prompt.mjs", "test/motion3/verify-motion3-cup.mjs", "test/motion3/verify-motion3-arm.mjs", "test/verify-proxy-figure.mjs", "test/verify-text-object.mjs",
+	"test/motion3/verify-motion3-core.mjs", "test/motion3/verify-playback-frame-store.mjs", "test/verify-playback-render-isolation.mjs", "test/motion3/verify-motion3-idle.mjs", "test/motion3/verify-motion3-life.mjs", "test/motion3/verify-motion3-headlead.mjs", "test/motion3/verify-motion3-gait.mjs", "test/motion3/verify-motion3-overlap.mjs", "test/motion3/verify-motion3-flip.mjs", "test/motion3/verify-motion3-float-fix.mjs", "test/motion3/verify-motion3-timing.mjs", "test/motion3/verify-motion3-self.mjs", "test/motion3/verify-motion3-commands.mjs", "test/motion3/verify-motion3-exitcar.mjs", "test/motion3/verify-motion3-agentloop.mjs", "test/motion3/verify-motion3-search.mjs", "test/motion3/verify-motion3-skills.mjs", "test/motion3/verify-motion3-carried.mjs", "test/motion3/verify-motion3-people.mjs", "test/motion3/verify-motion3-hit.mjs", "test/motion3/verify-motion3-person-fix.mjs", "test/motion3/verify-motion3-socket.mjs", "test/motion3/verify-motion3-shapes.mjs", "test/motion3/verify-motion3-grasp-fields.mjs", "test/motion3/verify-motion3-finger-contact.mjs", "test/motion3/verify-motion3-finger-pose.mjs", "test/motion3/verify-motion3-grasp-qa.mjs", "test/motion3/verify-motion3-load.mjs", "test/motion3/verify-motion3-throw.mjs", "test/motion3/verify-motion3-catch.mjs", "test/motion3/verify-motion3-spring.mjs", "test/motion3/verify-motion3-grasp-hints.mjs", "test/motion3/verify-motion3-reach-human.mjs", "test/motion3/verify-motion3-stance-grasp.mjs", "test/motion3/verify-motion3-grasp-friction.mjs", "test/motion3/verify-motion3-grasp-measure.mjs", "test/motion3/verify-motion3-contracts.mjs", "test/motion3/verify-motion3-describe.mjs", "test/motion3/verify-motion3-timeline.mjs", "test/motion3/verify-motion3-probes.mjs", "test/motion3/verify-motion3-grab.mjs", "test/motion3/verify-motion3-grab-blend.mjs", "test/motion3/verify-motion3-patch.mjs", "test/motion3/verify-motion3-patch-keys.mjs", "test/motion3/verify-motion3-stuck.mjs", "test/motion3/verify-motion3-repair.mjs", "test/motion3/verify-motion3-specstore.mjs", "test/motion3/verify-motion3-visual.mjs", "test/motion3/verify-motion3-goals.mjs", "test/motion3/verify-motion3-prompt.mjs", "test/motion3/verify-motion3-cup.mjs", "test/motion3/verify-motion3-arm.mjs", "test/motion3/verify-motion3-balance.mjs", "test/motion3/verify-physics-overlay.mjs", "test/verify-proxy-figure.mjs", "test/verify-text-object.mjs",
 	"test/verify-proxy-figure-bounds.mjs",
 	"test/verify-character-capabilities.mjs",
 	"test/verify-root-path.mjs",
@@ -29,7 +28,7 @@ const NODE_FILES = [
 	"test/ardy/verify-timeline-coordinates.mjs",
 	"test/verify-tokens.mjs", "test/verify-lens-scrub.mjs",
 	"test/demo/verify-api-routes.mjs",
-	"test/ik/verify-collision-capsules.mjs", "test/ik/verify-ik-pick.mjs",
+	"test/ik/verify-collision-capsules.mjs", "test/ik/verify-ik-pick.mjs", "test/ik/verify-contact-project.mjs",
 	"test/ik/verify-ground.mjs",
 	"test/ik/verify-physics-review.mjs",
 	"test/ik/verify-physics-support.mjs",
@@ -211,7 +210,7 @@ const NODE_FILES = [
 
 const BROWSER_FILES = [
 	"test/qa-proxy-entry-browser.mjs",
-	"test/qa-previs-start-browser.mjs", "test/qa-shortcut-friction-browser.mjs",
+	"test/qa-previs-start-browser.mjs", "test/qa-shortcut-friction-browser.mjs", "test/qa-ik-contact-browser.mjs",
 	"test/qa-storyboard-board-browser.mjs",
 	"test/qa-storyboard-export-browser.mjs", "test/qa-playback-guide-browser.mjs",
 	"test/qa-proxy-figure-browser.mjs", "test/qa-click-friction-browser.mjs", "test/qa-update-notice-browser.mjs",
@@ -259,7 +258,7 @@ const EXTRA_INVENTORY = ["test/ik/translation-step.mjs", "test/qa-scenes-v5-migr
 
 EXTRA_INVENTORY.push("test/qa-proxy-figure-browser.mjs", "test/qa-click-friction-browser.mjs", "test/qa-update-notice-browser.mjs");
 EXTRA_INVENTORY.push("test/qa-proxy-entry-browser.mjs");
-EXTRA_INVENTORY.push("test/qa-previs-start-browser.mjs", "test/qa-shortcut-friction-browser.mjs");
+EXTRA_INVENTORY.push("test/qa-previs-start-browser.mjs", "test/qa-shortcut-friction-browser.mjs", "test/qa-ik-contact-browser.mjs");
 EXTRA_INVENTORY.push("test/qa-storyboard-board-browser.mjs");
 EXTRA_INVENTORY.push("test/qa-storyboard-export-browser.mjs", "test/qa-playback-guide-browser.mjs");
 
@@ -401,17 +400,11 @@ const hasNodeSqlite = meetsMinimumNodeVersion(NODE_SQLITE_MIN);
 // fresh clone those suites must degrade to an actionable EXCLUDE instead of
 // a startup timeout that swallows the real ERR_MODULE_NOT_FOUND (CI installs
 // them explicitly with `npm --prefix mcp ci`, so its coverage is unchanged).
-// Probes the same dependency set bin/mcp-runtime.mjs verifies before running.
+// Every mcp/package.json dependency must be in mcp/node_modules itself: most of
+// them also resolve from the root tree, which would hide a missing mcp install.
 function hasMcpRuntimeDeps() {
-	try {
-		const requireFromMcp = createRequire(new URL("../mcp/package.json", import.meta.url));
-		for (const dependency of ["@modelcontextprotocol/sdk/server/mcp.js", "three", "ws", "zod"]) {
-			requireFromMcp.resolve(dependency);
-		}
-		return true;
-	} catch {
-		return false;
-	}
+	const { dependencies = {} } = JSON.parse(readFileSync(new URL("../mcp/package.json", import.meta.url), "utf8"));
+	return Object.keys(dependencies).every((name) => existsSync(new URL(`../mcp/node_modules/${name}/package.json`, import.meta.url)));
 }
 
 const mcpDepsInstalled = hasMcpRuntimeDeps();

package/tools/verify-package-tarball.mjs

@@ -2,12 +2,37 @@
 import { execFileSync } from "node:child_process";
 import { existsSync, mkdtempSync, mkdirSync, readFileSync, readdirSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
-import { join } from "node:path";
+import { dirname, join, relative, resolve } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 
 const packageRoot = fileURLToPath(new URL("..", import.meta.url));
 const temporaryRoot = mkdtempSync(join(tmpdir(), "cozyclay-package-check-"));
 const extractionRoot = join(temporaryRoot, "extracted");
+// Static, side-effect and dynamic imports with a relative specifier.
+const RELATIVE_IMPORT = /(?:\bfrom\s*|\bimport\s*\(\s*|\bimport\s+)["'](\.\.?\/[^"']+)["']/g;
+
+function* modulesUnder(dir) {
+	if (!existsSync(dir)) return;
+	for (const entry of readdirSync(dir, { withFileTypes: true })) {
+		if (entry.name === "node_modules") continue;
+		const path = join(dir, entry.name);
+		if (entry.isDirectory()) yield* modulesUnder(path);
+		else if (entry.name.endsWith(".mjs")) yield path;
+	}
+}
+
+// Every relative import of a shipped bin/ or mcp/ module must resolve inside the
+// tarball: a dev checkout has every file, an npm install only what `files` lists.
+function missingImports(packedRoot) {
+	const missing = [];
+	for (const file of [...modulesUnder(join(packedRoot, "bin")), ...modulesUnder(join(packedRoot, "mcp"))]) {
+		for (const [, specifier] of readFileSync(file, "utf8").matchAll(RELATIVE_IMPORT)) {
+			const target = resolve(dirname(file), specifier);
+			if (!existsSync(target)) missing.push(`${relative(packedRoot, file)} imports ${specifier} (${relative(packedRoot, target)} is not in the tarball)`);
+		}
+	}
+	return missing;
+}
 
 try {
 	mkdirSync(extractionRoot);
@@ -24,6 +49,9 @@ try {
 	execFileSync("tar", ["-xzf", tarball, "-C", extractionRoot]);
 
 	const packedRoot = join(extractionRoot, "package");
+	const missing = missingImports(packedRoot);
+	if (missing.length > 0) throw new Error(`npm tarball is missing modules its bin/ and mcp/ code imports:\n  ${missing.join("\n  ")}`);
+	console.log("package tarball imports PASS (every relative import in bin/ and mcp/ resolves inside the tarball)");
 	const metadataPath = join(packedRoot, "package.json");
 	const markerPath = join(packedRoot, "dist", "cozyclay-package.json");
 	const signatureModulePath = join(packedRoot, "bin", "package-signature.mjs");