@mengine/medeo-client 2.0.1-alpha.6 → 2.0.1-alpha.8

package/dist/index.js

@@ -1,6 +1,6 @@
-import { $ as ensureLaneTrack, A as assembleEntityContent, B as hasSequence, C as projectEntityTimeline, Ct as base64ToBytes, D as decodeEntityRelationRows, E as EntityTimelineProjectionError, F as updateEntityFields, G as fromVideoDocument, H as buildInitialVideoDocument, I as variantBaseEntityIds, J as assertValidVideoDocument, K as toVideoDocument, L as isJsonObject, M as assembleScriptText, N as findComposedAudioScript, O as ScriptCompositionError, P as selectAudioScriptSegment, Q as LANE_KINDS_IN_STACK_ORDER, R as createEntityId, S as resolveFieldPath, St as videoDocumentMirrorSchema, T as resolveEntityTimelineLayout, U as buildSpeechHostMap, V as isMediaAssetVariantKind, W as derivePositionFromAbs, X as partUnionSchema, Y as validateVideoDocument, Z as videoDocumentSchema, _ as audioScriptAssetHash, _t as VIDEO_DOCUMENT_SCHEMA_VERSION, a as applyEntityTimelineProjection, at as fillMainTrackTimeGaps, b as applyFieldChanges, bt as partUnionToDraft, c as writeVideoDocumentToDraft, ct as resolveAllSpeechOverlaps, d as LoroEntityDocument, dt as TIMELINE_SKELETON_DURATION_MS, et as findLaneTrack, f as LoroEntityDraft, ft as isEmptyVideoClip, g as audioScriptAssetFields, gt as ENTITY_TIMELINE_PROJECTION_SCHEMA_VERSION, h as audioScriptAssetContent, ht as DEFAULT_UNIT_TIME_MS, i as MirrorVideoDocumentAdapter, it as arrangeMainTrackSeamlessly, j as assemblePhoneticScriptContent, k as assembleCaptionContent, l as readVideoDocumentFromDraft, lt as resolveSpeechOverlapByShiftingVideos, m as entityOrderGroups, mt as safeDurationMs, n as createPlainMemoryAdapter, nt as solveVideoDocument, o as createMirrorVideoDocument, ot as reassignSpeechesToVideoClipsByTime, p as readEntityDocument, pt as partDurationMs, q as VideoDocumentValidationError, r as generatePartId, rt as cascadeAfterVideoClipChanges, s as createMirrorVideoDocumentAdapter, st as recalculateTimelineDuration, t as PlainMemoryAdapter, tt as laneTrackId, u as LORO_ENTITY_SCHEMA, ut as syncAggregatedClipsTimePosition, v as hasAudioScriptAsset, vt as effectiveVideoClipDurationMs, w as EntityProjectionGraph, wt as bytesToBase64, x as assertFieldChanges, xt as recordEntries, y as equalJson, yt as speedOf, z as createRelationId } from "./document-N-8GwtOX.js";
+import { $ as findLaneTrack, A as assemblePhoneticScriptContent, B as isMediaAssetVariantKind, C as EntityProjectionGraph, D as ScriptCompositionError, E as decodeEntityRelationRows, F as variantBaseEntityIds, G as toVideoDocument, H as buildSpeechHostMap, I as isJsonObject, J as validateVideoDocument, K as VideoDocumentValidationError, L as createEntityId, M as findComposedAudioScript, N as selectAudioScriptSegment, O as assembleCaptionContent, P as updateEntityFields, Q as ensureLaneTrack, R as createRelationId, S as projectEntityTimeline, St as bytesToBase64, T as EntityTimelineProjectionError, U as derivePositionFromAbs, V as buildInitialVideoDocument, W as fromVideoDocument, X as videoDocumentSchema, Y as partUnionSchema, Z as LANE_KINDS_IN_STACK_ORDER, _ as hasAudioScriptAsset, _t as speedOf, a as createMirrorVideoDocument, at as fillMainTrackTimeGaps, b as assertFieldChanges, bt as videoDocumentMirrorSchema, c as DocumentMutationGuard, ct as resolveAllSpeechOverlaps, d as LoroEntityDraft, dt as TIMELINE_SKELETON_DURATION_MS, et as hasResolvedPlacement, f as readEntityDocument, ft as isEmptyVideoClip, g as audioScriptAssetHash, gt as effectiveVideoClipDurationMs, h as audioScriptAssetFields, ht as DEFAULT_UNIT_TIME_MS, i as MirrorVideoDocumentAdapter, it as arrangeMainTrackSeamlessly, j as assembleScriptText, k as assembleEntityContent, l as LORO_ENTITY_SCHEMA, lt as resolveSpeechOverlapByShiftingVideos, m as audioScriptAssetContent, mt as safeDurationMs, n as createPlainMemoryAdapter, nt as solveVideoDocument, o as createMirrorVideoDocumentAdapter, ot as reassignSpeechesToVideoClipsByTime, p as entityOrderGroups, pt as partDurationMs, q as assertValidVideoDocument, r as generatePartId, rt as cascadeAfterVideoClipChanges, s as readVideoDocumentFromDraft, st as recalculateTimelineDuration, t as PlainMemoryAdapter, tt as laneTrackId, u as LoroEntityDocument, ut as syncAggregatedClipsTimePosition, v as equalJson, vt as partUnionToDraft, w as resolveEntityTimelineLayout, x as resolveFieldPath, xt as base64ToBytes, y as applyFieldChanges, yt as recordEntries, z as hasSequence } from "./document-DdwzfZ1g.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 { LoroDoc, UndoManager, VersionVector } from "loro-crdt";
 import { ClientServerSynchronizer, DocManager } from "@mengine/sync";
 import { DisposableSet, EventBus, Task } from "@mengine/utils";
 import { BaseDocStorage, DummyConnection } from "@mengine/storage";
@@ -60,12 +60,6 @@ var MengineHttpClient = class {
 	async fetchSnapshot() {
 		return await this.requestJson("snapshot");
 	}
-	async bootstrapSnapshot(snapshot) {
-		return await this.requestJson("bootstrap", {
-			method: "POST",
-			body: JSON.stringify({ snapshot: bytesToBase64(snapshot) })
-		});
-	}
 	/**
 	* Loro VV-diff pull: send the caller's oplog `VersionVector.encode` as `from`
 	* (omit for a full pull) and receive exactly the updates it is missing plus
@@ -168,9 +162,6 @@ async function safeReadJson$1(response) {
 //#endregion
 //#region src/client/sse.ts
 async function readMengineEventStream(options) {
-	const onUpdate = (event) => {
-		options.onUpdate(event);
-	};
 	const response = await options.client.fetch(options.client.eventsUrl(), {
 		headers: options.client.headers(),
 		signal: options.signal
@@ -189,15 +180,19 @@ async function readMengineEventStream(options) {
 		while (splitAt >= 0) {
 			const frame = buffer.slice(0, splitAt);
 			buffer = buffer.slice(buffer[splitAt] === "\r" ? splitAt + 4 : splitAt + 2);
-			handleSseFrame(frame, onUpdate);
+			handleSseFrame(frame, options);
 			splitAt = findSseFrameBoundary(buffer);
 		}
 	}
 }
-function handleSseFrame(frame, onUpdate) {
+function handleSseFrame(frame, options) {
 	const event = parseSseFrame(frame);
+	if (event.event === "resync") {
+		options.onResync?.();
+		return;
+	}
 	if (event.event !== "update" || event.data.length === 0) return;
-	onUpdate(JSON.parse(event.data.join("\n")));
+	options.onUpdate(JSON.parse(event.data.join("\n")));
 }
 function parseSseFrame(frame) {
 	let event = null;
@@ -584,36 +579,55 @@ function importMediaAsset(initial, fact, idFactory = (prefix) => `${prefix}_${gl
 		"image",
 		"video",
 		"audio",
-		"voice"
+		"voiceover"
 	].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`);
+	if ((fact.kind === "audio" || fact.kind === "voiceover") && fact.storageKey.trim() === "") throw new Error(`${fact.kind} ${fact.assetId} requires its physical storage key`);
 	decodeEntityRelationRows(initial, numericCoordinates);
 	assertCanonicalEditorResources(initial);
 	const entities = structuredClone([...initial.entities]);
 	const relations = structuredClone([...initial.relations]);
-	const system = fact.kind === "voice" ? "memota-speech" : "memota";
+	const system = fact.kind === "voiceover" ? "memota-speech" : "memota";
+	const entityKind = fact.kind === "voiceover" ? "audio" : fact.kind;
+	const timbre = fact.kind === "voiceover" ? fact.voice : void 0;
 	const existing = entities.filter((row) => {
 		const external = row.payload.external;
 		return isMediaAssetVariantKind(row.entityKind) && isJsonObject(external) && external.system === system && external.key === fact.assetId;
 	});
+	const requireMatchingVariant = (row) => {
+		const extent = row.payload.extent;
+		if (row.entityKind !== entityKind || fact.kind !== "image" && (!isJsonObject(extent) || extent.start !== 0 || extent.end !== fact.durationMs)) throw new Error(`Media facts conflict with existing identity for ${fact.assetId}`);
+		if (fact.storageKey !== void 0 && row.payload.storageKey !== fact.storageKey) {
+			if (row.payload.storageKey !== void 0) throw new Error(`Media facts conflict with existing storage key for ${fact.assetId}`);
+			return {
+				...row,
+				payload: {
+					...row.payload,
+					storageKey: fact.storageKey
+				}
+			};
+		}
+		return row;
+	};
 	if (existing.length > 1) throw new Error(`Duplicate media identities for ${fact.assetId}; reuse ${existing[0].entityId}`);
 	if (existing[0] !== void 0) {
-		const variant = requireMatchingVariant(existing[0], fact);
+		const variant = requireMatchingVariant(existing[0]);
 		replaceEntity$1(entities, variant.entityId, variant);
+		const voiceEntityId = bindVoiceTimbre(entities, relations, variant.entityId, timbre, idFactory);
 		return {
 			rows: {
 				entities,
 				relations
 			},
-			contentEntityId: variant.entityId
+			contentEntityId: variant.entityId,
+			...voiceEntityId
 		};
 	}
 	const entityId = createEntityId(idFactory("entity"));
 	if (entities.some((row) => row.entityId === entityId)) throw new Error(`Duplicate entity id ${entityId}`);
 	const variant = {
 		entityId,
-		entityKind: fact.kind,
+		entityKind,
 		payload: {
 			extent: fact.kind === "image" ? {
 				kind: "unbounded",
@@ -629,15 +643,11 @@ function importMediaAsset(initial, fact, idFactory = (prefix) => `${prefix}_${gl
 				system,
 				key: fact.assetId
 			},
-			...fact.storageKey === void 0 ? {} : { storageKey: fact.storageKey },
-			...fact.kind === "voice" && fact.voice !== void 0 ? { voice: {
-				system: fact.voice.system,
-				key: fact.voice.key,
-				...fact.voice.name === void 0 ? {} : { name: fact.voice.name }
-			} } : {}
+			...fact.storageKey === void 0 ? {} : { storageKey: fact.storageKey }
 		}
 	};
 	entities.push(variant);
+	const voiceEntityId = bindVoiceTimbre(entities, relations, entityId, timbre, idFactory);
 	const rows = {
 		entities,
 		relations
@@ -646,33 +656,58 @@ function importMediaAsset(initial, fact, idFactory = (prefix) => `${prefix}_${gl
 	assertCanonicalEditorResources(rows);
 	return {
 		rows,
-		contentEntityId: entityId
+		contentEntityId: entityId,
+		...voiceEntityId
 	};
 }
-function requireMatchingVariant(row, fact) {
-	const extent = row.payload.extent;
-	if (row.entityKind !== fact.kind || fact.kind !== "image" && (!isJsonObject(extent) || extent.start !== 0 || extent.end !== fact.durationMs) || fact.kind === "voice" && !sameVoice(row.payload.voice, fact.voice)) throw new Error(`Media facts conflict with existing identity for ${fact.assetId}`);
-	if (fact.storageKey !== void 0 && row.payload.storageKey !== fact.storageKey) {
-		if (row.payload.storageKey !== void 0) throw new Error(`Media facts conflict with existing storage key for ${fact.assetId}`);
-		return {
-			...row,
-			payload: {
-				...row.payload,
-				storageKey: fact.storageKey
-			}
-		};
+/**
+* Attach the timbre a synthesized voiceover was rendered with. One Voice
+* identity is shared by every take naming the same library entry, so an
+* existing row is reused rather than duplicated. Recorded media declares no
+* timbre and keeps no link.
+*/
+function bindVoiceTimbre(entities, relations, audioEntityId, descriptor, idFactory) {
+	const linked = relations.filter((relation) => relation.relationKind === "voice-timbre" && (relation.endpoint0EntityId === audioEntityId || relation.endpoint1EntityId === audioEntityId));
+	if (linked.length > 1) throw new Error(`Voiceover ${audioEntityId} has multiple Voice timbre relations`);
+	if (descriptor === void 0) {
+		if (linked.length > 0) throw new Error(`Recorded media ${audioEntityId} cannot keep a synthesized Voice timbre`);
+		return {};
 	}
-	return row;
+	const voice = entities.find((row) => row.entityKind === "voice" && sameVoiceDescriptor(row.payload.voice, descriptor)) ?? appendVoiceIdentity(entities, descriptor, idFactory);
+	const existing = linked[0];
+	if (existing === void 0) relations.push({
+		relationId: createRelationId(idFactory("relation")),
+		relationKind: "voice-timbre",
+		endpoint0EntityId: createEntityId(audioEntityId),
+		endpoint1EntityId: createEntityId(voice.entityId),
+		metadata: {},
+		trace: {}
+	});
+	else if (existing.endpoint0EntityId !== audioEntityId || existing.endpoint1EntityId !== voice.entityId) throw new Error(`Voiceover ${audioEntityId} already carries a different Voice timbre`);
+	return { voiceEntityId: voice.entityId };
+}
+function appendVoiceIdentity(entities, descriptor, idFactory) {
+	const voice = {
+		entityId: createEntityId(idFactory("entity")),
+		entityKind: "voice",
+		payload: { voice: {
+			system: descriptor.system,
+			key: descriptor.key,
+			...descriptor.name === void 0 ? {} : { name: descriptor.name }
+		} }
+	};
+	entities.push(voice);
+	return voice;
+}
+/** Two takes share a Voice identity only when they name the same library entry. */
+function sameVoiceDescriptor(stored, descriptor) {
+	return isJsonObject(stored) && stored.system === descriptor.system && stored.key === descriptor.key && stored.name === descriptor.name;
 }
 function replaceEntity$1(entities, entityId, replacement) {
 	const index = entities.findIndex((row) => row.entityId === entityId);
 	if (index < 0) throw new Error(`Entity id ${entityId} does not exist`);
 	entities[index] = replacement;
 }
-function sameVoice(left, right) {
-	if (right === void 0) return left === void 0;
-	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
 /**
@@ -1208,20 +1243,20 @@ var EntityTimelineEditor = class {
 				hostClipEntityId: input.hostClipEntityId,
 				anchorOffset: input.anchorOffset
 			};
-			if (input.placement !== void 0 && (input.hostClipEntityId !== void 0 || input.anchorOffset !== void 0)) throw new Error("Specify Voice placement or hostClipEntityId/anchorOffset, not both");
+			if (input.placement !== void 0 && (input.hostClipEntityId !== void 0 || input.anchorOffset !== void 0)) throw new Error("Specify voiceover placement or hostClipEntityId/anchorOffset, not both");
 			requireVolume(input.volume);
 			const imported = importMediaAsset(draft, input.media, this.idFactory);
 			replaceRows(draft, imported.rows);
-			const voice = requireEntityKind(draft, imported.contentEntityId, "voice");
+			const voiceover = requireEntityKind(draft, imported.contentEntityId, "audio");
 			const phonetic = this.requireComposedPhoneticScript(draft, input.phoneticScriptEntityId);
-			this.ensurePhoneticRender(draft, voice.entityId, phonetic.entityId);
+			this.ensurePhoneticRender(draft, voiceover.entityId, phonetic.entityId);
 			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,
+				contentEntityId: voiceover.entityId,
 				sourceRange: {
 					start: 0,
 					end: input.media.durationMs
@@ -1245,7 +1280,7 @@ var EntityTimelineEditor = class {
 				});
 				this.relinkRelation(draft, topology.markerContentRelation, {
 					endpoint0EntityId: topology.marker.entityId,
-					endpoint1EntityId: voice.entityId
+					endpoint1EntityId: voiceover.entityId
 				});
 				this.applyClipPlacement(draft, topology.clip.entityId, placement);
 				const placed = requireClipTopology(draft, topology.clip.entityId);
@@ -1264,11 +1299,12 @@ var EntityTimelineEditor = class {
 					}
 				});
 			}
-			this.reconcileVoiceoverCaptions(draft, voiceoverClipEntityId, voice.entityId, phonetic.entityId, input.captions);
+			this.reconcileVoiceoverCaptions(draft, voiceoverClipEntityId, voiceover.entityId, phonetic.entityId, input.captions);
 			this.resolveOneVoiceoverOverlap(draft);
 			return {
 				voiceoverClipEntityId,
-				voiceEntityId: voice.entityId,
+				voiceoverAudioEntityId: voiceover.entityId,
+				...imported.voiceEntityId === void 0 ? {} : { voiceEntityId: imported.voiceEntityId },
 				phoneticScriptEntityId: phonetic.entityId,
 				audioScriptEntityId: requireComposedAudioScript(draft, phonetic.entityId),
 				captionClipEntityIds: input.captions.map((caption) => caption.captionClipEntityId)
@@ -1474,23 +1510,23 @@ var EntityTimelineEditor = class {
 		draft.relations.push(this.createRelation(draft, "timeline-track", timeline.entityId, track.entityId));
 		return track;
 	}
-	/** The existing pronunciation variant a Voice consumes; composition is required. */
+	/** The existing pronunciation variant a voiceover consumes; composition is required. */
 	requireComposedPhoneticScript(draft, phoneticScriptEntityId) {
 		const phonetic = requireEntityKind(draft, phoneticScriptEntityId, "phonetic-script");
 		requireComposedAudioScript(draft, phonetic.entityId);
 		return phonetic;
 	}
 	/** Preserve the factual synthesis input, regardless of persisted endpoint positions. */
-	ensurePhoneticRender(draft, voiceEntityId, phoneticScriptEntityId) {
-		const renders = draft.relations.filter((relation) => relation.relationKind === "phonetic-script-render" && (relation.endpoint0EntityId === voiceEntityId || relation.endpoint1EntityId === voiceEntityId));
-		if (renders.length > 1) throw new Error(`Voice "${voiceEntityId}" has multiple PhoneticScript render relations`);
+	ensurePhoneticRender(draft, voiceoverAudioEntityId, phoneticScriptEntityId) {
+		const renders = draft.relations.filter((relation) => relation.relationKind === "phonetic-script-render" && (relation.endpoint0EntityId === voiceoverAudioEntityId || relation.endpoint1EntityId === voiceoverAudioEntityId));
+		if (renders.length > 1) throw new Error(`Voiceover "${voiceoverAudioEntityId}" has multiple PhoneticScript render relations`);
 		if (renders[0] !== void 0) {
-			if (otherEndpoint(renders[0], voiceEntityId) === phoneticScriptEntityId) return;
-			throw new Error(`Voice "${voiceEntityId}" already has a different PhoneticScript synthesis input`);
+			if (otherEndpoint(renders[0], voiceoverAudioEntityId) === phoneticScriptEntityId) return;
+			throw new Error(`Voiceover "${voiceoverAudioEntityId}" already has a different PhoneticScript synthesis input`);
 		}
-		draft.relations.push(this.createRelation(draft, "phonetic-script-render", voiceEntityId, phoneticScriptEntityId));
+		draft.relations.push(this.createRelation(draft, "phonetic-script-render", voiceoverAudioEntityId, phoneticScriptEntityId));
 	}
-	reconcileVoiceoverCaptions(draft, voiceoverClipEntityId, voiceEntityId, phoneticScriptEntityId, captions) {
+	reconcileVoiceoverCaptions(draft, voiceoverClipEntityId, voiceoverAudioEntityId, phoneticScriptEntityId, captions) {
 		const audioScriptEntityId = requireComposedAudioScript(draft, phoneticScriptEntityId);
 		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");
@@ -1521,7 +1557,7 @@ var EntityTimelineEditor = class {
 				};
 				draft.entities.push(content);
 				assertCaptionScript(draft, content.entityId, audioScriptEntityId);
-				draft.relations.push(this.createRelation(draft, "caption-alignment", content.entityId, voiceEntityId, { alignment: {
+				draft.relations.push(this.createRelation(draft, "caption-alignment", content.entityId, voiceoverAudioEntityId, { alignment: {
 					start: startMs,
 					end: startMs + durationMs
 				} }));
@@ -1578,7 +1614,7 @@ var EntityTimelineEditor = class {
 					}
 				}
 			});
-			this.replaceCaptionAlignment(draft, content.entityId, voiceEntityId, startMs, durationMs);
+			this.replaceCaptionAlignment(draft, content.entityId, voiceoverAudioEntityId, startMs, durationMs);
 		}
 	}
 	ensureRoleTrackForClip(draft, clipEntityId, role) {
@@ -1587,10 +1623,10 @@ var EntityTimelineEditor = class {
 		const timeline = requireEntityKind(draft, otherEndpoint(requireOneRelation(draft, track.entityId, "timeline-track"), track.entityId), "timeline");
 		return this.ensureRoleTrack(draft, timeline.entityId, role);
 	}
-	replaceCaptionAlignment(draft, captionEntityId, voiceEntityId, startMs, durationMs) {
+	replaceCaptionAlignment(draft, captionEntityId, voiceoverAudioEntityId, startMs, durationMs) {
 		const removed = new Set(incidentRelations(draft, captionEntityId).filter((relation) => relation.relationKind === "caption-alignment").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: {
+		draft.relations.push(this.createRelation(draft, "caption-alignment", captionEntityId, voiceoverAudioEntityId, { alignment: {
 			start: startMs,
 			end: startMs + durationMs
 		} }));
@@ -1999,7 +2035,7 @@ function migrateLegacyTimelineToEntities(legacy, assetFacts, initial = {
 }, 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");
+	if (hasResolvedPlacement(legacy)) fail("An entity projection cannot be migrated as legacy state");
 	const normalizedMainRanges = overlapNormalizedMainRanges(legacy);
 	let entities = structuredClone([...initial.entities]);
 	let relations = structuredClone([...initial.relations]);
@@ -2053,7 +2089,7 @@ function migrateLegacyTimelineToEntities(legacy, assetFacts, initial = {
 				relations
 			}, {
 				assetId: speech.origin_speech_id,
-				kind: "voice",
+				kind: "voiceover",
 				durationMs: speech.media_duration_ms,
 				storageKey: speech.audio_storage_key,
 				voice: {
@@ -2141,8 +2177,8 @@ function migrateLegacyTimelineToEntities(legacy, assetFacts, initial = {
 			} else if (part.caption !== void 0) {
 				const caption = part.caption;
 				duration = caption.initial_duration_ms;
-				const voice = contentByPartId.get(caption.speech_part_id);
-				const render = relations.find((relation) => relation.relationKind === "phonetic-script-render" && relation.endpoint0EntityId === voice);
+				const voiceover = contentByPartId.get(caption.speech_part_id);
+				const render = relations.find((relation) => relation.relationKind === "phonetic-script-render" && relation.endpoint0EntityId === voiceover);
 				const phonetic = entities.find((entity) => entity.entityId === render?.endpoint1EntityId);
 				const script = phonetic === void 0 ? void 0 : composedAudioScript(phonetic, entities);
 				if (script === void 0) fail("Legacy Caption has no composed AudioScript");
@@ -2169,7 +2205,7 @@ function migrateLegacyTimelineToEntities(legacy, assetFacts, initial = {
 					selection,
 					...caption.style === void 0 ? {} : { style: toEntityCaptionStyle(caption.style) }
 				});
-				link("caption-alignment", content, voice, { alignment: {
+				link("caption-alignment", content, voiceover, { alignment: {
 					start: caption.start_ms,
 					end: caption.start_ms + duration
 				} });
@@ -2225,27 +2261,23 @@ function migrateLegacyTimelineToEntities(legacy, assetFacts, initial = {
 		entities,
 		relations
 	};
-	assertEntityProjectionPreservesLegacy(legacy, projectEntityTimeline(rows, legacy.meta), rows);
+	assertEntityProjectionPreservesLegacy(legacy, projectEntityTimeline(rows), 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");
+	if (!hasResolvedPlacement(projection)) fail("Expected an entity projection for migration");
 	const normalizedMainRanges = overlapNormalizedMainRanges(legacy);
-	const compatibilityFacts = (document) => {
-		const { version: _version, ...view } = fromVideoDocument(document);
+	const compatibilityFacts = (document, placementResolved) => {
+		const view = fromVideoDocument(document, { placementResolved });
 		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
-		};
+		return { view };
 	};
-	if (canonical(compatibilityFacts(legacy)) !== canonical(compatibilityFacts(projection))) fail("Entity migration must preserve all existing timeline facts; edit after cutover");
+	if (canonical(compatibilityFacts(legacy, false)) !== canonical(compatibilityFacts(projection, true))) 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));
@@ -2512,21 +2544,21 @@ function requirePart(document, partId) {
 	if (part === void 0) fail(`Placed Clip ${partId} has no part payload`);
 	return part;
 }
-function ensureSpeechPhoneticChain(voiceEntityId, audioScriptText, phonemeScript, entities, relations, addEntity, link, documentAudioScriptEntityId) {
-	const renders = relations.filter((relation) => relation.relationKind === "phonetic-script-render" && relation.endpoint0EntityId === voiceEntityId);
-	if (renders.length > 1) fail(`Voice ${voiceEntityId} has ambiguous PhoneticScript provenance`);
+function ensureSpeechPhoneticChain(voiceoverAudioEntityId, audioScriptText, phonemeScript, entities, relations, addEntity, link, documentAudioScriptEntityId) {
+	const renders = relations.filter((relation) => relation.relationKind === "phonetic-script-render" && relation.endpoint0EntityId === voiceoverAudioEntityId);
+	if (renders.length > 1) fail(`Voiceover ${voiceoverAudioEntityId} has ambiguous PhoneticScript provenance`);
 	if (renders.length === 1) {
 		const phonetic = entities.find((entity) => entity.entityId === renders[0].endpoint1EntityId && entity.entityKind === "phonetic-script");
-		if (phonetic === void 0) fail(`Voice ${voiceEntityId} has a dangling PhoneticScript render`);
+		if (phonetic === void 0) fail(`Voiceover ${voiceoverAudioEntityId} has a dangling PhoneticScript render`);
 		const script = composedAudioScript(phonetic, entities);
-		if (script === void 0 || scriptText(script) !== audioScriptText) fail(`Voice ${voiceEntityId} conflicts with the legacy Speech script`);
+		if (script === void 0 || scriptText(script) !== audioScriptText) fail(`Voiceover ${voiceoverAudioEntityId} conflicts with the legacy Speech script`);
 		return phonetic.entityId;
 	}
 	const script = entities.find((entity) => entity.entityId === documentAudioScriptEntityId);
 	if (script === void 0 || script.entityKind !== "audio-script") fail("Migration must carry the fixed document AudioScript");
 	const segments = script.payload.segments;
 	if (Array.isArray(segments) && segments.length > 0) {
-		if (scriptText(script) !== audioScriptText) fail(`Voice ${voiceEntityId} conflicts with the project AudioScript text`);
+		if (scriptText(script) !== audioScriptText) fail(`Voiceover ${voiceoverAudioEntityId} conflicts with the project AudioScript text`);
 	} else {
 		const scriptIndex = entities.findIndex((row) => row.entityId === script.entityId);
 		entities[scriptIndex] = {
@@ -2541,7 +2573,7 @@ function ensureSpeechPhoneticChain(voiceEntityId, audioScriptText, phonemeScript
 		baseEntityIds: [script.entityId],
 		...phonemeScript === void 0 ? {} : { phonemeScript }
 	});
-	link("phonetic-script-render", voiceEntityId, phonetic);
+	link("phonetic-script-render", voiceoverAudioEntityId, phonetic);
 	return phonetic;
 }
 function composedAudioScript(phonetic, entities) {
@@ -3648,7 +3680,7 @@ function writeSpeechAssets(draft, assets) {
 			if (caption == null) continue;
 			const priorCaption = draft.part_library?.[captionId]?.caption;
 			setPart(draft, captionId, { caption: {
-				...priorCaption,
+				...priorCaption ?? { style: {} },
 				id: captionId,
 				kind: "caption",
 				initial_duration_ms: caption.duration_ms,
@@ -4057,6 +4089,10 @@ var ManualSyncDoc = class ManualSyncDoc {
 	client;
 	doc;
 	adapter;
+	/** Whether this document's timeline is owned by the Entity graph. */
+	isEntityDocument() {
+		return this.adapter.isEntityDocument();
+	}
 	editor;
 	/**
 	* The version the server is known to hold. Starts empty (nothing confirmed)
@@ -4075,17 +4111,24 @@ var ManualSyncDoc = class ManualSyncDoc {
 	* Fetches the snapshot up front rather than starting empty and converging: the
 	* agent's first act is to read the document, so there is no useful state before
 	* the snapshot lands. This also fails fast and loudly on a document that does
-	* not exist, instead of `MengineDocSession.waitForContent()`'s behavior of
-	* waiting forever for content that will never arrive.
+	* not exist or whose first snapshot is incomplete or invalid.
 	*/
 	static async open(options) {
-		const doc = new LoroDoc();
-		if (options.peerId != null) doc.setPeerId(options.peerId);
 		const response = await options.client.fetchSnapshot();
-		doc.import(base64ToBytes(response.snapshot));
-		const manualSyncDoc = new ManualSyncDoc(options.client, doc);
-		manualSyncDoc.watermark = manualSyncDoc.serverVVFrom(response.version.server_vv) ?? doc.oplogVersion();
-		return manualSyncDoc;
+		const doc = new LoroDoc();
+		let manualSyncDoc;
+		try {
+			if (options.peerId != null) doc.setPeerId(options.peerId);
+			if (doc.import(base64ToBytes(response.snapshot)).pending != null) throw new Error("Initial mengine snapshot has missing dependencies");
+			manualSyncDoc = new ManualSyncDoc(options.client, doc);
+			assertValidVideoDocument(manualSyncDoc.snapshot());
+			manualSyncDoc.watermark = manualSyncDoc.serverVVFrom(response.version.server_vv) ?? doc.oplogVersion();
+			return manualSyncDoc;
+		} catch (error) {
+			manualSyncDoc?.adapter.dispose();
+			doc.free();
+			throw error;
+		}
 	}
 	/** Current document read model (authoritative shape). */
 	snapshot() {
@@ -4104,9 +4147,9 @@ var ManualSyncDoc = class ManualSyncDoc {
 	editorPeerId() {
 		return this.doc.peerIdStr;
 	}
-	/** Current document projected to the legacy `VideoDraft` read shape. */
-	draft() {
-		return fromVideoDocument(this.adapter.snapshot());
+	/** Current content projected into the compatible track and part read shape. */
+	content() {
+		return fromVideoDocument(this.adapter.snapshot(), { placementResolved: this.isEntityDocument() });
 	}
 	/**
 	* Replay a deterministic sandbox journal into this document.
@@ -4126,9 +4169,8 @@ var ManualSyncDoc = class ManualSyncDoc {
 	*
 	* This pair replaces the legacy integer-version comparison that
 	* `DraftVersionDetector` used to tell the LLM "the draft was modified
-	* externally, reload before editing". Under mengine `meta.version` never
-	* changes, so that detector would go permanently silent; comparing version
-	* vectors restores the same capability.
+	* externally, reload before editing". Comparing Loro version vectors covers
+	* all collaborative edits without a business revision field in the document.
 	*
 	* Same capability, not a stronger one: like the legacy detector, this only
 	* reports what changed between two moments the caller chose to sample.
@@ -4212,6 +4254,7 @@ var ManualSyncDoc = class ManualSyncDoc {
 			if (serverVV != null) this.watermark = serverVV;
 			return {
 				kind: response.kind,
+				mengineUpdateSeq: response.version?.update_seq ?? response.update_seq ?? void 0,
 				updateSeq: response.update_seq ?? void 0,
 				collaborated: serverVV != null && !covers(localVersion, serverVV)
 			};
@@ -4250,22 +4293,24 @@ var ManualSyncDoc = class ManualSyncDoc {
 * recovers whatever the stream missed while it was down. Recovery therefore
 * lives in the synchronizer (keyed on the real doc version), not here.
 *
-* Each SSE frame's updates are forwarded verbatim via `onUpdate`; this
+* Update frames are forwarded via `onUpdate`, resync hints via `onResync`; this
 * connection keeps no version cursor and does no catch-up of its own. Dedup is
 * unnecessary because `LoroDoc.import` is idempotent by OpId/VV.
 */
 var SseConnection = class {
 	client;
 	onUpdate;
+	onResync;
 	reconnectDelayMs;
 	inner = void 0;
 	event = new EventBus();
 	streamTask = null;
 	_status = "idle";
 	_error;
-	constructor(client, onUpdate, reconnectDelayMs) {
+	constructor(client, onUpdate, onResync, reconnectDelayMs) {
 		this.client = client;
 		this.onUpdate = onUpdate;
+		this.onResync = onResync;
 		this.reconnectDelayMs = reconnectDelayMs;
 	}
 	get status() {
@@ -4326,10 +4371,12 @@ var SseConnection = class {
 					client: this.client,
 					signal,
 					onOpen: () => this.setStatus("connected"),
+					onResync: this.onResync,
 					onUpdate: (event) => {
 						for (const update of event.updates) this.onUpdate(update);
 					}
 				});
+				if (!signal.aborted) this.setStatus("connecting", /* @__PURE__ */ new Error("SSE stream closed"));
 			} catch (error) {
 				if (signal.aborted) break;
 				this.setStatus("connecting", error instanceof Error ? error : new Error(String(error)));
@@ -4374,7 +4421,7 @@ var MedeoHttpDocStorage = class {
 		this.options = options;
 		this.client = options.client;
 		this.docId = options.docId;
-		this.connection = new SseConnection(this.client, (update) => this.emitUpdate(update), options.sseReconnectDelayMs ?? 500);
+		this.connection = new SseConnection(this.client, (update) => this.emitUpdate(update), () => this.events.emit("resync"), options.sseReconnectDelayMs ?? 500);
 	}
 	get isReadonly() {
 		return this.options.readonlyMode ?? false;
@@ -4382,6 +4429,7 @@ var MedeoHttpDocStorage = class {
 	async getDoc(docId) {
 		this.assertDocId(docId);
 		const snapshot = await this.client.fetchSnapshot();
+		this.reportServerVersion(snapshot.version?.server_vv);
 		const now = /* @__PURE__ */ new Date();
 		return {
 			docId,
@@ -4393,6 +4441,7 @@ var MedeoHttpDocStorage = class {
 	async getDocDiff(docId, knownVersion) {
 		this.assertDocId(docId);
 		const response = await this.client.sync(knownVersion);
+		this.reportServerVersion(response.server_vv);
 		return {
 			docId,
 			missing: base64ToBytes(response.update),
@@ -4423,7 +4472,7 @@ var MedeoHttpDocStorage = class {
 		if (update.data.byteLength === 0) return {};
 		try {
 			const response = await this.client.pushUpdate(update.data);
-			const serverVV = decodeServerVV(response.version?.server_vv);
+			const serverVV = this.reportServerVersion(response.version?.server_vv);
 			this.events.emit("pushOutcome", {
 				kind: response.kind,
 				updateSeq: response.update_seq ?? void 0,
@@ -4451,6 +4500,19 @@ var MedeoHttpDocStorage = class {
 	subscribePushOutcome(callback) {
 		return this.events.on("pushOutcome", callback);
 	}
+	/** Observe live hints that require VV catch-up without replacing the SSE connection. */
+	subscribeResync(callback) {
+		return this.events.on("resync", callback);
+	}
+	/** Authoritative HTTP reads and accepted pushes, never inferred from SSE bytes. */
+	subscribeServerVersion(callback) {
+		return this.events.on("serverVersion", callback);
+	}
+	reportServerVersion(encoded) {
+		const version = decodeServerVV(encoded);
+		if (version != null) this.events.emit("serverVersion", version);
+		return version;
+	}
 	async deleteDoc(_docId) {
 		throw new Error("MedeoHttpDocStorage does not support deleteDoc");
 	}
@@ -4567,6 +4629,118 @@ var MemoryDocStorage = class extends BaseDocStorage {
 	}
 };
 //#endregion
+//#region src/session/document-undo-manager.ts
+/**
+* Tracks the shared LoroDoc independently of semantic editing. Undo/redo use
+* the same mutation guard as the adapter and publish settled availability.
+*/
+var DocumentUndoManager = class {
+	doc;
+	mutationGuard;
+	onChange;
+	manager;
+	unsubscribe;
+	disposed = false;
+	notificationQueued = false;
+	published = {
+		canUndo: false,
+		canRedo: false
+	};
+	activeSource = null;
+	constructor(doc, mutationGuard, onChange) {
+		this.doc = doc;
+		this.mutationGuard = mutationGuard;
+		this.onChange = onChange;
+		const peer = doc.peerIdStr;
+		this.manager = new UndoManager(doc, {
+			mergeInterval: 0,
+			maxUndoSteps: 100,
+			excludeOriginPrefixes: ["mengine.bootstrap", "mengine.initialize"],
+			onPush: (_isUndo, range) => {
+				this.scheduleNotification();
+				return {
+					value: this.activeSource ?? {
+						peer,
+						counter: range.start
+					},
+					cursors: []
+				};
+			},
+			onPop: () => this.scheduleNotification()
+		});
+		this.unsubscribe = doc.subscribe(() => this.scheduleNotification());
+	}
+	getState() {
+		this.assertActive();
+		return {
+			canUndo: this.manager.canUndo(),
+			canRedo: this.manager.canRedo()
+		};
+	}
+	undo(options) {
+		return this.applyUndoRedo("Undo", options);
+	}
+	redo(options) {
+		return this.applyUndoRedo("Redo", options);
+	}
+	beginGroup() {
+		this.assertActive();
+		this.mutationGuard.run(() => this.manager.groupStart());
+	}
+	endGroup() {
+		this.assertActive();
+		this.mutationGuard.run(() => this.manager.groupEnd());
+		this.scheduleNotification();
+	}
+	applyUndoRedo(kind, options) {
+		this.assertActive();
+		return this.mutationGuard.run(() => {
+			if (kind === "Undo" ? !this.manager.canUndo() : !this.manager.canRedo()) return false;
+			this.activeSource = kind === "Undo" ? this.manager.topUndoValue() : this.manager.topRedoValue();
+			try {
+				this.doc.setNextCommitOptions({ message: JSON.stringify({
+					semantic_op: kind,
+					payload: { source: this.activeSource },
+					intent: options?.intent ?? null,
+					actor: options?.actor ?? null
+				}) });
+				const before = this.doc.oplogFrontiers();
+				return (kind === "Undo" ? this.manager.undo() : this.manager.redo()) && this.doc.cmpWithFrontiers(before) !== 0;
+			} finally {
+				this.doc.clearNextCommitOptions();
+				this.activeSource = null;
+				this.scheduleNotification();
+			}
+		});
+	}
+	dispose() {
+		if (this.disposed) return;
+		this.disposed = true;
+		this.unsubscribe();
+		this.manager.setOnPush(void 0);
+		this.manager.setOnPop(void 0);
+		this.manager.free();
+	}
+	scheduleNotification() {
+		if (this.notificationQueued || this.disposed) return;
+		this.notificationQueued = true;
+		queueMicrotask(() => {
+			this.notificationQueued = false;
+			if (!this.disposed) this.publish();
+		});
+	}
+	publish() {
+		if (this.disposed) return;
+		const state = this.getState();
+		if (state.canUndo === this.published.canUndo && state.canRedo === this.published.canRedo) return;
+		this.published = state;
+		this.onChange();
+	}
+	assertActive() {
+		if (this.disposed) throw new Error("mengine doc undo manager is disposed");
+	}
+};
+//#endregion
 //#region src/session/mengine-doc-session.ts
 /**
 * Raised by {@link MengineDocSession.waitForServerAck} when the local edits it
@@ -4602,13 +4776,9 @@ var MengineAckFailedError = class extends Error {
 * A live editing session for one Medeo document — the single entry point clients
 * (FE draft driver, Agent, embeds) use to open, edit, and observe a document.
 *
-* It assembles the engine sync stack around one Medeo document:
-*
-*   local DocStorage  ─┐
-*                      ├─ ClientServerSynchronizer ── DocManager ── LoroDoc
-*   MedeoHttpDocStorage┘                                              │
-*                          (remote = Rust mengine-server)             ▼
-*                                                   MirrorVideoDocumentAdapter + SemanticEditor
+* SemanticEditor writes through MirrorVideoDocumentAdapter directly, while
+* DocumentUndoManager observes the same LoroDoc independently. Both mutation
+* paths use the session's DocumentMutationGuard, closed before teardown.
 *
 * `DocManager` owns the `LoroDoc`: local edits committed on the adapter are
 * picked up via `subscribeLocalUpdates`, saved to local storage, then pushed to
@@ -4629,11 +4799,20 @@ var MengineDocSession = class {
 	manager;
 	events = new EventBus();
 	disposables = new DisposableSet();
+	mutationGuard = new DocumentMutationGuard();
 	adapterValue = null;
 	editorValue = null;
+	undoManagerValue = null;
 	started = false;
+	startTask = null;
+	destroyed = false;
+	lifetime = null;
+	hasConnected = false;
+	initialVersionValue = null;
+	localVersionValue = null;
+	pushErrorValue = null;
 	/**
-	* Latest server oplog version seen on a push outcome. Lets `waitForServerAck`
+	* Latest server oplog version seen on an authoritative HTTP response. Lets `waitForServerAck`
 	* return without waiting when the server is already known to cover the local
 	* doc (e.g. nothing was edited since the last confirmed push).
 	*/
@@ -4662,14 +4841,14 @@ var MengineDocSession = class {
 		return this.server.subscribePushOutcome(callback);
 	}
 	/**
-	* Resolve once the server has durably accepted the local document state as of
+	* Resolve once the server has durably accepted the local commits as of
 	* *now* — the capability an Agent tool needs to answer "did my edit land?"
 	* before reporting success.
 	*
 	* Call it right after the editor ops whose durability matters. It snapshots the
-	* local doc's current version and resolves on the first push outcome whose
-	* `serverVV` covers that version, i.e. the server log is at least as advanced as
-	* the local doc was when this was called.
+	* latest local commit's version (or the loaded baseline before any edit) and
+	* resolves when an authoritative server version covers it. Remote-only
+	* imports do not extend this target, matching the displayed confirmation state.
 	*
 	* Version coverage, not byte identity, is the acceptance test — for two reasons:
 	* the ops may reach the server inside a merged blob rather than as the exact
@@ -4684,31 +4863,39 @@ var MengineDocSession = class {
 	* @throws {MengineAckFailedError} on timeout, rejection, or transport failure.
 	*/
 	async waitForServerAck(options = {}) {
-		if (this.adapterValue == null) throw new Error("mengine doc session is not started");
+		if (this.adapterValue == null || this.lifetime == null) throw new Error("mengine doc session is not started");
 		const timeoutMs = options.timeoutMs ?? 15e3;
-		const target = this.manager.connectDoc(this.docId).version();
+		const target = this.confirmationTarget() ?? this.manager.connectDoc(this.docId).version();
+		const signal = this.lifetime.signal;
 		if (this.serverVVValue != null && serverCovers(this.serverVVValue, target)) return;
 		await new Promise((resolve, reject) => {
-			let off = () => {};
+			const cleanup = [];
 			let done = false;
 			const settle = (error) => {
 				if (done) return;
 				done = true;
 				clearTimeout(timer);
-				off();
+				cleanup.forEach((off) => off());
 				if (error == null) resolve();
 				else reject(error);
 			};
 			const timer = setTimeout(() => {
 				settle(new MengineAckFailedError("timeout", void 0, void 0, `mengine did not acknowledge the update within ${timeoutMs}ms`));
 			}, timeoutMs);
-			off = this.server.subscribePushOutcome((outcome) => {
+			const onAbort = () => settle(new MengineAckFailedError("failed", void 0, void 0, "mengine doc session destroyed"));
+			signal.addEventListener("abort", onAbort, { once: true });
+			cleanup.push(() => signal.removeEventListener("abort", onAbort));
+			cleanup.push(this.events.on("syncState", () => {
+				if (this.serverVVValue != null && serverCovers(this.serverVVValue, target)) settle(void 0);
+			}));
+			cleanup.push(this.server.subscribePushOutcome((outcome) => {
 				if (outcome.kind === "rejected" || outcome.kind === "failed") {
 					settle(new MengineAckFailedError(outcome.kind, outcome.code, outcome.error, outcome.error?.message ?? `mengine push ${outcome.kind}`));
 					return;
 				}
-				if (outcome.serverVV != null && serverCovers(outcome.serverVV, target)) settle(void 0);
-			});
+			}));
+			if (signal.aborted) onAbort();
+			else this.synchronizer.requestSync(this.docId);
 		});
 	}
 	/**
@@ -4744,44 +4931,154 @@ var MengineDocSession = class {
 		if (this.adapterValue == null) throw new Error("mengine doc session is not started");
 		return this.adapterValue.snapshot();
 	}
+	/** Current-session undo/redo availability. Loading and closed sessions report false. */
+	getUndoState() {
+		return this.undoManagerValue?.getState() ?? {
+			canUndo: false,
+			canRedo: false
+		};
+	}
+	/**
+	* Supplies current availability immediately, then coalesces stack changes in a
+	* microtask. Session teardown publishes empty availability synchronously.
+	*/
+	subscribeUndoState(cb) {
+		const notify = () => cb(this.getUndoState());
+		const off = this.destroyed ? () => {} : this.events.on("undoState", notify);
+		notify();
+		return off;
+	}
+	/**
+	* Undo a local edit immediately; server confirmation remains asynchronous.
+	* On a shared LWW field this writes its prior value, potentially overwriting a
+	* later remote edit to that same field. Returns false if no update is produced.
+	*/
+	undo(options) {
+		if (this.undoManagerValue == null) throw new Error("mengine doc undo manager is not ready");
+		return this.undoManagerValue.undo(options);
+	}
+	/**
+	* Restore the state visible before undo without rerunning external side effects.
+	* Returns false if no update is produced; durable confirmation is separate.
+	*/
+	redo(options) {
+		if (this.undoManagerValue == null) throw new Error("mengine doc undo manager is not ready");
+		return this.undoManagerValue.redo(options);
+	}
+	/**
+	* Combine existing semantic operations (e.g. trim a clip and adjust its volume)
+	* or repeated commits during one drag gesture into a single undo step. A gesture
+	* that only previews locally and commits once on release needs no group.
+	* Each commit is immediately visible locally and enters sync independently;
+	* a later failure does not roll it back.
+	* Always pair with endUndoGroup in a finally block. Conflicting remote imports
+	* can end/split the group early, and unrelated local edits would join it.
+	* Complete asynchronous asset preparation before opening the group.
+	*/
+	beginUndoGroup() {
+		if (this.undoManagerValue == null) throw new Error("mengine doc undo manager is not ready");
+		this.undoManagerValue.beginGroup();
+	}
+	/** End a gesture, including one already split by a conflicting remote import. */
+	endUndoGroup() {
+		if (this.undoManagerValue == null) throw new Error("mengine doc undo manager is not ready");
+		this.undoManagerValue.endGroup();
+	}
 	/**
 	* Start the sync stack and connect the document.
 	*
-	* Returns once the local snapshot has loaded into the Loro doc so callers can
-	* read an initial snapshot. Remote convergence continues in the background and
-	* surfaces through `subscribe`.
+	* Returns after DocManager loads a local snapshot, or after the first remote
+	* sync when no local snapshot exists. A valid empty document is ready too.
+	* Cached documents can open before SSE connects; subsequent remote changes
+	* surface through `subscribe`.
 	*/
-	async start() {
-		if (this.started) return this.snapshot();
+	start() {
+		if (this.destroyed) return Promise.reject(/* @__PURE__ */ new Error("mengine doc session destroyed"));
+		if (this.startTask != null) return this.startTask;
 		this.started = true;
-		this.local.connection.connect();
-		this.server.connection.connect();
+		this.lifetime = new AbortController();
+		this.startTask = this.open().catch((error) => {
+			const wasDestroyed = this.destroyed;
+			this.destroy();
+			if (wasDestroyed) throw new Error("mengine doc session destroyed");
+			throw error;
+		});
+		return this.startTask;
+	}
+	async open() {
+		this.disposables.add(this.server.subscribeResync(() => this.synchronizer.requestSync(this.docId)));
+		this.disposables.add(this.server.subscribeServerVersion((version) => {
+			this.serverVVValue = version;
+			if (this.getSyncState().confirmation === "confirmed") this.pushErrorValue = null;
+			this.emitSyncState();
+		}));
+		this.disposables.add(this.server.subscribePushOutcome((outcome) => {
+			this.pushErrorValue = outcome.kind === "failed" || outcome.kind === "rejected" ? outcome.error ?? /* @__PURE__ */ new Error(`mengine push ${outcome.kind}`) : null;
+			this.emitSyncState();
+		}));
+		this.disposables.add(this.server.connection.onStatusChanged((status) => {
+			if (status === "connected") this.hasConnected = true;
+			this.emitSyncState();
+		}));
 		this.disposables.add(() => this.local.connection.disconnect());
 		this.disposables.add(() => this.server.connection.disconnect());
+		this.local.connection.connect();
+		await this.local.connection.waitForConnected().abortOn(this.lifetime.signal);
+		if (this.destroyed) throw new Error("mengine doc session destroyed");
+		this.server.connection.connect();
 		this.synchronizer.start();
 		this.manager.start();
 		this.disposables.add(() => this.synchronizer.stop());
 		this.disposables.add(() => this.manager.stop());
 		const doc = this.manager.connectDoc(this.docId);
-		if (this.options.peerId != null) doc.setPeerId(this.options.peerId);
-		this.adapterValue = new MirrorVideoDocumentAdapter(doc);
-		this.editorValue = new SemanticEditor(this.adapterValue);
 		this.disposables.add(() => this.manager.disconnectDoc(this.docId));
+		if (this.options.peerId != null) doc.setPeerId(this.options.peerId);
+		this.adapterValue = new MirrorVideoDocumentAdapter(doc, this.mutationGuard);
 		const unsubscribe = doc.subscribe((event) => {
 			if (this.adapterValue == null) return;
+			if (event.by === "local") this.localVersionValue = doc.version();
+			this.emitSyncState();
 			this.events.emit("update", {
 				source: event.by === "local" ? "local" : "remote",
 				snapshot: this.adapterValue.snapshot()
 			});
 		});
 		this.disposables.add(unsubscribe);
-		this.disposables.add(this.manager.onDocStateChange(this.docId, (state) => this.events.emit("state", state)));
-		this.disposables.add(this.server.subscribePushOutcome((outcome) => {
-			if (outcome.serverVV != null) this.serverVVValue = outcome.serverVV;
+		this.disposables.add(this.manager.onDocStateChange(this.docId, (state) => {
+			this.events.emit("state", state);
+			this.emitSyncState();
 		}));
-		await this.waitForContent();
+		await this.waitForInitialLoad();
+		if (this.destroyed) throw new Error("mengine doc session destroyed");
+		assertValidVideoDocument(this.snapshot());
+		this.undoManagerValue = new DocumentUndoManager(doc, this.mutationGuard, () => this.events.emit("undoState"));
+		this.editorValue = new SemanticEditor(this.adapterValue);
+		this.initialVersionValue = doc.version();
+		this.emitSyncState();
 		return this.snapshot();
 	}
+	getSyncState() {
+		const state = this.getState();
+		const target = this.confirmationTarget();
+		const confirmation = this.serverVVValue == null || target == null ? this.localVersionValue == null ? "unknown" : "pending" : serverCovers(this.serverVVValue, target) ? "confirmed" : "pending";
+		const connection = !this.started ? "disconnected" : this.server.connection.status === "connected" ? "connected" : this.hasConnected || this.server.connection.error != null ? "disconnected" : "connecting";
+		return {
+			confirmation,
+			phase: connection === "disconnected" ? "offline" : this.pushErrorValue != null || state.error != null ? "failed" : connection === "connecting" ? "connecting" : state.syncing ? "syncing" : "idle"
+		};
+	}
+	confirmationTarget() {
+		return this.localVersionValue ?? this.initialVersionValue;
+	}
+	/** Immediately supplies current state; unsubscribe when the host changes docs. */
+	subscribeSyncState(cb) {
+		const off = this.events.on("syncState", cb);
+		cb(this.getSyncState());
+		return off;
+	}
+	emitSyncState() {
+		this.events.emit("syncState", this.getSyncState());
+	}
 	subscribe(cb) {
 		return this.events.on("update", cb);
 	}
@@ -4792,40 +5089,48 @@ var MengineDocSession = class {
 		return this.manager.getDocState(this.docId);
 	}
 	destroy() {
+		if (this.destroyed) return;
+		this.destroyed = true;
+		this.mutationGuard.close();
+		this.started = false;
+		this.lifetime?.abort();
+		this.undoManagerValue?.dispose();
+		this.undoManagerValue = null;
+		this.events.emit("undoState");
 		this.disposables.dispose();
+		this.emitSyncState();
 		this.events.clearAll();
+		this.adapterValue?.dispose();
 		this.adapterValue = null;
 		this.editorValue = null;
 		this.started = false;
 	}
-	/**
-	* Resolve once the Loro doc holds the document root.
-	*
-	* `DocManager` loads from local storage, which starts empty for a fresh
-	* client; the server snapshot arrives asynchronously via the first sync job.
-	* `loaded` only means the local load ran, so we wait for actual content
-	* (populated schema roots) instead, surfaced by the doc subscription set up
-	* in `start()`.
-	*/
-	async waitForContent() {
-		if (this.hasContent()) return;
-		await new Promise((resolve) => {
-			const off = this.events.on("update", () => {
-				if (this.hasContent()) {
-					off();
-					resolve();
-				}
-			});
+	/** Local absence needs a remote sync; empty business content does not. */
+	async waitForInitialLoad() {
+		const signal = this.lifetime.signal;
+		await new Promise((resolve, reject) => {
+			let off = () => {};
+			let offConnection = () => {};
+			const finish = (error) => {
+				off();
+				offConnection();
+				signal.removeEventListener("abort", onAbort);
+				if (error != null) reject(error);
+				else resolve();
+			};
+			const onAbort = () => finish(/* @__PURE__ */ new Error("mengine doc session destroyed"));
+			const check = (state) => {
+				if (state.loaded && (state.loadedFromLocal || state.synced)) finish();
+				else if (state.error != null) finish(new Error(state.error));
+				else if (state.loaded && this.server.connection.error != null) finish(this.server.connection.error);
+			};
+			off = this.onStateChange(check);
+			offConnection = this.server.connection.onStatusChanged(() => check(this.getState()));
+			signal.addEventListener("abort", onAbort, { once: true });
+			if (signal.aborted) onAbort();
+			else check(this.getState());
 		});
 	}
-	hasContent() {
-		if (this.adapterValue == null) return false;
-		try {
-			return this.adapterValue.hasContent();
-		} catch {
-			return false;
-		}
-	}
 };
 /**
 * True when the *encoded* server version `serverVV` includes everything in
@@ -4849,4 +5154,4 @@ function serverCovers(serverVV, target) {
 	return covers(server, target);
 }
 //#endregion
-export { DEFAULT_UNIT_TIME_MS, ENTITY_TIMELINE_PROJECTION_SCHEMA_VERSION, EntityGraphHttpClient, EntityTimelineEditor, EntityTimelineProjectionError, IMPLEMENTED_SEMANTIC_OP_KINDS, LANE_KINDS_IN_STACK_ORDER, LORO_ENTITY_SCHEMA, LoroEntityDocument, LoroEntityDraft, ManualSyncDoc, MedeoHttpDocStorage, MemoryDocStorage, MengineAckFailedError, MengineDocSession, MengineHttpClient, MengineHttpRequestError, MenginePushRejectedError, MirrorVideoDocumentAdapter, PlainMemoryAdapter, SchemaValidator, ScriptCompositionError, SemanticEditor, TIMELINE_SKELETON_DURATION_MS, VIDEO_DOCUMENT_SCHEMA_VERSION, ValidationError, VideoDocumentValidationError, applyEntityRows, applyEntityTimelineProjection, applyFieldChanges, arrangeMainTrackSeamlessly, assembleCaptionContent, assembleEntityContent, assemblePhoneticScriptContent, assembleScriptText, assertCanonicalEditorResources, assertEntityProjectionPreservesLegacy, assertFieldChanges, assertMediaAssetWritePolicy, assertValidVideoDocument, audioScriptAssetContent, audioScriptAssetFields, audioScriptAssetHash, base64ToBytes, buildInitialVideoDocument, buildSpeechHostMap, bytesToBase64, cascadeAfterVideoClipChanges, compileEntityRows, createEditSandbox, createMirrorVideoDocument, createMirrorVideoDocumentAdapter, createPlainMemoryAdapter, decodeDocVersionMark, derivePositionFromAbs, effectiveVideoClipDurationMs, encodeDocVersionMark, ensureEditorFoundation, ensureLaneTrack, fillMainTrackTimeGaps, findComposedAudioScript, findLaneTrack, fromVideoDocument, generatePartId, getAt, hasAudioScriptAsset, hostForAbsMs, importMediaAsset, isEmptyVideoClip, isImplementedSemanticOpKind, isMap, laneTrackId, mainTrackRanges, migrateLegacyTimelineToEntities, partDurationMs, partUnionSchema, prepareCaptionContent, projectEntityTimeline, readDocumentAudioScript, readEntityDocument, readMainTrackItems, readMengineEventStream, readPart, readPartDurationMs, readVideoDocumentFromDraft, reassignSpeechesToVideoClipsByTime, recalculateTimelineDuration, relativePositionForAbs, replayJournal, resolveAllSpeechOverlaps, resolveEntityTimelineLayout, resolveFieldPath, resolveSpeechOverlapByShiftingVideos, safeDurationMs, schemas_exports as schemas, selectAudioScriptSegment, snapshotToPlain, solveVideoDocument, speedOf, syncAggregatedClipsTimePosition, toVideoDocument, validateVideoDocument, videoDocumentMirrorSchema, videoDocumentSchema, writeVideoDocumentToDraft };
+export { DEFAULT_UNIT_TIME_MS, EntityGraphHttpClient, EntityTimelineEditor, EntityTimelineProjectionError, IMPLEMENTED_SEMANTIC_OP_KINDS, LANE_KINDS_IN_STACK_ORDER, LORO_ENTITY_SCHEMA, LoroEntityDocument, LoroEntityDraft, ManualSyncDoc, MedeoHttpDocStorage, MemoryDocStorage, MengineAckFailedError, MengineDocSession, MengineHttpClient, MengineHttpRequestError, MenginePushRejectedError, MirrorVideoDocumentAdapter, PlainMemoryAdapter, SchemaValidator, ScriptCompositionError, SemanticEditor, TIMELINE_SKELETON_DURATION_MS, ValidationError, VideoDocumentValidationError, applyEntityRows, applyFieldChanges, arrangeMainTrackSeamlessly, assembleCaptionContent, assembleEntityContent, assemblePhoneticScriptContent, assembleScriptText, assertCanonicalEditorResources, assertEntityProjectionPreservesLegacy, assertFieldChanges, assertMediaAssetWritePolicy, assertValidVideoDocument, audioScriptAssetContent, audioScriptAssetFields, audioScriptAssetHash, base64ToBytes, buildInitialVideoDocument, buildSpeechHostMap, bytesToBase64, cascadeAfterVideoClipChanges, compileEntityRows, createEditSandbox, createMirrorVideoDocument, createMirrorVideoDocumentAdapter, createPlainMemoryAdapter, decodeDocVersionMark, derivePositionFromAbs, effectiveVideoClipDurationMs, encodeDocVersionMark, ensureEditorFoundation, ensureLaneTrack, fillMainTrackTimeGaps, findComposedAudioScript, findLaneTrack, fromVideoDocument, generatePartId, getAt, hasAudioScriptAsset, hostForAbsMs, importMediaAsset, isEmptyVideoClip, isImplementedSemanticOpKind, isMap, laneTrackId, mainTrackRanges, migrateLegacyTimelineToEntities, partDurationMs, partUnionSchema, prepareCaptionContent, projectEntityTimeline, readDocumentAudioScript, readEntityDocument, readMainTrackItems, readMengineEventStream, readPart, readPartDurationMs, readVideoDocumentFromDraft, reassignSpeechesToVideoClipsByTime, recalculateTimelineDuration, relativePositionForAbs, replayJournal, resolveAllSpeechOverlaps, resolveEntityTimelineLayout, resolveFieldPath, resolveSpeechOverlapByShiftingVideos, safeDurationMs, schemas_exports as schemas, selectAudioScriptSegment, snapshotToPlain, solveVideoDocument, speedOf, syncAggregatedClipsTimePosition, toVideoDocument, validateVideoDocument, videoDocumentMirrorSchema, videoDocumentSchema };