cozyclay 3.1.6 → 3.2.1

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/pose-fade.js

@@ -15,6 +15,8 @@ export function writePoseFadeOpacity(value, storage = globalThis.localStorage) {
 // Keyed by material: a material shared by several meshes is recorded once, so the restore is exact.
 const originals = new WeakMap();
 const noRaycast = () => {};
+// Keyed by mesh, not userData: R3F replaces an inline userData prop on re-render (#974).
+const savedRaycasts = new WeakMap();
 
 function materialsOf(mesh) {
 	return Array.isArray(mesh.material) ? mesh.material : mesh.material ? [mesh.material] : [];
@@ -67,11 +69,13 @@ export function applyPoseFade(root, fade, own = 1) {
 			}
 		}
 		if (unpickable && node.raycast !== noRaycast) {
-			node.userData.poseFadeRaycast = node.raycast;
+			if (Object.hasOwn(node, "raycast")) savedRaycasts.set(node, node.raycast);
 			node.raycast = noRaycast;
 		} else if (!unpickable && node.raycast === noRaycast) {
-			node.raycast = node.userData.poseFadeRaycast;
-			delete node.userData.poseFadeRaycast;
+			// Nothing saved means the prototype's method was in use: drop the own property.
+			if (savedRaycasts.has(node)) node.raycast = savedRaycasts.get(node);
+			else delete node.raycast;
+			savedRaycasts.delete(node);
 		}
 	});
 }

package/src/posestudio.jsx

@@ -6,6 +6,7 @@ import { POSE_BONES, normalizeBoneName, primeBindPose } from "./poses.js";
 import { poseThumbnail, warmThumbnailModels } from "./pose-thumbs.js";
 import { IK_TRACKS, MID_TRACKS, ikControlIsExposed } from "./motion/ik.js";
 import { pickIkHit } from "./motion/ik-pick.js";
+import { blockerDistanceTo, exposureProbe } from "./motion/ik-exposure.js";
 import { shouldRefreshIkExposure } from "./use-render-activity.js";
 import { POSER_LAYER } from "./dualview.jsx";
 import { ko } from "./locale.js";
@@ -283,7 +284,7 @@ const FK_ROTATE_SPEED = 5;
  * Every drag move calls `onSolve(kind, trackId, targetWorld)`; the drag end
  * calls `onDragEnd(trackId)` so the caller can key it.
  */
-export function IkHandles({ chains, fkJoints, ikState, enabled, focus, onFocus, onSolve, onDragEnd, selectionOnly = false, onPartPick }) {
+export function IkHandles({ chains, fkJoints, ikState, enabled, focus, onFocus, onSolve, onDragEnd, selectionOnly = false, onPartPick, focusToolsHidden = false, exposureProbeRef }) {
 	const { camera, gl, raycaster, scene } = useThree();
 	const handleRefs = useRef({}); // id -> mesh (all sphere handles)
 	const handleMetaRef = useRef(new Map()); // id -> { track, radius }
@@ -298,6 +299,9 @@ export function IkHandles({ chains, fkJoints, ikState, enabled, focus, onFocus,
 	const blockerRefs = useRef([]);
 	const skinnedBlockerProxiesRef = useRef(new Map());
 	const occlusionRay = useRef(new THREE.Raycaster()).current;
+	// The last pass's blockers, so the fingertip handles can ask the same exposure question (#913).
+	const occludersRef = useRef(null);
+	useEffect(() => { if (exposureProbeRef) exposureProbeRef.current = exposureProbe(camera, occludersRef); }, [exposureProbeRef, camera]);
 	const gizmoRef = useRef(null);
 	const ringRef = useRef(null); // rotation rings around the focused joint
 	const readoutRef = useRef(null);
@@ -405,7 +409,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
@@ -679,28 +683,9 @@ export function IkHandles({ chains, fkJoints, ikState, enabled, focus, onFocus,
 				mesh.getWorldPosition(tmp.viewPoint);
 				const targetDistance = tmp.cameraPos.distanceTo(tmp.viewPoint);
 				tmp.rayDirection.copy(tmp.viewPoint).sub(tmp.cameraPos).normalize();
-				occlusionRay.set(tmp.cameraPos, tmp.rayDirection);
-				occlusionRay.near = 0.001;
-				occlusionRay.far = Math.max(0.001, targetDistance - 0.001);
-				let blockerDistance = occlusionRay.intersectObjects(staticBlockers, false)[0]?.distance;
-				// A coarse cloud of baked skin-surface spheres preserves the
-				// actual animated silhouette without asking Three.js to skin
-				// every triangle once per control ray. Camera-only changes now
-				// test a few cached points; pose changes rebuild the cloud once.
-				for (const proxy of skinnedProxies) {
-					const radiusSq = proxy.radius * proxy.radius;
-					for (const point of proxy.points) {
-						const dx = point.x - tmp.cameraPos.x;
-						const dy = point.y - tmp.cameraPos.y;
-						const dz = point.z - tmp.cameraPos.z;
-						const along = dx * tmp.rayDirection.x + dy * tmp.rayDirection.y + dz * tmp.rayDirection.z;
-						if (along < 0 || along > targetDistance + proxy.radius) continue;
-						const perpendicularSq = dx * dx + dy * dy + dz * dz - along * along;
-						if (perpendicularSq > radiusSq) continue;
-						const distance = Math.max(0, along - Math.sqrt(radiusSq - perpendicularSq));
-						if (distance < (blockerDistance ?? Infinity)) blockerDistance = distance;
-					}
-				}
+				// A coarse cloud of baked skin-surface spheres preserves the animated
+				// silhouette; camera-only changes test a few cached points, pose changes rebuild the cloud once.
+				const blockerDistance = blockerDistanceTo(occlusionRay, tmp.cameraPos, tmp.rayDirection, targetDistance, staticBlockers, skinnedProxies);
 				const visibilityDepth = meta?.track.visibilityDepth ?? (meta?.radius ?? JOINT_R) * 2;
 				const isExposed = ikControlIsExposed(targetDistance, blockerDistance, visibilityDepth);
 				visibilityDetailRef.current.set(id, {
@@ -719,6 +704,7 @@ export function IkHandles({ chains, fkJoints, ikState, enabled, focus, onFocus,
 				tmp.viewPoint.applyMatrix4(camera.matrixWorldInverse);
 				exposureDepthRef.current.set(id, -tmp.viewPoint.z);
 			}
+			occludersRef.current = { blockers: [...blockers] };
 			exposurePerfRef.current.passes += 1;
 			exposurePerfRef.current.raycasts += Object.keys(handleRefs.current).length;
 			exposurePerfRef.current.lastPassMs = performance.now() - passStartedAt;
@@ -757,7 +743,8 @@ export function IkHandles({ chains, fkJoints, ikState, enabled, focus, onFocus,
 		}
 		// A focused control keeps its gizmo and rings even when the body hides it:
 		// the user picked it, and while focused nothing else can take a press.
-		const focusExposed = !!focus;
+		// Finger editing hands the focused hand's space to the fingertip handles: no gizmo, rings or readout.
+		const focusExposed = !!focus && !focusToolsHidden;
 		if (gizmoRef.current) gizmoRef.current.visible = focusExposed;
 		if (ringRef.current) ringRef.current.visible = focusExposed;
 
@@ -947,7 +934,7 @@ const CLICK_PX = 4;
 				handleRefs.current[p.track.id]?.visible &&
 				(handleRefs.current[p.track.id]?.userData.ikExposed !== false || !p.part || p.track.id === focused)
 			);
-			if (focused && !selectionOnly) picks = picks.filter((p) => p.track.id === focused);
+			if (focused && !selectionOnly) picks = picks.filter((p) => p.track.id === focused && !(focusToolsHidden && (p.axisDir || p.part)));
 			else picks = picks.filter((p) => !p.axisDir); // spheres only
 			if (!picks.length) {
 				if (focused) beginDrag("empty", { id: "empty" }, null, null, downXY);
@@ -1059,7 +1046,7 @@ const CLICK_PX = 4;
 		<group>
 			{IK_TRACKS.map((track) => (chains.has(track.id) ? sphereFor(track, "chain", sideColor(track.id), HANDLE_R) : null))}
 			{MID_TRACKS.map((track) => (chains.has(track.chain) ? sphereFor(track, "mid", sideColor(track.id), JOINT_R) : null))}
-			{[...(fkJoints ?? [])].map(([id, joint]) => sphereFor(joint.track, id === "hips" ? "body" : "fk", sideColor(id), id === "hips" ? HANDLE_R : JOINT_R))}
+			{[...(fkJoints ?? [])].filter(([, joint]) => !joint.track.finger).map(([id, joint]) => sphereFor(joint.track, id === "hips" ? "body" : "fk", sideColor(id), id === "hips" ? HANDLE_R : JOINT_R))}
 
 			{gizmoTrack && (
 				<group ref={gizmoRef} renderOrder={999}>
@@ -1141,7 +1128,7 @@ const CLICK_PX = 4;
 					})}
 				</group>
 			)}
-			{rotateTrack && rotationDeg && (
+			{rotateTrack && rotationDeg && !focusToolsHidden && (
 				<group ref={readoutRef}>
 					<Html zIndexRange={[20, 0]} style={{ pointerEvents: "none" }}>
 						<RotationReadout readout={rotationReadout(rotationDeg, rotationDrag)} />

package/src/project-browser.css

@@ -215,6 +215,12 @@
 	box-shadow: inset 0 0 0 var(--start-border-width, 1px) var(--row-divider, #1d1d20);
 }
 
+/* Cast style: a three-up switch under the mode switch. */
+.v2-start-screen .v2-start-mode.cast {
+	grid-template-columns: repeat(3, minmax(0, 1fr));
+	margin-top: var(--sp-1, 8px);
+}
+
 .v2-start-screen .v2-start-mode-option {
 	min-width: var(--start-template-min-width, 0);
 	display: flex;

package/src/project-browser.jsx

@@ -13,8 +13,10 @@ import {
 	requestHandlePermission,
 	storeProjectsDirectory,
 	DEFAULT_PREVIS_MODE,
+	DEFAULT_CAST_STYLE,
 } from "./project.js";
 import { BrandMark, TemplateThumb } from "./project-browser-art.jsx";
+import { CAST_OPTIONS, StartChoiceGroup } from "./project-start-choices.jsx";
 import "./project-browser.css";
 
 const APP_VERSION = packageInfo.version;
@@ -105,6 +107,7 @@ export function ProjectNameDialog({ open, initialName = "My Project", onCancel,
 export default function ProjectBrowser({ currentName, onOpen, onOpenFile, onNew, onClose, startup = false, starters = [], onStarter }) {
 	const starterTemplates = useMemo(() => starters.map(sampleTemplate), [starters]);
 	const [previsMode, setPrevisMode] = useState(DEFAULT_PREVIS_MODE);
+	const [castStyle, setCastStyle] = useState(DEFAULT_CAST_STYLE);
 	const templates = previsMode === "storyboard" ? [] : starterTemplates;
 	const defaultTemplate = starterTemplates[0] ?? NEW_PROJECT;
 	const [activeNav, setActiveNav] = useState(startup ? "new" : "recent");
@@ -211,11 +214,11 @@ export default function ProjectBrowser({ currentName, onOpen, onOpenFile, onNew,
 		const projectName = name.trim();
 		if (!projectName) return;
 		if (selectedTemplate?.starterId) {
-			onStarter?.(selectedTemplate.starterId, projectName, { previsMode: "animation" });
+			onStarter?.(selectedTemplate.starterId, projectName, { previsMode: "animation", castStyle });
 			return;
 		}
 		stagePendingProjectName(projectName);
-		onNew(projectName, { previsMode });
+		onNew(projectName, { previsMode, castStyle });
 	};
 
 	const recentEntries = [
@@ -260,22 +263,10 @@ export default function ProjectBrowser({ currentName, onOpen, onOpenFile, onNew,
 							{activeNav !== "new" && <button type="button" className="v2-start-close x" onClick={onClose} aria-label={ko("Close", "닫기")}>×</button>}
 						</div>
 						{activeNav === "new" && (
-							<div className="v2-start-mode" role="radiogroup" aria-label={ko("Project mode", "프로젝트 모드")} data-testid="start-previs-mode">
-								{MODE_OPTIONS.map((option) => (
-									<button
-										type="button"
-										key={option.id}
-										role="radio"
-										aria-checked={previsMode === option.id}
-										className={`v2-start-mode-option${previsMode === option.id ? " active" : ""}`}
-										data-previs-mode={option.id}
-										onClick={() => choosePrevisMode(option.id)}
-									>
-										<strong>{option.label()}</strong>
-										<span>{option.blurb()}</span>
-									</button>
-								))}
-							</div>
+							<>
+								<StartChoiceGroup label={ko("Project mode", "프로젝트 모드")} testId="start-previs-mode" dataKey="previs-mode" options={MODE_OPTIONS} value={previsMode} onChange={choosePrevisMode} />
+								<StartChoiceGroup label={ko("Cast style", "캐스트 방식")} testId="start-cast-style" dataKey="cast-style" options={CAST_OPTIONS} value={castStyle} onChange={setCastStyle} className="cast" />
+							</>
 						)}
 					</div>
 

package/src/project-start-choices.jsx

@@ -0,0 +1,45 @@
+import { ko } from "./locale.js";
+
+// Which bodies a new project is cast with (castStyle in project.js). The rig
+// is the detailed humanoid, the capsule the quick stand-in; hybrid mixes both
+// and is the default. Either body stays reachable from Add in every style.
+export const CAST_OPTIONS = [
+	{
+		id: "rig",
+		label: () => ko("Humanoid", "휴머노이드"),
+		blurb: () => ko("Detailed previs with X/Y Bot: pose, IK and motion.", "X/Y Bot으로 디테일한 프리비즈: 포즈, IK, 모션."),
+	},
+	{
+		id: "capsule",
+		label: () => ko("Capsule", "캡슐"),
+		blurb: () => ko("Simple previs with capsule figures: path and posture.", "캡슐 인물로 간단한 프리비즈: 경로와 자세."),
+	},
+	{
+		id: "hybrid",
+		label: () => ko("Hybrid", "하이브리드"),
+		blurb: () => ko("Mix both; the agent may use capsules for hard shots.", "둘을 섞어 씁니다. 어려운 샷은 에이전트가 캡슐을 쓸 수 있어요."),
+	},
+];
+
+// One segmented single-choice control on the New view. Each option carries
+// `data-<dataKey>` with its id so tests and styles can address it.
+export function StartChoiceGroup({ label, testId, dataKey, options, value, onChange, className = "" }) {
+	return (
+		<div className={`v2-start-mode${className ? ` ${className}` : ""}`} role="radiogroup" aria-label={label} data-testid={testId}>
+			{options.map((option) => (
+				<button
+					type="button"
+					key={option.id}
+					role="radio"
+					aria-checked={value === option.id}
+					className={`v2-start-mode-option${value === option.id ? " active" : ""}`}
+					{...{ [`data-${dataKey}`]: option.id }}
+					onClick={() => onChange(option.id)}
+				>
+					<strong>{option.label()}</strong>
+					<span>{option.blurb()}</span>
+				</button>
+			))}
+		</div>
+	);
+}

package/src/project.js

@@ -25,9 +25,12 @@ export const PROJECT_VERSION = 5;
 export const PREVIS_MODES = Object.freeze(["storyboard", "animation"]);
 export const DEFAULT_PREVIS_MODE = "animation";
 
-export function normalizePrevisMode(value) {
-	return PREVIS_MODES.includes(value) ? value : DEFAULT_PREVIS_MODE;
-}
+export const normalizePrevisMode = (value) => (PREVIS_MODES.includes(value) ? value : DEFAULT_PREVIS_MODE);
+// Which bodies the project is cast with: rigged humanoids for detailed previs,
+// capsule figures for simple previs, or a mix. A file without the field
+// predates the choice and already holds a rig character, so it reads as hybrid.
+export const CAST_STYLES = Object.freeze(["rig", "capsule", "hybrid"]), DEFAULT_CAST_STYLE = "hybrid";
+export const normalizeCastStyle = (value) => (CAST_STYLES.includes(value) ? value : DEFAULT_CAST_STYLE);
 export const PROJECT_EXTENSION = ".cclayproject";
 export const WORKFLOW_VERSION = 1;
 export const WORKFLOW_STORAGE_KEY = "cozyclay.workflow.v1";
@@ -301,7 +304,7 @@ function readEmbeddedAssets(value, report) {
  * assetRef references them. Throws `resources-too-large` when the whole
  * manifest exceeds its budget.
  */
-export function createProjectDocument({ scenesDocument, workspaceLayout, customPoses, name, previsMode, assets, savedAt, workflow }) {
+export function createProjectDocument({ scenesDocument, workspaceLayout, customPoses, name, previsMode, castStyle, assets, savedAt, workflow }) {
 	const assetRecords = new Map();
 	for (const record of Array.isArray(assets) ? assets : []) {
 		const asset = embeddedAsset(record);
@@ -323,7 +326,7 @@ export function createProjectDocument({ scenesDocument, workspaceLayout, customP
 		kind: "project",
 		version: PROJECT_VERSION,
 		name: typeof name === "string" && name.trim() ? name.trim() : "Untitled",
-		previsMode: normalizePrevisMode(previsMode),
+		previsMode: normalizePrevisMode(previsMode), castStyle: normalizeCastStyle(castStyle),
 		...(Number.isFinite(savedAt) && savedAt > 0 ? { savedAt } : {}),
 		scenes: scenesDocument,
 		workspace: workspaceLayout ?? null,
@@ -355,7 +358,7 @@ export function buildAnimationProjectFromStoryboard(project) {
 		workspaceLayout: structuredClone(project?.workspaceLayout ?? null),
 		customPoses: structuredClone(project?.customPoses ?? []),
 		name: `${project?.name || "Untitled"} - ${ko("Animation", "애니메이션")}`,
-		previsMode: "animation",
+		previsMode: "animation", castStyle: project?.castStyle,
 				assets: project?.assets ?? [],
 		workflow: structuredClone(project?.workflow ?? createWorkflowGraph()),
 		savedAt: Date.now(),
@@ -367,8 +370,8 @@ export function buildAnimationProjectFromStoryboard(project) {
  * problems?, project? }. Invalid embedded records are skipped, each one
  * reported as a warning string and a `{ kind, id, code, message }` problem.
  * v2/v3 files carry images at the top-level `assets`; v4 moves everything
- * under `resources`; v5 adds the top-level `previsMode` (absent or unknown
- * reads as the default). Older files are read as-is, never rewritten.
+ * under `resources`; v5 adds the top-level `previsMode` and `castStyle`
+ * (absent or unknown reads as the default). Older files are read as-is, never rewritten.
  */
 export function readProjectDocument(raw) {
 	let parsed;
@@ -402,7 +405,7 @@ export function readProjectDocument(raw) {
 		problems,
 		project: {
 			name: typeof parsed.name === "string" && parsed.name.trim() ? parsed.name.trim() : "Untitled",
-			previsMode: normalizePrevisMode(parsed.previsMode),
+			previsMode: normalizePrevisMode(parsed.previsMode), castStyle: normalizeCastStyle(parsed.castStyle),
 			savedAt: Number.isFinite(parsed.savedAt) && parsed.savedAt > 0 ? parsed.savedAt : null,
 			scenesDocument: { version: scenes.version, activeSceneId: scenes.activeSceneId ?? null, scenes: scenes.scenes },
 			workspaceLayout: parsed.workspace && typeof parsed.workspace === "object" ? parsed.workspace : null,
@@ -549,17 +552,18 @@ export function loadProjectSession(storage = globalThis.localStorage) {
 		const value = JSON.parse(storage?.getItem(PROJECT_SESSION_KEY) || "null");
 		if (!value || typeof value !== "object") return null;
 		const name = typeof value.name === "string" ? value.name.trim() : "";
-		return name ? { name, previsMode: normalizePrevisMode(value.previsMode), updatedAt: Number.isFinite(value.updatedAt) ? value.updatedAt : 0 } : null;
+		return name ? { name, previsMode: normalizePrevisMode(value.previsMode), castStyle: normalizeCastStyle(value.castStyle), updatedAt: Number.isFinite(value.updatedAt) ? value.updatedAt : 0 } : null;
 	} catch {
 		return null;
 	}
 }
 
-export function storeProjectSession(name, previsMode = DEFAULT_PREVIS_MODE, storage = globalThis.localStorage) {
+// `identity` is the previs mode, or `{ previsMode, castStyle }`.
+export function storeProjectSession(name, identity = DEFAULT_PREVIS_MODE, storage = globalThis.localStorage) {
 	const normalized = typeof name === "string" ? name.trim() : "";
 	if (!normalized) return false;
 	try {
-		storage?.setItem(PROJECT_SESSION_KEY, JSON.stringify({ name: normalized, previsMode: normalizePrevisMode(previsMode), updatedAt: Date.now() }));
+		storage?.setItem(PROJECT_SESSION_KEY, JSON.stringify({ name: normalized, previsMode: normalizePrevisMode(identity?.previsMode ?? identity), castStyle: normalizeCastStyle(identity?.castStyle), updatedAt: Date.now() }));
 		return true;
 	} catch {
 		return false;

package/src/proxy-figure-shape.js

@@ -0,0 +1,11 @@
+// Capsule figure dimensions in metres, shared by the renderer
+// (proxy-figure.jsx) and the rig-free bounds (character-kind.js).
+export const PROXY_BODY_RADIUS = 0.22;
+export const PROXY_BODY_HEIGHT = 1.45;
+export const PROXY_HEAD_RADIUS = 0.12;
+// Head centre sits this far above the top of the body or torso.
+export const PROXY_HEAD_LIFT = 0.13;
+// Sit is an L: a vertical torso at the hip and one leg capsule on the floor
+// reaching this far forward of the hip, along the way the figure faces (+z).
+export const PROXY_SIT_TORSO_HEIGHT = 0.85;
+export const PROXY_SIT_LEG_REACH = 0.55;

package/src/proxy-figure.jsx

@@ -1,10 +1,20 @@
 import { memo, useEffect, useMemo } from "react";
 import * as THREE from "three";
 import { defaultCharacterTint } from "./app-stage.jsx";
+import {
+	PROXY_BODY_HEIGHT as BODY_HEIGHT, PROXY_BODY_RADIUS as BODY_RADIUS, PROXY_HEAD_LIFT,
+	PROXY_HEAD_RADIUS as HEAD_RADIUS, PROXY_SIT_LEG_REACH, PROXY_SIT_TORSO_HEIGHT,
+} from "./proxy-figure-shape.js";
 
-const BODY_RADIUS = 0.22;
-const BODY_HEIGHT = 1.45;
-const HEAD_RADIUS = 0.12;
+function addPart(group, geometry, material, position) {
+	const mesh = new THREE.Mesh(geometry, material);
+	mesh.position.set(...position);
+	mesh.castShadow = true;
+	mesh.receiveShadow = true;
+	mesh.frustumCulled = false;
+	group.add(mesh);
+	return mesh;
+}
 
 export function proxyYaw(rot, posture = "stand") {
 	return (rot * Math.PI) / 180 + (posture === "lie" ? Math.PI : 0);
@@ -19,8 +29,8 @@ export const ProxyFigure = memo(function ProxyFigure({
 	pickId,
 	selected,
 }) {
-	const bodyHeight = posture === "sit" ? BODY_HEIGHT * 0.6 : BODY_HEIGHT;
-	const headY = bodyHeight + 0.13;
+	const seated = posture === "sit";
+	const bodyHeight = seated ? PROXY_SIT_TORSO_HEIGHT : BODY_HEIGHT;
 	const model = useMemo(() => {
 		const bodyMaterial = new THREE.MeshStandardMaterial({
 			color: tint ?? defaultCharacterTint({ model: "proxy-figure" }, 0),
@@ -29,20 +39,17 @@ export const ProxyFigure = memo(function ProxyFigure({
 			envMapIntensity: 0.35,
 		});
 		const group = new THREE.Group();
-		const body = new THREE.Mesh(new THREE.CapsuleGeometry(BODY_RADIUS, bodyHeight - BODY_RADIUS * 2, 12, 20), bodyMaterial);
-		body.position.y = bodyHeight / 2;
-		body.castShadow = true;
-		body.receiveShadow = true;
-		body.frustumCulled = false;
-		group.add(body);
-		const head = new THREE.Mesh(new THREE.SphereGeometry(HEAD_RADIUS, 16, 12), bodyMaterial);
-		head.position.y = headY;
-		head.castShadow = true;
-		head.receiveShadow = true;
-		head.frustumCulled = false;
-		group.add(head);
+		addPart(group, new THREE.CapsuleGeometry(BODY_RADIUS, bodyHeight - BODY_RADIUS * 2, 12, 20), bodyMaterial, [0, bodyHeight / 2, 0]);
+		addPart(group, new THREE.SphereGeometry(HEAD_RADIUS, 16, 12), bodyMaterial, [0, bodyHeight + PROXY_HEAD_LIFT, 0]);
+		if (seated) {
+			// Legs on the floor from behind the hip to PROXY_SIT_LEG_REACH ahead of
+			// it, along local +z: the way the figure (and a rig at the same rot) faces.
+			const legs = addPart(group, new THREE.CapsuleGeometry(BODY_RADIUS, PROXY_SIT_LEG_REACH - BODY_RADIUS, 12, 20), bodyMaterial,
+				[0, BODY_RADIUS, (PROXY_SIT_LEG_REACH - BODY_RADIUS) / 2]);
+			legs.rotation.x = Math.PI / 2;
+		}
 		return group;
-	}, [bodyHeight, headY, tint]);
+	}, [bodyHeight, seated, tint]);
 	useEffect(() => () => {
 		const materials = new Set();
 		model.traverse(node => {