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

package/dist/{document-BXQcpnOg.js → document-7Vi1AeQc.js}

@@ -2463,7 +2463,7 @@ const axVideoMarkerRelationSpec = emptySpec("axvideo-marker", "axvideo", "sequen
 const markerTimelineRelationSpec = emptySpec("marker-timeline", "sequence-marker", "timeline");
 const markerContentRelationSpec = Object.freeze({
 	kind: "marker-content",
-	validateEndpoints: (endpoints) => hasMarkerAndSequence(endpoints),
+	validateEndpoints: (endpoints) => endpoints[0].current().entityKind === "sequence-marker" && hasSequence(endpoints[1].current()),
 	validateMetadata: isEmptyMetadata
 });
 /**
@@ -2477,7 +2477,7 @@ const markerContentRelationSpec = Object.freeze({
 */
 const fromAssetRelationSpec = Object.freeze({
 	kind: "from-asset",
-	validateEndpoints: (endpoints) => hasExactlyOneAsset(endpoints),
+	validateEndpoints: (endpoints) => declaresKind(endpoints[0].current().entityKind, "MediaFile") && endpoints[1].current().entityKind === "asset",
 	validateMetadata: isAssetBinding
 });
 /**
@@ -2497,13 +2497,13 @@ const fromAssetRelationSpec = Object.freeze({
 */
 const toAssetRelationSpec = Object.freeze({
 	kind: "to-asset",
-	validateEndpoints: (endpoints) => hasExactlyOneAsset(endpoints),
+	validateEndpoints: (endpoints) => declaresKind(endpoints[0].current().entityKind, "MediaFile") && endpoints[1].current().entityKind === "asset",
 	validateMetadata: isAssetBinding
 });
-/** `generated(output, input)` means endpoint 0 was generated from endpoint 1. */
+/** `generated(output, input)` records media generation or an independent AudioScript revision. */
 const generatedRelationSpec = Object.freeze({
 	kind: "generated",
-	validateEndpoints: (endpoints) => endpoints.every((endpoint) => isGeneratedMedia(endpoint.current())),
+	validateEndpoints: (endpoints) => endpoints.every((endpoint) => isGeneratedMedia(endpoint.current())) || endpoints.every((endpoint) => endpoint.current().entityKind === "audio-script"),
 	validateMetadata: isEmptyMetadata
 });
 const captionAlignmentRelationSpec = Object.freeze({
@@ -2518,8 +2518,8 @@ const clipAnchorRelationSpec = Object.freeze({
 	validateMetadata: isEmptyMetadata
 });
 /**
-* The Voiceover and the PhoneticScript it was spoken from; kinds determine
-* roles regardless of endpoint positions.
+* The Voiceover and the PhoneticScript it was spoken from. Endpoint 0 is the
+* output and endpoint 1 is the input script.
 *
 * Every Voiceover must carry one: which words were said, and how, is the only
 * thing that makes speech reproducible, and a Voiceover that cannot answer it
@@ -2540,7 +2540,7 @@ const voiceTimbreRelationSpec = Object.freeze({
 	validateEndpoints: (endpoints) => hasKinds(endpoints, new Set(["voiceover"]), new Set(["voice"])),
 	validateMetadata: isEmptyMetadata
 });
-/** AudioScript was transcribed from Audio, Video, or recorded Voice; kinds determine roles. */
+/** AudioScript was transcribed from Audio or Video: `[script, source]`. */
 const audioScriptSourceRelationSpec = Object.freeze({
 	kind: "audio-script-source",
 	validateEndpoints: (endpoints) => hasKinds(endpoints, new Set(["audio-script"]), new Set([
@@ -2592,19 +2592,7 @@ function metadataSpec(kind, a, b, validateMetadata) {
 function hasKinds(endpoints, aKinds, bKinds) {
 	const first = endpoints[0].current().entityKind;
 	const second = endpoints[1].current().entityKind;
-	return aKinds.has(first) && bKinds.has(second) || aKinds.has(second) && bKinds.has(first);
-}
-function hasMarkerAndSequence(endpoints) {
-	const first = endpoints[0].current();
-	const second = endpoints[1].current();
-	return first.entityKind === "sequence-marker" && hasSequence(second) || second.entityKind === "sequence-marker" && hasSequence(first);
-}
-/** Exactly one end is the Asset, so the other end is unambiguously the bound entity. */
-function hasExactlyOneAsset(endpoints) {
-	const kinds = endpoints.map((endpoint) => endpoint.current().entityKind);
-	const assets = kinds.map((kind) => kind === "asset");
-	if (assets[0] === assets[1]) return false;
-	return declaresKind(assets[0] ? kinds[1] : kinds[0], "MediaFile");
+	return aKinds.has(first) && bKinds.has(second);
 }
 function isGeneratedMedia(entity) {
 	return entity.entityKind === "video" || entity.entityKind === "image" || entity.entityKind === "audio" || entity.entityKind === "voiceover";
@@ -2940,6 +2928,42 @@ function errorMessage(error) {
 	return error instanceof Error ? error.message : String(error);
 }
 //#endregion
+//#region ../medeo-dsl/src/relation-transition.ts
+var InvalidEntityRelationTransitionError = class extends Error {
+	issues;
+	constructor(issues) {
+		super(`Invalid Medeo relation transition:\n- ${issues.join("\n- ")}`);
+		this.issues = issues;
+		this.name = "InvalidEntityRelationTransitionError";
+	}
+};
+/** Enforce relation fact identity while admitting a complete candidate view. */
+function validateEntityRelationTransition(before, candidate) {
+	const issues = [];
+	const previous = new Map(before.relations.map((row) => [row.relationId, row]));
+	for (const relation of candidate.relations) {
+		const original = previous.get(relation.relationId);
+		if (original == null) {
+			if (relation.relationKind === "caption-alignment") issues.push(`new caption-alignment relation "${relation.relationId}" is forbidden`);
+			continue;
+		}
+		if (original.relationKind !== relation.relationKind || original.endpoint0EntityId !== relation.endpoint0EntityId || original.endpoint1EntityId !== relation.endpoint1EntityId) {
+			issues.push(`relation "${relation.relationId}" changed its kind or ordered endpoints`);
+			continue;
+		}
+		if (!sameJson(original.metadata, relation.metadata)) issues.push(`relation "${relation.relationId}" changed semantic metadata without a new identity`);
+		if (relation.relationKind === "caption-alignment" && !sameJson(original.trace, relation.trace)) issues.push(`legacy caption-alignment relation "${relation.relationId}" may only be carried unchanged or deleted`);
+	}
+	if (issues.length > 0) throw new InvalidEntityRelationTransitionError(issues);
+}
+function sameJson(left, right) {
+	if (left === right) return true;
+	if (Array.isArray(left) && Array.isArray(right)) return left.length === right.length && left.every((value, index) => sameJson(value, right[index]));
+	if (!isJsonObject(left) || !isJsonObject(right)) return false;
+	const leftKeys = Object.keys(left);
+	return leftKeys.length === Object.keys(right).length && leftKeys.every((key) => Object.hasOwn(right, key) && sameJson(left[key], right[key]));
+}
+//#endregion
 //#region src/document/entity-projection-values.ts
 /** A graph cannot be represented faithfully by the compatibility reader. */
 var EntityTimelineProjectionError = class extends Error {
@@ -3160,7 +3184,8 @@ function assertTrackContent(graph, role, content) {
 		assertSpeechContent(graph, content);
 		return;
 	}
-	if (!(role === "video_clip" ? ["image", "video"] : role === "caption" ? ["caption"] : ["audio"]).includes(content.entityKind)) fail(`unsupported compatibility content kind ${content.entityKind} on ${role} Track`);
+	const expected = role === "video_clip" ? ["image", "video"] : role === "caption" ? ["caption"] : ["audio"];
+	if (!expected.includes(content.entityKind)) fail(`${role} Track accepts ${expected.join(" or ")}, got ${content.entityKind}`);
 }
 function assertSpeechContent(graph, content) {
 	const assetLinks = graph.rows.relations.filter((relation) => relation.relationKind === "from-asset" && (relation.endpoint0EntityId === content.entityId || relation.endpoint1EntityId === content.entityId));
@@ -3179,7 +3204,7 @@ function assertSpeechContent(graph, content) {
 		if (asset.payload.system !== "memota") fail("Recorded Speech Audio requires an explicit memota key");
 		return;
 	}
-	fail(`unsupported compatibility content kind ${content.entityKind} on speech Track`);
+	fail(`speech Track accepts voiceover or audio, got ${content.entityKind}`);
 }
 //#endregion
 //#region src/document/entity-projection.ts
@@ -3781,6 +3806,19 @@ function writeEntityOrder(doc, group, roots, token) {
 //#region src/entity-crdt/entity-document.ts
 const LORO_ENTITY_SCHEMA = "medeo.entities.loro.v1";
 const MATERIALIZE_ORIGIN = "medeo.materialize";
+/** Read persisted relation roots before current entity versions are projected. */
+function readEntityRelationRecords(doc) {
+	if (root(doc).get("schema") !== "medeo.entities.loro.v1") throw new Error("Document has no Loro entity state");
+	return relationRecords(doc).map(({ rootId, identity, map, deleted }) => ({
+		relationId: createRelationId(rootId),
+		relationKind: identity.kind,
+		endpoint0EntityId: createEntityId(identity.endpoints[0]),
+		endpoint1EntityId: createEntityId(identity.endpoints[1]),
+		metadata: requireMap(map, "metadata").toJSON(),
+		trace: requireMap(map, "trace").toJSON(),
+		deleted
+	}));
+}
 function hash(value) {
 	return bytesToHex(sha256(new TextEncoder().encode(canonicalJson(value))));
 }
@@ -3872,23 +3910,17 @@ function readEntityDocument(doc, allowSelectionConflicts = false) {
 			}
 		};
 	});
-	const relations = [];
-	for (const key of section(doc, "relations").keys().sort((a, b) => a < b ? -1 : a > b ? 1 : 0)) {
-		const map = section(doc, "relations").get(key);
-		if (!(map instanceof LoroMap) || map.get("deleted") === true) continue;
-		const original = map.get("identity");
-		if (original.endpoints.some((id) => !ids.has(family(doc, id)))) continue;
-		const endpoints = original.endpoints.map((id) => currentId(doc, id, ids));
-		const relationId = equalJson(endpoints, original.endpoints) ? key : `relation_${hash([key, endpoints])}`;
-		relations.push({
-			relationId: createRelationId(relationId),
-			relationKind: original.kind,
+	const relations = activeRelationRecords(doc, ids).map(({ rootId, identity, map }) => {
+		const endpoints = identity.endpoints.map((id) => currentId(doc, id, ids));
+		return {
+			relationId: createRelationId(equalJson(endpoints, identity.endpoints) ? rootId : `relation_${hash([rootId, endpoints])}`),
+			relationKind: identity.kind,
 			endpoint0EntityId: createEntityId(endpoints[0]),
 			endpoint1EntityId: createEntityId(endpoints[1]),
 			metadata: requireMap(map, "metadata").toJSON(),
 			trace: requireMap(map, "trace").toJSON()
-		});
-	}
+		};
+	});
 	const project = {};
 	for (const [key, value] of Object.entries(section(doc, "attachments").toJSON())) {
 		if (typeof value !== "string") throw new Error(`Invalid project attachment ${key}`);
@@ -3907,6 +3939,32 @@ function readEntityDocument(doc, allowSelectionConflicts = false) {
 	}
 	return state;
 }
+function relationRecords(doc) {
+	const records = [];
+	for (const rootId of section(doc, "relations").keys().sort((a, b) => a < b ? -1 : a > b ? 1 : 0)) {
+		const map = section(doc, "relations").get(rootId);
+		if (!(map instanceof LoroMap)) throw new Error(`Invalid relation record ${rootId}`);
+		const value = map.get("identity");
+		if (!isJsonObject(value) || typeof value.kind !== "string" || !Array.isArray(value.endpoints) || value.endpoints.length !== 2 || !value.endpoints.every((endpoint) => typeof endpoint === "string")) throw new Error(`Invalid relation identity ${rootId}`);
+		const identity = {
+			kind: value.kind,
+			endpoints: [value.endpoints[0], value.endpoints[1]]
+		};
+		records.push({
+			rootId,
+			identity,
+			map,
+			deleted: map.get("deleted") === true
+		});
+	}
+	return records;
+}
+function activeRelationRecords(doc, ids) {
+	return relationRecords(doc).filter(({ identity, deleted }) => {
+		if (deleted) return false;
+		return identity.endpoints.every((id) => ids.has(family(doc, id)));
+	});
+}
 /** Native editing containers survive domain version changes and merge independently. */
 var LoroEntityDocument = class LoroEntityDocument {
 	doc;
@@ -3972,25 +4030,6 @@ var LoroEntityDocument = class LoroEntityDocument {
 		if (id === void 0) return [];
 		return this.snapshot().rows.relations.filter((row) => row.endpoint0EntityId === id || row.endpoint1EntityId === id);
 	}
-	/** Read unlinked Relation records for durable effect receipts; never part of the current semantic graph. */
-	tombstonedRelations() {
-		const result = [];
-		for (const key of section(this.doc, "relations").keys().sort((a, b) => a < b ? -1 : a > b ? 1 : 0)) {
-			const map = section(this.doc, "relations").get(key);
-			if (!(map instanceof LoroMap) || map.get("deleted") !== true) continue;
-			const identity = map.get("identity");
-			if (!identity || identity.endpoints.length !== 2) throw new Error(`Invalid tombstoned Relation ${key}`);
-			result.push({
-				relationId: createRelationId(key),
-				relationKind: identity.kind,
-				endpoint0EntityId: createEntityId(identity.endpoints[0]),
-				endpoint1EntityId: createEntityId(identity.endpoints[1]),
-				metadata: requireMap(map, "metadata").toJSON(),
-				trace: requireMap(map, "trace").toJSON()
-			});
-		}
-		return result;
-	}
 	/** Resolve a queued edit target through its native identity without changing history. */
 	resolveCurrentEntityId(id) {
 		return currentId(this.doc, id);
@@ -4156,16 +4195,47 @@ var LoroEntityDraft = class {
 		});
 	}
 	link(row) {
+		if (row.relationKind === "caption-alignment") throw new Error("caption-alignment Relations are read-only legacy facts");
+		if (row.relationKind === "generated" || row.relationKind === "clip-anchor") throw new Error(`Author ordered ${row.relationKind} Relations with the dedicated role-named method`);
 		this.record({
 			type: "relation",
 			row: clone(row)
 		});
 	}
-	patchRelation(relationId, metadata, trace) {
+	linkGenerated(input) {
+		this.record({
+			type: "relation",
+			row: {
+				relationId: input.relationId,
+				relationKind: "generated",
+				endpoint0EntityId: input.outputEntityId,
+				endpoint1EntityId: input.inputEntityId,
+				metadata: {},
+				trace: clone(input.trace ?? {})
+			}
+		});
+	}
+	linkClipAnchor(input) {
+		this.record({
+			type: "relation",
+			row: {
+				relationId: input.relationId,
+				relationKind: "clip-anchor",
+				endpoint0EntityId: input.childClipEntityId,
+				endpoint1EntityId: input.hostClipEntityId,
+				metadata: {},
+				trace: clone(input.trace ?? {})
+			}
+		});
+	}
+	patchRelationTrace(relationId, trace) {
+		const relation = this.snapshot().rows.relations.find((row) => row.relationId === relationId);
+		if (relation == null) throw new Error(`Unknown relation ${relationId}`);
+		if (relation.relationKind === "caption-alignment") throw new Error("caption-alignment Relations are read-only legacy facts");
 		this.record({
 			type: "relation-fields",
 			root: this.relationRoot(relationId),
-			metadata: clone(metadata),
+			metadata: clone(relation.metadata),
 			trace: clone(trace)
 		});
 	}
@@ -4261,8 +4331,9 @@ var LoroEntityDraft = class {
 		const key = this.relationRoot(relationId);
 		const map = section(this.doc, "relations").get(key);
 		if (!(map instanceof LoroMap) || map.get("deleted") === true) throw new Error("Unknown relation");
+		if (map.get("identity").kind === "caption-alignment") throw new Error("caption-alignment Relations are read-only legacy facts");
 		for (const change of changes) {
-			if (!["metadata", "trace"].includes(change.path[0]) || change.path.length < 2) throw new Error("Relation changes may only edit metadata or trace fields");
+			if (change.path[0] !== "trace" || change.path.length < 2) throw new Error("Relation changes may only edit trace fields");
 			const payload = {
 				metadata: requireMap(map, "metadata").toJSON(),
 				trace: requireMap(map, "trace").toJSON()
@@ -4778,4 +4849,4 @@ function createPlainMemoryAdapter(document, options) {
 	return new PlainMemoryAdapter(document, options);
 }
 //#endregion
-export { validateVideoDocument as $, EntityTimelineProjectionError as A, variantBaseEntityIds as B, equalJson as C, partUnionToDraft as Ct, projectEntityTimeline as D, bytesToBase64 as Dt, resolveFieldPath as E, base64ToBytes as Et, assemblePhoneticScriptContent as F, isMediaAssetVariantKind as G, createEntityId as H, assembleScriptText as I, derivePositionFromAbs as J, buildInitialVideoDocument as K, findComposedAudioScript as L, ScriptCompositionError as M, assembleCaptionContent as N, EntityProjectionGraph as O, assembleEntityContent as P, assertValidVideoDocument as Q, selectAudioScriptSegment as R, canonicalJson as S, speedOf as St, assertFieldChanges as T, videoDocumentMirrorSchema as Tt, createRelationId as U, isJsonObject as V, hasSequence as W, toVideoDocument as X, fromVideoDocument as Y, VideoDocumentValidationError as Z, audioScriptAssetOf as _, isEmptyVideoClip as _t, createMirrorVideoDocument as a, hasResolvedPlacement as at, phoneticScriptAssetOf as b, DEFAULT_UNIT_TIME_MS as bt, DocumentMutationGuard as c, cascadeAfterVideoClipChanges as ct, LoroEntityDraft as d, reassignSpeechesToVideoClipsByTime as dt, partUnionSchema as et, readEntityDocument as f, recalculateTimelineDuration as ft, audioScriptAssetHash as g, TIMELINE_SKELETON_DURATION_MS as gt, audioScriptAssetFields as h, syncAggregatedClipsTimePosition as ht, MirrorVideoDocumentAdapter as i, findLaneTrack as it, decodeEntityRelationRows as j, resolveEntityTimelineLayout as k, LORO_ENTITY_SCHEMA as l, arrangeMainTrackSeamlessly as lt, audioScriptAssetContent as m, resolveSpeechOverlapByShiftingVideos as mt, createPlainMemoryAdapter as n, LANE_KINDS_IN_STACK_ORDER as nt, createMirrorVideoDocumentAdapter as o, laneTrackId as ot, entityOrderGroups as p, resolveAllSpeechOverlaps as pt, buildSpeechHostMap as q, generatePartId as r, ensureLaneTrack as rt, readVideoDocumentFromDraft as s, solveVideoDocument as st, PlainMemoryAdapter as t, videoDocumentSchema as tt, LoroEntityDocument as u, fillMainTrackTimeGaps as ut, phoneticScriptAssetContent as v, partDurationMs as vt, applyFieldChanges as w, recordEntries as wt, scriptSourceAssetOf as x, effectiveVideoClipDurationMs as xt, phoneticScriptAssetHash as y, safeDurationMs as yt, updateEntityFields as z };
+export { VideoDocumentValidationError as $, resolveEntityTimelineLayout as A, selectAudioScriptSegment as B, canonicalJson as C, effectiveVideoClipDurationMs as Ct, resolveFieldPath as D, videoDocumentMirrorSchema as Dt, assertFieldChanges as E, recordEntries as Et, assembleCaptionContent as F, createRelationId as G, variantBaseEntityIds as H, assembleEntityContent as I, buildInitialVideoDocument as J, hasSequence as K, assemblePhoneticScriptContent as L, validateEntityRelationTransition as M, decodeEntityRelationRows as N, projectEntityTimeline as O, base64ToBytes as Ot, ScriptCompositionError as P, toVideoDocument as Q, assembleScriptText as R, scriptSourceAssetOf as S, DEFAULT_UNIT_TIME_MS as St, applyFieldChanges as T, partUnionToDraft as Tt, isJsonObject as U, updateEntityFields as V, createEntityId as W, derivePositionFromAbs as X, buildSpeechHostMap as Y, fromVideoDocument as Z, audioScriptAssetHash as _, syncAggregatedClipsTimePosition as _t, createMirrorVideoDocument as a, ensureLaneTrack as at, phoneticScriptAssetHash as b, partDurationMs as bt, DocumentMutationGuard as c, laneTrackId as ct, LoroEntityDraft as d, arrangeMainTrackSeamlessly as dt, assertValidVideoDocument as et, readEntityDocument as f, fillMainTrackTimeGaps as ft, audioScriptAssetFields as g, resolveSpeechOverlapByShiftingVideos as gt, audioScriptAssetContent as h, resolveAllSpeechOverlaps as ht, MirrorVideoDocumentAdapter as i, LANE_KINDS_IN_STACK_ORDER as it, EntityTimelineProjectionError as j, EntityProjectionGraph as k, bytesToBase64 as kt, LORO_ENTITY_SCHEMA as l, solveVideoDocument as lt, entityOrderGroups as m, recalculateTimelineDuration as mt, createPlainMemoryAdapter as n, partUnionSchema as nt, createMirrorVideoDocumentAdapter as o, findLaneTrack as ot, readEntityRelationRecords as p, reassignSpeechesToVideoClipsByTime as pt, isMediaAssetVariantKind as q, generatePartId as r, videoDocumentSchema as rt, readVideoDocumentFromDraft as s, hasResolvedPlacement as st, PlainMemoryAdapter as t, validateVideoDocument as tt, LoroEntityDocument as u, cascadeAfterVideoClipChanges as ut, audioScriptAssetOf as v, TIMELINE_SKELETON_DURATION_MS as vt, equalJson as w, speedOf as wt, phoneticScriptAssetOf as x, safeDurationMs as xt, phoneticScriptAssetContent as y, isEmptyVideoClip as yt, findComposedAudioScript as z };