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

package/dist/index.js

@@ -1,6 +1,8 @@
-import { $ as cascadeAfterVideoClipChanges, A as selectAudioScriptSegment, B as derivePositionFromAbs, C as decodeEntityRelationRows, D as assemblePhoneticScriptContent, E as assembleEntityContent, F as createRelationId, G as validateVideoDocument, H as toVideoDocument, I as hasSequence, J as LANE_KINDS_IN_STACK_ORDER, K as partUnionSchema, L as isMediaAssetVariantKind, M as variantBaseEntityIds, N as isJsonObject, O as assembleScriptText, P as createEntityId, Q as solveVideoDocument, R as buildInitialVideoDocument, S as EntityTimelineProjectionError, T as assembleCaptionContent, U as VideoDocumentValidationError, V as fromVideoDocument, W as assertValidVideoDocument, X as findLaneTrack, Y as ensureLaneTrack, Z as laneTrackId, _ as assertFieldChanges, _t as recordEntries, a as applyEntityTimelineProjection, at as resolveSpeechOverlapByShiftingVideos, b as EntityProjectionGraph, bt as bytesToBase64, c as writeVideoDocumentToDraft, ct as isEmptyVideoClip, d as LoroEntityDocument, dt as DEFAULT_UNIT_TIME_MS, et as arrangeMainTrackSeamlessly, f as LoroEntityDraft, ft as ENTITY_TIMELINE_PROJECTION_SCHEMA_VERSION, g as applyFieldChanges, gt as partUnionToDraft, h as equalJson, ht as speedOf, i as MirrorVideoDocumentAdapter, it as resolveAllSpeechOverlaps, j as updateEntityFields, k as findComposedAudioScript, l as readVideoDocumentFromDraft, lt as partDurationMs, m as entityOrderGroups, mt as effectiveVideoClipDurationMs, n as createPlainMemoryAdapter, nt as reassignSpeechesToVideoClipsByTime, o as createMirrorVideoDocument, ot as syncAggregatedClipsTimePosition, p as readEntityDocument, pt as VIDEO_DOCUMENT_SCHEMA_VERSION, q as videoDocumentSchema, r as generatePartId, rt as recalculateTimelineDuration, s as createMirrorVideoDocumentAdapter, st as TIMELINE_SKELETON_DURATION_MS, t as PlainMemoryAdapter, tt as fillMainTrackTimeGaps, u as LORO_ENTITY_SCHEMA, ut as safeDurationMs, v as resolveFieldPath, vt as videoDocumentMirrorSchema, w as ScriptCompositionError, x as resolveEntityTimelineLayout, y as projectEntityTimeline, yt as base64ToBytes, z as buildSpeechHostMap } from "./document-BSAUud6c.js";
+import { $ as validateVideoDocument, A as EntityTimelineProjectionError, B as variantBaseEntityIds, C as equalJson, Ct as partUnionToDraft, D as projectEntityTimeline, Dt as bytesToBase64, E as resolveFieldPath, Et as base64ToBytes, F as assemblePhoneticScriptContent, G as isMediaAssetVariantKind, H as createEntityId, I as assembleScriptText, J as derivePositionFromAbs, K as buildInitialVideoDocument, L as findComposedAudioScript, M as ScriptCompositionError, N as assembleCaptionContent, O as EntityProjectionGraph, P as assembleEntityContent, Q as assertValidVideoDocument, R as selectAudioScriptSegment, S as canonicalJson, St as speedOf, T as assertFieldChanges, Tt as videoDocumentMirrorSchema, U as createRelationId, V as isJsonObject, W as hasSequence, X as toVideoDocument, Y as fromVideoDocument, Z as VideoDocumentValidationError, _ as audioScriptAssetOf, _t as isEmptyVideoClip, a as createMirrorVideoDocument, at as hasResolvedPlacement, b as phoneticScriptAssetOf, bt as DEFAULT_UNIT_TIME_MS, c as DocumentMutationGuard, ct as cascadeAfterVideoClipChanges, d as LoroEntityDraft, dt as reassignSpeechesToVideoClipsByTime, et as partUnionSchema, f as readEntityDocument, ft as recalculateTimelineDuration, g as audioScriptAssetHash, gt as TIMELINE_SKELETON_DURATION_MS, h as audioScriptAssetFields, ht as syncAggregatedClipsTimePosition, i as MirrorVideoDocumentAdapter, it as findLaneTrack, j as decodeEntityRelationRows, k as resolveEntityTimelineLayout, l as LORO_ENTITY_SCHEMA, lt as arrangeMainTrackSeamlessly, m as audioScriptAssetContent, mt as resolveSpeechOverlapByShiftingVideos, n as createPlainMemoryAdapter, nt as LANE_KINDS_IN_STACK_ORDER, o as createMirrorVideoDocumentAdapter, ot as laneTrackId, p as entityOrderGroups, pt as resolveAllSpeechOverlaps, q as buildSpeechHostMap, r as generatePartId, rt as ensureLaneTrack, s as readVideoDocumentFromDraft, st as solveVideoDocument, t as PlainMemoryAdapter, tt as videoDocumentSchema, u as LoroEntityDocument, ut as fillMainTrackTimeGaps, v as phoneticScriptAssetContent, vt as partDurationMs, w as applyFieldChanges, wt as recordEntries, x as scriptSourceAssetOf, xt as effectiveVideoClipDurationMs, y as phoneticScriptAssetHash, yt as safeDurationMs, z as updateEntityFields } from "./document-BXQcpnOg.js";
 import { addSpeechesInputSchema, addVideoClipsInputSchema, adjustBgmVolumeInputSchema, adjustSpeechVolumeInputSchema, adjustVideoClipDurationInputSchema, adjustVideoClipVolumeInputSchema, changeSpeechScriptInputSchema, changeSpeechVoiceInputSchema, deleteBgmInputSchema, deleteSpeechesInputSchema, deleteVideoClipsInputSchema, moveSpeechesInputSchema, moveVideoClipsByAnchorInputSchema, moveVideoClipsInputSchema, replaceVideoClipContentInputSchema, replaceVideoClipSequenceInputSchema, setBgmInputSchema, setCaptionStyleInputSchema, setCaptionVisibilityInputSchema, setVideoClipSpeedShiftInputSchema, t as schemas_exports } from "./schemas.js";
-import { LoroDoc, VersionVector } from "loro-crdt";
+import { LoroDoc, UndoManager, VersionVector } from "loro-crdt";
+import { 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";
@@ -60,12 +62,6 @@ var MengineHttpClient = class {
 	async fetchSnapshot() {
 		return await this.requestJson("snapshot");
 	}
-	async bootstrapSnapshot(snapshot) {
-		return await this.requestJson("bootstrap", {
-			method: "POST",
-			body: JSON.stringify({ snapshot: bytesToBase64(snapshot) })
-		});
-	}
 	/**
 	* Loro VV-diff pull: send the caller's oplog `VersionVector.encode` as `from`
 	* (omit for a full pull) and receive exactly the updates it is missing plus
@@ -168,9 +164,6 @@ async function safeReadJson$1(response) {
 //#endregion
 //#region src/client/sse.ts
 async function readMengineEventStream(options) {
-	const onUpdate = (event) => {
-		options.onUpdate(event);
-	};
 	const response = await options.client.fetch(options.client.eventsUrl(), {
 		headers: options.client.headers(),
 		signal: options.signal
@@ -189,15 +182,19 @@ async function readMengineEventStream(options) {
 		while (splitAt >= 0) {
 			const frame = buffer.slice(0, splitAt);
 			buffer = buffer.slice(buffer[splitAt] === "\r" ? splitAt + 4 : splitAt + 2);
-			handleSseFrame(frame, onUpdate);
+			handleSseFrame(frame, options);
 			splitAt = findSseFrameBoundary(buffer);
 		}
 	}
 }
-function handleSseFrame(frame, onUpdate) {
+function handleSseFrame(frame, options) {
 	const event = parseSseFrame(frame);
+	if (event.event === "resync") {
+		options.onResync?.();
+		return;
+	}
 	if (event.event !== "update" || event.data.length === 0) return;
-	onUpdate(JSON.parse(event.data.join("\n")));
+	options.onUpdate(JSON.parse(event.data.join("\n")));
 }
 function parseSseFrame(frame) {
 	let event = null;
@@ -226,7 +223,8 @@ function compileEntityRows(snapshot, rows, validate) {
 }
 /** Compile an edit on an existing peer, retaining its native local undo history. */
 function applyEntityRows(editor, rows) {
-	const before = editor.snapshot().rows;
+	const baseline = editor.snapshot();
+	const before = baseline.rows;
 	const oldEntities = new Map(before.entities.map((row) => [row.entityId, row]));
 	const newEntities = new Map(rows.entities.map((row) => [row.entityId, row]));
 	const oldRelations = new Map(before.relations.map((row) => [row.relationId, row]));
@@ -242,10 +240,16 @@ function applyEntityRows(editor, rows) {
 					if (!equalJson(row.metadata, next.metadata) || !equalJson(row.trace, next.trace)) draft.patchRelation(row.relationId, next.metadata, next.trace);
 				}
 			}
+			let attached = baseline.project.audioScriptEntityId !== void 0;
 			for (const row of rows.entities) {
 				const previous = oldEntities.get(row.entityId);
-				if (!previous) draft.create(row);
-				else {
+				if (!previous) {
+					draft.create(row);
+					if (!attached && row.entityKind === "audio-script") {
+						draft.attach("audioScriptEntityId", String(row.entityId));
+						attached = true;
+					}
+				} else {
 					if (previous.entityKind !== row.entityKind) throw new Error("Entity kind cannot change");
 					if (!equalJson(previous.payload, row.payload)) draft.replaceOwned(row.entityId, row.payload);
 				}
@@ -288,66 +292,59 @@ const roleOrder$1 = {
 /**
 * MEngine editor policy, not a cardinality restriction on the general-purpose DSL.
 *
-* Media variants share one entity identity with their Asset: every
-* Image/Video/Audio/Voice Entity must carry its own external locator, every
-* external asset id has exactly one claimant, and no media variant may be
-* bound through a legacy `physical-asset` Relation. Dual-entity media graphs
-* are rejected, not migrated. Caption composes AudioScript text and may associate with a physical text Asset.
+* Resources live on Asset entities and are reached through `from-asset`: no
+* other entity carries a locator, one Asset claims each `(system, key)` pair,
+* and media reaches at most one Asset. Media whose bytes are not named through
+* that Relation is rejected rather than guessed at.
 */
 function assertCanonicalEditorResources(rows) {
 	if (rows.entities.filter((row) => row.entityKind === "timeline").length > 1) throw new EntityTimelineProjectionError("Editor requires exactly one Timeline");
 	for (const role of Object.keys(roleOrder$1)) if (rows.entities.filter((row) => row.entityKind === "track" && row.payload.role === role).length > 1) throw new EntityTimelineProjectionError(`Editor has multiple ${role} Tracks`);
 	const identityByAssetKey = /* @__PURE__ */ new Map();
-	const kinds = new Map(rows.entities.map((row) => [String(row.entityId), row.entityKind]));
 	for (const entity of rows.entities) {
-		if (isMediaAssetVariantKind(entity.entityKind) && memotaLocator(entity.payload.external) === void 0) throw new EntityTimelineProjectionError(`Media Entity ${entity.entityId} must carry its own Asset external identity`);
-		if (entity.entityKind !== "asset" && !isMediaAssetVariantKind(entity.entityKind)) continue;
-		const external = entity.payload.external;
-		if (!isJsonObject(external) || external.system !== "memota" && external.system !== "memota-speech" || typeof external.key !== "string") continue;
-		const key = JSON.stringify([external.system, external.key]);
-		const previous = identityByAssetKey.get(key);
-		if (previous !== void 0 && previous !== entity.entityId) throw new EntityTimelineProjectionError(`Duplicate Asset for ${key}; reuse ${previous}`);
-		identityByAssetKey.set(key, entity.entityId);
+		if (entity.entityKind === "asset") {
+			const locator = memotaLocator(entity.payload);
+			if (locator === void 0) throw new EntityTimelineProjectionError(`Asset ${entity.entityId} must state where its bytes live`);
+			const key = JSON.stringify([locator.system, locator.key]);
+			const previous = identityByAssetKey.get(key);
+			if (previous !== void 0 && previous !== entity.entityId) throw new EntityTimelineProjectionError(`Duplicate Asset for ${key}; reuse ${previous}`);
+			identityByAssetKey.set(key, entity.entityId);
+			continue;
+		}
+		if (memotaLocator(entity.payload) !== void 0) throw new EntityTimelineProjectionError(`Entity ${entity.entityId} must not carry a locator; link its Asset with from-asset`);
 	}
-	for (const relation of rows.relations) {
-		if (relation.relationKind !== "physical-asset") continue;
-		const mediaEndpoint = [relation.endpoint0EntityId, relation.endpoint1EntityId].find((endpoint) => isMediaAssetVariantKind(kinds.get(String(endpoint)) ?? ""));
-		if (mediaEndpoint !== void 0) throw new EntityTimelineProjectionError(`Cannot bind media Entity ${mediaEndpoint} through physical-asset Relation ${relation.relationId}; media owns its Asset identity directly`);
+	for (const entity of rows.entities) {
+		if (!isMediaAssetVariantKind(entity.entityKind)) continue;
+		if (assetIdsOf(rows, entity.entityId).length !== 1) throw new EntityTimelineProjectionError(`Media Entity ${entity.entityId} requires exactly one from-asset Asset`);
 	}
 }
+/** The Asset ids one entity reaches, in row order. */
+function assetIdsOf(rows, entityId) {
+	const assets = new Set(rows.entities.filter((row) => row.entityKind === "asset").map((row) => String(row.entityId)));
+	return rows.relations.filter((relation) => relation.relationKind === "from-asset").map((relation) => String(relation.endpoint0EntityId) === entityId ? String(relation.endpoint1EntityId) : String(relation.endpoint1EntityId) === entityId ? String(relation.endpoint0EntityId) : void 0).filter((id) => id !== void 0 && assets.has(id));
+}
 /**
 * Commit-transition policy shared by the editor, the HTTP commit boundary, the
 * host tool, and the entity stores. It compares the authoritative before and
-* after rows of one CAS commit and enforces the single-identity write rules
-* on the complete after state, with no exemption for historical graphs:
+* after rows of one CAS commit and enforces the resource rules on the complete
+* after state, with no exemption for historical graphs:
 *
-* 1. every Image/Video/Audio/Voice Entity carries its own Asset `external`
-*    identity;
-* 2. no `physical-asset` Relation may bind a media variant;
-* 3. a self-carried media identity is immutable — it cannot be rewritten to
-*    another asset id.
+* 1. every media Entity reaches exactly one Asset through `from-asset`;
+* 2. no entity other than an Asset carries a locator;
+* 3. an Asset's locator is immutable — pointing it at other bytes would
+*    silently rewrite every entity already made from it.
 *
-* Dual-entity media graphs are rejected instead of being migrated or merged
-* implicitly. Deleting media is explicit and allowed.
+* Deleting media is explicit and allowed.
 */
 function assertMediaAssetWritePolicy(before, after) {
 	const beforeEntities = new Map(before.entities.map((row) => [String(row.entityId), row]));
-	const afterKinds = new Map(after.entities.map((row) => [String(row.entityId), row.entityKind]));
+	assertCanonicalEditorResources(after);
 	for (const row of after.entities) {
-		if (!isMediaAssetVariantKind(row.entityKind)) continue;
-		if (memotaLocator(row.payload.external) === void 0) throw new EntityTimelineProjectionError(`Media Entity ${row.entityId} must carry its own Asset external identity`);
-	}
-	for (const relation of after.relations) {
-		if (relation.relationKind !== "physical-asset") continue;
-		const mediaEndpoint = [relation.endpoint0EntityId, relation.endpoint1EntityId].find((endpoint) => isMediaAssetVariantKind(afterKinds.get(String(endpoint)) ?? ""));
-		if (mediaEndpoint !== void 0) throw new EntityTimelineProjectionError(`Cannot bind media Entity ${mediaEndpoint} through physical-asset Relation ${relation.relationId}; media owns its Asset identity directly`);
-	}
-	for (const row of after.entities) {
-		if (!isMediaAssetVariantKind(row.entityKind)) continue;
-		const priorExternal = memotaLocator(beforeEntities.get(String(row.entityId))?.payload.external);
-		if (priorExternal === void 0) continue;
-		const nextExternal = memotaLocator(row.payload.external);
-		if (nextExternal !== void 0 && (nextExternal.system !== priorExternal.system || nextExternal.key !== priorExternal.key)) throw new EntityTimelineProjectionError(`Media Entity ${row.entityId} cannot rewrite its Asset external identity; create a new Entity instead`);
+		if (row.entityKind !== "asset") continue;
+		const prior = memotaLocator(beforeEntities.get(String(row.entityId))?.payload);
+		if (prior === void 0) continue;
+		const next = memotaLocator(row.payload);
+		if (next !== void 0 && (next.system !== prior.system || next.key !== prior.key)) throw new EntityTimelineProjectionError(`Asset ${row.entityId} cannot be pointed at other bytes; create a new Asset instead`);
 	}
 }
 function memotaLocator(value) {
@@ -362,23 +359,14 @@ function memotaLocator(value) {
 * explicit project attachment, multiple candidates are ambiguous. Existing
 * content IDs are reused here; Loro editing advances their immutable versions.
 */
-function ensureDocumentAudioScript(entities, idFactory, selectedEntityId) {
+function ensureDocumentAudioScript(entities, selectedEntityId) {
 	if (selectedEntityId != null) {
 		if (!entities.some((row) => row.entityKind === "audio-script" && row.entityId === selectedEntityId)) throw new EntityTimelineProjectionError(`Selected AudioScript ${selectedEntityId} does not exist`);
 		return selectedEntityId;
 	}
 	const scripts = entities.filter((row) => row.entityKind === "audio-script");
 	if (scripts.length > 1) throw new EntityTimelineProjectionError("Select an AudioScript for the editor panel when multiple scripts exist");
-	const existing = scripts[0];
-	if (existing !== void 0) return existing.entityId;
-	const id = createEntityId(idFactory("entity"));
-	if (entities.some((row) => row.entityId === id)) throw new Error(`Duplicate entity id ${id}`);
-	entities.push({
-		entityId: id,
-		entityKind: "audio-script",
-		payload: { segments: [] }
-	});
-	return id;
+	return scripts[0]?.entityId ?? null;
 }
 /** Add only missing editor structure; existing identities and owned settings are never replaced. */
 function ensureEditorFoundation(initial, idFactory = (prefix) => `${prefix}_${globalThis.crypto.randomUUID()}`, timelinePayload = {}, selectedAudioScriptEntityId) {
@@ -432,7 +420,7 @@ function ensureEditorFoundation(initial, idFactory = (prefix) => `${prefix}_${gl
 		}
 		trackEntityIds[role] = track.entityId;
 	}
-	const audioScriptEntityId = ensureDocumentAudioScript(entities, idFactory, selectedAudioScriptEntityId);
+	const audioScriptEntityId = ensureDocumentAudioScript(entities, selectedAudioScriptEntityId);
 	return {
 		rows: {
 			entities,
@@ -500,15 +488,16 @@ function parseWireState(value, expectedDocId) {
 	if (value.doc_id !== expectedDocId) throw new Error(`Entity-state response doc_id mismatch: expected "${expectedDocId}"`);
 	const rows = parseWireRows(value.rows);
 	decodeEntityRelationRows(rows, numericMarkerValidation$1);
-	if (typeof value.audio_script_entity_id !== "string") throw new Error("Document AudioScript is not initialized");
+	const attached = value.audio_script_entity_id;
+	if (attached !== null && typeof attached !== "string") throw new Error("Invalid document AudioScript identity");
 	if (typeof value.loro_snapshot !== "string") throw new Error("Missing causal Loro snapshot");
 	const state = {
 		revision: value.revision,
 		loroSnapshot: value.loro_snapshot,
 		rows,
-		audioScriptEntityId: value.audio_script_entity_id
+		audioScriptEntityId: attached
 	};
-	readDocumentAudioScript(state);
+	if (attached !== null) readDocumentAudioScript(state);
 	return state;
 }
 function parseWireRows(value) {
@@ -567,16 +556,38 @@ 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.
 *
-* A media variant is a logical facet of its Asset and shares one entity
-* identity: the import mints exactly one entity of the media kind that carries
-* the external locator itself, and deduplicates only against existing variants
-* that already carry the same `(system, key)`. Legacy dual-entity graphs
-* (`asset` row plus a `physical-asset` binding) are not reused and are
-* rejected by the canonical resource policy instead of being migrated.
+* The bytes are named once, on an Asset entity, and the media entity reaches
+* them through a `from-asset` Relation. Re-importing the same `(system, key)`
+* reuses that Asset and the media already made from it, so one stored resource
+* is never copied into several rows.
 */
 function importMediaAsset(initial, fact, idFactory = (prefix) => `${prefix}_${globalThis.crypto.randomUUID()}`) {
 	if (!fact.assetId || fact.assetId.trim() !== fact.assetId) throw new Error("Expected an asset id");
@@ -584,60 +595,60 @@ function importMediaAsset(initial, fact, idFactory = (prefix) => `${prefix}_${gl
 		"image",
 		"video",
 		"audio",
-		"voice"
+		"voiceover"
 	].includes(fact.kind)) throw new Error("Unsupported media kind");
 	if (fact.kind !== "image" && (!Number.isFinite(fact.durationMs) || fact.durationMs <= 0)) throw new Error(`${fact.kind} ${fact.assetId} requires its factual positive duration`);
-	if ((fact.kind === "audio" || fact.kind === "voice") && fact.storageKey.trim() === "") throw new Error(`${fact.kind} ${fact.assetId} requires its physical storage key`);
+	if ((fact.kind === "audio" || fact.kind === "voiceover") && fact.storageKey.trim() === "") throw new Error(`${fact.kind} ${fact.assetId} requires its physical storage key`);
 	decodeEntityRelationRows(initial, numericCoordinates);
 	assertCanonicalEditorResources(initial);
 	const entities = structuredClone([...initial.entities]);
 	const relations = structuredClone([...initial.relations]);
-	const system = fact.kind === "voice" ? "memota-speech" : "memota";
-	const existing = entities.filter((row) => {
-		const external = row.payload.external;
-		return isMediaAssetVariantKind(row.entityKind) && isJsonObject(external) && external.system === system && external.key === fact.assetId;
-	});
-	if (existing.length > 1) throw new Error(`Duplicate media identities for ${fact.assetId}; reuse ${existing[0].entityId}`);
-	if (existing[0] !== void 0) {
-		const variant = requireMatchingVariant(existing[0], fact);
-		replaceEntity$1(entities, variant.entityId, variant);
+	const system = fact.kind === "voiceover" ? "memota-speech" : "memota";
+	const entityKind = fact.kind;
+	const timbre = fact.kind === "voiceover" ? fact.voice : void 0;
+	const durationMs = fact.kind === "image" ? null : fact.durationMs;
+	const asset = ensureAsset(entities, relations, {
+		system,
+		key: fact.assetId,
+		storageKey: fact.storageKey
+	}, idFactory);
+	const madeFromAsset = entities.filter((row) => row.entityId !== asset.entityId && assetIdOf(relations, row.entityId) === asset.entityId);
+	if (madeFromAsset.length > 1) throw new Error(`Duplicate media identities for ${fact.assetId}; reuse ${madeFromAsset[0].entityId}`);
+	const existing = madeFromAsset[0];
+	if (existing !== void 0) {
+		if (existing.entityKind !== entityKind || existing.payload.durationMs !== durationMs) throw new Error(`Media facts conflict with existing identity for ${fact.assetId}`);
+		const voiceEntityId = bindVoiceTimbre(entities, relations, existing.entityId, timbre, idFactory);
 		return {
 			rows: {
 				entities,
 				relations
 			},
-			contentEntityId: variant.entityId
+			contentEntityId: existing.entityId,
+			assetEntityId: asset.entityId,
+			...voiceEntityId
 		};
 	}
 	const entityId = createEntityId(idFactory("entity"));
 	if (entities.some((row) => row.entityId === entityId)) throw new Error(`Duplicate entity id ${entityId}`);
-	const variant = {
+	entities.push({
 		entityId,
-		entityKind: fact.kind,
-		payload: {
-			extent: fact.kind === "image" ? {
-				kind: "unbounded",
-				start: 0
-			} : {
-				kind: "bounded",
-				start: 0,
-				end: fact.durationMs
-			},
-			sampling: fact.kind === "image" ? "constant" : "native",
-			coordinateSpace: "milliseconds",
-			external: {
-				system,
-				key: fact.assetId
-			},
-			...fact.storageKey === void 0 ? {} : { storageKey: fact.storageKey },
-			...fact.kind === "voice" && fact.voice !== void 0 ? { voice: {
-				system: fact.voice.system,
-				key: fact.voice.key,
-				...fact.voice.name === void 0 ? {} : { name: fact.voice.name }
-			} } : {}
-		}
-	};
-	entities.push(variant);
+		entityKind,
+		payload: { durationMs }
+	});
+	relations.push(assetLink(entityId, asset.entityId, idFactory));
+	if (fact.kind === "voiceover" && fact.phoneticScriptEntityId !== void 0) {
+		const phonetic = entities.find((row) => String(row.entityId) === fact.phoneticScriptEntityId);
+		if (phonetic?.entityKind !== "phonetic-script") throw new Error(`Voiceover ${fact.assetId} requires the PhoneticScript it was spoken from`);
+		relations.push({
+			relationId: createRelationId(idFactory("relation")),
+			relationKind: "phonetic-script-render",
+			endpoint0EntityId: entityId,
+			endpoint1EntityId: phonetic.entityId,
+			metadata: {},
+			trace: {}
+		});
+	}
+	const voiceEntityId = bindVoiceTimbre(entities, relations, entityId, timbre, idFactory);
 	const rows = {
 		entities,
 		relations
@@ -646,33 +657,113 @@ function importMediaAsset(initial, fact, idFactory = (prefix) => `${prefix}_${gl
 	assertCanonicalEditorResources(rows);
 	return {
 		rows,
-		contentEntityId: entityId
+		contentEntityId: entityId,
+		assetEntityId: asset.entityId,
+		...voiceEntityId
 	};
 }
-function requireMatchingVariant(row, fact) {
-	const extent = row.payload.extent;
-	if (row.entityKind !== fact.kind || fact.kind !== "image" && (!isJsonObject(extent) || extent.start !== 0 || extent.end !== fact.durationMs) || fact.kind === "voice" && !sameVoice(row.payload.voice, fact.voice)) throw new Error(`Media facts conflict with existing identity for ${fact.assetId}`);
-	if (fact.storageKey !== void 0 && row.payload.storageKey !== fact.storageKey) {
-		if (row.payload.storageKey !== void 0) throw new Error(`Media facts conflict with existing storage key for ${fact.assetId}`);
-		return {
-			...row,
+/** One Asset per `(system, key)`: the bytes are named in exactly one row. */
+function ensureAsset(entities, 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 replacement = {
+			entityId: createEntityId(idFactory("entity")),
+			entityKind: "asset",
 			payload: {
-				...row.payload,
-				storageKey: fact.storageKey
+				...found.payload,
+				storageKey: locator.storageKey
 			}
 		};
+		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;
 	}
-	return row;
+	const asset = {
+		entityId: createEntityId(idFactory("entity")),
+		entityKind: "asset",
+		payload: {
+			system: locator.system,
+			key: locator.key,
+			...locator.storageKey === void 0 ? {} : { storageKey: locator.storageKey }
+		}
+	};
+	entities.push(asset);
+	return asset;
+}
+function assetLink(entityId, assetEntityId, idFactory) {
+	return {
+		relationId: createRelationId(idFactory("relation")),
+		relationKind: "from-asset",
+		endpoint0EntityId: createEntityId(entityId),
+		endpoint1EntityId: createEntityId(assetEntityId),
+		metadata: {},
+		trace: {}
+	};
+}
+function assetIdOf(relations, entityId) {
+	const link = relations.find((relation) => relation.relationKind === "from-asset" && (relation.endpoint0EntityId === entityId || relation.endpoint1EntityId === entityId));
+	if (link === void 0) return void 0;
+	return String(link.endpoint0EntityId === entityId ? link.endpoint1EntityId : link.endpoint0EntityId);
+}
+/**
+* Attach the timbre a synthesized voiceover was rendered with. One Voice
+* identity is shared by every take naming the same library entry, so an
+* existing row is reused rather than duplicated. Recorded media declares no
+* timbre and keeps no link.
+*/
+function bindVoiceTimbre(entities, relations, audioEntityId, descriptor, idFactory) {
+	const linked = relations.filter((relation) => relation.relationKind === "voice-timbre" && (relation.endpoint0EntityId === audioEntityId || relation.endpoint1EntityId === audioEntityId));
+	if (linked.length > 1) throw new Error(`Voiceover ${audioEntityId} has multiple Voice timbre relations`);
+	if (descriptor === void 0) {
+		if (linked.length > 0) throw new Error(`Recorded media ${audioEntityId} cannot keep a synthesized Voice timbre`);
+		return {};
+	}
+	const voice = entities.find((row) => row.entityKind === "voice" && sameVoiceDescriptor(row.payload.voice, descriptor)) ?? appendVoiceIdentity(entities, descriptor, idFactory);
+	const existing = linked[0];
+	if (existing === void 0) relations.push({
+		relationId: createRelationId(idFactory("relation")),
+		relationKind: "voice-timbre",
+		endpoint0EntityId: createEntityId(audioEntityId),
+		endpoint1EntityId: createEntityId(voice.entityId),
+		metadata: {},
+		trace: {}
+	});
+	else if (existing.endpoint0EntityId !== audioEntityId || existing.endpoint1EntityId !== voice.entityId) throw new Error(`Voiceover ${audioEntityId} already carries a different Voice timbre`);
+	return { voiceEntityId: voice.entityId };
+}
+function appendVoiceIdentity(entities, descriptor, idFactory) {
+	const voice = {
+		entityId: createEntityId(idFactory("entity")),
+		entityKind: "voice",
+		payload: { voice: {
+			system: descriptor.system,
+			key: descriptor.key,
+			...descriptor.name === void 0 ? {} : { name: descriptor.name }
+		} }
+	};
+	entities.push(voice);
+	return voice;
+}
+/** Two takes share a Voice identity only when they name the same library entry. */
+function sameVoiceDescriptor(stored, descriptor) {
+	return isJsonObject(stored) && stored.system === descriptor.system && stored.key === descriptor.key && stored.name === descriptor.name;
 }
 function replaceEntity$1(entities, entityId, replacement) {
 	const index = entities.findIndex((row) => row.entityId === entityId);
 	if (index < 0) throw new Error(`Entity id ${entityId} does not exist`);
 	entities[index] = replacement;
 }
-function sameVoice(left, right) {
-	if (right === void 0) return left === void 0;
-	return isJsonObject(left) && left.system === right.system && left.key === right.key && left.name === right.name && Object.keys(left).every((key) => key === "system" || key === "key" || key === "name");
-}
 //#endregion
 //#region src/entity-editor/entity-timeline-editor.ts
 /**
@@ -705,7 +796,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) {
@@ -1016,49 +1107,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) {
@@ -1208,20 +1315,20 @@ var EntityTimelineEditor = class {
 				hostClipEntityId: input.hostClipEntityId,
 				anchorOffset: input.anchorOffset
 			};
-			if (input.placement !== void 0 && (input.hostClipEntityId !== void 0 || input.anchorOffset !== void 0)) throw new Error("Specify Voice placement or hostClipEntityId/anchorOffset, not both");
+			if (input.placement !== void 0 && (input.hostClipEntityId !== void 0 || input.anchorOffset !== void 0)) throw new Error("Specify voiceover placement or hostClipEntityId/anchorOffset, not both");
 			requireVolume(input.volume);
 			const imported = importMediaAsset(draft, input.media, this.idFactory);
 			replaceRows(draft, imported.rows);
-			const voice = requireEntityKind(draft, imported.contentEntityId, "voice");
+			const voiceover = requireEntityKind(draft, imported.contentEntityId, "voiceover");
 			const phonetic = this.requireComposedPhoneticScript(draft, input.phoneticScriptEntityId);
-			this.ensurePhoneticRender(draft, voice.entityId, phonetic.entityId);
+			this.ensurePhoneticRender(draft, voiceover.entityId, phonetic.entityId);
 			const speechTrack = this.ensureRoleTrack(draft, input.timelineEntityId, "speech");
 			const existing = draft.entities.find((row) => row.entityId === input.voiceoverClipEntityId);
 			let voiceoverClipEntityId;
 			if (existing === void 0) voiceoverClipEntityId = this.insertPlacedClipIntoDraft(draft, {
 				clipEntityId: input.voiceoverClipEntityId,
 				trackEntityId: speechTrack.entityId,
-				contentEntityId: voice.entityId,
+				contentEntityId: voiceover.entityId,
 				sourceRange: {
 					start: 0,
 					end: input.media.durationMs
@@ -1245,7 +1352,7 @@ var EntityTimelineEditor = class {
 				});
 				this.relinkRelation(draft, topology.markerContentRelation, {
 					endpoint0EntityId: topology.marker.entityId,
-					endpoint1EntityId: voice.entityId
+					endpoint1EntityId: voiceover.entityId
 				});
 				this.applyClipPlacement(draft, topology.clip.entityId, placement);
 				const placed = requireClipTopology(draft, topology.clip.entityId);
@@ -1264,11 +1371,12 @@ var EntityTimelineEditor = class {
 					}
 				});
 			}
-			this.reconcileVoiceoverCaptions(draft, voiceoverClipEntityId, voice.entityId, phonetic.entityId, input.captions);
+			this.reconcileVoiceoverCaptions(draft, voiceoverClipEntityId, voiceover.entityId, phonetic.entityId, input.captions);
 			this.resolveOneVoiceoverOverlap(draft);
 			return {
 				voiceoverClipEntityId,
-				voiceEntityId: voice.entityId,
+				voiceoverAudioEntityId: voiceover.entityId,
+				...imported.voiceEntityId === void 0 ? {} : { voiceEntityId: imported.voiceEntityId },
 				phoneticScriptEntityId: phonetic.entityId,
 				audioScriptEntityId: requireComposedAudioScript(draft, phonetic.entityId),
 				captionClipEntityIds: input.captions.map((caption) => caption.captionClipEntityId)
@@ -1383,13 +1491,7 @@ var EntityTimelineEditor = class {
 				entityId: input.captionEntityId === void 0 ? this.mintEntityId(draft) : requireAvailableEntityId(draft, input.captionEntityId),
 				entityKind: "caption",
 				payload: {
-					extent: {
-						kind: "bounded",
-						start: 0,
-						end: durationMs
-					},
-					sampling: "native",
-					coordinateSpace: "milliseconds",
+					durationMs,
 					baseEntityIds: captionBaseIds(input.baseEntityIds),
 					selection,
 					...input.style === void 0 ? {} : { style: cloneJsonObject(input.style, "Caption style") }
@@ -1413,12 +1515,481 @@ 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);
+			if (canonicalJson(resolveGeneratedVisualDecisions(draft, input, identityScope)) !== canonicalJson(envelope.decisions)) throw new Error("Frozen visual insertion decision no longer matches the causal baseline");
+			ensureEffectRoleTrack(draft, input.timelineEntityId, "video_clip", envelope.decisions.trackEntityId, identityScope);
+			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, stableEffectScope(generatedVisualsCommand, envelope.effectId, envelope.baselineFingerprint))) !== 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 imported = importMediaAsset(draft, item.renderMode === "synthesized" ? (({ phoneticScriptEntityId: _phoneticScriptEntityId, ...fact }) => fact)(item.media) : item.media, stableEffectIdFactory(identityScope, `speech:${index}:media`));
+				replaceRows(draft, imported.rows);
+				const speech = item.renderMode === "recorded" ? requireEntityKind(draft, imported.contentEntityId, "audio") : requireEntityKind(draft, imported.contentEntityId, "voiceover");
+				const scripts = materializeSpeechSource(draft, item, identityScope, index, trace, speech.entityId);
+				const existingRender = incidentRelations(draft, speech.entityId).filter((relation) => relation.relationKind === "phonetic-script-render");
+				if (item.renderMode === "synthesized") {
+					if (imported.voiceEntityId === void 0 || item.media.voice === void 0) throw new Error("Synthesized speech requires an explicit Voice identity");
+					if (item.media.phoneticScriptEntityId !== void 0 && item.media.phoneticScriptEntityId !== scripts.phonetic.entityId) throw new Error("Synthesized speech media conflicts with its PhoneticScript source");
+					requireSynthesizedSpeechIdentity(draft, requireEntityKind(draft, speech.entityId, "voiceover"), item.media);
+					if (existingRender.length > 1) throw new Error(`Speech Audio "${speech.entityId}" has ambiguous render lineage`);
+					const renderId = stableEffectId("relation", identityScope, `speech:${index}:render`);
+					const renderTrace = {
+						...trace,
+						role: "speech-render"
+					};
+					if (existingRender.length === 1) {
+						if (existingRender[0].endpoint0EntityId !== speech.entityId || existingRender[0].endpoint1EntityId !== scripts.phonetic.entityId) throw new Error(`Speech Audio "${speech.entityId}" has conflicting render lineage`);
+						replaceRelationWithTrace(draft, existingRender[0], speech.entityId, scripts.phonetic.entityId, renderTrace, renderId);
+					} else draft.relations.push(this.createRelation(draft, "phonetic-script-render", speech.entityId, scripts.phonetic.entityId, {}, renderTrace, renderId));
+				} else {
+					const timbre = incidentRelations(draft, speech.entityId).filter((relation) => relation.relationKind === "voice-timbre");
+					if (existingRender.length > 0 || timbre.length > 0) throw new Error("Recorded speech must not have Voice or render lineage");
+				}
+				const startMs = envelope.decisions.targetStartsMs[index];
+				const recordedSpeechClipId = envelope.decisions.recordedSpeechClipEntityIds[index];
+				let speechClipId;
+				if (!("targetSpeechClipEntityId" in item) && recordedSpeechClipId === null) 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,
+						role: "speech-content"
+					},
+					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 if (!("targetSpeechClipEntityId" in item)) {
+					if (item.renderMode !== "recorded" || typeof recordedSpeechClipId !== "string") throw new Error("Only recorded speech may reuse a raw Audio occurrence");
+					const target = requireCanonicalClipOnRole(draft, recordedSpeechClipId, "speech");
+					if (target.markerContentRelation.endpoint1EntityId !== speech.entityId) throw new Error("Recorded speech occurrence no longer uses the frozen raw Audio");
+					speechClipId = target.clip.entityId;
+					const currentVolume = typeof target.clip.payload.volume === "number" ? target.clip.payload.volume : 0;
+					replaceEntity(draft, target.clip.entityId, {
+						...target.clip,
+						payload: {
+							...target.clip.payload,
+							volume: requireVolume(item.volume ?? currentVolume)
+						}
+					});
+					replaceRelationWithTrace(draft, target.markerContentRelation, target.marker.entityId, speech.entityId, {
+						...trace,
+						role: "speech-content"
+					}, 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 ?? null);
+				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, {
+			tombstonedRelations: base.tombstonedRelations(),
+			getVersion: (id) => base.getVersion(id),
+			resolveCurrentEntityId: (id) => base.resolveCurrentEntityId(id)
+		});
+		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);
@@ -1437,7 +2008,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");
@@ -1474,23 +2045,23 @@ var EntityTimelineEditor = class {
 		draft.relations.push(this.createRelation(draft, "timeline-track", timeline.entityId, track.entityId));
 		return track;
 	}
-	/** The existing pronunciation variant a Voice consumes; composition is required. */
+	/** The existing pronunciation variant a voiceover consumes; composition is required. */
 	requireComposedPhoneticScript(draft, phoneticScriptEntityId) {
 		const phonetic = requireEntityKind(draft, phoneticScriptEntityId, "phonetic-script");
 		requireComposedAudioScript(draft, phonetic.entityId);
 		return phonetic;
 	}
 	/** Preserve the factual synthesis input, regardless of persisted endpoint positions. */
-	ensurePhoneticRender(draft, voiceEntityId, phoneticScriptEntityId) {
-		const renders = draft.relations.filter((relation) => relation.relationKind === "phonetic-script-render" && (relation.endpoint0EntityId === voiceEntityId || relation.endpoint1EntityId === voiceEntityId));
-		if (renders.length > 1) throw new Error(`Voice "${voiceEntityId}" has multiple PhoneticScript render relations`);
+	ensurePhoneticRender(draft, voiceoverAudioEntityId, phoneticScriptEntityId) {
+		const renders = draft.relations.filter((relation) => relation.relationKind === "phonetic-script-render" && (relation.endpoint0EntityId === voiceoverAudioEntityId || relation.endpoint1EntityId === voiceoverAudioEntityId));
+		if (renders.length > 1) throw new Error(`Voiceover "${voiceoverAudioEntityId}" has multiple PhoneticScript render relations`);
 		if (renders[0] !== void 0) {
-			if (otherEndpoint(renders[0], voiceEntityId) === phoneticScriptEntityId) return;
-			throw new Error(`Voice "${voiceEntityId}" already has a different PhoneticScript synthesis input`);
+			if (otherEndpoint(renders[0], voiceoverAudioEntityId) === phoneticScriptEntityId) return;
+			throw new Error(`Voiceover "${voiceoverAudioEntityId}" already has a different PhoneticScript synthesis input`);
 		}
-		draft.relations.push(this.createRelation(draft, "phonetic-script-render", voiceEntityId, phoneticScriptEntityId));
+		draft.relations.push(this.createRelation(draft, "phonetic-script-render", voiceoverAudioEntityId, phoneticScriptEntityId));
 	}
-	reconcileVoiceoverCaptions(draft, voiceoverClipEntityId, voiceEntityId, phoneticScriptEntityId, captions) {
+	reconcileVoiceoverCaptions(draft, voiceoverClipEntityId, voiceoverAudioEntityId, phoneticScriptEntityId, captions) {
 		const audioScriptEntityId = requireComposedAudioScript(draft, phoneticScriptEntityId);
 		const requested = new Set(captions.map((caption) => caption.captionClipEntityId));
 		if (requested.size !== captions.length) throw new Error("Caption Clip ids must be unique within a voiceover take");
@@ -1507,13 +2078,7 @@ var EntityTimelineEditor = class {
 					entityId: this.mintEntityId(draft),
 					entityKind: "caption",
 					payload: {
-						extent: {
-							kind: "bounded",
-							start: 0,
-							end: durationMs
-						},
-						sampling: "native",
-						coordinateSpace: "milliseconds",
+						durationMs,
 						baseEntityIds,
 						selection,
 						...caption.style === void 0 ? {} : { style: cloneJsonObject(caption.style, "Caption style") }
@@ -1521,7 +2086,7 @@ var EntityTimelineEditor = class {
 				};
 				draft.entities.push(content);
 				assertCaptionScript(draft, content.entityId, audioScriptEntityId);
-				draft.relations.push(this.createRelation(draft, "caption-alignment", content.entityId, voiceEntityId, { alignment: {
+				draft.relations.push(this.createRelation(draft, "caption-alignment", content.entityId, voiceoverAudioEntityId, { alignment: {
 					start: startMs,
 					end: startMs + durationMs
 				} }));
@@ -1578,7 +2143,7 @@ var EntityTimelineEditor = class {
 					}
 				}
 			});
-			this.replaceCaptionAlignment(draft, content.entityId, voiceEntityId, startMs, durationMs);
+			this.replaceCaptionAlignment(draft, content.entityId, voiceoverAudioEntityId, startMs, durationMs);
 		}
 	}
 	ensureRoleTrackForClip(draft, clipEntityId, role) {
@@ -1587,10 +2152,10 @@ var EntityTimelineEditor = class {
 		const timeline = requireEntityKind(draft, otherEndpoint(requireOneRelation(draft, track.entityId, "timeline-track"), track.entityId), "timeline");
 		return this.ensureRoleTrack(draft, timeline.entityId, role);
 	}
-	replaceCaptionAlignment(draft, captionEntityId, voiceEntityId, startMs, durationMs) {
+	replaceCaptionAlignment(draft, captionEntityId, voiceoverAudioEntityId, startMs, durationMs) {
 		const removed = new Set(incidentRelations(draft, captionEntityId).filter((relation) => relation.relationKind === "caption-alignment").map((relation) => relation.relationId));
 		draft.relations = draft.relations.filter((relation) => !removed.has(relation.relationId));
-		draft.relations.push(this.createRelation(draft, "caption-alignment", captionEntityId, voiceEntityId, { alignment: {
+		draft.relations.push(this.createRelation(draft, "caption-alignment", captionEntityId, voiceoverAudioEntityId, { alignment: {
 			start: startMs,
 			end: startMs + durationMs
 		} }));
@@ -1722,59 +2287,1047 @@ var EntityTimelineEditor = class {
 			else this.removeClipGraph(draft, child);
 		}
 	}
-	removeClipGraph(draft, clipEntityId) {
-		const topology = requireClipTopology(draft, clipEntityId);
-		assertOnlyStructuralIncidents(draft, topology.clip.entityId, new Set([
-			"track-clip",
-			"clip-marker",
-			"clip-anchor"
-		]));
-		assertOnlyStructuralIncidents(draft, topology.marker.entityId, new Set(["clip-marker", "marker-content"]));
-		const markerIsExclusive = incidentRelations(draft, topology.marker.entityId).filter((relation) => relation.relationKind === "clip-marker").length === 1;
-		const removed = new Set(incidentRelations(draft, topology.clip.entityId).map((relation) => relation.relationId));
-		if (markerIsExclusive) for (const relation of incidentRelations(draft, topology.marker.entityId)) removed.add(relation.relationId);
-		draft.relations = draft.relations.filter((relation) => !removed.has(relation.relationId));
-		draft.entities = draft.entities.filter((entity) => entity.entityId !== topology.clip.entityId && (!markerIsExclusive || entity.entityId !== topology.marker.entityId));
+	removeClipGraph(draft, clipEntityId) {
+		const topology = requireClipTopology(draft, clipEntityId);
+		assertOnlyStructuralIncidents(draft, topology.clip.entityId, new Set([
+			"track-clip",
+			"clip-marker",
+			"clip-anchor"
+		]));
+		assertOnlyStructuralIncidents(draft, topology.marker.entityId, new Set(["clip-marker", "marker-content"]));
+		const markerIsExclusive = incidentRelations(draft, topology.marker.entityId).filter((relation) => relation.relationKind === "clip-marker").length === 1;
+		const removed = new Set(incidentRelations(draft, topology.clip.entityId).map((relation) => relation.relationId));
+		if (markerIsExclusive) for (const relation of incidentRelations(draft, topology.marker.entityId)) removed.add(relation.relationId);
+		draft.relations = draft.relations.filter((relation) => !removed.has(relation.relationId));
+		draft.entities = draft.entities.filter((entity) => entity.entityId !== topology.clip.entityId && (!markerIsExclusive || entity.entityId !== topology.marker.entityId));
+	}
+	transact(edit) {
+		const draft = cloneRows(this.state);
+		const result = edit(draft);
+		validateFinalRows(draft);
+		assertMediaAssetWritePolicy(this.state, draft);
+		this.state = draft;
+		return result;
+	}
+	mintEntityId(draft) {
+		const entityId = createEntityId(this.idFactory("entity"));
+		if (draft.entities.some((entity) => entity.entityId === entityId)) throw new Error(`Entity id "${entityId}" already exists`);
+		return entityId;
+	}
+	createRelation(draft, relationKind, endpoint0EntityId, endpoint1EntityId, metadata = {}, trace = {}, requestedRelationId) {
+		return {
+			relationId: requestedRelationId === void 0 ? this.mintRelationId(draft) : requireAvailableRelationId(draft, requestedRelationId),
+			relationKind,
+			endpoint0EntityId,
+			endpoint1EntityId,
+			metadata,
+			trace
+		};
+	}
+	relinkRelation(draft, relation, endpoints) {
+		const relationId = this.mintRelationId(draft);
+		const index = draft.relations.findIndex((candidate) => candidate.relationId === relation.relationId);
+		if (index < 0) throw new Error(`Relation id "${relation.relationId}" does not exist`);
+		draft.relations[index] = {
+			...relation,
+			...endpoints,
+			relationId
+		};
+	}
+	mintRelationId(draft) {
+		const relationId = createRelationId(this.idFactory("relation"));
+		if (draft.relations.some((relation) => relation.relationId === relationId)) throw new Error(`Relation id "${relationId}" already exists`);
+		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 insertion position 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`);
+	}
+	const baselineFingerprint = captionBaselineFingerprint(base);
+	return deepFreeze({
+		version: 1,
+		baselineFingerprint,
+		effectId,
+		signature: generatedVisualSignature(input),
+		input,
+		decisions: resolveGeneratedVisualDecisions(rows, input, stableEffectScope(generatedVisualsCommand, effectId, baselineFingerprint))
+	});
+}
+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) {
+		assertSpeechRenderContract(rawInput.mode, item);
+		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)
+	});
+}
+function assertSpeechRenderContract(mode, item) {
+	if (item.renderMode === "recorded") {
+		if (mode !== "add") throw new Error("Recorded speech cannot replace a synthesized Voice");
+		if (item.media.kind !== "audio") throw new Error("Recorded speech requires raw Audio media");
+		if ("voice" in item.media && item.media.voice !== void 0) throw new Error("Recorded speech must not declare a Voice");
+		if (item.source.kind !== "audio-script") throw new Error("Recorded speech requires an AudioScript source");
+		return;
+	}
+	if (item.renderMode !== "synthesized") throw new Error("Speech renderMode must be recorded or synthesized");
+	if (item.media.kind !== "voiceover") throw new Error("Synthesized speech requires voiceover media");
+	if (item.media.voice === void 0) throw new Error("Synthesized speech requires an explicit Voice identity");
+}
+/** 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") {
+		const targetStartsMs = input.value.items.map((item) => safeWholeMs(item.placementStartMs, "Speech placement startMs"));
+		return {
+			speechTrackEntityId,
+			...captionTrackEntityId === void 0 ? {} : { captionTrackEntityId },
+			targetStartsMs,
+			recordedSpeechClipEntityIds: input.value.items.map((item, index) => item.renderMode === "recorded" ? resolveRecordedSpeechOccurrence(rows, item, speechTrackEntityId, targetStartsMs[index]) : null)
+		};
+	}
+	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,
+		recordedSpeechClipEntityIds: input.value.items.map(() => null)
+	};
+}
+function resolveRecordedSpeechOccurrence(rows, item, speechTrackEntityId, startMs) {
+	if (item.source.sourceMediaEntityIds.length !== 1) throw new Error("Recorded speech requires exactly one raw Audio source");
+	const audio = requireEntityKind(rows, item.source.sourceMediaEntityIds[0], "audio");
+	requireRecordedAudioAsset(rows, audio, item.media);
+	const candidates = [...resolveEntityTimelineLayout(rows).clips.values()].filter((placement) => placement.trackEntityId === speechTrackEntityId && placement.contentEntityId === audio.entityId);
+	if (candidates.length > 1) throw new Error("Recorded speech Audio occurrence is ambiguous");
+	const existing = candidates[0];
+	if (existing === void 0) return null;
+	if (existing.start !== startMs || existing.duration !== item.media.durationMs) throw new Error("Recorded speech Audio occurrence conflicts with the requested placement");
+	const topology = requireCanonicalClipOnRole(rows, existing.clipEntityId, "speech");
+	const sourceRange = requirePositiveRange(topology.marker.payload.sourceRange, "Recorded Speech sourceRange");
+	if (sourceRange.start !== 0 || sourceRange.end !== item.media.durationMs || topology.marker.payload.timeRemapping !== void 0) throw new Error("Recorded speech requires the complete, unremapped raw Audio occurrence");
+	return existing.clipEntityId;
+}
+function requireRecordedAudioAsset(rows, audio, media) {
+	const bindings = incidentRelations(rows, audio.entityId).filter((relation) => relation.relationKind === "from-asset");
+	if (bindings.length !== 1 || bindings[0].endpoint0EntityId !== audio.entityId) throw new Error("Recorded Audio requires one ordered from-asset binding");
+	const asset = requireEntityKind(rows, bindings[0].endpoint1EntityId, "asset");
+	if (asset.payload.system !== "memota" || asset.payload.key !== media.assetId || asset.payload.storageKey !== media.storageKey || audio.payload.durationMs !== media.durationMs) throw new Error("Recorded speech media must match its canonical memota Audio source");
+}
+function requireSynthesizedSpeechIdentity(rows, audio, media) {
+	const bindings = incidentRelations(rows, audio.entityId).filter((relation) => relation.relationKind === "from-asset");
+	if (bindings.length !== 1 || bindings[0].endpoint0EntityId !== audio.entityId) throw new Error("Synthesized speech requires one ordered from-asset binding");
+	const asset = requireEntityKind(rows, bindings[0].endpoint1EntityId, "asset");
+	if (asset.payload.system !== "memota-speech" || asset.payload.key !== media.assetId || asset.payload.storageKey !== media.storageKey || audio.payload.durationMs !== media.durationMs) throw new Error("Synthesized speech media must match its canonical memota-speech Voiceover");
+	const timbre = incidentRelations(rows, audio.entityId).filter((relation) => relation.relationKind === "voice-timbre");
+	if (timbre.length !== 1 || timbre[0].endpoint0EntityId !== audio.entityId) throw new Error("Synthesized speech requires one ordered Voice identity");
+	if (canonicalJson(requireEntityKind(rows, timbre[0].endpoint1EntityId, "voice").payload.voice) !== canonicalJson(media.voice)) throw new Error("Synthesized speech Voice conflicts with its trusted media fact");
+}
+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, speechAudioEntityId) {
+	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") {
+		if (item.renderMode === "recorded" && (source.sourceMediaEntityIds.length !== 1 || source.sourceMediaEntityIds[0] !== speechAudioEntityId)) throw new Error("Recorded speech Audio must be its sole AudioScript source");
+		const timed = validateResolvedAsrSegments(source.segments);
+		if (source.sourceMediaEntityIds.length === 0) throw new Error("Audio Speech source requires media lineage");
+		if (item.renderMode === "recorded") {
+			const selected = new Set(source.sourceMediaEntityIds);
+			rows.relations = rows.relations.filter((relation) => relation.relationKind !== "audio-script-source" || !selected.has(relation.endpoint1EntityId));
+		}
+		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"
+				}
+			});
+		}
+	}
+	if (item.renderMode === "recorded") return { audioScript };
+	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`);
 	}
-	transact(edit) {
-		const draft = cloneRows(this.state);
-		const result = edit(draft);
-		validateFinalRows(draft);
-		assertMediaAssetWritePolicy(this.state, draft);
-		this.state = draft;
+	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 === "to-asset").length > 0) throw new Error(`${label} AudioScript "${audioScriptEntityId}" must not have an authored Asset snapshot`);
+}
+function requireCanonicalAudioScriptAsset(rows, audioScriptEntityId) {
+	const bindings = incidentRelations(rows, audioScriptEntityId).filter((relation) => relation.relationKind === "to-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("to-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;
 	}
-	mintEntityId(draft) {
-		const entityId = createEntityId(this.idFactory("entity"));
-		if (draft.entities.some((entity) => entity.entityId === entityId)) throw new Error(`Entity id "${entityId}" already exists`);
-		return entityId;
+	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");
+	for (const item of value.input.value.items) assertSpeechRenderContract(value.input.mode, item);
+}
+function resolveSpeechAssetsReplay(rows, envelope, history) {
+	const currentTagged = rows.relations.filter((relation) => relation.trace.command === speechAssetsCommand && relation.trace.effectId === envelope.effectId);
+	const historicalTagged = (history?.tombstonedRelations ?? []).filter((relation) => relation.trace.command === speechAssetsCommand && relation.trace.effectId === envelope.effectId);
+	const tagged = [...currentTagged, ...historicalTagged];
+	const historicalIds = new Set(historicalTagged.map((relation) => relation.relationId));
+	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 sourceReceipts = relations.filter((relation) => relation.relationKind === "audio-script-source");
+		const contentRelations = relations.filter((relation) => relation.relationKind === "marker-content");
+		const speechContent = contentRelations.filter((relation) => relation.trace.role === "speech-content");
+		const captionContent = contentRelations.filter((relation) => relation.trace.role === "caption-content");
+		const receiptMarkers = relations.filter((relation) => relation.relationKind === "audio-script-marker");
+		const renders = relations.filter((relation) => relation.relationKind === "phonetic-script-render");
+		if (speechContent.length > 1) throw new Error(`Speech effect item ${index} has an ambiguous Speech occurrence receipt`);
+		if (speechContent.length === 0) throw new Error(`Speech effect item ${index} has an incomplete Speech occurrence receipt`);
+		if (contentRelations.length !== speechContent.length + captionContent.length) throw new Error(`Speech effect item ${index} has an unrecognized content receipt`);
+		const captionReceipts = item.captions.map((_, captionIndex) => captionContent.filter((relation) => relation.trace.captionIndex === captionIndex));
+		if (captionContent.some((relation) => !Number.isInteger(relation.trace.captionIndex) || relation.trace.captionIndex < 0 || relation.trace.captionIndex >= item.captions.length) || captionReceipts.some((matches) => matches.length > 1)) throw new Error(`Speech effect item ${index} has an ambiguous Caption receipt`);
+		const sourceIndexes = sourceReceipts.map((relation) => relation.trace.sourceIndex);
+		const expectedSourceCount = item.source.kind === "audio-script" ? item.source.sourceMediaEntityIds.length : void 0;
+		if ((expectedSourceCount === void 0 ? sourceReceipts.length > 0 : sourceIndexes.some((sourceIndex) => !Number.isInteger(sourceIndex) || sourceIndex < 0 || sourceIndex >= expectedSourceCount)) || new Set(sourceIndexes).size !== sourceIndexes.length) throw new Error(`Speech effect item ${index} has an ambiguous AudioScript source receipt`);
+		if (receiptMarkers.length > 1) throw new Error("Speech has an ambiguous AudioScript receipt");
+		if (item.renderMode === "recorded") {
+			if (sourceReceipts.length > 1) throw new Error("Recorded speech has an ambiguous AudioScript source receipt");
+			if (sourceReceipts.length === 0) throw new Error("Recorded speech has an incomplete AudioScript source receipt");
+			if (renders.length !== 0) throw new Error("Recorded speech must not have render lineage");
+		} else if (renders.length > 1) throw new Error(`Speech effect item ${index} has an ambiguous render receipt`);
+		else if (renders.length === 0) throw new Error(`Speech effect item ${index} has an incomplete render receipt`);
+		const historicalRecorded = item.renderMode === "recorded" && (speechContent.some((relation) => historicalIds.has(relation.relationId)) || sourceReceipts.some((relation) => historicalIds.has(relation.relationId)));
+		let audio;
+		let speechClip;
+		const speechReceipt = speechContent[0];
+		const speechReceiptIsHistorical = historicalIds.has(speechReceipt.relationId);
+		const speechKind = item.renderMode === "recorded" ? "audio" : "voiceover";
+		if (speechReceiptIsHistorical) {
+			requireHistoricalEntity(history?.getVersion(speechReceipt.endpoint1EntityId), speechReceipt.endpoint1EntityId, speechKind);
+			requireHistoricalEntity(history?.getVersion(speechReceipt.endpoint0EntityId), speechReceipt.endpoint0EntityId, "sequence-marker");
+		}
+		const currentSpeechId = speechReceiptIsHistorical ? history.resolveCurrentEntityId(speechReceipt.endpoint1EntityId) : speechReceipt.endpoint1EntityId;
+		const currentMarkerId = speechReceiptIsHistorical ? history.resolveCurrentEntityId(speechReceipt.endpoint0EntityId) : speechReceipt.endpoint0EntityId;
+		audio = requireEntityKind(rows, currentSpeechId, speechKind);
+		const speechMarker = requireEntityKind(rows, currentMarkerId, "sequence-marker");
+		speechClip = requireSingleClipForMarker(rows, speechMarker.entityId, "speech");
+		const currentSpeechContent = requireOneRelation(rows, speechMarker.entityId, "marker-content");
+		if (currentSpeechContent.endpoint0EntityId !== speechMarker.entityId || currentSpeechContent.endpoint1EntityId !== audio.entityId) throw new Error("Speech occurrence receipt no longer resolves to its current content");
+		let audioScriptId;
+		let phoneticScriptEntityId;
+		if (item.renderMode === "synthesized") {
+			const voiceover = requireEntityKind(rows, audio.entityId, "voiceover");
+			requireSynthesizedSpeechIdentity(rows, voiceover, item.media);
+			if (renders[0].endpoint0EntityId !== audio.entityId) throw new Error(`Speech effect item ${index} has an incomplete render receipt`);
+			const phonetic = requireEntityKind(rows, renders[0].endpoint1EntityId, "phonetic-script");
+			const currentRenders = incidentRelations(rows, voiceover.entityId).filter((relation) => relation.relationKind === "phonetic-script-render");
+			if (currentRenders.length !== 1 || currentRenders[0].endpoint0EntityId !== voiceover.entityId || currentRenders[0].endpoint1EntityId !== phonetic.entityId) throw new Error("Synthesized speech has ambiguous or conflicting current render lineage");
+			audioScriptId = requireComposedAudioScript(rows, phonetic.entityId);
+			phoneticScriptEntityId = phonetic.entityId;
+		} else {
+			audio = requireEntityKind(rows, audio.entityId, "audio");
+			requireRecordedAudioAsset(rows, audio, item.media);
+			if (sourceReceipts[0].endpoint1EntityId !== audio.entityId) throw new Error("Recorded speech has an incomplete AudioScript source receipt");
+			if (item.source.audioScriptEntityId !== void 0 && sourceReceipts[0].endpoint0EntityId !== item.source.audioScriptEntityId) throw new Error("Recorded speech receipt does not match the requested AudioScript identity");
+			const receiptScriptId = sourceReceipts[0].endpoint0EntityId;
+			const sourceReceiptIsHistorical = historicalIds.has(sourceReceipts[0].relationId);
+			const audioScript = sourceReceiptIsHistorical ? requireHistoricalEntity(history?.getVersion(receiptScriptId), receiptScriptId, "audio-script") : requireEntityKind(rows, receiptScriptId, "audio-script");
+			const expected = audioScriptSegmentsFromAsr(item.source.segments, item.source.audioScriptEntityId !== void 0);
+			if (canonicalJson(audioScript.payload.segments) !== canonicalJson(expected)) throw new Error("Recorded speech AudioScript conflicts with its immutable ASR source");
+			const currentScriptId = sourceReceiptIsHistorical ? createEntityId(history.resolveCurrentEntityId(receiptScriptId)) : audioScript.entityId;
+			requireNoAudioScriptAsset(rows, currentScriptId, "ASR-composed");
+			if (receiptMarkers.length === 1) {
+				const markerScriptId = historicalIds.has(receiptMarkers[0].relationId) ? audioScript.entityId : currentScriptId;
+				if (receiptMarkers[0].endpoint0EntityId !== markerScriptId) throw new Error("Recorded speech marker receipt conflicts with its AudioScript source receipt");
+			}
+			const sources = incidentRelations(rows, audio.entityId).filter((relation) => relation.relationKind === "audio-script-source");
+			if (sources.length > 1 || sources.length === 1 && (sources[0].endpoint1EntityId !== audio.entityId || requireEntityKind(rows, sources[0].endpoint0EntityId, "audio-script").entityKind !== "audio-script")) throw new Error("Recorded speech has ambiguous or reversed current AudioScript source lineage");
+			if (!historicalRecorded && (sources.length !== 1 || sources[0].endpoint0EntityId !== currentScriptId)) throw new Error("Recorded speech has an incomplete AudioScript source receipt");
+			if (incidentRelations(rows, audio.entityId).some((relation) => relation.relationKind === "voice-timbre" || relation.relationKind === "phonetic-script-render")) throw new Error("Recorded speech must not have Voice or render lineage");
+			audioScriptId = currentScriptId;
+			phoneticScriptEntityId = null;
+		}
+		const captionIds = [];
+		for (let captionIndex = 0; captionIndex < item.captions.length; captionIndex += 1) {
+			const matches = captionReceipts[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(phoneticScriptEntityId);
+		result.captionClipEntityIds.push(captionIds);
 	}
-	createRelation(draft, relationKind, endpoint0EntityId, endpoint1EntityId, metadata = {}) {
+	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, identityScope) {
+	const timeline = requireEntityKind(rows, input.timelineEntityId, "timeline");
+	const anchorInput = visualInsertionAnchor(input);
+	if (anchorInput.position === "track_start") {
+		const trackEntityId = resolveEffectTrackId(rows, timeline.entityId, "video_clip", identityScope);
+		const clips = resolveEntityTimelineLayout(rows).tracks.find((candidate) => candidate.entityId === trackEntityId)?.clips ?? [];
+		if (clips.some((clip) => clip.mode !== "sequential")) throw new Error("Generated visual insertion requires a fully sequential Video Track");
 		return {
-			relationId: this.mintRelationId(draft),
-			relationKind,
-			endpoint0EntityId,
-			endpoint1EntityId,
-			metadata,
-			trace: {}
+			trackEntityId,
+			anchorOrder: null,
+			anchorPosition: "track_start",
+			insertionOrders: visualInsertionOrders(rows, clips.map((clip) => clip.clipEntityId), 0, input.clips.length)
 		};
 	}
-	relinkRelation(draft, relation, endpoints) {
-		const relationId = this.mintRelationId(draft);
-		const index = draft.relations.findIndex((candidate) => candidate.relationId === relation.relationId);
-		if (index < 0) throw new Error(`Relation id "${relation.relationId}" does not exist`);
-		draft.relations[index] = {
-			...relation,
-			...endpoints,
-			relationId
-		};
+	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 && upper === void 0) return Array.from({ length: count }, (_, index) => index);
+	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 cannot set both Clip anchors");
+	if (before === void 0 && after === void 0) return { position: "track_start" };
+	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);
 	}
-	mintRelationId(draft) {
-		const relationId = createRelationId(this.idFactory("relation"));
-		if (draft.relations.some((relation) => relation.relationId === relationId)) throw new Error(`Relation id "${relationId}" already exists`);
-		return relationId;
+	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);
@@ -1812,6 +3365,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`);
@@ -1824,6 +3387,11 @@ function requireEntityKind(rows, entityIdValue, entityKind) {
 	if (entity.entityKind !== entityKind) throw new Error(`Entity "${entityId}" must have kind "${entityKind}", got "${entity.entityKind}"`);
 	return entity;
 }
+function requireHistoricalEntity(entity, entityId, entityKind) {
+	if (entity === void 0) throw new Error(`Historical Entity id "${entityId}" does not exist`);
+	if (entity.entityKind !== entityKind) throw new Error(`Historical Entity "${entityId}" must have kind "${entityKind}", got "${entity.entityKind}"`);
+	return entity;
+}
 function requireSequenceContent(rows, entityIdValue) {
 	if (/^(?:[a-z][a-z\d+.-]*:|\/\/)/i.test(entityIdValue)) throw new Error("Timeline content must reference an existing Sequence media Entity id; a URL is not allowed");
 	const entityId = createEntityId(entityIdValue);
@@ -1863,6 +3431,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, {
@@ -1938,6 +3511,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");
@@ -1999,11 +3581,19 @@ function migrateLegacyTimelineToEntities(legacy, assetFacts, initial = {
 }, idFactory = (prefix) => `${prefix}_${globalThis.crypto.randomUUID()}`) {
 	assertSupportedLegacy(legacy);
 	if (initial.entities.some((row) => row.entityKind === "timeline")) fail("Timeline already exists; migration is not an editing operation");
-	if (legacy.meta.schema_version === "video-document/entity-projection-v1") fail("An entity projection cannot be migrated as legacy state");
+	if (hasResolvedPlacement(legacy)) fail("An entity projection cannot be migrated as legacy state");
 	const normalizedMainRanges = overlapNormalizedMainRanges(legacy);
 	let entities = structuredClone([...initial.entities]);
 	let relations = structuredClone([...initial.relations]);
-	const documentAudioScriptEntityId = ensureDocumentAudioScript(entities, idFactory);
+	const documentAudioScriptEntityId = ensureDocumentAudioScript(entities) ?? (() => {
+		const id = createEntityId(idFactory("entity"));
+		entities.push({
+			entityId: id,
+			entityKind: "audio-script",
+			payload: { segments: [] }
+		});
+		return String(id);
+	})();
 	const addEntity = (kind, payload, existingId) => {
 		const entityId = createEntityId(existingId ?? idFactory("entity"));
 		if (entities.some((row) => row.entityId === entityId)) fail(`Migration entity identity collision: ${entityId}`);
@@ -2053,7 +3643,7 @@ function migrateLegacyTimelineToEntities(legacy, assetFacts, initial = {
 				relations
 			}, {
 				assetId: speech.origin_speech_id,
-				kind: "voice",
+				kind: "voiceover",
 				durationMs: speech.media_duration_ms,
 				storageKey: speech.audio_storage_key,
 				voice: {
@@ -2141,8 +3731,8 @@ function migrateLegacyTimelineToEntities(legacy, assetFacts, initial = {
 			} else if (part.caption !== void 0) {
 				const caption = part.caption;
 				duration = caption.initial_duration_ms;
-				const voice = contentByPartId.get(caption.speech_part_id);
-				const render = relations.find((relation) => relation.relationKind === "phonetic-script-render" && relation.endpoint0EntityId === voice);
+				const voiceover = contentByPartId.get(caption.speech_part_id);
+				const render = relations.find((relation) => relation.relationKind === "phonetic-script-render" && relation.endpoint0EntityId === voiceover);
 				const phonetic = entities.find((entity) => entity.entityId === render?.endpoint1EntityId);
 				const script = phonetic === void 0 ? void 0 : composedAudioScript(phonetic, entities);
 				if (script === void 0) fail("Legacy Caption has no composed AudioScript");
@@ -2158,18 +3748,12 @@ function migrateLegacyTimelineToEntities(legacy, assetFacts, initial = {
 					} }
 				};
 				content = addEntity("caption", {
-					extent: {
-						kind: "bounded",
-						start: 0,
-						end: duration
-					},
-					sampling: "native",
-					coordinateSpace: "milliseconds",
+					durationMs: duration,
 					baseEntityIds: [script.entityId],
 					selection,
 					...caption.style === void 0 ? {} : { style: toEntityCaptionStyle(caption.style) }
 				});
-				link("caption-alignment", content, voice, { alignment: {
+				link("caption-alignment", content, voiceover, { alignment: {
 					start: caption.start_ms,
 					end: caption.start_ms + duration
 				} });
@@ -2225,27 +3809,24 @@ function migrateLegacyTimelineToEntities(legacy, assetFacts, initial = {
 		entities,
 		relations
 	};
-	assertEntityProjectionPreservesLegacy(legacy, projectEntityTimeline(rows, legacy.meta), rows);
+	assertEntityProjectionPreservesLegacy(legacy, projectEntityTimeline(rows), rows);
 	return rows;
 }
 /** Server gate: a cutover may change representation, never the existing render facts. */
 function assertEntityProjectionPreservesLegacy(legacy, projection, rows) {
 	assertSupportedLegacy(legacy);
-	if (projection.meta.schema_version !== "video-document/entity-projection-v1") fail("Expected an entity projection for migration");
+	if (!hasResolvedPlacement(projection)) fail("Expected an entity projection for migration");
 	const normalizedMainRanges = overlapNormalizedMainRanges(legacy);
-	const compatibilityFacts = (document) => {
-		const { version: _version, ...view } = fromVideoDocument(document);
+	const compatibilityFacts = (document, placementResolved) => {
+		const view = fromVideoDocument(document, { placementResolved });
 		for (const part of Object.values(view.part_library ?? {})) {
 			const speech = part.speech;
 			if (speech?.phoneme_script === null) delete speech.phoneme_script;
+			if (speech !== void 0) delete speech.origin_asset_system;
 		}
-		const { schema_version: _schemaVersion, version: _metaVersion, ...meta } = document.meta;
-		return {
-			meta,
-			view
-		};
+		return { view };
 	};
-	if (canonical(compatibilityFacts(legacy)) !== canonical(compatibilityFacts(projection))) fail("Entity migration must preserve all existing timeline facts; edit after cutover");
+	if (canonical(compatibilityFacts(legacy, false)) !== canonical(compatibilityFacts(projection, true))) fail("Entity migration must preserve all existing timeline facts; edit after cutover");
 	const trackOrders = [];
 	for (const oldTrack of legacy.tracks ?? []) {
 		const candidates = rows.entities.filter((row) => row.entityKind === "track" && (oldTrack.id === void 0 ? row.payload.role === oldTrack.parts_kind : row.entityId === oldTrack.id));
@@ -2381,6 +3962,7 @@ function assertPartSupported(id, part, role) {
 	} else if (part.speech !== void 0) {
 		const speech = part.speech;
 		const phonemeScript = speech.phoneme_script;
+		const originAssetSystem = speech.origin_asset_system;
 		if (speech.id !== id || speech.kind !== "speech" || !trimmed(speech.origin_speech_id) || !trimmed(speech.audio_storage_key) || typeof speech.audio_script !== "string") fail("Migration requires complete Speech identity and physical take facts");
 		requirePositiveMilliseconds(speech.media_duration_ms, "Speech duration");
 		requireFinite(speech.volume, "Speech volume");
@@ -2389,6 +3971,7 @@ function assertPartSupported(id, part, role) {
 		if (!Array.isArray(speech.caption_ids) || speech.caption_ids.some((captionId) => !trimmed(captionId))) fail("Migration requires explicit Speech caption identities");
 		if (new Set(speech.caption_ids).size !== speech.caption_ids.length) fail("Migration requires unique Speech caption identities");
 		if (phonemeScript !== void 0 && phonemeScript !== null && typeof phonemeScript !== "string") fail("Migration requires a string phoneme_script when present");
+		if (originAssetSystem !== void 0 && originAssetSystem !== "memota-speech") fail("Legacy synthesized Speech requires a memota-speech origin asset");
 		assertKnownFields(speech.voice, ["id", "name"], "voice");
 		assertKnownFields(speech, [
 			"id",
@@ -2398,6 +3981,7 @@ function assertPartSupported(id, part, role) {
 			"volume",
 			"audio_storage_key",
 			"origin_speech_id",
+			"origin_asset_system",
 			"voice",
 			"caption_ids",
 			"phoneme_script"
@@ -2512,21 +4096,21 @@ function requirePart(document, partId) {
 	if (part === void 0) fail(`Placed Clip ${partId} has no part payload`);
 	return part;
 }
-function ensureSpeechPhoneticChain(voiceEntityId, audioScriptText, phonemeScript, entities, relations, addEntity, link, documentAudioScriptEntityId) {
-	const renders = relations.filter((relation) => relation.relationKind === "phonetic-script-render" && relation.endpoint0EntityId === voiceEntityId);
-	if (renders.length > 1) fail(`Voice ${voiceEntityId} has ambiguous PhoneticScript provenance`);
+function ensureSpeechPhoneticChain(voiceoverAudioEntityId, audioScriptText, phonemeScript, entities, relations, addEntity, link, documentAudioScriptEntityId) {
+	const renders = relations.filter((relation) => relation.relationKind === "phonetic-script-render" && relation.endpoint0EntityId === voiceoverAudioEntityId);
+	if (renders.length > 1) fail(`Voiceover ${voiceoverAudioEntityId} has ambiguous PhoneticScript provenance`);
 	if (renders.length === 1) {
 		const phonetic = entities.find((entity) => entity.entityId === renders[0].endpoint1EntityId && entity.entityKind === "phonetic-script");
-		if (phonetic === void 0) fail(`Voice ${voiceEntityId} has a dangling PhoneticScript render`);
+		if (phonetic === void 0) fail(`Voiceover ${voiceoverAudioEntityId} has a dangling PhoneticScript render`);
 		const script = composedAudioScript(phonetic, entities);
-		if (script === void 0 || scriptText(script) !== audioScriptText) fail(`Voice ${voiceEntityId} conflicts with the legacy Speech script`);
+		if (script === void 0 || scriptText(script) !== audioScriptText) fail(`Voiceover ${voiceoverAudioEntityId} conflicts with the legacy Speech script`);
 		return phonetic.entityId;
 	}
 	const script = entities.find((entity) => entity.entityId === documentAudioScriptEntityId);
 	if (script === void 0 || script.entityKind !== "audio-script") fail("Migration must carry the fixed document AudioScript");
 	const segments = script.payload.segments;
 	if (Array.isArray(segments) && segments.length > 0) {
-		if (scriptText(script) !== audioScriptText) fail(`Voice ${voiceEntityId} conflicts with the project AudioScript text`);
+		if (scriptText(script) !== audioScriptText) fail(`Voiceover ${voiceoverAudioEntityId} conflicts with the project AudioScript text`);
 	} else {
 		const scriptIndex = entities.findIndex((row) => row.entityId === script.entityId);
 		entities[scriptIndex] = {
@@ -2541,7 +4125,7 @@ function ensureSpeechPhoneticChain(voiceEntityId, audioScriptText, phonemeScript
 		baseEntityIds: [script.entityId],
 		...phonemeScript === void 0 ? {} : { phonemeScript }
 	});
-	link("phonetic-script-render", voiceEntityId, phonetic);
+	link("phonetic-script-render", voiceoverAudioEntityId, phonetic);
 	return phonetic;
 }
 function composedAudioScript(phonetic, entities) {
@@ -2659,13 +4243,7 @@ function prepareCaptionContent(rows, input) {
 		payload: {
 			...previous?.payload,
 			baseEntityIds,
-			extent: previous?.payload.extent ?? {
-				kind: "bounded",
-				start: 0,
-				end: input.durationMs
-			},
-			sampling: previous?.payload.sampling ?? "native",
-			coordinateSpace: previous?.payload.coordinateSpace ?? "milliseconds"
+			durationMs: previous?.payload.durationMs ?? input.durationMs
 		}
 	};
 	const graph = {
@@ -3648,7 +5226,7 @@ function writeSpeechAssets(draft, assets) {
 			if (caption == null) continue;
 			const priorCaption = draft.part_library?.[captionId]?.caption;
 			setPart(draft, captionId, { caption: {
-				...priorCaption,
+				...priorCaption ?? { style: {} },
 				id: captionId,
 				kind: "caption",
 				initial_duration_ms: caption.duration_ms,
@@ -4057,6 +5635,10 @@ var ManualSyncDoc = class ManualSyncDoc {
 	client;
 	doc;
 	adapter;
+	/** Whether this document's timeline is owned by the Entity graph. */
+	isEntityDocument() {
+		return this.adapter.isEntityDocument();
+	}
 	editor;
 	/**
 	* The version the server is known to hold. Starts empty (nothing confirmed)
@@ -4075,17 +5657,24 @@ var ManualSyncDoc = class ManualSyncDoc {
 	* Fetches the snapshot up front rather than starting empty and converging: the
 	* agent's first act is to read the document, so there is no useful state before
 	* the snapshot lands. This also fails fast and loudly on a document that does
-	* not exist, instead of `MengineDocSession.waitForContent()`'s behavior of
-	* waiting forever for content that will never arrive.
+	* not exist or whose first snapshot is incomplete or invalid.
 	*/
 	static async open(options) {
-		const doc = new LoroDoc();
-		if (options.peerId != null) doc.setPeerId(options.peerId);
 		const response = await options.client.fetchSnapshot();
-		doc.import(base64ToBytes(response.snapshot));
-		const manualSyncDoc = new ManualSyncDoc(options.client, doc);
-		manualSyncDoc.watermark = manualSyncDoc.serverVVFrom(response.version.server_vv) ?? doc.oplogVersion();
-		return manualSyncDoc;
+		const doc = new LoroDoc();
+		let manualSyncDoc;
+		try {
+			if (options.peerId != null) doc.setPeerId(options.peerId);
+			if (doc.import(base64ToBytes(response.snapshot)).pending != null) throw new Error("Initial mengine snapshot has missing dependencies");
+			manualSyncDoc = new ManualSyncDoc(options.client, doc);
+			assertValidVideoDocument(manualSyncDoc.snapshot());
+			manualSyncDoc.watermark = manualSyncDoc.serverVVFrom(response.version.server_vv) ?? doc.oplogVersion();
+			return manualSyncDoc;
+		} catch (error) {
+			manualSyncDoc?.adapter.dispose();
+			doc.free();
+			throw error;
+		}
 	}
 	/** Current document read model (authoritative shape). */
 	snapshot() {
@@ -4104,9 +5693,9 @@ var ManualSyncDoc = class ManualSyncDoc {
 	editorPeerId() {
 		return this.doc.peerIdStr;
 	}
-	/** Current document projected to the legacy `VideoDraft` read shape. */
-	draft() {
-		return fromVideoDocument(this.adapter.snapshot());
+	/** Current content projected into the compatible track and part read shape. */
+	content() {
+		return fromVideoDocument(this.adapter.snapshot(), { placementResolved: this.isEntityDocument() });
 	}
 	/**
 	* Replay a deterministic sandbox journal into this document.
@@ -4126,9 +5715,8 @@ var ManualSyncDoc = class ManualSyncDoc {
 	*
 	* This pair replaces the legacy integer-version comparison that
 	* `DraftVersionDetector` used to tell the LLM "the draft was modified
-	* externally, reload before editing". Under mengine `meta.version` never
-	* changes, so that detector would go permanently silent; comparing version
-	* vectors restores the same capability.
+	* externally, reload before editing". Comparing Loro version vectors covers
+	* all collaborative edits without a business revision field in the document.
 	*
 	* Same capability, not a stronger one: like the legacy detector, this only
 	* reports what changed between two moments the caller chose to sample.
@@ -4212,6 +5800,7 @@ var ManualSyncDoc = class ManualSyncDoc {
 			if (serverVV != null) this.watermark = serverVV;
 			return {
 				kind: response.kind,
+				mengineUpdateSeq: response.version?.update_seq ?? response.update_seq ?? void 0,
 				updateSeq: response.update_seq ?? void 0,
 				collaborated: serverVV != null && !covers(localVersion, serverVV)
 			};
@@ -4250,22 +5839,24 @@ var ManualSyncDoc = class ManualSyncDoc {
 * recovers whatever the stream missed while it was down. Recovery therefore
 * lives in the synchronizer (keyed on the real doc version), not here.
 *
-* Each SSE frame's updates are forwarded verbatim via `onUpdate`; this
+* Update frames are forwarded via `onUpdate`, resync hints via `onResync`; this
 * connection keeps no version cursor and does no catch-up of its own. Dedup is
 * unnecessary because `LoroDoc.import` is idempotent by OpId/VV.
 */
 var SseConnection = class {
 	client;
 	onUpdate;
+	onResync;
 	reconnectDelayMs;
 	inner = void 0;
 	event = new EventBus();
 	streamTask = null;
 	_status = "idle";
 	_error;
-	constructor(client, onUpdate, reconnectDelayMs) {
+	constructor(client, onUpdate, onResync, reconnectDelayMs) {
 		this.client = client;
 		this.onUpdate = onUpdate;
+		this.onResync = onResync;
 		this.reconnectDelayMs = reconnectDelayMs;
 	}
 	get status() {
@@ -4326,10 +5917,12 @@ var SseConnection = class {
 					client: this.client,
 					signal,
 					onOpen: () => this.setStatus("connected"),
+					onResync: this.onResync,
 					onUpdate: (event) => {
 						for (const update of event.updates) this.onUpdate(update);
 					}
 				});
+				if (!signal.aborted) this.setStatus("connecting", /* @__PURE__ */ new Error("SSE stream closed"));
 			} catch (error) {
 				if (signal.aborted) break;
 				this.setStatus("connecting", error instanceof Error ? error : new Error(String(error)));
@@ -4374,7 +5967,7 @@ var MedeoHttpDocStorage = class {
 		this.options = options;
 		this.client = options.client;
 		this.docId = options.docId;
-		this.connection = new SseConnection(this.client, (update) => this.emitUpdate(update), options.sseReconnectDelayMs ?? 500);
+		this.connection = new SseConnection(this.client, (update) => this.emitUpdate(update), () => this.events.emit("resync"), options.sseReconnectDelayMs ?? 500);
 	}
 	get isReadonly() {
 		return this.options.readonlyMode ?? false;
@@ -4382,6 +5975,7 @@ var MedeoHttpDocStorage = class {
 	async getDoc(docId) {
 		this.assertDocId(docId);
 		const snapshot = await this.client.fetchSnapshot();
+		this.reportServerVersion(snapshot.version?.server_vv);
 		const now = /* @__PURE__ */ new Date();
 		return {
 			docId,
@@ -4393,6 +5987,7 @@ var MedeoHttpDocStorage = class {
 	async getDocDiff(docId, knownVersion) {
 		this.assertDocId(docId);
 		const response = await this.client.sync(knownVersion);
+		this.reportServerVersion(response.server_vv);
 		return {
 			docId,
 			missing: base64ToBytes(response.update),
@@ -4423,7 +6018,7 @@ var MedeoHttpDocStorage = class {
 		if (update.data.byteLength === 0) return {};
 		try {
 			const response = await this.client.pushUpdate(update.data);
-			const serverVV = decodeServerVV(response.version?.server_vv);
+			const serverVV = this.reportServerVersion(response.version?.server_vv);
 			this.events.emit("pushOutcome", {
 				kind: response.kind,
 				updateSeq: response.update_seq ?? void 0,
@@ -4451,6 +6046,19 @@ var MedeoHttpDocStorage = class {
 	subscribePushOutcome(callback) {
 		return this.events.on("pushOutcome", callback);
 	}
+	/** Observe live hints that require VV catch-up without replacing the SSE connection. */
+	subscribeResync(callback) {
+		return this.events.on("resync", callback);
+	}
+	/** Authoritative HTTP reads and accepted pushes, never inferred from SSE bytes. */
+	subscribeServerVersion(callback) {
+		return this.events.on("serverVersion", callback);
+	}
+	reportServerVersion(encoded) {
+		const version = decodeServerVV(encoded);
+		if (version != null) this.events.emit("serverVersion", version);
+		return version;
+	}
 	async deleteDoc(_docId) {
 		throw new Error("MedeoHttpDocStorage does not support deleteDoc");
 	}
@@ -4567,6 +6175,118 @@ var MemoryDocStorage = class extends BaseDocStorage {
 	}
 };
 //#endregion
+//#region src/session/document-undo-manager.ts
+/**
+* Tracks the shared LoroDoc independently of semantic editing. Undo/redo use
+* the same mutation guard as the adapter and publish settled availability.
+*/
+var DocumentUndoManager = class {
+	doc;
+	mutationGuard;
+	onChange;
+	manager;
+	unsubscribe;
+	disposed = false;
+	notificationQueued = false;
+	published = {
+		canUndo: false,
+		canRedo: false
+	};
+	activeSource = null;
+	constructor(doc, mutationGuard, onChange) {
+		this.doc = doc;
+		this.mutationGuard = mutationGuard;
+		this.onChange = onChange;
+		const peer = doc.peerIdStr;
+		this.manager = new UndoManager(doc, {
+			mergeInterval: 0,
+			maxUndoSteps: 100,
+			excludeOriginPrefixes: ["mengine.bootstrap", "mengine.initialize"],
+			onPush: (_isUndo, range) => {
+				this.scheduleNotification();
+				return {
+					value: this.activeSource ?? {
+						peer,
+						counter: range.start
+					},
+					cursors: []
+				};
+			},
+			onPop: () => this.scheduleNotification()
+		});
+		this.unsubscribe = doc.subscribe(() => this.scheduleNotification());
+	}
+	getState() {
+		this.assertActive();
+		return {
+			canUndo: this.manager.canUndo(),
+			canRedo: this.manager.canRedo()
+		};
+	}
+	undo(options) {
+		return this.applyUndoRedo("Undo", options);
+	}
+	redo(options) {
+		return this.applyUndoRedo("Redo", options);
+	}
+	beginGroup() {
+		this.assertActive();
+		this.mutationGuard.run(() => this.manager.groupStart());
+	}
+	endGroup() {
+		this.assertActive();
+		this.mutationGuard.run(() => this.manager.groupEnd());
+		this.scheduleNotification();
+	}
+	applyUndoRedo(kind, options) {
+		this.assertActive();
+		return this.mutationGuard.run(() => {
+			if (kind === "Undo" ? !this.manager.canUndo() : !this.manager.canRedo()) return false;
+			this.activeSource = kind === "Undo" ? this.manager.topUndoValue() : this.manager.topRedoValue();
+			try {
+				this.doc.setNextCommitOptions({ message: JSON.stringify({
+					semantic_op: kind,
+					payload: { source: this.activeSource },
+					intent: options?.intent ?? null,
+					actor: options?.actor ?? null
+				}) });
+				const before = this.doc.oplogFrontiers();
+				return (kind === "Undo" ? this.manager.undo() : this.manager.redo()) && this.doc.cmpWithFrontiers(before) !== 0;
+			} finally {
+				this.doc.clearNextCommitOptions();
+				this.activeSource = null;
+				this.scheduleNotification();
+			}
+		});
+	}
+	dispose() {
+		if (this.disposed) return;
+		this.disposed = true;
+		this.unsubscribe();
+		this.manager.setOnPush(void 0);
+		this.manager.setOnPop(void 0);
+		this.manager.free();
+	}
+	scheduleNotification() {
+		if (this.notificationQueued || this.disposed) return;
+		this.notificationQueued = true;
+		queueMicrotask(() => {
+			this.notificationQueued = false;
+			if (!this.disposed) this.publish();
+		});
+	}
+	publish() {
+		if (this.disposed) return;
+		const state = this.getState();
+		if (state.canUndo === this.published.canUndo && state.canRedo === this.published.canRedo) return;
+		this.published = state;
+		this.onChange();
+	}
+	assertActive() {
+		if (this.disposed) throw new Error("mengine doc undo manager is disposed");
+	}
+};
+//#endregion
 //#region src/session/mengine-doc-session.ts
 /**
 * Raised by {@link MengineDocSession.waitForServerAck} when the local edits it
@@ -4602,13 +6322,9 @@ var MengineAckFailedError = class extends Error {
 * A live editing session for one Medeo document — the single entry point clients
 * (FE draft driver, Agent, embeds) use to open, edit, and observe a document.
 *
-* It assembles the engine sync stack around one Medeo document:
-*
-*   local DocStorage  ─┐
-*                      ├─ ClientServerSynchronizer ── DocManager ── LoroDoc
-*   MedeoHttpDocStorage┘                                              │
-*                          (remote = Rust mengine-server)             ▼
-*                                                   MirrorVideoDocumentAdapter + SemanticEditor
+* SemanticEditor writes through MirrorVideoDocumentAdapter directly, while
+* DocumentUndoManager observes the same LoroDoc independently. Both mutation
+* paths use the session's DocumentMutationGuard, closed before teardown.
 *
 * `DocManager` owns the `LoroDoc`: local edits committed on the adapter are
 * picked up via `subscribeLocalUpdates`, saved to local storage, then pushed to
@@ -4629,11 +6345,20 @@ var MengineDocSession = class {
 	manager;
 	events = new EventBus();
 	disposables = new DisposableSet();
+	mutationGuard = new DocumentMutationGuard();
 	adapterValue = null;
 	editorValue = null;
+	undoManagerValue = null;
 	started = false;
+	startTask = null;
+	destroyed = false;
+	lifetime = null;
+	hasConnected = false;
+	initialVersionValue = null;
+	localVersionValue = null;
+	pushErrorValue = null;
 	/**
-	* Latest server oplog version seen on a push outcome. Lets `waitForServerAck`
+	* Latest server oplog version seen on an authoritative HTTP response. Lets `waitForServerAck`
 	* return without waiting when the server is already known to cover the local
 	* doc (e.g. nothing was edited since the last confirmed push).
 	*/
@@ -4662,14 +6387,14 @@ var MengineDocSession = class {
 		return this.server.subscribePushOutcome(callback);
 	}
 	/**
-	* Resolve once the server has durably accepted the local document state as of
+	* Resolve once the server has durably accepted the local commits as of
 	* *now* — the capability an Agent tool needs to answer "did my edit land?"
 	* before reporting success.
 	*
 	* Call it right after the editor ops whose durability matters. It snapshots the
-	* local doc's current version and resolves on the first push outcome whose
-	* `serverVV` covers that version, i.e. the server log is at least as advanced as
-	* the local doc was when this was called.
+	* latest local commit's version (or the loaded baseline before any edit) and
+	* resolves when an authoritative server version covers it. Remote-only
+	* imports do not extend this target, matching the displayed confirmation state.
 	*
 	* Version coverage, not byte identity, is the acceptance test — for two reasons:
 	* the ops may reach the server inside a merged blob rather than as the exact
@@ -4684,31 +6409,39 @@ var MengineDocSession = class {
 	* @throws {MengineAckFailedError} on timeout, rejection, or transport failure.
 	*/
 	async waitForServerAck(options = {}) {
-		if (this.adapterValue == null) throw new Error("mengine doc session is not started");
+		if (this.adapterValue == null || this.lifetime == null) throw new Error("mengine doc session is not started");
 		const timeoutMs = options.timeoutMs ?? 15e3;
-		const target = this.manager.connectDoc(this.docId).version();
+		const target = this.confirmationTarget() ?? this.manager.connectDoc(this.docId).version();
+		const signal = this.lifetime.signal;
 		if (this.serverVVValue != null && serverCovers(this.serverVVValue, target)) return;
 		await new Promise((resolve, reject) => {
-			let off = () => {};
+			const cleanup = [];
 			let done = false;
 			const settle = (error) => {
 				if (done) return;
 				done = true;
 				clearTimeout(timer);
-				off();
+				cleanup.forEach((off) => off());
 				if (error == null) resolve();
 				else reject(error);
 			};
 			const timer = setTimeout(() => {
 				settle(new MengineAckFailedError("timeout", void 0, void 0, `mengine did not acknowledge the update within ${timeoutMs}ms`));
 			}, timeoutMs);
-			off = this.server.subscribePushOutcome((outcome) => {
+			const onAbort = () => settle(new MengineAckFailedError("failed", void 0, void 0, "mengine doc session destroyed"));
+			signal.addEventListener("abort", onAbort, { once: true });
+			cleanup.push(() => signal.removeEventListener("abort", onAbort));
+			cleanup.push(this.events.on("syncState", () => {
+				if (this.serverVVValue != null && serverCovers(this.serverVVValue, target)) settle(void 0);
+			}));
+			cleanup.push(this.server.subscribePushOutcome((outcome) => {
 				if (outcome.kind === "rejected" || outcome.kind === "failed") {
 					settle(new MengineAckFailedError(outcome.kind, outcome.code, outcome.error, outcome.error?.message ?? `mengine push ${outcome.kind}`));
 					return;
 				}
-				if (outcome.serverVV != null && serverCovers(outcome.serverVV, target)) settle(void 0);
-			});
+			}));
+			if (signal.aborted) onAbort();
+			else this.synchronizer.requestSync(this.docId);
 		});
 	}
 	/**
@@ -4744,44 +6477,154 @@ var MengineDocSession = class {
 		if (this.adapterValue == null) throw new Error("mengine doc session is not started");
 		return this.adapterValue.snapshot();
 	}
+	/** Current-session undo/redo availability. Loading and closed sessions report false. */
+	getUndoState() {
+		return this.undoManagerValue?.getState() ?? {
+			canUndo: false,
+			canRedo: false
+		};
+	}
+	/**
+	* Supplies current availability immediately, then coalesces stack changes in a
+	* microtask. Session teardown publishes empty availability synchronously.
+	*/
+	subscribeUndoState(cb) {
+		const notify = () => cb(this.getUndoState());
+		const off = this.destroyed ? () => {} : this.events.on("undoState", notify);
+		notify();
+		return off;
+	}
+	/**
+	* Undo a local edit immediately; server confirmation remains asynchronous.
+	* On a shared LWW field this writes its prior value, potentially overwriting a
+	* later remote edit to that same field. Returns false if no update is produced.
+	*/
+	undo(options) {
+		if (this.undoManagerValue == null) throw new Error("mengine doc undo manager is not ready");
+		return this.undoManagerValue.undo(options);
+	}
+	/**
+	* Restore the state visible before undo without rerunning external side effects.
+	* Returns false if no update is produced; durable confirmation is separate.
+	*/
+	redo(options) {
+		if (this.undoManagerValue == null) throw new Error("mengine doc undo manager is not ready");
+		return this.undoManagerValue.redo(options);
+	}
+	/**
+	* Combine existing semantic operations (e.g. trim a clip and adjust its volume)
+	* or repeated commits during one drag gesture into a single undo step. A gesture
+	* that only previews locally and commits once on release needs no group.
+	* Each commit is immediately visible locally and enters sync independently;
+	* a later failure does not roll it back.
+	* Always pair with endUndoGroup in a finally block. Conflicting remote imports
+	* can end/split the group early, and unrelated local edits would join it.
+	* Complete asynchronous asset preparation before opening the group.
+	*/
+	beginUndoGroup() {
+		if (this.undoManagerValue == null) throw new Error("mengine doc undo manager is not ready");
+		this.undoManagerValue.beginGroup();
+	}
+	/** End a gesture, including one already split by a conflicting remote import. */
+	endUndoGroup() {
+		if (this.undoManagerValue == null) throw new Error("mengine doc undo manager is not ready");
+		this.undoManagerValue.endGroup();
+	}
 	/**
 	* Start the sync stack and connect the document.
 	*
-	* Returns once the local snapshot has loaded into the Loro doc so callers can
-	* read an initial snapshot. Remote convergence continues in the background and
-	* surfaces through `subscribe`.
+	* Returns after DocManager loads a local snapshot, or after the first remote
+	* sync when no local snapshot exists. A valid empty document is ready too.
+	* Cached documents can open before SSE connects; subsequent remote changes
+	* surface through `subscribe`.
 	*/
-	async start() {
-		if (this.started) return this.snapshot();
+	start() {
+		if (this.destroyed) return Promise.reject(/* @__PURE__ */ new Error("mengine doc session destroyed"));
+		if (this.startTask != null) return this.startTask;
 		this.started = true;
-		this.local.connection.connect();
-		this.server.connection.connect();
+		this.lifetime = new AbortController();
+		this.startTask = this.open().catch((error) => {
+			const wasDestroyed = this.destroyed;
+			this.destroy();
+			if (wasDestroyed) throw new Error("mengine doc session destroyed");
+			throw error;
+		});
+		return this.startTask;
+	}
+	async open() {
+		this.disposables.add(this.server.subscribeResync(() => this.synchronizer.requestSync(this.docId)));
+		this.disposables.add(this.server.subscribeServerVersion((version) => {
+			this.serverVVValue = version;
+			if (this.getSyncState().confirmation === "confirmed") this.pushErrorValue = null;
+			this.emitSyncState();
+		}));
+		this.disposables.add(this.server.subscribePushOutcome((outcome) => {
+			this.pushErrorValue = outcome.kind === "failed" || outcome.kind === "rejected" ? outcome.error ?? /* @__PURE__ */ new Error(`mengine push ${outcome.kind}`) : null;
+			this.emitSyncState();
+		}));
+		this.disposables.add(this.server.connection.onStatusChanged((status) => {
+			if (status === "connected") this.hasConnected = true;
+			this.emitSyncState();
+		}));
 		this.disposables.add(() => this.local.connection.disconnect());
 		this.disposables.add(() => this.server.connection.disconnect());
+		this.local.connection.connect();
+		await this.local.connection.waitForConnected().abortOn(this.lifetime.signal);
+		if (this.destroyed) throw new Error("mengine doc session destroyed");
+		this.server.connection.connect();
 		this.synchronizer.start();
 		this.manager.start();
 		this.disposables.add(() => this.synchronizer.stop());
 		this.disposables.add(() => this.manager.stop());
 		const doc = this.manager.connectDoc(this.docId);
-		if (this.options.peerId != null) doc.setPeerId(this.options.peerId);
-		this.adapterValue = new MirrorVideoDocumentAdapter(doc);
-		this.editorValue = new SemanticEditor(this.adapterValue);
 		this.disposables.add(() => this.manager.disconnectDoc(this.docId));
+		if (this.options.peerId != null) doc.setPeerId(this.options.peerId);
+		this.adapterValue = new MirrorVideoDocumentAdapter(doc, this.mutationGuard);
 		const unsubscribe = doc.subscribe((event) => {
 			if (this.adapterValue == null) return;
+			if (event.by === "local") this.localVersionValue = doc.version();
+			this.emitSyncState();
 			this.events.emit("update", {
 				source: event.by === "local" ? "local" : "remote",
 				snapshot: this.adapterValue.snapshot()
 			});
 		});
 		this.disposables.add(unsubscribe);
-		this.disposables.add(this.manager.onDocStateChange(this.docId, (state) => this.events.emit("state", state)));
-		this.disposables.add(this.server.subscribePushOutcome((outcome) => {
-			if (outcome.serverVV != null) this.serverVVValue = outcome.serverVV;
+		this.disposables.add(this.manager.onDocStateChange(this.docId, (state) => {
+			this.events.emit("state", state);
+			this.emitSyncState();
 		}));
-		await this.waitForContent();
+		await this.waitForInitialLoad();
+		if (this.destroyed) throw new Error("mengine doc session destroyed");
+		assertValidVideoDocument(this.snapshot());
+		this.undoManagerValue = new DocumentUndoManager(doc, this.mutationGuard, () => this.events.emit("undoState"));
+		this.editorValue = new SemanticEditor(this.adapterValue);
+		this.initialVersionValue = doc.version();
+		this.emitSyncState();
 		return this.snapshot();
 	}
+	getSyncState() {
+		const state = this.getState();
+		const target = this.confirmationTarget();
+		const confirmation = this.serverVVValue == null || target == null ? this.localVersionValue == null ? "unknown" : "pending" : serverCovers(this.serverVVValue, target) ? "confirmed" : "pending";
+		const connection = !this.started ? "disconnected" : this.server.connection.status === "connected" ? "connected" : this.hasConnected || this.server.connection.error != null ? "disconnected" : "connecting";
+		return {
+			confirmation,
+			phase: connection === "disconnected" ? "offline" : this.pushErrorValue != null || state.error != null ? "failed" : connection === "connecting" ? "connecting" : state.syncing ? "syncing" : "idle"
+		};
+	}
+	confirmationTarget() {
+		return this.localVersionValue ?? this.initialVersionValue;
+	}
+	/** Immediately supplies current state; unsubscribe when the host changes docs. */
+	subscribeSyncState(cb) {
+		const off = this.events.on("syncState", cb);
+		cb(this.getSyncState());
+		return off;
+	}
+	emitSyncState() {
+		this.events.emit("syncState", this.getSyncState());
+	}
 	subscribe(cb) {
 		return this.events.on("update", cb);
 	}
@@ -4792,40 +6635,48 @@ var MengineDocSession = class {
 		return this.manager.getDocState(this.docId);
 	}
 	destroy() {
+		if (this.destroyed) return;
+		this.destroyed = true;
+		this.mutationGuard.close();
+		this.started = false;
+		this.lifetime?.abort();
+		this.undoManagerValue?.dispose();
+		this.undoManagerValue = null;
+		this.events.emit("undoState");
 		this.disposables.dispose();
+		this.emitSyncState();
 		this.events.clearAll();
+		this.adapterValue?.dispose();
 		this.adapterValue = null;
 		this.editorValue = null;
 		this.started = false;
 	}
-	/**
-	* Resolve once the Loro doc holds the document root.
-	*
-	* `DocManager` loads from local storage, which starts empty for a fresh
-	* client; the server snapshot arrives asynchronously via the first sync job.
-	* `loaded` only means the local load ran, so we wait for actual content
-	* (populated schema roots) instead, surfaced by the doc subscription set up
-	* in `start()`.
-	*/
-	async waitForContent() {
-		if (this.hasContent()) return;
-		await new Promise((resolve) => {
-			const off = this.events.on("update", () => {
-				if (this.hasContent()) {
-					off();
-					resolve();
-				}
-			});
+	/** Local absence needs a remote sync; empty business content does not. */
+	async waitForInitialLoad() {
+		const signal = this.lifetime.signal;
+		await new Promise((resolve, reject) => {
+			let off = () => {};
+			let offConnection = () => {};
+			const finish = (error) => {
+				off();
+				offConnection();
+				signal.removeEventListener("abort", onAbort);
+				if (error != null) reject(error);
+				else resolve();
+			};
+			const onAbort = () => finish(/* @__PURE__ */ new Error("mengine doc session destroyed"));
+			const check = (state) => {
+				if (state.loaded && (state.loadedFromLocal || state.synced)) finish();
+				else if (state.error != null) finish(new Error(state.error));
+				else if (state.loaded && this.server.connection.error != null) finish(this.server.connection.error);
+			};
+			off = this.onStateChange(check);
+			offConnection = this.server.connection.onStatusChanged(() => check(this.getState()));
+			signal.addEventListener("abort", onAbort, { once: true });
+			if (signal.aborted) onAbort();
+			else check(this.getState());
 		});
 	}
-	hasContent() {
-		if (this.adapterValue == null) return false;
-		try {
-			return this.adapterValue.hasContent();
-		} catch {
-			return false;
-		}
-	}
 };
 /**
 * True when the *encoded* server version `serverVV` includes everything in
@@ -4849,4 +6700,4 @@ function serverCovers(serverVV, target) {
 	return covers(server, target);
 }
 //#endregion
-export { DEFAULT_UNIT_TIME_MS, ENTITY_TIMELINE_PROJECTION_SCHEMA_VERSION, EntityGraphHttpClient, EntityTimelineEditor, EntityTimelineProjectionError, IMPLEMENTED_SEMANTIC_OP_KINDS, LANE_KINDS_IN_STACK_ORDER, LORO_ENTITY_SCHEMA, LoroEntityDocument, LoroEntityDraft, ManualSyncDoc, MedeoHttpDocStorage, MemoryDocStorage, MengineAckFailedError, MengineDocSession, MengineHttpClient, MengineHttpRequestError, MenginePushRejectedError, MirrorVideoDocumentAdapter, PlainMemoryAdapter, SchemaValidator, ScriptCompositionError, SemanticEditor, TIMELINE_SKELETON_DURATION_MS, VIDEO_DOCUMENT_SCHEMA_VERSION, ValidationError, VideoDocumentValidationError, applyEntityRows, applyEntityTimelineProjection, applyFieldChanges, arrangeMainTrackSeamlessly, assembleCaptionContent, assembleEntityContent, assemblePhoneticScriptContent, assembleScriptText, assertCanonicalEditorResources, assertEntityProjectionPreservesLegacy, assertFieldChanges, assertMediaAssetWritePolicy, assertValidVideoDocument, base64ToBytes, buildInitialVideoDocument, buildSpeechHostMap, bytesToBase64, cascadeAfterVideoClipChanges, compileEntityRows, createEditSandbox, createMirrorVideoDocument, createMirrorVideoDocumentAdapter, createPlainMemoryAdapter, decodeDocVersionMark, derivePositionFromAbs, effectiveVideoClipDurationMs, encodeDocVersionMark, ensureEditorFoundation, ensureLaneTrack, fillMainTrackTimeGaps, findComposedAudioScript, findLaneTrack, fromVideoDocument, generatePartId, getAt, hostForAbsMs, importMediaAsset, isEmptyVideoClip, isImplementedSemanticOpKind, isMap, laneTrackId, mainTrackRanges, migrateLegacyTimelineToEntities, partDurationMs, partUnionSchema, prepareCaptionContent, projectEntityTimeline, readDocumentAudioScript, readEntityDocument, readMainTrackItems, readMengineEventStream, readPart, readPartDurationMs, readVideoDocumentFromDraft, reassignSpeechesToVideoClipsByTime, recalculateTimelineDuration, relativePositionForAbs, replayJournal, resolveAllSpeechOverlaps, resolveEntityTimelineLayout, resolveFieldPath, resolveSpeechOverlapByShiftingVideos, safeDurationMs, schemas_exports as schemas, selectAudioScriptSegment, snapshotToPlain, solveVideoDocument, speedOf, syncAggregatedClipsTimePosition, toVideoDocument, validateVideoDocument, videoDocumentMirrorSchema, videoDocumentSchema, writeVideoDocumentToDraft };
+export { DEFAULT_UNIT_TIME_MS, EntityGraphHttpClient, EntityTimelineEditor, EntityTimelineProjectionError, IMPLEMENTED_SEMANTIC_OP_KINDS, LANE_KINDS_IN_STACK_ORDER, LORO_ENTITY_SCHEMA, LoroEntityDocument, LoroEntityDraft, ManualSyncDoc, MedeoHttpDocStorage, MemoryDocStorage, MengineAckFailedError, MengineDocSession, MengineHttpClient, MengineHttpRequestError, MenginePushRejectedError, MirrorVideoDocumentAdapter, PlainMemoryAdapter, SchemaValidator, ScriptCompositionError, SemanticEditor, TIMELINE_SKELETON_DURATION_MS, ValidationError, VideoDocumentValidationError, applyEntityRows, applyFieldChanges, arrangeMainTrackSeamlessly, assembleCaptionContent, assembleEntityContent, assemblePhoneticScriptContent, assembleScriptText, assertCanonicalEditorResources, assertEntityProjectionPreservesLegacy, assertFieldChanges, assertMediaAssetWritePolicy, assertValidVideoDocument, audioScriptAssetContent, audioScriptAssetFields, audioScriptAssetHash, audioScriptAssetOf, base64ToBytes, buildInitialVideoDocument, buildSpeechHostMap, bytesToBase64, cascadeAfterVideoClipChanges, 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, phoneticScriptAssetContent, phoneticScriptAssetHash, phoneticScriptAssetOf, 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, scriptSourceAssetOf, selectAudioScriptSegment, snapshotToPlain, solveVideoDocument, speedOf, syncAggregatedClipsTimePosition, toVideoDocument, validateVideoDocument, videoDocumentMirrorSchema, videoDocumentSchema };