@mengine/medeo-client 3.0.0 → 3.0.1-dsl.0

package/README.md

@@ -163,3 +163,7 @@ Caption text is matched forward in `speech.caption_ids` order. A failed exact ma
 `/relay` and `/testing` remain host/test-only entrypoints. The private DSL package is bundled into the client distribution.
 
 See [DSL index](../../docs/projects/medeo-dsl/README.md), [capability mapping and cutover](../../docs/projects/medeo-dsl/rfc/03-editor-and-document-cutover.md) and [known limits](../../docs/projects/medeo-dsl/known-unfixed.md). K04 audit segmentation is unchanged; one native commit can contain multiple Changes.
+
+The row-owned atomic binding stores the selection, pronunciation and file facts together. Public Action methods and domain snapshots retain their shape; the native Loro field layout requires matching SDK/server versions. Old field-per-fact DSL documents require explicit migration and are refused by the new reader and relay. See [the cutover contract](../../docs/projects/medeo-dsl/rfc/06-phonetic-binding-cutover.md).
+
+The public `/schemas` subpath retains the input contracts used by FE semantic-op dispatch. These live in `src/schemas` and do not expose a retired editor or storage writer (D201).

package/dist/{dsl-Cpk8WxcZ.js → dsl-BngbR2zr.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");
 }
@@ -638,6 +642,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) {
@@ -653,6 +714,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;
@@ -667,25 +729,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
@@ -921,15 +975,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);
@@ -1217,14 +1267,15 @@ 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
 		}
 	}];
 }
 //#endregion
-//#region ../../node_modules/.pnpm/loro-mirror@2.3.3_patch_hash=a551a0e4aa4f61ec88b0d9e970a183b5ee2955107a2e0bb03b378bc510c2f395_loro-crdt@1.16.4/node_modules/loro-mirror/dist/schema/resolver.js
+//#region ../../node_modules/.pnpm/loro-mirror@2.3.3_patch_hash=a551a0e4aa4f61ec88b0d9e970a183b5ee2955107a2e0bb03b378bc510c2f395_loro-crdt@1.16.1/node_modules/loro-mirror/dist/schema/resolver.js
 function getMapFieldSchema(schema, key) {
 	if (!schema) return void 0;
 	if (Object.prototype.hasOwnProperty.call(schema.definition, key)) return schema.definition[key];
@@ -1254,10 +1305,10 @@ function getChildContainerSchema(schema, childKey) {
 	}
 }
 //#endregion
-//#region ../../node_modules/.pnpm/loro-mirror@2.3.3_patch_hash=a551a0e4aa4f61ec88b0d9e970a183b5ee2955107a2e0bb03b378bc510c2f395_loro-crdt@1.16.4/node_modules/loro-mirror/dist/constants.js
+//#region ../../node_modules/.pnpm/loro-mirror@2.3.3_patch_hash=a551a0e4aa4f61ec88b0d9e970a183b5ee2955107a2e0bb03b378bc510c2f395_loro-crdt@1.16.1/node_modules/loro-mirror/dist/constants.js
 const CID_KEY = "$cid";
 //#endregion
-//#region ../../node_modules/.pnpm/loro-mirror@2.3.3_patch_hash=a551a0e4aa4f61ec88b0d9e970a183b5ee2955107a2e0bb03b378bc510c2f395_loro-crdt@1.16.4/node_modules/loro-mirror/dist/core/container-inference.js
+//#region ../../node_modules/.pnpm/loro-mirror@2.3.3_patch_hash=a551a0e4aa4f61ec88b0d9e970a183b5ee2955107a2e0bb03b378bc510c2f395_loro-crdt@1.16.1/node_modules/loro-mirror/dist/core/container-inference.js
 function isPlainObjectValue(value) {
 	return typeof value === "object" && value !== null && !Array.isArray(value) && !(value instanceof Date) && !(value instanceof RegExp) && typeof value !== "function";
 }
@@ -1296,7 +1347,7 @@ function getContainerValueKind(value) {
 	return "other";
 }
 //#endregion
-//#region ../../node_modules/.pnpm/loro-mirror@2.3.3_patch_hash=a551a0e4aa4f61ec88b0d9e970a183b5ee2955107a2e0bb03b378bc510c2f395_loro-crdt@1.16.4/node_modules/loro-mirror/dist/core/utils.js
+//#region ../../node_modules/.pnpm/loro-mirror@2.3.3_patch_hash=a551a0e4aa4f61ec88b0d9e970a183b5ee2955107a2e0bb03b378bc510c2f395_loro-crdt@1.16.1/node_modules/loro-mirror/dist/core/utils.js
 /**
 * Utility functions for Loro Mirror core
 */
@@ -1720,7 +1771,7 @@ function safeStringify(value, indent = 2) {
 	return JSON.stringify(replacer(value), null, indent);
 }
 //#endregion
-//#region ../../node_modules/.pnpm/loro-mirror@2.3.3_patch_hash=a551a0e4aa4f61ec88b0d9e970a183b5ee2955107a2e0bb03b378bc510c2f395_loro-crdt@1.16.4/node_modules/loro-mirror/dist/schema/validators.js
+//#region ../../node_modules/.pnpm/loro-mirror@2.3.3_patch_hash=a551a0e4aa4f61ec88b0d9e970a183b5ee2955107a2e0bb03b378bc510c2f395_loro-crdt@1.16.1/node_modules/loro-mirror/dist/schema/validators.js
 const schemaValidationCache = /* @__PURE__ */ new WeakMap();
 function isCacheableValue(value) {
 	return typeof value === "object" && value !== null;
@@ -2000,7 +2051,7 @@ function getDefaultValue(schema) {
 	}
 }
 //#endregion
-//#region ../../node_modules/.pnpm/loro-mirror@2.3.3_patch_hash=a551a0e4aa4f61ec88b0d9e970a183b5ee2955107a2e0bb03b378bc510c2f395_loro-crdt@1.16.4/node_modules/loro-mirror/dist/schema/index.js
+//#region ../../node_modules/.pnpm/loro-mirror@2.3.3_patch_hash=a551a0e4aa4f61ec88b0d9e970a183b5ee2955107a2e0bb03b378bc510c2f395_loro-crdt@1.16.1/node_modules/loro-mirror/dist/schema/index.js
 /**
 * Create a schema definition
 */
@@ -2765,7 +2816,7 @@ const produce = new Immer2({
 	useStrictShallowCopy: true
 }).produce;
 //#endregion
-//#region ../../node_modules/.pnpm/loro-mirror@2.3.3_patch_hash=a551a0e4aa4f61ec88b0d9e970a183b5ee2955107a2e0bb03b378bc510c2f395_loro-crdt@1.16.4/node_modules/loro-mirror/dist/core/debounce-timer.js
+//#region ../../node_modules/.pnpm/loro-mirror@2.3.3_patch_hash=a551a0e4aa4f61ec88b0d9e970a183b5ee2955107a2e0bb03b378bc510c2f395_loro-crdt@1.16.1/node_modules/loro-mirror/dist/core/debounce-timer.js
 /**
 * Deadline-based debounce timer.
 *
@@ -2823,7 +2874,7 @@ var DebounceTimer = class {
 	}
 };
 //#endregion
-//#region ../../node_modules/.pnpm/loro-mirror@2.3.3_patch_hash=a551a0e4aa4f61ec88b0d9e970a183b5ee2955107a2e0bb03b378bc510c2f395_loro-crdt@1.16.4/node_modules/loro-mirror/dist/core/ephemeral.js
+//#region ../../node_modules/.pnpm/loro-mirror@2.3.3_patch_hash=a551a0e4aa4f61ec88b0d9e970a183b5ee2955107a2e0bb03b378bc510c2f395_loro-crdt@1.16.1/node_modules/loro-mirror/dist/core/ephemeral.js
 /**
 * Manages ephemeral patches: storage, composition, path resolution, and finalization.
 */
@@ -3098,7 +3149,7 @@ var EphemeralPatchManager = class {
 	}
 };
 //#endregion
-//#region ../../node_modules/.pnpm/loro-mirror@2.3.3_patch_hash=a551a0e4aa4f61ec88b0d9e970a183b5ee2955107a2e0bb03b378bc510c2f395_loro-crdt@1.16.4/node_modules/loro-mirror/dist/core/tree-utils.js
+//#region ../../node_modules/.pnpm/loro-mirror@2.3.3_patch_hash=a551a0e4aa4f61ec88b0d9e970a183b5ee2955107a2e0bb03b378bc510c2f395_loro-crdt@1.16.1/node_modules/loro-mirror/dist/core/tree-utils.js
 function normalizeTreeJson(input, options) {
 	if (!Array.isArray(input)) return [];
 	return input.map((node) => normalizeTreeNode(node, options));
@@ -3121,7 +3172,7 @@ function isPlainRecord(value) {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 //#endregion
-//#region ../../node_modules/.pnpm/loro-mirror@2.3.3_patch_hash=a551a0e4aa4f61ec88b0d9e970a183b5ee2955107a2e0bb03b378bc510c2f395_loro-crdt@1.16.4/node_modules/loro-mirror/dist/core/loroEventApply.js
+//#region ../../node_modules/.pnpm/loro-mirror@2.3.3_patch_hash=a551a0e4aa4f61ec88b0d9e970a183b5ee2955107a2e0bb03b378bc510c2f395_loro-crdt@1.16.1/node_modules/loro-mirror/dist/core/loroEventApply.js
 function isJSONObject(v) {
 	return typeof v === "object" && v !== null && !Array.isArray(v);
 }
@@ -3543,7 +3594,7 @@ function isIgnoredByAncestor(id, ignoreSet, getContainerById) {
 	return false;
 }
 //#endregion
-//#region ../../node_modules/.pnpm/loro-mirror@2.3.3_patch_hash=a551a0e4aa4f61ec88b0d9e970a183b5ee2955107a2e0bb03b378bc510c2f395_loro-crdt@1.16.4/node_modules/loro-mirror/dist/core/diff.js
+//#region ../../node_modules/.pnpm/loro-mirror@2.3.3_patch_hash=a551a0e4aa4f61ec88b0d9e970a183b5ee2955107a2e0bb03b378bc510c2f395_loro-crdt@1.16.1/node_modules/loro-mirror/dist/core/diff.js
 /**
 * Finds the longest increasing subsequence of a sequence of numbers
 * @param sequence The sequence of numbers
@@ -4274,7 +4325,7 @@ function diffMap(doc, oldState, newState, containerId, schema, inferOptions) {
 	return changes;
 }
 //#endregion
-//#region ../../node_modules/.pnpm/loro-mirror@2.3.3_patch_hash=a551a0e4aa4f61ec88b0d9e970a183b5ee2955107a2e0bb03b378bc510c2f395_loro-crdt@1.16.4/node_modules/loro-mirror/dist/core/mirror.js
+//#region ../../node_modules/.pnpm/loro-mirror@2.3.3_patch_hash=a551a0e4aa4f61ec88b0d9e970a183b5ee2955107a2e0bb03b378bc510c2f395_loro-crdt@1.16.1/node_modules/loro-mirror/dist/core/mirror.js
 /**
 * Mirror core functionality for bidirectional sync between app state and Loro CRDT
 */
@@ -5845,6 +5896,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);
@@ -5911,13 +5986,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),
@@ -5969,20 +6038,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) {
@@ -6066,6 +6193,7 @@ function referenceTargets(table, row) {
 	}
 }
 function readMedeoDsl(doc, state) {
+	const logical = logicalDslState(state);
 	const diagnostics = [];
 	const diagnostic = (code, path, error) => diagnostics.push({
 		code,
@@ -6075,7 +6203,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] ?? []) {
@@ -6581,7 +6709,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"] ?? []);
@@ -6658,8 +6790,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. */
@@ -6851,6 +6986,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) {
@@ -6859,6 +7003,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];
@@ -6898,6 +7043,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") {
@@ -6916,12 +7063,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));
 			}
 		}
 	});
@@ -6968,7 +7124,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
 		});
@@ -7007,6 +7163,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,
@@ -7070,6 +7227,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.
@@ -7102,13 +7264,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 {
@@ -7123,6 +7279,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;
@@ -7847,8 +8012,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 = {
@@ -8072,7 +8241,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]] : []);
@@ -8089,7 +8259,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
@@ -8524,4 +8694,4 @@ function importedScript(id, text, mintSegment) {
 	};
 }
 //#endregion
-export { defaultIdFactory as _, DslEditor as a, tupleHash as b, UnsupportedDocumentFormatError as c, medeoDslLoroShape as d, captionContentCodec as f, DslProjectionError as g, resolveDslLayout as h, createInitialMedeoDsl as i, assertDslDocument as l, timeAnchorCodec as m, toVideoDraft as n, toAudioScriptViews as o, isInvalidAtomic as p, DEFAULT_UNIT_TIME_MS as r, MedeoDsl as s, fromVideoDraft as t, documentFormat as u, relationId as v, resourceId as y };
+export { DslProjectionError as _, DslEditor as a, resourceId as b, UnsupportedDocumentFormatError as c, documentFormat as d, medeoDslLoroShape as f, resolveDslLayout as g, timeAnchorCodec as h, createInitialMedeoDsl as i, assertDslDocument as l, isInvalidAtomic as m, toVideoDraft as n, toAudioScriptViews as o, captionContentCodec as p, DEFAULT_UNIT_TIME_MS as r, MedeoDsl as s, fromVideoDraft as t, assertPhoneticBindingFormat as u, defaultIdFactory as v, tupleHash as x, relationId as y };

package/dist/dsl.d.ts

@@ -1,2 +1,2 @@
-import { $ as ClipPlacement, A as VoiceoverResult, At as RichTextSnapshot, B as isInvalidAtomic, Bt as Voice, C as DslProjectionError, Ct as MedeoDslSnapshot, D as UploadText, Dt as RelationTables, E as DslEditor, Et as RelationTable, F as UnsupportedDocumentFormatError, Ft as TextMutation, G as CommitOptions, H as MedeoDslDraft, I as assertDslDocument, It as TextRun, J as AddDslClipsInput, K as OpActor, L as documentFormat, Lt as TimeAnchor, M as MedeoDsl, Mt as TextDelta, N as DslAudit, Nt as TextEdit, O as ApplyVoiceoverInput, Ot as RelationValues, P as DslTransaction, Pt as TextMark, Q as ReplaceDslClipsInput, R as InvalidAtomic, Rt as Track, S as DslLayout, St as FieldPatch, T as createInitialMedeoDsl, Tt as RelationMutation, U as MedeoDslLoroState, V as timeAnchorCodec, W as medeoDslLoroShape, X as DslClipUpdate, Y as ClipSource, Z as MoveDslClipsInput, _ as VideoDraftTimeline, _t as DslMutation, a as toAudioScriptViews, at as tupleHash, b as resolveDslLayout, bt as EntityTables, c as CaptionDisplayCue, ct as CaptionContent, d as VideoDraft, dt as CaptionText, et as DslIdFactory, f as VideoDraftCaptionStyle, ft as Clip, g as VideoDraftPartUnion, gt as DslDiagnostic, h as VideoDraftInput, ht as DeepReadonly, i as AudioScriptView, it as resourceId, j as CreateMedeoDslOptions, jt as StoredFile, k as VoiceoverCaptionInput, kt as ResourceSystem, l as DEFAULT_UNIT_TIME_MS, lt as CaptionSelection, m as VideoDraftContentPartUnion, mt as ContainNode, n as ImportedVideoDraft, nt as defaultIdFactory, o as VideoDraftProjection, ot as AudioScript, p as VideoDraftContent, pt as ContainMutation, q as AddDslClip, r as fromVideoDraft, rt as relationId, s as toVideoDraft, st as Caption, t as FromVideoDraftOptions, tt as EntityIdKind, u as VideoCreationSettings, ut as CaptionStyle, v as VideoDraftTrack, vt as EntityMutation, w as DslTrackLayout, wt as Media, x as DslClipLayout, xt as EntityValues, y as VideoDraftTrackItem, yt as EntityTable, z as captionContentCodec, zt as TrackRole } from "./index-DuM7I4Ku.js";
+import { $ as ClipPlacement, A as VoiceoverResult, At as RichTextSnapshot, B as isInvalidAtomic, Bt as Voice, C as DslProjectionError, Ct as MedeoDslSnapshot, D as UploadText, Dt as RelationTables, E as DslEditor, Et as RelationTable, F as UnsupportedDocumentFormatError, Ft as TextMutation, G as CommitOptions, H as MedeoDslDraft, I as assertDslDocument, It as TextRun, J as AddDslClipsInput, K as OpActor, L as documentFormat, Lt as TimeAnchor, M as MedeoDsl, Mt as TextDelta, N as DslAudit, Nt as TextEdit, O as ApplyVoiceoverInput, Ot as RelationValues, P as DslTransaction, Pt as TextMark, Q as ReplaceDslClipsInput, R as InvalidAtomic, Rt as Track, S as DslLayout, St as FieldPatch, T as createInitialMedeoDsl, Tt as RelationMutation, U as MedeoDslLoroState, V as timeAnchorCodec, W as medeoDslLoroShape, X as DslClipUpdate, Y as ClipSource, Z as MoveDslClipsInput, _ as VideoDraftTimeline, _t as DslMutation, a as toAudioScriptViews, at as tupleHash, b as resolveDslLayout, bt as EntityTables, c as CaptionDisplayCue, ct as CaptionContent, d as VideoDraft, dt as CaptionText, et as DslIdFactory, f as VideoDraftCaptionStyle, ft as Clip, g as VideoDraftPartUnion, gt as DslDiagnostic, h as VideoDraftInput, ht as DeepReadonly, i as AudioScriptView, it as resourceId, j as CreateMedeoDslOptions, jt as StoredFile, k as VoiceoverCaptionInput, kt as ResourceSystem, l as DEFAULT_UNIT_TIME_MS, lt as CaptionSelection, m as VideoDraftContentPartUnion, mt as ContainNode, n as ImportedVideoDraft, nt as defaultIdFactory, o as VideoDraftProjection, ot as AudioScript, p as VideoDraftContent, pt as ContainMutation, q as AddDslClip, r as fromVideoDraft, rt as relationId, s as toVideoDraft, st as Caption, t as FromVideoDraftOptions, tt as EntityIdKind, u as VideoCreationSettings, ut as CaptionStyle, v as VideoDraftTrack, vt as EntityMutation, w as DslTrackLayout, wt as Media, x as DslClipLayout, xt as EntityValues, y as VideoDraftTrackItem, yt as EntityTable, z as captionContentCodec, zt as TrackRole } from "./index-B1Lqm_Z1.js";
 export { type AddDslClip, type AddDslClipsInput, type ApplyVoiceoverInput, type AudioScript, type AudioScriptView, type Caption, type CaptionContent, type CaptionDisplayCue, type CaptionSelection, type CaptionStyle, type CaptionText, type Clip, type ClipPlacement, type ClipSource, type CommitOptions, type ContainMutation, type ContainNode, type CreateMedeoDslOptions, DEFAULT_UNIT_TIME_MS, type DeepReadonly, type DslAudit, type DslClipLayout, type DslClipUpdate, type DslDiagnostic, DslEditor, type DslIdFactory, type DslLayout, type DslMutation, DslProjectionError, type DslTrackLayout, type DslTransaction, type EntityIdKind, type EntityMutation, type EntityTable, type EntityTables, type EntityValues, type FieldPatch, type FromVideoDraftOptions, type ImportedVideoDraft, type InvalidAtomic, MedeoDsl, type MedeoDslDraft, type MedeoDslLoroState, type MedeoDslSnapshot, type Media, type MoveDslClipsInput, type OpActor, type RelationMutation, type RelationTable, type RelationTables, type RelationValues, type ReplaceDslClipsInput, type ResourceSystem, type RichTextSnapshot, type StoredFile, type TextDelta, type TextEdit, type TextMark, type TextMutation, type TextRun, type TimeAnchor, type Track, type TrackRole, UnsupportedDocumentFormatError, type UploadText, type VideoCreationSettings, type VideoDraft, type VideoDraftCaptionStyle, type VideoDraftContent, type VideoDraftContentPartUnion, type VideoDraftInput, type VideoDraftPartUnion, type VideoDraftProjection, type VideoDraftTimeline, type VideoDraftTrack, type VideoDraftTrackItem, type Voice, type VoiceoverCaptionInput, type VoiceoverResult, assertDslDocument, captionContentCodec, createInitialMedeoDsl, defaultIdFactory, documentFormat, fromVideoDraft, isInvalidAtomic, medeoDslLoroShape, relationId, resolveDslLayout, resourceId, timeAnchorCodec, toAudioScriptViews, toVideoDraft, tupleHash };

package/dist/dsl.js

@@ -1,2 +1,2 @@
-import { _ as defaultIdFactory, a as DslEditor, b as tupleHash, c as UnsupportedDocumentFormatError, d as medeoDslLoroShape, f as captionContentCodec, g as DslProjectionError, h as resolveDslLayout, i as createInitialMedeoDsl, l as assertDslDocument, m as timeAnchorCodec, n as toVideoDraft, o as toAudioScriptViews, p as isInvalidAtomic, r as DEFAULT_UNIT_TIME_MS, s as MedeoDsl, t as fromVideoDraft, u as documentFormat, v as relationId, y as resourceId } from "./dsl-Cpk8WxcZ.js";
+import { _ as DslProjectionError, a as DslEditor, b as resourceId, c as UnsupportedDocumentFormatError, d as documentFormat, f as medeoDslLoroShape, g as resolveDslLayout, h as timeAnchorCodec, i as createInitialMedeoDsl, l as assertDslDocument, m as isInvalidAtomic, n as toVideoDraft, o as toAudioScriptViews, p as captionContentCodec, r as DEFAULT_UNIT_TIME_MS, s as MedeoDsl, t as fromVideoDraft, v as defaultIdFactory, x as tupleHash, y as relationId } from "./dsl-BngbR2zr.js";
 export { DEFAULT_UNIT_TIME_MS, DslEditor, DslProjectionError, MedeoDsl, UnsupportedDocumentFormatError, assertDslDocument, captionContentCodec, createInitialMedeoDsl, defaultIdFactory, documentFormat, fromVideoDraft, isInvalidAtomic, medeoDslLoroShape, relationId, resolveDslLayout, resourceId, timeAnchorCodec, toAudioScriptViews, toVideoDraft, tupleHash };