@mengine/medeo-client 1.3.1-alpha.0 → 1.3.1-alpha.2

package/dist/index.js

@@ -1,4 +1,4 @@
-import { $ as videoDocumentMirrorSchema, A as ensureLaneTrack, B as resolveSpeechOverlapByShiftingVideos, C as toVideoDocument, D as partUnionSchema, E as validateVideoDocument, F as arrangeMainTrackSeamlessly, G as safeDurationMs, H as TIMELINE_SKELETON_DURATION_MS, I as fillMainTrackTimeGaps, J as VIDEO_DOCUMENT_SCHEMA_VERSION, K as DEFAULT_UNIT_TIME_MS, L as reassignSpeechesToVideoClipsByTime, M as laneTrackId, N as solveVideoDocument, O as videoDocumentSchema, P as cascadeAfterVideoClipChanges, Q as recordEntries, R as recalculateTimelineDuration, S as fromVideoDocument, T as assertValidVideoDocument, U as isEmptyVideoClip, V as syncAggregatedClipsTimePosition, W as partDurationMs, X as speedOf, Y as effectiveVideoClipDurationMs, Z as partUnionToDraft, _ as hasSequence, a as applyEntityTimelineProjection, b as buildSpeechHostMap, c as writeVideoDocumentToDraft, d as resolveEntityTimelineLayout, et as base64ToBytes, f as EntityTimelineProjectionError, g as createRelationId, h as createEntityId, i as MirrorVideoDocumentAdapter, j as findLaneTrack, k as LANE_KINDS_IN_STACK_ORDER, l as readVideoDocumentFromDraft, m as isJsonObject, n as createPlainMemoryAdapter, o as createMirrorVideoDocument, p as decodeEntityRelationRows, q as ENTITY_TIMELINE_PROJECTION_SCHEMA_VERSION, r as generatePartId, s as createMirrorVideoDocumentAdapter, t as PlainMemoryAdapter, tt as bytesToBase64, u as projectEntityTimeline, v as isMediaAssetVariantKind, w as VideoDocumentValidationError, x as derivePositionFromAbs, y as buildInitialVideoDocument, z as resolveAllSpeechOverlaps } from "./document-Caidonf8.js";
+import { $ as isEmptyVideoClip, A as buildSpeechHostMap, B as ensureLaneTrack, C as variantBaseEntityIds, D as hasSequence, E as createRelationId, F as assertValidVideoDocument, G as arrangeMainTrackSeamlessly, H as laneTrackId, I as validateVideoDocument, J as recalculateTimelineDuration, K as fillMainTrackTimeGaps, L as partUnionSchema, M as fromVideoDocument, N as toVideoDocument, O as isMediaAssetVariantKind, P as VideoDocumentValidationError, Q as TIMELINE_SKELETON_DURATION_MS, R as videoDocumentSchema, S as updateEntityFields, T as createEntityId, U as solveVideoDocument, V as findLaneTrack, W as cascadeAfterVideoClipChanges, X as resolveSpeechOverlapByShiftingVideos, Y as resolveAllSpeechOverlaps, Z as syncAggregatedClipsTimePosition, _ as assembleEntityContent, a as applyEntityTimelineProjection, at as effectiveVideoClipDurationMs, b as findComposedAudioScript, c as writeVideoDocumentToDraft, ct as recordEntries, d as EntityProjectionGraph, dt as bytesToBase64, et as partDurationMs, f as resolveEntityTimelineLayout, g as assembleCaptionContent, h as ScriptCompositionError, i as MirrorVideoDocumentAdapter, it as VIDEO_DOCUMENT_SCHEMA_VERSION, j as derivePositionFromAbs, k as buildInitialVideoDocument, l as readVideoDocumentFromDraft, lt as videoDocumentMirrorSchema, m as decodeEntityRelationRows, n as createPlainMemoryAdapter, nt as DEFAULT_UNIT_TIME_MS, o as createMirrorVideoDocument, ot as speedOf, p as EntityTimelineProjectionError, q as reassignSpeechesToVideoClipsByTime, r as generatePartId, rt as ENTITY_TIMELINE_PROJECTION_SCHEMA_VERSION, s as createMirrorVideoDocumentAdapter, st as partUnionToDraft, t as PlainMemoryAdapter, tt as safeDurationMs, u as projectEntityTimeline, ut as base64ToBytes, v as assemblePhoneticScriptContent, w as isJsonObject, x as selectAudioScriptSegments, y as assembleScriptText, z as LANE_KINDS_IN_STACK_ORDER } from "./document-BLYcbv8E.js";
 import { addSpeechesInputSchema, addVideoClipsInputSchema, adjustBgmVolumeInputSchema, adjustSpeechVolumeInputSchema, adjustVideoClipDurationInputSchema, adjustVideoClipVolumeInputSchema, changeSpeechScriptInputSchema, changeSpeechVoiceInputSchema, deleteBgmInputSchema, deleteSpeechesInputSchema, deleteVideoClipsInputSchema, moveSpeechesInputSchema, moveVideoClipsByAnchorInputSchema, moveVideoClipsInputSchema, replaceVideoClipContentInputSchema, replaceVideoClipSequenceInputSchema, setBgmInputSchema, setCaptionStyleInputSchema, setCaptionVisibilityInputSchema, setVideoClipSpeedShiftInputSchema, t as schemas_exports } from "./schemas.js";
 import { LoroDoc, VersionVector } from "loro-crdt";
 import { ClientServerSynchronizer, DocManager } from "@mengine/sync";
@@ -231,8 +231,7 @@ const roleOrder$1 = {
 * 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 inline text keeps its inline Asset and
-* `physical-asset` binding.
+* are rejected, not migrated. Caption composes AudioScript text and has no physical text Asset.
 */
 function assertCanonicalEditorResources(rows) {
 	if (rows.entities.filter((row) => row.entityKind === "timeline").length > 1) throw new EntityTimelineProjectionError("Editor requires exactly one Timeline");
@@ -263,8 +262,7 @@ function assertCanonicalEditorResources(rows) {
 *
 * 1. every Image/Video/Audio/Voice Entity carries its own Asset `external`
 *    identity;
-* 2. no `physical-asset` Relation may bind a media variant (Caption inline
-*    text keeps its inline Asset and binding);
+* 2. no `physical-asset` Relation may bind a media variant or Caption;
 * 3. a self-carried media identity is immutable — it cannot be rewritten to
 *    another asset id.
 *
@@ -608,6 +606,23 @@ function sameVoice(left, right) {
 }
 //#endregion
 //#region src/entity-editor/entity-timeline-editor.ts
+/**
+* Resolve the AudioScript a PhoneticScript composes. The composition is the
+* required text source: a variant without it has no content and fails here.
+*/
+function requireComposedAudioScript(rows, phoneticScriptEntityId) {
+	return assemblePhoneticScriptContent(rows, phoneticScriptEntityId).audioScript.entityId;
+}
+function captionSelections(selections) {
+	return structuredClone(selections);
+}
+function captionBaseIds(ids) {
+	if (!Array.isArray(ids) || ids.length === 0) throw new Error("Caption requires non-empty baseEntityIds");
+	return ids.map(createEntityId);
+}
+function assertCaptionScript(rows, captionId, scriptId) {
+	if (assembleCaptionContent(rows, captionId).audioScript.entityId !== scriptId) throw new Error("Voiceover Caption must compose the same AudioScript as the PhoneticScript");
+}
 const roleOrder = {
 	caption: 0,
 	video_clip: 1,
@@ -1129,7 +1144,8 @@ var EntityTimelineEditor = class {
 			const imported = importMediaAsset(draft, input.media, this.idFactory);
 			replaceRows(draft, imported.rows);
 			const voice = requireEntityKind(draft, imported.contentEntityId, "voice");
-			const script = this.ensureAudioScript(draft, voice.entityId, input.scriptText);
+			const phonetic = this.requireComposedPhoneticScript(draft, input.phoneticScriptEntityId);
+			this.ensurePhoneticRender(draft, voice.entityId, phonetic.entityId);
 			const speechTrack = this.ensureRoleTrack(draft, input.timelineEntityId, "speech");
 			const existing = draft.entities.find((row) => row.entityId === input.voiceoverClipEntityId);
 			let voiceoverClipEntityId;
@@ -1179,12 +1195,13 @@ var EntityTimelineEditor = class {
 					}
 				});
 			}
-			this.reconcileVoiceoverCaptions(draft, voiceoverClipEntityId, voice.entityId, script.entityId, input.captions);
+			this.reconcileVoiceoverCaptions(draft, voiceoverClipEntityId, voice.entityId, phonetic.entityId, input.captions);
 			this.resolveOneVoiceoverOverlap(draft);
 			return {
 				voiceoverClipEntityId,
 				voiceEntityId: voice.entityId,
-				audioScriptEntityId: script.entityId,
+				phoneticScriptEntityId: phonetic.entityId,
+				audioScriptEntityId: requireComposedAudioScript(draft, phonetic.entityId),
 				captionClipEntityIds: input.captions.map((caption) => caption.captionClipEntityId)
 			};
 		});
@@ -1268,33 +1285,30 @@ var EntityTimelineEditor = class {
 			const track = findRoleTrack(draft, input.timelineEntityId, "caption");
 			if (track === void 0) return;
 			const patch = cloneJsonObject(input.style, "Caption style");
+			const assembled = new EntityProjectionGraph(draft);
 			for (const clip of clipsOnTrack(draft, track.entityId)) {
 				const topology = requireClipTopology(draft, clip.entityId);
 				const caption = requireEntityKind(draft, otherEndpoint(topology.markerContentRelation, topology.marker.entityId), "caption");
-				const prior = caption.payload.style;
+				const prior = assembled.entity(caption.entityId).payload.style;
 				const style = isJsonObject(prior) ? prior : {};
-				replaceEntity(draft, caption.entityId, {
-					...caption,
-					payload: {
-						...caption.payload,
-						style: {
-							...style,
-							...patch
-						}
-					}
-				});
+				for (const updated of updateEntityFields(draft, caption.entityId, { style: {
+					...style,
+					...patch
+				} })) replaceEntity(draft, updated.entityId, updated);
 			}
 		});
 	}
 	/**
-	* Place an independent Caption: its own content entity, inline text Asset,
-	* and Clip with a display Marker. No Voice, provenance, or alignment is
-	* required — the placement describes only this use. Moving or stretching
-	* the returned Clip later changes the Clip/Marker, never the Caption entity.
+	* Place a Caption as a composed variant of an existing AudioScript: the
+	* entity stores baseEntityIds, selection, optional style, and inherent cue-bounded
+	* Sequence. This helper does not copy base text. The Clip and its display Marker describe this use;
+	* moving or stretching the returned Clip later changes the Clip/Marker,
+	* never the Caption entity or the AudioScript.
 	*/
 	insertCaptionClip(input) {
 		return this.transact((draft) => {
 			const durationMs = finitePositive(input.durationMs, "Caption durationMs");
+			const selections = captionSelections(input.selections);
 			const track = this.ensureRoleTrack(draft, input.timelineEntityId, "caption");
 			const content = {
 				entityId: this.mintEntityId(draft),
@@ -1307,20 +1321,13 @@ var EntityTimelineEditor = class {
 					},
 					sampling: "native",
 					coordinateSpace: "milliseconds",
-					text: input.text,
+					baseEntityIds: captionBaseIds(input.baseEntityIds),
+					selections,
 					...input.style === void 0 ? {} : { style: cloneJsonObject(input.style, "Caption style") }
 				}
 			};
-			const asset = {
-				entityId: this.mintEntityId(draft),
-				entityKind: "asset",
-				payload: { inline: {
-					mediaType: "text/plain",
-					text: input.text
-				} }
-			};
-			draft.entities.push(content, asset);
-			draft.relations.push(this.createRelation(draft, "physical-asset", content.entityId, asset.entityId));
+			draft.entities.push(content);
+			assembleCaptionContent(draft, content.entityId);
 			return this.insertPlacedClipIntoDraft(draft, {
 				trackEntityId: track.entityId,
 				contentEntityId: content.entityId,
@@ -1398,34 +1405,24 @@ var EntityTimelineEditor = class {
 		draft.relations.push(this.createRelation(draft, "timeline-track", timeline.entityId, track.entityId));
 		return track;
 	}
-	ensureAudioScript(draft, voiceEntityId, text) {
-		const renders = draft.relations.filter((relation) => relation.relationKind === "audio-script-render" && relation.endpoint0EntityId === voiceEntityId);
-		if (renders.length > 1) throw new Error(`Voice "${voiceEntityId}" has multiple AudioScript relations`);
+	/** The existing pronunciation variant a Voice 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`);
 		if (renders[0] !== void 0) {
-			const script = requireEntityKind(draft, renders[0].endpoint1EntityId, "audio-script");
-			const replacement = {
-				...script,
-				payload: { segments: [{
-					segmentId: "segment-0",
-					text
-				}] }
-			};
-			replaceEntity(draft, script.entityId, replacement);
-			return replacement;
+			if (otherEndpoint(renders[0], voiceEntityId) === phoneticScriptEntityId) return;
+			throw new Error(`Voice "${voiceEntityId}" already has a different PhoneticScript synthesis input`);
 		}
-		const script = {
-			entityId: this.mintEntityId(draft),
-			entityKind: "audio-script",
-			payload: { segments: [{
-				segmentId: "segment-0",
-				text
-			}] }
-		};
-		draft.entities.push(script);
-		draft.relations.push(this.createRelation(draft, "audio-script-render", voiceEntityId, script.entityId));
-		return script;
+		draft.relations.push(this.createRelation(draft, "phonetic-script-render", voiceEntityId, phoneticScriptEntityId));
 	}
-	reconcileVoiceoverCaptions(draft, voiceoverClipEntityId, voiceEntityId, scriptEntityId, captions) {
+	reconcileVoiceoverCaptions(draft, voiceoverClipEntityId, voiceEntityId, 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");
 		const existing = directAnchorChildren(draft, voiceoverClipEntityId).filter((clipId) => clipRole(draft, clipId) === "caption");
@@ -1434,6 +1431,8 @@ var EntityTimelineEditor = class {
 		for (const caption of captions) {
 			const startMs = finiteNonNegative(caption.startMs, "Caption startMs");
 			const durationMs = finitePositive(caption.durationMs, "Caption durationMs");
+			const selections = captionSelections(caption.selections);
+			const baseEntityIds = captionBaseIds(caption.baseEntityIds);
 			if (draft.entities.find((entity) => entity.entityId === caption.captionClipEntityId) === void 0) {
 				const content = {
 					entityId: this.mintEntityId(draft),
@@ -1446,23 +1445,17 @@ var EntityTimelineEditor = class {
 						},
 						sampling: "native",
 						coordinateSpace: "milliseconds",
-						text: caption.text,
+						baseEntityIds,
+						selections,
 						...caption.style === void 0 ? {} : { style: cloneJsonObject(caption.style, "Caption style") }
 					}
 				};
-				const asset = {
-					entityId: this.mintEntityId(draft),
-					entityKind: "asset",
-					payload: { inline: {
-						mediaType: "text/plain",
-						text: caption.text
-					} }
-				};
-				draft.entities.push(content, asset);
-				draft.relations.push(this.createRelation(draft, "physical-asset", content.entityId, asset.entityId), this.createRelation(draft, "caption-alignment", content.entityId, voiceEntityId, { alignment: {
+				draft.entities.push(content);
+				assertCaptionScript(draft, content.entityId, audioScriptEntityId);
+				draft.relations.push(this.createRelation(draft, "caption-alignment", content.entityId, voiceEntityId, { alignment: {
 					start: startMs,
 					end: startMs + durationMs
-				} }), this.createRelation(draft, "caption-provenance", content.entityId, scriptEntityId, { segmentAlignment: [] }));
+				} }));
 				this.insertPlacedClipIntoDraft(draft, {
 					clipEntityId: caption.captionClipEntityId,
 					trackEntityId: captionTrack.entityId,
@@ -1494,27 +1487,12 @@ var EntityTimelineEditor = class {
 				...content,
 				payload: {
 					...content.payload,
-					extent: {
-						kind: "bounded",
-						start: 0,
-						end: durationMs
-					},
-					text: caption.text,
+					baseEntityIds,
+					selections,
 					...Object.keys(style).length === 0 ? {} : { style }
 				}
 			});
-			const asset = requireEntityKind(draft, otherEndpoint(requireOneRelation(draft, content.entityId, "physical-asset"), content.entityId), "asset");
-			if (asset.payload.inline === void 0) throw new Error(`Caption "${caption.captionClipEntityId}" is not inline`);
-			replaceEntity(draft, asset.entityId, {
-				...asset,
-				payload: {
-					...asset.payload,
-					inline: {
-						mediaType: "text/plain",
-						text: caption.text
-					}
-				}
-			});
+			assertCaptionScript(draft, content.entityId, audioScriptEntityId);
 			this.applyClipPlacement(draft, topology.clip.entityId, {
 				kind: "anchored",
 				hostClipEntityId: voiceoverClipEntityId,
@@ -1525,17 +1503,13 @@ var EntityTimelineEditor = class {
 				...placed.marker,
 				payload: {
 					...placed.marker.payload,
-					sourceRange: {
-						start: 0,
-						end: durationMs
-					},
 					duration: {
 						mode: "fixed",
 						value: durationMs
 					}
 				}
 			});
-			this.replaceCaptionSemanticRelations(draft, content.entityId, voiceEntityId, scriptEntityId, startMs, durationMs);
+			this.replaceCaptionAlignment(draft, content.entityId, voiceEntityId, startMs, durationMs);
 		}
 	}
 	ensureRoleTrackForClip(draft, clipEntityId, role) {
@@ -1544,34 +1518,30 @@ var EntityTimelineEditor = class {
 		const timeline = requireEntityKind(draft, otherEndpoint(requireOneRelation(draft, track.entityId, "timeline-track"), track.entityId), "timeline");
 		return this.ensureRoleTrack(draft, timeline.entityId, role);
 	}
-	replaceCaptionSemanticRelations(draft, captionEntityId, voiceEntityId, scriptEntityId, startMs, durationMs) {
-		const removed = new Set(incidentRelations(draft, captionEntityId).filter((relation) => relation.relationKind === "caption-alignment" || relation.relationKind === "caption-provenance").map((relation) => relation.relationId));
+	replaceCaptionAlignment(draft, captionEntityId, voiceEntityId, 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: {
 			start: startMs,
 			end: startMs + durationMs
-		} }), this.createRelation(draft, "caption-provenance", captionEntityId, scriptEntityId, { segmentAlignment: [] }));
+		} }));
 	}
+	/**
+	* Remove one placed Caption use. The composed AudioScript outlives the
+	* caption: it may anchor further captions and remains the text owner.
+	*/
 	removeCaptionClipGraph(draft, clipEntityId) {
 		const topology = requireClipOnRole(draft, clipEntityId, "caption");
 		const caption = requireEntityKind(draft, otherEndpoint(topology.markerContentRelation, topology.marker.entityId), "caption");
-		const asset = requireEntityKind(draft, otherEndpoint(requireOneRelation(draft, caption.entityId, "physical-asset"), caption.entityId), "asset");
 		const contentRelations = incidentRelations(draft, caption.entityId);
-		const allowed = new Set([
-			"physical-asset",
-			"caption-alignment",
-			"caption-provenance",
-			"marker-content"
-		]);
+		const allowed = new Set(["caption-alignment", "marker-content"]);
 		const unsupported = contentRelations.filter((relation) => !allowed.has(relation.relationKind));
 		if (unsupported.length > 0) throw new Error(`Cannot delete Caption with unsupported Relation ${unsupported[0].relationId}`);
 		this.removeClipGraph(draft, clipEntityId);
 		if (incidentRelations(draft, caption.entityId).some((relation) => relation.relationKind === "marker-content")) return;
 		const removed = new Set(incidentRelations(draft, caption.entityId).map((relation) => relation.relationId));
-		const assetIncidents = incidentRelations(draft, asset.entityId);
-		const deleteAsset = asset.payload.inline !== void 0 && assetIncidents.every((relation) => removed.has(relation.relationId));
 		draft.relations = draft.relations.filter((relation) => !removed.has(relation.relationId));
-		draft.entities = draft.entities.filter((entity) => entity.entityId !== caption.entityId && (!deleteAsset || entity.entityId !== asset.entityId));
+		draft.entities = draft.entities.filter((entity) => entity.entityId !== caption.entityId);
 	}
 	replaceAnchorHost(draft, childClipEntityId, hostClipEntityId) {
 		const anchors = draft.relations.filter((relation) => relation.relationKind === "clip-anchor" && relation.endpoint0EntityId === childClipEntityId);
@@ -1992,7 +1962,6 @@ function migrateLegacyTimelineToEntities(legacy, assetFacts, initial = {
 		facts.set(fact.assetId, fact);
 	}
 	const contentByPartId = /* @__PURE__ */ new Map();
-	const scriptBySpeechClipId = /* @__PURE__ */ new Map();
 	for (const track of legacy.tracks ?? []) for (const item of track.items ?? []) {
 		const part = requirePart(legacy, item.part_id);
 		if (part.video_clip !== void 0) {
@@ -2026,7 +1995,8 @@ function migrateLegacyTimelineToEntities(legacy, assetFacts, initial = {
 			entities = [...imported.rows.entities];
 			relations = [...imported.rows.relations];
 			contentByPartId.set(item.part_id, imported.contentEntityId);
-			scriptBySpeechClipId.set(item.part_id, ensureAudioScript(imported.contentEntityId, speech.audio_script, entities, relations, addEntity, link));
+			const phonemeScript = speech.phoneme_script;
+			ensureSpeechPhoneticChain(imported.contentEntityId, speech.audio_script, typeof phonemeScript === "string" ? phonemeScript : void 0, entities, relations, addEntity, link);
 		} else if (part.bgm !== void 0) {
 			const bgm = part.bgm;
 			const fact = facts.get(bgm.origin_media_id);
@@ -2101,6 +2071,22 @@ 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 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");
+				const sourceText = scriptText(script);
+				const captionText = caption.text;
+				const offset = sourceText.indexOf(captionText);
+				if (!captionText.trim() || offset < 0 || sourceText.indexOf(captionText, offset + 1) >= 0) fail("Legacy Caption needs explicit unambiguous AudioScript selections before cutover");
+				const selections = [{
+					segmentId: "segment-0",
+					...sourceText === captionText ? {} : { textRange: {
+						start: Array.from(sourceText.slice(0, offset)).length,
+						end: Array.from(sourceText.slice(0, offset + captionText.length)).length
+					} }
+				}];
 				content = addEntity("caption", {
 					extent: {
 						kind: "bounded",
@@ -2109,21 +2095,14 @@ function migrateLegacyTimelineToEntities(legacy, assetFacts, initial = {
 					},
 					sampling: "native",
 					coordinateSpace: "milliseconds",
-					text: caption.text,
+					baseEntityIds: [script.entityId],
+					selections,
 					...caption.style === void 0 ? {} : { style: toEntityCaptionStyle(caption.style) }
 				});
-				const asset = addEntity("asset", { inline: {
-					mediaType: "text/plain",
-					text: caption.text
-				} });
-				link("physical-asset", content, asset);
-				const voice = contentByPartId.get(caption.speech_part_id);
-				const script = scriptBySpeechClipId.get(caption.speech_part_id);
 				link("caption-alignment", content, voice, { alignment: {
 					start: caption.start_ms,
 					end: caption.start_ms + duration
 				} });
-				link("caption-provenance", content, script, { segmentAlignment: [] });
 				markerPayload = {
 					sourceRange: {
 						start: 0,
@@ -2339,7 +2318,7 @@ function assertPartSupported(id, part, role) {
 		if (speech.voice?.name !== void 0 && typeof speech.voice.name !== "string") fail("Migration requires a string voice name when present");
 		if (!Array.isArray(speech.caption_ids) || speech.caption_ids.some((captionId) => !trimmed(captionId))) fail("Migration requires explicit Speech caption identities");
 		if (new Set(speech.caption_ids).size !== speech.caption_ids.length) fail("Migration requires unique Speech caption identities");
-		if (phonemeScript !== void 0 && phonemeScript !== null) fail("Non-null phoneme_script requires a phonetic-script migration adapter");
+		if (phonemeScript !== void 0 && phonemeScript !== null && typeof phonemeScript !== "string") fail("Migration requires a string phoneme_script when present");
 		assertKnownFields(speech.voice, ["id", "name"], "voice");
 		assertKnownFields(speech, [
 			"id",
@@ -2463,20 +2442,31 @@ function requirePart(document, partId) {
 	if (part === void 0) fail(`Placed Clip ${partId} has no part payload`);
 	return part;
 }
-function ensureAudioScript(voiceEntityId, text, entities, relations, addEntity, link) {
-	const renders = relations.filter((relation) => relation.relationKind === "audio-script-render" && relation.endpoint0EntityId === voiceEntityId);
-	if (renders.length > 1) fail(`Voice ${voiceEntityId} has ambiguous AudioScript provenance`);
+function ensureSpeechPhoneticChain(voiceEntityId, audioScriptText, phonemeScript, entities, relations, addEntity, link) {
+	const renders = relations.filter((relation) => relation.relationKind === "phonetic-script-render" && relation.endpoint0EntityId === voiceEntityId);
+	if (renders.length > 1) fail(`Voice ${voiceEntityId} has ambiguous PhoneticScript provenance`);
 	if (renders.length === 1) {
-		const script = entities.find((entity) => entity.entityId === renders[0].endpoint1EntityId && entity.entityKind === "audio-script");
-		if (script === void 0 || scriptText(script) !== text) fail(`Voice ${voiceEntityId} conflicts with the legacy Speech script`);
-		return script.entityId;
-	}
-	const script = addEntity("audio-script", { segments: [{
-		segmentId: "segment-0",
-		text
-	}] });
-	link("audio-script-render", voiceEntityId, script);
-	return script;
+		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`);
+		const script = composedAudioScript(phonetic, entities);
+		if (script === void 0 || scriptText(script) !== audioScriptText) fail(`Voice ${voiceEntityId} conflicts with the legacy Speech script`);
+		return phonetic.entityId;
+	}
+	const phonetic = addEntity("phonetic-script", {
+		baseEntityIds: [addEntity("audio-script", { segments: [{
+			segmentId: "segment-0",
+			text: audioScriptText
+		}] })],
+		...phonemeScript === void 0 ? {} : { phonemeScript }
+	});
+	link("phonetic-script-render", voiceEntityId, phonetic);
+	return phonetic;
+}
+function composedAudioScript(phonetic, entities) {
+	return findComposedAudioScript({
+		entities,
+		relations: []
+	}, phonetic.entityId, "phonetic-script");
 }
 function scriptText(script) {
 	const segments = script.payload.segments;
@@ -2566,6 +2556,82 @@ function fail(message) {
 	throw new EntityTimelineProjectionError(message);
 }
 //#endregion
+//#region src/entity-editor/caption-content.ts
+/** Author Caption content from semantic intent; callers never reconcile variant bases or assembled fields. */
+function prepareCaptionContent(rows, input) {
+	const entityId = createEntityId(input.contentEntityId);
+	const scriptId = createEntityId(input.audioScriptEntityId);
+	if (!Number.isFinite(input.durationMs) || input.durationMs <= 0) throw new Error("Caption duration must be positive");
+	const previous = rows.entities.find((row) => row.entityId === entityId);
+	if (previous !== void 0 && previous.entityKind !== "caption") throw new Error("Caption content identity has a different kind");
+	let baseEntityIds = [scriptId];
+	if (previous !== void 0) {
+		const source = assembleCaptionContent(rows, entityId).audioScript.entityId;
+		const bases = variantBaseEntityIds(previous);
+		if (source !== scriptId && !bases.includes(source)) throw new Error("Replacing an indirectly composed AudioScript requires an explicit composition change");
+		baseEntityIds = bases.map((id) => id === source ? scriptId : id);
+	}
+	const candidate = {
+		entityId,
+		entityKind: "caption",
+		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"
+		}
+	};
+	const graph = {
+		...rows,
+		entities: [...rows.entities.filter((row) => row.entityId !== entityId), candidate]
+	};
+	const textSource = {
+		...assembleEntityContent(graph, entityId),
+		entityKind: "audio-script"
+	};
+	const selected = {
+		...candidate,
+		payload: {
+			...candidate.payload,
+			selections: structuredClone(input.selections ?? selectCaptionText(textSource, input.text))
+		}
+	};
+	if (assembleCaptionContent({
+		...graph,
+		entities: graph.entities.map((row) => row.entityId === entityId ? selected : row)
+	}, entityId).text !== input.text) throw new Error("Caption review text differs from its assembled variant content");
+	return selected;
+}
+function selectCaptionText(script, text) {
+	if (!text.trim()) throw new Error("Caption text selection must not be blank");
+	const source = script;
+	const fullText = assembleScriptText(source);
+	const segments = source.payload.segments;
+	if (text === fullText) return segments.map((segment) => ({ segmentId: segment.segmentId }));
+	const matches = [];
+	for (const segment of segments) {
+		let offset = segment.text.indexOf(text);
+		while (offset !== -1) {
+			const start = Array.from(segment.text.slice(0, offset)).length;
+			matches.push({
+				segmentId: segment.segmentId,
+				textRange: {
+					start,
+					end: start + Array.from(text).length
+				}
+			});
+			offset = segment.text.indexOf(text, offset + 1);
+		}
+	}
+	if (matches.length !== 1) throw new Error("Caption text must select a unique AudioScript range; provide explicit selections");
+	return matches;
+}
+//#endregion
 //#region src/editor/snapshot-utils.ts
 function isMap(value) {
 	return value instanceof Map;
@@ -4704,4 +4770,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, ManualSyncDoc, MedeoHttpDocStorage, MemoryDocStorage, MengineAckFailedError, MengineDocSession, MengineHttpClient, MengineHttpRequestError, MenginePushRejectedError, MirrorVideoDocumentAdapter, PlainMemoryAdapter, SchemaValidator, SemanticEditor, TIMELINE_SKELETON_DURATION_MS, VIDEO_DOCUMENT_SCHEMA_VERSION, ValidationError, VideoDocumentValidationError, applyEntityTimelineProjection, arrangeMainTrackSeamlessly, assertCanonicalEditorResources, assertEntityProjectionPreservesLegacy, assertMediaAssetWritePolicy, assertValidVideoDocument, base64ToBytes, buildInitialVideoDocument, buildSpeechHostMap, bytesToBase64, cascadeAfterVideoClipChanges, createEditSandbox, createMirrorVideoDocument, createMirrorVideoDocumentAdapter, createPlainMemoryAdapter, decodeDocVersionMark, derivePositionFromAbs, effectiveVideoClipDurationMs, encodeDocVersionMark, ensureEditorFoundation, ensureLaneTrack, fillMainTrackTimeGaps, findLaneTrack, fromVideoDocument, generatePartId, getAt, hostForAbsMs, importMediaAsset, isEmptyVideoClip, isImplementedSemanticOpKind, isMap, laneTrackId, mainTrackRanges, migrateLegacyTimelineToEntities, partDurationMs, partUnionSchema, projectEntityTimeline, readMainTrackItems, readMengineEventStream, readPart, readPartDurationMs, readVideoDocumentFromDraft, reassignSpeechesToVideoClipsByTime, recalculateTimelineDuration, relativePositionForAbs, replayJournal, resolveAllSpeechOverlaps, resolveEntityTimelineLayout, resolveSpeechOverlapByShiftingVideos, safeDurationMs, schemas_exports as schemas, snapshotToPlain, solveVideoDocument, speedOf, syncAggregatedClipsTimePosition, toVideoDocument, validateVideoDocument, videoDocumentMirrorSchema, videoDocumentSchema, writeVideoDocumentToDraft };
+export { DEFAULT_UNIT_TIME_MS, ENTITY_TIMELINE_PROJECTION_SCHEMA_VERSION, EntityGraphHttpClient, EntityTimelineEditor, EntityTimelineProjectionError, IMPLEMENTED_SEMANTIC_OP_KINDS, LANE_KINDS_IN_STACK_ORDER, ManualSyncDoc, MedeoHttpDocStorage, MemoryDocStorage, MengineAckFailedError, MengineDocSession, MengineHttpClient, MengineHttpRequestError, MenginePushRejectedError, MirrorVideoDocumentAdapter, PlainMemoryAdapter, SchemaValidator, ScriptCompositionError, SemanticEditor, TIMELINE_SKELETON_DURATION_MS, VIDEO_DOCUMENT_SCHEMA_VERSION, ValidationError, VideoDocumentValidationError, applyEntityTimelineProjection, arrangeMainTrackSeamlessly, assembleCaptionContent, assembleEntityContent, assemblePhoneticScriptContent, assembleScriptText, assertCanonicalEditorResources, assertEntityProjectionPreservesLegacy, assertMediaAssetWritePolicy, assertValidVideoDocument, base64ToBytes, buildInitialVideoDocument, buildSpeechHostMap, bytesToBase64, cascadeAfterVideoClipChanges, 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, readMainTrackItems, readMengineEventStream, readPart, readPartDurationMs, readVideoDocumentFromDraft, reassignSpeechesToVideoClipsByTime, recalculateTimelineDuration, relativePositionForAbs, replayJournal, resolveAllSpeechOverlaps, resolveEntityTimelineLayout, resolveSpeechOverlapByShiftingVideos, safeDurationMs, schemas_exports as schemas, selectAudioScriptSegments, snapshotToPlain, solveVideoDocument, speedOf, syncAggregatedClipsTimePosition, toVideoDocument, validateVideoDocument, videoDocumentMirrorSchema, videoDocumentSchema, writeVideoDocumentToDraft };

package/dist/testing.d.ts

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

package/dist/testing.js

@@ -1,4 +1,4 @@
-import { J as VIDEO_DOCUMENT_SCHEMA_VERSION, et as base64ToBytes, s as createMirrorVideoDocumentAdapter, tt as bytesToBase64 } from "./document-Caidonf8.js";
+import { dt as bytesToBase64, it as VIDEO_DOCUMENT_SCHEMA_VERSION, s as createMirrorVideoDocumentAdapter, ut as base64ToBytes } from "./document-BLYcbv8E.js";
 import { t as classifyUpdate } from "./loro-relay-doc-ssdYpuef.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": "1.3.1-alpha.0",
+  "version": "1.3.1-alpha.2",
   "license": "UNLICENSED",
   "repository": {
     "type": "git",
@@ -27,9 +27,9 @@
     "immer": "^10.2.0",
     "loro-mirror": "^2.2.0",
     "zod": "^4.4.3",
-    "@mengine/storage": "1.3.1-alpha.0",
-    "@mengine/utils": "1.3.1-alpha.0",
-    "@mengine/sync": "1.3.1-alpha.0"
+    "@mengine/storage": "1.3.1-alpha.2",
+    "@mengine/sync": "1.3.1-alpha.2",
+    "@mengine/utils": "1.3.1-alpha.2"
   },
   "devDependencies": {
     "@types/node": "^25.9.1",