@mengine/medeo-client 2.0.1-alpha.3 → 2.0.1-alpha.31

package/dist/index.js

@@ -1,7 +1,8 @@
-import { t as __exportAll } from "./chunk-D7D4PA-g.js";
-import { A as isEmptyVideoClip, C as fillMainTrackTimeGaps, D as resolveSpeechOverlapByShiftingVideos, E as resolveAllSpeechOverlaps, F as partUnionToDraft, I as recordEntries, L as videoDocumentMirrorSchema, M as safeDurationMs, N as DEFAULT_UNIT_TIME_MS, O as syncAggregatedClipsTimePosition, P as effectiveVideoClipDurationMs, R as base64ToBytes, S as arrangeMainTrackSeamlessly, T as recalculateTimelineDuration, _ as ensureLaneTrack, a as DocumentMutationGuard, b as solveVideoDocument, c as derivePositionFromAbs, d as VideoDocumentValidationError, f as assertValidVideoDocument, g as LANE_KINDS_IN_STACK_ORDER, h as videoDocumentSchema, i as readVideoDocumentFromDraft, j as partDurationMs, k as TIMELINE_SKELETON_DURATION_MS, l as fromVideoDocument, m as partUnionSchema, n as createMirrorVideoDocument, o as buildInitialVideoDocument, p as validateVideoDocument, r as createMirrorVideoDocumentAdapter, s as buildSpeechHostMap, t as MirrorVideoDocumentAdapter, u as toVideoDocument, v as findLaneTrack, w as reassignSpeechesToVideoClipsByTime, x as cascadeAfterVideoClipChanges, y as laneTrackId, z as bytesToBase64 } from "./document-B_JQwrC5.js";
-import { z } from "zod";
-import { LoroDoc, UndoManager, VersionVector, decodeImportBlobMeta } from "loro-crdt";
+import { $ as buildSpeechHostMap, A as EntityProjectionGraph, At as recordEntries, B as assembleEntityContent, C as scriptSourceAssetOf, Ct as isEmptyVideoClip, D as assertFieldChanges, Dt as effectiveVideoClipDurationMs, E as applyFieldChanges, Et as DEFAULT_UNIT_TIME_MS, F as relationsFrom, G as updateEntityFields, H as assembleScriptText, I as relationsTo, J as createEntityId, K as variantBaseEntityIds, L as scriptContentHash, M as EntityTimelineProjectionError, Mt as base64ToBytes, N as validateEntityRelationTransition, Nt as bytesToBase64, O as resolveFieldPath, Ot as speedOf, P as decodeEntityRelationRows, Q as buildInitialVideoDocument, R as ScriptCompositionError, S as phoneticScriptAssetOf, St as TIMELINE_SKELETON_DURATION_MS, T as equalJson, Tt as safeDurationMs, U as findComposedAudioScript, V as assemblePhoneticScriptContent, W as selectAudioScriptSegment, X as hasSequence, Y as createRelationId, Z as isMediaAssetVariantKind, _ as audioScriptAssetHash, _t as reassignSpeechesToVideoClipsByTime, a as createMirrorVideoDocument, at as validateVideoDocument, b as phoneticScriptAssetContent, bt as resolveSpeechOverlapByShiftingVideos, c as DocumentMutationGuard, ct as LANE_KINDS_IN_STACK_ORDER, d as LoroEntityDraft, dt as hasResolvedPlacement, et as derivePositionFromAbs, f as readEntityDocument, ft as laneTrackId, g as audioScriptAssetFields, gt as fillMainTrackTimeGaps, h as audioScriptAssetContent, ht as arrangeMainTrackSeamlessly, i as MirrorVideoDocumentAdapter, it as assertValidVideoDocument, j as resolveEntityTimelineLayout, jt as videoDocumentMirrorSchema, k as projectEntityTimeline, kt as partUnionToDraft, l as LORO_ENTITY_SCHEMA, lt as ensureLaneTrack, m as entityOrderGroups, mt as cascadeAfterVideoClipChanges, n as createPlainMemoryAdapter, nt as toVideoDocument, o as createMirrorVideoDocumentAdapter, ot as partUnionSchema, p as readEntityRelationRecords, pt as solveVideoDocument, q as isJsonObject, r as generatePartId, rt as VideoDocumentValidationError, s as readVideoDocumentFromDraft, st as videoDocumentSchema, t as PlainMemoryAdapter, tt as fromVideoDocument, u as LoroEntityDocument, ut as findLaneTrack, v as audioScriptAssetOf, vt as recalculateTimelineDuration, w as canonicalJson, wt as partDurationMs, x as phoneticScriptAssetHash, xt as syncAggregatedClipsTimePosition, y as isTranscribedAudioScript, yt as resolveAllSpeechOverlaps, z as assembleCaptionContent } from "./document-BCQE5ofl.js";
+import { addSpeechesInputSchema, addVideoClipsInputSchema, adjustBgmVolumeInputSchema, adjustSpeechVolumeInputSchema, adjustVideoClipDurationInputSchema, adjustVideoClipVolumeInputSchema, changeSpeechScriptInputSchema, changeSpeechVoiceInputSchema, deleteBgmInputSchema, deleteSpeechesInputSchema, deleteVideoClipsInputSchema, moveSpeechesInputSchema, moveVideoClipsByAnchorInputSchema, moveVideoClipsInputSchema, replaceVideoClipContentInputSchema, replaceVideoClipSequenceInputSchema, setBgmInputSchema, setCaptionStyleInputSchema, setCaptionVisibilityInputSchema, setVideoClipSpeedShiftInputSchema, t as schemas_exports } from "./schemas.js";
+import { sha256 } from "@noble/hashes/sha2.js";
+import { bytesToHex } from "@noble/hashes/utils.js";
+import { LoroDoc, LoroMap, UndoManager, VersionVector } from "loro-crdt";
 import { ClientServerSynchronizer, DocManager } from "@mengine/sync";
 import { DisposableSet, EventBus, Task } from "@mengine/utils";
 import { BaseDocStorage, DummyConnection } from "@mengine/storage";
@@ -13,7 +14,7 @@ import { BaseDocStorage, DummyConnection } from "@mengine/storage";
 * namespace (mirrors the cluster's `/oapi/v1` precedent for an independent
 * subsystem) rather than folding into the shared `/api/v2/*` space.
 */
-const MENGINE_API_PREFIX = "/api/mengine/v1";
+const MENGINE_API_PREFIX$1 = "/api/mengine/v1";
 var MengineHttpRequestError = class extends Error {
 	status;
 	payload;
@@ -129,12 +130,12 @@ var MengineHttpClient = class {
 			...init,
 			headers
 		});
-		const payload = await safeReadJson(response);
+		const payload = await safeReadJson$1(response);
 		if (!response.ok) throw new MengineHttpRequestError(response.status, payload);
 		return payload;
 	}
 	endpoint(path) {
-		return `${this.options.httpOrigin.replace(/\/$/, "")}${MENGINE_API_PREFIX}/docs/${encodeURIComponent(this.options.docId)}/${path}`;
+		return `${this.options.httpOrigin.replace(/\/$/, "")}${MENGINE_API_PREFIX$1}/docs/${encodeURIComponent(this.options.docId)}/${path}`;
 	}
 };
 /**
@@ -151,627 +152,3038 @@ function asPushRejection(error) {
 	if (body.kind !== "rejected" || typeof body.code !== "string") return void 0;
 	return new MenginePushRejectedError(body.code, body.message ?? "", body.server_version, error.status);
 }
-async function safeReadJson(response) {
-	const text = await response.text();
-	if (text.length === 0) return null;
-	try {
-		return JSON.parse(text);
-	} catch {
-		return text;
+async function safeReadJson$1(response) {
+	const text = await response.text();
+	if (text.length === 0) return null;
+	try {
+		return JSON.parse(text);
+	} catch {
+		return text;
+	}
+}
+//#endregion
+//#region src/client/sse.ts
+async function readMengineEventStream(options) {
+	const response = await options.client.fetch(options.client.eventsUrl(), {
+		headers: options.client.headers(),
+		signal: options.signal
+	});
+	if (!response.ok) throw new Error(`mengine event stream failed: ${response.status}`);
+	const reader = response.body?.getReader();
+	if (reader == null) throw new Error("mengine event stream response has no readable body");
+	options.onOpen?.();
+	const decoder = new TextDecoder();
+	let buffer = "";
+	while (options.signal?.aborted !== true) {
+		const { done, value } = await reader.read();
+		if (done) return;
+		buffer += decoder.decode(value, { stream: true });
+		let splitAt = findSseFrameBoundary(buffer);
+		while (splitAt >= 0) {
+			const frame = buffer.slice(0, splitAt);
+			buffer = buffer.slice(buffer[splitAt] === "\r" ? splitAt + 4 : splitAt + 2);
+			handleSseFrame(frame, options);
+			splitAt = findSseFrameBoundary(buffer);
+		}
+	}
+}
+function handleSseFrame(frame, options) {
+	const event = parseSseFrame(frame);
+	if (event.event === "resync") {
+		options.onResync?.();
+		return;
+	}
+	if (event.event !== "update" || event.data.length === 0) return;
+	options.onUpdate(JSON.parse(event.data.join("\n")));
+}
+function parseSseFrame(frame) {
+	let event = null;
+	const data = [];
+	for (const line of frame.split(/\r?\n/)) if (line.startsWith("event:")) event = line.slice(6).trim();
+	else if (line.startsWith("data:")) data.push(line.slice(5).trimStart());
+	return {
+		event,
+		data
+	};
+}
+function findSseFrameBoundary(buffer) {
+	const lf = buffer.indexOf("\n\n");
+	const crlf = buffer.indexOf("\r\n\r\n");
+	if (lf < 0) return crlf;
+	if (crlf < 0) return lf;
+	return Math.min(lf, crlf);
+}
+//#endregion
+//#region src/entity-crdt/compile-rows.ts
+/** Lower a detached ordinary-object edit against its actual causal Loro baseline. */
+function compileEntityRows(snapshot, rows, validate, options = {}) {
+	const doc = new LoroDoc();
+	doc.import(snapshot);
+	return applyEntityRows(new LoroEntityDocument(doc, validate), rows, options);
+}
+/** Publish final rows as imported causal operations, outside the caller's local undo history. */
+function publishEntityRows(editor, rows, options = {}) {
+	const from = editor.doc.oplogVersion();
+	const compiled = compileEntityRows(editor.doc.export({ mode: "snapshot" }), rows, void 0, options);
+	editor.import(compiled.update);
+	return {
+		update: editor.doc.export({
+			mode: "update",
+			from
+		}),
+		state: editor.snapshot()
+	};
+}
+/** Compile an edit on an existing peer, retaining its native local undo history. */
+function applyEntityRows(editor, rows, options = {}) {
+	const baseline = editor.snapshot();
+	const before = baseline.rows;
+	const oldEntities = new Map(before.entities.map((row) => [row.entityId, row]));
+	const newEntities = new Map(rows.entities.map((row) => [row.entityId, row]));
+	const oldRelations = new Map(before.relations.map((row) => [row.relationId, row]));
+	const newRelations = new Map(rows.relations.map((row) => [row.relationId, row]));
+	const oldClipContent = new Map(before.relations.filter((row) => row.relationKind === "contain" && oldEntities.get(row.endpoint0EntityId)?.entityKind === "clip").map((row) => [row.endpoint0EntityId, row.relationId]));
+	const newClipContent = new Map(rows.relations.filter((row) => row.relationKind === "contain" && newEntities.get(row.endpoint0EntityId)?.entityKind === "clip").map((row) => [row.endpoint0EntityId, row.relationId]));
+	if (newEntities.size !== rows.entities.length || newRelations.size !== rows.relations.length) throw new Error("Duplicate domain identity");
+	validateEntityRelationTransition(before, rows);
+	return {
+		update: editor.transact((draft) => {
+			for (const row of before.relations) {
+				const next = newRelations.get(row.relationId);
+				if (!next) draft.unlink(row.relationId);
+				else {
+					if (next.relationKind !== row.relationKind || next.endpoint0EntityId !== row.endpoint0EntityId || next.endpoint1EntityId !== row.endpoint1EntityId) throw new Error("Relation identity cannot change kind or endpoint positions");
+					if (!equalJson(row.trace, next.trace)) draft.patchRelationTrace(row.relationId, next.trace);
+				}
+			}
+			let attached = baseline.project.audioScriptEntityId !== void 0;
+			for (const row of rows.entities) {
+				const previous = oldEntities.get(row.entityId);
+				if (!previous) {
+					draft.create(row);
+					if (!attached && row.entityKind === "audio-script") {
+						draft.attach("audioScriptEntityId", String(row.entityId));
+						attached = true;
+					}
+				} else {
+					if (previous.entityKind !== row.entityKind) throw new Error("Entity kind cannot change");
+					if (!equalJson(previous.payload, row.payload)) draft.replaceOwned(row.entityId, row.payload);
+				}
+			}
+			for (const row of rows.relations) if (!oldRelations.has(row.relationId)) draft.link(row);
+			for (const [clipId, relationId] of newClipContent) if (oldClipContent.get(clipId) !== relationId) draft.selectClipContent(relationId);
+			const beforeOrder = entityOrderGroups(before), afterOrder = entityOrderGroups(rows);
+			for (const group of new Set([...beforeOrder.keys(), ...afterOrder.keys()])) {
+				const next = afterOrder.get(group) ?? [];
+				if (!equalJson(beforeOrder.get(group) ?? [], next)) draft.order(group, next);
+			}
+			for (const row of before.entities) if (!newEntities.has(row.entityId)) draft.delete(row.entityId);
+			for (const [slot, entityId] of Object.entries(options.projectAttachments ?? {})) draft.attach(slot, entityId);
+			for (const [clipEntityId, phoneticScriptEntityId] of Object.entries(options.phoneticScriptSelections ?? {})) draft.selectPhoneticScript(clipEntityId, phoneticScriptEntityId);
+		}),
+		state: editor.snapshot()
+	};
+}
+//#endregion
+//#region src/entity-editor/document-audio-script.ts
+/** Read only the attached version and preserve every segment; never aggregate other scripts. */
+function readDocumentAudioScript(state) {
+	const id = state.audioScriptEntityId;
+	if (id === null) throw new EntityTimelineProjectionError("Document AudioScript is not initialized");
+	if (typeof id !== "string" || id.trim() !== id || !id) throw new EntityTimelineProjectionError("Invalid document AudioScript identity");
+	const entity = state.rows.entities.find((row) => row.entityId === id);
+	if (!entity || entity.entityKind !== "audio-script") throw new EntityTimelineProjectionError(`Document AudioScript ${id} must name the project AudioScript`);
+	const content = assembleEntityContent(state.rows, createEntityId(id));
+	assembleScriptText(content);
+	return {
+		entityId: id,
+		segments: structuredClone(content.payload.segments)
+	};
+}
+//#endregion
+//#region src/entity-editor/editor-resources.ts
+const roleOrder$1 = {
+	caption: 0,
+	video_clip: 1,
+	speech: 2,
+	bgm: 3
+};
+/**
+* MEngine editor policy, not a cardinality restriction on the general-purpose DSL.
+*
+* Resources live on Asset entities and are reached through `from-asset`: no
+* other entity carries a locator, one Asset claims each `(system, key)` pair,
+* and media reaches at most one Asset. Media whose bytes are not named through
+* that Relation is rejected rather than guessed at.
+*/
+function assertCanonicalEditorResources(rows) {
+	if (rows.entities.filter((row) => row.entityKind === "timeline").length > 1) throw new EntityTimelineProjectionError("Editor requires exactly one Timeline");
+	for (const role of Object.keys(roleOrder$1)) if (rows.entities.filter((row) => row.entityKind === "track" && row.payload.role === role).length > 1) throw new EntityTimelineProjectionError(`Editor has multiple ${role} Tracks`);
+	const identityByAssetKey = /* @__PURE__ */ new Map();
+	for (const entity of rows.entities) {
+		if (entity.entityKind === "asset") {
+			const locator = memotaLocator(entity.payload);
+			if (locator === void 0) throw new EntityTimelineProjectionError(`Asset ${entity.entityId} must state where its bytes live`);
+			const key = JSON.stringify([locator.system, locator.key]);
+			const previous = identityByAssetKey.get(key);
+			if (previous !== void 0 && previous !== entity.entityId) throw new EntityTimelineProjectionError(`Duplicate Asset for ${key}; reuse ${previous}`);
+			identityByAssetKey.set(key, entity.entityId);
+			continue;
+		}
+		if (memotaLocator(entity.payload) !== void 0) throw new EntityTimelineProjectionError(`Entity ${entity.entityId} must not carry a locator; link its Asset with from-asset`);
+	}
+	for (const entity of rows.entities) {
+		if (!isMediaAssetVariantKind(entity.entityKind)) continue;
+		if (assetIdsOf(rows, entity.entityId).length !== 1) throw new EntityTimelineProjectionError(`Media Entity ${entity.entityId} requires exactly one from-asset Asset`);
+	}
+}
+/** The Asset ids one entity reaches, in row order. */
+function assetIdsOf(rows, entityId) {
+	const assets = new Set(rows.entities.filter((row) => row.entityKind === "asset").map((row) => String(row.entityId)));
+	return rows.relations.filter((relation) => relation.relationKind === "from-asset").map((relation) => String(relation.endpoint0EntityId) === entityId ? String(relation.endpoint1EntityId) : String(relation.endpoint1EntityId) === entityId ? String(relation.endpoint0EntityId) : void 0).filter((id) => id !== void 0 && assets.has(id));
+}
+/**
+* Commit-transition policy shared by the editor, the HTTP commit boundary, the
+* host tool, and the entity stores. It compares the authoritative before and
+* after rows of one CAS commit and enforces the resource rules on the complete
+* after state, with no exemption for historical graphs:
+*
+* 1. every media Entity reaches exactly one Asset through `from-asset`;
+* 2. no entity other than an Asset carries a locator;
+* 3. an Asset's locator is immutable — pointing it at other bytes would
+*    silently rewrite every entity already made from it.
+*
+* Deleting media is explicit and allowed.
+*/
+function assertMediaAssetWritePolicy(before, after) {
+	const beforeEntities = new Map(before.entities.map((row) => [String(row.entityId), row]));
+	assertCanonicalEditorResources(after);
+	for (const relation of after.relations) {
+		if (relation.relationKind !== "from-asset" && relation.relationKind !== "to-asset") continue;
+		if (!isTranscribedAudioScript(after, relation.endpoint0EntityId)) continue;
+		if (before.relations.some((prior) => prior.relationKind === relation.relationKind && prior.endpoint0EntityId === relation.endpoint0EntityId && prior.endpoint1EntityId === relation.endpoint1EntityId)) continue;
+		throw new EntityTimelineProjectionError("ASR resources belong to Caption, not the transcribed AudioScript");
+	}
+	for (const row of after.entities) {
+		if (row.entityKind !== "asset") continue;
+		const prior = memotaLocator(beforeEntities.get(String(row.entityId))?.payload);
+		if (prior === void 0) continue;
+		const next = memotaLocator(row.payload);
+		if (next !== void 0 && (next.system !== prior.system || next.key !== prior.key)) throw new EntityTimelineProjectionError(`Asset ${row.entityId} cannot be pointed at other bytes; create a new Asset instead`);
+	}
+}
+function memotaLocator(value) {
+	if (!isJsonObject(value) || value.system !== "memota" && value.system !== "memota-speech" || typeof value.key !== "string" || value.key.trim() === "") return;
+	return {
+		system: value.system,
+		key: value.key
+	};
+}
+/**
+* Bootstrap an empty script when the foundation has no candidate. Without an
+* explicit project attachment, multiple candidates are ambiguous. Existing
+* content IDs are reused here; Loro editing advances their immutable versions.
+*/
+function ensureDocumentAudioScript(entities, selectedEntityId) {
+	if (selectedEntityId != null) {
+		if (!entities.some((row) => row.entityKind === "audio-script" && row.entityId === selectedEntityId)) throw new EntityTimelineProjectionError(`Selected AudioScript ${selectedEntityId} does not exist`);
+		return selectedEntityId;
+	}
+	const scripts = entities.filter((row) => row.entityKind === "audio-script");
+	if (scripts.length > 1) throw new EntityTimelineProjectionError("Select an AudioScript for the editor panel when multiple scripts exist");
+	return scripts[0]?.entityId ?? null;
+}
+/** Add only missing editor structure; existing identities and owned settings are never replaced. */
+function ensureEditorFoundation(initial, idFactory = (prefix) => `${prefix}_${globalThis.crypto.randomUUID()}`, timelinePayload = {}, selectedAudioScriptEntityId) {
+	const entities = structuredClone([...initial.entities]);
+	const relations = structuredClone([...initial.relations]);
+	const roots = entities.filter((row) => row.entityKind === "timeline");
+	if (roots.length > 1) throw new EntityTimelineProjectionError("Editor requires exactly one Timeline");
+	const mintEntity = () => {
+		const id = createEntityId(idFactory("entity"));
+		if (entities.some((row) => row.entityId === id)) throw new Error(`Duplicate entity id ${id}`);
+		return id;
+	};
+	let timeline = roots[0];
+	if (timeline === void 0) {
+		timeline = {
+			entityId: mintEntity(),
+			entityKind: "timeline",
+			payload: structuredClone(timelinePayload)
+		};
+		entities.push(timeline);
+	}
+	const trackEntityIds = {};
+	for (const role of Object.keys(roleOrder$1)) {
+		const matches = entities.filter((row) => row.entityKind === "track" && row.payload.role === role);
+		if (matches.length > 1) throw new EntityTimelineProjectionError(`Editor has multiple ${role} Tracks`);
+		let track = matches[0];
+		if (track === void 0) {
+			track = {
+				entityId: mintEntity(),
+				entityKind: "track",
+				payload: {
+					role,
+					order: roleOrder$1[role]
+				}
+			};
+			entities.push(track);
+		}
+		const bindings = relations.filter((row) => row.relationKind === "contain" && (row.endpoint0EntityId === track.entityId || row.endpoint1EntityId === track.entityId));
+		if (bindings.some((row) => row.endpoint0EntityId !== timeline.entityId && row.endpoint1EntityId !== timeline.entityId)) throw new EntityTimelineProjectionError(`Track ${track.entityId} belongs to another Timeline`);
+		if (bindings.length === 0) {
+			const relationId = createRelationId(idFactory("relation"));
+			if (relations.some((row) => row.relationId === relationId)) throw new Error(`Duplicate relation id ${relationId}`);
+			relations.push({
+				relationId,
+				relationKind: "contain",
+				endpoint0EntityId: timeline.entityId,
+				endpoint1EntityId: track.entityId,
+				metadata: {},
+				trace: {}
+			});
+		}
+		trackEntityIds[role] = track.entityId;
+	}
+	const audioScriptEntityId = ensureDocumentAudioScript(entities, selectedAudioScriptEntityId);
+	return {
+		rows: {
+			entities,
+			relations
+		},
+		timelineEntityId: timeline.entityId,
+		trackEntityIds,
+		audioScriptEntityId
+	};
+}
+//#endregion
+//#region src/entity-editor/entity-graph-http-client.ts
+const MENGINE_API_PREFIX = "/api/mengine/v1";
+var EntityGraphRevisionConflictError = class extends MengineHttpRequestError {
+	expectedRevision;
+	currentRevision;
+	constructor(expectedRevision, currentRevision, payload) {
+		super(409, payload);
+		this.expectedRevision = expectedRevision;
+		this.currentRevision = currentRevision;
+		this.name = "EntityGraphRevisionConflictError";
+	}
+};
+/** Browser-safe authenticated Loro client for a document's Entity graph. */
+var EntityGraphHttpClient = class {
+	options;
+	transport;
+	endpoint;
+	constructor(options) {
+		this.options = options;
+		this.transport = new MengineHttpClient(options);
+		const origin = options.httpOrigin.replace(/\/$/, "");
+		this.endpoint = `${origin}${MENGINE_API_PREFIX}/docs/${encodeURIComponent(options.docId)}/entity-state`;
+	}
+	async fetchState() {
+		return this.request({ method: "GET" });
+	}
+	/**
+	* Compile edits against the original causal snapshot and publish native Loro operations.
+	* The base revision is sent as an optimistic precondition, so a stale adoption
+	* fails loudly instead of letting Loro choose between concurrent selections.
+	*
+	* Deletion intent is derived from baseline IDs omitted from `nextRows`, so a
+	* transient create-then-remove never becomes a request to delete unknown
+	* persisted data.
+	*/
+	async commit(baseState, nextRows, options = {}) {
+		if (options.migrationBaseVv !== void 0) throw new Error("Legacy entity migration is not supported by the Loro contract");
+		const next = cloneAndValidateRows(nextRows);
+		assertMediaAssetWritePolicy(baseState.rows, next);
+		const compiled = compileEntityRows(base64ToBytes(baseState.loroSnapshot), next);
+		return this.commitUpdate(bytesToBase64(compiled.update), baseState.revision);
+	}
+	/** Send prepared bytes directly; omit `expectedRevision` for immutable fact publication. */
+	async commitUpdate(update, expectedRevision) {
+		if (expectedRevision !== void 0 && !isNonNegativeSafeInteger(expectedRevision)) throw new Error("expectedRevision must be a nonnegative safe integer");
+		return this.request({
+			method: "POST",
+			body: JSON.stringify({
+				update,
+				...expectedRevision === void 0 ? {} : { expected_revision: expectedRevision }
+			})
+		});
+	}
+	async request(init) {
+		const response = await this.transport.fetch(this.endpoint, {
+			...init,
+			headers: this.transport.headers()
+		});
+		const payload = await safeReadJson(response);
+		if (!response.ok) throw parseRevisionConflict(response.status, payload) ?? new MengineHttpRequestError(response.status, payload);
+		return parseWireState(payload, this.options.docId);
+	}
+};
+function parseRevisionConflict(status, value) {
+	if (status !== 409 || !isRecord(value) || !isRecord(value.error) || value.error.code !== "revision_conflict") return;
+	const error = value.error;
+	if (typeof error.message !== "string" || !isNonNegativeSafeInteger(error.expected_revision) || !isNonNegativeSafeInteger(error.current_revision)) return;
+	return new EntityGraphRevisionConflictError(error.expected_revision, error.current_revision, { error: {
+		code: "revision_conflict",
+		message: error.message,
+		expected_revision: error.expected_revision,
+		current_revision: error.current_revision
+	} });
+}
+function parseWireState(value, expectedDocId) {
+	if (!isRecord(value) || typeof value.doc_id !== "string" || !isNonNegativeSafeInteger(value.revision)) throw new Error("Invalid entity-state response envelope");
+	if (value.doc_id !== expectedDocId) throw new Error(`Entity-state response doc_id mismatch: expected "${expectedDocId}"`);
+	const rows = parseWireRows(value.rows);
+	decodeEntityRelationRows(rows, {});
+	const attached = value.audio_script_entity_id;
+	if (attached !== null && typeof attached !== "string") throw new Error("Invalid document AudioScript identity");
+	if (typeof value.loro_snapshot !== "string") throw new Error("Missing causal Loro snapshot");
+	const state = {
+		revision: value.revision,
+		loroSnapshot: value.loro_snapshot,
+		rows,
+		audioScriptEntityId: attached
+	};
+	if (attached !== null) readDocumentAudioScript(state);
+	return state;
+}
+function parseWireRows(value) {
+	if (!isRecord(value) || !Array.isArray(value.entities) || !Array.isArray(value.relations)) throw new Error("Invalid entity-state response rows");
+	return {
+		entities: value.entities.map(parseWireEntity),
+		relations: value.relations.map(parseWireRelation)
+	};
+}
+function parseWireEntity(value) {
+	if (!isRecord(value) || !isJsonObject(value.payload)) throw new Error("Invalid Entity row in entity-state response");
+	return {
+		entityId: createEntityId(requiredString(value.entity_id, "entity_id")),
+		entityKind: requiredString(value.entity_kind, "entity_kind"),
+		payload: structuredClone(value.payload)
+	};
+}
+function parseWireRelation(value) {
+	if (!isRecord(value) || !isJsonObject(value.metadata) || !isJsonObject(value.trace)) throw new Error("Invalid Relation row in entity-state response");
+	return {
+		relationId: createRelationId(requiredString(value.relation_id, "relation_id")),
+		relationKind: requiredString(value.relation_kind, "relation_kind"),
+		endpoint0EntityId: createEntityId(requiredString(value.endpoint_0_entity_id, "endpoint_0_entity_id")),
+		endpoint1EntityId: createEntityId(requiredString(value.endpoint_1_entity_id, "endpoint_1_entity_id")),
+		metadata: structuredClone(value.metadata),
+		trace: structuredClone(value.trace)
+	};
+}
+function cloneAndValidateRows(rows) {
+	const clone = structuredClone(rows);
+	decodeEntityRelationRows(clone, {});
+	return clone;
+}
+function requiredString(value, field) {
+	if (typeof value !== "string" || value.length === 0 || value.trim() !== value) throw new Error(`Invalid ${field} in entity-state response`);
+	return value;
+}
+function isRecord(value) {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function isNonNegativeSafeInteger(value) {
+	return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+}
+async function safeReadJson(response) {
+	const text = await response.text();
+	if (text.length === 0) return null;
+	try {
+		return JSON.parse(text);
+	} catch {
+		return text;
+	}
+}
+//#endregion
+//#region src/entity-editor/media-asset-import.ts
+/**
+* Import at the editor boundary, not at asset generation time. Existing
+* provenance is retained.
+*
+* The bytes are named once, on an Asset entity, and the media entity reaches
+* them through a `from-asset` Relation. Re-importing the same `(system, key)`
+* reuses that Asset and the media already made from it, so one stored resource
+* is never copied into several rows.
+*/
+function importMediaAsset(initial, fact, idFactory = (prefix) => `${prefix}_${globalThis.crypto.randomUUID()}`) {
+	if (!fact.assetId || fact.assetId.trim() !== fact.assetId) throw new Error("Expected an asset id");
+	if (![
+		"image",
+		"video",
+		"audio",
+		"voiceover-recording"
+	].includes(fact.kind)) throw new Error("Unsupported media kind");
+	if (fact.kind !== "image" && (!Number.isFinite(fact.durationMs) || fact.durationMs <= 0)) throw new Error(`${fact.kind} ${fact.assetId} requires its factual positive duration`);
+	if ((fact.kind === "audio" || fact.kind === "voiceover-recording") && fact.storageKey.trim() === "") throw new Error(`${fact.kind} ${fact.assetId} requires its physical storage key`);
+	decodeEntityRelationRows(initial, {});
+	assertCanonicalEditorResources(initial);
+	const entities = structuredClone([...initial.entities]);
+	const relations = structuredClone([...initial.relations]);
+	const system = fact.kind === "voiceover-recording" ? "memota-speech" : "memota";
+	const entityKind = fact.kind;
+	const timbre = fact.kind === "voiceover-recording" ? fact.voice : void 0;
+	const durationMs = fact.kind === "image" ? null : fact.durationMs;
+	const asset = ensureAsset(entities, {
+		system,
+		key: fact.assetId,
+		storageKey: fact.storageKey
+	}, idFactory);
+	const madeFromAsset = entities.filter((row) => row.entityId !== asset.entityId && assetIdOf(relations, row.entityId) === asset.entityId);
+	if (madeFromAsset.length > 1) throw new Error(`Duplicate media identities for ${fact.assetId}; reuse ${madeFromAsset[0].entityId}`);
+	const existing = madeFromAsset[0];
+	if (existing !== void 0) {
+		if (existing.entityKind !== entityKind || existing.payload.durationMs !== durationMs) throw new Error(`Media facts conflict with existing identity for ${fact.assetId}`);
+		const voiceEntityId = bindVoiceTimbre(entities, relations, existing.entityId, timbre, idFactory);
+		return {
+			rows: {
+				entities,
+				relations
+			},
+			contentEntityId: existing.entityId,
+			assetEntityId: asset.entityId,
+			...voiceEntityId
+		};
+	}
+	const entityId = createEntityId(idFactory("entity"));
+	if (entities.some((row) => row.entityId === entityId)) throw new Error(`Duplicate entity id ${entityId}`);
+	entities.push({
+		entityId,
+		entityKind,
+		payload: { durationMs }
+	});
+	relations.push(assetLink(entityId, asset.entityId, idFactory));
+	if (fact.kind === "voiceover-recording" && fact.phoneticScriptEntityId !== void 0) {
+		const phonetic = entities.find((row) => String(row.entityId) === fact.phoneticScriptEntityId);
+		if (phonetic?.entityKind !== "phonetic-script") throw new Error(`Voiceover ${fact.assetId} requires the PhoneticScript it was spoken from`);
+		relations.push({
+			relationId: createRelationId(idFactory("relation")),
+			relationKind: "derived-from",
+			endpoint0EntityId: entityId,
+			endpoint1EntityId: phonetic.entityId,
+			metadata: {},
+			trace: {}
+		});
+	}
+	const voiceEntityId = bindVoiceTimbre(entities, relations, entityId, timbre, idFactory);
+	const rows = {
+		entities,
+		relations
+	};
+	decodeEntityRelationRows(rows, {});
+	assertCanonicalEditorResources(rows);
+	return {
+		rows,
+		contentEntityId: entityId,
+		assetEntityId: asset.entityId,
+		...voiceEntityId
+	};
+}
+/** One Asset per `(system, key)`: the bytes are named in exactly one row. */
+function ensureAsset(entities, locator, idFactory) {
+	const found = entities.find((row) => row.entityKind === "asset" && row.payload.system === locator.system && row.payload.key === locator.key);
+	if (found !== void 0) {
+		if (locator.storageKey === void 0 || found.payload.storageKey === locator.storageKey) return found;
+		if (found.payload.storageKey !== void 0) throw new Error(`Media facts conflict with existing storage key for ${locator.key}`);
+		const filled = {
+			...found,
+			payload: {
+				...found.payload,
+				storageKey: locator.storageKey
+			}
+		};
+		replaceEntity$1(entities, found.entityId, filled);
+		return filled;
+	}
+	const asset = {
+		entityId: createEntityId(idFactory("entity")),
+		entityKind: "asset",
+		payload: {
+			system: locator.system,
+			key: locator.key,
+			...locator.storageKey === void 0 ? {} : { storageKey: locator.storageKey }
+		}
+	};
+	entities.push(asset);
+	return asset;
+}
+function assetLink(entityId, assetEntityId, idFactory) {
+	return {
+		relationId: createRelationId(idFactory("relation")),
+		relationKind: "from-asset",
+		endpoint0EntityId: createEntityId(entityId),
+		endpoint1EntityId: createEntityId(assetEntityId),
+		metadata: {},
+		trace: {}
+	};
+}
+function assetIdOf(relations, entityId) {
+	const link = relations.find((relation) => relation.relationKind === "from-asset" && (relation.endpoint0EntityId === entityId || relation.endpoint1EntityId === entityId));
+	if (link === void 0) return void 0;
+	return String(link.endpoint0EntityId === entityId ? link.endpoint1EntityId : link.endpoint0EntityId);
+}
+/**
+* Attach the timbre a synthesized voiceover was rendered with. One Voice
+* identity is shared by every take naming the same library entry, so an
+* existing row is reused rather than duplicated. Recorded media declares no
+* timbre and keeps no link.
+*/
+function bindVoiceTimbre(entities, relations, audioEntityId, descriptor, idFactory) {
+	const linked = relations.filter((relation) => relation.relationKind === "voice-timbre" && (relation.endpoint0EntityId === audioEntityId || relation.endpoint1EntityId === audioEntityId));
+	if (linked.length > 1) throw new Error(`Voiceover ${audioEntityId} has multiple Voice timbre relations`);
+	if (descriptor === void 0) {
+		if (linked.length > 0) throw new Error(`Recorded media ${audioEntityId} cannot keep a synthesized Voice timbre`);
+		return {};
+	}
+	const voice = entities.find((row) => row.entityKind === "voice" && sameVoiceDescriptor(row.payload.voice, descriptor)) ?? appendVoiceIdentity(entities, descriptor, idFactory);
+	const existing = linked[0];
+	if (existing === void 0) relations.push({
+		relationId: createRelationId(idFactory("relation")),
+		relationKind: "voice-timbre",
+		endpoint0EntityId: createEntityId(audioEntityId),
+		endpoint1EntityId: createEntityId(voice.entityId),
+		metadata: {},
+		trace: {}
+	});
+	else if (existing.endpoint0EntityId !== audioEntityId || existing.endpoint1EntityId !== voice.entityId) throw new Error(`Voiceover ${audioEntityId} already carries a different Voice timbre`);
+	return { voiceEntityId: voice.entityId };
+}
+function appendVoiceIdentity(entities, descriptor, idFactory) {
+	const voice = {
+		entityId: createEntityId(idFactory("entity")),
+		entityKind: "voice",
+		payload: { voice: {
+			system: descriptor.system,
+			key: descriptor.key,
+			...descriptor.name === void 0 ? {} : { name: descriptor.name }
+		} }
+	};
+	entities.push(voice);
+	return voice;
+}
+/** Two takes share a Voice identity only when they name the same library entry. */
+function sameVoiceDescriptor(stored, descriptor) {
+	return isJsonObject(stored) && stored.system === descriptor.system && stored.key === descriptor.key && stored.name === descriptor.name;
+}
+function replaceEntity$1(entities, entityId, replacement) {
+	const index = entities.findIndex((row) => row.entityId === entityId);
+	if (index < 0) throw new Error(`Entity id ${entityId} does not exist`);
+	entities[index] = replacement;
+}
+//#endregion
+//#region src/entity-editor/entity-timeline-editor.ts
+/**
+* Resolve the AudioScript a PhoneticScript composes. The composition is the
+* required text source: a variant without it has no content and fails here.
+*/
+function requireComposedAudioScript(rows, phoneticScriptEntityId) {
+	return assemblePhoneticScriptContent(rows, phoneticScriptEntityId).audioScript.entityId;
+}
+function captionSelection(selection) {
+	return structuredClone(selection);
+}
+function captionBaseIds(ids) {
+	if (!Array.isArray(ids) || ids.length === 0) throw new Error("Caption requires non-empty baseEntityIds");
+	return ids.map(createEntityId);
+}
+function assertCaptionScript(rows, captionId, scriptId) {
+	if (assembleCaptionContent(rows, captionId).audioScript.entityId !== scriptId) throw new Error("Voiceover Caption must compose the same AudioScript as the PhoneticScript");
+}
+const roleOrder = {
+	caption: 0,
+	video_clip: 1,
+	speech: 2,
+	bgm: 3
+};
+const defaultIdFactory = (prefix) => `${prefix}_${globalThis.crypto.randomUUID()}`;
+/**
+* Graph-native timeline authoring over authoritative Medeo Entity and Relation rows.
+*
+* Each mutation is applied to a detached graph, validated as a complete DSL set,
+* and committed only after validation succeeds.
+*/
+var EntityTimelineEditor = class {
+	idFactory;
+	state;
+	constructor(initialRows, idFactory = defaultIdFactory) {
+		this.idFactory = idFactory;
+		this.state = cloneRows(initialRows);
+	}
+	rows() {
+		return cloneRows(this.state);
+	}
+	insertClip(input) {
+		const requestedOrder = input.order;
+		const order = typeof requestedOrder === "number" ? requestedOrder : nextSequentialOrder(this.state, createEntityId(input.trackEntityId));
+		return this.insertPlacedClip({
+			trackEntityId: input.trackEntityId,
+			contentEntityId: input.contentEntityId,
+			inMs: input.inMs,
+			outMs: input.outMs,
+			placement: input.startMs === void 0 ? {
+				kind: "sequential",
+				order
+			} : {
+				kind: "absolute",
+				startMs: input.startMs
+			},
+			clipPayload: input.clipPayload
+		});
+	}
+	insertPlacedClip(input) {
+		return this.transact((draft) => this.insertPlacedClipIntoDraft(draft, input));
+	}
+	updateClipMarker(input) {
+		this.transact((draft) => {
+			const { marker } = requireClipTopology(draft, input.clipEntityId);
+			const payload = { ...cloneJsonObject(marker.payload, "Sequence Marker payload") };
+			if (input.inMs !== void 0) payload.inMs = finiteNonNegative(input.inMs, "inMs");
+			if (input.outMs !== void 0) payload.outMs = finitePositive(input.outMs, "outMs");
+			if (Object.hasOwn(input, "startMs")) if (input.startMs === void 0) {
+				delete payload.startMs;
+				if (!hasOutgoingClipAnchor(draft, input.clipEntityId)) {}
+			} else payload.startMs = finiteNonNegative(input.startMs, "startMs");
+			if (Object.hasOwn(input, "rate")) if (input.rate === void 0) delete payload.rate;
+			else payload.rate = finitePositive(input.rate, "linear speed rate");
+			replaceEntity(draft, marker.entityId, {
+				...marker,
+				payload
+			});
+		});
+	}
+	setClipPlacement(input) {
+		this.transact((draft) => this.applyClipPlacement(draft, input.clipEntityId, input.placement));
+	}
+	moveSequentialClips(input) {
+		if (input.clipEntityIds.length === 0) throw new Error("At least one Clip is required");
+		this.transact((draft) => {
+			const original = resolveEntityTimelineLayout(draft);
+			this.normalizeMainSequential(draft);
+			const before = resolveEntityTimelineLayout(draft);
+			const targetIds = new Set(input.clipEntityIds);
+			if (targetIds.size !== input.clipEntityIds.length) throw new Error("Clip ids must be unique");
+			const placements = input.clipEntityIds.map((id) => before.clips.get(id));
+			if (placements.some((placement) => placement === void 0 || placement.mode !== "sequential")) throw new Error("moveSequentialClips accepts only sequential Clips");
+			const trackIds = new Set(placements.map((placement) => placement.trackEntityId));
+			if (trackIds.size !== 1) throw new Error("Moved Clips must belong to one Track");
+			const trackId = [...trackIds][0];
+			const track = before.tracks.find((candidate) => candidate.entityId === trackId);
+			if (track?.role !== "video_clip") throw new Error("Only the video_clip Track supports sequential block moves");
+			const ordered = track.clips.filter((placement) => placement.mode === "sequential").map((placement) => placement.clipEntityId);
+			if (input.anchor.position !== "trackStart" && targetIds.has(input.anchor.clipEntityId)) throw new Error("Move anchor cannot be one of the moved Clips");
+			const moved = ordered.filter((id) => targetIds.has(id));
+			if (moved.length !== targetIds.size) throw new Error("Every moved Clip must exist on the target Track");
+			const remaining = ordered.filter((id) => !targetIds.has(id));
+			let insertAt = 0;
+			if (input.anchor.position !== "trackStart") {
+				const anchorIndex = remaining.indexOf(input.anchor.clipEntityId);
+				if (anchorIndex < 0) throw new Error("Move anchor Clip does not exist on the target Track");
+				insertAt = anchorIndex + (input.anchor.position === "after" ? 1 : 0);
+			}
+			[
+				...remaining.slice(0, insertAt),
+				...moved,
+				...remaining.slice(insertAt)
+			].forEach((clipId, order) => setClipOrder(draft, clipId, order));
+			if (input.onAnchored === "keepAbsolute") {
+				const affected = outgoingAnchorChildren(draft, new Set(track.clips.map((clip) => clip.clipEntityId))).filter((childId) => clipRole(draft, childId) === "speech").map((childId) => {
+					const placement = original.clips.get(childId);
+					if (placement === void 0) throw new Error(`Anchored child Clip "${childId}" is not placed`);
+					return {
+						childId,
+						start: placement.start
+					};
+				});
+				const after = resolveEntityTimelineLayout(draft);
+				for (const child of affected) this.reanchorAtAbsolute(draft, child.childId, child.start, after);
+			}
+			this.resolveOneVoiceoverOverlap(draft);
+		});
+	}
+	moveClipsToStarts(input) {
+		if (input.moves.length === 0) throw new Error("At least one Clip move is required");
+		this.transact((draft) => {
+			const original = resolveEntityTimelineLayout(draft);
+			const originalVideo = original.tracks.find((track) => track.role === "video_clip");
+			if (originalVideo === void 0) throw new Error("The timeline has no video_clip Track");
+			const preservedVoiceovers = outgoingAnchorChildren(draft, new Set(originalVideo.clips.map((clip) => clip.clipEntityId))).filter((clipId) => clipRole(draft, clipId) === "speech").map((clipId) => ({
+				clipId,
+				start: original.clips.get(clipId).start
+			}));
+			this.normalizeMainSequential(draft);
+			for (const move of input.moves) {
+				finiteNonNegative(move.newStartMs, "newStartMs");
+				requireClipOnRole(draft, move.clipEntityId, "video_clip");
+				const track = resolveEntityTimelineLayout(draft).tracks.find((candidate) => candidate.role === "video_clip");
+				const ordered = track.clips.map((clip) => clip.clipEntityId);
+				const from = ordered.indexOf(move.clipEntityId);
+				if (from < 0) throw new Error(`Clip "${move.clipEntityId}" is not on the video_clip Track`);
+				const remaining = track.clips.filter((clip) => clip.clipEntityId !== move.clipEntityId);
+				let cursor = 0;
+				let target = remaining.length;
+				for (const [index, clip] of remaining.entries()) {
+					if (move.newStartMs <= cursor + clip.duration / 2) {
+						target = index;
+						break;
+					}
+					cursor += clip.duration;
+				}
+				const next = [...ordered];
+				next.splice(from, 1);
+				next.splice(target, 0, move.clipEntityId);
+				next.forEach((clipId, order) => setClipOrder(draft, clipId, order));
+			}
+			const after = resolveEntityTimelineLayout(draft);
+			for (const voiceover of preservedVoiceovers) this.reanchorAtAbsolute(draft, voiceover.clipId, voiceover.start, after);
+			this.resolveOneVoiceoverOverlap(draft);
+		});
+	}
+	moveClip(input) {
+		this.transact((draft) => {
+			const topology = requireClipTopology(draft, input.clipEntityId);
+			const track = requireEntityKind(draft, input.trackEntityId, "track");
+			requireTrackTimeline(draft, track.entityId);
+			this.relinkRelation(draft, topology.trackRelation, {
+				endpoint0EntityId: track.entityId,
+				endpoint1EntityId: topology.clip.entityId
+			});
+		});
+	}
+	replaceClipContent(input) {
+		this.transact((draft) => {
+			const topology = requireClipTopology(draft, input.clipEntityId);
+			const content = requireSequenceContent(draft, input.contentEntityId);
+			const payload = {
+				...cloneJsonObject(topology.marker.payload, "Sequence Marker payload"),
+				...requireWindow(input.inMs, input.outMs)
+			};
+			delete payload.startMs;
+			delete payload.rate;
+			if (input.startMs !== void 0) payload.startMs = finiteNonNegative(input.startMs, "startMs");
+			if (input.rate !== void 0) payload.rate = finitePositive(input.rate, "linear speed rate");
+			replaceEntity(draft, topology.marker.entityId, {
+				...topology.marker,
+				payload
+			});
+			this.relinkRelation(draft, topology.contentRelation, {
+				endpoint0EntityId: topology.clip.entityId,
+				endpoint1EntityId: content.entityId
+			});
+		});
+	}
+	insertMediaClip(input) {
+		return this.transact((draft) => {
+			if (input.placement.kind === "sequential") this.normalizeMainSequential(draft);
+			const imported = importMediaAsset(draft, input.media, this.idFactory);
+			replaceRows(draft, imported.rows);
+			const track = this.ensureRoleTrack(draft, input.timelineEntityId, "video_clip");
+			const window = requireWindow(input.inMs, input.outMs);
+			const clipId = this.insertPlacedClipIntoDraft(draft, {
+				trackEntityId: track.entityId,
+				contentEntityId: imported.contentEntityId,
+				...window,
+				placement: input.placement,
+				...input.clipEntityId === void 0 ? {} : { clipEntityId: input.clipEntityId },
+				...input.volume === void 0 ? {} : { clipPayload: { volume: requireVolume(input.volume) } }
+			});
+			if (input.placement.kind === "sequential") this.resolveOneVoiceoverOverlap(draft);
+			return clipId;
+		});
+	}
+	insertMediaClips(input) {
+		if (input.clips.length === 0) throw new Error("At least one media Clip is required");
+		return this.transact((draft) => {
+			this.normalizeMainSequential(draft);
+			const track = this.ensureRoleTrack(draft, input.timelineEntityId, "video_clip");
+			const ordered = resolveEntityTimelineLayout(draft).tracks.find((candidate) => candidate.entityId === track.entityId)?.clips ?? [];
+			let insertAt = ordered.length;
+			const insertion = input.insertion;
+			if (insertion.kind === "before" || insertion.kind === "after") {
+				const anchorIndex = ordered.findIndex((clip) => clip.clipEntityId === insertion.clipEntityId);
+				if (anchorIndex >= 0) insertAt = anchorIndex + (insertion.kind === "after" ? 1 : 0);
+			} else {
+				const startMs = finiteNonNegative(insertion.startMs, "firstStart.startMs");
+				let cursor = 0;
+				for (const [index, clip] of ordered.entries()) {
+					if (startMs <= cursor + clip.duration / 2) {
+						insertAt = index;
+						break;
+					}
+					cursor += clip.duration;
+				}
+			}
+			const created = [];
+			for (const [offset, clip] of input.clips.entries()) {
+				const imported = importMediaAsset(draft, clip.media, this.idFactory);
+				replaceRows(draft, imported.rows);
+				const window = requireWindow(clip.inMs, clip.outMs);
+				created.push(this.insertPlacedClipIntoDraft(draft, {
+					trackEntityId: track.entityId,
+					contentEntityId: imported.contentEntityId,
+					...window,
+					placement: {
+						kind: "sequential",
+						order: ordered.length + offset
+					},
+					...clip.clipEntityId === void 0 ? {} : { clipEntityId: clip.clipEntityId },
+					...clip.volume === void 0 ? {} : { clipPayload: { volume: requireVolume(clip.volume) } }
+				}));
+			}
+			const desired = ordered.map((clip) => clip.clipEntityId);
+			desired.splice(insertAt, 0, ...created);
+			desired.forEach((clipId, order) => setClipOrder(draft, clipId, order));
+			this.resolveOneVoiceoverOverlap(draft);
+			return created;
+		});
+	}
+	replaceMediaClip(input) {
+		this.transact((draft) => {
+			this.normalizeMainSequential(draft);
+			const topology = requireClipOnRole(draft, input.clipEntityId, "video_clip");
+			const imported = importMediaAsset(draft, input.media, this.idFactory);
+			replaceRows(draft, imported.rows);
+			const window = requireWindow(input.inMs, input.outMs);
+			const markerPayloadValue = {
+				...cloneJsonObject(topology.marker.payload, "Sequence Marker payload"),
+				...window
+			};
+			delete markerPayloadValue.rate;
+			replaceEntity(draft, topology.marker.entityId, {
+				...topology.marker,
+				payload: markerPayloadValue
+			});
+			this.relinkRelation(draft, topology.contentRelation, {
+				endpoint0EntityId: topology.clip.entityId,
+				endpoint1EntityId: createEntityId(imported.contentEntityId)
+			});
+			this.resolveOneVoiceoverOverlap(draft);
+		});
+	}
+	setClipVolume(input) {
+		this.transact((draft) => {
+			const topology = requireClipTopology(draft, input.clipEntityId);
+			requireSupportedRole(draft, topology);
+			replaceEntity(draft, topology.clip.entityId, {
+				...topology.clip,
+				payload: {
+					...topology.clip.payload,
+					volume: requireVolume(input.volume)
+				}
+			});
+		});
+	}
+	setClipSpeed(input) {
+		this.transact((draft) => {
+			const initialTopology = requireClipOnRole(draft, input.clipEntityId, "video_clip");
+			const content = requireSequenceContent(draft, otherEndpoint(initialTopology.contentRelation, initialTopology.clip.entityId));
+			if (content.entityKind !== "video" && content.entityKind !== "image") throw new Error("Clip speed is supported only for Video or Image content");
+			const initialPayload = cloneJsonObject(initialTopology.marker.payload, "Sequence Marker payload");
+			const priorWindow = markerWindow(initialPayload);
+			if (input.rate === null && initialPayload.rate === void 0) return;
+			this.normalizeMainSequential(draft);
+			const topology = requireClipTopology(draft, input.clipEntityId);
+			const payload = { ...cloneJsonObject(topology.marker.payload, "Sequence Marker payload") };
+			const window = content.entityKind === "image" && initialPayload.rate === void 0 && input.rate !== null ? {
+				inMs: 0,
+				outMs: markerDuration(initialPayload, priorWindow)
+			} : priorWindow;
+			Object.assign(payload, window);
+			if (input.rate === null) delete payload.rate;
+			else {
+				const rate = finitePositive(input.rate, "linear speed rate");
+				const duration = Math.round((window.outMs - window.inMs) / rate);
+				if (duration <= 0 || !Number.isSafeInteger(duration)) throw new Error("Linear speed produces an invalid duration");
+				payload.rate = rate;
+			}
+			replaceEntity(draft, topology.marker.entityId, {
+				...topology.marker,
+				payload
+			});
+			this.resolveOneVoiceoverOverlap(draft);
+		});
+	}
+	trimClip(input) {
+		this.transact((draft) => {
+			this.normalizeMainSequential(draft);
+			const topology = requireClipOnRole(draft, input.clipEntityId, "video_clip");
+			const content = requireSequenceContent(draft, otherEndpoint(topology.contentRelation, topology.clip.entityId));
+			if (content.entityKind !== "video" && content.entityKind !== "image") throw new Error("Clip trimming is supported only for Video or Image content");
+			const window = requireWindow(input.inMs, input.outMs);
+			const payload = {
+				...cloneJsonObject(topology.marker.payload, "Sequence Marker payload"),
+				...window
+			};
+			const duration = markerDuration(payload, window);
+			if (duration <= 0 || !Number.isSafeInteger(duration)) throw new Error("Trim produces an invalid duration");
+			replaceEntity(draft, topology.marker.entityId, {
+				...topology.marker,
+				payload
+			});
+			this.resolveOneVoiceoverOverlap(draft);
+		});
+	}
+	replaceSequentialClips(input) {
+		if (input.oldClipEntityIds.length === 0 || input.newClips.length === 0) throw new Error("Replacement requires at least one old and one new Clip");
+		return this.transact((draft) => {
+			this.normalizeMainSequential(draft);
+			const before = resolveEntityTimelineLayout(draft);
+			const oldIds = new Set(input.oldClipEntityIds);
+			if (oldIds.size !== input.oldClipEntityIds.length) throw new Error("Old Clip ids must be unique");
+			const track = this.ensureRoleTrack(draft, input.timelineEntityId, "video_clip");
+			const ordered = before.tracks.find((candidate) => candidate.entityId === track.entityId)?.clips.filter((clip) => clip.mode === "sequential").map((clip) => clip.clipEntityId);
+			if (ordered === void 0) throw new Error("The video_clip Track is not present in the current layout");
+			const indexes = input.oldClipEntityIds.map((id) => ordered.indexOf(id));
+			if (indexes.some((index) => index < 0)) throw new Error("Every replaced Clip must be sequential on video_clip");
+			const sortedIndexes = [...indexes].sort((left, right) => left - right);
+			if (sortedIndexes.some((index, offset) => index !== sortedIndexes[0] + offset)) throw new Error("Replaced Clips must form one contiguous timeline run");
+			if (input.oldClipEntityIds.some((id, index) => id !== ordered[sortedIndexes[0] + index])) throw new Error("Replaced Clip ids must be listed in timeline order");
+			const insertOrder = sortedIndexes[0];
+			const temporaryOrder = ordered.length;
+			const created = [];
+			for (const [offset, replacement] of input.newClips.entries()) {
+				if (replacement.clipEntityId !== void 0 && oldIds.has(replacement.clipEntityId)) throw new Error("A replacement Clip id cannot reuse an Entity being removed");
+				const imported = importMediaAsset(draft, replacement.media, this.idFactory);
+				replaceRows(draft, imported.rows);
+				const window = requireWindow(replacement.inMs, replacement.outMs);
+				created.push(this.insertPlacedClipIntoDraft(draft, {
+					trackEntityId: track.entityId,
+					contentEntityId: imported.contentEntityId,
+					...window,
+					placement: {
+						kind: "sequential",
+						order: temporaryOrder + offset
+					},
+					...replacement.clipEntityId === void 0 ? {} : { clipEntityId: replacement.clipEntityId },
+					...replacement.volume === void 0 ? {} : { clipPayload: { volume: requireVolume(replacement.volume) } }
+				}));
+			}
+			for (const [index, oldId] of input.oldClipEntityIds.entries()) {
+				const children = directAnchorChildren(draft, oldId);
+				if (input.onAnchored === "remap" && created[index] !== void 0) for (const childId of children) this.replaceAnchorHost(draft, childId, created[index]);
+				else {
+					const scheduled = /* @__PURE__ */ new Set();
+					for (const childId of children) {
+						scheduled.add(childId);
+						this.removeAnchoredDescendants(draft, childId, scheduled);
+						this.removeClipGraph(draft, childId);
+					}
+				}
+			}
+			for (const oldId of input.oldClipEntityIds) this.removeClipGraph(draft, oldId);
+			[
+				...ordered.slice(0, insertOrder),
+				...created,
+				...ordered.slice(insertOrder + input.oldClipEntityIds.length)
+			].forEach((clipId, order) => setClipOrder(draft, clipId, order));
+			this.resolveOneVoiceoverOverlap(draft);
+			return created;
+		});
+	}
+	deleteClip(input) {
+		this.transact((draft) => {
+			const topology = requireClipTopology(draft, input.clipEntityId);
+			assertOnlyStructuralIncidents(draft, topology.clip.entityId, new Set(["contain", "marker"]));
+			assertOnlyStructuralIncidents(draft, topology.marker.entityId, new Set(["marker"]));
+			const markerIsExclusive = incidentRelations(draft, topology.marker.entityId).filter((relation) => relation.relationKind === "marker").length === 1;
+			const removedRelationIds = new Set([
+				topology.trackRelation.relationId,
+				topology.clipMarkerRelation.relationId,
+				topology.contentRelation.relationId
+			]);
+			if (markerIsExclusive) for (const relation of incidentRelations(draft, topology.marker.entityId)) removedRelationIds.add(relation.relationId);
+			draft.relations = draft.relations.filter((relation) => !removedRelationIds.has(relation.relationId));
+			draft.entities = draft.entities.filter((entity) => entity.entityId !== topology.clip.entityId && (!markerIsExclusive || entity.entityId !== topology.marker.entityId));
+		});
+	}
+	deleteClipTree(input) {
+		if (input.clipEntityIds.length === 0) throw new Error("At least one Clip is required");
+		this.transact((draft) => {
+			const targets = new Set(input.clipEntityIds);
+			if (targets.size !== input.clipEntityIds.length) throw new Error("Clip ids must be unique");
+			for (const target of targets) requireEntityKind(draft, target, "clip");
+			const includesVisual = [...targets].some((target) => clipRole(draft, target) === "video_clip");
+			const original = resolveEntityTimelineLayout(draft);
+			if (includesVisual) this.normalizeMainSequential(draft);
+			if (input.onAnchored === "detach") for (const childId of outgoingAnchorChildren(draft, targets)) {
+				if (targets.has(childId)) continue;
+				const placement = original.clips.get(childId);
+				if (placement === void 0) throw new Error(`Anchored child Clip "${childId}" is not placed`);
+				this.applyClipPlacement(draft, childId, {
+					kind: "absolute",
+					startMs: placement.start
+				});
+			}
+			else for (const target of targets) this.removeAnchoredDescendants(draft, target, targets);
+			for (const target of targets) this.removeClipGraph(draft, target);
+			if (includesVisual) this.resolveOneVoiceoverOverlap(draft);
+		});
+	}
+	updateClip(input) {
+		this.transact((draft) => {
+			const clip = requireEntityKind(draft, input.clipEntityId, "clip");
+			replaceEntity(draft, clip.entityId, {
+				...clip,
+				payload: cloneJsonObject(input.payload, "Clip payload")
+			});
+		});
+	}
+	upsertVoiceoverTake(input) {
+		return this.transact((draft) => {
+			this.normalizeMainSequential(draft);
+			const placement = input.placement ?? {
+				kind: "anchored",
+				hostClipEntityId: input.hostClipEntityId,
+				startMs: input.startMs
+			};
+			if (input.placement !== void 0 && (input.hostClipEntityId !== void 0 || input.startMs !== void 0)) throw new Error("Specify voiceover placement or hostClipEntityId/startMs, not both");
+			requireVolume(input.volume);
+			const imported = importMediaAsset(draft, input.media, this.idFactory);
+			replaceRows(draft, imported.rows);
+			const voiceover = requireEntityKind(draft, imported.contentEntityId, "voiceover-recording");
+			const phonetic = this.requireComposedPhoneticScript(draft, input.phoneticScriptEntityId);
+			this.ensurePhoneticRender(draft, voiceover.entityId, phonetic.entityId);
+			const speechTrack = this.ensureRoleTrack(draft, input.timelineEntityId, "speech");
+			const existing = draft.entities.find((row) => row.entityId === input.voiceoverClipEntityId);
+			let voiceoverClipEntityId;
+			if (existing === void 0) voiceoverClipEntityId = this.insertPlacedClipIntoDraft(draft, {
+				clipEntityId: input.voiceoverClipEntityId,
+				trackEntityId: speechTrack.entityId,
+				contentEntityId: voiceover.entityId,
+				inMs: 0,
+				outMs: input.media.durationMs,
+				placement,
+				clipPayload: { volume: input.volume }
+			});
+			else {
+				const topology = requireClipOnRole(draft, input.voiceoverClipEntityId, "speech");
+				voiceoverClipEntityId = topology.clip.entityId;
+				replaceEntity(draft, topology.clip.entityId, {
+					...topology.clip,
+					payload: {
+						...topology.clip.payload,
+						volume: input.volume
+					}
+				});
+				this.relinkRelation(draft, topology.contentRelation, {
+					endpoint0EntityId: topology.clip.entityId,
+					endpoint1EntityId: voiceover.entityId
+				});
+				this.applyClipPlacement(draft, topology.clip.entityId, placement);
+				const placed = requireClipTopology(draft, topology.clip.entityId);
+				replaceEntity(draft, placed.marker.entityId, {
+					...placed.marker,
+					payload: {
+						...placed.marker.payload,
+						inMs: 0,
+						outMs: input.media.durationMs
+					}
+				});
+			}
+			this.reconcileVoiceoverCaptions(draft, voiceoverClipEntityId, phonetic.entityId, input.captions);
+			this.resolveOneVoiceoverOverlap(draft);
+			return {
+				voiceoverClipEntityId,
+				voiceoverAudioEntityId: voiceover.entityId,
+				...imported.voiceEntityId === void 0 ? {} : { voiceEntityId: imported.voiceEntityId },
+				phoneticScriptEntityId: phonetic.entityId,
+				audioScriptEntityId: requireComposedAudioScript(draft, phonetic.entityId),
+				captionClipEntityIds: input.captions.map((caption) => caption.captionClipEntityId)
+			};
+		});
+	}
+	moveVoiceover(input) {
+		this.transact((draft) => {
+			requireClipOnRole(draft, input.voiceoverClipEntityId, "speech");
+			this.normalizeMainSequential(draft);
+			const layout = resolveEntityTimelineLayout(draft);
+			this.reanchorAtAbsolute(draft, input.voiceoverClipEntityId, finiteNonNegative(input.newStartMs, "newStartMs"), layout);
+			this.resolveOneVoiceoverOverlap(draft);
+		});
+	}
+	deleteVoiceover(input) {
+		this.transact((draft) => {
+			this.normalizeMainSequential(draft);
+			const targets = new Set(input.voiceoverClipEntityIds);
+			if (targets.size !== input.voiceoverClipEntityIds.length) throw new Error("Voiceover Clip ids must be unique");
+			for (const clipId of targets) {
+				requireClipOnRole(draft, clipId, "speech");
+				this.removeAnchoredDescendants(draft, clipId, targets);
+			}
+			for (const clipId of targets) this.removeClipGraph(draft, clipId);
+			this.resolveOneVoiceoverOverlap(draft);
+		});
+	}
+	setBgm(input) {
+		return this.transact((draft) => {
+			const imported = importMediaAsset(draft, input.media, this.idFactory);
+			replaceRows(draft, imported.rows);
+			const track = this.ensureRoleTrack(draft, input.timelineEntityId, "bgm");
+			const existing = clipsOnTrack(draft, track.entityId);
+			for (const clip of existing) this.removeClipGraph(draft, clip.entityId);
+			const clipId = this.insertPlacedClipIntoDraft(draft, {
+				clipEntityId: input.bgmClipEntityId,
+				trackEntityId: track.entityId,
+				contentEntityId: imported.contentEntityId,
+				inMs: 0,
+				outMs: input.media.durationMs,
+				placement: {
+					kind: "sequential",
+					order: 0
+				},
+				clipPayload: { volume: requireVolume(input.volume) }
+			});
+			const topology = requireClipTopology(draft, clipId);
+			replaceEntity(draft, topology.marker.entityId, {
+				...topology.marker,
+				payload: {
+					...topology.marker.payload,
+					fillTimeline: true
+				}
+			});
+			return clipId;
+		});
+	}
+	deleteBgm(input) {
+		this.transact((draft) => {
+			const track = findRoleTrack(draft, input.timelineEntityId, "bgm");
+			if (track === void 0) return;
+			for (const clip of clipsOnTrack(draft, track.entityId)) this.removeClipGraph(draft, clip.entityId);
+		});
+	}
+	setCaptionVisibility(input) {
+		this.transact((draft) => {
+			const track = this.ensureRoleTrack(draft, input.timelineEntityId, "caption");
+			replaceEntity(draft, track.entityId, {
+				...track,
+				payload: {
+					...track.payload,
+					hidden: input.hidden
+				}
+			});
+		});
+	}
+	patchCaptionStyle(input) {
+		this.transact((draft) => {
+			const track = findRoleTrack(draft, input.timelineEntityId, "caption");
+			if (track === void 0) return;
+			const patch = cloneJsonObject(input.style, "Caption style");
+			const assembled = new EntityProjectionGraph(draft);
+			for (const clip of clipsOnTrack(draft, track.entityId)) {
+				const topology = requireClipTopology(draft, clip.entityId);
+				const caption = requireEntityKind(draft, otherEndpoint(topology.contentRelation, topology.clip.entityId), "caption");
+				const prior = assembled.entity(caption.entityId).payload.style;
+				const style = isJsonObject(prior) ? prior : {};
+				for (const updated of updateEntityFields(draft, caption.entityId, { style: {
+					...style,
+					...patch
+				} })) replaceEntity(draft, updated.entityId, updated);
+			}
+		});
+	}
+	/**
+	* Place a Caption as a composed variant of an existing AudioScript: the
+	* entity stores baseEntityIds, selection, optional style, and inherent cue-bounded
+	* Sequence. This helper does not copy base text. The Clip and its display Marker describe this use;
+	* moving or stretching the returned Clip later changes the Clip/Marker,
+	* never the Caption entity or the AudioScript.
+	*/
+	insertCaptionClip(input) {
+		return this.transact((draft) => {
+			const durationMs = finitePositive(input.durationMs, "Caption durationMs");
+			const selection = captionSelection(input.selection);
+			const track = this.ensureRoleTrack(draft, input.timelineEntityId, "caption");
+			const content = {
+				entityId: input.captionEntityId === void 0 ? this.mintEntityId(draft) : requireAvailableEntityId(draft, input.captionEntityId),
+				entityKind: "caption",
+				payload: {
+					durationMs,
+					baseEntityIds: captionBaseIds(input.baseEntityIds),
+					selection,
+					...input.style === void 0 ? {} : { style: cloneJsonObject(input.style, "Caption style") }
+				}
+			};
+			draft.entities.push(content);
+			assembleCaptionContent(draft, content.entityId);
+			return this.insertPlacedClipIntoDraft(draft, {
+				trackEntityId: track.entityId,
+				contentEntityId: content.entityId,
+				inMs: 0,
+				outMs: durationMs,
+				placement: input.placement,
+				...input.captionClipEntityId === void 0 ? {} : { clipEntityId: input.captionClipEntityId }
+			});
+		});
+	}
+	insertPlacedClipIntoDraft(draft, input) {
+		const track = requireEntityKind(draft, input.trackEntityId, "track");
+		requireTrackTimeline(draft, track.entityId);
+		const content = requireSequenceContent(draft, input.contentEntityId);
+		const clipId = input.clipEntityId === void 0 ? this.mintEntityId(draft) : requireAvailableEntityId(draft, input.clipEntityId);
+		const markerId = this.mintEntityId(draft);
+		const clipPayload = { ...cloneJsonObject(input.clipPayload ?? {}, "Clip payload") };
+		const markerPlacement = applyPlacementPayload(input.placement);
+		const clip = {
+			entityId: clipId,
+			entityKind: "clip",
+			payload: clipPayload
+		};
+		const marker = {
+			entityId: markerId,
+			entityKind: "sequence-marker",
+			payload: markerPayload({
+				...requireWindow(input.inMs, input.outMs),
+				...markerPlacement
+			})
+		};
+		draft.entities.push(clip, marker);
+		draft.relations.push(this.createRelation(draft, "contain", track.entityId, clipId), this.createRelation(draft, "marker", clipId, markerId), this.createRelation(draft, "contain", clipId, content.entityId));
+		if (input.placement.kind === "anchored") {
+			const host = requireEntityKind(draft, input.placement.hostClipEntityId, "clip");
+			if (host.entityId === clipId) throw new Error("A Clip cannot anchor to itself");
+			draft.relations.push(this.createRelation(draft, "clip-anchor", clipId, host.entityId));
+		}
+		return clipId;
+	}
+	ensureRoleTrack(draft, timelineEntityId, role) {
+		const existing = findRoleTrack(draft, timelineEntityId, role);
+		if (existing !== void 0) return existing;
+		const timeline = requireEntityKind(draft, timelineEntityId, "timeline");
+		const track = {
+			entityId: this.mintEntityId(draft),
+			entityKind: "track",
+			payload: {
+				role,
+				order: roleOrder[role]
+			}
+		};
+		draft.entities.push(track);
+		draft.relations.push(this.createRelation(draft, "contain", timeline.entityId, track.entityId));
+		return track;
+	}
+	/** The existing pronunciation variant a voiceover consumes; composition is required. */
+	requireComposedPhoneticScript(draft, phoneticScriptEntityId) {
+		const phonetic = requireEntityKind(draft, phoneticScriptEntityId, "phonetic-script");
+		requireComposedAudioScript(draft, phonetic.entityId);
+		return phonetic;
+	}
+	/** Preserve the factual synthesis input as `[rendered Audio, PhoneticScript]`. */
+	ensurePhoneticRender(draft, voiceoverAudioEntityId, phoneticScriptEntityId) {
+		const renders = draft.relations.filter((relation) => relation.relationKind === "derived-from" && (relation.endpoint0EntityId === voiceoverAudioEntityId || relation.endpoint1EntityId === voiceoverAudioEntityId));
+		if (renders.length > 1) throw new Error(`Voiceover "${voiceoverAudioEntityId}" has multiple PhoneticScript render relations`);
+		if (renders[0] !== void 0) {
+			if (otherEndpoint(renders[0], voiceoverAudioEntityId) === phoneticScriptEntityId) return;
+			throw new Error(`Voiceover "${voiceoverAudioEntityId}" already has a different PhoneticScript synthesis input`);
+		}
+		draft.relations.push(this.createRelation(draft, "derived-from", voiceoverAudioEntityId, phoneticScriptEntityId));
+	}
+	reconcileVoiceoverCaptions(draft, voiceoverClipEntityId, phoneticScriptEntityId, captions) {
+		const audioScriptEntityId = requireComposedAudioScript(draft, phoneticScriptEntityId);
+		const requested = new Set(captions.map((caption) => caption.captionClipEntityId));
+		if (requested.size !== captions.length) throw new Error("Caption Clip ids must be unique within a voiceover take");
+		const existing = directAnchorChildren(draft, voiceoverClipEntityId).filter((clipId) => clipRole(draft, clipId) === "caption");
+		for (const clipId of existing) if (!requested.has(clipId)) this.removeCaptionClipGraph(draft, clipId);
+		const captionTrack = captions.length === 0 ? void 0 : this.ensureRoleTrackForClip(draft, voiceoverClipEntityId, "caption");
+		for (const caption of captions) {
+			const startMs = finiteNonNegative(caption.startMs, "Caption startMs");
+			const durationMs = finitePositive(caption.durationMs, "Caption durationMs");
+			const selection = captionSelection(caption.selection);
+			const baseEntityIds = captionBaseIds(caption.baseEntityIds);
+			if (draft.entities.find((entity) => entity.entityId === caption.captionClipEntityId) === void 0) {
+				const content = {
+					entityId: this.mintEntityId(draft),
+					entityKind: "caption",
+					payload: {
+						durationMs,
+						baseEntityIds,
+						selection,
+						...caption.style === void 0 ? {} : { style: cloneJsonObject(caption.style, "Caption style") }
+					}
+				};
+				draft.entities.push(content);
+				assertCaptionScript(draft, content.entityId, audioScriptEntityId);
+				this.insertPlacedClipIntoDraft(draft, {
+					clipEntityId: caption.captionClipEntityId,
+					trackEntityId: captionTrack.entityId,
+					contentEntityId: content.entityId,
+					inMs: 0,
+					outMs: durationMs,
+					placement: {
+						kind: "anchored",
+						hostClipEntityId: voiceoverClipEntityId,
+						startMs
+					}
+				});
+				continue;
+			}
+			const topology = requireClipOnRole(draft, caption.captionClipEntityId, "caption");
+			const content = requireEntityKind(draft, otherEndpoint(topology.contentRelation, topology.clip.entityId), "caption");
+			const priorStyle = isJsonObject(content.payload.style) ? content.payload.style : {};
+			const style = caption.style === void 0 ? priorStyle : {
+				...priorStyle,
+				...cloneJsonObject(caption.style, "Caption style")
+			};
+			replaceEntity(draft, content.entityId, {
+				...content,
+				payload: {
+					...content.payload,
+					baseEntityIds,
+					selection,
+					...Object.keys(style).length === 0 ? {} : { style }
+				}
+			});
+			assertCaptionScript(draft, content.entityId, audioScriptEntityId);
+			this.applyClipPlacement(draft, topology.clip.entityId, {
+				kind: "anchored",
+				hostClipEntityId: voiceoverClipEntityId,
+				startMs
+			});
+			const placed = requireClipTopology(draft, topology.clip.entityId);
+			const window = markerWindow(placed.marker.payload);
+			const rate = (window.outMs - window.inMs) / durationMs;
+			replaceEntity(draft, placed.marker.entityId, {
+				...placed.marker,
+				payload: {
+					...placed.marker.payload,
+					...rate === 1 ? {} : { rate }
+				}
+			});
+		}
+	}
+	ensureRoleTrackForClip(draft, clipEntityId, role) {
+		const topology = requireClipTopology(draft, clipEntityId);
+		const track = requireEntityKind(draft, otherEndpoint(topology.trackRelation, topology.clip.entityId), "track");
+		const timeline = requireEntityKind(draft, otherEndpoint(requireOneContain(draft, track.entityId, "contained"), track.entityId), "timeline");
+		return this.ensureRoleTrack(draft, timeline.entityId, role);
+	}
+	/**
+	* Remove one placed Caption use. The composed AudioScript outlives the
+	* caption: it may anchor further captions and remains the text owner.
+	*/
+	removeCaptionClipGraph(draft, clipEntityId) {
+		const topology = requireClipOnRole(draft, clipEntityId, "caption");
+		const caption = requireEntityKind(draft, otherEndpoint(topology.contentRelation, topology.clip.entityId), "caption");
+		const contentRelations = incidentRelations(draft, caption.entityId);
+		const allowed = new Set(["caption-alignment", "contain"]);
+		const unsupported = contentRelations.filter((relation) => !allowed.has(relation.relationKind));
+		if (unsupported.length > 0) throw new Error(`Cannot delete Caption with unsupported Relation ${unsupported[0].relationId}`);
+		this.removeClipGraph(draft, clipEntityId);
+		if (containing(draft, caption.entityId, "contained").length > 0) return;
+		const removed = new Set(incidentRelations(draft, caption.entityId).map((relation) => relation.relationId));
+		draft.relations = draft.relations.filter((relation) => !removed.has(relation.relationId));
+		draft.entities = draft.entities.filter((entity) => entity.entityId !== caption.entityId);
+	}
+	replaceAnchorHost(draft, childClipEntityId, hostClipEntityId) {
+		const anchors = draft.relations.filter((relation) => relation.relationKind === "clip-anchor" && relation.endpoint0EntityId === childClipEntityId);
+		if (anchors.length !== 1) throw new Error(`Clip "${childClipEntityId}" must have exactly one host`);
+		this.relinkRelation(draft, anchors[0], {
+			endpoint0EntityId: createEntityId(childClipEntityId),
+			endpoint1EntityId: createEntityId(hostClipEntityId)
+		});
+	}
+	/** Rebuild the legacy edit baseline from current visual order before a high-level cascade. */
+	normalizeMainSequential(draft) {
+		const videoTrack = resolveEntityTimelineLayout(draft).tracks.find((track) => track.role === "video_clip");
+		if (videoTrack === void 0) return;
+		videoTrack.clips.forEach((clip, order) => {
+			this.applyClipPlacement(draft, clip.clipEntityId, {
+				kind: "sequential",
+				order
+			});
+		});
+	}
+	resolveOneVoiceoverOverlap(draft) {
+		const layout = resolveEntityTimelineLayout(draft);
+		const speechTrack = layout.tracks.find((track) => track.role === "speech");
+		if (speechTrack === void 0) return;
+		const ranges = speechTrack.clips.map((speech) => {
+			const captions = directAnchorChildren(draft, speech.clipEntityId).filter((clipId) => clipRole(draft, clipId) === "caption").map((clipId) => layout.clips.get(clipId)).filter((value) => value !== void 0);
+			return {
+				speech,
+				start: Math.min(speech.start, ...captions.map((caption) => caption.start)),
+				end: Math.max(speech.start + speech.duration, ...captions.map((caption) => caption.start + caption.duration))
+			};
+		}).sort((left, right) => left.start - right.start || left.speech.clipEntityId.localeCompare(right.speech.clipEntityId));
+		for (let index = 1; index < ranges.length; index += 1) {
+			const prior = ranges[index - 1];
+			const current = ranges[index];
+			if (current.start >= prior.end) continue;
+			const hostId = current.speech.anchorClipEntityId;
+			if (hostId === void 0) continue;
+			const videoTrack = layout.tracks.find((track) => track.role === "video_clip");
+			const hostIndex = videoTrack?.clips.findIndex((clip) => clip.clipEntityId === hostId) ?? -1;
+			if (videoTrack === void 0 || hostIndex < 0) continue;
+			const overlapMs = Math.round(prior.end - current.start);
+			for (const [visualIndex, clip] of videoTrack.clips.entries()) this.applyClipPlacement(draft, clip.clipEntityId, {
+				kind: "absolute",
+				startMs: clip.start + (visualIndex >= hostIndex ? overlapMs : 0)
+			});
+			return;
+		}
+	}
+	applyClipPlacement(draft, clipEntityId, placement) {
+		const topology = requireClipTopology(draft, clipEntityId);
+		const clipPayload = { ...cloneJsonObject(topology.clip.payload, "Clip payload") };
+		const markerPayloadValue = { ...cloneJsonObject(topology.marker.payload, "Sequence Marker payload") };
+		delete markerPayloadValue.startMs;
+		const outgoingAnchors = draft.relations.filter((relation) => relation.relationKind === "clip-anchor" && relation.endpoint0EntityId === topology.clip.entityId);
+		const removed = new Set(outgoingAnchors.map((relation) => relation.relationId));
+		draft.relations = draft.relations.filter((relation) => !removed.has(relation.relationId));
+		if (placement.kind === "sequential") setClipOrder(draft, topology.clip.entityId, placement.order);
+		else if (placement.kind === "absolute") markerPayloadValue.startMs = finiteNonNegative(placement.startMs, "startMs");
+		else {
+			const host = requireEntityKind(draft, placement.hostClipEntityId, "clip");
+			if (host.entityId === topology.clip.entityId) throw new Error("A Clip cannot anchor to itself");
+			markerPayloadValue.startMs = finiteNonNegative(placement.startMs, "startMs");
+			draft.relations.push(this.createRelation(draft, "clip-anchor", topology.clip.entityId, host.entityId));
+		}
+		replaceEntity(draft, topology.clip.entityId, {
+			...topology.clip,
+			payload: clipPayload
+		});
+		replaceEntity(draft, topology.marker.entityId, {
+			...topology.marker,
+			payload: markerPayloadValue
+		});
+	}
+	reanchorAtAbsolute(draft, childClipEntityId, absoluteStart, layout) {
+		const hosts = layout.tracks.find((track) => track.role === "video_clip")?.clips.filter((clip) => clip.mode === "sequential") ?? [];
+		if (hosts.length === 0) {
+			if (layout.clips.get(childClipEntityId) === void 0) throw new Error(`Clip "${childClipEntityId}" is not placed`);
+			this.applyClipPlacement(draft, childClipEntityId, {
+				kind: "absolute",
+				startMs: absoluteStart
+			});
+			return;
+		}
+		const host = hosts.find((candidate) => candidate.start <= absoluteStart && absoluteStart < candidate.start + candidate.duration) ?? (absoluteStart < hosts[0].start ? hosts[0] : hosts.at(-1));
+		this.applyClipPlacement(draft, childClipEntityId, {
+			kind: "anchored",
+			hostClipEntityId: host.clipEntityId,
+			startMs: Math.max(0, Math.round(absoluteStart - host.start))
+		});
+	}
+	removeAnchoredDescendants(draft, hostClipEntityId, scheduled) {
+		const children = draft.relations.filter((relation) => relation.relationKind === "clip-anchor" && relation.endpoint1EntityId === hostClipEntityId).map((relation) => String(relation.endpoint0EntityId));
+		for (const child of children) {
+			if (scheduled.has(child)) continue;
+			const descendants = new Set(scheduled);
+			descendants.add(child);
+			this.removeAnchoredDescendants(draft, child, descendants);
+			if (clipRole(draft, child) === "caption") this.removeCaptionClipGraph(draft, child);
+			else this.removeClipGraph(draft, child);
+		}
+	}
+	removeClipGraph(draft, clipEntityId) {
+		const topology = requireClipTopology(draft, clipEntityId);
+		assertOnlyStructuralIncidents(draft, topology.clip.entityId, new Set([
+			"contain",
+			"marker",
+			"clip-anchor"
+		]));
+		assertOnlyStructuralIncidents(draft, topology.marker.entityId, new Set(["marker"]));
+		const markerIsExclusive = incidentRelations(draft, topology.marker.entityId).filter((relation) => relation.relationKind === "marker").length === 1;
+		const removed = new Set(incidentRelations(draft, topology.clip.entityId).map((relation) => relation.relationId));
+		if (markerIsExclusive) for (const relation of incidentRelations(draft, topology.marker.entityId)) removed.add(relation.relationId);
+		draft.relations = draft.relations.filter((relation) => !removed.has(relation.relationId));
+		draft.entities = draft.entities.filter((entity) => entity.entityId !== topology.clip.entityId && (!markerIsExclusive || entity.entityId !== topology.marker.entityId));
+	}
+	transact(edit) {
+		const draft = cloneRows(this.state);
+		const result = edit(draft);
+		validateFinalRows(draft);
+		assertMediaAssetWritePolicy(this.state, draft);
+		this.state = draft;
+		return result;
+	}
+	mintEntityId(draft) {
+		const entityId = createEntityId(this.idFactory("entity"));
+		if (draft.entities.some((entity) => entity.entityId === entityId)) throw new Error(`Entity id "${entityId}" already exists`);
+		return entityId;
+	}
+	createRelation(draft, relationKind, endpoint0EntityId, endpoint1EntityId, metadata = {}) {
+		return {
+			relationId: this.mintRelationId(draft),
+			relationKind,
+			endpoint0EntityId,
+			endpoint1EntityId,
+			metadata,
+			trace: {}
+		};
+	}
+	relinkRelation(draft, relation, endpoints) {
+		const relationId = this.mintRelationId(draft);
+		const index = draft.relations.findIndex((candidate) => candidate.relationId === relation.relationId);
+		if (index < 0) throw new Error(`Relation id "${relation.relationId}" does not exist`);
+		draft.relations[index] = {
+			...relation,
+			...endpoints,
+			relationId
+		};
+	}
+	mintRelationId(draft) {
+		const relationId = createRelationId(this.idFactory("relation"));
+		if (draft.relations.some((relation) => relation.relationId === relationId)) throw new Error(`Relation id "${relationId}" already exists`);
+		return relationId;
+	}
+};
+function validateFinalRows(rows) {
+	decodeEntityRelationRows(rows, {});
+	assertCanonicalEditorResources(rows);
+	validateTimelineHierarchy(rows);
+}
+function validateTimelineHierarchy(rows) {
+	for (const entity of rows.entities) {
+		if (entity.entityKind === "track") requireTrackTimeline(rows, entity.entityId);
+		if (entity.entityKind !== "clip") continue;
+		const trackRelations = containing(rows, entity.entityId, "contained");
+		if (trackRelations.length !== 1) throw new Error(`Clip Entity "${entity.entityId}" must belong to exactly one Track`);
+		requireEntityKind(rows, otherEndpoint(trackRelations[0], entity.entityId), "track");
+	}
+}
+function requireTrackTimeline(rows, trackEntityId) {
+	const timelineRelations = containing(rows, createEntityId(trackEntityId), "contained");
+	if (timelineRelations.filter((relation) => {
+		const otherId = otherEndpoint(relation, trackEntityId);
+		return rows.entities.some((entity) => entity.entityId === otherId && entity.entityKind === "timeline");
+	}).length !== 1 || timelineRelations.length !== 1) throw new Error(`Track Entity "${trackEntityId}" must belong to exactly one Timeline`);
+}
+function requireClipTopology(rows, clipEntityId) {
+	const clip = requireEntityKind(rows, clipEntityId, "clip");
+	const trackRelation = requireOneContain(rows, clip.entityId, "contained");
+	requireEntityKind(rows, otherEndpoint(trackRelation, clip.entityId), "track");
+	const clipMarkerRelation = requireOneRelation(rows, clip.entityId, "marker");
+	const marker = requireEntityKind(rows, otherEndpoint(clipMarkerRelation, clip.entityId), "sequence-marker");
+	const contentRelation = requireOneContain(rows, clip.entityId, "container");
+	requireSequenceContent(rows, otherEndpoint(contentRelation, clip.entityId));
+	return {
+		clip,
+		marker,
+		trackRelation,
+		clipMarkerRelation,
+		contentRelation
+	};
+}
+/**
+* One `contain` Relation with this entity on the stated side.
+*
+* A Clip is contained by its Track and contains its content; a Track is
+* contained by the Timeline and contains its Clips. Both are `contain`, so the
+* endpoint position is the only thing that tells them apart.
+*/
+function requireOneContain(rows, entityId, side) {
+	const matches = containing(rows, entityId, side);
+	if (matches.length !== 1) throw new Error(`Entity "${entityId}" must be the ${side} of exactly one contain Relation`);
+	return matches[0];
+}
+/** `contain` is ordered, so a lookup says which side it wants. */
+function containing(rows, entityId, side) {
+	return (side === "container" ? relationsFrom : relationsTo)(rows.relations, "contain", entityId);
+}
+function requireOneRelation(rows, entityId, relationKind) {
+	const matches = incidentRelations(rows, entityId).filter((relation) => relation.relationKind === relationKind);
+	if (matches.length !== 1) throw new Error(`Entity "${entityId}" must have exactly one ${relationKind} Relation`);
+	return matches[0];
+}
+function requireEntityKind(rows, entityIdValue, entityKind) {
+	const entityId = createEntityId(entityIdValue);
+	const entity = rows.entities.find((candidate) => candidate.entityId === entityId);
+	if (entity == null) throw new Error(`Entity id "${entityId}" does not exist`);
+	if (entity.entityKind !== entityKind) throw new Error(`Entity "${entityId}" must have kind "${entityKind}", got "${entity.entityKind}"`);
+	return entity;
+}
+function requireSequenceContent(rows, entityIdValue) {
+	if (/^(?:[a-z][a-z\d+.-]*:|\/\/)/i.test(entityIdValue)) throw new Error("Timeline content must reference an existing Sequence media Entity id; a URL is not allowed");
+	const entityId = createEntityId(entityIdValue);
+	const row = rows.entities.find((candidate) => candidate.entityId === entityId);
+	if (row == null) throw new Error(`Timeline content must reference an existing Sequence media Entity; "${entityId}" was not found`);
+	if (!hasSequence({
+		...row.payload,
+		entityId: row.entityId,
+		entityKind: row.entityKind
+	})) throw new Error(`Timeline content must reference a Sequence media Entity, but "${entityId}" has kind "${row.entityKind}"`);
+	return row;
+}
+function assertOnlyStructuralIncidents(rows, entityId, allowedKinds) {
+	const unsupported = incidentRelations(rows, entityId).filter((relation) => !allowedKinds.has(relation.relationKind));
+	if (unsupported.length === 0) return;
+	throw new Error(`Cannot delete Clip graph: Entity "${entityId}" has unsupported incident Relation id(s): ${unsupported.map((relation) => relation.relationId).sort().join(", ")}`);
+}
+function incidentRelations(rows, entityId) {
+	return rows.relations.filter((relation) => relation.endpoint0EntityId === entityId || relation.endpoint1EntityId === entityId);
+}
+function hasOutgoingClipAnchor(rows, clipEntityId) {
+	return rows.relations.some((relation) => relation.relationKind === "clip-anchor" && relation.endpoint0EntityId === clipEntityId);
+}
+function outgoingAnchorChildren(rows, hostIds) {
+	return rows.relations.filter((relation) => relation.relationKind === "clip-anchor" && hostIds.has(relation.endpoint1EntityId)).map((relation) => String(relation.endpoint0EntityId));
+}
+/** What the placement puts on the Marker; a sequential one puts nothing there. */
+function applyPlacementPayload(placement) {
+	if (placement.kind === "sequential") return {};
+	return { startMs: finiteNonNegative(placement.startMs, "startMs") };
+}
+function requireAvailableEntityId(rows, value) {
+	const entityId = createEntityId(value);
+	if (rows.entities.some((entity) => entity.entityId === entityId)) throw new Error(`Entity id "${entityId}" already exists`);
+	return entityId;
+}
+/**
+* Put a Clip at `order` among the Clips its Track contains.
+*
+* Where a Clip sits is the position of its membership Relation, so moving one
+* is moving that Relation — nothing on the Clip changes, and there are no
+* sibling positions left to keep in step.
+*/
+function setClipOrder(rows, clipEntityId, order) {
+	const membership = relationsTo(rows.relations, "contain", clipEntityId)[0];
+	if (membership === void 0) throw new Error(`Clip "${clipEntityId}" is contained by no Track`);
+	const slots = [];
+	const siblings = [];
+	for (const [index, relation] of rows.relations.entries()) {
+		if (relation.relationKind !== "contain" || relation.endpoint0EntityId !== membership.endpoint0EntityId) continue;
+		slots.push(index);
+		siblings.push(relation);
+	}
+	const from = siblings.indexOf(membership);
+	const moved = siblings.filter((relation) => relation !== membership);
+	moved.splice(Math.max(0, Math.min(order, moved.length)), 0, membership);
+	if (from < 0) return;
+	slots.forEach((slot, at) => rows.relations[slot] = moved[at]);
+}
+function findRoleTrack(rows, timelineEntityId, role) {
+	const timeline = requireEntityKind(rows, timelineEntityId, "timeline");
+	const tracks = containing(rows, timeline.entityId, "container").map((relation) => requireEntityKind(rows, otherEndpoint(relation, timeline.entityId), "track")).filter((track) => track.payload.role === role);
+	if (tracks.length > 1) throw new Error(`Timeline "${timelineEntityId}" has multiple ${role} Tracks`);
+	return tracks[0];
+}
+function clipsOnTrack(rows, trackEntityId) {
+	return containing(rows, trackEntityId, "container").map((relation) => requireEntityKind(rows, otherEndpoint(relation, trackEntityId), "clip"));
+}
+function clipRole(rows, clipEntityId) {
+	const topology = requireClipTopology(rows, clipEntityId);
+	return requireEntityKind(rows, otherEndpoint(topology.trackRelation, topology.clip.entityId), "track").payload.role;
+}
+function directAnchorChildren(rows, hostClipEntityId) {
+	return rows.relations.filter((relation) => relation.relationKind === "clip-anchor" && relation.endpoint1EntityId === hostClipEntityId).map((relation) => String(relation.endpoint0EntityId));
+}
+function requireSupportedRole(rows, topology) {
+	const role = requireEntityKind(rows, otherEndpoint(topology.trackRelation, topology.clip.entityId), "track").payload.role;
+	if (role !== "video_clip" && role !== "speech" && role !== "caption" && role !== "bgm") throw new Error(`Clip "${topology.clip.entityId}" is not on a supported timeline Track`);
+	return role;
+}
+function requireClipOnRole(rows, clipEntityId, role) {
+	const topology = requireClipTopology(rows, clipEntityId);
+	if (requireEntityKind(rows, otherEndpoint(topology.trackRelation, topology.clip.entityId), "track").payload.role !== role) throw new Error(`Clip "${clipEntityId}" must belong to the ${role} Track`);
+	return topology;
+}
+function finiteNumber(value, label) {
+	if (!Number.isFinite(value)) throw new Error(`${label} must be finite`);
+	return value;
+}
+function finitePositive(value, label) {
+	const result = finiteNumber(value, label);
+	if (result <= 0) throw new Error(`${label} must be positive`);
+	return result;
+}
+function requireVolume(value) {
+	const volume = finiteNumber(value, "Clip volume");
+	if (volume < -60 || volume > 20) throw new Error("Clip volume must be between -60 and 20 dB");
+	return volume;
+}
+function requireWindow(inMs, outMs, label = "Sequence Marker") {
+	const start = finiteNonNegative(inMs, `${label} inMs`);
+	const end = finitePositive(outMs, `${label} outMs`);
+	if (!Number.isSafeInteger(start) || !Number.isSafeInteger(end) || end <= start) throw new Error(`${label} must state a positive whole-millisecond window`);
+	return {
+		inMs: start,
+		outMs: end
+	};
+}
+function markerWindow(payload) {
+	return requireWindow(payload.inMs, payload.outMs);
+}
+/**
+* How long the Clip runs. The window and the rate are the only stored facts;
+* the played length follows from them rather than being kept in step by hand.
+*/
+function markerDuration(payload, window = markerWindow(payload)) {
+	return Math.round((window.outMs - window.inMs) / markerRate(payload));
+}
+function markerRate(payload) {
+	return payload.rate === void 0 ? 1 : finitePositive(payload.rate, "linear speed rate");
+}
+function replaceRows(rows, replacement) {
+	rows.entities = structuredClone([...replacement.entities]);
+	rows.relations = structuredClone([...replacement.relations]);
+}
+function finiteNonNegative(value, label) {
+	const result = finiteNumber(value, label);
+	if (result < 0) throw new Error(`${label} must be non-negative`);
+	return result;
+}
+/** How many Clips the Track already holds — the index a new one lands at. */
+function nextSequentialOrder(rows, trackEntityId) {
+	return relationsFrom(rows.relations, "contain", trackEntityId).length;
+}
+function otherEndpoint(relation, entityId) {
+	if (relation.endpoint0EntityId === entityId) return relation.endpoint1EntityId;
+	if (relation.endpoint1EntityId === entityId) return relation.endpoint0EntityId;
+	throw new Error(`Relation "${relation.relationId}" is not incident to Entity "${entityId}"`);
+}
+function replaceEntity(rows, entityId, replacement) {
+	const index = rows.entities.findIndex((entity) => entity.entityId === entityId);
+	if (index < 0) throw new Error(`Entity id "${entityId}" does not exist`);
+	rows.entities[index] = replacement;
+}
+function markerPayload(value) {
+	return cloneJsonObject(value, "Sequence Marker payload");
+}
+function cloneJsonObject(value, label) {
+	const cloned = structuredClone(value);
+	if (!isJsonObject(cloned)) throw new Error(`${label} must contain only JSON values`);
+	return cloned;
+}
+function cloneRows(rows) {
+	return {
+		entities: rows.entities.map((entity) => structuredClone(entity)),
+		relations: rows.relations.map((relation) => structuredClone(relation))
+	};
+}
+//#endregion
+//#region src/entity-editor/visual-assets-effect.ts
+const receiptKey = (effectId) => `editorEffectReceipt:${effectId}`;
+const effectEntityId = (role, effectId, index) => createEntityId(`entity_visual_effect_${role}_${effectId}_${index}`);
+const effectRelationId = (role, effectId, index) => createRelationId(`relation_visual_effect_${role}_${effectId}_${index}`);
+/** Read the authoritative timeline receipt, not a media-id heuristic. */
+function hasVisualAssetsEffect(rows, effectId) {
+	return rows.entities.find((row) => row.entityKind === "timeline")?.payload[receiptKey(effectId)] === true;
+}
+/**
+* Materialize a host-resolved visual command into native Entity/Relation rows.
+* The result is suitable for one revision-checked `EntityGraphHttpClient.commit`.
+* This does not fetch Assets or write remotely; callers must supply factual media
+* and lineage inputs after their own ownership checks.
+*/
+function applyVisualAssetsEffect(rows, input) {
+	if (!input.effect_id) throw new Error("Visual effect requires an effect_id");
+	if (hasVisualAssetsEffect(rows, input.effect_id)) return rows;
+	if (input.clips.length === 0) throw new Error("Visual effect requires clips");
+	if (input.before_clip_id !== void 0 && input.after_clip_id !== void 0) throw new Error("Visual effect accepts only one placement anchor");
+	const timeline = rows.entities.find((row) => row.entityKind === "timeline");
+	if (!timeline) throw new Error("Visual effect requires a Timeline");
+	if (!rows.entities.some((row) => row.entityKind === "track" && row.payload.role === "video_clip")) throw new Error("Visual effect requires a video Track");
+	const anchor = input.before_clip_id ?? input.after_clip_id;
+	if (anchor && !resolveEntityTimelineLayout(rows).tracks.find((track) => track.role === "video_clip")?.clips.some((clip) => clip.clipEntityId === anchor)) throw new Error(`Visual effect anchor ${anchor} no longer exists`);
+	let prepared = rows;
+	for (const clip of input.clips) {
+		prepared = importEffectMedia(prepared, visualMediaFact(clip));
+		for (const source of clip.lineage?.sources ?? []) if (source.assetId !== clip.media_id) prepared = importEffectMedia(prepared, source);
+		if (clip.lineage?.script) prepared = materializeScript(prepared, clip.lineage.script);
+	}
+	const entityIds = input.clips.map((_, index) => effectEntityId("marker", input.effect_id, index));
+	const relationIds = input.clips.flatMap((_, index) => [
+		effectRelationId("track_clip", input.effect_id, index),
+		effectRelationId("marker", input.effect_id, index),
+		effectRelationId("content", input.effect_id, index)
+	]);
+	const editor = new EntityTimelineEditor(prepared, (prefix) => {
+		const id = (prefix === "entity" ? entityIds : relationIds).shift();
+		if (!id) throw new Error(`Visual effect exhausted deterministic ${prefix} identities`);
+		return id;
+	});
+	for (const clip of input.clips) {
+		if (clip.media_kind !== "image" && clip.media_kind !== "video") throw new Error("Expected visual media");
+		if (clip.lineage?.script && clip.media_kind !== "video") throw new Error("Only Video may derive from Script");
+	}
+	editor.insertMediaClips({
+		timelineEntityId: timeline.entityId,
+		clips: input.clips.map((clip, index) => ({
+			clipEntityId: effectEntityId("clip", input.effect_id, index),
+			media: visualMediaFact(clip),
+			inMs: clip.play_in ?? 0,
+			outMs: clip.play_out ?? clip.media_duration_ms,
+			...clip.volume === void 0 ? {} : { volume: clip.volume }
+		})),
+		insertion: input.before_clip_id !== void 0 ? {
+			kind: "before",
+			clipEntityId: input.before_clip_id
+		} : input.after_clip_id !== void 0 ? {
+			kind: "after",
+			clipEntityId: input.after_clip_id
+		} : {
+			kind: "firstStart",
+			startMs: input.clips.find((clip) => clip.start_ms !== void 0)?.start_ms ?? 0
+		}
+	});
+	let next = editor.rows();
+	const relations = [...next.relations];
+	for (const [clipIndex, clip] of input.clips.entries()) {
+		const output = findMediaId(next, clip.media_id);
+		const seen = /* @__PURE__ */ new Set();
+		for (const [sourceIndex, sourceFact] of (clip.lineage?.sources ?? []).entries()) {
+			if (sourceFact.assetId === clip.media_id || seen.has(sourceFact.assetId)) continue;
+			seen.add(sourceFact.assetId);
+			const source = findMediaId(next, sourceFact.assetId, sourceFact.kind);
+			if (hasDerivation(relations, output, source)) continue;
+			relations.push({
+				relationId: createRelationId(`relation_visual_effect_${input.effect_id}_${clipIndex}_${sourceIndex}`),
+				relationKind: "derived-from",
+				endpoint0EntityId: output,
+				endpoint1EntityId: source,
+				metadata: {},
+				trace: { taskId: clip.lineage.generation_job_id }
+			});
+		}
+		const script = clip.lineage?.script;
+		if (!script) continue;
+		if (relations.filter((relation) => relation.relationKind === "derived-from" && relation.endpoint0EntityId === output && next.entities.some((row) => row.entityId === relation.endpoint1EntityId && row.entityKind === "script")).some((relation) => relation.endpoint1EntityId !== script.entity_id)) throw new Error(`Video ${clip.media_id} already derives from another Script`);
+		if (hasDerivation(relations, output, createEntityId(script.entity_id))) continue;
+		relations.push({
+			relationId: createRelationId(`relation_visual_effect_${input.effect_id}_script_${clipIndex}`),
+			relationKind: "derived-from",
+			endpoint0EntityId: output,
+			endpoint1EntityId: createEntityId(script.entity_id),
+			metadata: {},
+			trace: { taskId: clip.lineage.generation_job_id }
+		});
+	}
+	next = {
+		entities: next.entities,
+		relations
+	};
+	return {
+		entities: next.entities.map((row) => row.entityId === timeline.entityId ? {
+			...row,
+			payload: {
+				...row.payload,
+				[receiptKey(input.effect_id)]: true
+			}
+		} : row),
+		relations: next.relations
+	};
+}
+function visualMediaFact(clip) {
+	return clip.media_kind === "image" ? {
+		assetId: clip.media_id,
+		kind: "image",
+		...clip.storage_key ? { storageKey: clip.storage_key } : {}
+	} : {
+		assetId: clip.media_id,
+		kind: "video",
+		durationMs: clip.media_duration_ms,
+		...clip.storage_key ? { storageKey: clip.storage_key } : {}
+	};
+}
+function materializeScript(rows, script) {
+	const payload = {
+		segments: script.segments.map((segment) => ({
+			segmentId: segment.segment_id,
+			text: segment.text,
+			...segment.language === void 0 ? {} : { language: segment.language }
+		})),
+		contentHash: script.content_hash
+	};
+	if (payload.contentHash !== scriptContentHash(payload.segments)) throw new Error(`Script ${script.entity_id} content hash is invalid`);
+	const existing = rows.entities.find((row) => row.entityId === script.entity_id);
+	if (existing) {
+		if (existing.entityKind !== "script" || existing.payload.contentHash !== payload.contentHash || JSON.stringify(existing.payload.segments) !== JSON.stringify(payload.segments)) throw new Error(`Script ${script.entity_id} identity/content conflict`);
+		return rows;
+	}
+	return {
+		entities: [...rows.entities, {
+			entityId: createEntityId(script.entity_id),
+			entityKind: "script",
+			payload
+		}],
+		relations: rows.relations
+	};
+}
+function importEffectMedia(rows, fact) {
+	const system = fact.kind === "voiceover-recording" ? "memota-speech" : "memota";
+	const resolved = findCanonicalMedia(rows, fact.assetId, system);
+	if (resolved.asset && fact.storageKey !== void 0 && resolved.asset.payload.storageKey !== fact.storageKey) throw new Error(`Media ${fact.assetId} storageKey conflicts with its immutable Asset`);
+	const prepared = resolved.asset ? rows : {
+		entities: [...rows.entities, {
+			entityId: createEntityId(`entity_visual_media_${fact.assetId}_0`),
+			entityKind: "asset",
+			payload: {
+				system,
+				key: fact.assetId,
+				...fact.storageKey ? { storageKey: fact.storageKey } : {}
+			}
+		}],
+		relations: rows.relations
+	};
+	const voiceDescriptor = fact.kind === "voiceover-recording" ? fact.voice : void 0;
+	const existingVoice = voiceDescriptor ? rows.entities.find((row) => {
+		const voice = row.payload.voice;
+		return row.entityKind === "voice" && voice !== void 0 && voice.system === voiceDescriptor.system && voice.key === voiceDescriptor.key && voice.name === voiceDescriptor.name;
+	}) : void 0;
+	const hasTimbre = resolved.media !== void 0 && rows.relations.some((relation) => relation.relationKind === "voice-timbre" && relation.endpoint0EntityId === resolved.media.entityId);
+	const entities = [...resolved.media ? [] : [createEntityId(`entity_visual_media_${fact.assetId}_1`)], ...fact.kind === "voiceover-recording" && fact.voice && !existingVoice ? [createEntityId(`entity_visual_media_${fact.assetId}_2`)] : []];
+	const relations = [...resolved.media ? [] : [createRelationId(`relation_visual_media_${fact.assetId}_0`)], ...fact.kind === "voiceover-recording" && fact.voice && !hasTimbre ? [createRelationId(`relation_visual_media_${fact.assetId}_1`)] : []];
+	return importMediaAsset(prepared, fact, (prefix) => {
+		const id = (prefix === "entity" ? entities : relations).shift();
+		if (!id) throw new Error(`Media ${fact.assetId} exhausted deterministic ${prefix} slots`);
+		return id;
+	}).rows;
+}
+function findMediaId(rows, mediaId, kind) {
+	const media = findCanonicalMedia(rows, mediaId, kind === "voiceover-recording" ? "memota-speech" : "memota").media;
+	if (!media) throw new Error(`Imported media ${mediaId} is missing`);
+	return media.entityId;
+}
+function findCanonicalMedia(rows, mediaId, system = "memota") {
+	const assets = rows.entities.filter((row) => row.entityKind === "asset" && row.payload.system === system && row.payload.key === mediaId);
+	if (assets.length > 1) throw new Error(`Imported media ${mediaId} has duplicate Asset identities`);
+	const asset = assets[0];
+	if (!asset) return {};
+	const links = rows.relations.filter((relation) => relation.relationKind === "from-asset" && relation.endpoint1EntityId === asset.entityId);
+	if (rows.relations.some((relation) => relation.relationKind === "from-asset" && relation.endpoint0EntityId === asset.entityId)) throw new Error(`Imported media ${mediaId} has reversed from-asset relation`);
+	if (links.length > 1) throw new Error(`Imported media ${mediaId} has duplicate media identities`);
+	const media = rows.entities.find((row) => row.entityId === links[0]?.endpoint0EntityId);
+	if (links.length && (!media || media.entityKind !== "image" && media.entityKind !== "video" && media.entityKind !== "audio" && !(system === "memota-speech" && media.entityKind === "voiceover-recording"))) throw new Error(`Imported media ${mediaId} has invalid media identity`);
+	return {
+		asset,
+		...media ? { media } : {}
+	};
+}
+function hasDerivation(relations, output, source) {
+	return relations.some((relation) => relation.relationKind === "derived-from" && relation.endpoint0EntityId === output && relation.endpoint1EntityId === source);
+}
+//#endregion
+//#region src/entity-editor/revise-audio-script.ts
+/** Revise text as an independent authored document, never as a version-family mutation. */
+function reviseAudioScript(rows, input) {
+	if (typeof input.editId !== "string" || !input.editId.trim()) throw new Error("editId is required");
+	if (!Array.isArray(input.edits) || !input.edits.length) throw new Error("At least one segment edit is required");
+	const edits = /* @__PURE__ */ new Map();
+	for (const edit of input.edits) {
+		if (!edit.segmentId?.trim() || typeof edit.text !== "string" || !edit.text.trim()) throw new Error("Segment text must be nonempty");
+		if (edits.has(edit.segmentId)) throw new Error("Duplicate segment edit");
+		edits.set(edit.segmentId, edit.text);
+	}
+	const signature = hash({
+		...input,
+		captionUsages: input.captionUsages ?? []
+	});
+	const prior = rows.relations.filter((r) => r.relationKind === "derived-from" && r.trace.command === "revise-audio-script" && r.trace.editId === input.editId);
+	if (prior.length && (prior.length !== 1 || prior[0].trace.signature !== signature)) throw new Error("AudioScript edit identity conflict");
+	const source = rows.entities.find((row) => row.entityId === input.sourceAudioScriptEntityId);
+	if (source?.entityKind !== "audio-script") throw new Error("AudioScript source is missing");
+	assembleScriptText({
+		...source,
+		entityKind: "audio-script"
+	});
+	const payload = structuredClone(source.payload);
+	if (!Array.isArray(payload.segments)) throw new Error("AudioScript must own its segments");
+	const segmentIds = new Set(payload.segments.filter(isJsonObject).map((segment) => segment.segmentId));
+	for (const segmentId of edits.keys()) if (!segmentIds.has(segmentId)) throw new Error(`Unknown segment ${segmentId}`);
+	const changedSegments = /* @__PURE__ */ new Set();
+	payload.segments = payload.segments.map((segment) => {
+		if (segment === null || typeof segment !== "object" || Array.isArray(segment)) throw new Error("Invalid segment");
+		const text = edits.get(String(segment.segmentId)) ?? segment.text;
+		if (text !== segment.text) changedSegments.add(String(segment.segmentId));
+		return {
+			...segment,
+			text
+		};
+	});
+	if (!changedSegments.size) {
+		if (prior.length) throw new Error("AudioScript edit identity conflict");
+		return {
+			rows,
+			audioScriptEntityId: source.entityId,
+			captionUsages: [],
+			changed: false
+		};
+	}
+	delete payload.assetContentHash;
+	const id = hash(input.editId);
+	const audioScriptEntityId = createEntityId(`entity_script_revision_${id}`);
+	const audioScript = {
+		entityId: audioScriptEntityId,
+		entityKind: "audio-script",
+		payload
+	};
+	const provenance = {
+		relationId: createRelationId(`relation_script_revision_${id}`),
+		relationKind: "derived-from",
+		endpoint0EntityId: audioScriptEntityId,
+		endpoint1EntityId: source.entityId,
+		metadata: {},
+		trace: {
+			command: "revise-audio-script",
+			editId: input.editId,
+			signature
+		}
+	};
+	const selectedMarkers = /* @__PURE__ */ new Set();
+	const planCaption = (usage, index, targetAudioScriptEntityId) => {
+		if (selectedMarkers.has(usage.markerEntityId)) throw new Error("Duplicate caption usage");
+		selectedMarkers.add(usage.markerEntityId);
+		const caption = rows.entities.find((row) => row.entityId === usage.captionEntityId);
+		if (caption?.entityKind !== "caption") throw new Error("Caption is missing");
+		const assembled = assembleCaptionContent(rows, caption.entityId);
+		if (assembled.audioScript.entityId !== source.entityId) throw new Error("Caption does not use the source AudioScript");
+		const selection = assembled.caption.payload.selection;
+		if (isJsonObject(selection) && selection.textRange !== void 0 && typeof selection.segmentId === "string" && changedSegments.has(selection.segmentId) && usage.selection === void 0) throw new Error("Changed partial Caption requires an explicit selection");
+		const bases = caption.payload.baseEntityIds;
+		if (!Array.isArray(bases) || !bases.includes(source.entityId)) throw new Error("Caption requires a direct AudioScript base");
+		const clipMarkers = rows.relations.filter((r) => r.relationKind === "marker" && r.endpoint0EntityId === usage.clipEntityId);
+		const clipContents = rows.relations.filter((r) => r.relationKind === "contain" && r.endpoint0EntityId === usage.clipEntityId);
+		const markerOwners = rows.relations.filter((r) => r.relationKind === "marker" && r.endpoint1EntityId === usage.markerEntityId);
+		if (clipMarkers.length !== 1 || clipMarkers[0].endpoint1EntityId !== usage.markerEntityId || markerOwners.length !== 1 || clipContents.length !== 1) throw new Error("Caption usage conflict");
+		const newCaptionId = createEntityId(`entity_caption_revision_${id}_${index}`);
+		return {
+			clone: {
+				...caption,
+				entityId: newCaptionId,
+				payload: {
+					...structuredClone(caption.payload),
+					baseEntityIds: bases.map((base) => base === source.entityId ? targetAudioScriptEntityId : base),
+					...usage.selection === void 0 ? {} : { selection: structuredClone(usage.selection) }
+				}
+			},
+			clipContent: clipContents[0],
+			newCaptionId,
+			relationId: createRelationId(`relation_caption_revision_${id}_${index}`),
+			trace: {
+				command: "revise-audio-script",
+				editId: input.editId,
+				usageIndex: index
+			}
+		};
+	};
+	if (prior.length) {
+		const currentAudioScriptEntityId = prior[0].endpoint0EntityId;
+		if (!equalJson(prior[0], {
+			...provenance,
+			relationId: prior[0].relationId,
+			endpoint0EntityId: currentAudioScriptEntityId
+		})) throw new Error("AudioScript edit identity conflict");
+		const preservedScripts = rows.entities.filter((row) => row.entityId === currentAudioScriptEntityId);
+		const preservedScript = preservedScripts[0]?.entityKind === "audio-script" ? {
+			...preservedScripts[0],
+			payload: Object.fromEntries(Object.entries(preservedScripts[0].payload).filter(([key]) => key !== "assetContentHash"))
+		} : preservedScripts[0];
+		if (preservedScripts.length !== 1 || !equalJson(preservedScript, {
+			...audioScript,
+			entityId: currentAudioScriptEntityId
+		})) throw new Error("AudioScript edit identity conflict");
+		let relations = [...rows.relations];
+		let changed = false;
+		const captionUsages = [];
+		for (const [index, usage] of (input.captionUsages ?? []).entries()) {
+			const plan = planCaption(usage, index, currentAudioScriptEntityId);
+			const preservedCaptions = rows.entities.filter((row) => row.entityId === plan.newCaptionId);
+			if (preservedCaptions.length !== 1 || !equalJson(preservedCaptions[0], plan.clone)) throw new Error("Caption usage conflict after revision");
+			const plannedEdge = {
+				relationId: plan.relationId,
+				relationKind: "contain",
+				endpoint0EntityId: plan.clipContent.endpoint0EntityId,
+				endpoint1EntityId: plan.newCaptionId,
+				metadata: structuredClone(plan.clipContent.metadata),
+				trace: plan.trace
+			};
+			if (plan.clipContent.relationId === plan.relationId) {
+				if (!equalJson(plan.clipContent, plannedEdge)) throw new Error("Caption usage conflict after revision");
+			} else {
+				if (plan.clipContent.endpoint1EntityId !== usage.captionEntityId) throw new Error("Caption usage conflict after revision");
+				relations = relations.filter((row) => row.relationId !== plan.clipContent.relationId);
+				relations.push(plannedEdge);
+				changed = true;
+			}
+			captionUsages.push({
+				clipEntityId: usage.clipEntityId,
+				markerEntityId: usage.markerEntityId,
+				previousCaptionEntityId: usage.captionEntityId,
+				captionEntityId: plan.newCaptionId
+			});
+		}
+		if (!changed) return {
+			rows,
+			audioScriptEntityId: currentAudioScriptEntityId,
+			captionUsages,
+			changed: false
+		};
+		const revised = {
+			entities: rows.entities,
+			relations
+		};
+		decodeAndValidate(rows, revised);
+		return {
+			rows: revised,
+			audioScriptEntityId: currentAudioScriptEntityId,
+			captionUsages,
+			changed: true
+		};
+	}
+	const result = {
+		entities: [...rows.entities, audioScript],
+		relations: [...rows.relations, provenance]
+	};
+	const entities = [...result.entities];
+	let relations = [...result.relations];
+	const captionUsages = [];
+	for (const [index, usage] of (input.captionUsages ?? []).entries()) {
+		const plan = planCaption(usage, index, audioScriptEntityId);
+		if (plan.clipContent.endpoint1EntityId !== usage.captionEntityId) throw new Error("Caption usage conflict");
+		entities.push(plan.clone);
+		assembleCaptionContent({
+			entities,
+			relations
+		}, plan.newCaptionId);
+		relations = relations.filter((r) => r.relationId !== plan.clipContent.relationId);
+		relations.push({
+			relationId: plan.relationId,
+			relationKind: "contain",
+			endpoint0EntityId: plan.clipContent.endpoint0EntityId,
+			endpoint1EntityId: plan.newCaptionId,
+			metadata: structuredClone(plan.clipContent.metadata),
+			trace: plan.trace
+		});
+		captionUsages.push({
+			clipEntityId: usage.clipEntityId,
+			markerEntityId: usage.markerEntityId,
+			previousCaptionEntityId: usage.captionEntityId,
+			captionEntityId: plan.newCaptionId
+		});
+	}
+	const revised = {
+		entities,
+		relations
+	};
+	decodeAndValidate(rows, revised);
+	return {
+		rows: revised,
+		audioScriptEntityId,
+		captionUsages,
+		changed: true
+	};
+}
+function decodeAndValidate(previous, revised) {
+	decodeEntityRelationRows(revised, {});
+	validateEntityRelationTransition(previous, revised);
+}
+function hash(value) {
+	return bytesToHex(sha256(new TextEncoder().encode(canonicalJson(value))));
+}
+//#endregion
+//#region src/entity-editor/legacy-entity-migration.ts
+/** One-time import only. Ordinary editor operations must never reverse-diff a legacy document. */
+function migrateLegacyTimelineToEntities(legacy, assetFacts, initial = {
+	entities: [],
+	relations: []
+}, idFactory = (prefix) => `${prefix}_${globalThis.crypto.randomUUID()}`) {
+	assertSupportedLegacy(legacy);
+	if (initial.entities.some((row) => row.entityKind === "timeline")) fail("Timeline already exists; migration is not an editing operation");
+	if (hasResolvedPlacement(legacy)) fail("An entity projection cannot be migrated as legacy state");
+	const normalizedMainRanges = overlapNormalizedMainRanges(legacy);
+	let entities = structuredClone([...initial.entities]);
+	let relations = structuredClone([...initial.relations]);
+	const documentAudioScriptEntityId = ensureDocumentAudioScript(entities) ?? (() => {
+		const id = createEntityId(idFactory("entity"));
+		entities.push({
+			entityId: id,
+			entityKind: "audio-script",
+			payload: { segments: [] }
+		});
+		return String(id);
+	})();
+	const addEntity = (kind, payload, existingId) => {
+		const entityId = createEntityId(existingId ?? idFactory("entity"));
+		if (entities.some((row) => row.entityId === entityId)) fail(`Migration entity identity collision: ${entityId}`);
+		entities.push({
+			entityId,
+			entityKind: kind,
+			payload
+		});
+		return entityId;
+	};
+	const link = (kind, from, to, metadata = {}) => {
+		const relationId = createRelationId(idFactory("relation"));
+		if (relations.some((row) => row.relationId === relationId)) fail(`Migration relation identity collision: ${relationId}`);
+		relations.push({
+			relationId,
+			relationKind: kind,
+			endpoint0EntityId: createEntityId(from),
+			endpoint1EntityId: createEntityId(to),
+			metadata,
+			trace: {}
+		});
+	};
+	const facts = /* @__PURE__ */ new Map();
+	for (const fact of assetFacts) {
+		if (facts.has(fact.assetId)) fail(`Duplicate asset facts for ${fact.assetId}`);
+		facts.set(fact.assetId, fact);
+	}
+	const contentByPartId = /* @__PURE__ */ new Map();
+	for (const track of legacy.tracks ?? []) for (const item of track.items ?? []) {
+		const part = requirePart(legacy, item.part_id);
+		if (part.video_clip !== void 0) {
+			const assetId = part.video_clip.origin_media_id;
+			const fact = facts.get(assetId);
+			if (fact === void 0) fail(`Missing factual media metadata for ${assetId}`);
+			if (fact.kind !== "image" && fact.kind !== "video") fail(`Legacy video Clip ${item.part_id} requires an image or video fact`);
+			const imported = importMediaAsset({
+				entities,
+				relations
+			}, fact, idFactory);
+			entities = [...imported.rows.entities];
+			relations = [...imported.rows.relations];
+			contentByPartId.set(item.part_id, imported.contentEntityId);
+		} else if (part.speech !== void 0) {
+			const speech = part.speech;
+			const imported = importMediaAsset({
+				entities,
+				relations
+			}, {
+				assetId: speech.origin_speech_id,
+				kind: "voiceover-recording",
+				durationMs: speech.media_duration_ms,
+				storageKey: speech.audio_storage_key,
+				voice: {
+					system: "voice-library",
+					key: speech.voice.id,
+					...speech.voice.name === void 0 ? {} : { name: speech.voice.name }
+				}
+			}, idFactory);
+			entities = [...imported.rows.entities];
+			relations = [...imported.rows.relations];
+			contentByPartId.set(item.part_id, imported.contentEntityId);
+			const phonemeScript = speech.phoneme_script;
+			ensureSpeechPhoneticChain(imported.contentEntityId, speech.audio_script, typeof phonemeScript === "string" ? phonemeScript : void 0, entities, relations, addEntity, link, documentAudioScriptEntityId);
+		} else if (part.bgm !== void 0) {
+			const bgm = part.bgm;
+			const fact = facts.get(bgm.origin_media_id);
+			if (fact === void 0) fail(`Missing factual media metadata for ${bgm.origin_media_id}`);
+			if (fact.kind !== "audio") fail(`Legacy BGM ${item.part_id} requires an audio fact`);
+			if (fact.storageKey !== bgm.audio_storage_key) fail(`Factual storage key conflicts with legacy BGM ${item.part_id}`);
+			const imported = importMediaAsset({
+				entities,
+				relations
+			}, fact, idFactory);
+			entities = [...imported.rows.entities];
+			relations = [...imported.rows.relations];
+			contentByPartId.set(item.part_id, imported.contentEntityId);
+		}
+	}
+	const timeline = addEntity("timeline", legacy.timeline?.unit_time_ms === void 0 ? {} : { unit_time_ms: legacy.timeline.unit_time_ms });
+	const trackIds = /* @__PURE__ */ new Map();
+	for (const [order, oldTrack] of (legacy.tracks ?? []).entries()) {
+		const track = addEntity("track", {
+			role: oldTrack.parts_kind,
+			order,
+			...oldTrack.is_hidden === void 0 ? {} : { hidden: oldTrack.is_hidden }
+		}, oldTrack.id);
+		trackIds.set(oldTrack, track);
+		link("contain", timeline, track);
+	}
+	for (const oldTrack of legacy.tracks ?? []) {
+		const track = trackIds.get(oldTrack);
+		for (const [order, item] of (oldTrack.items ?? []).entries()) {
+			const part = requirePart(legacy, item.part_id);
+			const role = oldTrack.parts_kind;
+			const volume = part.video_clip?.volume ?? part.speech?.volume ?? part.bgm?.volume;
+			const clip = addEntity("clip", {
+				...volume === void 0 ? {} : { volume },
+				order: role === "bgm" ? 0 : order
+			}, item.part_id);
+			let content = contentByPartId.get(item.part_id);
+			let duration;
+			let markerPayload;
+			if (part.video_clip !== void 0) {
+				const video = part.video_clip;
+				duration = effectiveVideoClipDurationMs(video);
+				const fact = facts.get(video.origin_media_id);
+				const rate = speedOf(video.speed_shift);
+				markerPayload = {
+					inMs: video.play_in,
+					outMs: video.play_out,
+					...(fact.kind === "image" || fact.kind === "video") && video.speed_shift !== void 0 ? { rate } : {}
+				};
+			} else if (part.speech !== void 0) {
+				duration = part.speech.media_duration_ms;
+				markerPayload = {
+					inMs: 0,
+					outMs: duration
+				};
+			} else if (part.caption !== void 0) {
+				const caption = part.caption;
+				duration = caption.initial_duration_ms;
+				const voiceover = contentByPartId.get(caption.speech_part_id);
+				const render = relations.find((relation) => relation.relationKind === "derived-from" && relation.endpoint0EntityId === voiceover);
+				const phonetic = entities.find((entity) => entity.entityId === render?.endpoint1EntityId);
+				const script = phonetic === void 0 ? void 0 : composedAudioScript(phonetic, entities);
+				if (script === void 0) fail("Legacy Caption has no composed AudioScript");
+				const sourceText = scriptText(script);
+				const captionText = caption.text;
+				const offset = sourceText.indexOf(captionText);
+				if (!captionText.trim() || offset < 0 || sourceText.indexOf(captionText, offset + 1) >= 0) fail("Legacy Caption needs explicit unambiguous AudioScript selection before cutover");
+				const selection = {
+					segmentId: "segment-0",
+					...sourceText === captionText ? {} : { textRange: {
+						start: Array.from(sourceText.slice(0, offset)).length,
+						end: Array.from(sourceText.slice(0, offset + captionText.length)).length
+					} }
+				};
+				content = addEntity("caption", {
+					durationMs: duration,
+					baseEntityIds: [script.entityId],
+					selection,
+					...caption.style === void 0 ? {} : { style: toEntityCaptionStyle(caption.style) }
+				});
+				markerPayload = {
+					inMs: 0,
+					outMs: duration
+				};
+			} else {
+				const bgm = part.bgm;
+				const fact = facts.get(bgm.origin_media_id);
+				if (fact.kind !== "audio") fail(`Legacy BGM ${item.part_id} requires an audio fact`);
+				duration = fact.durationMs;
+				markerPayload = {
+					inMs: 0,
+					outMs: duration,
+					fillTimeline: true
+				};
+			}
+			if (content === void 0) fail(`Migration could not resolve content for ${item.part_id}`);
+			const normalizedMainRange = role === "video_clip" ? normalizedMainRanges?.get(item.part_id) : void 0;
+			if (normalizedMainRange !== void 0) markerPayload = {
+				...markerPayload,
+				startMs: normalizedMainRange.start
+			};
+			else if (item.time_position.mode === "absolute" && role !== "bgm" || item.time_position.mode === "anchored") markerPayload = {
+				...markerPayload,
+				startMs: item.time_position.offsetMs
+			};
+			const marker = addEntity("sequence-marker", markerPayload);
+			link("contain", track, clip);
+			link("marker", clip, marker);
+			link("contain", clip, content);
+			if (item.time_position.mode === "anchored") link("clip-anchor", clip, item.time_position.anchorPartId);
+		}
+	}
+	const rows = {
+		entities,
+		relations
+	};
+	assertEntityProjectionPreservesLegacy(legacy, projectEntityTimeline(rows), rows);
+	return rows;
+}
+/** Server gate: a cutover may change representation, never the existing render facts. */
+function assertEntityProjectionPreservesLegacy(legacy, projection, rows) {
+	assertSupportedLegacy(legacy);
+	if (!hasResolvedPlacement(projection)) fail("Expected an entity projection for migration");
+	const normalizedMainRanges = overlapNormalizedMainRanges(legacy);
+	const compatibilityFacts = (document, placementResolved) => {
+		const view = fromVideoDocument(document, { placementResolved });
+		for (const part of Object.values(view.part_library ?? {})) {
+			const speech = part.speech;
+			if (speech?.phoneme_script === null) delete speech.phoneme_script;
+			const speed = part.video_clip?.speed_shift;
+			if (speed !== void 0) delete speed.mode;
+		}
+		return { view };
+	};
+	if (canonical(compatibilityFacts(legacy, false)) !== canonical(compatibilityFacts(projection, true))) fail("Entity migration must preserve all existing timeline facts; edit after cutover");
+	const trackOrders = [];
+	for (const oldTrack of legacy.tracks ?? []) {
+		const candidates = rows.entities.filter((row) => row.entityKind === "track" && (oldTrack.id === void 0 ? row.payload.role === oldTrack.parts_kind : row.entityId === oldTrack.id));
+		if (candidates.length !== 1) fail("Migration must preserve every Track identity");
+		const track = candidates[0];
+		if (track.payload.role !== oldTrack.parts_kind || (track.payload.hidden ?? false) !== (oldTrack.is_hidden ?? false)) fail("Migration must preserve Track role and visibility");
+		if (typeof track.payload.order !== "number" || !Number.isFinite(track.payload.order)) fail("Migration must preserve Track order");
+		trackOrders.push(track.payload.order);
+		const sequentialOrders = [];
+		for (const item of oldTrack.items ?? []) {
+			const clip = rows.entities.find((row) => row.entityId === item.part_id && row.entityKind === "clip");
+			const binding = rows.relations.filter((row) => row.relationKind === "marker" && row.endpoint0EntityId === item.part_id && rows.entities.some((entity) => entity.entityId === row.endpoint1EntityId && entity.entityKind === "sequence-marker"));
+			const marker = rows.entities.find((row) => row.entityId === binding[0]?.endpoint1EntityId && row.entityKind === "sequence-marker");
+			if (clip === void 0 || binding.length !== 1 || marker === void 0) fail("Migration must preserve Clip/Marker placement identity");
+			const anchors = rows.relations.filter((row) => row.relationKind === "clip-anchor" && row.endpoint0EntityId === clip.entityId);
+			const normalizedMainRange = oldTrack.parts_kind === "video_clip" ? normalizedMainRanges?.get(item.part_id) : void 0;
+			if (normalizedMainRange !== void 0) {
+				if (marker.payload.startMs !== normalizedMainRange.start || anchors.length !== 0) fail("Migration must preserve the legacy overlap-normalized main Track");
+			} else if (oldTrack.parts_kind === "bgm") {
+				if (clip.payload.order !== 0 || marker.payload.startMs !== void 0 || marker.payload.fillTimeline !== true || anchors.length !== 0) fail("Migration must preserve timeline-filling BGM semantics");
+			} else if (item.time_position.mode === "sequential") {
+				if (marker.payload.startMs !== void 0 || typeof clip.payload.order !== "number" || !Number.isFinite(clip.payload.order) || anchors.length !== 0) fail("Migration must preserve sequential placement semantics");
+				sequentialOrders.push(clip.payload.order);
+			} else if (item.time_position.mode === "absolute") {
+				if (marker.payload.startMs !== item.time_position.offsetMs || anchors.length !== 0) fail("Migration must preserve absolute placement semantics");
+			} else if (marker.payload.startMs !== item.time_position.offsetMs || anchors.length !== 1 || anchors[0].endpoint1EntityId !== item.time_position.anchorPartId) fail("Migration must preserve anchored placement semantics");
+		}
+		if (sequentialOrders.some((order, index) => index > 0 && order <= sequentialOrders[index - 1])) fail("Migration must preserve sequential Clip order");
+	}
+	if (trackOrders.some((order, index) => index > 0 && order <= trackOrders[index - 1])) fail("Migration must preserve Track stacking order");
+}
+function assertSupportedLegacy(document) {
+	assertValidVideoDocument(document);
+	const tracks = document.tracks ?? [];
+	assertKnownFields(document.timeline ?? {}, ["unit_time_ms"], "Timeline");
+	if (document.timeline?.unit_time_ms !== void 0 && (typeof document.timeline.unit_time_ms !== "number" || !Number.isFinite(document.timeline.unit_time_ms) || document.timeline.unit_time_ms <= 0)) fail("Migration requires a positive finite unit_time_ms");
+	const seenRoles = /* @__PURE__ */ new Set();
+	const placed = /* @__PURE__ */ new Map();
+	for (const track of tracks) {
+		const role = track.parts_kind;
+		if (role === void 0 || ![
+			"video_clip",
+			"speech",
+			"caption",
+			"bgm"
+		].includes(role)) fail("Every legacy Track requires a supported role");
+		if (seenRoles.has(role)) fail(`The compatibility editor supports only one ${role} Track`);
+		seenRoles.add(role);
+		if (track.id !== void 0 && (track.id.trim() === "" || track.id.trim() !== track.id)) fail("Migration requires trimmed Track identities");
+		for (const item of track.items ?? []) {
+			if (item.part_id.trim() === "" || item.part_id.trim() !== item.part_id) fail("Migration requires trimmed Clip identities");
+			if (placed.has(item.part_id)) fail(`Legacy part ${item.part_id} is placed more than once`);
+			placed.set(item.part_id, {
+				track,
+				item
+			});
+			assertKnownFields(item.time_position, item.time_position.mode === "sequential" ? ["mode"] : [
+				"mode",
+				"anchorPartId",
+				"offsetMs"
+			], "placement");
+			if (item.time_position.mode === "absolute") requireMilliseconds(item.time_position.offsetMs, "absolute offset");
+			if (item.time_position.mode === "anchored") {
+				if (item.time_position.anchorPartId.trim() === "" || item.time_position.anchorPartId.trim() !== item.time_position.anchorPartId) fail("Migration requires a trimmed anchor identity");
+				requireMilliseconds(item.time_position.offsetMs, "anchor offset");
+			}
+			if (item.fallback_abs_ms !== void 0) requireMilliseconds(item.fallback_abs_ms, "anchor fallback");
+			assertKnownFields(item, [
+				"part_id",
+				"time_position",
+				"fallback_abs_ms"
+			], "TrackItem");
+		}
+		assertKnownFields(track, [
+			"id",
+			"parts_kind",
+			"is_hidden",
+			"items"
+		], "Track");
+	}
+	for (const [id, part] of Object.entries(document.part_library ?? {})) {
+		const placement = placed.get(id);
+		if (placement === void 0) fail(`Cannot discard unplaced legacy part ${id}`);
+		assertPartSupported(id, part, placement.track.parts_kind);
+	}
+	for (const id of placed.keys()) if (document.part_library?.[id] === void 0) fail(`Placed Clip ${id} has no part payload`);
+	assertLegacyRelations(document, placed);
+}
+function assertPartSupported(id, part, role) {
+	assertKnownFields(part, [
+		"video_clip",
+		"speech",
+		"caption",
+		"bgm"
+	], "Part");
+	const present = [
+		"video_clip",
+		"speech",
+		"caption",
+		"bgm"
+	].filter((kind) => part[kind] !== void 0);
+	if (present.length !== 1 || present[0] !== role) fail(`Legacy part ${id} must match its ${role} Track`);
+	if (part.video_clip !== void 0) {
+		const clip = part.video_clip;
+		if (clip.id !== id || clip.kind !== "video_clip" || !trimmed(clip.origin_media_id) || clip.play_in === void 0 || clip.play_out === void 0) fail("Migration requires complete Clip identity, media and trim facts");
+		requireMilliseconds(clip.play_in, "Clip play_in");
+		requireMilliseconds(clip.play_out, "Clip play_out");
+		if (clip.play_out <= clip.play_in) fail("Migration requires a non-empty Clip trim window");
+		requireFinite(clip.volume, "Clip volume");
+		const speed = clip.speed_shift;
+		if (speed !== void 0 && (speed.category !== "linear" || speed.config?.linear === void 0 || speed.mode !== void 0 && typeof speed.mode !== "string")) fail("Nonlinear speed requires an entity remapping adapter");
+		if (speed !== void 0) {
+			const rate = speed.config?.linear?.speed;
+			if (typeof rate !== "number" || !Number.isFinite(rate) || rate <= 0) fail("Migration requires a positive finite speed");
+			assertKnownFields(speed, [
+				"category",
+				"mode",
+				"config"
+			], "speed_shift");
+			assertKnownFields(speed.config, ["linear"], "speed config");
+			assertKnownFields(speed.config.linear, ["speed"], "linear speed");
+		}
+		assertKnownFields(clip, [
+			"id",
+			"kind",
+			"origin_media_id",
+			"play_in",
+			"play_out",
+			"volume",
+			"speed_shift"
+		], "Clip");
+	} else if (part.speech !== void 0) {
+		const speech = part.speech;
+		const phonemeScript = speech.phoneme_script;
+		if (speech.id !== id || speech.kind !== "speech" || !trimmed(speech.origin_speech_id) || !trimmed(speech.audio_storage_key) || typeof speech.audio_script !== "string") fail("Migration requires complete Speech identity and physical take facts");
+		requirePositiveMilliseconds(speech.media_duration_ms, "Speech duration");
+		requireFinite(speech.volume, "Speech volume");
+		if (!trimmed(speech.voice?.id)) fail("Migration requires an explicit voice-library identity");
+		if (speech.voice?.name !== void 0 && typeof speech.voice.name !== "string") fail("Migration requires a string voice name when present");
+		if (!Array.isArray(speech.caption_ids) || speech.caption_ids.some((captionId) => !trimmed(captionId))) fail("Migration requires explicit Speech caption identities");
+		if (new Set(speech.caption_ids).size !== speech.caption_ids.length) fail("Migration requires unique Speech caption identities");
+		if (phonemeScript !== void 0 && phonemeScript !== null && typeof phonemeScript !== "string") fail("Migration requires a string phoneme_script when present");
+		assertKnownFields(speech.voice, ["id", "name"], "voice");
+		assertKnownFields(speech, [
+			"id",
+			"kind",
+			"media_duration_ms",
+			"audio_script",
+			"volume",
+			"audio_storage_key",
+			"origin_speech_id",
+			"voice",
+			"caption_ids",
+			"phoneme_script"
+		], "Speech");
+	} else if (part.caption !== void 0) {
+		const caption = part.caption;
+		if (caption.id !== id || caption.kind !== "caption" || !trimmed(caption.speech_part_id) || typeof caption.text !== "string") fail("Migration requires complete Caption identity, Speech provenance and text");
+		requireMilliseconds(caption.start_ms, "Caption source offset");
+		requirePositiveMilliseconds(caption.initial_duration_ms, "Caption duration");
+		if (caption.style !== void 0) assertCaptionStyle(caption.style);
+		assertKnownFields(caption, [
+			"id",
+			"kind",
+			"initial_duration_ms",
+			"speech_part_id",
+			"text",
+			"start_ms",
+			"style"
+		], "Caption");
+	} else if (part.bgm !== void 0) {
+		const bgm = part.bgm;
+		if (bgm.id !== id || bgm.kind !== "bgm" || !trimmed(bgm.origin_media_id) || !trimmed(bgm.audio_storage_key)) fail("Migration requires complete BGM identity and physical media facts");
+		requireFinite(bgm.volume, "BGM volume");
+		assertKnownFields(bgm, [
+			"id",
+			"kind",
+			"audio_storage_key",
+			"volume",
+			"origin_media_id"
+		], "BGM");
 	}
 }
-//#endregion
-//#region src/client/sse.ts
-async function readMengineEventStream(options) {
-	const response = await options.client.fetch(options.client.eventsUrl(), {
-		headers: options.client.headers(),
-		signal: options.signal
-	});
-	if (!response.ok) throw new Error(`mengine event stream failed: ${response.status}`);
-	const reader = response.body?.getReader();
-	if (reader == null) throw new Error("mengine event stream response has no readable body");
-	options.onOpen?.();
-	const decoder = new TextDecoder();
-	let buffer = "";
-	while (options.signal?.aborted !== true) {
-		const { done, value } = await reader.read();
-		if (done) return;
-		buffer += decoder.decode(value, { stream: true });
-		let splitAt = findSseFrameBoundary(buffer);
-		while (splitAt >= 0) {
-			const frame = buffer.slice(0, splitAt);
-			buffer = buffer.slice(buffer[splitAt] === "\r" ? splitAt + 4 : splitAt + 2);
-			handleSseFrame(frame, options);
-			splitAt = findSseFrameBoundary(buffer);
+function assertLegacyRelations(document, placed) {
+	const captionIdsBySpeech = /* @__PURE__ */ new Map();
+	for (const track of document.tracks ?? []) {
+		if (track.parts_kind === "bgm" && (track.items?.length ?? 0) > 1) fail("The compatibility editor supports only one BGM Clip");
+		for (const item of track.items ?? []) {
+			const part = requirePart(document, item.part_id);
+			const position = item.time_position;
+			if (track.parts_kind === "video_clip" && position.mode === "anchored") fail("Anchored video Clips require an overlay adapter");
+			if (track.parts_kind === "bgm") {
+				if (position.mode !== "absolute" || position.offsetMs !== 0) fail("Legacy BGM must start at the Timeline origin");
+			} else if (position.mode === "anchored") {
+				const host = placed.get(position.anchorPartId);
+				if (host === void 0) fail(`Legacy anchor ${position.anchorPartId} is not placed`);
+				if (track.parts_kind === "speech" && host.track.parts_kind !== "video_clip") fail("Speech may only anchor to a video Clip");
+				if (track.parts_kind === "caption") {
+					if (host.track.parts_kind !== "speech") fail("Caption may only anchor to a Speech Clip");
+					const caption = part.caption;
+					if (position.anchorPartId !== caption.speech_part_id || position.offsetMs !== caption.start_ms) fail("Caption placement must agree with its Speech provenance and source offset");
+				}
+			} else if (track.parts_kind === "caption") fail("Caption placement requires an explicit Speech anchor");
+			if (part.caption !== void 0) {
+				const ids = captionIdsBySpeech.get(part.caption.speech_part_id) ?? [];
+				ids.push(item.part_id);
+				captionIdsBySpeech.set(part.caption.speech_part_id, ids);
+			}
 		}
 	}
+	for (const [id, placement] of placed) {
+		const speech = requirePart(document, id).speech;
+		if (speech === void 0) continue;
+		const expected = captionIdsBySpeech.get(id) ?? [];
+		if (canonical(speech.caption_ids) !== canonical(expected)) fail(`Speech ${id} caption_ids must agree with the Caption Track order`);
+		if (placement.item.time_position.mode === "anchored") continue;
+		if (placement.item.time_position.mode !== "absolute") fail("Speech placement must be anchored or absolute");
+	}
+	const intervals = (fromVideoDocument(document).main_track?.items ?? []).map((item) => {
+		const clip = document.part_library?.[item.part_id]?.video_clip;
+		if (clip === void 0) fail("Projection must preserve every video Clip");
+		return {
+			start: item.abs_time_position ?? 0,
+			end: (item.abs_time_position ?? 0) + effectiveVideoClipDurationMs(clip)
+		};
+	}).sort((left, right) => left.start - right.start);
+	if (intervals.some((interval, index) => index > 0 && interval.start < intervals[index - 1].end)) fail("Overlapping video Clips require an overlay adapter");
 }
-function handleSseFrame(frame, options) {
-	const event = parseSseFrame(frame);
-	if (event.event === "resync") {
-		options.onResync?.();
-		return;
+/**
+* Legacy reads perform one speech-overlap pass after laying the visual lane out
+* sequentially. Entity reads deliberately do not run that hidden cascade. When
+* the pass moved any visual Clip, cutover therefore records the complete solved
+* visual lane as explicit target ranges. Mixing absolute and sequential Clips
+* would create two unrelated placement chains and could reorder the lane.
+*/
+function overlapNormalizedMainRanges(document) {
+	const track = document.tracks?.find((candidate) => candidate.parts_kind === "video_clip");
+	if (track === void 0 || (track.items?.length ?? 0) === 0) return void 0;
+	const solved = fromVideoDocument(document).main_track?.items ?? [];
+	const starts = new Map(solved.map((item) => [item.part_id, requireMilliseconds(item.abs_time_position, `Solved position for ${item.part_id ?? "unknown Clip"}`)]));
+	let cursor = 0;
+	let moved = false;
+	const ranges = /* @__PURE__ */ new Map();
+	for (const item of track.items ?? []) {
+		const part = requirePart(document, item.part_id).video_clip;
+		if (part === void 0) fail(`Projection must preserve video Clip ${item.part_id}`);
+		const duration = effectiveVideoClipDurationMs(part);
+		const start = starts.get(item.part_id);
+		if (start === void 0) fail(`Projection must preserve video Clip ${item.part_id}`);
+		if (start !== cursor) moved = true;
+		const end = start + duration;
+		requireMilliseconds(end, `Solved end for ${item.part_id}`);
+		ranges.set(item.part_id, {
+			start,
+			end
+		});
+		cursor += duration;
 	}
-	if (event.event !== "update" || event.data.length === 0) return;
-	options.onUpdate(JSON.parse(event.data.join("\n")));
+	return moved ? ranges : void 0;
 }
-function parseSseFrame(frame) {
-	let event = null;
-	const data = [];
-	for (const line of frame.split(/\r?\n/)) if (line.startsWith("event:")) event = line.slice(6).trim();
-	else if (line.startsWith("data:")) data.push(line.slice(5).trimStart());
+function requirePart(document, partId) {
+	const part = document.part_library?.[partId];
+	if (part === void 0) fail(`Placed Clip ${partId} has no part payload`);
+	return part;
+}
+function ensureSpeechPhoneticChain(voiceoverAudioEntityId, audioScriptText, phonemeScript, entities, relations, addEntity, link, documentAudioScriptEntityId) {
+	const renders = relations.filter((relation) => relation.relationKind === "derived-from" && relation.endpoint0EntityId === voiceoverAudioEntityId);
+	if (renders.length > 1) fail(`Voiceover ${voiceoverAudioEntityId} has ambiguous PhoneticScript provenance`);
+	if (renders.length === 1) {
+		const phonetic = entities.find((entity) => entity.entityId === renders[0].endpoint1EntityId && entity.entityKind === "phonetic-script");
+		if (phonetic === void 0) fail(`Voiceover ${voiceoverAudioEntityId} has a dangling PhoneticScript render`);
+		const script = composedAudioScript(phonetic, entities);
+		if (script === void 0 || scriptText(script) !== audioScriptText) fail(`Voiceover ${voiceoverAudioEntityId} conflicts with the legacy Speech script`);
+		return phonetic.entityId;
+	}
+	const script = entities.find((entity) => entity.entityId === documentAudioScriptEntityId);
+	if (script === void 0 || script.entityKind !== "audio-script") fail("Migration must carry the fixed document AudioScript");
+	const segments = script.payload.segments;
+	if (Array.isArray(segments) && segments.length > 0) {
+		if (scriptText(script) !== audioScriptText) fail(`Voiceover ${voiceoverAudioEntityId} conflicts with the project AudioScript text`);
+	} else {
+		const scriptIndex = entities.findIndex((row) => row.entityId === script.entityId);
+		entities[scriptIndex] = {
+			...script,
+			payload: { segments: [{
+				segmentId: "segment-0",
+				text: audioScriptText
+			}] }
+		};
+	}
+	const phonetic = addEntity("phonetic-script", {
+		baseEntityIds: [script.entityId],
+		...phonemeScript === void 0 ? {} : { phonemeScript }
+	});
+	link("derived-from", voiceoverAudioEntityId, phonetic);
+	return phonetic;
+}
+function composedAudioScript(phonetic, entities) {
+	return findComposedAudioScript({
+		entities,
+		relations: []
+	}, phonetic.entityId, "phonetic-script");
+}
+function scriptText(script) {
+	const segments = script.payload.segments;
+	if (!Array.isArray(segments)) fail("AudioScript requires segments");
+	return segments.map((segment) => {
+		if (segment === null || typeof segment !== "object" || Array.isArray(segment) || typeof segment.text !== "string") fail("AudioScript segment requires text");
+		return segment.text;
+	}).join("");
+}
+function toEntityCaptionStyle(style) {
 	return {
-		event,
-		data
+		...style.font_id === void 0 ? {} : { font: {
+			system: "font-library",
+			key: style.font_id
+		} },
+		...style.font_size === void 0 ? {} : { fontSize: style.font_size },
+		...style.font_color === void 0 ? {} : { fontColor: style.font_color },
+		...style.font_weight === void 0 ? {} : { fontWeight: style.font_weight },
+		...style.entrance_animation === void 0 ? {} : { entranceAnimation: style.entrance_animation },
+		...style.entrance_animation_duration_ms === void 0 ? {} : { entranceAnimationDurationMs: style.entrance_animation_duration_ms },
+		...style.stroke_color === void 0 ? {} : { strokeColor: style.stroke_color },
+		...style.stroke_width === void 0 ? {} : { strokeWidth: style.stroke_width },
+		...style.position_x === void 0 ? {} : { positionX: style.position_x },
+		...style.position_y === void 0 ? {} : { positionY: style.position_y }
 	};
 }
-function findSseFrameBoundary(buffer) {
-	const lf = buffer.indexOf("\n\n");
-	const crlf = buffer.indexOf("\r\n\r\n");
-	if (lf < 0) return crlf;
-	if (crlf < 0) return lf;
-	return Math.min(lf, crlf);
+function assertCaptionStyle(style) {
+	if (style.font_id !== void 0 && !trimmed(style.font_id)) fail("Caption font_id must be a trimmed identity");
+	for (const value of [
+		style.font_size,
+		style.font_weight,
+		style.entrance_animation_duration_ms,
+		style.stroke_width,
+		style.position_x,
+		style.position_y
+	]) if (value !== void 0) requireFinite(value, "Caption style number");
+	for (const value of [
+		style.font_color,
+		style.entrance_animation,
+		style.stroke_color
+	]) if (value !== void 0 && typeof value !== "string") fail("Caption style text must be a string");
+	assertKnownFields(style, [
+		"font_id",
+		"font_size",
+		"font_color",
+		"font_weight",
+		"entrance_animation",
+		"entrance_animation_duration_ms",
+		"stroke_color",
+		"stroke_width",
+		"position_x",
+		"position_y"
+	], "Caption style");
 }
-//#endregion
-//#region src/editor/id-gen.ts
-/**
-* Part-id generation, aligned with the online ecosystem.
-*
-* The authoritative online producers — agent-harness (`@harness/shared`
-* `genObjId`) and director.v2 (`common/obj_id.py` `gen_obj_id`) — both mint part
-* ids as `` `${prefix}_${ulid()}` ``, and real captured drafts use exactly that
-* shape (`clip_…` / `spe_…` / `cap_…` / `bgm_…`, each a 26-char ULID). The engine
-* previously emitted `vc_<base36 timestamp><6 random>`, a different prefix AND a
-* different encoding — the sole cross-repo id divergence. This module removes it
-* by emitting the same `<prefix>_<ULID>` bytes.
-*
-* The ULID is generated inline (Crockford Base32, 48-bit time + 80-bit random)
-* rather than pulling the `ulid` npm package: the randomness class matches the
-* old generator (both `Math.random`-based) and it keeps `@mengine/medeo-client`
-* dependency-free for a purely mechanical id string. Part ids only need to be
-* unique and lexicographically time-sortable, which this satisfies.
-*/
-/** Crockford Base32 alphabet (no I, L, O, U), per the ULID spec. */
-const CROCKFORD = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
-const TIME_LEN = 10;
-const RANDOM_LEN = 16;
-function encodeTime(now) {
-	let out = "";
-	let ms = now;
-	for (let i = TIME_LEN - 1; i >= 0; i--) {
-		const mod = ms % 32;
-		out = CROCKFORD[mod] + out;
-		ms = (ms - mod) / 32;
-	}
-	return out;
+function requireFinite(value, label) {
+	if (typeof value !== "number" || !Number.isFinite(value)) fail(`${label} must be finite`);
+	return value;
 }
-function encodeRandom() {
-	let out = "";
-	for (let i = 0; i < RANDOM_LEN; i++) out += CROCKFORD[Math.floor(Math.random() * 32)];
-	return out;
+function requireMilliseconds(value, label) {
+	const result = requireFinite(value, label);
+	if (!Number.isSafeInteger(result) || result < 0) fail(`${label} must be non-negative whole milliseconds`);
+	return result;
 }
-/** A 26-char Crockford Base32 ULID (10-char time + 16-char random). */
-function ulid() {
-	return encodeTime(Date.now()) + encodeRandom();
+function requirePositiveMilliseconds(value, label) {
+	const result = requireMilliseconds(value, label);
+	if (result <= 0) fail(`${label} must be positive`);
+	return result;
 }
-function generatePartId(prefix) {
-	return `${prefix}_${ulid()}`;
+function trimmed(value) {
+	return typeof value === "string" && value.trim() !== "" && value.trim() === value;
+}
+function assertKnownFields(value, fields, label) {
+	if (Object.entries(value).some(([key, field]) => field !== void 0 && !fields.includes(key))) fail(`Unknown legacy ${label} fields require an explicit migration adapter`);
+}
+function canonical(value) {
+	if (Array.isArray(value)) return `[${value.map(canonical).join(",")}]`;
+	if (value !== null && typeof value === "object") return `{${Object.entries(value).filter(([, field]) => field !== void 0).sort(([left], [right]) => left.localeCompare(right)).map(([key, field]) => `${JSON.stringify(key)}:${canonical(field)}`).join(",")}}`;
+	return JSON.stringify(value) ?? "undefined";
+}
+function fail(message) {
+	throw new EntityTimelineProjectionError(message);
 }
 //#endregion
-//#region src/editor/schemas/shared.ts
-const clipIdSchema = z.string().min(1).describe("The clip part ID on the timeline");
-const clipIdsSchema = z.array(clipIdSchema).min(1).refine((ids) => new Set(ids).size === ids.length, { message: "Duplicate clip IDs are not allowed" }).describe("List of clip part IDs (no duplicates allowed)");
-const mediaIdSchema = z.string().min(1).describe("The media asset ID");
-const speechIdSchema = z.string().min(1).describe("The speech part ID on the timeline");
-const timelineMsSchema = z.number().int().min(0).describe("Time position in milliseconds on the timeline (>= 0)");
-const positiveMsSchema = z.number().int().positive().describe("Duration in milliseconds (> 0)");
-const volumeSchema = z.number().min(-60).max(20).describe("Volume in decibels (-60.0 to 20.0; 0.0 = original, -60 = mute, +20 = max)");
-const speechIdsSchema = z.array(speechIdSchema).min(1).refine((ids) => new Set(ids).size === ids.length, { message: "Duplicate speech IDs are not allowed" }).describe("List of speech part IDs (no duplicates allowed)");
-const tangentHandleSchema = z.object({
-	x: z.number().finite(),
-	y: z.number().finite()
-}).describe("Bezier tangent handle (x, y)");
-const speedKeyframeSchema = z.object({
-	position: z.number().min(0).max(1),
-	rate: z.number().min(0),
-	in_tangent: tangentHandleSchema.optional(),
-	out_tangent: tangentHandleSchema.optional()
-}).describe("A speed keyframe: normalized position (0..1), rate, optional tangents");
-/**
-* A clip's playback-speed fact, the only thing `SetVideoClipSpeedShift` writes.
-* Mirrors the IDL `SpeedShift`: `category` is `linear` | `curve`, and `config`
-* is a discriminated union — `{ linear: { speed } }` for a constant multiplier
-* (the multiplier projection reads at `config.linear.speed`) or `{ curve: {
-* keyframes } }` for a Bezier-controlled variable speed (RFC 02 / `reference/16`
-* §0). Exactly one of `linear` / `curve` is present.
-*/
-const speedShiftSchema = z.object({
-	category: z.enum(["linear", "curve"]),
-	mode: z.string(),
-	config: z.union([z.object({ linear: z.object({ speed: z.number().finite().positive() }) }), z.object({ curve: z.object({ keyframes: z.array(speedKeyframeSchema).min(2) }) })])
-}).describe("Speed shift: linear multiplier or Bezier curve, mirroring the IDL shape");
-const voiceSchema = z.object({
-	id: z.string().min(1),
-	name: z.string()
-}).describe("TTS voice summary attached to a speech");
-//#endregion
-//#region src/editor/schemas/speech-assets.ts
-/**
-* The materialized TTS result shared by `AddSpeeches` / `ChangeSpeechScript` /
-* `ChangeSpeechVoice` (see `results/phase-4-side-effect-payload-contract.md`
-* §1/§2). The side effect (TTS/ASR + billing) runs upstream; the op receives the
-* stable speech + caption parts and writes them as authoritative facts. No
-* cascade runs on write — the projection derives absolute positions on read.
-*
-* Each speech carries the anchoring fact directly (RFC 02 §4): the host video
-* clip `anchor_part_id` and the `offset_ms` within it. The upstream caller
-* already knows which clip a speech attaches to, so the op writes
-* `{ mode:'anchored', anchorPartId, offsetMs }` verbatim — no write-time
-* host-picking. Captions anchor to their speech via the caption part's
-* `start_ms` (offset within the speech).
-*/
-const speechAssetSchema = z.object({
-	speech_id: speechIdSchema.describe("The speech part ID (= side-effect speech_parts[].id)"),
-	anchor_part_id: clipIdSchema.describe("Host video clip part ID the speech anchors to (RFC 02 §4)"),
-	offset_ms: timelineMsSchema.describe("Offset within the host clip (speech.abs = host.abs + offset_ms)"),
-	audio_storage_key: z.string().min(1),
-	duration_ms: positiveMsSchema,
-	audio_script: z.string(),
-	volume: volumeSchema,
-	voice: voiceSchema,
-	origin_speech_id: z.string().min(1),
-	caption_ids: z.array(z.string().min(1)).describe("Caption part IDs owned by this speech")
-});
-const captionAssetSchema = z.object({
-	caption_id: z.string().min(1).describe("The caption part ID (= side-effect created_caption_parts[].id)"),
-	speech_part_id: speechIdSchema.describe("The owning speech part ID"),
-	text: z.string(),
-	start_ms: timelineMsSchema.describe("Offset within the host speech (caption.abs = speech.abs + start_ms)"),
-	duration_ms: positiveMsSchema
-});
-/** A materialized speech-subtree write (speeches + their captions). */
-const speechAssetsSchema = z.object({
-	speeches: z.array(speechAssetSchema).min(1).describe("Materialized speech parts to write"),
-	captions: z.array(captionAssetSchema).describe("Materialized caption parts owned by the speeches")
-});
-//#endregion
-//#region src/editor/schemas/add-speeches.ts
-/**
-* Add speeches (and their captions). TTS runs upstream; the stable speech /
-* caption parts arrive materialized (see `speech-assets.ts`). The op writes the
-* parts and each speech's `{ mode:'anchored', anchorPartId, offsetMs }` fact
-* verbatim — no write-time host-picking, no cascade (RFC 02 §4). The projection
-* derives absolute positions on read.
-*/
-const addSpeechesInputSchema = speechAssetsSchema.describe("Materialized speeches + captions to add");
+//#region src/entity-editor/caption-content.ts
+/** Author Caption content from semantic intent; callers never reconcile variant bases or assembled fields. */
+function prepareCaptionContent(rows, input) {
+	const entityId = createEntityId(input.contentEntityId);
+	const scriptId = createEntityId(input.audioScriptEntityId);
+	if (!Number.isFinite(input.durationMs) || input.durationMs <= 0) throw new Error("Caption duration must be positive");
+	const previous = rows.entities.find((row) => row.entityId === entityId);
+	if (previous !== void 0 && previous.entityKind !== "caption") throw new Error("Caption content identity has a different kind");
+	let baseEntityIds = [scriptId];
+	if (previous !== void 0) {
+		const source = assembleCaptionContent(rows, entityId).audioScript.entityId;
+		const bases = variantBaseEntityIds(previous);
+		if (source !== scriptId && !bases.includes(source)) throw new Error("Replacing an indirectly composed AudioScript requires an explicit composition change");
+		baseEntityIds = bases.map((id) => id === source ? scriptId : id);
+	}
+	const candidate = {
+		entityId,
+		entityKind: "caption",
+		payload: {
+			...previous?.payload,
+			baseEntityIds,
+			durationMs: previous?.payload.durationMs ?? input.durationMs
+		}
+	};
+	const graph = {
+		...rows,
+		entities: [...rows.entities.filter((row) => row.entityId !== entityId), candidate]
+	};
+	const textSource = {
+		...assembleEntityContent(graph, entityId),
+		entityKind: "audio-script"
+	};
+	const selected = {
+		...candidate,
+		payload: {
+			...candidate.payload,
+			selection: structuredClone(input.selection ?? selectCaptionText(textSource, input.text))
+		}
+	};
+	if (assembleCaptionContent({
+		...graph,
+		entities: graph.entities.map((row) => row.entityId === entityId ? selected : row)
+	}, entityId).text !== input.text) throw new Error("Caption review text differs from its assembled variant content");
+	return selected;
+}
+function selectCaptionText(script, text) {
+	if (!text.trim()) throw new Error("Caption text selection must not be blank");
+	const segments = script.payload.segments;
+	const matches = [];
+	for (const segment of segments) {
+		let offset = segment.text.indexOf(text);
+		while (offset !== -1) {
+			const start = Array.from(segment.text.slice(0, offset)).length;
+			matches.push({
+				segmentId: segment.segmentId,
+				textRange: {
+					start,
+					end: start + Array.from(text).length
+				}
+			});
+			offset = segment.text.indexOf(text, offset + 1);
+		}
+	}
+	if (matches.length !== 1) throw new Error("Caption text must select a unique AudioScript range; provide explicit selection");
+	return matches[0];
+}
 //#endregion
-//#region src/editor/schemas/add-video-clips.ts
-/**
-* Add video clips to a track. Each clip's duration facts are separated so a
-* single number is never overloaded (RFC 02 / `reference/16` §0b):
-*
-* - `media_duration_ms` is the source media's intrinsic full length (a resource
-*   fact, written to the part);
-* - `play_in` / `play_out` are the optional trim window into that media; when
-*   omitted the whole media is used (`play_in=0`, `play_out=media_duration_ms`).
-*
-* The clip's effective timeline duration is derived by the projection from the
-* trim window and `speed_shift` — it is never an input here.
-*/
-const addVideoClipsInputSchema = z.object({
-	clips: z.array(z.object({
-		media_id: mediaIdSchema.describe("The media asset ID for the video clip"),
-		start_ms: timelineMsSchema.optional().describe("Absolute start time in milliseconds on the timeline"),
-		media_duration_ms: positiveMsSchema.describe("The source media's intrinsic full length in ms"),
-		play_in: timelineMsSchema.optional().describe("Trim window start in the media (default 0)"),
-		play_out: positiveMsSchema.optional().describe("Trim window end in the media (default media_duration_ms)"),
-		track_id: z.string().min(1).optional().describe("Target track ID (optional, defaults to main track)")
-	})).min(1).describe("List of video clips to create"),
-	before_clip_id: z.string().min(1).optional().describe("Insert new clips before this clip ID"),
-	after_clip_id: z.string().min(1).optional().describe("Insert new clips after this clip ID")
-}).superRefine((data, ctx) => {
-	if (data.before_clip_id != null && data.after_clip_id != null) {
-		ctx.addIssue({
-			code: z.ZodIssueCode.custom,
-			message: "Cannot provide both before_clip_id and after_clip_id"
-		});
-		return;
+//#region src/entity-crdt/legacy-schema-migration.ts
+const LEGACY_KINDS = new Set([
+	"timeline-track",
+	"track-clip",
+	"clip-marker",
+	"marker-content",
+	"audio-script-marker",
+	"audio-script-source",
+	"generated"
+]);
+function whole(value, label) {
+	if (!Number.isSafeInteger(value) || value < 0) throw new Error(`Legacy SequenceMarker ${label} is invalid`);
+	return value;
+}
+function legacyMarkerPayload(payload, annotation) {
+	if (payload.inMs !== void 0 || payload.outMs !== void 0) return void 0;
+	const keys = canonicalJson(Object.keys(payload).sort());
+	if (!(annotation ? [[
+		"duration",
+		"segmentRanges",
+		"sourceRange"
+	]] : [
+		["duration", "sourceRange"],
+		[
+			"anchorOffset",
+			"duration",
+			"sourceRange"
+		],
+		[
+			"duration",
+			"sourceRange",
+			"targetRange"
+		],
+		[
+			"duration",
+			"sourceRange",
+			"timeRemapping"
+		]
+	]).some((shape) => keys === canonicalJson(shape))) throw new Error("Legacy SequenceMarker has unsupported fields");
+	if (!isJsonObject(payload.sourceRange) || !isJsonObject(payload.duration)) throw new Error("Legacy SequenceMarker ranges are invalid");
+	const inMs = whole(payload.sourceRange.start, "sourceRange.start");
+	const outMs = whole(payload.sourceRange.end, "sourceRange.end");
+	const duration = whole(payload.duration.value, "duration.value");
+	if (payload.duration.mode !== "fixed" || duration === 0 || outMs <= inMs) throw new Error("Legacy SequenceMarker duration is invalid");
+	const rate = (outMs - inMs) / duration;
+	if (!Number.isFinite(rate) || rate <= 0) throw new Error("Legacy SequenceMarker rate is invalid");
+	if (annotation) {
+		if (rate !== 1 || !Array.isArray(payload.segmentRanges)) throw new Error("Legacy AudioScript annotation Marker is invalid");
+		return {
+			inMs,
+			outMs,
+			segmentRanges: payload.segmentRanges
+		};
 	}
-	const hasRelative = data.before_clip_id != null || data.after_clip_id != null;
-	for (let i = 0; i < data.clips.length; i++) {
-		const clip = data.clips[i];
-		if (hasRelative && clip.start_ms != null) ctx.addIssue({
-			code: z.ZodIssueCode.custom,
-			message: `clips[${i}].start_ms must not be provided when using before_clip_id or after_clip_id`,
-			path: [
-				"clips",
-				i,
-				"start_ms"
-			]
-		});
-		if (!hasRelative && clip.start_ms == null) ctx.addIssue({
-			code: z.ZodIssueCode.custom,
-			message: `clips[${i}].start_ms is required when not using relative positioning`,
-			path: [
-				"clips",
-				i,
-				"start_ms"
-			]
-		});
-		const playIn = clip.play_in ?? 0;
-		const playOut = clip.play_out ?? clip.media_duration_ms;
-		if (playOut > clip.media_duration_ms) ctx.addIssue({
-			code: z.ZodIssueCode.custom,
-			message: `clips[${i}].play_out ${playOut}ms exceeds media_duration_ms ${clip.media_duration_ms}ms`,
-			path: [
-				"clips",
-				i,
-				"play_out"
-			]
-		});
-		if (playIn >= playOut) ctx.addIssue({
-			code: z.ZodIssueCode.custom,
-			message: `clips[${i}].play_in ${playIn}ms must be less than play_out ${playOut}ms`,
-			path: [
-				"clips",
-				i,
-				"play_in"
-			]
-		});
+	let startMs = 0;
+	if (payload.anchorOffset !== void 0) startMs = whole(payload.anchorOffset, "anchorOffset");
+	if (payload.targetRange !== void 0) {
+		if (!isJsonObject(payload.targetRange)) throw new Error("Legacy SequenceMarker targetRange is invalid");
+		startMs = whole(payload.targetRange.start, "targetRange.start");
+		const targetEnd = whole(payload.targetRange.end, "targetRange.end");
+		if (targetEnd <= startMs || targetEnd - startMs !== duration) throw new Error("Legacy SequenceMarker targetRange disagrees with duration");
+	}
+	if (payload.timeRemapping !== void 0) {
+		const remapping = payload.timeRemapping;
+		if (!isJsonObject(remapping) || canonicalJson(Object.keys(remapping).sort()) !== canonicalJson([
+			"kind",
+			"mode",
+			"rate"
+		]) || remapping.kind !== "linear" || remapping.mode !== "constant" || typeof remapping.rate !== "number" || !Number.isFinite(remapping.rate) || remapping.rate <= 0) throw new Error("Legacy SequenceMarker timeRemapping is invalid");
+		if (remapping.rate !== rate) throw new Error("Legacy SequenceMarker timeRemapping disagrees with duration");
 	}
-});
-//#endregion
-//#region src/editor/schemas/adjust-bgm-volume.ts
-const adjustBgmVolumeInputSchema = z.object({ bgm: z.array(z.object({
-	bgm_id: clipIdSchema.describe("The bgm part ID to adjust volume for"),
-	volume: volumeSchema.describe("Volume in decibels (-60.0 to 20.0; 0.0 = original)")
-})).min(1).describe("List of bgm parts with their new volume settings") });
-//#endregion
-//#region src/editor/schemas/adjust-speech-volume.ts
-const adjustSpeechVolumeInputSchema = z.object({ speeches: z.array(z.object({
-	speech_id: speechIdSchema.describe("The speech part ID to adjust volume for"),
-	volume: volumeSchema.describe("Volume in decibels (-60.0 to 20.0; 0.0 = original)")
-})).min(1).describe("List of speeches with their new volume settings") });
-//#endregion
-//#region src/editor/schemas/adjust-video-clip-duration.ts
-/**
-* Re-trim existing video clips (the user-facing "adjust duration" gesture is a
-* trim of the source window). The new `play_in` / `play_out` are the facts; the
-* effective timeline duration is derived from them and the clip's `speed_shift`,
-* and the change reflows downstream clips, speeches, and the timeline inside the
-* op's transaction (no caller-materialized cascade).
-*/
-const adjustVideoClipDurationInputSchema = z.object({ clips: z.array(z.object({
-	clip_id: clipIdSchema.describe("The video clip part ID to re-trim"),
-	play_in: timelineMsSchema.describe("New trim window start in the source media"),
-	play_out: positiveMsSchema.describe("New trim window end in the source media")
-})).min(1).describe("Video clips with their new trim windows") });
-//#endregion
-//#region src/editor/schemas/adjust-video-clip-volume.ts
-const adjustVideoClipVolumeInputSchema = z.object({ clips: z.array(z.object({
-	clip_id: clipIdSchema.describe("The video clip part ID to adjust volume for"),
-	volume: volumeSchema.describe("Volume in decibels (-60.0 to 20.0; 0.0 = original)")
-})).min(1).describe("List of video clips with their new volume settings") });
-//#endregion
-//#region src/editor/schemas/change-speech.ts
-/**
-* Change a speech's script or voice. Both re-run TTS upstream and return the
-* regenerated speech / caption parts in the same materialized shape as
-* `AddSpeeches` (`speech-assets.ts`); the op upserts them by id (the speech part
-* id is preserved across a re-TTS), re-seats at `start_ms`, and reflows. Old
-* caption parts no longer owned by the speech are removed via `caption_ids`.
-*/
-const changeSpeechScriptInputSchema = speechAssetsSchema.describe("Regenerated speeches + captions (new script)");
-const changeSpeechVoiceInputSchema = speechAssetsSchema.describe("Regenerated speeches + captions (new voice)");
-//#endregion
-//#region src/editor/schemas/delete-bgm.ts
-/**
-* Remove the document BGM. Pure document edit: clears the bgm lane and removes
-* the bgm part. Takes no input (a document holds at most one bgm); an empty
-* object keeps the op signature uniform with the rest.
-*/
-const deleteBgmInputSchema = z.object({}).describe("Remove the document BGM (no parameters)");
-//#endregion
-//#region src/editor/schemas/delete-speeches.ts
-/**
-* Delete speeches with their captions. Pure document edit (no side effect): the
-* op removes each speech part, cascade-deletes the captions it owns (via
-* `caption_ids` / `speech_part_id`), drops their track items, and reflows.
-*/
-const deleteSpeechesInputSchema = z.object({ speech_ids: speechIdsSchema.describe("Speech part IDs to delete (their captions cascade-delete)") });
-//#endregion
-//#region src/editor/schemas/delete-video-clips.ts
-/**
-* How a delete handles the anchored subtree (speeches anchored to a deleted clip,
-* and their captions) — a delete-op policy, not a data-model field (reference/17
-* §6). `cascade` (default) removes the subtree; `detach` keeps the direct
-* anchored children, re-pinning them to `absolute` so they stay on the timeline.
-*/
-const anchoredDeletePolicySchema = z.enum(["cascade", "detach"]);
-const deleteVideoClipsInputSchema = z.object({
-	clip_ids: clipIdsSchema.describe("List of video clip part IDs to delete from the main track"),
-	on_anchored: anchoredDeletePolicySchema.optional().describe("How to treat anchored children (default cascade)")
-});
-//#endregion
-//#region src/editor/schemas/move-speeches.ts
-/**
-* Move speeches in time. Pure document edit: the op re-seats each speech at its
-* new absolute `start_ms`; the cascade reassigns it to the host video clip,
-* resolves overlaps, and reflows. Captions follow their speech.
-*/
-const moveSpeechesInputSchema = z.object({ speeches: z.array(z.object({
-	speech_id: speechIdSchema.describe("The speech part ID to move"),
-	new_start_ms: timelineMsSchema.describe("New absolute start time on the timeline")
-})).min(1).describe("Speeches to move to new positions") });
-//#endregion
-//#region src/editor/schemas/move-video-clips-by-anchor.ts
-/**
-* Where the moved block lands on the main track.
-*
-* A discriminated union rather than two optional `before_clip_id` /
-* `after_clip_id` fields (the shape `addVideoClips` had to use, because there the
-* two modes share a whole clip description): here the alternatives carry nothing
-* in common, so making them mutually exclusive *by type* removes three runtime
-* `superRefine` checks that would otherwise have to be written and tested.
-*
-* `track_start` is an explicit member, not the absence of an anchor. The
-* agent-harness mutation this maps from treats "neither anchor given" as
-* "move to the front" (`applyBatchMoveVideoClips` falls back to `insertIndex = 0`),
-* which is a default buried in a tool description. Requiring the caller to name
-* that intent keeps a forgotten field from silently reordering the timeline.
-*/
-const moveAnchorSchema = z.discriminatedUnion("position", [
-	z.object({
-		position: z.literal("before"),
-		clip_id: clipIdSchema.describe("The moved block lands immediately before this clip")
-	}),
-	z.object({
-		position: z.literal("after"),
-		clip_id: clipIdSchema.describe("The moved block lands immediately after this clip")
-	}),
-	z.object({ position: z.literal("track_start") })
-]).describe("Where the moved block lands: before/after a reference clip, or at the head of the track");
-/**
-* What happens to the speeches anchored to the clips being moved.
-*
-* - `follow` keeps each speech anchored where it is, so it travels with its clip
-*   to the new position. In the anchored model this is the *no-op* branch: a
-*   speech's authoritative fact is `{ anchorPartId, offsetMs }` and its absolute
-*   time is derived on read from the host's position, so moving the host moves
-*   the speech with no write to the speech at all.
-* - `keep_absolute` preserves each speech's current absolute landing instead, then
-*   re-anchors it to whichever clip now covers that time (RFC 02 §9.1/§11.1). This
-*   is the branch that costs an extra pass, and the one the FE timeline uses.
-*
-* **Required, with no default**, matching `deleteVideoClips` and
-* `replaceVideoClipSequence`. The two branches decide which picture the user's
-* narration ends up over, which is too consequential to infer from a missing
-* field — and neither branch is "safe enough" to be the implicit one.
-*/
-const movedClipAnchoredPolicySchema = z.enum(["follow", "keep_absolute"]);
-/**
-* Reorder a set of main-track clips relative to a reference clip.
-*
-* Distinct from `moveVideoClips`, which positions clips by absolute time
-* (`new_start_ms`) and is what the FE timeline dispatches after a drag. Main-track
-* clips are `sequential`-positioned, so absolute time is not authoritative state
-* there (RFC 02 §4/§7): `moveVideoClips` has to *guess* an index back out of the
-* time it was handed, whereas an anchor already is the ordinal fact being changed.
-* Keeping them separate also isolates blast radius — this method can diverge on
-* speech policy without touching the FE path.
-*
-* `clip_ids` need not be contiguous. They move as one block, keeping their
-* relative order, which is the agent-harness `batch_move_video_clips` contract.
-*/
-const moveVideoClipsByAnchorInputSchema = z.object({
-	clip_ids: clipIdsSchema.describe("Clips to move as one block, keeping their relative order. Need not be contiguous on the track."),
-	anchor: moveAnchorSchema,
-	on_anchored: movedClipAnchoredPolicySchema.describe("What happens to speeches anchored to the moved clips (required — see the policy doc)")
-});
-//#endregion
-//#region src/editor/schemas/move-video-clips.ts
-const moveVideoClipsInputSchema = z.object({ clips: z.array(z.object({
-	clip_id: clipIdSchema.describe("The video clip part ID to move"),
-	new_start_ms: timelineMsSchema.describe("New absolute start time in milliseconds on the timeline"),
-	new_track_id: z.string().min(1).optional().describe("Target track ID to move the clip to (optional)")
-})).min(1).describe("List of video clips to move to new positions") });
-//#endregion
-//#region src/editor/schemas/replace-video-clip-content.ts
-/**
-* Replace the media backing existing video clips. The media import runs upstream
-* (Director); its stable result — the new media id, intrinsic length, and the
-* reset trim window — arrives materialized (see
-* `results/phase-4-side-effect-payload-contract.md` §4). Director resets
-* `play_in=0` / `play_out=media_duration_ms` and clears `speed_shift` on
-* replacement. The clip `part_id`s (hence their track items) are unchanged; the
-* editor reflows the main track from the new effective durations.
-*/
-const replaceVideoClipContentInputSchema = z.object({ clips: z.array(z.object({
-	clip_id: clipIdSchema.describe("Existing video clip part ID to re-point"),
-	origin_media_id: mediaIdSchema.describe("The new media asset ID"),
-	media_duration_ms: positiveMsSchema.describe("The new media's intrinsic full length"),
-	play_in: timelineMsSchema.describe("Trim window start in the new media (usually 0)"),
-	play_out: positiveMsSchema.describe("Trim window end in the new media (usually = media_duration_ms)"),
-	volume: volumeSchema
-})).min(1).describe("Video clips whose media is being replaced") });
-//#endregion
-//#region src/editor/schemas/replace-video-clip-sequence.ts
-/**
-* What happens to the speeches anchored to the clips being replaced.
-*
-* - `remap` re-anchors each surviving speech to the new clip in the SAME POSITION
-*   of the sequence, keeping its offset — old[i]'s children become new[i]'s
-*   children. An old clip with no counterpart (fewer new clips than old) has its
-*   subtree deleted, because there is nothing left to anchor to.
-* - `cascade` deletes every anchored speech (and its captions) outright, like
-*   `deleteVideoClips`.
-*
-* **Required, with no default.** The two branches differ in whether the user's
-* narration survives, and the agent tool that drives this op makes its
-* `preserve_speeches` flag required for that reason. A default here would let a
-* caller that forgot the field silently delete speech.
-*/
-const anchoredReplacePolicySchema = z.enum(["remap", "cascade"]);
-/**
-* Replace a contiguous run of main-track clips with a new run.
-*
-* A composite of delete + insert that cannot be expressed as the two ops in
-* sequence, because the anchored speeches have to survive *across* the swap: with
-* `remap` they are re-anchored positionally, which needs both the old and the new
-* ids in the same transaction (ADR 0009 — the cascade stays in the editor, callers
-* never re-wire anchors themselves).
-*
-* Duration facts follow `addVideoClips`: `media_duration_ms` is the source's
-* intrinsic length and the trim window defaults to the whole media. The effective
-* timeline duration is derived by the projection, never an input.
-*
-* `media_id` is optional: omitting it creates a **deliberate empty placeholder
-* clip** (`origin_media_id: ''`) — structure with no picture. This is the only op
-* that can produce one, and it is authoritative state, unlike the gap fillers the
-* read-side solve mints (which never enter the document).
-*/
-const replaceVideoClipSequenceInputSchema = z.object({
-	old_clip_ids: clipIdsSchema.describe("The clips being replaced: a contiguous main-track run, listed in timeline order"),
-	new_clips: z.array(z.object({
-		media_id: mediaIdSchema.optional().describe("The replacement media asset ID. Omit to create an empty placeholder clip."),
-		media_duration_ms: positiveMsSchema.describe("The source media's intrinsic full length in ms"),
-		play_in: timelineMsSchema.optional().describe("Trim window start in the media (default 0)"),
-		play_out: positiveMsSchema.optional().describe("Trim window end in the media (default media_duration_ms)")
-	})).min(1).describe("The replacement clips, in the order they take on the track"),
-	on_anchored: anchoredReplacePolicySchema.describe("What happens to speeches anchored to the replaced clips (required — see the policy doc)")
-}).superRefine((data, ctx) => {
-	for (let i = 0; i < data.new_clips.length; i++) {
-		const clip = data.new_clips[i];
-		const playIn = clip.play_in ?? 0;
-		const playOut = clip.play_out ?? clip.media_duration_ms;
-		if (playOut > clip.media_duration_ms) ctx.addIssue({
-			code: z.ZodIssueCode.custom,
-			message: `new_clips[${i}].play_out ${playOut}ms exceeds media_duration_ms ${clip.media_duration_ms}ms`,
-			path: [
-				"new_clips",
-				i,
-				"play_out"
-			]
-		});
-		if (playIn >= playOut) ctx.addIssue({
-			code: z.ZodIssueCode.custom,
-			message: `new_clips[${i}].play_in ${playIn}ms must be less than play_out ${playOut}ms`,
-			path: [
-				"new_clips",
-				i,
-				"play_in"
-			]
-		});
+	return {
+		inMs,
+		outMs,
+		startMs,
+		...rate === 1 ? {} : { rate }
+	};
+}
+function relationId(root, kind) {
+	return createRelationId(`relation_${bytesToHex(sha256(new TextEncoder().encode(canonicalJson([root, kind]))))}`);
+}
+function entityRoot(doc, id) {
+	const origins = doc.getMap("medeo").get("origins");
+	if (!(origins instanceof LoroMap)) throw new Error("Missing Loro entity origins");
+	const origin = origins.get(id);
+	return typeof origin === "string" ? origin : id;
+}
+function mappedRow(doc, row, records) {
+	const endpoint0 = entityRoot(doc, row.endpoint0EntityId);
+	const endpoint1 = entityRoot(doc, row.endpoint1EntityId);
+	let kind;
+	let endpoints;
+	if (row.relationKind === "timeline-track" || row.relationKind === "track-clip") {
+		kind = "contain";
+		endpoints = [endpoint0, endpoint1];
+	} else if (row.relationKind === "clip-marker" || row.relationKind === "audio-script-marker") {
+		kind = "marker";
+		endpoints = [endpoint0, endpoint1];
+	} else if (row.relationKind === "audio-script-source" || row.relationKind === "generated") {
+		kind = "derived-from";
+		endpoints = [endpoint0, endpoint1];
+	} else {
+		const owners = records.filter((candidate) => !candidate.deleted && candidate.relationKind === "clip-marker" && entityRoot(doc, candidate.endpoint1EntityId) === endpoint0);
+		if (owners.length !== 1) throw new Error(`Legacy marker-content ${row.relationId} requires exactly one clip-marker owner`);
+		endpoints = [entityRoot(doc, owners[0].endpoint0EntityId), endpoint1];
+		kind = "contain";
 	}
-});
-//#endregion
-//#region src/editor/schemas/set-bgm.ts
-/**
-* Set the document BGM. The media's stable result (storage key) arrives
-* materialized from upstream (see
-* `results/phase-4-side-effect-payload-contract.md` §3). The op upserts the bgm
-* part and seats it on the bgm lane; its effective length is always the whole
-* timeline, derived by the projection on read — so there is no `duration_ms`
-* input or fact (RFC 02 / `reference/16` §0b). A `bgm_id` lets the op replace an
-* existing bgm part by id.
-*/
-const setBgmInputSchema = z.object({
-	bgm_id: z.string().min(1).describe("The bgm part ID to write"),
-	audio_storage_key: z.string().min(1),
-	origin_media_id: mediaIdSchema,
-	volume: volumeSchema
-});
-//#endregion
-//#region src/editor/schemas/set-caption-style.ts
-/**
-* Set the caption visual style. GLOBAL by design: the style applies to every
-* caption part in the document — it carries NO `caption_id`. This mirrors the FE,
-* whose caption-style store (`caption-style.ts:persistCaptionStylePatch`) iterates
-* ALL captions and writes the same normalized style to each; the product has a
-* single document-wide caption style, not per-caption styling.
-*
-* Every field is optional and maps to a `CaptionStyle` attribute (snake_case
-* IDL). A field present in the input is written to every caption; a field ABSENT
-* from the input is left untouched on each caption (the editor merges the patch
-* onto each caption's existing style — this is a value edit, not a full-style
-* replace, so a partial patch such as "recolor only" does not wipe font size).
-*
-* Pure document edit, no cascade — captions keep their positions; only the style
-* sub-map of each caption part changes.
-*/
-const setCaptionStyleInputSchema = z.object({
-	font_id: z.string().min(1).optional().describe("Font ID referencing a font from the font library"),
-	font_size: z.number().positive().optional().describe("Font size in points"),
-	font_color: z.string().min(1).optional().describe("Font color as hex string, e.g. \"#FFFFFF\""),
-	font_weight: z.number().int().optional().describe("Numeric font weight, e.g. 400 or 700"),
-	entrance_animation: z.string().optional().describe("Entrance animation preset ID, e.g. \"fade\" or \"none\""),
-	entrance_animation_duration_ms: z.number().min(0).optional().describe("Entrance animation duration in ms"),
-	stroke_color: z.string().min(1).optional().describe("Outline/stroke color as hex string, e.g. \"#000000\""),
-	stroke_width: z.number().min(0).optional().describe("Outline/stroke width in pixels"),
-	position_x: z.number().optional().describe("Caption center X as a fraction (0.0 to 1.0)"),
-	position_y: z.number().optional().describe("Caption center Y as a fraction (0.0 to 1.0)")
-}).describe("Document-wide caption style patch (no caption_id; applies to every caption)");
-//#endregion
-//#region src/editor/schemas/set-caption-visibility.ts
-/**
-* Toggle caption visibility (the caption track's `is_hidden` flag). Pure
-* document edit, no cascade — captions keep their positions; only the lane's
-* hidden flag changes.
-*/
-const setCaptionVisibilityInputSchema = z.object({ is_hidden: z.boolean().describe("Whether the caption track is hidden") });
-//#endregion
-//#region src/editor/schemas/set-video-clip-speed-shift.ts
-/**
-* Set the playback speed of existing video clips. Per the speed-shift decision
-* (`reference/16` §0): the op writes only the `speed_shift` fact — it does NOT
-* store an effective `duration_ms` (projection derives it from the trim window /
-* speed) and does NOT scale anchored speeches' relative offsets (offsets stay
-* put; the cascade reflows absolute positions). A `null` speed_shift clears the
-* speed back to original (1×).
-*/
-const setVideoClipSpeedShiftInputSchema = z.object({ clips: z.array(z.object({
-	clip_id: clipIdSchema.describe("The video clip part ID to set speed for"),
-	speed_shift: speedShiftSchema.nullable().describe("The new speed setting, or null to reset to 1×")
-})).min(1).describe("Video clips with their new speed settings") });
-//#endregion
-//#region src/editor/schemas/index.ts
-var schemas_exports = /* @__PURE__ */ __exportAll({
-	addSpeechesInputSchema: () => addSpeechesInputSchema,
-	addVideoClipsInputSchema: () => addVideoClipsInputSchema,
-	adjustBgmVolumeInputSchema: () => adjustBgmVolumeInputSchema,
-	adjustSpeechVolumeInputSchema: () => adjustSpeechVolumeInputSchema,
-	adjustVideoClipDurationInputSchema: () => adjustVideoClipDurationInputSchema,
-	adjustVideoClipVolumeInputSchema: () => adjustVideoClipVolumeInputSchema,
-	anchoredDeletePolicySchema: () => anchoredDeletePolicySchema,
-	anchoredReplacePolicySchema: () => anchoredReplacePolicySchema,
-	changeSpeechScriptInputSchema: () => changeSpeechScriptInputSchema,
-	changeSpeechVoiceInputSchema: () => changeSpeechVoiceInputSchema,
-	clipIdSchema: () => clipIdSchema,
-	clipIdsSchema: () => clipIdsSchema,
-	deleteBgmInputSchema: () => deleteBgmInputSchema,
-	deleteSpeechesInputSchema: () => deleteSpeechesInputSchema,
-	deleteVideoClipsInputSchema: () => deleteVideoClipsInputSchema,
-	mediaIdSchema: () => mediaIdSchema,
-	moveAnchorSchema: () => moveAnchorSchema,
-	moveSpeechesInputSchema: () => moveSpeechesInputSchema,
-	moveVideoClipsByAnchorInputSchema: () => moveVideoClipsByAnchorInputSchema,
-	moveVideoClipsInputSchema: () => moveVideoClipsInputSchema,
-	movedClipAnchoredPolicySchema: () => movedClipAnchoredPolicySchema,
-	positiveMsSchema: () => positiveMsSchema,
-	replaceVideoClipContentInputSchema: () => replaceVideoClipContentInputSchema,
-	replaceVideoClipSequenceInputSchema: () => replaceVideoClipSequenceInputSchema,
-	setBgmInputSchema: () => setBgmInputSchema,
-	setCaptionStyleInputSchema: () => setCaptionStyleInputSchema,
-	setCaptionVisibilityInputSchema: () => setCaptionVisibilityInputSchema,
-	setVideoClipSpeedShiftInputSchema: () => setVideoClipSpeedShiftInputSchema,
-	speechAssetsSchema: () => speechAssetsSchema,
-	speechIdSchema: () => speechIdSchema,
-	speechIdsSchema: () => speechIdsSchema,
-	speedShiftSchema: () => speedShiftSchema,
-	timelineMsSchema: () => timelineMsSchema,
-	voiceSchema: () => voiceSchema,
-	volumeSchema: () => volumeSchema
-});
+	return {
+		relationId: relationId(row.relationId, kind),
+		relationKind: kind,
+		endpoint0EntityId: createEntityId(endpoints[0]),
+		endpoint1EntityId: createEntityId(endpoints[1]),
+		metadata: row.metadata,
+		trace: row.trace
+	};
+}
+/** Replace only the four positionally equivalent alpha23 relation kinds. */
+function migrateAlpha23EntityDocument(doc) {
+	if (doc.getMap("medeo").get("schema") !== "medeo.entities.loro.v1") return void 0;
+	const records = readEntityRelationRecords(doc);
+	const legacy = records.filter((row) => !row.deleted && LEGACY_KINDS.has(row.relationKind));
+	if (legacy.length === 0) return void 0;
+	const replacements = legacy.map((row) => mappedRow(doc, row, records));
+	const current = readEntityDocument(doc, true).rows;
+	const markerPayloads = /* @__PURE__ */ new Map();
+	for (const relation of current.relations) {
+		if (relation.relationKind !== "clip-marker" && relation.relationKind !== "audio-script-marker") continue;
+		const marker = current.entities.find((row) => row.entityId === relation.endpoint1EntityId);
+		if (marker?.entityKind !== "sequence-marker") throw new Error(`Legacy ${relation.relationKind} ${relation.relationId} has no SequenceMarker`);
+		const payload = legacyMarkerPayload(marker.payload, relation.relationKind === "audio-script-marker");
+		if (payload !== void 0) markerPayloads.set(marker.entityId, payload);
+	}
+	const occupied = new Set(records.map((row) => String(row.relationId)));
+	for (const row of replacements) if (occupied.has(row.relationId)) throw new Error(`Legacy relation migration ID collision: ${row.relationId}`);
+	return new LoroEntityDocument(doc).transact((draft) => {
+		for (const [markerId, payload] of markerPayloads) draft.replaceOwned(markerId, payload);
+		for (const row of legacy) draft.unlink(row.relationId);
+		for (const row of replacements) draft.link(row);
+	});
+}
 //#endregion
 //#region src/editor/snapshot-utils.ts
 function isMap(value) {
@@ -1121,9 +3533,11 @@ function readPartLibrary(draft) {
 var SemanticEditor = class {
 	doc;
 	validator;
-	constructor(doc, validator = new SchemaValidator()) {
+	idFactory;
+	constructor(doc, validator = new SchemaValidator(), idFactory = generatePartId) {
 		this.doc = doc;
 		this.validator = validator;
+		this.idFactory = idFactory;
 	}
 	async moveVideoClips(input, options) {
 		this.validator.validateMoveVideoClips(input, this.doc);
@@ -1203,7 +3617,7 @@ var SemanticEditor = class {
 			track.items ??= [];
 			let at = insertIndex;
 			for (const clip of input.clips) {
-				const partId = generatePartId("clip");
+				const partId = this.idFactory("clip");
 				setPart(draft, partId, { video_clip: {
 					id: partId,
 					kind: "video_clip",
@@ -1250,7 +3664,7 @@ var SemanticEditor = class {
 			const newItems = [];
 			const newClipIds = [];
 			for (const clip of input.new_clips) {
-				const partId = generatePartId("clip");
+				const partId = this.idFactory("clip");
 				setPart(draft, partId, { video_clip: {
 					id: partId,
 					kind: "video_clip",
@@ -1870,6 +4284,111 @@ function deleteAnchoredSubtree(draft, clipId) {
 	for (const speechId of anchored) deleteSpeechSubtree(draft, speechId);
 }
 //#endregion
+//#region src/editor/journal.ts
+/**
+* Wire a plain-memory adapter + editor that share a recording id factory, so
+* every mutating transact lands in `journal` with ordered `generated_ids`.
+*/
+function createEditSandbox(document, options) {
+	const adapter = createPlainMemoryAdapter(document, options);
+	return {
+		adapter,
+		editor: new SemanticEditor(adapter, new SchemaValidator(), adapter.idFactory),
+		journal: adapter.journal
+	};
+}
+/**
+* Re-drive `doc` from a recorded journal, forcing each entry's `generated_ids`
+* through a queue-backed id factory. Never mints fresh ids: an empty queue on
+* demand throws `unrecorded id`; leftover ids after an entry throws
+* `unconsumed ids`. Legacy entries without `generated_ids` are treated as `[]`.
+*/
+async function replayJournal(doc, journal) {
+	const queue = [];
+	const idFactory = (_prefix) => {
+		const id = queue.shift();
+		if (id == null) throw new Error("unrecorded id");
+		return id;
+	};
+	const editor = new SemanticEditor(doc, new SchemaValidator(), idFactory);
+	for (const entry of journal) {
+		queue.push(...entry.generated_ids ?? []);
+		await dispatchEntry(editor, entry);
+		if (queue.length > 0) throw new Error("unconsumed ids");
+	}
+}
+/** Dispatch one journal entry to the matching editor method; payload is passed through. */
+async function dispatchEntry(editor, entry) {
+	const payload = entry.payload;
+	const options = entry.intent != null ? { intent: entry.intent } : void 0;
+	switch (entry.kind) {
+		case "MoveVideoClips":
+			await editor.moveVideoClips(payload, options);
+			return;
+		case "MoveVideoClipsByAnchor":
+			await editor.moveVideoClipsByAnchor(payload, options);
+			return;
+		case "DeleteVideoClips":
+			await editor.deleteVideoClips(payload, options);
+			return;
+		case "AddVideoClips":
+			await editor.addVideoClips(payload, options);
+			return;
+		case "AdjustVideoClipVolume":
+			await editor.adjustVideoClipVolume(payload, options);
+			return;
+		case "SetVideoClipSpeedShift":
+			await editor.setVideoClipSpeedShift(payload, options);
+			return;
+		case "ReplaceVideoClipContent":
+			await editor.replaceVideoClipContent(payload, options);
+			return;
+		case "ReplaceVideoClipSequence":
+			await editor.replaceVideoClipSequence(payload, options);
+			return;
+		case "AdjustVideoClipDuration":
+			await editor.adjustVideoClipDuration(payload, options);
+			return;
+		case "AddSpeeches":
+			await editor.addSpeeches(payload, options);
+			return;
+		case "DeleteSpeeches":
+			await editor.deleteSpeeches(payload, options);
+			return;
+		case "MoveSpeeches":
+			await editor.moveSpeeches(payload, options);
+			return;
+		case "ChangeSpeechScript":
+			await editor.changeSpeechScript(payload, options);
+			return;
+		case "ChangeSpeechVoice":
+			await editor.changeSpeechVoice(payload, options);
+			return;
+		case "AdjustSpeechVolume":
+			await editor.adjustSpeechVolume(payload, options);
+			return;
+		case "SetCaptionVisibility":
+			await editor.setCaptionVisibility(payload, options);
+			return;
+		case "SetCaptionStyle":
+			await editor.setCaptionStyle(payload, options);
+			return;
+		case "SetBgm":
+			await editor.setBgm(payload, options);
+			return;
+		case "DeleteBgm":
+			await editor.deleteBgm(payload, options);
+			return;
+		case "AdjustBgmVolume":
+			await editor.adjustBgmVolume(payload, options);
+			return;
+		default: {
+			const _exhaustive = entry.kind;
+			throw new Error(`replayJournal: unsupported kind ${String(_exhaustive)}`);
+		}
+	}
+}
+//#endregion
 //#region src/editor/types.ts
 /** Runtime list of the frozen, implemented kinds (for guards / introspection). */
 const IMPLEMENTED_SEMANTIC_OP_KINDS = [
@@ -2012,6 +4531,10 @@ var ManualSyncDoc = class ManualSyncDoc {
 	client;
 	doc;
 	adapter;
+	/** Whether this document's timeline is owned by the Entity graph. */
+	isEntityDocument() {
+		return this.adapter.isEntityDocument();
+	}
 	editor;
 	/**
 	* The version the server is known to hold. Starts empty (nothing confirmed)
@@ -2068,7 +4591,19 @@ var ManualSyncDoc = class ManualSyncDoc {
 	}
 	/** Current content projected into the compatible track and part read shape. */
 	content() {
-		return fromVideoDocument(this.adapter.snapshot());
+		return fromVideoDocument(this.adapter.snapshot(), { placementResolved: this.isEntityDocument() });
+	}
+	/**
+	* Replay a deterministic sandbox journal into this document.
+	*
+	* The adapter stays private so callers cannot bypass the manual-sync
+	* lifecycle; journal replay is the one host-side operation that needs the
+	* adapter's transaction boundary and recorded id queue. Durability is still
+	* explicit: call {@link push} after replay and report success only from its
+	* verdict.
+	*/
+	async replayJournal(journal) {
+		await replayJournal(this.adapter, journal);
 	}
 	/**
 	* Mark the document state the caller has just observed, for a later
@@ -2713,7 +5248,6 @@ var MengineDocSession = class {
 	started = false;
 	startTask = null;
 	destroyed = false;
-	closeTask = null;
 	lifetime = null;
 	hasConnected = false;
 	initialVersionValue = null;
@@ -2732,7 +5266,8 @@ var MengineDocSession = class {
 		this.server = new MedeoHttpDocStorage({
 			docId: options.docId,
 			client: options.client,
-			sseReconnectDelayMs: options.sseReconnectDelayMs
+			sseReconnectDelayMs: options.sseReconnectDelayMs,
+			readonlyMode: options.readonlyMode
 		});
 		this.synchronizer = new ClientServerSynchronizer(this.local, this.server);
 		this.manager = new DocManager(this.local, this.synchronizer);
@@ -2815,6 +5350,24 @@ var MengineDocSession = class {
 		if (this.editorValue == null) throw new Error("mengine doc session is not started");
 		return this.editorValue;
 	}
+	/**
+	* Opaque version token of the local oplog (base64 `VersionVector.encode`).
+	* Equality-comparable only: equal means no observed change (local or
+	* remote-arrived) since the token was taken. Throws when not started.
+	*/
+	version() {
+		if (this.adapterValue == null) throw new Error("mengine doc session is not started");
+		return bytesToBase64(this.adapterValue.doc.oplogVersion().encode());
+	}
+	/**
+	* The live document adapter, exposed for journal replay (commit channel).
+	* Replaying through it still goes SemanticEditor → Loro → mengine-server —
+	* no write bypass. Typed by the narrow interface on purpose.
+	*/
+	get documentAdapter() {
+		if (this.adapterValue == null) throw new Error("mengine doc session is not started");
+		return this.adapterValue;
+	}
 	/** Current document snapshot (read model). */
 	snapshot() {
 		if (this.adapterValue == null) throw new Error("mengine doc session is not started");
@@ -2914,13 +5467,6 @@ var MengineDocSession = class {
 		this.local.connection.connect();
 		await this.local.connection.waitForConnected().abortOn(this.lifetime.signal);
 		if (this.destroyed) throw new Error("mengine doc session destroyed");
-		if (this.options.initialSnapshot) {
-			await this.local.pushDocUpdate({
-				docId: this.docId,
-				data: this.options.initialSnapshot
-			}, "initial-snapshot");
-			if (this.destroyed) throw new Error("mengine doc session destroyed");
-		}
 		this.server.connection.connect();
 		this.synchronizer.start();
 		this.manager.start();
@@ -2932,7 +5478,7 @@ var MengineDocSession = class {
 		this.adapterValue = new MirrorVideoDocumentAdapter(doc, this.mutationGuard);
 		const unsubscribe = doc.subscribe((event) => {
 			if (this.adapterValue == null) return;
-			if (event.by === "local") this.trackLocalVersion(doc.version());
+			if (event.by === "local") this.localVersionValue = doc.version();
 			this.emitSyncState();
 			this.events.emit("update", {
 				source: event.by === "local" ? "local" : "remote",
@@ -2940,10 +5486,6 @@ var MengineDocSession = class {
 			});
 		});
 		this.disposables.add(unsubscribe);
-		this.disposables.add(this.manager.onLocalUpdateReceived(this.docId, (update) => {
-			this.trackLocalVersion(decodeImportBlobMeta(update, true).partialEndVersionVector);
-			this.emitSyncState();
-		}));
 		this.disposables.add(this.manager.onDocStateChange(this.docId, (state) => {
 			this.events.emit("state", state);
 			this.emitSyncState();
@@ -2954,39 +5496,9 @@ var MengineDocSession = class {
 		this.undoManagerValue = new DocumentUndoManager(doc, this.mutationGuard, () => this.events.emit("undoState"));
 		this.editorValue = new SemanticEditor(this.adapterValue);
 		this.initialVersionValue = doc.version();
-		if (this.localVersionValue) this.trackLocalVersion(this.initialVersionValue);
 		this.emitSyncState();
 		return this.snapshot();
 	}
-	getLocalSaveState() {
-		return this.getState().localSave;
-	}
-	/** Immediately reports local transaction state; independent of server confirmation. */
-	subscribeLocalSaveState(cb) {
-		const off = this.events.on("state", () => cb(this.getLocalSaveState()));
-		cb(this.getLocalSaveState());
-		return off;
-	}
-	/** Waits for commits present now to reach local storage. Does not wait for the network. */
-	async waitForLocalSave(options = {}) {
-		if (!this.editorValue || this.destroyed) throw new Error("mengine doc session is not started");
-		await this.manager.waitForLocalSave(this.docId).timeout(options.timeoutMs ?? 15e3);
-	}
-	/** Stop accepting edits and drain local persistence before releasing resources.
-	* A failed local write keeps retrying, even after the host has unmounted.
-	* Hosts should use this for normal teardown; destroy() is immediate cancellation. */
-	close() {
-		if (this.closeTask) return this.closeTask;
-		if (this.destroyed || !this.editorValue) {
-			this.destroy();
-			return Promise.resolve();
-		}
-		this.mutationGuard.close();
-		this.synchronizer.stop();
-		this.server.connection.disconnect();
-		this.closeTask = this.manager.waitForLocalSave(this.docId).then(() => this.destroy());
-		return this.closeTask;
-	}
 	getSyncState() {
 		const state = this.getState();
 		const target = this.confirmationTarget();
@@ -2997,14 +5509,6 @@ var MengineDocSession = class {
 			phase: connection === "disconnected" ? "offline" : this.pushErrorValue != null || state.error != null ? "failed" : connection === "connecting" ? "connecting" : state.syncing ? "syncing" : "idle"
 		};
 	}
-	trackLocalVersion(version) {
-		const target = VersionVector.parseJSON(this.confirmationTarget()?.toJSON() ?? /* @__PURE__ */ new Map());
-		for (const [peer, counter] of version.toJSON()) if ((target.get(peer) ?? 0) < counter) target.setEnd({
-			peer,
-			counter
-		});
-		this.localVersionValue = target;
-	}
 	confirmationTarget() {
 		return this.localVersionValue ?? this.initialVersionValue;
 	}
@@ -3092,4 +5596,4 @@ function serverCovers(serverVV, target) {
 	return covers(server, target);
 }
 //#endregion
-export { DEFAULT_UNIT_TIME_MS, IMPLEMENTED_SEMANTIC_OP_KINDS, LANE_KINDS_IN_STACK_ORDER, ManualSyncDoc, MedeoHttpDocStorage, MemoryDocStorage, MengineAckFailedError, MengineDocSession, MengineHttpClient, MengineHttpRequestError, MenginePushRejectedError, MirrorVideoDocumentAdapter, SchemaValidator, SemanticEditor, TIMELINE_SKELETON_DURATION_MS, ValidationError, VideoDocumentValidationError, arrangeMainTrackSeamlessly, assertValidVideoDocument, base64ToBytes, buildInitialVideoDocument, buildSpeechHostMap, bytesToBase64, cascadeAfterVideoClipChanges, createMirrorVideoDocument, createMirrorVideoDocumentAdapter, decodeDocVersionMark, derivePositionFromAbs, encodeDocVersionMark, ensureLaneTrack, fillMainTrackTimeGaps, findLaneTrack, fromVideoDocument, generatePartId, getAt, hostForAbsMs, isEmptyVideoClip, isImplementedSemanticOpKind, isMap, laneTrackId, mainTrackRanges, partDurationMs, partUnionSchema, readMainTrackItems, readMengineEventStream, readPart, readPartDurationMs, readVideoDocumentFromDraft, reassignSpeechesToVideoClipsByTime, recalculateTimelineDuration, relativePositionForAbs, resolveAllSpeechOverlaps, resolveSpeechOverlapByShiftingVideos, safeDurationMs, schemas_exports as schemas, snapshotToPlain, solveVideoDocument, syncAggregatedClipsTimePosition, toVideoDocument, validateVideoDocument, videoDocumentMirrorSchema, videoDocumentSchema };
+export { DEFAULT_UNIT_TIME_MS, EntityGraphHttpClient, EntityGraphRevisionConflictError, EntityTimelineEditor, EntityTimelineProjectionError, IMPLEMENTED_SEMANTIC_OP_KINDS, LANE_KINDS_IN_STACK_ORDER, LORO_ENTITY_SCHEMA, LoroEntityDocument, LoroEntityDraft, ManualSyncDoc, MedeoHttpDocStorage, MemoryDocStorage, MengineAckFailedError, MengineDocSession, MengineHttpClient, MengineHttpRequestError, MenginePushRejectedError, MirrorVideoDocumentAdapter, PlainMemoryAdapter, SchemaValidator, ScriptCompositionError, SemanticEditor, TIMELINE_SKELETON_DURATION_MS, ValidationError, VideoDocumentValidationError, applyEntityRows, applyFieldChanges, applyVisualAssetsEffect, arrangeMainTrackSeamlessly, assembleCaptionContent, assembleEntityContent, assemblePhoneticScriptContent, assembleScriptText, assertCanonicalEditorResources, assertEntityProjectionPreservesLegacy, assertFieldChanges, assertMediaAssetWritePolicy, assertValidVideoDocument, audioScriptAssetContent, audioScriptAssetFields, audioScriptAssetHash, audioScriptAssetOf, base64ToBytes, buildInitialVideoDocument, buildSpeechHostMap, bytesToBase64, cascadeAfterVideoClipChanges, compileEntityRows, createEditSandbox, createMirrorVideoDocument, createMirrorVideoDocumentAdapter, createPlainMemoryAdapter, decodeDocVersionMark, derivePositionFromAbs, effectiveVideoClipDurationMs, encodeDocVersionMark, ensureEditorFoundation, ensureLaneTrack, fillMainTrackTimeGaps, findComposedAudioScript, findLaneTrack, fromVideoDocument, generatePartId, getAt, hasVisualAssetsEffect, hostForAbsMs, importMediaAsset, isEmptyVideoClip, isImplementedSemanticOpKind, isMap, isTranscribedAudioScript, laneTrackId, mainTrackRanges, migrateAlpha23EntityDocument, migrateLegacyTimelineToEntities, partDurationMs, partUnionSchema, phoneticScriptAssetContent, phoneticScriptAssetHash, phoneticScriptAssetOf, prepareCaptionContent, projectEntityTimeline, publishEntityRows, readDocumentAudioScript, readEntityDocument, readEntityRelationRecords, readMainTrackItems, readMengineEventStream, readPart, readPartDurationMs, readVideoDocumentFromDraft, reassignSpeechesToVideoClipsByTime, recalculateTimelineDuration, relativePositionForAbs, replayJournal, resolveAllSpeechOverlaps, resolveEntityTimelineLayout, resolveFieldPath, resolveSpeechOverlapByShiftingVideos, reviseAudioScript, safeDurationMs, schemas_exports as schemas, scriptSourceAssetOf, selectAudioScriptSegment, snapshotToPlain, solveVideoDocument, speedOf, syncAggregatedClipsTimePosition, toVideoDocument, validateVideoDocument, videoDocumentMirrorSchema, videoDocumentSchema };