@mengine/medeo-client 2.0.1-alpha.26 → 2.0.1-alpha.28

package/dist/index.js

@@ -1,6 +1,8 @@
-import { $ as assertValidVideoDocument, A as decodeEntityRelationRows, B as updateEntityFields, C as applyFieldChanges, Ct as speedOf, D as EntityProjectionGraph, Dt as base64ToBytes, E as projectEntityTimeline, Et as videoDocumentMirrorSchema, F as assembleEntityContent, G as hasSequence, H as isJsonObject, I as assemblePhoneticScriptContent, J as buildSpeechHostMap, K as isMediaAssetVariantKind, L as assembleScriptText, M as relationsTo, N as ScriptCompositionError, O as resolveEntityTimelineLayout, Ot as bytesToBase64, P as assembleCaptionContent, Q as VideoDocumentValidationError, R as findComposedAudioScript, S as equalJson, St as effectiveVideoClipDurationMs, T as resolveFieldPath, Tt as recordEntries, U as createEntityId, V as variantBaseEntityIds, W as createRelationId, X as fromVideoDocument, Y as derivePositionFromAbs, Z as toVideoDocument, _ as audioScriptAssetOf, _t as TIMELINE_SKELETON_DURATION_MS, a as createMirrorVideoDocument, at as findLaneTrack, b as phoneticScriptAssetOf, bt as safeDurationMs, c as DocumentMutationGuard, ct as solveVideoDocument, d as LoroEntityDraft, dt as fillMainTrackTimeGaps, et as validateVideoDocument, f as readEntityDocument, ft as reassignSpeechesToVideoClipsByTime, g as audioScriptAssetHash, gt as syncAggregatedClipsTimePosition, h as audioScriptAssetFields, ht as resolveSpeechOverlapByShiftingVideos, i as MirrorVideoDocumentAdapter, it as ensureLaneTrack, j as relationsFrom, k as EntityTimelineProjectionError, l as LORO_ENTITY_SCHEMA, lt as cascadeAfterVideoClipChanges, m as audioScriptAssetContent, mt as resolveAllSpeechOverlaps, n as createPlainMemoryAdapter, nt as videoDocumentSchema, o as createMirrorVideoDocumentAdapter, ot as hasResolvedPlacement, p as entityOrderGroups, pt as recalculateTimelineDuration, q as buildInitialVideoDocument, r as generatePartId, rt as LANE_KINDS_IN_STACK_ORDER, s as readVideoDocumentFromDraft, st as laneTrackId, t as PlainMemoryAdapter, tt as partUnionSchema, u as LoroEntityDocument, ut as arrangeMainTrackSeamlessly, v as phoneticScriptAssetContent, vt as isEmptyVideoClip, w as assertFieldChanges, wt as partUnionToDraft, x as scriptSourceAssetOf, xt as DEFAULT_UNIT_TIME_MS, y as phoneticScriptAssetHash, yt as partDurationMs, z as selectAudioScriptSegment } from "./document-Ct11SMBS.js";
+import { $ as fromVideoDocument, A as resolveEntityTimelineLayout, At as base64ToBytes, B as assembleScriptText, C as canonicalJson, Ct as safeDurationMs, D as resolveFieldPath, Dt as partUnionToDraft, E as assertFieldChanges, Et as speedOf, F as relationsTo, G as isJsonObject, H as selectAudioScriptSegment, I as ScriptCompositionError, J as hasSequence, K as createEntityId, L as assembleCaptionContent, M as validateEntityRelationTransition, N as decodeEntityRelationRows, O as projectEntityTimeline, Ot as recordEntries, P as relationsFrom, Q as derivePositionFromAbs, R as assembleEntityContent, S as scriptSourceAssetOf, St as partDurationMs, T as applyFieldChanges, Tt as effectiveVideoClipDurationMs, U as updateEntityFields, V as findComposedAudioScript, W as variantBaseEntityIds, X as buildInitialVideoDocument, Y as isMediaAssetVariantKind, Z as buildSpeechHostMap, _ as audioScriptAssetHash, _t as resolveAllSpeechOverlaps, a as createMirrorVideoDocument, at as videoDocumentSchema, b as phoneticScriptAssetHash, bt as TIMELINE_SKELETON_DURATION_MS, c as DocumentMutationGuard, ct as findLaneTrack, d as LoroEntityDraft, dt as solveVideoDocument, et as toVideoDocument, f as readEntityDocument, ft as cascadeAfterVideoClipChanges, g as audioScriptAssetFields, gt as recalculateTimelineDuration, h as audioScriptAssetContent, ht as reassignSpeechesToVideoClipsByTime, i as MirrorVideoDocumentAdapter, it as partUnionSchema, j as EntityTimelineProjectionError, jt as bytesToBase64, k as EntityProjectionGraph, kt as videoDocumentMirrorSchema, l as LORO_ENTITY_SCHEMA, lt as hasResolvedPlacement, m as entityOrderGroups, mt as fillMainTrackTimeGaps, n as createPlainMemoryAdapter, nt as assertValidVideoDocument, o as createMirrorVideoDocumentAdapter, ot as LANE_KINDS_IN_STACK_ORDER, p as readEntityRelationRecords, pt as arrangeMainTrackSeamlessly, q as createRelationId, r as generatePartId, rt as validateVideoDocument, s as readVideoDocumentFromDraft, st as ensureLaneTrack, t as PlainMemoryAdapter, tt as VideoDocumentValidationError, u as LoroEntityDocument, ut as laneTrackId, v as audioScriptAssetOf, vt as resolveSpeechOverlapByShiftingVideos, w as equalJson, wt as DEFAULT_UNIT_TIME_MS, x as phoneticScriptAssetOf, xt as isEmptyVideoClip, y as phoneticScriptAssetContent, yt as syncAggregatedClipsTimePosition, z as assemblePhoneticScriptContent } from "./document-DcpvSvQK.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, UndoManager, VersionVector } from "loro-crdt";
+import { LoroDoc, LoroMap, UndoManager, VersionVector } from "loro-crdt";
+import { sha256 } from "@noble/hashes/sha2.js";
+import { bytesToHex } from "@noble/hashes/utils.js";
 import { ClientServerSynchronizer, DocManager } from "@mengine/sync";
 import { DisposableSet, EventBus, Task } from "@mengine/utils";
 import { BaseDocStorage, DummyConnection } from "@mengine/storage";
@@ -214,20 +216,36 @@ function findSseFrameBoundary(buffer) {
 //#endregion
 //#region src/entity-crdt/compile-rows.ts
 /** Lower a detached ordinary-object edit against its actual causal Loro baseline. */
-function compileEntityRows(snapshot, rows, validate) {
+function compileEntityRows(snapshot, rows, validate, options = {}) {
 	const doc = new LoroDoc();
 	doc.import(snapshot);
-	return applyEntityRows(new LoroEntityDocument(doc, validate), rows);
+	return applyEntityRows(new LoroEntityDocument(doc, validate), rows, options);
+}
+/** Publish final rows as imported causal operations, outside the caller's local undo history. */
+function publishEntityRows(editor, rows, options = {}) {
+	const from = editor.doc.oplogVersion();
+	const compiled = compileEntityRows(editor.doc.export({ mode: "snapshot" }), rows, void 0, options);
+	editor.import(compiled.update);
+	return {
+		update: editor.doc.export({
+			mode: "update",
+			from
+		}),
+		state: editor.snapshot()
+	};
 }
 /** Compile an edit on an existing peer, retaining its native local undo history. */
-function applyEntityRows(editor, rows) {
+function applyEntityRows(editor, rows, options = {}) {
 	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]));
 	const newRelations = new Map(rows.relations.map((row) => [row.relationId, row]));
+	const oldClipContent = new Map(before.relations.filter((row) => row.relationKind === "contain" && oldEntities.get(row.endpoint0EntityId)?.entityKind === "clip").map((row) => [row.endpoint0EntityId, row.relationId]));
+	const newClipContent = new Map(rows.relations.filter((row) => row.relationKind === "contain" && newEntities.get(row.endpoint0EntityId)?.entityKind === "clip").map((row) => [row.endpoint0EntityId, row.relationId]));
 	if (newEntities.size !== rows.entities.length || newRelations.size !== rows.relations.length) throw new Error("Duplicate domain identity");
+	validateEntityRelationTransition(before, rows);
 	return {
 		update: editor.transact((draft) => {
 			for (const row of before.relations) {
@@ -235,7 +253,7 @@ function applyEntityRows(editor, rows) {
 				if (!next) draft.unlink(row.relationId);
 				else {
 					if (next.relationKind !== row.relationKind || next.endpoint0EntityId !== row.endpoint0EntityId || next.endpoint1EntityId !== row.endpoint1EntityId) throw new Error("Relation identity cannot change kind or endpoint positions");
-					if (!equalJson(row.metadata, next.metadata) || !equalJson(row.trace, next.trace)) draft.patchRelation(row.relationId, next.metadata, next.trace);
+					if (!equalJson(row.trace, next.trace)) draft.patchRelationTrace(row.relationId, next.trace);
 				}
 			}
 			let attached = baseline.project.audioScriptEntityId !== void 0;
@@ -253,12 +271,15 @@ function applyEntityRows(editor, rows) {
 				}
 			}
 			for (const row of rows.relations) if (!oldRelations.has(row.relationId)) draft.link(row);
+			for (const [clipId, relationId] of newClipContent) if (oldClipContent.get(clipId) !== relationId) draft.selectClipContent(relationId);
 			const beforeOrder = entityOrderGroups(before), afterOrder = entityOrderGroups(rows);
 			for (const group of new Set([...beforeOrder.keys(), ...afterOrder.keys()])) {
 				const next = afterOrder.get(group) ?? [];
 				if (!equalJson(beforeOrder.get(group) ?? [], next)) draft.order(group, next);
 			}
 			for (const row of before.entities) if (!newEntities.has(row.entityId)) draft.delete(row.entityId);
+			for (const [slot, entityId] of Object.entries(options.projectAttachments ?? {})) draft.attach(slot, entityId);
+			for (const [clipEntityId, phoneticScriptEntityId] of Object.entries(options.phoneticScriptSelections ?? {})) draft.selectPhoneticScript(clipEntityId, phoneticScriptEntityId);
 		}),
 		state: editor.snapshot()
 	};
@@ -432,6 +453,16 @@ function ensureEditorFoundation(initial, idFactory = (prefix) => `${prefix}_${gl
 //#endregion
 //#region src/entity-editor/entity-graph-http-client.ts
 const MENGINE_API_PREFIX = "/api/mengine/v1";
+var EntityGraphRevisionConflictError = class extends MengineHttpRequestError {
+	expectedRevision;
+	currentRevision;
+	constructor(expectedRevision, currentRevision, payload) {
+		super(409, payload);
+		this.expectedRevision = expectedRevision;
+		this.currentRevision = currentRevision;
+		this.name = "EntityGraphRevisionConflictError";
+	}
+};
 /** Browser-safe authenticated Loro client for a document's Entity graph. */
 var EntityGraphHttpClient = class {
 	options;
@@ -448,6 +479,8 @@ var EntityGraphHttpClient = class {
 	}
 	/**
 	* Compile edits against the original causal snapshot and publish native Loro operations.
+	* The base revision is sent as an optimistic precondition, so a stale adoption
+	* fails loudly instead of letting Loro choose between concurrent selections.
 	*
 	* Deletion intent is derived from baseline IDs omitted from `nextRows`, so a
 	* transient create-then-remove never becomes a request to delete unknown
@@ -458,13 +491,17 @@ var EntityGraphHttpClient = class {
 		const next = cloneAndValidateRows(nextRows);
 		assertMediaAssetWritePolicy(baseState.rows, next);
 		const compiled = compileEntityRows(base64ToBytes(baseState.loroSnapshot), next);
-		return this.commitUpdate(bytesToBase64(compiled.update));
+		return this.commitUpdate(bytesToBase64(compiled.update), baseState.revision);
 	}
-	/** Send the same prepared bytes on retry; never recompile an unconfirmed edit. */
-	async commitUpdate(update) {
+	/** Send prepared bytes directly; omit `expectedRevision` for immutable fact publication. */
+	async commitUpdate(update, expectedRevision) {
+		if (expectedRevision !== void 0 && !isNonNegativeSafeInteger(expectedRevision)) throw new Error("expectedRevision must be a nonnegative safe integer");
 		return this.request({
 			method: "POST",
-			body: JSON.stringify({ update })
+			body: JSON.stringify({
+				update,
+				...expectedRevision === void 0 ? {} : { expected_revision: expectedRevision }
+			})
 		});
 	}
 	async request(init) {
@@ -473,10 +510,21 @@ var EntityGraphHttpClient = class {
 			headers: this.transport.headers()
 		});
 		const payload = await safeReadJson(response);
-		if (!response.ok) throw new MengineHttpRequestError(response.status, payload);
+		if (!response.ok) throw parseRevisionConflict(response.status, payload) ?? new MengineHttpRequestError(response.status, payload);
 		return parseWireState(payload, this.options.docId);
 	}
 };
+function parseRevisionConflict(status, value) {
+	if (status !== 409 || !isRecord(value) || !isRecord(value.error) || value.error.code !== "revision_conflict") return;
+	const error = value.error;
+	if (typeof error.message !== "string" || !isNonNegativeSafeInteger(error.expected_revision) || !isNonNegativeSafeInteger(error.current_revision)) return;
+	return new EntityGraphRevisionConflictError(error.expected_revision, error.current_revision, { error: {
+		code: "revision_conflict",
+		message: error.message,
+		expected_revision: error.expected_revision,
+		current_revision: error.current_revision
+	} });
+}
 function parseWireState(value, expectedDocId) {
 	if (!isRecord(value) || typeof value.doc_id !== "string" || !isNonNegativeSafeInteger(value.revision)) throw new Error("Invalid entity-state response envelope");
 	if (value.doc_id !== expectedDocId) throw new Error(`Entity-state response doc_id mismatch: expected "${expectedDocId}"`);
@@ -1228,7 +1276,7 @@ var EntityTimelineEditor = class {
 					}
 				});
 			}
-			this.reconcileVoiceoverCaptions(draft, voiceoverClipEntityId, voiceover.entityId, phonetic.entityId, input.captions);
+			this.reconcileVoiceoverCaptions(draft, voiceoverClipEntityId, phonetic.entityId, input.captions);
 			this.resolveOneVoiceoverOverlap(draft);
 			return {
 				voiceoverClipEntityId,
@@ -1415,7 +1463,7 @@ var EntityTimelineEditor = class {
 		requireComposedAudioScript(draft, phonetic.entityId);
 		return phonetic;
 	}
-	/** Preserve the factual synthesis input, regardless of persisted endpoint positions. */
+	/** Preserve the factual synthesis input as `[rendered Audio, PhoneticScript]`. */
 	ensurePhoneticRender(draft, voiceoverAudioEntityId, phoneticScriptEntityId) {
 		const renders = draft.relations.filter((relation) => relation.relationKind === "derived-from" && (relation.endpoint0EntityId === voiceoverAudioEntityId || relation.endpoint1EntityId === voiceoverAudioEntityId));
 		if (renders.length > 1) throw new Error(`Voiceover "${voiceoverAudioEntityId}" has multiple PhoneticScript render relations`);
@@ -1425,7 +1473,7 @@ var EntityTimelineEditor = class {
 		}
 		draft.relations.push(this.createRelation(draft, "derived-from", voiceoverAudioEntityId, phoneticScriptEntityId));
 	}
-	reconcileVoiceoverCaptions(draft, voiceoverClipEntityId, voiceoverAudioEntityId, phoneticScriptEntityId, captions) {
+	reconcileVoiceoverCaptions(draft, voiceoverClipEntityId, 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");
@@ -1450,10 +1498,6 @@ var EntityTimelineEditor = class {
 				};
 				draft.entities.push(content);
 				assertCaptionScript(draft, content.entityId, audioScriptEntityId);
-				draft.relations.push(this.createRelation(draft, "caption-alignment", content.entityId, voiceoverAudioEntityId, { alignment: {
-					start: startMs,
-					end: startMs + durationMs
-				} }));
 				this.insertPlacedClipIntoDraft(draft, {
 					clipEntityId: caption.captionClipEntityId,
 					trackEntityId: captionTrack.entityId,
@@ -1500,7 +1544,6 @@ var EntityTimelineEditor = class {
 					...rate === 1 ? {} : { rate }
 				}
 			});
-			this.replaceCaptionAlignment(draft, content.entityId, voiceoverAudioEntityId, startMs, durationMs);
 		}
 	}
 	ensureRoleTrackForClip(draft, clipEntityId, role) {
@@ -1509,14 +1552,6 @@ var EntityTimelineEditor = class {
 		const timeline = requireEntityKind(draft, otherEndpoint(requireOneContain(draft, track.entityId, "contained"), track.entityId), "timeline");
 		return this.ensureRoleTrack(draft, timeline.entityId, role);
 	}
-	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, voiceoverAudioEntityId, { alignment: {
-			start: startMs,
-			end: startMs + durationMs
-		} }));
-	}
 	/**
 	* Remove one placed Caption use. The composed AudioScript outlives the
 	* caption: it may anchor further captions and remains the text owner.
@@ -1912,6 +1947,224 @@ function cloneRows(rows) {
 	};
 }
 //#endregion
+//#region src/entity-editor/revise-audio-script.ts
+/** Revise text as an independent authored document, never as a version-family mutation. */
+function reviseAudioScript(rows, input) {
+	if (typeof input.editId !== "string" || !input.editId.trim()) throw new Error("editId is required");
+	if (!Array.isArray(input.edits) || !input.edits.length) throw new Error("At least one segment edit is required");
+	const edits = /* @__PURE__ */ new Map();
+	for (const edit of input.edits) {
+		if (!edit.segmentId?.trim() || typeof edit.text !== "string" || !edit.text.trim()) throw new Error("Segment text must be nonempty");
+		if (edits.has(edit.segmentId)) throw new Error("Duplicate segment edit");
+		edits.set(edit.segmentId, edit.text);
+	}
+	const signature = hash({
+		...input,
+		captionUsages: input.captionUsages ?? []
+	});
+	const prior = rows.relations.filter((r) => r.relationKind === "derived-from" && r.trace.command === "revise-audio-script" && r.trace.editId === input.editId);
+	if (prior.length && (prior.length !== 1 || prior[0].trace.signature !== signature)) throw new Error("AudioScript edit identity conflict");
+	const source = rows.entities.find((row) => row.entityId === input.sourceAudioScriptEntityId);
+	if (source?.entityKind !== "audio-script") throw new Error("AudioScript source is missing");
+	assembleScriptText({
+		...source,
+		entityKind: "audio-script"
+	});
+	const payload = structuredClone(source.payload);
+	if (!Array.isArray(payload.segments)) throw new Error("AudioScript must own its segments");
+	const segmentIds = new Set(payload.segments.filter(isJsonObject).map((segment) => segment.segmentId));
+	for (const segmentId of edits.keys()) if (!segmentIds.has(segmentId)) throw new Error(`Unknown segment ${segmentId}`);
+	const changedSegments = /* @__PURE__ */ new Set();
+	payload.segments = payload.segments.map((segment) => {
+		if (segment === null || typeof segment !== "object" || Array.isArray(segment)) throw new Error("Invalid segment");
+		const text = edits.get(String(segment.segmentId)) ?? segment.text;
+		if (text !== segment.text) changedSegments.add(String(segment.segmentId));
+		return {
+			...segment,
+			text
+		};
+	});
+	if (!changedSegments.size) {
+		if (prior.length) throw new Error("AudioScript edit identity conflict");
+		return {
+			rows,
+			audioScriptEntityId: source.entityId,
+			captionUsages: [],
+			changed: false
+		};
+	}
+	delete payload.assetContentHash;
+	const id = hash(input.editId);
+	const audioScriptEntityId = createEntityId(`entity_script_revision_${id}`);
+	const audioScript = {
+		entityId: audioScriptEntityId,
+		entityKind: "audio-script",
+		payload
+	};
+	const provenance = {
+		relationId: createRelationId(`relation_script_revision_${id}`),
+		relationKind: "derived-from",
+		endpoint0EntityId: audioScriptEntityId,
+		endpoint1EntityId: source.entityId,
+		metadata: {},
+		trace: {
+			command: "revise-audio-script",
+			editId: input.editId,
+			signature
+		}
+	};
+	const selectedMarkers = /* @__PURE__ */ new Set();
+	const planCaption = (usage, index, targetAudioScriptEntityId) => {
+		if (selectedMarkers.has(usage.markerEntityId)) throw new Error("Duplicate caption usage");
+		selectedMarkers.add(usage.markerEntityId);
+		const caption = rows.entities.find((row) => row.entityId === usage.captionEntityId);
+		if (caption?.entityKind !== "caption") throw new Error("Caption is missing");
+		const assembled = assembleCaptionContent(rows, caption.entityId);
+		if (assembled.audioScript.entityId !== source.entityId) throw new Error("Caption does not use the source AudioScript");
+		const selection = assembled.caption.payload.selection;
+		if (isJsonObject(selection) && selection.textRange !== void 0 && typeof selection.segmentId === "string" && changedSegments.has(selection.segmentId) && usage.selection === void 0) throw new Error("Changed partial Caption requires an explicit selection");
+		const bases = caption.payload.baseEntityIds;
+		if (!Array.isArray(bases) || !bases.includes(source.entityId)) throw new Error("Caption requires a direct AudioScript base");
+		const clipMarkers = rows.relations.filter((r) => r.relationKind === "marker" && r.endpoint0EntityId === usage.clipEntityId);
+		const clipContents = rows.relations.filter((r) => r.relationKind === "contain" && r.endpoint0EntityId === usage.clipEntityId);
+		const markerOwners = rows.relations.filter((r) => r.relationKind === "marker" && r.endpoint1EntityId === usage.markerEntityId);
+		if (clipMarkers.length !== 1 || clipMarkers[0].endpoint1EntityId !== usage.markerEntityId || markerOwners.length !== 1 || clipContents.length !== 1) throw new Error("Caption usage conflict");
+		const newCaptionId = createEntityId(`entity_caption_revision_${id}_${index}`);
+		return {
+			clone: {
+				...caption,
+				entityId: newCaptionId,
+				payload: {
+					...structuredClone(caption.payload),
+					baseEntityIds: bases.map((base) => base === source.entityId ? targetAudioScriptEntityId : base),
+					...usage.selection === void 0 ? {} : { selection: structuredClone(usage.selection) }
+				}
+			},
+			clipContent: clipContents[0],
+			newCaptionId,
+			relationId: createRelationId(`relation_caption_revision_${id}_${index}`),
+			trace: {
+				command: "revise-audio-script",
+				editId: input.editId,
+				usageIndex: index
+			}
+		};
+	};
+	if (prior.length) {
+		const currentAudioScriptEntityId = prior[0].endpoint0EntityId;
+		if (!equalJson(prior[0], {
+			...provenance,
+			relationId: prior[0].relationId,
+			endpoint0EntityId: currentAudioScriptEntityId
+		})) throw new Error("AudioScript edit identity conflict");
+		const preservedScripts = rows.entities.filter((row) => row.entityId === currentAudioScriptEntityId);
+		const preservedScript = preservedScripts[0]?.entityKind === "audio-script" ? {
+			...preservedScripts[0],
+			payload: Object.fromEntries(Object.entries(preservedScripts[0].payload).filter(([key]) => key !== "assetContentHash"))
+		} : preservedScripts[0];
+		if (preservedScripts.length !== 1 || !equalJson(preservedScript, {
+			...audioScript,
+			entityId: currentAudioScriptEntityId
+		})) throw new Error("AudioScript edit identity conflict");
+		let relations = [...rows.relations];
+		let changed = false;
+		const captionUsages = [];
+		for (const [index, usage] of (input.captionUsages ?? []).entries()) {
+			const plan = planCaption(usage, index, currentAudioScriptEntityId);
+			const preservedCaptions = rows.entities.filter((row) => row.entityId === plan.newCaptionId);
+			if (preservedCaptions.length !== 1 || !equalJson(preservedCaptions[0], plan.clone)) throw new Error("Caption usage conflict after revision");
+			const plannedEdge = {
+				relationId: plan.relationId,
+				relationKind: "contain",
+				endpoint0EntityId: plan.clipContent.endpoint0EntityId,
+				endpoint1EntityId: plan.newCaptionId,
+				metadata: structuredClone(plan.clipContent.metadata),
+				trace: plan.trace
+			};
+			if (plan.clipContent.relationId === plan.relationId) {
+				if (!equalJson(plan.clipContent, plannedEdge)) throw new Error("Caption usage conflict after revision");
+			} else {
+				if (plan.clipContent.endpoint1EntityId !== usage.captionEntityId) throw new Error("Caption usage conflict after revision");
+				relations = relations.filter((row) => row.relationId !== plan.clipContent.relationId);
+				relations.push(plannedEdge);
+				changed = true;
+			}
+			captionUsages.push({
+				clipEntityId: usage.clipEntityId,
+				markerEntityId: usage.markerEntityId,
+				previousCaptionEntityId: usage.captionEntityId,
+				captionEntityId: plan.newCaptionId
+			});
+		}
+		if (!changed) return {
+			rows,
+			audioScriptEntityId: currentAudioScriptEntityId,
+			captionUsages,
+			changed: false
+		};
+		const revised = {
+			entities: rows.entities,
+			relations
+		};
+		decodeAndValidate(rows, revised);
+		return {
+			rows: revised,
+			audioScriptEntityId: currentAudioScriptEntityId,
+			captionUsages,
+			changed: true
+		};
+	}
+	const result = {
+		entities: [...rows.entities, audioScript],
+		relations: [...rows.relations, provenance]
+	};
+	const entities = [...result.entities];
+	let relations = [...result.relations];
+	const captionUsages = [];
+	for (const [index, usage] of (input.captionUsages ?? []).entries()) {
+		const plan = planCaption(usage, index, audioScriptEntityId);
+		if (plan.clipContent.endpoint1EntityId !== usage.captionEntityId) throw new Error("Caption usage conflict");
+		entities.push(plan.clone);
+		assembleCaptionContent({
+			entities,
+			relations
+		}, plan.newCaptionId);
+		relations = relations.filter((r) => r.relationId !== plan.clipContent.relationId);
+		relations.push({
+			relationId: plan.relationId,
+			relationKind: "contain",
+			endpoint0EntityId: plan.clipContent.endpoint0EntityId,
+			endpoint1EntityId: plan.newCaptionId,
+			metadata: structuredClone(plan.clipContent.metadata),
+			trace: plan.trace
+		});
+		captionUsages.push({
+			clipEntityId: usage.clipEntityId,
+			markerEntityId: usage.markerEntityId,
+			previousCaptionEntityId: usage.captionEntityId,
+			captionEntityId: plan.newCaptionId
+		});
+	}
+	const revised = {
+		entities,
+		relations
+	};
+	decodeAndValidate(rows, revised);
+	return {
+		rows: revised,
+		audioScriptEntityId,
+		captionUsages,
+		changed: true
+	};
+}
+function decodeAndValidate(previous, revised) {
+	decodeEntityRelationRows(revised, {});
+	validateEntityRelationTransition(previous, revised);
+}
+function hash(value) {
+	return bytesToHex(sha256(new TextEncoder().encode(canonicalJson(value))));
+}
+//#endregion
 //#region src/entity-editor/legacy-entity-migration.ts
 /** One-time import only. Ordinary editor operations must never reverse-diff a legacy document. */
 function migrateLegacyTimelineToEntities(legacy, assetFacts, initial = {
@@ -2076,10 +2329,6 @@ function migrateLegacyTimelineToEntities(legacy, assetFacts, initial = {
 					selection,
 					...caption.style === void 0 ? {} : { style: toEntityCaptionStyle(caption.style) }
 				});
-				link("caption-alignment", content, voiceover, { alignment: {
-					start: caption.start_ms,
-					end: caption.start_ms + duration
-				} });
 				markerPayload = {
 					inMs: 0,
 					outMs: duration
@@ -2587,6 +2836,147 @@ function selectCaptionText(script, text) {
 	return matches[0];
 }
 //#endregion
+//#region src/entity-crdt/legacy-schema-migration.ts
+const LEGACY_KINDS = new Set([
+	"timeline-track",
+	"track-clip",
+	"clip-marker",
+	"marker-content",
+	"audio-script-marker",
+	"audio-script-source",
+	"generated"
+]);
+function whole(value, label) {
+	if (!Number.isSafeInteger(value) || value < 0) throw new Error(`Legacy SequenceMarker ${label} is invalid`);
+	return value;
+}
+function legacyMarkerPayload(payload, annotation) {
+	if (payload.inMs !== void 0 || payload.outMs !== void 0) return void 0;
+	const keys = canonicalJson(Object.keys(payload).sort());
+	if (!(annotation ? [[
+		"duration",
+		"segmentRanges",
+		"sourceRange"
+	]] : [
+		["duration", "sourceRange"],
+		[
+			"anchorOffset",
+			"duration",
+			"sourceRange"
+		],
+		[
+			"duration",
+			"sourceRange",
+			"targetRange"
+		],
+		[
+			"duration",
+			"sourceRange",
+			"timeRemapping"
+		]
+	]).some((shape) => keys === canonicalJson(shape))) throw new Error("Legacy SequenceMarker has unsupported fields");
+	if (!isJsonObject(payload.sourceRange) || !isJsonObject(payload.duration)) throw new Error("Legacy SequenceMarker ranges are invalid");
+	const inMs = whole(payload.sourceRange.start, "sourceRange.start");
+	const outMs = whole(payload.sourceRange.end, "sourceRange.end");
+	const duration = whole(payload.duration.value, "duration.value");
+	if (payload.duration.mode !== "fixed" || duration === 0 || outMs <= inMs) throw new Error("Legacy SequenceMarker duration is invalid");
+	const rate = (outMs - inMs) / duration;
+	if (!Number.isFinite(rate) || rate <= 0) throw new Error("Legacy SequenceMarker rate is invalid");
+	if (annotation) {
+		if (rate !== 1 || !Array.isArray(payload.segmentRanges)) throw new Error("Legacy AudioScript annotation Marker is invalid");
+		return {
+			inMs,
+			outMs,
+			segmentRanges: payload.segmentRanges
+		};
+	}
+	let startMs = 0;
+	if (payload.anchorOffset !== void 0) startMs = whole(payload.anchorOffset, "anchorOffset");
+	if (payload.targetRange !== void 0) {
+		if (!isJsonObject(payload.targetRange)) throw new Error("Legacy SequenceMarker targetRange is invalid");
+		startMs = whole(payload.targetRange.start, "targetRange.start");
+		const targetEnd = whole(payload.targetRange.end, "targetRange.end");
+		if (targetEnd <= startMs || targetEnd - startMs !== duration) throw new Error("Legacy SequenceMarker targetRange disagrees with duration");
+	}
+	if (payload.timeRemapping !== void 0) {
+		const remapping = payload.timeRemapping;
+		if (!isJsonObject(remapping) || canonicalJson(Object.keys(remapping).sort()) !== canonicalJson([
+			"kind",
+			"mode",
+			"rate"
+		]) || remapping.kind !== "linear" || remapping.mode !== "constant" || typeof remapping.rate !== "number" || !Number.isFinite(remapping.rate) || remapping.rate <= 0) throw new Error("Legacy SequenceMarker timeRemapping is invalid");
+		if (remapping.rate !== rate) throw new Error("Legacy SequenceMarker timeRemapping disagrees with duration");
+	}
+	return {
+		inMs,
+		outMs,
+		startMs,
+		...rate === 1 ? {} : { rate }
+	};
+}
+function relationId(root, kind) {
+	return createRelationId(`relation_${bytesToHex(sha256(new TextEncoder().encode(canonicalJson([root, kind]))))}`);
+}
+function entityRoot(doc, id) {
+	const origins = doc.getMap("medeo").get("origins");
+	if (!(origins instanceof LoroMap)) throw new Error("Missing Loro entity origins");
+	const origin = origins.get(id);
+	return typeof origin === "string" ? origin : id;
+}
+function mappedRow(doc, row, records) {
+	const endpoint0 = entityRoot(doc, row.endpoint0EntityId);
+	const endpoint1 = entityRoot(doc, row.endpoint1EntityId);
+	let kind;
+	let endpoints;
+	if (row.relationKind === "timeline-track" || row.relationKind === "track-clip") {
+		kind = "contain";
+		endpoints = [endpoint0, endpoint1];
+	} else if (row.relationKind === "clip-marker" || row.relationKind === "audio-script-marker") {
+		kind = "marker";
+		endpoints = [endpoint0, endpoint1];
+	} else if (row.relationKind === "audio-script-source" || row.relationKind === "generated") {
+		kind = "derived-from";
+		endpoints = [endpoint0, endpoint1];
+	} else {
+		const owners = records.filter((candidate) => !candidate.deleted && candidate.relationKind === "clip-marker" && entityRoot(doc, candidate.endpoint1EntityId) === endpoint0);
+		if (owners.length !== 1) throw new Error(`Legacy marker-content ${row.relationId} requires exactly one clip-marker owner`);
+		endpoints = [entityRoot(doc, owners[0].endpoint0EntityId), endpoint1];
+		kind = "contain";
+	}
+	return {
+		relationId: relationId(row.relationId, kind),
+		relationKind: kind,
+		endpoint0EntityId: createEntityId(endpoints[0]),
+		endpoint1EntityId: createEntityId(endpoints[1]),
+		metadata: row.metadata,
+		trace: row.trace
+	};
+}
+/** Replace only the four positionally equivalent alpha23 relation kinds. */
+function migrateAlpha23EntityDocument(doc) {
+	if (doc.getMap("medeo").get("schema") !== "medeo.entities.loro.v1") return void 0;
+	const records = readEntityRelationRecords(doc);
+	const legacy = records.filter((row) => !row.deleted && LEGACY_KINDS.has(row.relationKind));
+	if (legacy.length === 0) return void 0;
+	const replacements = legacy.map((row) => mappedRow(doc, row, records));
+	const current = readEntityDocument(doc, true).rows;
+	const markerPayloads = /* @__PURE__ */ new Map();
+	for (const relation of current.relations) {
+		if (relation.relationKind !== "clip-marker" && relation.relationKind !== "audio-script-marker") continue;
+		const marker = current.entities.find((row) => row.entityId === relation.endpoint1EntityId);
+		if (marker?.entityKind !== "sequence-marker") throw new Error(`Legacy ${relation.relationKind} ${relation.relationId} has no SequenceMarker`);
+		const payload = legacyMarkerPayload(marker.payload, relation.relationKind === "audio-script-marker");
+		if (payload !== void 0) markerPayloads.set(marker.entityId, payload);
+	}
+	const occupied = new Set(records.map((row) => String(row.relationId)));
+	for (const row of replacements) if (occupied.has(row.relationId)) throw new Error(`Legacy relation migration ID collision: ${row.relationId}`);
+	return new LoroEntityDocument(doc).transact((draft) => {
+		for (const [markerId, payload] of markerPayloads) draft.replaceOwned(markerId, payload);
+		for (const row of legacy) draft.unlink(row.relationId);
+		for (const row of replacements) draft.link(row);
+	});
+}
+//#endregion
 //#region src/editor/snapshot-utils.ts
 function isMap(value) {
 	return value instanceof Map;
@@ -4998,4 +5388,4 @@ function serverCovers(serverVV, target) {
 	return covers(server, target);
 }
 //#endregion
-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 };
+export { DEFAULT_UNIT_TIME_MS, EntityGraphHttpClient, EntityGraphRevisionConflictError, 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, migrateAlpha23EntityDocument, migrateLegacyTimelineToEntities, partDurationMs, partUnionSchema, phoneticScriptAssetContent, phoneticScriptAssetHash, phoneticScriptAssetOf, prepareCaptionContent, projectEntityTimeline, publishEntityRows, readDocumentAudioScript, readEntityDocument, readEntityRelationRecords, readMainTrackItems, readMengineEventStream, readPart, readPartDurationMs, readVideoDocumentFromDraft, reassignSpeechesToVideoClipsByTime, recalculateTimelineDuration, relativePositionForAbs, replayJournal, resolveAllSpeechOverlaps, resolveEntityTimelineLayout, resolveFieldPath, resolveSpeechOverlapByShiftingVideos, reviseAudioScript, safeDurationMs, schemas_exports as schemas, scriptSourceAssetOf, selectAudioScriptSegment, snapshotToPlain, solveVideoDocument, speedOf, syncAggregatedClipsTimePosition, toVideoDocument, validateVideoDocument, videoDocumentMirrorSchema, videoDocumentSchema };

package/dist/testing.d.ts

@@ -1,4 +1,4 @@
-import { c as MirrorVideoDocumentAdapter, kt as VideoDraft } from "./index-CcIoMxs1.js";
+import { c as MirrorVideoDocumentAdapter, kt as VideoDraft } from "./index-BYv9FPSS.js";
 
 //#region src/testing/in-memory-mengine-server.d.ts
 /**

package/dist/testing.js

@@ -1,4 +1,4 @@
-import { Dt as base64ToBytes, Ot as bytesToBase64, o as createMirrorVideoDocumentAdapter } from "./document-Ct11SMBS.js";
+import { At as base64ToBytes, jt as bytesToBase64, o as createMirrorVideoDocumentAdapter } from "./document-DcpvSvQK.js";
 import { t as classifyUpdate } from "./loro-relay-doc-cJSY-uau.js";
 import { LoroDoc, VersionVector, encodeFrontiers } from "loro-crdt";
 //#region src/testing/in-memory-mengine-server.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mengine/medeo-client",
-  "version": "2.0.1-alpha.26",
+  "version": "2.0.1-alpha.28",
   "license": "UNLICENSED",
   "repository": {
     "type": "git",
@@ -28,9 +28,9 @@
     "immer": "^10.2.0",
     "loro-mirror": "^2.3.3",
     "zod": "^4.4.3",
-    "@mengine/storage": "2.0.1-alpha.26",
-    "@mengine/utils": "2.0.1-alpha.26",
-    "@mengine/sync": "2.0.1-alpha.26"
+    "@mengine/sync": "2.0.1-alpha.28",
+    "@mengine/utils": "2.0.1-alpha.28",
+    "@mengine/storage": "2.0.1-alpha.28"
   },
   "devDependencies": {
     "@types/node": "^25.9.1",