cozyclay 3.0.3 → 3.1.1

package/src/material-presets.js

@@ -0,0 +1,78 @@
+/**
+ * Material presets: named surface looks for sculpt parts (`material`, `finish`)
+ * and plain primitives (`object.material`, `object.finish`). Pure data and the
+ * record rules, no three.js, so the recipe reader, the scene record and Node
+ * tests share one list; material-look.js turns an entry into a material.
+ *
+ * A record keeps only the names. `color` stays the base tint ("#c24a3b" with
+ * wood is red-painted wood), and a colour left at the blockout grey takes the
+ * preset's own (brick with no colour draws brick red). `finish` replaces the
+ * preset's roughness: chrome is metal + gloss, frosted glass is glass + matte.
+ * Clay with no finish is exactly the look every prop wore before presets.
+ *
+ * An entry (every field optional): roughness, metalness, color (its natural
+ * tint), physical (MeshPhysicalMaterial fields), env (reflection strength on
+ * a stage with no environment of its own), and a pattern with its tile in
+ * metres, the axis its grain runs along (up: the part's own y; long: its
+ * longest side; hang: its most upright side, skipping a slab's thickness),
+ * albedo contrast, bump depth in metres, roughness variation and a mask
+ * colour (brick mortar).
+ */
+
+import { GREY_BOX } from "./object-colors.js";
+
+export const MATERIAL_LOOKS = Object.freeze({
+	clay: { roughness: 0.82 },
+	wood: { roughness: 0.68, color: "#9a6b3f", pattern: "wood", tile: 0.5, grain: "long", contrast: 0.32, bump: 0.0015, roughVar: 0.1 },
+	straw: { roughness: 0.88, color: "#c8a85c", pattern: "straw", tile: 0.6, grain: "hang", contrast: 0.5, bump: 0.02, roughVar: 0.08 },
+	stone: { roughness: 0.9, color: "#8d8a83", pattern: "stone", tile: 1, contrast: 0.32, bump: 0.008, roughVar: 0.1 },
+	brick: { roughness: 0.88, color: "#a5503a", pattern: "brick", tile: 0.5, grain: "hang", contrast: 0.22, bump: 0.008, roughVar: 0.08, mask: "#b9b3a8" },
+	concrete: { roughness: 0.92, color: "#a7a49d", pattern: "concrete", tile: 1.2, contrast: 0.2, bump: 0.0015, roughVar: 0.08 },
+	metal: { roughness: 0.32, metalness: 1, color: "#c9ccd1", env: 1, pattern: "brushed", tile: 0.4, contrast: 0.06, bump: 0.0001, roughVar: 0.12 },
+	glass: { roughness: 0.04, color: "#f2f7f7", env: 1, physical: { transmission: 1, ior: 1.5 } },
+	ceramic: { roughness: 0.35, color: "#efece4", env: 0.45, physical: { clearcoat: 1, clearcoatRoughness: 0.06 } },
+	plastic: { roughness: 0.3, env: 0.35 },
+	rubber: { roughness: 0.92, color: "#2d2d2f", pattern: "stipple", tile: 0.15, contrast: 0.08, bump: 0.0003, roughVar: 0.06 },
+	fabric: { roughness: 0.95, pattern: "weave", tile: 0.12, contrast: 0.22, bump: 0.0008, roughVar: 0.05, physical: { sheen: 1, sheenRoughness: 0.6 } },
+	paper: { roughness: 0.88, color: "#ebe6da", pattern: "paper", tile: 0.25, contrast: 0.08, bump: 0.0002 },
+	foliage: { roughness: 0.62, color: "#4f7d34", pattern: "leaves", tile: 0.6, contrast: 0.45, bump: 0.015, roughVar: 0.15, physical: { sheen: 0.8, sheenRoughness: 0.45 } },
+});
+
+export const MATERIAL_PRESETS = Object.freeze(Object.keys(MATERIAL_LOOKS));
+/** What a finish sets the roughness to, whatever the preset's own. */
+export const FINISH_ROUGHNESS = Object.freeze({ matte: 0.85, satin: 0.45, gloss: 0.12 });
+export const MATERIAL_FINISHES = Object.freeze(Object.keys(FINISH_ROUGHNESS));
+
+/** The colour a surface draws in: the authored one, or the preset's own while
+ * the authored one is still the blockout grey. */
+export function lookTint(color, preset) {
+	const own = MATERIAL_LOOKS[preset]?.color;
+	return own && (!color || color.toLowerCase() === GREY_BOX) ? own : color ?? GREY_BOX;
+}
+
+/** The record renderers that draw a preset (props.jsx Primitive). */
+const LOOK_RENDERERS = new Set(["cube", "sphere", "capsule", "cylinder", "cone", "plane"]);
+const LOOK_KEYS = [["material", MATERIAL_PRESETS], ["finish", MATERIAL_FINISHES]];
+
+/** The patch keys object.update reads for the look, on the renderers that draw one. */
+export const objectMaterialKeys = (renderer) => (LOOK_RENDERERS.has(renderer) ? LOOK_KEYS.map(([key]) => key) : []);
+
+/** The material/finish a normalized record keeps: known names on a primitive,
+ * nothing otherwise, so records written before presets come back unchanged. */
+export function objectMaterialFields(record, renderer) {
+	if (!LOOK_RENDERERS.has(renderer)) return {};
+	return Object.fromEntries(LOOK_KEYS.filter(([key, names]) => names.includes(record?.[key])).map(([key]) => [key, record[key]]));
+}
+
+/** The material/finish part of an object.update patch: a known name sets it,
+ * null removes it (back to the preset default), anything else is ignored. */
+export function objectMaterialPatch(object, patch) {
+	if (!LOOK_RENDERERS.has(object?.renderer)) return {};
+	const update = {};
+	for (const [key, names] of LOOK_KEYS) {
+		const value = patch?.[key];
+		if (value === undefined || (value !== null && !names.includes(value))) continue;
+		if ((value ?? undefined) !== object[key]) update[key] = value;
+	}
+	return update;
+}

package/src/material-textures.js

@@ -0,0 +1,157 @@
+/**
+ * Procedural surface detail for the material presets: one small seamless tile
+ * per pattern, from integer hashes, so every machine draws the same pixels.
+ * Pure arithmetic, no three.js and no DOM; material-look.js wraps the bytes in
+ * a DataTexture the first time a preset is drawn, and never in Node.
+ *
+ * Channels, each 0..255: R albedo detail (128 is the authored colour), G
+ * height (0..255 spans the preset's bump depth), B roughness offset (128 is
+ * none), A where a second colour shows (brick mortar). Each pattern is drawn
+ * in tile coordinates u (across) and v (along the grain, or up), both 0..1;
+ * R and B are re-centred on their mean afterwards, so a preset never shifts
+ * the colour the author picked.
+ */
+
+export const PATTERN_SIZE = 256;
+
+function hash(x, y, seed) {
+	let h = Math.imul(x, 0x27d4eb2d) ^ Math.imul(y, 0x165667b1) ^ Math.imul(seed, 0x9e3779b1);
+	h = Math.imul(h ^ (h >>> 15), 0x85ebca6b);
+	h = Math.imul(h ^ (h >>> 13), 0xc2b2ae35);
+	return ((h ^ (h >>> 16)) >>> 0) / 4294967296;
+}
+const wrap = (i, n) => ((i % n) + n) % n;
+const smooth = (t) => t * t * (3 - 2 * t);
+const step = (a, b, x) => smooth(Math.min(1, Math.max(0, (x - a) / (b - a))));
+
+/** Value noise on a px by py lattice over the tile, seamless at its edges. */
+function noise(u, v, px, py, seed) {
+	const x = u * px, y = v * py, ix = Math.floor(x), iy = Math.floor(y);
+	const fx = smooth(x - ix), fy = smooth(y - iy);
+	const x0 = wrap(ix, px), x1 = wrap(ix + 1, px), y0 = wrap(iy, py), y1 = wrap(iy + 1, py);
+	const a = hash(x0, y0, seed), b = hash(x1, y0, seed), c = hash(x0, y1, seed), d = hash(x1, y1, seed);
+	return a + (b - a) * fx + (c - a) * fy + (a - b - c + d) * fx * fy;
+}
+
+function fbm(u, v, px, py, octaves, seed) {
+	let sum = 0, amp = 0.5, total = 0;
+	for (let o = 0; o < octaves; o += 1) {
+		sum += amp * noise(u, v, px << o, py << o, seed + o);
+		total += amp;
+		amp /= 2;
+	}
+	return sum / total;
+}
+
+/** Worley cells on an n by n jittered grid, seamless: the nearest and second
+ * nearest feature distances (tile units) and the nearest cell's hash. */
+function cells(u, v, n, seed) {
+	const x = u * n, y = v * n, ix = Math.floor(x), iy = Math.floor(y);
+	let f1 = 9, f2 = 9, id = 0;
+	for (let dy = -1; dy <= 1; dy += 1) {
+		for (let dx = -1; dx <= 1; dx += 1) {
+			const cx = ix + dx, cy = iy + dy, wx = wrap(cx, n), wy = wrap(cy, n);
+			const d = Math.hypot(cx + hash(wx, wy, seed) - x, cy + hash(wx, wy, seed + 1) - y) / n;
+			if (d < f1) {
+				f2 = f1;
+				f1 = d;
+				id = hash(wx, wy, seed + 2);
+			} else if (d < f2) f2 = d;
+		}
+	}
+	return { f1, f2, id };
+}
+
+/** Each pattern: (u, v) to [albedo, height, roughness, mask]. */
+const PATTERNS = {
+	// Ten rings across the tile, wandering along it, over fine fibres.
+	wood(u, v) {
+		const late = (0.5 + 0.5 * Math.sin(2 * Math.PI * (u * 10 + fbm(u, v, 2, 1, 3, 11) * 2.2))) ** 6;
+		const fibre = noise(u, v, 128, 4, 12), fleck = fbm(u, v, 16, 2, 2, 13);
+		return [0.5 - 0.45 * late + 0.25 * fibre + 0.2 * fleck, 0.6 * fibre - 0.5 * late, 0.5 + 0.4 * late - 0.2 * fibre, 0];
+	},
+	// Four overlapping courses of strands; each course is thickest at its ragged
+	// lower edge and shaded just under the edge of the course above.
+	straw(u, v) {
+		const strand = 0.6 * noise(u, v, 192, 3, 21) + 0.4 * noise(u, v, 96, 2, 22);
+		const course = v * 4 + 0.12 * noise(u, v, 48, 1, 23), cv = course - Math.floor(course);
+		const shade = step(0.55, 1, cv);
+		return [0.5 * strand - 0.45 * shade + 0.1 * fbm(u, v, 6, 2, 2, 24), 0.7 * (1 - cv) + 0.3 * strand, 0.5 + 0.2 * shade, 0];
+	},
+	// Weathered fieldstone: lumpy noise, stones of their own tone, dark joints.
+	stone(u, v) {
+		const lump = fbm(u, v, 4, 4, 5, 31), cell = cells(u, v, 5, 32), grain = noise(u, v, 128, 128, 33);
+		const edge = cell.f2 - cell.f1, crack = 1 - step(0, 0.012, edge);
+		return [0.35 * lump + 0.25 * cell.id + 0.12 * grain - 0.35 * crack, 0.5 * lump + 0.35 * step(0, 0.08, edge) + 0.1 * grain, 0.25 * lump + 0.15 * crack, 0];
+	},
+	// Running bond: six 83 mm courses of two 250 mm bricks on the 0.5 m tile,
+	// 10 mm recessed mortar joints (the mask), each brick its own tone.
+	brick(u, v) {
+		const row = Math.floor(v * 6), cv = v * 6 - row;
+		const across = u * 2 + (row % 2 ? 0.5 : 0), col = Math.floor(across), cu = across - col;
+		const gap = Math.min(Math.min(cu, 1 - cu) / 2, Math.min(cv, 1 - cv) / 6), joint = 0.01;
+		const grit = noise(u, v, 96, 96, 42), mortar = 1 - step(joint * 0.6, joint, gap);
+		return [0.35 * hash(wrap(col, 2), row, 41) + 0.15 * grit + 0.15 * fbm(u, v, 8, 8, 3, 43), 0.85 * step(joint * 0.6, joint * 2.2, gap) + 0.15 * grit, 0.1 * grit + 0.15 * mortar, mortar];
+	},
+	// Cast concrete: soft mottling, fine grit, scattered air pits.
+	concrete(u, v) {
+		const mottle = fbm(u, v, 3, 3, 5, 51), grit = noise(u, v, 160, 160, 52), pit = step(0.86, 0.95, noise(u, v, 48, 48, 53));
+		return [0.3 * mottle + 0.1 * grit - 0.25 * pit, 0.4 * mottle + 0.25 * grit - 0.6 * pit, 0.2 * mottle, 0];
+	},
+	// Brushed metal: fine lines across the tile and faint smudges in the sheen.
+	brushed(u, v) {
+		const brush = 0.6 * noise(u, v, 3, 220, 61) + 0.4 * noise(u, v, 2, 110, 62), smudge = fbm(u, v, 3, 3, 4, 63);
+		return [0.15 * brush + 0.1 * smudge, brush, 0.35 * brush + 0.4 * smudge, 0];
+	},
+	stipple(u, v) {
+		const fine = noise(u, v, 128, 128, 71), wear = fbm(u, v, 6, 6, 3, 72);
+		return [0.2 * wear + 0.1 * fine, fine, 0.3 * wear, 0];
+	},
+	// Plain weave: 32 threads each way, over and under, each thread its own tone.
+	weave(u, v) {
+		const x = u * 32, y = v * 32, i = Math.floor(x), j = Math.floor(y);
+		const across = Math.sin(Math.PI * (x - i)), along = Math.sin(Math.PI * (y - j)), warp = (i + j) % 2 === 0;
+		const height = warp ? across * (0.75 + 0.25 * along) : along * (0.75 + 0.25 * across);
+		return [0.3 * height + 0.2 * (warp ? hash(i, 0, 81) : hash(0, j, 82)) + 0.1 * noise(u, v, 256, 256, 83), height, -0.2 * height, 0];
+	},
+	paper(u, v) {
+		const pulp = fbm(u, v, 8, 8, 4, 91), fibre = noise(u, v, 64, 8, 92) * noise(u, v, 8, 64, 93);
+		return [0.12 * pulp + 0.1 * fibre, pulp + 0.5 * fibre, 0.1 * pulp, 0];
+	},
+	// Two layers of leaf cells; the leaf nearer its own centre lies on top, and
+	// where neither covers the surface a dark gap shows through.
+	leaves(u, v) {
+		const big = cells(u, v, 6, 101), small = cells(u, v, 9, 104);
+		const domeBig = Math.max(0, 1 - big.f1 * 6 * 1.6), domeSmall = 0.9 * Math.max(0, 1 - small.f1 * 9 * 1.6);
+		const top = domeBig >= domeSmall ? big : small, dome = Math.max(domeBig, domeSmall), gap = 1 - step(0, 0.15, dome);
+		return [0.45 * top.id + 0.2 * dome - 0.5 * gap + 0.05 * noise(u, v, 64, 64, 107), dome, 0.3 * top.id + 0.3 * gap, 0];
+	},
+};
+
+export const PATTERN_NAMES = Object.freeze(Object.keys(PATTERNS));
+
+/** The RGBA bytes of one pattern's tile, PATTERN_SIZE square, row 0 at v = 0. */
+export function patternPixels(name) {
+	const draw = PATTERNS[name];
+	if (!draw) throw new Error(`unknown material pattern "${name}"`);
+	const count = PATTERN_SIZE * PATTERN_SIZE, raw = new Float32Array(count * 4);
+	for (let y = 0; y < PATTERN_SIZE; y += 1) {
+		for (let x = 0; x < PATTERN_SIZE; x += 1) raw.set(draw((x + 0.5) / PATTERN_SIZE, (y + 0.5) / PATTERN_SIZE), (y * PATTERN_SIZE + x) * 4);
+	}
+	let albedo = 0, rough = 0, low = Infinity, high = -Infinity;
+	for (let i = 0; i < count; i += 1) {
+		albedo += raw[i * 4] / count;
+		rough += raw[i * 4 + 2] / count;
+		low = Math.min(low, raw[i * 4 + 1]);
+		high = Math.max(high, raw[i * 4 + 1]);
+	}
+	const span = high - low || 1, byte = (value) => Math.round(255 * Math.min(1, Math.max(0, value)));
+	const out = new Uint8Array(count * 4);
+	for (let i = 0; i < count; i += 1) {
+		out[i * 4] = byte(raw[i * 4] - albedo + 0.5);
+		out[i * 4 + 1] = byte((raw[i * 4 + 1] - low) / span);
+		out[i * 4 + 2] = byte(raw[i * 4 + 2] - rough + 0.5);
+		out[i * 4 + 3] = byte(raw[i * 4 + 3]);
+	}
+	return out;
+}

package/src/motion/ground.js

@@ -3,20 +3,11 @@ import { isEffectivelyHidden, objectFootprintBounds } from "../scene-objects.js"
 /**
  * Ground height under a point, from the scene's objects (issue #250).
  *
- * AutoPhysics review measures every contact against ONE flat floor
- * (`floorY`). When a character stands on a box or a step its feet get pulled
- * down to the floor plane. This module answers "what is the ground here?" so
- * contact detection, span anchors, and toe minimum heights can use the
- * surface actually under the foot.
- *
- * DRAFT - the sampler exists and is tested; physics-review.js does not call
- * it yet. Wiring plan:
- *   1. supportIntervals(): compare the sole to groundAt(toe.x, toe.z), not
- *      floorY, in the "low enough to be a contact" test.
- *   2. Span anchors carry y = groundAt(anchor.x, anchor.z); footLockTrack
- *      anchors and relaxToePath's toeMinHeight take that value per frame.
- *   3. Penetration / float metrics and the root lift measure against the
- *      local ground under each support site.
+ * Against ONE flat floor (`floorY`), a character standing on a box or a step
+ * would read as sunk into it. This module answers "what is the ground here?":
+ * studio-agent-motion.js samples it per support site, and physics-review.js
+ * takes it as `groundAt` for contact spans, foot anchors and the floor/float
+ * metrics, so they measure against the surface actually under the foot.
  *
  * Surface model: each scene object is an axis-aligned box from
  * objectFootprintBounds (yaw-exact XZ footprint, flat top at topY). The

package/src/motion/playback-frame-store.js

@@ -0,0 +1,79 @@
+import { useEffect, useSyncExternalStore } from "react";
+import { shotIndexAtFrame } from "../cuts.js";
+
+// The playhead lives here, outside React: playback ticks write it and only the
+// components that show the frame subscribe, so App does not re-render per frame.
+let currentFrame = 0;
+const listeners = new Set();
+let applyPlaybackFrame = null;
+
+export function playbackFrame() {
+	return currentFrame;
+}
+
+export function setPlaybackFrame(next) {
+	const frame = typeof next === "function" ? next(currentFrame) : next;
+	if (!Number.isFinite(frame) || frame === currentFrame) return currentFrame;
+	currentFrame = frame;
+	if (typeof window !== "undefined") window.__cozyclayPlaybackFrame = frame;
+	for (const listener of listeners) listener();
+	return currentFrame;
+}
+
+export function advancePlaybackFrame(frameCount, count) {
+	const frame = setPlaybackFrame((current) => (current + count) % frameCount);
+	applyPlaybackFrame?.(frame);
+	return frame;
+}
+
+export function registerPlaybackFrameApplier(applier) {
+	applyPlaybackFrame = applier;
+	return () => {
+		if (applyPlaybackFrame === applier) applyPlaybackFrame = null;
+	};
+}
+
+export function createPlaybackFrameSetter({ getFrameCount, setReactFrame, onFrame }) {
+	return (update) => {
+		const next = typeof update === "function" ? update(playbackFrame()) : update;
+		const frame = Math.max(0, Math.min(getFrameCount() - 1, Math.round(next)));
+		setPlaybackFrame(frame);
+		setReactFrame(frame);
+		onFrame?.(frame);
+	};
+}
+
+export function commitPlaybackFrame(setReactFrame, onFrame) {
+	const frame = playbackFrame();
+	setReactFrame(frame);
+	onFrame?.(frame);
+	return frame;
+}
+
+export function usePlaybackSnapshot(getSnapshot) {
+	return useSyncExternalStore(subscribePlaybackFrame, getSnapshot, getSnapshot);
+}
+
+export function usePlaybackEffects({ playing = false, commit = () => {}, onStop = null } = {}) {
+	useEffect(() => {
+		if (!playing) {
+			commit();
+			onStop?.();
+		}
+		// Runs on play/stop transitions only; commit and onStop are recreated every render.
+	}, [playing]);
+}
+
+/** The shots domain's timeline frame: React state (owned by the caller) for edits, the store for playback.
+ * activeShotIdx subscribes to the store, so it re-renders only when playback crosses a cut. */
+export function usePlaybackFrameState({ frameCount, setReactFrame, shots }) {
+	const setTlFrame = createPlaybackFrameSetter({ getFrameCount: () => frameCount, setReactFrame });
+	const activeShotIdx = usePlaybackSnapshot(() => shotIndexAtFrame(shots, playbackFrame()));
+	const activeShot = shots[activeShotIdx] ?? null;
+	return { setTlFrame, commitPlaybackFrame: () => commitPlaybackFrame(setReactFrame), activeShotIdx, activeShot };
+}
+
+function subscribePlaybackFrame(listener) {
+	listeners.add(listener);
+	return () => listeners.delete(listener);
+}

package/src/motion/playback-probe.js

@@ -0,0 +1,16 @@
+import { sampleAt } from "../sample-at.js";
+
+export function playbackProbe(probe, frame, fallback) {
+	const sampled = probe.scene ? sampleAt(probe.scene, null, frame).subject : null;
+	const carried = sampled && probe.carry ? probe.carry(sampled, frame) : sampled;
+	return carried ?? fallback;
+}
+
+export function probeVisibility(vector, camera, subject, height) {
+	let visible = false;
+	for (const y of [0.1, height * 0.94]) {
+		vector.set(subject.x, y, subject.z).project(camera);
+		if (vector.z < 1 && Math.abs(vector.x) <= 1 && Math.abs(vector.y) <= 1) visible = true;
+	}
+	return visible;
+}

package/src/motion/playback-subject.js

@@ -0,0 +1,7 @@
+import { sampleAt } from "../sample-at.js";
+
+export function usePlaybackSubjectPosition({ motion, subjectCarry, scene, frame }) {
+	if (!motion && !subjectCarry) return null;
+	const subject = sampleAt(scene, null, frame).subject;
+	return subjectCarry ? subjectCarry(subject, frame) : subject;
+}

package/src/motion/timeline.css

@@ -778,11 +778,13 @@
 	box-shadow: none;
 }
 
+/* Shots cut against each other: a hairline between neighbours, not a wide gutter, so a run of cuts reads as
+   one sequence. Free-camera time between shots still shows as its own gap. */
 .v2-sequencer .tl-shot-block {
 	top: var(--tl-clip-inset, 7px);
 	bottom: var(--tl-clip-inset, 7px);
-	left: calc(var(--tl-f-start) * 100% + var(--tl-clip-inset, 7px));
-	width: max(var(--tl-min-clip-width, 1px), calc((var(--tl-f-end) - var(--tl-f-start)) * 100% - (var(--tl-clip-inset, 7px) * 2)));
+	left: calc(var(--tl-f-start) * 100% + var(--tl-shot-gap, 1px));
+	width: max(var(--tl-min-clip-width, 1px), calc((var(--tl-f-end) - var(--tl-f-start)) * 100% - (var(--tl-shot-gap, 1px) * 2)));
 	padding: var(--sp-1, 8px) var(--sp-1, 8px) var(--tl-shot-footer-height, 28px);
 	border: 0;
 	border-radius: var(--r-1, 4px);
@@ -854,6 +856,10 @@
 	background: var(--select-tint, rgba(232, 163, 61, .14));
 }
 
+/* The trim grips appear with the shot under the pointer, not as a column of marks at every cut. */
+.v2-sequencer .tl-shot-edge { opacity: 0; transition: opacity .12s; }
+.v2-sequencer .tl-shot-block:is(:hover, :focus-within) .tl-shot-edge { opacity: 1; }
+
 /* The bar hangs above the block's top-left corner instead of inside it: a
    short cut (40 frames ~ 38px) is narrower than Split + Duplicate + Delete,
    and an in-block bar would sit on the shot's name, turning a click on the
@@ -926,13 +932,22 @@
 	pointer-events: auto;
 }
 
+/* A camera key sits on its Shot's key strip (the line along the box's foot), as a small diamond: at the
+   lane's first-row height it landed on the box's top corner, in the gutter between two Shots. */
 .v2-sequencer .tl-marker.cam {
-	top: calc(var(--tl-track-row-height, 38px) / 2);
-	bottom: auto;
+	top: auto;
+	bottom: calc(var(--tl-clip-inset, 7px) + var(--tl-key-strip-height, 12px) / 2);
+	width: 7px;
+	height: 7px;
+	border-radius: 1.5px;
 	background: var(--camera, #a78bfa);
-	transform: translate(-50%, -50%) rotate(45deg);
+	box-shadow: 0 0 0 1.5px var(--tl-camera-clip, #3d3354);
+	transform: translate(-50%, 50%) rotate(45deg);
 	z-index: 7;
 }
+/* A key on a Shot's first or last frame steps just inside the box instead of straddling its edge. */
+.v2-sequencer .tl-marker.cam[data-edge="start"] { margin-left: 7px; }
+.v2-sequencer .tl-marker.cam[data-edge="end"] { margin-left: -7px; }
 
 .v2-sequencer .tl-marker.wp {
 	background: var(--ok, #4fbf7a);
@@ -1151,6 +1166,29 @@
 	background: var(--select, #e8a33d);
 }
 
+/* In a Shot box the height graph is a ~20 px strip: the points are small dots ON the curve, quiet on other
+   shots and full on the selected or hovered one, and their hit area stays a full finger wide. Hovering a curve
+   thickens it and the cursor says which way it moves. The axis labels have no room. */
+.v2-sequencer .tl-shot-block .tl-crane-knob {
+	width: 7px;
+	height: 7px;
+	border: 1.5px solid var(--tl-camera-rail, #302a40);
+	box-shadow: none;
+	opacity: .5;
+	transition: opacity .12s;
+}
+.v2-sequencer .tl-shot-block .sg-shot.height { z-index: 2; }
+.v2-sequencer .tl-shot-block .tl-crane-knob::before { content: ""; position: absolute; inset: -6px; border-radius: 50%; }
+.v2-sequencer .tl-shot-block .tl-crane-knob.selected { width: 9px; height: 9px; }
+.v2-sequencer .tl-shot-block:is(.selected, .active, :hover) .tl-crane-knob { opacity: 1; }
+.v2-sequencer .tl-shot-block .tl-crane-knob:hover, .v2-sequencer .tl-shot-block .tl-crane-knob:focus-visible { outline: none; transform: translate(-50%, -50%) scale(1.3); }
+.v2-sequencer .tl-shot-block .tl-crane-line { stroke-width: 1.5px; }
+.v2-sequencer .tl-shot-block .sg-shot .sg-body svg { cursor: ns-resize; }
+.v2-sequencer .tl-shot-block .sg-shot:hover :is(.sg-line, .tl-crane-line) { stroke-width: 2.5px; }
+.v2-sequencer .tl-shot-block .tl-crane-time-pick { opacity: 0; }
+.v2-sequencer .tl-shot-block .tl-crane-time-pick.selected { opacity: 1; }
+.v2-sequencer .tl-shot-block .tl-crane-editor :is(.sg-scale-top, .sg-scale-avg, .sg-scale-zero) { display: none; }
+
 .v2-sequencer .sg-shot {
 	left: var(--sp-1, 8px);
 	right: var(--sp-1, 8px);

package/src/motion/timeline.jsx

@@ -273,8 +273,9 @@ function CraneHeightEditor({ crane, railRange, durationFrames, selectedIndex, on
 					key={index}
 					type="button"
 					className={"tl-crane-knob" + (index === selectedIndex ? " selected" : "")}
-					// an end point sits ON the window edge; clamp it inside so the knob stays a whole, grabbable circle
-					style={{ left: `clamp(9px, ${xFor(point.t) * 100}%, calc(100% - 9px))`, top: `clamp(9px, ${yFor(point.height) * 100}%, calc(100% - 9px))` }}
+					// an end point sits ON the window edge; clamp it inside so the knob stays whole. The clamp is the
+					// knob's own radius: a wider one pinned every knob of a 20 px Shot strip to one row, off its curve.
+					style={{ left: `clamp(5px, ${xFor(point.t) * 100}%, calc(100% - 5px))`, top: `clamp(5px, ${yFor(point.height) * 100}%, calc(100% - 5px))` }}
 					aria-label={ko(`Crane point ${index + 1}, ${point.height.toFixed(1)} metres`, `크레인 점 ${index + 1}, ${point.height.toFixed(1)}미터`)}
 					onPointerDown={(event) => {
 						event.preventDefault();
@@ -2199,7 +2200,7 @@ export default function Timeline({
 									{name === SHOTS_LANE && shots.flatMap((shot, index) => (shot.cameraKeys ?? []).map((key) => (
 										<span
 											key={`${shot.id}:${key.frame}`}
-											className="tl-marker cam"
+											className="tl-marker cam" data-edge={key.frame <= shot.startFrame ? "start" : key.frame >= shot.endFrame ? "end" : undefined}
 											style={{ "--tl-f": framePct(key.frame, displayFrameCount) }}
 											title={isKo ? `${key.frame}프레임의 카메라 키 — 클릭해 이동, 드래그로 시간 변경, 오른쪽 클릭으로 삭제` : `Camera key at frame ${key.frame} — click to jump, drag to re-time, right-click to remove`}
 											onPointerDown={(e) => beginCameraKeyDrag(e, key, index)}

package/src/motion3/body.js

@@ -3,11 +3,43 @@
 // outside positive, metres) and, for the limbs, the skin radius along the bone. A limb collides as
 // spheres on its bone axis (limbProbes); bodyDistance is the nearest skin of every other bone but
 // the limb's own neighbours (SKIP), so an arm reads the torso, the head, the legs and the other arm.
-import yBody from "./rigs/y-bot-tpose-body.json" with { type: "json" };
-import xBody from "./rigs/x-bot-tpose-body.json" with { type: "json" };
 import { add, sub, scale, apply, T, len, dot, clamp } from "./compiler/math.js";
 
-const BODIES = { "y-bot-tpose": yBody, "x-bot-tpose": xBody };
+// The fits are ~0.5 MB of base64 grids, most of the editor's first-load JavaScript were they imported: each
+// is an asset file instead, read the first time a compile needs it. Node reads it from disk; a worker (or the
+// editor, should a compile run before preloadBodies has it) reads it synchronously over HTTP, so bodyFor
+// stays synchronous everywhere. The editor fetches both in the background after its first paint (main.jsx).
+const BODIES = {
+	"y-bot-tpose": new URL("./rigs/y-bot-tpose-body.json", import.meta.url),
+	"x-bot-tpose": new URL("./rigs/x-bot-tpose-body.json", import.meta.url),
+};
+const fits = new Map();
+
+function readFit(url) {
+	const fs = url.protocol === "file:" ? globalThis.process?.getBuiltinModule?.("node:fs") : null;
+	if (fs) return JSON.parse(fs.readFileSync(url, "utf8"));
+	const xhr = new XMLHttpRequest();
+	xhr.open("GET", url.href, false);
+	xhr.send();
+	if (xhr.status !== 200) throw new Error(`motion body fit ${url.pathname}: HTTP ${xhr.status}`);
+	return JSON.parse(xhr.responseText);
+}
+
+function fitOf(model) {
+	if (!fits.has(model)) fits.set(model, readFit(BODIES[model]));
+	return fits.get(model);
+}
+
+/** Fetches every rig's fit in the background, so a compile on this thread never waits on one. */
+export function preloadBodies() {
+	return Promise.all(Object.entries(BODIES).map(async ([model, url]) => {
+		if (fits.has(model)) return;
+		const response = await fetch(url);
+		if (!response.ok) throw new Error(`motion body fit ${url.pathname}: HTTP ${response.status}`);
+		const fit = await response.json();
+		if (!fits.has(model)) fits.set(model, fit);
+	}));
+}
 /** Distance read outside a grid: far enough that no probe counts it as touching. */
 const FAR = 0.1;
 const cache = new Map();
@@ -28,9 +60,9 @@ function skipOf(sk, b) {
 
 /** The fitted body of skeleton sk, or null for a rig without one. */
 export function bodyFor(sk) {
-	const fit = BODIES[sk.model];
-	if (!fit) return null;
+	if (!BODIES[sk.model]) return null;
 	if (cache.has(sk.model)) return cache.get(sk.model);
+	const fit = fitOf(sk.model);
 	const grids = Object.entries(fit.grids).map(([name, g]) => {
 		const half = g.dims.map(d => ((d - 1) * fit.step) / 2), centre = g.min.map((m, k) => m + half[k]);
 		return { b: sk.index[name], min: g.min, dims: g.dims, data: decode(g.data), centre, reach: len(half) };

package/src/motion3/carried.js

@@ -8,6 +8,7 @@
 import { palmAxes } from "./compiler/limbs.js";
 import { SIDES } from "./compiler/pose.js";
 import { add, scale, norm, sub, dot, cross, apply, mul, T, axisRot, I3 } from "./compiler/math.js";
+import { bonePoint } from "./compiler/skeleton.js";
 
 export const isCarried = o => typeof o?.prop === "string";
 /** A follow entry { follow: <ref>, offset?, aim?, visible?, level? } (C16, follow.js): the record rides a point of the body. */
@@ -23,9 +24,16 @@ export function propOrigin(sk, spec, s, o) {
 	return scale(prop.origin.map(b => s.P[sk.index[b]]).reduce((a, p) => add(a, p), [0, 0, 0]), 1 / prop.origin.length);
 }
 
-/** World { pos, R } of a carried record on pose s (at/along offset, PR #14). */
-export function carriedPose(sk, spec, s, o) {
-	const ax = palmAxes(sk, s, SIDES[spec.props[o.prop].hand]), origin = propOrigin(sk, spec, s, o);
+/** The prop origin carried by its hand's bone on pose s, where the bind pose has it against the hand: closing fingers do not move it (#816). */
+function handOrigin(sk, prop, s) {
+	const h = sk.index[`${SIDES[prop.hand]}Hand`], P = sk.restWorldPos;
+	const mean = scale(prop.origin.map(b => P[sk.index[b]]).reduce((a, p) => add(a, p), [0, 0, 0]), 1 / prop.origin.length);
+	return bonePoint(s, h, apply(T(sk.restWorldRot[h]), sub(mean, P[h])));
+}
+
+/** World { pos, R } of a carried record on pose s (at/along offset, PR #14); `fixed`: the origin rides the hand bone (seat.js). */
+export function carriedPose(sk, spec, s, o, fixed = false) {
+	const ax = palmAxes(sk, s, SIDES[spec.props[o.prop].hand]), origin = fixed ? handOrigin(sk, spec.props[o.prop], s) : propOrigin(sk, spec, s, o);
 	const palm = v => add(scale(ax.d, v[0]), add(scale(ax.l, v[1]), scale(ax.n, v[2])));
 	const y = norm(palm(o.along ?? [0, 0, 1]));
 	let x = sub(ax.d, scale(y, dot(ax.d, y)));

package/src/motion3/compile-job.js

@@ -1,6 +1,6 @@
 // One motion compile as a job of plain data, the same in the compile worker (compile-worker.js) and on
 // the calling thread (commands/motion3-compile.js, where no worker runs: Node, tests): the rig by model
-// name, the motion scene (scene.js motionScene of the editor's objects: boxes only), the spec as sent, and
+// name, the motion scene (scene.js motionScene of the editor's objects: oriented boxes; shapes.js reads a sphere or a cylinder round from them), the spec as sent, and
 // what to do with it (probes, checks, lenient, repair, bake). The answer is plain data and typed arrays
 // only (the compiler's out holds closures), so it crosses a worker boundary: QA, observations, the stored
 // spec, and the baked take when asked.

package/src/motion3/compiler/compile.js

@@ -35,6 +35,8 @@ import { fitWeight } from "../fix/self.js";
 import { holdHook } from "../object-keys.js";
 import { HAND_CLEAR, keepOut, wristBody } from "../body.js";
 import { objectPoseAt, handOf, restingAt, frameAt, spanOf } from "../object-pose.js";
+import { heldFor } from "./finger-close.js";
+import { sagOf } from "../load.js";
 
 const smooth = x => x * x * (3 - 2 * x);
 // how far past the straight arm a grasp fit's wrist target may end before it counts as wound up (solveFrame), m
@@ -136,6 +138,10 @@ function hooksFor(ctx, c, f, inFit = false, lead = true, fitSide = null) {
 		afterArm: (k, s, diag) => measureProps(ctx, k, s, diag),
 		// a fit's passes only place the wrist; the final pose (and a plain one) turns the hand onto the body
 		grip: inFit ? undefined : (k, s, diag) => gripHand(ctx, sk, s, SIDES[k], k, c, f, diag),
+		// a carry's weight lowers a plain IK hand's target, on the final pose only (load.js)
+		sag: inFit ? undefined : (k, s, target) => sagOf(ctx, k, f, s, target, (1 - fitWeight(ctx.spec, c, k)) * Math.min(1, Math.max(0, c[`armw_${k}`] ?? 0))),
+		// fingers close on what the hand holds, on the final pose only (finger-close.js)
+		heldShapes: inFit || !ctx.grasp ? undefined : (k, s) => heldFor(ctx, c, f, k, s),
 	};
 }
 
@@ -186,7 +192,7 @@ export function compileMotion(spec, { sk, scene }, opts = {}) {
 	if (!(frameCount >= 1 && frameCount <= 20000)) throw new Error("MOTION_SPEC_INVALID: frames must be 1..20000");
 	const fix = fixOptions(spec.fix);
 	const [a, b] = opts.window ? [Math.max(0, opts.window[0]), Math.min(frameCount - 1, opts.window[1])] : [0, frameCount - 1];
-	const ctx = { sk, spec, scene, softReach: fix.reach, push: { l: new Map(), r: new Map() }, swivel: { l: new Map(), r: new Map() }, skinPush: { l: new Map(), r: new Map() }, keepOut: fix.self ? wristBody(sk) : null };
+	const ctx = { sk, spec, scene, grasp: fix.grasp, softReach: fix.reach, push: { l: new Map(), r: new Map() }, swivel: { l: new Map(), r: new Map() }, skinPush: { l: new Map(), r: new Map() }, keepOut: fix.self ? wristBody(sk) : null };
 	const out = { ctx, fps: spec.fps ?? 30, frameCount, f0: a, frames: [] };
 	// object anchors read the pose refs read (object-pose.js), on the frame being solved
 	ctx.objectPose = (id, f, now) => objectPoseAt(out, id, f, now);