cozyclay 3.0.3 → 3.1.1

package/src/cuts.js

@@ -127,6 +127,17 @@ export function addShotAtFrame(shots, frame, frameCount, currentFraming, duratio
 	return [...list, createShot(`Shot ${list.length + 1}`, target, endFrame, keys)].sort((a, b) => a.startFrame - b.startFrame);
 }
 
+/** Add Shot when the take has no free time left: the take grows by one default
+ * shot at its end and the new shot fills that, so the button never silently does
+ * nothing. Existing shots are untouched. Null past maxFrameCount. */
+export function appendShotGrowingTake(shots, frameCount, currentFraming, maxFrameCount) {
+	const list = Array.isArray(shots) ? shots : [];
+	const startFrame = Math.max(frameNumber(frameCount, 1), ...list.map((shot) => shot.endFrame + 1));
+	const grownCount = startFrame + DEFAULT_SHOT_FRAMES;
+	if (grownCount > maxFrameCount) return null;
+	return { shots: addShotAtFrame(list, startFrame, grownCount, currentFraming), frameCount: grownCount };
+}
+
 export function resizeShot(shots, shotId, edge, rawFrame, frameCount) {
 	const shot = shotById(shots, shotId);
 	if (edge !== "start" && edge !== "end") return shots;

package/src/domains/cast.js

@@ -546,7 +546,7 @@ export function useCast(appContext) {
 		return current.length;
 	}
 
-	/** ARDY-demo style authoring: each empty-floor press in the Shot view drops
+	/** Click-to-place authoring: each empty-floor press in the Shot view drops
 	    the next waypoint where it was clicked; the frame gap comes from walking
 	    distance. The bird's-eye board selects and drags existing waypoints. */
 	function addFloorWaypoint(point) {
@@ -715,7 +715,8 @@ export function useCast(appContext) {
 	}
 	function undoScene() {
 		const receipt = appContext.bus.run('edit.undo');
-		if (receipt.status === 'noop') appContext.notify(ko("Nothing to undo", "실행 취소할 작업이 없어요"));
+		// A refusal says why: the last edit belongs to a running task (parallel tasks), which its own card undoes.
+		if (receipt.status === 'noop' || receipt.ok === false) appContext.notify(receipt.ok === false ? ko(receipt.message ?? "Undo was refused", `실행 취소 불가: ${receipt.message ?? ""}`) : ko("Nothing to undo", "실행 취소할 작업이 없어요"));
 		return receipt;
 	}
 	function redoScene() {

package/src/domains/motion.js

@@ -29,8 +29,8 @@ import {
 } from "../motion/ik.js";
 import * as THREE from "three";
 import { StudioProtocolError } from "../studio-agent-protocol.js";
-
 import { applyTakeFrame } from "../motion3/playback.js";
+import { advancePlayback, installPlaybackApplier } from "./playback.js";
 import { isKo, ko } from "../locale.js";
 import { isProxyFigure } from "../scenes.js";
 import { refuseRigOnly } from "../character-kind.js";
@@ -625,15 +625,7 @@ export function useMotion(appContext) {
 
 
 	function advanceFrame(steps = 1) {
-		const count = Math.max(1, Math.floor(steps));
-		const previewEnd = appContext.shared.cameraPreviewEndRef.current;
-		if (previewEnd != null && appContext.shared.tlFrameRef.current + count >= previewEnd) {
-			appContext.shared.cameraPreviewEndRef.current = null;
-			appContext.shared.setTlFrame(previewEnd);
-			appContext.shared.setTlPlaying(false);
-			return;
-		}
-		appContext.shared.setTlFrame((f) => (f + count) % appContext.shared.frameCountRef.current);
+		advancePlayback(appContext.shared, steps);
 	}
 
 	function stepFrame(delta) {
@@ -677,6 +669,7 @@ export function useMotion(appContext) {
 			appContext.shared.poseMemberAtFrame(appContext.shared.rigs[entry.id], entry.sessionMotion, appContext.shared.ikStatesRef.current.get(entry.id), frame, IK_CORRECTION_BLEND_FRAMES);
 		}
 	};
+	installPlaybackApplier(appContext, motion, poseOtherCastMembers, ikEvaluate, IK_CORRECTION_BLEND_FRAMES);
 
 	function toggleIkMode() {
 		const next = !ikMode;

package/src/domains/playback.js

@@ -0,0 +1,32 @@
+import { advancePlaybackFrame, registerPlaybackFrameApplier } from "../motion/playback-frame-store.js";
+
+function createPlaybackApplier(appContext, motion, poseOtherCastMembers, ikEvaluate, blendFrames) {
+	return (frame) => {
+		appContext.shared.tlFrameRef.current = frame;
+		appContext.shared.propFrameRef.current = frame;
+		appContext.patchTimeline({ currentFrame: frame });
+		if (appContext.shared.activeRig) appContext.shared.poseMemberAtFrame(appContext.shared.activeRig, motion, null, frame);
+		poseOtherCastMembers(frame);
+		const state = appContext.shared.ikStateRef.current;
+		if (!appContext.shared.posing && state?.chains && (appContext.shared.ikMode || state.keys.size > 0)) {
+			ikEvaluate(state.chains, state, frame, state.fkJoints, motion ? blendFrames : 0);
+		}
+	};
+}
+
+export function installPlaybackApplier(...args) {
+	return registerPlaybackFrameApplier(createPlaybackApplier(...args));
+}
+
+// A camera-shot preview stops at its shot's end; otherwise the playhead wraps.
+export function advancePlayback(shared, steps) {
+	const count = Math.max(1, Math.floor(steps));
+	const previewEnd = shared.cameraPreviewEndRef.current;
+	if (previewEnd != null && shared.tlFrameRef.current + count >= previewEnd) {
+		shared.cameraPreviewEndRef.current = null;
+		shared.setTlFrame(previewEnd);
+		shared.setTlPlaying(false);
+		return;
+	}
+	advancePlaybackFrame(shared.frameCountRef.current, count);
+}

package/src/domains/scenes.js

@@ -208,9 +208,8 @@ export function useScenes(appContext) {
 	// A first-run author should choose a document (or explicitly start a named
 	// local draft). Keep this as a light startup sheet so the studio remains
 	// inspectable while the choice is pending; it never traps the topbar.
-	// ?tutorial=camera opens the starter scene itself (#209), so the chooser is
-	// suppressed the same way a ?scene= launch suppresses it.
-	const [projectStartupOpen, setProjectStartupOpen] = useState(() => !appContext.shared.playgroundMode && !appContext.shared.cameraTutorialQuery && !playgroundSceneUrl(globalThis.location?.search) && !loadProjectSession()?.name);
+	// A ?scene= launch opens its starter instead of the chooser.
+	const [projectStartupOpen, setProjectStartupOpen] = useState(() => !appContext.shared.playgroundMode && !playgroundSceneUrl(globalThis.location?.search) && !loadProjectSession()?.name);
 
 	const [projectManifest, setProjectManifest] = useState({ items: [], totals: { embedded: 0, external: 0, missing: 0, bytes: 0 }, missing: [] });
 
@@ -400,10 +399,6 @@ export function useScenes(appContext) {
 		if (!["valid", "migrated"].includes(checked.status)) throw new StudioProtocolError("INVALID_ARGUMENT", "Invalid project scene document.");
 		project = { ...project, scenesDocument: checked.document };
 		appContext.shared.studioDocumentEpochRef.current = crypto.randomUUID();
-		appContext.shared.tutorialProjectEpochRef.current += 1;
-		appContext.shared.tutorialSeedEpochRef.current = null;
-		appContext.shared.setTutorialSeedPending(false);
-		appContext.shared.setCameraTutorialHandoff(null);
 		appContext.shared.exportShotIdRef.current = null;
 		const source = project.scenesDocument;
 				// A project FILE carries its own scene document and never passes the
@@ -425,25 +420,16 @@ export function useScenes(appContext) {
 		domain.setDirty(false);
 		storeProjectSession(project.name, projectPrevisMode);
 		setProjectStartupOpen(false);
-		// Whatever document this is, it is no longer the scene the tutorial opened
-		// for itself; startCameraTutorial re-arms the flag after its own open.
-		appContext.shared.tutorialStarterRef.current = false;
 		setProjectManifest(resourceManifest({ scenesDocument: doc, workflow: resolvedWorkflow, poseLibrary: mergedCustomPoses, assets: project.assets ?? [], workflowOutputRefs }));
 		track("project:opened", { age_bucket: bucketProjectAge(Date.now() - (project.savedAt ?? Date.now())) });
 	}
 
 	/** Open a bundled starter scene as a fresh, saveable project. Used by the
-	 * first-run dialog and by `npx cozyclay --scene <id>` (`?scene=`), which is
-	 * how the landing-page tutorial hands people into the local studio. */
+	 * first-run dialog and by `npx cozyclay --scene <id>` (`?scene=`). */
 	async function openStarterScene(id, source = "starter", context = null, name = null) {
 		if (source === "starter" && domain.dirtyStore.read("projectDirty") && !window.confirm(ko("Discard unsaved changes and start a new project?", "저장되지 않은 변경사항을 버리고 새 프로젝트를 시작할까요?"))) return false;
-		const before = source === "tutorial" ? collectProjectSnapshot("Tutorial") : null;
-		const epoch = appContext.shared.tutorialProjectEpochRef.current;
 		const url = playgroundSceneUrl(`?scene=${encodeURIComponent(id)}`);
 		const project = url ? await fetchSceneProject(url) : null;
-		// A pending tutorial fetch has no authority over work authored/opened
-		// while it was loading, including an unnamed project.
-		if (source === "tutorial" && (epoch !== appContext.shared.tutorialProjectEpochRef.current || before !== collectProjectSnapshot("Tutorial"))) return false;
 		if (!project) {
 			appContext.notify(ko("That starter scene is not in this build", "이 빌드에는 그 시작 장면이 없어요"));
 			return false;
@@ -596,11 +582,6 @@ export function useScenes(appContext) {
 	}
 
 	function openScene(scene, nextScenes) {
-		appContext.shared.tutorialProjectEpochRef.current += 1;
-		appContext.shared.tutorialSeedEpochRef.current = null;
-		appContext.shared.setTutorialSeedPending(false);
-		appContext.shared.setCameraTutorial(false);
-		appContext.shared.setCameraTutorialHandoff(null);
 		appContext.shared.exportShotIdRef.current = null;
 		appContext.shared.studioSceneEpochRef.current = crypto.randomUUID();
 		const shotState = restoredShotState(scene);

package/src/domains/shots.js

@@ -1,6 +1,7 @@
 import { useEffect, useRef, useState } from 'react';
 import { aimAt } from '../controls.jsx';
 import { PRESETS, DEFAULT_DURATION_S, TIMELINE_FPS } from '../app-stage.jsx';
+import { usePlaybackFrameState } from '../motion/playback-frame-store.js';
 import { CAMERA_MOVES, SUBJECT_HEIGHT_M, focalMmToFov, fovToFocalMm } from '../shot.js';
 import { CAMERA_PRESETS, cameraPresetFraming } from '../camera-move.js';
 import { createDocumentStore } from '../document-store.js';
@@ -236,9 +237,8 @@ export function useShots(appContext) {
   const [moveFollow] = useState(true);
   const [railDraw, setRailDraw] = useState(false);
   const [craneSelectedIndex, setCraneSelectedIndex] = useState(null);
-  const [tlFrame, setTlFrame] = useState(0);
-  const [tlFps, setTlFps] = useState(TIMELINE_FPS);
-  const activeShotIdx = shotIndexAtFrame(shots, tlFrame), activeShot = shots[activeShotIdx] ?? null;
+  const [tlFrame, setTlFrameState] = useState(0), [tlFps, setTlFps] = useState(TIMELINE_FPS);
+  const { setTlFrame, commitPlaybackFrame, activeShotIdx, activeShot } = usePlaybackFrameState({ frameCount: tlFrameCount, setReactFrame: setTlFrameState, shots });
   const cameraKeys = activeShot?.cameraKeys ?? [], activeCamera = createCameraBlock(activeShot?.camera);
   const craneActive = !!activeCamera.craneHeight, cameraRail = activeCamera.cameraRail;
   const activeShotDuration = activeShot ? activeShot.endFrame - activeShot.startFrame + 1 : 0;
@@ -364,7 +364,7 @@ export function useShots(appContext) {
       const travel = Math.ceil(curve.length / speed * tlFps) + Math.round(tlFps * 0.5);
       const endFrame = Math.min(tlFrameCount - 1, activeShot.startFrame + Math.max(travel, activeShot.endFrame - activeShot.startFrame));
       setTimelineShotRange(activeShot.id, activeShot.startFrame, endFrame);
-      // The landing tutorial's last step is pressing ▶ (#602): open the player
+      // In the landing playground a drawn rail opens the player
       // on the shot camera, but leave playback to the visitor.
       appContext.shared.enterPreview(); appContext.shared.setTlPlaying(false); setTlFrame(activeShot.startFrame);
       appContext.notify(isKo ? '레일 완성 — 샷 카메라 시점으로 전환했습니다. ▶ 로 재생, Esc 로 복귀' : 'Rail drawn — you are looking through the shot camera. Press ▶ to ride it; Esc goes back to flying.'); return;
@@ -418,7 +418,7 @@ export function useShots(appContext) {
   }
   return { ...domain, shots, setShots, editShots, fovDeg, setFovDeg, cameraMove, customMove, startupShotState,
     movePlaying, setMovePlaying, moveFollow, railDraw, setRailDraw, craneSelectedIndex, setCraneSelectedIndex,
-    tlFrame, setTlFrame, tlFrameCount, setTlFrameCount, tlFps, setTlFps, activeShotIdx, activeShot, cameraKeys,
+    tlFrame, setTlFrame, commitPlaybackFrame, tlFrameCount, setTlFrameCount, tlFps, setTlFps, activeShotIdx, activeShot, cameraKeys,
     activeCamera, craneActive, cameraRail, activeShotDuration, hasCameraKeys, changeActiveCamera, changeShotTargetModel,
     syncActiveCameraFraming, commitManualCameraFraming, beginCameraFramingGesture, beginTimelineEditGesture,
     setShotCameraRail, clearShotCameraRail, changeCameraRail, addCameraKeyframe, moveCameraKeyframe, removeCameraKeyframe, clearMove,

package/src/dualview.jsx

@@ -1,6 +1,8 @@
 import { useEffect, useMemo, useRef } from "react";
 import { useFrame, useThree } from "@react-three/fiber";
 import * as THREE from "three";
+import { fitAspect } from "./shot-frame.js";
+import { updateVisibleViewOffsets } from "./viewport-visible-rect.js";
 
 /**
  * Two live viewports out of one scene.
@@ -104,17 +106,6 @@ const EDGE_FRAGMENT = `
 	}
 `;
 
-/** largest centred sub-rect of `rect` with the given aspect */
-export function fitAspect(rect, aspect) {
-	let w = rect.w;
-	let h = w / aspect;
-	if (h > rect.h) {
-		h = rect.h;
-		w = h * aspect;
-	}
-	return { x: rect.x + (rect.w - w) / 2, y: rect.y + (rect.h - h) / 2, w, h };
-}
-
 export function DualRender({ stageRef, mainRef, insetRef, shotPreviewRef, shotCamRef, planCamRef, poserCamRef, editorCamRef, ikMode = false, planIsMain, playMode = false, lookThrough = false, insetCollapsed = false, planZoom = 1, shotAspect = SHOT_ASPECT, editorLook = false }) {
 	const invalidate = useThree((state) => state.invalidate);
 	const lastPoserPose = useRef({ position: new THREE.Vector3(), quaternion: new THREE.Quaternion(), valid: false });
@@ -245,6 +236,7 @@ export function DualRender({ stageRef, mainRef, insetRef, shotPreviewRef, shotCa
 			return { x: r.left - base.left, y: r.top - base.top, w: r.width, h: r.height };
 		};
 		const mainRect = rectOf(mainRef.current);
+		updateVisibleViewOffsets({ editorCam, poserCam, canvas: gl.domElement.getBoundingClientRect(), aspect: mainRect.w / mainRect.h });
 		// A collapsed inset is just its tag pill: skip the whole inset pass
 		// instead of drawing a squished viewport into it.
 		const insetRect = insetCollapsed ? { x: 0, y: 0, w: 0, h: 0 } : rectOf(insetRef.current);
@@ -451,8 +443,6 @@ export function DualRender({ stageRef, mainRef, insetRef, shotPreviewRef, shotCa
 				// IK mode: the main pane is the poser working view (free navigation,
 				// handle layer visible); the inset is the FROZEN shot camera — the
 				// separate camera-placement screen the framing lives on.
-				poserCam.aspect = mainRect.w / mainRect.h;
-				poserCam.updateProjectionMatrix();
 				drawEditorPane(poserCam, mainRect, null, !navigatingCamera);
 				if (!navigatingCamera || redrawFrozenPanes) drawVisibleInset(shotCam, insetRect, fitAspect(insetRect, shotAspect), !navigatingCamera);
 				drawPreviewCard();
@@ -465,8 +455,6 @@ export function DualRender({ stageRef, mainRef, insetRef, shotPreviewRef, shotCa
 				// navigation that never touches the recording. The shot camera only
 				// appears in its own preview pane, framed to the export aspect and
 				// stripped of editing chrome, exactly like an exported frame.
-				editorCam.aspect = mainRect.w / mainRect.h;
-				editorCam.updateProjectionMatrix();
 				// A right-drag is a camera gesture even with IK off. Keep the main
 				// image readable while the camera is moving by deferring the expensive
 				// edge/ink pass until the gesture ends; the plan inset stays frozen.
@@ -479,6 +467,14 @@ export function DualRender({ stageRef, mainRef, insetRef, shotPreviewRef, shotCa
 				// can fly the recording lens with the same bindings as the free camera.
 				// The QA hook (`window.__cozyclay.setLookThrough`) draws the same path.
 				// Look-through is the recording lens: it keeps the authored stage.
+				// The pane is the open stage less the rails (shell.css), so the
+				// canvas around it is bars too: clear it, or the last full-canvas
+				// draw stays there and reads as picture the export does not have.
+				if (lookThrough) {
+					gl.setScissorTest(false);
+					gl.setClearColor(letterbox, 1);
+					gl.clear(true, true, false);
+				}
 				draw(shotCam, shotPane, fitAspect(shotPane, shotAspect), !navigatingCamera);
 				if (!navigatingCamera || redrawFrozenPanes) drawVisibleInset(planCam, planPane, null, false);
 				drawPreviewCard();

package/src/hierarchy-panel.css

@@ -326,13 +326,27 @@
 	outline: var(--outliner-border-width, 1px) solid var(--select, #e8a33d);
 }
 
+/* The context menu is portaled to <body> inside this layer, which keeps the
+   `.v2-outliner` style scope without a box of its own (hierarchy-panel.jsx).
+   It and the scene switcher's list share the popover tokens (themes.css). */
+.v2-outliner.v2-outliner-layer {
+	display: contents;
+}
+
+.v2-outliner .hierarchy-context-menu,
+.dropdown-menu.hierarchy-scene-menu {
+	z-index: var(--z-popover, 90);
+	border: var(--outliner-border-width, 1px) solid var(--popover-border, var(--row-divider, #1d1d20));
+	border-radius: var(--popover-radius, 6px);
+	background: var(--popover-surface, var(--surface-raised, #1e1e21));
+	-webkit-backdrop-filter: var(--popover-blur, none);
+	backdrop-filter: var(--popover-blur, none);
+	box-shadow: var(--popover-shadow, 0 8px 24px rgba(0, 0, 0, .45));
+}
+
 .v2-outliner .hierarchy-context-menu {
 	min-width: var(--outliner-menu-width, 220px);
 	padding: var(--outliner-menu-padding, 4px);
-	border: var(--outliner-border-width, 1px) solid var(--row-divider, #1d1d20);
-	border-radius: var(--r-2, 6px);
-	background: var(--surface-raised, #1e1e21);
-	box-shadow: 0 var(--sp-1, 8px) var(--sp-3, 16px) var(--overlay, rgba(12,12,13,.78));
 }
 
 .v2-outliner .hierarchy-context-item {

package/src/hierarchy-panel.jsx

@@ -1,9 +1,11 @@
 import { useEffect, useMemo, useRef, useState } from "react";
+import { createPortal } from "react-dom";
 import { ko, isKo } from "./locale.js";
 import { buildHierarchyNodes } from "./hierarchy-model.js";
 import { sceneObjectIdFromHierarchy } from "./scene-objects.js";
 import { CatalogueEntries, displayObjectLabel } from "./object-catalog.jsx";
 import { Dropdown } from "./ui.jsx";
+import { usePopover } from "./popover.js";
 import { isImeComposing } from "./ime.js";
 import "./hierarchy-panel.css";
 
@@ -97,6 +99,7 @@ function ScenePill({ scenes, activeSceneId, onSceneSelect, onSceneCreate, onRena
 				value={activeSceneId}
 				options={options}
 				ariaLabel={ko("Select scene", "장면 선택")}
+				menuClassName="hierarchy-scene-menu"
 				onChange={(value) => {
 					if (value === NEW_SCENE_OPTION) onSceneCreate?.();
 					else if (value !== activeSceneId) onSceneSelect?.(value);
@@ -194,11 +197,9 @@ function RowContextMenu({ menu, onClose, onAction, onAddObject }) {
 	const [deleteArmed, setDeleteArmed] = useState(false);
 	useEffect(() => setDeleteArmed(false), [menu]);
 
+	usePopover(menu, onClose, [rootRef]);
 	useEffect(() => {
 		if (!menu) return undefined;
-		const onDocDown = (event) => {
-			if (rootRef.current && !rootRef.current.contains(event.target)) onClose();
-		};
 		const onKey = (event) => {
 			if (event.key !== "Escape") return;
 			// Capture phase + stopImmediatePropagation: closing the menu must
@@ -206,12 +207,8 @@ function RowContextMenu({ menu, onClose, onAction, onAddObject }) {
 			event.stopImmediatePropagation();
 			onClose();
 		};
-		document.addEventListener("mousedown", onDocDown);
 		window.addEventListener("keydown", onKey, true);
-		return () => {
-			document.removeEventListener("mousedown", onDocDown);
-			window.removeEventListener("keydown", onKey, true);
-		};
+		return () => window.removeEventListener("keydown", onKey, true);
 	}, [menu, onClose]);
 
 	if (!menu) return null;
@@ -221,8 +218,11 @@ function RowContextMenu({ menu, onClose, onAction, onAddObject }) {
 		left: Math.max(4, Math.min(menu.x, window.innerWidth - 244)),
 		top: Math.max(4, Math.min(menu.y, window.innerHeight - menu.height)),
 	};
-	return (
-		<div className="hierarchy-context-menu" role="menu" style={style} ref={rootRef}>
+	// Portaled: the glass column clips and blurs its children, so an in-place
+	// menu was cut at the column edge and sat under body-level popovers. The
+	// display:contents layer keeps the `.v2-outliner` style scope.
+	return createPortal(
+		<div className="v2-outliner v2-outliner-layer"><div className="hierarchy-context-menu" role="menu" style={style} ref={rootRef}>
 			{menu.kind === "scene" ? (
 				<>
 					<button type="button" role="menuitem" className="hierarchy-context-item" onClick={() => onAction("rename", menu.id)}>
@@ -292,7 +292,8 @@ function RowContextMenu({ menu, onClose, onAction, onAddObject }) {
 			) : (
 				<CatalogueEntries onPick={onAddObject} />
 			)}
-		</div>
+		</div></div>,
+		document.body,
 	);
 }
 

package/src/kits/held.js

@@ -38,9 +38,10 @@ export const bat = {
 
 export const ball = {
 	label: "Baseball", prop: "ballGrip",
-	description: "7.4 cm baseball held in the right fingers",
+	description: "7.4 cm baseball held in the right palm and fingers",
 	props: { ballGrip: { hand: "r", origin: RIGHT_FINGERS, points: { centre: [0, 0, -0.035] } } },
-	carry: { prop: "ballGrip", at: [0, 0, -0.035], along: [0, 1, 0] },
+	// no pinned point: it rests against the palm where the hand takes it and the fingers close round it (motion3 seat.js)
+	carry: { prop: "ballGrip", grasp: "spherical" },
 	parts: [{ role: "body", kind: "sphere", at: [0, -0.037, 0], scale: [0.074, 0.074, 0.074], color: "#f1ede3" }],
 };
 

package/src/light-blockers.js

@@ -19,9 +19,9 @@
 import { practicalShadows, withShadowCapWarnings } from "./object-look.js";
 import { isEffectivelyHidden } from "./object-hidden.js";
 
-/** Renderers whose meshes cast shadows (props.jsx, set-pieces.jsx, sculpts, imported meshes).
+/** Renderers whose meshes cast shadows (props.jsx primitives, sculpts, imported meshes).
  * A plane and a cutout are cards: nothing can be inside them. */
-const CASTERS = new Set(["cube", "sphere", "capsule", "cylinder", "cone", "car", "chair", "small-plane", "sculpt", "mesh"]);
+const CASTERS = new Set(["cube", "sphere", "capsule", "cylinder", "cone", "sculpt", "mesh"]);
 const DEG = Math.PI / 180;
 const EPS = 1e-6;
 const MAX_WARNINGS = 4;

package/src/main.jsx

@@ -12,6 +12,7 @@ import { registerPwa } from "./pwa.js";
 import { LOCALE } from "./locale.js";
 import { initAnalytics } from "./analytics.js";
 import { fetchPlaygroundProject, isPlaygroundEmbed, playgroundSceneUrl, stashPlaygroundProject } from "./playground.js";
+import { preloadBodies } from "./motion3/body.js";
 
 registerPwa();
 void initAnalytics();
@@ -34,6 +35,10 @@ async function boot() {
 			</ErrorBoundary>
 		</StrictMode>,
 	);
+	// The motion compiler's body fits are not in the first-load bundle (motion3/body.js): fetch them once
+	// the first screen is up, so a saved take compiled on this thread does not have to wait for them.
+	const idle = globalThis.requestIdleCallback ?? (run => setTimeout(run, 200));
+	idle(() => preloadBodies().catch(error => console.warn("[cozyclay] could not preload the motion body fits", error)));
 }
 
 void boot();

package/src/material-look.js

@@ -0,0 +1,189 @@
+/**
+ * Material presets as three.js materials (the table is material-presets.js),
+ * one factory for sculpt parts and plain primitives. `lookMaterial(look)`
+ * mints a material per call, which the caller owns and disposes; its detail
+ * comes from pattern textures (material-textures.js) generated once per
+ * pattern on first draw and shared by every material that uses it, so no one
+ * owner may free them (material.dispose() leaves uniforms alone).
+ *
+ * Mapping is triplanar in the mesh's own frame, measured in metres (the
+ * frame's scale is divided back out): the pattern rides with a moving prop,
+ * keeps its size on a stretched cube and never reads a geometry's UVs, which
+ * on a blob's remapped UV sphere would pinch at the poles. A directional
+ * pattern (grain, thatch, brick courses) runs along the axis the vertex
+ * shader picks from the part's size and its tilt in the world. The shader
+ * text is the same for every preset (only uniforms differ), so all of them
+ * share one compiled program per material class.
+ *
+ * Reflections: the studio stage look has no scene environment, and a metal
+ * there would reflect black. While the scene has none, the reflective presets
+ * take a RoomEnvironment prefiltered once per renderer; on a stage with an
+ * environment they reflect that one, at its intensity, like everything else.
+ */
+
+import * as THREE from "three";
+import { RoomEnvironment } from "three/examples/jsm/environments/RoomEnvironment.js";
+import { FINISH_ROUGHNESS, MATERIAL_LOOKS, lookTint } from "./material-presets.js";
+import { PATTERN_SIZE, patternPixels } from "./material-textures.js";
+
+const VERTEX_HEAD = `
+uniform vec3 lookExtent;
+uniform float lookTile;
+uniform float lookGrain;
+varying vec3 vLookPos;
+varying vec3 vLookNormal;`;
+
+// lookGrain: 0 the part's own y, 1 its longest side, 2 its most upright side
+// (a slab's thickness never counts). A downward axis is flipped so a thatch
+// course's lower edge stays at the bottom.
+const VERTEX_BODY = `
+mat3 lookFrame = mat3( modelMatrix );
+#ifdef USE_INSTANCING
+	lookFrame = lookFrame * mat3( instanceMatrix );
+#endif
+vec3 lookSize = max( vec3( length( lookFrame[ 0 ] ), length( lookFrame[ 1 ] ), length( lookFrame[ 2 ] ) ), vec3( 1e-6 ) );
+vec3 lookExt = lookExtent * lookSize;
+vec3 lookUp = vec3( lookFrame[ 0 ].y, lookFrame[ 1 ].y, lookFrame[ 2 ].y ) / lookSize;
+int lookAxis = 1;
+if ( lookGrain > 1.5 ) {
+	vec3 score = abs( lookUp );
+	float thin = min( lookExt.x, min( lookExt.y, lookExt.z ) );
+	float mid = lookExt.x + lookExt.y + lookExt.z - thin - max( lookExt.x, max( lookExt.y, lookExt.z ) );
+	if ( thin < 0.35 * mid ) score -= 2.0 * vec3( equal( lookExt, vec3( thin ) ) );
+	lookAxis = score.x >= score.y && score.x >= score.z ? 0 : ( score.y >= score.z ? 1 : 2 );
+} else if ( lookGrain > 0.5 ) {
+	lookAxis = lookExt.x >= lookExt.y && lookExt.x >= lookExt.z ? 0 : ( lookExt.y >= lookExt.z ? 1 : 2 );
+}
+vec3 lookP = transformed * lookSize / lookTile;
+vec3 lookN = objectNormal / lookSize;
+if ( lookAxis == 0 ) { lookP = lookP.yxz; lookN = lookN.yxz; }
+else if ( lookAxis == 2 ) { lookP = lookP.xzy; lookN = lookN.xzy; }
+if ( lookGrain > 1.5 && lookUp[ lookAxis ] < 0.0 ) { lookP.y = - lookP.y; lookN.y = - lookN.y; }
+vLookPos = lookP;
+vLookNormal = lookN;`;
+
+// Bump is Mikkelsen's surface gradient with unnormalized screen derivatives,
+// so `lookAmount.y` is a real relief depth in metres at any distance.
+const FRAGMENT_HEAD = `
+uniform sampler2D lookMap;
+uniform vec4 lookAmount;
+uniform vec3 lookMask;
+varying vec3 vLookPos;
+varying vec3 vLookNormal;
+vec4 lookTriplanar( vec3 q, vec3 w ) {
+	return texture2D( lookMap, q.zy ) * w.x + texture2D( lookMap, q.xz ) * w.y + texture2D( lookMap, q.xy ) * w.z;
+}
+vec3 lookPerturb( vec3 pos, vec3 n, vec2 dH, float face ) {
+	vec3 sx = dFdx( pos ), sy = dFdy( pos );
+	vec3 r1 = cross( sy, n ), r2 = cross( n, sx );
+	float det = dot( sx, r1 ) * face;
+	if ( abs( det ) < 1e-14 ) return n;
+	return normalize( abs( det ) * n - sign( det ) * ( dH.x * r1 + dH.y * r2 ) );
+}`;
+
+const FRAGMENT_COLOR = `
+vec3 lookW = pow( abs( normalize( vLookNormal ) ), vec3( 4.0 ) );
+lookW /= lookW.x + lookW.y + lookW.z;
+vec4 lookTex = lookTriplanar( vLookPos, lookW );
+vec2 lookDH = lookAmount.y * ( vec2( lookTriplanar( vLookPos + dFdx( vLookPos ), lookW ).g, lookTriplanar( vLookPos + dFdy( vLookPos ), lookW ).g ) - lookTex.g );
+diffuseColor.rgb *= max( 0.0, 1.0 + ( lookTex.r - 0.5 ) * 2.0 * lookAmount.x );
+diffuseColor.rgb = mix( diffuseColor.rgb, lookMask, lookTex.a * lookAmount.w );`;
+
+const FRAGMENT_ROUGHNESS = "\nroughnessFactor = clamp( roughnessFactor + ( lookTex.b - 0.5 ) * 2.0 * lookAmount.z, 0.03, 1.0 );";
+const FRAGMENT_NORMAL = "\nnormal = lookPerturb( - vViewPosition, normal, lookDH, faceDirection );";
+
+const after = (marker, code) => (source) => source.replace(marker, `${marker}${code}`);
+const patchVertex = [after("#include <common>", VERTEX_HEAD), after("#include <begin_vertex>", VERTEX_BODY)];
+const patchFragment = [after("#include <common>", FRAGMENT_HEAD), after("#include <color_fragment>", FRAGMENT_COLOR),
+	after("#include <roughnessmap_fragment>", FRAGMENT_ROUGHNESS), after("#include <normal_fragment_maps>", FRAGMENT_NORMAL)];
+const GRAIN = { up: 0, long: 1, hang: 2 };
+
+const patternTextures = new Map();
+/** The shared tile for a pattern, made on first use. Never disposed: every
+ * material of the preset, now and later, samples the same one. */
+function patternTexture(pattern) {
+	let texture = patternTextures.get(pattern);
+	if (!texture) {
+		texture = new THREE.DataTexture(patternPixels(pattern), PATTERN_SIZE, PATTERN_SIZE);
+		texture.wrapS = texture.wrapT = THREE.RepeatWrapping;
+		texture.magFilter = THREE.LinearFilter;
+		texture.minFilter = THREE.LinearMipmapLinearFilter;
+		texture.generateMipmaps = true;
+		texture.anisotropy = 8;
+		texture.needsUpdate = true;
+		patternTextures.set(pattern, texture);
+	}
+	return texture;
+}
+
+/** Hooks the pattern into a material. The texture is fetched at compile time,
+ * which only a renderer does, so Node never generates one. */
+function addPattern(material, preset, size) {
+	const uniforms = {
+		lookMap: { value: null },
+		lookTile: { value: preset.tile },
+		lookExtent: { value: new THREE.Vector3(...size) },
+		lookGrain: { value: GRAIN[preset.grain ?? "up"] },
+		lookAmount: { value: new THREE.Vector4(preset.contrast ?? 0, preset.bump ?? 0, preset.roughVar ?? 0, preset.mask ? 0.9 : 0) },
+		lookMask: { value: new THREE.Color(preset.mask ?? "#000000") },
+	};
+	material.onBeforeCompile = (shader) => {
+		uniforms.lookMap.value ??= patternTexture(preset.pattern);
+		Object.assign(shader.uniforms, uniforms);
+		shader.vertexShader = patchVertex.reduce((source, patch) => patch(source), shader.vertexShader);
+		shader.fragmentShader = patchFragment.reduce((source, patch) => patch(source), shader.fragmentShader);
+	};
+	material.customProgramCacheKey = () => "cozyclay-look-1";
+}
+
+const studioMaps = new WeakMap();
+/** A neutral room to reflect, prefiltered once per renderer and kept. */
+function studioReflections(renderer) {
+	let map = studioMaps.get(renderer);
+	if (!map) {
+		const generator = new THREE.PMREMGenerator(renderer), room = new RoomEnvironment();
+		map = generator.fromScene(room, 0.04).texture;
+		room.dispose();
+		generator.dispose();
+		studioMaps.set(renderer, map);
+	}
+	return map;
+}
+
+/** Runs before each draw: the room while the scene has no environment, the
+ * scene's own (envMap null) once it has one. three swaps the program itself. */
+function reflectWhenBare(intensity) {
+	return function onBeforeRender(renderer, scene) {
+		const own = scene?.environment ? null : studioReflections(renderer);
+		if (this.envMap === own) return;
+		this.envMap = own;
+		this.envMapIntensity = intensity;
+	};
+}
+
+const WHITE = new THREE.Color("#ffffff");
+
+/**
+ * A material for `look` = { material, finish, color, size, side }: the preset
+ * name (unknown or absent is clay), the finish, the authored colour, the
+ * surface's extent in its mesh frame (metres; sizes the glass thickness and
+ * steers the grain) and an optional side. `extra` is set last (polygon offset).
+ */
+export function lookMaterial(look, extra = null) {
+	const name = Object.hasOwn(MATERIAL_LOOKS, look.material ?? "") ? look.material : "clay";
+	const preset = MATERIAL_LOOKS[name], size = look.size ?? [1, 1, 1];
+	const roughness = FINISH_ROUGHNESS[look.finish] ?? preset.roughness;
+	const color = new THREE.Color(lookTint(look.color, name));
+	const params = { color, roughness, metalness: preset.metalness ?? 0, ...(look.side === undefined ? {} : { side: look.side }), ...extra };
+	let material;
+	if (preset.physical) {
+		const physical = { ...preset.physical };
+		if (physical.transmission) physical.thickness = Math.min(0.5, Math.max(0.002, Math.min(...size) / 2));
+		if (physical.sheen) physical.sheenColor = color.clone().lerp(WHITE, 0.25);
+		if (physical.clearcoat && look.finish) Object.assign(physical, { clearcoat: look.finish === "matte" ? 0 : 1, clearcoatRoughness: roughness / 2 });
+		material = new THREE.MeshPhysicalMaterial({ ...params, ...physical });
+	} else material = new THREE.MeshStandardMaterial(params);
+	if (preset.pattern) addPattern(material, preset, size);
+	if (preset.env) material.onBeforeRender = reflectWhenBare(preset.env);
+	return material;
+}