cozyclay 3.0.2 → 3.1.0

package/src/analytics.js

@@ -116,7 +116,6 @@ const EVENT_PROPERTIES = Object.freeze({
 	"project:opened": ["age_bucket"],
 	"craft:first_action": ["action_kind"],
 	"craft:first_edit": ["edit_kind", "definition_version"],
-	"motion:backend_state": ["backend", "host_configured"],
 	"motion:generate_requested": ["surface", "input_mode", "request_id"],
 	"motion:preflight_blocked": ["reason", "surface", "request_id"],
 	"motion:preflight_passed": ["backend", "surface", "request_id"],
@@ -136,19 +135,14 @@ const EVENT_PROPERTIES = Object.freeze({
 	"playground:first_action": ["action_kind"],
 	"playground:first_edit": ["edit_kind", "definition_version"],
 	"activation:completed": ["activation_path"],
-	"tutorial:started": ["surface", "tutorial_version", "start_source"],
-	"tutorial:step_entered": ["surface", "tutorial_version", "step_kind"],
-	"tutorial:step_completed": ["surface", "tutorial_version", "step_kind", "elapsed_bucket"],
-	"tutorial:completed": ["surface", "tutorial_version", "elapsed_bucket"],
-	"tutorial:dismissed": ["surface", "tutorial_version", "step_kind"],
 	"sculpt_run": ["outcome", "rounds", "final_iou", "duration_ms", "had_target"],
 	...EXECUTION_TELEMETRY_PROPERTY_KEYS,
 });
 const FEATURE_NAMES = new Set([
 	"pose_edit", "pose_save", "camera_fly", "orbit", "dolly_rail", "crane_graph", "timeline_scrub",
 	"prompt_block_add", "shot_add", "shot_cut", "export_pose", "export_frame", "export_video",
-	"export_depth_video", "export_keyframe_pack", "fal_motion_open",
-	"mcp_connected", "auto_color", "plan_view", "camera_tutorial",
+	"export_depth_video", "export_keyframe_pack",
+	"mcp_connected", "auto_color", "plan_view",
 ]);
 // `site` and `playground` arrive through `npx cozyclay --via <source>` from the
 // landing page's copy commands; the others are the first-launch prompt answers.
@@ -159,7 +153,6 @@ const MOTION_ERROR_CODES = new Set(["aborted", "unsupported_route", "generation_
 const MOTION_PROPERTY_VALUES = Object.freeze({
 	// `fal` is the Studio's AI video route (H3 Max Turbo through api.cozyclay.org).
 	backend: new Set(["none", "local_kimodo", "hosted", "fal"]),
-	host_configured: new Set([true, false]),
 	surface: new Set(["timeline", "line_edit", "trail", "mcp", "fal_card", "agent"]),
 	input_mode: new Set(["prompt", "pose", "edit", "a_to_b", "still"]),
 	// `locked`: the AI video route is not enabled for this account yet.
@@ -176,13 +169,6 @@ const EXPORT_PROPERTY_VALUES = Object.freeze({
 	duration_bucket: new Set(["lt1s", "1-3s", "3-10s", "10-30s", "gte30s"]),
 	failure_code: EXPORT_FAILURE_CODES,
 });
-const TUTORIAL_PROPERTY_VALUES = Object.freeze({
-	surface: new Set(["studio", "playground"]),
-	tutorial_version: new Set([1]),
-	start_source: new Set(["query", "settings", "landing"]),
-	step_kind: new Set(["fly", "walk", "dolly", "orbit", "shot", "rail", "play"]),
-	elapsed_bucket: new Set(["lt1s", "1-3s", "3-10s", "10-30s", "gte30s"]),
-});
 // Sculpt mode (#739): one sculpt_run per finished run. Numbers only: no
 // reference image, recipe, part name or sculpt id ever rides along.
 export const SCULPT_RUN_OUTCOMES = Object.freeze(["done", "cancelled", "failed"]);
@@ -242,7 +228,7 @@ let deviceProfileStarted = false;
 // move action_count_bucket.
 const PASSIVE_EVENTS = new Set([
 	"app:session_started", "app:session_ended", "install:first_launch",
-	"motion:backend_state", "app:error", "device:profile",
+	"app:error", "device:profile",
 ]);
 
 function storage() {
@@ -320,7 +306,6 @@ export function sanitizeProps(event, props) {
 				if (typeof props[key] !== "string" || !/^[a-f0-9]{32}$/.test(props[key])) continue;
 			} else if (!MOTION_PROPERTY_VALUES[key]?.has(props[key])) continue;
 		}
-		if (event.startsWith("tutorial:") && !TUTORIAL_PROPERTY_VALUES[key]?.has(props[key])) continue;
 		if (event.startsWith("workflow:") || event.startsWith("agent:") || event.startsWith("mcp:")) {
 			if (key === "run_id" || key === "turn_id" || key === "request_id") {
 				if (typeof props[key] !== "string" || !/^[a-f0-9]{32}$/.test(props[key])) continue;
@@ -372,136 +357,6 @@ export function sanitizeProps(event, props) {
 	return sanitized;
 }
 
-/**
- * Convert the bridge health payload into the analytics contract. The bridge
- * only exposes a safe location label; the configured host itself never leaves
- * the local process. A missing/unhealthy bridge is the useful `none` bucket.
- */
-export function motionBackendState(health) {
-	if (!health || health.ok !== true) return { backend: "none", host_configured: false };
-	if (typeof health.backend === "string" && ["none", "local_kimodo", "hosted"].includes(health.backend)) {
-		return {
-			backend: health.backend,
-			host_configured: health.host_configured === true
-				|| (typeof health.host === "string" && health.host.trim().length > 0),
-		};
-	}
-	const host = typeof health.host === "string" ? health.host.trim() : "";
-	return {
-		// The current /ardy bridge is the local Kimodo integration even when it
-		// dispatches to a configured GPU box over SSH. A future hosted API can
-		// opt into the explicit `backend: "hosted"` field above.
-		backend: "local_kimodo",
-		host_configured: Boolean(host),
-	};
-}
-
-/** Read only structured readiness; raw health/error prose never classifies intent. */
-export function motionPreflightReason(health, { body = {}, lineEditSupported = false } = {}) {
-	if (!health || health.backend === "none" || (health.ok !== true && (health.host_configured === false || health.reason === "unconfigured"))) return "unconfigured";
-	if (health.ok !== true) return "unreachable";
-	if ((body.lineEdit || body.replay?.length) && !lineEditSupported) return "unsupported_route";
-	// The #267 local MLX/cpp route supports a single unconstrained prompt.
-	// ProjFlow line edits have their own capability/runner, even on a local bridge.
-	if (!body.lineEdit && health.host === "local" && health.device === "local" && (
-		body.segments?.length > 1 || body.posePin || body.waypoints?.length || body.motionEdit || body.preserve
-	)) return "unsupported_route";
-	return null;
-}
-
-export function motionFailureCode(error, fallbackCode) {
-	try {
-		if (error?.name === "AbortError") return "aborted";
-		if (MOTION_ERROR_CODES.has(fallbackCode)) return fallbackCode;
-		if (error instanceof Error) return "generation_failed";
-	} catch {
-		// Cross-realm error objects may have throwing getters.
-	}
-	return "unknown";
-}
-
-/** One explicit request, not an authoring draft. All methods are telemetry-only:
- * no return value may decide whether generation runs. Duplicate/out-of-order
- * callbacks cannot advance the funnel, and application is separate from success.
- */
-export function startMotionRequest(metadata, dependencies = {}) {
-	let phase = "requested";
-	let props = null;
-	let startedAt = NaN;
-	let now = () => performance.now();
-	let capture = track;
-	const clock = () => { try { return now(); } catch { return NaN; } };
-	const emit = (event, extra = {}) => {
-		if (!props) return;
-		try {
-			Promise.resolve(capture(event, sanitizeProps(event, { ...props, ...extra }))).catch(() => {
-				// A rejected transport must not change generation.
-			});
-		} catch {
-			// Telemetry is best effort, including capture/payload failures.
-		}
-	};
-	try {
-		now = dependencies.now ?? now;
-		capture = dependencies.capture ?? capture;
-		const bytes = globalThis.crypto.getRandomValues(new Uint8Array(16));
-		const request_id = [...bytes].map((byte) => byte.toString(16).padStart(2, "0")).join("");
-		props = { ...sanitizeProps("motion:generate_requested", metadata), request_id };
-		emit("motion:generate_requested");
-	} catch {
-		// Omit telemetry without secure randomness; never derive an ID from content.
-		props = null;
-	}
-	return {
-		preflight(health, options) {
-			if (phase !== "requested") return;
-			try {
-				const reason = motionPreflightReason(health, options);
-				phase = reason ? "blocked" : "passed";
-				if (props) props.backend = motionBackendState(health).backend;
-				emit(reason ? "motion:preflight_blocked" : "motion:preflight_passed", reason ? { reason } : {});
-			} catch {
-				// A malformed telemetry input cannot stop the real request.
-			}
-		},
-		/** A route that decides readiness without the /ardy health payload (the
-		 * Fal card): refuse with one closed reason, such as `locked`. */
-		block(reason) {
-			if (phase !== "requested") return;
-			phase = "blocked";
-			emit("motion:preflight_blocked", { reason });
-		},
-		/** The same route's acceptance, naming the backend that will run it. */
-		pass(backend) {
-			if (phase !== "requested") return;
-			phase = "passed";
-			if (props) props.backend = backend;
-			emit("motion:preflight_passed");
-		},
-		start() {
-			if (phase !== "passed") return;
-			phase = "started";
-			startedAt = clock();
-			emit("motion:job_started");
-		},
-		succeed() {
-			if (phase !== "started") return;
-			phase = "succeeded";
-			emit("motion:job_succeeded", { duration_bucket: bucketMs(clock() - startedAt) });
-		},
-		fail(error, fallbackCode) {
-			if (phase !== "started") return;
-			phase = "failed";
-			emit("motion:job_failed", { duration_bucket: bucketMs(clock() - startedAt), error_code: motionFailureCode(error, fallbackCode) });
-		},
-		apply() {
-			if (phase !== "succeeded") return;
-			phase = "applied";
-			emit("motion:result_applied");
-		},
-	};
-}
-
 export const FEATURE_USAGE_NAMES = Object.freeze([...FEATURE_NAMES]);
 
 export function bucketCount(value) {

package/src/app-stage.jsx

@@ -62,7 +62,7 @@ export {
 
 export * from "./stage-attach-frames.js";
 
-export { Character } from "./stage-characters.jsx";
+export { Character, PlaybackCharacter } from "./stage-characters.jsx";
 
 export {
 	ShotRig,

package/src/asset-pane.jsx

@@ -49,9 +49,6 @@ const OBJECT_GLYPHS = {
 	cylinder: "M5 7c0-1.38 3.13-2.5 7-2.5s7 1.12 7 2.5-3.13 2.5-7 2.5S5 8.38 5 7z M5 7v10c0 1.38 3.13 2.5 7 2.5s7-1.12 7-2.5V7",
 	cone: "M12 3.5 5 17 M12 3.5 19 17 M5 17c0 1.38 3.13 2.5 7 2.5s7-1.12 7-2.5",
 	plane: "M12 7.5 21 12l-9 4.5L3 12z",
-	chair: "M7 3.5h10v8.5H7z M5.5 12h13v3h-13z M7 15v5.5 M17 15v5.5",
-	car: "M3 15.5v-3l2.5-.5 2.5-4h8l3 4 2 .5v3z M6 15.5a1.75 1.75 0 1 0 3.5 0 M14.5 15.5a1.75 1.75 0 1 0 3.5 0 M8 12h10",
-	"small-plane": "M12 3v18 M3 11.5l9-2 9 2v2l-9-1-9 1z M8.5 19.5 12 18.5l3.5 1",
 };
 
 const STORAGE_FOLDER = "__storage";
@@ -368,12 +365,11 @@ function matchesQuery(label, query) {
 	return !query || String(label).toLowerCase().includes(query);
 }
 
-/** Folder ids in display order. Basic Shapes and Sets split the object
- * catalogue by its own groups; Props holds what the user imported. */
+/** Folder ids in display order. Basic Shapes holds the object catalogue's
+ * primitives; Props holds what the user imported. */
 const FOLDERS = [
 	{ id: "basic", label: () => ko("Basic Shapes", "기본 도형") },
 	{ id: "characters", label: () => ko("Characters", "인물") },
-	{ id: "sets", label: () => ko("Sets", "세트") },
 	{ id: "props", label: () => ko("Props", "소품") },
 	{ id: "cameras", label: () => ko("Cameras", "카메라") },
 	{ id: "motions", label: () => ko("Motions", "모션") },
@@ -389,7 +385,7 @@ function catalogueTile(entry, props) {
 			key={key}
 			assetKey={key}
 			label={label}
-			type={entry.group === "Primitives" ? ko("Shape", "도형") : ko("Set piece", "세트 소품")}
+			type={ko("Shape", "도형")}
 			title={ko(`Drag ${entry.label} into the scene, or double-click to place it at the origin`, `${label}을(를) 씬에 드래그하거나 더블클릭해 원점에 놓으세요`)}
 			preview={<ObjectPreview kind={entry.kind} color={entry.color} />}
 			selected={props.selectedKey === key}
@@ -408,10 +404,9 @@ export function FolderGrid({ folder, query, ...props }) {
 	const { imageAssetIds, meshAssetIds, shots = [], takeVersions = [], poses = [], onShotOpen, onTakeOpen, selectedKey, onSelect } = props;
 	let tiles = [];
 	let empty = null;
-	if (folder === "basic" || folder === "sets") {
-		const group = folder === "basic" ? "Primitives" : "Set pieces";
+	if (folder === "basic") {
 		tiles = OBJECT_LIBRARY
-			.filter((entry) => entry.group === group && matchesQuery(displayObjectLabel(entry.label), query))
+			.filter((entry) => entry.group === "Primitives" && matchesQuery(displayObjectLabel(entry.label), query))
 			.map((entry) => catalogueTile(entry, props));
 	} else if (folder === "characters") {
 		tiles = CHARACTER_ASSETS.filter((asset) => matchesQuery(asset.label, query)).map((asset) => {

package/src/auto-flat.js

@@ -0,0 +1,10 @@
+/**
+ * The viewport's auto-colour material: a solid-view response for
+ * auto-coloured surfaces. A neutral studio shade lets the derived hue reach
+ * the eye unmultiplied; under our warm key light a plain standard material
+ * turns every hue olive. Full roughness kills the specular sheen and a
+ * self-light of the same hue lifts the shadow side.
+ */
+export function autoFlat(hex) {
+	return { color: hex, roughness: 1, metalness: 0, emissive: hex, emissiveIntensity: 0.4 };
+}

package/src/bus-task-scopes.js

@@ -0,0 +1,69 @@
+// The document targets a command writes, known before it runs, for tasks that edit one scene at once (parallel Studio
+// tasks, P1). A key names one target: object:<id> (a group carries its subtree), character:<id> (its placement, its
+// take, its IK), shot:<id> (its camera, rail and keys), or one of the singletons stage (light, environment, lens),
+// timeline (frame count, shot order and ranges) and scene (documents, the cast library, a replace of a whole kind).
+// timeline and scene are exclusive: no other task runs beside them. A command that only creates (object.add, a kit,
+// character.add) needs no key: what it makes joins its task. A command this table does not know writes scene, so a
+// new command is safe until it is named here.
+const EXCLUSIVE_KEYS = new Set(['timeline', 'scene']);
+const KEY = /^(?:(?:object|character|shot):[A-Za-z0-9][A-Za-z0-9._:-]*|stage|timeline|scene)$/;
+export const isScopeKey = key => typeof key === 'string' && key.length <= 140 && KEY.test(key);
+
+const SCENE = ['cast.replace', 'cast.setCustomPoses', 'cast.showExtras', 'cast.removePose', 'objects.replace', 'shot.replace', 'ai.prepareShot'];
+const TIMELINE = ['shot.create', 'shot.createStill', 'shot.split', 'shot.duplicate', 'shot.remove', 'shot.reorder', 'shot.setRange', 'shot.setTimeline'];
+const CREATE = ['object.add', 'object.createKit', 'asset.import', 'character.add'];
+const CHARACTER = /^(character\.|characters?\b|cast\.(savePose|setLayer)$|ik\.|motion\.)/;
+
+/** object:<id> and every object under it. */
+function objectKeys(ids, state) {
+	const rows = state?.objects ?? [], out = new Set();
+	const visit = id => { if (!id || out.has(`object:${id}`)) return; out.add(`object:${id}`); for (const row of rows) if (row.parent === id) visit(row.id); };
+	for (const id of ids) visit(id);
+	return [...out];
+}
+const arrangeKeys = (ops, state) => ops.flatMap(op => op.op === 'create' ? [] : op.op === 'group' ? objectKeys([op.parentId, ...op.childIds], state)
+	: op.op === 'ungroup' ? objectKeys(op.childIds, state) : objectKeys([op.id], state));
+
+/**
+ * The keys command `id` with validated `args` writes against state `state` (the bus's read), or [] when it writes
+ * none (a read, a view change, a pure creation). `entry` is its registry entry (kind, readOnly).
+ */
+export function commandKeys(id, args = {}, state = {}, entry = {}) {
+	if (entry.kind === 'document' || /^(scene|project)\./.test(id) || id === 'load_scenes' || SCENE.includes(id)) return ['scene'];
+	if (entry.readOnly || entry.kind === 'transient' || /^(view|timeline)\./.test(id) || ['motion.qa', 'motion.sample', 'motion.describe', 'motion.report', 'sculpt.compare', 'export.shotVideo'].includes(id)) return [];
+	if (CREATE.includes(id)) return [];
+	if (id === 'objects.batch') return [...new Set(args.ops.flatMap(op => commandKeys(op.name, op.args, state)))];
+	if (id === 'objects.arrange') return [...new Set(arrangeKeys(args.ops, state))];
+	if (id === 'characters.arrange') return args.ops.flatMap(op => op.op === 'create' ? [] : [`character:${op.characterId}`]);
+	if (id.startsWith('stage.') || id === 'shot.setLens') return ['stage'];
+	if (TIMELINE.includes(id)) return ['timeline'];
+	if (id.startsWith('shot.')) {
+		const shot = args.shotId ?? args.id ?? state.selectedShotId;
+		return shot ? [`shot:${shot}`] : ['timeline'];
+	}
+	if (id === 'object.group') return objectKeys([args.parent, ...args.children], state);
+	if (id === 'object.ungroup') return objectKeys(args.children, state);
+	if (id === 'object.remove') return objectKeys(args.ids, state);
+	if (id === 'object.attach' || id === 'motion.keyObject') return [`character:${args.characterId}`, ...objectKeys([args.objectId], state)];
+	if (id.startsWith('object.')) return objectKeys([args.id ?? args.objectId], state);
+	if (CHARACTER.test(id) && (args.characterId ?? args.id)) return [`character:${args.characterId ?? args.id}`];
+	return ['scene'];
+}
+
+/** The key an id a receipt names resolves to in state, or null (the scene's own id, a removed target). */
+export function keyOfId(id, state = {}) {
+	if ((state.objects ?? []).some(row => row.id === id)) return `object:${id}`;
+	if ((state.characters ?? []).some(row => row.id === id)) return `character:${id}`;
+	if ((state.shots ?? []).some(row => row.id === id)) return `shot:${id}`;
+	return null;
+}
+
+/** Why `keys` cannot join task `taskId` beside the other open tasks, or null. */
+export function scopeConflict(taskId, keys, tasks) {
+	for (const other of tasks.values()) {
+		if (other.taskId === taskId) continue;
+		const held = keys.find(key => other.keys.has(key) || EXCLUSIVE_KEYS.has(key) || [...other.keys].some(k => EXCLUSIVE_KEYS.has(k)));
+		if (held) return `${held} is held by task ${other.taskId}${other.title ? ` (${other.title})` : ''}`;
+	}
+	return null;
+}

package/src/bus-task-targets.js

@@ -0,0 +1,48 @@
+// What a task's scope keys are in the editor's document stores, for the bus's tasks (bus-tasks.js): a snapshot of a
+// key is its rows (an object's row; a character's cast row and motion layer; a shot's row) or, for stage and timeline,
+// the whole slices; restoring puts every row back where it stood (or removes a row the task created) in one composed
+// entry, so undo, history and saves see an ordinary edit. scene is not restorable: documents have no undo.
+import { StudioProtocolError } from './studio-agent-protocol.js';
+
+const ROWS = { object: [['objects', null]], character: [['cast', 'characters'], ['motion', null]], shot: [['shot', 'shots']] };
+const WHOLE = { stage: ['stage'], timeline: ['shot', 'motion'] };
+const split = key => { const at = key.indexOf(':'); return at < 0 ? [key] : [key.slice(0, at), key.slice(at + 1)]; };
+
+function put(slice, part) {
+	if ('whole' in part) return part.whole;
+	const rows = (part.path ? slice[part.path] : slice).filter(row => row.id !== part.id);
+	if (part.row) rows.splice(Math.min(part.index, rows.length), 0, part.row);
+	return part.path ? { ...slice, [part.path]: rows } : rows;
+}
+
+/** snapshotTarget(key) and restoreTargets([{ key, value }]) over the app's store domains (ports.storeDomain, ports.beginAction). */
+export function taskTargetPorts(ports) {
+	const store = domain => ports.storeDomain?.(domain)?.documentStore;
+	const rowParts = (kind, id, read) => ROWS[kind].filter(([domain]) => store(domain)).map(([domain, path]) => {
+		const slice = store(domain).read(domain), rows = (path ? slice?.[path] : slice) ?? [];
+		const index = read ? rows.findIndex(row => row.id === id) : -1;
+		return { domain, path, id, index, row: index < 0 ? undefined : rows[index] };
+	});
+	return {
+		snapshotTarget(key) {
+			const [kind, id] = split(key);
+			if (WHOLE[kind]) return WHOLE[kind].filter(store).map(domain => ({ domain, whole: store(domain).read(domain) }));
+			return ROWS[kind] ? rowParts(kind, id, true) : null;
+		},
+		restoreTargets(values) {
+			const parts = values.flatMap(({ key, value }) => {
+				if (value === null) throw new StudioProtocolError('CAPABILITY_MISSING', `${key} cannot be restored: a document change has no undo.`);
+				const [kind, id] = split(key);
+				return value ?? rowParts(kind, id, false);
+			});
+			const domains = [...new Set(parts.map(part => part.domain))];
+			if (!domains.length) return { historyEntryId: null };
+			const session = ports.beginAction(domains[0], null);
+			try {
+				for (const domain of domains.slice(1)) session.touch(domain);
+				session.run(() => { for (const part of parts) store(part.domain).write(part.domain, slice => put(slice, part)); });
+				return session.commit();
+			} catch (error) { session.cancel(); throw error; }
+		},
+	};
+}

package/src/bus-tasks.js

@@ -0,0 +1,181 @@
+// Tasks: several agents editing one scene at once (parallel Studio tasks, P1; plan in docs). A task holds a scope of
+// keys (bus-task-scopes.js) instead of the whole-scene turn lock: its commands write only inside it, each command
+// commits as its own short entry (the per-command write lock is the document's own composition), and admission reads
+// the scope's target tokens, not the scene revision, so another task's edit elsewhere never makes it stale. Before a
+// key's first write the task keeps its pre-image (ports.snapshotTarget); cancel and undo-task put the pre-images back
+// as one new entry (ports.restoreTargets), which touches no other task's keys. A mark and rollback (a script's start)
+// and undo_edit of the task's newest edit restore the same way. The user's own edits are never refused: the task's
+// next command on a target the user changed answers STALE_TARGET once. Ctrl+Z stops at a running task's entry.
+// A single agent turn (agent.turn.*) is untouched: tasks and a turn never run together.
+import { StudioProtocolError, validateReceipt } from './studio-agent-protocol.js';
+import { commandKeys, keyOfId, scopeConflict, isScopeKey } from './bus-task-scopes.js';
+
+const fail = (code, message) => { throw new StudioProtocolError(code, message); };
+const VERBS = ['begin', 'requestScope', 'mark', 'rollback', 'finish', 'cancel', 'undo'];
+const FINISHED_KEPT = 32;
+const listOf = keys => [...keys].slice(0, 6).join(', ') + (keys.length > 6 ? ` and ${keys.length - 6} more` : '');
+
+export function createBusTasks({ ports, emit }) {
+	const open = new Map(), finished = new Map(), entryTask = new Map();
+	const tokenOf = key => {
+		const [kind, id] = key.split(/:(.*)/s);
+		if (id !== undefined) return ports.readTarget?.(id) ?? 'absent';
+		const state = ports.read();
+		return kind === 'scene' ? `r${state.revision}` : `${kind}:${state.domainRevisions?.[kind === 'timeline' ? 'shot' : kind] ?? 0}`;
+	};
+	const snapshot = key => ({ key, value: ports.snapshotTarget ? ports.snapshotTarget(key) : fail('CAPABILITY_MISSING', 'This editor cannot snapshot task targets.') });
+	// A scene key has no restorable value (documents have no undo): it is left as it is and said so.
+	function restore(task, values, action) {
+		task.skipped = values.filter(v => v.value === null).map(v => v.key);
+		values = values.filter(v => v.value !== null);
+		if (!values.length) return null;
+		if (!ports.restoreTargets) fail('CAPABILITY_MISSING', 'This editor cannot restore task targets.');
+		const { historyEntryId = null } = ports.restoreTargets(values) ?? {};
+		if (historyEntryId) entryTask.set(historyEntryId, task.taskId);
+		task.restored = [...new Set(values.map(({ key }) => key.includes(':') ? key.slice(key.indexOf(':') + 1) : ports.read().host.sceneId))];
+		for (const { key } of values) task.tokens.set(key, tokenOf(key));
+		emit?.({ type: `task.${action}`, taskId: task.taskId, keys: values.map(v => v.key) });
+		return historyEntryId;
+	}
+	function grant(task, keys) {
+		const bad = keys.find(key => !isScopeKey(key));
+		if (bad !== undefined) fail('INVALID_ARGUMENT', `"${bad}" is not a scope key: object:<id>, character:<id>, shot:<id>, stage, timeline or scene.`);
+		const conflict = scopeConflict(task.taskId, keys, open);
+		if (conflict) fail('SCOPE_BUSY', `${conflict}; wait for it, or ask for what is free.`);
+		for (const key of keys) if (!task.keys.has(key)) { task.keys.add(key); task.tokens.set(key, tokenOf(key)); }
+	}
+	function receipt(id, task, request, before, { historyEntryId = null, affectedIds = [], output, warnings = [] } = {}) {
+		const after = ports.read();
+		if (task.skipped?.length) warnings = [...warnings, { code: 'SCOPE_NOT_RESTORED', message: `Left as they are (a document change has no undo): ${listOf(task.skipped)}.` }];
+		task.skipped = null;
+		return validateReceipt({ ok: true, status: 'completed', kind: 'transaction', commandId: request.commandId, receiptId: crypto.randomUUID(), host: before.host,
+			action: id, txId: task.taskId, authored: Boolean(historyEntryId), revision: { before: before.revision, after: after.revision },
+			affectedIds: historyEntryId && !affectedIds.length ? task.restored : affectedIds, delta: [],
+			checks: { coverage: 'task-scope' }, warnings, undo: historyEntryId ? { historyEntryId, entries: 1, canUndoDirect: false } : null,
+			output: { scope: [...task.keys], ...output } });
+	}
+	const ownerOf = (request, taskId) => { if (request.origin !== 'agent' || request.taskId !== taskId) fail('CAPABILITY_MISSING', 'Only the owning task can control it.'); };
+	return {
+		get size() { return open.size; },
+		controls: (object, identifier) => Object.fromEntries(VERBS.map(verb => [`task.${verb}`,
+			verb === 'begin' || verb === 'requestScope'
+				? { ...object({ taskId: identifier, scope: { type: 'array', items: { type: 'string' }, maxItems: 64 } }), properties: { taskId: identifier, scope: { type: 'array', items: { type: 'string' }, maxItems: 64 }, reads: { type: 'array', items: { type: 'string' }, maxItems: 64 }, title: { type: 'string', maxLength: 120 } } }
+				: object({ taskId: identifier })])),
+		/** The open task a request names (null without one); a request naming a closed task is refused. */
+		of(request, id) {
+			if (!request.taskId) return null;
+			const task = open.get(request.taskId);
+			if (!task && !id.startsWith('task.')) fail('STALE_TARGET', `Task ${request.taskId} is not open.`);
+			return task ?? null;
+		},
+		/** task.* controls. `busy` says why no task may begin (an agent turn or a command transaction is open). */
+		control(id, args, request, before, busy) {
+			if (id === 'task.undo') {
+				const task = finished.get(args.taskId) ?? fail('UNDO_EXPIRED', `Task ${args.taskId} is not a finished task this editor still holds.`);
+				// A key moved when its token did and its content did too: a later task undone first puts the same content back
+				// under a new token, and that is not a change.
+				const moved = [...task.final].filter(([key, { token, value }]) => tokenOf(key) !== token && JSON.stringify(snapshot(key).value) !== value).map(([key]) => key);
+				if (moved.length) fail('UNDO_CONFLICT', `Changed since the task finished: ${listOf(moved)}; undo those first or edit by hand.`);
+				const historyEntryId = restore(task, [...task.pre.values()], 'undone');
+				finished.delete(args.taskId);
+				return receipt(id, task, request, before, { historyEntryId, affectedIds: task.affectedIds });
+			}
+			ownerOf(request, args.taskId);
+			if (id === 'task.begin') {
+				if (busy) fail('TARGET_BUSY', busy);
+				if (open.has(args.taskId) || finished.has(args.taskId)) fail('INVALID_ARGUMENT', `Task ${args.taskId} already exists.`);
+				const task = { taskId: args.taskId, title: args.title ?? '', keys: new Set(), reads: new Set(args.reads ?? []), tokens: new Map(), pre: new Map(), edits: [], notices: [], affectedIds: [] };
+				grant(task, args.scope);
+				open.set(task.taskId, task);
+				emit?.({ type: 'task.begun', taskId: task.taskId, scope: [...task.keys] });
+				return receipt(id, task, request, before);
+			}
+			const task = open.get(args.taskId) ?? fail('STALE_TARGET', `Task ${args.taskId} is not open.`);
+			if (id === 'task.requestScope') { grant(task, args.scope); emit?.({ type: 'task.scope', taskId: task.taskId, scope: [...task.keys] }); return receipt(id, task, request, before); }
+			if (id === 'task.mark') { task.mark = { values: [...task.keys].map(snapshot), keys: new Set(task.keys) }; return receipt(id, task, request, before); }
+			if (id === 'task.rollback') {
+				const mark = task.mark ?? fail('STALE_TARGET', 'The task has no mark to roll back to.');
+				task.mark = null;
+				const after = [...task.keys].filter(key => !mark.keys.has(key)).map(key => task.pre.get(key) ?? snapshot(key));
+				const historyEntryId = restore(task, [...mark.values, ...after], 'rolledBack');
+				task.edits = task.edits.filter(edit => edit.mark !== mark);
+				return receipt(id, task, request, before, { historyEntryId });
+			}
+			open.delete(task.taskId);
+			if (id === 'task.cancel') {
+				const historyEntryId = restore(task, [...task.pre.values()], 'cancelled');
+				return receipt(id, task, request, before, { historyEntryId, affectedIds: task.affectedIds });
+			}
+			task.final = new Map([...task.pre.keys()].map(key => [key, { token: tokenOf(key), value: JSON.stringify(snapshot(key).value) }]));
+			finished.set(task.taskId, task);
+			while (finished.size > FINISHED_KEPT) finished.delete(finished.keys().next().value);
+			emit?.({ type: 'task.finished', taskId: task.taskId });
+			return receipt(id, task, request, before, { affectedIds: task.affectedIds, output: { edits: task.edits.length } });
+		},
+		/**
+		 * Admits a command: a task writes only inside its scope, on targets nobody else changed since it last looked; a
+		 * wire caller outside any task may not write a running task's keys; the UI always may. Answers the point a
+		 * task's edit restores to (undo_edit of it), after keeping each key's first pre-image.
+		 */
+		admit(task, entry, args, request, before) {
+			if (!task && !open.size) return null;
+			const keys = entry?.id ? commandKeys(entry.id, args, before, entry) : [];
+			// The user's own edit is never refused; a running task whose scope it touches hears of it (the panel's card).
+			if (!task && request.origin === 'ui') { for (const other of open.values()) { const mine = keys.filter(key => other.keys.has(key)); if (mine.length) emit?.({ type: 'task.userEdit', taskId: other.taskId, keys: mine }); } return null; }
+			if (!task) {
+				const held = keys.find(key => scopeConflict(null, [key], open));
+				if (held) fail('SCOPE_BUSY', `${scopeConflict(null, [held], open)}; this command waits for that task.`);
+				return null;
+			}
+			const outside = keys.filter(key => !task.keys.has(key));
+			if (outside.length) fail('SCOPE_DENIED', `Outside this task's scope: ${listOf(outside)}. Ask for it with task.requestScope, or leave it to the task that holds it.`);
+			const moved = keys.filter(key => task.tokens.has(key) && tokenOf(key) !== task.tokens.get(key));
+			if (moved.length) {
+				for (const key of moved) task.tokens.set(key, tokenOf(key));
+				fail('STALE_TARGET', `${listOf(moved)} changed outside this task (the user, or an undo) since it last looked; read it again, then retry.`);
+			}
+			for (const key of keys) if (!task.pre.has(key)) task.pre.set(key, snapshot(key));
+			return { task, keys, values: keys.map(snapshot), mark: task.mark };
+		},
+		/** Files a task's receipt: ids it created join its scope, it may be undone newest first, readers hear of it. */
+		record(point, recorded) {
+			if (!point || !recorded?.ok) return recorded;
+			const { task } = point, state = ports.read(), warnings = [];
+			let grew = false;
+			for (const id of recorded.affectedIds ?? []) {
+				const key = keyOfId(id, state);
+				if (!key || task.keys.has(key)) continue;
+				if (scopeConflict(task.taskId, [key], open)) warnings.push({ code: 'SCOPE_DENIED', message: `${key} changed outside the task's scope.` });
+				else { task.keys.add(key); grew = true; if (!point.keys.includes(key)) { task.pre.set(key, { key, value: undefined }); point.values.push({ key, value: undefined }); } }
+			}
+			if (grew) emit?.({ type: 'task.scope', taskId: task.taskId, scope: [...task.keys] });
+			for (const key of task.keys) task.tokens.set(key, tokenOf(key));
+			if (recorded.authored) {
+				task.edits.push({ receiptId: recorded.receiptId, values: point.values, keys: point.keys, mark: point.mark });
+				task.affectedIds = [...new Set([...task.affectedIds, ...recorded.affectedIds])];
+				if (recorded.undo?.historyEntryId) entryTask.set(recorded.undo.historyEntryId, task.taskId);
+				for (const other of open.values()) for (const key of point.keys) if (other !== task && other.reads.has(key)) {
+					other.notices.push({ code: 'DEPENDENCY_CHANGED', message: `${key}, which this task reads, was changed by task ${task.taskId}.` });
+					emit?.({ type: 'task.dependencyChanged', taskId: other.taskId, key, by: task.taskId });
+				}
+			}
+			const heard = task.notices.splice(0);
+			return heard.length || warnings.length ? { ...recorded, warnings: [...recorded.warnings, ...warnings, ...heard].slice(0, 12) } : recorded;
+		},
+		/** History traversal: undo_edit of a task's newest edit inside it; the UI's undo stops at a running task's entry. */
+		traversal(id, args, request, before, frontier) {
+			const task = request.taskId ? open.get(request.taskId) : null;
+			if (task && id === 'edit.undo') {
+				const at = task.edits.findIndex(edit => edit.receiptId === args.receiptId);
+				if (at < 0) fail('TARGET_BUSY', `Inside a task, undo_edit takes the receiptId of the task's own newest edit${task.edits.length ? ` (now ${task.edits.at(-1).receiptId})` : ''}.`);
+				if (at < task.edits.length - 1) fail('UNDO_CONFLICT', `Later edits of this task come after it; undo them first, newest first: ${task.edits.slice(at + 1).reverse().map(edit => edit.receiptId).join(', ')}.`);
+				const edit = task.edits.pop(), historyEntryId = restore(task, edit.values, 'editUndone');
+				return receipt(id, task, request, before, { historyEntryId, output: { undoneReceiptId: edit.receiptId } });
+			}
+			const owner = open.get(entryTask.get(frontier));
+			if (!task && owner) fail('TARGET_BUSY', `The last edit belongs to running task ${owner.taskId}${owner.title ? ` (${owner.title})` : ''}; cancel or undo it from that task.`);
+			return null;
+		},
+		dispose() { open.clear(); finished.clear(); entryTask.clear(); },
+	};
+}