@mengine/medeo-client 2.0.1-alpha.2 → 2.0.1-alpha.20

package/dist/index.js

@@ -1,6 +1,6 @@
-import { $ as cascadeAfterVideoClipChanges, A as selectAudioScriptSegment, B as derivePositionFromAbs, C as decodeEntityRelationRows, D as assemblePhoneticScriptContent, E as assembleEntityContent, F as createRelationId, G as validateVideoDocument, H as toVideoDocument, I as hasSequence, J as LANE_KINDS_IN_STACK_ORDER, K as partUnionSchema, L as isMediaAssetVariantKind, M as variantBaseEntityIds, N as isJsonObject, O as assembleScriptText, P as createEntityId, Q as solveVideoDocument, R as buildInitialVideoDocument, S as EntityTimelineProjectionError, T as assembleCaptionContent, U as VideoDocumentValidationError, V as fromVideoDocument, W as assertValidVideoDocument, X as findLaneTrack, Y as ensureLaneTrack, Z as laneTrackId, _ as assertFieldChanges, _t as recordEntries, a as applyEntityTimelineProjection, at as resolveSpeechOverlapByShiftingVideos, b as EntityProjectionGraph, bt as bytesToBase64, c as writeVideoDocumentToDraft, ct as isEmptyVideoClip, d as LoroEntityDocument, dt as DEFAULT_UNIT_TIME_MS, et as arrangeMainTrackSeamlessly, f as LoroEntityDraft, ft as ENTITY_TIMELINE_PROJECTION_SCHEMA_VERSION, g as applyFieldChanges, gt as partUnionToDraft, h as equalJson, ht as speedOf, i as MirrorVideoDocumentAdapter, it as resolveAllSpeechOverlaps, j as updateEntityFields, k as findComposedAudioScript, l as readVideoDocumentFromDraft, lt as partDurationMs, m as entityOrderGroups, mt as effectiveVideoClipDurationMs, n as createPlainMemoryAdapter, nt as reassignSpeechesToVideoClipsByTime, o as createMirrorVideoDocument, ot as syncAggregatedClipsTimePosition, p as readEntityDocument, pt as VIDEO_DOCUMENT_SCHEMA_VERSION, q as videoDocumentSchema, r as generatePartId, rt as recalculateTimelineDuration, s as createMirrorVideoDocumentAdapter, st as TIMELINE_SKELETON_DURATION_MS, t as PlainMemoryAdapter, tt as fillMainTrackTimeGaps, u as LORO_ENTITY_SCHEMA, ut as safeDurationMs, v as resolveFieldPath, vt as videoDocumentMirrorSchema, w as ScriptCompositionError, x as resolveEntityTimelineLayout, y as projectEntityTimeline, yt as base64ToBytes, z as buildSpeechHostMap } from "./document-BSAUud6c.js";
+import { $ as partUnionSchema, A as decodeEntityRelationRows, B as isJsonObject, C as applyFieldChanges, Ct as recordEntries, D as EntityProjectionGraph, E as projectEntityTimeline, Et as bytesToBase64, F as assembleScriptText, G as buildInitialVideoDocument, H as createRelationId, I as findComposedAudioScript, J as fromVideoDocument, K as buildSpeechHostMap, L as selectAudioScriptSegment, M as assembleCaptionContent, N as assembleEntityContent, O as resolveEntityTimelineLayout, P as assemblePhoneticScriptContent, Q as validateVideoDocument, R as updateEntityFields, S as equalJson, St as partUnionToDraft, T as resolveFieldPath, Tt as base64ToBytes, U as hasSequence, V as createEntityId, W as isMediaAssetVariantKind, X as VideoDocumentValidationError, Y as toVideoDocument, Z as assertValidVideoDocument, _ as audioScriptAssetOf, _t as partDurationMs, a as createMirrorVideoDocument, at as laneTrackId, b as phoneticScriptAssetOf, bt as effectiveVideoClipDurationMs, c as DocumentMutationGuard, ct as arrangeMainTrackSeamlessly, d as LoroEntityDraft, dt as recalculateTimelineDuration, et as videoDocumentSchema, f as readEntityDocument, ft as resolveAllSpeechOverlaps, g as audioScriptAssetHash, gt as isEmptyVideoClip, h as audioScriptAssetFields, ht as TIMELINE_SKELETON_DURATION_MS, i as MirrorVideoDocumentAdapter, it as hasResolvedPlacement, j as ScriptCompositionError, k as EntityTimelineProjectionError, l as LORO_ENTITY_SCHEMA, lt as fillMainTrackTimeGaps, m as audioScriptAssetContent, mt as syncAggregatedClipsTimePosition, n as createPlainMemoryAdapter, nt as ensureLaneTrack, o as createMirrorVideoDocumentAdapter, ot as solveVideoDocument, p as entityOrderGroups, pt as resolveSpeechOverlapByShiftingVideos, q as derivePositionFromAbs, r as generatePartId, rt as findLaneTrack, s as readVideoDocumentFromDraft, st as cascadeAfterVideoClipChanges, t as PlainMemoryAdapter, tt as LANE_KINDS_IN_STACK_ORDER, u as LoroEntityDocument, ut as reassignSpeechesToVideoClipsByTime, v as phoneticScriptAssetContent, vt as safeDurationMs, w as assertFieldChanges, wt as videoDocumentMirrorSchema, x as scriptSourceAssetOf, xt as speedOf, y as phoneticScriptAssetHash, yt as DEFAULT_UNIT_TIME_MS, z as variantBaseEntityIds } from "./document-yPiwEmkJ.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;
@@ -226,7 +221,8 @@ function compileEntityRows(snapshot, rows, validate) {
 }
 /** Compile an edit on an existing peer, retaining its native local undo history. */
 function applyEntityRows(editor, rows) {
-	const before = editor.snapshot().rows;
+	const baseline = editor.snapshot();
+	const before = baseline.rows;
 	const oldEntities = new Map(before.entities.map((row) => [row.entityId, row]));
 	const newEntities = new Map(rows.entities.map((row) => [row.entityId, row]));
 	const oldRelations = new Map(before.relations.map((row) => [row.relationId, row]));
@@ -242,10 +238,16 @@ function applyEntityRows(editor, rows) {
 					if (!equalJson(row.metadata, next.metadata) || !equalJson(row.trace, next.trace)) draft.patchRelation(row.relationId, next.metadata, next.trace);
 				}
 			}
+			let attached = baseline.project.audioScriptEntityId !== void 0;
 			for (const row of rows.entities) {
 				const previous = oldEntities.get(row.entityId);
-				if (!previous) draft.create(row);
-				else {
+				if (!previous) {
+					draft.create(row);
+					if (!attached && row.entityKind === "audio-script") {
+						draft.attach("audioScriptEntityId", String(row.entityId));
+						attached = true;
+					}
+				} else {
 					if (previous.entityKind !== row.entityKind) throw new Error("Entity kind cannot change");
 					if (!equalJson(previous.payload, row.payload)) draft.replaceOwned(row.entityId, row.payload);
 				}
@@ -288,66 +290,59 @@ const roleOrder$1 = {
 /**
 * MEngine editor policy, not a cardinality restriction on the general-purpose DSL.
 *
-* Media variants share one entity identity with their Asset: every
-* Image/Video/Audio/Voice Entity must carry its own external locator, every
-* external asset id has exactly one claimant, and no media variant may be
-* bound through a legacy `physical-asset` Relation. Dual-entity media graphs
-* are rejected, not migrated. Caption composes AudioScript text and may associate with a physical text Asset.
+* Resources live on Asset entities and are reached through `from-asset`: no
+* other entity carries a locator, one Asset claims each `(system, key)` pair,
+* and media reaches at most one Asset. Media whose bytes are not named through
+* that Relation is rejected rather than guessed at.
 */
 function assertCanonicalEditorResources(rows) {
 	if (rows.entities.filter((row) => row.entityKind === "timeline").length > 1) throw new EntityTimelineProjectionError("Editor requires exactly one Timeline");
 	for (const role of Object.keys(roleOrder$1)) if (rows.entities.filter((row) => row.entityKind === "track" && row.payload.role === role).length > 1) throw new EntityTimelineProjectionError(`Editor has multiple ${role} Tracks`);
 	const identityByAssetKey = /* @__PURE__ */ new Map();
-	const kinds = new Map(rows.entities.map((row) => [String(row.entityId), row.entityKind]));
 	for (const entity of rows.entities) {
-		if (isMediaAssetVariantKind(entity.entityKind) && memotaLocator(entity.payload.external) === void 0) throw new EntityTimelineProjectionError(`Media Entity ${entity.entityId} must carry its own Asset external identity`);
-		if (entity.entityKind !== "asset" && !isMediaAssetVariantKind(entity.entityKind)) continue;
-		const external = entity.payload.external;
-		if (!isJsonObject(external) || external.system !== "memota" && external.system !== "memota-speech" || typeof external.key !== "string") continue;
-		const key = JSON.stringify([external.system, external.key]);
-		const previous = identityByAssetKey.get(key);
-		if (previous !== void 0 && previous !== entity.entityId) throw new EntityTimelineProjectionError(`Duplicate Asset for ${key}; reuse ${previous}`);
-		identityByAssetKey.set(key, entity.entityId);
+		if (entity.entityKind === "asset") {
+			const locator = memotaLocator(entity.payload);
+			if (locator === void 0) throw new EntityTimelineProjectionError(`Asset ${entity.entityId} must state where its bytes live`);
+			const key = JSON.stringify([locator.system, locator.key]);
+			const previous = identityByAssetKey.get(key);
+			if (previous !== void 0 && previous !== entity.entityId) throw new EntityTimelineProjectionError(`Duplicate Asset for ${key}; reuse ${previous}`);
+			identityByAssetKey.set(key, entity.entityId);
+			continue;
+		}
+		if (memotaLocator(entity.payload) !== void 0) throw new EntityTimelineProjectionError(`Entity ${entity.entityId} must not carry a locator; link its Asset with from-asset`);
 	}
-	for (const relation of rows.relations) {
-		if (relation.relationKind !== "physical-asset") continue;
-		const mediaEndpoint = [relation.endpoint0EntityId, relation.endpoint1EntityId].find((endpoint) => isMediaAssetVariantKind(kinds.get(String(endpoint)) ?? ""));
-		if (mediaEndpoint !== void 0) throw new EntityTimelineProjectionError(`Cannot bind media Entity ${mediaEndpoint} through physical-asset Relation ${relation.relationId}; media owns its Asset identity directly`);
+	for (const entity of rows.entities) {
+		if (!isMediaAssetVariantKind(entity.entityKind)) continue;
+		if (assetIdsOf(rows, entity.entityId).length !== 1) throw new EntityTimelineProjectionError(`Media Entity ${entity.entityId} requires exactly one from-asset Asset`);
 	}
 }
+/** The Asset ids one entity reaches, in row order. */
+function assetIdsOf(rows, entityId) {
+	const assets = new Set(rows.entities.filter((row) => row.entityKind === "asset").map((row) => String(row.entityId)));
+	return rows.relations.filter((relation) => relation.relationKind === "from-asset").map((relation) => String(relation.endpoint0EntityId) === entityId ? String(relation.endpoint1EntityId) : String(relation.endpoint1EntityId) === entityId ? String(relation.endpoint0EntityId) : void 0).filter((id) => id !== void 0 && assets.has(id));
+}
 /**
 * Commit-transition policy shared by the editor, the HTTP commit boundary, the
 * host tool, and the entity stores. It compares the authoritative before and
-* after rows of one CAS commit and enforces the single-identity write rules
-* on the complete after state, with no exemption for historical graphs:
+* after rows of one CAS commit and enforces the resource rules on the complete
+* after state, with no exemption for historical graphs:
 *
-* 1. every Image/Video/Audio/Voice Entity carries its own Asset `external`
-*    identity;
-* 2. no `physical-asset` Relation may bind a media variant;
-* 3. a self-carried media identity is immutable — it cannot be rewritten to
-*    another asset id.
+* 1. every media Entity reaches exactly one Asset through `from-asset`;
+* 2. no entity other than an Asset carries a locator;
+* 3. an Asset's locator is immutable — pointing it at other bytes would
+*    silently rewrite every entity already made from it.
 *
-* Dual-entity media graphs are rejected instead of being migrated or merged
-* implicitly. Deleting media is explicit and allowed.
+* Deleting media is explicit and allowed.
 */
 function assertMediaAssetWritePolicy(before, after) {
 	const beforeEntities = new Map(before.entities.map((row) => [String(row.entityId), row]));
-	const afterKinds = new Map(after.entities.map((row) => [String(row.entityId), row.entityKind]));
+	assertCanonicalEditorResources(after);
 	for (const row of after.entities) {
-		if (!isMediaAssetVariantKind(row.entityKind)) continue;
-		if (memotaLocator(row.payload.external) === void 0) throw new EntityTimelineProjectionError(`Media Entity ${row.entityId} must carry its own Asset external identity`);
-	}
-	for (const relation of after.relations) {
-		if (relation.relationKind !== "physical-asset") continue;
-		const mediaEndpoint = [relation.endpoint0EntityId, relation.endpoint1EntityId].find((endpoint) => isMediaAssetVariantKind(afterKinds.get(String(endpoint)) ?? ""));
-		if (mediaEndpoint !== void 0) throw new EntityTimelineProjectionError(`Cannot bind media Entity ${mediaEndpoint} through physical-asset Relation ${relation.relationId}; media owns its Asset identity directly`);
-	}
-	for (const row of after.entities) {
-		if (!isMediaAssetVariantKind(row.entityKind)) continue;
-		const priorExternal = memotaLocator(beforeEntities.get(String(row.entityId))?.payload.external);
-		if (priorExternal === void 0) continue;
-		const nextExternal = memotaLocator(row.payload.external);
-		if (nextExternal !== void 0 && (nextExternal.system !== priorExternal.system || nextExternal.key !== priorExternal.key)) throw new EntityTimelineProjectionError(`Media Entity ${row.entityId} cannot rewrite its Asset external identity; create a new Entity instead`);
+		if (row.entityKind !== "asset") continue;
+		const prior = memotaLocator(beforeEntities.get(String(row.entityId))?.payload);
+		if (prior === void 0) continue;
+		const next = memotaLocator(row.payload);
+		if (next !== void 0 && (next.system !== prior.system || next.key !== prior.key)) throw new EntityTimelineProjectionError(`Asset ${row.entityId} cannot be pointed at other bytes; create a new Asset instead`);
 	}
 }
 function memotaLocator(value) {
@@ -362,23 +357,14 @@ function memotaLocator(value) {
 * explicit project attachment, multiple candidates are ambiguous. Existing
 * content IDs are reused here; Loro editing advances their immutable versions.
 */
-function ensureDocumentAudioScript(entities, idFactory, selectedEntityId) {
+function ensureDocumentAudioScript(entities, selectedEntityId) {
 	if (selectedEntityId != null) {
 		if (!entities.some((row) => row.entityKind === "audio-script" && row.entityId === selectedEntityId)) throw new EntityTimelineProjectionError(`Selected AudioScript ${selectedEntityId} does not exist`);
 		return selectedEntityId;
 	}
 	const scripts = entities.filter((row) => row.entityKind === "audio-script");
 	if (scripts.length > 1) throw new EntityTimelineProjectionError("Select an AudioScript for the editor panel when multiple scripts exist");
-	const existing = scripts[0];
-	if (existing !== void 0) return existing.entityId;
-	const id = createEntityId(idFactory("entity"));
-	if (entities.some((row) => row.entityId === id)) throw new Error(`Duplicate entity id ${id}`);
-	entities.push({
-		entityId: id,
-		entityKind: "audio-script",
-		payload: { segments: [] }
-	});
-	return id;
+	return scripts[0]?.entityId ?? null;
 }
 /** Add only missing editor structure; existing identities and owned settings are never replaced. */
 function ensureEditorFoundation(initial, idFactory = (prefix) => `${prefix}_${globalThis.crypto.randomUUID()}`, timelinePayload = {}, selectedAudioScriptEntityId) {
@@ -432,7 +418,7 @@ function ensureEditorFoundation(initial, idFactory = (prefix) => `${prefix}_${gl
 		}
 		trackEntityIds[role] = track.entityId;
 	}
-	const audioScriptEntityId = ensureDocumentAudioScript(entities, idFactory, selectedAudioScriptEntityId);
+	const audioScriptEntityId = ensureDocumentAudioScript(entities, selectedAudioScriptEntityId);
 	return {
 		rows: {
 			entities,
@@ -500,15 +486,16 @@ function parseWireState(value, expectedDocId) {
 	if (value.doc_id !== expectedDocId) throw new Error(`Entity-state response doc_id mismatch: expected "${expectedDocId}"`);
 	const rows = parseWireRows(value.rows);
 	decodeEntityRelationRows(rows, numericMarkerValidation$1);
-	if (typeof value.audio_script_entity_id !== "string") throw new Error("Document AudioScript is not initialized");
+	const attached = value.audio_script_entity_id;
+	if (attached !== null && typeof attached !== "string") throw new Error("Invalid document AudioScript identity");
 	if (typeof value.loro_snapshot !== "string") throw new Error("Missing causal Loro snapshot");
 	const state = {
 		revision: value.revision,
 		loroSnapshot: value.loro_snapshot,
 		rows,
-		audioScriptEntityId: value.audio_script_entity_id
+		audioScriptEntityId: attached
 	};
-	readDocumentAudioScript(state);
+	if (attached !== null) readDocumentAudioScript(state);
 	return state;
 }
 function parseWireRows(value) {
@@ -571,12 +558,10 @@ const numericCoordinates = { compareMarkerPoints: (_marker, _range, left, right)
 * Import at the editor boundary, not at asset generation time. Existing
 * provenance is retained.
 *
-* A media variant is a logical facet of its Asset and shares one entity
-* identity: the import mints exactly one entity of the media kind that carries
-* the external locator itself, and deduplicates only against existing variants
-* that already carry the same `(system, key)`. Legacy dual-entity graphs
-* (`asset` row plus a `physical-asset` binding) are not reused and are
-* rejected by the canonical resource policy instead of being migrated.
+* The bytes are named once, on an Asset entity, and the media entity reaches
+* them through a `from-asset` Relation. Re-importing the same `(system, key)`
+* reuses that Asset and the media already made from it, so one stored resource
+* is never copied into several rows.
 */
 function importMediaAsset(initial, fact, idFactory = (prefix) => `${prefix}_${globalThis.crypto.randomUUID()}`) {
 	if (!fact.assetId || fact.assetId.trim() !== fact.assetId) throw new Error("Expected an asset id");
@@ -584,60 +569,60 @@ 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 existing = entities.filter((row) => {
-		const external = row.payload.external;
-		return isMediaAssetVariantKind(row.entityKind) && isJsonObject(external) && external.system === system && external.key === fact.assetId;
-	});
-	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);
-		replaceEntity$1(entities, variant.entityId, variant);
+	const system = fact.kind === "voiceover" ? "memota-speech" : "memota";
+	const entityKind = fact.kind;
+	const timbre = fact.kind === "voiceover" ? fact.voice : void 0;
+	const durationMs = fact.kind === "image" ? null : fact.durationMs;
+	const asset = ensureAsset(entities, {
+		system,
+		key: fact.assetId,
+		storageKey: fact.storageKey
+	}, idFactory);
+	const madeFromAsset = entities.filter((row) => row.entityId !== asset.entityId && assetIdOf(relations, row.entityId) === asset.entityId);
+	if (madeFromAsset.length > 1) throw new Error(`Duplicate media identities for ${fact.assetId}; reuse ${madeFromAsset[0].entityId}`);
+	const existing = madeFromAsset[0];
+	if (existing !== void 0) {
+		if (existing.entityKind !== entityKind || existing.payload.durationMs !== durationMs) throw new Error(`Media facts conflict with existing identity for ${fact.assetId}`);
+		const voiceEntityId = bindVoiceTimbre(entities, relations, existing.entityId, timbre, idFactory);
 		return {
 			rows: {
 				entities,
 				relations
 			},
-			contentEntityId: variant.entityId
+			contentEntityId: existing.entityId,
+			assetEntityId: asset.entityId,
+			...voiceEntityId
 		};
 	}
 	const entityId = createEntityId(idFactory("entity"));
 	if (entities.some((row) => row.entityId === entityId)) throw new Error(`Duplicate entity id ${entityId}`);
-	const variant = {
+	entities.push({
 		entityId,
-		entityKind: fact.kind,
-		payload: {
-			extent: fact.kind === "image" ? {
-				kind: "unbounded",
-				start: 0
-			} : {
-				kind: "bounded",
-				start: 0,
-				end: fact.durationMs
-			},
-			sampling: fact.kind === "image" ? "constant" : "native",
-			coordinateSpace: "milliseconds",
-			external: {
-				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 }
-			} } : {}
-		}
-	};
-	entities.push(variant);
+		entityKind,
+		payload: { durationMs }
+	});
+	relations.push(assetLink(entityId, asset.entityId, idFactory));
+	if (fact.kind === "voiceover" && fact.phoneticScriptEntityId !== void 0) {
+		const phonetic = entities.find((row) => String(row.entityId) === fact.phoneticScriptEntityId);
+		if (phonetic?.entityKind !== "phonetic-script") throw new Error(`Voiceover ${fact.assetId} requires the PhoneticScript it was spoken from`);
+		relations.push({
+			relationId: createRelationId(idFactory("relation")),
+			relationKind: "phonetic-script-render",
+			endpoint0EntityId: entityId,
+			endpoint1EntityId: phonetic.entityId,
+			metadata: {},
+			trace: {}
+		});
+	}
+	const voiceEntityId = bindVoiceTimbre(entities, relations, entityId, timbre, idFactory);
 	const rows = {
 		entities,
 		relations
@@ -646,33 +631,102 @@ function importMediaAsset(initial, fact, idFactory = (prefix) => `${prefix}_${gl
 	assertCanonicalEditorResources(rows);
 	return {
 		rows,
-		contentEntityId: entityId
+		contentEntityId: entityId,
+		assetEntityId: asset.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,
+/** One Asset per `(system, key)`: the bytes are named in exactly one row. */
+function ensureAsset(entities, locator, idFactory) {
+	const found = entities.find((row) => row.entityKind === "asset" && row.payload.system === locator.system && row.payload.key === locator.key);
+	if (found !== void 0) {
+		if (locator.storageKey === void 0 || found.payload.storageKey === locator.storageKey) return found;
+		if (found.payload.storageKey !== void 0) throw new Error(`Media facts conflict with existing storage key for ${locator.key}`);
+		const filled = {
+			...found,
 			payload: {
-				...row.payload,
-				storageKey: fact.storageKey
+				...found.payload,
+				storageKey: locator.storageKey
 			}
 		};
+		replaceEntity$1(entities, found.entityId, filled);
+		return filled;
 	}
-	return row;
+	const asset = {
+		entityId: createEntityId(idFactory("entity")),
+		entityKind: "asset",
+		payload: {
+			system: locator.system,
+			key: locator.key,
+			...locator.storageKey === void 0 ? {} : { storageKey: locator.storageKey }
+		}
+	};
+	entities.push(asset);
+	return asset;
+}
+function assetLink(entityId, assetEntityId, idFactory) {
+	return {
+		relationId: createRelationId(idFactory("relation")),
+		relationKind: "from-asset",
+		endpoint0EntityId: createEntityId(entityId),
+		endpoint1EntityId: createEntityId(assetEntityId),
+		metadata: {},
+		trace: {}
+	};
+}
+function assetIdOf(relations, entityId) {
+	const link = relations.find((relation) => relation.relationKind === "from-asset" && (relation.endpoint0EntityId === entityId || relation.endpoint1EntityId === entityId));
+	if (link === void 0) return void 0;
+	return String(link.endpoint0EntityId === entityId ? link.endpoint1EntityId : link.endpoint0EntityId);
+}
+/**
+* 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 {};
+	}
+	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 +1262,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, "voiceover");
 			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 +1299,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 +1318,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)
@@ -1383,13 +1438,7 @@ var EntityTimelineEditor = class {
 				entityId: input.captionEntityId === void 0 ? this.mintEntityId(draft) : requireAvailableEntityId(draft, input.captionEntityId),
 				entityKind: "caption",
 				payload: {
-					extent: {
-						kind: "bounded",
-						start: 0,
-						end: durationMs
-					},
-					sampling: "native",
-					coordinateSpace: "milliseconds",
+					durationMs,
 					baseEntityIds: captionBaseIds(input.baseEntityIds),
 					selection,
 					...input.style === void 0 ? {} : { style: cloneJsonObject(input.style, "Caption style") }
@@ -1474,23 +1523,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");
@@ -1507,13 +1556,7 @@ var EntityTimelineEditor = class {
 					entityId: this.mintEntityId(draft),
 					entityKind: "caption",
 					payload: {
-						extent: {
-							kind: "bounded",
-							start: 0,
-							end: durationMs
-						},
-						sampling: "native",
-						coordinateSpace: "milliseconds",
+						durationMs,
 						baseEntityIds,
 						selection,
 						...caption.style === void 0 ? {} : { style: cloneJsonObject(caption.style, "Caption style") }
@@ -1521,7 +1564,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 +1621,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 +1630,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,11 +2042,19 @@ 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]);
-	const documentAudioScriptEntityId = ensureDocumentAudioScript(entities, idFactory);
+	const documentAudioScriptEntityId = ensureDocumentAudioScript(entities) ?? (() => {
+		const id = createEntityId(idFactory("entity"));
+		entities.push({
+			entityId: id,
+			entityKind: "audio-script",
+			payload: { segments: [] }
+		});
+		return String(id);
+	})();
 	const addEntity = (kind, payload, existingId) => {
 		const entityId = createEntityId(existingId ?? idFactory("entity"));
 		if (entities.some((row) => row.entityId === entityId)) fail(`Migration entity identity collision: ${entityId}`);
@@ -2053,7 +2104,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 +2192,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");
@@ -2158,18 +2209,12 @@ function migrateLegacyTimelineToEntities(legacy, assetFacts, initial = {
 					} }
 				};
 				content = addEntity("caption", {
-					extent: {
-						kind: "bounded",
-						start: 0,
-						end: duration
-					},
-					sampling: "native",
-					coordinateSpace: "milliseconds",
+					durationMs: duration,
 					baseEntityIds: [script.entityId],
 					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 +2270,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 +2553,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 +2582,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) {
@@ -2659,13 +2700,7 @@ function prepareCaptionContent(rows, input) {
 		payload: {
 			...previous?.payload,
 			baseEntityIds,
-			extent: previous?.payload.extent ?? {
-				kind: "bounded",
-				start: 0,
-				end: input.durationMs
-			},
-			sampling: previous?.payload.sampling ?? "native",
-			coordinateSpace: previous?.payload.coordinateSpace ?? "milliseconds"
+			durationMs: previous?.payload.durationMs ?? input.durationMs
 		}
 	};
 	const graph = {
@@ -3648,7 +3683,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 +4092,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 +4114,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 +4150,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 +4172,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 +4257,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 +4296,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 +4374,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 +4424,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 +4432,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 +4444,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 +4475,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 +4503,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 +4632,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 +4779,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 +4802,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 +4844,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 +4866,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 +4934,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 +5092,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 +5157,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, base64ToBytes, buildInitialVideoDocument, buildSpeechHostMap, bytesToBase64, cascadeAfterVideoClipChanges, compileEntityRows, createEditSandbox, createMirrorVideoDocument, createMirrorVideoDocumentAdapter, createPlainMemoryAdapter, decodeDocVersionMark, derivePositionFromAbs, effectiveVideoClipDurationMs, encodeDocVersionMark, ensureEditorFoundation, ensureLaneTrack, fillMainTrackTimeGaps, findComposedAudioScript, findLaneTrack, fromVideoDocument, generatePartId, getAt, 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, audioScriptAssetOf, base64ToBytes, buildInitialVideoDocument, buildSpeechHostMap, bytesToBase64, cascadeAfterVideoClipChanges, compileEntityRows, createEditSandbox, createMirrorVideoDocument, createMirrorVideoDocumentAdapter, createPlainMemoryAdapter, decodeDocVersionMark, derivePositionFromAbs, effectiveVideoClipDurationMs, encodeDocVersionMark, ensureEditorFoundation, ensureLaneTrack, fillMainTrackTimeGaps, findComposedAudioScript, findLaneTrack, fromVideoDocument, generatePartId, getAt, hostForAbsMs, importMediaAsset, isEmptyVideoClip, isImplementedSemanticOpKind, isMap, laneTrackId, mainTrackRanges, migrateLegacyTimelineToEntities, partDurationMs, partUnionSchema, phoneticScriptAssetContent, phoneticScriptAssetHash, phoneticScriptAssetOf, prepareCaptionContent, projectEntityTimeline, readDocumentAudioScript, readEntityDocument, readMainTrackItems, readMengineEventStream, readPart, readPartDurationMs, readVideoDocumentFromDraft, reassignSpeechesToVideoClipsByTime, recalculateTimelineDuration, relativePositionForAbs, replayJournal, resolveAllSpeechOverlaps, resolveEntityTimelineLayout, resolveFieldPath, resolveSpeechOverlapByShiftingVideos, safeDurationMs, schemas_exports as schemas, scriptSourceAssetOf, selectAudioScriptSegment, snapshotToPlain, solveVideoDocument, speedOf, syncAggregatedClipsTimePosition, toVideoDocument, validateVideoDocument, videoDocumentMirrorSchema, videoDocumentSchema };