@mengine/medeo-client 1.1.0 → 1.2.1-alpha.0

package/dist/index.js

@@ -1,6 +1,5 @@
-import { t as __exportAll } from "./chunk-D7D4PA-g.js";
-import { A as partDurationMs, C as reassignSpeechesToVideoClipsByTime, D as syncAggregatedClipsTimePosition, E as resolveSpeechOverlapByShiftingVideos, F as recordEntries, I as videoDocumentMirrorSchema, L as base64ToBytes, M as VIDEO_DOCUMENT_SCHEMA_VERSION, N as effectiveVideoClipDurationMs, O as TIMELINE_SKELETON_DURATION_MS, P as partUnionToDraft, R as bytesToBase64, S as fillMainTrackTimeGaps, T as resolveAllSpeechOverlaps, _ as findLaneTrack, a as buildInitialVideoDocument, b as cascadeAfterVideoClipChanges, c as fromVideoDocument, d as assertValidVideoDocument, f as validateVideoDocument, g as ensureLaneTrack, h as LANE_KINDS_IN_STACK_ORDER, i as readVideoDocumentFromDraft, j as safeDurationMs, k as isEmptyVideoClip, l as toVideoDocument, m as videoDocumentSchema, n as createMirrorVideoDocument, o as buildSpeechHostMap, p as partUnionSchema, r as createMirrorVideoDocumentAdapter, s as derivePositionFromAbs, t as MirrorVideoDocumentAdapter, u as VideoDocumentValidationError, v as laneTrackId, w as recalculateTimelineDuration, x as arrangeMainTrackSeamlessly, y as solveVideoDocument } from "./document-C98vSu7J.js";
-import { z } from "zod";
+import { A as resolveSpeechOverlapByShiftingVideos, B as partUnionToDraft, C as solveVideoDocument, D as reassignSpeechesToVideoClipsByTime, E as fillMainTrackTimeGaps, F as safeDurationMs, H as videoDocumentMirrorSchema, I as DEFAULT_UNIT_TIME_MS, L as VIDEO_DOCUMENT_SCHEMA_VERSION, M as TIMELINE_SKELETON_DURATION_MS, N as isEmptyVideoClip, O as recalculateTimelineDuration, P as partDurationMs, R as effectiveVideoClipDurationMs, S as laneTrackId, T as arrangeMainTrackSeamlessly, U as base64ToBytes, V as recordEntries, W as bytesToBase64, _ as partUnionSchema, a as createMirrorVideoDocument, b as ensureLaneTrack, c as readVideoDocumentFromDraft, d as derivePositionFromAbs, f as fromVideoDocument, g as validateVideoDocument, h as assertValidVideoDocument, i as MirrorVideoDocumentAdapter, j as syncAggregatedClipsTimePosition, k as resolveAllSpeechOverlaps, l as buildInitialVideoDocument, m as VideoDocumentValidationError, n as createPlainMemoryAdapter, o as createMirrorVideoDocumentAdapter, p as toVideoDocument, r as generatePartId, s as writeVideoDocumentToDraft, t as PlainMemoryAdapter, u as buildSpeechHostMap, v as videoDocumentSchema, w as cascadeAfterVideoClipChanges, x as findLaneTrack, y as LANE_KINDS_IN_STACK_ORDER, z as speedOf } from "./document-49OdvviW.js";
+import { addSpeechesInputSchema, addVideoClipsInputSchema, adjustBgmVolumeInputSchema, adjustSpeechVolumeInputSchema, adjustVideoClipDurationInputSchema, adjustVideoClipVolumeInputSchema, changeSpeechScriptInputSchema, changeSpeechVoiceInputSchema, deleteBgmInputSchema, deleteSpeechesInputSchema, deleteVideoClipsInputSchema, moveSpeechesInputSchema, moveVideoClipsByAnchorInputSchema, moveVideoClipsInputSchema, replaceVideoClipContentInputSchema, replaceVideoClipSequenceInputSchema, setBgmInputSchema, setCaptionStyleInputSchema, setCaptionVisibilityInputSchema, setVideoClipSpeedShiftInputSchema, t as schemas_exports } from "./schemas.js";
 import { LoroDoc, VersionVector } from "loro-crdt";
 import { ClientServerSynchronizer, DocManager } from "@mengine/sync";
 import { DisposableSet, EventBus, Task } from "@mengine/utils";
@@ -218,566 +217,6 @@ function findSseFrameBoundary(buffer) {
 	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;
@@ -1126,9 +565,11 @@ function readPartLibrary(draft) {
 var SemanticEditor = class {
 	doc;
 	validator;
-	constructor(doc, validator = new SchemaValidator()) {
+	idFactory;
+	constructor(doc, validator = new SchemaValidator(), idFactory = generatePartId) {
 		this.doc = doc;
 		this.validator = validator;
+		this.idFactory = idFactory;
 	}
 	async moveVideoClips(input, options) {
 		this.validator.validateMoveVideoClips(input, this.doc);
@@ -1208,7 +649,7 @@ var SemanticEditor = class {
 			track.items ??= [];
 			let at = insertIndex;
 			for (const clip of input.clips) {
-				const partId = generatePartId("clip");
+				const partId = this.idFactory("clip");
 				setPart(draft, partId, { video_clip: {
 					id: partId,
 					kind: "video_clip",
@@ -1255,7 +696,7 @@ var SemanticEditor = class {
 			const newItems = [];
 			const newClipIds = [];
 			for (const clip of input.new_clips) {
-				const partId = generatePartId("clip");
+				const partId = this.idFactory("clip");
 				setPart(draft, partId, { video_clip: {
 					id: partId,
 					kind: "video_clip",
@@ -1875,6 +1316,111 @@ function deleteAnchoredSubtree(draft, clipId) {
 	for (const speechId of anchored) deleteSpeechSubtree(draft, speechId);
 }
 //#endregion
+//#region src/editor/journal.ts
+/**
+* Wire a plain-memory adapter + editor that share a recording id factory, so
+* every mutating transact lands in `journal` with ordered `generated_ids`.
+*/
+function createEditSandbox(document, options) {
+	const adapter = createPlainMemoryAdapter(document, options);
+	return {
+		adapter,
+		editor: new SemanticEditor(adapter, new SchemaValidator(), adapter.idFactory),
+		journal: adapter.journal
+	};
+}
+/**
+* Re-drive `doc` from a recorded journal, forcing each entry's `generated_ids`
+* through a queue-backed id factory. Never mints fresh ids: an empty queue on
+* demand throws `unrecorded id`; leftover ids after an entry throws
+* `unconsumed ids`. Legacy entries without `generated_ids` are treated as `[]`.
+*/
+async function replayJournal(doc, journal) {
+	const queue = [];
+	const idFactory = (_prefix) => {
+		const id = queue.shift();
+		if (id == null) throw new Error("unrecorded id");
+		return id;
+	};
+	const editor = new SemanticEditor(doc, new SchemaValidator(), idFactory);
+	for (const entry of journal) {
+		queue.push(...entry.generated_ids ?? []);
+		await dispatchEntry(editor, entry);
+		if (queue.length > 0) throw new Error("unconsumed ids");
+	}
+}
+/** Dispatch one journal entry to the matching editor method; payload is passed through. */
+async function dispatchEntry(editor, entry) {
+	const payload = entry.payload;
+	const options = entry.intent != null ? { intent: entry.intent } : void 0;
+	switch (entry.kind) {
+		case "MoveVideoClips":
+			await editor.moveVideoClips(payload, options);
+			return;
+		case "MoveVideoClipsByAnchor":
+			await editor.moveVideoClipsByAnchor(payload, options);
+			return;
+		case "DeleteVideoClips":
+			await editor.deleteVideoClips(payload, options);
+			return;
+		case "AddVideoClips":
+			await editor.addVideoClips(payload, options);
+			return;
+		case "AdjustVideoClipVolume":
+			await editor.adjustVideoClipVolume(payload, options);
+			return;
+		case "SetVideoClipSpeedShift":
+			await editor.setVideoClipSpeedShift(payload, options);
+			return;
+		case "ReplaceVideoClipContent":
+			await editor.replaceVideoClipContent(payload, options);
+			return;
+		case "ReplaceVideoClipSequence":
+			await editor.replaceVideoClipSequence(payload, options);
+			return;
+		case "AdjustVideoClipDuration":
+			await editor.adjustVideoClipDuration(payload, options);
+			return;
+		case "AddSpeeches":
+			await editor.addSpeeches(payload, options);
+			return;
+		case "DeleteSpeeches":
+			await editor.deleteSpeeches(payload, options);
+			return;
+		case "MoveSpeeches":
+			await editor.moveSpeeches(payload, options);
+			return;
+		case "ChangeSpeechScript":
+			await editor.changeSpeechScript(payload, options);
+			return;
+		case "ChangeSpeechVoice":
+			await editor.changeSpeechVoice(payload, options);
+			return;
+		case "AdjustSpeechVolume":
+			await editor.adjustSpeechVolume(payload, options);
+			return;
+		case "SetCaptionVisibility":
+			await editor.setCaptionVisibility(payload, options);
+			return;
+		case "SetCaptionStyle":
+			await editor.setCaptionStyle(payload, options);
+			return;
+		case "SetBgm":
+			await editor.setBgm(payload, options);
+			return;
+		case "DeleteBgm":
+			await editor.deleteBgm(payload, options);
+			return;
+		case "AdjustBgmVolume":
+			await editor.adjustBgmVolume(payload, options);
+			return;
+		default: {
+			const _exhaustive = entry.kind;
+			throw new Error(`replayJournal: unsupported kind ${String(_exhaustive)}`);
+		}
+	}
+}
+//#endregion
 //#region src/editor/types.ts
 /** Runtime list of the frozen, implemented kinds (for guards / introspection). */
 const IMPLEMENTED_SEMANTIC_OP_KINDS = [
@@ -2348,13 +1894,18 @@ var MedeoHttpDocStorage = class {
 		};
 	}
 	/**
-	* Forward one update to the server.
+	* Forward one update to the server, returning what the server says it now holds.
 	*
-	* The `DocStorage` contract returns `void`, so the server's verdict cannot be
-	* the return value — it is published on {@link subscribePushOutcome} instead,
-	* for BOTH outcomes and failures. That channel is what makes the push
-	* observable; previously the verdict was read and dropped, so a `duplicate`
-	* (bytes contributed nothing) was indistinguishable from a successful write.
+	* 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.
@@ -2362,14 +1913,17 @@ var MedeoHttpDocStorage = class {
 	*/
 	async pushDocUpdate(update, _origin) {
 		this.assertDocId(update.docId);
-		if (this.isReadonly || update.data.byteLength === 0) return;
+		if (this.isReadonly) throw new Error(`MedeoHttpDocStorage is readonly; refusing to push ${update.docId}`);
+		if (update.data.byteLength === 0) return {};
 		try {
 			const response = await this.client.pushUpdate(update.data);
+			const serverVV = decodeServerVV(response.version?.server_vv);
 			this.events.emit("pushOutcome", {
 				kind: response.kind,
 				updateSeq: response.update_seq ?? void 0,
-				serverVV: decodeServerVV(response.version?.server_vv)
+				serverVV
 			});
+			return { version: serverVV };
 		} catch (error) {
 			const failure = error instanceof Error ? error : new Error(String(error));
 			const rejected = error instanceof MenginePushRejectedError;
@@ -2467,6 +2021,7 @@ var MemoryDocStorage = class extends BaseDocStorage {
 			},
 			origin
 		});
+		return {};
 	}
 	async deleteDoc(docId) {
 		this.entries.delete(docId);
@@ -2659,6 +2214,24 @@ var MengineDocSession = class {
 		if (this.editorValue == null) throw new Error("mengine doc session is not started");
 		return this.editorValue;
 	}
+	/**
+	* Opaque version token of the local oplog (base64 `VersionVector.encode`).
+	* Equality-comparable only: equal means no observed change (local or
+	* remote-arrived) since the token was taken. Throws when not started.
+	*/
+	version() {
+		if (this.adapterValue == null) throw new Error("mengine doc session is not started");
+		return bytesToBase64(this.adapterValue.doc.oplogVersion().encode());
+	}
+	/**
+	* The live document adapter, exposed for journal replay (commit channel).
+	* Replaying through it still goes SemanticEditor → Loro → mengine-server —
+	* no write bypass. Typed by the narrow interface on purpose.
+	*/
+	get documentAdapter() {
+		if (this.adapterValue == null) throw new Error("mengine doc session is not started");
+		return this.adapterValue;
+	}
 	/** Current document snapshot (read model). */
 	snapshot() {
 		if (this.adapterValue == null) throw new Error("mengine doc session is not started");
@@ -2769,4 +2342,4 @@ function serverCovers(serverVV, target) {
 	return covers(server, target);
 }
 //#endregion
-export { IMPLEMENTED_SEMANTIC_OP_KINDS, LANE_KINDS_IN_STACK_ORDER, ManualSyncDoc, MedeoHttpDocStorage, MemoryDocStorage, MengineAckFailedError, MengineDocSession, MengineHttpClient, MengineHttpRequestError, MenginePushRejectedError, MirrorVideoDocumentAdapter, SchemaValidator, SemanticEditor, TIMELINE_SKELETON_DURATION_MS, VIDEO_DOCUMENT_SCHEMA_VERSION, ValidationError, VideoDocumentValidationError, arrangeMainTrackSeamlessly, assertValidVideoDocument, base64ToBytes, buildInitialVideoDocument, buildSpeechHostMap, bytesToBase64, cascadeAfterVideoClipChanges, createMirrorVideoDocument, createMirrorVideoDocumentAdapter, decodeDocVersionMark, derivePositionFromAbs, encodeDocVersionMark, ensureLaneTrack, fillMainTrackTimeGaps, findLaneTrack, fromVideoDocument, generatePartId, getAt, hostForAbsMs, isEmptyVideoClip, isImplementedSemanticOpKind, isMap, laneTrackId, mainTrackRanges, partDurationMs, partUnionSchema, readMainTrackItems, readMengineEventStream, readPart, readPartDurationMs, readVideoDocumentFromDraft, reassignSpeechesToVideoClipsByTime, recalculateTimelineDuration, relativePositionForAbs, resolveAllSpeechOverlaps, resolveSpeechOverlapByShiftingVideos, safeDurationMs, schemas_exports as schemas, snapshotToPlain, solveVideoDocument, syncAggregatedClipsTimePosition, toVideoDocument, validateVideoDocument, videoDocumentMirrorSchema, videoDocumentSchema };
+export { DEFAULT_UNIT_TIME_MS, IMPLEMENTED_SEMANTIC_OP_KINDS, LANE_KINDS_IN_STACK_ORDER, ManualSyncDoc, MedeoHttpDocStorage, MemoryDocStorage, MengineAckFailedError, MengineDocSession, MengineHttpClient, MengineHttpRequestError, MenginePushRejectedError, MirrorVideoDocumentAdapter, PlainMemoryAdapter, SchemaValidator, SemanticEditor, TIMELINE_SKELETON_DURATION_MS, VIDEO_DOCUMENT_SCHEMA_VERSION, ValidationError, VideoDocumentValidationError, arrangeMainTrackSeamlessly, assertValidVideoDocument, base64ToBytes, buildInitialVideoDocument, buildSpeechHostMap, bytesToBase64, cascadeAfterVideoClipChanges, createEditSandbox, createMirrorVideoDocument, createMirrorVideoDocumentAdapter, createPlainMemoryAdapter, decodeDocVersionMark, derivePositionFromAbs, effectiveVideoClipDurationMs, encodeDocVersionMark, ensureLaneTrack, fillMainTrackTimeGaps, findLaneTrack, fromVideoDocument, generatePartId, getAt, hostForAbsMs, isEmptyVideoClip, isImplementedSemanticOpKind, isMap, laneTrackId, mainTrackRanges, partDurationMs, partUnionSchema, readMainTrackItems, readMengineEventStream, readPart, readPartDurationMs, readVideoDocumentFromDraft, reassignSpeechesToVideoClipsByTime, recalculateTimelineDuration, relativePositionForAbs, replayJournal, resolveAllSpeechOverlaps, resolveSpeechOverlapByShiftingVideos, safeDurationMs, schemas_exports as schemas, snapshotToPlain, solveVideoDocument, speedOf, syncAggregatedClipsTimePosition, toVideoDocument, validateVideoDocument, videoDocumentMirrorSchema, videoDocumentSchema, writeVideoDocumentToDraft };