@mengine/medeo-client 1.3.1-alpha.1 → 1.3.1-alpha.2

package/README.md

@@ -74,18 +74,17 @@ plan. A speech-overlap shift is explicit placement on the real visual Clips;
 an uncovered time interval does not require an invented empty-media entity.
 
 Generated Voice links to a pre-existing PhoneticScript through `phonetic-script-render`.
-Caption and PhoneticScript each compose a real AudioScript through exactly one
-`caption-composition` or `phonetic-script-composition` relation. AudioScript owns
-`segments[].text`; the variants never persist a text copy. Read complete content
+Caption and PhoneticScript each compose a real AudioScript by directly holding `baseEntityIds`, an array that may compose multiple entities. AudioScript owns
+`segments[].text`; assembly never automatically persists a copy on the variants. Read complete content
 with `assembleCaptionContent` or `assemblePhoneticScriptContent`. Broken composition
-fails explicitly. Recorded Audio/Video/Voice can be the ASR source via
+fails explicitly. Same-name fields from different bases are rejected even for equal values and even if the variant declares that field. After base fields are unambiguous, explicit own fields may override them without mutating the bases. Recorded Audio/Video/Voice can be the ASR source via
 `audio-script-source`, without creating a synthesis variant.
 
-`insertCaptionClip` requires `audioScriptEntityId` and `selections`. Each selection
+`insertCaptionClip` requires `baseEntityIds` and `selections`. Each selection
 names a source `segmentId` and optionally a half-open Unicode code-point
 `textRange: {start, end}`. This permits display re-segmentation without rewriting
 the original script. `upsertVoiceoverTake` requires the real
-`phoneticScriptEntityId` used for synthesis; its captions select the same script.
+`phoneticScriptEntityId` used for synthesis; its captions supply their own `baseEntityIds` and select the same script.
 External speech identity and storage key stay on Voice.
 
 AudioScript has no intrinsic Sequence and cannot enter a Clip. `audio-script-marker`
@@ -107,3 +106,9 @@ It rejects `video-document/entity-projection-v1` documents. Production entity
 tools and editor adapters must not fall back to it or raw `/updates` on failure.
 For an entity projection, `meta.version` is the committed entity revision; the
 Loro version vector remains the transport-sync cursor.
+
+### Transparent variant fields in the DSL sandbox
+
+`entities.get/list` return complete assembled fields. Consumers do not query base IDs or merge source payloads. `entities.update` patches supplied fields, preserves omitted fields, and routes inherited fields to their declaring entity. Explicit own-field declarations use `entities.declareFields`; these override unambiguous base fields without changing the base. Persisted entity rows and command payloads contain owned fields only. Base collisions are validated before own overrides.
+
+`prepareCaptionContent` accepts caption authoring intent and handles source composition, visible text selection, and preservation of existing intrinsic timing inside the SDK.

package/dist/{document-Bf200CmD.js → document-BLYcbv8E.js}

@@ -1524,13 +1524,49 @@ function isRecord$1(value) {
 	return typeof value === "object" && value != null && !Array.isArray(value);
 }
 //#endregion
+//#region ../medeo-dsl/src/ids.ts
+function createEntityId(value) {
+	return createId(value, "EntityId");
+}
+function createRelationId(value) {
+	return createId(value, "RelationId");
+}
+function createId(value, label) {
+	if (value.length === 0 || value.trim() !== value) throw new Error(`${label} must be a non-empty trimmed string`);
+	return value;
+}
+//#endregion
+//#region ../medeo-dsl/src/json-values.ts
+const nativeObjectConstructorSource = Function.prototype.toString.call(Object);
+function isJsonObject(value) {
+	return isJsonValue(value, /* @__PURE__ */ new Set()) && !Array.isArray(value) && value !== null;
+}
+function isJsonValue(value, ancestors) {
+	if (value === null || typeof value === "string" || typeof value === "boolean") return true;
+	if (typeof value === "number") return Number.isFinite(value);
+	if (typeof value !== "object") return false;
+	if (!Array.isArray(value) && !isPlainObject(value)) return false;
+	if (ancestors.has(value)) return false;
+	ancestors.add(value);
+	const valid = Array.isArray(value) ? value.every((item) => isJsonValue(item, ancestors)) : Object.values(value).every((item) => isJsonValue(item, ancestors));
+	ancestors.delete(value);
+	return valid;
+}
+/** Recognize an ordinary object from any VM realm without admitting class instances. */
+function isPlainObject(value) {
+	try {
+		const prototype = Object.getPrototypeOf(value);
+		if (prototype === null) return true;
+		if (Object.getPrototypeOf(prototype) !== null) return false;
+		const constructor = Object.getOwnPropertyDescriptor(prototype, "constructor")?.value;
+		return typeof constructor === "function" && constructor.prototype === prototype && Function.prototype.toString.call(constructor) === nativeObjectConstructorSource;
+	} catch {
+		return false;
+	}
+}
+//#endregion
 //#region ../medeo-dsl/src/composition.ts
-/**
-* Raised when a variant's complete content cannot be assembled from its
-* required composition Relation. Assembly never falls back to variant-local
-* text: a missing, ambiguous, or dangling source is an error, not an empty
-* read.
-*/
+/** Assembly fails explicitly when declared bases cannot provide valid, unambiguous content. */
 var ScriptCompositionError = class extends Error {
 	code;
 	entityId;
@@ -1541,23 +1577,111 @@ var ScriptCompositionError = class extends Error {
 		this.name = "ScriptCompositionError";
 	}
 };
-function compositionRelationKind(variantKind) {
-	return variantKind === "caption" ? "caption-composition" : "phonetic-script-composition";
+/** Direct base IDs are structural fields, never ordinary Relation endpoints. */
+function variantBaseEntityIds(entity) {
+	if (!Object.hasOwn(entity.payload, "baseEntityIds")) return [];
+	const ids = entity.payload.baseEntityIds;
+	if (!Array.isArray(ids) || ids.length === 0 || !ids.every((id) => typeof id === "string" && id.trim() === id && id.length > 0) || new Set(ids).size !== ids.length) throw new ScriptCompositionError("invalid_bases", entity.entityId, `Entity "${entity.entityId}" requires non-empty, unique baseEntityIds`);
+	return ids.map(createEntityId);
+}
+/** Validate all base providers before applying explicit own fields; ordering cannot resolve ambiguity. */
+function assembleEntityContent(rows, entityId) {
+	const byId = /* @__PURE__ */ new Map();
+	for (const row of rows.entities) {
+		if (byId.has(row.entityId)) throw new ScriptCompositionError("composition_ambiguous", row.entityId, `duplicate entity id "${row.entityId}"`);
+		byId.set(row.entityId, row);
+	}
+	const active = /* @__PURE__ */ new Set();
+	const cache = /* @__PURE__ */ new Map();
+	const visit = (id) => {
+		const cached = cache.get(id);
+		if (cached !== void 0) return cached;
+		if (active.has(id)) throw new ScriptCompositionError("composition_cycle", id, `Cyclic baseEntityIds at "${id}"`);
+		const row = byId.get(id);
+		if (row === void 0) throw new ScriptCompositionError("composition_dangling", id, `Missing base entity "${id}" in this document`);
+		if (!isJsonObject(row.payload) || Object.hasOwn(row.payload, "entityId") || Object.hasOwn(row.payload, "entityKind")) throw new ScriptCompositionError("invalid_bases", id, `Entity "${id}" requires JSON own fields without reserved identity fields`);
+		active.add(id);
+		const inherited = {};
+		const providers = /* @__PURE__ */ new Map();
+		for (const baseId of variantBaseEntityIds(row)) {
+			const base = visit(baseId);
+			for (const [field, value] of Object.entries(base.payload)) {
+				if (field === "baseEntityIds") continue;
+				const previous = providers.get(field);
+				if (previous !== void 0) throw new ScriptCompositionError("field_conflict", id, `Entity "${id}" field "${field}" conflicts between bases "${previous}" and "${baseId}"; own fields cannot resolve base ambiguity`);
+				providers.set(field, baseId);
+				Object.defineProperty(inherited, field, {
+					value,
+					enumerable: true,
+					configurable: true,
+					writable: true
+				});
+			}
+		}
+		const assembled = {
+			...row,
+			payload: JSON.parse(JSON.stringify({
+				...inherited,
+				...row.payload
+			}))
+		};
+		active.delete(id);
+		cache.set(id, assembled);
+		return assembled;
+	};
+	return visit(entityId);
+}
+/** Resolve a field's declaring entity after validating the entire composition. */
+function resolveEntityFieldOwner(rows, entityId, field) {
+	assembleEntityContent(rows, entityId);
+	const byId = new Map(rows.entities.map((row) => [row.entityId, row]));
+	const find = (id) => {
+		const row = byId.get(id);
+		if (Object.hasOwn(row.payload, field)) return id;
+		if (field === "baseEntityIds") return void 0;
+		for (const baseId of variantBaseEntityIds(row)) {
+			const owner = find(baseId);
+			if (owner !== void 0) return owner;
+		}
+	};
+	return find(entityId) ?? entityId;
+}
+/** Patch assembled fields without copying inherited fields into the variant's stored payload. */
+function updateEntityFields(rows, entityId, fields) {
+	assembleEntityContent(rows, entityId);
+	if (!isJsonObject(fields) || Object.hasOwn(fields, "entityId") || Object.hasOwn(fields, "entityKind")) throw new ScriptCompositionError("invalid_bases", entityId, "Field updates require JSON without reserved identity fields");
+	const updates = /* @__PURE__ */ new Map();
+	for (const [field, value] of Object.entries(fields)) {
+		const ownerId = resolveEntityFieldOwner(rows, entityId, field);
+		const owner = updates.get(ownerId) ?? rows.entities.find((row) => row.entityId === ownerId);
+		updates.set(ownerId, {
+			...owner,
+			payload: {
+				...owner.payload,
+				[field]: value
+			}
+		});
+	}
+	return [...updates.values()].map((row) => JSON.parse(JSON.stringify(row)));
 }
-/**
-* Resolve the one AudioScript a variant composes. Relations are queried from
-* both endpoints, so persisted endpoint positions do not matter.
-*/
+/** Find the actual AudioScript text owner through direct variant bases. */
 function findComposedAudioScript(rows, variantEntityId, variantKind) {
-	const kind = compositionRelationKind(variantKind);
-	const edges = rows.relations.filter((relation) => relation.relationKind === kind && (relation.endpoint0EntityId === variantEntityId || relation.endpoint1EntityId === variantEntityId));
-	if (edges.length === 0) throw new ScriptCompositionError("composition_missing", variantEntityId, `${variantKind} "${variantEntityId}" has no ${kind} Relation; it has no content without its AudioScript`);
-	if (edges.length > 1) throw new ScriptCompositionError("composition_ambiguous", variantEntityId, `${variantKind} "${variantEntityId}" has ${edges.length} ${kind} Relations; exactly one AudioScript is required`);
-	const edge = edges[0];
-	const otherId = edge.endpoint0EntityId === variantEntityId ? edge.endpoint1EntityId : edge.endpoint0EntityId;
-	const script = rows.entities.find((entity) => entity.entityId === otherId);
-	if (script === void 0 || script.entityKind !== "audio-script") throw new ScriptCompositionError("composition_dangling", variantEntityId, `${variantKind} "${variantEntityId}" ${kind} Relation must resolve a live AudioScript, got "${script?.entityKind ?? "missing entity"}"`);
-	return script;
+	const variant = requireEntityKind(rows, variantEntityId, variantKind);
+	assembleEntityContent(rows, variantEntityId);
+	const sources = /* @__PURE__ */ new Map();
+	const seen = /* @__PURE__ */ new Set();
+	const visit = (row) => {
+		for (const id of variantBaseEntityIds(row)) {
+			if (seen.has(id)) continue;
+			seen.add(id);
+			const base = rows.entities.find((candidate) => candidate.entityId === id);
+			if (base.entityKind === "audio-script") sources.set(id, assembleEntityContent(rows, id));
+			else visit(base);
+		}
+	};
+	visit(variant);
+	if (sources.size !== 1) throw new ScriptCompositionError(sources.size === 0 ? "composition_missing" : "composition_ambiguous", variantEntityId, `${variantKind} "${variantEntityId}" baseEntityIds must resolve one AudioScript text owner, got ${sources.size}`);
+	return [...sources.values()][0];
 }
 /** Join the whole AudioScript text in segment order. */
 function assembleScriptText(script) {
@@ -1574,16 +1698,15 @@ function isScriptSegment(value) {
 	const segment = value;
 	return typeof segment.segmentId === "string" && segment.segmentId.trim() !== "" && typeof segment.text === "string" && (segment.language === void 0 || typeof segment.language === "string");
 }
-/**
-* Assemble the complete Caption content from its AudioScript: the selected
-* segments in selection order, joined as display text. The Caption payload
-* never carries text, so a broken composition fails here instead of silently
-* rendering an empty caption.
-*/
+/** Assemble selected text after base-field validation and explicit variant overrides. */
 function assembleCaptionContent(rows, captionEntityId) {
-	const caption = requireEntityKind(rows, captionEntityId, "caption");
+	requireEntityKind(rows, captionEntityId, "caption");
+	const caption = assembleEntityContent(rows, captionEntityId);
 	const script = findComposedAudioScript(rows, captionEntityId, "caption");
-	const segments = selectAudioScriptSegments(script, captionSelections(caption));
+	const segments = selectAudioScriptSegments({
+		...script,
+		payload: caption.payload
+	}, captionSelections(caption));
 	return {
 		caption,
 		audioScript: script,
@@ -1596,9 +1719,13 @@ function assembleCaptionContent(rows, captionEntityId) {
 * AudioScript's base text plus the variant's own phoneme and prosody fields.
 */
 function assemblePhoneticScriptContent(rows, phoneticScriptEntityId) {
-	const phoneticScript = requireEntityKind(rows, phoneticScriptEntityId, "phonetic-script");
+	requireEntityKind(rows, phoneticScriptEntityId, "phonetic-script");
+	const phoneticScript = assembleEntityContent(rows, phoneticScriptEntityId);
 	const audioScript = findComposedAudioScript(rows, phoneticScriptEntityId, "phonetic-script");
-	const segments = scriptSegments(audioScript);
+	const segments = scriptSegments({
+		...audioScript,
+		payload: phoneticScript.payload
+	});
 	return {
 		phoneticScript,
 		audioScript,
@@ -1641,16 +1768,15 @@ function requireEntityKind(rows, entityIdValue, entityKind) {
 	return entity;
 }
 //#endregion
-//#region ../medeo-dsl/src/ids.ts
-function createEntityId(value) {
-	return createId(value, "EntityId");
-}
-function createRelationId(value) {
-	return createId(value, "RelationId");
-}
-function createId(value, label) {
-	if (value.length === 0 || value.trim() !== value) throw new Error(`${label} must be a non-empty trimmed string`);
-	return value;
+//#region ../medeo-dsl/src/rows.ts
+function entityToRow(entity) {
+	const { entityId, entityKind, ...payload } = entity;
+	if (!isJsonObject(payload)) throw new Error(`Entity "${entityId}" payload must contain only JSON values`);
+	return {
+		entityId,
+		entityKind,
+		payload
+	};
 }
 //#endregion
 //#region ../medeo-dsl/src/invariants.ts
@@ -1671,6 +1797,19 @@ function validateMediaAssetIdentity(entity, index) {
 function validateEntityRelationSet(entityRefs, index, options) {
 	const { entities, issues } = collectRelatedEntities(entityRefs, index);
 	const entityIds = new Set(entities.map((entity) => entity.entityId));
+	const rows = {
+		entities: entities.map((entity) => entityToRow(entity.current())),
+		relations: []
+	};
+	for (const entity of entities) try {
+		assembleEntityContent(rows, entity.entityId);
+	} catch (error) {
+		issues.push({
+			code: "invalid_variant_composition",
+			entityId: entity.entityId,
+			message: error instanceof Error ? error.message : "Invalid variant composition"
+		});
+	}
 	for (const entity of entities) {
 		const current = entity.current();
 		const entityIssues = validateEntity(entity, entityIds);
@@ -1691,8 +1830,8 @@ function validateEntityRelationSet(entityRefs, index, options) {
 			issues.push(...validateClipPlacement(entity, index));
 		}
 		if (current.entityKind === "axvideo") issues.push(...validateAXVideoAdmission(entity, index));
-		if (current.entityKind === "caption") issues.push(...validateCaptionComposition(entity, index));
-		if (current.entityKind === "phonetic-script") issues.push(...validatePhoneticComposition(entity, index));
+		if (current.entityKind === "caption") issues.push(...validateCaptionComposition(entity, index, entities));
+		if (current.entityKind === "phonetic-script") issues.push(...validatePhoneticComposition(entity, index, entities));
 		issues.push(...validateSequenceComposition(entity));
 	}
 	issues.push(...validateClipAnchorCycles(entities, index));
@@ -1795,60 +1934,32 @@ function validateAXVideoAdmission(axVideo, index) {
 		message: "AXVideo must have exactly one live AXVideo-Marker Relation"
 	}];
 }
-/**
-* Variant composition is the content contract, not an optional label: a
-* Caption must compose exactly one live AudioScript and its segment selection
-* must name that script's own segments. Text is never stored on the variant,
-* so a missing source means no valid caption content and fails validation.
-*/
-function validateCaptionComposition(caption, index) {
-	return validateVariantComposition(caption, index, "caption", "caption-composition", "caption_composition_required");
+/** Validate a Caption against the complete entity set, including its directly held bases. */
+function validateCaptionComposition(caption, index, entities = []) {
+	return validateVariantComposition(caption, index, entities, "caption");
 }
-/** Same required-composition contract for the pronunciation variant. */
-function validatePhoneticComposition(phonetic, index) {
-	return validateVariantComposition(phonetic, index, "phonetic-script", "phonetic-script-composition", "phonetic_script_composition_required");
+function validatePhoneticComposition(phonetic, index, entities = []) {
+	return validateVariantComposition(phonetic, index, entities, "phonetic-script");
 }
-function validateVariantComposition(variant, index, variantKind, compositionKind, issueCode) {
-	const relations = [...index.relationsOf(variant)];
+function validateVariantComposition(variant, index, entities, kind) {
 	const issues = [];
-	const physicalEdges = ofKind(relations, "physical-asset");
-	if (variantKind === "caption" && physicalEdges.length > 0) issues.push({
+	if (kind === "caption" && ofKind([...index.relationsOf(variant)], "physical-asset").length > 0) issues.push({
 		code: "caption_physical_asset_forbidden",
 		entityId: variant.entityId,
 		message: "Caption text is composed from its AudioScript; Caption must not bind a Physical Asset"
 	});
-	const compositionEdges = ofKind(relations, compositionKind);
-	if (compositionEdges.length !== 1) {
-		issues.push({
-			code: issueCode,
-			entityId: variant.entityId,
-			message: `${variantKind} must have exactly one ${compositionKind} Relation to a live AudioScript`
-		});
-		return issues;
-	}
-	const script = compositionEdges[0]?.other(variant)?.deref()?.current();
-	if (script?.entityKind !== "audio-script") {
-		issues.push({
-			code: issueCode,
-			entityId: variant.entityId,
-			message: `${variantKind} ${compositionKind} Relation must resolve a live AudioScript`
-		});
-		return issues;
-	}
-	if (variantKind !== "caption") return issues;
-	const selections = variant.current().selections;
-	if (!Array.isArray(selections)) return issues;
+	const rows = {
+		entities: collectRelatedEntities([...entities, variant], index).entities.map((ref) => entityToRow(ref.current())),
+		relations: []
+	};
 	try {
-		selectAudioScriptSegments({
-			entityId: script.entityId,
-			entityKind: "audio-script",
-			payload: { segments: script.segments.map((segment) => ({ ...segment })) }
-		}, selections);
+		if (kind === "caption") assembleCaptionContent(rows, variant.entityId);
+		else assemblePhoneticScriptContent(rows, variant.entityId);
 	} catch (error) {
 		issues.push({
-			code: "caption_selection_invalid",
+			code: kind === "caption" ? "caption_composition_required" : "phonetic_script_composition_required",
 			entityId: variant.entityId,
-			message: error instanceof Error ? error.message : "Invalid Caption selection"
+			message: error instanceof Error ? error.message : "Invalid variant composition"
 		});
 	}
 	return issues;
@@ -2123,7 +2234,6 @@ function validateVoicePayload(value, problems) {
 	if (voice.name !== void 0 && typeof voice.name !== "string") problems.push("voice.name must be a string when present");
 }
 function validateCaptionPayload(value, problems) {
-	if (value.text !== void 0) problems.push("text is composed from the AudioScript; Caption must not store a text copy");
 	const selections = value.selections;
 	if (!Array.isArray(selections)) problems.push("selections must be a non-empty array of AudioScript segment selections");
 	else {
@@ -2180,8 +2290,7 @@ function validateRange(value, path, required, problems) {
 }
 /** Phonetic variants store pronunciation fields only; base text stays in the AudioScript. */
 function validatePhoneticScriptPayload(value, problems) {
-	if (value.text !== void 0) problems.push("text is composed from AudioScript; PhoneticScript must not store a text copy");
-	if (value.segments !== void 0) problems.push("segments carry the base text owned by the AudioScript; PhoneticScript stores pronunciation fields only");
+	if (value.segments !== void 0) validateScriptPayload(value, problems);
 	if (value.phonemeScript !== void 0 && (typeof value.phonemeScript !== "string" || value.phonemeScript.trim() === "")) problems.push("phonemeScript must be a non-empty string when present");
 	if (value.prosody !== void 0 && !isRecord(value.prosody)) problems.push("prosody must be an object when present");
 }
@@ -2227,6 +2336,7 @@ function visitPeerEntityIdPaths(value, entityKind, parentPath, ancestors, paths)
 	if (Array.isArray(value)) for (const [index, item] of value.entries()) visitPeerEntityIdPaths(item, entityKind, `${parentPath}[${index}]`, ancestors, paths);
 	else for (const [key, child] of Object.entries(value)) {
 		const path = parentPath.length === 0 ? key : `${parentPath}.${key}`;
+		if (parentPath.length === 0 && key === "baseEntityIds") continue;
 		if (!(parentPath.length === 0 && key === "entityId") && !isOwnedLocalIdPath(entityKind, path) && isEntityIdFieldName(key)) paths.push(path);
 		visitPeerEntityIdPaths(child, entityKind, path, ancestors, paths);
 	}
@@ -2246,7 +2356,7 @@ function visitPeerEntityValues(value, entityKind, ownEntityId, entityIds, path,
 	ancestors.add(value);
 	if (Array.isArray(value)) for (const [index, item] of value.entries()) visitPeerEntityValues(item, entityKind, ownEntityId, entityIds, `${path}[${index}]`, ancestors, paths);
 	else for (const [key, child] of Object.entries(value)) {
-		if (path.length === 0 && (key === "entityId" || key === "entityKind")) continue;
+		if (path.length === 0 && (key === "entityId" || key === "entityKind" || key === "baseEntityIds")) continue;
 		visitPeerEntityValues(child, entityKind, ownEntityId, entityIds, path.length === 0 ? key : `${path}.${key}`, ancestors, paths);
 	}
 	ancestors.delete(value);
@@ -2267,12 +2377,20 @@ function isOwnedLocalEntityValuePath(entityKind, path) {
 	if (isMediaAssetVariantKind(entityKind) && /^(?:external\.(?:system|key)|storageKey)$/.test(path)) return true;
 	if (entityKind === "voice" && /^voice\.(?:system|key|name)$/.test(path)) return true;
 	if (entityKind === "caption" && (path.startsWith("style.") || /^selections\[\d+\]\.segmentId$/.test(path))) return true;
-	if (entityKind === "audio-script" && /^segments\[\d+\]\.(?:segmentId|text|language)$/.test(path)) return true;
+	if ([
+		"audio-script",
+		"caption",
+		"phonetic-script"
+	].includes(entityKind) && /^segments\[\d+\]\.(?:segmentId|text|language)$/.test(path)) return true;
 	return false;
 }
 function isOwnedLocalIdPath(entityKind, path) {
 	if (path === "lifecycle.actorId") return true;
-	if (entityKind === "audio-script" && /^segments\[\d+\]\.segmentId$/.test(path)) return true;
+	if ([
+		"audio-script",
+		"caption",
+		"phonetic-script"
+	].includes(entityKind) && /^segments\[\d+\]\.segmentId$/.test(path)) return true;
 	if (entityKind === "caption" && /^selections\[\d+\]\.segmentId$/.test(path)) return true;
 	if (entityKind === "sequence-marker" && /^segmentRanges\[\d+\]\.segmentId$/.test(path)) return true;
 	if (entityKind === "asset" && /^(?:tracks\[\d+\]\.trackId|renditions\[\d+\]\.renditionId)$/.test(path)) return true;
@@ -2329,35 +2447,6 @@ function ofKind(relations, kind) {
 	return relations.filter((relation) => relation.kind === kind);
 }
 //#endregion
-//#region ../medeo-dsl/src/json-values.ts
-const nativeObjectConstructorSource = Function.prototype.toString.call(Object);
-function isJsonObject(value) {
-	return isJsonValue(value, /* @__PURE__ */ new Set()) && !Array.isArray(value) && value !== null;
-}
-function isJsonValue(value, ancestors) {
-	if (value === null || typeof value === "string" || typeof value === "boolean") return true;
-	if (typeof value === "number") return Number.isFinite(value);
-	if (typeof value !== "object") return false;
-	if (!Array.isArray(value) && !isPlainObject(value)) return false;
-	if (ancestors.has(value)) return false;
-	ancestors.add(value);
-	const valid = Array.isArray(value) ? value.every((item) => isJsonValue(item, ancestors)) : Object.values(value).every((item) => isJsonValue(item, ancestors));
-	ancestors.delete(value);
-	return valid;
-}
-/** Recognize an ordinary object from any VM realm without admitting class instances. */
-function isPlainObject(value) {
-	try {
-		const prototype = Object.getPrototypeOf(value);
-		if (prototype === null) return true;
-		if (Object.getPrototypeOf(prototype) !== null) return false;
-		const constructor = Object.getOwnPropertyDescriptor(prototype, "constructor")?.value;
-		return typeof constructor === "function" && constructor.prototype === prototype && Function.prototype.toString.call(constructor) === nativeObjectConstructorSource;
-	} catch {
-		return false;
-	}
-}
-//#endregion
 //#region ../medeo-dsl/src/relation-specs.ts
 const timelineTrackRelationSpec = emptySpec("timeline-track", "timeline", "track");
 const trackClipRelationSpec = emptySpec("track-clip", "track", "clip");
@@ -2380,15 +2469,6 @@ const generatedRelationSpec = Object.freeze({
 	validateEndpoints: (endpoints) => endpoints.every((endpoint) => isGeneratedMedia(endpoint.current())),
 	validateMetadata: isEmptyMetadata
 });
-/**
-* Variant composition: the required content relation between a variant and its
-* AudioScript. This is the assembly source for the variant's base text — never
-* a downgradeable provenance label. A variant without exactly one live
-* composition Relation has no valid content and fails validation.
-*/
-const phoneticScriptCompositionRelationSpec = metadataSpec("phonetic-script-composition", "phonetic-script", "audio-script", isSegmentAlignmentMetadata);
-/** See {@link phoneticScriptCompositionRelationSpec}; Caption is the display variant. */
-const captionCompositionRelationSpec = metadataSpec("caption-composition", "caption", "audio-script", isSegmentAlignmentMetadata);
 const captionAlignmentRelationSpec = Object.freeze({
 	kind: "caption-alignment",
 	validateEndpoints: (endpoints) => hasKinds(endpoints, new Set(["caption"]), new Set(["audio", "voice"])),
@@ -2437,8 +2517,6 @@ const builtInRelationSpecs = Object.freeze([
 	markerTimelineRelationSpec,
 	physicalAssetRelationSpec,
 	generatedRelationSpec,
-	phoneticScriptCompositionRelationSpec,
-	captionCompositionRelationSpec,
 	captionAlignmentRelationSpec,
 	clipAnchorRelationSpec,
 	phoneticScriptRenderRelationSpec,
@@ -2481,9 +2559,6 @@ function isAssetBinding(value) {
 	const orderingKey = /(order|ordinal|position|rank|index|z[_-]?index)/i;
 	return Object.keys(value).every((key) => !orderingKey.test(key));
 }
-function isSegmentAlignmentMetadata(value) {
-	return isJsonObject(value) && Object.hasOwn(value, "segmentAlignment");
-}
 function isCaptionAlignmentMetadata(value) {
 	return isJsonObject(value) && Object.hasOwn(value, "alignment");
 }
@@ -2669,7 +2744,13 @@ function decodeEntityRelationRows(rows, options) {
 	const entitiesById = /* @__PURE__ */ new Map();
 	const extensionEntityKinds = new Set(options.entityKinds ?? []);
 	for (const row of rows.entities) {
-		const entity = decodeEntityRow(row, extensionEntityKinds, issues);
+		let entity = decodeEntityRow(row, extensionEntityKinds, issues);
+		if (entity != null) try {
+			entity = decodeEntityRow(assembleEntityContent(rows, row.entityId), extensionEntityKinds, issues);
+		} catch (error) {
+			issues.push(errorMessage(error));
+			continue;
+		}
 		if (entity == null) continue;
 		const ref = createEntityRef(entity);
 		if (entitiesById.has(ref.entityId)) {
@@ -2849,9 +2930,9 @@ var EntityProjectionGraph = class {
 	timeline;
 	constructor(rows) {
 		this.rows = rows;
-		decodeEntityRelationRows(rows, { compareMarkerPoints: (_marker, _range, left, right) => finite(left, "range point") - finite(right, "range point") });
-		this.entities = new Map(rows.entities.map((row) => [String(row.entityId), row]));
-		const roots = rows.entities.filter((row) => row.entityKind === "timeline");
+		const decoded = decodeEntityRelationRows(rows, { compareMarkerPoints: (_marker, _range, left, right) => finite(left, "range point") - finite(right, "range point") });
+		this.entities = new Map([...decoded.entitiesById.values()].map((ref) => [String(ref.entityId), entityToRow(ref.current())]));
+		const roots = [...this.entities.values()].filter((row) => row.entityKind === "timeline");
 		if (roots.length !== 1) fail("compatibility projection requires exactly one Timeline");
 		this.timeline = roots[0];
 	}
@@ -3539,4 +3620,4 @@ function createPlainMemoryAdapter(document, options) {
 	return new PlainMemoryAdapter(document, options);
 }
 //#endregion
-export { ENTITY_TIMELINE_PROJECTION_SCHEMA_VERSION as $, VideoDocumentValidationError as A, cascadeAfterVideoClipChanges as B, hasSequence as C, derivePositionFromAbs as D, buildSpeechHostMap as E, LANE_KINDS_IN_STACK_ORDER as F, resolveAllSpeechOverlaps as G, fillMainTrackTimeGaps as H, ensureLaneTrack as I, TIMELINE_SKELETON_DURATION_MS as J, resolveSpeechOverlapByShiftingVideos as K, findLaneTrack as L, validateVideoDocument as M, partUnionSchema as N, fromVideoDocument as O, videoDocumentSchema as P, DEFAULT_UNIT_TIME_MS as Q, laneTrackId as R, selectAudioScriptSegments as S, buildInitialVideoDocument as T, reassignSpeechesToVideoClipsByTime as U, arrangeMainTrackSeamlessly as V, recalculateTimelineDuration as W, partDurationMs as X, isEmptyVideoClip as Y, safeDurationMs as Z, ScriptCompositionError as _, applyEntityTimelineProjection as a, videoDocumentMirrorSchema as at, assembleScriptText as b, writeVideoDocumentToDraft as c, resolveEntityTimelineLayout as d, VIDEO_DOCUMENT_SCHEMA_VERSION as et, EntityTimelineProjectionError as f, createRelationId as g, createEntityId as h, MirrorVideoDocumentAdapter as i, recordEntries as it, assertValidVideoDocument as j, toVideoDocument as k, readVideoDocumentFromDraft as l, isJsonObject as m, createPlainMemoryAdapter as n, speedOf as nt, createMirrorVideoDocument as o, base64ToBytes as ot, decodeEntityRelationRows as p, syncAggregatedClipsTimePosition as q, generatePartId as r, partUnionToDraft as rt, createMirrorVideoDocumentAdapter as s, bytesToBase64 as st, PlainMemoryAdapter as t, effectiveVideoClipDurationMs as tt, projectEntityTimeline as u, assembleCaptionContent as v, isMediaAssetVariantKind as w, findComposedAudioScript as x, assemblePhoneticScriptContent as y, solveVideoDocument as z };
+export { isEmptyVideoClip as $, buildSpeechHostMap as A, ensureLaneTrack as B, variantBaseEntityIds as C, hasSequence as D, createRelationId as E, assertValidVideoDocument as F, arrangeMainTrackSeamlessly as G, laneTrackId as H, validateVideoDocument as I, recalculateTimelineDuration as J, fillMainTrackTimeGaps as K, partUnionSchema as L, fromVideoDocument as M, toVideoDocument as N, isMediaAssetVariantKind as O, VideoDocumentValidationError as P, TIMELINE_SKELETON_DURATION_MS as Q, videoDocumentSchema as R, updateEntityFields as S, createEntityId as T, solveVideoDocument as U, findLaneTrack as V, cascadeAfterVideoClipChanges as W, resolveSpeechOverlapByShiftingVideos as X, resolveAllSpeechOverlaps as Y, syncAggregatedClipsTimePosition as Z, assembleEntityContent as _, applyEntityTimelineProjection as a, effectiveVideoClipDurationMs as at, findComposedAudioScript as b, writeVideoDocumentToDraft as c, recordEntries as ct, EntityProjectionGraph as d, bytesToBase64 as dt, partDurationMs as et, resolveEntityTimelineLayout as f, assembleCaptionContent as g, ScriptCompositionError as h, MirrorVideoDocumentAdapter as i, VIDEO_DOCUMENT_SCHEMA_VERSION as it, derivePositionFromAbs as j, buildInitialVideoDocument as k, readVideoDocumentFromDraft as l, videoDocumentMirrorSchema as lt, decodeEntityRelationRows as m, createPlainMemoryAdapter as n, DEFAULT_UNIT_TIME_MS as nt, createMirrorVideoDocument as o, speedOf as ot, EntityTimelineProjectionError as p, reassignSpeechesToVideoClipsByTime as q, generatePartId as r, ENTITY_TIMELINE_PROJECTION_SCHEMA_VERSION as rt, createMirrorVideoDocumentAdapter as s, partUnionToDraft as st, PlainMemoryAdapter as t, safeDurationMs as tt, projectEntityTimeline as u, base64ToBytes as ut, assemblePhoneticScriptContent as v, isJsonObject as w, selectAudioScriptSegments as x, assembleScriptText as y, LANE_KINDS_IN_STACK_ORDER as z };

package/dist/{index-PYtGeXNk.d.ts → index-Dxxu0Mi1.d.ts}

@@ -914,7 +914,7 @@ interface CaptionTextRange extends JsonObject {
  * One ordered entry of the Caption's segment selection. `segmentId` quotes the
  * composed AudioScript's own stable segment identity — a local id quoted by the
  * variant, never a peer Entity reference. Text itself is never copied here;
- * complete Caption content is assembled along the caption-composition Relation.
+ * complete Caption content is assembled through its direct baseEntityIds.
  * The optional `textRange` narrows one Segment to an intra-Segment sub-span
  * (intra-segment re-segmentation); without it the whole Segment text is selected.
  */
@@ -924,7 +924,7 @@ type CaptionSegmentSelection = JsonObject & {
 };
 //#endregion
 //#region ../medeo-dsl/src/relations.d.ts
-type KnownRelationKind = 'timeline-track' | 'track-clip' | 'clip-marker' | 'marker-content' | 'axvideo-marker' | 'marker-timeline' | 'physical-asset' | 'generated' | 'phonetic-script-composition' | 'caption-composition' | 'caption-alignment' | 'clip-anchor' | 'phonetic-script-render' | 'audio-script-source' | 'audio-script-marker';
+type KnownRelationKind = 'timeline-track' | 'track-clip' | 'clip-marker' | 'marker-content' | 'axvideo-marker' | 'marker-timeline' | 'physical-asset' | 'generated' | 'caption-alignment' | 'clip-anchor' | 'phonetic-script-render' | 'audio-script-source' | 'audio-script-marker';
 type RelationKind = KnownRelationKind | (string & {});
 type RelationTrace = JsonObject;
 /**

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { t as index_d_exports } from "./index-CMa6ZCtX.js";
-import { $ as VoiceDescriptor, A as generatePartId, At as effectiveVideoClipDurationMs, B as ResolvedEntityClipPlacement, C as PlannedSemanticOpKind, Ct as VideoClipPart, D as SnapshotReadable, Dt as VideoDocumentValidationIssueCode, E as SchemaValidator, Et as VideoDocumentValidationIssue, F as videoDocumentMirrorSchema, Ft as PartAggregation, G as EntityTimelineProjectionError, H as ResolvedEntityTrack, I as VideoDocumentValidationError, It as SpeedShift, J as CaptionSegmentSelection, K as EntityRelationRows, L as assertValidVideoDocument, Lt as Timeline$1, M as TrackItemDraft, Mt as Attachment, N as VideoDocumentDraft, Nt as CaptionPart$1, O as ValidationError, Ot as VideoDraft, P as VideoDocumentMirrorSchema, Pt as CaptionStyle, Q as SequenceRange, R as validateVideoDocument, Rt as Track$1, S as ImplementedSemanticOpKind, St as VIDEO_DOCUMENT_SCHEMA_VERSION, T as isImplementedSemanticOpKind, Tt as VideoDocumentSchemaVersion, U as resolveEntityTimelineLayout, V as ResolvedEntityTimelineLayout, W as projectEntityTimeline, X as ScriptTextSegment, Y as CaptionStyleFields, Z as SequenceDuration, _ as SemanticEditor, _t as SpeechPart, a as PlainMemoryAdapter, at as DerivedItemPosition, b as TransactAudit, bt as TrackItem, c as MirrorVideoDocumentAdapter, ct as derivePositionFromAbs, d as createMirrorVideoDocument, dt as BgmPart, et as JsonObject, f as createMirrorVideoDocumentAdapter, ft as CaptionPart, g as SemanticDocumentAdapter, gt as PartUnion, h as OpActor, ht as PartKind, i as JournalEntry, it as buildInitialVideoDocument, j as TrackDraft, jt as speedOf, k as PartIdFactory, kt as VideoDraftPartUnion, l as MirrorVideoDocumentOptions, lt as fromVideoDocument, m as CommitOptions, mt as ENTITY_TIMELINE_PROJECTION_SCHEMA_VERSION, n as videoDocumentSchema, nt as EntityId, o as PlainMemoryAdapterOptions, ot as SpeechHostMap, p as writeVideoDocumentToDraft, pt as DEFAULT_UNIT_TIME_MS, q as EntityRow, r as readVideoDocumentFromDraft, rt as InitialDocumentFacts, s as createPlainMemoryAdapter, st as buildSpeechHostMap, t as partUnionSchema, tt as JsonValue, u as applyEntityTimelineProjection, ut as toVideoDocument, v as SemanticOpInput, vt as Timeline, w as SemanticOpKind, wt as VideoDocument, x as IMPLEMENTED_SEMANTIC_OP_KINDS, xt as TrackItemTimePosition, y as SemanticOpName, yt as Track, z as EntityTimelineTrackRole, zt as TrackItem$1 } from "./index-PYtGeXNk.js";
+import { $ as VoiceDescriptor, A as generatePartId, At as effectiveVideoClipDurationMs, B as ResolvedEntityClipPlacement, C as PlannedSemanticOpKind, Ct as VideoClipPart, D as SnapshotReadable, Dt as VideoDocumentValidationIssueCode, E as SchemaValidator, Et as VideoDocumentValidationIssue, F as videoDocumentMirrorSchema, Ft as PartAggregation, G as EntityTimelineProjectionError, H as ResolvedEntityTrack, I as VideoDocumentValidationError, It as SpeedShift, J as CaptionSegmentSelection, K as EntityRelationRows, L as assertValidVideoDocument, Lt as Timeline$1, M as TrackItemDraft, Mt as Attachment, N as VideoDocumentDraft, Nt as CaptionPart$1, O as ValidationError, Ot as VideoDraft, P as VideoDocumentMirrorSchema, Pt as CaptionStyle, Q as SequenceRange, R as validateVideoDocument, Rt as Track$1, S as ImplementedSemanticOpKind, St as VIDEO_DOCUMENT_SCHEMA_VERSION, T as isImplementedSemanticOpKind, Tt as VideoDocumentSchemaVersion, U as resolveEntityTimelineLayout, V as ResolvedEntityTimelineLayout, W as projectEntityTimeline, X as ScriptTextSegment, Y as CaptionStyleFields, Z as SequenceDuration, _ as SemanticEditor, _t as SpeechPart, a as PlainMemoryAdapter, at as DerivedItemPosition, b as TransactAudit, bt as TrackItem, c as MirrorVideoDocumentAdapter, ct as derivePositionFromAbs, d as createMirrorVideoDocument, dt as BgmPart, et as JsonObject, f as createMirrorVideoDocumentAdapter, ft as CaptionPart, g as SemanticDocumentAdapter, gt as PartUnion, h as OpActor, ht as PartKind, i as JournalEntry, it as buildInitialVideoDocument, j as TrackDraft, jt as speedOf, k as PartIdFactory, kt as VideoDraftPartUnion, l as MirrorVideoDocumentOptions, lt as fromVideoDocument, m as CommitOptions, mt as ENTITY_TIMELINE_PROJECTION_SCHEMA_VERSION, n as videoDocumentSchema, nt as EntityId, o as PlainMemoryAdapterOptions, ot as SpeechHostMap, p as writeVideoDocumentToDraft, pt as DEFAULT_UNIT_TIME_MS, q as EntityRow, r as readVideoDocumentFromDraft, rt as InitialDocumentFacts, s as createPlainMemoryAdapter, st as buildSpeechHostMap, t as partUnionSchema, tt as JsonValue, u as applyEntityTimelineProjection, ut as toVideoDocument, v as SemanticOpInput, vt as Timeline, w as SemanticOpKind, wt as VideoDocument, x as IMPLEMENTED_SEMANTIC_OP_KINDS, xt as TrackItemTimePosition, y as SemanticOpName, yt as Track, z as EntityTimelineTrackRole, zt as TrackItem$1 } from "./index-Dxxu0Mi1.js";
 import { PeerID } from "loro-crdt";
 import { DocState } from "@mengine/sync";
 import { BaseDocStorage, Connection, DocDiff, DocPushReceipt, DocSnapshotRecord, DocStorage, DocStorageOptions, DocUpdate, DocUpdateRecord } from "@mengine/storage";
@@ -179,13 +179,8 @@ interface MengineEventStreamOptions {
 declare function readMengineEventStream(options: MengineEventStreamOptions): Promise<void>;
 //#endregion
 //#region ../medeo-dsl/src/composition.d.ts
-type ScriptCompositionIssueCode = 'composition_missing' | 'composition_ambiguous' | 'composition_dangling' | 'unknown_segment' | 'empty_selection' | 'invalid_script' | 'invalid_selection';
-/**
- * Raised when a variant's complete content cannot be assembled from its
- * required composition Relation. Assembly never falls back to variant-local
- * text: a missing, ambiguous, or dangling source is an error, not an empty
- * read.
- */
+type ScriptCompositionIssueCode = 'field_conflict' | 'composition_cycle' | 'invalid_bases' | 'composition_missing' | 'composition_ambiguous' | 'composition_dangling' | 'unknown_segment' | 'empty_selection' | 'invalid_script' | 'invalid_selection';
+/** Assembly fails explicitly when declared bases cannot provide valid, unambiguous content. */
 declare class ScriptCompositionError extends Error {
   readonly code: ScriptCompositionIssueCode;
   readonly entityId: EntityId;
@@ -207,19 +202,13 @@ interface AssembledPhoneticScriptContent {
   /** Complete base text owned by the AudioScript. */
   readonly text: string;
 }
-/**
- * Resolve the one AudioScript a variant composes. Relations are queried from
- * both endpoints, so persisted endpoint positions do not matter.
- */
+/** Validate all base providers before applying explicit own fields; ordering cannot resolve ambiguity. */
+declare function assembleEntityContent(rows: EntityRelationRows, entityId: EntityId): EntityRow;
+/** Find the actual AudioScript text owner through direct variant bases. */
 declare function findComposedAudioScript(rows: EntityRelationRows, variantEntityId: EntityId, variantKind: 'caption' | 'phonetic-script'): EntityRow<'audio-script'>;
 /** Join the whole AudioScript text in segment order. */
 declare function assembleScriptText(script: EntityRow<'audio-script'>): string;
-/**
- * Assemble the complete Caption content from its AudioScript: the selected
- * segments in selection order, joined as display text. The Caption payload
- * never carries text, so a broken composition fails here instead of silently
- * rendering an empty caption.
- */
+/** Assemble selected text after base-field validation and explicit variant overrides. */
 declare function assembleCaptionContent(rows: EntityRelationRows, captionEntityId: EntityId): AssembledCaptionContent;
 /**
  * Assemble the complete Phonetic Script content for TTS: the composed
@@ -339,6 +328,8 @@ interface DeleteClipTreeInput {
 interface VoiceoverCaptionFact {
   /** Stable placed caption identity supplied by the materialized side effect. */
   readonly captionClipEntityId: string;
+  /** Directly held bases; includes the AudioScript used by the Voice. */
+  readonly baseEntityIds: readonly string[];
   /** Ordered selection of AudioScript segments; caption text is never passed inline. */
   readonly selections: readonly CaptionSegmentSelection[];
   readonly startMs: number;
@@ -427,7 +418,7 @@ interface VoiceoverTakeResult {
   readonly voiceEntityId: string;
   /** The pronunciation variant the Voice was rendered from. */
   readonly phoneticScriptEntityId: string;
-  /** The base-text owner resolved along the phonetic composition Relation. */
+  /** The base-text owner resolved from the PhoneticScript baseEntityIds. */
   readonly audioScriptEntityId: string;
   readonly captionClipEntityIds: readonly string[];
 }
@@ -460,8 +451,8 @@ interface InsertCaptionClipInput {
   readonly timelineEntityId: string;
   /** Stable placed caption identity, distinct from the Caption content identity. */
   readonly captionClipEntityId?: string;
-  /** Existing base-text owner; the Caption composes it instead of storing text. */
-  readonly audioScriptEntityId: string;
+  /** Existing bases composed by this variant; includes an AudioScript text owner. */
+  readonly baseEntityIds: readonly string[];
   /** Ordered selection of the AudioScript segments this Caption displays. */
   readonly selections: readonly CaptionSegmentSelection[];
   /** Intrinsic cue length of the Caption entity itself; display comes from the placement. */
@@ -549,8 +540,8 @@ declare class EntityTimelineEditor {
   patchCaptionStyle(input: PatchCaptionStyleInput): void;
   /**
    * Place a Caption as a composed variant of an existing AudioScript: the
-   * entity stores only its selection, style, and inherent cue-bounded
-   * Sequence — never text. The Clip and its display Marker describe this use;
+   * entity stores baseEntityIds, selection, optional style, and inherent cue-bounded
+   * Sequence. This helper does not copy base text. The Clip and its display Marker describe this use;
    * moving or stretching the returned Clip later changes the Clip/Marker,
    * never the Caption entity or the AudioScript.
    */
@@ -563,7 +554,7 @@ declare class EntityTimelineEditor {
   private ensurePhoneticRender;
   private reconcileVoiceoverCaptions;
   private ensureRoleTrackForClip;
-  private replaceCaptionSemanticRelations;
+  private replaceCaptionAlignment;
   /**
    * Remove one placed Caption use. The composed AudioScript outlives the
    * caption: it may anchor further captions and remains the text owner.
@@ -651,6 +642,17 @@ declare function migrateLegacyTimelineToEntities(legacy: VideoDocument, assetFac
 /** Server gate: a cutover may change representation, never the existing render facts. */
 declare function assertEntityProjectionPreservesLegacy(legacy: VideoDocument, projection: VideoDocument, rows: EntityRelationRows): void;
 //#endregion
+//#region src/entity-editor/caption-content.d.ts
+interface CaptionContentInput {
+  readonly contentEntityId: string;
+  readonly audioScriptEntityId: string;
+  readonly text: string;
+  readonly selections?: readonly CaptionSegmentSelection[];
+  readonly durationMs: number;
+}
+/** Author Caption content from semantic intent; callers never reconcile variant bases or assembled fields. */
+declare function prepareCaptionContent(rows: EntityRelationRows, input: CaptionContentInput): EntityRow<'caption'>;
+//#endregion
 //#region src/editor/journal.d.ts
 /**
  * Wire a plain-memory adapter + editor that share a recording id factory, so
@@ -1555,4 +1557,4 @@ declare function hostForAbsMs(ranges: MainClipRange[], absMs: number): MainClipR
  */
 declare function relativePositionForAbs(ranges: MainClipRange[], absMs: number): TrackItemTimePosition;
 //#endregion
-export { type Aggregation, type AssembledCaptionContent, type AssembledPhoneticScriptContent, type Attachment, type AudioMediaAssetFact, type BgmPart, type CaptionPart, type CaptionSegmentSelection, type CaptionStyle, type ClipEntityId, type ClipPlacement, type CommitOptions, DEFAULT_UNIT_TIME_MS, type DeleteBgmInput, type DeleteClipInput, type DeleteClipTreeInput, type DeleteVoiceoverInput, type DerivedItemPosition, type DocStorageLike, type DocVersionMark, ENTITY_TIMELINE_PROJECTION_SCHEMA_VERSION, type EditorFoundation, type EntityGraphCommitOptions, EntityGraphHttpClient, type EntityGraphState, EntityTimelineEditor, type EntityTimelineIdFactory, EntityTimelineProjectionError, type EntityTimelineTrackRole, IMPLEMENTED_SEMANTIC_OP_KINDS, type ImageMediaAssetFact, type ImplementedSemanticOpKind, type ImportedMediaAsset, type InitialDocumentFacts, type InsertCaptionClipInput, type InsertClipInput, type InsertMediaClipInput, type InsertMediaClipsInput, type InsertPlacedClipInput, type JournalEntry, LANE_KINDS_IN_STACK_ORDER, type LaneKind, type LinearClipSpeed, type MainClipRange, type MakeEmptyPart, ManualSyncDoc, type ManualSyncDocOptions, MedeoHttpDocStorage, type MedeoHttpDocStorageOptions, type MediaAssetFact, type MediaClipInsertion, MemoryDocStorage, MengineAckFailedError, type MengineAuditEntry, type MengineAuditResponse, MengineDocSession, type MengineDocSessionOptions, type MengineDocSessionUpdateEvent, type MengineDocumentVersion, type MengineEventStreamOptions, MengineHttpClient, type MengineHttpClientOptions, MengineHttpRequestError, MenginePushRejectedError, type MenginePushResponse, type MenginePushUpdateResponse, type MengineRejectedResponse, type MengineSnapshotResponse, type MengineSseUpdateEvent, type MengineSyncResponse, type MengineUpdateMeta, MirrorVideoDocumentAdapter, type MirrorVideoDocumentOptions, type MoveClipInput, type MoveClipsToStartsInput, type MoveSequentialClipsInput, type MoveVoiceoverInput, type OpActor, type PartAggregation, type PartIdFactory, type PartKind, type PartUnion, type PatchCaptionStyleInput, PlainMemoryAdapter, type PlainMemoryAdapterOptions, type PlannedSemanticOpKind, type PullFailureReason, type PullResult, type PushOutcome, type PushOutcomeKind, type PushResult, type PushResultKind, type ReplaceClipContentInput, type ReplaceMediaClipInput, type ReplaceSequentialClipsInput, type ReplacementMediaClipInput, type ResolvedEntityClipPlacement, type ResolvedEntityTimelineLayout, type ResolvedEntityTrack, SchemaValidator, ScriptCompositionError, type SemanticDocumentAdapter, SemanticEditor, type SemanticOpInput, type SemanticOpKind, type SemanticOpName, type SequentialClipAnchor, type SetBgmInput, type SetCaptionVisibilityInput, type SetClipPlacementInput, type SetClipSpeedInput, type SetClipVolumeInput, type SnapshotReadable, type SolvedVideoDocument, type SpeechHostMap, type SpeechPart, type SpeedShift, TIMELINE_SKELETON_DURATION_MS, type Timeline, type TimelineDoc, type TimelineItem, type Track, type TrackDraft, type TrackItem, type TrackItemDraft, type TrackItemTimePosition, type TransactAudit, type TrimClipInput, type UpdateClipInput, type UpdateClipMarkerInput, VIDEO_DOCUMENT_SCHEMA_VERSION, ValidationError, type VideoClipPart, type VideoDocument, type VideoDocumentDraft, type VideoDocumentMirrorSchema, type VideoDocumentSchemaVersion, VideoDocumentValidationError, type VideoDocumentValidationIssue, type VideoDocumentValidationIssueCode, type VideoDraft, type CaptionPart$1 as VideoDraftCaptionPart, type VideoDraftPartUnion, type Timeline$1 as VideoDraftTimeline, type Track$1 as VideoDraftTrack, type TrackItem$1 as VideoDraftTrackItem, type VideoMediaAssetFact, type VisualMediaAssetFact, type VoiceMediaAssetFact, type VoiceoverCaptionFact, type VoiceoverTakeInput, type VoiceoverTakeResult, type WaitForServerAckOptions, applyEntityTimelineProjection, arrangeMainTrackSeamlessly, assembleCaptionContent, assemblePhoneticScriptContent, assembleScriptText, assertCanonicalEditorResources, assertEntityProjectionPreservesLegacy, assertMediaAssetWritePolicy, assertValidVideoDocument, base64ToBytes, buildInitialVideoDocument, buildSpeechHostMap, bytesToBase64, cascadeAfterVideoClipChanges, 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, projectEntityTimeline, readMainTrackItems, readMengineEventStream, readPart, readPartDurationMs, readVideoDocumentFromDraft, reassignSpeechesToVideoClipsByTime, recalculateTimelineDuration, relativePositionForAbs, replayJournal, resolveAllSpeechOverlaps, resolveEntityTimelineLayout, resolveSpeechOverlapByShiftingVideos, safeDurationMs, index_d_exports as schemas, selectAudioScriptSegments, snapshotToPlain, solveVideoDocument, speedOf, syncAggregatedClipsTimePosition, toVideoDocument, validateVideoDocument, videoDocumentMirrorSchema, videoDocumentSchema, writeVideoDocumentToDraft };
+export { type Aggregation, type AssembledCaptionContent, type AssembledPhoneticScriptContent, type Attachment, type AudioMediaAssetFact, type BgmPart, type CaptionContentInput, type CaptionPart, type CaptionSegmentSelection, type CaptionStyle, type ClipEntityId, type ClipPlacement, type CommitOptions, DEFAULT_UNIT_TIME_MS, type DeleteBgmInput, type DeleteClipInput, type DeleteClipTreeInput, type DeleteVoiceoverInput, type DerivedItemPosition, type DocStorageLike, type DocVersionMark, ENTITY_TIMELINE_PROJECTION_SCHEMA_VERSION, type EditorFoundation, type EntityGraphCommitOptions, EntityGraphHttpClient, type EntityGraphState, EntityTimelineEditor, type EntityTimelineIdFactory, EntityTimelineProjectionError, type EntityTimelineTrackRole, IMPLEMENTED_SEMANTIC_OP_KINDS, type ImageMediaAssetFact, type ImplementedSemanticOpKind, type ImportedMediaAsset, type InitialDocumentFacts, type InsertCaptionClipInput, type InsertClipInput, type InsertMediaClipInput, type InsertMediaClipsInput, type InsertPlacedClipInput, type JournalEntry, LANE_KINDS_IN_STACK_ORDER, type LaneKind, type LinearClipSpeed, type MainClipRange, type MakeEmptyPart, ManualSyncDoc, type ManualSyncDocOptions, MedeoHttpDocStorage, type MedeoHttpDocStorageOptions, type MediaAssetFact, type MediaClipInsertion, MemoryDocStorage, MengineAckFailedError, type MengineAuditEntry, type MengineAuditResponse, MengineDocSession, type MengineDocSessionOptions, type MengineDocSessionUpdateEvent, type MengineDocumentVersion, type MengineEventStreamOptions, MengineHttpClient, type MengineHttpClientOptions, MengineHttpRequestError, MenginePushRejectedError, type MenginePushResponse, type MenginePushUpdateResponse, type MengineRejectedResponse, type MengineSnapshotResponse, type MengineSseUpdateEvent, type MengineSyncResponse, type MengineUpdateMeta, MirrorVideoDocumentAdapter, type MirrorVideoDocumentOptions, type MoveClipInput, type MoveClipsToStartsInput, type MoveSequentialClipsInput, type MoveVoiceoverInput, type OpActor, type PartAggregation, type PartIdFactory, type PartKind, type PartUnion, type PatchCaptionStyleInput, PlainMemoryAdapter, type PlainMemoryAdapterOptions, type PlannedSemanticOpKind, type PullFailureReason, type PullResult, type PushOutcome, type PushOutcomeKind, type PushResult, type PushResultKind, type ReplaceClipContentInput, type ReplaceMediaClipInput, type ReplaceSequentialClipsInput, type ReplacementMediaClipInput, type ResolvedEntityClipPlacement, type ResolvedEntityTimelineLayout, type ResolvedEntityTrack, SchemaValidator, ScriptCompositionError, type SemanticDocumentAdapter, SemanticEditor, type SemanticOpInput, type SemanticOpKind, type SemanticOpName, type SequentialClipAnchor, type SetBgmInput, type SetCaptionVisibilityInput, type SetClipPlacementInput, type SetClipSpeedInput, type SetClipVolumeInput, type SnapshotReadable, type SolvedVideoDocument, type SpeechHostMap, type SpeechPart, type SpeedShift, TIMELINE_SKELETON_DURATION_MS, type Timeline, type TimelineDoc, type TimelineItem, type Track, type TrackDraft, type TrackItem, type TrackItemDraft, type TrackItemTimePosition, type TransactAudit, type TrimClipInput, type UpdateClipInput, type UpdateClipMarkerInput, VIDEO_DOCUMENT_SCHEMA_VERSION, ValidationError, type VideoClipPart, type VideoDocument, type VideoDocumentDraft, type VideoDocumentMirrorSchema, type VideoDocumentSchemaVersion, VideoDocumentValidationError, type VideoDocumentValidationIssue, type VideoDocumentValidationIssueCode, type VideoDraft, type CaptionPart$1 as VideoDraftCaptionPart, type VideoDraftPartUnion, type Timeline$1 as VideoDraftTimeline, type Track$1 as VideoDraftTrack, type TrackItem$1 as VideoDraftTrackItem, type VideoMediaAssetFact, type VisualMediaAssetFact, type VoiceMediaAssetFact, type VoiceoverCaptionFact, type VoiceoverTakeInput, type VoiceoverTakeResult, type WaitForServerAckOptions, applyEntityTimelineProjection, arrangeMainTrackSeamlessly, assembleCaptionContent, assembleEntityContent, assemblePhoneticScriptContent, assembleScriptText, assertCanonicalEditorResources, assertEntityProjectionPreservesLegacy, assertMediaAssetWritePolicy, assertValidVideoDocument, base64ToBytes, buildInitialVideoDocument, buildSpeechHostMap, bytesToBase64, cascadeAfterVideoClipChanges, 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, readMainTrackItems, readMengineEventStream, readPart, readPartDurationMs, readVideoDocumentFromDraft, reassignSpeechesToVideoClipsByTime, recalculateTimelineDuration, relativePositionForAbs, replayJournal, resolveAllSpeechOverlaps, resolveEntityTimelineLayout, resolveSpeechOverlapByShiftingVideos, safeDurationMs, index_d_exports as schemas, selectAudioScriptSegments, snapshotToPlain, solveVideoDocument, speedOf, syncAggregatedClipsTimePosition, toVideoDocument, validateVideoDocument, videoDocumentMirrorSchema, videoDocumentSchema, writeVideoDocumentToDraft };

package/dist/index.js

@@ -1,4 +1,4 @@
-import { $ as ENTITY_TIMELINE_PROJECTION_SCHEMA_VERSION, A as VideoDocumentValidationError, B as cascadeAfterVideoClipChanges, C as hasSequence, D as derivePositionFromAbs, E as buildSpeechHostMap, F as LANE_KINDS_IN_STACK_ORDER, G as resolveAllSpeechOverlaps, H as fillMainTrackTimeGaps, I as ensureLaneTrack, J as TIMELINE_SKELETON_DURATION_MS, K as resolveSpeechOverlapByShiftingVideos, L as findLaneTrack, M as validateVideoDocument, N as partUnionSchema, O as fromVideoDocument, P as videoDocumentSchema, Q as DEFAULT_UNIT_TIME_MS, R as laneTrackId, S as selectAudioScriptSegments, T as buildInitialVideoDocument, U as reassignSpeechesToVideoClipsByTime, V as arrangeMainTrackSeamlessly, W as recalculateTimelineDuration, X as partDurationMs, Y as isEmptyVideoClip, Z as safeDurationMs, _ as ScriptCompositionError, a as applyEntityTimelineProjection, at as videoDocumentMirrorSchema, b as assembleScriptText, c as writeVideoDocumentToDraft, d as resolveEntityTimelineLayout, et as VIDEO_DOCUMENT_SCHEMA_VERSION, f as EntityTimelineProjectionError, g as createRelationId, h as createEntityId, i as MirrorVideoDocumentAdapter, it as recordEntries, j as assertValidVideoDocument, k as toVideoDocument, l as readVideoDocumentFromDraft, m as isJsonObject, n as createPlainMemoryAdapter, nt as speedOf, o as createMirrorVideoDocument, ot as base64ToBytes, p as decodeEntityRelationRows, q as syncAggregatedClipsTimePosition, r as generatePartId, rt as partUnionToDraft, s as createMirrorVideoDocumentAdapter, st as bytesToBase64, t as PlainMemoryAdapter, tt as effectiveVideoClipDurationMs, u as projectEntityTimeline, v as assembleCaptionContent, w as isMediaAssetVariantKind, x as findComposedAudioScript, y as assemblePhoneticScriptContent, z as solveVideoDocument } from "./document-Bf200CmD.js";
+import { $ as isEmptyVideoClip, A as buildSpeechHostMap, B as ensureLaneTrack, C as variantBaseEntityIds, D as hasSequence, E as createRelationId, F as assertValidVideoDocument, G as arrangeMainTrackSeamlessly, H as laneTrackId, I as validateVideoDocument, J as recalculateTimelineDuration, K as fillMainTrackTimeGaps, L as partUnionSchema, M as fromVideoDocument, N as toVideoDocument, O as isMediaAssetVariantKind, P as VideoDocumentValidationError, Q as TIMELINE_SKELETON_DURATION_MS, R as videoDocumentSchema, S as updateEntityFields, T as createEntityId, U as solveVideoDocument, V as findLaneTrack, W as cascadeAfterVideoClipChanges, X as resolveSpeechOverlapByShiftingVideos, Y as resolveAllSpeechOverlaps, Z as syncAggregatedClipsTimePosition, _ as assembleEntityContent, a as applyEntityTimelineProjection, at as effectiveVideoClipDurationMs, b as findComposedAudioScript, c as writeVideoDocumentToDraft, ct as recordEntries, d as EntityProjectionGraph, dt as bytesToBase64, et as partDurationMs, f as resolveEntityTimelineLayout, g as assembleCaptionContent, h as ScriptCompositionError, i as MirrorVideoDocumentAdapter, it as VIDEO_DOCUMENT_SCHEMA_VERSION, j as derivePositionFromAbs, k as buildInitialVideoDocument, l as readVideoDocumentFromDraft, lt as videoDocumentMirrorSchema, m as decodeEntityRelationRows, n as createPlainMemoryAdapter, nt as DEFAULT_UNIT_TIME_MS, o as createMirrorVideoDocument, ot as speedOf, p as EntityTimelineProjectionError, q as reassignSpeechesToVideoClipsByTime, r as generatePartId, rt as ENTITY_TIMELINE_PROJECTION_SCHEMA_VERSION, s as createMirrorVideoDocumentAdapter, st as partUnionToDraft, t as PlainMemoryAdapter, tt as safeDurationMs, u as projectEntityTimeline, ut as base64ToBytes, v as assemblePhoneticScriptContent, w as isJsonObject, x as selectAudioScriptSegments, y as assembleScriptText, z as LANE_KINDS_IN_STACK_ORDER } from "./document-BLYcbv8E.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";
@@ -616,8 +616,12 @@ function requireComposedAudioScript(rows, phoneticScriptEntityId) {
 function captionSelections(selections) {
 	return structuredClone(selections);
 }
-function assertSelectionNamesScriptSegments(rows, audioScriptEntityId, selections) {
-	selectAudioScriptSegments(requireEntityKind(rows, audioScriptEntityId, "audio-script"), selections);
+function captionBaseIds(ids) {
+	if (!Array.isArray(ids) || ids.length === 0) throw new Error("Caption requires non-empty baseEntityIds");
+	return ids.map(createEntityId);
+}
+function assertCaptionScript(rows, captionId, scriptId) {
+	if (assembleCaptionContent(rows, captionId).audioScript.entityId !== scriptId) throw new Error("Voiceover Caption must compose the same AudioScript as the PhoneticScript");
 }
 const roleOrder = {
 	caption: 0,
@@ -1281,28 +1285,23 @@ var EntityTimelineEditor = class {
 			const track = findRoleTrack(draft, input.timelineEntityId, "caption");
 			if (track === void 0) return;
 			const patch = cloneJsonObject(input.style, "Caption style");
+			const assembled = new EntityProjectionGraph(draft);
 			for (const clip of clipsOnTrack(draft, track.entityId)) {
 				const topology = requireClipTopology(draft, clip.entityId);
 				const caption = requireEntityKind(draft, otherEndpoint(topology.markerContentRelation, topology.marker.entityId), "caption");
-				const prior = caption.payload.style;
+				const prior = assembled.entity(caption.entityId).payload.style;
 				const style = isJsonObject(prior) ? prior : {};
-				replaceEntity(draft, caption.entityId, {
-					...caption,
-					payload: {
-						...caption.payload,
-						style: {
-							...style,
-							...patch
-						}
-					}
-				});
+				for (const updated of updateEntityFields(draft, caption.entityId, { style: {
+					...style,
+					...patch
+				} })) replaceEntity(draft, updated.entityId, updated);
 			}
 		});
 	}
 	/**
 	* Place a Caption as a composed variant of an existing AudioScript: the
-	* entity stores only its selection, style, and inherent cue-bounded
-	* Sequence — never text. The Clip and its display Marker describe this use;
+	* entity stores baseEntityIds, selection, optional style, and inherent cue-bounded
+	* Sequence. This helper does not copy base text. The Clip and its display Marker describe this use;
 	* moving or stretching the returned Clip later changes the Clip/Marker,
 	* never the Caption entity or the AudioScript.
 	*/
@@ -1310,8 +1309,6 @@ var EntityTimelineEditor = class {
 		return this.transact((draft) => {
 			const durationMs = finitePositive(input.durationMs, "Caption durationMs");
 			const selections = captionSelections(input.selections);
-			const script = requireEntityKind(draft, input.audioScriptEntityId, "audio-script");
-			assertSelectionNamesScriptSegments(draft, script.entityId, selections);
 			const track = this.ensureRoleTrack(draft, input.timelineEntityId, "caption");
 			const content = {
 				entityId: this.mintEntityId(draft),
@@ -1324,12 +1321,13 @@ var EntityTimelineEditor = class {
 					},
 					sampling: "native",
 					coordinateSpace: "milliseconds",
+					baseEntityIds: captionBaseIds(input.baseEntityIds),
 					selections,
 					...input.style === void 0 ? {} : { style: cloneJsonObject(input.style, "Caption style") }
 				}
 			};
 			draft.entities.push(content);
-			draft.relations.push(this.createRelation(draft, "caption-composition", content.entityId, script.entityId, { segmentAlignment: [] }));
+			assembleCaptionContent(draft, content.entityId);
 			return this.insertPlacedClipIntoDraft(draft, {
 				trackEntityId: track.entityId,
 				contentEntityId: content.entityId,
@@ -1434,7 +1432,7 @@ var EntityTimelineEditor = class {
 			const startMs = finiteNonNegative(caption.startMs, "Caption startMs");
 			const durationMs = finitePositive(caption.durationMs, "Caption durationMs");
 			const selections = captionSelections(caption.selections);
-			assertSelectionNamesScriptSegments(draft, audioScriptEntityId, selections);
+			const baseEntityIds = captionBaseIds(caption.baseEntityIds);
 			if (draft.entities.find((entity) => entity.entityId === caption.captionClipEntityId) === void 0) {
 				const content = {
 					entityId: this.mintEntityId(draft),
@@ -1447,12 +1445,14 @@ var EntityTimelineEditor = class {
 						},
 						sampling: "native",
 						coordinateSpace: "milliseconds",
+						baseEntityIds,
 						selections,
 						...caption.style === void 0 ? {} : { style: cloneJsonObject(caption.style, "Caption style") }
 					}
 				};
 				draft.entities.push(content);
-				draft.relations.push(this.createRelation(draft, "caption-composition", content.entityId, audioScriptEntityId, { segmentAlignment: [] }), this.createRelation(draft, "caption-alignment", content.entityId, voiceEntityId, { alignment: {
+				assertCaptionScript(draft, content.entityId, audioScriptEntityId);
+				draft.relations.push(this.createRelation(draft, "caption-alignment", content.entityId, voiceEntityId, { alignment: {
 					start: startMs,
 					end: startMs + durationMs
 				} }));
@@ -1487,10 +1487,12 @@ var EntityTimelineEditor = class {
 				...content,
 				payload: {
 					...content.payload,
+					baseEntityIds,
 					selections,
 					...Object.keys(style).length === 0 ? {} : { style }
 				}
 			});
+			assertCaptionScript(draft, content.entityId, audioScriptEntityId);
 			this.applyClipPlacement(draft, topology.clip.entityId, {
 				kind: "anchored",
 				hostClipEntityId: voiceoverClipEntityId,
@@ -1507,7 +1509,7 @@ var EntityTimelineEditor = class {
 					}
 				}
 			});
-			this.replaceCaptionSemanticRelations(draft, content.entityId, voiceEntityId, audioScriptEntityId, startMs, durationMs);
+			this.replaceCaptionAlignment(draft, content.entityId, voiceEntityId, startMs, durationMs);
 		}
 	}
 	ensureRoleTrackForClip(draft, clipEntityId, role) {
@@ -1516,13 +1518,13 @@ var EntityTimelineEditor = class {
 		const timeline = requireEntityKind(draft, otherEndpoint(requireOneRelation(draft, track.entityId, "timeline-track"), track.entityId), "timeline");
 		return this.ensureRoleTrack(draft, timeline.entityId, role);
 	}
-	replaceCaptionSemanticRelations(draft, captionEntityId, voiceEntityId, scriptEntityId, startMs, durationMs) {
-		const removed = new Set(incidentRelations(draft, captionEntityId).filter((relation) => relation.relationKind === "caption-alignment" || relation.relationKind === "caption-composition").map((relation) => relation.relationId));
+	replaceCaptionAlignment(draft, captionEntityId, voiceEntityId, startMs, durationMs) {
+		const removed = new Set(incidentRelations(draft, captionEntityId).filter((relation) => relation.relationKind === "caption-alignment").map((relation) => relation.relationId));
 		draft.relations = draft.relations.filter((relation) => !removed.has(relation.relationId));
 		draft.relations.push(this.createRelation(draft, "caption-alignment", captionEntityId, voiceEntityId, { alignment: {
 			start: startMs,
 			end: startMs + durationMs
-		} }), this.createRelation(draft, "caption-composition", captionEntityId, scriptEntityId, { segmentAlignment: [] }));
+		} }));
 	}
 	/**
 	* Remove one placed Caption use. The composed AudioScript outlives the
@@ -1532,11 +1534,7 @@ var EntityTimelineEditor = class {
 		const topology = requireClipOnRole(draft, clipEntityId, "caption");
 		const caption = requireEntityKind(draft, otherEndpoint(topology.markerContentRelation, topology.marker.entityId), "caption");
 		const contentRelations = incidentRelations(draft, caption.entityId);
-		const allowed = new Set([
-			"caption-composition",
-			"caption-alignment",
-			"marker-content"
-		]);
+		const allowed = new Set(["caption-alignment", "marker-content"]);
 		const unsupported = contentRelations.filter((relation) => !allowed.has(relation.relationKind));
 		if (unsupported.length > 0) throw new Error(`Cannot delete Caption with unsupported Relation ${unsupported[0].relationId}`);
 		this.removeClipGraph(draft, clipEntityId);
@@ -2076,7 +2074,7 @@ function migrateLegacyTimelineToEntities(legacy, assetFacts, initial = {
 				const voice = contentByPartId.get(caption.speech_part_id);
 				const render = relations.find((relation) => relation.relationKind === "phonetic-script-render" && relation.endpoint0EntityId === voice);
 				const phonetic = entities.find((entity) => entity.entityId === render?.endpoint1EntityId);
-				const script = phonetic === void 0 ? void 0 : composedAudioScript(phonetic, entities, relations);
+				const script = phonetic === void 0 ? void 0 : composedAudioScript(phonetic, entities);
 				if (script === void 0) fail("Legacy Caption has no composed AudioScript");
 				const sourceText = scriptText(script);
 				const captionText = caption.text;
@@ -2097,10 +2095,10 @@ function migrateLegacyTimelineToEntities(legacy, assetFacts, initial = {
 					},
 					sampling: "native",
 					coordinateSpace: "milliseconds",
+					baseEntityIds: [script.entityId],
 					selections,
 					...caption.style === void 0 ? {} : { style: toEntityCaptionStyle(caption.style) }
 				});
-				link("caption-composition", content, script.entityId, { segmentAlignment: [] });
 				link("caption-alignment", content, voice, { alignment: {
 					start: caption.start_ms,
 					end: caption.start_ms + duration
@@ -2450,25 +2448,25 @@ function ensureSpeechPhoneticChain(voiceEntityId, audioScriptText, phonemeScript
 	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`);
-		const script = composedAudioScript(phonetic, entities, relations);
+		const script = composedAudioScript(phonetic, entities);
 		if (script === void 0 || scriptText(script) !== audioScriptText) fail(`Voice ${voiceEntityId} conflicts with the legacy Speech script`);
 		return phonetic.entityId;
 	}
-	const script = addEntity("audio-script", { segments: [{
-		segmentId: "segment-0",
-		text: audioScriptText
-	}] });
-	const phonetic = addEntity("phonetic-script", phonemeScript === void 0 ? {} : { phonemeScript });
-	link("phonetic-script-composition", phonetic, script, { segmentAlignment: [] });
+	const phonetic = addEntity("phonetic-script", {
+		baseEntityIds: [addEntity("audio-script", { segments: [{
+			segmentId: "segment-0",
+			text: audioScriptText
+		}] })],
+		...phonemeScript === void 0 ? {} : { phonemeScript }
+	});
 	link("phonetic-script-render", voiceEntityId, phonetic);
 	return phonetic;
 }
-function composedAudioScript(phonetic, entities, relations) {
-	const edges = relations.filter((relation) => relation.relationKind === "phonetic-script-composition" && (relation.endpoint0EntityId === phonetic.entityId || relation.endpoint1EntityId === phonetic.entityId));
-	if (edges.length !== 1) return void 0;
-	const edge = edges[0];
-	const otherId = edge.endpoint0EntityId === phonetic.entityId ? edge.endpoint1EntityId : edge.endpoint0EntityId;
-	return entities.find((entity) => entity.entityId === otherId);
+function composedAudioScript(phonetic, entities) {
+	return findComposedAudioScript({
+		entities,
+		relations: []
+	}, phonetic.entityId, "phonetic-script");
 }
 function scriptText(script) {
 	const segments = script.payload.segments;
@@ -2558,6 +2556,82 @@ function fail(message) {
 	throw new EntityTimelineProjectionError(message);
 }
 //#endregion
+//#region src/entity-editor/caption-content.ts
+/** Author Caption content from semantic intent; callers never reconcile variant bases or assembled fields. */
+function prepareCaptionContent(rows, input) {
+	const entityId = createEntityId(input.contentEntityId);
+	const scriptId = createEntityId(input.audioScriptEntityId);
+	if (!Number.isFinite(input.durationMs) || input.durationMs <= 0) throw new Error("Caption duration must be positive");
+	const previous = rows.entities.find((row) => row.entityId === entityId);
+	if (previous !== void 0 && previous.entityKind !== "caption") throw new Error("Caption content identity has a different kind");
+	let baseEntityIds = [scriptId];
+	if (previous !== void 0) {
+		const source = assembleCaptionContent(rows, entityId).audioScript.entityId;
+		const bases = variantBaseEntityIds(previous);
+		if (source !== scriptId && !bases.includes(source)) throw new Error("Replacing an indirectly composed AudioScript requires an explicit composition change");
+		baseEntityIds = bases.map((id) => id === source ? scriptId : id);
+	}
+	const candidate = {
+		entityId,
+		entityKind: "caption",
+		payload: {
+			...previous?.payload,
+			baseEntityIds,
+			extent: previous?.payload.extent ?? {
+				kind: "bounded",
+				start: 0,
+				end: input.durationMs
+			},
+			sampling: previous?.payload.sampling ?? "native",
+			coordinateSpace: previous?.payload.coordinateSpace ?? "milliseconds"
+		}
+	};
+	const graph = {
+		...rows,
+		entities: [...rows.entities.filter((row) => row.entityId !== entityId), candidate]
+	};
+	const textSource = {
+		...assembleEntityContent(graph, entityId),
+		entityKind: "audio-script"
+	};
+	const selected = {
+		...candidate,
+		payload: {
+			...candidate.payload,
+			selections: structuredClone(input.selections ?? selectCaptionText(textSource, input.text))
+		}
+	};
+	if (assembleCaptionContent({
+		...graph,
+		entities: graph.entities.map((row) => row.entityId === entityId ? selected : row)
+	}, entityId).text !== input.text) throw new Error("Caption review text differs from its assembled variant content");
+	return selected;
+}
+function selectCaptionText(script, text) {
+	if (!text.trim()) throw new Error("Caption text selection must not be blank");
+	const source = script;
+	const fullText = assembleScriptText(source);
+	const segments = source.payload.segments;
+	if (text === fullText) return segments.map((segment) => ({ segmentId: segment.segmentId }));
+	const matches = [];
+	for (const segment of segments) {
+		let offset = segment.text.indexOf(text);
+		while (offset !== -1) {
+			const start = Array.from(segment.text.slice(0, offset)).length;
+			matches.push({
+				segmentId: segment.segmentId,
+				textRange: {
+					start,
+					end: start + Array.from(text).length
+				}
+			});
+			offset = segment.text.indexOf(text, offset + 1);
+		}
+	}
+	if (matches.length !== 1) throw new Error("Caption text must select a unique AudioScript range; provide explicit selections");
+	return matches;
+}
+//#endregion
 //#region src/editor/snapshot-utils.ts
 function isMap(value) {
 	return value instanceof Map;
@@ -4696,4 +4770,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, ScriptCompositionError, SemanticEditor, TIMELINE_SKELETON_DURATION_MS, VIDEO_DOCUMENT_SCHEMA_VERSION, ValidationError, VideoDocumentValidationError, applyEntityTimelineProjection, arrangeMainTrackSeamlessly, assembleCaptionContent, assemblePhoneticScriptContent, assembleScriptText, assertCanonicalEditorResources, assertEntityProjectionPreservesLegacy, assertMediaAssetWritePolicy, assertValidVideoDocument, base64ToBytes, buildInitialVideoDocument, buildSpeechHostMap, bytesToBase64, cascadeAfterVideoClipChanges, 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, projectEntityTimeline, readMainTrackItems, readMengineEventStream, readPart, readPartDurationMs, readVideoDocumentFromDraft, reassignSpeechesToVideoClipsByTime, recalculateTimelineDuration, relativePositionForAbs, replayJournal, resolveAllSpeechOverlaps, resolveEntityTimelineLayout, resolveSpeechOverlapByShiftingVideos, safeDurationMs, schemas_exports as schemas, selectAudioScriptSegments, snapshotToPlain, solveVideoDocument, speedOf, syncAggregatedClipsTimePosition, toVideoDocument, validateVideoDocument, videoDocumentMirrorSchema, videoDocumentSchema, writeVideoDocumentToDraft };
+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, ScriptCompositionError, SemanticEditor, TIMELINE_SKELETON_DURATION_MS, VIDEO_DOCUMENT_SCHEMA_VERSION, ValidationError, VideoDocumentValidationError, applyEntityTimelineProjection, arrangeMainTrackSeamlessly, assembleCaptionContent, assembleEntityContent, assemblePhoneticScriptContent, assembleScriptText, assertCanonicalEditorResources, assertEntityProjectionPreservesLegacy, assertMediaAssetWritePolicy, assertValidVideoDocument, base64ToBytes, buildInitialVideoDocument, buildSpeechHostMap, bytesToBase64, cascadeAfterVideoClipChanges, 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, readMainTrackItems, readMengineEventStream, readPart, readPartDurationMs, readVideoDocumentFromDraft, reassignSpeechesToVideoClipsByTime, recalculateTimelineDuration, relativePositionForAbs, replayJournal, resolveAllSpeechOverlaps, resolveEntityTimelineLayout, resolveSpeechOverlapByShiftingVideos, safeDurationMs, schemas_exports as schemas, selectAudioScriptSegments, snapshotToPlain, solveVideoDocument, speedOf, syncAggregatedClipsTimePosition, toVideoDocument, validateVideoDocument, videoDocumentMirrorSchema, videoDocumentSchema, writeVideoDocumentToDraft };

package/dist/testing.d.ts

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

package/dist/testing.js

@@ -1,4 +1,4 @@
-import { et as VIDEO_DOCUMENT_SCHEMA_VERSION, ot as base64ToBytes, s as createMirrorVideoDocumentAdapter, st as bytesToBase64 } from "./document-Bf200CmD.js";
+import { dt as bytesToBase64, it as VIDEO_DOCUMENT_SCHEMA_VERSION, s as createMirrorVideoDocumentAdapter, ut as base64ToBytes } from "./document-BLYcbv8E.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.3.1-alpha.1",
+  "version": "1.3.1-alpha.2",
   "license": "UNLICENSED",
   "repository": {
     "type": "git",
@@ -27,9 +27,9 @@
     "immer": "^10.2.0",
     "loro-mirror": "^2.2.0",
     "zod": "^4.4.3",
-    "@mengine/utils": "1.3.1-alpha.1",
-    "@mengine/storage": "1.3.1-alpha.1",
-    "@mengine/sync": "1.3.1-alpha.1"
+    "@mengine/storage": "1.3.1-alpha.2",
+    "@mengine/sync": "1.3.1-alpha.2",
+    "@mengine/utils": "1.3.1-alpha.2"
   },
   "devDependencies": {
     "@types/node": "^25.9.1",
@@ -39,8 +39,8 @@
     "typescript": "^6.0.3",
     "vite-plugin-wasm": "^3.6.0",
     "vite-plus": "^0.1.23",
-    "@mengine/medeo-dsl": "0.0.0",
-    "@mengine/idl-codegen": "0.0.0"
+    "@mengine/idl-codegen": "0.0.0",
+    "@mengine/medeo-dsl": "0.0.0"
   },
   "peerDependencies": {
     "loro-crdt": "^1.13.6"