@mengine/medeo-client 2.0.1-alpha.13 → 2.0.1-alpha.14

package/dist/index.js

@@ -1,6 +1,8 @@
-import { $ as partUnionSchema, A as decodeEntityRelationRows, B as isJsonObject, C as applyFieldChanges, Ct as recordEntries, D as EntityProjectionGraph, E as projectEntityTimeline, Et as bytesToBase64, F as assembleScriptText, G as buildInitialVideoDocument, H as createRelationId, I as findComposedAudioScript, J as fromVideoDocument, K as buildSpeechHostMap, L as selectAudioScriptSegment, M as assembleCaptionContent, N as assembleEntityContent, O as resolveEntityTimelineLayout, P as assemblePhoneticScriptContent, Q as validateVideoDocument, R as updateEntityFields, S as equalJson, St as partUnionToDraft, T as resolveFieldPath, Tt as base64ToBytes, U as hasSequence, V as createEntityId, W as isMediaAssetVariantKind, X as VideoDocumentValidationError, Y as toVideoDocument, Z as assertValidVideoDocument, _ as audioScriptAssetOf, _t as partDurationMs, a as createMirrorVideoDocument, at as laneTrackId, b as phoneticScriptAssetOf, bt as effectiveVideoClipDurationMs, c as DocumentMutationGuard, ct as arrangeMainTrackSeamlessly, d as LoroEntityDraft, dt as recalculateTimelineDuration, et as videoDocumentSchema, f as readEntityDocument, ft as resolveAllSpeechOverlaps, g as audioScriptAssetHash, gt as isEmptyVideoClip, h as audioScriptAssetFields, ht as TIMELINE_SKELETON_DURATION_MS, i as MirrorVideoDocumentAdapter, it as hasResolvedPlacement, j as ScriptCompositionError, k as EntityTimelineProjectionError, l as LORO_ENTITY_SCHEMA, lt as fillMainTrackTimeGaps, m as audioScriptAssetContent, mt as syncAggregatedClipsTimePosition, n as createPlainMemoryAdapter, nt as ensureLaneTrack, o as createMirrorVideoDocumentAdapter, ot as solveVideoDocument, p as entityOrderGroups, pt as resolveSpeechOverlapByShiftingVideos, q as derivePositionFromAbs, r as generatePartId, rt as findLaneTrack, s as readVideoDocumentFromDraft, st as cascadeAfterVideoClipChanges, t as PlainMemoryAdapter, tt as LANE_KINDS_IN_STACK_ORDER, u as LoroEntityDocument, ut as reassignSpeechesToVideoClipsByTime, v as phoneticScriptAssetContent, vt as safeDurationMs, w as assertFieldChanges, wt as videoDocumentMirrorSchema, x as scriptSourceAssetOf, xt as speedOf, y as phoneticScriptAssetHash, yt as DEFAULT_UNIT_TIME_MS, z as variantBaseEntityIds } from "./document-CAZ_A9R8.js";
+import { $ as ensureLaneTrack, A as assembleEntityContent, B as hasSequence, C as projectEntityTimeline, Ct as bytesToBase64, D as decodeEntityRelationRows, E as EntityTimelineProjectionError, F as updateEntityFields, G as fromVideoDocument, H as buildInitialVideoDocument, I as variantBaseEntityIds, J as assertValidVideoDocument, K as toVideoDocument, L as isJsonObject, M as assembleScriptText, N as findComposedAudioScript, O as ScriptCompositionError, P as selectAudioScriptSegment, Q as LANE_KINDS_IN_STACK_ORDER, R as createEntityId, S as resolveFieldPath, St as base64ToBytes, T as resolveEntityTimelineLayout, U as buildSpeechHostMap, V as isMediaAssetVariantKind, W as derivePositionFromAbs, X as partUnionSchema, Y as validateVideoDocument, Z as videoDocumentSchema, _ as audioScriptAssetOf, _t as effectiveVideoClipDurationMs, a as createMirrorVideoDocument, at as arrangeMainTrackSeamlessly, b as applyFieldChanges, bt as recordEntries, c as DocumentMutationGuard, ct as recalculateTimelineDuration, d as LoroEntityDraft, dt as syncAggregatedClipsTimePosition, et as findLaneTrack, f as readEntityDocument, ft as TIMELINE_SKELETON_DURATION_MS, g as audioScriptAssetHash, gt as DEFAULT_UNIT_TIME_MS, h as audioScriptAssetFields, ht as safeDurationMs, i as MirrorVideoDocumentAdapter, it as cascadeAfterVideoClipChanges, j as assemblePhoneticScriptContent, k as assembleCaptionContent, l as LORO_ENTITY_SCHEMA, lt as resolveAllSpeechOverlaps, m as audioScriptAssetContent, mt as partDurationMs, n as createPlainMemoryAdapter, nt as laneTrackId, o as createMirrorVideoDocumentAdapter, ot as fillMainTrackTimeGaps, p as entityOrderGroups, pt as isEmptyVideoClip, q as VideoDocumentValidationError, r as generatePartId, rt as solveVideoDocument, s as readVideoDocumentFromDraft, st as reassignSpeechesToVideoClipsByTime, t as PlainMemoryAdapter, tt as hasResolvedPlacement, u as LoroEntityDocument, ut as resolveSpeechOverlapByShiftingVideos, v as canonicalJson, vt as speedOf, w as EntityProjectionGraph, x as assertFieldChanges, xt as videoDocumentMirrorSchema, y as equalJson, yt as partUnionToDraft, z as createRelationId } from "./document-BHHbS_17.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 { 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";
@@ -221,8 +223,7 @@ function compileEntityRows(snapshot, rows, validate) {
 }
 /** Compile an edit on an existing peer, retaining its native local undo history. */
 function applyEntityRows(editor, rows) {
-	const baseline = editor.snapshot();
-	const before = baseline.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]));
@@ -238,16 +239,10 @@ function applyEntityRows(editor, rows) {
 					if (!equalJson(row.metadata, next.metadata) || !equalJson(row.trace, next.trace)) draft.patchRelation(row.relationId, next.metadata, next.trace);
 				}
 			}
-			let attached = baseline.project.audioScriptEntityId !== void 0;
 			for (const row of rows.entities) {
 				const previous = oldEntities.get(row.entityId);
-				if (!previous) {
-					draft.create(row);
-					if (!attached && row.entityKind === "audio-script") {
-						draft.attach("audioScriptEntityId", String(row.entityId));
-						attached = true;
-					}
-				} else {
+				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);
 				}
@@ -357,14 +352,23 @@ function memotaLocator(value) {
 * explicit project attachment, multiple candidates are ambiguous. Existing
 * content IDs are reused here; Loro editing advances their immutable versions.
 */
-function ensureDocumentAudioScript(entities, selectedEntityId) {
+function ensureDocumentAudioScript(entities, idFactory, selectedEntityId) {
 	if (selectedEntityId != null) {
 		if (!entities.some((row) => row.entityKind === "audio-script" && row.entityId === selectedEntityId)) throw new EntityTimelineProjectionError(`Selected AudioScript ${selectedEntityId} does not exist`);
 		return selectedEntityId;
 	}
 	const scripts = entities.filter((row) => row.entityKind === "audio-script");
 	if (scripts.length > 1) throw new EntityTimelineProjectionError("Select an AudioScript for the editor panel when multiple scripts exist");
-	return scripts[0]?.entityId ?? null;
+	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 = {}, selectedAudioScriptEntityId) {
@@ -418,7 +422,7 @@ function ensureEditorFoundation(initial, idFactory = (prefix) => `${prefix}_${gl
 		}
 		trackEntityIds[role] = track.entityId;
 	}
-	const audioScriptEntityId = ensureDocumentAudioScript(entities, selectedAudioScriptEntityId);
+	const audioScriptEntityId = ensureDocumentAudioScript(entities, idFactory, selectedAudioScriptEntityId);
 	return {
 		rows: {
 			entities,
@@ -486,16 +490,15 @@ 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);
-	const attached = value.audio_script_entity_id;
-	if (attached !== null && typeof attached !== "string") throw new Error("Invalid document AudioScript identity");
+	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,
 		loroSnapshot: value.loro_snapshot,
 		rows,
-		audioScriptEntityId: attached
+		audioScriptEntityId: value.audio_script_entity_id
 	};
-	if (attached !== null) readDocumentAudioScript(state);
+	readDocumentAudioScript(state);
 	return state;
 }
 function parseWireRows(value) {
@@ -554,6 +557,30 @@ const numericCoordinates = { compareMarkerPoints: (_marker, _range, left, right)
 	if (typeof left !== "number" || typeof right !== "number" || !Number.isFinite(left) || !Number.isFinite(right)) throw new Error("Media editor requires numeric coordinates");
 	return left - right;
 } };
+/** Import only the fixed ASR artifact; Caption entities are authored separately. */
+function importCaptionAsset(initial, fact, idFactory = (prefix) => `${prefix}_${globalThis.crypto.randomUUID()}`) {
+	if (!fact.assetId || fact.assetId.trim() !== fact.assetId) throw new Error("Expected a caption asset id");
+	if (fact.storageKey !== void 0 && (!fact.storageKey || fact.storageKey.trim() !== fact.storageKey)) throw new Error("Caption asset storage key must be non-empty and trimmed");
+	decodeEntityRelationRows(initial, numericCoordinates);
+	assertCanonicalEditorResources(initial);
+	const entities = structuredClone([...initial.entities]);
+	const relations = structuredClone([...initial.relations]);
+	const asset = ensureAsset(entities, relations, {
+		system: "memota",
+		key: fact.assetId,
+		...fact.storageKey === void 0 ? {} : { storageKey: fact.storageKey }
+	}, idFactory);
+	const rows = {
+		entities,
+		relations
+	};
+	decodeEntityRelationRows(rows, numericCoordinates);
+	assertCanonicalEditorResources(rows);
+	return {
+		rows,
+		assetEntityId: asset.entityId
+	};
+}
 /**
 * Import at the editor boundary, not at asset generation time. Existing
 * provenance is retained.
@@ -581,7 +608,7 @@ function importMediaAsset(initial, fact, idFactory = (prefix) => `${prefix}_${gl
 	const entityKind = fact.kind === "voiceover" ? "audio" : fact.kind;
 	const timbre = fact.kind === "voiceover" ? fact.voice : void 0;
 	const durationMs = fact.kind === "image" ? null : fact.durationMs;
-	const asset = ensureAsset(entities, {
+	const asset = ensureAsset(entities, relations, {
 		system,
 		key: fact.assetId,
 		storageKey: fact.storageKey
@@ -625,20 +652,31 @@ function importMediaAsset(initial, fact, idFactory = (prefix) => `${prefix}_${gl
 	};
 }
 /** One Asset per `(system, key)`: the bytes are named in exactly one row. */
-function ensureAsset(entities, locator, idFactory) {
+function ensureAsset(entities, relations, locator, idFactory) {
 	const found = entities.find((row) => row.entityKind === "asset" && row.payload.system === locator.system && row.payload.key === locator.key);
 	if (found !== void 0) {
 		if (locator.storageKey === void 0 || found.payload.storageKey === locator.storageKey) return found;
 		if (found.payload.storageKey !== void 0) throw new Error(`Media facts conflict with existing storage key for ${locator.key}`);
-		const filled = {
-			...found,
+		const replacement = {
+			entityId: createEntityId(idFactory("entity")),
+			entityKind: "asset",
 			payload: {
 				...found.payload,
 				storageKey: locator.storageKey
 			}
 		};
-		replaceEntity$1(entities, found.entityId, filled);
-		return filled;
+		if (entities.some((row) => row.entityId === replacement.entityId)) throw new Error(`Duplicate entity id ${replacement.entityId}`);
+		const bindings = relations.filter((relation) => relation.relationKind === "from-asset" && (relation.endpoint0EntityId === found.entityId || relation.endpoint1EntityId === found.entityId)).sort((left, right) => String(left.relationId).localeCompare(String(right.relationId)));
+		const replaced = new Set(bindings.map((relation) => relation.relationId));
+		const nextBindings = bindings.map((relation) => ({
+			...relation,
+			relationId: createRelationId(idFactory("relation")),
+			endpoint0EntityId: relation.endpoint0EntityId === found.entityId ? replacement.entityId : relation.endpoint0EntityId,
+			endpoint1EntityId: relation.endpoint1EntityId === found.entityId ? replacement.entityId : relation.endpoint1EntityId
+		}));
+		relations.splice(0, relations.length, ...relations.filter((relation) => !replaced.has(relation.relationId)), ...nextBindings);
+		replaceEntity$1(entities, found.entityId, replacement);
+		return replacement;
 	}
 	const asset = {
 		entityId: createEntityId(idFactory("entity")),
@@ -747,7 +785,7 @@ const defaultIdFactory = (prefix) => `${prefix}_${globalThis.crypto.randomUUID()
 * Each mutation is applied to a detached graph, validated as a complete DSL set,
 * and committed only after validation succeeds.
 */
-var EntityTimelineEditor = class {
+var EntityTimelineEditor = class EntityTimelineEditor {
 	idFactory;
 	state;
 	constructor(initialRows, idFactory = defaultIdFactory) {
@@ -1058,49 +1096,65 @@ var EntityTimelineEditor = class {
 		});
 	}
 	setClipSpeed(input) {
+		this.transact((draft) => this.setClipSpeedIntoDraft(draft, input));
+	}
+	/** Apply one typed Director speed effect as a single graph transaction. */
+	setVideoClipSpeeds(input) {
+		if (input.clips.length === 0) throw new Error("At least one Video Clip speed is required");
+		if (new Set(input.clips.map((clip) => clip.videoClipEntityId)).size !== input.clips.length) throw new Error("Video Clip speed targets must be unique");
 		this.transact((draft) => {
-			const initialTopology = requireClipOnRole(draft, input.clipEntityId, "video_clip");
-			const content = requireSequenceContent(draft, otherEndpoint(initialTopology.markerContentRelation, initialTopology.marker.entityId));
-			if (content.entityKind !== "video" && content.entityKind !== "image") throw new Error("Clip speed is supported only for Video or Image content");
-			const initialPayload = cloneJsonObject(initialTopology.marker.payload, "Sequence Marker payload");
-			const priorSource = requirePositiveRange(initialPayload.sourceRange, "sourceRange");
-			if (input.timeRemapping === null && initialPayload.timeRemapping === void 0) return;
-			this.normalizeMainSequential(draft);
-			const topology = requireClipTopology(draft, input.clipEntityId);
-			const payload = { ...cloneJsonObject(topology.marker.payload, "Sequence Marker payload") };
-			let sourceRange = priorSource;
-			if (content.entityKind === "image" && initialPayload.timeRemapping === void 0 && input.timeRemapping !== null) sourceRange = {
-				start: 0,
-				end: markerDuration(initialPayload, priorSource)
-			};
-			if (input.timeRemapping === null) {
-				delete payload.timeRemapping;
-				payload.sourceRange = sourceRange;
-				payload.duration = {
-					mode: "fixed",
-					value: sourceRange.end - sourceRange.start
-				};
-			} else {
-				const rate = finitePositive(input.timeRemapping.rate, "linear speed rate");
-				const duration = Math.round((sourceRange.end - sourceRange.start) / rate);
-				if (duration <= 0 || !Number.isSafeInteger(duration)) throw new Error("Linear speed produces an invalid duration");
-				payload.sourceRange = sourceRange;
-				payload.duration = {
-					mode: "fixed",
-					value: duration
-				};
-				payload.timeRemapping = {
-					kind: "linear",
-					rate,
-					...input.timeRemapping.mode === void 0 ? {} : { mode: input.timeRemapping.mode }
-				};
+			for (const clip of input.clips) {
+				const rate = speedModeRate(clip.mode);
+				this.setClipSpeedIntoDraft(draft, {
+					clipEntityId: clip.videoClipEntityId,
+					timeRemapping: rate === 1 ? null : {
+						kind: "linear",
+						rate,
+						mode: "constant"
+					}
+				});
 			}
-			resizeAbsoluteTarget(payload, markerDuration(payload, sourceRange));
-			replaceEntity(draft, topology.marker.entityId, {
-				...topology.marker,
-				payload
-			});
-			this.resolveOneVoiceoverOverlap(draft);
+		});
+	}
+	setClipSpeedIntoDraft(draft, input) {
+		const topology = requireCanonicalClipOnRole(draft, input.clipEntityId, "video_clip");
+		const content = requireSequenceContent(draft, topology.markerContentRelation.endpoint1EntityId);
+		if (content.entityKind !== "video" && content.entityKind !== "image") throw new Error("Clip speed is supported only for Video or Image content");
+		const initialPayload = cloneJsonObject(topology.marker.payload, "Sequence Marker payload");
+		const priorSource = requirePositiveRange(initialPayload.sourceRange, "sourceRange");
+		if (input.timeRemapping === null && initialPayload.timeRemapping === void 0) return;
+		const payload = { ...cloneJsonObject(topology.marker.payload, "Sequence Marker payload") };
+		let sourceRange = priorSource;
+		if (content.entityKind === "image" && initialPayload.timeRemapping === void 0 && input.timeRemapping !== null) sourceRange = {
+			start: 0,
+			end: markerDuration(initialPayload, priorSource)
+		};
+		if (input.timeRemapping === null) {
+			delete payload.timeRemapping;
+			payload.sourceRange = sourceRange;
+			payload.duration = {
+				mode: "fixed",
+				value: sourceRange.end - sourceRange.start
+			};
+		} else {
+			const rate = finitePositive(input.timeRemapping.rate, "linear speed rate");
+			const duration = Math.round((sourceRange.end - sourceRange.start) / rate);
+			if (duration <= 0 || !Number.isSafeInteger(duration)) throw new Error("Linear speed produces an invalid duration");
+			payload.sourceRange = sourceRange;
+			payload.duration = {
+				mode: "fixed",
+				value: duration
+			};
+			payload.timeRemapping = {
+				kind: "linear",
+				rate,
+				...input.timeRemapping.mode === void 0 ? {} : { mode: input.timeRemapping.mode }
+			};
+		}
+		resizeAbsoluteTarget(payload, markerDuration(payload, sourceRange));
+		replaceEntity(draft, topology.marker.entityId, {
+			...topology.marker,
+			payload
 		});
 	}
 	trimClip(input) {
@@ -1450,12 +1504,447 @@ var EntityTimelineEditor = class {
 			});
 		});
 	}
+	#applyCaptionAssets(envelope) {
+		return this.transact((draft) => {
+			const input = envelope.input;
+			const effectId = requireTrimmed(input.effectId, "Caption effect id");
+			const identityScope = stableEffectScope(captionAssetsCommand, effectId, envelope.baselineFingerprint);
+			const segments = validateAsrSegments(input.segments);
+			const source = requireEntityKind(draft, input.source.entityId, input.source.entityKind);
+			const track = requireCanonicalCaptionTrack(draft, input.timelineEntityId, input.trackEntityId);
+			const signature = envelope.signature;
+			const replay = resolveCaptionAssetsReplay(draft, input, effectId, signature, segments, source.entityId, track.entityId);
+			if (replay !== void 0) return replay;
+			const imported = importCaptionAsset(draft, input.captionAsset, stableEffectIdFactory(identityScope, "caption-asset"));
+			if (imported.assetEntityId !== envelope.decisions.captionAsset.resultAssetEntityId) throw new Error("Frozen Caption Asset decision no longer matches the causal baseline");
+			replaceRows(draft, imported.rows);
+			const scriptId = requireAvailableEntityId(draft, stableEffectId("entity", identityScope, "audio-script"));
+			const scriptMarkerId = requireAvailableEntityId(draft, stableEffectId("entity", identityScope, "audio-script-marker"));
+			const asrStartMs = Math.min(...segments.map((segment) => segment.startMs));
+			const asrEndMs = Math.max(...segments.map((segment) => segment.endMs));
+			draft.entities.push({
+				entityId: scriptId,
+				entityKind: "audio-script",
+				payload: { segments: segments.map(({ segmentId, text, language }) => ({
+					segmentId,
+					text,
+					...language === void 0 ? {} : { language }
+				})) }
+			});
+			draft.entities.push({
+				entityId: scriptMarkerId,
+				entityKind: "sequence-marker",
+				payload: {
+					sourceRange: {
+						start: asrStartMs,
+						end: asrEndMs
+					},
+					duration: {
+						mode: "fixed",
+						value: asrEndMs - asrStartMs
+					},
+					segmentRanges: segments.map(({ segmentId, startMs, endMs }) => ({
+						segmentId,
+						startMs,
+						endMs
+					}))
+				}
+			});
+			draft.relations.push(this.createRelation(draft, "audio-script-source", scriptId, source.entityId, {}, effectTrace(effectId, signature), stableEffectId("relation", identityScope, "audio-script-source")), this.createRelation(draft, "audio-script-marker", scriptId, scriptMarkerId, {}, effectTrace(effectId, signature), stableEffectId("relation", identityScope, "audio-script-marker")));
+			const captionEntityIds = [];
+			const captionClipEntityIds = [];
+			for (const [index, segment] of segments.entries()) {
+				const durationMs = segment.endMs - segment.startMs;
+				const target = envelope.decisions.targetRanges[index];
+				if (target?.segmentId !== segment.segmentId) throw new Error("Frozen Caption placement order is invalid");
+				const targetRange = {
+					start: target.start,
+					end: target.end
+				};
+				const captionId = requireAvailableEntityId(draft, stableEffectId("entity", identityScope, `caption:${segment.segmentId}`));
+				draft.entities.push({
+					entityId: captionId,
+					entityKind: "caption",
+					payload: {
+						durationMs,
+						baseEntityIds: [scriptId],
+						selection: { segmentId: segment.segmentId }
+					}
+				});
+				const trace = effectTrace(effectId, signature, segment.segmentId);
+				draft.relations.push(this.createRelation(draft, "from-asset", captionId, createEntityId(imported.assetEntityId), {}, trace, stableEffectId("relation", identityScope, `caption-asset:${segment.segmentId}`)));
+				const clipId = this.insertPlacedClipIntoDraft(draft, {
+					clipEntityId: stableEffectId("entity", identityScope, `caption-clip:${segment.segmentId}`),
+					markerEntityId: stableEffectId("entity", identityScope, `caption-marker:${segment.segmentId}`),
+					trackEntityId: track.entityId,
+					contentEntityId: captionId,
+					sourceRange: {
+						start: 0,
+						end: durationMs
+					},
+					duration: {
+						mode: "fixed",
+						value: targetRange.end - targetRange.start
+					},
+					placement: {
+						kind: "absolute",
+						targetRange
+					},
+					relationTrace: trace,
+					relationIds: {
+						trackClip: stableEffectId("relation", identityScope, `track-clip:${segment.segmentId}`),
+						clipMarker: stableEffectId("relation", identityScope, `clip-marker:${segment.segmentId}`),
+						markerContent: stableEffectId("relation", identityScope, `marker-content:${segment.segmentId}`)
+					}
+				});
+				captionEntityIds.push(captionId);
+				captionClipEntityIds.push(clipId);
+			}
+			return {
+				audioScriptEntityId: scriptId,
+				audioScriptMarkerEntityId: scriptMarkerId,
+				captionAssetEntityId: imported.assetEntityId,
+				captionEntityIds,
+				captionClipEntityIds
+			};
+		});
+	}
+	static compileCaptionAssetsEffect(base, envelope) {
+		assertCaptionAssetsEnvelope(envelope);
+		const input = envelope.input;
+		const effectId = requireTrimmed(input.effectId, "Caption effect id");
+		const segments = validateAsrSegments(input.segments);
+		if (effectId !== envelope.effectId || captionEffectSignature(input, segments) !== envelope.signature) throw new Error("Caption effect envelope signature does not match its canonical input");
+		const current = cloneRows(base.snapshot().rows);
+		const replay = resolveCaptionAssetsReplay(current, input, effectId, envelope.signature, segments, createEntityId(input.source.entityId), createEntityId(input.trackEntityId));
+		if (replay !== void 0) return {
+			result: replay,
+			replayed: true,
+			rows: current
+		};
+		const fingerprint = captionBaselineFingerprint(base);
+		if (fingerprint !== envelope.baselineFingerprint) throw new Error("Caption effect baseline changed; independently prepared envelopes on divergent baselines are unsupported");
+		if (canonicalJson(resolveCaptionEffectDecisions(current, input, stableEffectScope(captionAssetsCommand, effectId, fingerprint), segments)) !== canonicalJson(envelope.decisions)) throw new Error("Caption effect decisions no longer match the frozen causal baseline");
+		const doc = base.doc.fork();
+		doc.setPeerId(stableEffectPeerId(captionAssetsCommand, effectId, fingerprint));
+		const staged = new LoroEntityDocument(doc);
+		const editor = new EntityTimelineEditor(staged.snapshot().rows, () => {
+			throw new Error("Caption effects must use effect-derived identities");
+		});
+		const result = editor.#applyCaptionAssets(envelope);
+		const applied = applyEntityRows(staged, editor.rows());
+		return {
+			result,
+			replayed: false,
+			update: applied.update,
+			rows: applied.state.rows
+		};
+	}
+	#applyGeneratedVisuals(envelope) {
+		return this.transact((draft) => {
+			const { input } = envelope;
+			const identityScope = stableEffectScope(generatedVisualsCommand, envelope.effectId, envelope.baselineFingerprint);
+			const anchorInput = visualInsertionAnchor(input);
+			const anchor = requireCanonicalClipOnRole(draft, anchorInput.clipEntityId, "video_clip");
+			if (anchor.trackRelation.endpoint0EntityId !== envelope.decisions.trackEntityId || anchor.trackRelation.endpoint1EntityId !== anchor.clip.entityId || anchorInput.position !== envelope.decisions.anchorPosition) throw new Error("Frozen visual insertion anchor is no longer canonical");
+			const ordered = resolveEntityTimelineLayout(draft).tracks.find((candidate) => candidate.entityId === envelope.decisions.trackEntityId)?.clips.map((clip) => clip.clipEntityId);
+			const anchorIndex = ordered?.indexOf(anchor.clip.entityId) ?? -1;
+			if (ordered === void 0 || anchorIndex < 0 || anchorIndex !== envelope.decisions.anchorOrder) throw new Error("Frozen visual insertion order no longer matches the causal baseline");
+			const clipEntityIds = [];
+			const mediaEntityIds = [];
+			for (const [index, clip] of input.clips.entries()) {
+				const imported = importMediaAsset(draft, clip.media, stableEffectIdFactory(identityScope, `visual:${index}:media`));
+				replaceRows(draft, imported.rows);
+				const media = requireSequenceContent(draft, imported.contentEntityId);
+				if (media.entityKind !== "video" && media.entityKind !== "image") throw new Error("Generated visual content must be Video or Image");
+				const durationMs = safeWholeMs(clip.durationMs, "Generated visual durationMs");
+				if (durationMs === 0 || clip.media.kind === "video" && durationMs > clip.media.durationMs) throw new Error("Generated visual duration must fit its immutable media Sequence");
+				const trace = generatedVisualTrace(envelope, index, clip.generationJobId);
+				const clipId = this.insertPlacedClipIntoDraft(draft, {
+					clipEntityId: stableEffectId("entity", identityScope, `visual:${index}:clip`),
+					markerEntityId: stableEffectId("entity", identityScope, `visual:${index}:marker`),
+					trackEntityId: envelope.decisions.trackEntityId,
+					contentEntityId: media.entityId,
+					sourceRange: {
+						start: 0,
+						end: durationMs
+					},
+					duration: {
+						mode: "fixed",
+						value: durationMs
+					},
+					placement: {
+						kind: "sequential",
+						order: envelope.decisions.insertionOrders[index]
+					},
+					...clip.volume === void 0 ? {} : { clipPayload: { volume: clip.volume } },
+					relationTrace: trace,
+					relationIds: {
+						trackClip: stableEffectId("relation", identityScope, `visual:${index}:track-clip`),
+						clipMarker: stableEffectId("relation", identityScope, `visual:${index}:clip-marker`),
+						markerContent: stableEffectId("relation", identityScope, `visual:${index}:marker-content`)
+					}
+				});
+				for (const [sourceIndex, sourceId] of clip.sourceMediaEntityIds.entries()) {
+					const source = requireSequenceContent(draft, sourceId);
+					if (![
+						"video",
+						"image",
+						"audio"
+					].includes(source.entityKind)) throw new Error("Generated visual lineage requires Video, Image, or Audio inputs");
+					draft.relations.push(this.createRelation(draft, "generated", media.entityId, source.entityId, {}, generatedVisualTrace(envelope, index, clip.generationJobId, sourceIndex), stableEffectId("relation", identityScope, `visual:${index}:generated:${sourceIndex}`)));
+				}
+				clipEntityIds.push(clipId);
+				mediaEntityIds.push(media.entityId);
+			}
+			return {
+				clipEntityIds,
+				mediaEntityIds
+			};
+		});
+	}
+	static compileGeneratedVisualEffect(base, envelope) {
+		assertGeneratedVisualEnvelope(envelope);
+		consumeEffectEnvelope(consumedGeneratedVisualEnvelopes, envelope, "Generated visual");
+		const current = cloneRows(base.snapshot().rows);
+		const replay = resolveGeneratedVisualReplay(current, envelope);
+		if (replay !== void 0) return {
+			result: replay,
+			replayed: true,
+			rows: current
+		};
+		const fingerprint = captionBaselineFingerprint(base);
+		if (fingerprint !== envelope.baselineFingerprint) throw new Error("Generated visual effect baseline changed; prepare a new effect from the authority");
+		if (canonicalJson(resolveGeneratedVisualDecisions(current, envelope.input)) !== canonicalJson(envelope.decisions)) throw new Error("Generated visual decisions no longer match the frozen causal baseline");
+		const doc = base.doc.fork();
+		doc.setPeerId(stableEffectPeerId(generatedVisualsCommand, envelope.effectId, fingerprint));
+		const staged = new LoroEntityDocument(doc);
+		const editor = new EntityTimelineEditor(staged.snapshot().rows, () => {
+			throw new Error("Generated visual effects must use effect-derived identities");
+		});
+		const result = editor.#applyGeneratedVisuals(envelope);
+		const applied = applyEntityRows(staged, editor.rows());
+		return {
+			result,
+			replayed: false,
+			update: applied.update,
+			rows: applied.state.rows
+		};
+	}
+	#applySpeechAssets(envelope) {
+		return this.transact((draft) => {
+			const { input } = envelope;
+			const value = input.value;
+			const identityScope = stableEffectScope(speechAssetsCommand, envelope.effectId, envelope.baselineFingerprint);
+			const speechTrack = ensureEffectRoleTrack(draft, value.timelineEntityId, "speech", envelope.decisions.speechTrackEntityId, identityScope);
+			const captionTrack = value.items.some((item) => item.captions.length > 0) ? ensureEffectRoleTrack(draft, value.timelineEntityId, "caption", envelope.decisions.captionTrackEntityId, identityScope) : void 0;
+			const speechClipEntityIds = [];
+			const speechAudioEntityIds = [];
+			const audioScriptEntityIds = [];
+			const phoneticScriptEntityIds = [];
+			const captionClipEntityIds = [];
+			for (const [index, item] of value.items.entries()) {
+				const trace = speechEffectTrace(envelope, index);
+				const scripts = materializeSpeechSource(draft, item, identityScope, index, trace);
+				const imported = importMediaAsset(draft, item.media, stableEffectIdFactory(identityScope, `speech:${index}:media`));
+				replaceRows(draft, imported.rows);
+				const speech = requireEntityKind(draft, imported.contentEntityId, "audio");
+				if (imported.voiceEntityId === void 0 || item.media.voice === void 0) throw new Error("Generated speech requires an explicit Voice identity");
+				if (incidentRelations(draft, speech.entityId).filter((relation) => relation.relationKind === "phonetic-script-render").length > 0) throw new Error(`Speech Audio "${speech.entityId}" already has render lineage`);
+				draft.relations.push(this.createRelation(draft, "phonetic-script-render", speech.entityId, scripts.phonetic.entityId, {}, {
+					...trace,
+					role: "speech-render"
+				}, stableEffectId("relation", identityScope, `speech:${index}:render`)));
+				const startMs = envelope.decisions.targetStartsMs[index];
+				let speechClipId;
+				if (!("targetSpeechClipEntityId" in item)) speechClipId = this.insertPlacedClipIntoDraft(draft, {
+					clipEntityId: stableEffectId("entity", identityScope, `speech:${index}:clip`),
+					markerEntityId: stableEffectId("entity", identityScope, `speech:${index}:marker`),
+					trackEntityId: speechTrack.entityId,
+					contentEntityId: speech.entityId,
+					sourceRange: {
+						start: 0,
+						end: item.media.durationMs
+					},
+					duration: {
+						mode: "fixed",
+						value: item.media.durationMs
+					},
+					placement: {
+						kind: "absolute",
+						targetRange: {
+							start: startMs,
+							end: startMs + item.media.durationMs
+						}
+					},
+					clipPayload: { volume: requireVolume(item.volume ?? 0) },
+					relationTrace: trace,
+					relationIds: {
+						trackClip: stableEffectId("relation", identityScope, `speech:${index}:track-clip`),
+						clipMarker: stableEffectId("relation", identityScope, `speech:${index}:clip-marker`),
+						markerContent: stableEffectId("relation", identityScope, `speech:${index}:marker-content`)
+					}
+				});
+				else {
+					const target = requireCanonicalClipOnRole(draft, item.targetSpeechClipEntityId, "speech");
+					if (target.trackRelation.endpoint0EntityId !== speechTrack.entityId) throw new Error("Replacement Speech occurrence is not on the frozen Speech Track");
+					speechClipId = target.clip.entityId;
+					replaceEntity(draft, target.clip.entityId, {
+						...target.clip,
+						payload: {
+							...target.clip.payload,
+							volume: requireVolume(item.volume ?? 0)
+						}
+					});
+					replaceRelationWithTrace(draft, target.markerContentRelation, target.marker.entityId, speech.entityId, {
+						...trace,
+						role: "speech-content"
+					}, stableEffectId("relation", identityScope, `speech:${index}:marker-content`));
+					const markerPayload = { ...cloneJsonObject(target.marker.payload, "Speech Marker payload") };
+					markerPayload.sourceRange = {
+						start: 0,
+						end: item.media.durationMs
+					};
+					markerPayload.duration = {
+						mode: "fixed",
+						value: item.media.durationMs
+					};
+					resizeAbsoluteTarget(markerPayload, item.media.durationMs);
+					replaceEntity(draft, target.marker.entityId, {
+						...target.marker,
+						payload: markerPayload
+					});
+				}
+				const currentCaptionIds = "targetCaptionClipEntityIds" in item ? item.targetCaptionClipEntityIds : [];
+				const itemCaptionIds = [];
+				for (const [captionIndex, caption] of item.captions.entries()) {
+					const durationMs = safeWholeMs(caption.endMs, "Speech Caption endMs") - safeWholeMs(caption.startMs, "Speech Caption startMs");
+					if (durationMs <= 0) throw new Error("Speech Caption must have positive duration");
+					const captionEntity = {
+						entityId: requireAvailableEntityId(draft, stableEffectId("entity", identityScope, `speech:${index}:caption:${captionIndex}`)),
+						entityKind: "caption",
+						payload: {
+							baseEntityIds: [scripts.audioScript.entityId],
+							selection: captionSelection(caption.selection),
+							durationMs
+						}
+					};
+					draft.entities.push(captionEntity);
+					assembleCaptionContent(draft, captionEntity.entityId);
+					const captionTrace = {
+						...trace,
+						role: "caption-content",
+						captionIndex
+					};
+					let captionClipId;
+					const existingCaptionId = currentCaptionIds[captionIndex];
+					if (!("targetSpeechClipEntityId" in item) || existingCaptionId === void 0) captionClipId = this.insertPlacedClipIntoDraft(draft, {
+						clipEntityId: stableEffectId("entity", identityScope, `speech:${index}:caption:${captionIndex}:clip`),
+						markerEntityId: stableEffectId("entity", identityScope, `speech:${index}:caption:${captionIndex}:marker`),
+						trackEntityId: captionTrack.entityId,
+						contentEntityId: captionEntity.entityId,
+						sourceRange: {
+							start: 0,
+							end: durationMs
+						},
+						duration: {
+							mode: "fixed",
+							value: durationMs
+						},
+						placement: {
+							kind: "absolute",
+							targetRange: {
+								start: startMs + caption.startMs,
+								end: startMs + caption.endMs
+							}
+						},
+						relationTrace: captionTrace,
+						relationIds: {
+							trackClip: stableEffectId("relation", identityScope, `speech:${index}:caption:${captionIndex}:track-clip`),
+							clipMarker: stableEffectId("relation", identityScope, `speech:${index}:caption:${captionIndex}:clip-marker`),
+							markerContent: stableEffectId("relation", identityScope, `speech:${index}:caption:${captionIndex}:marker-content`)
+						}
+					});
+					else {
+						const targetCaption = requireCanonicalClipOnRole(draft, existingCaptionId, "caption");
+						if (targetCaption.trackRelation.endpoint0EntityId !== captionTrack.entityId) throw new Error("Replacement Caption occurrence is not on the frozen Caption Track");
+						captionClipId = targetCaption.clip.entityId;
+						replaceRelationWithTrace(draft, targetCaption.markerContentRelation, targetCaption.marker.entityId, captionEntity.entityId, captionTrace, stableEffectId("relation", identityScope, `speech:${index}:caption:${captionIndex}:marker-content`));
+						replaceEntity(draft, targetCaption.marker.entityId, {
+							...targetCaption.marker,
+							payload: {
+								...targetCaption.marker.payload,
+								sourceRange: {
+									start: 0,
+									end: durationMs
+								},
+								duration: {
+									mode: "fixed",
+									value: durationMs
+								},
+								targetRange: {
+									start: startMs + caption.startMs,
+									end: startMs + caption.endMs
+								}
+							}
+						});
+					}
+					itemCaptionIds.push(captionClipId);
+				}
+				for (const retiredCaptionId of currentCaptionIds.slice(item.captions.length)) {
+					const retired = requireCanonicalClipOnRole(draft, retiredCaptionId, "caption");
+					if (retired.trackRelation.endpoint0EntityId !== envelope.decisions.captionTrackEntityId) throw new Error("Retired Caption occurrence is not on the frozen Caption Track");
+					retireClipOccurrence(draft, retired);
+				}
+				speechClipEntityIds.push(speechClipId);
+				speechAudioEntityIds.push(speech.entityId);
+				audioScriptEntityIds.push(scripts.audioScript.entityId);
+				phoneticScriptEntityIds.push(scripts.phonetic.entityId);
+				captionClipEntityIds.push(itemCaptionIds);
+			}
+			return {
+				speechClipEntityIds,
+				speechAudioEntityIds,
+				audioScriptEntityIds,
+				phoneticScriptEntityIds,
+				captionClipEntityIds
+			};
+		});
+	}
+	static compileSpeechAssetsEffect(base, envelope) {
+		assertSpeechAssetsEnvelope(envelope);
+		consumeEffectEnvelope(consumedSpeechEnvelopes, envelope, "Speech");
+		const current = cloneRows(base.snapshot().rows);
+		const replay = resolveSpeechAssetsReplay(current, envelope);
+		if (replay !== void 0) return {
+			result: replay,
+			replayed: true,
+			rows: current
+		};
+		const fingerprint = captionBaselineFingerprint(base);
+		if (fingerprint !== envelope.baselineFingerprint) throw new Error("Speech effect baseline changed; prepare a new effect from the authority");
+		if (canonicalJson(resolveSpeechEffectDecisions(current, envelope.input, envelope.effectId, fingerprint)) !== canonicalJson(envelope.decisions)) throw new Error("Speech effect decisions no longer match the frozen causal baseline");
+		const doc = base.doc.fork();
+		doc.setPeerId(stableEffectPeerId(speechAssetsCommand, envelope.effectId, fingerprint));
+		const staged = new LoroEntityDocument(doc);
+		const editor = new EntityTimelineEditor(staged.snapshot().rows, stableEffectIdFactory(stableEffectScope(speechAssetsCommand, envelope.effectId, fingerprint), "speech-editor"));
+		editor.#applySpeechAssets(envelope);
+		const applied = applyEntityRows(staged, editor.rows());
+		const result = resolveSpeechAssetsReplay(cloneRows(applied.state.rows), envelope);
+		if (result === void 0) throw new Error("Committed Speech effect is missing its complete receipt");
+		return {
+			result,
+			replayed: false,
+			update: applied.update,
+			rows: applied.state.rows
+		};
+	}
 	insertPlacedClipIntoDraft(draft, input) {
 		const track = requireEntityKind(draft, input.trackEntityId, "track");
 		requireTrackTimeline(draft, track.entityId);
 		const content = requireSequenceContent(draft, input.contentEntityId);
 		const clipId = input.clipEntityId === void 0 ? this.mintEntityId(draft) : requireAvailableEntityId(draft, input.clipEntityId);
-		const markerId = this.mintEntityId(draft);
+		const markerId = input.markerEntityId === void 0 ? this.mintEntityId(draft) : requireAvailableEntityId(draft, input.markerEntityId);
 		const clipPayload = { ...cloneJsonObject(input.clipPayload ?? {}, "Clip payload") };
 		delete clipPayload.order;
 		const markerPlacement = applyPlacementPayload(clipPayload, input.placement);
@@ -1474,7 +1963,7 @@ var EntityTimelineEditor = class {
 			})
 		};
 		draft.entities.push(clip, marker);
-		draft.relations.push(this.createRelation(draft, "track-clip", track.entityId, clipId), this.createRelation(draft, "clip-marker", clipId, markerId), this.createRelation(draft, "marker-content", markerId, content.entityId));
+		draft.relations.push(this.createRelation(draft, "track-clip", track.entityId, clipId, {}, input.relationTrace, input.relationIds?.trackClip), this.createRelation(draft, "clip-marker", clipId, markerId, {}, input.relationTrace, input.relationIds?.clipMarker), this.createRelation(draft, "marker-content", markerId, content.entityId, {}, input.relationTrace, input.relationIds?.markerContent));
 		if (input.placement.kind === "anchored") {
 			const host = requireEntityKind(draft, input.placement.hostClipEntityId, "clip");
 			if (host.entityId === clipId) throw new Error("A Clip cannot anchor to itself");
@@ -1780,14 +2269,14 @@ var EntityTimelineEditor = class {
 		if (draft.entities.some((entity) => entity.entityId === entityId)) throw new Error(`Entity id "${entityId}" already exists`);
 		return entityId;
 	}
-	createRelation(draft, relationKind, endpoint0EntityId, endpoint1EntityId, metadata = {}) {
+	createRelation(draft, relationKind, endpoint0EntityId, endpoint1EntityId, metadata = {}, trace = {}, requestedRelationId) {
 		return {
-			relationId: this.mintRelationId(draft),
+			relationId: requestedRelationId === void 0 ? this.mintRelationId(draft) : requireAvailableRelationId(draft, requestedRelationId),
 			relationKind,
 			endpoint0EntityId,
 			endpoint1EntityId,
 			metadata,
-			trace: {}
+			trace
 		};
 	}
 	relinkRelation(draft, relation, endpoints) {
@@ -1806,6 +2295,859 @@ var EntityTimelineEditor = class {
 		return relationId;
 	}
 };
+/** Freeze every state-dependent choice once in the sole FE tool-effect handler. */
+function prepareCaptionAssetsEffect(base, rawInput) {
+	const effectId = requireTrimmed(rawInput.effectId, "Caption effect id");
+	const segments = validateAsrSegments(rawInput.segments);
+	const input = structuredClone({
+		...rawInput,
+		effectId,
+		segments
+	});
+	const rows = cloneRows(base.snapshot().rows);
+	const signature = captionEffectSignature(input, segments);
+	const baselineFingerprint = captionBaselineFingerprint(base);
+	return deepFreeze({
+		version: 1,
+		baselineFingerprint,
+		effectId,
+		signature,
+		input,
+		decisions: resolveCaptionEffectDecisions(rows, input, stableEffectScope(captionAssetsCommand, effectId, baselineFingerprint), segments)
+	});
+}
+/**
+* Compile only a frozen envelope on its exact causal baseline. Collaborators
+* receive the resulting Loro update, never the raw effect.
+*/
+function compileCaptionAssetsEffect(base, envelope) {
+	return EntityTimelineEditor.compileCaptionAssetsEffect(base, envelope);
+}
+const captionAssetsCommand = "apply-caption-assets";
+const generatedVisualsCommand = "add-generated-visuals";
+const speechAssetsCommand = "apply-speech-assets";
+const consumedGeneratedVisualEnvelopes = /* @__PURE__ */ new Set();
+const consumedSpeechEnvelopes = /* @__PURE__ */ new Set();
+function consumeEffectEnvelope(consumed, envelope, label) {
+	const key = `${envelope.baselineFingerprint}\u0000${envelope.effectId}\u0000${envelope.signature}`;
+	if (consumed.has(key)) throw new Error(`${label} effect envelope is one-shot; retain and retry the compiled Loro update bytes`);
+	consumed.add(key);
+}
+/** Freeze the explicit insertion anchor and lineage on one causal baseline. */
+function prepareGeneratedVisualEffect(base, rawInput) {
+	const effectId = requireTrimmed(rawInput.effectId, "Generated visual effect id");
+	if (rawInput.clips.length === 0) throw new Error("Generated visual effect requires at least one clip");
+	const clips = rawInput.clips.map((clip, index) => {
+		const generationJobId = requireTrimmed(clip.generationJobId, `Generated visual ${index} generation job id`);
+		const durationMs = safeWholeMs(clip.durationMs, `Generated visual ${index} durationMs`);
+		if (durationMs === 0 || clip.media.kind === "video" && durationMs > clip.media.durationMs) throw new Error(`Generated visual ${index} duration must fit its immutable media Sequence`);
+		if (clip.sourceMediaEntityIds.length === 0) throw new Error(`Generated visual ${index} requires explicit source lineage`);
+		const sourceMediaEntityIds = clip.sourceMediaEntityIds.map((sourceId) => requireTrimmed(sourceId, `Generated visual ${index} source media id`));
+		if (new Set(sourceMediaEntityIds).size !== sourceMediaEntityIds.length) throw new Error(`Generated visual ${index} source lineage must be unique`);
+		return {
+			...structuredClone(clip),
+			durationMs,
+			generationJobId,
+			sourceMediaEntityIds
+		};
+	});
+	const input = structuredClone({
+		...rawInput,
+		effectId,
+		clips
+	});
+	const rows = cloneRows(base.snapshot().rows);
+	for (const [index, clip] of input.clips.entries()) for (const sourceId of clip.sourceMediaEntityIds) {
+		const source = requireSequenceContent(rows, sourceId);
+		if (![
+			"video",
+			"image",
+			"audio"
+		].includes(source.entityKind)) throw new Error(`Generated visual ${index} source must be Video, Image, or Audio`);
+	}
+	return deepFreeze({
+		version: 1,
+		baselineFingerprint: captionBaselineFingerprint(base),
+		effectId,
+		signature: generatedVisualSignature(input),
+		input,
+		decisions: resolveGeneratedVisualDecisions(rows, input)
+	});
+}
+function prepareContinueVideoEffect(base, input) {
+	const rows = cloneRows(base.snapshot().rows);
+	requireEntityKind(rows, input.sourceMediaEntityId, "video");
+	requireEntityKind(rows, input.tailFrameEntityId, "image");
+	return prepareGeneratedVisualEffect(base, {
+		effectId: input.effectId,
+		timelineEntityId: input.timelineEntityId,
+		afterClipEntityId: input.afterClipEntityId,
+		clips: [{
+			media: input.media,
+			durationMs: input.media.durationMs,
+			generationJobId: input.effectId,
+			sourceMediaEntityIds: [input.sourceMediaEntityId, input.tailFrameEntityId]
+		}]
+	});
+}
+/** Compile once at the FE authority; retain the returned update bytes for retry and collaborators. */
+function compileGeneratedVisualEffect(base, envelope) {
+	return EntityTimelineEditor.compileGeneratedVisualEffect(base, envelope);
+}
+function prepareSpeechAssetsEffect(base, rawInput) {
+	for (const item of rawInput.value.items) if (item.source.kind === "audio-script") if (item.source.audioScriptEntityId === void 0) audioScriptSegmentsFromAsr(item.source.segments, false);
+	else validateResolvedAsrSegments(item.source.segments);
+	else validateScriptSegments(item.source.segments);
+	const value = structuredClone(rawInput.value);
+	const effectId = requireTrimmed(value.effectId, "Speech effect id");
+	if (value.items.length === 0) throw new Error("Speech effect requires at least one item");
+	if (new Set(value.items.map((item) => item.media.assetId)).size !== value.items.length) throw new Error("Speech effect media assets must be unique");
+	const input = structuredClone({
+		...rawInput,
+		value: {
+			...value,
+			effectId
+		}
+	});
+	const baselineFingerprint = captionBaselineFingerprint(base);
+	return deepFreeze({
+		version: 1,
+		baselineFingerprint,
+		effectId,
+		signature: speechEffectSignature(input),
+		input,
+		decisions: resolveSpeechEffectDecisions(cloneRows(base.snapshot().rows), input, effectId, baselineFingerprint)
+	});
+}
+/** Compile once at the FE authority; retain the returned update bytes for retry and collaborators. */
+function compileSpeechAssetsEffect(base, envelope) {
+	return EntityTimelineEditor.compileSpeechAssetsEffect(base, envelope);
+}
+function validateAsrSegments(segments) {
+	if (segments.length === 0) throw new Error("Caption assets require at least one ASR segment");
+	const ids = /* @__PURE__ */ new Set();
+	return segments.map((segment) => {
+		const segmentId = requireTrimmed(segment.segmentId, "ASR segment id");
+		if (ids.has(segmentId)) throw new Error(`Duplicate ASR segment id "${segmentId}"`);
+		ids.add(segmentId);
+		if (typeof segment.text !== "string" || segment.text.trim() === "") throw new Error(`ASR segment "${segmentId}" requires visible text`);
+		const startMs = safeWholeMs(segment.startMs, `ASR segment "${segmentId}" startMs`);
+		const endMs = safeWholeMs(segment.endMs, `ASR segment "${segmentId}" endMs`);
+		if (endMs <= startMs) throw new Error(`ASR segment "${segmentId}" must have positive duration`);
+		const language = segment.language === void 0 ? void 0 : requireTrimmed(segment.language, `ASR segment "${segmentId}" language`);
+		return {
+			segmentId,
+			text: segment.text,
+			startMs,
+			endMs,
+			...language === void 0 ? {} : { language }
+		};
+	});
+}
+function requireCanonicalCaptionTrack(rows, timelineEntityId, trackEntityId) {
+	const timeline = requireEntityKind(rows, timelineEntityId, "timeline");
+	const track = requireEntityKind(rows, trackEntityId, "track");
+	if (track.payload.role !== "caption") throw new Error(`Track "${track.entityId}" must have role "caption"`);
+	const bindings = incidentRelations(rows, track.entityId).filter((relation) => relation.relationKind === "timeline-track");
+	if (bindings.length !== 1) throw new Error(`Caption Track "${track.entityId}" must have one unambiguous Timeline`);
+	const binding = bindings[0];
+	if (binding.endpoint0EntityId !== timeline.entityId || binding.endpoint1EntityId !== track.entityId) throw new Error("timeline-track must use ordered endpoints [Timeline, Track]");
+	return track;
+}
+function resolveSourceOccurrence(rows, input, sourceEntityId) {
+	const clip = requireEntityKind(rows, input.sourceOccurrence.clipEntityId, "clip");
+	const marker = requireEntityKind(rows, input.sourceOccurrence.markerEntityId, "sequence-marker");
+	const clipMarkers = incidentRelations(rows, clip.entityId).filter((relation) => relation.relationKind === "clip-marker");
+	if (clipMarkers.length !== 1 || clipMarkers[0].endpoint0EntityId !== clip.entityId || clipMarkers[0].endpoint1EntityId !== marker.entityId) throw new Error("Source occurrence requires one ordered clip-marker [Clip, SequenceMarker]");
+	const contents = incidentRelations(rows, marker.entityId).filter((relation) => relation.relationKind === "marker-content");
+	if (contents.length !== 1 || contents[0].endpoint0EntityId !== marker.entityId || contents[0].endpoint1EntityId !== sourceEntityId) throw new Error("Source occurrence requires one ordered marker-content [SequenceMarker, source Entity]");
+	const trackBindings = incidentRelations(rows, clip.entityId).filter((relation) => relation.relationKind === "track-clip");
+	if (trackBindings.length !== 1 || trackBindings[0].endpoint1EntityId !== clip.entityId) throw new Error("Source occurrence requires one ordered track-clip [Track, Clip]");
+	const sourceTrack = requireEntityKind(rows, trackBindings[0].endpoint0EntityId, "track");
+	const timelineBindings = incidentRelations(rows, sourceTrack.entityId).filter((relation) => relation.relationKind === "timeline-track");
+	if (timelineBindings.length !== 1 || timelineBindings[0].endpoint0EntityId !== input.timelineEntityId || timelineBindings[0].endpoint1EntityId !== sourceTrack.entityId) throw new Error("Source occurrence must be placed on the selected Timeline through [Timeline, Track]");
+	const placement = resolveEntityTimelineLayout(rows).clips.get(clip.entityId);
+	if (placement === void 0 || placement.markerEntityId !== marker.entityId || placement.contentEntityId !== sourceEntityId) throw new Error("Source occurrence is not an unambiguous placed use of the selected source Entity");
+	const sourceRange = requirePositiveRange(marker.payload.sourceRange, "Source occurrence sourceRange");
+	return {
+		sourceRange,
+		timelineStart: placement.start,
+		rate: (sourceRange.end - sourceRange.start) / placement.duration
+	};
+}
+function occurrenceTargetRange(occurrence, segment) {
+	if (segment.startMs < occurrence.sourceRange.start || segment.endMs > occurrence.sourceRange.end) throw new Error(`ASR segment "${segment.segmentId}" is outside the selected source occurrence`);
+	const start = Math.round(occurrence.timelineStart + (segment.startMs - occurrence.sourceRange.start) / occurrence.rate);
+	const end = Math.round(occurrence.timelineStart + (segment.endMs - occurrence.sourceRange.start) / occurrence.rate);
+	if (end <= start) throw new Error(`ASR segment "${segment.segmentId}" collapses under the occurrence time mapping`);
+	return {
+		start,
+		end
+	};
+}
+function resolveCaptionEffectDecisions(rows, input, identityScope, segments) {
+	const source = requireEntityKind(rows, input.source.entityId, input.source.entityKind);
+	requireCanonicalCaptionTrack(rows, input.timelineEntityId, input.trackEntityId);
+	const occurrence = resolveSourceOccurrence(rows, input, source.entityId);
+	return {
+		sourceOccurrence: {
+			sourceStartMs: occurrence.sourceRange.start,
+			sourceEndMs: occurrence.sourceRange.end,
+			timelineStartMs: occurrence.timelineStart,
+			rate: occurrence.rate
+		},
+		targetRanges: segments.map((segment) => ({
+			segmentId: segment.segmentId,
+			...occurrenceTargetRange(occurrence, segment)
+		})),
+		captionAsset: resolveCaptionAssetDecision(rows, input, identityScope)
+	};
+}
+function resolveCaptionAssetDecision(rows, input, identityScope) {
+	const assetId = requireTrimmed(input.captionAsset.assetId, "Caption asset id");
+	const storageKey = input.captionAsset.storageKey === void 0 ? void 0 : requireTrimmed(input.captionAsset.storageKey, "Caption asset storage key");
+	const matches = rows.entities.filter((row) => row.entityKind === "asset" && row.payload.system === "memota" && row.payload.key === assetId);
+	if (matches.length > 1) throw new Error(`Caption Asset "${assetId}" is ambiguous`);
+	const existing = matches[0];
+	if (existing === void 0) return {
+		mode: "create",
+		resultAssetEntityId: stableEffectId("entity", identityScope, "caption-asset:entity:0"),
+		reboundRelationIds: []
+	};
+	if (storageKey === void 0 || existing.payload.storageKey === storageKey) return {
+		mode: "reuse",
+		priorAssetEntityId: existing.entityId,
+		resultAssetEntityId: existing.entityId,
+		reboundRelationIds: []
+	};
+	if (existing.payload.storageKey !== void 0) throw new Error(`Caption Asset "${assetId}" conflicts with its existing storage key`);
+	const bindings = rows.relations.filter((relation) => relation.relationKind === "from-asset" && (relation.endpoint0EntityId === existing.entityId || relation.endpoint1EntityId === existing.entityId)).map((relation) => String(relation.relationId)).sort();
+	return {
+		mode: "replace",
+		priorAssetEntityId: existing.entityId,
+		resultAssetEntityId: stableEffectId("entity", identityScope, "caption-asset:entity:0"),
+		reboundRelationIds: bindings
+	};
+}
+function captionBaselineFingerprint(base) {
+	const causal = bytesToHex(base.doc.oplogVersion().encode());
+	return bytesToHex(sha256(new TextEncoder().encode(canonicalJson({
+		causal,
+		state: base.snapshot()
+	}))));
+}
+function resolveSpeechEffectDecisions(rows, input, effectId, baselineFingerprint) {
+	const { value } = input;
+	requireEntityKind(rows, value.timelineEntityId, "timeline");
+	for (const item of value.items) if (item.source.kind === "phonetic-script") requirePersistedPhoneticSourceScript(rows, item.source);
+	else if (item.source.audioScriptEntityId !== void 0) requireAssetlessAsrSourceScript(rows, item.source);
+	const scope = stableEffectScope(speechAssetsCommand, effectId, baselineFingerprint);
+	const speechTrackEntityId = resolveEffectTrackId(rows, value.timelineEntityId, "speech", scope);
+	const captionTrackEntityId = value.items.some((item) => item.captions.length > 0 || "targetCaptionClipEntityIds" in item && item.targetCaptionClipEntityIds.length > 0) ? resolveEffectTrackId(rows, value.timelineEntityId, "caption", scope) : void 0;
+	if (input.mode === "add") return {
+		speechTrackEntityId,
+		...captionTrackEntityId === void 0 ? {} : { captionTrackEntityId },
+		targetStartsMs: input.value.items.map((item) => safeWholeMs(item.placementStartMs, "Speech placement startMs"))
+	};
+	const targets = input.value.items.map((item) => item.targetSpeechClipEntityId);
+	if (new Set(targets).size !== targets.length) throw new Error("Replacement Speech targets must be unique");
+	const captionTargets = input.value.items.flatMap((item) => item.targetCaptionClipEntityIds);
+	if (new Set(captionTargets).size !== captionTargets.length) throw new Error("Replacement Caption targets must be unique across the effect");
+	const layout = resolveEntityTimelineLayout(rows);
+	const starts = input.value.items.map((item) => {
+		const target = requireCanonicalClipOnRole(rows, item.targetSpeechClipEntityId, "speech");
+		if (target.trackRelation.endpoint0EntityId !== speechTrackEntityId || target.trackRelation.endpoint1EntityId !== target.clip.entityId) throw new Error("Replacement Speech target must use ordered Track/Clip endpoints");
+		for (const captionId of item.targetCaptionClipEntityIds) {
+			const caption = requireCanonicalClipOnRole(rows, captionId, "caption");
+			if (captionTrackEntityId === void 0 || caption.trackRelation.endpoint0EntityId !== captionTrackEntityId || caption.trackRelation.endpoint1EntityId !== caption.clip.entityId) throw new Error("Replacement Caption target must use ordered Track/Clip endpoints");
+		}
+		const placed = layout.clips.get(target.clip.entityId);
+		if (placed === void 0) throw new Error(`Replacement Speech Clip "${target.clip.entityId}" is not placed`);
+		return placed.start;
+	});
+	return {
+		speechTrackEntityId,
+		...captionTrackEntityId === void 0 ? {} : { captionTrackEntityId },
+		targetStartsMs: starts
+	};
+}
+function resolveEffectTrackId(rows, timelineEntityId, role, identityScope) {
+	if (rows.relations.filter((relation) => relation.relationKind === "timeline-track" && relation.endpoint1EntityId === timelineEntityId).length > 0) throw new Error("timeline-track must use ordered endpoints [Timeline, Track]");
+	const candidates = rows.relations.filter((relation) => relation.relationKind === "timeline-track" && relation.endpoint0EntityId === timelineEntityId).map((relation) => requireEntityKind(rows, relation.endpoint1EntityId, "track")).filter((track) => track.payload.role === role);
+	if (candidates.length > 1) throw new Error(`${role} Track is ambiguous`);
+	return candidates[0]?.entityId ?? createEntityId(stableEffectId("entity", identityScope, `track:${role}`));
+}
+function ensureEffectRoleTrack(rows, timelineEntityId, role, expectedTrackId, identityScope) {
+	const resolved = resolveEffectTrackId(rows, timelineEntityId, role, identityScope);
+	if (resolved !== expectedTrackId) throw new Error(`Frozen ${role} Track decision changed`);
+	if (rows.entities.find((entity) => entity.entityId === resolved) !== void 0) return requireEntityKind(rows, resolved, "track");
+	const track = {
+		entityId: createEntityId(expectedTrackId),
+		entityKind: "track",
+		payload: {
+			role,
+			order: roleOrder[role]
+		}
+	};
+	rows.entities.push(track);
+	rows.relations.push({
+		relationId: createRelationId(stableEffectId("relation", identityScope, `timeline-track:${role}`)),
+		relationKind: "timeline-track",
+		endpoint0EntityId: createEntityId(timelineEntityId),
+		endpoint1EntityId: track.entityId,
+		metadata: {},
+		trace: {}
+	});
+	return track;
+}
+function materializeSpeechSource(rows, item, identityScope, itemIndex, trace) {
+	const source = item.source;
+	const segments = source.kind === "audio-script" ? audioScriptSegmentsFromAsr(source.segments, source.audioScriptEntityId !== void 0) : validateScriptSegments(source.segments);
+	const requestedScriptId = source.audioScriptEntityId === void 0 ? stableEffectId("entity", identityScope, `speech:${itemIndex}:audio-script`) : requireTrimmed(source.audioScriptEntityId, "AudioScript entity id");
+	const existingScript = rows.entities.find((entity) => entity.entityId === requestedScriptId);
+	let audioScript;
+	if (existingScript === void 0) {
+		if (source.kind === "phonetic-script") throw new Error(`Phonetic Speech source AudioScript "${requestedScriptId}" must already exist with an Asset`);
+		audioScript = {
+			entityId: requireAvailableEntityId(rows, requestedScriptId),
+			entityKind: "audio-script",
+			payload: { segments }
+		};
+		rows.entities.push(audioScript);
+	} else {
+		audioScript = requireEntityKind(rows, requestedScriptId, "audio-script");
+		if (canonicalJson(audioScript.payload.segments) !== canonicalJson(segments)) throw new Error(`AudioScript "${requestedScriptId}" conflicts with the immutable Speech source`);
+		if (source.kind === "phonetic-script") requireCanonicalAudioScriptAsset(rows, audioScript.entityId);
+		else requireNoAudioScriptAsset(rows, audioScript.entityId, "ASR-composed");
+	}
+	if (source.kind === "audio-script") {
+		const timed = validateResolvedAsrSegments(source.segments);
+		if (source.sourceMediaEntityIds.length === 0) throw new Error("Audio Speech source requires media lineage");
+		for (const [sourceIndex, sourceId] of source.sourceMediaEntityIds.entries()) {
+			const media = requireSequenceContent(rows, sourceId);
+			if (media.entityKind !== "audio" && media.entityKind !== "video") throw new Error("audio-script-source requires Audio or Video input");
+			const existing = rows.relations.filter((relation) => relation.relationKind === "audio-script-source" && (relation.endpoint0EntityId === audioScript.entityId || relation.endpoint1EntityId === audioScript.entityId));
+			if (existing.some((relation) => relation.endpoint0EntityId !== audioScript.entityId)) throw new Error("audio-script-source must use ordered endpoints [AudioScript, source media]");
+			if (!existing.some((relation) => relation.endpoint1EntityId === media.entityId)) rows.relations.push({
+				relationId: createRelationId(stableEffectId("relation", identityScope, `speech:${itemIndex}:audio-source:${sourceIndex}`)),
+				relationKind: "audio-script-source",
+				endpoint0EntityId: audioScript.entityId,
+				endpoint1EntityId: media.entityId,
+				metadata: {},
+				trace: {
+					...trace,
+					role: "audio-script-source",
+					sourceIndex
+				}
+			});
+		}
+		const markerLinks = incidentRelations(rows, audioScript.entityId).filter((relation) => relation.relationKind === "audio-script-marker");
+		if (markerLinks.some((relation) => relation.endpoint0EntityId !== audioScript.entityId)) throw new Error("audio-script-marker must use ordered endpoints [AudioScript, annotation SequenceMarker]");
+		if (markerLinks.length > 1) throw new Error(`AudioScript "${audioScript.entityId}" has ambiguous timing annotations`);
+		const segmentRanges = timed.map((segment) => ({
+			segmentId: segment.segmentId,
+			startMs: segment.startMs,
+			endMs: segment.endMs
+		}));
+		if (markerLinks[0] !== void 0) {
+			if (canonicalJson(requireEntityKind(rows, markerLinks[0].endpoint1EntityId, "sequence-marker").payload.segmentRanges) !== canonicalJson(segmentRanges)) throw new Error(`AudioScript "${audioScript.entityId}" timing conflicts with the immutable Speech source`);
+		} else {
+			const markerId = stableEffectId("entity", identityScope, `speech:${itemIndex}:audio-script-marker`);
+			rows.entities.push({
+				entityId: createEntityId(markerId),
+				entityKind: "sequence-marker",
+				payload: {
+					sourceRange: {
+						start: source.sourceStartMs,
+						end: source.sourceStartMs + item.media.durationMs
+					},
+					duration: {
+						mode: "fixed",
+						value: item.media.durationMs
+					},
+					segmentRanges
+				}
+			});
+			rows.relations.push({
+				relationId: createRelationId(stableEffectId("relation", identityScope, `speech:${itemIndex}:script-marker`)),
+				relationKind: "audio-script-marker",
+				endpoint0EntityId: audioScript.entityId,
+				endpoint1EntityId: createEntityId(markerId),
+				metadata: {},
+				trace: {
+					...trace,
+					role: "audio-script-marker"
+				}
+			});
+		}
+	}
+	const phoneticId = source.kind === "phonetic-script" ? requireTrimmed(source.phoneticScriptEntityId, "PhoneticScript entity id") : stableEffectId("entity", identityScope, `speech:${itemIndex}:phonetic-script`);
+	const existingPhonetic = rows.entities.find((entity) => entity.entityId === phoneticId);
+	const phoneticPayload = {
+		baseEntityIds: [audioScript.entityId],
+		...source.kind === "phonetic-script" && source.phonemeScript !== void 0 ? { phonemeScript: source.phonemeScript } : {}
+	};
+	let phonetic;
+	if (existingPhonetic === void 0) {
+		phonetic = {
+			entityId: requireAvailableEntityId(rows, phoneticId),
+			entityKind: "phonetic-script",
+			payload: phoneticPayload
+		};
+		rows.entities.push(phonetic);
+	} else {
+		phonetic = requireEntityKind(rows, phoneticId, "phonetic-script");
+		if (canonicalJson(phonetic.payload) !== canonicalJson(phoneticPayload)) throw new Error(`PhoneticScript "${phoneticId}" conflicts with the immutable Speech source`);
+	}
+	assemblePhoneticScriptContent(rows, phonetic.entityId);
+	return {
+		audioScript,
+		phonetic
+	};
+}
+function requirePersistedPhoneticSourceScript(rows, source) {
+	const scriptId = requireTrimmed(source.audioScriptEntityId, "AudioScript entity id");
+	const audioScript = requireEntityKind(rows, scriptId, "audio-script");
+	const segments = validateScriptSegments(source.segments);
+	if (canonicalJson(audioScript.payload.segments) !== canonicalJson(segments)) throw new Error(`AudioScript "${scriptId}" conflicts with the immutable Speech source`);
+	requireCanonicalAudioScriptAsset(rows, audioScript.entityId);
+	return audioScript;
+}
+function requireAssetlessAsrSourceScript(rows, source) {
+	const scriptId = requireTrimmed(source.audioScriptEntityId, "AudioScript entity id");
+	const audioScript = requireEntityKind(rows, scriptId, "audio-script");
+	const segments = audioScriptSegmentsFromAsr(source.segments, true);
+	if (canonicalJson(audioScript.payload.segments) !== canonicalJson(segments)) throw new Error(`AudioScript "${scriptId}" conflicts with the immutable ASR source`);
+	requireNoAudioScriptAsset(rows, audioScript.entityId, "ASR-composed");
+	return audioScript;
+}
+function requireNoAudioScriptAsset(rows, audioScriptEntityId, label) {
+	if (incidentRelations(rows, audioScriptEntityId).filter((relation) => relation.relationKind === "from-asset").length > 0) throw new Error(`${label} AudioScript "${audioScriptEntityId}" must not have an Asset binding`);
+}
+function requireCanonicalAudioScriptAsset(rows, audioScriptEntityId) {
+	const bindings = incidentRelations(rows, audioScriptEntityId).filter((relation) => relation.relationKind === "from-asset");
+	if (bindings.length !== 1) throw new Error(`AudioScript "${audioScriptEntityId}" requires exactly one Asset binding`);
+	const binding = bindings[0];
+	if (binding.endpoint0EntityId !== audioScriptEntityId) throw new Error("from-asset must use ordered endpoints [AudioScript, Asset]");
+	const asset = requireEntityKind(rows, binding.endpoint1EntityId, "asset");
+	if (asset.payload.system !== "memota" || typeof asset.payload.key !== "string" || asset.payload.key.length === 0 || asset.payload.key.trim() !== asset.payload.key) throw new Error(`AudioScript Asset "${asset.entityId}" must state a canonical memota locator`);
+	return asset;
+}
+function validateScriptSegments(segments) {
+	if (segments.length === 0) throw new Error("Speech source requires at least one script segment");
+	const ids = /* @__PURE__ */ new Set();
+	return Array.from({ length: segments.length }, (_, index) => {
+		if (!Object.hasOwn(segments, index)) throw new Error("Speech source segments must not be sparse");
+		const value = segments[index];
+		const segment = strictJsonObject(value, `Speech source segment ${index}`);
+		if (typeof segment.segmentId !== "string") throw new Error("Speech source segment id must be a string");
+		const segmentId = requireTrimmed(segment.segmentId, "Speech source segment id");
+		if (ids.has(segmentId)) throw new Error(`Duplicate Speech source segment id "${segmentId}"`);
+		ids.add(segmentId);
+		if (typeof segment.text !== "string" || segment.text.trim() === "") throw new Error("Speech source text is required");
+		if (segment.language !== void 0 && typeof segment.language !== "string") throw new Error("Speech source language must be a string");
+		return {
+			...segment,
+			segmentId,
+			text: segment.text,
+			...segment.language === void 0 ? {} : { language: requireTrimmed(segment.language, "Speech source language") }
+		};
+	});
+}
+function validateResolvedAsrSegments(segments) {
+	return validateScriptSegments(segments).map((segment) => {
+		const segmentId = segment.segmentId;
+		const startMs = safeWholeMs(segment.startMs, `ASR segment "${segmentId}" startMs`);
+		const endMs = safeWholeMs(segment.endMs, `ASR segment "${segmentId}" endMs`);
+		if (endMs <= startMs) throw new Error(`ASR segment "${segmentId}" must have positive duration`);
+		return {
+			...segment,
+			segmentId,
+			text: segment.text,
+			startMs,
+			endMs
+		};
+	});
+}
+function audioScriptSegmentsFromAsr(segments, preserveResolvedFields) {
+	return validateResolvedAsrSegments(segments).map((timed) => {
+		if (!preserveResolvedFields) {
+			const allowed = new Set([
+				"segmentId",
+				"text",
+				"language",
+				"startMs",
+				"endMs"
+			]);
+			const extras = Object.keys(timed).filter((key) => !allowed.has(key));
+			if (extras.length > 0) throw new Error(`New ASR segment must not contain host-resolved fields: ${extras.join(", ")}`);
+			return {
+				segmentId: timed.segmentId,
+				text: timed.text,
+				...timed.language === void 0 ? {} : { language: timed.language }
+			};
+		}
+		const segment = { ...timed };
+		delete segment.startMs;
+		delete segment.endMs;
+		return segment;
+	});
+}
+function strictJsonObject(value, label) {
+	const clone = strictJsonValue(value, label, /* @__PURE__ */ new WeakSet());
+	if (!isJsonObject(clone)) throw new Error(`${label} must be a plain JSON object`);
+	return clone;
+}
+function strictJsonValue(value, label, seen) {
+	if (value === null || typeof value === "string" || typeof value === "boolean") return value;
+	if (typeof value === "number") {
+		if (!Number.isFinite(value)) throw new Error(`${label} must not contain non-finite JSON numbers`);
+		return value;
+	}
+	if (Array.isArray(value)) {
+		if (seen.has(value)) throw new Error(`${label} must not contain cyclic JSON values`);
+		seen.add(value);
+		const result = [];
+		for (let index = 0; index < value.length; index += 1) {
+			if (!Object.hasOwn(value, index)) throw new Error(`${label} must not contain sparse JSON arrays`);
+			result.push(strictJsonValue(value[index], `${label}[${index}]`, seen));
+		}
+		seen.delete(value);
+		return result;
+	}
+	if (typeof value !== "object" || value === void 0) throw new Error(`${label} must contain only JSON values`);
+	const prototype = Object.getPrototypeOf(value);
+	if (prototype !== Object.prototype && prototype !== null) throw new Error(`${label} must not contain objects with custom prototypes`);
+	if (seen.has(value)) throw new Error(`${label} must not contain cyclic JSON values`);
+	seen.add(value);
+	const result = {};
+	for (const [key, child] of Object.entries(value)) {
+		if (child === void 0) throw new Error(`${label}.${key} must not be undefined`);
+		result[key] = strictJsonValue(child, `${label}.${key}`, seen);
+	}
+	seen.delete(value);
+	return result;
+}
+function replaceRelationWithTrace(rows, previous, endpoint0EntityId, endpoint1EntityId, trace, relationId) {
+	rows.relations = rows.relations.filter((relation) => relation.relationId !== previous.relationId);
+	rows.relations.push({
+		relationId: requireAvailableRelationId(rows, relationId),
+		relationKind: previous.relationKind,
+		endpoint0EntityId,
+		endpoint1EntityId,
+		metadata: previous.metadata,
+		trace
+	});
+}
+/** Retire one editor use while retaining its immutable content row and Loro history. */
+function retireClipOccurrence(rows, topology) {
+	const removedRelations = new Set([
+		topology.trackRelation.relationId,
+		topology.clipMarkerRelation.relationId,
+		topology.markerContentRelation.relationId
+	]);
+	rows.relations = rows.relations.filter((relation) => !removedRelations.has(relation.relationId));
+	rows.entities = rows.entities.filter((entity) => entity.entityId !== topology.clip.entityId && entity.entityId !== topology.marker.entityId);
+}
+function speechEffectSignature(input) {
+	return bytesToHex(sha256(new TextEncoder().encode(canonicalJson(input))));
+}
+function speechEffectTrace(envelope, itemIndex) {
+	return {
+		command: speechAssetsCommand,
+		effectId: envelope.effectId,
+		signature: envelope.signature,
+		mode: envelope.input.mode,
+		itemIndex
+	};
+}
+function assertSpeechAssetsEnvelope(value) {
+	if (value.version !== 1 || !Object.isFrozen(value) || !Object.isFrozen(value.input) || !Object.isFrozen(value.decisions) || speechEffectSignature(value.input) !== value.signature || value.effectId !== value.input.value.effectId) throw new Error("Speech effect requires a canonical frozen envelope");
+}
+function resolveSpeechAssetsReplay(rows, envelope) {
+	const tagged = rows.relations.filter((relation) => relation.trace.command === speechAssetsCommand && relation.trace.effectId === envelope.effectId);
+	if (tagged.length === 0) return void 0;
+	if (tagged.some((relation) => relation.trace.signature !== envelope.signature)) throw new Error(`Speech effect "${envelope.effectId}" was already applied with different input`);
+	const result = {
+		speechClipEntityIds: [],
+		speechAudioEntityIds: [],
+		audioScriptEntityIds: [],
+		phoneticScriptEntityIds: [],
+		captionClipEntityIds: []
+	};
+	for (const [index, item] of envelope.input.value.items.entries()) {
+		const relations = tagged.filter((relation) => relation.trace.itemIndex === index);
+		const renders = relations.filter((relation) => relation.relationKind === "phonetic-script-render");
+		if (renders.length !== 1) throw new Error(`Speech effect item ${index} has an incomplete render receipt`);
+		const render = renders[0];
+		const audio = requireEntityKind(rows, render.endpoint0EntityId, "audio");
+		const phonetic = requireEntityKind(rows, render.endpoint1EntityId, "phonetic-script");
+		const audioScriptId = requireComposedAudioScript(rows, phonetic.entityId);
+		const contentRelations = relations.filter((relation) => relation.relationKind === "marker-content");
+		const speechContent = contentRelations.filter((relation) => relation.trace.role !== "caption-content");
+		if (speechContent.length !== 1 || speechContent[0].endpoint1EntityId !== audio.entityId) throw new Error(`Speech effect item ${index} has an incomplete Speech occurrence receipt`);
+		const speechClip = requireSingleClipForMarker(rows, requireEntityKind(rows, speechContent[0].endpoint0EntityId, "sequence-marker").entityId, "speech");
+		const captionIds = [];
+		for (let captionIndex = 0; captionIndex < item.captions.length; captionIndex += 1) {
+			const matches = contentRelations.filter((relation) => relation.trace.role === "caption-content" && relation.trace.captionIndex === captionIndex);
+			if (matches.length !== 1) throw new Error(`Speech effect item ${index} Caption receipt is incomplete`);
+			if (assembleCaptionContent(rows, requireEntityKind(rows, matches[0].endpoint1EntityId, "caption").entityId).audioScript.entityId !== audioScriptId) throw new Error("Speech Caption must retain the same AudioScript base");
+			captionIds.push(requireSingleClipForMarker(rows, matches[0].endpoint0EntityId, "caption").entityId);
+		}
+		result.speechClipEntityIds.push(speechClip.entityId);
+		result.speechAudioEntityIds.push(audio.entityId);
+		result.audioScriptEntityIds.push(audioScriptId);
+		result.phoneticScriptEntityIds.push(phonetic.entityId);
+		result.captionClipEntityIds.push(captionIds);
+	}
+	return result;
+}
+function requireSingleClipForMarker(rows, markerEntityId, role) {
+	const links = incidentRelations(rows, markerEntityId).filter((relation) => relation.relationKind === "clip-marker");
+	if (links.length !== 1 || links[0].endpoint1EntityId !== markerEntityId) throw new Error("clip-marker must use one ordered [Clip, SequenceMarker] relation");
+	return requireClipOnRole(rows, links[0].endpoint0EntityId, role).clip;
+}
+function resolveGeneratedVisualDecisions(rows, input) {
+	const timeline = requireEntityKind(rows, input.timelineEntityId, "timeline");
+	const anchorInput = visualInsertionAnchor(input);
+	const anchor = requireCanonicalClipOnRole(rows, anchorInput.clipEntityId, "video_clip");
+	const track = requireEntityKind(rows, anchor.trackRelation.endpoint0EntityId, "track");
+	if (anchor.trackRelation.endpoint1EntityId !== anchor.clip.entityId) throw new Error("track-clip must use ordered endpoints [Track, Clip]");
+	const timelineLinks = incidentRelations(rows, track.entityId).filter((relation) => relation.relationKind === "timeline-track");
+	if (timelineLinks.length !== 1) throw new Error(`Video Track "${track.entityId}" must have one unambiguous Timeline`);
+	const timelineLink = timelineLinks[0];
+	if (timelineLink.endpoint0EntityId !== timeline.entityId || timelineLink.endpoint1EntityId !== track.entityId) throw new Error("timeline-track must use ordered endpoints [Timeline, Track]");
+	const resolvedTrack = resolveEntityTimelineLayout(rows).tracks.find((candidate) => candidate.entityId === track.entityId);
+	const anchorOrder = resolvedTrack?.clips.findIndex((clip) => clip.clipEntityId === anchor.clip.entityId) ?? -1;
+	if (anchorOrder < 0) throw new Error(`Visual anchor Clip "${anchor.clip.entityId}" is not placed on its Track`);
+	if (resolvedTrack.clips.some((clip) => clip.mode !== "sequential")) throw new Error("Generated visual insertion requires a fully sequential Video Track");
+	const insertionIndex = anchorOrder + (anchorInput.position === "after" ? 1 : 0);
+	return {
+		trackEntityId: track.entityId,
+		anchorOrder,
+		anchorPosition: anchorInput.position,
+		insertionOrders: visualInsertionOrders(rows, resolvedTrack.clips.map((clip) => clip.clipEntityId), insertionIndex, input.clips.length)
+	};
+}
+function visualInsertionOrders(rows, orderedClipIds, insertionIndex, count) {
+	const orders = orderedClipIds.map((clipId) => {
+		const order = requireEntityKind(rows, clipId, "clip").payload.order;
+		if (typeof order !== "number" || !Number.isFinite(order)) throw new Error(`Sequential Clip "${clipId}" requires a finite order`);
+		return order;
+	});
+	if (orders.some((order, index) => index > 0 && order <= orders[index - 1])) throw new Error("Generated visual insertion requires unambiguous increasing Clip orders");
+	const lower = orders[insertionIndex - 1];
+	const upper = orders[insertionIndex];
+	if (lower === void 0) return Array.from({ length: count }, (_, index) => upper - count + index);
+	if (upper === void 0) return Array.from({ length: count }, (_, index) => lower + index + 1);
+	const gap = (upper - lower) / (count + 1);
+	const result = Array.from({ length: count }, (_, index) => lower + gap * (index + 1));
+	if (result.some((order, index) => !Number.isFinite(order) || order <= (index === 0 ? lower : result[index - 1]) || order >= upper)) throw new Error("Clip order precision is insufficient for generated visual insertion");
+	return result;
+}
+function visualInsertionAnchor(input) {
+	const before = input.beforeClipEntityId;
+	const after = input.afterClipEntityId;
+	if (before === void 0 === (after === void 0)) throw new Error("Generated visual effect requires exactly one before or after Clip anchor");
+	return before === void 0 ? {
+		position: "after",
+		clipEntityId: requireTrimmed(after, "After Clip anchor")
+	} : {
+		position: "before",
+		clipEntityId: requireTrimmed(before, "Before Clip anchor")
+	};
+}
+function generatedVisualSignature(input) {
+	return bytesToHex(sha256(new TextEncoder().encode(canonicalJson(input))));
+}
+function assertGeneratedVisualEnvelope(value) {
+	if (value.version !== 1 || !Object.isFrozen(value) || !Object.isFrozen(value.input) || !Object.isFrozen(value.decisions) || requireTrimmed(value.baselineFingerprint, "Generated visual baseline fingerprint") !== value.baselineFingerprint || requireTrimmed(value.effectId, "Generated visual effect id") !== value.effectId || generatedVisualSignature(value.input) !== value.signature) throw new Error("Generated visual effect requires a canonical frozen envelope");
+}
+function generatedVisualTrace(envelope, itemIndex, generationJobId, sourceIndex) {
+	return {
+		command: generatedVisualsCommand,
+		effectId: envelope.effectId,
+		signature: envelope.signature,
+		itemIndex,
+		generationJobId,
+		...sourceIndex === void 0 ? {} : { sourceIndex }
+	};
+}
+function resolveGeneratedVisualReplay(rows, envelope) {
+	const tagged = rows.relations.filter((relation) => relation.trace.command === generatedVisualsCommand && relation.trace.effectId === envelope.effectId);
+	if (tagged.length === 0) return void 0;
+	if (tagged.some((relation) => relation.trace.signature !== envelope.signature)) throw new Error(`Generated visual effect "${envelope.effectId}" was already applied with different input`);
+	const clipEntityIds = [];
+	const mediaEntityIds = [];
+	let expectedCount = 0;
+	for (const [index, clipInput] of envelope.input.clips.entries()) {
+		const item = tagged.filter((relation) => relation.trace.itemIndex === index);
+		const trackLink = requireGeneratedVisualRelation(item, "track-clip", index);
+		if (trackLink.endpoint0EntityId !== envelope.decisions.trackEntityId || requireEntityKind(rows, trackLink.endpoint1EntityId, "clip").entityId !== trackLink.endpoint1EntityId) throw new Error("track-clip must use ordered endpoints [Track, Clip]");
+		const clipEntityId = trackLink.endpoint1EntityId;
+		const markerLink = requireGeneratedVisualRelation(item, "clip-marker", index);
+		if (markerLink.endpoint0EntityId !== clipEntityId) throw new Error("clip-marker must use ordered endpoints [Clip, SequenceMarker]");
+		const marker = requireEntityKind(rows, markerLink.endpoint1EntityId, "sequence-marker");
+		const contentLink = requireGeneratedVisualRelation(item, "marker-content", index);
+		if (contentLink.endpoint0EntityId !== marker.entityId) throw new Error("marker-content must use ordered endpoints [SequenceMarker, media]");
+		const media = requireSequenceContent(rows, contentLink.endpoint1EntityId);
+		if (media.entityKind !== "video" && media.entityKind !== "image") throw new Error("Generated visual receipt must reference Video or Image output");
+		const lineage = item.filter((relation) => relation.relationKind === "generated");
+		if (lineage.length !== clipInput.sourceMediaEntityIds.length) throw new Error(`Generated visual ${index} has incomplete source lineage`);
+		for (const [sourceIndex, sourceId] of clipInput.sourceMediaEntityIds.entries()) {
+			const matches = lineage.filter((relation) => relation.trace.sourceIndex === sourceIndex);
+			if (matches.length !== 1 || matches[0].endpoint0EntityId !== media.entityId || matches[0].endpoint1EntityId !== sourceId) throw new Error("generated must use ordered endpoints [output media, input media]");
+		}
+		expectedCount += 3 + clipInput.sourceMediaEntityIds.length;
+		clipEntityIds.push(clipEntityId);
+		mediaEntityIds.push(media.entityId);
+	}
+	if (tagged.length !== expectedCount) throw new Error(`Generated visual effect "${envelope.effectId}" has an ambiguous relation receipt`);
+	return {
+		clipEntityIds,
+		mediaEntityIds
+	};
+}
+function requireGeneratedVisualRelation(relations, kind, itemIndex) {
+	const matches = relations.filter((relation) => relation.relationKind === kind);
+	if (matches.length !== 1) throw new Error(`Generated visual ${itemIndex} must have exactly one ${kind} Relation`);
+	return matches[0];
+}
+function assertCaptionAssetsEnvelope(value) {
+	if (value.version !== 1 || !Object.isFrozen(value) || !Object.isFrozen(value.input) || !Object.isFrozen(value.decisions) || requireTrimmed(value.baselineFingerprint, "Caption baseline fingerprint") !== value.baselineFingerprint || requireTrimmed(value.signature, "Caption effect signature") !== value.signature) throw new Error("Caption effect requires a canonical frozen envelope");
+}
+function deepFreeze(value) {
+	if (value !== null && typeof value === "object" && !Object.isFrozen(value)) {
+		for (const child of Object.values(value)) deepFreeze(child);
+		Object.freeze(value);
+	}
+	return value;
+}
+function captionEffectSignature(input, segments) {
+	const value = JSON.stringify({
+		timelineEntityId: input.timelineEntityId,
+		trackEntityId: input.trackEntityId,
+		source: {
+			entityId: input.source.entityId,
+			entityKind: input.source.entityKind
+		},
+		sourceOccurrence: {
+			clipEntityId: input.sourceOccurrence.clipEntityId,
+			markerEntityId: input.sourceOccurrence.markerEntityId
+		},
+		captionAsset: {
+			assetId: input.captionAsset.assetId,
+			...input.captionAsset.storageKey === void 0 ? {} : { storageKey: input.captionAsset.storageKey }
+		},
+		segments
+	});
+	return bytesToHex(sha256(new TextEncoder().encode(value)));
+}
+function effectTrace(effectId, signature, segmentId) {
+	return {
+		command: captionAssetsCommand,
+		effectId,
+		signature,
+		...segmentId === void 0 ? {} : { segmentId }
+	};
+}
+function stableEffectId(kind, effectId, localKey) {
+	return `${kind}_effect_${bytesToHex(sha256(new TextEncoder().encode(`${captionAssetsCommand}\u0000${effectId}\u0000${kind}\u0000${localKey}`))).slice(0, 40)}`;
+}
+function stableEffectScope(command, effectId, baselineFingerprint) {
+	return `${command}\u0000${effectId}\u0000${baselineFingerprint}`;
+}
+function stableEffectIdFactory(effectId, namespace) {
+	const counters = {
+		entity: 0,
+		relation: 0
+	};
+	return (kind) => stableEffectId(kind, effectId, `${namespace}:${kind}:${counters[kind]++}`);
+}
+function stableEffectPeerId(command, effectId, baselineFingerprint) {
+	const digest = sha256(new TextEncoder().encode(`${command}\u0000${effectId}\u0000${baselineFingerprint}\u0000loro-peer`));
+	return BigInt(`0x${bytesToHex(digest).slice(0, 15)}`).toString();
+}
+function isCaptionEffectRelation(relation, effectId) {
+	return relation.trace.command === captionAssetsCommand && relation.trace.effectId === effectId;
+}
+function resolveCaptionAssetsReplay(rows, input, effectId, signature, segments, sourceEntityId, trackEntityId) {
+	const tagged = rows.relations.filter((relation) => isCaptionEffectRelation(relation, effectId));
+	if (tagged.length === 0) return void 0;
+	if (tagged.some((relation) => relation.trace.signature !== signature)) throw new Error(`Caption effect "${effectId}" was already applied with different input`);
+	const sourceRelations = tagged.filter((relation) => relation.relationKind === "audio-script-source");
+	if (sourceRelations.length !== 1) throw new Error(`Caption effect "${effectId}" has an ambiguous source receipt`);
+	const sourceRelation = sourceRelations[0];
+	if (sourceRelation.endpoint1EntityId !== sourceEntityId) throw new Error("audio-script-source must use ordered endpoints [AudioScript, source media]");
+	const script = requireEntityKind(rows, sourceRelation.endpoint0EntityId, "audio-script");
+	if (!sameScriptSegments(script.payload.segments, segments)) throw new Error(`Caption effect "${effectId}" AudioScript no longer matches its immutable ASR result`);
+	const scriptMarkerRelations = tagged.filter((relation) => relation.relationKind === "audio-script-marker");
+	if (scriptMarkerRelations.length !== 1 || scriptMarkerRelations[0].endpoint0EntityId !== script.entityId) throw new Error("audio-script-marker must use ordered endpoints [AudioScript, annotation SequenceMarker]");
+	const scriptMarker = requireEntityKind(rows, scriptMarkerRelations[0].endpoint1EntityId, "sequence-marker");
+	if (!sameSegmentRanges(scriptMarker.payload.segmentRanges, segments)) throw new Error(`Caption effect "${effectId}" annotation Marker no longer matches its immutable ASR timing`);
+	let assetEntityId;
+	const captionEntityIds = [];
+	const captionClipEntityIds = [];
+	for (const segment of segments) {
+		const relations = tagged.filter((relation) => relation.trace.segmentId === segment.segmentId);
+		const assetLink = requireTaggedRelation(relations, "from-asset", segment.segmentId);
+		const caption = requireEntityKind(rows, assetLink.endpoint0EntityId, "caption");
+		const asset = requireEntityKind(rows, assetLink.endpoint1EntityId, "asset");
+		if (assetEntityId !== void 0 && asset.entityId !== assetEntityId) throw new Error(`Caption effect "${effectId}" references multiple Caption Assets`);
+		assetEntityId = asset.entityId;
+		if (asset.payload.system !== "memota" || asset.payload.key !== input.captionAsset.assetId || input.captionAsset.storageKey !== void 0 && asset.payload.storageKey !== input.captionAsset.storageKey) throw new Error(`Caption effect "${effectId}" Caption Asset does not match its receipt`);
+		const selection = caption.payload.selection;
+		const bases = caption.payload.baseEntityIds;
+		if (caption.payload.durationMs !== segment.endMs - segment.startMs || !isJsonObject(selection) || selection.segmentId !== segment.segmentId || !Array.isArray(bases) || bases.length !== 1 || bases[0] !== script.entityId) throw new Error(`Caption effect "${effectId}" Caption "${caption.entityId}" conflicts with its ASR segment`);
+		const contentLink = requireTaggedRelation(relations, "marker-content", segment.segmentId);
+		if (contentLink.endpoint1EntityId !== caption.entityId) throw new Error("marker-content must use ordered endpoints [SequenceMarker, Caption]");
+		const marker = requireEntityKind(rows, contentLink.endpoint0EntityId, "sequence-marker");
+		const markerLink = requireTaggedRelation(relations, "clip-marker", segment.segmentId);
+		if (markerLink.endpoint1EntityId !== marker.entityId) throw new Error("clip-marker must use ordered endpoints [Clip, SequenceMarker]");
+		const clip = requireEntityKind(rows, markerLink.endpoint0EntityId, "clip");
+		const trackLink = requireTaggedRelation(relations, "track-clip", segment.segmentId);
+		if (trackLink.endpoint0EntityId !== trackEntityId || trackLink.endpoint1EntityId !== clip.entityId) throw new Error("track-clip must use ordered endpoints [Track, Clip]");
+		captionEntityIds.push(caption.entityId);
+		captionClipEntityIds.push(clip.entityId);
+	}
+	if (assetEntityId === void 0 || tagged.length !== 2 + segments.length * 4) throw new Error(`Caption effect "${effectId}" has an incomplete or ambiguous relation receipt`);
+	return {
+		audioScriptEntityId: script.entityId,
+		audioScriptMarkerEntityId: scriptMarker.entityId,
+		captionAssetEntityId: assetEntityId,
+		captionEntityIds,
+		captionClipEntityIds
+	};
+}
+function requireTaggedRelation(relations, kind, segmentId) {
+	const matches = relations.filter((relation) => relation.relationKind === kind);
+	if (matches.length !== 1) throw new Error(`ASR segment "${segmentId}" must have exactly one ${kind} Relation`);
+	return matches[0];
+}
+function sameScriptSegments(value, segments) {
+	if (!Array.isArray(value) || value.length !== segments.length) return false;
+	return value.every((entry, index) => {
+		if (!isJsonObject(entry)) return false;
+		const expected = segments[index];
+		return entry.segmentId === expected.segmentId && entry.text === expected.text && entry.language === expected.language && Object.keys(entry).every((key) => key === "segmentId" || key === "text" || key === "language");
+	});
+}
+function sameSegmentRanges(value, segments) {
+	if (!Array.isArray(value) || value.length !== segments.length) return false;
+	return value.every((entry, index) => {
+		if (!isJsonObject(entry)) return false;
+		const expected = segments[index];
+		return entry.segmentId === expected.segmentId && entry.startMs === expected.startMs && entry.endMs === expected.endMs && Object.keys(entry).every((key) => key === "segmentId" || key === "startMs" || key === "endMs");
+	});
+}
+function requireTrimmed(value, label) {
+	if (typeof value !== "string" || value.length === 0 || value.trim() !== value) throw new Error(`${label} must be non-empty and trimmed`);
+	return value;
+}
+function safeWholeMs(value, label) {
+	if (!Number.isSafeInteger(value) || value < 0) throw new Error(`${label} must be a non-negative whole millisecond`);
+	return value;
+}
 function validateFinalRows(rows) {
 	decodeEntityRelationRows(rows, numericMarkerValidation);
 	assertCanonicalEditorResources(rows);
@@ -1843,6 +3185,16 @@ function requireClipTopology(rows, clipEntityId) {
 		markerContentRelation
 	};
 }
+function requireCanonicalClipOnRole(rows, clipEntityId, role) {
+	const topology = requireClipTopology(rows, clipEntityId);
+	if (topology.trackRelation.endpoint1EntityId !== topology.clip.entityId || topology.clipMarkerRelation.endpoint0EntityId !== topology.clip.entityId || topology.clipMarkerRelation.endpoint1EntityId !== topology.marker.entityId || topology.markerContentRelation.endpoint0EntityId !== topology.marker.entityId) throw new Error("Occurrence must use ordered Track→Clip→SequenceMarker→content endpoints");
+	const track = requireEntityKind(rows, topology.trackRelation.endpoint0EntityId, "track");
+	if (track.payload.role !== role) throw new Error(`Clip "${clipEntityId}" must belong to the ${role} Track`);
+	const timelineLinks = incidentRelations(rows, track.entityId).filter((relation) => relation.relationKind === "timeline-track");
+	if (timelineLinks.length !== 1 || timelineLinks[0].endpoint1EntityId !== track.entityId) throw new Error("timeline-track must use one ordered [Timeline, Track] relation");
+	requireEntityKind(rows, timelineLinks[0].endpoint0EntityId, "timeline");
+	return topology;
+}
 function requireOneRelation(rows, entityId, relationKind) {
 	const matches = incidentRelations(rows, entityId).filter((relation) => relation.relationKind === relationKind);
 	if (matches.length !== 1) throw new Error(`Entity "${entityId}" must have exactly one ${relationKind} Relation`);
@@ -1894,6 +3246,11 @@ function requireAvailableEntityId(rows, value) {
 	if (rows.entities.some((entity) => entity.entityId === entityId)) throw new Error(`Entity id "${entityId}" already exists`);
 	return entityId;
 }
+function requireAvailableRelationId(rows, value) {
+	const relationId = createRelationId(value);
+	if (rows.relations.some((relation) => relation.relationId === relationId)) throw new Error(`Relation id "${relationId}" already exists`);
+	return relationId;
+}
 function setClipOrder(rows, clipEntityId, order) {
 	const clip = requireEntityKind(rows, clipEntityId, "clip");
 	replaceEntity(rows, clip.entityId, {
@@ -1969,6 +3326,15 @@ function linearRate(value) {
 	if (!isJsonObject(value) || value.kind !== "linear") throw new Error("Only linear Clip time remapping is supported");
 	return finitePositive(value.rate, "linear speed rate");
 }
+function speedModeRate(mode) {
+	switch (mode) {
+		case "0.5x": return .5;
+		case "0.75x": return .75;
+		case "1.0x": return 1;
+		case "1.5x": return 1.5;
+		case "2.0x": return 2;
+	}
+}
 function resizeAbsoluteTarget(payload, duration) {
 	if (payload.targetRange === void 0) return;
 	const target = requirePositiveRange(payload.targetRange, "targetRange");
@@ -2034,15 +3400,7 @@ function migrateLegacyTimelineToEntities(legacy, assetFacts, initial = {
 	const normalizedMainRanges = overlapNormalizedMainRanges(legacy);
 	let entities = structuredClone([...initial.entities]);
 	let relations = structuredClone([...initial.relations]);
-	const documentAudioScriptEntityId = ensureDocumentAudioScript(entities) ?? (() => {
-		const id = createEntityId(idFactory("entity"));
-		entities.push({
-			entityId: id,
-			entityKind: "audio-script",
-			payload: { segments: [] }
-		});
-		return String(id);
-	})();
+	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}`);
@@ -5145,4 +6503,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, 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, compileCaptionAssetsEffect, compileEntityRows, compileGeneratedVisualEffect, compileSpeechAssetsEffect, createEditSandbox, createMirrorVideoDocument, createMirrorVideoDocumentAdapter, createPlainMemoryAdapter, decodeDocVersionMark, derivePositionFromAbs, effectiveVideoClipDurationMs, encodeDocVersionMark, ensureEditorFoundation, ensureLaneTrack, fillMainTrackTimeGaps, findComposedAudioScript, findLaneTrack, fromVideoDocument, generatePartId, getAt, hostForAbsMs, importCaptionAsset, importMediaAsset, isEmptyVideoClip, isImplementedSemanticOpKind, isMap, laneTrackId, mainTrackRanges, migrateLegacyTimelineToEntities, partDurationMs, partUnionSchema, prepareCaptionAssetsEffect, prepareCaptionContent, prepareContinueVideoEffect, prepareGeneratedVisualEffect, prepareSpeechAssetsEffect, projectEntityTimeline, readDocumentAudioScript, readEntityDocument, readMainTrackItems, readMengineEventStream, readPart, readPartDurationMs, readVideoDocumentFromDraft, reassignSpeechesToVideoClipsByTime, recalculateTimelineDuration, relativePositionForAbs, replayJournal, resolveAllSpeechOverlaps, resolveEntityTimelineLayout, resolveFieldPath, resolveSpeechOverlapByShiftingVideos, safeDurationMs, schemas_exports as schemas, selectAudioScriptSegment, snapshotToPlain, solveVideoDocument, speedOf, syncAggregatedClipsTimePosition, toVideoDocument, validateVideoDocument, videoDocumentMirrorSchema, videoDocumentSchema };