@mengine/medeo-client 1.2.1-alpha.9 → 1.3.1-alpha.0

package/dist/index.js

@@ -1,4 +1,4 @@
-import { $ as base64ToBytes, A as findLaneTrack, B as syncAggregatedClipsTimePosition, C as VideoDocumentValidationError, D as videoDocumentSchema, E as partUnionSchema, F as fillMainTrackTimeGaps, G as DEFAULT_UNIT_TIME_MS, H as isEmptyVideoClip, I as reassignSpeechesToVideoClipsByTime, J as effectiveVideoClipDurationMs, K as ENTITY_TIMELINE_PROJECTION_SCHEMA_VERSION, L as recalculateTimelineDuration, M as solveVideoDocument, N as cascadeAfterVideoClipChanges, O as LANE_KINDS_IN_STACK_ORDER, P as arrangeMainTrackSeamlessly, Q as videoDocumentMirrorSchema, R as resolveAllSpeechOverlaps, S as toVideoDocument, T as validateVideoDocument, U as partDurationMs, V as TIMELINE_SKELETON_DURATION_MS, W as safeDurationMs, X as partUnionToDraft, Y as speedOf, Z as recordEntries, _ as EntityTimelineProjectionError, a as applyEntityTimelineProjection, b as derivePositionFromAbs, c as writeVideoDocumentToDraft, d as resolveEntityTimelineLayout, et as bytesToBase64, f as decodeEntityRelationRows, g as hasSequence, h as createRelationId, i as MirrorVideoDocumentAdapter, j as laneTrackId, k as ensureLaneTrack, l as readVideoDocumentFromDraft, m as createEntityId, n as createPlainMemoryAdapter, o as createMirrorVideoDocument, p as isJsonObject, q as VIDEO_DOCUMENT_SCHEMA_VERSION, r as generatePartId, s as createMirrorVideoDocumentAdapter, t as PlainMemoryAdapter, u as projectEntityTimeline, v as buildInitialVideoDocument, w as assertValidVideoDocument, x as fromVideoDocument, y as buildSpeechHostMap, z as resolveSpeechOverlapByShiftingVideos } from "./document-Df6awJDH.js";
+import { $ as videoDocumentMirrorSchema, A as ensureLaneTrack, B as resolveSpeechOverlapByShiftingVideos, C as toVideoDocument, D as partUnionSchema, E as validateVideoDocument, F as arrangeMainTrackSeamlessly, G as safeDurationMs, H as TIMELINE_SKELETON_DURATION_MS, I as fillMainTrackTimeGaps, J as VIDEO_DOCUMENT_SCHEMA_VERSION, K as DEFAULT_UNIT_TIME_MS, L as reassignSpeechesToVideoClipsByTime, M as laneTrackId, N as solveVideoDocument, O as videoDocumentSchema, P as cascadeAfterVideoClipChanges, Q as recordEntries, R as recalculateTimelineDuration, S as fromVideoDocument, T as assertValidVideoDocument, U as isEmptyVideoClip, V as syncAggregatedClipsTimePosition, W as partDurationMs, X as speedOf, Y as effectiveVideoClipDurationMs, Z as partUnionToDraft, _ as hasSequence, a as applyEntityTimelineProjection, b as buildSpeechHostMap, c as writeVideoDocumentToDraft, d as resolveEntityTimelineLayout, et as base64ToBytes, f as EntityTimelineProjectionError, g as createRelationId, h as createEntityId, i as MirrorVideoDocumentAdapter, j as findLaneTrack, k as LANE_KINDS_IN_STACK_ORDER, l as readVideoDocumentFromDraft, m as isJsonObject, n as createPlainMemoryAdapter, o as createMirrorVideoDocument, p as decodeEntityRelationRows, q as ENTITY_TIMELINE_PROJECTION_SCHEMA_VERSION, r as generatePartId, s as createMirrorVideoDocumentAdapter, t as PlainMemoryAdapter, tt as bytesToBase64, u as projectEntityTimeline, v as isMediaAssetVariantKind, w as VideoDocumentValidationError, x as derivePositionFromAbs, y as buildInitialVideoDocument, z as resolveAllSpeechOverlaps } from "./document-Caidonf8.js";
 import { addSpeechesInputSchema, addVideoClipsInputSchema, adjustBgmVolumeInputSchema, adjustSpeechVolumeInputSchema, adjustVideoClipDurationInputSchema, adjustVideoClipVolumeInputSchema, changeSpeechScriptInputSchema, changeSpeechVoiceInputSchema, deleteBgmInputSchema, deleteSpeechesInputSchema, deleteVideoClipsInputSchema, moveSpeechesInputSchema, moveVideoClipsByAnchorInputSchema, moveVideoClipsInputSchema, replaceVideoClipContentInputSchema, replaceVideoClipSequenceInputSchema, setBgmInputSchema, setCaptionStyleInputSchema, setCaptionVisibilityInputSchema, setVideoClipSpeedShiftInputSchema, t as schemas_exports } from "./schemas.js";
 import { LoroDoc, VersionVector } from "loro-crdt";
 import { ClientServerSynchronizer, DocManager } from "@mengine/sync";
@@ -217,6 +217,149 @@ function findSseFrameBoundary(buffer) {
 	return Math.min(lf, crlf);
 }
 //#endregion
+//#region src/entity-editor/editor-resources.ts
+const roleOrder$1 = {
+	caption: 0,
+	video_clip: 1,
+	speech: 2,
+	bgm: 3
+};
+/**
+* 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 inline text keeps its inline Asset and
+* `physical-asset` binding.
+*/
+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);
+	}
+	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`);
+	}
+}
+/**
+* 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:
+*
+* 1. every Image/Video/Audio/Voice Entity carries its own Asset `external`
+*    identity;
+* 2. no `physical-asset` Relation may bind a media variant (Caption inline
+*    text keeps its inline Asset and binding);
+* 3. a self-carried media identity is immutable — it cannot be rewritten to
+*    another asset id.
+*
+* Dual-entity media graphs are rejected instead of being migrated or merged
+* implicitly. 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]));
+	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`);
+	}
+}
+function memotaLocator(value) {
+	if (!isJsonObject(value) || value.system !== "memota" && value.system !== "memota-speech" || typeof value.key !== "string" || value.key.trim() === "") return;
+	return {
+		system: value.system,
+		key: value.key
+	};
+}
+/** Add only missing editor structure; existing identities and owned settings are never replaced. */
+function ensureEditorFoundation(initial, idFactory = (prefix) => `${prefix}_${globalThis.crypto.randomUUID()}`, timelinePayload = {}) {
+	const entities = structuredClone([...initial.entities]);
+	const relations = structuredClone([...initial.relations]);
+	const roots = entities.filter((row) => row.entityKind === "timeline");
+	if (roots.length > 1) throw new EntityTimelineProjectionError("Editor requires exactly one Timeline");
+	const mintEntity = () => {
+		const id = createEntityId(idFactory("entity"));
+		if (entities.some((row) => row.entityId === id)) throw new Error(`Duplicate entity id ${id}`);
+		return id;
+	};
+	let timeline = roots[0];
+	if (timeline === void 0) {
+		timeline = {
+			entityId: mintEntity(),
+			entityKind: "timeline",
+			payload: structuredClone(timelinePayload)
+		};
+		entities.push(timeline);
+	}
+	const trackEntityIds = {};
+	for (const role of Object.keys(roleOrder$1)) {
+		const matches = entities.filter((row) => row.entityKind === "track" && row.payload.role === role);
+		if (matches.length > 1) throw new EntityTimelineProjectionError(`Editor has multiple ${role} Tracks`);
+		let track = matches[0];
+		if (track === void 0) {
+			track = {
+				entityId: mintEntity(),
+				entityKind: "track",
+				payload: {
+					role,
+					order: roleOrder$1[role]
+				}
+			};
+			entities.push(track);
+		}
+		const bindings = relations.filter((row) => row.relationKind === "timeline-track" && (row.endpoint0EntityId === track.entityId || row.endpoint1EntityId === track.entityId));
+		if (bindings.some((row) => row.endpoint0EntityId !== timeline.entityId && row.endpoint1EntityId !== timeline.entityId)) throw new EntityTimelineProjectionError(`Track ${track.entityId} belongs to another Timeline`);
+		if (bindings.length === 0) {
+			const relationId = createRelationId(idFactory("relation"));
+			if (relations.some((row) => row.relationId === relationId)) throw new Error(`Duplicate relation id ${relationId}`);
+			relations.push({
+				relationId,
+				relationKind: "timeline-track",
+				endpoint0EntityId: timeline.entityId,
+				endpoint1EntityId: track.entityId,
+				metadata: {},
+				trace: {}
+			});
+		}
+		trackEntityIds[role] = track.entityId;
+	}
+	return {
+		rows: {
+			entities,
+			relations
+		},
+		timelineEntityId: timeline.entityId,
+		trackEntityIds
+	};
+}
+//#endregion
 //#region src/entity-editor/entity-graph-http-client.ts
 const MENGINE_API_PREFIX = "/api/mengine/v1";
 const numericMarkerValidation$1 = { compareMarkerPoints: (_marker, _range, left, right) => {
@@ -248,6 +391,7 @@ var EntityGraphHttpClient = class {
 		if (!isNonNegativeSafeInteger(baseState.revision)) throw new Error("Entity graph revision must be a non-negative safe integer");
 		const baseRows = cloneAndValidateRows(baseState.rows);
 		const next = cloneAndValidateRows(nextRows);
+		assertMediaAssetWritePolicy(baseRows, next);
 		const nextEntityIds = new Set(next.entities.map((row) => row.entityId));
 		const nextRelationIds = new Set(next.relations.map((row) => row.relationId));
 		const deletedEntityIds = baseRows.entities.map((row) => row.entityId).filter((entityId) => !nextEntityIds.has(entityId)).sort();
@@ -356,8 +500,18 @@ 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 at the editor boundary, not at asset generation time. Existing provenance is retained. */
-function importMediaAsset(initial, fact, idFactory = (prefix) => `${prefix}_${globalThis.crypto.randomUUID()}`, selection = {}) {
+/**
+* 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.
+*/
+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");
 	if (![
 		"image",
@@ -368,59 +522,32 @@ function importMediaAsset(initial, fact, idFactory = (prefix) => `${prefix}_${gl
 	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`);
 	decodeEntityRelationRows(initial, numericCoordinates);
+	assertCanonicalEditorResources(initial);
 	const entities = structuredClone([...initial.entities]);
 	const relations = structuredClone([...initial.relations]);
-	const assets = entities.filter((row) => {
+	const system = fact.kind === "voice" ? "memota-speech" : "memota";
+	const existing = entities.filter((row) => {
 		const external = row.payload.external;
-		return row.entityKind === "asset" && isJsonObject(external) && external.system === (fact.kind === "voice" ? "memota-speech" : "memota") && external.key === fact.assetId && (selection.assetEntityId === void 0 || row.entityId === selection.assetEntityId);
+		return isMediaAssetVariantKind(row.entityKind) && isJsonObject(external) && external.system === system && external.key === fact.assetId;
 	});
-	if (selection.assetEntityId !== void 0 && assets.length !== 1) throw new Error("Selected Asset does not match the recalled asset facts");
-	if (assets.length > 1) throw new Error(`Ambiguous Asset bindings for ${fact.assetId}; select assetEntityId explicitly`);
-	const mintEntity = () => {
-		const id = createEntityId(idFactory("entity"));
-		if (entities.some((row) => row.entityId === id)) throw new Error(`Duplicate entity id ${id}`);
-		return id;
-	};
-	let asset = assets[0];
-	if (asset === void 0) {
-		asset = {
-			entityId: mintEntity(),
-			entityKind: "asset",
-			payload: {
-				external: {
-					system: fact.kind === "voice" ? "memota-speech" : "memota",
-					key: fact.assetId
-				},
-				...fact.storageKey === void 0 ? {} : { storageKey: fact.storageKey }
-			}
+	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);
+		return {
+			rows: {
+				entities,
+				relations
+			},
+			contentEntityId: variant.entityId
 		};
-		entities.push(asset);
-	} else if (fact.storageKey !== void 0) {
-		if (asset.payload.storageKey !== void 0 && asset.payload.storageKey !== fact.storageKey) throw new Error(`Media facts conflict with existing storage key for ${fact.assetId}`);
-		if (asset.payload.storageKey === void 0) {
-			asset = {
-				...asset,
-				payload: {
-					...asset.payload,
-					storageKey: fact.storageKey
-				}
-			};
-			const assetIndex = entities.findIndex((row) => row.entityId === asset.entityId);
-			entities[assetIndex] = asset;
-		}
 	}
-	const bindings = relations.filter((row) => row.relationKind === "physical-asset" && (row.endpoint0EntityId === asset.entityId || row.endpoint1EntityId === asset.entityId) && (selection.contentEntityId === void 0 || (row.endpoint0EntityId === asset.entityId ? row.endpoint1EntityId : row.endpoint0EntityId) === selection.contentEntityId));
-	const contentIds = new Set(bindings.map((row) => row.endpoint0EntityId === asset.entityId ? row.endpoint1EntityId : row.endpoint0EntityId));
-	if (selection.contentEntityId !== void 0 && contentIds.size !== 1) throw new Error("Selected media Entity is not bound to the selected Asset");
-	if (contentIds.size > 1) throw new Error(`Ambiguous media bindings for ${fact.assetId}; select contentEntityId explicitly`);
-	let content;
-	if (bindings[0] !== void 0) {
-		const relation = bindings[0];
-		content = entities.find((row) => row.entityId === (relation.endpoint0EntityId === asset.entityId ? relation.endpoint1EntityId : relation.endpoint0EntityId));
-		const extent = content?.payload.extent;
-		if (content?.entityKind !== fact.kind || fact.kind !== "image" && (!isJsonObject(extent) || extent.start !== 0 || extent.end !== fact.durationMs) || fact.kind === "voice" && !sameVoice(content.payload.voice, fact.voice)) throw new Error(`Media facts conflict with existing binding for ${fact.assetId}`);
-	} else {
-		const payload = {
+	const entityId = createEntityId(idFactory("entity"));
+	if (entities.some((row) => row.entityId === entityId)) throw new Error(`Duplicate entity id ${entityId}`);
+	const variant = {
+		entityId,
+		entityKind: fact.kind,
+		payload: {
 			extent: fact.kind === "image" ? {
 				kind: "unbounded",
 				start: 0
@@ -431,43 +558,52 @@ function importMediaAsset(initial, fact, idFactory = (prefix) => `${prefix}_${gl
 			},
 			sampling: fact.kind === "image" ? "constant" : "native",
 			coordinateSpace: "milliseconds",
-			...fact.kind === "voice" ? { voice: {
+			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 }
 			} } : {}
-		};
-		const createdContent = {
-			entityId: mintEntity(),
-			entityKind: fact.kind,
-			payload
-		};
-		content = createdContent;
-		entities.push(createdContent);
-		const relationId = createRelationId(idFactory("relation"));
-		if (relations.some((row) => row.relationId === relationId)) throw new Error(`Duplicate relation id ${relationId}`);
-		relations.push({
-			relationId,
-			relationKind: "physical-asset",
-			endpoint0EntityId: createdContent.entityId,
-			endpoint1EntityId: asset.entityId,
-			metadata: {},
-			trace: {}
-		});
-	}
+		}
+	};
+	entities.push(variant);
 	const rows = {
 		entities,
 		relations
 	};
 	decodeEntityRelationRows(rows, numericCoordinates);
-	if (content === void 0) throw new Error(`Media Entity could not be resolved for ${fact.assetId}`);
+	assertCanonicalEditorResources(rows);
 	return {
 		rows,
-		assetEntityId: asset.entityId,
-		contentEntityId: content.entityId
+		contentEntityId: entityId
 	};
 }
+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,
+			payload: {
+				...row.payload,
+				storageKey: fact.storageKey
+			}
+		};
+	}
+	return row;
+}
+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
@@ -983,9 +1119,13 @@ var EntityTimelineEditor = class {
 	upsertVoiceoverTake(input) {
 		return this.transact((draft) => {
 			this.normalizeMainSequential(draft);
-			finiteNonNegative(input.anchorOffset, "Voiceover anchorOffset");
+			const placement = input.placement ?? {
+				kind: "anchored",
+				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");
 			requireVolume(input.volume);
-			requireClipOnRole(draft, input.hostClipEntityId, "video_clip");
 			const imported = importMediaAsset(draft, input.media, this.idFactory);
 			replaceRows(draft, imported.rows);
 			const voice = requireEntityKind(draft, imported.contentEntityId, "voice");
@@ -1005,11 +1145,7 @@ var EntityTimelineEditor = class {
 					mode: "fixed",
 					value: input.media.durationMs
 				},
-				placement: {
-					kind: "anchored",
-					hostClipEntityId: input.hostClipEntityId,
-					anchorOffset: input.anchorOffset
-				},
+				placement,
 				clipPayload: { volume: input.volume }
 			});
 			else {
@@ -1026,11 +1162,7 @@ var EntityTimelineEditor = class {
 					endpoint0EntityId: topology.marker.entityId,
 					endpoint1EntityId: voice.entityId
 				});
-				this.applyClipPlacement(draft, topology.clip.entityId, {
-					kind: "anchored",
-					hostClipEntityId: input.hostClipEntityId,
-					anchorOffset: input.anchorOffset
-				});
+				this.applyClipPlacement(draft, topology.clip.entityId, placement);
 				const placed = requireClipTopology(draft, topology.clip.entityId);
 				replaceEntity(draft, placed.marker.entityId, {
 					...placed.marker,
@@ -1154,6 +1286,57 @@ var EntityTimelineEditor = class {
 			}
 		});
 	}
+	/**
+	* Place an independent Caption: its own content entity, inline text Asset,
+	* and Clip with a display Marker. No Voice, provenance, or alignment is
+	* required — the placement describes only this use. Moving or stretching
+	* the returned Clip later changes the Clip/Marker, never the Caption entity.
+	*/
+	insertCaptionClip(input) {
+		return this.transact((draft) => {
+			const durationMs = finitePositive(input.durationMs, "Caption durationMs");
+			const track = this.ensureRoleTrack(draft, input.timelineEntityId, "caption");
+			const content = {
+				entityId: this.mintEntityId(draft),
+				entityKind: "caption",
+				payload: {
+					extent: {
+						kind: "bounded",
+						start: 0,
+						end: durationMs
+					},
+					sampling: "native",
+					coordinateSpace: "milliseconds",
+					text: input.text,
+					...input.style === void 0 ? {} : { style: cloneJsonObject(input.style, "Caption style") }
+				}
+			};
+			const asset = {
+				entityId: this.mintEntityId(draft),
+				entityKind: "asset",
+				payload: { inline: {
+					mediaType: "text/plain",
+					text: input.text
+				} }
+			};
+			draft.entities.push(content, asset);
+			draft.relations.push(this.createRelation(draft, "physical-asset", content.entityId, asset.entityId));
+			return this.insertPlacedClipIntoDraft(draft, {
+				trackEntityId: track.entityId,
+				contentEntityId: content.entityId,
+				sourceRange: {
+					start: 0,
+					end: durationMs
+				},
+				duration: {
+					mode: "fixed",
+					value: durationMs
+				},
+				placement: input.placement,
+				...input.captionClipEntityId === void 0 ? {} : { clipEntityId: input.captionClipEntityId }
+			});
+		});
+	}
 	insertPlacedClipIntoDraft(draft, input) {
 		const track = requireEntityKind(draft, input.trackEntityId, "track");
 		requireTrackTimeline(draft, track.entityId);
@@ -1518,6 +1701,7 @@ var EntityTimelineEditor = class {
 		const draft = cloneRows(this.state);
 		const result = edit(draft);
 		validateFinalRows(draft);
+		assertMediaAssetWritePolicy(this.state, draft);
 		this.state = draft;
 		return result;
 	}
@@ -1554,6 +1738,7 @@ var EntityTimelineEditor = class {
 };
 function validateFinalRows(rows) {
 	decodeEntityRelationRows(rows, numericMarkerValidation);
+	assertCanonicalEditorResources(rows);
 	validateTimelineHierarchy(rows);
 }
 function validateTimelineHierarchy(rows) {
@@ -4519,4 +4704,4 @@ function serverCovers(serverVV, target) {
 	return covers(server, target);
 }
 //#endregion
-export { DEFAULT_UNIT_TIME_MS, ENTITY_TIMELINE_PROJECTION_SCHEMA_VERSION, EntityGraphHttpClient, EntityTimelineEditor, EntityTimelineProjectionError, IMPLEMENTED_SEMANTIC_OP_KINDS, LANE_KINDS_IN_STACK_ORDER, ManualSyncDoc, MedeoHttpDocStorage, MemoryDocStorage, MengineAckFailedError, MengineDocSession, MengineHttpClient, MengineHttpRequestError, MenginePushRejectedError, MirrorVideoDocumentAdapter, PlainMemoryAdapter, SchemaValidator, SemanticEditor, TIMELINE_SKELETON_DURATION_MS, VIDEO_DOCUMENT_SCHEMA_VERSION, ValidationError, VideoDocumentValidationError, applyEntityTimelineProjection, arrangeMainTrackSeamlessly, assertEntityProjectionPreservesLegacy, assertValidVideoDocument, base64ToBytes, buildInitialVideoDocument, buildSpeechHostMap, bytesToBase64, cascadeAfterVideoClipChanges, createEditSandbox, createMirrorVideoDocument, createMirrorVideoDocumentAdapter, createPlainMemoryAdapter, decodeDocVersionMark, derivePositionFromAbs, effectiveVideoClipDurationMs, encodeDocVersionMark, ensureLaneTrack, fillMainTrackTimeGaps, findLaneTrack, fromVideoDocument, generatePartId, getAt, hostForAbsMs, importMediaAsset, isEmptyVideoClip, isImplementedSemanticOpKind, isMap, laneTrackId, mainTrackRanges, migrateLegacyTimelineToEntities, partDurationMs, partUnionSchema, projectEntityTimeline, readMainTrackItems, readMengineEventStream, readPart, readPartDurationMs, readVideoDocumentFromDraft, reassignSpeechesToVideoClipsByTime, recalculateTimelineDuration, relativePositionForAbs, replayJournal, resolveAllSpeechOverlaps, resolveEntityTimelineLayout, resolveSpeechOverlapByShiftingVideos, safeDurationMs, schemas_exports as schemas, snapshotToPlain, solveVideoDocument, speedOf, syncAggregatedClipsTimePosition, toVideoDocument, validateVideoDocument, videoDocumentMirrorSchema, videoDocumentSchema, writeVideoDocumentToDraft };
+export { DEFAULT_UNIT_TIME_MS, ENTITY_TIMELINE_PROJECTION_SCHEMA_VERSION, EntityGraphHttpClient, EntityTimelineEditor, EntityTimelineProjectionError, IMPLEMENTED_SEMANTIC_OP_KINDS, LANE_KINDS_IN_STACK_ORDER, ManualSyncDoc, MedeoHttpDocStorage, MemoryDocStorage, MengineAckFailedError, MengineDocSession, MengineHttpClient, MengineHttpRequestError, MenginePushRejectedError, MirrorVideoDocumentAdapter, PlainMemoryAdapter, SchemaValidator, SemanticEditor, TIMELINE_SKELETON_DURATION_MS, VIDEO_DOCUMENT_SCHEMA_VERSION, ValidationError, VideoDocumentValidationError, applyEntityTimelineProjection, arrangeMainTrackSeamlessly, assertCanonicalEditorResources, assertEntityProjectionPreservesLegacy, assertMediaAssetWritePolicy, assertValidVideoDocument, base64ToBytes, buildInitialVideoDocument, buildSpeechHostMap, bytesToBase64, cascadeAfterVideoClipChanges, createEditSandbox, createMirrorVideoDocument, createMirrorVideoDocumentAdapter, createPlainMemoryAdapter, decodeDocVersionMark, derivePositionFromAbs, effectiveVideoClipDurationMs, encodeDocVersionMark, ensureEditorFoundation, ensureLaneTrack, fillMainTrackTimeGaps, findLaneTrack, fromVideoDocument, generatePartId, getAt, hostForAbsMs, importMediaAsset, isEmptyVideoClip, isImplementedSemanticOpKind, isMap, laneTrackId, mainTrackRanges, migrateLegacyTimelineToEntities, partDurationMs, partUnionSchema, projectEntityTimeline, readMainTrackItems, readMengineEventStream, readPart, readPartDurationMs, readVideoDocumentFromDraft, reassignSpeechesToVideoClipsByTime, recalculateTimelineDuration, relativePositionForAbs, replayJournal, resolveAllSpeechOverlaps, resolveEntityTimelineLayout, resolveSpeechOverlapByShiftingVideos, safeDurationMs, schemas_exports as schemas, snapshotToPlain, solveVideoDocument, speedOf, syncAggregatedClipsTimePosition, toVideoDocument, validateVideoDocument, videoDocumentMirrorSchema, videoDocumentSchema, writeVideoDocumentToDraft };

package/dist/testing.d.ts

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

package/dist/testing.js

@@ -1,4 +1,4 @@
-import { $ as base64ToBytes, et as bytesToBase64, q as VIDEO_DOCUMENT_SCHEMA_VERSION, s as createMirrorVideoDocumentAdapter } from "./document-Df6awJDH.js";
+import { J as VIDEO_DOCUMENT_SCHEMA_VERSION, et as base64ToBytes, s as createMirrorVideoDocumentAdapter, tt as bytesToBase64 } from "./document-Caidonf8.js";
 import { t as classifyUpdate } from "./loro-relay-doc-ssdYpuef.js";
 import { LoroDoc, VersionVector, encodeFrontiers } from "loro-crdt";
 //#region src/testing/in-memory-mengine-server.ts

package/package.json

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