@mengine/medeo-client 2.0.1-alpha.5 → 2.0.1-alpha.7

package/README.md

@@ -112,3 +112,34 @@ Loro version vector remains the transport-sync cursor.
 `entities.get/list` return complete assembled fields. Consumers do not query base IDs or merge source payloads. `entities.update` patches supplied fields, preserves omitted fields, and routes inherited fields to their declaring entity. Explicit own-field declarations use `entities.declareFields`; these override unambiguous base fields without changing the base. Persisted entity rows and command payloads contain owned fields only. Base collisions are validated before own overrides.
 
 `prepareCaptionContent` accepts caption authoring intent and handles source composition, visible text selection, and preservation of existing intrinsic timing inside the SDK.
+This package owns the shared `VideoDocument` contract, semantic editing layer, and runtime-neutral HTTP/SSE client used by medeo-web, agent-harness, and server-side validation code. UI adapters such as `DraftMutationDriver` stay in product repositories.
+
+`MengineDocSession.start()` waits for DocManager to load a local snapshot, or for the first remote sync if no local snapshot exists, then validates the content. A cached document can open before SSE connects; a cold start waits for SSE and the existing sync cycle. Session does not prefetch or import an initial snapshot itself.
+
+`getState().loaded` means the first local load completed. Once loaded, `loadedFromLocal` reports whether that load imported a snapshot, including a valid empty document. It stays unchanged by later edits and remote updates. Document readiness does not depend on metadata or nonempty tracks.
+
+## Session undo/redo
+
+After `await session.start()`, `session.undo(options?)` and `session.redo(options?)` synchronously apply local history and return whether they produced a document update. `options` accepts the same actor/intent metadata as semantic edits. Read the resulting document through `session.snapshot()`; use `waitForServerAck()` only when durable confirmation is required.
+
+`getUndoState()` returns the current `{ canUndo, canRedo }` immediately. `subscribeUndoState(callback)` immediately provides that state, then coalesces subsequent stack changes in a microtask after mutations settle. Several synchronous commands may produce only one availability notification; use the getter when reading directly after a command. Teardown publishes empty availability synchronously and cancels pending notifications. Dispose the returned subscription with the host. Loading and closed sessions report an empty history; history commands require a ready session.
+
+History belongs to one document/session peer. The loaded baseline and remote imports are not recorded. Each semantic commit is a separate step (up to 100); a new local edit invalidates redo. Reconnecting preserves history, while reopening starts empty. Empty or ineffective history actions return false. Never reuse a peer ID across concurrent sessions.
+
+Use `beginUndoGroup()` / `endUndoGroup()` to combine existing semantic operations into one undo step, or to combine repeated commits during one gesture. Always end in `finally`. Every constituent commit is immediately visible locally and enters synchronization independently; if a later operation fails, earlier commits remain applied. Conflicting remote imports may split/end a group early, and unrelated local edits in the same session would join an open group.
+
+Mirror's draft callback and commit are synchronous. SemanticEditor methods return promises, but their document mutations currently finish synchronously before the promise resolves. Await external asset generation before opening a group, then compose the local semantic operations. Keeping a group open across asynchronous work does not provide transaction isolation, deferred publication, or rollback. If several changes must be atomic, implement one semantic operation with one synchronous draft callback. A gesture that uses only local previews and commits once on release already needs no group.
+
+Flush pending local preview/debounce work before undo/redo. Mutating again from a document-update observer during a mutation is rejected; schedule the next command after the current one returns.
+
+The session assembles SemanticEditor with MirrorVideoDocumentAdapter directly. DocumentUndoManager independently observes the same LoroDoc and owns undo/redo, grouping and audit metadata. Both write paths share a synchronous DocumentMutationGuard; the session closes it before teardown callbacks, and each component releases its own resources. Standalone adapters create their own guard by default and reject use after disposal while leaving the borrowed LoroDoc usable.
+
+Undo/redo append ordinary synchronized updates and retain audit metadata (`Undo`/`Redo`, actor, and `payload.source` identifying an original local change). Existing revision bindings remain immutable. Redo reuses already materialized assets without repeating generation, billing, or attachment requests. Network failures do not automatically reverse history.
+
+Loro history uses new writes: undo on a shared LWW field restores its value before the local edit, potentially overwriting a later remote write to the same field; redo restores the value visible before undo. Unrelated remote fields remain intact. Undoing a local insertion removes the object and makes dependent remote edits invisible until redo restores the object. Caption creation includes its style container, even when empty, so a later style edit only changes fields and undo preserves another peer's independently edited fields. Initial document seeding preserves supplied styles and creates empty maps for captions without styles. No write-time repair or migration of older CRDT documents is provided.
+
+## Large-update resynchronization
+
+`MengineDocSession` handles SSE `event: resync` by scheduling the existing version-vector sync on the current connection. The event carries no Loro bytes and does not create an edit or undo step. A hint arriving while an HTTP sync is in flight schedules another diff so changes newer than that response are still fetched. Low-level users of `readMengineEventStream` can handle the same hint with `onResync`; `MedeoHttpDocStorage` exposes `subscribeResync`.
+
+Deploy this client before enabling server-side resync notifications. Older clients ignore the event. Large HTTP pushes remain valid: the server chooses inline update or resync notification after persistence, rather than requiring client-side fragmentation. Base64 encoding uses `Uint8Array.toBase64()` where available, with a chunked fallback preserving the same padded wire representation.

package/dist/{document-Bzzcn3g7.js → document-Bnxm1p5E.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: {}
@@ -3094,7 +3048,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) {
@@ -3183,10 +3137,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,
@@ -3844,6 +3794,10 @@ var LoroEntityDocument = class LoroEntityDocument {
 		if (id === void 0) return [];
 		return this.snapshot().rows.relations.filter((row) => row.endpoint0EntityId === id || row.endpoint1EntityId === id);
 	}
+	/** Resolve a queued edit target through its native identity without changing history. */
+	resolveCurrentEntityId(id) {
+		return currentId(this.doc, id);
+	}
 	getVersion(id) {
 		const entity = section(this.doc, "entities").get(id);
 		if (!isJsonObject(entity)) return void 0;
@@ -3917,12 +3871,12 @@ var LoroEntityDocument = class LoroEntityDocument {
 		return this.historyEdit(() => this.undoManager.redo());
 	}
 	historyEdit(run) {
-		const before = this.snapshot();
+		const before = new Map(this.snapshot().rows.entities.map((row) => [family(this.doc, row.entityId), row]));
 		if (!run()) return false;
 		const after = this.snapshot();
 		for (const row of after.rows.entities) {
 			const id = family(this.doc, row.entityId);
-			const previous = before.rows.entities.find((item) => family(this.doc, item.entityId) === id);
+			const previous = before.get(id);
 			if (previous && !equalJson(owned(previous.payload), owned(row.payload))) workspace(this.doc, id).ensureMergeableMap("changes").set(globalThis.crypto.randomUUID(), true);
 		}
 		materialize(this.doc);
@@ -4267,13 +4221,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`,
@@ -4290,20 +4268,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
 	};
@@ -4327,9 +4293,6 @@ function rowToTrack(row) {
 		})
 	};
 }
-function emptyToUndefined(value) {
-	return value == null || value === "" ? void 0 : value;
-}
 //#endregion
 //#region src/document/mirror-adapter.ts
 /**
@@ -4342,33 +4305,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
@@ -4377,80 +4357,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) {
@@ -4534,10 +4505,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) => {
@@ -4550,7 +4523,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);
@@ -4561,7 +4534,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);
@@ -4582,4 +4555,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 };