@mengine/medeo-client 2.1.1-dsl.22 → 2.1.1-dsl.24

package/README.md

@@ -16,16 +16,14 @@ const [clipId] = session.editor.addClips({
 session.editor.setClipVolume(clipId, -3, { actor: { user_id: userId, role: 'user' } });
 await session.waitForServerAck(); // Local completion is separate from durable confirmation.
 const { content, diagnostics } = session.projectVideoDraft();
-session.destroy();
+await session.close();
 ```
 
 `start()`, `snapshot()` and subscription events expose `MedeoDslSnapshot`. `session.dsl` exposes controlled `transact`/`applyMutations`; ordinary business callers use `session.editor`. Rich text uses the native text adapter. `readonlyMode` blocks editing and Undo/Redo. Closing a session also invalidates captured editor/document references.
 
-For explicit synchronization, use `ManualSyncDoc.open({client, peerId})`, then `pull()`, `editor`, `push()` and `dispose()`. Both lifecycles use the same binary snapshot/update and version-coverage contracts. Neither silently upgrades old documents or overwrites an incompatible cache.
-
 ## Local persistence
 
-Browser hosts can inject `IndexedDBDocStorage` through `localStorage`. An optional `initialSnapshot` merges a freshly fetched server snapshot into that storage before DocManager loads it; it never replaces locally saved, unconfirmed edits. The host can require a successful online fetch before constructing the session.
+Browser hosts can inject `IndexedDBDocStorage` through `localStorage`. An optional `initialSnapshot` merges a freshly fetched server snapshot into that storage before DocManager loads it; it never replaces locally saved, unconfirmed edits. The incoming snapshot and combined local history are format-checked before the merge is persisted. The host can require a successful online fetch before constructing the session.
 
 `getLocalSaveState()` / `subscribeLocalSaveState()` report `{ status: 'saving' | 'saved' | 'failed', error }` for this session's local commits. This is separate from `getSyncState()` and server confirmation. The storage adapter determines durability: IndexedDB resolves only after its transaction commits; MemoryDocStorage remains in memory. Failed saves retain their causal order and retry without blocking other documents.
 
@@ -37,6 +35,8 @@ Edits received from another local-storage peer also remain unconfirmed until cov
 
 Reopening uses the stored Loro history and the server's version vector to derive missing updates, without replaying semantic operations or their external side effects. Undo history remains limited to the current session.
 
+For explicit synchronization, use `ManualSyncDoc.open({client, peerId})`, then `pull()`, `editor`, `push()` and `dispose()`. Both lifecycles use the same binary snapshot/update and version-coverage contracts. Neither silently upgrades old documents or overwrites an incompatible cache.
+
 ## Editing and conversion
 
 - Track: create, reorder, hide and delete.
@@ -126,7 +126,7 @@ Each handle owns one long-lived Mirror. Ordinary fields and Tree read from its i
 
 Mirror 2.3.3 cannot safely move an existing node under a parent created in the same draft. The document transaction rejects this combination before writing. When a business Action actually needs it, implement its scoped native path with one audited commit as specified by [K03](../../docs/projects/medeo-dsl/known-unfixed.md#k03-mirror-同批新建父节点并移入已有节点); that fallback is not implemented yet.
 
-Loro 1.16.1 and loro-mirror 2.3.3 are the lockfile baseline. Mirror is pinned with a [workspace dependency patch](../../patches/README.md): its optional `setState(..., {applyNative})` hook runs after the ordinary draft reaches Loro and before one commit. The full native event updates Mirror before DSL subscribers are notified. The hook is internal to the DSL adapter; Actions never receive a native-write callback. It supports non-ephemeral Mirror instances, and must not commit/export/import or await. A registry install of loro-mirror never carries the patch, so the published package bundles the patched Mirror, runtime and declarations; consumers install only the `loro-crdt` peer and configure no patch. Transactions probe the Mirror once and refuse to write when the hook is missing rather than drop native edits. Native writes preserve marks and actual container identities; a plain Mirror string snapshot still does not contain rich-text marks. Tests cover snapshot/update round trips, concurrent moves and replacements, field merging, optional reset, malformed codecs, deletion/recreation, rich text, Cursor ownership, subscriptions and Action failure preflight. The conversion library is implemented; production server/editor/player entry points have not switched.
+Loro 1.16.1 and loro-mirror 2.3.3 are the lockfile baseline. Mirror is pinned with a [workspace dependency patch](../../patches/README.md): its optional `setState(..., {applyNative})` hook runs after the ordinary draft reaches Loro and before one commit. The full native event updates Mirror before DSL subscribers are notified. The hook is internal to the DSL adapter; Actions never receive a native-write callback. It supports non-ephemeral Mirror instances, and must not commit/export/import or await. A registry install of loro-mirror never carries the patch, so the published package bundles the patched Mirror, runtime and declarations; consumers install only the `loro-crdt` peer and configure no patch. Transactions probe the Mirror once and refuse to write when the hook is missing rather than drop native edits. Native writes preserve marks and actual container identities; a plain Mirror string snapshot still does not contain rich-text marks. Tests cover snapshot/update round trips, concurrent moves and replacements, field merging, optional reset, malformed codecs, deletion/recreation, rich text, Cursor ownership, subscriptions and Action failure preflight. The server and current tool/sandbox source entrypoints use DSL documents. Deployment and each external consumer's acceptance are tracked separately in the status document.
 
 Run the package test/build tasks through `vp run @mengine/medeo-client#test` and `vp run @mengine/medeo-client#build`.
 
@@ -158,8 +158,12 @@ Caption text is matched forward in `speech.caption_ids` order. A failed exact ma
 
 ## Legacy consumers
 
-`SemanticEditor`, `VideoDocument`, their adapters and old timeline projection have been removed. `@mengine/medeo-client/legacy` retains only the old EntityTimelineEditor, entity transport and its direct VideoDraft projection. Old entity tool/sandbox imports use this entry until their business adaptation is implemented. The obsolete timeline-journal replay rejects nonempty plans before writing. They cannot open new DSL documents. `/schemas` remains the old tool's schema contract, not the new Editor input model.
+`SemanticEditor`, `VideoDocument`, their adapters and old timeline projection have been removed. `@mengine/medeo-client/legacy` retains only the old EntityTimelineEditor, entity transport and its direct VideoDraft projection. Current medeo-tool/sandbox uses the DSL entrypoints; the legacy entry supports explicitly retained Entity consumers. The obsolete timeline-journal replay rejects nonempty plans before writing. They cannot open new DSL documents. `/schemas` retains the legacy Entity tool schema contract. The current Editor uses the DSL model.
 
 `/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.
+
+### PhoneticScript storage cutover
+
+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).

package/dist/{dsl-B7-4dMjr.js → dsl-Bvv_51Ns.js}

@@ -1,4 +1,4 @@
-import { $ as assertEntityPatch, A as getRootContainerByType, B as isValueOfContainerType, C as applyEncode, D as decodeNestedJsonValues, E as containerIdToContainerType, F as isArrayLike, G as tryUpdateToContainer, H as schemaToContainerType, I as isObject, J as getChildContainerSchema, K as valuesEqual, L as isObjectLike, M as hasTransform, N as inferContainerTypeFromValue, O as deepEqual, P as insertChildToMap, Q as assertEntity, R as isStateAndSchemaOfType, S as applyDecode, T as cidsEqual, U as stripUndefined, V as safeStringify, W as tryInferContainerType, X as getMapFieldSchema, Y as getChildSchema, Z as assertCaptionContent, _ as isLoroMovableListSchema, _t as resourceId, at as assertTimeAnchor, b as schemaContainsIgnoreField, c as isInvalidAtomic, ct as isRecord, d as schema, dt as relationTables, et as assertId, f as getDefaultValue, ft as validLanguage, g as isLoroMapSchema, gt as relationId, h as isLoroListSchema, ht as defaultIdFactory, it as assertScriptSegment, j as hardenCidDescriptors, k as defineCidProperty, l as phonemeCodec, lt as mergeFields, m as isListLikeSchema, mt as assertResourceIdentity, n as textStyles, nt as assertPhoneticScript, o as medeoDslLoroShape, ot as atomicFields, p as isContainerSchema, pt as assertRelationIdentity, q as CID_KEY, rt as assertRelation, s as captionContentCodec, st as entityTables, t as DEFAULT_UNIT_TIME_MS, tt as assertPhoneme, ut as patchRow, v as isLoroTreeSchema, w as applySchemaToInferOptions, x as validateSchema, y as isRootSchemaType, z as isTreeID } from "./video-draft-types-BfIXM8q3.js";
+import { $ as assertCaptionContent, A as deepEqual, B as isStateAndSchemaOfType, C as validateSchema, D as cidsEqual, E as applySchemaToInferOptions, F as inferContainerTypeFromValue, G as stripUndefined, H as isValueOfContainerType, I as insertChildToMap, J as valuesEqual, K as tryInferContainerType, L as isArrayLike, M as getRootContainerByType, N as hardenCidDescriptors, O as containerIdToContainerType, P as hasTransform, Q as getMapFieldSchema, R as isObject, S as schemaContainsIgnoreField, T as applyEncode, U as safeStringify, V as isTreeID, W as schemaToContainerType, X as getChildContainerSchema, Y as CID_KEY, Z as getChildSchema, _ as isLoroListSchema, _t as assertRelationIdentity, a as assertPhoneticBindingFormat, at as assertPhoneticScript, b as isLoroTreeSchema, bt as relationId, c as captionContentCodec, ct as assertSeqMarker, d as phoneticBindingCodec, dt as entityTables, et as assertEntity, ft as isRecord, g as isListLikeSchema, gt as validLanguage, h as isContainerSchema, ht as relationTables, it as assertPhonemeScript, j as defineCidProperty, k as decodeNestedJsonValues, l as isInvalidAtomic, lt as assertTimeAnchor, m as getDefaultValue, mt as patchRow, n as textStyles, nt as assertId, ot as assertRelation, p as schema, pt as mergeFields, q as tryUpdateToContainer, rt as assertPhoneme, s as medeoDslLoroShape, st as assertScriptSegment, t as DEFAULT_UNIT_TIME_MS, tt as assertEntityPatch, u as phonemeCodec, ut as atomicFields, v as isLoroMapSchema, vt as assertResourceIdentity, w as applyDecode, x as isRootSchemaType, xt as resourceId, y as isLoroMovableListSchema, yt as defaultIdFactory, z as isObjectLike } from "./video-draft-types-DRGBN0we.js";
 import { Cursor, LoroDoc, LoroList, LoroMap, LoroMovableList, LoroText, LoroTree, isContainer, isContainerId } from "loro-crdt";
 import { Immer, setAutoFreeze } from "immer";
 //#region ../medeo-dsl/src/text.ts
@@ -311,6 +311,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) {
@@ -326,6 +383,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;
@@ -340,25 +398,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
@@ -594,15 +644,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);
@@ -890,7 +936,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
 		}
@@ -3905,6 +3952,54 @@ function mergeInitialIntoBaseWithSchema(base, init, rootSchema) {
 	}
 }
 //#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) {
@@ -3988,6 +4083,7 @@ function referenceTargets(table, row) {
 	}
 }
 function readMedeoDsl(doc, state) {
+	const logical = logicalDslState(state);
 	const diagnostics = [];
 	const diagnostic = (code, path, error) => diagnostics.push({
 		code,
@@ -3997,7 +4093,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] ?? []) {
@@ -4503,7 +4599,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"] ?? []);
@@ -4580,8 +4680,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. */
@@ -4773,6 +4876,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) {
@@ -4781,6 +4893,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];
@@ -4820,6 +4933,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") {
@@ -4838,12 +4953,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));
 			}
 		}
 	});
@@ -4890,7 +5014,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
 		});
@@ -4929,6 +5053,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,
@@ -4992,6 +5117,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.
@@ -5024,13 +5154,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 {
@@ -5045,6 +5169,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;
@@ -5769,8 +5902,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 = {

package/dist/dsl.d.ts

@@ -1,3 +1,3 @@
-import { $ as TextMutation, A as DeepReadonly, C as CaptionContent, D as Clip, E as CaptionText, F as EntityTables, G as ResourceSystem, H as RelationTable, I as EntityValues, K as RichTextSnapshot, L as FieldPatch, M as DslMutation, N as EntityMutation, O as ContainMutation, P as EntityTable, Q as TextMark, R as MedeoDslSnapshot, S as Caption, T as CaptionStyle, U as RelationTables, V as RelationMutation, W as RelationValues, X as TextDelta, Y as StoredFile, Z as TextEdit, _ as defaultIdFactory, a as VideoDraftCaptionStyle, b as tupleHash, c as VideoDraftInput, d as VideoDraftTrack, et as TextRun, f as VideoDraftTrackItem, g as EntityIdKind, h as DslIdFactory, i as VideoDraft, it as Voice, j as DslDiagnostic, k as ContainNode, l as VideoDraftPartUnion, m as OpActor, n as DEFAULT_UNIT_TIME_MS, nt as Track, o as VideoDraftContent, p as CommitOptions, r as VideoCreationSettings, rt as TrackRole, s as VideoDraftContentPartUnion, t as CaptionDisplayCue, tt as TimeAnchor, u as VideoDraftTimeline, v as relationId, w as CaptionSelection, x as AudioScript, y as resourceId, z as Media } from "./video-draft-types-0J2vfXBu.js";
-import { A as MedeoDslDraft, C as UnsupportedDocumentFormatError, D as captionContentCodec, E as InvalidAtomic, F as ClipSource, I as DslClipUpdate, L as MoveDslClipsInput, M as medeoDslLoroShape, N as AddDslClip, O as isInvalidAtomic, P as AddDslClipsInput, R as ReplaceDslClipsInput, S as DslTransaction, T as documentFormat, _ as VoiceoverCaptionInput, a as toAudioScriptViews, b as MedeoDsl, c as resolveDslLayout, d as DslProjectionError, f as DslTrackLayout, g as ApplyVoiceoverInput, h as UploadText, i as AudioScriptView, j as MedeoDslLoroState, k as timeAnchorCodec, l as DslClipLayout, m as DslEditor, n as ImportedVideoDraft, o as VideoDraftProjection, p as createInitialMedeoDsl, r as fromVideoDraft, s as toVideoDraft, t as FromVideoDraftOptions, u as DslLayout, v as VoiceoverResult, w as assertDslDocument, x as DslAudit, y as CreateMedeoDslOptions, z as ClipPlacement } from "./index-DVmvFhEn.js";
+import { $ as TextMark, A as DeepReadonly, C as CaptionContent, D as Clip, E as CaptionText, F as EntityTables, G as RelationValues, H as RelationMutation, I as EntityValues, K as ResourceSystem, L as FieldPatch, M as DslMutation, N as EntityMutation, O as ContainMutation, P as EntityTable, Q as TextEdit, R as MedeoDslSnapshot, S as Caption, T as CaptionStyle, U as RelationTable, W as RelationTables, X as StoredFile, Z as TextDelta, _ as defaultIdFactory, a as VideoDraftCaptionStyle, at as Voice, b as tupleHash, c as VideoDraftInput, d as VideoDraftTrack, et as TextMutation, f as VideoDraftTrackItem, g as EntityIdKind, h as DslIdFactory, i as VideoDraft, it as TrackRole, j as DslDiagnostic, k as ContainNode, l as VideoDraftPartUnion, m as OpActor, n as DEFAULT_UNIT_TIME_MS, nt as TimeAnchor, o as VideoDraftContent, p as CommitOptions, q as RichTextSnapshot, r as VideoCreationSettings, rt as Track, s as VideoDraftContentPartUnion, t as CaptionDisplayCue, tt as TextRun, u as VideoDraftTimeline, v as relationId, w as CaptionSelection, x as AudioScript, y as resourceId, z as Media } from "./video-draft-types-slnHaNs9.js";
+import { A as MedeoDslDraft, C as UnsupportedDocumentFormatError, D as captionContentCodec, E as InvalidAtomic, F as ClipSource, I as DslClipUpdate, L as MoveDslClipsInput, M as medeoDslLoroShape, N as AddDslClip, O as isInvalidAtomic, P as AddDslClipsInput, R as ReplaceDslClipsInput, S as DslTransaction, T as documentFormat, _ as VoiceoverCaptionInput, a as toAudioScriptViews, b as MedeoDsl, c as resolveDslLayout, d as DslProjectionError, f as DslTrackLayout, g as ApplyVoiceoverInput, h as UploadText, i as AudioScriptView, j as MedeoDslLoroState, k as timeAnchorCodec, l as DslClipLayout, m as DslEditor, n as ImportedVideoDraft, o as VideoDraftProjection, p as createInitialMedeoDsl, r as fromVideoDraft, s as toVideoDraft, t as FromVideoDraftOptions, u as DslLayout, v as VoiceoverResult, w as assertDslDocument, x as DslAudit, y as CreateMedeoDslOptions, z as ClipPlacement } from "./index-CmuDB_Gm.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,3 +1,3 @@
-import { _t as resourceId, a as documentFormat, c as isInvalidAtomic, gt as relationId, ht as defaultIdFactory, i as assertDslDocument, o as medeoDslLoroShape, r as UnsupportedDocumentFormatError, s as captionContentCodec, t as DEFAULT_UNIT_TIME_MS, u as timeAnchorCodec, vt as tupleHash } from "./video-draft-types-BfIXM8q3.js";
-import { a as toAudioScriptViews, c as DslProjectionError, i as DslEditor, n as toVideoDraft, o as MedeoDsl, r as createInitialMedeoDsl, s as resolveDslLayout, t as fromVideoDraft } from "./dsl-B7-4dMjr.js";
+import { St as tupleHash, bt as relationId, c as captionContentCodec, f as timeAnchorCodec, i as assertDslDocument, l as isInvalidAtomic, o as documentFormat, r as UnsupportedDocumentFormatError, s as medeoDslLoroShape, t as DEFAULT_UNIT_TIME_MS, xt as resourceId, yt as defaultIdFactory } from "./video-draft-types-DRGBN0we.js";
+import { a as toAudioScriptViews, c as DslProjectionError, i as DslEditor, n as toVideoDraft, o as MedeoDsl, r as createInitialMedeoDsl, s as resolveDslLayout, t as fromVideoDraft } from "./dsl-Bvv_51Ns.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 };

package/dist/{index-CcNkkQll.d.ts → index-BGEcTwoD.d.ts}

@@ -1,6 +1,6 @@
-import { G as ResourceSystem, R as MedeoDslSnapshot, rt as TrackRole } from "./video-draft-types-0J2vfXBu.js";
-import { b as MedeoDsl, h as UploadText, i as AudioScriptView, m as DslEditor, o as VideoDraftProjection } from "./index-DVmvFhEn.js";
-import { _ as ManualSyncTransport, a as MengineDocSessionOptions, g as ManualSyncDocOptions, n as DocumentSession, r as DocumentSessionUpdateEvent } from "./index-D4Bgukns.js";
+import { K as ResourceSystem, R as MedeoDslSnapshot, it as TrackRole } from "./video-draft-types-slnHaNs9.js";
+import { b as MedeoDsl, h as UploadText, i as AudioScriptView, m as DslEditor, o as VideoDraftProjection } from "./index-CmuDB_Gm.js";
+import { P as MengineDraftResponse, _ as ManualSyncTransport, a as MengineDocSessionOptions, g as ManualSyncDocOptions, n as DocumentSession, r as DocumentSessionUpdateEvent } from "./index-BOgr8p8C.js";
 
 //#region src/manual-sync/manual-sync-doc.d.ts
 /** Explicit synchronization over the same DSL/editor used by the live Session. */
@@ -180,6 +180,8 @@ declare class ManualSyncDoc extends ManualSyncTransport {
     }[];
   };
   projectVideoDraft(): VideoDraftProjection;
+  /** Read the acknowledged server revision; without a new push, confirm against the current server view. */
+  readPersistedDraft(updateSeq?: number): Promise<MengineDraftResponse>;
   dispose(): void;
 }
 //#endregion

package/dist/{index-D4Bgukns.d.ts → index-BOgr8p8C.d.ts}

@@ -1,4 +1,4 @@
-import { j as DslDiagnostic, o as VideoDraftContent, p as CommitOptions } from "./video-draft-types-0J2vfXBu.js";
+import { j as DslDiagnostic, o as VideoDraftContent, p as CommitOptions } from "./video-draft-types-slnHaNs9.js";
 import { LoroDoc, PeerID, VersionVector } from "loro-crdt";
 import { DocState, LocalSaveState } from "@mengine/sync";
 import { BaseDocStorage, Connection, DocDiff, DocPushReceipt, DocSnapshotRecord, DocStorage, DocStorageOptions, DocUpdate, DocUpdateRecord } from "@mengine/storage";
@@ -255,7 +255,7 @@ type PushResultKind = 'ack' | 'duplicate' | 'rejected' | 'failed' | 'nothing_to_
  */
 interface PushResult {
   kind: PushResultKind;
-  /** Server document sequence observed after a successful `ack` or `duplicate`. */
+  /** Server sequence from an `ack`/`duplicate`, retained on an idle retry so its revision can be verified. */
   mengineUpdateSeq?: number | undefined;
   /** @deprecated Ack-only sequence retained until consumers adopt `mengineUpdateSeq`. */
   updateSeq?: number | undefined;
@@ -301,10 +301,12 @@ interface ManualSyncDocOptions {
 }
 /** Shared explicit pull/push lifecycle; model-specific editors never implement transport. */
 declare class ManualSyncTransport {
-  private readonly client;
+  protected readonly client: MengineHttpClient;
   protected readonly doc: LoroDoc;
   private watermark;
   private disposed;
+  /** A retry with no new bytes still verifies the revision from its last durable receipt. */
+  private confirmedSequence?;
   protected constructor(client: MengineHttpClient, doc: LoroDoc, watermark: VersionVector);
   editorPeerId(): PeerID;
   protected assertActive(): void;
@@ -581,6 +583,7 @@ type DocumentSessionModel<Snapshot, Editor, Document> = (doc: LoroDoc, guard: Do
 declare class DocumentSession<Snapshot, Editor, Document> {
   private readonly options;
   private readonly model;
+  private readonly validateDocument;
   private readonly docId;
   private readonly local;
   private readonly server;
@@ -607,7 +610,7 @@ declare class DocumentSession<Snapshot, Editor, Document> {
    * doc (e.g. nothing was edited since the last confirmed push).
    */
   private serverVVValue;
-  constructor(options: MengineDocSessionOptions, model: DocumentSessionModel<Snapshot, Editor, Document>);
+  constructor(options: MengineDocSessionOptions, model: DocumentSessionModel<Snapshot, Editor, Document>, validateDocument: (doc: LoroDoc) => void);
   /**
    * Observe every push verdict, including `duplicate` and failures.
    *

package/dist/{index-DVmvFhEn.d.ts → index-CmuDB_Gm.d.ts}

@@ -1,4 +1,4 @@
-import { B as PhonemeSelection, J as SegmentSelection, L as FieldPatch, M as DslMutation, R as MedeoDslSnapshot, T as CaptionStyle, Y as StoredFile, Z as TextEdit, c as VideoDraftInput, h as DslIdFactory, it as Voice, j as DslDiagnostic, o as VideoDraftContent, p as CommitOptions, q as SegmentRange, rt as TrackRole, tt as TimeAnchor, w as CaptionSelection, z as Media } from "./video-draft-types-0J2vfXBu.js";
+import { B as PhonemeSelection, J as SegmentRange, L as FieldPatch, M as DslMutation, Q as TextEdit, R as MedeoDslSnapshot, T as CaptionStyle, V as PhoneticScript, X as StoredFile, Y as SegmentSelection, at as Voice, c as VideoDraftInput, h as DslIdFactory, it as TrackRole, j as DslDiagnostic, nt as TimeAnchor, o as VideoDraftContent, p as CommitOptions, w as CaptionSelection, z as Media } from "./video-draft-types-slnHaNs9.js";
 import { ContainerType, Cursor, LoroDoc, PeerID, TreeID } from "loro-crdt";
 
 //#region src/dsl/action-context.d.ts
@@ -483,20 +483,12 @@ declare const medeoDslLoroShape: RootSchemaType<{
     options: {};
   };
   'phonetic-script-entities': LoroMapSchemaWithCatchall<{}, LoroMapSchema<{
-    phoneme: /*elided*/any;
-    system: /*elided*/any;
-    key: /*elided*/any;
-    storageKey: /*elided*/any;
-    digest: /*elided*/any;
+    binding: /*elided*/any;
   }> & {
     options: {};
   } & {
     catchall: <C extends SchemaType>(catchallSchema: C) => LoroMapSchemaWithCatchall<{
-      phoneme: /*elided*/any;
-      system: /*elided*/any;
-      key: /*elided*/any;
-      storageKey: /*elided*/any;
-      digest: /*elided*/any;
+      binding: /*elided*/any;
     }, C>;
   }> & {
     options: {};
@@ -589,8 +581,9 @@ type ContainDraftNode = Omit<Input['contain-relations'][number], 'id' | 'childre
   children: ContainDraftNode[];
 };
 type DraftFields<T> = T extends Cursor ? T : T extends (infer Item)[] ? DraftFields<Item>[] : T extends object ? { [K in keyof T as undefined extends T[K] ? never : K]: DraftFields<T[K]> } & { [K in keyof T as undefined extends T[K] ? K : never]?: DraftFields<T[K]> } : T;
-type MedeoDslDraft = DraftFields<Omit<Input, 'contain-relations'>> & {
+type MedeoDslDraft = DraftFields<Omit<Input, 'contain-relations' | 'phonetic-script-entities'>> & {
   'contain-relations': ContainDraftNode[];
+  'phonetic-script-entities': Record<string, PhoneticScript>;
 };
 //#endregion
 //#region ../medeo-dsl/src/schema/codec.d.ts
@@ -614,7 +607,7 @@ declare const captionContentCodec: AtomicCodec<SegmentSelection>;
 declare function documentFormat(doc: LoroDoc): 'dsl' | 'legacy' | 'mixed' | 'unknown';
 declare class UnsupportedDocumentFormatError extends Error {
   readonly code = "unsupported_document_format";
-  constructor();
+  constructor(message?: string);
 }
 /** Run after initial import, before opening an editable handle. Empty new documents still have one Timeline. */
 declare function assertDslDocument(doc: LoroDoc): void;
@@ -691,6 +684,8 @@ declare class MedeoDsl {
   applyMutations(mutations: readonly DslMutation[], audit: DslAudit): void;
   editText(scriptId: string, segmentId: string, expectedBodyId: string, edits: readonly TextEdit[], audit: DslAudit): void;
   editCaptionText(captionId: string, expectedBodyId: string, edits: readonly TextEdit[], audit: DslAudit): void;
+  /** Check the session's write capability before an Action starts host-owned resource I/O. */
+  assertWritable(): void;
   /**
    * A run inside one segment as native Cursors. Local ranges exclude insertions at their start and
    * include insertions at their end. K01 remains deferred.
@@ -698,6 +693,7 @@ declare class MedeoDsl {
   textRange(scriptId: string, segmentId: string, start: number, end: number): SegmentSelection;
   dispose(): void;
   private mutate;
+  private assertReadyToWrite;
   private notify;
   private assertActive;
 }

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { $ as TextMutation, A as DeepReadonly, C as CaptionContent, D as Clip, E as CaptionText, F as EntityTables, G as ResourceSystem, H as RelationTable, I as EntityValues, K as RichTextSnapshot, L as FieldPatch, M as DslMutation, N as EntityMutation, O as ContainMutation, P as EntityTable, Q as TextMark, R as MedeoDslSnapshot, S as Caption, T as CaptionStyle, U as RelationTables, V as RelationMutation, W as RelationValues, X as TextDelta, Y as StoredFile, Z as TextEdit, _ as defaultIdFactory, a as VideoDraftCaptionStyle, b as tupleHash, c as VideoDraftInput, d as VideoDraftTrack, et as TextRun, f as VideoDraftTrackItem, g as EntityIdKind, h as DslIdFactory, i as VideoDraft, it as Voice, j as DslDiagnostic, k as ContainNode, l as VideoDraftPartUnion, m as OpActor, n as DEFAULT_UNIT_TIME_MS, nt as Track, o as VideoDraftContent, p as CommitOptions, r as VideoCreationSettings, rt as TrackRole, s as VideoDraftContentPartUnion, t as CaptionDisplayCue, tt as TimeAnchor, u as VideoDraftTimeline, v as relationId, w as CaptionSelection, x as AudioScript, y as resourceId, z as Media } from "./video-draft-types-0J2vfXBu.js";
-import { A as MedeoDslDraft, C as UnsupportedDocumentFormatError, D as captionContentCodec, E as InvalidAtomic, F as ClipSource, I as DslClipUpdate, L as MoveDslClipsInput, M as medeoDslLoroShape, N as AddDslClip, O as isInvalidAtomic, P as AddDslClipsInput, R as ReplaceDslClipsInput, S as DslTransaction, T as documentFormat, _ as VoiceoverCaptionInput, a as toAudioScriptViews, b as MedeoDsl, c as resolveDslLayout, d as DslProjectionError, f as DslTrackLayout, g as ApplyVoiceoverInput, h as UploadText, i as AudioScriptView, j as MedeoDslLoroState, k as timeAnchorCodec, l as DslClipLayout, m as DslEditor, n as ImportedVideoDraft, o as VideoDraftProjection, p as createInitialMedeoDsl, r as fromVideoDraft, s as toVideoDraft, t as FromVideoDraftOptions, u as DslLayout, v as VoiceoverResult, w as assertDslDocument, x as DslAudit, y as CreateMedeoDslOptions, z as ClipPlacement } from "./index-DVmvFhEn.js";
-import { A as MenginePushRejectedError, B as MengineSyncResponse, C as PushResult, D as MengineHttpClient, E as readMengineEventStream, F as MenginePushResponse, H as base64ToBytes, I as MenginePushUpdateResponse, L as MengineRejectedResponse, M as MengineAuditResponse, N as MengineDocumentVersion, O as MengineHttpClientOptions, P as MengineDraftResponse, R as MengineSnapshotResponse, S as PullResult, T as MengineEventStreamOptions, U as bytesToBase64, V as MengineUpdateMeta, a as MengineDocSessionOptions, b as DocVersionMark, c as WaitForLocalSaveOptions, d as MengineUndoState, f as MedeoHttpDocStorage, g as ManualSyncDocOptions, h as PushOutcomeKind, i as MengineAckFailedError, j as MengineAuditEntry, k as MengineHttpRequestError, l as WaitForServerAckOptions, m as PushOutcome, o as MengineDocSyncState, p as MedeoHttpDocStorageOptions, s as MengineLocalSaveState, t as MemoryDocStorage, u as DocStorageLike, v as decodeDocVersionMark, w as PushResultKind, x as PullFailureReason, y as encodeDocVersionMark, z as MengineSseUpdateEvent } from "./index-D4Bgukns.js";
-import { n as MengineDocSessionUpdateEvent, r as ManualSyncDoc, t as MengineDocSession } from "./index-CcNkkQll.js";
+import { $ as TextMark, A as DeepReadonly, C as CaptionContent, D as Clip, E as CaptionText, F as EntityTables, G as RelationValues, H as RelationMutation, I as EntityValues, K as ResourceSystem, L as FieldPatch, M as DslMutation, N as EntityMutation, O as ContainMutation, P as EntityTable, Q as TextEdit, R as MedeoDslSnapshot, S as Caption, T as CaptionStyle, U as RelationTable, W as RelationTables, X as StoredFile, Z as TextDelta, _ as defaultIdFactory, a as VideoDraftCaptionStyle, at as Voice, b as tupleHash, c as VideoDraftInput, d as VideoDraftTrack, et as TextMutation, f as VideoDraftTrackItem, g as EntityIdKind, h as DslIdFactory, i as VideoDraft, it as TrackRole, j as DslDiagnostic, k as ContainNode, l as VideoDraftPartUnion, m as OpActor, n as DEFAULT_UNIT_TIME_MS, nt as TimeAnchor, o as VideoDraftContent, p as CommitOptions, q as RichTextSnapshot, r as VideoCreationSettings, rt as Track, s as VideoDraftContentPartUnion, t as CaptionDisplayCue, tt as TextRun, u as VideoDraftTimeline, v as relationId, w as CaptionSelection, x as AudioScript, y as resourceId, z as Media } from "./video-draft-types-slnHaNs9.js";
+import { A as MedeoDslDraft, C as UnsupportedDocumentFormatError, D as captionContentCodec, E as InvalidAtomic, F as ClipSource, I as DslClipUpdate, L as MoveDslClipsInput, M as medeoDslLoroShape, N as AddDslClip, O as isInvalidAtomic, P as AddDslClipsInput, R as ReplaceDslClipsInput, S as DslTransaction, T as documentFormat, _ as VoiceoverCaptionInput, a as toAudioScriptViews, b as MedeoDsl, c as resolveDslLayout, d as DslProjectionError, f as DslTrackLayout, g as ApplyVoiceoverInput, h as UploadText, i as AudioScriptView, j as MedeoDslLoroState, k as timeAnchorCodec, l as DslClipLayout, m as DslEditor, n as ImportedVideoDraft, o as VideoDraftProjection, p as createInitialMedeoDsl, r as fromVideoDraft, s as toVideoDraft, t as FromVideoDraftOptions, u as DslLayout, v as VoiceoverResult, w as assertDslDocument, x as DslAudit, y as CreateMedeoDslOptions, z as ClipPlacement } from "./index-CmuDB_Gm.js";
+import { A as MenginePushRejectedError, B as MengineSyncResponse, C as PushResult, D as MengineHttpClient, E as readMengineEventStream, F as MenginePushResponse, H as base64ToBytes, I as MenginePushUpdateResponse, L as MengineRejectedResponse, M as MengineAuditResponse, N as MengineDocumentVersion, O as MengineHttpClientOptions, P as MengineDraftResponse, R as MengineSnapshotResponse, S as PullResult, T as MengineEventStreamOptions, U as bytesToBase64, V as MengineUpdateMeta, a as MengineDocSessionOptions, b as DocVersionMark, c as WaitForLocalSaveOptions, d as MengineUndoState, f as MedeoHttpDocStorage, g as ManualSyncDocOptions, h as PushOutcomeKind, i as MengineAckFailedError, j as MengineAuditEntry, k as MengineHttpRequestError, l as WaitForServerAckOptions, m as PushOutcome, o as MengineDocSyncState, p as MedeoHttpDocStorageOptions, s as MengineLocalSaveState, t as MemoryDocStorage, u as DocStorageLike, v as decodeDocVersionMark, w as PushResultKind, x as PullFailureReason, y as encodeDocVersionMark, z as MengineSseUpdateEvent } from "./index-BOgr8p8C.js";
+import { n as MengineDocSessionUpdateEvent, r as ManualSyncDoc, t as MengineDocSession } from "./index-BGEcTwoD.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 DocStorageLike, type DocVersionMark, 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, ManualSyncDoc, type ManualSyncDocOptions, MedeoDsl, type MedeoDslDraft, type MedeoDslLoroState, type MedeoDslSnapshot, MedeoHttpDocStorage, type MedeoHttpDocStorageOptions, type Media, MemoryDocStorage, MengineAckFailedError, type MengineAuditEntry, type MengineAuditResponse, MengineDocSession, type MengineDocSessionOptions, type MengineDocSessionUpdateEvent, type MengineDocSyncState, type MengineDocumentVersion, type MengineDraftResponse, type MengineEventStreamOptions, MengineHttpClient, type MengineHttpClientOptions, MengineHttpRequestError, type MengineLocalSaveState, MenginePushRejectedError, type MenginePushResponse, type MenginePushUpdateResponse, type MengineRejectedResponse, type MengineSnapshotResponse, type MengineSseUpdateEvent, type MengineSyncResponse, type MengineUndoState, type MengineUpdateMeta, type MoveDslClipsInput, type OpActor, type PullFailureReason, type PullResult, type PushOutcome, type PushOutcomeKind, type PushResult, type PushResultKind, 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, type WaitForLocalSaveOptions, type WaitForServerAckOptions, assertDslDocument, base64ToBytes, bytesToBase64, captionContentCodec, createInitialMedeoDsl, decodeDocVersionMark, defaultIdFactory, documentFormat, encodeDocVersionMark, fromVideoDraft, isInvalidAtomic, medeoDslLoroShape, readMengineEventStream, relationId, resolveDslLayout, resourceId, timeAnchorCodec, toAudioScriptViews, toVideoDraft, tupleHash };

package/dist/index.js

@@ -1,8 +1,8 @@
 import { n as bytesToBase64, t as base64ToBytes } from "./base64-D-jd-dr5.js";
-import { a as covers, c as readMengineEventStream, d as MenginePushRejectedError, i as openManualDocument, l as MengineHttpClient, n as MedeoHttpDocStorage, o as decodeDocVersionMark, r as ManualSyncTransport, s as encodeDocVersionMark, t as MemoryDocStorage, u as MengineHttpRequestError } from "./storage-BW3tI_ER.js";
-import { _t as resourceId, a as documentFormat, c as isInvalidAtomic, gt as relationId, ht as defaultIdFactory, i as assertDslDocument, o as medeoDslLoroShape, r as UnsupportedDocumentFormatError, s as captionContentCodec, t as DEFAULT_UNIT_TIME_MS, u as timeAnchorCodec, vt as tupleHash } from "./video-draft-types-BfIXM8q3.js";
-import { a as toAudioScriptViews, c as DslProjectionError, i as DslEditor, n as toVideoDraft, o as MedeoDsl, r as createInitialMedeoDsl, s as resolveDslLayout, t as fromVideoDraft } from "./dsl-B7-4dMjr.js";
-import { UndoManager, VersionVector, decodeImportBlobMeta } from "loro-crdt";
+import { a as covers, c as readMengineEventStream, d as MenginePushRejectedError, i as openManualDocument, l as MengineHttpClient, n as MedeoHttpDocStorage, o as decodeDocVersionMark, r as ManualSyncTransport, s as encodeDocVersionMark, t as MemoryDocStorage, u as MengineHttpRequestError } from "./storage-evqvKS4B.js";
+import { St as tupleHash, bt as relationId, c as captionContentCodec, f as timeAnchorCodec, i as assertDslDocument, l as isInvalidAtomic, o as documentFormat, r as UnsupportedDocumentFormatError, s as medeoDslLoroShape, t as DEFAULT_UNIT_TIME_MS, xt as resourceId, yt as defaultIdFactory } from "./video-draft-types-DRGBN0we.js";
+import { a as toAudioScriptViews, c as DslProjectionError, i as DslEditor, n as toVideoDraft, o as MedeoDsl, r as createInitialMedeoDsl, s as resolveDslLayout, t as fromVideoDraft } from "./dsl-Bvv_51Ns.js";
+import { LoroDoc, UndoManager, VersionVector, decodeImportBlobMeta } from "loro-crdt";
 import { ClientServerSynchronizer, DocManager } from "@mengine/sync";
 import { DisposableSet, EventBus } from "@mengine/utils";
 //#region src/manual-sync/manual-sync-doc.ts
@@ -27,6 +27,15 @@ var ManualSyncDoc = class ManualSyncDoc extends ManualSyncTransport {
 	projectVideoDraft() {
 		return toVideoDraft(this.snapshot());
 	}
+	/** Read the acknowledged server revision; without a new push, confirm against the current server view. */
+	async readPersistedDraft(updateSeq) {
+		this.assertActive();
+		const result = updateSeq === void 0 ? await this.client.fetchDraft() : await this.client.fetchDraftAt(updateSeq);
+		this.assertActive();
+		if (updateSeq !== void 0 && result.version.update_seq !== updateSeq) throw new Error("The projected revision does not match the push receipt");
+		if (!covers(VersionVector.decode(base64ToBytes(result.version.server_vv)), this.doc.oplogVersion())) throw new Error("The projected server revision does not hold the local update");
+		return result;
+	}
 	dispose() {
 		this.dsl.dispose();
 		super.dispose();
@@ -209,6 +218,7 @@ var MengineAckFailedError = class extends Error {
 var DocumentSession = class {
 	options;
 	model;
+	validateDocument;
 	docId;
 	local;
 	server;
@@ -235,9 +245,10 @@ var DocumentSession = class {
 	* doc (e.g. nothing was edited since the last confirmed push).
 	*/
 	serverVVValue = null;
-	constructor(options, model) {
+	constructor(options, model, validateDocument) {
 		this.options = options;
 		this.model = model;
+		this.validateDocument = validateDocument;
 		this.mutationGuard = new DocumentMutationGuard(options.readonlyMode);
 		this.docId = options.docId;
 		this.local = options.localStorage ?? new MemoryDocStorage();
@@ -441,6 +452,17 @@ var DocumentSession = class {
 		await this.local.connection.waitForConnected().abortOn(this.lifetime.signal);
 		if (this.destroyed) throw new Error("mengine doc session destroyed");
 		if (this.options.initialSnapshot) {
+			const preview = new LoroDoc();
+			try {
+				if (preview.import(this.options.initialSnapshot).pending) throw new Error("Snapshot has missing dependencies");
+				this.validateDocument(preview);
+				const cached = await this.local.getDoc(this.docId);
+				if (cached && preview.import(cached.data).pending) throw new Error("Cached document has missing dependencies");
+				this.validateDocument(preview);
+			} finally {
+				preview.free();
+			}
+			if (this.destroyed) throw new Error("mengine doc session destroyed");
 			await this.local.pushDocUpdate({
 				docId: this.docId,
 				data: this.options.initialSnapshot
@@ -637,7 +659,7 @@ var MengineDocSession = class extends DocumentSession {
 				subscribe: (listener) => dsl.subscribe(listener),
 				dispose: () => dsl.dispose()
 			};
-		});
+		}, assertDslDocument);
 	}
 	get dsl() {
 		return this.document;

package/dist/legacy.d.ts

@@ -1,5 +1,5 @@
-import { i as VideoDraft, l as VideoDraftPartUnion, o as VideoDraftContent, p as CommitOptions, t as CaptionDisplayCue } from "./video-draft-types-0J2vfXBu.js";
-import { A as MenginePushRejectedError, B as MengineSyncResponse, C as PushResult, D as MengineHttpClient, E as readMengineEventStream, F as MenginePushResponse, H as base64ToBytes, I as MenginePushUpdateResponse, L as MengineRejectedResponse, M as MengineAuditResponse, N as MengineDocumentVersion, O as MengineHttpClientOptions, P as MengineDraftResponse, R as MengineSnapshotResponse, S as PullResult, T as MengineEventStreamOptions, U as bytesToBase64, V as MengineUpdateMeta, _ as ManualSyncTransport, a as MengineDocSessionOptions, b as DocVersionMark, d as MengineUndoState, f as MedeoHttpDocStorage, g as ManualSyncDocOptions, h as PushOutcomeKind, j as MengineAuditEntry, k as MengineHttpRequestError, l as WaitForServerAckOptions, m as PushOutcome, o as MengineDocSyncState, p as MedeoHttpDocStorageOptions, t as MemoryDocStorage, u as DocStorageLike, v as decodeDocVersionMark, w as PushResultKind, x as PullFailureReason, y as encodeDocVersionMark, z as MengineSseUpdateEvent } from "./index-D4Bgukns.js";
+import { i as VideoDraft, l as VideoDraftPartUnion, o as VideoDraftContent, p as CommitOptions, t as CaptionDisplayCue } from "./video-draft-types-slnHaNs9.js";
+import { A as MenginePushRejectedError, B as MengineSyncResponse, C as PushResult, D as MengineHttpClient, E as readMengineEventStream, F as MenginePushResponse, H as base64ToBytes, I as MenginePushUpdateResponse, L as MengineRejectedResponse, M as MengineAuditResponse, N as MengineDocumentVersion, O as MengineHttpClientOptions, P as MengineDraftResponse, R as MengineSnapshotResponse, S as PullResult, T as MengineEventStreamOptions, U as bytesToBase64, V as MengineUpdateMeta, _ as ManualSyncTransport, a as MengineDocSessionOptions, b as DocVersionMark, d as MengineUndoState, f as MedeoHttpDocStorage, g as ManualSyncDocOptions, h as PushOutcomeKind, j as MengineAuditEntry, k as MengineHttpRequestError, l as WaitForServerAckOptions, m as PushOutcome, o as MengineDocSyncState, p as MedeoHttpDocStorageOptions, t as MemoryDocStorage, u as DocStorageLike, v as decodeDocVersionMark, w as PushResultKind, x as PullFailureReason, y as encodeDocVersionMark, z as MengineSseUpdateEvent } from "./index-BOgr8p8C.js";
 import { LoroDoc, PeerID } from "loro-crdt";
 
 //#region ../medeo-dsl/depreacted/sandbox.d.ts

package/dist/legacy.js

@@ -1,6 +1,6 @@
 import { n as bytesToBase64, t as base64ToBytes } from "./base64-D-jd-dr5.js";
-import { c as readMengineEventStream, d as MenginePushRejectedError, i as openManualDocument, l as MengineHttpClient, n as MedeoHttpDocStorage, o as decodeDocVersionMark, r as ManualSyncTransport, s as encodeDocVersionMark, t as MemoryDocStorage, u as MengineHttpRequestError } from "./storage-BW3tI_ER.js";
-import { a as documentFormat, r as UnsupportedDocumentFormatError, t as DEFAULT_UNIT_TIME_MS } from "./video-draft-types-BfIXM8q3.js";
+import { c as readMengineEventStream, d as MenginePushRejectedError, i as openManualDocument, l as MengineHttpClient, n as MedeoHttpDocStorage, o as decodeDocVersionMark, r as ManualSyncTransport, s as encodeDocVersionMark, t as MemoryDocStorage, u as MengineHttpRequestError } from "./storage-evqvKS4B.js";
+import { o as documentFormat, r as UnsupportedDocumentFormatError, t as DEFAULT_UNIT_TIME_MS } from "./video-draft-types-DRGBN0we.js";
 import { u as volumeSchema } from "./shared-iWnU2osE.js";
 import { sha256 } from "@noble/hashes/sha2.js";
 import { LoroDoc, LoroMap, LoroMovableList, LoroText, UndoManager } from "loro-crdt";

package/dist/{storage-BW3tI_ER.js → storage-evqvKS4B.js}

@@ -293,6 +293,8 @@ var ManualSyncTransport = class {
 	doc;
 	watermark;
 	disposed = false;
+	/** A retry with no new bytes still verifies the revision from its last durable receipt. */
+	confirmedSequence;
 	constructor(client, doc, watermark) {
 		this.client = client;
 		this.doc = doc;
@@ -395,7 +397,8 @@ var ManualSyncTransport = class {
 		const localVersion = this.doc.oplogVersion();
 		if (covers(this.watermark, localVersion)) return {
 			kind: "nothing_to_push",
-			collaborated: false
+			collaborated: false,
+			...this.confirmedSequence === void 0 ? {} : { mengineUpdateSeq: this.confirmedSequence }
 		};
 		const update = this.doc.export({
 			mode: "update",
@@ -405,6 +408,7 @@ var ManualSyncTransport = class {
 			const response = await this.client.pushUpdate(update);
 			const serverVV = this.serverVVFrom(response.version?.server_vv);
 			if (serverVV != null) this.watermark = serverVV;
+			this.confirmedSequence = response.version?.update_seq ?? response.update_seq ?? void 0;
 			return {
 				kind: response.kind,
 				mengineUpdateSeq: response.version?.update_seq ?? response.update_seq ?? void 0,

package/dist/testing.d.ts

@@ -1,5 +1,5 @@
-import { i as VideoDraft } from "./video-draft-types-0J2vfXBu.js";
-import { b as MedeoDsl } from "./index-DVmvFhEn.js";
+import { i as VideoDraft } from "./video-draft-types-slnHaNs9.js";
+import { b as MedeoDsl } from "./index-CmuDB_Gm.js";
 import { LoroDoc } from "loro-crdt";
 
 //#region src/testing/in-memory-mengine-server.d.ts
@@ -16,6 +16,7 @@ import { LoroDoc } from "loro-crdt";
 declare class InMemoryMengineServer {
   private readonly doc;
   private readonly updates;
+  private readonly revisions;
   private readonly subscribers;
   private seq;
   private hasSnapshot;
@@ -28,6 +29,7 @@ declare class InMemoryMengineServer {
   readonly fetchImpl: typeof fetch;
   private parsePath;
   private version;
+  private handleDraft;
   private handleSnapshot;
   private handleBootstrap;
   private handleSync;

package/dist/testing.js

@@ -1,6 +1,6 @@
 import { n as bytesToBase64, t as base64ToBytes } from "./base64-D-jd-dr5.js";
-import { a as documentFormat, i as assertDslDocument } from "./video-draft-types-BfIXM8q3.js";
-import { i as DslEditor, n as toVideoDraft, o as MedeoDsl, r as createInitialMedeoDsl } from "./dsl-B7-4dMjr.js";
+import { a as assertPhoneticBindingFormat, i as assertDslDocument, o as documentFormat } from "./video-draft-types-DRGBN0we.js";
+import { i as DslEditor, n as toVideoDraft, o as MedeoDsl, r as createInitialMedeoDsl } from "./dsl-Bvv_51Ns.js";
 import { t as classifyUpdate } from "./loro-relay-doc-Bi6JKqtQ.js";
 import { LoroDoc, VersionVector, encodeFrontiers } from "loro-crdt";
 //#region src/testing/in-memory-mengine-server.ts
@@ -17,6 +17,7 @@ import { LoroDoc, VersionVector, encodeFrontiers } from "loro-crdt";
 var InMemoryMengineServer = class {
 	doc = new LoroDoc();
 	updates = [];
+	revisions = /* @__PURE__ */ new Map();
 	subscribers = /* @__PURE__ */ new Set();
 	seq = 0;
 	hasSnapshot = false;
@@ -40,6 +41,7 @@ var InMemoryMengineServer = class {
 			try {
 				this.doc.import(dsl.doc.export({ mode: "snapshot" }));
 				this.hasSnapshot = true;
+				this.revisions.set(0, this.doc.export({ mode: "snapshot" }));
 				return new Response(await this.handleSnapshot().text(), {
 					status: 201,
 					headers: { "content-type": "application/json" }
@@ -48,24 +50,9 @@ var InMemoryMengineServer = class {
 				dsl.dispose();
 			}
 		}
-		if (path === "draft" && method === "GET") {
-			if (!this.hasSnapshot) return this.handleSnapshot();
-			assertDslDocument(this.doc);
-			const dsl = new MedeoDsl(this.doc);
-			try {
-				return Response.json({
-					...toVideoDraft(dsl.getSnapshot()),
-					version: this.version()
-				});
-			} catch (error) {
-				return Response.json({ error: {
-					code: "projection_unsupported",
-					message: String(error)
-				} }, { status: 422 });
-			} finally {
-				dsl.dispose();
-			}
-		}
+		if (path === "draft" && method === "GET") return this.handleDraft();
+		const revision = /^revisions\/(\d+)\/draft$/.exec(path);
+		if (revision && method === "GET") return this.handleDraft(Number(revision[1]));
 		if (/^\/internal\/mengine\/v1\/docs\/[^/]+\/bootstrap$/.test(new URL(url).pathname) && method === "POST") return this.handleBootstrap(init);
 		if (path.startsWith("sync") && method === "GET") return this.handleSync(url);
 		if (path === "updates" && method === "POST") return this.handlePush(init);
@@ -82,13 +69,37 @@ var InMemoryMengineServer = class {
 		const afterDocId = url.slice(start + 21);
 		return afterDocId.slice(afterDocId.indexOf("/") + 1);
 	}
-	version() {
+	version(doc = this.doc, seq = this.seq) {
 		return {
-			update_seq: this.seq,
-			server_vv: bytesToBase64(this.doc.oplogVersion().encode()),
-			frontiers: bytesToBase64(encodeFrontiers(this.doc.oplogFrontiers()))
+			update_seq: seq,
+			server_vv: bytesToBase64(doc.oplogVersion().encode()),
+			frontiers: bytesToBase64(encodeFrontiers(doc.oplogFrontiers()))
 		};
 	}
+	handleDraft(updateSeq) {
+		if (!this.hasSnapshot) return this.handleSnapshot();
+		const seq = updateSeq ?? this.seq;
+		const snapshot = this.revisions.get(seq);
+		if (!snapshot) return Response.json({ code: "not_found" }, { status: 404 });
+		const doc = new LoroDoc();
+		doc.import(snapshot);
+		const dsl = new MedeoDsl(doc);
+		try {
+			assertDslDocument(doc);
+			return Response.json({
+				...toVideoDraft(dsl.getSnapshot()),
+				version: this.version(doc, seq)
+			});
+		} catch (error) {
+			return Response.json({
+				code: updateSeq === void 0 ? "projection_unsupported" : "revision_unprojectable",
+				message: String(error)
+			}, { status: 422 });
+		} finally {
+			dsl.dispose();
+			doc.free();
+		}
+	}
 	handleSnapshot() {
 		if (!this.hasSnapshot) return Response.json({
 			kind: "rejected",
@@ -105,6 +116,7 @@ var InMemoryMengineServer = class {
 		if (body.snapshot != null && !this.hasSnapshot) {
 			this.doc.import(base64ToBytes(body.snapshot));
 			this.hasSnapshot = true;
+			this.revisions.set(0, this.doc.export({ mode: "snapshot" }));
 		}
 		return this.handleSnapshot();
 	}
@@ -167,10 +179,16 @@ var InMemoryMengineServer = class {
 		try {
 			probe.import(this.doc.export({ mode: "snapshot" }));
 			probe.import(data);
-			if (documentFormat(probe) === "mixed") return Response.json({
+			let unsupported = documentFormat(probe) === "mixed";
+			if (documentFormat(probe) === "dsl") try {
+				assertPhoneticBindingFormat(probe);
+			} catch {
+				unsupported = true;
+			}
+			if (unsupported) return Response.json({
 				kind: "rejected",
 				code: "unsupported_document_format",
-				message: "Cannot mix legacy and DSL content roots",
+				message: "Unsupported or mixed DSL storage format",
 				server_version: serverVersion
 			}, { status: 422 });
 		} finally {
@@ -179,6 +197,7 @@ var InMemoryMengineServer = class {
 		this.doc.import(data);
 		this.hasSnapshot = true;
 		this.seq += 1;
+		this.revisions.set(this.seq, this.doc.export({ mode: "snapshot" }));
 		const meta = extractMeta(this.doc, baseVV);
 		const stored = {
 			updateSeq: this.seq,

package/dist/{video-draft-types-BfIXM8q3.js → video-draft-types-DRGBN0we.js}

@@ -1,5 +1,5 @@
 import { sha256 } from "@noble/hashes/sha2.js";
-import { Cursor } from "loro-crdt";
+import { Cursor, isContainer } from "loro-crdt";
 //#region ../medeo-dsl/src/ids.ts
 function bytesToBase64url(bytes) {
 	let binary = "";
@@ -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");
 }
@@ -1375,6 +1379,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);
@@ -1441,13 +1469,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),
@@ -1499,14 +1521,24 @@ 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
@@ -1516,4 +1548,4 @@ const textStyles = { language: { expand: "after" } };
 //#region src/dsl/projection/video-draft-types.ts
 const DEFAULT_UNIT_TIME_MS = 33.333;
 //#endregion
-export { assertEntityPatch as $, getRootContainerByType as A, isValueOfContainerType as B, applyEncode as C, decodeNestedJsonValues as D, containerIdToContainerType as E, isArrayLike as F, tryUpdateToContainer as G, schemaToContainerType as H, isObject as I, getChildContainerSchema as J, valuesEqual as K, isObjectLike as L, hasTransform as M, inferContainerTypeFromValue as N, deepEqual as O, insertChildToMap as P, assertEntity as Q, isStateAndSchemaOfType as R, applyDecode as S, cidsEqual as T, stripUndefined as U, safeStringify as V, tryInferContainerType as W, getMapFieldSchema as X, getChildSchema as Y, assertCaptionContent as Z, isLoroMovableListSchema as _, resourceId as _t, documentFormat as a, assertTimeAnchor as at, schemaContainsIgnoreField as b, isInvalidAtomic as c, isRecord as ct, schema as d, relationTables as dt, assertId as et, getDefaultValue as f, validLanguage as ft, isLoroMapSchema as g, relationId as gt, isLoroListSchema as h, defaultIdFactory as ht, assertDslDocument as i, assertScriptSegment as it, hardenCidDescriptors as j, defineCidProperty as k, phonemeCodec as l, mergeFields as lt, isListLikeSchema as m, assertResourceIdentity as mt, textStyles as n, assertPhoneticScript as nt, medeoDslLoroShape as o, atomicFields as ot, isContainerSchema as p, assertRelationIdentity as pt, CID_KEY as q, UnsupportedDocumentFormatError as r, assertRelation as rt, captionContentCodec as s, entityTables as st, DEFAULT_UNIT_TIME_MS as t, assertPhoneme as tt, timeAnchorCodec as u, patchRow as ut, isLoroTreeSchema as v, tupleHash as vt, applySchemaToInferOptions as w, validateSchema as x, isRootSchemaType as y, isTreeID as z };
+export { assertCaptionContent as $, deepEqual as A, isStateAndSchemaOfType as B, validateSchema as C, cidsEqual as D, applySchemaToInferOptions as E, inferContainerTypeFromValue as F, stripUndefined as G, isValueOfContainerType as H, insertChildToMap as I, valuesEqual as J, tryInferContainerType as K, isArrayLike as L, getRootContainerByType as M, hardenCidDescriptors as N, containerIdToContainerType as O, hasTransform as P, getMapFieldSchema as Q, isObject as R, schemaContainsIgnoreField as S, tupleHash as St, applyEncode as T, safeStringify as U, isTreeID as V, schemaToContainerType as W, getChildContainerSchema as X, CID_KEY as Y, getChildSchema as Z, isLoroListSchema as _, assertRelationIdentity as _t, assertPhoneticBindingFormat as a, assertPhoneticScript as at, isLoroTreeSchema as b, relationId as bt, captionContentCodec as c, assertSeqMarker as ct, phoneticBindingCodec as d, entityTables as dt, assertEntity as et, timeAnchorCodec as f, isRecord as ft, isListLikeSchema as g, validLanguage as gt, isContainerSchema as h, relationTables as ht, assertDslDocument as i, assertPhonemeScript as it, defineCidProperty as j, decodeNestedJsonValues as k, isInvalidAtomic as l, assertTimeAnchor as lt, getDefaultValue as m, patchRow as mt, textStyles as n, assertId as nt, documentFormat as o, assertRelation as ot, schema as p, mergeFields as pt, tryUpdateToContainer as q, UnsupportedDocumentFormatError as r, assertPhoneme as rt, medeoDslLoroShape as s, assertScriptSegment as st, DEFAULT_UNIT_TIME_MS as t, assertEntityPatch as tt, phonemeCodec as u, atomicFields as ut, isLoroMapSchema as v, assertResourceIdentity as vt, applyDecode as w, isRootSchemaType as x, resourceId as xt, isLoroMovableListSchema as y, defaultIdFactory as yt, isObjectLike as z };

package/dist/{video-draft-types-0J2vfXBu.d.ts → video-draft-types-slnHaNs9.d.ts}

@@ -879,4 +879,4 @@ type VideoDraftContent = Pick<VideoDraft, 'timeline' | 'main_track' | 'above_mai
 type VideoDraftInput = Pick<VideoDraft, keyof VideoDraftContent>;
 declare const DEFAULT_UNIT_TIME_MS = 33.333;
 //#endregion
-export { TextMutation as $, DeepReadonly as A, PhonemeSelection as B, CaptionContent as C, Clip as D, CaptionText as E, EntityTables as F, ResourceSystem as G, RelationTable as H, EntityValues as I, SegmentSelection as J, RichTextSnapshot as K, FieldPatch as L, DslMutation as M, EntityMutation as N, ContainMutation as O, EntityTable as P, TextMark as Q, MedeoDslSnapshot as R, Caption as S, CaptionStyle$1 as T, RelationTables as U, RelationMutation as V, RelationValues as W, TextDelta as X, StoredFile as Y, TextEdit as Z, defaultIdFactory as _, VideoDraftCaptionStyle as a, tupleHash as b, VideoDraftInput as c, VideoDraftTrack as d, TextRun as et, VideoDraftTrackItem as f, EntityIdKind as g, DslIdFactory as h, VideoDraft as i, Voice as it, DslDiagnostic as j, ContainNode as k, VideoDraftPartUnion as l, OpActor as m, DEFAULT_UNIT_TIME_MS as n, Track$1 as nt, VideoDraftContent as o, CommitOptions as p, SegmentRange as q, VideoCreationSettings as r, TrackRole as rt, VideoDraftContentPartUnion as s, CaptionDisplayCue as t, TimeAnchor as tt, VideoDraftTimeline as u, relationId as v, CaptionSelection as w, AudioScript as x, resourceId as y, Media as z };
+export { TextMark as $, DeepReadonly as A, PhonemeSelection as B, CaptionContent as C, Clip as D, CaptionText as E, EntityTables as F, RelationValues as G, RelationMutation as H, EntityValues as I, SegmentRange as J, ResourceSystem as K, FieldPatch as L, DslMutation as M, EntityMutation as N, ContainMutation as O, EntityTable as P, TextEdit as Q, MedeoDslSnapshot as R, Caption as S, CaptionStyle$1 as T, RelationTable as U, PhoneticScript as V, RelationTables as W, StoredFile as X, SegmentSelection as Y, TextDelta as Z, defaultIdFactory as _, VideoDraftCaptionStyle as a, Voice as at, tupleHash as b, VideoDraftInput as c, VideoDraftTrack as d, TextMutation as et, VideoDraftTrackItem as f, EntityIdKind as g, DslIdFactory as h, VideoDraft as i, TrackRole as it, DslDiagnostic as j, ContainNode as k, VideoDraftPartUnion as l, OpActor as m, DEFAULT_UNIT_TIME_MS as n, TimeAnchor as nt, VideoDraftContent as o, CommitOptions as p, RichTextSnapshot as q, VideoCreationSettings as r, Track$1 as rt, VideoDraftContentPartUnion as s, CaptionDisplayCue as t, TextRun as tt, VideoDraftTimeline as u, relationId as v, CaptionSelection as w, AudioScript as x, resourceId as y, Media as z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mengine/medeo-client",
-  "version": "2.1.1-dsl.22",
+  "version": "2.1.1-dsl.24",
   "license": "UNLICENSED",
   "repository": {
     "type": "git",
@@ -29,9 +29,9 @@
     "@noble/hashes": "^2.4.0",
     "immer": "^10.2.0",
     "zod": "^4.4.3",
-    "@mengine/storage": "2.1.1-dsl.22",
-    "@mengine/sync": "2.1.1-dsl.22",
-    "@mengine/utils": "2.1.1-dsl.22"
+    "@mengine/storage": "2.1.1-dsl.24",
+    "@mengine/sync": "2.1.1-dsl.24",
+    "@mengine/utils": "2.1.1-dsl.24"
   },
   "devDependencies": {
     "@types/node": "^25.9.1",
@@ -42,8 +42,8 @@
     "typescript": "^6.0.3",
     "vite-plugin-wasm": "^3.6.0",
     "vite-plus": "^0.1.23",
-    "@mengine/idl-codegen": "0.0.0",
-    "@mengine/medeo-dsl": "0.0.0"
+    "@mengine/medeo-dsl": "0.0.0",
+    "@mengine/idl-codegen": "0.0.0"
   },
   "peerDependencies": {
     "loro-crdt": "^1.16.1"