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

package/README.md

@@ -44,8 +44,7 @@ boundary already fails rows whose media variants lack `external` or carry a
 media is an explicit caller decision, and no implicit historical merge or
 identity rewriting occurs. The
 compatibility reader reads physical facts directly from the media variant;
-Caption inline text still resolves its inline Asset through
-`physical-asset`.
+Caption text is assembled from its required AudioScript composition and never stored in an inline Asset.
 
 `SequenceMarker` owns source/target ranges, duration, and time remapping. `Clip`
 owns clip properties such as volume; `Track` owns track properties. References
@@ -74,15 +73,26 @@ their follow, keep-absolute, cascade, or detach decisions into the same entity
 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.
 
-Voice links to its AudioScript through `audio-script-render`; Caption links to
-its source script and optional alignment Voice through separate provenance/alignment relations. External
-speech identity and physical storage key belong to the Voice Entity itself.
-`insertCaptionClip` creates a complete independent Caption placement;
-`upsertVoiceoverTake` accepts explicit `placement` for independent voice.
-AudioScript carries only text. `audio-script-marker` attaches directly assigned
-`segmentRanges` timing; those annotation Markers cannot be Clip display Markers.
-Caption styles belong to Caption; text can have a real inline text Asset rather
-than a fabricated Memota ID. Background Audio's Marker declares
+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
+with `assembleCaptionContent` or `assemblePhoneticScriptContent`. Broken composition
+fails explicitly. 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
+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.
+External speech identity and storage key stay on Voice.
+
+AudioScript has no intrinsic Sequence and cannot enter a Clip. `audio-script-marker`
+attaches directly assigned `segmentRanges` timing; annotation Markers never refer
+to upstream Markers and cannot be Clip display Markers. Moving or aligning a
+Caption changes its external display Marker, preserving intrinsic Caption extent.
+Caption owns its styles and text selection. Background Audio's Marker declares
 `durationPolicy: 'timeline'`: its source duration stays factual,
 while the view fills the non-BGM timeline duration.
 

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

@@ -1524,6 +1524,123 @@ function isRecord$1(value) {
 	return typeof value === "object" && value != null && !Array.isArray(value);
 }
 //#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.
+*/
+var ScriptCompositionError = class extends Error {
+	code;
+	entityId;
+	constructor(code, entityId, message) {
+		super(message);
+		this.code = code;
+		this.entityId = entityId;
+		this.name = "ScriptCompositionError";
+	}
+};
+function compositionRelationKind(variantKind) {
+	return variantKind === "caption" ? "caption-composition" : "phonetic-script-composition";
+}
+/**
+* Resolve the one AudioScript a variant composes. Relations are queried from
+* both endpoints, so persisted endpoint positions do not matter.
+*/
+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;
+}
+/** Join the whole AudioScript text in segment order. */
+function assembleScriptText(script) {
+	return scriptSegments(script).map((segment) => segment.text).join("");
+}
+function scriptSegments(script) {
+	const segments = script.payload.segments;
+	if (!Array.isArray(segments)) throw new ScriptCompositionError("composition_dangling", script.entityId, `AudioScript "${script.entityId}" requires segments`);
+	if (!segments.every(isScriptSegment) || new Set(segments.map((s) => s.segmentId)).size !== segments.length) throw new ScriptCompositionError("invalid_script", script.entityId, "AudioScript requires valid segments with unique local segmentId and text");
+	return segments;
+}
+function isScriptSegment(value) {
+	if (typeof value !== "object" || value == null || Array.isArray(value)) return false;
+	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.
+*/
+function assembleCaptionContent(rows, captionEntityId) {
+	const caption = requireEntityKind(rows, captionEntityId, "caption");
+	const script = findComposedAudioScript(rows, captionEntityId, "caption");
+	const segments = selectAudioScriptSegments(script, captionSelections(caption));
+	return {
+		caption,
+		audioScript: script,
+		segments,
+		text: segments.map((segment) => segment.text).join("")
+	};
+}
+/**
+* Assemble the complete Phonetic Script content for TTS: the composed
+* AudioScript's base text plus the variant's own phoneme and prosody fields.
+*/
+function assemblePhoneticScriptContent(rows, phoneticScriptEntityId) {
+	const phoneticScript = requireEntityKind(rows, phoneticScriptEntityId, "phonetic-script");
+	const audioScript = findComposedAudioScript(rows, phoneticScriptEntityId, "phonetic-script");
+	const segments = scriptSegments(audioScript);
+	return {
+		phoneticScript,
+		audioScript,
+		segments,
+		text: segments.map((segment) => segment.text).join("")
+	};
+}
+function captionSelections(caption) {
+	const selections = caption.payload.selections;
+	if (!Array.isArray(selections) || selections.length === 0) throw new ScriptCompositionError("empty_selection", caption.entityId, `Caption "${caption.entityId}" requires a non-empty segment selection into its AudioScript`);
+	if (!selections.every(isSegmentSelection)) throw new ScriptCompositionError("invalid_selection", caption.entityId, "Caption selections require a segmentId and optional textRange");
+	return selections;
+}
+function isSegmentSelection(value) {
+	return typeof value === "object" && value != null && !Array.isArray(value) && typeof value.segmentId === "string" && value.segmentId.trim() !== "" && Object.keys(value).every((key) => key === "segmentId" || key === "textRange");
+}
+/** Select source text without creating another authoritative text field. */
+function selectAudioScriptSegments(script, selections) {
+	if (!Array.isArray(selections) || selections.length === 0 || !selections.every(isSegmentSelection) || new Set(selections.map((s) => s.segmentId)).size !== selections.length) throw new ScriptCompositionError("invalid_selection", script.entityId, "Caption selections must be non-empty and name unique source segments");
+	const bySegmentId = new Map(scriptSegments(script).map((segment) => [segment.segmentId, segment]));
+	const selected = selections.map((selection) => {
+		const segment = bySegmentId.get(selection.segmentId);
+		if (segment === void 0) throw new ScriptCompositionError("unknown_segment", script.entityId, `Caption selection "${selection.segmentId}" does not name a segment of AudioScript "${script.entityId}"`);
+		if (selection.textRange === void 0) return segment;
+		const range = selection.textRange;
+		const points = Array.from(segment.text);
+		if (typeof range !== "object" || range === null || !Number.isSafeInteger(range.start) || !Number.isSafeInteger(range.end) || range.start < 0 || range.end <= range.start || range.end > points.length || Object.keys(range).some((key) => key !== "start" && key !== "end")) throw new ScriptCompositionError("invalid_selection", script.entityId, "Caption textRange must be a non-empty half-open Unicode code-point range within its source segment");
+		return {
+			...segment,
+			text: points.slice(range.start, range.end).join("")
+		};
+	});
+	if (!selected.map((segment) => segment.text).join("").trim()) throw new ScriptCompositionError("empty_selection", script.entityId, "Caption selection must contain visible source text");
+	return selected;
+}
+function requireEntityKind(rows, entityIdValue, entityKind) {
+	const entity = rows.entities.find((candidate) => candidate.entityId === entityIdValue);
+	if (entity === void 0) throw new ScriptCompositionError("composition_dangling", entityIdValue, `Entity "${entityIdValue}" does not exist`);
+	if (entity.entityKind !== entityKind) throw new ScriptCompositionError("composition_dangling", entityIdValue, `Entity "${entityIdValue}" must have kind "${entityKind}", got "${entity.entityKind}"`);
+	return entity;
+}
+//#endregion
 //#region ../medeo-dsl/src/ids.ts
 function createEntityId(value) {
 	return createId(value, "EntityId");
@@ -1539,8 +1656,9 @@ function createId(value, label) {
 //#region ../medeo-dsl/src/invariants.ts
 /**
 * Media variants own their Asset identity directly: a `physical-asset`
-* Relation may not bind them. Caption inline text (and other non-media
-* Sequence entities) keep their Asset binding.
+* Relation may not bind them. Caption text is composed domain content, so
+* Captions do not bind Physical Assets either; the Relation vocabulary stays
+* open for future physical pipeline semantics.
 */
 function validateMediaAssetIdentity(entity, index) {
 	return [...index.relationsOf(entity)].filter((relation) => relation.kind === "physical-asset").map(() => ({
@@ -1573,7 +1691,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(...validateCaptionAsset(entity, index));
+		if (current.entityKind === "caption") issues.push(...validateCaptionComposition(entity, index));
+		if (current.entityKind === "phonetic-script") issues.push(...validatePhoneticComposition(entity, index));
 		issues.push(...validateSequenceComposition(entity));
 	}
 	issues.push(...validateClipAnchorCycles(entities, index));
@@ -1676,25 +1795,63 @@ function validateAXVideoAdmission(axVideo, index) {
 		message: "AXVideo must have exactly one live AXVideo-Marker Relation"
 	}];
 }
-function validateCaptionAsset(caption, index) {
-	const assets = ofKind([...index.relationsOf(caption)], "physical-asset").map((relation) => relation.other(caption)?.deref()?.current()).filter((entity) => entity?.entityKind === "asset");
-	if (assets.length > 0) {
-		const captionText = caption.current().text;
-		if (!assets.some((asset) => {
-			const inline = asset.inline;
-			return isRecord(inline) && inline.mediaType === "text/plain" && inline.text !== captionText;
-		})) return [];
-		return [{
-			code: "caption_inline_asset_mismatch",
-			entityId: caption.entityId,
-			message: "Caption text must match the text/plain inline Physical Asset"
-		}];
+/**
+* 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");
+}
+/** 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 validateVariantComposition(variant, index, variantKind, compositionKind, issueCode) {
+	const relations = [...index.relationsOf(variant)];
+	const issues = [];
+	const physicalEdges = ofKind(relations, "physical-asset");
+	if (variantKind === "caption" && physicalEdges.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;
 	}
-	return [{
-		code: "caption_asset_required",
-		entityId: caption.entityId,
-		message: "Caption must have a Physical Asset Relation"
-	}];
+	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;
+	try {
+		selectAudioScriptSegments({
+			entityId: script.entityId,
+			entityKind: "audio-script",
+			payload: { segments: script.segments.map((segment) => ({ ...segment })) }
+		}, selections);
+	} catch (error) {
+		issues.push({
+			code: "caption_selection_invalid",
+			entityId: variant.entityId,
+			message: error instanceof Error ? error.message : "Invalid Caption selection"
+		});
+	}
+	return issues;
 }
 function validateClipPlacement(clip, index) {
 	const marker = ofKind([...index.relationsOf(clip)], "clip-marker")[0]?.other(clip)?.deref();
@@ -1822,6 +1979,18 @@ function validateKnownEntityPayload(entity) {
 	const value = entity;
 	const problems = [];
 	if (value.lifecycle !== void 0 && !isRecord(value.lifecycle)) problems.push("lifecycle must be an object when present");
+	if (entity.entityKind === "audio-script" || entity.entityKind === "phonetic-script") {
+		for (const key of [
+			"extent",
+			"sampling",
+			"coordinateSpace",
+			"sourceRange",
+			"targetRange",
+			"duration",
+			"startMs",
+			"endMs"
+		]) if (Object.hasOwn(value, key)) problems.push(`${key} is not intrinsic script data; assign an external annotation Marker`);
+	}
 	switch (entity.entityKind) {
 		case "track":
 			validateOptionalField(value, "hidden", "boolean", problems);
@@ -1848,9 +2017,11 @@ function validateKnownEntityPayload(entity) {
 			validateMarkerPayload(value, problems);
 			break;
 		case "audio-script":
-		case "phonetic-script":
 			validateScriptPayload(value, problems);
 			break;
+		case "phonetic-script":
+			validatePhoneticScriptPayload(value, problems);
+			break;
 		case "timeline":
 		case "viewport": break;
 		case "clip":
@@ -1914,24 +2085,18 @@ function validateSegmentRanges(value, problems) {
 function validateAssetPayload(value, problems) {
 	validateExternalLocator(value, problems);
 	validateStorageKey(value, problems);
-	const inline = value.inline;
-	if (inline !== void 0) if (!isRecord(inline)) problems.push("inline must be an object when present");
-	else {
-		if (inline.mediaType !== "text/plain") problems.push("inline.mediaType must be \"text/plain\"");
-		if (typeof inline.text !== "string") problems.push("inline.text must be a string");
-	}
-	if (value.external !== void 0 && value.inline !== void 0) problems.push("Asset must not combine external and inline physical locations");
+	if (value.inline !== void 0) problems.push("inline is not a physical location; text is domain content owned by its AudioScript");
 }
 /**
 * Media variants own their Asset locator directly: `external` is required and
-* inline text stays an Asset-kind-only value so the two physical-location
+* textual domain content is owned by AudioScript; the physical-location
 * vocabularies cannot mix.
 */
 function validateMediaAssetFields(value, problems) {
 	if (value.external === void 0) problems.push("external is required; media variants own their Asset identity");
 	else validateExternalLocator(value, problems);
 	validateStorageKey(value, problems);
-	if (value.inline !== void 0) problems.push("inline is an Asset-kind field; media variants use external");
+	if (value.inline !== void 0) problems.push("media variants use external locators, not inline domain text");
 }
 function validateExternalLocator(value, problems) {
 	const external = value.external;
@@ -1958,7 +2123,27 @@ 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 && typeof value.text !== "string") problems.push("text must be a string when present");
+	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 {
+		if (selections.length === 0) problems.push("selections must name at least one AudioScript segment");
+		const seen = /* @__PURE__ */ new Set();
+		for (const [index, selection] of selections.entries()) {
+			if (!isRecord(selection)) {
+				problems.push(`selections[${index}] must be an object`);
+				continue;
+			}
+			if (typeof selection.segmentId !== "string" || selection.segmentId.trim() === "") problems.push(`selections[${index}].segmentId must be a string`);
+			else if (seen.has(selection.segmentId)) problems.push(`selections[${index}].segmentId must be unique within the Caption`);
+			else seen.add(selection.segmentId);
+			if (Object.keys(selection).some((key) => key !== "segmentId" && key !== "textRange")) problems.push(`selections[${index}] may only contain segmentId and textRange`);
+			if (selection.textRange !== void 0) {
+				const range = selection.textRange;
+				if (!isRecord(range) || !Number.isSafeInteger(range.start) || !Number.isSafeInteger(range.end) || range.start < 0 || range.end <= range.start || Object.keys(range).some((key) => key !== "start" && key !== "end")) problems.push(`selections[${index}].textRange must be a non-empty half-open code-point range`);
+			}
+		}
+	}
 	const style = value.style;
 	if (style === void 0) return;
 	if (!isRecord(style)) {
@@ -1993,6 +2178,13 @@ function validateRange(value, path, required, problems) {
 	if (!Object.hasOwn(value, "start") || value.start === void 0) problems.push(`${path}.start is required`);
 	if (!Object.hasOwn(value, "end") || value.end === void 0) problems.push(`${path}.end is required`);
 }
+/** 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.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");
+}
 function validateScriptPayload(value, problems) {
 	if (!Array.isArray(value.segments)) {
 		problems.push("segments must be an array");
@@ -2071,16 +2263,17 @@ function isOwnedLocalEntityValuePath(entityKind, path) {
 	].includes(entityKind) && /^(?:sampling|coordinateSpace|coordinateSpace\.unit|extent\.kind)$/.test(path)) return true;
 	if (entityKind === "sequence-marker" && /^(?:durationPolicy|duration\.mode|timeRemapping\.(?:kind|mode))$/.test(path)) return true;
 	if (entityKind === "sequence-marker" && /^segmentRanges\[\d+\]\.segmentId$/.test(path)) return true;
-	if (entityKind === "asset" && /^(?:external\.(?:system|key)|storageKey|inline\.(?:mediaType|text))$/.test(path)) return true;
+	if (entityKind === "asset" && /^(?:external\.(?:system|key)|storageKey)$/.test(path)) return true;
 	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 === "text" || path.startsWith("style."))) return true;
-	if ((entityKind === "audio-script" || entityKind === "phonetic-script") && /^segments\[\d+\]\.(?:segmentId|text|language)$/.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;
 	return false;
 }
 function isOwnedLocalIdPath(entityKind, path) {
 	if (path === "lifecycle.actorId") return true;
-	if ((entityKind === "audio-script" || entityKind === "phonetic-script") && /^segments\[\d+\]\.segmentId$/.test(path)) return true;
+	if (entityKind === "audio-script" && /^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;
 	return false;
@@ -2187,8 +2380,15 @@ const generatedRelationSpec = Object.freeze({
 	validateEndpoints: (endpoints) => endpoints.every((endpoint) => isGeneratedMedia(endpoint.current())),
 	validateMetadata: isEmptyMetadata
 });
-const phoneticScriptProvenanceRelationSpec = metadataSpec("phonetic-script-provenance", "phonetic-script", "audio-script", isSegmentAlignmentMetadata);
-const captionProvenanceRelationSpec = metadataSpec("caption-provenance", "caption", "audio-script", isSegmentAlignmentMetadata);
+/**
+* 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"])),
@@ -2200,19 +2400,20 @@ const clipAnchorRelationSpec = Object.freeze({
 	validateEndpoints: (endpoints) => endpoints[0].current().entityKind === "clip" && endpoints[1].current().entityKind === "clip",
 	validateMetadata: isEmptyMetadata
 });
-/** `audio-script-render(output, script)` means endpoint 0 was rendered from endpoint 1. */
-const audioScriptRenderRelationSpec = Object.freeze({
-	kind: "audio-script-render",
-	validateEndpoints: (endpoints) => {
-		const outputKind = endpoints[0].current().entityKind;
-		return (outputKind === "audio" || outputKind === "voice") && endpoints[1].current().entityKind === "audio-script";
-	},
+/** Voice is generated from PhoneticScript; kinds determine roles regardless of endpoint positions. */
+const phoneticScriptRenderRelationSpec = Object.freeze({
+	kind: "phonetic-script-render",
+	validateEndpoints: (endpoints) => hasKinds(endpoints, new Set(["voice"]), new Set(["phonetic-script"])),
 	validateMetadata: isEmptyMetadata
 });
-/** `audio-script-source(script, source)` means endpoint 0 was transcribed from endpoint 1. */
+/** AudioScript was transcribed from Audio, Video, or recorded Voice; kinds determine roles. */
 const audioScriptSourceRelationSpec = Object.freeze({
 	kind: "audio-script-source",
-	validateEndpoints: (endpoints) => hasKinds(endpoints, new Set(["audio-script"]), new Set(["audio", "video"])),
+	validateEndpoints: (endpoints) => hasKinds(endpoints, new Set(["audio-script"]), new Set([
+		"audio",
+		"video",
+		"voice"
+	])),
 	validateMetadata: isEmptyMetadata
 });
 /**
@@ -2236,11 +2437,11 @@ const builtInRelationSpecs = Object.freeze([
 	markerTimelineRelationSpec,
 	physicalAssetRelationSpec,
 	generatedRelationSpec,
-	phoneticScriptProvenanceRelationSpec,
-	captionProvenanceRelationSpec,
+	phoneticScriptCompositionRelationSpec,
+	captionCompositionRelationSpec,
 	captionAlignmentRelationSpec,
 	clipAnchorRelationSpec,
-	audioScriptRenderRelationSpec,
+	phoneticScriptRenderRelationSpec,
 	audioScriptSourceRelationSpec,
 	audioScriptMarkerRelationSpec
 ]);
@@ -2339,7 +2540,7 @@ var BiRelationIndex = class {
 	byRelationId = /* @__PURE__ */ new Map();
 	link(input) {
 		if (input.spec.kind === "generated") throw new Error("Author generated Relations with linkGenerated({ output, input })");
-		if (input.spec.kind === "clip-anchor" || input.spec.kind === "audio-script-render" || input.spec.kind === "audio-script-source") throw new Error(`Author ordered ${input.spec.kind} Relations with the dedicated role-named method`);
+		if (input.spec.kind === "clip-anchor" || input.spec.kind === "phonetic-script-render" || input.spec.kind === "audio-script-source") throw new Error(`Author ordered ${input.spec.kind} Relations with the dedicated role-named method`);
 		return this.linkValidated(input);
 	}
 	/** Author `generated(output, input)` without exposing positional arguments. */
@@ -2362,12 +2563,12 @@ var BiRelationIndex = class {
 			trace: input.trace
 		});
 	}
-	/** Author `audio-script-render(output, script)` without exposing positional arguments. */
-	linkAudioScriptRender(input) {
+	/** Author `phonetic-script-render(output, phoneticScript)` without exposing positional arguments. */
+	linkPhoneticScriptRender(input) {
 		return this.linkValidated({
 			relationId: input.relationId,
-			spec: audioScriptRenderRelationSpec,
-			endpoints: [input.output, input.script],
+			spec: phoneticScriptRenderRelationSpec,
+			endpoints: [input.output, input.phoneticScript],
 			metadata: {},
 			trace: input.trace
 		});
@@ -2860,7 +3061,7 @@ function projectEntityTimeline(rows, meta) {
 			const asset = mediaAssetFacts(graph, content);
 			requireUntrimmedAudio(content, marker, placement);
 			const external = externalLocator(asset, "memota-speech");
-			const script = graph.one(content.entityId, "audio-script-render", "audio-script");
+			const assembled = graph.adjacent(content.entityId, "phonetic-script-render").length > 0 || content.payload.voice !== void 0 ? assemblePhoneticScriptContent(rows, graph.one(content.entityId, "phonetic-script-render", "phonetic-script").entityId) : void 0;
 			const voice = content.payload.voice;
 			if (voice !== void 0 && (!object(voice) || voice.system !== "voice-library" || typeof voice.key !== "string")) fail("Voice must use an explicit voice-library locator");
 			const captionIds = layout.tracks.flatMap((candidate) => candidate.role === "caption" ? candidate.clips.filter((caption) => caption.anchorClipEntityId === clip.entityId).map((caption) => caption.clipEntityId) : []);
@@ -2870,7 +3071,7 @@ function projectEntityTimeline(rows, meta) {
 				media_duration_ms: placement.duration,
 				audio_storage_key: storageKey(asset),
 				origin_speech_id: external.key,
-				audio_script: scriptText(script),
+				audio_script: assembled?.text ?? (graph.adjacent(content.entityId, "audio-script-source").length > 0 ? assembleScriptText(graph.one(content.entityId, "audio-script-source", "audio-script")) : ""),
 				volume: volume.data,
 				voice: object(voice) ? {
 					id: typeof voice.key === "string" ? voice.key : void 0,
@@ -2879,12 +3080,7 @@ function projectEntityTimeline(rows, meta) {
 				caption_ids: captionIds
 			} };
 		} else if (track.role === "caption") {
-			const text = content.payload.text;
-			if (typeof text !== "string") fail("Caption " + content.entityId + " requires its text");
-			const asset = graph.one(content.entityId, "physical-asset", "asset");
-			const inline = asset.payload.inline;
-			if (inline !== void 0 && (!object(inline) || inline.mediaType !== "text/plain" || inline.text !== text)) fail("Inline Caption Asset and Caption text must agree");
-			if (inline === void 0 && !object(asset.payload.external)) fail("Caption Asset must identify physical text or contain actual inline text");
+			const text = assembleCaptionContent(rows, content.entityId).text;
 			if (marker.payload.timeRemapping !== void 0) fail("Caption timeRemapping is not supported by this reader");
 			const style = captionStyle(content.payload.style);
 			const anchor = placement.anchorClipEntityId === void 0 ? void 0 : layout.clips.get(placement.anchorClipEntityId);
@@ -2972,14 +3168,6 @@ function storageKey(asset) {
 	if (typeof asset.payload.storageKey !== "string" || asset.payload.storageKey.trim() === "") fail("Asset " + asset.entityId + " requires its factual storageKey");
 	return asset.payload.storageKey;
 }
-function scriptText(script) {
-	const segments = script.payload.segments;
-	if (!Array.isArray(segments)) fail("AudioScript requires segments");
-	return segments.map((segment) => {
-		if (!object(segment) || typeof segment.text !== "string") fail("AudioScript segment requires text");
-		return segment.text;
-	}).join("");
-}
 function captionStyle(value) {
 	if (value === void 0) return void 0;
 	if (!object(value)) fail("Caption style must be an object");
@@ -3351,4 +3539,4 @@ function createPlainMemoryAdapter(document, options) {
 	return new PlainMemoryAdapter(document, options);
 }
 //#endregion
-export { videoDocumentMirrorSchema as $, ensureLaneTrack as A, resolveSpeechOverlapByShiftingVideos as B, toVideoDocument as C, partUnionSchema as D, validateVideoDocument as E, arrangeMainTrackSeamlessly as F, safeDurationMs as G, TIMELINE_SKELETON_DURATION_MS as H, fillMainTrackTimeGaps as I, VIDEO_DOCUMENT_SCHEMA_VERSION as J, DEFAULT_UNIT_TIME_MS as K, reassignSpeechesToVideoClipsByTime as L, laneTrackId as M, solveVideoDocument as N, videoDocumentSchema as O, cascadeAfterVideoClipChanges as P, recordEntries as Q, recalculateTimelineDuration as R, fromVideoDocument as S, assertValidVideoDocument as T, isEmptyVideoClip as U, syncAggregatedClipsTimePosition as V, partDurationMs as W, speedOf as X, effectiveVideoClipDurationMs as Y, partUnionToDraft as Z, hasSequence as _, applyEntityTimelineProjection as a, buildSpeechHostMap as b, writeVideoDocumentToDraft as c, resolveEntityTimelineLayout as d, base64ToBytes as et, EntityTimelineProjectionError as f, createRelationId as g, createEntityId as h, MirrorVideoDocumentAdapter as i, findLaneTrack as j, LANE_KINDS_IN_STACK_ORDER as k, readVideoDocumentFromDraft as l, isJsonObject as m, createPlainMemoryAdapter as n, createMirrorVideoDocument as o, decodeEntityRelationRows as p, ENTITY_TIMELINE_PROJECTION_SCHEMA_VERSION as q, generatePartId as r, createMirrorVideoDocumentAdapter as s, PlainMemoryAdapter as t, bytesToBase64 as tt, projectEntityTimeline as u, isMediaAssetVariantKind as v, VideoDocumentValidationError as w, derivePositionFromAbs as x, buildInitialVideoDocument as y, resolveAllSpeechOverlaps as z };
+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 };

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

@@ -849,6 +849,13 @@ type RelationId = string & {
   readonly [relationIdBrand]: 'RelationId';
 };
 //#endregion
+//#region ../medeo-dsl/src/json-values.d.ts
+type JsonPrimitive = string | number | boolean | null;
+type JsonValue = JsonPrimitive | JsonObject | readonly JsonValue[];
+type JsonObject = {
+  readonly [key: string]: JsonValue;
+};
+//#endregion
 //#region ../medeo-dsl/src/entities.d.ts
 type KnownEntityKind = 'axvideo' | 'timeline' | 'track' | 'clip' | 'asset' | 'video' | 'audio' | 'voice' | 'image' | 'sequence-marker' | 'viewport' | 'audio-script' | 'phonetic-script' | 'caption';
 declare const extensionEntityKindBrand: unique symbol;
@@ -867,6 +874,11 @@ type SequenceDuration<Span = unknown> = {
   readonly mode: 'fixed';
   readonly value: Span;
 };
+interface ScriptTextSegment {
+  readonly segmentId: string;
+  readonly text: string;
+  readonly language?: string;
+}
 interface VoiceDescriptor {
   readonly system: 'voice-library';
   readonly key: string;
@@ -888,16 +900,31 @@ interface CaptionStyleFields {
   readonly positionX?: number;
   readonly positionY?: number;
 }
-//#endregion
-//#region ../medeo-dsl/src/json-values.d.ts
-type JsonPrimitive = string | number | boolean | null;
-type JsonValue = JsonPrimitive | JsonObject | readonly JsonValue[];
-type JsonObject = {
-  readonly [key: string]: JsonValue;
+/**
+ * Half-open `[start, end)` position window inside one Segment's text, counted
+ * in Unicode code points (not UTF-16 code units), so a boundary never splits a
+ * surrogate pair. Positions are non-negative safe integers with `start < end`;
+ * `end` must not exceed the Segment's code-point length.
+ */
+interface CaptionTextRange extends JsonObject {
+  readonly start: number;
+  readonly end: number;
+}
+/**
+ * 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.
+ * The optional `textRange` narrows one Segment to an intra-Segment sub-span
+ * (intra-segment re-segmentation); without it the whole Segment text is selected.
+ */
+type CaptionSegmentSelection = JsonObject & {
+  readonly segmentId: string;
+  readonly textRange?: CaptionTextRange;
 };
 //#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-provenance' | 'caption-provenance' | 'caption-alignment' | 'clip-anchor' | 'audio-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' | 'phonetic-script-composition' | 'caption-composition' | 'caption-alignment' | 'clip-anchor' | 'phonetic-script-render' | 'audio-script-source' | 'audio-script-marker';
 type RelationKind = KnownRelationKind | (string & {});
 type RelationTrace = JsonObject;
 /**
@@ -1655,10 +1682,10 @@ declare const videoDocumentSchema: z.ZodObject<{
   tracks: z.ZodOptional<z.ZodArray<z.ZodObject<{
     id: z.ZodOptional<z.ZodString>;
     parts_kind: z.ZodOptional<z.ZodEnum<{
+      video_clip: "video_clip";
       speech: "speech";
       caption: "caption";
       bgm: "bgm";
-      video_clip: "video_clip";
     }>>;
     is_hidden: z.ZodOptional<z.ZodBoolean>;
     items: z.ZodOptional<z.ZodArray<z.ZodObject<{
@@ -1740,4 +1767,4 @@ declare const videoDocumentSchema: z.ZodObject<{
   }, z.core.$loose>]>>>;
 }, z.core.$loose>;
 //#endregion
-export { VoiceDescriptor as $, generatePartId as A, Attachment as At, ResolvedEntityClipPlacement as B, PlannedSemanticOpKind as C, VideoDocumentSchemaVersion as Ct, SnapshotReadable as D, VideoDraftPartUnion as Dt, SchemaValidator as E, VideoDraft as Et, videoDocumentMirrorSchema as F, Timeline$1 as Ft, EntityTimelineProjectionError as G, ResolvedEntityTrack as H, VideoDocumentValidationError as I, Track$1 as It, JsonObject as J, EntityRelationRows as K, assertValidVideoDocument as L, TrackItem$1 as Lt, TrackItemDraft as M, CaptionStyle as Mt, VideoDocumentDraft as N, PartAggregation as Nt, ValidationError as O, effectiveVideoClipDurationMs as Ot, VideoDocumentMirrorSchema as P, SpeedShift as Pt, SequenceRange as Q, validateVideoDocument as R, ImplementedSemanticOpKind as S, VideoDocument as St, isImplementedSemanticOpKind as T, VideoDocumentValidationIssueCode as Tt, resolveEntityTimelineLayout as U, ResolvedEntityTimelineLayout as V, projectEntityTimeline as W, CaptionStyleFields as X, JsonValue as Y, SequenceDuration as Z, SemanticEditor as _, Track as _t, PlainMemoryAdapter as a, buildSpeechHostMap as at, TransactAudit as b, VIDEO_DOCUMENT_SCHEMA_VERSION as bt, MirrorVideoDocumentAdapter as c, toVideoDocument as ct, createMirrorVideoDocument as d, DEFAULT_UNIT_TIME_MS as dt, EntityId as et, createMirrorVideoDocumentAdapter as f, ENTITY_TIMELINE_PROJECTION_SCHEMA_VERSION as ft, SemanticDocumentAdapter as g, Timeline as gt, OpActor as h, SpeechPart as ht, JournalEntry as i, SpeechHostMap as it, TrackDraft as j, CaptionPart$1 as jt, PartIdFactory as k, speedOf as kt, MirrorVideoDocumentOptions as l, BgmPart as lt, CommitOptions as m, PartUnion as mt, videoDocumentSchema as n, buildInitialVideoDocument as nt, PlainMemoryAdapterOptions as o, derivePositionFromAbs as ot, writeVideoDocumentToDraft as p, PartKind as pt, EntityRow as q, readVideoDocumentFromDraft as r, DerivedItemPosition as rt, createPlainMemoryAdapter as s, fromVideoDocument as st, partUnionSchema as t, InitialDocumentFacts as tt, applyEntityTimelineProjection as u, CaptionPart as ut, SemanticOpInput as v, TrackItem as vt, SemanticOpKind as w, VideoDocumentValidationIssue as wt, IMPLEMENTED_SEMANTIC_OP_KINDS as x, VideoClipPart as xt, SemanticOpName as y, TrackItemTimePosition as yt, EntityTimelineTrackRole as z };
+export { VoiceDescriptor as $, generatePartId as A, effectiveVideoClipDurationMs as At, ResolvedEntityClipPlacement as B, PlannedSemanticOpKind as C, VideoClipPart as Ct, SnapshotReadable as D, VideoDocumentValidationIssueCode as Dt, SchemaValidator as E, VideoDocumentValidationIssue as Et, videoDocumentMirrorSchema as F, PartAggregation as Ft, EntityTimelineProjectionError as G, ResolvedEntityTrack as H, VideoDocumentValidationError as I, SpeedShift as It, CaptionSegmentSelection as J, EntityRelationRows as K, assertValidVideoDocument as L, Timeline$1 as Lt, TrackItemDraft as M, Attachment as Mt, VideoDocumentDraft as N, CaptionPart$1 as Nt, ValidationError as O, VideoDraft as Ot, VideoDocumentMirrorSchema as P, CaptionStyle as Pt, SequenceRange as Q, validateVideoDocument as R, Track$1 as Rt, ImplementedSemanticOpKind as S, VIDEO_DOCUMENT_SCHEMA_VERSION as St, isImplementedSemanticOpKind as T, VideoDocumentSchemaVersion as Tt, resolveEntityTimelineLayout as U, ResolvedEntityTimelineLayout as V, projectEntityTimeline as W, ScriptTextSegment as X, CaptionStyleFields as Y, SequenceDuration as Z, SemanticEditor as _, SpeechPart as _t, PlainMemoryAdapter as a, DerivedItemPosition as at, TransactAudit as b, TrackItem as bt, MirrorVideoDocumentAdapter as c, derivePositionFromAbs as ct, createMirrorVideoDocument as d, BgmPart as dt, JsonObject as et, createMirrorVideoDocumentAdapter as f, CaptionPart as ft, SemanticDocumentAdapter as g, PartUnion as gt, OpActor as h, PartKind as ht, JournalEntry as i, buildInitialVideoDocument as it, TrackDraft as j, speedOf as jt, PartIdFactory as k, VideoDraftPartUnion as kt, MirrorVideoDocumentOptions as l, fromVideoDocument as lt, CommitOptions as m, ENTITY_TIMELINE_PROJECTION_SCHEMA_VERSION as mt, videoDocumentSchema as n, EntityId as nt, PlainMemoryAdapterOptions as o, SpeechHostMap as ot, writeVideoDocumentToDraft as p, DEFAULT_UNIT_TIME_MS as pt, EntityRow as q, readVideoDocumentFromDraft as r, InitialDocumentFacts as rt, createPlainMemoryAdapter as s, buildSpeechHostMap as st, partUnionSchema as t, JsonValue as tt, applyEntityTimelineProjection as u, toVideoDocument as ut, SemanticOpInput as v, Timeline as vt, SemanticOpKind as w, VideoDocument as wt, IMPLEMENTED_SEMANTIC_OP_KINDS as x, TrackItemTimePosition as xt, SemanticOpName as y, Track as yt, EntityTimelineTrackRole as z, TrackItem$1 as zt };