@mengine/medeo-client 2.1.0 → 2.1.1-dsl.0

package/dist/index.js

@@ -1,2538 +1,63 @@
-import { t as __exportAll } from "./chunk-D7D4PA-g.js";
-import { A as isEmptyVideoClip, C as fillMainTrackTimeGaps, D as resolveSpeechOverlapByShiftingVideos, E as resolveAllSpeechOverlaps, F as partUnionToDraft, I as recordEntries, L as videoDocumentMirrorSchema, M as safeDurationMs, N as DEFAULT_UNIT_TIME_MS, O as syncAggregatedClipsTimePosition, P as effectiveVideoClipDurationMs, R as base64ToBytes, S as arrangeMainTrackSeamlessly, T as recalculateTimelineDuration, _ as ensureLaneTrack, a as DocumentMutationGuard, b as solveVideoDocument, c as derivePositionFromAbs, d as VideoDocumentValidationError, f as assertValidVideoDocument, g as LANE_KINDS_IN_STACK_ORDER, h as videoDocumentSchema, i as readVideoDocumentFromDraft, j as partDurationMs, k as TIMELINE_SKELETON_DURATION_MS, l as fromVideoDocument, m as partUnionSchema, n as createMirrorVideoDocument, o as buildInitialVideoDocument, p as validateVideoDocument, r as createMirrorVideoDocumentAdapter, s as buildSpeechHostMap, t as MirrorVideoDocumentAdapter, u as toVideoDocument, v as findLaneTrack, w as reassignSpeechesToVideoClipsByTime, x as cascadeAfterVideoClipChanges, y as laneTrackId, z as bytesToBase64 } from "./document-B_JQwrC5.js";
-import { z } from "zod";
-import { LoroDoc, UndoManager, VersionVector, decodeImportBlobMeta } from "loro-crdt";
+import { n as bytesToBase64, t as base64ToBytes } from "./base64-D-jd-dr5.js";
+import { a as covers, c as readMengineEventStream, d as MenginePushRejectedError, i as openManualDocument, l as MengineHttpClient, n as MedeoHttpDocStorage, o as decodeDocVersionMark, r as ManualSyncTransport, s as encodeDocVersionMark, t as MemoryDocStorage, u as MengineHttpRequestError } from "./storage-BW3tI_ER.js";
+import { C as resourceId, S as relationId, a as documentFormat, c as isInvalidAtomic, i as assertDslDocument, l as timeAnchorCodec, o as medeoDslLoroShape, r as UnsupportedDocumentFormatError, s as captionContentCodec, t as DEFAULT_UNIT_TIME_MS, w as tupleHash, x as defaultIdFactory } from "./video-draft-types-DTXxvPt-.js";
+import { a as MedeoDsl, i as DslEditor, n as toVideoDraft, o as resolveDslLayout, r as createInitialMedeoDsl, s as DslProjectionError, t as fromVideoDraft } from "./dsl-Dkecq_2c.js";
+import { UndoManager, VersionVector } from "loro-crdt";
 import { ClientServerSynchronizer, DocManager } from "@mengine/sync";
-import { DisposableSet, EventBus, Task } from "@mengine/utils";
-import { BaseDocStorage, DummyConnection } from "@mengine/storage";
-//#region src/client/http-client.ts
-/**
-* Public route prefix of the mengine doc-collaboration API. Must stay in lockstep
-* with `apps/mengine-server`'s `API_PREFIX` — the two form the private wire
-* contract between this client and the relay server. Versioned, mengine-owned
-* 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";
-var MengineHttpRequestError = class extends Error {
-	status;
-	payload;
-	constructor(status, payload) {
-		super(`mengine request failed: ${status}`);
-		this.status = status;
-		this.payload = payload;
-		this.name = "MengineHttpRequestError";
-	}
-};
-/**
-* A push the server refused on its merits (`kind: 'rejected'`), as opposed to a
-* transport failure. Carries the server's machine `code` so callers can branch on
-* *why* rather than on an HTTP status:
-*
-* - `missing_dependency` (server answers 409) — retryable: the update depends on
-*   ops the server log lacks, so catching up and re-exporting resolves it.
-* - `corrupt_update` (server answers 422) — never valid, retrying cannot help.
-*
-* Distinct from {@link MengineHttpRequestError} (transport/status-level failure)
-* and from a raw `fetch` rejection (network down): the three are separate classes
-* so a caller can tell "the server said no" from "the server never answered".
-*/
-var MenginePushRejectedError = class extends Error {
-	code;
-	serverMessage;
-	serverVersion;
-	status;
-	constructor(code, serverMessage, serverVersion, status) {
-		super(`mengine rejected update: ${code}: ${serverMessage}`);
-		this.code = code;
-		this.serverMessage = serverMessage;
-		this.serverVersion = serverVersion;
-		this.status = status;
-		this.name = "MenginePushRejectedError";
-	}
-};
-var MengineHttpClient = class {
-	options;
-	fetchImpl;
-	constructor(options) {
-		this.options = options;
-		this.fetchImpl = options.fetchImpl ?? globalThis.fetch.bind(globalThis);
-	}
-	async fetchSnapshot() {
-		return await this.requestJson("snapshot");
-	}
-	/**
-	* Loro VV-diff pull: send the caller's oplog `VersionVector.encode` as `from`
-	* (omit for a full pull) and receive exactly the updates it is missing plus
-	* the server's current VV. Replaces the old integer `after_update_id` cursor.
-	*/
-	async sync(fromVV) {
-		const query = fromVV != null ? `?from=${encodeURIComponent(bytesToBase64(fromVV))}` : "";
-		return await this.requestJson(`sync${query}`);
-	}
-	/** Audit trail: extracted metadata per accepted update, in log order. */
-	async audit() {
-		return await this.requestJson("audit");
-	}
-	/**
-	* Append one Loro update to the server log.
-	*
-	* Resolves for both accepted outcomes and hands the verdict back verbatim —
-	* `ack` (appended, `update_seq` allocated) and `duplicate` (already known, no
-	* row appended). A `duplicate` is NOT an error, but it is also not an ack: it
-	* means the bytes contributed nothing, so a caller waiting for its own write to
-	* land must be able to tell them apart. Hence the verdict is returned rather
-	* than collapsed into `void`.
-	*
-	* Rejections raise {@link MenginePushRejectedError} carrying the server's
-	* machine `code`. The server answers them with 409/422, so the failure arrives
-	* as a non-ok response; this method re-reads the parsed body to recover `code` /
-	* `server_version` instead of leaving the caller a bare status. Transport-level
-	* failures stay {@link MengineHttpRequestError}, and a dead network keeps
-	* surfacing as the underlying `fetch` rejection.
-	*/
-	async pushUpdate(update) {
-		let response;
-		try {
-			response = await this.requestJson("updates", {
-				method: "POST",
-				body: JSON.stringify({ update: bytesToBase64(update) })
-			});
-		} catch (error) {
-			throw asPushRejection(error) ?? error;
-		}
-		if (response.kind === "rejected") throw new MenginePushRejectedError(response.code, response.message, response.server_version, void 0);
-		return response;
-	}
-	eventsUrl() {
-		return this.endpoint("events");
-	}
-	headers() {
-		const headers = new Headers();
-		headers.set("accept", "application/json");
-		headers.set("content-type", "application/json");
-		const authToken = typeof this.options.authToken === "function" ? this.options.authToken() : this.options.authToken;
-		if (authToken != null && authToken !== "") headers.set("authorization", `Bearer ${authToken}`);
-		const userId = typeof this.options.userId === "function" ? this.options.userId() : this.options.userId;
-		if (userId != null && userId !== "") headers.set("medeo-user-id", userId);
-		return headers;
-	}
-	async fetch(input, init) {
-		return await this.fetchImpl(input, init);
-	}
-	async requestJson(path, init = {}) {
-		const headers = this.headers();
-		new Headers(init.headers).forEach((value, key) => {
-			headers.set(key, value);
-		});
-		const response = await this.fetchImpl(this.endpoint(path), {
-			...init,
-			headers
-		});
-		const payload = await safeReadJson(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}`;
-	}
-};
-/**
-* Recover a typed rejection from a failed request: the server sends `rejected`
-* bodies with a 409/422 status, so they surface as {@link MengineHttpRequestError}
-* whose payload still carries the machine `code`. Returns `undefined` for any
-* other failure so the caller rethrows the original.
-*/
-function asPushRejection(error) {
-	if (!(error instanceof MengineHttpRequestError)) return void 0;
-	const payload = error.payload;
-	if (payload == null || typeof payload !== "object") return void 0;
-	const body = payload;
-	if (body.kind !== "rejected" || typeof body.code !== "string") return void 0;
-	return new MenginePushRejectedError(body.code, body.message ?? "", body.server_version, error.status);
-}
-async function safeReadJson(response) {
-	const text = await response.text();
-	if (text.length === 0) return null;
-	try {
-		return JSON.parse(text);
-	} catch {
-		return text;
-	}
-}
-//#endregion
-//#region src/client/sse.ts
-async function readMengineEventStream(options) {
-	const response = await options.client.fetch(options.client.eventsUrl(), {
-		headers: options.client.headers(),
-		signal: options.signal
-	});
-	if (!response.ok) throw new Error(`mengine event stream failed: ${response.status}`);
-	const reader = response.body?.getReader();
-	if (reader == null) throw new Error("mengine event stream response has no readable body");
-	options.onOpen?.();
-	const decoder = new TextDecoder();
-	let buffer = "";
-	while (options.signal?.aborted !== true) {
-		const { done, value } = await reader.read();
-		if (done) return;
-		buffer += decoder.decode(value, { stream: true });
-		let splitAt = findSseFrameBoundary(buffer);
-		while (splitAt >= 0) {
-			const frame = buffer.slice(0, splitAt);
-			buffer = buffer.slice(buffer[splitAt] === "\r" ? splitAt + 4 : splitAt + 2);
-			handleSseFrame(frame, options);
-			splitAt = findSseFrameBoundary(buffer);
-		}
-	}
-}
-function handleSseFrame(frame, options) {
-	const event = parseSseFrame(frame);
-	if (event.event === "resync") {
-		options.onResync?.();
-		return;
-	}
-	if (event.event !== "update" || event.data.length === 0) return;
-	options.onUpdate(JSON.parse(event.data.join("\n")));
-}
-function parseSseFrame(frame) {
-	let event = null;
-	const data = [];
-	for (const line of frame.split(/\r?\n/)) if (line.startsWith("event:")) event = line.slice(6).trim();
-	else if (line.startsWith("data:")) data.push(line.slice(5).trimStart());
-	return {
-		event,
-		data
-	};
-}
-function findSseFrameBoundary(buffer) {
-	const lf = buffer.indexOf("\n\n");
-	const crlf = buffer.indexOf("\r\n\r\n");
-	if (lf < 0) return crlf;
-	if (crlf < 0) return lf;
-	return Math.min(lf, crlf);
-}
-//#endregion
-//#region src/editor/id-gen.ts
-/**
-* Part-id generation, aligned with the online ecosystem.
-*
-* The authoritative online producers — agent-harness (`@harness/shared`
-* `genObjId`) and director.v2 (`common/obj_id.py` `gen_obj_id`) — both mint part
-* ids as `` `${prefix}_${ulid()}` ``, and real captured drafts use exactly that
-* shape (`clip_…` / `spe_…` / `cap_…` / `bgm_…`, each a 26-char ULID). The engine
-* previously emitted `vc_<base36 timestamp><6 random>`, a different prefix AND a
-* different encoding — the sole cross-repo id divergence. This module removes it
-* by emitting the same `<prefix>_<ULID>` bytes.
-*
-* The ULID is generated inline (Crockford Base32, 48-bit time + 80-bit random)
-* rather than pulling the `ulid` npm package: the randomness class matches the
-* old generator (both `Math.random`-based) and it keeps `@mengine/medeo-client`
-* dependency-free for a purely mechanical id string. Part ids only need to be
-* unique and lexicographically time-sortable, which this satisfies.
-*/
-/** Crockford Base32 alphabet (no I, L, O, U), per the ULID spec. */
-const CROCKFORD = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
-const TIME_LEN = 10;
-const RANDOM_LEN = 16;
-function encodeTime(now) {
-	let out = "";
-	let ms = now;
-	for (let i = TIME_LEN - 1; i >= 0; i--) {
-		const mod = ms % 32;
-		out = CROCKFORD[mod] + out;
-		ms = (ms - mod) / 32;
-	}
-	return out;
-}
-function encodeRandom() {
-	let out = "";
-	for (let i = 0; i < RANDOM_LEN; i++) out += CROCKFORD[Math.floor(Math.random() * 32)];
-	return out;
-}
-/** A 26-char Crockford Base32 ULID (10-char time + 16-char random). */
-function ulid() {
-	return encodeTime(Date.now()) + encodeRandom();
-}
-function generatePartId(prefix) {
-	return `${prefix}_${ulid()}`;
-}
-//#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"
-			]
-		});
-	}
-});
-//#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
-});
-//#endregion
-//#region src/editor/snapshot-utils.ts
-function isMap(value) {
-	return value instanceof Map;
-}
-function snapshotToPlain(value) {
-	if (value instanceof Map) {
-		const obj = {};
-		for (const [k, v] of value) obj[String(k)] = snapshotToPlain(v);
-		return obj;
-	}
-	if (Array.isArray(value)) return value.map(snapshotToPlain);
-	return value;
-}
-function getAt(snapshot, ...keys) {
-	let cur = snapshot;
-	for (const k of keys) if (cur instanceof Map) cur = cur.get(k);
-	else if (cur != null && typeof cur === "object") cur = cur[k];
-	else return;
-	return cur;
-}
-function readMainTrackItems(snapshot) {
-	const tracks = getAt(snapshot, "tracks");
-	const items = getAt(Array.isArray(tracks) ? tracks.find((t) => getAt(t, "parts_kind") === "video_clip") : void 0, "items");
-	if (!Array.isArray(items)) return [];
-	return items.map((item) => {
-		if (item instanceof Map) return { part_id: optionalString(item.get("part_id")) };
-		if (item != null && typeof item === "object") return { part_id: optionalString(item.part_id) };
-		return { part_id: void 0 };
-	});
-}
-/**
-* The effective timeline duration of a part read from a raw snapshot. No part
-* stores a derived `duration_ms` in authoritative state (reference/17 §5): a
-* video clip's length is its trim window `play_out - play_in` over the speed
-* multiplier; a speech's is its intrinsic `media_duration_ms`; a caption's is its
-* `initial_duration_ms`. Falls back to `fallback` when no source value is
-* resolvable (e.g. an unknown/raw part).
-*/
-function readPartDurationMs(snapshot, partId, fallback = 1e3) {
-	const part = readPart(snapshot, partId);
-	if (part == null) return fallback;
-	let sourceMs;
-	if (part.part_kind === "video_clip") {
-		const playIn = numericValue(part.play_in);
-		const playOut = numericValue(part.play_out);
-		if (playIn != null && playOut != null) {
-			const speed = videoClipSpeed(part.speed_shift);
-			sourceMs = Math.round((playOut - playIn) / speed);
-		}
-	} else if (part.part_kind === "speech") sourceMs = numericValue(part.media_duration_ms);
-	else if (part.part_kind === "caption") sourceMs = numericValue(part.initial_duration_ms);
-	return sourceMs != null && Number.isFinite(sourceMs) ? sourceMs : fallback;
-}
-function numericValue(value) {
-	return typeof value === "number" && Number.isFinite(value) ? value : void 0;
-}
-/** The linear speed multiplier of a raw `speed_shift` blob, defaulting to 1. */
-function videoClipSpeed(speedShift) {
-	const speed = speedShift?.config?.linear?.speed;
-	return typeof speed === "number" && Number.isFinite(speed) && speed > 0 ? speed : 1;
-}
-function readPart(snapshot, partId) {
-	const part = getAt(snapshot, "part_library", partId);
-	if (part == null) return null;
-	const plain = snapshotToPlain(part);
-	if ("video_clip" in plain && plain.video_clip != null) return {
-		...plain.video_clip,
-		part_kind: "video_clip"
-	};
-	if ("speech" in plain && plain.speech != null) return {
-		...plain.speech,
-		part_kind: "speech"
-	};
-	if ("caption" in plain && plain.caption != null) return {
-		...plain.caption,
-		part_kind: "caption"
-	};
-	if ("bgm" in plain && plain.bgm != null) return {
-		...plain.bgm,
-		part_kind: "bgm"
-	};
-	return plain;
-}
-function optionalString(value) {
-	return typeof value === "string" ? value : void 0;
-}
-//#endregion
-//#region src/editor/schema-validator.ts
-var ValidationError = class extends Error {
-	code;
-	context;
-	constructor(code, message, context) {
-		super(`[${code}] ${message}`);
-		this.name = "ValidationError";
-		this.code = code;
-		this.context = context;
-	}
-};
-var SchemaValidator = class {
-	validateMoveVideoClips(input, doc) {
-		const parsed = this.parse(moveVideoClipsInputSchema, input, "move_invalid_input");
-		const knownIds = this.mainTrackIds(doc);
-		for (const clip of parsed.clips) if (!knownIds.has(clip.clip_id)) throw new ValidationError("move_clip_not_found", `clip_id "${clip.clip_id}" not present on main_track`, { clip_id: clip.clip_id });
-	}
-	/**
-	* The anchor must not be one of the clips being moved. Unlike the schema's
-	* mutual exclusions this needs the input read as a whole, so it stays here.
-	*
-	* Rejected rather than normalized: "put this block before itself" has no
-	* defensible outcome — treating it as a no-op hides a caller bug behind a
-	* success, and picking any surviving neighbour invents an intent. The legacy
-	* `applyBatchMoveVideoClips` omits this check (a self-anchor there silently
-	* lands the block at its own pre-move index); director's original move tool
-	* did enforce it (`_validate_position`: "不是被移动的clips"), and that is the
-	* behaviour worth keeping.
-	*/
-	validateMoveVideoClipsByAnchor(input, doc) {
-		const parsed = this.parse(moveVideoClipsByAnchorInputSchema, input, "move_by_anchor_invalid_input");
-		const knownIds = this.mainTrackIds(doc);
-		for (const clipId of parsed.clip_ids) if (!knownIds.has(clipId)) throw new ValidationError("move_by_anchor_clip_not_found", `clip_id "${clipId}" not present on main_track`, { clip_id: clipId });
-		if (parsed.anchor.position === "track_start") return;
-		const anchorId = parsed.anchor.clip_id;
-		if (!knownIds.has(anchorId)) throw new ValidationError("move_by_anchor_anchor_not_found", `anchor clip_id "${anchorId}" not present on main_track`, { anchor_clip_id: anchorId });
-		if (parsed.clip_ids.includes(anchorId)) throw new ValidationError("move_by_anchor_anchor_is_moved", `anchor clip_id "${anchorId}" is itself being moved`, { anchor_clip_id: anchorId });
-	}
-	validateDeleteVideoClips(input, doc) {
-		const parsed = this.parse(deleteVideoClipsInputSchema, input, "delete_invalid_input");
-		const knownIds = this.mainTrackIds(doc);
-		for (const id of parsed.clip_ids) if (!knownIds.has(id)) throw new ValidationError("delete_clip_not_found", `clip_id "${id}" not present on main_track`, { clip_id: id });
-	}
-	validateAddVideoClips(input, doc) {
-		const parsed = this.parse(addVideoClipsInputSchema, input, "add_invalid_input");
-		const knownIds = this.mainTrackIds(doc);
-		if (parsed.before_clip_id != null && !knownIds.has(parsed.before_clip_id)) throw new ValidationError("add_before_clip_not_found", `before_clip_id "${parsed.before_clip_id}" not on main_track`, { before_clip_id: parsed.before_clip_id });
-		if (parsed.after_clip_id != null && !knownIds.has(parsed.after_clip_id)) throw new ValidationError("add_after_clip_not_found", `after_clip_id "${parsed.after_clip_id}" not on main_track`, { after_clip_id: parsed.after_clip_id });
-	}
-	validateAdjustVideoClipVolume(input, doc) {
-		const parsed = this.parse(adjustVideoClipVolumeInputSchema, input, "adjust_volume_invalid_input");
-		const snapshot = doc.snapshot();
-		for (const c of parsed.clips) this.assertPartKind(snapshot, c.clip_id, "video_clip", "adjust_volume");
-	}
-	validateSetVideoClipSpeedShift(input, doc) {
-		const parsed = this.parse(setVideoClipSpeedShiftInputSchema, input, "set_speed_invalid_input");
-		const snapshot = doc.snapshot();
-		for (const c of parsed.clips) this.assertPartKind(snapshot, c.clip_id, "video_clip", "set_speed");
-	}
-	validateReplaceVideoClipContent(input, doc) {
-		const parsed = this.parse(replaceVideoClipContentInputSchema, input, "replace_content_invalid_input");
-		const snapshot = doc.snapshot();
-		for (const c of parsed.clips) {
-			this.assertPartKind(snapshot, c.clip_id, "video_clip", "replace_content");
-			if (c.play_in >= c.play_out || c.play_out > c.media_duration_ms) throw new ValidationError("replace_content_invalid_window", `trim window [${c.play_in}, ${c.play_out}] must be non-empty and within media_duration_ms ${c.media_duration_ms}`, {
-				clip_id: c.clip_id,
-				play_in: c.play_in,
-				play_out: c.play_out,
-				media_duration_ms: c.media_duration_ms
-			});
-		}
-	}
-	/**
-	* `old_clip_ids` must name a **contiguous run of the main track, in track
-	* order**. A sparse or reordered selection is rejected rather than normalized:
-	* a sparse selection has no single stretch to swap, so the insert index, the
-	* positional speech remap, and the resulting order would each need a different
-	* arbitrary choice. Mirrors the agent tool's own contract ("must be a
-	* contiguous main-track sequence listed in timeline order").
-	*/
-	validateReplaceVideoClipSequence(input, doc) {
-		const parsed = this.parse(replaceVideoClipSequenceInputSchema, input, "replace_sequence_invalid_input");
-		const items = readMainTrackItems(doc.snapshot());
-		const indexById = new Map(items.map((it, index) => [it.part_id, index]));
-		const indices = [];
-		for (const clipId of parsed.old_clip_ids) {
-			const index = indexById.get(clipId);
-			if (index == null) throw new ValidationError("replace_sequence_clip_not_found", `clip_id "${clipId}" not present on main_track`, { clip_id: clipId });
-			indices.push(index);
-		}
-		for (let i = 1; i < indices.length; i++) if (indices[i] !== (indices[i - 1] ?? 0) + 1) throw new ValidationError("replace_sequence_not_contiguous", `old_clip_ids must be a contiguous main-track run in track order, got indices [${indices.join(", ")}]`, { indices });
-	}
-	validateAdjustVideoClipDuration(input, doc) {
-		const parsed = this.parse(adjustVideoClipDurationInputSchema, input, "adjust_duration_invalid_input");
-		const snapshot = doc.snapshot();
-		for (const c of parsed.clips) {
-			this.assertPartKind(snapshot, c.clip_id, "video_clip", "adjust_duration");
-			if (c.play_out <= c.play_in) throw new ValidationError("adjust_duration_invalid_window", `play_out must be greater than play_in`, {
-				clip_id: c.clip_id,
-				play_in: c.play_in,
-				play_out: c.play_out
-			});
-		}
-	}
-	validateAdjustSpeechVolume(input, doc) {
-		const parsed = this.parse(adjustSpeechVolumeInputSchema, input, "adjust_speech_volume_invalid_input");
-		const snapshot = doc.snapshot();
-		for (const s of parsed.speeches) this.assertPartKind(snapshot, s.speech_id, "speech", "adjust_speech_volume");
-	}
-	validateAdjustBgmVolume(input, doc) {
-		const parsed = this.parse(adjustBgmVolumeInputSchema, input, "adjust_bgm_volume_invalid_input");
-		const snapshot = doc.snapshot();
-		for (const b of parsed.bgm) this.assertPartKind(snapshot, b.bgm_id, "bgm", "adjust_bgm_volume");
-	}
-	validateAddSpeeches(input, doc) {
-		const parsed = this.parse(addSpeechesInputSchema, input, "add_speeches_invalid_input");
-		this.assertCaptionsOwned(parsed, "add_speeches");
-		this.assertAnchorsExist(parsed, doc, "add_speeches");
-	}
-	validateChangeSpeechScript(input, doc) {
-		const parsed = this.parse(changeSpeechScriptInputSchema, input, "change_script_invalid_input");
-		this.assertCaptionsOwned(parsed, "change_script");
-		this.assertSpeechesExist(parsed, doc, "change_script");
-		this.assertAnchorsExist(parsed, doc, "change_script");
-	}
-	validateChangeSpeechVoice(input, doc) {
-		const parsed = this.parse(changeSpeechVoiceInputSchema, input, "change_voice_invalid_input");
-		this.assertCaptionsOwned(parsed, "change_voice");
-		this.assertSpeechesExist(parsed, doc, "change_voice");
-		this.assertAnchorsExist(parsed, doc, "change_voice");
-	}
-	validateDeleteSpeeches(input, doc) {
-		const parsed = this.parse(deleteSpeechesInputSchema, input, "delete_speeches_invalid_input");
-		const snapshot = doc.snapshot();
-		for (const id of parsed.speech_ids) this.assertPartKind(snapshot, id, "speech", "delete_speeches");
-	}
-	validateMoveSpeeches(input, doc) {
-		const parsed = this.parse(moveSpeechesInputSchema, input, "move_speeches_invalid_input");
-		const snapshot = doc.snapshot();
-		for (const s of parsed.speeches) this.assertPartKind(snapshot, s.speech_id, "speech", "move_speeches");
-	}
-	validateSetBgm(input, _doc) {
-		this.parse(setBgmInputSchema, input, "set_bgm_invalid_input");
-	}
-	validateDeleteBgm(input, _doc) {
-		this.parse(deleteBgmInputSchema, input, "delete_bgm_invalid_input");
-	}
-	validateSetCaptionVisibility(input, _doc) {
-		this.parse(setCaptionVisibilityInputSchema, input, "set_caption_visibility_invalid_input");
-	}
-	validateSetCaptionStyle(input, _doc) {
-		this.parse(setCaptionStyleInputSchema, input, "set_caption_style_invalid_input");
-	}
-	parse(schema, input, code) {
-		const parsed = schema.safeParse(input);
-		if (!parsed.success) throw new ValidationError(code, parsed.error.message, { issues: parsed.error.issues });
-		return parsed.data;
-	}
-	mainTrackIds(doc) {
-		const items = readMainTrackItems(doc.snapshot());
-		return new Set(items.map((it) => it.part_id).filter((id) => id != null));
-	}
-	/** Every caption a speech declares in `caption_ids` must be supplied in `captions`. */
-	assertCaptionsOwned(assets, opName) {
-		const supplied = new Set(assets.captions.map((c) => c.caption_id));
-		for (const speech of assets.speeches) for (const captionId of speech.caption_ids) if (!supplied.has(captionId)) throw new ValidationError(`${opName}_caption_not_supplied`, `speech declares caption not in payload`, {
-			speech_id: speech.speech_id,
-			caption_id: captionId
-		});
-	}
-	/** Each regenerated speech (re-TTS) must already exist in the document. */
-	assertSpeechesExist(assets, doc, opName) {
-		const snapshot = doc.snapshot();
-		for (const speech of assets.speeches) this.assertPartKind(snapshot, speech.speech_id, "speech", opName);
-	}
-	/**
-	* Each speech's `anchor_part_id` must point at a video clip that already
-	* exists. A relative speech anchored to a missing clip cannot be positioned
-	* by the projection and has no host to recover to (RFC 02 §4/§11.1), so the
-	* write must be rejected rather than landing a dangling reference. (Restores
-	* the dangling-reference guard the old `validateMaterializedPatch` carried;
-	* ADR 0009.)
-	*/
-	assertAnchorsExist(assets, doc, opName) {
-		const snapshot = doc.snapshot();
-		for (const speech of assets.speeches) this.assertPartKind(snapshot, speech.anchor_part_id, "video_clip", `${opName}_anchor`);
-	}
-	assertPartKind(snapshot, partId, kind, opName) {
-		const part = readPart(snapshot, partId);
-		if (part == null) throw new ValidationError(`${opName}_part_not_found`, `part_library has no entry for "${partId}"`, { part_id: partId });
-		if (part.part_kind !== kind) throw new ValidationError(`${opName}_wrong_part_kind`, `part_id "${partId}" is kind "${String(part.part_kind)}", expected "${kind}"`, {
-			part_id: partId,
-			part_kind: part.part_kind
-		});
-	}
-};
-//#endregion
-//#region src/timeline-core/locate.ts
-/**
-* The flow-ordered main-track clip ranges (cumulative effective durations from
-* 0). Empty-media gap fillers are not in authoritative state, so this reflects
-* only the real clips the draft stores.
-*/
-function mainTrackRanges(draft) {
-	const partLibrary = readPartLibrary(draft);
-	const items = (draft.tracks ?? []).find((t) => t?.parts_kind === "video_clip")?.items ?? [];
-	const ranges = [];
-	let cursor = 0;
-	for (const item of items) {
-		const partId = item?.part_id;
-		if (partId == null) continue;
-		const clip = partLibrary[partId]?.video_clip;
-		if (clip == null) continue;
-		const durationMs = effectiveVideoClipDurationMs(clip);
-		ranges.push({
-			partId,
-			startMs: cursor,
-			endMs: cursor + durationMs
-		});
-		cursor += durationMs;
-	}
-	return ranges;
-}
-/**
-* Pick the host video clip an absolute time lands in, with the harness two-sided
-* fallback: before the first clip → first clip; after the last → last clip.
-* Returns null only when there is no clip at all (caller leaves the item as-is).
-*/
-function hostForAbsMs(ranges, absMs) {
-	if (ranges.length === 0) return null;
-	const hit = ranges.find((r) => r.startMs <= absMs && absMs < r.endMs);
-	if (hit != null) return hit;
-	return absMs < ranges[0].startMs ? ranges[0] : ranges[ranges.length - 1];
-}
-/**
-* Build an `anchored` time position anchoring `absMs` to the host clip it lands
-* in (offset clamped to a non-negative integer). Falls back to `absolute` when
-* there is no host clip. Pair with `fallbackAbsMs = absMs` on the item.
-*/
-function relativePositionForAbs(ranges, absMs) {
-	const host = hostForAbsMs(ranges, absMs);
-	if (host == null) return {
-		mode: "absolute",
-		offsetMs: Math.round(absMs)
-	};
-	return {
-		mode: "anchored",
-		anchorPartId: host.partId,
-		offsetMs: Math.max(0, Math.round(absMs - host.startMs))
-	};
-}
-function readPartLibrary(draft) {
-	const out = {};
-	for (const [partId, part] of recordEntries(draft.part_library)) if (part != null) out[partId] = part;
-	return out;
-}
-//#endregion
-//#region src/editor/semantic-editor.ts
-var SemanticEditor = class {
-	doc;
-	validator;
-	constructor(doc, validator = new SchemaValidator()) {
-		this.doc = doc;
-		this.validator = validator;
-	}
-	async moveVideoClips(input, options) {
-		this.validator.validateMoveVideoClips(input, this.doc);
-		this.doc.transact((draft) => {
-			const items = mainTrackItems(draft);
-			if (items == null) return;
-			const beforeRanges = mainTrackRanges(draft);
-			for (const clip of input.clips) {
-				const layout = this.computeMainTrackLayout(draft);
-				const fromItem = layout.find((it) => it.part_id === clip.clip_id);
-				if (fromItem == null) throw new Error(`moveVideoClips: clip "${clip.clip_id}" disappeared mid-batch`);
-				const toIndex = this.indexForStartMs(layout, clip.new_start_ms, fromItem.index);
-				if (toIndex === fromItem.index) continue;
-				moveItem(items, fromItem.index, toIndex);
-			}
-			reparentSpeechesAfterMainTrackChange(draft, beforeRanges);
-		}, audit("MoveVideoClips", input, options));
-	}
-	/**
-	* Reorder main-track clips relative to an anchor clip, moving them as one block.
-	*
-	* The ordinal sibling of `moveVideoClips`: main-track clips are
-	* `sequential`-positioned, so their order is the authoritative fact and absolute
-	* time is derived on read (RFC 02 §4/§7). A caller that already knows "put these
-	* after that one" should say so, instead of computing a timeline offset that this
-	* editor would only have to resolve back into an index.
-	*
-	* `on_anchored` decides the speech treatment and is required. Note the asymmetry
-	* in cost: `follow` writes nothing to the speeches (their `{ anchorPartId,
-	* offsetMs }` facts stay valid and the derived absolute time moves with the host),
-	* while `keep_absolute` runs the extra re-parent pass that preserves each
-	* speech's absolute landing. `moveVideoClips` is permanently `keep_absolute`,
-	* matching the FE timeline it serves.
-	*/
-	async moveVideoClipsByAnchor(input, options) {
-		this.validator.validateMoveVideoClipsByAnchor(input, this.doc);
-		this.doc.transact((draft) => {
-			const items = mainTrackItems(draft);
-			if (items == null) return;
-			const beforeRanges = mainTrackRanges(draft);
-			const targets = new Set(input.clip_ids);
-			const movedIndices = [];
-			for (let i = 0; i < items.length; i++) {
-				const partId = items[i]?.part_id;
-				if (partId != null && targets.has(partId)) movedIndices.push(i);
-			}
-			if (movedIndices.length === 0) return;
-			const insertIndex = anchorInsertIndex(items, input.anchor);
-			const moved = movedIndices.map((index) => items[index]);
-			for (let i = movedIndices.length - 1; i >= 0; i--) items.splice(movedIndices[i], 1);
-			const removedBefore = movedIndices.filter((index) => index < insertIndex).length;
-			items.splice(insertIndex - removedBefore, 0, ...moved);
-			if (input.on_anchored === "keep_absolute") reparentSpeechesAfterMainTrackChange(draft, beforeRanges);
-			else refreshAnchoredFallbackAbs(draft);
-		}, audit("MoveVideoClipsByAnchor", input, options));
-	}
-	async deleteVideoClips(input, options) {
-		this.validator.validateDeleteVideoClips(input, this.doc);
-		const targets = new Set(input.clip_ids);
-		const policy = input.on_anchored ?? "cascade";
-		this.doc.transact((draft) => {
-			const track = mainTrackRow(draft);
-			if (track?.items == null) return;
-			if (policy === "detach") for (const clipId of targets) detachAnchoredChildren(draft, clipId);
-			track.items = track.items.filter((item) => item.part_id == null || !targets.has(item.part_id));
-			for (const clipId of targets) {
-				if (policy === "cascade") deleteAnchoredSubtree(draft, clipId);
-				deletePart(draft, clipId);
-			}
-		}, audit("DeleteVideoClips", input, options));
-	}
-	async addVideoClips(input, options) {
-		this.validator.validateAddVideoClips(input, this.doc);
-		const insertIndex = this.computeAddInsertIndex(input);
-		this.doc.transact((draft) => {
-			const track = ensureMainTrack(draft);
-			track.items ??= [];
-			let at = insertIndex;
-			for (const clip of input.clips) {
-				const partId = generatePartId("clip");
-				setPart(draft, partId, { video_clip: {
-					id: partId,
-					kind: "video_clip",
-					play_in: clip.play_in ?? 0,
-					play_out: clip.play_out ?? clip.media_duration_ms,
-					volume: 0,
-					origin_media_id: clip.media_id
-				} });
-				track.items.splice(at, 0, {
-					part_id: partId,
-					time_position: { mode: "sequential" },
-					fallback_abs_ms: void 0
-				});
-				at += 1;
-			}
-		}, audit("AddVideoClips", input, options));
-	}
-	/**
-	* Swap a contiguous run of main-track clips for a new run, in one transaction.
-	*
-	* Composite by necessity, not convenience: with `on_anchored: 'remap'` each
-	* surviving speech is re-anchored to the new clip in the **same position of the
-	* sequence** (old[i] → new[i]), which needs both id sets live at once. Splitting
-	* it into `deleteVideoClips` + `addVideoClips` would leave the caller holding the
-	* anchor re-wiring — the cascade-in-the-caller mistake ADR 0009 retires.
-	*
-	* Positional pairing, not by count: when there are fewer new clips than old, the
-	* unmatched old clips have no counterpart, so their anchored subtrees are deleted
-	* (there is nothing to anchor to). When there are more new clips than old, the
-	* extra ones simply arrive with no children.
-	*
-	* The new clips are inserted where the run started, so surrounding order is
-	* preserved. Every position is derived on read (RFC 02 §7) — this writes only the
-	* facts: track order, the trim windows, and the surviving anchors.
-	*/
-	async replaceVideoClipSequence(input, options) {
-		this.validator.validateReplaceVideoClipSequence(input, this.doc);
-		this.doc.transact((draft) => {
-			const track = mainTrackRow(draft);
-			if (track?.items == null) return;
-			const targets = new Set(input.old_clip_ids);
-			const insertIndex = track.items.findIndex((item) => item?.part_id != null && targets.has(item.part_id));
-			const at = insertIndex < 0 ? track.items.length : insertIndex;
-			const newItems = [];
-			const newClipIds = [];
-			for (const clip of input.new_clips) {
-				const partId = generatePartId("clip");
-				setPart(draft, partId, { video_clip: {
-					id: partId,
-					kind: "video_clip",
-					play_in: clip.play_in ?? 0,
-					play_out: clip.play_out ?? clip.media_duration_ms,
-					volume: 0,
-					origin_media_id: clip.media_id ?? ""
-				} });
-				newItems.push({
-					part_id: partId,
-					time_position: { mode: "sequential" },
-					fallback_abs_ms: void 0
-				});
-				newClipIds.push(partId);
-			}
-			if (input.on_anchored === "remap") for (let i = 0; i < input.old_clip_ids.length; i++) {
-				const newClipId = newClipIds[i];
-				if (newClipId == null) {
-					deleteAnchoredSubtree(draft, input.old_clip_ids[i]);
-					continue;
-				}
-				reanchorAnchoredChildren(draft, input.old_clip_ids[i], newClipId);
-			}
-			else for (const clipId of targets) deleteAnchoredSubtree(draft, clipId);
-			track.items = track.items.filter((item) => item?.part_id == null || !targets.has(item.part_id));
-			for (const clipId of targets) deletePart(draft, clipId);
-			track.items.splice(at, 0, ...newItems);
-		}, audit("ReplaceVideoClipSequence", input, options));
-	}
-	async adjustVideoClipVolume(input, options) {
-		this.validator.validateAdjustVideoClipVolume(input, this.doc);
-		this.doc.transact((draft) => {
-			for (const c of input.clips) {
-				const videoClip = draft.part_library?.[c.clip_id]?.video_clip;
-				if (videoClip == null) continue;
-				setPart(draft, c.clip_id, { video_clip: {
-					...videoClip,
-					kind: "video_clip",
-					volume: c.volume
-				} });
-			}
-		}, audit("AdjustVideoClipVolume", input, options));
-	}
-	async setVideoClipSpeedShift(input, options) {
-		this.validator.validateSetVideoClipSpeedShift(input, this.doc);
-		this.doc.transact((draft) => {
-			for (const clip of input.clips) {
-				const videoClip = draft.part_library?.[clip.clip_id]?.video_clip;
-				if (videoClip == null) continue;
-				const next = {
-					...videoClip,
-					kind: "video_clip",
-					speed_shift: normalizeSpeedShift(clip.speed_shift)
-				};
-				setPart(draft, clip.clip_id, { video_clip: next });
-			}
-		}, audit("SetVideoClipSpeedShift", input, options));
-	}
-	async adjustSpeechVolume(input, options) {
-		this.validator.validateAdjustSpeechVolume(input, this.doc);
-		this.doc.transact((draft) => {
-			for (const s of input.speeches) {
-				const speech = draft.part_library?.[s.speech_id]?.speech;
-				if (speech == null) continue;
-				setPart(draft, s.speech_id, { speech: {
-					...speech,
-					kind: "speech",
-					volume: s.volume
-				} });
-			}
-		}, audit("AdjustSpeechVolume", input, options));
-	}
-	async adjustBgmVolume(input, options) {
-		this.validator.validateAdjustBgmVolume(input, this.doc);
-		this.doc.transact((draft) => {
-			for (const b of input.bgm) {
-				const bgm = draft.part_library?.[b.bgm_id]?.bgm;
-				if (bgm == null) continue;
-				setPart(draft, b.bgm_id, { bgm: {
-					...bgm,
-					kind: "bgm",
-					volume: b.volume
-				} });
-			}
-		}, audit("AdjustBgmVolume", input, options));
-	}
-	/**
-	* Replace the media backing existing video clips. The new media's stable
-	* result (new media id, intrinsic length, reset trim window) is materialized
-	* upstream; the clip ids and their track items are unchanged. Only the part
-	* facts change — effective duration and downstream positions are derived by
-	* the projection on read.
-	*/
-	async replaceVideoClipContent(input, options) {
-		this.validator.validateReplaceVideoClipContent(input, this.doc);
-		this.doc.transact((draft) => {
-			for (const clip of input.clips) {
-				const videoClip = draft.part_library?.[clip.clip_id]?.video_clip;
-				if (videoClip == null) continue;
-				setPart(draft, clip.clip_id, { video_clip: {
-					...videoClip,
-					kind: "video_clip",
-					origin_media_id: clip.origin_media_id,
-					play_in: clip.play_in,
-					play_out: clip.play_out,
-					volume: clip.volume,
-					speed_shift: void 0
-				} });
-			}
-		}, audit("ReplaceVideoClipContent", input, options));
-	}
-	/**
-	* Re-trim clips. Only the `play_in` / `play_out` facts change; the new
-	* effective duration and the resulting downstream reflow are derived by the
-	* projection on read (anchored speeches follow their host clip automatically).
-	*/
-	async adjustVideoClipDuration(input, options) {
-		this.validator.validateAdjustVideoClipDuration(input, this.doc);
-		this.doc.transact((draft) => {
-			for (const clip of input.clips) {
-				const videoClip = draft.part_library?.[clip.clip_id]?.video_clip;
-				if (videoClip == null) continue;
-				setPart(draft, clip.clip_id, { video_clip: {
-					...videoClip,
-					kind: "video_clip",
-					play_in: clip.play_in,
-					play_out: clip.play_out
-				} });
-			}
-			refreshAnchoredFallbackAbs(draft);
-		}, audit("AdjustVideoClipDuration", input, options));
-	}
-	/**
-	* Add speeches (and their captions). TTS runs upstream; the materialized
-	* speech / caption parts arrive in `input`, each carrying its host clip
-	* `anchor_part_id` + `offset_ms`. The editor writes the parts and their
-	* `anchored` `time_position` facts verbatim — no write-time host-picking, no
-	* cascade. The projection derives absolute positions on read.
-	*/
-	async addSpeeches(input, options) {
-		this.validator.validateAddSpeeches(input, this.doc);
-		this.doc.transact((draft) => {
-			writeSpeechAssets(draft, input);
-		}, audit("AddSpeeches", input, options));
-	}
-	/** Delete speeches with their captions; the subtree is removed (§9.2). Surviving lanes keep their facts. */
-	async deleteSpeeches(input, options) {
-		this.validator.validateDeleteSpeeches(input, this.doc);
-		this.doc.transact((draft) => {
-			for (const speechId of input.speech_ids) deleteSpeechSubtree(draft, speechId);
-		}, audit("DeleteSpeeches", input, options));
-	}
-	/**
-	* Move speeches in time (§9.1). One forward positioning pass: anchor each
-	* speech to the main-track clip its new absolute start lands in and write the
-	* resulting `anchored` `time_position` fact. No cascade — the projection
-	* derives absolute positions on read.
-	*/
-	async moveSpeeches(input, options) {
-		this.validator.validateMoveSpeeches(input, this.doc);
-		this.doc.transact((draft) => {
-			const ranges = mainTrackRanges(draft);
-			const track = findLaneTrack(draft, "speech");
-			for (const move of input.speeches) {
-				const item = (track?.items ?? []).find((it) => it?.part_id === move.speech_id);
-				if (item == null) continue;
-				item.time_position = relativePositionForAbs(ranges, move.new_start_ms);
-				item.fallback_abs_ms = move.new_start_ms;
-			}
-		}, audit("MoveSpeeches", input, options));
-	}
-	/** Change a speech's script. Re-TTS runs upstream; the regenerated parts arrive materialized (no cascade). */
-	async changeSpeechScript(input, options) {
-		this.validator.validateChangeSpeechScript(input, this.doc);
-		this.doc.transact((draft) => {
-			writeSpeechAssets(draft, input);
-		}, audit("ChangeSpeechScript", input, options));
-	}
-	/** Change a speech's voice. Re-TTS runs upstream; the regenerated parts arrive materialized (no cascade). */
-	async changeSpeechVoice(input, options) {
-		this.validator.validateChangeSpeechVoice(input, this.doc);
-		this.doc.transact((draft) => {
-			writeSpeechAssets(draft, input);
-		}, audit("ChangeSpeechVoice", input, options));
-	}
-	/**
-	* Set the document BGM. The media's stable result arrives materialized.
-	*
-	* KNOWN GAP (non-blocking, FE callers only): a public-library BGM also needs
-	* project-level media ownership registered, or it plays but never appears in
-	* the project's media library. This editor deliberately does not do it — the
-	* document edit is complete and correct, and ownership is a side effect owned
-	* by whoever holds the authoritative media data (memota), not by a CRDT write.
-	*
-	* Who is affected, as of 2026-08-13: the agent harness registers it on BOTH
-	* its legacy and mengine paths (shared `resolveMutation` calls memota
-	* `attachMedia` directly), and FE's legacy REST path gets it from Director.
-	* Only FE's mengine path is missing it. FE cannot call memota directly:
-	* `attachMedia` is exposed on memota's internal contract only, so the fix is a
-	* Director proxy route — NOT a new Director business endpoint, since Director
-	* stopped owning media ownership entirely (`a2951355`, 2026-08-05).
-	*
-	* Tracked as a Phase 7 gate (it must land before "new documents default to
-	* mengine" makes public-library BGM a routine operation). See
-	* `docs/projects/medeo-integration/results/phase-6-m4-legacy-refresh-isolation.md`.
-	*/
-	async setBgm(input, options) {
-		this.validator.validateSetBgm(input, this.doc);
-		this.doc.transact((draft) => {
-			const track = ensureLaneTrack(draft, "bgm");
-			for (const item of track.items ?? []) if (item?.part_id != null) deletePart(draft, item.part_id);
-			setPart(draft, input.bgm_id, { bgm: {
-				id: input.bgm_id,
-				kind: "bgm",
-				audio_storage_key: input.audio_storage_key,
-				volume: input.volume,
-				origin_media_id: input.origin_media_id
-			} });
-			track.items = [{
-				part_id: input.bgm_id,
-				time_position: {
-					mode: "absolute",
-					offsetMs: 0
-				},
-				fallback_abs_ms: void 0
-			}];
-		}, audit("SetBgm", input, options));
-	}
-	/** Remove the document BGM; clears the bgm lane and removes the part. */
-	async deleteBgm(input, options) {
-		this.validator.validateDeleteBgm(input, this.doc);
-		this.doc.transact((draft) => {
-			const track = findLaneTrack(draft, "bgm");
-			if (track == null) return;
-			for (const item of track.items ?? []) if (item?.part_id != null) deletePart(draft, item.part_id);
-			track.items = [];
-		}, audit("DeleteBgm", input, options));
-	}
-	/** Toggle caption visibility (caption track `is_hidden`). */
-	async setCaptionVisibility(input, options) {
-		this.validator.validateSetCaptionVisibility(input, this.doc);
-		this.doc.transact((draft) => {
-			const track = findLaneTrack(draft, "caption");
-			if (track == null) return;
-			track.is_hidden = input.is_hidden;
-		}, audit("SetCaptionVisibility", input, options));
-	}
-	/**
-	* Set the document-wide caption style. GLOBAL (no `caption_id`): the patch is
-	* merged onto EVERY caption part's `style`, mirroring the FE, which applies a
-	* single style to all captions (`caption-style.ts:persistCaptionStylePatch`).
-	*
-	* Merge, not replace: only the fields present in the input overwrite the
-	* caption's existing style; absent fields are carried forward. So a partial
-	* patch ("recolor only") keeps the caption's font size. Pure document edit, no
-	* cascade — positions are untouched.
-	*/
-	async setCaptionStyle(input, options) {
-		this.validator.validateSetCaptionStyle(input, this.doc);
-		this.doc.transact((draft) => {
-			const library = draft.part_library ?? {};
-			for (const partId of Object.keys(library)) {
-				const caption = library[partId]?.caption;
-				if (caption == null) continue;
-				setPart(draft, partId, { caption: {
-					...caption,
-					kind: "caption",
-					style: {
-						...caption.style,
-						...input
-					}
-				} });
-			}
-		}, audit("SetCaptionStyle", input, options));
-	}
-	/**
-	* Resolve the main-track sequential layout from `source`. Callers inside a
-	* `transact` MUST pass the live `draft` so item order reflects in-progress
-	* mutations; the default `this.doc.snapshot()` is only committed state and is
-	* correct for read-only callers outside a transaction. `readMainTrackItems` /
-	* `readPartDurationMs` accept both an immer draft and a raw snapshot.
-	*/
-	computeMainTrackLayout(source = this.doc.snapshot()) {
-		const items = readMainTrackItems(source);
-		const layout = [];
-		let cur = 0;
-		for (let i = 0; i < items.length; i++) {
-			const partId = items[i].part_id;
-			if (partId == null) continue;
-			const durationMs = readPartDurationMs(source, partId, 1e3);
-			layout.push({
-				index: i,
-				part_id: partId,
-				start_ms: cur,
-				end_ms: cur + durationMs
-			});
-			cur += durationMs;
-		}
-		return layout;
-	}
-	indexForStartMs(layout, newStartMs, selfIndex) {
-		const without = layout.filter((it) => it.index !== selfIndex);
-		let cur = 0;
-		let target = without.length;
-		for (let i = 0; i < without.length; i++) {
-			const it = without[i];
-			const durationMs = it.end_ms - it.start_ms;
-			if (newStartMs <= cur + durationMs / 2) {
-				target = i;
-				break;
-			}
-			cur += durationMs;
-		}
-		return Math.max(0, Math.min(target, layout.length - 1));
-	}
-	computeAddInsertIndex(input) {
-		const items = readMainTrackItems(this.doc.snapshot());
-		if (input.before_clip_id != null) {
-			const idx = items.findIndex((it) => it.part_id === input.before_clip_id);
-			return idx < 0 ? items.length : idx;
-		}
-		if (input.after_clip_id != null) {
-			const idx = items.findIndex((it) => it.part_id === input.after_clip_id);
-			return idx < 0 ? items.length : idx + 1;
-		}
-		const firstStart = input.clips[0]?.start_ms;
-		if (firstStart == null) return items.length;
-		const snapshot = this.doc.snapshot();
-		let cur = 0;
-		for (let i = 0; i < items.length; i++) {
-			const partId = items[i].part_id;
-			const durationMs = partId == null ? 1e3 : readPartDurationMs(snapshot, partId, 1e3);
-			if (firstStart <= cur + durationMs / 2) return i;
-			cur += durationMs;
-		}
-		return items.length;
-	}
-};
-function audit(kind, payload, options) {
-	return {
-		kind,
-		payload,
-		intent: options?.intent ?? null,
-		...options?.actor ? { actor: options.actor } : {}
-	};
-}
-function mainTrackRow(draft) {
-	return (draft.tracks ?? []).find((t) => t?.parts_kind === "video_clip");
-}
-/**
-* Locate the main (video_clip) track in the single `tracks` list, minting an
-* empty one in lane-stacking order if absent (reference/17 §4: lane =
-* `parts_kind`). Used by ops that add the first clips into an empty document.
-* Delegates to `ensureLaneTrack` so the caption → main → speech/bgm ordering is
-* enforced in one place.
-*/
-function ensureMainTrack(draft) {
-	return ensureLaneTrack(draft, "video_clip");
-}
-function mainTrackItems(draft) {
-	const track = mainTrackRow(draft);
-	if (track == null) return void 0;
-	track.items ??= [];
-	return track.items;
-}
-/**
-* Resolve a `MoveAnchor` into an insertion slot in the **pre-extraction** item
-* list; the caller adjusts for items removed ahead of it.
-*
-* A missing anchor cannot reach here — `validateMoveVideoClipsByAnchor` rejects it
-* loudly first. This deliberately differs from `computeAddInsertIndex`, which
-* falls back to appending: adding clips with a stale anchor still has an obvious
-* intent (put them somewhere), while moving to a slot that no longer exists does
-* not. The `-1` guard stays as a defence-in-depth for a caller that bypassed
-* validation, and appending is the least destructive reading.
-*/
-function anchorInsertIndex(items, anchor) {
-	if (anchor.position === "track_start") return 0;
-	const index = items.findIndex((item) => item?.part_id === anchor.clip_id);
-	if (index < 0) return items.length;
-	return anchor.position === "before" ? index : index + 1;
-}
-function moveItem(items, from, to) {
-	if (from === to) return;
-	const [moved] = items.splice(from, 1);
-	items.splice(to, 0, moved);
-}
-function setPart(draft, partId, part) {
-	draft.part_library ??= {};
-	draft.part_library[partId] = partUnionToDraft(part);
-}
-function deletePart(draft, partId) {
-	if (draft.part_library != null) delete draft.part_library[partId];
-}
-/**
-* The validated speed-shift input already matches the domain `SpeedShift` shape
-* (`category` enum + `config` linear/curve union, mirroring the IDL); this just
-* narrows `null` (clear speed back to 1×) to `undefined`.
-*/
-function normalizeSpeedShift(input) {
-	return input ?? void 0;
-}
-/**
-* Write a materialized speech subtree into the draft: upsert each speech +
-* caption part, and insert/update their lane items with `anchored` `time_position`
-* facts taken verbatim from the input (RFC 02 §4) — speech anchors to its host
-* video clip (`anchor_part_id` + `offset_ms`); caption anchors to its speech
-* (offset = caption part `start_ms`). No absolute time is written; the
-* projection derives it on read. On re-TTS the speech id is preserved, so an
-* existing item is re-positioned rather than duplicated.
-*/
-function writeSpeechAssets(draft, assets) {
-	const captionById = new Map(assets.captions.map((c) => [c.caption_id, c]));
-	const speechTrack = ensureLaneTrack(draft, "speech");
-	speechTrack.items ??= [];
-	let captionItems;
-	const ensureCaptionItems = () => {
-		if (captionItems == null) {
-			const track = ensureLaneTrack(draft, "caption");
-			track.items ??= [];
-			captionItems = track.items;
-		}
-		return captionItems;
-	};
-	const ranges = mainTrackRanges(draft);
-	const hostStartMs = (anchorPartId) => ranges.find((r) => r.partId === anchorPartId)?.startMs;
-	for (const speech of assets.speeches) {
-		const priorCaptionIds = draft.part_library?.[speech.speech_id]?.speech?.caption_ids ?? [];
-		const nextCaptionIds = new Set(speech.caption_ids);
-		const removedCaptionIds = priorCaptionIds.filter((id) => id != null && !nextCaptionIds.has(id));
-		for (const captionId of removedCaptionIds) deletePart(draft, captionId);
-		if (removedCaptionIds.length > 0) {
-			const lane = findLaneTrack(draft, "caption");
-			const removed = new Set(removedCaptionIds);
-			if (lane?.items != null) lane.items = lane.items.filter((it) => it?.part_id == null || !removed.has(it.part_id));
-		}
-		const priorSpeech = draft.part_library?.[speech.speech_id]?.speech;
-		setPart(draft, speech.speech_id, { speech: {
-			...priorSpeech,
-			id: speech.speech_id,
-			kind: "speech",
-			media_duration_ms: speech.duration_ms,
-			audio_script: speech.audio_script,
-			volume: speech.volume,
-			audio_storage_key: speech.audio_storage_key,
-			origin_speech_id: speech.origin_speech_id,
-			voice: speech.voice,
-			caption_ids: speech.caption_ids
-		} });
-		const hostStart = hostStartMs(speech.anchor_part_id);
-		const speechAbs = hostStart == null ? void 0 : hostStart + speech.offset_ms;
-		placeRelative(speechTrack.items, speech.speech_id, speech.anchor_part_id, speech.offset_ms, speechAbs);
-		for (const captionId of speech.caption_ids) {
-			const caption = captionById.get(captionId);
-			if (caption == null) continue;
-			const priorCaption = draft.part_library?.[captionId]?.caption;
-			setPart(draft, captionId, { caption: {
-				...priorCaption ?? { style: {} },
-				id: captionId,
-				kind: "caption",
-				initial_duration_ms: caption.duration_ms,
-				speech_part_id: speech.speech_id,
-				text: caption.text,
-				start_ms: caption.start_ms
-			} });
-			const captionAbs = speechAbs == null ? void 0 : speechAbs + caption.start_ms;
-			placeRelative(ensureCaptionItems(), captionId, speech.speech_id, caption.start_ms, captionAbs);
-		}
-	}
-}
-/**
-* Insert a lane item with an `anchored` time position fact, or re-position it if
-* already present. `fallbackAbsMs` is the orphan-recovery snapshot (RFC 02
-* §11.1): the item's absolute landing the caller resolved from its anchor, so a
-* freshly-created anchored item can still be recovered if its anchor is later
-* concurrently deleted. Pass `undefined` only when the anchor's absolute
-* position cannot be resolved (no host clip yet).
-*/
-function placeRelative(items, partId, anchorPartId, offsetMs, fallbackAbsMs) {
-	const timePosition = {
-		mode: "anchored",
-		anchorPartId,
-		offsetMs: Math.max(0, Math.round(offsetMs))
-	};
-	const existing = items.find((it) => it?.part_id === partId);
-	if (existing != null) {
-		existing.time_position = timePosition;
-		if (fallbackAbsMs != null) existing.fallback_abs_ms = fallbackAbsMs;
-		return;
-	}
-	items.push({
-		part_id: partId,
-		time_position: timePosition,
-		fallback_abs_ms: fallbackAbsMs
-	});
-}
-/**
-* After the main-track flow order changes (move / reorder), re-parent each
-* anchored speech to the clip its *preserved* absolute landing now falls in
-* (RFC 02 §9.1). `beforeRanges` is the pre-change main-track layout, used only
-* to recover each speech's current absolute time; the new layout is read fresh.
-* Writes only the affected speech `position` facts — a single forward pass, not
-* a cascade. Captions follow their speech (relative to it), so they need no
-* rewrite.
-*/
-function reparentSpeechesAfterMainTrackChange(draft, beforeRanges) {
-	const speechTrack = findLaneTrack(draft, "speech");
-	if (speechTrack?.items == null) return;
-	const beforeStart = new Map(beforeRanges.map((r) => [r.partId, r.startMs]));
-	const afterRanges = mainTrackRanges(draft);
-	for (const item of speechTrack.items) {
-		const timePosition = item?.time_position;
-		if (timePosition?.mode !== "anchored") continue;
-		const hostStart = beforeStart.get(timePosition.anchorPartId);
-		if (hostStart == null) continue;
-		const currentAbs = hostStart + timePosition.offsetMs;
-		item.time_position = relativePositionForAbs(afterRanges, currentAbs);
-		item.fallback_abs_ms = currentAbs;
-	}
-}
-/**
-* Refresh the orphan-recovery snapshot (`fallback_abs_ms`, RFC 02 §11.1) of
-* every `anchored` speech from the current main-track layout, keeping the
-* `time_position` facts untouched. Called after an op that shifts clip positions
-* without re-parenting (e.g. re-trim), so a later orphan recovery uses an
-* absolute landing that matches the post-edit layout, not a stale one. Speeches
-* whose anchor clip is absent are left as-is (recovery handles them).
-*/
-function refreshAnchoredFallbackAbs(draft) {
-	const speechTrack = findLaneTrack(draft, "speech");
-	if (speechTrack?.items == null) return;
-	const startByPart = new Map(mainTrackRanges(draft).map((r) => [r.partId, r.startMs]));
-	for (const item of speechTrack.items) {
-		const timePosition = item?.time_position;
-		if (timePosition?.mode !== "anchored") continue;
-		const hostStart = startByPart.get(timePosition.anchorPartId);
-		if (hostStart == null) continue;
-		item.fallback_abs_ms = hostStart + timePosition.offsetMs;
-	}
-}
-/**
-* Remove a speech part, its captions, and all their lane items (RFC 02 §9.2
-* subtree). The cascade basis is the anchored `time_position`, not the speech's
-* `caption_ids` (reference/17 §6): a caption is deleted iff it is `anchored` to
-* this speech (`time_position.anchorPartId === speechId`). `caption_ids` stays as
-* a resource-intrinsic fact (reference/17 principle 4) but no longer drives
-* deletion — "what to delete" is decoupled from "what the resource is".
-*/
-function deleteSpeechSubtree(draft, speechId) {
-	const captionTrack = findLaneTrack(draft, "caption");
-	const anchoredCaptionIds = new Set((captionTrack?.items ?? []).filter((it) => it?.time_position?.mode === "anchored" && it.time_position.anchorPartId === speechId).map((it) => it.part_id).filter((id) => id != null));
-	deletePart(draft, speechId);
-	for (const captionId of anchoredCaptionIds) deletePart(draft, captionId);
-	const speechTrack = findLaneTrack(draft, "speech");
-	if (speechTrack?.items != null) speechTrack.items = speechTrack.items.filter((it) => it?.part_id !== speechId);
-	if (captionTrack?.items != null) captionTrack.items = captionTrack.items.filter((it) => it?.part_id == null || !anchoredCaptionIds.has(it.part_id));
-}
-/**
-* Detach the direct anchored children of a video clip (reference/17 §6 `detach`):
-* each speech anchored to `clipId` is re-pinned to `{ mode:'absolute' }` at its
-* current projected landing, so it stays on the timeline once the clip is gone.
-* Computed while the anchor chain is intact (call before removing the clip), so
-* the absolute landing is always resolvable — no `fallback_abs_ms` read needed.
-*
-* Only the *direct* children detach: a speech's captions anchor to the speech
-* (not the clip), so they keep following the speech and need no rewrite.
-*/
-function detachAnchoredChildren(draft, clipId) {
-	const speechTrack = findLaneTrack(draft, "speech");
-	if (speechTrack?.items == null) return;
-	const clipStart = new Map(mainTrackRanges(draft).map((r) => [r.partId, r.startMs])).get(clipId);
-	for (const item of speechTrack.items) {
-		const timePosition = item?.time_position;
-		if (timePosition?.mode !== "anchored" || timePosition.anchorPartId !== clipId) continue;
-		const abs = (clipStart ?? item.fallback_abs_ms ?? 0) + timePosition.offsetMs;
-		item.time_position = {
-			mode: "absolute",
-			offsetMs: Math.max(0, Math.round(abs))
-		};
-		item.fallback_abs_ms = void 0;
-	}
-}
-/**
-* Re-anchor the direct anchored children of `fromClipId` onto `toClipId`, keeping
-* each child's `offsetMs` unchanged.
-*
-* "Same offset into the replacement" is the whole point: a speech that started
-* 100ms into the clip it narrated still starts 100ms into the clip that replaced
-* it, whatever the two clips' durations are. Absolute time is NOT preserved here
-* (that is `moveVideoClips`' rule, where the clip stays and the timeline reflows
-* around it) — the clip itself is being swapped out, so following it is what keeps
-* narration attached to the picture it describes.
-*
-* `fallback_abs_ms` is deliberately left alone: it is the orphan-recovery snapshot
-* (RFC 02 §11.1), refreshed by the projection on the next read. Writing a guess
-* here would make this op compete with the follow-the-clock refresh for the same
-* LWW unit.
-*
-* Only direct children move: captions anchor to their speech, so they follow it
-* without a rewrite.
-*/
-function reanchorAnchoredChildren(draft, fromClipId, toClipId) {
-	const speechTrack = findLaneTrack(draft, "speech");
-	if (speechTrack?.items == null) return;
-	for (const item of speechTrack.items) {
-		const timePosition = item?.time_position;
-		if (timePosition?.mode !== "anchored" || timePosition.anchorPartId !== fromClipId) continue;
-		item.time_position = {
-			...timePosition,
-			anchorPartId: toClipId
-		};
-	}
-}
-/** Delete every speech (with its captions) anchored to the given video clip (RFC 02 §9.2). */
-function deleteAnchoredSubtree(draft, clipId) {
-	const anchored = (findLaneTrack(draft, "speech")?.items ?? []).filter((it) => it?.time_position?.mode === "anchored" && it.time_position.anchorPartId === clipId).map((it) => it.part_id).filter((id) => id != null);
-	for (const speechId of anchored) deleteSpeechSubtree(draft, speechId);
-}
-//#endregion
-//#region src/editor/types.ts
-/** Runtime list of the frozen, implemented kinds (for guards / introspection). */
-const IMPLEMENTED_SEMANTIC_OP_KINDS = [
-	"MoveVideoClips",
-	"MoveVideoClipsByAnchor",
-	"DeleteVideoClips",
-	"AddVideoClips",
-	"AdjustVideoClipVolume",
-	"SetVideoClipSpeedShift",
-	"ReplaceVideoClipContent",
-	"ReplaceVideoClipSequence",
-	"AdjustVideoClipDuration",
-	"AddSpeeches",
-	"DeleteSpeeches",
-	"MoveSpeeches",
-	"ChangeSpeechScript",
-	"ChangeSpeechVoice",
-	"AdjustSpeechVolume",
-	"SetCaptionVisibility",
-	"SetCaptionStyle",
-	"SetBgm",
-	"DeleteBgm",
-	"AdjustBgmVolume"
-];
-function isImplementedSemanticOpKind(kind) {
-	return IMPLEMENTED_SEMANTIC_OP_KINDS.includes(kind);
-}
-//#endregion
-//#region src/manual-sync/doc-version-mark.ts
-/**
-* Encode a {@link DocVersionMark} for storage or transport.
-*
-* The mark stays opaque across the round trip — the string is not a version
-* number and must not be compared, ordered, or parsed. Its only use is
-* {@link decodeDocVersionMark} followed by `hasChangedSince`.
-*
-* Callers that persist this should know the encoded length grows with the number
-* of peers that have ever written to the document (one counter each), and the FE
-* mints a fresh peer per page load. Still small in practice (a few hundred bytes
-* for dozens of peers), but it grows with document age rather than size; version
-* vector compaction is deferred to a later phase.
-*/
-function encodeDocVersionMark(mark) {
-	return bytesToBase64(mark.encoded);
-}
-/**
-* Rebuild a mark from {@link encodeDocVersionMark}'s output.
-*
-* Returns `undefined` for input this did not produce (a legacy integer version,
-* a truncated value, an empty string). That is the honest answer — "I cannot
-* establish what you last saw" — and callers should treat it as "no baseline"
-* rather than as "unchanged". Decoding does not validate the bytes as a version
-* vector; `hasChangedSince` reports "changed" for an undecodable mark, which is
-* the conservative direction.
-*/
-function decodeDocVersionMark(encoded) {
-	if (encoded === "") return void 0;
-	try {
-		return {
-			__brand: "mengine-doc-version-mark",
-			encoded: base64ToBytes(encoded)
-		};
-	} catch {
-		return;
-	}
-}
-//#endregion
-//#region src/manual-sync/version-coverage.ts
-/**
-* Version-vector coverage: "does `outer` contain everything in `inner`?"
-*
-* This one predicate answers three different questions in the manual-sync document, which
-* is why it is factored out rather than inlined three times:
-*
-* | question                              | call                            |
-* | ------------------------------------- | ------------------------------- |
-* | is there anything left to push?       | `covers(watermark, localOplog)`  |
-* | did someone else write concurrently?  | `covers(localOplog, serverVV)`   |
-* | has the doc moved since I last read?  | `covers(seenVersion, localOplog)`|
-*
-* `VersionVector.compare` cannot be used for any of them: it returns `undefined`
-* for concurrent vectors, and concurrency is the NORMAL case here — the server
-* routinely holds peers the local doc has never seen, and after a collaborative
-* merge the local doc holds ops the watermark predates. Treating "concurrent" as
-* "not covered" is right for some of these and wrong for others, so the per-peer
-* counter check is the only formulation that stays correct for all three.
-*
-* Equality must NOT be used as a substitute either: once collaboration happens
-* the watermark legitimately *leads* the local doc (it carries other peers'
-* counters), so an equality test reports "still has ops to push" forever.
-*/
-function covers(outer, inner) {
-	for (const [peer, counter] of inner.toJSON()) if ((outer.get(peer) ?? 0) < counter) return false;
-	return true;
-}
-//#endregion
+import { DisposableSet, EventBus } from "@mengine/utils";
 //#region src/manual-sync/manual-sync-doc.ts
-/**
-* Agent-facing document with explicit `pull()` / `push()` over one Loro
-* document, with no background sync (ADR 0015 D1–D4).
-*
-* It deliberately does NOT reuse `MengineDocSession`'s stack. That stack —
-* SSE + local `DocStorage` + `ClientServerSynchronizer` + `DocManager` — is
-* correct for a browser editor and actively wrong here:
-*
-* - Its retry backoff lands *outside* the tool-call lifetime, so a write can
-*   settle seconds after the tool already told the LLM what happened.
-* - It has no durable local queue in the harness, so pending pushes die with the
-*   process — that is lost data, reported as success.
-* - Agent semantics require the document to change only at points the agent can
-*   name. If it converged on its own between tool calls, "what state was this
-*   decision based on" would be unanswerable, and a remote change could land
-*   mid-edit.
-*
-* What replaces the whole background job queue is one variable: the **watermark**,
-* the version the server has confirmed. `push()` exports `{mode:'update', from:
-* watermark}` and only advances it on a confirmed verdict, so a failed push is
-* retried implicitly — the next push carries both the failed ops and any new
-* ones, in one blob. No queue, no timer, no retry bookkeeping.
-*
-* Two non-obvious properties of that watermark, both verified against a real
-* server in the ADR 0015 spike:
-*
-* - It can legitimately *lead* the local document (it carries other peers'
-*   counters). Exporting `from` a leading watermark does not error; the blob
-*   correctly contains only the local peer's new ops. So a collaborative merge
-*   does not force a pull before pushing.
-* - Therefore every emptiness/coverage test must be one-directional containment,
-*   never equality. See {@link covers}.
-*
-* Lifecycle: one `LoroDoc` per document, shared across agent loops with a
-* refcount held by the caller's session registry. Rebuilding the doc per tool
-* call would mint a new peer each time and permanently inflate the document's
-* version vector for every future reader.
-*
-* Not thread-safe by design and it does not need to be: harness tool calls run
-* serially (`execToolCalls` is a `for` + `await`).
-*/
-var ManualSyncDoc = class ManualSyncDoc {
-	client;
-	doc;
-	adapter;
+/** Explicit synchronization over the same DSL/editor used by the live Session. */
+var ManualSyncDoc = class ManualSyncDoc extends ManualSyncTransport {
+	dsl;
 	editor;
-	/**
-	* The version the server is known to hold. Starts empty (nothing confirmed)
-	* and only ever moves forward on a verdict that proves the server took our ops.
-	*/
-	watermark = new VersionVector(/* @__PURE__ */ new Map());
-	constructor(client, doc) {
-		this.client = client;
-		this.doc = doc;
-		this.adapter = new MirrorVideoDocumentAdapter(doc);
-		this.editor = new SemanticEditor(this.adapter);
+	constructor(client, doc, watermark) {
+		super(client, doc, watermark);
+		assertDslDocument(doc);
+		this.dsl = new MedeoDsl(doc);
+		this.editor = new DslEditor(this.dsl);
 	}
-	/**
-	* Open an existing server document.
-	*
-	* 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.
-	*/
-	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;
-		}
+	static open(options) {
+		return openManualDocument(options, (doc, watermark) => new ManualSyncDoc(options.client, doc, watermark));
 	}
-	/** Current document read model (authoritative shape). */
 	snapshot() {
-		return this.adapter.snapshot();
-	}
-	/**
-	* The Loro peer this document writes as.
-	*
-	* Exposed because the peer is an externally-meaningful fact, not an internal
-	* detail: it is the identity every op this document emits is attributed to, and
-	* callers mint it under rules of their own (the harness reserves a range so a
-	* peer id alone says "Agent wrote this"). Being able to read it back means those
-	* rules can be verified against the live document rather than against whatever
-	* was passed to the constructor.
-	*/
-	editorPeerId() {
-		return this.doc.peerIdStr;
-	}
-	/** Current content projected into the compatible track and part read shape. */
-	content() {
-		return fromVideoDocument(this.adapter.snapshot());
-	}
-	/**
-	* 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.
-	*
-	* Same capability, not a stronger one: like the legacy detector, this only
-	* reports what changed between two moments the caller chose to sample.
-	*/
-	versionMark() {
-		return {
-			__brand: "mengine-doc-version-mark",
-			encoded: this.doc.oplogVersion().encode()
-		};
-	}
-	/**
-	* Has the document moved since `mark` was taken?
-	*
-	* Reports any advance, whoever caused it — including this document's own edits.
-	* The caller decides what is interesting: a detector sampling once per turn is
-	* asking "did anything happen", and its own edits legitimately count.
-	*/
-	hasChangedSince(mark) {
-		let previous;
-		try {
-			previous = VersionVector.decode(mark.encoded);
-		} catch {
-			return true;
-		}
-		return !covers(previous, this.doc.oplogVersion());
-	}
-	/**
-	* Fetch and merge everything the server has that this document lacks.
-	*
-	* Must run *before* the editor on each tool call. `SemanticEditor` validates
-	* against the local document, so editing a stale one validates against a world
-	* that no longer exists: the ADR 0015 spike confirmed that without pull-first
-	* an edit to a clip another writer had already deleted passes validation and is
-	* accepted by the server. Pulling afterwards cannot undo that.
-	*
-	* A failure is returned, not thrown — a transient network blip must not make
-	* the tool unusable (M2/A ruling; legacy tolerates read failures the same way).
-	* The caller proceeds on a possibly-stale document knowingly.
-	*/
-	async pull() {
-		const before = this.doc.oplogVersion();
-		try {
-			const update = base64ToBytes((await this.client.sync(before.encode())).update);
-			if (update.byteLength > 0) this.doc.import(update);
-			return {
-				ok: true,
-				changed: !covers(before, this.doc.oplogVersion())
-			};
-		} catch (error) {
-			return {
-				ok: false,
-				reason: "failed",
-				error: error instanceof Error ? error : new Error(String(error))
-			};
-		}
+		this.assertActive();
+		return this.dsl.getSnapshot();
 	}
-	/**
-	* Push every local op the server has not confirmed, and report the verdict.
-	*
-	* The return value is the durability answer a tool needs before claiming
-	* success: only `ack` / `duplicate` mean the server holds the ops. This is why
-	* this class exists rather than an ack-waiter — with a direct call, "did it
-	* land" is simply the result.
-	*
-	* `duplicate` counts as durable: the bytes added nothing *because* the server
-	* already had them.
-	*/
-	async push() {
-		const localVersion = this.doc.oplogVersion();
-		if (covers(this.watermark, localVersion)) return {
-			kind: "nothing_to_push",
-			collaborated: false
-		};
-		const update = this.doc.export({
-			mode: "update",
-			from: this.watermark
-		});
-		try {
-			const response = await this.client.pushUpdate(update);
-			const serverVV = this.serverVVFrom(response.version?.server_vv);
-			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)
-			};
-		} catch (error) {
-			const failure = error instanceof Error ? error : new Error(String(error));
-			const rejected = error instanceof MenginePushRejectedError;
-			return {
-				kind: rejected ? "rejected" : "failed",
-				collaborated: false,
-				code: rejected ? error.code : void 0,
-				error: failure
-			};
-		}
+	projectVideoDraft() {
+		return toVideoDraft(this.snapshot());
 	}
-	/** Decode a wire `server_vv`, tolerating absence/corruption (never throws). */
-	serverVVFrom(serverVV) {
-		if (serverVV == null || serverVV === "") return void 0;
-		try {
-			return VersionVector.decode(base64ToBytes(serverVV));
-		} catch {
-			return;
-		}
+	dispose() {
+		this.dsl.dispose();
+		super.dispose();
 	}
 };
 //#endregion
-//#region src/storage/medeo-http-doc-storage.ts
-/**
-* SSE-backed {@link Connection} for the mengine-server document stream.
-*
-* It owns the live SSE read loop and reflects its lifecycle as connection
-* status: `connecting` while (re)establishing, `connected` once the stream is
-* open, back to `connecting` on a drop (auto-reconnect), `closed` on
-* `disconnect`. Reporting a drop as a status change is the whole point — the
-* synchronizer watches `onStatusChanged` and, on any change, tears down and
-* re-runs its connect cycle, which re-issues `getDocDiff(doc.version())` and so
-* recovers whatever the stream missed while it was down. Recovery therefore
-* lives in the synchronizer (keyed on the real doc version), not here.
-*
-* Update frames are forwarded via `onUpdate`, resync hints via `onResync`; this
-* connection keeps no version cursor and does no catch-up of its own. Dedup is
-* unnecessary because `LoroDoc.import` is idempotent by OpId/VV.
-*/
-var SseConnection = class {
-	client;
-	onUpdate;
-	onResync;
-	reconnectDelayMs;
-	inner = void 0;
-	event = new EventBus();
-	streamTask = null;
-	_status = "idle";
-	_error;
-	constructor(client, onUpdate, onResync, reconnectDelayMs) {
-		this.client = client;
-		this.onUpdate = onUpdate;
-		this.onResync = onResync;
-		this.reconnectDelayMs = reconnectDelayMs;
-	}
-	get status() {
-		return this._status;
-	}
-	get error() {
-		return this._error;
-	}
-	connect() {
-		if (this.streamTask != null) return;
-		const task = Task.spawn((scope) => this.runStreamLoop(scope.signal));
-		this.streamTask = task;
-		const release = () => {
-			if (this.streamTask === task) this.streamTask = null;
-		};
-		task.then(release, release);
-	}
-	disconnect() {
-		this.streamTask?.cancel();
-		this.streamTask = null;
-		this.setStatus("closed");
-	}
-	waitForConnected() {
-		return new Task((resolve, reject, scope) => {
-			if (this._status === "connected") {
-				resolve();
-				return;
-			}
-			const off = this.onStatusChanged((status, error) => {
-				if (status === "connected") {
-					off();
-					resolve();
-				} else if (status === "closed") {
-					off();
-					reject(error ?? /* @__PURE__ */ new Error("SSE connection closed"));
-				}
-			});
-			scope.disposer.add(off);
-		});
-	}
-	onStatusChanged(cb) {
-		return this.event.on("statusChanged", ({ status, error }) => cb(status, error));
-	}
-	setStatus(status, error) {
-		if (this._status === status && this._error === error) return;
-		this._status = status;
-		this._error = error;
-		this.event.emit("statusChanged", {
-			status,
-			error
-		});
-	}
-	async runStreamLoop(signal) {
-		while (!signal.aborted) {
-			this.setStatus("connecting");
-			try {
-				await readMengineEventStream({
-					client: this.client,
-					signal,
-					onOpen: () => this.setStatus("connected"),
-					onResync: this.onResync,
-					onUpdate: (event) => {
-						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)));
-			}
-			if (signal.aborted) break;
-			try {
-				await Task.delay(this.reconnectDelayMs).abortOn(signal);
-			} catch {
-				break;
-			}
-		}
-	}
-};
+//#region src/session/document-mutation-guard.ts
 /**
-* Adapts the mengine-server HTTP/SSE protocol to the engine `DocStorage`
-* contract so `ClientServerSynchronizer` can treat it as a remote peer.
-*
-* Deliberately thin (mirrors the socket `DocStorage` in the playground): it
-* forwards live SSE updates and exposes a version-vector diff, and keeps NO
-* sync state of its own.
-*
-* - `getDocDiff(docId, knownVersion)` pulls the server-computed VV-diff via
-*   `GET /sync?from=<vv>` — the synchronizer passes the real `doc.version()`, so
-*   the response carries exactly the ops the doc is missing. `getDoc` (full
-*   `/snapshot`) stays for cold start, when the caller holds no version yet.
-* - `pushDocUpdate` forwards a Loro update; the server appends it.
-* - `subscribeDocUpdate` registers a callback for live SSE updates. It does no
-*   catch-up and keeps no cursor: after an SSE drop the connection reports a
-*   status change, and the synchronizer re-runs its cycle to catch up via
-*   `getDocDiff(doc.version())`. `LoroDoc.import` is idempotent (OpId/VV), so
-*   re-forwarded or echoed updates are harmless.
-*
-* It is bound to a single `docId` because `MengineHttpClient` is per-document.
+* @internal
+* Shared by synchronous mutation entry points for one document. The session
+* closes it before teardown callbacks can attempt another write.
 */
-var MedeoHttpDocStorage = class {
-	options;
-	connection;
-	client;
-	docId;
-	events = new EventBus();
-	constructor(options) {
-		this.options = options;
-		this.client = options.client;
-		this.docId = options.docId;
-		this.connection = new SseConnection(this.client, (update) => this.emitUpdate(update), () => this.events.emit("resync"), options.sseReconnectDelayMs ?? 500);
-	}
-	get isReadonly() {
-		return this.options.readonlyMode ?? false;
-	}
-	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,
-			data: base64ToBytes(snapshot.snapshot),
-			createdAt: now,
-			updatedAt: now
-		};
-	}
-	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),
-			version: base64ToBytes(response.server_vv)
-		};
+var DocumentMutationGuard = class {
+	readonlyMode;
+	running = false;
+	closed = false;
+	constructor(readonlyMode = false) {
+		this.readonlyMode = readonlyMode;
 	}
-	/**
-	* Forward one update to the server, returning what the server says it now holds.
-	*
-	* The returned `server_vv` is the server's own statement about itself, computed
-	* inside the write transaction. A caller tracking "what the remote has" can
-	* adopt it directly, which is strictly better than inferring that bound from
-	* the pushed blob: it also covers ops other peers wrote, so those stop being
-	* re-sent on every later push. `ack` and `duplicate` both carry it.
-	*
-	* The verdict itself stays on {@link subscribePushOutcome}, which reports
-	* failures too — a return value cannot. Previously the verdict was read and
-	* dropped, so a `duplicate` (bytes contributed nothing) was indistinguishable
-	* from a successful write.
-	*
-	* The error is still rethrown after being published: the synchronizer treats a
-	* throw as "retry this cycle", and swallowing it here would strand the update.
-	* Publishing is therefore additive observability, not error handling.
-	*/
-	async pushDocUpdate(update, _origin) {
-		this.assertDocId(update.docId);
-		if (this.isReadonly) throw new Error(`MedeoHttpDocStorage is readonly; refusing to push ${update.docId}`);
-		if (update.data.byteLength === 0) return {};
+	run(mutation) {
+		if (this.closed) throw new Error("mengine document is disposed");
+		if (this.readonlyMode) throw new Error("mengine document is read-only");
+		if (this.running) throw new Error("mengine document mutation is already running");
+		this.running = true;
 		try {
-			const response = await this.client.pushUpdate(update.data);
-			const serverVV = this.reportServerVersion(response.version?.server_vv);
-			this.events.emit("pushOutcome", {
-				kind: response.kind,
-				updateSeq: response.update_seq ?? void 0,
-				serverVV
-			});
-			return { version: serverVV };
-		} catch (error) {
-			const failure = error instanceof Error ? error : new Error(String(error));
-			const rejected = error instanceof MenginePushRejectedError;
-			this.events.emit("pushOutcome", {
-				kind: rejected ? "rejected" : "failed",
-				code: rejected ? error.code : void 0,
-				error: failure
-			});
-			throw error;
-		}
-	}
-	/**
-	* Observe the server's verdict for every pushed update, including failures.
-	*
-	* This is the loud channel the `void`-returning `DocStorage.pushDocUpdate`
-	* cannot express. Consumers that need "did my write land" (the agent's
-	* tool-level ack wait) subscribe here.
-	*/
-	subscribePushOutcome(callback) {
-		return this.events.on("pushOutcome", callback);
-	}
-	/** Observe live hints that require VV catch-up without replacing the SSE connection. */
-	subscribeResync(callback) {
-		return this.events.on("resync", 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");
-	}
-	subscribeDocUpdate(callback) {
-		return this.events.on("update", ({ update, origin }) => callback(update, origin));
-	}
-	assertDocId(docId) {
-		if (docId !== this.docId) throw new Error(`MedeoHttpDocStorage is bound to ${this.docId}, received ${docId}`);
-	}
-	emitUpdate(base64Update) {
-		this.events.emit("update", {
-			update: {
-				docId: this.docId,
-				data: base64ToBytes(base64Update)
-			},
-			origin: void 0
-		});
-	}
-};
-/**
-* Decode the wire `server_vv` into raw bytes, tolerating absence. A server that
-* omits the version block still yields a usable outcome (the kind is the useful
-* part); only the version-coverage wait degrades, so this must not throw.
-*/
-function decodeServerVV(serverVV) {
-	if (serverVV == null || serverVV === "") return void 0;
-	try {
-		return base64ToBytes(serverVV);
-	} catch {
-		return;
-	}
-}
-//#endregion
-//#region src/storage/memory-doc-storage.ts
-/**
-* Runtime-neutral local `DocStorage` backed by in-process memory.
-*
-* `IndexedDBDocStorage` is the browser-side local storage, but it requires
-* `indexedDB`/`idb`, which is absent in Node (FE/agent tests, unit tests, SSR).
-* The mengine runtime injects this implementation as the local peer in those
-* environments so the same `DocManager` + `ClientServerSynchronizer` wiring
-* works without a browser. It mirrors the merge-on-read and update-sequence
-* behavior of `IndexedDBDocStorage` so sync semantics are identical.
-*/
-var MemoryDocStorage = class extends BaseDocStorage {
-	connection = new DummyConnection();
-	entries = /* @__PURE__ */ new Map();
-	constructor(options = {}) {
-		super(options);
-	}
-	async pushDocUpdate(update, origin) {
-		const entry = this.entry(update.docId);
-		if (entry.snapshot == null && entry.updates.length === 0) {
-			const now = this.now();
-			entry.snapshot = {
-				docId: update.docId,
-				data: update.data,
-				createdAt: now,
-				updatedAt: now
-			};
-		} else {
-			entry.seq += 1;
-			entry.updates.push({
-				docId: update.docId,
-				seq: entry.seq,
-				data: update.data,
-				createdAt: this.now()
-			});
-		}
-		this.event.emit("update", {
-			update: {
-				docId: update.docId,
-				data: update.data
-			},
-			origin
-		});
-		return {};
-	}
-	async deleteDoc(docId) {
-		this.entries.delete(docId);
-	}
-	async getDocSnapshot(docId) {
-		return this.entries.get(docId)?.snapshot ?? null;
-	}
-	async setDocSnapshot(snapshot) {
-		const entry = this.entry(snapshot.docId);
-		if (entry.snapshot == null || entry.snapshot.updatedAt <= snapshot.updatedAt) entry.snapshot = snapshot;
-		return true;
-	}
-	async getDocUpdates(docId) {
-		return [...this.entries.get(docId)?.updates ?? []];
-	}
-	async markUpdatesMerged(docId, updates) {
-		const entry = this.entries.get(docId);
-		if (!entry) return 0;
-		const merged = new Set(updates.map((update) => update.seq));
-		entry.updates = entry.updates.filter((update) => !merged.has(update.seq));
-		return merged.size;
-	}
-	entry(docId) {
-		let entry = this.entries.get(docId);
-		if (!entry) {
-			entry = {
-				snapshot: null,
-				updates: [],
-				seq: 0
-			};
-			this.entries.set(docId, entry);
+			return mutation();
+		} finally {
+			this.running = false;
 		}
-		return entry;
 	}
-	now() {
-		return /* @__PURE__ */ new Date();
+	close() {
+		this.closed = true;
 	}
 };
 //#endregion
@@ -2648,9 +173,9 @@ var DocumentUndoManager = class {
 	}
 };
 //#endregion
-//#region src/session/mengine-doc-session.ts
+//#region src/session/document-session.ts
 /**
-* Raised by {@link MengineDocSession.waitForServerAck} when the local edits it
+* Raised by {@link DocumentSession.waitForServerAck} when the local edits it
 * was asked to confirm were not acknowledged as durable.
 *
 * Named `...AckFailed`, not `...AckTimeout`: two of the three `reason` values are
@@ -2679,26 +204,10 @@ var MengineAckFailedError = class extends Error {
 		this.name = "MengineAckFailedError";
 	}
 };
-/**
-* A live editing session for one Medeo document — the single entry point clients
-* (FE draft driver, Agent, embeds) use to open, edit, and observe a document.
-*
-* SemanticEditor writes through MirrorVideoDocumentAdapter directly, while
-* DocumentUndoManager observes the same LoroDoc independently. Both mutation
-* paths use the session's DocumentMutationGuard, closed before teardown.
-*
-* `DocManager` owns the `LoroDoc`: local edits committed on the adapter are
-* picked up via `subscribeLocalUpdates`, saved to local storage, then pushed to
-* the server by the synchronizer. Remote SSE updates flow server → synchronizer
-* → local storage → manager → `LoroDoc`. A single `LoroDoc.subscribe` turns any
-* resulting change into a snapshot event, so callers never track update ids by
-* hand.
-*
-* Replaces the per-consumer hand-written pull/SSE loops that previously lived in
-* the standalone client session and `MengineDraftDriver` with one verified path.
-*/
-var MengineDocSession = class {
+/** Shared binary synchronization lifecycle. Models attach only after initial loading succeeds. */
+var DocumentSession = class {
 	options;
+	model;
 	docId;
 	local;
 	server;
@@ -2706,14 +215,13 @@ var MengineDocSession = class {
 	manager;
 	events = new EventBus();
 	disposables = new DisposableSet();
-	mutationGuard = new DocumentMutationGuard();
+	mutationGuard;
 	adapterValue = null;
 	editorValue = null;
 	undoManagerValue = null;
 	started = false;
 	startTask = null;
 	destroyed = false;
-	closeTask = null;
 	lifetime = null;
 	hasConnected = false;
 	initialVersionValue = null;
@@ -2725,14 +233,17 @@ var MengineDocSession = class {
 	* doc (e.g. nothing was edited since the last confirmed push).
 	*/
 	serverVVValue = null;
-	constructor(options) {
+	constructor(options, model) {
 		this.options = options;
+		this.model = model;
+		this.mutationGuard = new DocumentMutationGuard(options.readonlyMode);
 		this.docId = options.docId;
 		this.local = options.localStorage ?? new MemoryDocStorage();
 		this.server = new MedeoHttpDocStorage({
 			docId: options.docId,
 			client: options.client,
-			sseReconnectDelayMs: options.sseReconnectDelayMs
+			sseReconnectDelayMs: options.sseReconnectDelayMs,
+			readonlyMode: options.readonlyMode
 		});
 		this.synchronizer = new ClientServerSynchronizer(this.local, this.server);
 		this.manager = new DocManager(this.local, this.synchronizer);
@@ -2815,6 +326,19 @@ 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());
+	}
+	get document() {
+		if (this.adapterValue == null || this.editorValue == null) throw new Error("mengine doc session is not started");
+		return this.adapterValue.document;
+	}
 	/** Current document snapshot (read model). */
 	snapshot() {
 		if (this.adapterValue == null) throw new Error("mengine doc session is not started");
@@ -2914,13 +438,6 @@ var MengineDocSession = class {
 		this.local.connection.connect();
 		await this.local.connection.waitForConnected().abortOn(this.lifetime.signal);
 		if (this.destroyed) throw new Error("mengine doc session destroyed");
-		if (this.options.initialSnapshot) {
-			await this.local.pushDocUpdate({
-				docId: this.docId,
-				data: this.options.initialSnapshot
-			}, "initial-snapshot");
-			if (this.destroyed) throw new Error("mengine doc session destroyed");
-		}
 		this.server.connection.connect();
 		this.synchronizer.start();
 		this.manager.start();
@@ -2929,64 +446,33 @@ var MengineDocSession = class {
 		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);
-		this.adapterValue = new MirrorVideoDocumentAdapter(doc, this.mutationGuard);
-		const unsubscribe = doc.subscribe((event) => {
-			if (this.adapterValue == null) return;
-			if (event.by === "local") this.trackLocalVersion(doc.version());
-			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.onLocalUpdateReceived(this.docId, (update) => {
-			this.trackLocalVersion(decodeImportBlobMeta(update, true).partialEndVersionVector);
-			this.emitSyncState();
-		}));
 		this.disposables.add(this.manager.onDocStateChange(this.docId, (state) => {
 			this.events.emit("state", state);
 			this.emitSyncState();
 		}));
 		await this.waitForInitialLoad();
 		if (this.destroyed) throw new Error("mengine doc session destroyed");
-		assertValidVideoDocument(this.snapshot());
+		this.adapterValue = this.model(doc, this.mutationGuard);
+		this.disposables.add(this.adapterValue.subscribe((source) => {
+			if (!this.adapterValue) return;
+			if (source === "local") this.localVersionValue = doc.version();
+			this.emitSyncState();
+			this.events.emit("update", {
+				source,
+				snapshot: this.adapterValue.snapshot()
+			});
+		}));
+		this.events.emit("update", {
+			source: "remote",
+			snapshot: this.snapshot()
+		});
+		if (this.destroyed) throw new Error("mengine doc session destroyed");
 		this.undoManagerValue = new DocumentUndoManager(doc, this.mutationGuard, () => this.events.emit("undoState"));
-		this.editorValue = new SemanticEditor(this.adapterValue);
+		this.editorValue = this.adapterValue.editor;
 		this.initialVersionValue = doc.version();
-		if (this.localVersionValue) this.trackLocalVersion(this.initialVersionValue);
 		this.emitSyncState();
 		return this.snapshot();
 	}
-	getLocalSaveState() {
-		return this.getState().localSave;
-	}
-	/** Immediately reports local transaction state; independent of server confirmation. */
-	subscribeLocalSaveState(cb) {
-		const off = this.events.on("state", () => cb(this.getLocalSaveState()));
-		cb(this.getLocalSaveState());
-		return off;
-	}
-	/** Waits until all local saves finish, including edits made while waiting. Does not wait for the network. */
-	async waitForLocalSave(options = {}) {
-		if (!this.editorValue || this.destroyed) throw new Error("mengine doc session is not started");
-		await this.manager.waitForLocalSave(this.docId).timeout(options.timeoutMs ?? 15e3);
-	}
-	/** Stop accepting edits and drain local persistence before releasing resources.
-	* A failed local write keeps retrying, even after the host has unmounted.
-	* Hosts should use this for normal teardown; destroy() is immediate cancellation. */
-	close() {
-		if (this.closeTask) return this.closeTask;
-		if (this.destroyed || !this.editorValue) {
-			this.destroy();
-			return Promise.resolve();
-		}
-		this.mutationGuard.close();
-		this.synchronizer.stop();
-		this.server.connection.disconnect();
-		this.closeTask = this.manager.waitForLocalSave(this.docId).then(() => this.destroy());
-		return this.closeTask;
-	}
 	getSyncState() {
 		const state = this.getState();
 		const target = this.confirmationTarget();
@@ -2997,14 +483,6 @@ var MengineDocSession = class {
 			phase: connection === "disconnected" ? "offline" : this.pushErrorValue != null || state.error != null ? "failed" : connection === "connecting" ? "connecting" : state.syncing ? "syncing" : "idle"
 		};
 	}
-	trackLocalVersion(version) {
-		const target = VersionVector.parseJSON(this.confirmationTarget()?.toJSON() ?? /* @__PURE__ */ new Map());
-		for (const [peer, counter] of version.toJSON()) if ((target.get(peer) ?? 0) < counter) target.setEnd({
-			peer,
-			counter
-		});
-		this.localVersionValue = target;
-	}
 	confirmationTarget() {
 		return this.localVersionValue ?? this.initialVersionValue;
 	}
@@ -3092,4 +570,29 @@ 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 };
+//#region src/session/mengine-doc-session.ts
+/** Default collaborative session: one DSL handle and one editor over the synchronized LoroDoc. */
+var MengineDocSession = class extends DocumentSession {
+	constructor(options) {
+		super(options, (doc, guard) => {
+			assertDslDocument(doc);
+			const dsl = new MedeoDsl(doc, { mutationGuard: guard });
+			return {
+				doc,
+				document: dsl,
+				editor: new DslEditor(dsl),
+				snapshot: () => dsl.getSnapshot(),
+				subscribe: (listener) => dsl.subscribe(listener),
+				dispose: () => dsl.dispose()
+			};
+		});
+	}
+	get dsl() {
+		return this.document;
+	}
+	projectVideoDraft() {
+		return toVideoDraft(this.snapshot());
+	}
+};
+//#endregion
+export { DEFAULT_UNIT_TIME_MS, DslEditor, DslProjectionError, ManualSyncDoc, MedeoDsl, MedeoHttpDocStorage, MemoryDocStorage, MengineAckFailedError, MengineDocSession, MengineHttpClient, MengineHttpRequestError, MenginePushRejectedError, UnsupportedDocumentFormatError, assertDslDocument, base64ToBytes, bytesToBase64, captionContentCodec, createInitialMedeoDsl, decodeDocVersionMark, defaultIdFactory, documentFormat, encodeDocVersionMark, fromVideoDraft, isInvalidAtomic, medeoDslLoroShape, readMengineEventStream, relationId, resolveDslLayout, resourceId, timeAnchorCodec, toVideoDraft, tupleHash };