@mengine/medeo-client 1.3.1-alpha.5 → 1.3.1-alpha.6

package/dist/index.js

@@ -1,6 +1,5 @@
-import { t as __exportAll } from "./chunk-D7D4PA-g.js";
-import { A as partDurationMs, C as reassignSpeechesToVideoClipsByTime, D as syncAggregatedClipsTimePosition, E as resolveSpeechOverlapByShiftingVideos, F as recordEntries, I as videoDocumentMirrorSchema, L as base64ToBytes, M as DEFAULT_UNIT_TIME_MS, N as effectiveVideoClipDurationMs, O as TIMELINE_SKELETON_DURATION_MS, P as partUnionToDraft, R as bytesToBase64, S as fillMainTrackTimeGaps, T as resolveAllSpeechOverlaps, _ as findLaneTrack, a as buildInitialVideoDocument, b as cascadeAfterVideoClipChanges, c as fromVideoDocument, d as assertValidVideoDocument, f as validateVideoDocument, g as ensureLaneTrack, h as LANE_KINDS_IN_STACK_ORDER, i as readVideoDocumentFromDraft, j as safeDurationMs, k as isEmptyVideoClip, l as toVideoDocument, m as videoDocumentSchema, n as createMirrorVideoDocument, o as buildSpeechHostMap, p as partUnionSchema, r as createMirrorVideoDocumentAdapter, s as derivePositionFromAbs, t as MirrorVideoDocumentAdapter, u as VideoDocumentValidationError, v as laneTrackId, w as recalculateTimelineDuration, x as arrangeMainTrackSeamlessly, y as solveVideoDocument } from "./document-CkFhI8ir.js";
-import { z } from "zod";
+import { $ as isEmptyVideoClip, A as buildSpeechHostMap, B as ensureLaneTrack, C as variantBaseEntityIds, D as hasSequence, E as createRelationId, F as assertValidVideoDocument, G as arrangeMainTrackSeamlessly, H as laneTrackId, I as validateVideoDocument, J as recalculateTimelineDuration, K as fillMainTrackTimeGaps, L as partUnionSchema, M as fromVideoDocument, N as toVideoDocument, O as isMediaAssetVariantKind, P as VideoDocumentValidationError, Q as TIMELINE_SKELETON_DURATION_MS, R as videoDocumentSchema, S as updateEntityFields, T as createEntityId, U as solveVideoDocument, V as findLaneTrack, W as cascadeAfterVideoClipChanges, X as resolveSpeechOverlapByShiftingVideos, Y as resolveAllSpeechOverlaps, Z as syncAggregatedClipsTimePosition, _ as assembleEntityContent, a as applyEntityTimelineProjection, at as effectiveVideoClipDurationMs, b as findComposedAudioScript, c as writeVideoDocumentToDraft, ct as recordEntries, d as EntityProjectionGraph, dt as bytesToBase64, et as partDurationMs, f as resolveEntityTimelineLayout, g as assembleCaptionContent, h as ScriptCompositionError, i as MirrorVideoDocumentAdapter, it as VIDEO_DOCUMENT_SCHEMA_VERSION, j as derivePositionFromAbs, k as buildInitialVideoDocument, l as readVideoDocumentFromDraft, lt as videoDocumentMirrorSchema, m as decodeEntityRelationRows, n as createPlainMemoryAdapter, nt as DEFAULT_UNIT_TIME_MS, o as createMirrorVideoDocument, ot as speedOf, p as EntityTimelineProjectionError, q as reassignSpeechesToVideoClipsByTime, r as generatePartId, rt as ENTITY_TIMELINE_PROJECTION_SCHEMA_VERSION, s as createMirrorVideoDocumentAdapter, st as partUnionToDraft, t as PlainMemoryAdapter, tt as safeDurationMs, u as projectEntityTimeline, ut as base64ToBytes, v as assemblePhoneticScriptContent, w as isJsonObject, x as selectAudioScriptSegments, y as assembleScriptText, z as LANE_KINDS_IN_STACK_ORDER } from "./document-BLYcbv8E.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 { LoroDoc, VersionVector } from "loro-crdt";
 import { ClientServerSynchronizer, DocManager } from "@mengine/sync";
 import { DisposableSet, EventBus, Task } from "@mengine/utils";
@@ -13,7 +12,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;
@@ -135,12 +134,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}`;
 	}
 };
 /**
@@ -157,7 +156,7 @@ 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) {
+async function safeReadJson$1(response) {
 	const text = await response.text();
 	if (text.length === 0) return null;
 	try {
@@ -195,588 +194,2443 @@ async function readMengineEventStream(options) {
 		}
 	}
 }
-function handleSseFrame(frame, onUpdate) {
-	const event = parseSseFrame(frame);
-	if (event.event !== "update" || event.data.length === 0) return;
-	onUpdate(JSON.parse(event.data.join("\n")));
+function handleSseFrame(frame, onUpdate) {
+	const event = parseSseFrame(frame);
+	if (event.event !== "update" || event.data.length === 0) return;
+	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-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.
+*
+* Media variants share one entity identity with their Asset: every
+* Image/Video/Audio/Voice Entity must carry its own external locator, every
+* external asset id has exactly one claimant, and no media variant may be
+* bound through a legacy `physical-asset` Relation. Dual-entity media graphs
+* are rejected, not migrated. Caption composes AudioScript text and has no physical text Asset.
+*/
+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();
+	const kinds = new Map(rows.entities.map((row) => [String(row.entityId), row.entityKind]));
+	for (const entity of rows.entities) {
+		if (isMediaAssetVariantKind(entity.entityKind) && memotaLocator(entity.payload.external) === void 0) throw new EntityTimelineProjectionError(`Media Entity ${entity.entityId} must carry its own Asset external identity`);
+		if (entity.entityKind !== "asset" && !isMediaAssetVariantKind(entity.entityKind)) continue;
+		const external = entity.payload.external;
+		if (!isJsonObject(external) || external.system !== "memota" && external.system !== "memota-speech" || typeof external.key !== "string") continue;
+		const key = JSON.stringify([external.system, external.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);
+	}
+	for (const relation of rows.relations) {
+		if (relation.relationKind !== "physical-asset") continue;
+		const mediaEndpoint = [relation.endpoint0EntityId, relation.endpoint1EntityId].find((endpoint) => isMediaAssetVariantKind(kinds.get(String(endpoint)) ?? ""));
+		if (mediaEndpoint !== void 0) throw new EntityTimelineProjectionError(`Cannot bind media Entity ${mediaEndpoint} through physical-asset Relation ${relation.relationId}; media owns its Asset identity directly`);
+	}
+}
+/**
+* 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 single-identity write rules
+* on the complete after state, with no exemption for historical graphs:
+*
+* 1. every Image/Video/Audio/Voice Entity carries its own Asset `external`
+*    identity;
+* 2. no `physical-asset` Relation may bind a media variant or Caption;
+* 3. a self-carried media identity is immutable — it cannot be rewritten to
+*    another asset id.
+*
+* Dual-entity media graphs are rejected instead of being migrated or merged
+* implicitly. Deleting media is explicit and allowed.
+*/
+function assertMediaAssetWritePolicy(before, after) {
+	const beforeEntities = new Map(before.entities.map((row) => [String(row.entityId), row]));
+	const afterKinds = new Map(after.entities.map((row) => [String(row.entityId), row.entityKind]));
+	for (const row of after.entities) {
+		if (!isMediaAssetVariantKind(row.entityKind)) continue;
+		if (memotaLocator(row.payload.external) === void 0) throw new EntityTimelineProjectionError(`Media Entity ${row.entityId} must carry its own Asset external identity`);
+	}
+	for (const relation of after.relations) {
+		if (relation.relationKind !== "physical-asset") continue;
+		const mediaEndpoint = [relation.endpoint0EntityId, relation.endpoint1EntityId].find((endpoint) => isMediaAssetVariantKind(afterKinds.get(String(endpoint)) ?? ""));
+		if (mediaEndpoint !== void 0) throw new EntityTimelineProjectionError(`Cannot bind media Entity ${mediaEndpoint} through physical-asset Relation ${relation.relationId}; media owns its Asset identity directly`);
+	}
+	for (const row of after.entities) {
+		if (!isMediaAssetVariantKind(row.entityKind)) continue;
+		const priorExternal = memotaLocator(beforeEntities.get(String(row.entityId))?.payload.external);
+		if (priorExternal === void 0) continue;
+		const nextExternal = memotaLocator(row.payload.external);
+		if (nextExternal !== void 0 && (nextExternal.system !== priorExternal.system || nextExternal.key !== priorExternal.key)) throw new EntityTimelineProjectionError(`Media Entity ${row.entityId} cannot rewrite its Asset external identity; create a new Entity 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
+	};
+}
+/** Add only missing editor structure; existing identities and owned settings are never replaced. */
+function ensureEditorFoundation(initial, idFactory = (prefix) => `${prefix}_${globalThis.crypto.randomUUID()}`, timelinePayload = {}) {
+	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 === "timeline-track" && (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: "timeline-track",
+				endpoint0EntityId: timeline.entityId,
+				endpoint1EntityId: track.entityId,
+				metadata: {},
+				trace: {}
+			});
+		}
+		trackEntityIds[role] = track.entityId;
+	}
+	return {
+		rows: {
+			entities,
+			relations
+		},
+		timelineEntityId: timeline.entityId,
+		trackEntityIds
+	};
+}
+//#endregion
+//#region src/entity-editor/entity-graph-http-client.ts
+const MENGINE_API_PREFIX = "/api/mengine/v1";
+const numericMarkerValidation$1 = { compareMarkerPoints: (_marker, _range, left, right) => {
+	if (typeof left !== "number" || !Number.isFinite(left) || typeof right !== "number" || !Number.isFinite(right)) throw new Error("entity-state requires finite numeric Marker coordinates");
+	return left < right ? -1 : left > right ? 1 : 0;
+} };
+/** Browser-safe authenticated CAS 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" });
+	}
+	/**
+	* Replace the complete Entity graph under the baseline revision.
+	*
+	* 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 (!isNonNegativeSafeInteger(baseState.revision)) throw new Error("Entity graph revision must be a non-negative safe integer");
+		const baseRows = cloneAndValidateRows(baseState.rows);
+		const next = cloneAndValidateRows(nextRows);
+		assertMediaAssetWritePolicy(baseRows, next);
+		const nextEntityIds = new Set(next.entities.map((row) => row.entityId));
+		const nextRelationIds = new Set(next.relations.map((row) => row.relationId));
+		const deletedEntityIds = baseRows.entities.map((row) => row.entityId).filter((entityId) => !nextEntityIds.has(entityId)).sort();
+		const deletedRelationIds = baseRows.relations.map((row) => row.relationId).filter((relationId) => !nextRelationIds.has(relationId)).sort();
+		return this.request({
+			method: "POST",
+			body: JSON.stringify({
+				expected_revision: baseState.revision,
+				rows: toWireRows(next),
+				deleted_entity_ids: deletedEntityIds,
+				deleted_relation_ids: deletedRelationIds,
+				...options.migrationBaseVv === void 0 ? {} : { migration_base_vv: options.migrationBaseVv }
+			})
+		});
+	}
+	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 new MengineHttpRequestError(response.status, payload);
+		return parseWireState(payload, this.options.docId);
+	}
+};
+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, numericMarkerValidation$1);
+	return {
+		revision: value.revision,
+		rows
+	};
+}
+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, numericMarkerValidation$1);
+	return clone;
+}
+function toWireRows(rows) {
+	return {
+		entities: rows.entities.map((row) => ({
+			entity_id: row.entityId,
+			entity_kind: row.entityKind,
+			payload: row.payload
+		})),
+		relations: rows.relations.map((row) => ({
+			relation_id: row.relationId,
+			relation_kind: row.relationKind,
+			endpoint_0_entity_id: row.endpoint0EntityId,
+			endpoint_1_entity_id: row.endpoint1EntityId,
+			metadata: row.metadata,
+			trace: row.trace
+		}))
+	};
+}
+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
+const numericCoordinates = { compareMarkerPoints: (_marker, _range, left, right) => {
+	if (typeof left !== "number" || typeof right !== "number" || !Number.isFinite(left) || !Number.isFinite(right)) throw new Error("Media editor requires numeric coordinates");
+	return left - right;
+} };
+/**
+* Import at the editor boundary, not at asset generation time. Existing
+* provenance is retained.
+*
+* A media variant is a logical facet of its Asset and shares one entity
+* identity: the import mints exactly one entity of the media kind that carries
+* the external locator itself, and deduplicates only against existing variants
+* that already carry the same `(system, key)`. Legacy dual-entity graphs
+* (`asset` row plus a `physical-asset` binding) are not reused and are
+* rejected by the canonical resource policy instead of being migrated.
+*/
+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",
+		"voice"
+	].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 === "voice") && fact.storageKey.trim() === "") throw new Error(`${fact.kind} ${fact.assetId} requires its physical storage key`);
+	decodeEntityRelationRows(initial, numericCoordinates);
+	assertCanonicalEditorResources(initial);
+	const entities = structuredClone([...initial.entities]);
+	const relations = structuredClone([...initial.relations]);
+	const system = fact.kind === "voice" ? "memota-speech" : "memota";
+	const existing = entities.filter((row) => {
+		const external = row.payload.external;
+		return isMediaAssetVariantKind(row.entityKind) && isJsonObject(external) && external.system === system && external.key === fact.assetId;
+	});
+	if (existing.length > 1) throw new Error(`Duplicate media identities for ${fact.assetId}; reuse ${existing[0].entityId}`);
+	if (existing[0] !== void 0) {
+		const variant = requireMatchingVariant(existing[0], fact);
+		replaceEntity$1(entities, variant.entityId, variant);
+		return {
+			rows: {
+				entities,
+				relations
+			},
+			contentEntityId: variant.entityId
+		};
+	}
+	const entityId = createEntityId(idFactory("entity"));
+	if (entities.some((row) => row.entityId === entityId)) throw new Error(`Duplicate entity id ${entityId}`);
+	const variant = {
+		entityId,
+		entityKind: fact.kind,
+		payload: {
+			extent: fact.kind === "image" ? {
+				kind: "unbounded",
+				start: 0
+			} : {
+				kind: "bounded",
+				start: 0,
+				end: fact.durationMs
+			},
+			sampling: fact.kind === "image" ? "constant" : "native",
+			coordinateSpace: "milliseconds",
+			external: {
+				system,
+				key: fact.assetId
+			},
+			...fact.storageKey === void 0 ? {} : { storageKey: fact.storageKey },
+			...fact.kind === "voice" && fact.voice !== void 0 ? { voice: {
+				system: fact.voice.system,
+				key: fact.voice.key,
+				...fact.voice.name === void 0 ? {} : { name: fact.voice.name }
+			} } : {}
+		}
+	};
+	entities.push(variant);
+	const rows = {
+		entities,
+		relations
+	};
+	decodeEntityRelationRows(rows, numericCoordinates);
+	assertCanonicalEditorResources(rows);
+	return {
+		rows,
+		contentEntityId: entityId
+	};
+}
+function requireMatchingVariant(row, fact) {
+	const extent = row.payload.extent;
+	if (row.entityKind !== fact.kind || fact.kind !== "image" && (!isJsonObject(extent) || extent.start !== 0 || extent.end !== fact.durationMs) || fact.kind === "voice" && !sameVoice(row.payload.voice, fact.voice)) throw new Error(`Media facts conflict with existing identity for ${fact.assetId}`);
+	if (fact.storageKey !== void 0 && row.payload.storageKey !== fact.storageKey) {
+		if (row.payload.storageKey !== void 0) throw new Error(`Media facts conflict with existing storage key for ${fact.assetId}`);
+		return {
+			...row,
+			payload: {
+				...row.payload,
+				storageKey: fact.storageKey
+			}
+		};
+	}
+	return row;
+}
+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;
+}
+function sameVoice(left, right) {
+	if (right === void 0) return left === void 0;
+	return isJsonObject(left) && left.system === right.system && left.key === right.key && left.name === right.name && Object.keys(left).every((key) => key === "system" || key === "key" || key === "name");
+}
+//#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 captionSelections(selections) {
+	return structuredClone(selections);
+}
+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.clipPayload?.order;
+		const order = typeof requestedOrder === "number" ? requestedOrder : nextSequentialOrder(this.state, createEntityId(input.trackEntityId));
+		return this.insertPlacedClip({
+			trackEntityId: input.trackEntityId,
+			contentEntityId: input.contentEntityId,
+			sourceRange: input.sourceRange,
+			duration: input.duration,
+			placement: input.targetRange === void 0 ? {
+				kind: "sequential",
+				order
+			} : {
+				kind: "absolute",
+				targetRange: input.targetRange
+			},
+			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.sourceRange !== void 0) payload.sourceRange = cloneJsonValue(input.sourceRange, "sourceRange");
+			if (input.duration !== void 0) payload.duration = cloneJsonValue(input.duration, "duration");
+			if (Object.hasOwn(input, "targetRange")) if (input.targetRange === void 0) {
+				delete payload.targetRange;
+				if (!hasOutgoingClipAnchor(draft, input.clipEntityId)) {
+					const trackId = otherEndpoint(requireOneRelation(draft, createEntityId(input.clipEntityId), "track-clip"), input.clipEntityId);
+					const clipPayload = { ...cloneJsonObject(requireEntityKind(draft, input.clipEntityId, "clip").payload, "Clip payload") };
+					clipPayload.order ??= nextSequentialOrder(draft, trackId);
+					replaceEntity(draft, createEntityId(input.clipEntityId), {
+						...requireEntityKind(draft, input.clipEntityId, "clip"),
+						payload: clipPayload
+					});
+				}
+			} else {
+				payload.targetRange = cloneJsonValue(input.targetRange, "targetRange");
+				const clip = requireEntityKind(draft, input.clipEntityId, "clip");
+				const clipPayload = { ...cloneJsonObject(clip.payload, "Clip payload") };
+				delete clipPayload.order;
+				replaceEntity(draft, clip.entityId, {
+					...clip,
+					payload: clipPayload
+				});
+			}
+			if (Object.hasOwn(input, "timeRemapping")) if (input.timeRemapping === void 0) delete payload.timeRemapping;
+			else payload.timeRemapping = cloneJsonValue(input.timeRemapping, "timeRemapping");
+			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"),
+				sourceRange: cloneJsonValue(input.sourceRange, "sourceRange"),
+				duration: cloneJsonValue(input.duration, "duration")
+			};
+			delete payload.targetRange;
+			delete payload.timeRemapping;
+			if (input.targetRange !== void 0) payload.targetRange = cloneJsonValue(input.targetRange, "targetRange");
+			if (input.timeRemapping !== void 0) payload.timeRemapping = cloneJsonValue(input.timeRemapping, "timeRemapping");
+			replaceEntity(draft, topology.marker.entityId, {
+				...topology.marker,
+				payload
+			});
+			if (!hasOutgoingClipAnchor(draft, topology.clip.entityId)) {
+				const clipPayload = { ...cloneJsonObject(topology.clip.payload, "Clip payload") };
+				if (input.targetRange === void 0) clipPayload.order ??= nextSequentialOrder(draft, otherEndpoint(topology.trackRelation, topology.clip.entityId));
+				else delete clipPayload.order;
+				replaceEntity(draft, topology.clip.entityId, {
+					...topology.clip,
+					payload: clipPayload
+				});
+			}
+			this.relinkRelation(draft, topology.markerContentRelation, {
+				endpoint0EntityId: topology.marker.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 sourceRange = requirePositiveRange(input.sourceRange, "sourceRange");
+			const clipId = this.insertPlacedClipIntoDraft(draft, {
+				trackEntityId: track.entityId,
+				contentEntityId: imported.contentEntityId,
+				sourceRange,
+				duration: {
+					mode: "fixed",
+					value: sourceRange.end - sourceRange.start
+				},
+				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 sourceRange = requirePositiveRange(clip.sourceRange, "sourceRange");
+				created.push(this.insertPlacedClipIntoDraft(draft, {
+					trackEntityId: track.entityId,
+					contentEntityId: imported.contentEntityId,
+					sourceRange,
+					duration: {
+						mode: "fixed",
+						value: sourceRange.end - sourceRange.start
+					},
+					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 sourceRange = requirePositiveRange(input.sourceRange, "sourceRange");
+			const markerPayloadValue = {
+				...cloneJsonObject(topology.marker.payload, "Sequence Marker payload"),
+				sourceRange,
+				duration: {
+					mode: "fixed",
+					value: sourceRange.end - sourceRange.start
+				}
+			};
+			delete markerPayloadValue.timeRemapping;
+			resizeAbsoluteTarget(markerPayloadValue, sourceRange.end - sourceRange.start);
+			replaceEntity(draft, topology.marker.entityId, {
+				...topology.marker,
+				payload: markerPayloadValue
+			});
+			this.relinkRelation(draft, topology.markerContentRelation, {
+				endpoint0EntityId: topology.marker.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.markerContentRelation, initialTopology.marker.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 priorSource = requirePositiveRange(initialPayload.sourceRange, "sourceRange");
+			if (input.timeRemapping === null && initialPayload.timeRemapping === void 0) return;
+			this.normalizeMainSequential(draft);
+			const topology = requireClipTopology(draft, input.clipEntityId);
+			const payload = { ...cloneJsonObject(topology.marker.payload, "Sequence Marker payload") };
+			let sourceRange = priorSource;
+			if (content.entityKind === "image" && initialPayload.timeRemapping === void 0 && input.timeRemapping !== null) sourceRange = {
+				start: 0,
+				end: markerDuration(initialPayload, priorSource)
+			};
+			if (input.timeRemapping === null) {
+				delete payload.timeRemapping;
+				payload.sourceRange = sourceRange;
+				payload.duration = {
+					mode: "fixed",
+					value: sourceRange.end - sourceRange.start
+				};
+			} else {
+				const rate = finitePositive(input.timeRemapping.rate, "linear speed rate");
+				const duration = Math.round((sourceRange.end - sourceRange.start) / rate);
+				if (duration <= 0 || !Number.isSafeInteger(duration)) throw new Error("Linear speed produces an invalid duration");
+				payload.sourceRange = sourceRange;
+				payload.duration = {
+					mode: "fixed",
+					value: duration
+				};
+				payload.timeRemapping = {
+					kind: "linear",
+					rate,
+					...input.timeRemapping.mode === void 0 ? {} : { mode: input.timeRemapping.mode }
+				};
+			}
+			resizeAbsoluteTarget(payload, markerDuration(payload, sourceRange));
+			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.markerContentRelation, topology.marker.entityId));
+			if (content.entityKind !== "video" && content.entityKind !== "image") throw new Error("Clip trimming is supported only for Video or Image content");
+			const sourceRange = requirePositiveRange(input.sourceRange, "sourceRange");
+			const payload = {
+				...cloneJsonObject(topology.marker.payload, "Sequence Marker payload"),
+				sourceRange
+			};
+			const rate = linearRate(payload.timeRemapping);
+			const duration = Math.round((sourceRange.end - sourceRange.start) / rate);
+			if (duration <= 0 || !Number.isSafeInteger(duration)) throw new Error("Trim produces an invalid duration");
+			payload.duration = {
+				mode: "fixed",
+				value: duration
+			};
+			resizeAbsoluteTarget(payload, 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 sourceRange = requirePositiveRange(replacement.sourceRange, "sourceRange");
+				created.push(this.insertPlacedClipIntoDraft(draft, {
+					trackEntityId: track.entityId,
+					contentEntityId: imported.contentEntityId,
+					sourceRange,
+					duration: {
+						mode: "fixed",
+						value: sourceRange.end - sourceRange.start
+					},
+					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(["track-clip", "clip-marker"]));
+			assertOnlyStructuralIncidents(draft, topology.marker.entityId, new Set(["clip-marker", "marker-content"]));
+			const markerIsExclusive = incidentRelations(draft, topology.marker.entityId).filter((relation) => relation.relationKind === "clip-marker").length === 1;
+			const removedRelationIds = new Set([topology.trackRelation.relationId, topology.clipMarkerRelation.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",
+					targetRange: {
+						start: placement.start,
+						end: placement.start + placement.duration
+					}
+				});
+			}
+			else for (const target of targets) this.removeAnchoredDescendants(draft, target, targets);
+			for (const target of targets) this.removeClipGraph(draft, target);
+			normalizeSequentialOrders(draft);
+			if (includesVisual) this.resolveOneVoiceoverOverlap(draft);
+		});
+	}
+	updateClip(input) {
+		this.transact((draft) => {
+			const clip = requireEntityKind(draft, input.clipEntityId, "clip");
+			const priorOrder = clip.payload.order;
+			replaceEntity(draft, clip.entityId, {
+				...clip,
+				payload: {
+					...cloneJsonObject(input.payload, "Clip payload"),
+					...priorOrder === void 0 || Object.hasOwn(input.payload, "order") ? {} : { order: priorOrder }
+				}
+			});
+		});
+	}
+	upsertVoiceoverTake(input) {
+		return this.transact((draft) => {
+			this.normalizeMainSequential(draft);
+			const placement = input.placement ?? {
+				kind: "anchored",
+				hostClipEntityId: input.hostClipEntityId,
+				anchorOffset: input.anchorOffset
+			};
+			if (input.placement !== void 0 && (input.hostClipEntityId !== void 0 || input.anchorOffset !== void 0)) throw new Error("Specify Voice placement or hostClipEntityId/anchorOffset, not both");
+			requireVolume(input.volume);
+			const imported = importMediaAsset(draft, input.media, this.idFactory);
+			replaceRows(draft, imported.rows);
+			const voice = requireEntityKind(draft, imported.contentEntityId, "voice");
+			const phonetic = this.requireComposedPhoneticScript(draft, input.phoneticScriptEntityId);
+			this.ensurePhoneticRender(draft, voice.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: voice.entityId,
+				sourceRange: {
+					start: 0,
+					end: input.media.durationMs
+				},
+				duration: {
+					mode: "fixed",
+					value: 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.markerContentRelation, {
+					endpoint0EntityId: topology.marker.entityId,
+					endpoint1EntityId: voice.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,
+						sourceRange: {
+							start: 0,
+							end: input.media.durationMs
+						},
+						duration: {
+							mode: "fixed",
+							value: input.media.durationMs
+						}
+					}
+				});
+			}
+			this.reconcileVoiceoverCaptions(draft, voiceoverClipEntityId, voice.entityId, phonetic.entityId, input.captions);
+			this.resolveOneVoiceoverOverlap(draft);
+			return {
+				voiceoverClipEntityId,
+				voiceEntityId: voice.entityId,
+				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,
+				sourceRange: {
+					start: 0,
+					end: input.media.durationMs
+				},
+				duration: { mode: "from-source" },
+				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,
+					durationPolicy: "timeline"
+				}
+			});
+			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.markerContentRelation, topology.marker.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 selections = captionSelections(input.selections);
+			const track = this.ensureRoleTrack(draft, input.timelineEntityId, "caption");
+			const content = {
+				entityId: this.mintEntityId(draft),
+				entityKind: "caption",
+				payload: {
+					extent: {
+						kind: "bounded",
+						start: 0,
+						end: durationMs
+					},
+					sampling: "native",
+					coordinateSpace: "milliseconds",
+					baseEntityIds: captionBaseIds(input.baseEntityIds),
+					selections,
+					...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,
+				sourceRange: {
+					start: 0,
+					end: durationMs
+				},
+				duration: {
+					mode: "fixed",
+					value: 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") };
+		delete clipPayload.order;
+		const markerPlacement = applyPlacementPayload(clipPayload, input.placement);
+		const clip = {
+			entityId: clipId,
+			entityKind: "clip",
+			payload: clipPayload
+		};
+		const marker = {
+			entityId: markerId,
+			entityKind: "sequence-marker",
+			payload: markerPayload({
+				sourceRange: input.sourceRange,
+				duration: input.duration,
+				...markerPlacement
+			})
+		};
+		draft.entities.push(clip, marker);
+		draft.relations.push(this.createRelation(draft, "track-clip", track.entityId, clipId), this.createRelation(draft, "clip-marker", clipId, markerId), this.createRelation(draft, "marker-content", markerId, 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) {
+			if (existing.payload.order === void 0) {
+				const replacement = {
+					...existing,
+					payload: {
+						...existing.payload,
+						order: roleOrder[role]
+					}
+				};
+				replaceEntity(draft, existing.entityId, replacement);
+				return replacement;
+			}
+			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, "timeline-track", timeline.entityId, track.entityId));
+		return track;
+	}
+	/** The existing pronunciation variant a Voice 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, regardless of persisted endpoint positions. */
+	ensurePhoneticRender(draft, voiceEntityId, phoneticScriptEntityId) {
+		const renders = draft.relations.filter((relation) => relation.relationKind === "phonetic-script-render" && (relation.endpoint0EntityId === voiceEntityId || relation.endpoint1EntityId === voiceEntityId));
+		if (renders.length > 1) throw new Error(`Voice "${voiceEntityId}" has multiple PhoneticScript render relations`);
+		if (renders[0] !== void 0) {
+			if (otherEndpoint(renders[0], voiceEntityId) === phoneticScriptEntityId) return;
+			throw new Error(`Voice "${voiceEntityId}" already has a different PhoneticScript synthesis input`);
+		}
+		draft.relations.push(this.createRelation(draft, "phonetic-script-render", voiceEntityId, phoneticScriptEntityId));
+	}
+	reconcileVoiceoverCaptions(draft, voiceoverClipEntityId, voiceEntityId, 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 selections = captionSelections(caption.selections);
+			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: {
+						extent: {
+							kind: "bounded",
+							start: 0,
+							end: durationMs
+						},
+						sampling: "native",
+						coordinateSpace: "milliseconds",
+						baseEntityIds,
+						selections,
+						...caption.style === void 0 ? {} : { style: cloneJsonObject(caption.style, "Caption style") }
+					}
+				};
+				draft.entities.push(content);
+				assertCaptionScript(draft, content.entityId, audioScriptEntityId);
+				draft.relations.push(this.createRelation(draft, "caption-alignment", content.entityId, voiceEntityId, { alignment: {
+					start: startMs,
+					end: startMs + durationMs
+				} }));
+				this.insertPlacedClipIntoDraft(draft, {
+					clipEntityId: caption.captionClipEntityId,
+					trackEntityId: captionTrack.entityId,
+					contentEntityId: content.entityId,
+					sourceRange: {
+						start: 0,
+						end: durationMs
+					},
+					duration: {
+						mode: "fixed",
+						value: durationMs
+					},
+					placement: {
+						kind: "anchored",
+						hostClipEntityId: voiceoverClipEntityId,
+						anchorOffset: startMs
+					}
+				});
+				continue;
+			}
+			const topology = requireClipOnRole(draft, caption.captionClipEntityId, "caption");
+			const content = requireEntityKind(draft, otherEndpoint(topology.markerContentRelation, topology.marker.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,
+					selections,
+					...Object.keys(style).length === 0 ? {} : { style }
+				}
+			});
+			assertCaptionScript(draft, content.entityId, audioScriptEntityId);
+			this.applyClipPlacement(draft, topology.clip.entityId, {
+				kind: "anchored",
+				hostClipEntityId: voiceoverClipEntityId,
+				anchorOffset: startMs
+			});
+			const placed = requireClipTopology(draft, topology.clip.entityId);
+			replaceEntity(draft, placed.marker.entityId, {
+				...placed.marker,
+				payload: {
+					...placed.marker.payload,
+					duration: {
+						mode: "fixed",
+						value: durationMs
+					}
+				}
+			});
+			this.replaceCaptionAlignment(draft, content.entityId, voiceEntityId, startMs, durationMs);
+		}
+	}
+	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(requireOneRelation(draft, track.entityId, "timeline-track"), track.entityId), "timeline");
+		return this.ensureRoleTrack(draft, timeline.entityId, role);
+	}
+	replaceCaptionAlignment(draft, captionEntityId, voiceEntityId, startMs, durationMs) {
+		const removed = new Set(incidentRelations(draft, captionEntityId).filter((relation) => relation.relationKind === "caption-alignment").map((relation) => relation.relationId));
+		draft.relations = draft.relations.filter((relation) => !removed.has(relation.relationId));
+		draft.relations.push(this.createRelation(draft, "caption-alignment", captionEntityId, voiceEntityId, { alignment: {
+			start: startMs,
+			end: startMs + durationMs
+		} }));
+	}
+	/**
+	* 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.markerContentRelation, topology.marker.entityId), "caption");
+		const contentRelations = incidentRelations(draft, caption.entityId);
+		const allowed = new Set(["caption-alignment", "marker-content"]);
+		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 (incidentRelations(draft, caption.entityId).some((relation) => relation.relationKind === "marker-content")) 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",
+				targetRange: {
+					start: clip.start + (visualIndex >= hostIndex ? overlapMs : 0),
+					end: clip.start + clip.duration + (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 clipPayload.order;
+		delete markerPayloadValue.targetRange;
+		delete markerPayloadValue.anchorOffset;
+		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") clipPayload.order = finiteNumber(placement.order, "Clip order");
+		else if (placement.kind === "absolute") markerPayloadValue.targetRange = cloneJsonValue(placement.targetRange, "targetRange");
+		else {
+			const host = requireEntityKind(draft, placement.hostClipEntityId, "clip");
+			if (host.entityId === topology.clip.entityId) throw new Error("A Clip cannot anchor to itself");
+			markerPayloadValue.anchorOffset = finiteNonNegative(placement.anchorOffset, "anchorOffset");
+			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) {
+			const child = layout.clips.get(childClipEntityId);
+			if (child === void 0) throw new Error(`Clip "${childClipEntityId}" is not placed`);
+			this.applyClipPlacement(draft, childClipEntityId, {
+				kind: "absolute",
+				targetRange: {
+					start: absoluteStart,
+					end: absoluteStart + child.duration
+				}
+			});
+			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,
+			anchorOffset: 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([
+			"track-clip",
+			"clip-marker",
+			"clip-anchor"
+		]));
+		assertOnlyStructuralIncidents(draft, topology.marker.entityId, new Set(["clip-marker", "marker-content"]));
+		const markerIsExclusive = incidentRelations(draft, topology.marker.entityId).filter((relation) => relation.relationKind === "clip-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, numericMarkerValidation);
+	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 = incidentRelations(rows, entity.entityId).filter((relation) => relation.relationKind === "track-clip");
+		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 = incidentRelations(rows, trackEntityId).filter((relation) => relation.relationKind === "timeline-track");
+	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 = requireOneRelation(rows, clip.entityId, "track-clip");
+	requireEntityKind(rows, otherEndpoint(trackRelation, clip.entityId), "track");
+	const clipMarkerRelation = requireOneRelation(rows, clip.entityId, "clip-marker");
+	const marker = requireEntityKind(rows, otherEndpoint(clipMarkerRelation, clip.entityId), "sequence-marker");
+	const markerContentRelation = requireOneRelation(rows, marker.entityId, "marker-content");
+	requireSequenceContent(rows, otherEndpoint(markerContentRelation, marker.entityId));
+	return {
+		clip,
+		marker,
+		trackRelation,
+		clipMarkerRelation,
+		markerContentRelation
+	};
+}
+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));
+}
+function applyPlacementPayload(clipPayload, placement) {
+	if (placement.kind === "sequential") {
+		clipPayload.order = finiteNumber(placement.order, "Clip order");
+		return {};
+	}
+	if (placement.kind === "absolute") return { targetRange: cloneJsonValue(placement.targetRange, "targetRange") };
+	return { anchorOffset: finiteNonNegative(placement.anchorOffset, "anchorOffset") };
+}
+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;
+}
+function setClipOrder(rows, clipEntityId, order) {
+	const clip = requireEntityKind(rows, clipEntityId, "clip");
+	replaceEntity(rows, clip.entityId, {
+		...clip,
+		payload: {
+			...clip.payload,
+			order
+		}
+	});
+}
+function normalizeSequentialOrders(rows) {
+	for (const track of rows.entities.filter((entity) => entity.entityKind === "track")) rows.relations.filter((relation) => relation.relationKind === "track-clip" && relation.endpoint0EntityId === track.entityId).map((relation) => rows.entities.find((entity) => entity.entityId === relation.endpoint1EntityId)).filter((entity) => entity?.entityKind === "clip" && typeof entity.payload.order === "number").sort((left, right) => Number(left.payload.order) - Number(right.payload.order)).forEach((clip, order) => setClipOrder(rows, clip.entityId, order));
+}
+function findRoleTrack(rows, timelineEntityId, role) {
+	const timeline = requireEntityKind(rows, timelineEntityId, "timeline");
+	const tracks = incidentRelations(rows, timeline.entityId).filter((relation) => relation.relationKind === "timeline-track").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 incidentRelations(rows, trackEntityId).filter((relation) => relation.relationKind === "track-clip").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 requirePositiveRange(value, label) {
+	if (!isJsonObject(value)) throw new Error(`${label} must be an object`);
+	const start = finiteNonNegative(value.start, `${label}.start`);
+	const end = finitePositive(value.end, `${label}.end`);
+	if (!Number.isSafeInteger(start) || !Number.isSafeInteger(end) || end <= start) throw new Error(`${label} must be a positive whole-millisecond range`);
+	return {
+		start,
+		end
+	};
+}
+function markerDuration(payload, sourceRange) {
+	const duration = payload.duration;
+	if (!isJsonObject(duration)) throw new Error("Sequence Marker duration must be an object");
+	if (duration.mode === "from-source") return sourceRange.end - sourceRange.start;
+	if (duration.mode !== "fixed") throw new Error("Sequence Marker duration mode is unsupported");
+	return finitePositive(duration.value, "Sequence Marker fixed duration");
+}
+function linearRate(value) {
+	if (value === void 0) return 1;
+	if (!isJsonObject(value) || value.kind !== "linear") throw new Error("Only linear Clip time remapping is supported");
+	return finitePositive(value.rate, "linear speed rate");
+}
+function resizeAbsoluteTarget(payload, duration) {
+	if (payload.targetRange === void 0) return;
+	const target = requirePositiveRange(payload.targetRange, "targetRange");
+	payload.targetRange = {
+		start: target.start,
+		end: target.start + duration
+	};
+}
+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;
+}
+function nextSequentialOrder(rows, trackEntityId) {
+	const orders = rows.relations.filter((relation) => relation.relationKind === "track-clip" && relation.endpoint0EntityId === trackEntityId).map((relation) => rows.entities.find((entity) => entity.entityId === relation.endpoint1EntityId)?.payload.order).filter((order) => typeof order === "number" && Number.isFinite(order));
+	return orders.length === 0 ? 0 : Math.max(...orders) + 1;
+}
+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 cloneJsonValue(value, label) {
+	return cloneJsonObject({ value }, label).value;
+}
+function cloneRows(rows) {
+	return {
+		entities: rows.entities.map((entity) => structuredClone(entity)),
+		relations: rows.relations.map((relation) => structuredClone(relation))
+	};
+}
+const numericMarkerValidation = { compareMarkerPoints: (_marker, _range, left, right) => {
+	if (typeof left !== "number" || !Number.isFinite(left) || typeof right !== "number" || !Number.isFinite(right)) throw new Error("Sequence Marker points must use finite numeric coordinates");
+	return left - right;
+} };
+//#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 (legacy.meta.schema_version === "video-document/entity-projection-v1") 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 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: "voice",
+				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);
+		} 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("timeline-track", 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 },
+				...item.time_position.mode === "sequential" && !(role === "video_clip" && normalizedMainRanges !== void 0) || role === "bgm" ? { 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 = {
+					sourceRange: {
+						start: video.play_in,
+						end: video.play_out
+					},
+					duration: {
+						mode: "fixed",
+						value: duration
+					},
+					...(fact.kind === "image" || fact.kind === "video") && video.speed_shift !== void 0 ? { timeRemapping: {
+						kind: "linear",
+						mode: video.speed_shift?.mode ?? "constant",
+						rate
+					} } : {}
+				};
+			} else if (part.speech !== void 0) {
+				duration = part.speech.media_duration_ms;
+				markerPayload = {
+					sourceRange: {
+						start: 0,
+						end: duration
+					},
+					duration: {
+						mode: "fixed",
+						value: duration
+					}
+				};
+			} else if (part.caption !== void 0) {
+				const caption = part.caption;
+				duration = caption.initial_duration_ms;
+				const voice = contentByPartId.get(caption.speech_part_id);
+				const render = relations.find((relation) => relation.relationKind === "phonetic-script-render" && relation.endpoint0EntityId === voice);
+				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 selections before cutover");
+				const selections = [{
+					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", {
+					extent: {
+						kind: "bounded",
+						start: 0,
+						end: duration
+					},
+					sampling: "native",
+					coordinateSpace: "milliseconds",
+					baseEntityIds: [script.entityId],
+					selections,
+					...caption.style === void 0 ? {} : { style: toEntityCaptionStyle(caption.style) }
+				});
+				link("caption-alignment", content, voice, { alignment: {
+					start: caption.start_ms,
+					end: caption.start_ms + duration
+				} });
+				markerPayload = {
+					sourceRange: {
+						start: 0,
+						end: duration
+					},
+					duration: {
+						mode: "fixed",
+						value: 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 = {
+					sourceRange: {
+						start: 0,
+						end: duration
+					},
+					duration: { mode: "from-source" },
+					durationPolicy: "timeline"
+				};
+			}
+			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,
+				targetRange: normalizedMainRange
+			};
+			else if (item.time_position.mode === "absolute" && role !== "bgm") markerPayload = {
+				...markerPayload,
+				targetRange: {
+					start: item.time_position.offsetMs,
+					end: item.time_position.offsetMs + duration
+				}
+			};
+			else if (item.time_position.mode === "anchored") markerPayload = {
+				...markerPayload,
+				anchorOffset: item.time_position.offsetMs
+			};
+			const marker = addEntity("sequence-marker", markerPayload);
+			link("track-clip", track, clip);
+			link("clip-marker", clip, marker);
+			link("marker-content", marker, content);
+			if (item.time_position.mode === "anchored") link("clip-anchor", clip, item.time_position.anchorPartId);
+		}
+	}
+	const rows = {
+		entities,
+		relations
+	};
+	assertEntityProjectionPreservesLegacy(legacy, projectEntityTimeline(rows, legacy.meta), rows);
+	return rows;
+}
+/** Server gate: a cutover may change representation, never the existing render facts. */
+function assertEntityProjectionPreservesLegacy(legacy, projection, rows) {
+	assertSupportedLegacy(legacy);
+	if (projection.meta.schema_version !== "video-document/entity-projection-v1") fail("Expected an entity projection for migration");
+	const normalizedMainRanges = overlapNormalizedMainRanges(legacy);
+	const compatibilityFacts = (document) => {
+		const { version: _version, ...view } = fromVideoDocument(document);
+		for (const part of Object.values(view.part_library ?? {})) {
+			const speech = part.speech;
+			if (speech?.phoneme_script === null) delete speech.phoneme_script;
+		}
+		const { schema_version: _schemaVersion, version: _metaVersion, ...meta } = document.meta;
+		return {
+			meta,
+			view
+		};
+	};
+	if (canonical(compatibilityFacts(legacy)) !== canonical(compatibilityFacts(projection))) 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 === "clip-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 (clip.payload.order !== void 0 || !isExactRange(marker.payload.targetRange, normalizedMainRange) || marker.payload.anchorOffset !== void 0 || 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.targetRange !== void 0 || marker.payload.anchorOffset !== void 0 || marker.payload.durationPolicy !== "timeline" || anchors.length !== 0) fail("Migration must preserve timeline-filling BGM semantics");
+			} else if (item.time_position.mode === "sequential") {
+				if (marker.payload.targetRange !== void 0 || marker.payload.anchorOffset !== 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") {
+				const target = marker.payload.targetRange;
+				if (clip.payload.order !== void 0 || !isRangeStartingAt(target, item.time_position.offsetMs) || marker.payload.anchorOffset !== void 0 || anchors.length !== 0) fail("Migration must preserve absolute placement semantics");
+			} else if (clip.payload.order !== void 0 || marker.payload.targetRange !== void 0 || marker.payload.anchorOffset !== 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 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 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");
+	}
 }
-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 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");
 }
-//#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.
+* 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.
 */
-/** 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;
+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;
 	}
-	return out;
+	return moved ? ranges : void 0;
 }
-function encodeRandom() {
-	let out = "";
-	for (let i = 0; i < RANDOM_LEN; i++) out += CROCKFORD[Math.floor(Math.random() * 32)];
-	return out;
+function requirePart(document, partId) {
+	const part = document.part_library?.[partId];
+	if (part === void 0) fail(`Placed Clip ${partId} has no part payload`);
+	return part;
 }
-/** A 26-char Crockford Base32 ULID (10-char time + 16-char random). */
-function ulid() {
-	return encodeTime(Date.now()) + encodeRandom();
+function ensureSpeechPhoneticChain(voiceEntityId, audioScriptText, phonemeScript, entities, relations, addEntity, link) {
+	const renders = relations.filter((relation) => relation.relationKind === "phonetic-script-render" && relation.endpoint0EntityId === voiceEntityId);
+	if (renders.length > 1) fail(`Voice ${voiceEntityId} 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(`Voice ${voiceEntityId} has a dangling PhoneticScript render`);
+		const script = composedAudioScript(phonetic, entities);
+		if (script === void 0 || scriptText(script) !== audioScriptText) fail(`Voice ${voiceEntityId} conflicts with the legacy Speech script`);
+		return phonetic.entityId;
+	}
+	const phonetic = addEntity("phonetic-script", {
+		baseEntityIds: [addEntity("audio-script", { segments: [{
+			segmentId: "segment-0",
+			text: audioScriptText
+		}] })],
+		...phonemeScript === void 0 ? {} : { phonemeScript }
+	});
+	link("phonetic-script-render", voiceEntityId, phonetic);
+	return phonetic;
 }
-function generatePartId(prefix) {
-	return `${prefix}_${ulid()}`;
+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 {
+		...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 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");
+}
+function isRangeStartingAt(value, expectedStart) {
+	return value !== null && typeof value === "object" && !Array.isArray(value) && value.start === expectedStart;
+}
+function isExactRange(value, expected) {
+	return value !== null && typeof value === "object" && !Array.isArray(value) && value.start === expected.start && value.end === expected.end;
+}
+function requireFinite(value, label) {
+	if (typeof value !== "number" || !Number.isFinite(value)) fail(`${label} must be finite`);
+	return value;
+}
+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;
+}
+function requirePositiveMilliseconds(value, label) {
+	const result = requireMilliseconds(value, label);
+	if (result <= 0) fail(`${label} must be positive`);
+	return result;
+}
+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");
-//#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;
-	}
-	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"
-			]
-		});
-	}
-});
-//#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"
-			]
-		});
+//#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,
+			extent: previous?.payload.extent ?? {
+				kind: "bounded",
+				start: 0,
+				end: input.durationMs
+			},
+			sampling: previous?.payload.sampling ?? "native",
+			coordinateSpace: previous?.payload.coordinateSpace ?? "milliseconds"
+		}
+	};
+	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,
+			selections: structuredClone(input.selections ?? 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 source = script;
+	const fullText = assembleScriptText(source);
+	const segments = source.payload.segments;
+	if (text === fullText) return segments.map((segment) => ({ segmentId: segment.segmentId }));
+	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);
+		}
 	}
-});
-//#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
-});
+	if (matches.length !== 1) throw new Error("Caption text must select a unique AudioScript range; provide explicit selections");
+	return matches;
+}
 //#endregion
 //#region src/editor/snapshot-utils.ts
 function isMap(value) {
@@ -1126,9 +2980,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);
@@ -1208,7 +3064,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",
@@ -1255,7 +3111,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",
@@ -1875,6 +3731,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 = [
@@ -2035,24 +3996,17 @@ var ManualSyncDoc = class ManualSyncDoc {
 	* Fetches the snapshot up front rather than starting empty and converging: the
 	* agent's first act is to read the document, so there is no useful state before
 	* the snapshot lands. This also fails fast and loudly on a document that does
-	* not exist or whose first snapshot is incomplete or invalid.
+	* not exist, instead of `MengineDocSession.waitForContent()`'s behavior of
+	* waiting forever for content that will never arrive.
 	*/
 	static async open(options) {
-		const response = await options.client.fetchSnapshot();
 		const doc = new LoroDoc();
-		let manualSyncDoc;
-		try {
-			if (options.peerId != null) doc.setPeerId(options.peerId);
-			if (doc.import(base64ToBytes(response.snapshot)).pending != null) throw new Error("Initial mengine snapshot has missing dependencies");
-			manualSyncDoc = new ManualSyncDoc(options.client, doc);
-			assertValidVideoDocument(manualSyncDoc.snapshot());
-			manualSyncDoc.watermark = manualSyncDoc.serverVVFrom(response.version.server_vv) ?? doc.oplogVersion();
-			return manualSyncDoc;
-		} catch (error) {
-			manualSyncDoc?.adapter.dispose();
-			doc.free();
-			throw error;
-		}
+		if (options.peerId != null) doc.setPeerId(options.peerId);
+		const response = await options.client.fetchSnapshot();
+		doc.import(base64ToBytes(response.snapshot));
+		const manualSyncDoc = new ManualSyncDoc(options.client, doc);
+		manualSyncDoc.watermark = manualSyncDoc.serverVVFrom(response.version.server_vv) ?? doc.oplogVersion();
+		return manualSyncDoc;
 	}
 	/** Current document read model (authoritative shape). */
 	snapshot() {
@@ -2071,18 +4025,31 @@ var ManualSyncDoc = class ManualSyncDoc {
 	editorPeerId() {
 		return this.doc.peerIdStr;
 	}
-	/** Current content projected into the compatible track and part read shape. */
-	content() {
+	/** Current document projected to the legacy `VideoDraft` read shape. */
+	draft() {
 		return fromVideoDocument(this.adapter.snapshot());
 	}
 	/**
+	* 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
 	* {@link hasChangedSince}.
 	*
 	* This pair replaces the legacy integer-version comparison that
 	* `DraftVersionDetector` used to tell the LLM "the draft was modified
-	* externally, reload before editing". Comparing Loro version vectors covers
-	* all collaborative edits without a business revision field in the document.
+	* externally, reload before editing". Under mengine `meta.version` never
+	* changes, so that detector would go permanently silent; comparing version
+	* vectors restores the same capability.
 	*
 	* Same capability, not a stronger one: like the legacy detector, this only
 	* reports what changed between two moments the caller chose to sample.
@@ -2166,7 +4133,6 @@ var ManualSyncDoc = class ManualSyncDoc {
 			if (serverVV != null) this.watermark = serverVV;
 			return {
 				kind: response.kind,
-				mengineUpdateSeq: response.version?.update_seq ?? response.update_seq ?? void 0,
 				updateSeq: response.update_seq ?? void 0,
 				collaborated: serverVV != null && !covers(localVersion, serverVV)
 			};
@@ -2285,7 +4251,6 @@ var SseConnection = class {
 						for (const update of event.updates) this.onUpdate(update);
 					}
 				});
-				if (!signal.aborted) this.setStatus("connecting", /* @__PURE__ */ new Error("SSE stream closed"));
 			} catch (error) {
 				if (signal.aborted) break;
 				this.setStatus("connecting", error instanceof Error ? error : new Error(String(error)));
@@ -2338,7 +4303,6 @@ var MedeoHttpDocStorage = class {
 	async getDoc(docId) {
 		this.assertDocId(docId);
 		const snapshot = await this.client.fetchSnapshot();
-		this.reportServerVersion(snapshot.version?.server_vv);
 		const now = /* @__PURE__ */ new Date();
 		return {
 			docId,
@@ -2350,7 +4314,6 @@ var MedeoHttpDocStorage = class {
 	async getDocDiff(docId, knownVersion) {
 		this.assertDocId(docId);
 		const response = await this.client.sync(knownVersion);
-		this.reportServerVersion(response.server_vv);
 		return {
 			docId,
 			missing: base64ToBytes(response.update),
@@ -2381,7 +4344,7 @@ var MedeoHttpDocStorage = class {
 		if (update.data.byteLength === 0) return {};
 		try {
 			const response = await this.client.pushUpdate(update.data);
-			const serverVV = this.reportServerVersion(response.version?.server_vv);
+			const serverVV = decodeServerVV(response.version?.server_vv);
 			this.events.emit("pushOutcome", {
 				kind: response.kind,
 				updateSeq: response.update_seq ?? void 0,
@@ -2409,15 +4372,6 @@ var MedeoHttpDocStorage = class {
 	subscribePushOutcome(callback) {
 		return this.events.on("pushOutcome", callback);
 	}
-	/** Authoritative HTTP reads and accepted pushes, never inferred from SSE bytes. */
-	subscribeServerVersion(callback) {
-		return this.events.on("serverVersion", callback);
-	}
-	reportServerVersion(encoded) {
-		const version = decodeServerVV(encoded);
-		if (version != null) this.events.emit("serverVersion", version);
-		return version;
-	}
 	async deleteDoc(_docId) {
 		throw new Error("MedeoHttpDocStorage does not support deleteDoc");
 	}
@@ -2599,15 +4553,8 @@ var MengineDocSession = class {
 	adapterValue = null;
 	editorValue = null;
 	started = false;
-	startTask = null;
-	destroyed = false;
-	lifetime = null;
-	hasConnected = false;
-	initialVersionValue = null;
-	localVersionValue = null;
-	pushErrorValue = null;
 	/**
-	* Latest server oplog version seen on an authoritative HTTP response. Lets `waitForServerAck`
+	* Latest server oplog version seen on a push outcome. Lets `waitForServerAck`
 	* return without waiting when the server is already known to cover the local
 	* doc (e.g. nothing was edited since the last confirmed push).
 	*/
@@ -2619,7 +4566,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);
@@ -2635,14 +4583,14 @@ var MengineDocSession = class {
 		return this.server.subscribePushOutcome(callback);
 	}
 	/**
-	* Resolve once the server has durably accepted the local commits as of
+	* Resolve once the server has durably accepted the local document state as of
 	* *now* — the capability an Agent tool needs to answer "did my edit land?"
 	* before reporting success.
 	*
 	* Call it right after the editor ops whose durability matters. It snapshots the
-	* latest local commit's version (or the loaded baseline before any edit) and
-	* resolves when an authoritative server version covers it. Remote-only
-	* imports do not extend this target, matching the displayed confirmation state.
+	* local doc's current version and resolves on the first push outcome whose
+	* `serverVV` covers that version, i.e. the server log is at least as advanced as
+	* the local doc was when this was called.
 	*
 	* Version coverage, not byte identity, is the acceptance test — for two reasons:
 	* the ops may reach the server inside a merged blob rather than as the exact
@@ -2657,39 +4605,31 @@ var MengineDocSession = class {
 	* @throws {MengineAckFailedError} on timeout, rejection, or transport failure.
 	*/
 	async waitForServerAck(options = {}) {
-		if (this.adapterValue == null || this.lifetime == null) throw new Error("mengine doc session is not started");
+		if (this.adapterValue == null) throw new Error("mengine doc session is not started");
 		const timeoutMs = options.timeoutMs ?? 15e3;
-		const target = this.confirmationTarget() ?? this.manager.connectDoc(this.docId).version();
-		const signal = this.lifetime.signal;
+		const target = this.manager.connectDoc(this.docId).version();
 		if (this.serverVVValue != null && serverCovers(this.serverVVValue, target)) return;
 		await new Promise((resolve, reject) => {
-			const cleanup = [];
+			let off = () => {};
 			let done = false;
 			const settle = (error) => {
 				if (done) return;
 				done = true;
 				clearTimeout(timer);
-				cleanup.forEach((off) => off());
+				off();
 				if (error == null) resolve();
 				else reject(error);
 			};
 			const timer = setTimeout(() => {
 				settle(new MengineAckFailedError("timeout", void 0, void 0, `mengine did not acknowledge the update within ${timeoutMs}ms`));
 			}, timeoutMs);
-			const onAbort = () => settle(new MengineAckFailedError("failed", void 0, void 0, "mengine doc session destroyed"));
-			signal.addEventListener("abort", onAbort, { once: true });
-			cleanup.push(() => signal.removeEventListener("abort", onAbort));
-			cleanup.push(this.events.on("syncState", () => {
-				if (this.serverVVValue != null && serverCovers(this.serverVVValue, target)) settle(void 0);
-			}));
-			cleanup.push(this.server.subscribePushOutcome((outcome) => {
+			off = this.server.subscribePushOutcome((outcome) => {
 				if (outcome.kind === "rejected" || outcome.kind === "failed") {
 					settle(new MengineAckFailedError(outcome.kind, outcome.code, outcome.error, outcome.error?.message ?? `mengine push ${outcome.kind}`));
 					return;
 				}
-			}));
-			if (signal.aborted) onAbort();
-			else this.synchronizer.requestSync(this.docId);
+				if (outcome.serverVV != null && serverCovers(outcome.serverVV, target)) settle(void 0);
+			});
 		});
 	}
 	/**
@@ -2702,6 +4642,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");
@@ -2714,100 +4672,37 @@ var MengineDocSession = class {
 	* read an initial snapshot. Remote convergence continues in the background and
 	* surfaces through `subscribe`.
 	*/
-	start() {
-		if (this.destroyed) return Promise.reject(/* @__PURE__ */ new Error("mengine doc session destroyed"));
-		if (this.startTask != null) return this.startTask;
+	async start() {
+		if (this.started) return this.snapshot();
 		this.started = true;
-		this.lifetime = new AbortController();
-		this.startTask = this.open().catch((error) => {
-			const wasDestroyed = this.destroyed;
-			this.destroy();
-			if (wasDestroyed) throw new Error("mengine doc session destroyed");
-			throw error;
-		});
-		return this.startTask;
-	}
-	async open() {
-		const signal = this.lifetime.signal;
-		this.disposables.add(() => this.local.connection.disconnect());
 		this.local.connection.connect();
-		await this.local.connection.waitForConnected().abortOn(signal);
-		const cached = await Task.spawn(() => this.local.getDoc(this.docId)).abortOn(signal);
-		const initial = cached?.data.byteLength ? void 0 : await Task.spawn(() => this.options.client.fetchSnapshot()).abortOn(signal);
-		const data = initial == null ? cached.data : base64ToBytes(initial.snapshot);
-		if (this.destroyed) throw new Error("mengine doc session destroyed");
-		this.disposables.add(this.server.subscribeServerVersion((version) => {
-			this.serverVVValue = version;
-			if (this.getSyncState().confirmation === "confirmed") this.pushErrorValue = null;
-			this.emitSyncState();
-		}));
-		this.disposables.add(this.server.subscribePushOutcome((outcome) => {
-			this.pushErrorValue = outcome.kind === "failed" || outcome.kind === "rejected" ? outcome.error ?? /* @__PURE__ */ new Error(`mengine push ${outcome.kind}`) : null;
-			this.emitSyncState();
-		}));
-		this.disposables.add(this.server.connection.onStatusChanged((status) => {
-			if (status === "connected") this.hasConnected = true;
-			this.emitSyncState();
-		}));
-		this.disposables.add(() => this.server.connection.disconnect());
 		this.server.connection.connect();
+		this.disposables.add(() => this.local.connection.disconnect());
+		this.disposables.add(() => this.server.connection.disconnect());
 		this.synchronizer.start();
 		this.manager.start();
 		this.disposables.add(() => this.synchronizer.stop());
 		this.disposables.add(() => this.manager.stop());
 		const doc = this.manager.connectDoc(this.docId);
-		this.disposables.add(() => this.manager.disconnectDoc(this.docId));
 		if (this.options.peerId != null) doc.setPeerId(this.options.peerId);
-		if (doc.import(data).pending != null) throw new Error("Initial mengine snapshot has missing dependencies");
 		this.adapterValue = new MirrorVideoDocumentAdapter(doc);
-		const adapter = this.adapterValue;
-		this.disposables.add(() => adapter.dispose());
-		assertValidVideoDocument(this.adapterValue.snapshot());
-		this.initialVersionValue = doc.version();
-		if (initial != null) this.serverVVValue = base64ToBytes(initial.version.server_vv);
 		this.editorValue = new SemanticEditor(this.adapterValue);
+		this.disposables.add(() => this.manager.disconnectDoc(this.docId));
 		const unsubscribe = doc.subscribe((event) => {
 			if (this.adapterValue == null) return;
-			if (event.by === "local") this.localVersionValue = doc.version();
-			this.emitSyncState();
 			this.events.emit("update", {
 				source: event.by === "local" ? "local" : "remote",
 				snapshot: this.adapterValue.snapshot()
 			});
 		});
 		this.disposables.add(unsubscribe);
-		this.disposables.add(this.manager.onDocStateChange(this.docId, (state) => {
-			this.events.emit("state", state);
-			this.emitSyncState();
+		this.disposables.add(this.manager.onDocStateChange(this.docId, (state) => this.events.emit("state", state)));
+		this.disposables.add(this.server.subscribePushOutcome((outcome) => {
+			if (outcome.serverVV != null) this.serverVVValue = outcome.serverVV;
 		}));
-		await this.waitForLocalLoad();
-		assertValidVideoDocument(this.snapshot());
-		this.initialVersionValue = doc.version();
-		this.emitSyncState();
+		await this.waitForContent();
 		return this.snapshot();
 	}
-	getSyncState() {
-		const state = this.getState();
-		const target = this.confirmationTarget();
-		const confirmation = this.serverVVValue == null || target == null ? this.localVersionValue == null ? "unknown" : "pending" : serverCovers(this.serverVVValue, target) ? "confirmed" : "pending";
-		const connection = !this.started ? "disconnected" : this.server.connection.status === "connected" ? "connected" : this.hasConnected || this.server.connection.error != null ? "disconnected" : "connecting";
-		return {
-			confirmation,
-			phase: connection === "disconnected" ? "offline" : this.pushErrorValue != null || state.error != null ? "failed" : connection === "connecting" ? "connecting" : state.syncing ? "syncing" : "idle"
-		};
-	}
-	confirmationTarget() {
-		return this.localVersionValue ?? this.initialVersionValue;
-	}
-	/** Immediately supplies current state; unsubscribe when the host changes docs. */
-	subscribeSyncState(cb) {
-		const off = this.events.on("syncState", cb);
-		cb(this.getSyncState());
-		return off;
-	}
-	emitSyncState() {
-		this.events.emit("syncState", this.getSyncState());
-	}
 	subscribe(cb) {
 		return this.events.on("update", cb);
 	}
@@ -2818,39 +4713,40 @@ var MengineDocSession = class {
 		return this.manager.getDocState(this.docId);
 	}
 	destroy() {
-		if (this.destroyed) return;
-		this.destroyed = true;
-		this.started = false;
-		this.lifetime?.abort();
 		this.disposables.dispose();
-		this.emitSyncState();
 		this.events.clearAll();
 		this.adapterValue = null;
 		this.editorValue = null;
 		this.started = false;
 	}
-	/** Merge persisted local edits before exposing the initial content. */
-	async waitForLocalLoad() {
-		const signal = this.lifetime.signal;
-		await new Promise((resolve, reject) => {
-			let off = () => {};
-			const finish = (error) => {
-				off();
-				signal.removeEventListener("abort", onAbort);
-				if (error != null) reject(error);
-				else resolve();
-			};
-			const onAbort = () => finish(/* @__PURE__ */ new Error("mengine doc session destroyed"));
-			const check = (state) => {
-				if (state.loaded) finish();
-				else if (state.error != null) finish(new Error(state.error));
-			};
-			off = this.onStateChange(check);
-			signal.addEventListener("abort", onAbort, { once: true });
-			if (signal.aborted) onAbort();
-			else check(this.getState());
+	/**
+	* Resolve once the Loro doc holds the document root.
+	*
+	* `DocManager` loads from local storage, which starts empty for a fresh
+	* client; the server snapshot arrives asynchronously via the first sync job.
+	* `loaded` only means the local load ran, so we wait for actual content
+	* (populated schema roots) instead, surfaced by the doc subscription set up
+	* in `start()`.
+	*/
+	async waitForContent() {
+		if (this.hasContent()) return;
+		await new Promise((resolve) => {
+			const off = this.events.on("update", () => {
+				if (this.hasContent()) {
+					off();
+					resolve();
+				}
+			});
 		});
 	}
+	hasContent() {
+		if (this.adapterValue == null) return false;
+		try {
+			return this.adapterValue.hasContent();
+		} catch {
+			return false;
+		}
+	}
 };
 /**
 * True when the *encoded* server version `serverVV` includes everything in
@@ -2874,4 +4770,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, ENTITY_TIMELINE_PROJECTION_SCHEMA_VERSION, EntityGraphHttpClient, EntityTimelineEditor, EntityTimelineProjectionError, IMPLEMENTED_SEMANTIC_OP_KINDS, LANE_KINDS_IN_STACK_ORDER, ManualSyncDoc, MedeoHttpDocStorage, MemoryDocStorage, MengineAckFailedError, MengineDocSession, MengineHttpClient, MengineHttpRequestError, MenginePushRejectedError, MirrorVideoDocumentAdapter, PlainMemoryAdapter, SchemaValidator, ScriptCompositionError, SemanticEditor, TIMELINE_SKELETON_DURATION_MS, VIDEO_DOCUMENT_SCHEMA_VERSION, ValidationError, VideoDocumentValidationError, applyEntityTimelineProjection, arrangeMainTrackSeamlessly, assembleCaptionContent, assembleEntityContent, assemblePhoneticScriptContent, assembleScriptText, assertCanonicalEditorResources, assertEntityProjectionPreservesLegacy, assertMediaAssetWritePolicy, assertValidVideoDocument, base64ToBytes, buildInitialVideoDocument, buildSpeechHostMap, bytesToBase64, cascadeAfterVideoClipChanges, createEditSandbox, createMirrorVideoDocument, createMirrorVideoDocumentAdapter, createPlainMemoryAdapter, decodeDocVersionMark, derivePositionFromAbs, effectiveVideoClipDurationMs, encodeDocVersionMark, ensureEditorFoundation, ensureLaneTrack, fillMainTrackTimeGaps, findComposedAudioScript, findLaneTrack, fromVideoDocument, generatePartId, getAt, hostForAbsMs, importMediaAsset, isEmptyVideoClip, isImplementedSemanticOpKind, isMap, laneTrackId, mainTrackRanges, migrateLegacyTimelineToEntities, partDurationMs, partUnionSchema, prepareCaptionContent, projectEntityTimeline, readMainTrackItems, readMengineEventStream, readPart, readPartDurationMs, readVideoDocumentFromDraft, reassignSpeechesToVideoClipsByTime, recalculateTimelineDuration, relativePositionForAbs, replayJournal, resolveAllSpeechOverlaps, resolveEntityTimelineLayout, resolveSpeechOverlapByShiftingVideos, safeDurationMs, schemas_exports as schemas, selectAudioScriptSegments, snapshotToPlain, solveVideoDocument, speedOf, syncAggregatedClipsTimePosition, toVideoDocument, validateVideoDocument, videoDocumentMirrorSchema, videoDocumentSchema, writeVideoDocumentToDraft };