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

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 reassignSpeechesToVideoClipsByTime, A as isJsonObject, B as VideoDocumentValidationError, C as assembleEntityContent, D as selectAudioScriptSegments, E as findComposedAudioScript, F as buildInitialVideoDocument, G as LANE_KINDS_IN_STACK_ORDER, H as validateVideoDocument, I as buildSpeechHostMap, J as laneTrackId, K as ensureLaneTrack, L as derivePositionFromAbs, M as createRelationId, N as hasSequence, O as updateEntityFields, P as isMediaAssetVariantKind, Q as fillMainTrackTimeGaps, R as fromVideoDocument, S as assembleCaptionContent, T as assembleScriptText, U as partUnionSchema, V as assertValidVideoDocument, W as videoDocumentSchema, X as cascadeAfterVideoClipChanges, Y as solveVideoDocument, Z as arrangeMainTrackSeamlessly, _ as EntityProjectionGraph, _t as bytesToBase64, a as applyEntityTimelineProjection, at as isEmptyVideoClip, b as decodeEntityRelationRows, c as writeVideoDocumentToDraft, ct as DEFAULT_UNIT_TIME_MS, d as LoroEntityDocument, dt as effectiveVideoClipDurationMs, et as recalculateTimelineDuration, f as LoroEntityDraft, ft as speedOf, g as projectEntityTimeline, gt as base64ToBytes, h as equalJson, ht as videoDocumentMirrorSchema, i as MirrorVideoDocumentAdapter, it as TIMELINE_SKELETON_DURATION_MS, j as createEntityId, k as variantBaseEntityIds, l as readVideoDocumentFromDraft, lt as ENTITY_TIMELINE_PROJECTION_SCHEMA_VERSION, m as entityOrderGroups, mt as recordEntries, n as createPlainMemoryAdapter, nt as resolveSpeechOverlapByShiftingVideos, o as createMirrorVideoDocument, ot as partDurationMs, p as readEntityDocument, pt as partUnionToDraft, q as findLaneTrack, r as generatePartId, rt as syncAggregatedClipsTimePosition, s as createMirrorVideoDocumentAdapter, st as safeDurationMs, t as PlainMemoryAdapter, tt as resolveAllSpeechOverlaps, u as LORO_ENTITY_SCHEMA, ut as VIDEO_DOCUMENT_SCHEMA_VERSION, v as resolveEntityTimelineLayout, w as assemblePhoneticScriptContent, x as ScriptCompositionError, y as EntityTimelineProjectionError, z as toVideoDocument } from "./document-BxWxPFTj.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";
@@ -217,6 +217,67 @@ function findSseFrameBoundary(buffer) {
 	return Math.min(lf, crlf);
 }
 //#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) {
+	const doc = new LoroDoc();
+	doc.import(snapshot);
+	return applyEntityRows(new LoroEntityDocument(doc, validate), rows);
+}
+/** Compile an edit on an existing peer, retaining its native local undo history. */
+function applyEntityRows(editor, rows) {
+	const before = editor.snapshot().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]));
+	if (newEntities.size !== rows.entities.length || newRelations.size !== rows.relations.length) throw new Error("Duplicate domain identity");
+	return {
+		update: editor.transact((draft) => {
+			for (const row of before.relations) {
+				const next = newRelations.get(row.relationId);
+				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);
+				}
+			}
+			for (const row of rows.entities) {
+				const previous = oldEntities.get(row.entityId);
+				if (!previous) draft.create(row);
+				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);
+				}
+			}
+			for (const row of rows.relations) if (!oldRelations.has(row.relationId)) draft.link(row);
+			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);
+		}),
+		state: editor.snapshot()
+	};
+}
+//#endregion
+//#region src/entity-editor/document-audio-script.ts
+/** Read only the attached version and preserve every segment; never aggregate other scripts. */
+function readDocumentAudioScript(state) {
+	const id = state.audioScriptEntityId;
+	if (id === null) throw new EntityTimelineProjectionError("Document AudioScript is not initialized");
+	if (typeof id !== "string" || id.trim() !== id || !id) throw new EntityTimelineProjectionError("Invalid document AudioScript identity");
+	const entity = state.rows.entities.find((row) => row.entityId === id);
+	if (!entity || entity.entityKind !== "audio-script") throw new EntityTimelineProjectionError(`Document AudioScript ${id} must name the project AudioScript`);
+	const content = assembleEntityContent(state.rows, createEntityId(id));
+	assembleScriptText(content);
+	return {
+		entityId: id,
+		segments: structuredClone(content.payload.segments)
+	};
+}
+//#endregion
 //#region src/entity-editor/editor-resources.ts
 const roleOrder$1 = {
 	caption: 0,
@@ -231,8 +292,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 +323,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.
 *
@@ -298,6 +357,26 @@ function memotaLocator(value) {
 		key: value.key
 	};
 }
+/**
+* The project AudioScript is a fixed structure identity, like the Timeline: at
+* most one may exist, and a missing one is minted atomically with empty
+* segments. Project initialization and legacy migration share this single
+* path, so both produce the same canonical structure.
+*/
+function ensureDocumentAudioScript(entities, idFactory) {
+	const scripts = entities.filter((row) => row.entityKind === "audio-script");
+	if (scripts.length > 1) throw new EntityTimelineProjectionError("Editor requires exactly one AudioScript");
+	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;
+}
 /** Add only missing editor structure; existing identities and owned settings are never replaced. */
 function ensureEditorFoundation(initial, idFactory = (prefix) => `${prefix}_${globalThis.crypto.randomUUID()}`, timelinePayload = {}) {
 	const entities = structuredClone([...initial.entities]);
@@ -350,13 +429,15 @@ function ensureEditorFoundation(initial, idFactory = (prefix) => `${prefix}_${gl
 		}
 		trackEntityIds[role] = track.entityId;
 	}
+	const audioScriptEntityId = ensureDocumentAudioScript(entities, idFactory);
 	return {
 		rows: {
 			entities,
 			relations
 		},
 		timelineEntityId: timeline.entityId,
-		trackEntityIds
+		trackEntityIds,
+		audioScriptEntityId
 	};
 }
 //#endregion
@@ -366,7 +447,7 @@ const numericMarkerValidation$1 = { compareMarkerPoints: (_marker, _range, left,
 	if (typeof left !== "number" || !Number.isFinite(left) || typeof right !== "number" || !Number.isFinite(right)) throw new Error("entity-state requires finite numeric Marker coordinates");
 	return left < right ? -1 : left > right ? 1 : 0;
 } };
-/** Browser-safe authenticated CAS client for a document's Entity graph. */
+/** Browser-safe authenticated Loro client for a document's Entity graph. */
 var EntityGraphHttpClient = class {
 	options;
 	transport;
@@ -381,30 +462,24 @@ var EntityGraphHttpClient = class {
 		return this.request({ method: "GET" });
 	}
 	/**
-	* Replace the complete Entity graph under the baseline revision.
+	* Compile edits against the original causal snapshot and publish native Loro operations.
 	*
 	* Deletion intent is derived from baseline IDs omitted from `nextRows`, so a
 	* transient create-then-remove never becomes a request to delete unknown
 	* persisted data.
 	*/
 	async commit(baseState, nextRows, options = {}) {
-		if (!isNonNegativeSafeInteger(baseState.revision)) throw new Error("Entity graph revision must be a non-negative safe integer");
-		const baseRows = cloneAndValidateRows(baseState.rows);
+		if (options.migrationBaseVv !== void 0) throw new Error("Legacy entity migration is not supported by the Loro contract");
 		const next = cloneAndValidateRows(nextRows);
-		assertMediaAssetWritePolicy(baseRows, next);
-		const nextEntityIds = new Set(next.entities.map((row) => row.entityId));
-		const nextRelationIds = new Set(next.relations.map((row) => row.relationId));
-		const deletedEntityIds = baseRows.entities.map((row) => row.entityId).filter((entityId) => !nextEntityIds.has(entityId)).sort();
-		const deletedRelationIds = baseRows.relations.map((row) => row.relationId).filter((relationId) => !nextRelationIds.has(relationId)).sort();
+		assertMediaAssetWritePolicy(baseState.rows, next);
+		const compiled = compileEntityRows(base64ToBytes(baseState.loroSnapshot), next);
+		return this.commitUpdate(bytesToBase64(compiled.update));
+	}
+	/** Send the same prepared bytes on retry; never recompile an unconfirmed edit. */
+	async commitUpdate(update) {
 		return this.request({
 			method: "POST",
-			body: JSON.stringify({
-				expected_revision: baseState.revision,
-				rows: toWireRows(next),
-				deleted_entity_ids: deletedEntityIds,
-				deleted_relation_ids: deletedRelationIds,
-				...options.migrationBaseVv === void 0 ? {} : { migration_base_vv: options.migrationBaseVv }
-			})
+			body: JSON.stringify({ update })
 		});
 	}
 	async request(init) {
@@ -422,10 +497,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);
-	return {
+	if (typeof value.audio_script_entity_id !== "string") throw new Error("Document AudioScript is not initialized");
+	if (typeof value.loro_snapshot !== "string") throw new Error("Missing causal Loro snapshot");
+	const state = {
 		revision: value.revision,
-		rows
+		loroSnapshot: value.loro_snapshot,
+		rows,
+		audioScriptEntityId: value.audio_script_entity_id
 	};
+	readDocumentAudioScript(state);
+	return state;
 }
 function parseWireRows(value) {
 	if (!isRecord(value) || !Array.isArray(value.entities) || !Array.isArray(value.relations)) throw new Error("Invalid entity-state response rows");
@@ -458,23 +539,6 @@ function cloneAndValidateRows(rows) {
 	decodeEntityRelationRows(clone, numericMarkerValidation$1);
 	return clone;
 }
-function toWireRows(rows) {
-	return {
-		entities: rows.entities.map((row) => ({
-			entity_id: row.entityId,
-			entity_kind: row.entityKind,
-			payload: row.payload
-		})),
-		relations: rows.relations.map((row) => ({
-			relation_id: row.relationId,
-			relation_kind: row.relationKind,
-			endpoint_0_entity_id: row.endpoint0EntityId,
-			endpoint_1_entity_id: row.endpoint1EntityId,
-			metadata: row.metadata,
-			trace: row.trace
-		}))
-	};
-}
 function requiredString(value, field) {
 	if (typeof value !== "string" || value.length === 0 || value.trim() !== value) throw new Error(`Invalid ${field} in entity-state response`);
 	return value;
@@ -608,6 +672,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 +1210,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 +1261,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 +1351,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 +1387,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 +1471,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 +1497,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 +1511,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 +1553,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 +1569,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 +1584,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);
@@ -1964,6 +2000,7 @@ function migrateLegacyTimelineToEntities(legacy, assetFacts, initial = {
 	const normalizedMainRanges = overlapNormalizedMainRanges(legacy);
 	let entities = structuredClone([...initial.entities]);
 	let relations = structuredClone([...initial.relations]);
+	const documentAudioScriptEntityId = ensureDocumentAudioScript(entities, idFactory);
 	const addEntity = (kind, payload, existingId) => {
 		const entityId = createEntityId(existingId ?? idFactory("entity"));
 		if (entities.some((row) => row.entityId === entityId)) fail(`Migration entity identity collision: ${entityId}`);
@@ -1992,7 +2029,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 +2062,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, documentAudioScriptEntityId);
 		} else if (part.bgm !== void 0) {
 			const bgm = part.bgm;
 			const fact = facts.get(bgm.origin_media_id);
@@ -2101,6 +2138,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 +2162,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 +2385,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 +2509,43 @@ 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, 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`);
 	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 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 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`);
+	} else {
+		const scriptIndex = entities.findIndex((row) => row.entityId === script.entityId);
+		entities[scriptIndex] = {
+			...script,
+			payload: { segments: [{
+				segmentId: "segment-0",
+				text: audioScriptText
+			}] }
+		};
 	}
-	const script = addEntity("audio-script", { segments: [{
-		segmentId: "segment-0",
-		text
-	}] });
-	link("audio-script-render", voiceEntityId, script);
-	return script;
+	const phonetic = addEntity("phonetic-script", {
+		baseEntityIds: [script.entityId],
+		...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 +2635,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 +4849,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, 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, arrangeMainTrackSeamlessly, assembleCaptionContent, assembleEntityContent, assemblePhoneticScriptContent, assembleScriptText, assertCanonicalEditorResources, assertEntityProjectionPreservesLegacy, 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, resolveSpeechOverlapByShiftingVideos, safeDurationMs, schemas_exports as schemas, selectAudioScriptSegments, snapshotToPlain, solveVideoDocument, speedOf, syncAggregatedClipsTimePosition, toVideoDocument, validateVideoDocument, videoDocumentMirrorSchema, videoDocumentSchema, writeVideoDocumentToDraft };