@mengine/medeo-client 2.0.1-alpha.5 → 2.0.1-alpha.7

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-Bzzcn3g7.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-Bnxm1p5E.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;
@@ -1999,7 +1994,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]);
@@ -2225,27 +2220,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));
@@ -3648,7 +3639,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 +4048,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 +4070,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 +4106,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 +4128,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 +4213,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 +4252,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 +4330,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 +4380,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 +4388,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 +4400,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 +4431,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 +4459,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 +4588,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 +4735,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 +4758,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 +4800,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 +4822,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 +4890,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 +5048,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 +5113,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 };