@mengine/medeo-client 3.1.0 → 3.1.1-dsl.0

package/dist/{dsl-C0-G8JVT.js → dsl-Xm5NW58k.js}

@@ -145,8 +145,12 @@ function assertCaptionContent(value) {
 }
 const phonemeFields = {
 	...selectionFields,
-	phonemeScript: optional$1(string)
+	phonemeScript: optional$1(nonempty)
 };
+/** D190: omitted pronunciation uses the selected source words; an authored pronunciation is never empty. */
+function assertPhonemeScript(value) {
+	if (value !== void 0 && !nonempty(value)) throw new Error("phonemeScript must be nonempty when provided");
+}
 function assertPhoneme(value) {
 	if (!segmentSelection(phonemeFields)(value)) throw new Error("Invalid phoneme");
 }
@@ -174,7 +178,7 @@ const locator = {
 };
 /**
 * A placeholder medium is an Image with no file, standing in where a legacy VideoDraft placed a
-* visual clip the old editor drew as a blank (D196). The blank one stands in for a clip placed
+* visual clip the old editor drew as a blank (D205). The blank one stands in for a clip placed
 * without media (`origin_media_id: ''`); one keyed by a memota media id stands in for media the
 * clip named but Director found missing, so the id survives. Importing keeps the clips' time on
 * them instead of dropping them. Only migration authors them.
@@ -608,9 +612,10 @@ function assertPhonemeSelection(rows, selection, text) {
 	assertSegmentRange(selection, text);
 	if (selection.phonemeScript !== void 0 && typeof selection.phonemeScript !== "string") throw new Error("phonemeScript is a string");
 }
-/** A caption's text comes from a selection of a script or from its own text, never both. */
+/** Every new or rewritten Caption selects its words from one AudioScript segment. */
 function assertCaptionSource(caption, selected) {
-	if (caption?.text !== void 0 && selected) throw new Error("Caption must have only one content source");
+	if (!selected) throw new Error("Caption must select a segment of an AudioScript");
+	if (caption?.text !== void 0) throw new Error("Caption must have only one content source");
 }
 //#endregion
 //#region ../medeo-dsl/src/contain.ts
@@ -670,6 +675,63 @@ function assertContainTree(rows, tree) {
 	}
 }
 //#endregion
+//#region ../medeo-dsl/src/clip-playback.ts
+const playable = {
+	video_clip: ["video", "image"],
+	speech: ["audio", "voiceover-recording"],
+	caption: ["caption"],
+	bgm: ["audio"]
+};
+function supportsClipSpeed(source) {
+	return isRecord(source) && [
+		"video",
+		"audio",
+		"voiceover-recording"
+	].includes(String(source.kind));
+}
+/** Content-kind admission is shared by Actions, script compilation and the final transaction. */
+function assertClipSourceRole(role, kind) {
+	if (!playable[role]?.includes(kind)) throw new Error(`A ${role} Track does not play ${kind}`);
+}
+function assertClipWindow(window, duration) {
+	if (!Number.isSafeInteger(window.inMs) || !Number.isSafeInteger(window.outMs) || window.inMs < 0 || window.outMs <= window.inMs) throw new Error("Invalid Clip window");
+	if (duration !== void 0 && window.outMs > duration) throw new Error(`Invalid Clip window: ${window.outMs}ms is past its content's ${duration}ms`);
+}
+/** Check authored playback facts; a remote merge is still read by projection with diagnostics. */
+function assertClipPlayback(clip, source, role) {
+	if (!isRecord(source)) throw new Error("Invalid Clip source");
+	const kind = source.kind ?? "caption";
+	const marker = clip.seqMarker;
+	assertSeqMarker(marker);
+	if (marker.outMs <= marker.inMs) throw new Error("Clip window must be nonempty");
+	if (role !== void 0) assertClipSourceRole(role, kind);
+	if (marker.rate !== void 0 && !supportsClipSpeed(source)) throw new Error("Only video and sound change speed");
+	const duration = typeof source.durationMs === "number" ? source.durationMs : void 0;
+	if (marker.fillTimeline) {
+		if (kind !== "audio") throw new Error("Only BGM audio fills the Timeline");
+		if (marker.inMs !== 0 || marker.rate !== void 0 && marker.rate !== 1 || marker.outMs !== duration) throw new Error(`A Clip that fills the Timeline plays its whole source at 1×: inMs 0, outMs ${duration ?? "its length"}, no rate; the Timeline's end cuts it`);
+	}
+	assertClipWindow(marker);
+}
+function clipParents(tree) {
+	const result = /* @__PURE__ */ new Map();
+	for (const track of tree) for (const clip of track.children ?? []) result.set(clip.entityId, track.entityId);
+	return result;
+}
+/** A new parent or Track role revalidates that binding, without blocking unrelated merged rows. */
+function assertClipPlacements(before, after, previousTree, nextTree) {
+	const previous = clipParents(previousTree);
+	for (const [id, parent] of clipParents(nextTree)) {
+		const track = after["track-entities"][parent];
+		const previousTrack = before["track-entities"][parent];
+		if (previous.get(id) === parent && (track === void 0 || isRecord(track) && isRecord(previousTrack) && previousTrack.role === track.role)) continue;
+		const role = requireEntity(after, "track-entities", parent).role;
+		const clip = after["clip-entities"][id];
+		if (!clip) continue;
+		assertClipPlayback(clip, after["media-entities"][clip.source] ?? after["caption-entities"][clip.source], role);
+	}
+}
+//#endregion
 //#region ../medeo-dsl/src/plan.ts
 /** Include removed nested keys: a partial merge alone would conceal a deleted required field. */
 function replacementPatch(before, after) {
@@ -685,6 +747,7 @@ function replacementPatch(before, after) {
 */
 function assertChangeAdmitted(change) {
 	const { before, after } = change;
+	const parents = change.containment ? clipParents(change.containment.after) : void 0;
 	for (const [table, rows] of change.entities) for (const [id, fields] of rows) {
 		const value = after[table][id];
 		if (value === void 0) continue;
@@ -699,25 +762,17 @@ function assertChangeAdmitted(change) {
 		}
 		const row = value;
 		for (const field of referenceFields[table] ?? []) if (!old || fields.has(field)) assertReferenceAdmitted(after, table, id, field, row[field]);
-		const marker = row.seqMarker;
-		if (table === "clip-entities" && (!old || fields.has("seqMarker")) && marker?.outMs <= marker?.inMs) throw new Error("Clip window must be nonempty");
-		if (table === "clip-entities" && (!old || fields.has("seqMarker") || fields.has("source"))) assertFillsWithWholeSource(after, marker, row.source);
+		if (table === "clip-entities" && (!old || fields.has("seqMarker") || fields.has("source"))) {
+			const parent = parents?.get(id);
+			assertClipPlayback(row, after["media-entities"][row.source] ?? after["caption-entities"][row.source], parent === void 0 ? void 0 : requireEntity(after, "track-entities", parent).role);
+		}
 	}
 	if (change.entities.has("timeline-entities") && Object.keys(after["timeline-entities"]).length > 1) throw new Error("Document already has a Timeline");
 	for (const [table, ids] of change.relations) for (const id of ids) {
 		const value = after[table][id];
 		if (value !== void 0) assertRelationAdmitted(after, table, id, value);
 	}
-}
-/**
-* A Clip that fills the Timeline plays its whole source at 1×: the player loops a short source and
-* cuts a long one at the Timeline's end (RFC 02 §3.3), so a window or speed of its own has no meaning.
-*/
-function assertFillsWithWholeSource(rows, marker, source) {
-	if (marker?.fillTimeline !== true) return;
-	const media = typeof source === "string" ? rows["media-entities"][source] : void 0;
-	const durationMs = typeof media?.durationMs === "number" ? media.durationMs : void 0;
-	if (marker.inMs !== 0 || marker.rate !== void 0 && marker.rate !== 1 || durationMs !== void 0 && marker.outMs !== durationMs) throw new Error(`A Clip that fills the Timeline plays its whole source at 1×: inMs 0, outMs ${durationMs ?? "its length"}, no rate; the Timeline's end cuts it`);
+	if (change.containment) assertClipPlacements(before, after, change.containment.before, change.containment.after);
 }
 //#endregion
 //#region src/dsl/projection/types.ts
@@ -953,15 +1008,11 @@ function requireSource(s, id, role) {
 	return media;
 }
 function assertMediaRole(media, role) {
-	if (!media || !{
-		video_clip: ["video", "image"],
-		speech: ["audio", "voiceover-recording"],
-		bgm: ["audio"],
-		caption: []
-	}[role].includes(media.kind)) throw new Error(`Source is not allowed on ${role} Track`);
+	if (!media) throw new Error(`Missing source for ${role} Track`);
+	assertClipSourceRole(role, media.kind);
 }
 function validateWindow(window, duration) {
-	if (!Number.isSafeInteger(window.inMs) || !Number.isSafeInteger(window.outMs) || window.inMs < 0 || window.outMs <= window.inMs || duration !== void 0 && window.outMs > duration) throw new Error("Invalid Clip window");
+	assertClipWindow(window, duration);
 }
 function trackOf(s, id) {
 	requireClip(s, id);
@@ -1249,7 +1300,8 @@ function replaceSourcePlan(s, clipId, input) {
 		patch: {
 			seqMarker: {
 				inMs: input.inMs,
-				outMs: input.outMs
+				outMs: input.outMs,
+				...supportsClipSpeed(source.source) ? {} : { rate: void 0 }
 			},
 			source: source.id
 		}
@@ -5877,6 +5929,30 @@ const phonemeCodec = codec((v) => {
 	assertPhoneme(value);
 	return value;
 });
+/** A row-owned binding couples the selection, pronunciation and its immutable file in one LWW value. */
+const phoneticBindingCodec = codec((value) => {
+	assertEntity("phonetic-script-entities", value);
+	assertPhoneticScript(void 0, { ...value });
+	return JSON.stringify({
+		phoneme: JSON.parse(phonemeCodec.encode(value.phoneme)),
+		system: value.system,
+		key: value.key,
+		storageKey: value.storageKey,
+		digest: value.digest
+	});
+}, (raw) => {
+	const value = JSON.parse(raw);
+	if (!isRecord(value)) throw new Error("Expected a PhoneticScript binding");
+	const phoneme = phonemeCodec.decode(JSON.stringify(value.phoneme));
+	if (isInvalidAtomic(phoneme)) throw new Error(phoneme.reason);
+	const binding = {
+		...value,
+		phoneme
+	};
+	assertEntity("phonetic-script-entities", binding);
+	assertPhoneticScript(void 0, binding);
+	return binding;
+});
 /** A Clip's sequence marker is stored as one string, so it is taken or replaced whole. */
 const seqMarkerCodec = codec((v) => {
 	assertSeqMarker(v);
@@ -5943,13 +6019,7 @@ const medeoDslLoroShape = schema({
 		storageKey: schema.String(optional),
 		digest: schema.String(optional)
 	})),
-	"phonetic-script-entities": schema.LoroMapRecord(schema.LoroMap({
-		phoneme: atomicValue(phonemeCodec),
-		system: schema.String(optional),
-		key: schema.String(optional),
-		storageKey: schema.String(optional),
-		digest: schema.String(optional)
-	})),
+	"phonetic-script-entities": schema.LoroMapRecord(schema.LoroMap({ binding: atomicValue(phoneticBindingCodec) })),
 	"caption-entities": schema.LoroMapRecord(schema.LoroMap({
 		selection: optionalAtomicValue(captionContentCodec),
 		text: schema.LoroText(optional),
@@ -6001,20 +6071,78 @@ function documentFormat(doc) {
 }
 var UnsupportedDocumentFormatError = class extends Error {
 	code = "unsupported_document_format";
-	constructor() {
-		super("Expected a new DSL document; legacy, mixed or uninitialized content is not supported");
+	constructor(message = "Expected a new DSL document; legacy, mixed or uninitialized content is not supported") {
+		super(message);
 		this.name = "UnsupportedDocumentFormatError";
 	}
 };
 /** Run after initial import, before opening an editable handle. Empty new documents still have one Timeline. */
 function assertDslDocument(doc) {
 	if (documentFormat(doc) !== "dsl" || doc.getMap("timeline-entities").keys().length !== 1) throw new UnsupportedDocumentFormatError();
+	assertPhoneticBindingFormat(doc);
+}
+/** This storage cutover has no field-per-fact reader or mixed-version write path. */
+function assertPhoneticBindingFormat(doc) {
+	if (!Object.hasOwn(doc.getShallowValue(), "phonetic-script-entities")) return;
+	const table = doc.getMap("phonetic-script-entities");
+	for (const id of table.keys()) {
+		const row = table.get(id);
+		if (!isContainer(row) || row.kind() !== "Map" || row.keys().some((key) => key !== "binding") || typeof row.get("binding") !== "string") throw new UnsupportedDocumentFormatError("PhoneticScript storage requires one atomic binding; old DSL documents need explicit migration");
+	}
 }
 //#endregion
 //#region ../medeo-dsl/src/schema/text-styles.ts
 /** How rich-text marks extend at their edges: a language runs on into text typed after it. */
 const textStyles = { language: { expand: "after" } };
 //#endregion
+//#region src/dsl/document/phonetic-binding.ts
+/**
+* Actions and the transaction guard keep their domain-shaped rows. The native schema stores
+* a PhoneticScript's facts under one binding; this lens applies draft edits to that single value.
+* It never reads the retired field-per-fact representation.
+*/
+function logicalDslState(native) {
+	const phonetics = new Proxy({}, {
+		get: (_target, key) => typeof key === "string" ? native["phonetic-script-entities"]?.[key]?.binding : void 0,
+		set: (_target, key, value) => {
+			if (typeof key !== "string") throw new Error("Invalid PhoneticScript key");
+			native["phonetic-script-entities"] ??= {};
+			const existing = native["phonetic-script-entities"][key];
+			if (existing) existing.binding = value;
+			else native["phonetic-script-entities"][key] = { binding: value };
+			return true;
+		},
+		deleteProperty: (_target, key) => {
+			if (typeof key === "string") delete native["phonetic-script-entities"][key];
+			return true;
+		},
+		ownKeys: () => Object.keys(native["phonetic-script-entities"] ?? {}),
+		has: (_target, key) => typeof key === "string" && Object.hasOwn(native["phonetic-script-entities"] ?? {}, key),
+		getOwnPropertyDescriptor: (_target, key) => typeof key === "string" && Object.hasOwn(native["phonetic-script-entities"] ?? {}, key) ? {
+			configurable: true,
+			enumerable: true,
+			writable: true,
+			value: native["phonetic-script-entities"][key].binding
+		} : void 0
+	});
+	const view = {};
+	for (const key of new Set([
+		...Object.keys(native),
+		...entityTables,
+		...relationTables,
+		"contain-relations"
+	])) Object.defineProperty(view, key, {
+		configurable: true,
+		enumerable: true,
+		get: () => key === "phonetic-script-entities" ? phonetics : Reflect.get(native, key),
+		set: (value) => {
+			if (key === "phonetic-script-entities") throw new Error("Cannot replace the PhoneticScript table");
+			Reflect.set(native, key, value);
+		}
+	});
+	return view;
+}
+//#endregion
 //#region src/dsl/document/read.ts
 /** Looking up a missing root must not create it. */
 function rootMap(doc, name) {
@@ -6098,6 +6226,7 @@ function referenceTargets(table, row) {
 	}
 }
 function readMedeoDsl(doc, state) {
+	const logical = logicalDslState(state);
 	const diagnostics = [];
 	const diagnostic = (code, path, error) => diagnostics.push({
 		code,
@@ -6107,7 +6236,7 @@ function readMedeoDsl(doc, state) {
 	const entities = Object.fromEntries(entityTables.map((t) => [t, {}]));
 	const relations = Object.fromEntries(relationTables.map((t) => [t, {}]));
 	const richText = {};
-	for (const table of entityTables) for (const [id, raw] of Object.entries(state[table] ?? {})) try {
+	for (const table of entityTables) for (const [id, raw] of Object.entries(logical[table] ?? {})) try {
 		assertId(id);
 		let v = raw;
 		for (const field of optionalReferences[table] ?? []) {
@@ -6613,7 +6742,11 @@ function validateDraft(tracked) {
 		before,
 		after: state,
 		entities: tracked.entities,
-		relations: tracked.relations
+		relations: tracked.relations,
+		containment: {
+			before: plainTree(before["contain-relations"] ?? []),
+			after: plainTree(state["contain-relations"] ?? [])
+		}
 	});
 	if (!tracked.treeChanged) return;
 	const oldNodes = nodeIndex(before["contain-relations"] ?? []);
@@ -6690,8 +6823,11 @@ function runTransaction(doc, mirror, edit, options, setReject) {
 	const steps = [];
 	const newCaptionTexts = /* @__PURE__ */ new Map();
 	const bodies = /* @__PURE__ */ new Map();
-	const before = mirror.getState();
-	mirror.setState((raw) => {
+	const nativeBefore = mirror.getState();
+	const before = logicalDslState(nativeBefore);
+	const phoneticRows = /* @__PURE__ */ new Map();
+	mirror.setState((native) => {
+		const raw = logicalDslState(native);
 		const tracked = new TransactionDraft(raw, before);
 		setReject((error) => tracked.fail(error));
 		/** The current text of a Caption's own Text or a script segment, as this transaction leaves it so far. */
@@ -6883,6 +7019,15 @@ function runTransaction(doc, mirror, edit, options, setReject) {
 				for (const step of steps) if (step.type === "text") if ("captionId" in step.target) requireEntity(raw, "caption-entities", step.target.captionId);
 				else requireSegment(raw, step.target.audioScriptId, step.target.segmentId);
 				assertSelectionsAfter(raw, before, tracked, steps);
+				const changedPhonetics = new Set([...tracked.entities.get("phonetic-script-entities")?.keys() ?? [], ...steps.flatMap((step) => step.type !== "text" && step.table === "phonetic-script-entities" ? [step.id] : [])]);
+				for (const id of changedPhonetics) {
+					const row = raw["phonetic-script-entities"][id];
+					phoneticRows.set(id, row ? copyInput(row) : void 0);
+					if (!row) continue;
+					const old = nativeBefore["phonetic-script-entities"][id];
+					if (old) native["phonetic-script-entities"][id] = old;
+					else delete native["phonetic-script-entities"][id];
+				}
 				for (const [id, fields] of tracked.entities.get("caption-entities") ?? []) {
 					const row = raw["caption-entities"][id];
 					if (fields.has("text") && row?.text !== void 0 && before["caption-entities"][id]?.text === void 0) {
@@ -6891,6 +7036,7 @@ function runTransaction(doc, mirror, edit, options, setReject) {
 					}
 				}
 				for (const table of Object.keys(selectionField)) {
+					if (table === "phonetic-script-entities") continue;
 					const field = selectionField[table];
 					for (const [id, fields] of tracked.entities.get(table) ?? []) {
 						const row = raw[table][id];
@@ -6930,6 +7076,8 @@ function runTransaction(doc, mirror, edit, options, setReject) {
 					applyTextEdits(text, step.edits);
 					continue;
 				}
+				const phonetic = step.table === "phonetic-script-entities" ? phoneticRows.get(step.id) : void 0;
+				if (step.table === "phonetic-script-entities" && !phonetic) continue;
 				const row = entityRow(doc, step.table, step.id);
 				const field = selectionField[step.table];
 				if (step.type === "range") {
@@ -6948,12 +7096,21 @@ function runTransaction(doc, mirror, edit, options, setReject) {
 						if (!value.start || !value.end) throw new Error("Unable to construct prepared range");
 					}
 					if (step.phonemeScript !== void 0) value.phonemeScript = step.phonemeScript;
-					if (!row) throw new Error("Unable to construct prepared range");
-					row.set(field, codecs[step.table].encode(value));
-				} else if (step.value !== void 0) {
+					if (phonetic) phonetic.phoneme = value;
+					else {
+						if (!row) throw new Error("Unable to construct prepared range");
+						row.set(field, codecs[step.table].encode(value));
+					}
+				} else if (step.value !== void 0) if (phonetic) phonetic.phoneme = step.value;
+				else {
 					if (!row) throw new Error("Prepared selection owner is missing");
 					row.set(field, codecs[step.table].encode(step.value));
-				} else if (row?.get(field) !== void 0) row.delete(field);
+				}
+				else if (row?.get(field) !== void 0) row.delete(field);
+			}
+			for (const [id, binding] of phoneticRows) {
+				if (!binding) continue;
+				(entityRow(doc, "phonetic-script-entities", id) ?? doc.getMap("phonetic-script-entities").setContainer(id, new LoroMap())).set("binding", phoneticBindingCodec.encode(binding));
 			}
 		}
 	});
@@ -6966,7 +7123,7 @@ function runTransaction(doc, mirror, edit, options, setReject) {
 function assertSelectionsAfter(raw, before, tracked, steps) {
 	const selected = new Set(Object.entries(before["caption-entities"]).filter(([, caption]) => typeof caption === "object" && caption.selection !== void 0).map(([id]) => id));
 	const changedCaptions = /* @__PURE__ */ new Set();
-	for (const [id, fields] of tracked.entities.get("caption-entities") ?? []) if (fields.has("text")) changedCaptions.add(id);
+	for (const [id, fields] of tracked.entities.get("caption-entities") ?? []) if (!before["caption-entities"][id] || fields.has("text")) changedCaptions.add(id);
 	const phonemes = /* @__PURE__ */ new Map();
 	for (const step of steps) {
 		if (step.type === "text") {
@@ -7000,7 +7157,7 @@ function assertSelectionsAfter(raw, before, tracked, steps) {
 		if (!row) continue;
 		const phoneme = phonemes.has(id) ? phonemes.get(id) : row.phoneme;
 		const old = before["phonetic-script-entities"][id];
-		assertPhoneticScript(old, {
+		assertPhoneticScript(old ? { ...old } : void 0, {
 			...row,
 			phoneme: isRecord(phoneme) ? phoneme : void 0
 		});
@@ -7039,6 +7196,7 @@ var MedeoDsl = class MedeoDsl {
 			"tracks",
 			"part_library"
 		].some((key) => Object.hasOwn(roots, key))) throw new Error("Expected a new DSL document, not a legacy content model");
+		assertPhoneticBindingFormat(doc);
 		doc.configTextStyle(textStyles);
 		this.mirror = new Mirror({
 			doc,
@@ -7102,6 +7260,11 @@ var MedeoDsl = class MedeoDsl {
 	editCaptionText(captionId, expectedBodyId, edits, audit) {
 		this.transact((tx) => tx.editCaptionText(captionId, edits, expectedBodyId), audit);
 	}
+	/** Check the session's write capability before an Action starts host-owned resource I/O. */
+	assertWritable() {
+		this.assertReadyToWrite();
+		this.options.mutationGuard?.run(() => {});
+	}
 	/**
 	* A run inside one segment as native Cursors. Local ranges exclude insertions at their start and
 	* include insertions at their end. K01 remains deferred.
@@ -7134,13 +7297,7 @@ var MedeoDsl = class MedeoDsl {
 		if (this.ownsDoc) this.doc.free();
 	}
 	mutate(run) {
-		this.assertActive();
-		if (this.writing || this.notifying) {
-			const error = /* @__PURE__ */ new Error("A DSL mutation is already running");
-			this.rejectTransaction?.(error);
-			throw error;
-		}
-		if (this.doc.getPendingTxnLength() !== 0) throw new Error("Commit external native edits before a DSL mutation");
+		this.assertReadyToWrite();
 		const apply = () => {
 			this.writing = true;
 			try {
@@ -7155,6 +7312,15 @@ var MedeoDsl = class MedeoDsl {
 		if (this.options.mutationGuard) this.options.mutationGuard.run(apply);
 		else apply();
 	}
+	assertReadyToWrite() {
+		this.assertActive();
+		if (this.writing || this.notifying) {
+			const error = /* @__PURE__ */ new Error("A DSL mutation is already running");
+			this.rejectTransaction?.(error);
+			throw error;
+		}
+		if (this.doc.getPendingTxnLength() !== 0) throw new Error("Commit external native edits before a DSL mutation");
+	}
 	notify() {
 		if (this.disposed || !this.dirty) return;
 		this.dirty = false;
@@ -7181,12 +7347,13 @@ function spokenScripts(snapshot, recordingId) {
 	const found = /* @__PURE__ */ new Map();
 	const seen = /* @__PURE__ */ new Set();
 	const visit = (id, phoneticScriptId) => {
-		if (seen.has(id)) return;
-		seen.add(id);
 		if (snapshot["audio-script-entities"][id]) {
-			if (!found.has(id)) found.set(id, phoneticScriptId);
+			if (!found.has(id)) found.set(id, /* @__PURE__ */ new Set());
+			if (phoneticScriptId !== void 0) found.get(id).add(phoneticScriptId);
 			return;
 		}
+		if (seen.has(id)) return;
+		seen.add(id);
 		const phonetic = snapshot["phonetic-script-entities"][id];
 		if (phonetic) {
 			visit(phonetic.phoneme.audioScriptId, id);
@@ -7196,11 +7363,18 @@ function spokenScripts(snapshot, recordingId) {
 	};
 	visit(recordingId);
 	if (!found.size) {
-		for (const r of relations) if (r.sourceId === recordingId && snapshot["audio-script-entities"][r.entityId]) found.set(r.entityId, void 0);
+		for (const r of relations) if (r.sourceId === recordingId && snapshot["audio-script-entities"][r.entityId]) found.set(r.entityId, /* @__PURE__ */ new Set());
 	}
-	return [...found].map(([audioScriptId, phoneticScriptId]) => phoneticScriptId === void 0 ? { audioScriptId } : {
-		audioScriptId,
-		phoneticScriptId
+	return [...found].map(([audioScriptId, ids]) => {
+		const phoneticScriptIds = [...ids];
+		if (phoneticScriptIds.length === 1) return {
+			audioScriptId,
+			phoneticScriptId: phoneticScriptIds[0]
+		};
+		return phoneticScriptIds.length ? {
+			audioScriptId,
+			phoneticScriptIds
+		} : { audioScriptId };
 	});
 }
 /** Every AudioScript in the document with its PhoneticScripts, the Speech Clips saying it and the Caption Clips showing it. */
@@ -7245,7 +7419,6 @@ function toAudioScriptViews(snapshot) {
 		});
 	}
 	const layout = resolveDslLayout(snapshot);
-	for (const view of views.values()) placeTranscript(snapshot, layout, view);
 	const timbres = Object.values(snapshot["voice-timbre-relations"]);
 	for (const track of layout.tracks) for (const { clipId } of track.clips) {
 		const source = snapshot["clip-entities"][clipId]?.source;
@@ -7269,6 +7442,7 @@ function toAudioScriptViews(snapshot) {
 					clipId,
 					recordingId: source,
 					...spoken.phoneticScriptId === void 0 ? {} : { phoneticScriptId: spoken.phoneticScriptId },
+					...spoken.phoneticScriptIds === void 0 ? {} : { phoneticScriptIds: spoken.phoneticScriptIds },
 					voices,
 					...applied === void 0 ? {} : { applied }
 				});
@@ -7285,19 +7459,23 @@ function toAudioScriptViews(snapshot) {
 			segment
 		});
 	}
+	for (const view of views.values()) placeTranscript(snapshot, layout, view);
 	return [...views.values()];
 }
 /**
 * A transcript's segments on the Timeline: a segment's time is in the medium the script was read
-* off, so it lands where the earliest Clip playing that medium holds that moment in its window.
+* off. An authored Caption anchor identifies its use of that medium; otherwise the earliest
+* Clip holding that source moment is used. The source time is never taken from the Caption.
 */
 function placeTranscript(snapshot, layout, view) {
 	if (!view.sourceMediaIds.length) return;
 	const plays = layout.tracks.flatMap((track) => track.clips).filter((clip) => view.sourceMediaIds.includes(snapshot["clip-entities"][clip.clipId]?.source ?? "")).sort((a, b) => a.startMs - b.startMs);
-	for (const segment of view.segments) {
+	for (const [index, segment] of view.segments.entries()) {
 		const at = segment.startMs;
 		if (at === void 0) continue;
-		const clip = plays.find((c) => c.inMs <= at && at < c.outMs);
+		const anchoredUses = new Set(view.captions.filter((caption) => caption.segment === index).map((caption) => layout.clips[caption.clipId]?.anchorClipId));
+		const candidates = plays.filter((c) => c.inMs <= at && at < c.outMs);
+		const clip = candidates.find((c) => anchoredUses.has(c.clipId)) ?? candidates[0];
 		if (clip) segment.timelineMs = Math.round(clip.startMs + (at - clip.inMs) / clip.rate);
 	}
 }
@@ -7308,14 +7486,26 @@ function placeTranscript(snapshot, layout, view) {
 * not what a take was synthesized from (D190).
 */
 function appliedSpeech(snapshot, recordingId, spoken) {
-	const sourceId = spoken.phoneticScriptId ?? spoken.audioScriptId;
-	const recorded = Object.values(snapshot["derived-from-relations"]).find((r) => r.entityId === recordingId && r.sourceId === sourceId)?.sourceDigest;
-	const current = spoken.phoneticScriptId === void 0 ? void 0 : snapshot["phonetic-script-entities"][sourceId]?.digest;
-	return recorded === void 0 || current === void 0 ? void 0 : recorded === current;
+	const ids = spoken.phoneticScriptIds ?? (spoken.phoneticScriptId === void 0 ? [] : [spoken.phoneticScriptId]);
+	if (!ids.length) return void 0;
+	let unknown = false;
+	for (const sourceId of ids) {
+		const recorded = Object.values(snapshot["derived-from-relations"]).find((r) => r.entityId === recordingId && r.sourceId === sourceId)?.sourceDigest;
+		const current = snapshot["phonetic-script-entities"][sourceId]?.digest;
+		if (recorded === void 0 || current === void 0) unknown = true;
+		else if (recorded !== current) return false;
+	}
+	return unknown ? void 0 : true;
 }
 //#endregion
 //#region src/dsl/voiceover-actions.ts
-function voiceoverPlan(s, input, result) {
+function matchesPlainPhoneticOrigin(s, id, scriptId, segmentId) {
+	const phonetic = s["phonetic-script-entities"][id];
+	const run = s.phoneticText[id];
+	const segment = s["audio-script-entities"][scriptId]?.segments.find((item) => item.id === segmentId);
+	return phonetic?.phoneme.audioScriptId === scriptId && phonetic.phoneme.segmentId === segmentId && phonetic.phoneme.phonemeScript === void 0 && run?.start === 0 && run.end === segment?.text.length;
+}
+function voiceoverPlan(s, input, result, plainPhoneticIds) {
 	if (requireTrack(s, input.trackId).role !== "speech" || input.media.kind !== "voiceover-recording") throw new Error("Voiceover requires a speech Track and a recording");
 	if (input.captions.length && (!input.captionTrackId || requireTrack(s, input.captionTrackId).role !== "caption")) throw new Error("Caption Track is required");
 	const existing = s["clip-entities"][result.clipId];
@@ -7354,15 +7544,44 @@ function voiceoverPlan(s, input, result) {
 		inMs: 0,
 		outMs: input.media.durationMs
 	}, input.media.durationMs);
-	mutations.push({
-		type: "set-relation",
-		table: "derived-from-relations",
-		value: {
-			entityId: result.mediaId,
-			sourceId: phoneticScriptId ?? result.audioScriptId,
-			...input.sourceDigest === void 0 ? {} : { sourceDigest: input.sourceDigest }
-		}
-	});
+	if (phoneticScriptId !== void 0) {
+		const recorded = Object.values(s["derived-from-relations"]).find((origin) => origin.entityId === result.mediaId && origin.sourceId === phoneticScriptId);
+		if (recorded?.sourceDigest !== void 0 && input.sourceDigest !== void 0 && recorded.sourceDigest !== input.sourceDigest) throw new Error("A recording already has a different synthesis digest");
+		if (!recorded || recorded.sourceDigest === void 0 && input.sourceDigest !== void 0) mutations.push({
+			type: "set-relation",
+			table: "derived-from-relations",
+			value: {
+				entityId: result.mediaId,
+				sourceId: phoneticScriptId,
+				...input.sourceDigest === void 0 ? {} : { sourceDigest: input.sourceDigest }
+			}
+		});
+	} else {
+		if (input.sourceDigest !== void 0) throw new Error("A synthesis digest requires its PhoneticScript");
+		if (plainPhoneticIds.length !== segmentIds.length) throw new Error("Expected one PhoneticScript id per plain segment");
+		segmentIds.forEach((segmentId, i) => {
+			const id = plainPhoneticIds[i];
+			if (s["phonetic-script-entities"][id]) {
+				if (!matchesPlainPhoneticOrigin(s, id, result.audioScriptId, segmentId)) throw new Error("PhoneticScript id already names another synthesis origin");
+			} else mutations.push({
+				type: "create-entity",
+				table: "phonetic-script-entities",
+				id,
+				value: { phoneme: {
+					audioScriptId: result.audioScriptId,
+					segmentId
+				} }
+			});
+			if (!Object.values(s["derived-from-relations"]).some((origin) => origin.entityId === result.mediaId && origin.sourceId === id)) mutations.push({
+				type: "set-relation",
+				table: "derived-from-relations",
+				value: {
+					entityId: result.mediaId,
+					sourceId: id
+				}
+			});
+		});
+	}
 	if (input.voice) {
 		const id = resourceId("voice", input.voice.system, input.voice.key);
 		mutations.push({
@@ -7859,10 +8078,20 @@ var DslEditor = class {
 			captionClipIds: input.captions.map((c) => c.clipId ?? this.idFactory("clip")),
 			captionIds: input.captions.map(() => this.idFactory("caption"))
 		};
+		const state = this.dsl.getSnapshot();
+		const plainSegments = input.script.segments === void 0 ? state["audio-script-entities"][result.audioScriptId]?.segments.map((segment) => segment.id) ?? [] : result.segmentIds;
+		const plainPhoneticIds = input.script.phoneticScriptId === void 0 ? plainSegments.map((segmentId) => {
+			const origins = Object.values(state["derived-from-relations"]).filter((origin) => {
+				if (origin.entityId !== result.mediaId) return false;
+				return matchesPlainPhoneticOrigin(state, origin.sourceId, result.audioScriptId, segmentId);
+			});
+			if (origins.length > 1) throw new Error("Ambiguous plain recording origin");
+			return origins[0]?.sourceId ?? this.idFactory("phonetic-script");
+		}) : [];
 		this.write("applyVoiceover", {
 			input,
 			result
-		}, voiceoverPlan(this.dsl.getSnapshot(), input, result), options);
+		}, voiceoverPlan(state, input, result, plainPhoneticIds), options);
 		return result;
 	}
 	voiceoverScriptId(script) {
@@ -7879,8 +8108,12 @@ var DslEditor = class {
 	* it; an unchanged one keeps its file. Recordings already spoken from it keep their derived-from.
 	*/
 	async setPhoneticScript(input, options) {
+		this.dsl.assertWritable();
 		const id = input.phoneticScriptId ?? this.idFactory("phonetic-script");
 		const range = segmentRange(input);
+		assertId(id);
+		assertSegmentRange(range, requireSegment(this.dsl.getSnapshot(), range.audioScriptId, range.segmentId).text);
+		assertPhonemeScript(input.phonemeScript);
 		const file = input.phonemeScript === void 0 ? {} : await this.fileFor(id, input.phonemeScript);
 		const exists = Object.hasOwn(this.dsl.getSnapshot()["phonetic-script-entities"], id);
 		const cleared = {
@@ -8105,7 +8338,8 @@ function toVideoDraft(snapshot) {
 					} }
 				} };
 			} else if (track.role === "speech") {
-				if (!source || source.kind !== "voiceover-recording" || source.system !== "memota-speech") fail("Legacy Speech requires a memota-speech VoiceoverRecording");
+				if (!source || source.kind !== "audio" && source.kind !== "voiceover-recording") fail("Speech playback requires an Audio or VoiceoverRecording");
+				if (source.system !== "memota" && !(source.kind === "voiceover-recording" && source.system === "memota-speech")) fail("Speech playback requires a Memota audio file");
 				requireWholeAudio(source, clip, fail);
 				if (clip.fillTimeline) fail("Legacy Speech cannot express timeline fill");
 				const voices = Object.values(snapshot["voice-timbre-relations"]).filter((r) => r.recordingId === sourceId).flatMap((r) => snapshot["voice-entities"][r.voiceId] ? [snapshot["voice-entities"][r.voiceId]] : []);
@@ -8122,7 +8356,7 @@ function toVideoDraft(snapshot) {
 					audio_storage_key: source.storageKey,
 					origin_speech_id: source.key,
 					volume: clip.volume,
-					audio_script: spokenText(snapshot, sourceId),
+					audio_script: source.kind === "voiceover-recording" ? spokenText(snapshot, sourceId) : "",
 					voice: voice ? {
 						id: voice.key,
 						name: voice.name
@@ -8218,6 +8452,15 @@ function spokenText(snapshot, recordingId) {
 	if (!first) return "";
 	if (first.phoneticScriptId !== void 0) return snapshot.phoneticText[first.phoneticScriptId]?.text ?? "";
 	const script = snapshot["audio-script-entities"][first.audioScriptId];
+	if (first.phoneticScriptIds !== void 0 && script) {
+		const ids = first.phoneticScriptIds;
+		const selections = ids.map((id) => snapshot["phonetic-script-entities"][id]);
+		if (!(ids.length === script.segments.length && script.segments.every((segment) => {
+			const matching = ids.filter((id) => snapshot["phonetic-script-entities"][id]?.phoneme.segmentId === segment.id);
+			const run = matching.length === 1 ? snapshot.phoneticText[matching[0]] : void 0;
+			return run?.start === 0 && run.end === segment.text.length;
+		})) || selections.some((selection) => selection.phoneme.phonemeScript !== void 0)) projectionError("ambiguous-script", `media-entities/${recordingId}`, "Multiple phonetic sources require complete plain selections of one script");
+	}
 	return script ? script.segments.map((segment) => segment.text).join("\n") : "";
 }
 //#endregion
@@ -8440,11 +8683,7 @@ function prepare(input, options) {
 					start: start - segment.start,
 					end: end - segment.start
 				});
-			} else diagnostics.push({
-				code: "caption-text-unmatched",
-				path: `part_library/${captionId}/text`,
-				message: "No forward exact match; preserved as independent Caption text"
-			});
+			} else fail(`part_library/${captionId}/text`, "Caption must match a segment of its AudioScript");
 		}
 	}
 	const hosts = /* @__PURE__ */ new Map();
@@ -8487,16 +8726,14 @@ function prepare(input, options) {
 			if (caption.speech_part_id !== void 0 && owner.get(id) !== caption.speech_part_id) fail(`part_library/${id}/speech_part_id`, "Caption ownership must agree with ordered speech.caption_ids");
 			sourceId = claim(mint("caption"));
 			const selected = selections.get(id), style = fromDraftStyle(caption.style);
+			if (!selected) fail(`part_library/${id}/text`, "Caption must select a segment of an AudioScript");
 			mutations.push({
 				type: "create-entity",
 				table: "caption-entities",
 				id: sourceId,
-				value: {
-					...style === void 0 ? {} : { style },
-					...selected ? {} : { text: caption.text }
-				}
+				value: style === void 0 ? {} : { style }
 			});
-			if (selected) mutations.push({
+			mutations.push({
 				type: "set-caption-content",
 				captionId: sourceId,
 				...selected
@@ -8684,4 +8921,4 @@ function normalizeLegacyVideoDraft(input, mediaFacts = []) {
 	};
 }
 //#endregion
-export { tupleHash as C, resourceId as S, DslProjectionError as _, createInitialMedeoDsl as a, defaultIdFactory as b, MedeoDsl as c, documentFormat as d, medeoDslLoroShape as f, resolveDslLayout as g, timeAnchorCodec as h, DEFAULT_UNIT_TIME_MS as i, UnsupportedDocumentFormatError as l, isInvalidAtomic as m, fromVideoDraft as n, DslEditor as o, captionContentCodec as p, toVideoDraft as r, toAudioScriptViews as s, normalizeLegacyVideoDraft as t, assertDslDocument as u, BLANK_PLACEHOLDER as v, relationId as x, missingMediaPlaceholder as y };
+export { relationId as C, defaultIdFactory as S, tupleHash as T, timeAnchorCodec as _, createInitialMedeoDsl as a, BLANK_PLACEHOLDER as b, toAudioScriptViews as c, assertDslDocument as d, assertPhoneticBindingFormat as f, isInvalidAtomic as g, captionContentCodec as h, DEFAULT_UNIT_TIME_MS as i, MedeoDsl as l, medeoDslLoroShape as m, fromVideoDraft as n, DslEditor as o, documentFormat as p, toVideoDraft as r, spokenScripts as s, normalizeLegacyVideoDraft as t, UnsupportedDocumentFormatError as u, resolveDslLayout as v, resourceId as w, missingMediaPlaceholder as x, DslProjectionError as y };