@mengine/medeo-client 2.0.1-alpha.6 → 2.0.1-alpha.8

package/dist/{document-N-8GwtOX.js → document-DdwzfZ1g.js}

@@ -1,5 +1,5 @@
 import { u as volumeSchema } from "./shared-iWnU2osE.js";
-import { Mirror, schema } from "loro-mirror";
+import { Mirror, schema, validateSchema } from "loro-mirror";
 import { z } from "zod";
 import { LoroDoc, LoroMap, LoroMovableList, LoroText, UndoManager } from "loro-crdt";
 import { sha256 } from "@noble/hashes/sha2.js";
@@ -7,9 +7,11 @@ import { bytesToHex } from "@noble/hashes/utils.js";
 import { produce } from "immer";
 //#region src/client/base64.ts
 function bytesToBase64(bytes) {
-	let binary = "";
-	for (const byte of bytes) binary += String.fromCharCode(byte);
-	return btoa(binary);
+	const native = bytes.toBase64;
+	if (typeof native === "function") return native.call(bytes);
+	const chunks = [];
+	for (let offset = 0; offset < bytes.length; offset += 8192) chunks.push(String.fromCharCode(...bytes.subarray(offset, offset + 8192)));
+	return btoa(chunks.join(""));
 }
 function base64ToBytes(base64) {
 	const binary = atob(base64);
@@ -47,10 +49,6 @@ function base64ToBytes(base64) {
 *   value, last-writer-wins). The derived `fallback_abs_ms` snapshot sits beside
 *   it as its own number field — a separate LWW unit so a projection refresh
 *   never clobbers a `time_position` edit.
-* - meta lives in a `meta` LoroMap: the mirror root only accepts container
-*   schemas, so meta scalars can't sit at the root as bare values. The domain
-*   `VideoDocument` keeps the same `meta` wrapper, so the shapes are isomorphic
-*   and the read/seed mapping is a near-identity.
 * - `part_library` values are nested `LoroMap`s: the value is a `LoroMap` with
 *   four mutually-exclusive optional part sub-maps (`video_clip` / `speech` /
 *   `caption` / `bgm`), each a `LoroMap` whose fields are stored as real Loro
@@ -64,16 +62,10 @@ function base64ToBytes(base64) {
 *   as opaque JSON-blob sub-keys via `transform`. The four sub-keys are optional,
 *   so the "exactly one part kind" union invariant is not enforced by the schema
 *   type; it is rebuilt by `draftToPartUnion` on read and gated by zod on write.
-* - a caption's `style` is the one lazily-created optional child container, so
-*   `captionPart` sets `mergeableMapChildContainers: true` — two peers can
-*   concurrently first-create the same caption's `style` (one attribute each), and
-*   only a mergeable child converges instead of last-writer-wins dropping one. All
-*   other nested maps are keyed by a unique id (`part_library`) or created
-*   atomically with their parent (`partValue`'s part sub-map), so they never hit
-*   that concurrent-first-create fork and stay on plain `setContainer`. See the
-*   note on `captionPart` below.
-* - `video_creation_settings` is an opaque JSON blob carried in a string via
-*   `transform`: a whole value, last-writer-wins (no field-level concurrent edits).
+* - a caption's `style` is a mergeable child map for independent style fields.
+*   Creation paths materialize it with the caption, even when empty, so undoing
+*   a later style edit never removes the parent reference. Other nested maps
+*   keep their regular container identities from creation.
 */
 /**
 * JSON-blob transform for an opaque, last-writer-wins value carried in a Loro
@@ -154,16 +146,6 @@ const partValue = schema.LoroMap({
 	bgm: bgmPart
 });
 const videoDocumentMirrorSchema = schema({
-	meta: schema.LoroMap({
-		schema_version: schema.String({ required: false }),
-		draft_id: schema.String({ required: false }),
-		project_id: schema.String({ required: false }),
-		owner_id: schema.String({ required: false }),
-		thumbnail_storage_key: schema.String({ required: false }),
-		chat_session_id: schema.String({ required: false }),
-		video_creation_settings: schema.String({ required: false }).transform(jsonTransform()),
-		version: schema.Number({ required: false })
-	}),
 	timeline: schema.LoroMap({ unit_time_ms: schema.Number({ required: false }) }),
 	tracks: schema.LoroMovableList(track, (t) => t.id),
 	part_library: schema.LoroMapRecord(partValue)
@@ -213,9 +195,6 @@ function recordEntries(record) {
 }
 //#endregion
 //#region src/document/types.ts
-const VIDEO_DOCUMENT_SCHEMA_VERSION = "video-document/v0";
-/** A server-derived compatibility view, never an editor write authority. */
-const ENTITY_TIMELINE_PROJECTION_SCHEMA_VERSION = "video-document/entity-projection-v1";
 /** The linear speed multiplier of a `speed_shift`, defaulting to 1 (original). */
 function speedOf(speedShift) {
 	const speed = speedShift?.config?.linear?.speed;
@@ -549,12 +528,12 @@ function cascadeAfterVideoClipChanges(doc, makeEmptyPart) {
 * read-view: absolute time per item, `part_aggregations`, and total duration.
 * This is the read side of the single-directional flow — never written back.
 */
-function solveVideoDocument(document) {
+function solveVideoDocument(document, options = {}) {
 	const doc = videoDocumentToTimelineDoc(document);
 	let counter = 0;
 	const derivedFillerPartIds = /* @__PURE__ */ new Set();
-	if (document.meta.schema_version === "video-document/entity-projection-v1") {
-		for (const track of document.tracks ?? []) if (track.items?.some((item) => item.time_position.mode === "sequential" || item.time_position.mode === "anchored" && !Number.isSafeInteger(item.fallback_abs_ms))) throw new Error("An entity timeline projection must contain resolved placement facts");
+	if (options.placementResolved === true) {
+		assertResolvedPlacement(document);
 		recalculateTimelineDuration(doc);
 	} else cascadeAfterVideoClipChanges(doc, () => {
 		const partId = `empty_${counter++}`;
@@ -759,6 +738,19 @@ function ensureLaneTrack(draft, kind) {
 function findLaneTrack(draft, kind) {
 	return (draft.tracks ?? []).find((t) => t?.parts_kind === kind);
 }
+/**
+* Whether every item already states a position that can be read without running
+* the cascade: nothing `sequential`, and every `anchored` item carrying the
+* absolute landing its writer stamped. This is a verification predicate, not a
+* provenance test — see `SolveVideoDocumentOptions.placementResolved`.
+*/
+function hasResolvedPlacement(document) {
+	return (document.tracks ?? []).every((track) => (track.items ?? []).every((item) => item.time_position.mode !== "sequential" && (item.time_position.mode !== "anchored" || Number.isSafeInteger(item.fallback_abs_ms))));
+}
+/** A producer that claims resolved placement must actually have resolved it. */
+function assertResolvedPlacement(document) {
+	if (!hasResolvedPlacement(document)) throw new Error("An entity timeline projection must contain resolved placement facts");
+}
 //#endregion
 //#region src/document/zod-schema.ts
 const partKindSchema = z.enum([
@@ -859,18 +851,7 @@ const partUnionSchema = z.union([
 		"bgm"
 	].filter((k) => p[k] != null).length === 1;
 }, { message: "A part_library value must have exactly one of video_clip / speech / caption / bgm" });
-const videoDocumentMetaSchema = z.object({
-	schema_version: z.enum([VIDEO_DOCUMENT_SCHEMA_VERSION, ENTITY_TIMELINE_PROJECTION_SCHEMA_VERSION]),
-	draft_id: z.string().optional(),
-	project_id: z.string().optional(),
-	owner_id: z.string().optional(),
-	thumbnail_storage_key: z.string().optional(),
-	chat_session_id: z.string().optional(),
-	video_creation_settings: z.unknown().optional(),
-	version: finiteNumber.optional()
-}).passthrough();
 const videoDocumentSchema = z.object({
-	meta: videoDocumentMetaSchema,
 	timeline: z.object({ unit_time_ms: finiteNumber.optional() }).passthrough().optional(),
 	tracks: z.array(trackSchema).optional(),
 	part_library: z.record(z.string(), partUnionSchema).optional()
@@ -1140,13 +1121,13 @@ function zodPath(path) {
 //#endregion
 //#region src/document/projection.ts
 /**
-* Projection between the authoritative `VideoDocument` and the legacy
-* `VideoDraft` read-view (RFC 02 §5/§7). Both directions live here:
+* Projection between authoritative `VideoDocument` and compatible content
+* layouts (RFC 02 §5/§7). Both directions live here:
 *
 * - `toVideoDocument` ingests a `VideoDraft`, deriving each item's `position`
 *   from the legacy absolute layout + aggregations; derived values (abs time,
 *   `part_aggregations`, total duration) are dropped.
-* - `fromVideoDocument` solves a `VideoDocument` back into a `VideoDraft` via the
+* - `fromVideoDocument` solves a `VideoDocument` into `VideoDraftContent` via the
 *   timeline-core cascade, re-deriving exactly those values.
 *
 * Business validation lives in `validation.ts`; `fromVideoDocument` asserts a
@@ -1177,16 +1158,6 @@ function toVideoDocument(draft) {
 		...(draft.below_main_tracks ?? []).map((t) => toTrack(t, false))
 	];
 	return {
-		meta: {
-			schema_version: VIDEO_DOCUMENT_SCHEMA_VERSION,
-			draft_id: draft.id,
-			project_id: draft.project_id,
-			owner_id: draft.owner_id,
-			thumbnail_storage_key: draft.thumbnail_storage_key,
-			chat_session_id: draft.chat_session_id,
-			video_creation_settings: clone$1(draft.video_creation_settings),
-			version: draft.version
-		},
 		timeline: draft.timeline == null ? void 0 : { unit_time_ms: draft.timeline.unit_time_ms },
 		tracks,
 		part_library: toAuthoritativePartLibrary(draft.part_library)
@@ -1296,8 +1267,8 @@ function deriveItem(item, isMain, speechHost, partLibrary) {
 	};
 }
 /**
-* Project the authoritative `VideoDocument` back into the legacy `VideoDraft`
-* read-view, solving each item's absolute position, the `part_aggregations`, and
+* Project `VideoDocument` into `VideoDraftContent`, solving each item's
+* absolute position, the `part_aggregations`, and
 * the total duration via the timeline-core cascade.
 *
 * The read-view is a compatibility contract, and the IDL declares
@@ -1311,33 +1282,26 @@ function deriveItem(item, isMain, speechHost, partLibrary) {
 * These two are defaultable because the projection knows their values on its own:
 * absent `unit_time_ms` means "no display granularity was ever stated" and absent
 * `is_hidden` means "this track was never hidden". `version` is NOT defaultable
-* here — its only honest value is server state (`update_seq`) that a
-* `VideoDocument` cannot see, so it stays absent and the HTTP layer fills it.
+* here — it belongs to Director assembly using the server envelope update_seq.
+* Neither business metadata nor a revision counter belongs in content projection.
 */
-function fromVideoDocument(document) {
+function fromVideoDocument(document, options = {}) {
 	assertValidVideoDocument(document);
-	const view = solveVideoDocument(document);
+	const view = solveVideoDocument(document, options);
 	const tracks = document.tracks ?? [];
 	const mainTrack = tracks.find((t) => t.parts_kind === "video_clip");
 	const aboveTracks = tracks.filter((t) => t.parts_kind === "caption");
 	const belowTracks = tracks.filter((t) => t.parts_kind === "speech" || t.parts_kind === "bgm");
 	return {
-		id: document.meta.draft_id,
-		project_id: document.meta.project_id,
-		owner_id: document.meta.owner_id,
-		thumbnail_storage_key: document.meta.thumbnail_storage_key,
 		timeline: {
 			duration_ms: view.durationMs,
 			unit_time_ms: document.timeline?.unit_time_ms ?? 33.333
 		},
-		video_creation_settings: clone$1(document.meta.video_creation_settings),
-		chat_session_id: document.meta.chat_session_id,
 		main_track: draftTrack(mainTrack, view.absByPartId),
 		above_main_tracks: aboveTracks.map((t) => draftTrack(t, view.absByPartId)),
 		below_main_tracks: belowTracks.map((t) => draftTrack(t, view.absByPartId)),
 		part_aggregations: view.aggregations,
-		part_library: toReadViewPartLibrary(view.partLibrary, view.durationMs, view.derivedFillerPartIds),
-		version: document.meta.version
+		part_library: toReadViewPartLibrary(view.partLibrary, view.durationMs, view.derivedFillerPartIds)
 	};
 }
 /**
@@ -1444,7 +1408,7 @@ function clone$1(value) {
 //#region src/document/initial-document.ts
 /**
 * Build the `VideoDocument` a newly created project starts from: the caller's
-* project facts, no parts, and one empty track per lane.
+* no parts and one empty track per lane. Business facts remain in Director.
 *
 * The empty lane tracks are the reason this function exists rather than callers
 * assembling a document inline. Lane tracks are otherwise minted lazily by the
@@ -1465,18 +1429,8 @@ function clone$1(value) {
 * supplies, and total duration is derived on read (RFC 02 §6), so a new document
 * has no timeline fact to state.
 */
-function buildInitialVideoDocument(facts) {
+function buildInitialVideoDocument() {
 	return {
-		meta: {
-			schema_version: VIDEO_DOCUMENT_SCHEMA_VERSION,
-			draft_id: facts.draftId,
-			project_id: facts.projectId,
-			owner_id: facts.ownerId,
-			thumbnail_storage_key: void 0,
-			chat_session_id: facts.chatSessionId,
-			video_creation_settings: facts.videoCreationSettings,
-			version: void 0
-		},
 		timeline: void 0,
 		tracks: emptyLaneTracks(),
 		part_library: {}
@@ -1493,8 +1447,63 @@ function emptyLaneTracks() {
 }
 //#endregion
 //#region ../medeo-dsl/src/entities.ts
+/**
+* The declared trait set of every known kind.
+*
+* `caption` carries `sequence` on purpose: a Caption owns the display timing of
+* the one AudioScript segment it shows, which is what admits it into a Clip.
+* `voice` carries no media or sequence trait — it is a timbre identity, not
+* playable content; a rendered voiceover is an `audio` entity.
+*/
+const ENTITY_TRAIT_KINDS = Object.freeze({
+	axvideo: Object.freeze([
+		"container",
+		"sequence",
+		"visual",
+		"audible"
+	]),
+	timeline: Object.freeze(["container"]),
+	track: Object.freeze(["container", "sequence"]),
+	clip: Object.freeze(["container"]),
+	asset: Object.freeze([]),
+	video: Object.freeze([
+		"media-file",
+		"sequence",
+		"visual",
+		"audible"
+	]),
+	audio: Object.freeze([
+		"media-file",
+		"sequence",
+		"audible"
+	]),
+	image: Object.freeze([
+		"media-file",
+		"sequence",
+		"visual"
+	]),
+	voice: Object.freeze(["container", "ip-bound"]),
+	"sequence-marker": Object.freeze([]),
+	viewport: Object.freeze([]),
+	"audio-script": Object.freeze(["segment-text"]),
+	"phonetic-script": Object.freeze(["segment-text"]),
+	caption: Object.freeze(["segment-text", "sequence"])
+});
+/** Declared traits of a known kind; extension kinds declare none through this table. */
+function traitKindsOf(entityKind) {
+	return isKnownEntityKind(entityKind) ? ENTITY_TRAIT_KINDS[entityKind] : [];
+}
+function hasTraitKind(entityKind, trait) {
+	return traitKindsOf(entityKind).includes(trait);
+}
+/**
+* Sequence admission asks the declared traits first, so a kind that does not
+* declare `sequence` can never buy its way in by carrying the fields. Extension
+* kinds declare no traits and stay structurally detected.
+*/
 function hasSequence(entity) {
-	if (isKnownNonSequenceKind(entity.entityKind) || isReservedEntityKind(entity.entityKind)) return false;
+	if (isReservedEntityKind(entity.entityKind)) return false;
+	if (isKnownEntityKind(entity.entityKind) && !hasTraitKind(entity.entityKind, "sequence")) return false;
 	return isSequenceFields(entity);
 }
 function isSequenceFields(value) {
@@ -1507,22 +1516,16 @@ function isSequenceFields(value) {
 	if (value.sampling !== "native" && value.sampling !== "constant" && value.sampling !== "derived") return false;
 	return "coordinateSpace" in value && value.coordinateSpace !== void 0;
 }
-function isKnownSequenceKind(kind) {
-	return isMediaAssetVariantKind(kind) || kind === "caption" || kind === "axvideo";
-}
 function isMediaAssetVariantKind(kind) {
-	return kind === "video" || kind === "image" || kind === "audio" || kind === "voice";
+	return kind === "video" || kind === "image" || kind === "audio";
 }
 function isKnownEntityKind(kind) {
-	return isKnownSequenceKind(kind) || isKnownNonSequenceKind(kind);
+	return Object.hasOwn(ENTITY_TRAIT_KINDS, kind);
 }
 function isReservedEntityKind(kind) {
 	const normalized = kind.toLowerCase().replaceAll("-", "").replaceAll("_", "");
 	return normalized === "speech" || normalized === "videodocument";
 }
-function isKnownNonSequenceKind(kind) {
-	return kind === "timeline" || kind === "track" || kind === "clip" || kind === "asset" || kind === "sequence-marker" || kind === "viewport" || kind === "audio-script" || kind === "phonetic-script";
-}
 function isRecord$1(value) {
 	return typeof value === "object" && value != null && !Array.isArray(value);
 }
@@ -2105,12 +2108,15 @@ function validateKnownEntityPayload(entity) {
 			break;
 		case "video":
 		case "audio":
-		case "voice":
+			validateSequencePayload(value, "bounded", "native", problems);
+			validateMediaAssetFields(value, problems);
+			break;
 		case "caption":
 			validateSequencePayload(value, "bounded", "native", problems);
-			if (entity.entityKind !== "caption") validateMediaAssetFields(value, problems);
-			if (entity.entityKind === "voice") validateVoicePayload(value, problems);
-			if (entity.entityKind === "caption") validateCaptionPayload(value, problems);
+			validateCaptionPayload(value, problems);
+			break;
+		case "voice":
+			validateVoicePayload(value, problems);
 			break;
 		case "image":
 			validateSequencePayload(value, "unbounded", "constant", problems);
@@ -2217,11 +2223,26 @@ function validateExternalLocator(value, problems) {
 function validateStorageKey(value, problems) {
 	if (value.storageKey !== void 0 && (typeof value.storageKey !== "string" || value.storageKey.trim() === "")) problems.push("storageKey must be a non-empty string when present");
 }
+/**
+* Voice is a timbre identity, not playable content: it owns the voice-library
+* descriptor and nothing that would make it look like media or a Sequence. The
+* rendered voiceover is an `audio` entity bound by a `voice-timbre` Relation.
+*/
 function validateVoicePayload(value, problems) {
+	for (const key of [
+		"extent",
+		"sampling",
+		"coordinateSpace",
+		"external",
+		"storageKey"
+	]) if (Object.hasOwn(value, key)) problems.push(`${key} belongs to the rendered Audio, not to the Voice identity`);
 	const voice = value.voice;
-	if (voice === void 0) return;
+	if (voice === void 0) {
+		problems.push("voice is required; a Voice entity is its voice-library identity");
+		return;
+	}
 	if (!isRecord(voice)) {
-		problems.push("voice must be an object when present");
+		problems.push("voice must be an object");
 		return;
 	}
 	if (voice.system !== "voice-library") problems.push("voice.system must be \"voice-library\"");
@@ -2353,7 +2374,6 @@ function isOwnedLocalEntityValuePath(entityKind, path) {
 	if ([
 		"video",
 		"audio",
-		"voice",
 		"image",
 		"caption",
 		"axvideo"
@@ -2417,7 +2437,7 @@ function collectRelatedEntities(entityRefs, index) {
 	};
 }
 function expectedSequenceShape(kind) {
-	if (kind === "video" || kind === "audio" || kind === "voice" || kind === "caption") return {
+	if (kind === "video" || kind === "audio" || kind === "caption") return {
 		extent: "bounded",
 		sampling: "native"
 	};
@@ -2458,7 +2478,7 @@ const generatedRelationSpec = Object.freeze({
 });
 const captionAlignmentRelationSpec = Object.freeze({
 	kind: "caption-alignment",
-	validateEndpoints: (endpoints) => hasKinds(endpoints, new Set(["caption"]), new Set(["audio", "voice"])),
+	validateEndpoints: (endpoints) => hasKinds(endpoints, new Set(["caption"]), new Set(["audio"])),
 	validateMetadata: isCaptionAlignmentMetadata
 });
 /** `clip-anchor(child, host)` means endpoint 0 follows endpoint 1. */
@@ -2467,20 +2487,29 @@ const clipAnchorRelationSpec = Object.freeze({
 	validateEndpoints: (endpoints) => endpoints[0].current().entityKind === "clip" && endpoints[1].current().entityKind === "clip",
 	validateMetadata: isEmptyMetadata
 });
-/** Voice is generated from PhoneticScript; kinds determine roles regardless of endpoint positions. */
+/**
+* The rendered voiceover Audio and the PhoneticScript it was synthesized from;
+* kinds determine roles regardless of endpoint positions.
+*/
 const phoneticScriptRenderRelationSpec = Object.freeze({
 	kind: "phonetic-script-render",
-	validateEndpoints: (endpoints) => hasKinds(endpoints, new Set(["voice"]), new Set(["phonetic-script"])),
+	validateEndpoints: (endpoints) => hasKinds(endpoints, new Set(["audio"]), new Set(["phonetic-script"])),
+	validateMetadata: isEmptyMetadata
+});
+/**
+* The timbre identity a rendered voiceover Audio was synthesized with. Voice
+* stays an identity: it never carries the audio itself, so the link between the
+* two is a Relation rather than one shared entity.
+*/
+const voiceTimbreRelationSpec = Object.freeze({
+	kind: "voice-timbre",
+	validateEndpoints: (endpoints) => hasKinds(endpoints, new Set(["audio"]), new Set(["voice"])),
 	validateMetadata: isEmptyMetadata
 });
 /** AudioScript was transcribed from Audio, Video, or recorded Voice; kinds determine roles. */
 const audioScriptSourceRelationSpec = Object.freeze({
 	kind: "audio-script-source",
-	validateEndpoints: (endpoints) => hasKinds(endpoints, new Set(["audio-script"]), new Set([
-		"audio",
-		"video",
-		"voice"
-	])),
+	validateEndpoints: (endpoints) => hasKinds(endpoints, new Set(["audio-script"]), new Set(["audio", "video"])),
 	validateMetadata: isEmptyMetadata
 });
 /**
@@ -2507,6 +2536,7 @@ const builtInRelationSpecs = Object.freeze([
 	captionAlignmentRelationSpec,
 	clipAnchorRelationSpec,
 	phoneticScriptRenderRelationSpec,
+	voiceTimbreRelationSpec,
 	audioScriptSourceRelationSpec,
 	audioScriptMarkerRelationSpec
 ]);
@@ -2536,7 +2566,7 @@ function hasAssetAndSequence(endpoints) {
 	return first.entityKind === "asset" && hasSequence(second) || second.entityKind === "asset" && hasSequence(first);
 }
 function isGeneratedMedia(entity) {
-	return entity.entityKind === "video" || entity.entityKind === "image" || entity.entityKind === "audio" || entity.entityKind === "voice";
+	return entity.entityKind === "video" || entity.entityKind === "image" || entity.entityKind === "audio";
 }
 function isEmptyMetadata(value) {
 	return isJsonObject(value) && Object.keys(value).length === 0;
@@ -2966,7 +2996,7 @@ function resolveGraphLayout(graph) {
 			if (clip.entityKind !== "clip" || graph.adjacent(clip.entityId, "track-clip").length !== 1) fail(`Clip ${clip.entityId} must belong to exactly one Track`);
 			const marker = graph.one(clip.entityId, "clip-marker", "sequence-marker");
 			const content = graph.one(marker.entityId, "marker-content");
-			if (!(typedRole === "video_clip" ? ["image", "video"] : typedRole === "speech" ? ["voice"] : typedRole === "caption" ? ["caption"] : ["audio"]).includes(content.entityKind)) fail(`unsupported compatibility content kind ${content.entityKind} on ${typedRole} Track`);
+			if (!(typedRole === "video_clip" ? ["image", "video"] : typedRole === "speech" ? ["audio"] : typedRole === "caption" ? ["caption"] : ["audio"]).includes(content.entityKind)) fail(`unsupported compatibility content kind ${content.entityKind} on ${typedRole} Track`);
 			const space = content.payload.coordinateSpace;
 			if (space !== "ms" && space !== "milliseconds" && (!object(space) || space.unit !== "ms" && space.unit !== "milliseconds")) fail(`media ${content.entityId} must state millisecond coordinates for this reader`);
 			const source = range(marker.payload.sourceRange, "sourceRange");
@@ -3045,7 +3075,7 @@ function resolveGraphLayout(graph) {
 		let start = fact.absoluteStart ?? 0;
 		if (fact.mode === "anchored") {
 			const host = resolve(fact.anchorId);
-			if (fact.role === "speech" && !["video_clip", "bgm"].includes(facts.get(host.clipEntityId).role)) fail("An anchored Voice must use a visual or BGM Clip as its host");
+			if (fact.role === "speech" && !["video_clip", "bgm"].includes(facts.get(host.clipEntityId).role)) fail("An anchored voiceover must use a visual or BGM Clip as its host");
 			start = host.start + fact.anchorOffset;
 		} else if (fact.predecessor !== void 0) {
 			const prior = resolve(fact.predecessor);
@@ -3094,7 +3124,7 @@ function resolveGraphLayout(graph) {
 * consulted as an editing fact. Peer IDs appear only in this derived read
 * contract, reconstructed from relations; they are not stored in payloads.
 */
-function projectEntityTimeline(rows, meta) {
+function projectEntityTimeline(rows) {
 	const graph = new EntityProjectionGraph(rows);
 	const layout = resolveGraphLayout(graph);
 	for (const track of layout.tracks) {
@@ -3129,8 +3159,11 @@ function projectEntityTimeline(rows, meta) {
 			const asset = mediaAssetFacts(graph, content);
 			requireUntrimmedAudio(content, marker, placement);
 			const external = externalLocator(asset, "memota-speech");
-			const assembled = graph.adjacent(content.entityId, "phonetic-script-render").length > 0 || content.payload.voice !== void 0 ? assemblePhoneticScriptContent(rows, graph.one(content.entityId, "phonetic-script-render", "phonetic-script").entityId) : void 0;
-			const voice = content.payload.voice;
+			const renderEdges = graph.adjacent(content.entityId, "phonetic-script-render");
+			const timbreEdges = graph.adjacent(content.entityId, "voice-timbre");
+			const assembled = renderEdges.length > 0 || timbreEdges.length > 0 ? assemblePhoneticScriptContent(rows, graph.one(content.entityId, "phonetic-script-render", "phonetic-script").entityId) : void 0;
+			if (timbreEdges.length > 1) fail("A voiceover resolves at most one Voice identity");
+			const voice = timbreEdges.length === 0 ? void 0 : graph.one(content.entityId, "voice-timbre", "voice").payload.voice;
 			if (voice !== void 0 && (!object(voice) || voice.system !== "voice-library" || typeof voice.key !== "string")) fail("Voice must use an explicit voice-library locator");
 			const captionIds = layout.tracks.flatMap((candidate) => candidate.role === "caption" ? candidate.clips.filter((caption) => caption.anchorClipEntityId === clip.entityId).map((caption) => caption.clipEntityId) : []);
 			parts[clip.entityId] = { speech: {
@@ -3183,10 +3216,6 @@ function projectEntityTimeline(rows, meta) {
 		}
 	}
 	const document = {
-		meta: {
-			...structuredClone(meta),
-			schema_version: ENTITY_TIMELINE_PROJECTION_SCHEMA_VERSION
-		},
 		timeline: graph.timeline.payload.unit_time_ms === void 0 ? void 0 : { unit_time_ms: positive(graph.timeline.payload.unit_time_ms, "unit_time_ms") },
 		tracks: layout.tracks.map((track) => ({
 			id: track.entityId,
@@ -4271,13 +4300,37 @@ function materialize(doc, allowSelectionConflicts = false) {
 	for (const [slot, id] of Object.entries(state.project)) if (project.get(slot) !== id) project.set(slot, id);
 }
 //#endregion
+//#region src/document/document-mutation-guard.ts
+/**
+* @internal
+* Shared by synchronous mutation entry points for one document. The session
+* closes it before teardown callbacks can attempt another write.
+*/
+var DocumentMutationGuard = class {
+	running = false;
+	closed = false;
+	run(mutation) {
+		if (this.closed) throw new Error("mengine document is disposed");
+		if (this.running) throw new Error("mengine document mutation is already running");
+		this.running = true;
+		try {
+			return mutation();
+		} finally {
+			this.running = false;
+		}
+	}
+	close() {
+		this.closed = true;
+	}
+};
+//#endregion
 //#region src/document/mirror-read.ts
 /**
 * Project the mirror state (`VideoDocumentDraft`) into the authoritative
 * `VideoDocument`. The storage shape is isomorphic to the domain shape (RFC 03
-* §4, reference/17 §4: meta map + a single `tracks` list + part_library), so this
+* §4, reference/17 §4: timeline + a single `tracks` list + part_library), so this
 * is a near-identity — it reads `time_position` / `fallback_abs_ms` JSON blobs
-* back into structured values and trims empty strings, nothing more.
+* back into structured values and selects content fields. Legacy meta is ignored.
 *
 * It maps only authoritative facts (RFC 02 §6): `part_id` + `time_position`. The
 * projection-derived `VideoDraft` read-view (absolute time, `part_aggregations`,
@@ -4294,20 +4347,8 @@ function readVideoDocumentFromDraft(draft) {
 		if (part != null) partLibrary[partId] = part;
 	}
 	const timeline = draft.timeline;
-	const hasTimeline = timeline?.unit_time_ms != null;
-	const meta = draft.meta;
 	return {
-		meta: {
-			schema_version: meta?.schema_version === "video-document/entity-projection-v1" ? ENTITY_TIMELINE_PROJECTION_SCHEMA_VERSION : VIDEO_DOCUMENT_SCHEMA_VERSION,
-			draft_id: emptyToUndefined(meta?.draft_id),
-			project_id: emptyToUndefined(meta?.project_id),
-			owner_id: emptyToUndefined(meta?.owner_id),
-			thumbnail_storage_key: emptyToUndefined(meta?.thumbnail_storage_key),
-			chat_session_id: emptyToUndefined(meta?.chat_session_id),
-			video_creation_settings: meta?.video_creation_settings ?? void 0,
-			version: meta?.version ?? void 0
-		},
-		timeline: hasTimeline ? { unit_time_ms: timeline.unit_time_ms } : void 0,
+		timeline: timeline?.unit_time_ms != null ? { unit_time_ms: timeline.unit_time_ms } : void 0,
 		tracks: rowsToTracks(draft.tracks),
 		part_library: partLibrary
 	};
@@ -4331,9 +4372,6 @@ function rowToTrack(row) {
 		})
 	};
 }
-function emptyToUndefined(value) {
-	return value == null || value === "" ? void 0 : value;
-}
 //#endregion
 //#region src/document/mirror-adapter.ts
 /**
@@ -4346,33 +4384,50 @@ function emptyToUndefined(value) {
 * - `transact(edit, audit)` runs the whole op in one `mirror.setState` callback:
 *   one diff, one `doc.commit` carrying the audit message. The callback edits an
 *   immer draft, so a throw inside it discards the draft and never touches Loro
-*   (natural rollback) — no `guard` / `rollback` / `openTransaction` machinery.
+*   (natural rollback) without a document checkout or compensating commit.
 * - mirror's `idSelector` (track items keyed by `part_id`) diffs reorders to
 *   real Loro `move` ops on every lane, so per-item CRDT identity survives on
 *   main and secondary tracks alike.
 */
 var MirrorVideoDocumentAdapter = class {
 	doc;
+	mutationGuard;
 	mirror;
-	constructor(doc) {
+	disposed = false;
+	constructor(doc, mutationGuard = new DocumentMutationGuard()) {
 		this.doc = doc;
+		this.mutationGuard = mutationGuard;
 		this.mirror = new Mirror({
 			doc,
-			schema: videoDocumentMirrorSchema
+			schema: videoDocumentMirrorSchema,
+			validateUpdates: false
 		});
 	}
 	snapshot() {
-		const document = readVideoDocumentFromDraft(this.mirror.getState());
-		if (this.doc.getMap("medeo").get("schema") === "medeo.entities.loro.v1") return projectEntityTimeline(readEntityDocument(this.doc).rows, document.meta);
-		return document;
+		this.assertActive();
+		if (this.isEntityDocument()) return projectEntityTimeline(readEntityDocument(this.doc).rows);
+		return readVideoDocumentFromDraft(this.mirror.getState());
 	}
 	/**
-	* True once the doc holds real document content. A fresh mirror over an empty
-	* doc still reports defaulted root maps, so probe the stored `schema_version`
-	* (empty until a snapshot is bootstrapped or synced in).
+	* Native Entity authority: placement is already solved by the Entity graph.
+	*
+	* The root check goes through `getShallowValue` first because `getMap` creates
+	* the container on access — probing a legacy document for `medeo` would
+	* otherwise mutate it, which a read must never do.
 	*/
-	hasContent() {
-		return (this.mirror.getState().meta?.schema_version ?? "") !== "";
+	isEntityDocument() {
+		const roots = this.doc.getShallowValue();
+		if (!Object.hasOwn(roots, "medeo")) return false;
+		return this.doc.getMap("medeo").get("schema") === LORO_ENTITY_SCHEMA;
+	}
+	/**
+	* Release mirror subscriptions; do not reuse this adapter afterwards.
+	* The caller still owns the borrowed LoroDoc.
+	*/
+	dispose() {
+		if (this.disposed) return;
+		this.disposed = true;
+		this.mirror.dispose();
 	}
 	/**
 	* Apply one op as a single transaction. `edit` mutates the immer draft; mirror
@@ -4381,80 +4436,71 @@ var MirrorVideoDocumentAdapter = class {
 	* skips the commit — matching the prior "empty op leaves no audit" behavior.
 	*/
 	transact(edit, audit) {
-		if (this.snapshot().meta.schema_version === "video-document/entity-projection-v1") throw new Error("Entity timeline projections are read-only; edit the Medeo entities instead");
-		this.mirror.setState((draft) => {
-			edit(draft);
-		}, {
-			origin: "mengine.semantic_editor",
-			message: JSON.stringify({
-				semantic_op: audit.kind,
-				payload: audit.payload,
-				intent: audit.intent ?? null,
-				actor: audit.actor ?? null
-			})
+		this.assertActive();
+		if (this.isEntityDocument()) throw new Error("Entity documents are read-only through this adapter; edit the Medeo entities instead");
+		this.mutationGuard.run(() => {
+			this.mirror.setState((draft) => {
+				edit(draft);
+				const result = validateSchema(videoDocumentMirrorSchema, {
+					timeline: draft.timeline,
+					tracks: draft.tracks,
+					part_library: draft.part_library
+				});
+				if (!result.valid) throw new Error(`Invalid content update: ${result.errors?.join("; ")}`);
+			}, {
+				origin: "mengine.semantic_editor",
+				message: JSON.stringify({
+					semantic_op: audit.kind,
+					payload: audit.payload,
+					intent: audit.intent ?? null,
+					actor: audit.actor ?? null
+				})
+			});
 		});
 	}
+	assertActive() {
+		if (this.disposed) throw new Error("mengine document adapter is disposed");
+	}
 };
 /** Build a fresh Loro doc seeded with `document` through the mirror. */
 function createMirrorVideoDocument(document, options = {}) {
 	assertValidVideoDocument(document);
 	const doc = new LoroDoc();
-	if (options.peerId != null) doc.setPeerId(options.peerId);
-	new Mirror({
-		doc,
-		schema: videoDocumentMirrorSchema
-	}).setState((draft) => {
-		writeVideoDocumentToDraft(draft, document);
-	}, { origin: options.origin ?? "mengine.bootstrap" });
-	return doc;
+	try {
+		if (options.peerId != null) doc.setPeerId(options.peerId);
+		const mirror = new Mirror({
+			doc,
+			schema: videoDocumentMirrorSchema
+		});
+		try {
+			mirror.setState((draft) => {
+				seedDraft(draft, document);
+			}, { origin: options.origin ?? "mengine.bootstrap" });
+			return doc;
+		} finally {
+			mirror.dispose();
+		}
+	} catch (error) {
+		doc.free();
+		throw error;
+	}
 }
 /** Build a `MirrorVideoDocumentAdapter` over a fresh doc seeded with `document`. */
 function createMirrorVideoDocumentAdapter(document, options) {
 	return new MirrorVideoDocumentAdapter(createMirrorVideoDocument(document, options));
 }
-/** Host-only replacement of a derived view, retaining the existing Loro history. */
-function applyEntityTimelineProjection(doc, projection, entityRevision) {
-	if (projection.meta.schema_version !== "video-document/entity-projection-v1") throw new Error("Expected an entity timeline projection");
-	if (!Number.isSafeInteger(entityRevision) || entityRevision < 1) throw new Error("Expected a positive entity revision");
-	assertValidVideoDocument(projection);
-	const from = doc.oplogVersion();
-	new Mirror({
-		doc,
-		schema: videoDocumentMirrorSchema
-	}).setState((draft) => writeVideoDocumentToDraft(draft, {
-		...projection,
-		meta: {
-			...projection.meta,
-			version: entityRevision
-		}
-	}), {
-		origin: "mengine.entity_projection",
-		message: JSON.stringify({
-			semantic_op: "EntityTimelineProjection",
-			entity_revision: entityRevision
-		})
-	});
-	return doc.export({
-		mode: "update",
-		from
-	});
-}
-/** Write a whole `VideoDocument` into a draft (seed a fresh doc / plain-memory state). */
-function writeVideoDocumentToDraft(draft, document) {
-	draft.meta = {
-		schema_version: document.meta.schema_version,
-		draft_id: document.meta.draft_id ?? void 0,
-		project_id: document.meta.project_id ?? void 0,
-		owner_id: document.meta.owner_id ?? void 0,
-		thumbnail_storage_key: document.meta.thumbnail_storage_key ?? void 0,
-		chat_session_id: document.meta.chat_session_id ?? void 0,
-		video_creation_settings: document.meta.video_creation_settings ?? void 0,
-		version: document.meta.version ?? void 0
-	};
+/** Write a whole `VideoDocument` into the mirror draft (seed a fresh doc / plain-memory state). */
+function seedDraft(draft, document) {
 	draft.timeline = { unit_time_ms: document.timeline?.unit_time_ms ?? void 0 };
 	draft.tracks = (document.tracks ?? []).map(toTrackRow);
 	draft.part_library = {};
-	for (const [partId, part] of Object.entries(document.part_library ?? {})) draft.part_library[partId] = partUnionToDraft(part);
+	for (const [partId, part] of Object.entries(document.part_library ?? {})) {
+		const createdPart = part.caption != null ? { caption: {
+			...part.caption,
+			style: part.caption.style ?? {}
+		} } : part;
+		draft.part_library[partId] = partUnionToDraft(createdPart);
+	}
 }
 /** Map a domain `Track` to a draft track row (no lane/lane_order — see schema). */
 function toTrackRow(track) {
@@ -4538,10 +4584,12 @@ var PlainMemoryAdapter = class {
 	* use this so every minted id is appended to the current transact's list.
 	*/
 	idFactory;
+	readOnly;
 	constructor(document, options) {
 		assertValidVideoDocument(document);
+		this.readOnly = options?.readOnly === true;
 		const draft = {};
-		writeVideoDocumentToDraft(draft, document);
+		seedDraft(draft, document);
 		this.state = draft;
 		this.baseIdFactory = options?.idFactory ?? generatePartId;
 		this.idFactory = (prefix) => {
@@ -4554,7 +4602,7 @@ var PlainMemoryAdapter = class {
 		return this._journal;
 	}
 	hasContent() {
-		return (this.state.meta?.schema_version ?? "") !== "";
+		return this.state.tracks !== void 0 || this.state.timeline !== void 0;
 	}
 	snapshot() {
 		return readVideoDocumentFromDraft(this.state);
@@ -4565,7 +4613,7 @@ var PlainMemoryAdapter = class {
 	* no structural change — skip journal, matching mirror "no change, no commit".
 	*/
 	transact(edit, audit) {
-		if (this.state.meta?.schema_version === "video-document/entity-projection-v1") throw new Error("Entity timeline projections are read-only; edit the Medeo entities instead");
+		if (this.readOnly) throw new Error("Entity documents are read-only here; edit the Medeo entities instead");
 		this.pendingIds = [];
 		try {
 			const next = produce(this.state, edit);
@@ -4586,4 +4634,4 @@ function createPlainMemoryAdapter(document, options) {
 	return new PlainMemoryAdapter(document, options);
 }
 //#endregion
-export { ensureLaneTrack as $, assembleEntityContent as A, hasSequence as B, projectEntityTimeline as C, base64ToBytes as Ct, decodeEntityRelationRows as D, EntityTimelineProjectionError as E, updateEntityFields as F, fromVideoDocument as G, buildInitialVideoDocument as H, variantBaseEntityIds as I, assertValidVideoDocument as J, toVideoDocument as K, isJsonObject as L, assembleScriptText as M, findComposedAudioScript as N, ScriptCompositionError as O, selectAudioScriptSegment as P, LANE_KINDS_IN_STACK_ORDER as Q, createEntityId as R, resolveFieldPath as S, videoDocumentMirrorSchema as St, resolveEntityTimelineLayout as T, buildSpeechHostMap as U, isMediaAssetVariantKind as V, derivePositionFromAbs as W, partUnionSchema as X, validateVideoDocument as Y, videoDocumentSchema as Z, audioScriptAssetHash as _, VIDEO_DOCUMENT_SCHEMA_VERSION as _t, applyEntityTimelineProjection as a, fillMainTrackTimeGaps as at, applyFieldChanges as b, partUnionToDraft as bt, writeVideoDocumentToDraft as c, resolveAllSpeechOverlaps as ct, LoroEntityDocument as d, TIMELINE_SKELETON_DURATION_MS as dt, findLaneTrack as et, LoroEntityDraft as f, isEmptyVideoClip as ft, audioScriptAssetFields as g, ENTITY_TIMELINE_PROJECTION_SCHEMA_VERSION as gt, audioScriptAssetContent as h, DEFAULT_UNIT_TIME_MS as ht, MirrorVideoDocumentAdapter as i, arrangeMainTrackSeamlessly as it, assemblePhoneticScriptContent as j, assembleCaptionContent as k, readVideoDocumentFromDraft as l, resolveSpeechOverlapByShiftingVideos as lt, entityOrderGroups as m, safeDurationMs as mt, createPlainMemoryAdapter as n, solveVideoDocument as nt, createMirrorVideoDocument as o, reassignSpeechesToVideoClipsByTime as ot, readEntityDocument as p, partDurationMs as pt, VideoDocumentValidationError as q, generatePartId as r, cascadeAfterVideoClipChanges as rt, createMirrorVideoDocumentAdapter as s, recalculateTimelineDuration as st, PlainMemoryAdapter as t, laneTrackId as tt, LORO_ENTITY_SCHEMA as u, syncAggregatedClipsTimePosition as ut, hasAudioScriptAsset as v, effectiveVideoClipDurationMs as vt, EntityProjectionGraph as w, bytesToBase64 as wt, assertFieldChanges as x, recordEntries as xt, equalJson as y, speedOf as yt, createRelationId as z };
+export { findLaneTrack as $, assemblePhoneticScriptContent as A, isMediaAssetVariantKind as B, EntityProjectionGraph as C, ScriptCompositionError as D, decodeEntityRelationRows as E, variantBaseEntityIds as F, toVideoDocument as G, buildSpeechHostMap as H, isJsonObject as I, validateVideoDocument as J, VideoDocumentValidationError as K, createEntityId as L, findComposedAudioScript as M, selectAudioScriptSegment as N, assembleCaptionContent as O, updateEntityFields as P, ensureLaneTrack as Q, createRelationId as R, projectEntityTimeline as S, bytesToBase64 as St, EntityTimelineProjectionError as T, derivePositionFromAbs as U, buildInitialVideoDocument as V, fromVideoDocument as W, videoDocumentSchema as X, partUnionSchema as Y, LANE_KINDS_IN_STACK_ORDER as Z, hasAudioScriptAsset as _, speedOf as _t, createMirrorVideoDocument as a, fillMainTrackTimeGaps as at, assertFieldChanges as b, videoDocumentMirrorSchema as bt, DocumentMutationGuard as c, resolveAllSpeechOverlaps as ct, LoroEntityDraft as d, TIMELINE_SKELETON_DURATION_MS as dt, hasResolvedPlacement as et, readEntityDocument as f, isEmptyVideoClip as ft, audioScriptAssetHash as g, effectiveVideoClipDurationMs as gt, audioScriptAssetFields as h, DEFAULT_UNIT_TIME_MS as ht, MirrorVideoDocumentAdapter as i, arrangeMainTrackSeamlessly as it, assembleScriptText as j, assembleEntityContent as k, LORO_ENTITY_SCHEMA as l, resolveSpeechOverlapByShiftingVideos as lt, audioScriptAssetContent as m, safeDurationMs as mt, createPlainMemoryAdapter as n, solveVideoDocument as nt, createMirrorVideoDocumentAdapter as o, reassignSpeechesToVideoClipsByTime as ot, entityOrderGroups as p, partDurationMs as pt, assertValidVideoDocument as q, generatePartId as r, cascadeAfterVideoClipChanges as rt, readVideoDocumentFromDraft as s, recalculateTimelineDuration as st, PlainMemoryAdapter as t, laneTrackId as tt, LoroEntityDocument as u, syncAggregatedClipsTimePosition as ut, equalJson as v, partUnionToDraft as vt, resolveEntityTimelineLayout as w, resolveFieldPath as x, base64ToBytes as xt, applyFieldChanges as y, recordEntries as yt, hasSequence as z };