cozyclay 2.0.2 → 2.1.0

package/src/ardy-bridge-contract.js

@@ -0,0 +1,281 @@
+import { ko, isKo } from "./locale.js";
+import { LINE_EDIT_TRACK_IDS, PINNED_CURVE_ENDS } from "./line-edit.js";
+import { FK_TRACKS, IK_TRACKS, MID_TRACKS } from "./ardy/ik.js";
+
+// Two clocks, one boundary. The app timeline runs the production 24 fps —
+// the rate the reference footage and the recorded export are counted in.
+// ARDY Core generates on its trained 20 fps clock and that cannot move, so
+// takes are RETIMED inbound (bridge → app, retimeMotion) and frame numbers
+// are CONVERTED outbound (app → bridge, toArdyFrame). Nothing between the
+// boundaries may mix the clocks.
+export const TIMELINE_FPS = 24;
+// The motion bridge uses the Studio's fixed 24 fps production clock.
+export const ARDY_FPS = 24;
+export const toArdyFrame = (frame) => Math.round((frame * ARDY_FPS) / TIMELINE_FPS);
+
+// Outbound converters: timeline-frame entries → strictly-ascending bridge
+// frames. Rounding can land two timeline frames on one bridge frame; the
+// first wins — the bridge refuses non-ascending lists outright.
+/** Where a placed pose lands, in TIMELINE frames, for a clip of `clipFrames`. */
+export function posePlacementFrame(placement, clipFrames, playheadFrame) {
+	const last = Math.max(0, clipFrames - 1);
+	if (placement === "end") return last;
+	if (placement === "middle") return Math.round(last / 2);
+	if (placement === "playhead") return Math.max(0, Math.min(last, playheadFrame));
+	return 0;
+}
+
+export function toArdyFrameEntries(entries) {
+	const out = [];
+	for (const entry of entries) {
+		const frame = toArdyFrame(entry.frame);
+		if (out.length && frame <= out[out.length - 1].frame) continue;
+		out.push({ ...entry, frame });
+	}
+	return out;
+}
+
+export function toArdySegments(segments) {
+	const out = [];
+	for (const segment of segments) {
+		const startFrame = toArdyFrame(segment.startFrame);
+		const endFrame = toArdyFrame(segment.endFrame);
+		if (endFrame <= startFrame) continue; // a zero-length rounding remnant covers nothing
+		out.push({ ...segment, startFrame, endFrame });
+	}
+	return out;
+}
+
+export const DEFAULT_DURATION_S = 15; // pre-motion timeline duration; shown as duration × TIMELINE_FPS frames
+export const DEFAULT_PLAYBACK_SPEED = 1;
+export const BRIDGE_RECHECK_MS = 3000;
+export const ARDY_PROMPT_HORIZON_FRAMES = 2 * TIMELINE_FPS; // core model horizon: 2 seconds, counted on the timeline clock
+export const MAX_WAYPOINTS = 32; // ARDY bridge contract: a root path holds 2..32 distinct waypoint frames
+export const ARDY_PROMPT_MAX = 500; // bridge contract: prompt must be non-empty, capped at 500 chars
+export const ARDY_DURATION_MIN = 1; // the UI works in whole seconds; the bridge floor is 0.15 s
+export const ARDY_DURATION_MAX = 1200; // bridge contract: duration capped at 1200 s
+export const ARDY_SEED_MAX = 2 ** 31 - 1; // bridge contract: optional seed, integer in 0..2**31-1
+// Scheduled inpainting (contract C3): how hard a regeneration holds onto the
+// take that is already loaded. 0 turns preserving OFF entirely; 0.5 is the
+// paper's recommended setting. The app ships this RAW number and nothing else:
+// the strength -> denoising-schedule mapping (sigma_s = round(1000 * strength),
+// sigma_e = min(50, sigma_s), diffusion time 0..1000) lives on the box side, and
+// duplicating it here is exactly how the two would silently drift apart.
+export const ARDY_PRESERVE_DEFAULT = 0.5;
+export const DEFAULT_PROMPT_CLIPS = [];
+
+/** The prompt-block schedule: every authored block in frame order, with the gaps
+ * between them filled by the base prompt so the bridge always receives one
+ * contiguous 0..clipFrames sequence. Blocks shorter than 3 frames are dropped —
+ * they cannot carry a generation.
+ * Pure and shared on purpose: the request assembly decides which blocks count as
+ * "edited", and the preserve panel has to name the SAME blocks. Re-deriving them
+ * approximately beside the slider is how the UI starts promising a locality the
+ * wire does not carry. */
+export function buildPromptSchedule(sourcePromptClips, clipFrames, prompt) {
+	const segments = [];
+	let cursor = 0;
+	for (const clip of sourcePromptClips) {
+		const startFrame = Math.max(cursor, Math.min(clipFrames, clip.startFrame));
+		const endFrame = Math.max(startFrame, Math.min(clipFrames, clip.endFrame));
+		if (startFrame > cursor) segments.push({ startFrame: cursor, endFrame: startFrame, prompt });
+		if (endFrame - startFrame >= 3) segments.push({ startFrame, endFrame, prompt: clip.text.trim() || prompt });
+		cursor = Math.max(cursor, endFrame);
+		if (cursor >= clipFrames) break;
+	}
+	if (cursor < clipFrames) segments.push({ startFrame: cursor, endFrame: clipFrames, prompt });
+	if (segments.length === 0) segments.push({ startFrame: 0, endFrame: clipFrames, prompt });
+	return segments;
+}
+
+/** The DISTINCT ik track ids keyed inside the half-open timeline span
+ * [startFrame, endFrame). `ikState.keys` is Map(frame -> Map(trackId -> pose)),
+ * so a frame with several dragged effectors contributes all of them. */
+export function ikTracksInRange(ikState, ikFrames, startFrame, endFrame) {
+	const tracks = new Set();
+	for (const frame of ikFrames) {
+		if (frame < startFrame || frame >= endFrame) continue;
+		for (const trackId of ikState?.keys?.get(frame)?.keys() ?? []) tracks.add(trackId);
+	}
+	return [...tracks];
+}
+
+/* Which limb a keyed IK track frees once the preserve mask is grouped
+   (contract C3v2). The single source of truth for track -> mask group is
+   TRACK_GROUPS in tools/kimodo/preserve-mask.mjs; nothing under tools/ may be
+   imported into src/, so the rule is transcribed here — as USER-FACING LABELS
+   only, never as a second copy of the mapping the wire depends on:
+     leftHand,  leftElbow  -> leftArm     rightHand, rightElbow -> rightArm
+     leftFoot,  leftKnee   -> leftLeg     rightFoot, rightKnee  -> rightLeg
+     head,      neck       -> head        spine, chest, leftShoulder,
+     hips                  -> torso AND root      rightShoulder -> torso
+   The track ids are the same namespace on both sides (src/ardy/ik.js owns
+   them), so the app ships whatever ids it has and the mask builder maps them.
+   Torso and pelvis tracks are worded as the whole body: the pelvis carries the
+   global transform as well as a bone, and naming a limb beside it would promise
+   a locality the mask does not have. */
+export const PRESERVE_TRACK_LIMBS = {
+	leftHand: "leftArm",
+	leftElbow: "leftArm",
+	rightHand: "rightArm",
+	rightElbow: "rightArm",
+	leftFoot: "leftLeg",
+	leftKnee: "leftLeg",
+	rightFoot: "rightLeg",
+	rightKnee: "rightLeg",
+	head: "head",
+	neck: "head",
+	spine: "body",
+	chest: "body",
+	leftShoulder: "body",
+	rightShoulder: "body",
+	hips: "body",
+};
+// A fixed reading order, so the same edit always reads back the same way.
+export const PRESERVE_LIMB_ORDER = ["head", "leftArm", "rightArm", "leftLeg", "rightLeg"];
+export const preserveLimbLabel = (limb) => ({
+	head: ko("head", "머리"),
+	leftArm: ko("left arm", "왼팔"),
+	rightArm: ko("right arm", "오른팔"),
+	leftLeg: ko("left leg", "왼발"),
+	rightLeg: ko("right leg", "오른발"),
+}[limb]);
+
+/** One muted line naming what a grouped preserve run will regenerate, or "" when
+ * no track can be attributed — then the request carries no `tracks` either and
+ * the panel's existing whole-take wording is already the truth. */
+export function preserveTracksSummary(tracks) {
+	const limbs = new Set();
+	for (const trackId of tracks) {
+		const limb = PRESERVE_TRACK_LIMBS[trackId];
+		if (limb) limbs.add(limb);
+	}
+	if (limbs.size === 0) return "";
+	if (limbs.has("body")) return ko("regenerates the whole body", "몸 전체를 다시 생성");
+	const names = PRESERVE_LIMB_ORDER.filter((limb) => limbs.has(limb)).map(preserveLimbLabel);
+	return isKo ? `${names.join("·")}만 다시 생성` : `regenerates ${names.join(" · ")} only`;
+}
+
+/* --------------------------- line editing (C6) ---------------------------
+ * "Grab the joint's motion path and pull it; the joint follows the pulled path
+ * exactly" (ProjFlow). The arithmetic lives in ./line-edit.js; what stays here
+ * is the panel's own vocabulary and the one thing App owns that the pure module
+ * cannot — the mapping from a track id to a HUMAN LABEL, which is read straight
+ * out of ik.js's three tables so the picker can never drift from the pose
+ * studio's own naming. An id in LINE_EDIT_TRACK_IDS with no entry in those
+ * tables is a bug, and falling back to the raw id makes it visible instead of
+ * silent. */
+export const LINE_EDIT_TRACK_OPTIONS = LINE_EDIT_TRACK_IDS.map((id) => ({
+	value: id,
+	label: [...IK_TRACKS, ...MID_TRACKS, ...FK_TRACKS].find((track) => track.id === id)?.label ?? id,
+}));
+/** The same human label, by id — what a version-strip chip says a refinement
+ * touched ("Refine · Left Hand"). */
+export const lineTrackLabel = (id) => LINE_EDIT_TRACK_OPTIONS.find((option) => option.value === id)?.label ?? id;
+/** The default edited track: a wrist is the joint the paper's own demo draws
+ * with, and the one whose screen trajectory a user can actually see. */
+export const LINE_EDIT_DEFAULT_TRACK = "leftHand";
+/** Draw a grab handle every Nth frame. Fewer would leave the curve looking
+ * un-grabbable in the gaps; more turns a 200-frame range into a solid bead of
+ * dots. The hit test tolerates CURVE_GRAB_RADIUS_PX regardless, so the handles
+ * are an affordance rather than the actual geometry. */
+export const LINE_CURVE_MARKER_STRIDE = 4;
+/** The shortest curve with anything draggable in it: both ends are hard-pinned
+ * to the original trajectory, so a range needs more than 2 x PINNED_CURVE_ENDS
+ * frames before the middle can move at all. */
+export const MIN_CURVE_POINTS = PINNED_CURVE_ENDS * 2 + 1;
+/** How long a released drag has to sit still before it costs a preview. Long
+ * enough that pull-pull-pull is one request instead of three, short enough that
+ * the loop still feels like it answers the gesture — a preview round trip is
+ * ~1 s on the warm service, so 150 ms is noise against it. */
+export const LINE_PREVIEW_DEBOUNCE_MS = 150;
+/** How often the line-edit capability is re-probed while the bridge is up and
+ * the answer is still no.
+ *
+ * The bridge answers `capabilities.lineEdit` from a LAZY ssh probe of the
+ * ProjFlow box behind a 5 s cache, so the very first /ardy/health of a session
+ * can land on a cold cache and come back false — a box that is perfectly fine
+ * two seconds later. Asking once per bridge-up transition therefore made the
+ * whole mode dead until a reload (first boot broken, second boot fine, which is
+ * exactly how it was reported). A capability is an ADVERTISEMENT, so it is
+ * allowed to arrive late; what is not allowed is to assume it. 4 s sits just
+ * under the bridge's own 5 s TTL, so a retry can actually see a new answer
+ * rather than re-reading the same cached false. */
+export const LINE_CAPABILITY_RETRY_MS = 4000;
+/** Why a validateLineEdit code refused, said once, in the user's language.
+ * Keyed by the pure module's stable codes so the copy and the check can never
+ * disagree about which field was wrong. */
+export const LINE_EDIT_REFUSALS = {
+	sourceMotion: ["The current take has no bridge source — generate it once before editing a path", "현재 테이크에 브리지 원본이 없어요 — 궤적을 편집하기 전에 한 번 생성하세요"],
+	track: ["Pick a joint to edit first", "먼저 편집할 관절을 고르세요"],
+	frameRange: ["The frame range must sit inside the clip and span at least 2 frames", "프레임 구간은 클립 안에 있어야 하고 최소 2프레임이어야 해요"],
+	points: ["Pull a longer stretch of the path — a single point is not a path", "궤적을 좀 더 길게 잡아당겨 주세요 — 점 하나는 경로가 아니에요"],
+	camera: ["The camera could not be captured — nudge the view and try again", "카메라를 캡처하지 못했어요 — 뷰를 조금 움직인 뒤 다시 시도하세요"],
+	prompt: ["The motion prompt is not usable for a line edit", "모션 프롬프트를 라인 편집에 쓸 수 없어요"],
+	pins: ["The pinned moments could not be sent — try clearing them and pinning again", "찍은 순간을 보낼 수 없어요 — 지우고 다시 찍어 보세요"],
+	shape: ["The line edit could not be assembled", "라인 편집을 구성하지 못했어요"],
+};
+/** Why curveToPoints2d refused. Same shape, different stage: these are about
+ * the CURVE, before there is a payload to validate. */
+export const LINE_CURVE_REFUSALS = {
+	empty: ["This joint is not visible over the chosen frames — frame it in view first", "선택한 구간에서 이 관절이 보이지 않아요 — 먼저 화면 안에 들어오도록 잡아 주세요"],
+	offscreen: ["The pulled path leaves the frame — keep it inside the dashed border", "잡아당긴 궤적이 화면을 벗어났어요 — 점선 테두리 안에 두세요"],
+};
+
+// Named ingest failures, in both locales. A reason the user cannot act on is
+// not a message: each line says what was wrong with THIS source.
+export const MULTIMODEL_REASONS = {
+	"url-empty": ["Enter a video URL first", "영상 URL을 먼저 입력하세요"],
+	"url-protocol-relative": ["Use a full https:// address", "https:// 로 시작하는 전체 주소를 쓰세요"],
+	"url-scheme-unsupported": ["Only http(s) or a local /path is accepted", "http(s) 또는 로컬 /경로만 사용할 수 있어요"],
+	"url-platform-page": [
+		"YouTube/Vimeo pages are players, not video files, and block browser downloads. Start the dev bridge to use the URL directly, or download the clip and use Choose video.",
+		"유튜브·비메오 주소는 영상 파일이 아니라 플레이어 페이지이고 브라우저 다운로드를 막습니다. 개발 브리지를 켜면 URL을 그대로 쓸 수 있고, 아니면 영상을 내려받아 '영상 선택'을 쓰세요.",
+	],
+	"url-malformed": ["That address could not be parsed", "주소를 해석할 수 없어요"],
+	"fetch-failed": ["The host refused a browser download (CORS or offline)", "호스트가 브라우저 다운로드를 거부했어요(CORS 또는 오프라인)"],
+	"not-a-video": ["That address did not return a video (check the path)", "그 주소는 영상을 반환하지 않았어요(경로를 확인하세요)"],
+	"decode-failed": ["This browser cannot decode that video", "이 브라우저가 디코딩할 수 없는 영상이에요"],
+	"duration-unreadable": ["The clip length could not be read", "클립 길이를 읽지 못했어요"],
+	"dimensions-unreadable": ["The frame size could not be read", "프레임 크기를 읽지 못했어요"],
+	"probe-timeout": ["The video never reported metadata", "영상이 메타데이터를 보내지 않았어요"],
+	"fetch-unavailable": ["This browser cannot download files", "이 브라우저는 파일을 내려받을 수 없어요"],
+	"footage-load-timeout": ["The clip never became seekable", "클립이 탐색 가능한 상태가 되지 않았어요"],
+	"seek-timeout": ["Seeking inside the clip stalled", "클립 내부 탐색이 멈췄어요"],
+	"pose-runtime-unavailable": ["The pose engine is missing from this build", "이 빌드에 포즈 엔진이 없어요"],
+	"pose-model-download-failed": ["The pose model could not be downloaded (offline?)", "포즈 모델을 내려받지 못했어요(오프라인인가요?)"],
+	"pose-engine-download-failed": ["The pose engine could not be downloaded (offline?)", "포즈 엔진을 내려받지 못했어요(오프라인인가요?)"],
+	"pose-engine-init-failed": ["The pose engine failed to start on this device", "이 기기에서 포즈 엔진을 시작하지 못했어요"],
+	"rest-unavailable": ["The rig rest data (/ardy/cskel27-rest.json) could not be loaded", "리그 레스트 데이터(/ardy/cskel27-rest.json)를 불러오지 못했어요"],
+	"no-person-found": ["No person was detected in the footage", "영상에서 사람을 감지하지 못했어요"],
+	"no-person-in-photo": ["No person was detected in that photograph", "사진에서 사람을 감지하지 못했어요"],
+	"image-load-timeout": ["The photograph never finished decoding", "사진 디코딩이 끝나지 않았어요"],
+	"pose-partly-occluded": ["Shoulders and hips must both be visible in the photograph", "사진에 어깨와 골반이 모두 보여야 해요"],
+	"no-usable-pose": ["A person was seen, but no stable pose could be fitted", "사람은 보였지만 안정적인 포즈를 만들지 못했어요"],
+	"rig-not-loaded": ["Subject 1's rig is not loaded yet", "인물 1 리그가 아직 로드되지 않았어요"],
+	"bridge-unreachable": ["The dev bridge did not answer", "개발 브리지가 응답하지 않아요"],
+	"bridge-footage-incomplete": ["The bridge stream ended without footage", "브리지 전송이 영상 없이 끝났어요"],
+	"footage-url-invalid": ["That address could not be used for a bridge download", "이 주소는 브리지 다운로드에 쓸 수 없어요"],
+	"footage-probe-failed": ["The bridge could not read that page's video info", "브리지가 그 페이지의 영상 정보를 읽지 못했어요"],
+	"footage-live-unsupported": ["Live streams have no fixed length and cannot be ingested", "라이브 스트림은 길이가 없어 인제스트할 수 없어요"],
+	"footage-too-long": ["That video is over 15 minutes — trim or pick a shorter one", "15분이 넘는 영상이에요 — 잘라내거나 더 짧은 걸 골라 주세요"],
+	"footage-download-failed": ["The bridge could not download that video", "브리지가 영상을 내려받지 못했어요"],
+	"footage-normalize-failed": ["The bridge could not convert that video for extraction", "브리지가 영상을 추출용으로 변환하지 못했어요"],
+	"footage-timeout": ["The bridge download took too long and was stopped", "브리지 다운로드가 너무 오래 걸려 중단됐어요"],
+	"bridge-extract-incomplete": ["The bridge stream ended without a take", "브리지 전송이 테이크 없이 끝났어요"],
+	"extract-host-missing": ["The bridge has no GPU box configured (CCLAY_EXTRACT_HOST)", "브리지에 GPU 박스가 설정돼 있지 않아요(CCLAY_EXTRACT_HOST)"],
+	"extract-bridge-required": ["GVHMR extraction requires the local GPU bridge", "GVHMR 추출에는 로컬 GPU 브리지가 필요해요"],
+	"extract-backend-unsupported": ["This bridge is not configured for GVHMR", "이 브리지가 GVHMR로 설정되지 않았어요"],
+	"extract-upload-failed": ["The footage could not be copied to the GPU box", "영상을 GPU 박스로 복사하지 못했어요"],
+	"extract-upload-too-large": ["That clip is too large to upload for extraction (300 MB cap)", "추출 업로드 한도(300MB)를 넘는 영상이에요"],
+	"extract-upload-empty": ["No video bytes arrived at the bridge", "브리지에 영상 데이터가 도착하지 않았어요"],
+	"extract-footage-unknown": ["The bridge no longer holds that download — re-ingest the URL", "브리지에 그 다운로드가 더 이상 없어요 — URL을 다시 넣어 주세요"],
+	"extract-run-failed": ["GVHMR failed on the GPU box (see the bridge log)", "GPU 박스에서 GVHMR 실행이 실패했어요(브리지 로그 확인)"],
+	"extract-no-person": ["The GPU box tracked no person in that footage", "GPU 박스가 영상에서 사람을 추적하지 못했어요"],
+	"extract-convert-failed": ["The extracted take could not be converted for the timeline", "추출된 테이크를 타임라인용으로 변환하지 못했어요"],
+	"extract-timeout": ["GPU extraction took too long and was stopped", "GPU 추출이 너무 오래 걸려 중단됐어요"],
+};
+
+// Extraction samples and bakes straight onto the production clock — an
+// extracted take never touches ARDY, so it never needs retiming either.
+export const MULTIMODEL_SAMPLE_FPS = TIMELINE_FPS;

package/src/asset-pane.jsx

@@ -1,6 +1,6 @@
 import { useEffect, useLayoutEffect, useRef, useState, useSyncExternalStore } from "react";
 import { ko } from "./locale.js";
-import { CHARACTER_MODEL_IDS } from "./scenes.js";
+import { CHARACTER_MODEL_IDS, PROXY_FIGURE_MODEL } from "./scenes.js";
 import { OBJECT_LIBRARY } from "./scene-objects.js";
 import { displayObjectLabel } from "./object-catalog.jsx";
 import { assetAspect, isMeshAssetId, isSupportedMeshType } from "./scene-assets.js";
@@ -10,14 +10,25 @@ import ResourceStatus from "./resource-status.jsx";
 import { logStore } from "./shell/log-store.js";
 import "./asset-pane.css";
 
-/** Casting assets offered in the Content browser's Characters folder. `id` doubles as the FBX
- * file stem and the ARDY wire rig name (see scenes.js). */
-export const CHARACTER_ASSETS = CHARACTER_MODEL_IDS.map((id) => ({
-	id,
-	label: id === "y-bot-tpose" ? "Y Bot" : "X Bot",
-}));
+/** Casting assets offered in the Content browser's Characters folder. A rig's `id` doubles as
+ * the FBX file stem and the ARDY wire rig name (see scenes.js); the capsule figure has no FBX. */
+export const CHARACTER_ASSETS = [
+	...CHARACTER_MODEL_IDS.map((id) => ({
+		id,
+		label: id === "y-bot-tpose" ? "Y Bot" : "X Bot",
+	})),
+	{ id: PROXY_FIGURE_MODEL, label: ko("Capsule figure", "캡슐 인물") },
+];
 
 function CharacterPreview({ model }) {
+	if (model === PROXY_FIGURE_MODEL) {
+		return (
+			<svg className="asset-card-preview" viewBox="0 0 48 48" aria-hidden="true" data-preview="proxy-figure">
+				<circle cx="24" cy="8.5" r="5.5" />
+				<rect x="16" y="16" width="16" height="26" rx="8" />
+			</svg>
+		);
+	}
 	const yBot = model === "y-bot-tpose";
 	return (
 		<svg className="asset-card-preview" viewBox="0 0 48 48" aria-hidden="true">
@@ -392,7 +403,7 @@ function EmptyNote({ children }) {
 	return <p className="content-empty">{children}</p>;
 }
 
-function FolderGrid({ folder, query, ...props }) {
+export function FolderGrid({ folder, query, ...props }) {
 	const { imageAssetIds, meshAssetIds, shots = [], takeVersions = [], poses = [], onShotOpen, onTakeOpen, selectedKey, onSelect } = props;
 	let tiles = [];
 	let empty = null;
@@ -653,7 +664,6 @@ export default function AssetPane({
 						</button>
 					</nav>
 					<div className="content-main">
-						{/* Only a project that carries resources has totals worth a line. */}
 						{resourceManifest?.items?.length ? <ResourceStatus manifest={resourceManifest} compact /> : null}
 						{manageStorage ? (
 							<StorageManager unusedAssetIds={unusedAssetIds} usedAssetIds={usedAssetIds} usageCounts={usageCounts} graphSignature={graphSignature} trashCount={trashCount} onDelete={onDeleteUnusedAsset} onUndo={onUndoDelete} deletingAssetId={deletingAssetId} />

package/src/auto-color.js

@@ -20,7 +20,7 @@ export function hashObjectId(id) {
 		hash ^= id.charCodeAt(index);
 		hash = Math.imul(hash, 16777619) >>> 0;
 	}
-	return hash >>> 0;
+	return hash;
 }
 
 const GOLDEN_RATIO_CONJUGATE = 0.61803398875;

package/src/burn-in.js

@@ -51,7 +51,7 @@ export function compositeStamp(pixels, width, height, stamp, { marginX = 0, marg
 }
 
 /** Rasterize one stamp line into RGBA bytes (browser-only: Canvas 2D). */
-export function renderStampBitmap(text, { fontPx = 18, padX = 10, padY = 6, maxWidth = Infinity } = {}) {
+function renderStampBitmap(text, { fontPx = 18, padX = 10, padY = 6, maxWidth = Infinity } = {}) {
 	const probe = new OffscreenCanvas(1, 1).getContext("2d");
 	probe.font = `600 ${fontPx}px ui-monospace, Menlo, monospace`;
 	const textW = Math.ceil(probe.measureText(text).width);

package/src/camera-block.js

@@ -5,7 +5,7 @@ import { createTiming, timingIsFlat } from "./speed-envelope.js";
 
 export const CAMERA_MODES = Object.freeze(["keys", "follow", "rail"]);
 
-export const CAMERA_FOLLOW_DEFAULTS = Object.freeze({
+const CAMERA_FOLLOW_DEFAULTS = Object.freeze({
 	distance: 3,
 	height: 1.6,
 	response: 0.7,

package/src/camera-follow.js

@@ -1,4 +1,5 @@
 import { timingProgress } from "./speed-envelope.js";
+import { monotoneCubicAt } from "./monotone-cubic.js";
 
 /**
  * Follow camera: a real crew in three pieces of math.
@@ -200,7 +201,7 @@ export function buildFollowTrack(subject, fps, params = {}) {
 	const p = { ...FOLLOW_DEFAULTS, ...params };
 	if (!subject || subject.length === 0) return [];
 	const dt = followFixedTimestep(fps);
-	const dirs = travelDirections(subject, fps, p.initialDir ?? null, p.dirBlend);
+	const dirs = travelDirections(subject, fps, p.initialDir, p.dirBlend);
 	const offsets = dirs.map((dir) => rotateDirection({ x: -dir.x, z: -dir.z }, p.orbitOffsetDeg));
 	const vels = smoothedVelocities(subject, fps);
 	const omega = omegaFor(p.response);
@@ -269,8 +270,6 @@ export function buildFollowTrack(subject, fps, params = {}) {
 	return track;
 }
 
-/* ----------------------------------------------------------- the crane --- */
-
 /** Accepts the canonical { points } crane or the legacy { start, end } pair. */
 function cranePoints(value) {
 	if (!value || typeof value !== "object") return null;
@@ -290,34 +289,9 @@ function cranePoints(value) {
 export function craneHeightAt(craneHeight, progress) {
 	const points = cranePoints(craneHeight);
 	if (!points) return NaN;
-	const clamped = Math.max(0, Math.min(1, progress));
-	if (clamped <= points[0].t) return points[0].height;
-	if (clamped >= points[points.length - 1].t) return points[points.length - 1].height;
-	let i = 0;
-	while (i < points.length - 2 && clamped > points[i + 1].t) i += 1;
-	const p0 = points[i];
-	const p1 = points[i + 1];
-	const h = p1.t - p0.t;
-	if (h < 1e-9) return p1.height;
-	const secant = (a, b) => (b.height - a.height) / Math.max(b.t - a.t, 1e-9);
-	const d = secant(p0, p1);
-	// harmonic mean of neighbouring secants; zero across a local extremum
-	const mono = (sa, sb) => (sa * sb <= 0 ? 0 : (2 * sa * sb) / (sa + sb));
-	const m0 = i > 0 ? mono(secant(points[i - 1], p0), d) : d;
-	const m1 = i < points.length - 2 ? mono(d, secant(p1, points[i + 2])) : d;
-	const u = (clamped - p0.t) / h;
-	const u2 = u * u;
-	const u3 = u2 * u;
-	return (
-		(2 * u3 - 3 * u2 + 1) * p0.height +
-		(u3 - 2 * u2 + u) * h * m0 +
-		(-2 * u3 + 3 * u2) * p1.height +
-		(u3 - u2) * h * m1
-	);
+	return monotoneCubicAt(points, Math.max(0, Math.min(1, progress)), (point) => point.height);
 }
 
-/* ------------------------------------------------------------ the rail --- */
-
 /**
  * Ramer–Douglas–Peucker: an authored stroke is hundreds of jittery pointer
  * samples; the rail wants the handful of points that carry its shape.
@@ -463,7 +437,7 @@ export function buildRailFollowTrack(subject, fps, rail, params = {}) {
 	const crane = cranePoints(p.craneHeight) ? p.craneHeight : null;
 	const craneTargetAt = (arc) => {
 		if (!crane) return p.height;
-		return craneHeightAt(crane, rail.length < 1e-9 ? 1 : arc / rail.length);
+		return craneHeightAt(crane, arc / rail.length);
 	};
 
 	const distanceErrorAt = (s, subj) => {
@@ -512,13 +486,13 @@ export function buildRailFollowTrack(subject, fps, rail, params = {}) {
 			// area is the rail length, and a cut pins "at this frame, be at
 			// this point of the rail". Null timing is the identity — the
 			// constant-speed schedule this line always was.
-			const authoredS = rail.length * timingProgress(p.dollyTiming ?? null, progress);
+			const authoredS = rail.length * timingProgress(p.dollyTiming, progress);
 			const distanceS = bestSNear(authoredS, subject[f], p.searchWindow, 0);
 			// Distance influence fades to zero at both authored endpoints, so
 			// it refines the middle of the move without shifting its marks.
 			const correctionEnvelope = Math.sin(Math.PI * progress) ** 2;
 			const correction = (distanceS - authoredS) * clamp(p.distanceInfluence, 0, 1) * correctionEnvelope;
-			const ledS = rail.length * timingProgress(p.dollyTiming ?? null, Math.min(1, progress + leadFraction));
+			const ledS = rail.length * timingProgress(p.dollyTiming, Math.min(1, progress + leadFraction));
 			const sTarget = Math.max(s, Math.min(rail.length, ledS + correction));
 			[s, sVel] = cappedSpringStep(s, sVel, sTarget, omega, dt, p.maxDollySpeed);
 			s = Math.max(0, Math.min(s, rail.length));
@@ -535,3 +509,72 @@ export function buildRailFollowTrack(subject, fps, rail, params = {}) {
 	}
 	return track;
 }
+
+/**
+ * Prepare an x/z rail bend for one crane mark: a copy of the drawn control
+ * points (with one inserted at the mark's base when none is close enough to
+ * anchor the bend) plus a per-point weight — a cosine bump centred on the
+ * anchor that fades to zero by the neighbouring crane marks, so dragging one
+ * mark can never tow the marks beside it. For an interior mark both rail
+ * ends are pinned outright. `maxControls` stops the seeding at a schema
+ * ceiling (the nearest point anchors the bend instead).
+ */
+export function prepareRailBend(controlPoints, base, marks, markIndex, { maxControls = Infinity } = {}) {
+	const controls = (controlPoints ?? []).map((entry) => ({ ...entry }));
+	if (controls.length < 2) return null;
+	// nearest control point / segment to the mark's base
+	let nearestIdx = 0;
+	let nearestD = Infinity;
+	for (let i = 0; i < controls.length; i += 1) {
+		const d = Math.hypot(controls[i].x - base.x, controls[i].z - base.z);
+		if (d < nearestD) {
+			nearestD = d;
+			nearestIdx = i;
+		}
+	}
+	const interior = markIndex > 0 && markIndex < marks.length - 1;
+	let anchorIdx = nearestIdx;
+	if (interior && nearestD > 0.25 && controls.length < maxControls) {
+		// no control point near the mark: bend needs a vertex to pull, so one
+		// is seeded at the base, on the segment the base projects onto
+		let segmentIdx = 0;
+		let segmentD = Infinity;
+		for (let i = 0; i < controls.length - 1; i += 1) {
+			const ax = controls[i].x;
+			const az = controls[i].z;
+			const bx = controls[i + 1].x;
+			const bz = controls[i + 1].z;
+			const lenSq = Math.max((bx - ax) ** 2 + (bz - az) ** 2, 1e-9);
+			const u = Math.max(0, Math.min(1, ((base.x - ax) * (bx - ax) + (base.z - az) * (bz - az)) / lenSq));
+			const d = Math.hypot(ax + (bx - ax) * u - base.x, az + (bz - az) * u - base.z);
+			if (d < segmentD) {
+				segmentD = d;
+				segmentIdx = i;
+			}
+		}
+		// An object route's points carry a height; the seed takes the one the
+		// curve has there. (The camera rail's points have none.)
+		const seed = { x: base.x, z: base.z };
+		if (base.y !== undefined) seed.y = base.y;
+		controls.splice(segmentIdx + 1, 0, seed);
+		anchorIdx = segmentIdx + 1;
+	}
+	// normalized arc parameter of each control point along the control polygon
+	const ts = [0];
+	for (let i = 1; i < controls.length; i += 1) {
+		ts.push(ts[i - 1] + Math.hypot(controls[i].x - controls[i - 1].x, controls[i].z - controls[i - 1].z));
+	}
+	const total = Math.max(ts[ts.length - 1], 1e-9);
+	for (let i = 0; i < ts.length; i += 1) ts[i] /= total;
+	// the bump reaches exactly to the neighbouring crane marks
+	const t0 = ts[anchorIdx];
+	const previous = markIndex > 0 ? marks[markIndex - 1].t : null;
+	const next = markIndex < marks.length - 1 ? marks[markIndex + 1].t : null;
+	const radius = Math.max(0.15, Math.min(previous != null ? t0 - previous : 1, next != null ? next - t0 : 1));
+	const weights = ts.map((t, i) => {
+		if (interior && (i === 0 || i === ts.length - 1)) return 0;
+		const d = Math.abs(t - t0);
+		return d >= radius ? 0 : 0.5 * (1 + Math.cos((Math.PI * d) / radius));
+	});
+	return { startControls: controls, weights, t0, radius };
+}

package/src/camera-move.js

@@ -30,8 +30,6 @@ export function cameraPresetFraming(id, subject = {}, filmback = {}) {
 	return { id, pos, yaw, pitch, fovDeg, focalMm: preset.focalMm };
 }
 
-/* ------------------------------------------------------------ framing --- */
-
 /**
  * Snapshot the shot camera as a plain framing record.
  * yaw/pitch follow the YXZ free-look convention in controls.jsx.
@@ -151,8 +149,6 @@ export function interpolateFraming(a, b, anchor, t, ease = easeInOut, filmback =
 	};
 }
 
-/* ----------------------------------------------------------- naming ---- */
-
 const DEG = 180 / Math.PI;
 
 // Below these deltas the camera is, cinematically speaking, not doing that.
@@ -288,8 +284,6 @@ export function moveSlate(move) {
 	return `${end[0]} → ${end[1]} · ${move.label.toUpperCase()}`;
 }
 
-/* ------------------------------------------------- multi-key sequences --- */
-
 /**
  * Sample an N-key camera move at a frame. Keys are sorted frame-unique
  * records `{ frame, framing }`. Before the first key and after the last the

package/src/camera-tutorial.jsx

@@ -98,8 +98,6 @@ export const CAMERA_TUTORIAL_STEPS = [
 const NAV_KINDS = new Set(["fly", "walk", "dolly", "orbit"]);
 const SIGNAL_KINDS = new Set(["shot", "rail"]);
 
-/* ------------------------------------------------------------- beacons --- */
-
 // Where each of the last three steps actually happens (#211). The card names
 // the gesture; these pin a numbered circle and a caption onto the control
 // itself, so "click + Add shot" stops being a treasure hunt across two panes.
@@ -249,8 +247,6 @@ export function TutorialBeacon({ kind, step, role, selector, label, requires = n
 	);
 }
 
-/* -------------------------------------------------------- gesture cues --- */
-
 // Steps 1–4 have no control to point at: the gesture IS the interface. The cue
 // draws the mouse and the keys the step wants, animated the way the hand is
 // supposed to move, and sits centre-bottom of the viewport where the eye
@@ -330,7 +326,7 @@ export function GestureCue({ kind, walked, leaving = false, onLeft }) {
  * Top-View inset, and never takes the pointer except on its own close button
  * — every step is completed by working the studio underneath it.
  */
-export function CameraTutorial({ previewing = false, shotCount = 0, railReady = false, analytics, onStepChange, onClose, onComplete, handoff = null, shotId = null, onOpenExport, onContinue }) {
+export function CameraTutorial({ previsMode, previewing = false, shotCount = 0, railReady = false, analytics, onStepChange, onClose, onComplete, handoff = null, shotId = null, onOpenExport, onContinue }) {
 	const [done, setDone] = useState(() => new Set());
 	const [walked, setWalked] = useState(() => new Set());
 	const [cue, setCue] = useState(null);
@@ -429,6 +425,9 @@ export function CameraTutorial({ previewing = false, shotCount = 0, railReady =
 		});
 	}, [currentKind]);
 
+	// Storyboard projects never show the camera tutorial (its steps are shot/rail/play).
+	if (previsMode === "storyboard") return null;
+
 	return (
 	<>
 		<aside
@@ -510,8 +509,8 @@ export function CameraTutorial({ previewing = false, shotCount = 0, railReady =
 				role={beacon.role}
 				selector={beacon.selector}
 				label={beacon.label}
-				requires={beacon.requires ?? null}
-				absent={beacon.absent ?? null}
+				requires={beacon.requires}
+				absent={beacon.absent}
 			/>
 		))}
 	</>