@mengine/medeo-client 1.2.1-alpha.7 → 1.2.1-alpha.8

package/dist/index.js

@@ -1,4 +1,4 @@
-import { A as resolveSpeechOverlapByShiftingVideos, B as partUnionToDraft, C as solveVideoDocument, D as reassignSpeechesToVideoClipsByTime, E as fillMainTrackTimeGaps, F as safeDurationMs, H as videoDocumentMirrorSchema, I as DEFAULT_UNIT_TIME_MS, L as VIDEO_DOCUMENT_SCHEMA_VERSION, M as TIMELINE_SKELETON_DURATION_MS, N as isEmptyVideoClip, O as recalculateTimelineDuration, P as partDurationMs, R as effectiveVideoClipDurationMs, S as laneTrackId, T as arrangeMainTrackSeamlessly, U as base64ToBytes, V as recordEntries, W as bytesToBase64, _ as partUnionSchema, a as createMirrorVideoDocument, b as ensureLaneTrack, c as readVideoDocumentFromDraft, d as derivePositionFromAbs, f as fromVideoDocument, g as validateVideoDocument, h as assertValidVideoDocument, i as MirrorVideoDocumentAdapter, j as syncAggregatedClipsTimePosition, k as resolveAllSpeechOverlaps, l as buildInitialVideoDocument, m as VideoDocumentValidationError, n as createPlainMemoryAdapter, o as createMirrorVideoDocumentAdapter, p as toVideoDocument, r as generatePartId, s as writeVideoDocumentToDraft, t as PlainMemoryAdapter, u as buildSpeechHostMap, v as videoDocumentSchema, w as cascadeAfterVideoClipChanges, x as findLaneTrack, y as LANE_KINDS_IN_STACK_ORDER, z as speedOf } from "./document-49OdvviW.js";
+import { $ as base64ToBytes, A as findLaneTrack, B as syncAggregatedClipsTimePosition, C as VideoDocumentValidationError, D as videoDocumentSchema, E as partUnionSchema, F as fillMainTrackTimeGaps, G as DEFAULT_UNIT_TIME_MS, H as isEmptyVideoClip, I as reassignSpeechesToVideoClipsByTime, J as effectiveVideoClipDurationMs, K as ENTITY_TIMELINE_PROJECTION_SCHEMA_VERSION, L as recalculateTimelineDuration, M as solveVideoDocument, N as cascadeAfterVideoClipChanges, O as LANE_KINDS_IN_STACK_ORDER, P as arrangeMainTrackSeamlessly, Q as videoDocumentMirrorSchema, R as resolveAllSpeechOverlaps, S as toVideoDocument, T as validateVideoDocument, U as partDurationMs, V as TIMELINE_SKELETON_DURATION_MS, W as safeDurationMs, X as partUnionToDraft, Y as speedOf, Z as recordEntries, _ as EntityTimelineProjectionError, a as applyEntityTimelineProjection, b as derivePositionFromAbs, c as writeVideoDocumentToDraft, d as resolveEntityTimelineLayout, et as bytesToBase64, f as decodeEntityRelationRows, g as hasSequence, h as createRelationId, i as MirrorVideoDocumentAdapter, j as laneTrackId, k as ensureLaneTrack, l as readVideoDocumentFromDraft, m as createEntityId, n as createPlainMemoryAdapter, o as createMirrorVideoDocument, p as isJsonObject, q as VIDEO_DOCUMENT_SCHEMA_VERSION, r as generatePartId, s as createMirrorVideoDocumentAdapter, t as PlainMemoryAdapter, u as projectEntityTimeline, v as buildInitialVideoDocument, w as assertValidVideoDocument, x as fromVideoDocument, y as buildSpeechHostMap, z as resolveSpeechOverlapByShiftingVideos } from "./document-Df6awJDH.js";
 import { addSpeechesInputSchema, addVideoClipsInputSchema, adjustBgmVolumeInputSchema, adjustSpeechVolumeInputSchema, adjustVideoClipDurationInputSchema, adjustVideoClipVolumeInputSchema, changeSpeechScriptInputSchema, changeSpeechVoiceInputSchema, deleteBgmInputSchema, deleteSpeechesInputSchema, deleteVideoClipsInputSchema, moveSpeechesInputSchema, moveVideoClipsByAnchorInputSchema, moveVideoClipsInputSchema, replaceVideoClipContentInputSchema, replaceVideoClipSequenceInputSchema, setBgmInputSchema, setCaptionStyleInputSchema, setCaptionVisibilityInputSchema, setVideoClipSpeedShiftInputSchema, t as schemas_exports } from "./schemas.js";
 import { LoroDoc, VersionVector } from "loro-crdt";
 import { ClientServerSynchronizer, DocManager } from "@mengine/sync";
@@ -12,7 +12,7 @@ import { BaseDocStorage, DummyConnection } from "@mengine/storage";
 * namespace (mirrors the cluster's `/oapi/v1` precedent for an independent
 * subsystem) rather than folding into the shared `/api/v2/*` space.
 */
-const MENGINE_API_PREFIX = "/api/mengine/v1";
+const MENGINE_API_PREFIX$1 = "/api/mengine/v1";
 var MengineHttpRequestError = class extends Error {
 	status;
 	payload;
@@ -134,12 +134,12 @@ var MengineHttpClient = class {
 			...init,
 			headers
 		});
-		const payload = await safeReadJson(response);
+		const payload = await safeReadJson$1(response);
 		if (!response.ok) throw new MengineHttpRequestError(response.status, payload);
 		return payload;
 	}
 	endpoint(path) {
-		return `${this.options.httpOrigin.replace(/\/$/, "")}${MENGINE_API_PREFIX}/docs/${encodeURIComponent(this.options.docId)}/${path}`;
+		return `${this.options.httpOrigin.replace(/\/$/, "")}${MENGINE_API_PREFIX$1}/docs/${encodeURIComponent(this.options.docId)}/${path}`;
 	}
 };
 /**
@@ -156,7 +156,7 @@ function asPushRejection(error) {
 	if (body.kind !== "rejected" || typeof body.code !== "string") return void 0;
 	return new MenginePushRejectedError(body.code, body.message ?? "", body.server_version, error.status);
 }
-async function safeReadJson(response) {
+async function safeReadJson$1(response) {
 	const text = await response.text();
 	if (text.length === 0) return null;
 	try {
@@ -217,6 +217,2170 @@ function findSseFrameBoundary(buffer) {
 	return Math.min(lf, crlf);
 }
 //#endregion
+//#region src/entity-editor/entity-graph-http-client.ts
+const MENGINE_API_PREFIX = "/api/mengine/v1";
+const numericMarkerValidation$1 = { compareMarkerPoints: (_marker, _range, left, right) => {
+	if (typeof left !== "number" || !Number.isFinite(left) || typeof right !== "number" || !Number.isFinite(right)) throw new Error("entity-state requires finite numeric Marker coordinates");
+	return left < right ? -1 : left > right ? 1 : 0;
+} };
+/** Browser-safe authenticated CAS client for a document's Entity graph. */
+var EntityGraphHttpClient = class {
+	options;
+	transport;
+	endpoint;
+	constructor(options) {
+		this.options = options;
+		this.transport = new MengineHttpClient(options);
+		const origin = options.httpOrigin.replace(/\/$/, "");
+		this.endpoint = `${origin}${MENGINE_API_PREFIX}/docs/${encodeURIComponent(options.docId)}/entity-state`;
+	}
+	async fetchState() {
+		return this.request({ method: "GET" });
+	}
+	/**
+	* Replace the complete Entity graph under the baseline revision.
+	*
+	* Deletion intent is derived from baseline IDs omitted from `nextRows`, so a
+	* transient create-then-remove never becomes a request to delete unknown
+	* persisted data.
+	*/
+	async commit(baseState, nextRows, options = {}) {
+		if (!isNonNegativeSafeInteger(baseState.revision)) throw new Error("Entity graph revision must be a non-negative safe integer");
+		const baseRows = cloneAndValidateRows(baseState.rows);
+		const next = cloneAndValidateRows(nextRows);
+		const nextEntityIds = new Set(next.entities.map((row) => row.entityId));
+		const nextRelationIds = new Set(next.relations.map((row) => row.relationId));
+		const deletedEntityIds = baseRows.entities.map((row) => row.entityId).filter((entityId) => !nextEntityIds.has(entityId)).sort();
+		const deletedRelationIds = baseRows.relations.map((row) => row.relationId).filter((relationId) => !nextRelationIds.has(relationId)).sort();
+		return this.request({
+			method: "POST",
+			body: JSON.stringify({
+				expected_revision: baseState.revision,
+				rows: toWireRows(next),
+				deleted_entity_ids: deletedEntityIds,
+				deleted_relation_ids: deletedRelationIds,
+				...options.migrationBaseVv === void 0 ? {} : { migration_base_vv: options.migrationBaseVv }
+			})
+		});
+	}
+	async request(init) {
+		const response = await this.transport.fetch(this.endpoint, {
+			...init,
+			headers: this.transport.headers()
+		});
+		const payload = await safeReadJson(response);
+		if (!response.ok) throw new MengineHttpRequestError(response.status, payload);
+		return parseWireState(payload, this.options.docId);
+	}
+};
+function parseWireState(value, expectedDocId) {
+	if (!isRecord(value) || typeof value.doc_id !== "string" || !isNonNegativeSafeInteger(value.revision)) throw new Error("Invalid entity-state response envelope");
+	if (value.doc_id !== expectedDocId) throw new Error(`Entity-state response doc_id mismatch: expected "${expectedDocId}"`);
+	const rows = parseWireRows(value.rows);
+	decodeEntityRelationRows(rows, numericMarkerValidation$1);
+	return {
+		revision: value.revision,
+		rows
+	};
+}
+function parseWireRows(value) {
+	if (!isRecord(value) || !Array.isArray(value.entities) || !Array.isArray(value.relations)) throw new Error("Invalid entity-state response rows");
+	return {
+		entities: value.entities.map(parseWireEntity),
+		relations: value.relations.map(parseWireRelation)
+	};
+}
+function parseWireEntity(value) {
+	if (!isRecord(value) || !isJsonObject(value.payload)) throw new Error("Invalid Entity row in entity-state response");
+	return {
+		entityId: createEntityId(requiredString(value.entity_id, "entity_id")),
+		entityKind: requiredString(value.entity_kind, "entity_kind"),
+		payload: structuredClone(value.payload)
+	};
+}
+function parseWireRelation(value) {
+	if (!isRecord(value) || !isJsonObject(value.metadata) || !isJsonObject(value.trace)) throw new Error("Invalid Relation row in entity-state response");
+	return {
+		relationId: createRelationId(requiredString(value.relation_id, "relation_id")),
+		relationKind: requiredString(value.relation_kind, "relation_kind"),
+		endpoint0EntityId: createEntityId(requiredString(value.endpoint_0_entity_id, "endpoint_0_entity_id")),
+		endpoint1EntityId: createEntityId(requiredString(value.endpoint_1_entity_id, "endpoint_1_entity_id")),
+		metadata: structuredClone(value.metadata),
+		trace: structuredClone(value.trace)
+	};
+}
+function cloneAndValidateRows(rows) {
+	const clone = structuredClone(rows);
+	decodeEntityRelationRows(clone, numericMarkerValidation$1);
+	return clone;
+}
+function toWireRows(rows) {
+	return {
+		entities: rows.entities.map((row) => ({
+			entity_id: row.entityId,
+			entity_kind: row.entityKind,
+			payload: row.payload
+		})),
+		relations: rows.relations.map((row) => ({
+			relation_id: row.relationId,
+			relation_kind: row.relationKind,
+			endpoint_0_entity_id: row.endpoint0EntityId,
+			endpoint_1_entity_id: row.endpoint1EntityId,
+			metadata: row.metadata,
+			trace: row.trace
+		}))
+	};
+}
+function requiredString(value, field) {
+	if (typeof value !== "string" || value.length === 0 || value.trim() !== value) throw new Error(`Invalid ${field} in entity-state response`);
+	return value;
+}
+function isRecord(value) {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function isNonNegativeSafeInteger(value) {
+	return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+}
+async function safeReadJson(response) {
+	const text = await response.text();
+	if (text.length === 0) return null;
+	try {
+		return JSON.parse(text);
+	} catch {
+		return text;
+	}
+}
+//#endregion
+//#region src/entity-editor/media-asset-import.ts
+const numericCoordinates = { compareMarkerPoints: (_marker, _range, left, right) => {
+	if (typeof left !== "number" || typeof right !== "number" || !Number.isFinite(left) || !Number.isFinite(right)) throw new Error("Media editor requires numeric coordinates");
+	return left - right;
+} };
+/** Import at the editor boundary, not at asset generation time. Existing provenance is retained. */
+function importMediaAsset(initial, fact, idFactory = (prefix) => `${prefix}_${globalThis.crypto.randomUUID()}`, selection = {}) {
+	if (!fact.assetId || fact.assetId.trim() !== fact.assetId) throw new Error("Expected an asset id");
+	if (![
+		"image",
+		"video",
+		"audio",
+		"voice"
+	].includes(fact.kind)) throw new Error("Unsupported media kind");
+	if (fact.kind !== "image" && (!Number.isFinite(fact.durationMs) || fact.durationMs <= 0)) throw new Error(`${fact.kind} ${fact.assetId} requires its factual positive duration`);
+	if ((fact.kind === "audio" || fact.kind === "voice") && fact.storageKey.trim() === "") throw new Error(`${fact.kind} ${fact.assetId} requires its physical storage key`);
+	decodeEntityRelationRows(initial, numericCoordinates);
+	const entities = structuredClone([...initial.entities]);
+	const relations = structuredClone([...initial.relations]);
+	const assets = entities.filter((row) => {
+		const external = row.payload.external;
+		return row.entityKind === "asset" && isJsonObject(external) && external.system === (fact.kind === "voice" ? "memota-speech" : "memota") && external.key === fact.assetId && (selection.assetEntityId === void 0 || row.entityId === selection.assetEntityId);
+	});
+	if (selection.assetEntityId !== void 0 && assets.length !== 1) throw new Error("Selected Asset does not match the recalled asset facts");
+	if (assets.length > 1) throw new Error(`Ambiguous Asset bindings for ${fact.assetId}; select assetEntityId explicitly`);
+	const mintEntity = () => {
+		const id = createEntityId(idFactory("entity"));
+		if (entities.some((row) => row.entityId === id)) throw new Error(`Duplicate entity id ${id}`);
+		return id;
+	};
+	let asset = assets[0];
+	if (asset === void 0) {
+		asset = {
+			entityId: mintEntity(),
+			entityKind: "asset",
+			payload: {
+				external: {
+					system: fact.kind === "voice" ? "memota-speech" : "memota",
+					key: fact.assetId
+				},
+				...fact.storageKey === void 0 ? {} : { storageKey: fact.storageKey }
+			}
+		};
+		entities.push(asset);
+	} else if (fact.storageKey !== void 0) {
+		if (asset.payload.storageKey !== void 0 && asset.payload.storageKey !== fact.storageKey) throw new Error(`Media facts conflict with existing storage key for ${fact.assetId}`);
+		if (asset.payload.storageKey === void 0) {
+			asset = {
+				...asset,
+				payload: {
+					...asset.payload,
+					storageKey: fact.storageKey
+				}
+			};
+			const assetIndex = entities.findIndex((row) => row.entityId === asset.entityId);
+			entities[assetIndex] = asset;
+		}
+	}
+	const bindings = relations.filter((row) => row.relationKind === "physical-asset" && (row.endpoint0EntityId === asset.entityId || row.endpoint1EntityId === asset.entityId) && (selection.contentEntityId === void 0 || (row.endpoint0EntityId === asset.entityId ? row.endpoint1EntityId : row.endpoint0EntityId) === selection.contentEntityId));
+	const contentIds = new Set(bindings.map((row) => row.endpoint0EntityId === asset.entityId ? row.endpoint1EntityId : row.endpoint0EntityId));
+	if (selection.contentEntityId !== void 0 && contentIds.size !== 1) throw new Error("Selected media Entity is not bound to the selected Asset");
+	if (contentIds.size > 1) throw new Error(`Ambiguous media bindings for ${fact.assetId}; select contentEntityId explicitly`);
+	let content;
+	if (bindings[0] !== void 0) {
+		const relation = bindings[0];
+		content = entities.find((row) => row.entityId === (relation.endpoint0EntityId === asset.entityId ? relation.endpoint1EntityId : relation.endpoint0EntityId));
+		const extent = content?.payload.extent;
+		if (content?.entityKind !== fact.kind || fact.kind !== "image" && (!isJsonObject(extent) || extent.start !== 0 || extent.end !== fact.durationMs) || fact.kind === "voice" && !sameVoice(content.payload.voice, fact.voice)) throw new Error(`Media facts conflict with existing binding for ${fact.assetId}`);
+	} else {
+		const payload = {
+			extent: fact.kind === "image" ? {
+				kind: "unbounded",
+				start: 0
+			} : {
+				kind: "bounded",
+				start: 0,
+				end: fact.durationMs
+			},
+			sampling: fact.kind === "image" ? "constant" : "native",
+			coordinateSpace: "milliseconds",
+			...fact.kind === "voice" ? { voice: {
+				system: fact.voice.system,
+				key: fact.voice.key,
+				...fact.voice.name === void 0 ? {} : { name: fact.voice.name }
+			} } : {}
+		};
+		const createdContent = {
+			entityId: mintEntity(),
+			entityKind: fact.kind,
+			payload
+		};
+		content = createdContent;
+		entities.push(createdContent);
+		const relationId = createRelationId(idFactory("relation"));
+		if (relations.some((row) => row.relationId === relationId)) throw new Error(`Duplicate relation id ${relationId}`);
+		relations.push({
+			relationId,
+			relationKind: "physical-asset",
+			endpoint0EntityId: createdContent.entityId,
+			endpoint1EntityId: asset.entityId,
+			metadata: {},
+			trace: {}
+		});
+	}
+	const rows = {
+		entities,
+		relations
+	};
+	decodeEntityRelationRows(rows, numericCoordinates);
+	if (content === void 0) throw new Error(`Media Entity could not be resolved for ${fact.assetId}`);
+	return {
+		rows,
+		assetEntityId: asset.entityId,
+		contentEntityId: content.entityId
+	};
+}
+function sameVoice(left, right) {
+	return isJsonObject(left) && left.system === right.system && left.key === right.key && left.name === right.name && Object.keys(left).every((key) => key === "system" || key === "key" || key === "name");
+}
+//#endregion
+//#region src/entity-editor/entity-timeline-editor.ts
+const roleOrder = {
+	caption: 0,
+	video_clip: 1,
+	speech: 2,
+	bgm: 3
+};
+const defaultIdFactory = (prefix) => `${prefix}_${globalThis.crypto.randomUUID()}`;
+/**
+* Graph-native timeline authoring over authoritative Medeo Entity and Relation rows.
+*
+* Each mutation is applied to a detached graph, validated as a complete DSL set,
+* and committed only after validation succeeds.
+*/
+var EntityTimelineEditor = class {
+	idFactory;
+	state;
+	constructor(initialRows, idFactory = defaultIdFactory) {
+		this.idFactory = idFactory;
+		this.state = cloneRows(initialRows);
+	}
+	rows() {
+		return cloneRows(this.state);
+	}
+	insertClip(input) {
+		const requestedOrder = input.clipPayload?.order;
+		const order = typeof requestedOrder === "number" ? requestedOrder : nextSequentialOrder(this.state, createEntityId(input.trackEntityId));
+		return this.insertPlacedClip({
+			trackEntityId: input.trackEntityId,
+			contentEntityId: input.contentEntityId,
+			sourceRange: input.sourceRange,
+			duration: input.duration,
+			placement: input.targetRange === void 0 ? {
+				kind: "sequential",
+				order
+			} : {
+				kind: "absolute",
+				targetRange: input.targetRange
+			},
+			clipPayload: input.clipPayload
+		});
+	}
+	insertPlacedClip(input) {
+		return this.transact((draft) => this.insertPlacedClipIntoDraft(draft, input));
+	}
+	updateClipMarker(input) {
+		this.transact((draft) => {
+			const { marker } = requireClipTopology(draft, input.clipEntityId);
+			const payload = { ...cloneJsonObject(marker.payload, "Sequence Marker payload") };
+			if (input.sourceRange !== void 0) payload.sourceRange = cloneJsonValue(input.sourceRange, "sourceRange");
+			if (input.duration !== void 0) payload.duration = cloneJsonValue(input.duration, "duration");
+			if (Object.hasOwn(input, "targetRange")) if (input.targetRange === void 0) {
+				delete payload.targetRange;
+				if (!hasOutgoingClipAnchor(draft, input.clipEntityId)) {
+					const trackId = otherEndpoint(requireOneRelation(draft, createEntityId(input.clipEntityId), "track-clip"), input.clipEntityId);
+					const clipPayload = { ...cloneJsonObject(requireEntityKind(draft, input.clipEntityId, "clip").payload, "Clip payload") };
+					clipPayload.order ??= nextSequentialOrder(draft, trackId);
+					replaceEntity(draft, createEntityId(input.clipEntityId), {
+						...requireEntityKind(draft, input.clipEntityId, "clip"),
+						payload: clipPayload
+					});
+				}
+			} else {
+				payload.targetRange = cloneJsonValue(input.targetRange, "targetRange");
+				const clip = requireEntityKind(draft, input.clipEntityId, "clip");
+				const clipPayload = { ...cloneJsonObject(clip.payload, "Clip payload") };
+				delete clipPayload.order;
+				replaceEntity(draft, clip.entityId, {
+					...clip,
+					payload: clipPayload
+				});
+			}
+			if (Object.hasOwn(input, "timeRemapping")) if (input.timeRemapping === void 0) delete payload.timeRemapping;
+			else payload.timeRemapping = cloneJsonValue(input.timeRemapping, "timeRemapping");
+			replaceEntity(draft, marker.entityId, {
+				...marker,
+				payload
+			});
+		});
+	}
+	setClipPlacement(input) {
+		this.transact((draft) => this.applyClipPlacement(draft, input.clipEntityId, input.placement));
+	}
+	moveSequentialClips(input) {
+		if (input.clipEntityIds.length === 0) throw new Error("At least one Clip is required");
+		this.transact((draft) => {
+			const original = resolveEntityTimelineLayout(draft);
+			this.normalizeMainSequential(draft);
+			const before = resolveEntityTimelineLayout(draft);
+			const targetIds = new Set(input.clipEntityIds);
+			if (targetIds.size !== input.clipEntityIds.length) throw new Error("Clip ids must be unique");
+			const placements = input.clipEntityIds.map((id) => before.clips.get(id));
+			if (placements.some((placement) => placement === void 0 || placement.mode !== "sequential")) throw new Error("moveSequentialClips accepts only sequential Clips");
+			const trackIds = new Set(placements.map((placement) => placement.trackEntityId));
+			if (trackIds.size !== 1) throw new Error("Moved Clips must belong to one Track");
+			const trackId = [...trackIds][0];
+			const track = before.tracks.find((candidate) => candidate.entityId === trackId);
+			if (track?.role !== "video_clip") throw new Error("Only the video_clip Track supports sequential block moves");
+			const ordered = track.clips.filter((placement) => placement.mode === "sequential").map((placement) => placement.clipEntityId);
+			if (input.anchor.position !== "trackStart" && targetIds.has(input.anchor.clipEntityId)) throw new Error("Move anchor cannot be one of the moved Clips");
+			const moved = ordered.filter((id) => targetIds.has(id));
+			if (moved.length !== targetIds.size) throw new Error("Every moved Clip must exist on the target Track");
+			const remaining = ordered.filter((id) => !targetIds.has(id));
+			let insertAt = 0;
+			if (input.anchor.position !== "trackStart") {
+				const anchorIndex = remaining.indexOf(input.anchor.clipEntityId);
+				if (anchorIndex < 0) throw new Error("Move anchor Clip does not exist on the target Track");
+				insertAt = anchorIndex + (input.anchor.position === "after" ? 1 : 0);
+			}
+			[
+				...remaining.slice(0, insertAt),
+				...moved,
+				...remaining.slice(insertAt)
+			].forEach((clipId, order) => setClipOrder(draft, clipId, order));
+			if (input.onAnchored === "keepAbsolute") {
+				const affected = outgoingAnchorChildren(draft, new Set(track.clips.map((clip) => clip.clipEntityId))).filter((childId) => clipRole(draft, childId) === "speech").map((childId) => {
+					const placement = original.clips.get(childId);
+					if (placement === void 0) throw new Error(`Anchored child Clip "${childId}" is not placed`);
+					return {
+						childId,
+						start: placement.start
+					};
+				});
+				const after = resolveEntityTimelineLayout(draft);
+				for (const child of affected) this.reanchorAtAbsolute(draft, child.childId, child.start, after);
+			}
+			this.resolveOneVoiceoverOverlap(draft);
+		});
+	}
+	moveClipsToStarts(input) {
+		if (input.moves.length === 0) throw new Error("At least one Clip move is required");
+		this.transact((draft) => {
+			const original = resolveEntityTimelineLayout(draft);
+			const originalVideo = original.tracks.find((track) => track.role === "video_clip");
+			if (originalVideo === void 0) throw new Error("The timeline has no video_clip Track");
+			const preservedVoiceovers = outgoingAnchorChildren(draft, new Set(originalVideo.clips.map((clip) => clip.clipEntityId))).filter((clipId) => clipRole(draft, clipId) === "speech").map((clipId) => ({
+				clipId,
+				start: original.clips.get(clipId).start
+			}));
+			this.normalizeMainSequential(draft);
+			for (const move of input.moves) {
+				finiteNonNegative(move.newStartMs, "newStartMs");
+				requireClipOnRole(draft, move.clipEntityId, "video_clip");
+				const track = resolveEntityTimelineLayout(draft).tracks.find((candidate) => candidate.role === "video_clip");
+				const ordered = track.clips.map((clip) => clip.clipEntityId);
+				const from = ordered.indexOf(move.clipEntityId);
+				if (from < 0) throw new Error(`Clip "${move.clipEntityId}" is not on the video_clip Track`);
+				const remaining = track.clips.filter((clip) => clip.clipEntityId !== move.clipEntityId);
+				let cursor = 0;
+				let target = remaining.length;
+				for (const [index, clip] of remaining.entries()) {
+					if (move.newStartMs <= cursor + clip.duration / 2) {
+						target = index;
+						break;
+					}
+					cursor += clip.duration;
+				}
+				const next = [...ordered];
+				next.splice(from, 1);
+				next.splice(target, 0, move.clipEntityId);
+				next.forEach((clipId, order) => setClipOrder(draft, clipId, order));
+			}
+			const after = resolveEntityTimelineLayout(draft);
+			for (const voiceover of preservedVoiceovers) this.reanchorAtAbsolute(draft, voiceover.clipId, voiceover.start, after);
+			this.resolveOneVoiceoverOverlap(draft);
+		});
+	}
+	moveClip(input) {
+		this.transact((draft) => {
+			const topology = requireClipTopology(draft, input.clipEntityId);
+			const track = requireEntityKind(draft, input.trackEntityId, "track");
+			requireTrackTimeline(draft, track.entityId);
+			this.relinkRelation(draft, topology.trackRelation, {
+				endpoint0EntityId: track.entityId,
+				endpoint1EntityId: topology.clip.entityId
+			});
+		});
+	}
+	replaceClipContent(input) {
+		this.transact((draft) => {
+			const topology = requireClipTopology(draft, input.clipEntityId);
+			const content = requireSequenceContent(draft, input.contentEntityId);
+			const payload = {
+				...cloneJsonObject(topology.marker.payload, "Sequence Marker payload"),
+				sourceRange: cloneJsonValue(input.sourceRange, "sourceRange"),
+				duration: cloneJsonValue(input.duration, "duration")
+			};
+			delete payload.targetRange;
+			delete payload.timeRemapping;
+			if (input.targetRange !== void 0) payload.targetRange = cloneJsonValue(input.targetRange, "targetRange");
+			if (input.timeRemapping !== void 0) payload.timeRemapping = cloneJsonValue(input.timeRemapping, "timeRemapping");
+			replaceEntity(draft, topology.marker.entityId, {
+				...topology.marker,
+				payload
+			});
+			if (!hasOutgoingClipAnchor(draft, topology.clip.entityId)) {
+				const clipPayload = { ...cloneJsonObject(topology.clip.payload, "Clip payload") };
+				if (input.targetRange === void 0) clipPayload.order ??= nextSequentialOrder(draft, otherEndpoint(topology.trackRelation, topology.clip.entityId));
+				else delete clipPayload.order;
+				replaceEntity(draft, topology.clip.entityId, {
+					...topology.clip,
+					payload: clipPayload
+				});
+			}
+			this.relinkRelation(draft, topology.markerContentRelation, {
+				endpoint0EntityId: topology.marker.entityId,
+				endpoint1EntityId: content.entityId
+			});
+		});
+	}
+	insertMediaClip(input) {
+		return this.transact((draft) => {
+			if (input.placement.kind === "sequential") this.normalizeMainSequential(draft);
+			const imported = importMediaAsset(draft, input.media, this.idFactory);
+			replaceRows(draft, imported.rows);
+			const track = this.ensureRoleTrack(draft, input.timelineEntityId, "video_clip");
+			const sourceRange = requirePositiveRange(input.sourceRange, "sourceRange");
+			const clipId = this.insertPlacedClipIntoDraft(draft, {
+				trackEntityId: track.entityId,
+				contentEntityId: imported.contentEntityId,
+				sourceRange,
+				duration: {
+					mode: "fixed",
+					value: sourceRange.end - sourceRange.start
+				},
+				placement: input.placement,
+				...input.clipEntityId === void 0 ? {} : { clipEntityId: input.clipEntityId },
+				...input.volume === void 0 ? {} : { clipPayload: { volume: requireVolume(input.volume) } }
+			});
+			if (input.placement.kind === "sequential") this.resolveOneVoiceoverOverlap(draft);
+			return clipId;
+		});
+	}
+	insertMediaClips(input) {
+		if (input.clips.length === 0) throw new Error("At least one media Clip is required");
+		return this.transact((draft) => {
+			this.normalizeMainSequential(draft);
+			const track = this.ensureRoleTrack(draft, input.timelineEntityId, "video_clip");
+			const ordered = resolveEntityTimelineLayout(draft).tracks.find((candidate) => candidate.entityId === track.entityId)?.clips ?? [];
+			let insertAt = ordered.length;
+			const insertion = input.insertion;
+			if (insertion.kind === "before" || insertion.kind === "after") {
+				const anchorIndex = ordered.findIndex((clip) => clip.clipEntityId === insertion.clipEntityId);
+				if (anchorIndex >= 0) insertAt = anchorIndex + (insertion.kind === "after" ? 1 : 0);
+			} else {
+				const startMs = finiteNonNegative(insertion.startMs, "firstStart.startMs");
+				let cursor = 0;
+				for (const [index, clip] of ordered.entries()) {
+					if (startMs <= cursor + clip.duration / 2) {
+						insertAt = index;
+						break;
+					}
+					cursor += clip.duration;
+				}
+			}
+			const created = [];
+			for (const [offset, clip] of input.clips.entries()) {
+				const imported = importMediaAsset(draft, clip.media, this.idFactory);
+				replaceRows(draft, imported.rows);
+				const sourceRange = requirePositiveRange(clip.sourceRange, "sourceRange");
+				created.push(this.insertPlacedClipIntoDraft(draft, {
+					trackEntityId: track.entityId,
+					contentEntityId: imported.contentEntityId,
+					sourceRange,
+					duration: {
+						mode: "fixed",
+						value: sourceRange.end - sourceRange.start
+					},
+					placement: {
+						kind: "sequential",
+						order: ordered.length + offset
+					},
+					...clip.clipEntityId === void 0 ? {} : { clipEntityId: clip.clipEntityId },
+					...clip.volume === void 0 ? {} : { clipPayload: { volume: requireVolume(clip.volume) } }
+				}));
+			}
+			const desired = ordered.map((clip) => clip.clipEntityId);
+			desired.splice(insertAt, 0, ...created);
+			desired.forEach((clipId, order) => setClipOrder(draft, clipId, order));
+			this.resolveOneVoiceoverOverlap(draft);
+			return created;
+		});
+	}
+	replaceMediaClip(input) {
+		this.transact((draft) => {
+			this.normalizeMainSequential(draft);
+			const topology = requireClipOnRole(draft, input.clipEntityId, "video_clip");
+			const imported = importMediaAsset(draft, input.media, this.idFactory);
+			replaceRows(draft, imported.rows);
+			const sourceRange = requirePositiveRange(input.sourceRange, "sourceRange");
+			const markerPayloadValue = {
+				...cloneJsonObject(topology.marker.payload, "Sequence Marker payload"),
+				sourceRange,
+				duration: {
+					mode: "fixed",
+					value: sourceRange.end - sourceRange.start
+				}
+			};
+			delete markerPayloadValue.timeRemapping;
+			resizeAbsoluteTarget(markerPayloadValue, sourceRange.end - sourceRange.start);
+			replaceEntity(draft, topology.marker.entityId, {
+				...topology.marker,
+				payload: markerPayloadValue
+			});
+			this.relinkRelation(draft, topology.markerContentRelation, {
+				endpoint0EntityId: topology.marker.entityId,
+				endpoint1EntityId: createEntityId(imported.contentEntityId)
+			});
+			this.resolveOneVoiceoverOverlap(draft);
+		});
+	}
+	setClipVolume(input) {
+		this.transact((draft) => {
+			const topology = requireClipTopology(draft, input.clipEntityId);
+			requireSupportedRole(draft, topology);
+			replaceEntity(draft, topology.clip.entityId, {
+				...topology.clip,
+				payload: {
+					...topology.clip.payload,
+					volume: requireVolume(input.volume)
+				}
+			});
+		});
+	}
+	setClipSpeed(input) {
+		this.transact((draft) => {
+			const initialTopology = requireClipOnRole(draft, input.clipEntityId, "video_clip");
+			const content = requireSequenceContent(draft, otherEndpoint(initialTopology.markerContentRelation, initialTopology.marker.entityId));
+			if (content.entityKind !== "video" && content.entityKind !== "image") throw new Error("Clip speed is supported only for Video or Image content");
+			const initialPayload = cloneJsonObject(initialTopology.marker.payload, "Sequence Marker payload");
+			const priorSource = requirePositiveRange(initialPayload.sourceRange, "sourceRange");
+			if (input.timeRemapping === null && initialPayload.timeRemapping === void 0) return;
+			this.normalizeMainSequential(draft);
+			const topology = requireClipTopology(draft, input.clipEntityId);
+			const payload = { ...cloneJsonObject(topology.marker.payload, "Sequence Marker payload") };
+			let sourceRange = priorSource;
+			if (content.entityKind === "image" && initialPayload.timeRemapping === void 0 && input.timeRemapping !== null) sourceRange = {
+				start: 0,
+				end: markerDuration(initialPayload, priorSource)
+			};
+			if (input.timeRemapping === null) {
+				delete payload.timeRemapping;
+				payload.sourceRange = sourceRange;
+				payload.duration = {
+					mode: "fixed",
+					value: sourceRange.end - sourceRange.start
+				};
+			} else {
+				const rate = finitePositive(input.timeRemapping.rate, "linear speed rate");
+				const duration = Math.round((sourceRange.end - sourceRange.start) / rate);
+				if (duration <= 0 || !Number.isSafeInteger(duration)) throw new Error("Linear speed produces an invalid duration");
+				payload.sourceRange = sourceRange;
+				payload.duration = {
+					mode: "fixed",
+					value: duration
+				};
+				payload.timeRemapping = {
+					kind: "linear",
+					rate,
+					...input.timeRemapping.mode === void 0 ? {} : { mode: input.timeRemapping.mode }
+				};
+			}
+			resizeAbsoluteTarget(payload, markerDuration(payload, sourceRange));
+			replaceEntity(draft, topology.marker.entityId, {
+				...topology.marker,
+				payload
+			});
+			this.resolveOneVoiceoverOverlap(draft);
+		});
+	}
+	trimClip(input) {
+		this.transact((draft) => {
+			this.normalizeMainSequential(draft);
+			const topology = requireClipOnRole(draft, input.clipEntityId, "video_clip");
+			const content = requireSequenceContent(draft, otherEndpoint(topology.markerContentRelation, topology.marker.entityId));
+			if (content.entityKind !== "video" && content.entityKind !== "image") throw new Error("Clip trimming is supported only for Video or Image content");
+			const sourceRange = requirePositiveRange(input.sourceRange, "sourceRange");
+			const payload = {
+				...cloneJsonObject(topology.marker.payload, "Sequence Marker payload"),
+				sourceRange
+			};
+			const rate = linearRate(payload.timeRemapping);
+			const duration = Math.round((sourceRange.end - sourceRange.start) / rate);
+			if (duration <= 0 || !Number.isSafeInteger(duration)) throw new Error("Trim produces an invalid duration");
+			payload.duration = {
+				mode: "fixed",
+				value: duration
+			};
+			resizeAbsoluteTarget(payload, duration);
+			replaceEntity(draft, topology.marker.entityId, {
+				...topology.marker,
+				payload
+			});
+			this.resolveOneVoiceoverOverlap(draft);
+		});
+	}
+	replaceSequentialClips(input) {
+		if (input.oldClipEntityIds.length === 0 || input.newClips.length === 0) throw new Error("Replacement requires at least one old and one new Clip");
+		return this.transact((draft) => {
+			this.normalizeMainSequential(draft);
+			const before = resolveEntityTimelineLayout(draft);
+			const oldIds = new Set(input.oldClipEntityIds);
+			if (oldIds.size !== input.oldClipEntityIds.length) throw new Error("Old Clip ids must be unique");
+			const track = this.ensureRoleTrack(draft, input.timelineEntityId, "video_clip");
+			const ordered = before.tracks.find((candidate) => candidate.entityId === track.entityId)?.clips.filter((clip) => clip.mode === "sequential").map((clip) => clip.clipEntityId);
+			if (ordered === void 0) throw new Error("The video_clip Track is not present in the current layout");
+			const indexes = input.oldClipEntityIds.map((id) => ordered.indexOf(id));
+			if (indexes.some((index) => index < 0)) throw new Error("Every replaced Clip must be sequential on video_clip");
+			const sortedIndexes = [...indexes].sort((left, right) => left - right);
+			if (sortedIndexes.some((index, offset) => index !== sortedIndexes[0] + offset)) throw new Error("Replaced Clips must form one contiguous timeline run");
+			if (input.oldClipEntityIds.some((id, index) => id !== ordered[sortedIndexes[0] + index])) throw new Error("Replaced Clip ids must be listed in timeline order");
+			const insertOrder = sortedIndexes[0];
+			const temporaryOrder = ordered.length;
+			const created = [];
+			for (const [offset, replacement] of input.newClips.entries()) {
+				if (replacement.clipEntityId !== void 0 && oldIds.has(replacement.clipEntityId)) throw new Error("A replacement Clip id cannot reuse an Entity being removed");
+				const imported = importMediaAsset(draft, replacement.media, this.idFactory);
+				replaceRows(draft, imported.rows);
+				const sourceRange = requirePositiveRange(replacement.sourceRange, "sourceRange");
+				created.push(this.insertPlacedClipIntoDraft(draft, {
+					trackEntityId: track.entityId,
+					contentEntityId: imported.contentEntityId,
+					sourceRange,
+					duration: {
+						mode: "fixed",
+						value: sourceRange.end - sourceRange.start
+					},
+					placement: {
+						kind: "sequential",
+						order: temporaryOrder + offset
+					},
+					...replacement.clipEntityId === void 0 ? {} : { clipEntityId: replacement.clipEntityId },
+					...replacement.volume === void 0 ? {} : { clipPayload: { volume: requireVolume(replacement.volume) } }
+				}));
+			}
+			for (const [index, oldId] of input.oldClipEntityIds.entries()) {
+				const children = directAnchorChildren(draft, oldId);
+				if (input.onAnchored === "remap" && created[index] !== void 0) for (const childId of children) this.replaceAnchorHost(draft, childId, created[index]);
+				else {
+					const scheduled = /* @__PURE__ */ new Set();
+					for (const childId of children) {
+						scheduled.add(childId);
+						this.removeAnchoredDescendants(draft, childId, scheduled);
+						this.removeClipGraph(draft, childId);
+					}
+				}
+			}
+			for (const oldId of input.oldClipEntityIds) this.removeClipGraph(draft, oldId);
+			[
+				...ordered.slice(0, insertOrder),
+				...created,
+				...ordered.slice(insertOrder + input.oldClipEntityIds.length)
+			].forEach((clipId, order) => setClipOrder(draft, clipId, order));
+			this.resolveOneVoiceoverOverlap(draft);
+			return created;
+		});
+	}
+	deleteClip(input) {
+		this.transact((draft) => {
+			const topology = requireClipTopology(draft, input.clipEntityId);
+			assertOnlyStructuralIncidents(draft, topology.clip.entityId, new Set(["track-clip", "clip-marker"]));
+			assertOnlyStructuralIncidents(draft, topology.marker.entityId, new Set(["clip-marker", "marker-content"]));
+			const markerIsExclusive = incidentRelations(draft, topology.marker.entityId).filter((relation) => relation.relationKind === "clip-marker").length === 1;
+			const removedRelationIds = new Set([topology.trackRelation.relationId, topology.clipMarkerRelation.relationId]);
+			if (markerIsExclusive) for (const relation of incidentRelations(draft, topology.marker.entityId)) removedRelationIds.add(relation.relationId);
+			draft.relations = draft.relations.filter((relation) => !removedRelationIds.has(relation.relationId));
+			draft.entities = draft.entities.filter((entity) => entity.entityId !== topology.clip.entityId && (!markerIsExclusive || entity.entityId !== topology.marker.entityId));
+		});
+	}
+	deleteClipTree(input) {
+		if (input.clipEntityIds.length === 0) throw new Error("At least one Clip is required");
+		this.transact((draft) => {
+			const targets = new Set(input.clipEntityIds);
+			if (targets.size !== input.clipEntityIds.length) throw new Error("Clip ids must be unique");
+			for (const target of targets) requireEntityKind(draft, target, "clip");
+			const includesVisual = [...targets].some((target) => clipRole(draft, target) === "video_clip");
+			const original = resolveEntityTimelineLayout(draft);
+			if (includesVisual) this.normalizeMainSequential(draft);
+			if (input.onAnchored === "detach") for (const childId of outgoingAnchorChildren(draft, targets)) {
+				if (targets.has(childId)) continue;
+				const placement = original.clips.get(childId);
+				if (placement === void 0) throw new Error(`Anchored child Clip "${childId}" is not placed`);
+				this.applyClipPlacement(draft, childId, {
+					kind: "absolute",
+					targetRange: {
+						start: placement.start,
+						end: placement.start + placement.duration
+					}
+				});
+			}
+			else for (const target of targets) this.removeAnchoredDescendants(draft, target, targets);
+			for (const target of targets) this.removeClipGraph(draft, target);
+			normalizeSequentialOrders(draft);
+			if (includesVisual) this.resolveOneVoiceoverOverlap(draft);
+		});
+	}
+	updateClip(input) {
+		this.transact((draft) => {
+			const clip = requireEntityKind(draft, input.clipEntityId, "clip");
+			const priorOrder = clip.payload.order;
+			replaceEntity(draft, clip.entityId, {
+				...clip,
+				payload: {
+					...cloneJsonObject(input.payload, "Clip payload"),
+					...priorOrder === void 0 || Object.hasOwn(input.payload, "order") ? {} : { order: priorOrder }
+				}
+			});
+		});
+	}
+	upsertVoiceoverTake(input) {
+		return this.transact((draft) => {
+			this.normalizeMainSequential(draft);
+			finiteNonNegative(input.anchorOffset, "Voiceover anchorOffset");
+			requireVolume(input.volume);
+			requireClipOnRole(draft, input.hostClipEntityId, "video_clip");
+			const imported = importMediaAsset(draft, input.media, this.idFactory);
+			replaceRows(draft, imported.rows);
+			const voice = requireEntityKind(draft, imported.contentEntityId, "voice");
+			const script = this.ensureAudioScript(draft, voice.entityId, input.scriptText);
+			const speechTrack = this.ensureRoleTrack(draft, input.timelineEntityId, "speech");
+			const existing = draft.entities.find((row) => row.entityId === input.voiceoverClipEntityId);
+			let voiceoverClipEntityId;
+			if (existing === void 0) voiceoverClipEntityId = this.insertPlacedClipIntoDraft(draft, {
+				clipEntityId: input.voiceoverClipEntityId,
+				trackEntityId: speechTrack.entityId,
+				contentEntityId: voice.entityId,
+				sourceRange: {
+					start: 0,
+					end: input.media.durationMs
+				},
+				duration: {
+					mode: "fixed",
+					value: input.media.durationMs
+				},
+				placement: {
+					kind: "anchored",
+					hostClipEntityId: input.hostClipEntityId,
+					anchorOffset: input.anchorOffset
+				},
+				clipPayload: { volume: input.volume }
+			});
+			else {
+				const topology = requireClipOnRole(draft, input.voiceoverClipEntityId, "speech");
+				voiceoverClipEntityId = topology.clip.entityId;
+				replaceEntity(draft, topology.clip.entityId, {
+					...topology.clip,
+					payload: {
+						...topology.clip.payload,
+						volume: input.volume
+					}
+				});
+				this.relinkRelation(draft, topology.markerContentRelation, {
+					endpoint0EntityId: topology.marker.entityId,
+					endpoint1EntityId: voice.entityId
+				});
+				this.applyClipPlacement(draft, topology.clip.entityId, {
+					kind: "anchored",
+					hostClipEntityId: input.hostClipEntityId,
+					anchorOffset: input.anchorOffset
+				});
+				const placed = requireClipTopology(draft, topology.clip.entityId);
+				replaceEntity(draft, placed.marker.entityId, {
+					...placed.marker,
+					payload: {
+						...placed.marker.payload,
+						sourceRange: {
+							start: 0,
+							end: input.media.durationMs
+						},
+						duration: {
+							mode: "fixed",
+							value: input.media.durationMs
+						}
+					}
+				});
+			}
+			this.reconcileVoiceoverCaptions(draft, voiceoverClipEntityId, voice.entityId, script.entityId, input.captions);
+			this.resolveOneVoiceoverOverlap(draft);
+			return {
+				voiceoverClipEntityId,
+				voiceEntityId: voice.entityId,
+				audioScriptEntityId: script.entityId,
+				captionClipEntityIds: input.captions.map((caption) => caption.captionClipEntityId)
+			};
+		});
+	}
+	moveVoiceover(input) {
+		this.transact((draft) => {
+			requireClipOnRole(draft, input.voiceoverClipEntityId, "speech");
+			this.normalizeMainSequential(draft);
+			const layout = resolveEntityTimelineLayout(draft);
+			this.reanchorAtAbsolute(draft, input.voiceoverClipEntityId, finiteNonNegative(input.newStartMs, "newStartMs"), layout);
+			this.resolveOneVoiceoverOverlap(draft);
+		});
+	}
+	deleteVoiceover(input) {
+		this.transact((draft) => {
+			this.normalizeMainSequential(draft);
+			const targets = new Set(input.voiceoverClipEntityIds);
+			if (targets.size !== input.voiceoverClipEntityIds.length) throw new Error("Voiceover Clip ids must be unique");
+			for (const clipId of targets) {
+				requireClipOnRole(draft, clipId, "speech");
+				this.removeAnchoredDescendants(draft, clipId, targets);
+			}
+			for (const clipId of targets) this.removeClipGraph(draft, clipId);
+			this.resolveOneVoiceoverOverlap(draft);
+		});
+	}
+	setBgm(input) {
+		return this.transact((draft) => {
+			const imported = importMediaAsset(draft, input.media, this.idFactory);
+			replaceRows(draft, imported.rows);
+			const track = this.ensureRoleTrack(draft, input.timelineEntityId, "bgm");
+			const existing = clipsOnTrack(draft, track.entityId);
+			for (const clip of existing) this.removeClipGraph(draft, clip.entityId);
+			const clipId = this.insertPlacedClipIntoDraft(draft, {
+				clipEntityId: input.bgmClipEntityId,
+				trackEntityId: track.entityId,
+				contentEntityId: imported.contentEntityId,
+				sourceRange: {
+					start: 0,
+					end: input.media.durationMs
+				},
+				duration: { mode: "from-source" },
+				placement: {
+					kind: "sequential",
+					order: 0
+				},
+				clipPayload: { volume: requireVolume(input.volume) }
+			});
+			const topology = requireClipTopology(draft, clipId);
+			replaceEntity(draft, topology.marker.entityId, {
+				...topology.marker,
+				payload: {
+					...topology.marker.payload,
+					durationPolicy: "timeline"
+				}
+			});
+			return clipId;
+		});
+	}
+	deleteBgm(input) {
+		this.transact((draft) => {
+			const track = findRoleTrack(draft, input.timelineEntityId, "bgm");
+			if (track === void 0) return;
+			for (const clip of clipsOnTrack(draft, track.entityId)) this.removeClipGraph(draft, clip.entityId);
+		});
+	}
+	setCaptionVisibility(input) {
+		this.transact((draft) => {
+			const track = this.ensureRoleTrack(draft, input.timelineEntityId, "caption");
+			replaceEntity(draft, track.entityId, {
+				...track,
+				payload: {
+					...track.payload,
+					hidden: input.hidden
+				}
+			});
+		});
+	}
+	patchCaptionStyle(input) {
+		this.transact((draft) => {
+			const track = findRoleTrack(draft, input.timelineEntityId, "caption");
+			if (track === void 0) return;
+			const patch = cloneJsonObject(input.style, "Caption style");
+			for (const clip of clipsOnTrack(draft, track.entityId)) {
+				const topology = requireClipTopology(draft, clip.entityId);
+				const caption = requireEntityKind(draft, otherEndpoint(topology.markerContentRelation, topology.marker.entityId), "caption");
+				const prior = caption.payload.style;
+				const style = isJsonObject(prior) ? prior : {};
+				replaceEntity(draft, caption.entityId, {
+					...caption,
+					payload: {
+						...caption.payload,
+						style: {
+							...style,
+							...patch
+						}
+					}
+				});
+			}
+		});
+	}
+	insertPlacedClipIntoDraft(draft, input) {
+		const track = requireEntityKind(draft, input.trackEntityId, "track");
+		requireTrackTimeline(draft, track.entityId);
+		const content = requireSequenceContent(draft, input.contentEntityId);
+		const clipId = input.clipEntityId === void 0 ? this.mintEntityId(draft) : requireAvailableEntityId(draft, input.clipEntityId);
+		const markerId = this.mintEntityId(draft);
+		const clipPayload = { ...cloneJsonObject(input.clipPayload ?? {}, "Clip payload") };
+		delete clipPayload.order;
+		const markerPlacement = applyPlacementPayload(clipPayload, input.placement);
+		const clip = {
+			entityId: clipId,
+			entityKind: "clip",
+			payload: clipPayload
+		};
+		const marker = {
+			entityId: markerId,
+			entityKind: "sequence-marker",
+			payload: markerPayload({
+				sourceRange: input.sourceRange,
+				duration: input.duration,
+				...markerPlacement
+			})
+		};
+		draft.entities.push(clip, marker);
+		draft.relations.push(this.createRelation(draft, "track-clip", track.entityId, clipId), this.createRelation(draft, "clip-marker", clipId, markerId), this.createRelation(draft, "marker-content", markerId, content.entityId));
+		if (input.placement.kind === "anchored") {
+			const host = requireEntityKind(draft, input.placement.hostClipEntityId, "clip");
+			if (host.entityId === clipId) throw new Error("A Clip cannot anchor to itself");
+			draft.relations.push(this.createRelation(draft, "clip-anchor", clipId, host.entityId));
+		}
+		return clipId;
+	}
+	ensureRoleTrack(draft, timelineEntityId, role) {
+		const existing = findRoleTrack(draft, timelineEntityId, role);
+		if (existing !== void 0) {
+			if (existing.payload.order === void 0) {
+				const replacement = {
+					...existing,
+					payload: {
+						...existing.payload,
+						order: roleOrder[role]
+					}
+				};
+				replaceEntity(draft, existing.entityId, replacement);
+				return replacement;
+			}
+			return existing;
+		}
+		const timeline = requireEntityKind(draft, timelineEntityId, "timeline");
+		const track = {
+			entityId: this.mintEntityId(draft),
+			entityKind: "track",
+			payload: {
+				role,
+				order: roleOrder[role]
+			}
+		};
+		draft.entities.push(track);
+		draft.relations.push(this.createRelation(draft, "timeline-track", timeline.entityId, track.entityId));
+		return track;
+	}
+	ensureAudioScript(draft, voiceEntityId, text) {
+		const renders = draft.relations.filter((relation) => relation.relationKind === "audio-script-render" && relation.endpoint0EntityId === voiceEntityId);
+		if (renders.length > 1) throw new Error(`Voice "${voiceEntityId}" has multiple AudioScript relations`);
+		if (renders[0] !== void 0) {
+			const script = requireEntityKind(draft, renders[0].endpoint1EntityId, "audio-script");
+			const replacement = {
+				...script,
+				payload: { segments: [{
+					segmentId: "segment-0",
+					text
+				}] }
+			};
+			replaceEntity(draft, script.entityId, replacement);
+			return replacement;
+		}
+		const script = {
+			entityId: this.mintEntityId(draft),
+			entityKind: "audio-script",
+			payload: { segments: [{
+				segmentId: "segment-0",
+				text
+			}] }
+		};
+		draft.entities.push(script);
+		draft.relations.push(this.createRelation(draft, "audio-script-render", voiceEntityId, script.entityId));
+		return script;
+	}
+	reconcileVoiceoverCaptions(draft, voiceoverClipEntityId, voiceEntityId, scriptEntityId, captions) {
+		const requested = new Set(captions.map((caption) => caption.captionClipEntityId));
+		if (requested.size !== captions.length) throw new Error("Caption Clip ids must be unique within a voiceover take");
+		const existing = directAnchorChildren(draft, voiceoverClipEntityId).filter((clipId) => clipRole(draft, clipId) === "caption");
+		for (const clipId of existing) if (!requested.has(clipId)) this.removeCaptionClipGraph(draft, clipId);
+		const captionTrack = captions.length === 0 ? void 0 : this.ensureRoleTrackForClip(draft, voiceoverClipEntityId, "caption");
+		for (const caption of captions) {
+			const startMs = finiteNonNegative(caption.startMs, "Caption startMs");
+			const durationMs = finitePositive(caption.durationMs, "Caption durationMs");
+			if (draft.entities.find((entity) => entity.entityId === caption.captionClipEntityId) === void 0) {
+				const content = {
+					entityId: this.mintEntityId(draft),
+					entityKind: "caption",
+					payload: {
+						extent: {
+							kind: "bounded",
+							start: 0,
+							end: durationMs
+						},
+						sampling: "native",
+						coordinateSpace: "milliseconds",
+						text: caption.text,
+						...caption.style === void 0 ? {} : { style: cloneJsonObject(caption.style, "Caption style") }
+					}
+				};
+				const asset = {
+					entityId: this.mintEntityId(draft),
+					entityKind: "asset",
+					payload: { inline: {
+						mediaType: "text/plain",
+						text: caption.text
+					} }
+				};
+				draft.entities.push(content, asset);
+				draft.relations.push(this.createRelation(draft, "physical-asset", content.entityId, asset.entityId), this.createRelation(draft, "caption-alignment", content.entityId, voiceEntityId, { alignment: {
+					start: startMs,
+					end: startMs + durationMs
+				} }), this.createRelation(draft, "caption-provenance", content.entityId, scriptEntityId, { segmentAlignment: [] }));
+				this.insertPlacedClipIntoDraft(draft, {
+					clipEntityId: caption.captionClipEntityId,
+					trackEntityId: captionTrack.entityId,
+					contentEntityId: content.entityId,
+					sourceRange: {
+						start: 0,
+						end: durationMs
+					},
+					duration: {
+						mode: "fixed",
+						value: durationMs
+					},
+					placement: {
+						kind: "anchored",
+						hostClipEntityId: voiceoverClipEntityId,
+						anchorOffset: startMs
+					}
+				});
+				continue;
+			}
+			const topology = requireClipOnRole(draft, caption.captionClipEntityId, "caption");
+			const content = requireEntityKind(draft, otherEndpoint(topology.markerContentRelation, topology.marker.entityId), "caption");
+			const priorStyle = isJsonObject(content.payload.style) ? content.payload.style : {};
+			const style = caption.style === void 0 ? priorStyle : {
+				...priorStyle,
+				...cloneJsonObject(caption.style, "Caption style")
+			};
+			replaceEntity(draft, content.entityId, {
+				...content,
+				payload: {
+					...content.payload,
+					extent: {
+						kind: "bounded",
+						start: 0,
+						end: durationMs
+					},
+					text: caption.text,
+					...Object.keys(style).length === 0 ? {} : { style }
+				}
+			});
+			const asset = requireEntityKind(draft, otherEndpoint(requireOneRelation(draft, content.entityId, "physical-asset"), content.entityId), "asset");
+			if (asset.payload.inline === void 0) throw new Error(`Caption "${caption.captionClipEntityId}" is not inline`);
+			replaceEntity(draft, asset.entityId, {
+				...asset,
+				payload: {
+					...asset.payload,
+					inline: {
+						mediaType: "text/plain",
+						text: caption.text
+					}
+				}
+			});
+			this.applyClipPlacement(draft, topology.clip.entityId, {
+				kind: "anchored",
+				hostClipEntityId: voiceoverClipEntityId,
+				anchorOffset: startMs
+			});
+			const placed = requireClipTopology(draft, topology.clip.entityId);
+			replaceEntity(draft, placed.marker.entityId, {
+				...placed.marker,
+				payload: {
+					...placed.marker.payload,
+					sourceRange: {
+						start: 0,
+						end: durationMs
+					},
+					duration: {
+						mode: "fixed",
+						value: durationMs
+					}
+				}
+			});
+			this.replaceCaptionSemanticRelations(draft, content.entityId, voiceEntityId, scriptEntityId, startMs, durationMs);
+		}
+	}
+	ensureRoleTrackForClip(draft, clipEntityId, role) {
+		const topology = requireClipTopology(draft, clipEntityId);
+		const track = requireEntityKind(draft, otherEndpoint(topology.trackRelation, topology.clip.entityId), "track");
+		const timeline = requireEntityKind(draft, otherEndpoint(requireOneRelation(draft, track.entityId, "timeline-track"), track.entityId), "timeline");
+		return this.ensureRoleTrack(draft, timeline.entityId, role);
+	}
+	replaceCaptionSemanticRelations(draft, captionEntityId, voiceEntityId, scriptEntityId, startMs, durationMs) {
+		const removed = new Set(incidentRelations(draft, captionEntityId).filter((relation) => relation.relationKind === "caption-alignment" || relation.relationKind === "caption-provenance").map((relation) => relation.relationId));
+		draft.relations = draft.relations.filter((relation) => !removed.has(relation.relationId));
+		draft.relations.push(this.createRelation(draft, "caption-alignment", captionEntityId, voiceEntityId, { alignment: {
+			start: startMs,
+			end: startMs + durationMs
+		} }), this.createRelation(draft, "caption-provenance", captionEntityId, scriptEntityId, { segmentAlignment: [] }));
+	}
+	removeCaptionClipGraph(draft, clipEntityId) {
+		const topology = requireClipOnRole(draft, clipEntityId, "caption");
+		const caption = requireEntityKind(draft, otherEndpoint(topology.markerContentRelation, topology.marker.entityId), "caption");
+		const asset = requireEntityKind(draft, otherEndpoint(requireOneRelation(draft, caption.entityId, "physical-asset"), caption.entityId), "asset");
+		const contentRelations = incidentRelations(draft, caption.entityId);
+		const allowed = new Set([
+			"physical-asset",
+			"caption-alignment",
+			"caption-provenance",
+			"marker-content"
+		]);
+		const unsupported = contentRelations.filter((relation) => !allowed.has(relation.relationKind));
+		if (unsupported.length > 0) throw new Error(`Cannot delete Caption with unsupported Relation ${unsupported[0].relationId}`);
+		this.removeClipGraph(draft, clipEntityId);
+		if (incidentRelations(draft, caption.entityId).some((relation) => relation.relationKind === "marker-content")) return;
+		const removed = new Set(incidentRelations(draft, caption.entityId).map((relation) => relation.relationId));
+		const assetIncidents = incidentRelations(draft, asset.entityId);
+		const deleteAsset = asset.payload.inline !== void 0 && assetIncidents.every((relation) => removed.has(relation.relationId));
+		draft.relations = draft.relations.filter((relation) => !removed.has(relation.relationId));
+		draft.entities = draft.entities.filter((entity) => entity.entityId !== caption.entityId && (!deleteAsset || entity.entityId !== asset.entityId));
+	}
+	replaceAnchorHost(draft, childClipEntityId, hostClipEntityId) {
+		const anchors = draft.relations.filter((relation) => relation.relationKind === "clip-anchor" && relation.endpoint0EntityId === childClipEntityId);
+		if (anchors.length !== 1) throw new Error(`Clip "${childClipEntityId}" must have exactly one host`);
+		this.relinkRelation(draft, anchors[0], {
+			endpoint0EntityId: createEntityId(childClipEntityId),
+			endpoint1EntityId: createEntityId(hostClipEntityId)
+		});
+	}
+	/** Rebuild the legacy edit baseline from current visual order before a high-level cascade. */
+	normalizeMainSequential(draft) {
+		const videoTrack = resolveEntityTimelineLayout(draft).tracks.find((track) => track.role === "video_clip");
+		if (videoTrack === void 0) return;
+		videoTrack.clips.forEach((clip, order) => {
+			this.applyClipPlacement(draft, clip.clipEntityId, {
+				kind: "sequential",
+				order
+			});
+		});
+	}
+	resolveOneVoiceoverOverlap(draft) {
+		const layout = resolveEntityTimelineLayout(draft);
+		const speechTrack = layout.tracks.find((track) => track.role === "speech");
+		if (speechTrack === void 0) return;
+		const ranges = speechTrack.clips.map((speech) => {
+			const captions = directAnchorChildren(draft, speech.clipEntityId).filter((clipId) => clipRole(draft, clipId) === "caption").map((clipId) => layout.clips.get(clipId)).filter((value) => value !== void 0);
+			return {
+				speech,
+				start: Math.min(speech.start, ...captions.map((caption) => caption.start)),
+				end: Math.max(speech.start + speech.duration, ...captions.map((caption) => caption.start + caption.duration))
+			};
+		}).sort((left, right) => left.start - right.start || left.speech.clipEntityId.localeCompare(right.speech.clipEntityId));
+		for (let index = 1; index < ranges.length; index += 1) {
+			const prior = ranges[index - 1];
+			const current = ranges[index];
+			if (current.start >= prior.end) continue;
+			const hostId = current.speech.anchorClipEntityId;
+			if (hostId === void 0) continue;
+			const videoTrack = layout.tracks.find((track) => track.role === "video_clip");
+			const hostIndex = videoTrack?.clips.findIndex((clip) => clip.clipEntityId === hostId) ?? -1;
+			if (videoTrack === void 0 || hostIndex < 0) continue;
+			const overlapMs = Math.round(prior.end - current.start);
+			for (const [visualIndex, clip] of videoTrack.clips.entries()) this.applyClipPlacement(draft, clip.clipEntityId, {
+				kind: "absolute",
+				targetRange: {
+					start: clip.start + (visualIndex >= hostIndex ? overlapMs : 0),
+					end: clip.start + clip.duration + (visualIndex >= hostIndex ? overlapMs : 0)
+				}
+			});
+			return;
+		}
+	}
+	applyClipPlacement(draft, clipEntityId, placement) {
+		const topology = requireClipTopology(draft, clipEntityId);
+		const clipPayload = { ...cloneJsonObject(topology.clip.payload, "Clip payload") };
+		const markerPayloadValue = { ...cloneJsonObject(topology.marker.payload, "Sequence Marker payload") };
+		delete clipPayload.order;
+		delete markerPayloadValue.targetRange;
+		delete markerPayloadValue.anchorOffset;
+		const outgoingAnchors = draft.relations.filter((relation) => relation.relationKind === "clip-anchor" && relation.endpoint0EntityId === topology.clip.entityId);
+		const removed = new Set(outgoingAnchors.map((relation) => relation.relationId));
+		draft.relations = draft.relations.filter((relation) => !removed.has(relation.relationId));
+		if (placement.kind === "sequential") clipPayload.order = finiteNumber(placement.order, "Clip order");
+		else if (placement.kind === "absolute") markerPayloadValue.targetRange = cloneJsonValue(placement.targetRange, "targetRange");
+		else {
+			const host = requireEntityKind(draft, placement.hostClipEntityId, "clip");
+			if (host.entityId === topology.clip.entityId) throw new Error("A Clip cannot anchor to itself");
+			markerPayloadValue.anchorOffset = finiteNonNegative(placement.anchorOffset, "anchorOffset");
+			draft.relations.push(this.createRelation(draft, "clip-anchor", topology.clip.entityId, host.entityId));
+		}
+		replaceEntity(draft, topology.clip.entityId, {
+			...topology.clip,
+			payload: clipPayload
+		});
+		replaceEntity(draft, topology.marker.entityId, {
+			...topology.marker,
+			payload: markerPayloadValue
+		});
+	}
+	reanchorAtAbsolute(draft, childClipEntityId, absoluteStart, layout) {
+		const hosts = layout.tracks.find((track) => track.role === "video_clip")?.clips.filter((clip) => clip.mode === "sequential") ?? [];
+		if (hosts.length === 0) {
+			const child = layout.clips.get(childClipEntityId);
+			if (child === void 0) throw new Error(`Clip "${childClipEntityId}" is not placed`);
+			this.applyClipPlacement(draft, childClipEntityId, {
+				kind: "absolute",
+				targetRange: {
+					start: absoluteStart,
+					end: absoluteStart + child.duration
+				}
+			});
+			return;
+		}
+		const host = hosts.find((candidate) => candidate.start <= absoluteStart && absoluteStart < candidate.start + candidate.duration) ?? (absoluteStart < hosts[0].start ? hosts[0] : hosts.at(-1));
+		this.applyClipPlacement(draft, childClipEntityId, {
+			kind: "anchored",
+			hostClipEntityId: host.clipEntityId,
+			anchorOffset: Math.max(0, Math.round(absoluteStart - host.start))
+		});
+	}
+	removeAnchoredDescendants(draft, hostClipEntityId, scheduled) {
+		const children = draft.relations.filter((relation) => relation.relationKind === "clip-anchor" && relation.endpoint1EntityId === hostClipEntityId).map((relation) => String(relation.endpoint0EntityId));
+		for (const child of children) {
+			if (scheduled.has(child)) continue;
+			const descendants = new Set(scheduled);
+			descendants.add(child);
+			this.removeAnchoredDescendants(draft, child, descendants);
+			if (clipRole(draft, child) === "caption") this.removeCaptionClipGraph(draft, child);
+			else this.removeClipGraph(draft, child);
+		}
+	}
+	removeClipGraph(draft, clipEntityId) {
+		const topology = requireClipTopology(draft, clipEntityId);
+		assertOnlyStructuralIncidents(draft, topology.clip.entityId, new Set([
+			"track-clip",
+			"clip-marker",
+			"clip-anchor"
+		]));
+		assertOnlyStructuralIncidents(draft, topology.marker.entityId, new Set(["clip-marker", "marker-content"]));
+		const markerIsExclusive = incidentRelations(draft, topology.marker.entityId).filter((relation) => relation.relationKind === "clip-marker").length === 1;
+		const removed = new Set(incidentRelations(draft, topology.clip.entityId).map((relation) => relation.relationId));
+		if (markerIsExclusive) for (const relation of incidentRelations(draft, topology.marker.entityId)) removed.add(relation.relationId);
+		draft.relations = draft.relations.filter((relation) => !removed.has(relation.relationId));
+		draft.entities = draft.entities.filter((entity) => entity.entityId !== topology.clip.entityId && (!markerIsExclusive || entity.entityId !== topology.marker.entityId));
+	}
+	transact(edit) {
+		const draft = cloneRows(this.state);
+		const result = edit(draft);
+		validateFinalRows(draft);
+		this.state = draft;
+		return result;
+	}
+	mintEntityId(draft) {
+		const entityId = createEntityId(this.idFactory("entity"));
+		if (draft.entities.some((entity) => entity.entityId === entityId)) throw new Error(`Entity id "${entityId}" already exists`);
+		return entityId;
+	}
+	createRelation(draft, relationKind, endpoint0EntityId, endpoint1EntityId, metadata = {}) {
+		return {
+			relationId: this.mintRelationId(draft),
+			relationKind,
+			endpoint0EntityId,
+			endpoint1EntityId,
+			metadata,
+			trace: {}
+		};
+	}
+	relinkRelation(draft, relation, endpoints) {
+		const relationId = this.mintRelationId(draft);
+		const index = draft.relations.findIndex((candidate) => candidate.relationId === relation.relationId);
+		if (index < 0) throw new Error(`Relation id "${relation.relationId}" does not exist`);
+		draft.relations[index] = {
+			...relation,
+			...endpoints,
+			relationId
+		};
+	}
+	mintRelationId(draft) {
+		const relationId = createRelationId(this.idFactory("relation"));
+		if (draft.relations.some((relation) => relation.relationId === relationId)) throw new Error(`Relation id "${relationId}" already exists`);
+		return relationId;
+	}
+};
+function validateFinalRows(rows) {
+	decodeEntityRelationRows(rows, numericMarkerValidation);
+	validateTimelineHierarchy(rows);
+}
+function validateTimelineHierarchy(rows) {
+	for (const entity of rows.entities) {
+		if (entity.entityKind === "track") requireTrackTimeline(rows, entity.entityId);
+		if (entity.entityKind !== "clip") continue;
+		const trackRelations = incidentRelations(rows, entity.entityId).filter((relation) => relation.relationKind === "track-clip");
+		if (trackRelations.length !== 1) throw new Error(`Clip Entity "${entity.entityId}" must belong to exactly one Track`);
+		requireEntityKind(rows, otherEndpoint(trackRelations[0], entity.entityId), "track");
+	}
+}
+function requireTrackTimeline(rows, trackEntityId) {
+	const timelineRelations = incidentRelations(rows, trackEntityId).filter((relation) => relation.relationKind === "timeline-track");
+	if (timelineRelations.filter((relation) => {
+		const otherId = otherEndpoint(relation, trackEntityId);
+		return rows.entities.some((entity) => entity.entityId === otherId && entity.entityKind === "timeline");
+	}).length !== 1 || timelineRelations.length !== 1) throw new Error(`Track Entity "${trackEntityId}" must belong to exactly one Timeline`);
+}
+function requireClipTopology(rows, clipEntityId) {
+	const clip = requireEntityKind(rows, clipEntityId, "clip");
+	const trackRelation = requireOneRelation(rows, clip.entityId, "track-clip");
+	requireEntityKind(rows, otherEndpoint(trackRelation, clip.entityId), "track");
+	const clipMarkerRelation = requireOneRelation(rows, clip.entityId, "clip-marker");
+	const marker = requireEntityKind(rows, otherEndpoint(clipMarkerRelation, clip.entityId), "sequence-marker");
+	const markerContentRelation = requireOneRelation(rows, marker.entityId, "marker-content");
+	requireSequenceContent(rows, otherEndpoint(markerContentRelation, marker.entityId));
+	return {
+		clip,
+		marker,
+		trackRelation,
+		clipMarkerRelation,
+		markerContentRelation
+	};
+}
+function requireOneRelation(rows, entityId, relationKind) {
+	const matches = incidentRelations(rows, entityId).filter((relation) => relation.relationKind === relationKind);
+	if (matches.length !== 1) throw new Error(`Entity "${entityId}" must have exactly one ${relationKind} Relation`);
+	return matches[0];
+}
+function requireEntityKind(rows, entityIdValue, entityKind) {
+	const entityId = createEntityId(entityIdValue);
+	const entity = rows.entities.find((candidate) => candidate.entityId === entityId);
+	if (entity == null) throw new Error(`Entity id "${entityId}" does not exist`);
+	if (entity.entityKind !== entityKind) throw new Error(`Entity "${entityId}" must have kind "${entityKind}", got "${entity.entityKind}"`);
+	return entity;
+}
+function requireSequenceContent(rows, entityIdValue) {
+	if (/^(?:[a-z][a-z\d+.-]*:|\/\/)/i.test(entityIdValue)) throw new Error("Timeline content must reference an existing Sequence media Entity id; a URL is not allowed");
+	const entityId = createEntityId(entityIdValue);
+	const row = rows.entities.find((candidate) => candidate.entityId === entityId);
+	if (row == null) throw new Error(`Timeline content must reference an existing Sequence media Entity; "${entityId}" was not found`);
+	if (!hasSequence({
+		...row.payload,
+		entityId: row.entityId,
+		entityKind: row.entityKind
+	})) throw new Error(`Timeline content must reference a Sequence media Entity, but "${entityId}" has kind "${row.entityKind}"`);
+	return row;
+}
+function assertOnlyStructuralIncidents(rows, entityId, allowedKinds) {
+	const unsupported = incidentRelations(rows, entityId).filter((relation) => !allowedKinds.has(relation.relationKind));
+	if (unsupported.length === 0) return;
+	throw new Error(`Cannot delete Clip graph: Entity "${entityId}" has unsupported incident Relation id(s): ${unsupported.map((relation) => relation.relationId).sort().join(", ")}`);
+}
+function incidentRelations(rows, entityId) {
+	return rows.relations.filter((relation) => relation.endpoint0EntityId === entityId || relation.endpoint1EntityId === entityId);
+}
+function hasOutgoingClipAnchor(rows, clipEntityId) {
+	return rows.relations.some((relation) => relation.relationKind === "clip-anchor" && relation.endpoint0EntityId === clipEntityId);
+}
+function outgoingAnchorChildren(rows, hostIds) {
+	return rows.relations.filter((relation) => relation.relationKind === "clip-anchor" && hostIds.has(relation.endpoint1EntityId)).map((relation) => String(relation.endpoint0EntityId));
+}
+function applyPlacementPayload(clipPayload, placement) {
+	if (placement.kind === "sequential") {
+		clipPayload.order = finiteNumber(placement.order, "Clip order");
+		return {};
+	}
+	if (placement.kind === "absolute") return { targetRange: cloneJsonValue(placement.targetRange, "targetRange") };
+	return { anchorOffset: finiteNonNegative(placement.anchorOffset, "anchorOffset") };
+}
+function requireAvailableEntityId(rows, value) {
+	const entityId = createEntityId(value);
+	if (rows.entities.some((entity) => entity.entityId === entityId)) throw new Error(`Entity id "${entityId}" already exists`);
+	return entityId;
+}
+function setClipOrder(rows, clipEntityId, order) {
+	const clip = requireEntityKind(rows, clipEntityId, "clip");
+	replaceEntity(rows, clip.entityId, {
+		...clip,
+		payload: {
+			...clip.payload,
+			order
+		}
+	});
+}
+function normalizeSequentialOrders(rows) {
+	for (const track of rows.entities.filter((entity) => entity.entityKind === "track")) rows.relations.filter((relation) => relation.relationKind === "track-clip" && relation.endpoint0EntityId === track.entityId).map((relation) => rows.entities.find((entity) => entity.entityId === relation.endpoint1EntityId)).filter((entity) => entity?.entityKind === "clip" && typeof entity.payload.order === "number").sort((left, right) => Number(left.payload.order) - Number(right.payload.order)).forEach((clip, order) => setClipOrder(rows, clip.entityId, order));
+}
+function findRoleTrack(rows, timelineEntityId, role) {
+	const timeline = requireEntityKind(rows, timelineEntityId, "timeline");
+	const tracks = incidentRelations(rows, timeline.entityId).filter((relation) => relation.relationKind === "timeline-track").map((relation) => requireEntityKind(rows, otherEndpoint(relation, timeline.entityId), "track")).filter((track) => track.payload.role === role);
+	if (tracks.length > 1) throw new Error(`Timeline "${timelineEntityId}" has multiple ${role} Tracks`);
+	return tracks[0];
+}
+function clipsOnTrack(rows, trackEntityId) {
+	return incidentRelations(rows, trackEntityId).filter((relation) => relation.relationKind === "track-clip").map((relation) => requireEntityKind(rows, otherEndpoint(relation, trackEntityId), "clip"));
+}
+function clipRole(rows, clipEntityId) {
+	const topology = requireClipTopology(rows, clipEntityId);
+	return requireEntityKind(rows, otherEndpoint(topology.trackRelation, topology.clip.entityId), "track").payload.role;
+}
+function directAnchorChildren(rows, hostClipEntityId) {
+	return rows.relations.filter((relation) => relation.relationKind === "clip-anchor" && relation.endpoint1EntityId === hostClipEntityId).map((relation) => String(relation.endpoint0EntityId));
+}
+function requireSupportedRole(rows, topology) {
+	const role = requireEntityKind(rows, otherEndpoint(topology.trackRelation, topology.clip.entityId), "track").payload.role;
+	if (role !== "video_clip" && role !== "speech" && role !== "caption" && role !== "bgm") throw new Error(`Clip "${topology.clip.entityId}" is not on a supported timeline Track`);
+	return role;
+}
+function requireClipOnRole(rows, clipEntityId, role) {
+	const topology = requireClipTopology(rows, clipEntityId);
+	if (requireEntityKind(rows, otherEndpoint(topology.trackRelation, topology.clip.entityId), "track").payload.role !== role) throw new Error(`Clip "${clipEntityId}" must belong to the ${role} Track`);
+	return topology;
+}
+function finiteNumber(value, label) {
+	if (!Number.isFinite(value)) throw new Error(`${label} must be finite`);
+	return value;
+}
+function finitePositive(value, label) {
+	const result = finiteNumber(value, label);
+	if (result <= 0) throw new Error(`${label} must be positive`);
+	return result;
+}
+function requireVolume(value) {
+	const volume = finiteNumber(value, "Clip volume");
+	if (volume < -60 || volume > 20) throw new Error("Clip volume must be between -60 and 20 dB");
+	return volume;
+}
+function requirePositiveRange(value, label) {
+	if (!isJsonObject(value)) throw new Error(`${label} must be an object`);
+	const start = finiteNonNegative(value.start, `${label}.start`);
+	const end = finitePositive(value.end, `${label}.end`);
+	if (!Number.isSafeInteger(start) || !Number.isSafeInteger(end) || end <= start) throw new Error(`${label} must be a positive whole-millisecond range`);
+	return {
+		start,
+		end
+	};
+}
+function markerDuration(payload, sourceRange) {
+	const duration = payload.duration;
+	if (!isJsonObject(duration)) throw new Error("Sequence Marker duration must be an object");
+	if (duration.mode === "from-source") return sourceRange.end - sourceRange.start;
+	if (duration.mode !== "fixed") throw new Error("Sequence Marker duration mode is unsupported");
+	return finitePositive(duration.value, "Sequence Marker fixed duration");
+}
+function linearRate(value) {
+	if (value === void 0) return 1;
+	if (!isJsonObject(value) || value.kind !== "linear") throw new Error("Only linear Clip time remapping is supported");
+	return finitePositive(value.rate, "linear speed rate");
+}
+function resizeAbsoluteTarget(payload, duration) {
+	if (payload.targetRange === void 0) return;
+	const target = requirePositiveRange(payload.targetRange, "targetRange");
+	payload.targetRange = {
+		start: target.start,
+		end: target.start + duration
+	};
+}
+function replaceRows(rows, replacement) {
+	rows.entities = structuredClone([...replacement.entities]);
+	rows.relations = structuredClone([...replacement.relations]);
+}
+function finiteNonNegative(value, label) {
+	const result = finiteNumber(value, label);
+	if (result < 0) throw new Error(`${label} must be non-negative`);
+	return result;
+}
+function nextSequentialOrder(rows, trackEntityId) {
+	const orders = rows.relations.filter((relation) => relation.relationKind === "track-clip" && relation.endpoint0EntityId === trackEntityId).map((relation) => rows.entities.find((entity) => entity.entityId === relation.endpoint1EntityId)?.payload.order).filter((order) => typeof order === "number" && Number.isFinite(order));
+	return orders.length === 0 ? 0 : Math.max(...orders) + 1;
+}
+function otherEndpoint(relation, entityId) {
+	if (relation.endpoint0EntityId === entityId) return relation.endpoint1EntityId;
+	if (relation.endpoint1EntityId === entityId) return relation.endpoint0EntityId;
+	throw new Error(`Relation "${relation.relationId}" is not incident to Entity "${entityId}"`);
+}
+function replaceEntity(rows, entityId, replacement) {
+	const index = rows.entities.findIndex((entity) => entity.entityId === entityId);
+	if (index < 0) throw new Error(`Entity id "${entityId}" does not exist`);
+	rows.entities[index] = replacement;
+}
+function markerPayload(value) {
+	return cloneJsonObject(value, "Sequence Marker payload");
+}
+function cloneJsonObject(value, label) {
+	const cloned = structuredClone(value);
+	if (!isJsonObject(cloned)) throw new Error(`${label} must contain only JSON values`);
+	return cloned;
+}
+function cloneJsonValue(value, label) {
+	return cloneJsonObject({ value }, label).value;
+}
+function cloneRows(rows) {
+	return {
+		entities: rows.entities.map((entity) => structuredClone(entity)),
+		relations: rows.relations.map((relation) => structuredClone(relation))
+	};
+}
+const numericMarkerValidation = { compareMarkerPoints: (_marker, _range, left, right) => {
+	if (typeof left !== "number" || !Number.isFinite(left) || typeof right !== "number" || !Number.isFinite(right)) throw new Error("Sequence Marker points must use finite numeric coordinates");
+	return left - right;
+} };
+//#endregion
+//#region src/entity-editor/legacy-entity-migration.ts
+/** One-time import only. Ordinary editor operations must never reverse-diff a legacy document. */
+function migrateLegacyTimelineToEntities(legacy, assetFacts, initial = {
+	entities: [],
+	relations: []
+}, idFactory = (prefix) => `${prefix}_${globalThis.crypto.randomUUID()}`) {
+	assertSupportedLegacy(legacy);
+	if (initial.entities.some((row) => row.entityKind === "timeline")) fail("Timeline already exists; migration is not an editing operation");
+	if (legacy.meta.schema_version === "video-document/entity-projection-v1") fail("An entity projection cannot be migrated as legacy state");
+	const normalizedMainRanges = overlapNormalizedMainRanges(legacy);
+	let entities = structuredClone([...initial.entities]);
+	let relations = structuredClone([...initial.relations]);
+	const addEntity = (kind, payload, existingId) => {
+		const entityId = createEntityId(existingId ?? idFactory("entity"));
+		if (entities.some((row) => row.entityId === entityId)) fail(`Migration entity identity collision: ${entityId}`);
+		entities.push({
+			entityId,
+			entityKind: kind,
+			payload
+		});
+		return entityId;
+	};
+	const link = (kind, from, to, metadata = {}) => {
+		const relationId = createRelationId(idFactory("relation"));
+		if (relations.some((row) => row.relationId === relationId)) fail(`Migration relation identity collision: ${relationId}`);
+		relations.push({
+			relationId,
+			relationKind: kind,
+			endpoint0EntityId: createEntityId(from),
+			endpoint1EntityId: createEntityId(to),
+			metadata,
+			trace: {}
+		});
+	};
+	const facts = /* @__PURE__ */ new Map();
+	for (const fact of assetFacts) {
+		if (facts.has(fact.assetId)) fail(`Duplicate asset facts for ${fact.assetId}`);
+		facts.set(fact.assetId, fact);
+	}
+	const contentByPartId = /* @__PURE__ */ new Map();
+	const scriptBySpeechClipId = /* @__PURE__ */ new Map();
+	for (const track of legacy.tracks ?? []) for (const item of track.items ?? []) {
+		const part = requirePart(legacy, item.part_id);
+		if (part.video_clip !== void 0) {
+			const assetId = part.video_clip.origin_media_id;
+			const fact = facts.get(assetId);
+			if (fact === void 0) fail(`Missing factual media metadata for ${assetId}`);
+			if (fact.kind !== "image" && fact.kind !== "video") fail(`Legacy video Clip ${item.part_id} requires an image or video fact`);
+			const imported = importMediaAsset({
+				entities,
+				relations
+			}, fact, idFactory);
+			entities = [...imported.rows.entities];
+			relations = [...imported.rows.relations];
+			contentByPartId.set(item.part_id, imported.contentEntityId);
+		} else if (part.speech !== void 0) {
+			const speech = part.speech;
+			const imported = importMediaAsset({
+				entities,
+				relations
+			}, {
+				assetId: speech.origin_speech_id,
+				kind: "voice",
+				durationMs: speech.media_duration_ms,
+				storageKey: speech.audio_storage_key,
+				voice: {
+					system: "voice-library",
+					key: speech.voice.id,
+					...speech.voice.name === void 0 ? {} : { name: speech.voice.name }
+				}
+			}, idFactory);
+			entities = [...imported.rows.entities];
+			relations = [...imported.rows.relations];
+			contentByPartId.set(item.part_id, imported.contentEntityId);
+			scriptBySpeechClipId.set(item.part_id, ensureAudioScript(imported.contentEntityId, speech.audio_script, entities, relations, addEntity, link));
+		} else if (part.bgm !== void 0) {
+			const bgm = part.bgm;
+			const fact = facts.get(bgm.origin_media_id);
+			if (fact === void 0) fail(`Missing factual media metadata for ${bgm.origin_media_id}`);
+			if (fact.kind !== "audio") fail(`Legacy BGM ${item.part_id} requires an audio fact`);
+			if (fact.storageKey !== bgm.audio_storage_key) fail(`Factual storage key conflicts with legacy BGM ${item.part_id}`);
+			const imported = importMediaAsset({
+				entities,
+				relations
+			}, fact, idFactory);
+			entities = [...imported.rows.entities];
+			relations = [...imported.rows.relations];
+			contentByPartId.set(item.part_id, imported.contentEntityId);
+		}
+	}
+	const timeline = addEntity("timeline", legacy.timeline?.unit_time_ms === void 0 ? {} : { unit_time_ms: legacy.timeline.unit_time_ms });
+	const trackIds = /* @__PURE__ */ new Map();
+	for (const [order, oldTrack] of (legacy.tracks ?? []).entries()) {
+		const track = addEntity("track", {
+			role: oldTrack.parts_kind,
+			order,
+			...oldTrack.is_hidden === void 0 ? {} : { hidden: oldTrack.is_hidden }
+		}, oldTrack.id);
+		trackIds.set(oldTrack, track);
+		link("timeline-track", timeline, track);
+	}
+	for (const oldTrack of legacy.tracks ?? []) {
+		const track = trackIds.get(oldTrack);
+		for (const [order, item] of (oldTrack.items ?? []).entries()) {
+			const part = requirePart(legacy, item.part_id);
+			const role = oldTrack.parts_kind;
+			const volume = part.video_clip?.volume ?? part.speech?.volume ?? part.bgm?.volume;
+			const clip = addEntity("clip", {
+				...volume === void 0 ? {} : { volume },
+				...item.time_position.mode === "sequential" && !(role === "video_clip" && normalizedMainRanges !== void 0) || role === "bgm" ? { order: role === "bgm" ? 0 : order } : {}
+			}, item.part_id);
+			let content = contentByPartId.get(item.part_id);
+			let duration;
+			let markerPayload;
+			if (part.video_clip !== void 0) {
+				const video = part.video_clip;
+				duration = effectiveVideoClipDurationMs(video);
+				const fact = facts.get(video.origin_media_id);
+				const rate = speedOf(video.speed_shift);
+				markerPayload = {
+					sourceRange: {
+						start: video.play_in,
+						end: video.play_out
+					},
+					duration: {
+						mode: "fixed",
+						value: duration
+					},
+					...(fact.kind === "image" || fact.kind === "video") && video.speed_shift !== void 0 ? { timeRemapping: {
+						kind: "linear",
+						mode: video.speed_shift?.mode ?? "constant",
+						rate
+					} } : {}
+				};
+			} else if (part.speech !== void 0) {
+				duration = part.speech.media_duration_ms;
+				markerPayload = {
+					sourceRange: {
+						start: 0,
+						end: duration
+					},
+					duration: {
+						mode: "fixed",
+						value: duration
+					}
+				};
+			} else if (part.caption !== void 0) {
+				const caption = part.caption;
+				duration = caption.initial_duration_ms;
+				content = addEntity("caption", {
+					extent: {
+						kind: "bounded",
+						start: 0,
+						end: duration
+					},
+					sampling: "native",
+					coordinateSpace: "milliseconds",
+					text: caption.text,
+					...caption.style === void 0 ? {} : { style: toEntityCaptionStyle(caption.style) }
+				});
+				const asset = addEntity("asset", { inline: {
+					mediaType: "text/plain",
+					text: caption.text
+				} });
+				link("physical-asset", content, asset);
+				const voice = contentByPartId.get(caption.speech_part_id);
+				const script = scriptBySpeechClipId.get(caption.speech_part_id);
+				link("caption-alignment", content, voice, { alignment: {
+					start: caption.start_ms,
+					end: caption.start_ms + duration
+				} });
+				link("caption-provenance", content, script, { segmentAlignment: [] });
+				markerPayload = {
+					sourceRange: {
+						start: 0,
+						end: duration
+					},
+					duration: {
+						mode: "fixed",
+						value: duration
+					}
+				};
+			} else {
+				const bgm = part.bgm;
+				const fact = facts.get(bgm.origin_media_id);
+				if (fact.kind !== "audio") fail(`Legacy BGM ${item.part_id} requires an audio fact`);
+				duration = fact.durationMs;
+				markerPayload = {
+					sourceRange: {
+						start: 0,
+						end: duration
+					},
+					duration: { mode: "from-source" },
+					durationPolicy: "timeline"
+				};
+			}
+			if (content === void 0) fail(`Migration could not resolve content for ${item.part_id}`);
+			const normalizedMainRange = role === "video_clip" ? normalizedMainRanges?.get(item.part_id) : void 0;
+			if (normalizedMainRange !== void 0) markerPayload = {
+				...markerPayload,
+				targetRange: normalizedMainRange
+			};
+			else if (item.time_position.mode === "absolute" && role !== "bgm") markerPayload = {
+				...markerPayload,
+				targetRange: {
+					start: item.time_position.offsetMs,
+					end: item.time_position.offsetMs + duration
+				}
+			};
+			else if (item.time_position.mode === "anchored") markerPayload = {
+				...markerPayload,
+				anchorOffset: item.time_position.offsetMs
+			};
+			const marker = addEntity("sequence-marker", markerPayload);
+			link("track-clip", track, clip);
+			link("clip-marker", clip, marker);
+			link("marker-content", marker, content);
+			if (item.time_position.mode === "anchored") link("clip-anchor", clip, item.time_position.anchorPartId);
+		}
+	}
+	const rows = {
+		entities,
+		relations
+	};
+	assertEntityProjectionPreservesLegacy(legacy, projectEntityTimeline(rows, legacy.meta), rows);
+	return rows;
+}
+/** Server gate: a cutover may change representation, never the existing render facts. */
+function assertEntityProjectionPreservesLegacy(legacy, projection, rows) {
+	assertSupportedLegacy(legacy);
+	if (projection.meta.schema_version !== "video-document/entity-projection-v1") fail("Expected an entity projection for migration");
+	const normalizedMainRanges = overlapNormalizedMainRanges(legacy);
+	const compatibilityFacts = (document) => {
+		const { version: _version, ...view } = fromVideoDocument(document);
+		for (const part of Object.values(view.part_library ?? {})) {
+			const speech = part.speech;
+			if (speech?.phoneme_script === null) delete speech.phoneme_script;
+		}
+		const { schema_version: _schemaVersion, version: _metaVersion, ...meta } = document.meta;
+		return {
+			meta,
+			view
+		};
+	};
+	if (canonical(compatibilityFacts(legacy)) !== canonical(compatibilityFacts(projection))) fail("Entity migration must preserve all existing timeline facts; edit after cutover");
+	const trackOrders = [];
+	for (const oldTrack of legacy.tracks ?? []) {
+		const candidates = rows.entities.filter((row) => row.entityKind === "track" && (oldTrack.id === void 0 ? row.payload.role === oldTrack.parts_kind : row.entityId === oldTrack.id));
+		if (candidates.length !== 1) fail("Migration must preserve every Track identity");
+		const track = candidates[0];
+		if (track.payload.role !== oldTrack.parts_kind || (track.payload.hidden ?? false) !== (oldTrack.is_hidden ?? false)) fail("Migration must preserve Track role and visibility");
+		if (typeof track.payload.order !== "number" || !Number.isFinite(track.payload.order)) fail("Migration must preserve Track order");
+		trackOrders.push(track.payload.order);
+		const sequentialOrders = [];
+		for (const item of oldTrack.items ?? []) {
+			const clip = rows.entities.find((row) => row.entityId === item.part_id && row.entityKind === "clip");
+			const binding = rows.relations.filter((row) => row.relationKind === "clip-marker" && row.endpoint0EntityId === item.part_id && rows.entities.some((entity) => entity.entityId === row.endpoint1EntityId && entity.entityKind === "sequence-marker"));
+			const marker = rows.entities.find((row) => row.entityId === binding[0]?.endpoint1EntityId && row.entityKind === "sequence-marker");
+			if (clip === void 0 || binding.length !== 1 || marker === void 0) fail("Migration must preserve Clip/Marker placement identity");
+			const anchors = rows.relations.filter((row) => row.relationKind === "clip-anchor" && row.endpoint0EntityId === clip.entityId);
+			const normalizedMainRange = oldTrack.parts_kind === "video_clip" ? normalizedMainRanges?.get(item.part_id) : void 0;
+			if (normalizedMainRange !== void 0) {
+				if (clip.payload.order !== void 0 || !isExactRange(marker.payload.targetRange, normalizedMainRange) || marker.payload.anchorOffset !== void 0 || anchors.length !== 0) fail("Migration must preserve the legacy overlap-normalized main Track");
+			} else if (oldTrack.parts_kind === "bgm") {
+				if (clip.payload.order !== 0 || marker.payload.targetRange !== void 0 || marker.payload.anchorOffset !== void 0 || marker.payload.durationPolicy !== "timeline" || anchors.length !== 0) fail("Migration must preserve timeline-filling BGM semantics");
+			} else if (item.time_position.mode === "sequential") {
+				if (marker.payload.targetRange !== void 0 || marker.payload.anchorOffset !== void 0 || typeof clip.payload.order !== "number" || !Number.isFinite(clip.payload.order) || anchors.length !== 0) fail("Migration must preserve sequential placement semantics");
+				sequentialOrders.push(clip.payload.order);
+			} else if (item.time_position.mode === "absolute") {
+				const target = marker.payload.targetRange;
+				if (clip.payload.order !== void 0 || !isRangeStartingAt(target, item.time_position.offsetMs) || marker.payload.anchorOffset !== void 0 || anchors.length !== 0) fail("Migration must preserve absolute placement semantics");
+			} else if (clip.payload.order !== void 0 || marker.payload.targetRange !== void 0 || marker.payload.anchorOffset !== item.time_position.offsetMs || anchors.length !== 1 || anchors[0].endpoint1EntityId !== item.time_position.anchorPartId) fail("Migration must preserve anchored placement semantics");
+		}
+		if (sequentialOrders.some((order, index) => index > 0 && order <= sequentialOrders[index - 1])) fail("Migration must preserve sequential Clip order");
+	}
+	if (trackOrders.some((order, index) => index > 0 && order <= trackOrders[index - 1])) fail("Migration must preserve Track stacking order");
+}
+function assertSupportedLegacy(document) {
+	assertValidVideoDocument(document);
+	const tracks = document.tracks ?? [];
+	assertKnownFields(document.timeline ?? {}, ["unit_time_ms"], "Timeline");
+	if (document.timeline?.unit_time_ms !== void 0 && (typeof document.timeline.unit_time_ms !== "number" || !Number.isFinite(document.timeline.unit_time_ms) || document.timeline.unit_time_ms <= 0)) fail("Migration requires a positive finite unit_time_ms");
+	const seenRoles = /* @__PURE__ */ new Set();
+	const placed = /* @__PURE__ */ new Map();
+	for (const track of tracks) {
+		const role = track.parts_kind;
+		if (role === void 0 || ![
+			"video_clip",
+			"speech",
+			"caption",
+			"bgm"
+		].includes(role)) fail("Every legacy Track requires a supported role");
+		if (seenRoles.has(role)) fail(`The compatibility editor supports only one ${role} Track`);
+		seenRoles.add(role);
+		if (track.id !== void 0 && (track.id.trim() === "" || track.id.trim() !== track.id)) fail("Migration requires trimmed Track identities");
+		for (const item of track.items ?? []) {
+			if (item.part_id.trim() === "" || item.part_id.trim() !== item.part_id) fail("Migration requires trimmed Clip identities");
+			if (placed.has(item.part_id)) fail(`Legacy part ${item.part_id} is placed more than once`);
+			placed.set(item.part_id, {
+				track,
+				item
+			});
+			assertKnownFields(item.time_position, item.time_position.mode === "sequential" ? ["mode"] : [
+				"mode",
+				"anchorPartId",
+				"offsetMs"
+			], "placement");
+			if (item.time_position.mode === "absolute") requireMilliseconds(item.time_position.offsetMs, "absolute offset");
+			if (item.time_position.mode === "anchored") {
+				if (item.time_position.anchorPartId.trim() === "" || item.time_position.anchorPartId.trim() !== item.time_position.anchorPartId) fail("Migration requires a trimmed anchor identity");
+				requireMilliseconds(item.time_position.offsetMs, "anchor offset");
+			}
+			if (item.fallback_abs_ms !== void 0) requireMilliseconds(item.fallback_abs_ms, "anchor fallback");
+			assertKnownFields(item, [
+				"part_id",
+				"time_position",
+				"fallback_abs_ms"
+			], "TrackItem");
+		}
+		assertKnownFields(track, [
+			"id",
+			"parts_kind",
+			"is_hidden",
+			"items"
+		], "Track");
+	}
+	for (const [id, part] of Object.entries(document.part_library ?? {})) {
+		const placement = placed.get(id);
+		if (placement === void 0) fail(`Cannot discard unplaced legacy part ${id}`);
+		assertPartSupported(id, part, placement.track.parts_kind);
+	}
+	for (const id of placed.keys()) if (document.part_library?.[id] === void 0) fail(`Placed Clip ${id} has no part payload`);
+	assertLegacyRelations(document, placed);
+}
+function assertPartSupported(id, part, role) {
+	assertKnownFields(part, [
+		"video_clip",
+		"speech",
+		"caption",
+		"bgm"
+	], "Part");
+	const present = [
+		"video_clip",
+		"speech",
+		"caption",
+		"bgm"
+	].filter((kind) => part[kind] !== void 0);
+	if (present.length !== 1 || present[0] !== role) fail(`Legacy part ${id} must match its ${role} Track`);
+	if (part.video_clip !== void 0) {
+		const clip = part.video_clip;
+		if (clip.id !== id || clip.kind !== "video_clip" || !trimmed(clip.origin_media_id) || clip.play_in === void 0 || clip.play_out === void 0) fail("Migration requires complete Clip identity, media and trim facts");
+		requireMilliseconds(clip.play_in, "Clip play_in");
+		requireMilliseconds(clip.play_out, "Clip play_out");
+		if (clip.play_out <= clip.play_in) fail("Migration requires a non-empty Clip trim window");
+		requireFinite(clip.volume, "Clip volume");
+		const speed = clip.speed_shift;
+		if (speed !== void 0 && (speed.category !== "linear" || speed.config?.linear === void 0 || speed.mode !== void 0 && typeof speed.mode !== "string")) fail("Nonlinear speed requires an entity remapping adapter");
+		if (speed !== void 0) {
+			const rate = speed.config?.linear?.speed;
+			if (typeof rate !== "number" || !Number.isFinite(rate) || rate <= 0) fail("Migration requires a positive finite speed");
+			assertKnownFields(speed, [
+				"category",
+				"mode",
+				"config"
+			], "speed_shift");
+			assertKnownFields(speed.config, ["linear"], "speed config");
+			assertKnownFields(speed.config.linear, ["speed"], "linear speed");
+		}
+		assertKnownFields(clip, [
+			"id",
+			"kind",
+			"origin_media_id",
+			"play_in",
+			"play_out",
+			"volume",
+			"speed_shift"
+		], "Clip");
+	} else if (part.speech !== void 0) {
+		const speech = part.speech;
+		const phonemeScript = speech.phoneme_script;
+		if (speech.id !== id || speech.kind !== "speech" || !trimmed(speech.origin_speech_id) || !trimmed(speech.audio_storage_key) || typeof speech.audio_script !== "string") fail("Migration requires complete Speech identity and physical take facts");
+		requirePositiveMilliseconds(speech.media_duration_ms, "Speech duration");
+		requireFinite(speech.volume, "Speech volume");
+		if (!trimmed(speech.voice?.id)) fail("Migration requires an explicit voice-library identity");
+		if (speech.voice?.name !== void 0 && typeof speech.voice.name !== "string") fail("Migration requires a string voice name when present");
+		if (!Array.isArray(speech.caption_ids) || speech.caption_ids.some((captionId) => !trimmed(captionId))) fail("Migration requires explicit Speech caption identities");
+		if (new Set(speech.caption_ids).size !== speech.caption_ids.length) fail("Migration requires unique Speech caption identities");
+		if (phonemeScript !== void 0 && phonemeScript !== null) fail("Non-null phoneme_script requires a phonetic-script migration adapter");
+		assertKnownFields(speech.voice, ["id", "name"], "voice");
+		assertKnownFields(speech, [
+			"id",
+			"kind",
+			"media_duration_ms",
+			"audio_script",
+			"volume",
+			"audio_storage_key",
+			"origin_speech_id",
+			"voice",
+			"caption_ids",
+			"phoneme_script"
+		], "Speech");
+	} else if (part.caption !== void 0) {
+		const caption = part.caption;
+		if (caption.id !== id || caption.kind !== "caption" || !trimmed(caption.speech_part_id) || typeof caption.text !== "string") fail("Migration requires complete Caption identity, Speech provenance and text");
+		requireMilliseconds(caption.start_ms, "Caption source offset");
+		requirePositiveMilliseconds(caption.initial_duration_ms, "Caption duration");
+		if (caption.style !== void 0) assertCaptionStyle(caption.style);
+		assertKnownFields(caption, [
+			"id",
+			"kind",
+			"initial_duration_ms",
+			"speech_part_id",
+			"text",
+			"start_ms",
+			"style"
+		], "Caption");
+	} else if (part.bgm !== void 0) {
+		const bgm = part.bgm;
+		if (bgm.id !== id || bgm.kind !== "bgm" || !trimmed(bgm.origin_media_id) || !trimmed(bgm.audio_storage_key)) fail("Migration requires complete BGM identity and physical media facts");
+		requireFinite(bgm.volume, "BGM volume");
+		assertKnownFields(bgm, [
+			"id",
+			"kind",
+			"audio_storage_key",
+			"volume",
+			"origin_media_id"
+		], "BGM");
+	}
+}
+function assertLegacyRelations(document, placed) {
+	const captionIdsBySpeech = /* @__PURE__ */ new Map();
+	for (const track of document.tracks ?? []) {
+		if (track.parts_kind === "bgm" && (track.items?.length ?? 0) > 1) fail("The compatibility editor supports only one BGM Clip");
+		for (const item of track.items ?? []) {
+			const part = requirePart(document, item.part_id);
+			const position = item.time_position;
+			if (track.parts_kind === "video_clip" && position.mode === "anchored") fail("Anchored video Clips require an overlay adapter");
+			if (track.parts_kind === "bgm") {
+				if (position.mode !== "absolute" || position.offsetMs !== 0) fail("Legacy BGM must start at the Timeline origin");
+			} else if (position.mode === "anchored") {
+				const host = placed.get(position.anchorPartId);
+				if (host === void 0) fail(`Legacy anchor ${position.anchorPartId} is not placed`);
+				if (track.parts_kind === "speech" && host.track.parts_kind !== "video_clip") fail("Speech may only anchor to a video Clip");
+				if (track.parts_kind === "caption") {
+					if (host.track.parts_kind !== "speech") fail("Caption may only anchor to a Speech Clip");
+					const caption = part.caption;
+					if (position.anchorPartId !== caption.speech_part_id || position.offsetMs !== caption.start_ms) fail("Caption placement must agree with its Speech provenance and source offset");
+				}
+			} else if (track.parts_kind === "caption") fail("Caption placement requires an explicit Speech anchor");
+			if (part.caption !== void 0) {
+				const ids = captionIdsBySpeech.get(part.caption.speech_part_id) ?? [];
+				ids.push(item.part_id);
+				captionIdsBySpeech.set(part.caption.speech_part_id, ids);
+			}
+		}
+	}
+	for (const [id, placement] of placed) {
+		const speech = requirePart(document, id).speech;
+		if (speech === void 0) continue;
+		const expected = captionIdsBySpeech.get(id) ?? [];
+		if (canonical(speech.caption_ids) !== canonical(expected)) fail(`Speech ${id} caption_ids must agree with the Caption Track order`);
+		if (placement.item.time_position.mode === "anchored") continue;
+		if (placement.item.time_position.mode !== "absolute") fail("Speech placement must be anchored or absolute");
+	}
+	const intervals = (fromVideoDocument(document).main_track?.items ?? []).map((item) => {
+		const clip = document.part_library?.[item.part_id]?.video_clip;
+		if (clip === void 0) fail("Projection must preserve every video Clip");
+		return {
+			start: item.abs_time_position ?? 0,
+			end: (item.abs_time_position ?? 0) + effectiveVideoClipDurationMs(clip)
+		};
+	}).sort((left, right) => left.start - right.start);
+	if (intervals.some((interval, index) => index > 0 && interval.start < intervals[index - 1].end)) fail("Overlapping video Clips require an overlay adapter");
+}
+/**
+* Legacy reads perform one speech-overlap pass after laying the visual lane out
+* sequentially. Entity reads deliberately do not run that hidden cascade. When
+* the pass moved any visual Clip, cutover therefore records the complete solved
+* visual lane as explicit target ranges. Mixing absolute and sequential Clips
+* would create two unrelated placement chains and could reorder the lane.
+*/
+function overlapNormalizedMainRanges(document) {
+	const track = document.tracks?.find((candidate) => candidate.parts_kind === "video_clip");
+	if (track === void 0 || (track.items?.length ?? 0) === 0) return void 0;
+	const solved = fromVideoDocument(document).main_track?.items ?? [];
+	const starts = new Map(solved.map((item) => [item.part_id, requireMilliseconds(item.abs_time_position, `Solved position for ${item.part_id ?? "unknown Clip"}`)]));
+	let cursor = 0;
+	let moved = false;
+	const ranges = /* @__PURE__ */ new Map();
+	for (const item of track.items ?? []) {
+		const part = requirePart(document, item.part_id).video_clip;
+		if (part === void 0) fail(`Projection must preserve video Clip ${item.part_id}`);
+		const duration = effectiveVideoClipDurationMs(part);
+		const start = starts.get(item.part_id);
+		if (start === void 0) fail(`Projection must preserve video Clip ${item.part_id}`);
+		if (start !== cursor) moved = true;
+		const end = start + duration;
+		requireMilliseconds(end, `Solved end for ${item.part_id}`);
+		ranges.set(item.part_id, {
+			start,
+			end
+		});
+		cursor += duration;
+	}
+	return moved ? ranges : void 0;
+}
+function requirePart(document, partId) {
+	const part = document.part_library?.[partId];
+	if (part === void 0) fail(`Placed Clip ${partId} has no part payload`);
+	return part;
+}
+function ensureAudioScript(voiceEntityId, text, entities, relations, addEntity, link) {
+	const renders = relations.filter((relation) => relation.relationKind === "audio-script-render" && relation.endpoint0EntityId === voiceEntityId);
+	if (renders.length > 1) fail(`Voice ${voiceEntityId} has ambiguous AudioScript provenance`);
+	if (renders.length === 1) {
+		const script = entities.find((entity) => entity.entityId === renders[0].endpoint1EntityId && entity.entityKind === "audio-script");
+		if (script === void 0 || scriptText(script) !== text) fail(`Voice ${voiceEntityId} conflicts with the legacy Speech script`);
+		return script.entityId;
+	}
+	const script = addEntity("audio-script", { segments: [{
+		segmentId: "segment-0",
+		text
+	}] });
+	link("audio-script-render", voiceEntityId, script);
+	return script;
+}
+function scriptText(script) {
+	const segments = script.payload.segments;
+	if (!Array.isArray(segments)) fail("AudioScript requires segments");
+	return segments.map((segment) => {
+		if (segment === null || typeof segment !== "object" || Array.isArray(segment) || typeof segment.text !== "string") fail("AudioScript segment requires text");
+		return segment.text;
+	}).join("");
+}
+function toEntityCaptionStyle(style) {
+	return {
+		...style.font_id === void 0 ? {} : { font: {
+			system: "font-library",
+			key: style.font_id
+		} },
+		...style.font_size === void 0 ? {} : { fontSize: style.font_size },
+		...style.font_color === void 0 ? {} : { fontColor: style.font_color },
+		...style.font_weight === void 0 ? {} : { fontWeight: style.font_weight },
+		...style.entrance_animation === void 0 ? {} : { entranceAnimation: style.entrance_animation },
+		...style.entrance_animation_duration_ms === void 0 ? {} : { entranceAnimationDurationMs: style.entrance_animation_duration_ms },
+		...style.stroke_color === void 0 ? {} : { strokeColor: style.stroke_color },
+		...style.stroke_width === void 0 ? {} : { strokeWidth: style.stroke_width },
+		...style.position_x === void 0 ? {} : { positionX: style.position_x },
+		...style.position_y === void 0 ? {} : { positionY: style.position_y }
+	};
+}
+function assertCaptionStyle(style) {
+	if (style.font_id !== void 0 && !trimmed(style.font_id)) fail("Caption font_id must be a trimmed identity");
+	for (const value of [
+		style.font_size,
+		style.font_weight,
+		style.entrance_animation_duration_ms,
+		style.stroke_width,
+		style.position_x,
+		style.position_y
+	]) if (value !== void 0) requireFinite(value, "Caption style number");
+	for (const value of [
+		style.font_color,
+		style.entrance_animation,
+		style.stroke_color
+	]) if (value !== void 0 && typeof value !== "string") fail("Caption style text must be a string");
+	assertKnownFields(style, [
+		"font_id",
+		"font_size",
+		"font_color",
+		"font_weight",
+		"entrance_animation",
+		"entrance_animation_duration_ms",
+		"stroke_color",
+		"stroke_width",
+		"position_x",
+		"position_y"
+	], "Caption style");
+}
+function isRangeStartingAt(value, expectedStart) {
+	return value !== null && typeof value === "object" && !Array.isArray(value) && value.start === expectedStart;
+}
+function isExactRange(value, expected) {
+	return value !== null && typeof value === "object" && !Array.isArray(value) && value.start === expected.start && value.end === expected.end;
+}
+function requireFinite(value, label) {
+	if (typeof value !== "number" || !Number.isFinite(value)) fail(`${label} must be finite`);
+	return value;
+}
+function requireMilliseconds(value, label) {
+	const result = requireFinite(value, label);
+	if (!Number.isSafeInteger(result) || result < 0) fail(`${label} must be non-negative whole milliseconds`);
+	return result;
+}
+function requirePositiveMilliseconds(value, label) {
+	const result = requireMilliseconds(value, label);
+	if (result <= 0) fail(`${label} must be positive`);
+	return result;
+}
+function trimmed(value) {
+	return typeof value === "string" && value.trim() !== "" && value.trim() === value;
+}
+function assertKnownFields(value, fields, label) {
+	if (Object.entries(value).some(([key, field]) => field !== void 0 && !fields.includes(key))) fail(`Unknown legacy ${label} fields require an explicit migration adapter`);
+}
+function canonical(value) {
+	if (Array.isArray(value)) return `[${value.map(canonical).join(",")}]`;
+	if (value !== null && typeof value === "object") return `{${Object.entries(value).filter(([, field]) => field !== void 0).sort(([left], [right]) => left.localeCompare(right)).map(([key, field]) => `${JSON.stringify(key)}:${canonical(field)}`).join(",")}}`;
+	return JSON.stringify(value) ?? "undefined";
+}
+function fail(message) {
+	throw new EntityTimelineProjectionError(message);
+}
+//#endregion
 //#region src/editor/snapshot-utils.ts
 function isMap(value) {
 	return value instanceof Map;
@@ -2151,7 +4315,8 @@ var MengineDocSession = class {
 		this.server = new MedeoHttpDocStorage({
 			docId: options.docId,
 			client: options.client,
-			sseReconnectDelayMs: options.sseReconnectDelayMs
+			sseReconnectDelayMs: options.sseReconnectDelayMs,
+			readonlyMode: options.readonlyMode
 		});
 		this.synchronizer = new ClientServerSynchronizer(this.local, this.server);
 		this.manager = new DocManager(this.local, this.synchronizer);
@@ -2354,4 +4519,4 @@ function serverCovers(serverVV, target) {
 	return covers(server, target);
 }
 //#endregion
-export { DEFAULT_UNIT_TIME_MS, IMPLEMENTED_SEMANTIC_OP_KINDS, LANE_KINDS_IN_STACK_ORDER, ManualSyncDoc, MedeoHttpDocStorage, MemoryDocStorage, MengineAckFailedError, MengineDocSession, MengineHttpClient, MengineHttpRequestError, MenginePushRejectedError, MirrorVideoDocumentAdapter, PlainMemoryAdapter, SchemaValidator, SemanticEditor, TIMELINE_SKELETON_DURATION_MS, VIDEO_DOCUMENT_SCHEMA_VERSION, ValidationError, VideoDocumentValidationError, arrangeMainTrackSeamlessly, assertValidVideoDocument, base64ToBytes, buildInitialVideoDocument, buildSpeechHostMap, bytesToBase64, cascadeAfterVideoClipChanges, createEditSandbox, createMirrorVideoDocument, createMirrorVideoDocumentAdapter, createPlainMemoryAdapter, decodeDocVersionMark, derivePositionFromAbs, effectiveVideoClipDurationMs, encodeDocVersionMark, ensureLaneTrack, fillMainTrackTimeGaps, findLaneTrack, fromVideoDocument, generatePartId, getAt, hostForAbsMs, isEmptyVideoClip, isImplementedSemanticOpKind, isMap, laneTrackId, mainTrackRanges, partDurationMs, partUnionSchema, readMainTrackItems, readMengineEventStream, readPart, readPartDurationMs, readVideoDocumentFromDraft, reassignSpeechesToVideoClipsByTime, recalculateTimelineDuration, relativePositionForAbs, replayJournal, resolveAllSpeechOverlaps, resolveSpeechOverlapByShiftingVideos, safeDurationMs, schemas_exports as schemas, snapshotToPlain, solveVideoDocument, speedOf, syncAggregatedClipsTimePosition, toVideoDocument, validateVideoDocument, videoDocumentMirrorSchema, videoDocumentSchema, writeVideoDocumentToDraft };
+export { DEFAULT_UNIT_TIME_MS, ENTITY_TIMELINE_PROJECTION_SCHEMA_VERSION, EntityGraphHttpClient, EntityTimelineEditor, EntityTimelineProjectionError, IMPLEMENTED_SEMANTIC_OP_KINDS, LANE_KINDS_IN_STACK_ORDER, ManualSyncDoc, MedeoHttpDocStorage, MemoryDocStorage, MengineAckFailedError, MengineDocSession, MengineHttpClient, MengineHttpRequestError, MenginePushRejectedError, MirrorVideoDocumentAdapter, PlainMemoryAdapter, SchemaValidator, SemanticEditor, TIMELINE_SKELETON_DURATION_MS, VIDEO_DOCUMENT_SCHEMA_VERSION, ValidationError, VideoDocumentValidationError, applyEntityTimelineProjection, arrangeMainTrackSeamlessly, assertEntityProjectionPreservesLegacy, assertValidVideoDocument, base64ToBytes, buildInitialVideoDocument, buildSpeechHostMap, bytesToBase64, cascadeAfterVideoClipChanges, createEditSandbox, createMirrorVideoDocument, createMirrorVideoDocumentAdapter, createPlainMemoryAdapter, decodeDocVersionMark, derivePositionFromAbs, effectiveVideoClipDurationMs, encodeDocVersionMark, ensureLaneTrack, fillMainTrackTimeGaps, findLaneTrack, fromVideoDocument, generatePartId, getAt, hostForAbsMs, importMediaAsset, isEmptyVideoClip, isImplementedSemanticOpKind, isMap, laneTrackId, mainTrackRanges, migrateLegacyTimelineToEntities, partDurationMs, partUnionSchema, projectEntityTimeline, readMainTrackItems, readMengineEventStream, readPart, readPartDurationMs, readVideoDocumentFromDraft, reassignSpeechesToVideoClipsByTime, recalculateTimelineDuration, relativePositionForAbs, replayJournal, resolveAllSpeechOverlaps, resolveEntityTimelineLayout, resolveSpeechOverlapByShiftingVideos, safeDurationMs, schemas_exports as schemas, snapshotToPlain, solveVideoDocument, speedOf, syncAggregatedClipsTimePosition, toVideoDocument, validateVideoDocument, videoDocumentMirrorSchema, videoDocumentSchema, writeVideoDocumentToDraft };