@mengine/medeo-client 0.1.3 → 1.0.1-alpha.0

package/dist/document-DgffKwRw.js

@@ -0,0 +1,1593 @@
+import { Mirror, schema } from "loro-mirror";
+import { z } from "zod";
+import { LoroDoc } from "loro-crdt";
+import { produce } from "immer";
+//#region src/client/base64.ts
+function bytesToBase64(bytes) {
+	let binary = "";
+	for (const byte of bytes) binary += String.fromCharCode(byte);
+	return btoa(binary);
+}
+function base64ToBytes(base64) {
+	const binary = atob(base64);
+	const bytes = new Uint8Array(binary.length);
+	for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+	return bytes;
+}
+//#endregion
+//#region src/document/mirror-schema.ts
+/**
+* Declarative `loro-mirror` schema for `VideoDocument` — the canonical structural
+* SSOT and live storage wire (replaces the hand-rolled `@mengine/schema`
+* definition + adapter, see ADR 0008).
+*
+* Mirror gives an in-memory immutable state synced to the Loro doc by declarative
+* diff, so the storage layer no longer hand-writes per-region reconcile or a
+* transaction state machine. The shapes here store only authoritative facts
+* (RFC 02 §6): per-item absolute time, `part_aggregations`, and total duration
+* are projection-derived (cascade-solved at read time), so they are absent here.
+*
+* - tracks live in a single `tracks` `LoroMovableList` keyed by track id
+*   (reference/17 §4). Lane is expressed by each track's `parts_kind`, not by
+*   which container it lives in; order is the movable-list order itself. There is
+*   no `lane` / `lane_order` field, so two peers inserting tracks never collide
+*   on an order integer — list moves are conflict-free (RFC 03 §4). The legacy
+*   keyed-map (`LoroMapRecord` + an integer `lane_order`) and the prior three
+*   named containers are gone; the `main` / `above` / `below` three-pane view is
+*   rebuilt by the projection from `parts_kind`.
+* - each track's `items` is a `LoroMovableList` keyed by `part_id`: a part is
+*   placed at most once per lane, so `part_id` is the stable placement identity.
+*   Reorder diffs to a real Loro `move`, preserving per-item CRDT identity on
+*   every lane (main and secondary alike).
+* - `time_position` is the authoritative positioning fact (RFC 02 §4,
+*   reference/17 §3), carried as an opaque JSON blob string (a whole tagged-union
+*   value, last-writer-wins). The derived `fallback_abs_ms` snapshot sits beside
+*   it as its own number field — a separate LWW unit so a projection refresh
+*   never clobbers a `time_position` edit.
+* - meta lives in a `meta` LoroMap: the mirror root only accepts container
+*   schemas, so meta scalars can't sit at the root as bare values. The domain
+*   `VideoDocument` keeps the same `meta` wrapper, so the shapes are isomorphic
+*   and the read/seed mapping is a near-identity.
+* - `part_library` values are nested `LoroMap`s: the value is a `LoroMap` with
+*   four mutually-exclusive optional part sub-maps (`video_clip` / `speech` /
+*   `caption` / `bgm`), each a `LoroMap` whose fields are stored as real Loro
+*   sub-keys. This makes each field its own CRDT unit, so two peers editing
+*   different fields of the same part (e.g. one volume, one play_out) merge
+*   field-by-field instead of one whole-value overwrite. Field `required` mirrors
+*   the Smithy `@required` contract (see `video_draft_comp.smithy`). `kind` is not
+*   stored (the present sub-key names the kind); `duration_ms` is not stored (it
+*   is derived, reference/17 §5). Nested values that the engine does not edit
+*   field-by-field — `speed_shift` (a tagged union), `voice`, `caption_ids` — stay
+*   as opaque JSON-blob sub-keys via `transform`. The four sub-keys are optional,
+*   so the "exactly one part kind" union invariant is not enforced by the schema
+*   type; it is rebuilt by `draftToPartUnion` on read and gated by zod on write.
+* - a caption's `style` is the one lazily-created optional child container, so
+*   `captionPart` sets `mergeableMapChildContainers: true` — two peers can
+*   concurrently first-create the same caption's `style` (one attribute each), and
+*   only a mergeable child converges instead of last-writer-wins dropping one. All
+*   other nested maps are keyed by a unique id (`part_library`) or created
+*   atomically with their parent (`partValue`'s part sub-map), so they never hit
+*   that concurrent-first-create fork and stay on plain `setContainer`. See the
+*   note on `captionPart` below.
+* - `video_creation_settings` is an opaque JSON blob carried in a string via
+*   `transform`: a whole value, last-writer-wins (no field-level concurrent edits).
+*/
+/**
+* JSON-blob transform for an opaque, last-writer-wins value carried in a Loro
+* string. The field must be declared `required: false`: an absent field decodes
+* to `undefined` (mirror never calls `decode`/`encode` for null/undefined),
+* which is how we represent "no value" instead of encoding a `null` sentinel.
+*/
+function jsonTransform() {
+	return {
+		decode: (value) => JSON.parse(value),
+		encode: (value) => JSON.stringify(value),
+		isEqual: "encoded-value-equality"
+	};
+}
+const trackItem = schema.LoroMap({
+	part_id: schema.String(),
+	time_position: schema.String().transform(jsonTransform()),
+	fallback_abs_ms: schema.Number({ required: false })
+});
+const track = schema.LoroMap({
+	id: schema.String(),
+	parts_kind: schema.String({ required: false }),
+	is_hidden: schema.Boolean({ required: false }),
+	items: schema.LoroMovableList(trackItem, (item) => item.part_id)
+});
+const videoClipPart = schema.LoroMap({
+	id: schema.String(),
+	play_in: schema.Number(),
+	play_out: schema.Number(),
+	volume: schema.Number(),
+	origin_media_id: schema.String(),
+	speed_shift: schema.String({ required: false }).transform(jsonTransform())
+}, { required: false });
+const speechPart = schema.LoroMap({
+	id: schema.String(),
+	media_duration_ms: schema.Number(),
+	audio_script: schema.String(),
+	volume: schema.Number(),
+	audio_storage_key: schema.String(),
+	origin_speech_id: schema.String(),
+	voice: schema.String().transform(jsonTransform()),
+	caption_ids: schema.String().transform(jsonTransform())
+}, { required: false });
+const captionStyle = schema.LoroMap({
+	font_id: schema.String({ required: false }),
+	font_size: schema.Number({ required: false }),
+	font_color: schema.String({ required: false }),
+	font_weight: schema.Number({ required: false }),
+	entrance_animation: schema.String({ required: false }),
+	entrance_animation_duration_ms: schema.Number({ required: false }),
+	stroke_color: schema.String({ required: false }),
+	stroke_width: schema.Number({ required: false }),
+	position_x: schema.Number({ required: false }),
+	position_y: schema.Number({ required: false })
+}, { required: false });
+const captionPart = schema.LoroMap({
+	id: schema.String(),
+	initial_duration_ms: schema.Number(),
+	speech_part_id: schema.String(),
+	text: schema.String(),
+	start_ms: schema.Number(),
+	style: captionStyle
+}, {
+	required: false,
+	mergeableMapChildContainers: true
+});
+const bgmPart = schema.LoroMap({
+	id: schema.String(),
+	audio_storage_key: schema.String(),
+	volume: schema.Number(),
+	origin_media_id: schema.String()
+}, { required: false });
+const partValue = schema.LoroMap({
+	video_clip: videoClipPart,
+	speech: speechPart,
+	caption: captionPart,
+	bgm: bgmPart
+});
+const videoDocumentMirrorSchema = schema({
+	meta: schema.LoroMap({
+		schema_version: schema.String({ required: false }),
+		draft_id: schema.String({ required: false }),
+		project_id: schema.String({ required: false }),
+		owner_id: schema.String({ required: false }),
+		thumbnail_storage_key: schema.String({ required: false }),
+		chat_session_id: schema.String({ required: false }),
+		video_creation_settings: schema.String({ required: false }).transform(jsonTransform()),
+		version: schema.Number({ required: false })
+	}),
+	timeline: schema.LoroMap({ unit_time_ms: schema.Number({ required: false }) }),
+	tracks: schema.LoroMovableList(track, (t) => t.id),
+	part_library: schema.LoroMapRecord(partValue)
+});
+/** Project a discriminated `PartUnion` into the draft's four-optional shape. */
+function partUnionToDraft(part) {
+	if (part.video_clip != null) return { video_clip: omitKind(part.video_clip) };
+	if (part.speech != null) return { speech: omitKind(part.speech) };
+	if (part.caption != null) return { caption: omitKind(part.caption) };
+	return { bgm: omitKind(part.bgm) };
+}
+/**
+* Rebuild a discriminated `PartUnion` from a draft part value: pick the one
+* present sub-key, restore its `kind`, and drop the `$cid`. Returns `undefined`
+* when no part sub-key is present (an empty/placeholder value).
+*/
+function draftToPartUnion(value) {
+	if (value == null) return void 0;
+	const v = value;
+	if (v.video_clip != null) return { video_clip: withKind(v.video_clip, "video_clip") };
+	if (v.speech != null) return { speech: withKind(v.speech, "speech") };
+	if (v.caption != null) return { caption: withKind(v.caption, "caption") };
+	if (v.bgm != null) return { bgm: withKind(v.bgm, "bgm") };
+}
+/** Drop `kind` (not stored) and `$cid` from a part payload for the draft. */
+function omitKind(part) {
+	const { kind: _kind, $cid: _cid, ...rest } = part;
+	return rest;
+}
+/** Restore `kind` (and drop `$cid`) on a part sub-map read from the draft. */
+function withKind(part, kind) {
+	const { $cid: _cid, ...rest } = part;
+	return {
+		...rest,
+		kind
+	};
+}
+/** Entries of a draft record (e.g. `tracks`) with `$cid` stripped. */
+function recordEntries(record) {
+	if (record == null) return [];
+	const out = [];
+	for (const [key, value] of Object.entries(record)) {
+		if (key === "$cid") continue;
+		out.push([key, value]);
+	}
+	return out;
+}
+//#endregion
+//#region src/document/types.ts
+const VIDEO_DOCUMENT_SCHEMA_VERSION = "video-document/v0";
+/** The linear speed multiplier of a `speed_shift`, defaulting to 1 (original). */
+function speedOf(speedShift) {
+	const speed = speedShift?.config?.linear?.speed;
+	return typeof speed === "number" && Number.isFinite(speed) && speed > 0 ? speed : 1;
+}
+/**
+* A video clip's effective timeline duration, derived from authoritative facts
+* (RFC 02, `reference/16` §4, reference/17 §5): the trim window
+* `play_out - play_in` divided by the speed multiplier, rounded to integer ms.
+* `play_in` / `play_out` are optional in the IDL but every write path sets them
+* (defaulting to the whole media), and the legacy-ingest projection backfills the
+* window from a legacy `duration_ms` — so an authoritative clip always carries a
+* trim window and there is no stored `duration_ms` to fall back to. A clip with
+* neither bound yields 0. Speeds the clip up (>1× → shorter) or down (<1×).
+*/
+function effectiveVideoClipDurationMs(clip) {
+	const speed = speedOf(clip.speed_shift);
+	const sourceMs = (clip.play_out ?? 0) - (clip.play_in ?? 0);
+	const effective = Math.round(sourceMs / speed);
+	return Number.isFinite(effective) && effective > 0 ? effective : 0;
+}
+//#endregion
+//#region src/timeline-core/types.ts
+/** Total document duration when there is no real content (matches FE bgm fallback). */
+const TIMELINE_SKELETON_DURATION_MS = 2e4;
+/** Empty placeholder clip marker: a video_clip part with no backing media. */
+function isEmptyVideoClip(part) {
+	const clip = part?.video_clip;
+	if (clip == null) return false;
+	return clip.origin_media_id == null || clip.origin_media_id === "";
+}
+/** Clamp a duration to a non-negative integer (NaN/Infinity/negative → 0). */
+function safeDurationMs(value) {
+	const n = Number(value);
+	if (!Number.isFinite(n) || n <= 0) return 0;
+	return Math.round(n);
+}
+function partDurationMs(doc, partId) {
+	const part = doc.part_library[partId];
+	if (part?.video_clip != null) return safeDurationMs(effectiveVideoClipDurationMs(part.video_clip));
+	if (part?.bgm != null) return doc.timeline.duration_ms > 0 ? doc.timeline.duration_ms : TIMELINE_SKELETON_DURATION_MS;
+	if (part?.speech != null) return safeDurationMs(part.speech.media_duration_ms);
+	if (part?.caption != null) return safeDurationMs(part.caption.initial_duration_ms);
+	return 0;
+}
+//#endregion
+//#region src/timeline-core/cascade.ts
+/**
+* Canonical timeline cascade primitives (ADR 0009).
+*
+* Single source of truth for "how an edit's connected regions move": main-track
+* seamless layout, aggregation position sync + reassignment, total-duration
+* recompute, speech-overlap resolution, gap filling. Reconciled per ADR 0009 §4:
+*
+* - product behavior follows the FE current implementation;
+* - all times are integer ms — positions/durations are rounded, never floated;
+* - function decomposition follows agent-harness (the Python-derived structure).
+*
+* Every function mutates the `TimelineDoc` in place (the editor runs them inside
+* one immer `transact`, so in-place edits diff correctly).
+*/
+/**
+* Lay the main track out head-to-tail from 0, rewriting each item's
+* `abs_time_position`. Items whose part is missing from the library are dropped.
+*/
+function arrangeMainTrackSeamlessly(doc) {
+	const kept = [];
+	let cursor = 0;
+	for (const item of doc.main_track) {
+		if (doc.part_library[item.part_id] == null) continue;
+		item.abs_time_position = cursor;
+		cursor += partDurationMs(doc, item.part_id);
+		kept.push(item);
+	}
+	doc.main_track = kept;
+}
+/**
+* Sync attached parts' absolute positions from their host:
+*   speech.abs   = host_video.abs + relative_time_position
+*   caption.abs  = speech.abs + caption.start_ms
+*/
+function syncAggregatedClipsTimePosition(doc) {
+	const videoByPart = indexByPart(doc.main_track);
+	const speechByPart = indexByPart(doc.speech_track);
+	for (const aggregation of doc.aggregations) {
+		const videoItem = videoByPart.get(aggregation.body_part_id);
+		if (videoItem == null) continue;
+		for (const attachment of aggregation.attachments) {
+			const speechItem = speechByPart.get(attachment.part_id);
+			if (speechItem == null) continue;
+			speechItem.abs_time_position = videoItem.abs_time_position + attachment.relative_time_position;
+		}
+	}
+	for (const captionItem of doc.caption_track) {
+		const captionPart = doc.part_library[captionItem.part_id]?.caption;
+		if (captionPart == null) continue;
+		const speechItem = captionPart.speech_part_id == null ? void 0 : speechByPart.get(captionPart.speech_part_id);
+		if (speechItem == null) continue;
+		captionItem.abs_time_position = speechItem.abs_time_position + safeDurationMs(captionPart.start_ms);
+	}
+}
+/**
+* Reassign each speech to the video clip whose time range contains its start,
+* rebuilding `aggregations`. A speech before the first clip or after the last
+* falls back to the first / last clip respectively (FE: see §4 note — FE falls
+* back to last only; we keep the harness two-sided fallback because a speech
+* dragged before clip 0 belonging to the last clip is clearly wrong, and the FE
+* single-sided rule is an acknowledged rough edge). `relative_time_position` is
+* clamped to a non-negative integer.
+*/
+function reassignSpeechesToVideoClipsByTime(doc) {
+	const ranges = doc.main_track.filter((item) => doc.part_library[item.part_id] != null).map((item) => ({
+		part_id: item.part_id,
+		start: item.abs_time_position,
+		end: item.abs_time_position + partDurationMs(doc, item.part_id)
+	}));
+	if (ranges.length === 0) {
+		doc.aggregations = [];
+		return;
+	}
+	const rebuilt = /* @__PURE__ */ new Map();
+	for (const speechItem of doc.speech_track) {
+		const start = speechItem.abs_time_position;
+		const targetRange = ranges.find((r) => r.start <= start && start < r.end) ?? (start < ranges[0].start ? ranges[0] : ranges[ranges.length - 1]);
+		const relative = Math.max(0, Math.round(start - targetRange.start));
+		const targetId = targetRange.part_id;
+		let aggregation = rebuilt.get(targetId);
+		if (aggregation == null) {
+			aggregation = {
+				body_part_id: targetId,
+				attachments: []
+			};
+			rebuilt.set(targetId, aggregation);
+		}
+		aggregation.attachments.push({
+			part_id: speechItem.part_id,
+			relative_time_position: relative
+		});
+	}
+	doc.aggregations = ranges.map((r) => rebuilt.get(r.part_id)).filter((a) => a != null);
+}
+/**
+* Recompute `timeline.duration_ms` as the max end (abs + duration) across main,
+* speech, and caption lanes (BGM does not extend the timeline).
+*
+* BGM has no authoritative duration (RFC 02 / `reference/16` §0b): its effective
+* length is always the timeline total, so it is not written back here — the
+* projection derives it from `timeline.duration_ms` on read (`partDurationMs`
+* returns the timeline total for a bgm part). The empty-document 20s skeleton is
+* applied at that read step, not stored.
+*/
+function recalculateTimelineDuration(doc) {
+	const max = Math.max(laneEndMs(doc, doc.main_track), laneEndMs(doc, doc.speech_track), laneEndMs(doc, doc.caption_track));
+	doc.timeline.duration_ms = max;
+}
+/**
+* Resolve one speech overlap by shifting the overlapping speech's host video
+* (and every clip after it) right. Returns true when one overlap was resolved;
+* callers loop until it returns false. The compared range is the speech merged
+* with its captions: start = min(speech.start, captions.start) (FE behavior),
+* end = max(speech.end, captions.end).
+*/
+function resolveSpeechOverlapByShiftingVideos(doc) {
+	const speeches = doc.speech_track;
+	for (let i = 1; i < speeches.length; i++) {
+		const prev = speechWithCaptionsRange(doc, speeches[i - 1]);
+		const curr = speechWithCaptionsRange(doc, speeches[i]);
+		if (prev == null || curr == null) continue;
+		if (curr.start >= prev.end) continue;
+		const overlapMs = Math.round(prev.end - curr.start);
+		const hostId = hostVideoOf(doc, speeches[i].part_id);
+		if (hostId == null) continue;
+		const fromIndex = doc.main_track.findIndex((item) => item.part_id === hostId);
+		if (fromIndex < 0) continue;
+		for (let idx = fromIndex; idx < doc.main_track.length; idx++) doc.main_track[idx].abs_time_position += overlapMs;
+		syncAggregatedClipsTimePosition(doc);
+		return true;
+	}
+	return false;
+}
+/**
+* Resolve speech overlaps for one cascade pass. Mirrors the authoritative FE
+* `ensureNoOverlappingClips`, which is documented to resolve AT MOST ONE overlap
+* per cascade and is invoked exactly once at every FE call site — the supported
+* ops each produce at most one new overlap. It is NOT a fixpoint loop: shifting a
+* host right also moves every speech anchored to it, so two speeches sharing a
+* host can never be separated by shifting. Looping to a "fixed point" there does
+* not converge — it accumulates the same overlap every iteration and pushes the
+* clip arbitrarily far right (e.g. a sped-up clip landing at ~287k ms instead of
+* its seamless slot). A single pass matches FE product behavior and terminates.
+*/
+function resolveAllSpeechOverlaps(doc) {
+	resolveSpeechOverlapByShiftingVideos(doc);
+}
+/**
+* Make the main track gapless by adjusting/merging empty placeholder clips or
+* inserting new ones between real clips. Mirrors the harness four-case rule, but
+* the merge of two adjacent empty clips keeps the earlier clip (harness Case 4).
+* Requires `makeEmptyPart` to mint a placeholder part (the editor supplies an
+* id generator).
+*/
+function fillMainTrackTimeGaps(doc, makeEmptyPart) {
+	const items = doc.main_track;
+	let i = 0;
+	while (i < items.length) {
+		const current = items[i];
+		const currentPart = doc.part_library[current.part_id];
+		if (currentPart == null) {
+			i += 1;
+			continue;
+		}
+		const currentEnd = current.abs_time_position + partDurationMs(doc, current.part_id);
+		if (i + 1 >= items.length) break;
+		const next = items[i + 1];
+		const nextPart = doc.part_library[next.part_id];
+		if (nextPart == null) {
+			i += 1;
+			continue;
+		}
+		const gap = next.abs_time_position - currentEnd;
+		if (gap > 0) {
+			if (isEmptyVideoClip(currentPart)) {
+				extendEmptyClip(currentPart.video_clip, gap);
+				continue;
+			}
+			if (isEmptyVideoClip(nextPart)) {
+				next.abs_time_position -= gap;
+				extendEmptyClip(nextPart.video_clip, gap);
+				i += 1;
+				continue;
+			}
+			const { partId } = makeEmptyPart(gap);
+			doc.part_library[partId] = { video_clip: {
+				id: partId,
+				kind: "video_clip",
+				play_in: 0,
+				play_out: gap,
+				volume: 0,
+				origin_media_id: ""
+			} };
+			items.splice(i + 1, 0, {
+				part_id: partId,
+				time_position: { mode: "sequential" },
+				abs_time_position: currentEnd
+			});
+			i += 1;
+			continue;
+		}
+		if (gap === 0 && isEmptyVideoClip(currentPart) && isEmptyVideoClip(nextPart)) {
+			extendEmptyClip(currentPart.video_clip, partDurationMs(doc, next.part_id));
+			items.splice(i + 1, 1);
+			delete doc.part_library[next.part_id];
+			continue;
+		}
+		i += 1;
+	}
+}
+function indexByPart(items) {
+	const map = /* @__PURE__ */ new Map();
+	for (const item of items) map.set(item.part_id, item);
+	return map;
+}
+function laneEndMs(doc, items) {
+	let max = 0;
+	for (const item of items) {
+		if (doc.part_library[item.part_id] == null) continue;
+		const end = item.abs_time_position + partDurationMs(doc, item.part_id);
+		if (end > max) max = end;
+	}
+	return max;
+}
+function extendEmptyClip(clip, byMs) {
+	clip.play_out = safeDurationMs(clip.play_out) + byMs;
+}
+/** speech merged with its captions: start = min, end = max. */
+function speechWithCaptionsRange(doc, speechItem) {
+	const speech = doc.part_library[speechItem.part_id]?.speech;
+	if (speech == null) return null;
+	let start = speechItem.abs_time_position;
+	let end = speechItem.abs_time_position + safeDurationMs(speech.media_duration_ms);
+	for (const captionId of captionIdsOf(speech)) {
+		const captionItem = doc.caption_track.find((item) => item.part_id === captionId);
+		const captionPart = doc.part_library[captionId]?.caption;
+		if (captionItem == null || captionPart == null) continue;
+		const cStart = captionItem.abs_time_position;
+		const cEnd = captionItem.abs_time_position + safeDurationMs(captionPart.initial_duration_ms);
+		if (cStart < start) start = cStart;
+		if (cEnd > end) end = cEnd;
+	}
+	return {
+		start,
+		end
+	};
+}
+function captionIdsOf(speech) {
+	return (speech.caption_ids ?? []).filter((id) => id != null);
+}
+function hostVideoOf(doc, speechPartId) {
+	for (const aggregation of doc.aggregations) if (aggregation.attachments.some((att) => att.part_id === speechPartId)) return aggregation.body_part_id;
+	return null;
+}
+//#endregion
+//#region src/timeline-core/entrypoints.ts
+/**
+* The full solve pipeline: arrange → sync → reassign → resolve-overlap →
+* fill-gaps → recalc. The single cascade the read-side projection runs; ops
+* never call it (they write only facts — RFC 02 §7/§10).
+*/
+function cascadeAfterVideoClipChanges(doc, makeEmptyPart) {
+	arrangeMainTrackSeamlessly(doc);
+	syncAggregatedClipsTimePosition(doc);
+	reassignSpeechesToVideoClipsByTime(doc);
+	resolveAllSpeechOverlaps(doc);
+	fillMainTrackTimeGaps(doc, makeEmptyPart);
+	recalculateTimelineDuration(doc);
+}
+//#endregion
+//#region src/timeline-core/bridge.ts
+/**
+* Solve a `VideoDocument` (authoritative, position-only) into its derived
+* read-view: absolute time per item, `part_aggregations`, and total duration.
+* This is the read side of the single-directional flow — never written back.
+*/
+function solveVideoDocument(document) {
+	const doc = videoDocumentToTimelineDoc(document);
+	let counter = 0;
+	cascadeAfterVideoClipChanges(doc, () => ({ partId: `empty_${counter++}` }));
+	const absByPartId = /* @__PURE__ */ new Map();
+	for (const item of doc.main_track) absByPartId.set(item.part_id, item.abs_time_position);
+	for (const item of doc.speech_track) absByPartId.set(item.part_id, item.abs_time_position);
+	for (const item of doc.caption_track) absByPartId.set(item.part_id, item.abs_time_position);
+	for (const item of doc.bgm_track) absByPartId.set(item.part_id, item.abs_time_position);
+	return {
+		absByPartId,
+		aggregations: doc.aggregations.map((aggregation) => ({
+			body_part_id: aggregation.body_part_id,
+			attachments: aggregation.attachments.map((a) => ({
+				part_id: a.part_id,
+				relative_time_position: a.relative_time_position
+			}))
+		})),
+		durationMs: doc.timeline.duration_ms,
+		partLibrary: doc.part_library
+	};
+}
+function videoDocumentToTimelineDoc(document) {
+	const partLibrary = {};
+	for (const [partId, part] of Object.entries(document.part_library ?? {})) partLibrary[partId] = part;
+	const laneItems = (track) => (track?.items ?? []).map((item) => ({
+		part_id: item.part_id,
+		time_position: item.time_position,
+		abs_time_position: seedAbs(item.time_position, item.fallback_abs_ms),
+		fallback_abs_ms: item.fallback_abs_ms
+	}));
+	const tracks = document.tracks ?? [];
+	let mainItems = [];
+	let speechItems = [];
+	let bgmItems = [];
+	let captionItems = [];
+	for (const t of tracks) switch (t.parts_kind) {
+		case "video_clip":
+			mainItems = mainItems.concat(laneItems(t));
+			break;
+		case "speech":
+			speechItems = speechItems.concat(laneItems(t));
+			break;
+		case "bgm":
+			bgmItems = bgmItems.concat(laneItems(t));
+			break;
+		case "caption":
+			captionItems = captionItems.concat(laneItems(t));
+			break;
+	}
+	return {
+		main_track: mainItems,
+		speech_track: speechItems,
+		caption_track: captionItems,
+		bgm_track: bgmItems,
+		part_library: partLibrary,
+		aggregations: seedAggregations(mainItems, speechItems),
+		timeline: {
+			duration_ms: 0,
+			unit_time_ms: document.timeline?.unit_time_ms ?? 0
+		}
+	};
+}
+/**
+* Seed an item's solve-variable `abs_time_position` from its `time_position` (and
+* the `fallback_abs_ms` snapshot carried beside it): `absolute` → `offsetMs`;
+* `anchored` → `fallbackAbsMs` (last solved position, also the orphan-recovery
+* anchor when the host is gone); `sequential` → 0 (the cascade lays the main
+* track out head-to-tail). The cascade then resolves anchored items against their
+* host, so this seed only needs to put each item somewhere plausible for the
+* first reassign/overlap pass.
+*/
+function seedAbs(position, fallbackAbsMs) {
+	switch (position.mode) {
+		case "absolute": return Math.round(position.offsetMs);
+		case "anchored": return Math.round(fallbackAbsMs ?? 0);
+		case "sequential": return 0;
+	}
+}
+/**
+* Build the cascade `aggregations` parent-map from anchored items: an anchored
+* item's `anchorPartId` is the host's `part_id` (= `body_part_id`), `offsetMs`
+* is `relative_time_position`. Only main-track (video) hosts form aggregations;
+* caption→speech relations are recomputed by the cascade from `caption.start_ms`.
+*/
+function seedAggregations(mainItems, speechItems) {
+	const mainPartIds = new Set(mainItems.map((item) => item.part_id));
+	const byHost = /* @__PURE__ */ new Map();
+	const order = [];
+	for (const speech of speechItems) {
+		if (speech.time_position.mode !== "anchored") continue;
+		const host = speech.time_position.anchorPartId;
+		if (!mainPartIds.has(host)) continue;
+		let aggregation = byHost.get(host);
+		if (aggregation == null) {
+			aggregation = {
+				body_part_id: host,
+				attachments: []
+			};
+			byHost.set(host, aggregation);
+			order.push(host);
+		}
+		aggregation.attachments.push({
+			part_id: speech.part_id,
+			relative_time_position: speech.time_position.offsetMs
+		});
+	}
+	return order.map((host) => byHost.get(host));
+}
+/**
+* Lane-stacking rank for the single `tracks` list (reference/17 §4): caption
+* (above) sits before the video_clip main track, which sits before speech / bgm
+* (below). The `tracks` array is kept in this top-to-bottom order so a freshly
+* minted track lands in the right place and the projection's three-pane rebuild
+* stays deterministic.
+*/
+function laneRank(kind) {
+	switch (kind) {
+		case "caption": return 0;
+		case "video_clip": return 1;
+		case "speech":
+		case "bgm": return 2;
+		default: return 3;
+	}
+}
+/**
+* Insert a freshly-minted track into `tracks` at the position that keeps the
+* lane-stacking order (caption → main → speech/bgm). Inserts before the first
+* track whose rank is strictly greater, so same-rank tracks keep insertion order.
+*/
+function insertTrackByLaneOrder(tracks, track) {
+	const rank = laneRank(track.parts_kind);
+	const at = tracks.findIndex((t) => laneRank(t?.parts_kind) > rank);
+	if (at < 0) tracks.push(track);
+	else tracks.splice(at, 0, track);
+}
+/**
+* Locate a lane's track row in the single `tracks` list by kind, minting an empty
+* row in lane-stacking order if absent (reference/17 §4: lane = `parts_kind`).
+* Ops use this to write authoritative items onto the right lane. The track id
+* mirrors the seed convention (`<kind>_track`).
+*/
+function ensureLaneTrack(draft, kind) {
+	draft.tracks ??= [];
+	let track = draft.tracks.find((t) => t?.parts_kind === kind);
+	if (track == null) {
+		track = {
+			id: kind === "video_clip" ? "main_track" : `${kind}_track`,
+			parts_kind: kind,
+			is_hidden: void 0,
+			items: []
+		};
+		insertTrackByLaneOrder(draft.tracks, track);
+	}
+	track.items ??= [];
+	return track;
+}
+/** Find a secondary lane's track row without minting it. */
+function findLaneTrack(draft, kind) {
+	return (draft.tracks ?? []).find((t) => t?.parts_kind === kind);
+}
+//#endregion
+//#region src/document/zod-schema.ts
+const partKindSchema = z.enum([
+	"video_clip",
+	"speech",
+	"caption",
+	"bgm"
+]);
+const finiteNumber = z.number().finite();
+const trackItemTimePositionSchema = z.discriminatedUnion("mode", [
+	z.object({ mode: z.literal("sequential") }).passthrough(),
+	z.object({
+		mode: z.literal("anchored"),
+		anchorPartId: z.string(),
+		offsetMs: finiteNumber
+	}).passthrough(),
+	z.object({
+		mode: z.literal("absolute"),
+		offsetMs: finiteNumber
+	}).passthrough()
+]);
+const trackItemSchema = z.object({
+	part_id: z.string(),
+	time_position: trackItemTimePositionSchema,
+	fallback_abs_ms: finiteNumber.optional()
+}).passthrough();
+const trackSchema = z.object({
+	id: z.string().optional(),
+	parts_kind: partKindSchema.optional(),
+	is_hidden: z.boolean().optional(),
+	items: z.array(trackItemSchema).optional()
+}).passthrough();
+const speedShiftSchema = z.object({
+	category: z.string().optional(),
+	mode: z.string().optional(),
+	config: z.object({ linear: z.object({ speed: finiteNumber.optional() }).passthrough().optional() }).passthrough().optional()
+}).passthrough();
+const videoClipPartSchema = z.object({
+	id: z.string().optional(),
+	kind: z.literal("video_clip"),
+	duration_ms: finiteNumber.optional(),
+	play_in: finiteNumber,
+	play_out: finiteNumber,
+	volume: finiteNumber,
+	origin_media_id: z.string(),
+	speed_shift: speedShiftSchema.optional()
+}).passthrough();
+const speechPartSchema = z.object({
+	id: z.string().optional(),
+	kind: z.literal("speech"),
+	media_duration_ms: finiteNumber,
+	duration_ms: finiteNumber.optional(),
+	audio_script: z.string(),
+	volume: finiteNumber,
+	audio_storage_key: z.string(),
+	origin_speech_id: z.string(),
+	voice: z.unknown(),
+	caption_ids: z.array(z.string())
+}).passthrough();
+const captionPartSchema = z.object({
+	id: z.string().optional(),
+	kind: z.literal("caption"),
+	initial_duration_ms: finiteNumber,
+	speech_part_id: z.string(),
+	text: z.string(),
+	start_ms: finiteNumber,
+	style: z.object({
+		font_id: z.string().optional(),
+		font_size: finiteNumber.optional(),
+		font_color: z.string().optional(),
+		font_weight: finiteNumber.optional(),
+		entrance_animation: z.string().optional(),
+		entrance_animation_duration_ms: finiteNumber.optional(),
+		stroke_color: z.string().optional(),
+		stroke_width: finiteNumber.optional(),
+		position_x: finiteNumber.optional(),
+		position_y: finiteNumber.optional()
+	}).passthrough().optional()
+}).passthrough();
+const bgmPartSchema = z.object({
+	id: z.string().optional(),
+	kind: z.literal("bgm"),
+	audio_storage_key: z.string(),
+	volume: finiteNumber,
+	origin_media_id: z.string()
+}).passthrough();
+const partUnionSchema = z.union([
+	z.object({ video_clip: videoClipPartSchema }).passthrough(),
+	z.object({ speech: speechPartSchema }).passthrough(),
+	z.object({ caption: captionPartSchema }).passthrough(),
+	z.object({ bgm: bgmPartSchema }).passthrough()
+]).refine((part) => {
+	const p = part;
+	return [
+		"video_clip",
+		"speech",
+		"caption",
+		"bgm"
+	].filter((k) => p[k] != null).length === 1;
+}, { message: "A part_library value must have exactly one of video_clip / speech / caption / bgm" });
+const videoDocumentMetaSchema = z.object({
+	schema_version: z.literal(VIDEO_DOCUMENT_SCHEMA_VERSION),
+	draft_id: z.string().optional(),
+	project_id: z.string().optional(),
+	owner_id: z.string().optional(),
+	thumbnail_storage_key: z.string().optional(),
+	chat_session_id: z.string().optional(),
+	video_creation_settings: z.unknown().optional(),
+	version: finiteNumber.optional()
+}).passthrough();
+const videoDocumentSchema = z.object({
+	meta: videoDocumentMetaSchema,
+	timeline: z.object({ unit_time_ms: finiteNumber.optional() }).passthrough().optional(),
+	tracks: z.array(trackSchema).optional(),
+	part_library: z.record(z.string(), partUnionSchema).optional()
+}).passthrough().refine((doc) => (doc.tracks ?? []).filter((t) => t.parts_kind === "video_clip").length <= 1, {
+	message: "A VideoDocument may have at most one video_clip (main) track",
+	path: ["tracks"]
+});
+//#endregion
+//#region src/document/validation.ts
+/**
+* Business-level schema guard for `VideoDocument` (RFC 03 §9). It is the gate
+* that decides whether an arbitrary value is a *legal* `VideoDocument` before it
+* is written into Loro — distinct from two neighbours:
+*
+* - `zod-schema.ts` (`videoDocumentSchema`) checks structure/shape only; this
+*   file layers the business rules on top (part-kind match, reference integrity,
+*   `position.anchorPartId` targets, value ranges, identity uniqueness).
+* - loro-mirror's own `validateSchema` (run on every `setState`) only checks the
+*   storage structure, never these business invariants.
+*
+* Projection (`projection.ts`) calls `assertValidVideoDocument` before solving a
+* document into the legacy `VideoDraft`.
+*/
+var VideoDocumentValidationError = class extends Error {
+	issues;
+	constructor(issues) {
+		super(`Invalid VideoDocument: ${issues.map((issue) => issue.message).join("; ")}`);
+		this.issues = issues;
+		this.name = "VideoDocumentValidationError";
+	}
+};
+/**
+* Assert the document is legal enough to project. Only `error`-severity issues
+* hard-reject; `recoverable` ones (dangling anchor / orphan, RFC 02 §11.1) are
+* left for the projection to heal on read and do NOT throw. Use
+* `validateVideoDocument` directly to inspect recoverable issues too.
+*/
+function assertValidVideoDocument(document) {
+	const blocking = validateVideoDocument(document).filter((issue) => (issue.severity ?? "error") === "error");
+	if (blocking.length > 0) throw new VideoDocumentValidationError(blocking);
+}
+function validateVideoDocument(document) {
+	const parsed = videoDocumentSchema.safeParse(document);
+	if (!parsed.success) return parsed.error.issues.map((issue) => ({
+		code: "invalid_schema",
+		path: zodPath(issue.path),
+		message: issue.message
+	}));
+	const doc = parsed.data;
+	const issues = [];
+	const partLibrary = doc.part_library ?? {};
+	for (const [partId, part] of Object.entries(partLibrary)) {
+		if (!partUnionSchema.safeParse(part).success) {
+			issues.push({
+				code: "unknown_part_kind",
+				path: `/part_library/${partId}`,
+				message: `Part "${partId}" is not a supported part union`
+			});
+			continue;
+		}
+		const wrapperKind = getPartUnionKind(part);
+		const innerKind = getPartKind(part);
+		if (wrapperKind != null && innerKind != null && wrapperKind !== innerKind) issues.push({
+			code: "part_kind_mismatch",
+			path: `/part_library/${partId}`,
+			message: `Part "${partId}" wrapper kind "${wrapperKind}" does not match inner kind "${innerKind}"`
+		});
+		validatePartValues(partId, part, issues);
+	}
+	for (const [idx, track] of (doc.tracks ?? []).entries()) validateTrack(track, `tracks/${idx}`, partLibrary, issues, track.parts_kind === "video_clip");
+	validateSpeechCaptionReferences(partLibrary, issues);
+	validatePositionReferences(doc, partLibrary, issues);
+	return issues;
+}
+/**
+* An `anchored` item whose `anchorPartId` no longer exists in the library is the
+* orphan condition (RFC 02 §4/§11.1) — e.g. a speech whose host video, or a
+* caption whose host speech, was concurrently deleted while this item was being
+* reparented in. This is flagged as a **recoverable** issue, NOT a hard error:
+* the projection heals it on read (the item's `fallback_abs_ms` snapshot seeds
+* its absolute position, then the cascade reassigns it to the nearest available
+* host, or it stays put as an absolute item). Reporting it here keeps the orphan
+* observable without blocking projection — the opposite of a hard reject, which
+* would make an inevitable concurrent-delete outcome un-projectable (§11.1).
+*/
+function validatePositionReferences(doc, partLibrary, issues) {
+	const tracks = (doc.tracks ?? []).map((track, idx) => ({
+		track,
+		path: `tracks/${idx}`
+	}));
+	for (const { track, path } of tracks) for (const [idx, item] of (track?.items ?? []).entries()) {
+		if (item.time_position.mode !== "anchored") continue;
+		if (partLibrary[item.time_position.anchorPartId] == null) issues.push({
+			code: "invalid_position_anchor",
+			path: `/${path}/items/${idx}/time_position/anchorPartId`,
+			message: `Track item "${path}/${idx}" anchors to missing part "${item.time_position.anchorPartId}"`,
+			severity: "recoverable"
+		});
+	}
+}
+function validatePartValues(partId, part, issues) {
+	const payload = part.video_clip ?? part.speech ?? part.caption ?? part.bgm ?? void 0;
+	if (payload == null) return;
+	if ("duration_ms" in payload && payload.duration_ms != null && payload.duration_ms < 0) issues.push({
+		code: "invalid_part_value",
+		path: `/part_library/${partId}/duration_ms`,
+		message: `Part "${partId}" has negative duration_ms`
+	});
+	if ("volume" in payload && payload.volume != null && !Number.isFinite(payload.volume)) issues.push({
+		code: "invalid_part_value",
+		path: `/part_library/${partId}/volume`,
+		message: `Part "${partId}" has non-finite volume`
+	});
+	if (part.video_clip != null) {
+		const { play_in, play_out } = part.video_clip;
+		if (play_in != null && play_in < 0) issues.push({
+			code: "invalid_part_value",
+			path: `/part_library/${partId}/play_in`,
+			message: `Video clip "${partId}" has negative play_in`
+		});
+		if (play_out != null && play_in != null && play_out < play_in) issues.push({
+			code: "invalid_part_value",
+			path: `/part_library/${partId}/play_out`,
+			message: `Video clip "${partId}" has play_out before play_in`
+		});
+	}
+}
+function validateTrack(track, path, partLibrary, issues, isMainTrack) {
+	if (track == null) return;
+	const seenPartIds = /* @__PURE__ */ new Set();
+	for (const [idx, item] of (track.items ?? []).entries()) {
+		const partId = item.part_id;
+		if (partId != null && partId !== "") if (seenPartIds.has(partId)) issues.push({
+			code: "duplicate_track_item_identity",
+			path: `/${path}/items/${idx}/part_id`,
+			message: `Track item "${path}/${idx}" reuses part_id "${partId}"`
+		});
+		else seenPartIds.add(partId);
+		if (partId == null || partId === "") {
+			issues.push({
+				code: "missing_part_reference",
+				path: `/${path}/items/${idx}/part_id`,
+				message: `Track item "${path}/${idx}" has no part_id`
+			});
+			continue;
+		}
+		const part = partLibrary[partId];
+		if (part == null) {
+			issues.push({
+				code: "missing_part_reference",
+				path: `/${path}/items/${idx}/part_id`,
+				message: `Track item "${path}/${idx}" references missing part "${partId}"`
+			});
+			continue;
+		}
+		const partKind = getPartKind(part);
+		if (isMainTrack && partKind !== "video_clip") issues.push({
+			code: "main_track_non_video_clip",
+			path: `/${path}/items/${idx}/part_id`,
+			message: `Main track item "${path}/${idx}" references non-video part "${partId}"`
+		});
+		if (track.parts_kind != null && partKind != null && track.parts_kind !== partKind) issues.push({
+			code: "track_kind_mismatch",
+			path: `/${path}/items/${idx}/part_id`,
+			message: `Track "${path}" expects "${track.parts_kind}" but part "${partId}" is "${partKind}"`
+		});
+	}
+}
+/**
+* Check speech↔caption references. A reference to a *missing* part (speech's
+* caption_ids → deleted caption, or caption's speech_part_id → deleted speech)
+* is the orphan condition (RFC 02 §11.1): reported as **recoverable** so the
+* projection can heal it on read, not block. A *back-pointer mismatch* (caption
+* exists but does not point back) is data corruption, kept as a hard error.
+*/
+function validateSpeechCaptionReferences(partLibrary, issues) {
+	for (const [partId, part] of Object.entries(partLibrary)) {
+		if (part.speech != null) for (const captionId of part.speech.caption_ids ?? []) {
+			const caption = partLibrary[captionId]?.caption;
+			if (caption == null) {
+				issues.push({
+					code: "invalid_speech_caption_reference",
+					path: `/part_library/${partId}/speech/caption_ids`,
+					message: `Speech "${partId}" references missing caption "${captionId}"`,
+					severity: "recoverable"
+				});
+				continue;
+			}
+			if (caption.speech_part_id !== partId) issues.push({
+				code: "invalid_speech_caption_reference",
+				path: `/part_library/${captionId}/caption/speech_part_id`,
+				message: `Caption "${captionId}" does not point back to speech "${partId}"`
+			});
+		}
+		if (part.caption != null) {
+			const speechId = part.caption.speech_part_id;
+			if (speechId != null && partLibrary[speechId]?.speech == null) issues.push({
+				code: "invalid_speech_caption_reference",
+				path: `/part_library/${partId}/caption/speech_part_id`,
+				message: `Caption "${partId}" references missing speech "${speechId}"`,
+				severity: "recoverable"
+			});
+		}
+	}
+}
+function getPartUnionKind(part) {
+	if (part.video_clip != null) return "video_clip";
+	if (part.speech != null) return "speech";
+	if (part.caption != null) return "caption";
+	if (part.bgm != null) return "bgm";
+}
+function getPartKind(part) {
+	return part.video_clip?.kind ?? part.speech?.kind ?? part.caption?.kind ?? part.bgm?.kind;
+}
+function zodPath(path) {
+	if (path.length === 0) return "/";
+	return `/${path.map(String).join("/")}`;
+}
+//#endregion
+//#region src/document/projection.ts
+/**
+* Projection between the authoritative `VideoDocument` and the legacy
+* `VideoDraft` read-view (RFC 02 §5/§7). Both directions live here:
+*
+* - `toVideoDocument` ingests a `VideoDraft`, deriving each item's `position`
+*   from the legacy absolute layout + aggregations; derived values (abs time,
+*   `part_aggregations`, total duration) are dropped.
+* - `fromVideoDocument` solves a `VideoDocument` back into a `VideoDraft` via the
+*   timeline-core cascade, re-deriving exactly those values.
+*
+* Business validation lives in `validation.ts`; `fromVideoDocument` asserts a
+* valid document before solving.
+*/
+/**
+* Ingest the legacy `VideoDraft` into the authoritative `VideoDocument`,
+* deriving each item's `time_position` from the legacy absolute layout +
+* aggregations (RFC 02 §4/§5). Absolute time, `part_aggregations`, and total
+* duration are dropped — they are re-derived by the projection.
+*/
+function toVideoDocument(draft) {
+	const speechHost = buildSpeechHostMap(draft.part_aggregations);
+	const partLibrary = draft.part_library ?? {};
+	const toTrack = (track, isMain) => {
+		if (track == null) return void 0;
+		return {
+			id: track.id,
+			parts_kind: track.parts_kind,
+			is_hidden: track.is_hidden,
+			items: (track.items ?? []).map((item) => deriveItem(item, isMain, speechHost, partLibrary))
+		};
+	};
+	const mainTrack = toTrack(draft.main_track, true);
+	const tracks = [
+		...(draft.above_main_tracks ?? []).map((t) => toTrack(t, false)),
+		...mainTrack == null ? [] : [mainTrack],
+		...(draft.below_main_tracks ?? []).map((t) => toTrack(t, false))
+	];
+	return {
+		meta: {
+			schema_version: VIDEO_DOCUMENT_SCHEMA_VERSION,
+			draft_id: draft.id,
+			project_id: draft.project_id,
+			owner_id: draft.owner_id,
+			thumbnail_storage_key: draft.thumbnail_storage_key,
+			chat_session_id: draft.chat_session_id,
+			video_creation_settings: clone(draft.video_creation_settings),
+			version: draft.version
+		},
+		timeline: draft.timeline == null ? void 0 : { unit_time_ms: draft.timeline.unit_time_ms },
+		tracks,
+		part_library: toAuthoritativePartLibrary(draft.part_library)
+	};
+}
+/**
+* Map the legacy `VideoDraft` part library into the authoritative shape
+* (reference/17 §5): the authoritative parts store no derived part-level
+* duration, so the read-view `duration_ms` is dropped from video / speech / bgm.
+* For a caption the legacy `duration_ms` is the generation-time length, stored
+* authoritatively as `initial_duration_ms`.
+*/
+function toAuthoritativePartLibrary(partLibrary) {
+	if (partLibrary == null) return void 0;
+	const out = {};
+	for (const [partId, part] of Object.entries(partLibrary)) {
+		if (typeof part !== "object" || part == null) continue;
+		if (part.video_clip != null) out[partId] = { video_clip: withTrimWindowFromDuration(part.video_clip) };
+		else if (part.speech != null) {
+			const { duration_ms, rest } = splitDurationMs(part.speech);
+			out[partId] = { speech: {
+				...rest,
+				media_duration_ms: rest.media_duration_ms ?? duration_ms
+			} };
+		} else if (part.caption != null) {
+			const { duration_ms, rest } = splitDurationMs(part.caption);
+			out[partId] = { caption: {
+				...rest,
+				initial_duration_ms: duration_ms
+			} };
+		} else if (part.bgm != null) out[partId] = { bgm: omitDurationMs(part.bgm) };
+	}
+	return out;
+}
+/**
+* Build a speech-host map from a part_aggregations list. Used by
+* `toVideoDocument` (legacy VideoDraft → VideoDocument) to recover each speech's
+* host video clip and relative offset. Aggregation items with null ids are
+* skipped (malformed input tolerance).
+*/
+function buildSpeechHostMap(aggregations) {
+	const map = /* @__PURE__ */ new Map();
+	for (const aggregation of aggregations ?? []) {
+		const host = aggregation.body_part_id;
+		if (host == null) continue;
+		for (const attachment of aggregation.attachments ?? []) {
+			if (attachment.part_id == null) continue;
+			map.set(attachment.part_id, {
+				hostPartId: host,
+				offsetMs: Math.round(attachment.relative_time_position ?? 0)
+			});
+		}
+	}
+	return map;
+}
+/**
+* Derive `time_position` (and `fallbackAbsMs` for anchored items) from a legacy
+* absolute time + pre-built speech-host map + part library. The three-branch
+* rule (RFC 02 §4/§5, reference/17 §3):
+*
+*   1. main-track → `sequential`
+*   2. speech/attachment (part_id in speechHost) → `anchored(host, offsetMs)`
+*   3. caption (part has `speech_part_id`) → `anchored(speech, start_ms)`
+*   4. everything else → `absolute(abs)`
+*
+* `partLibrary` values may be `PartUnion | string | undefined` (draft raw
+* form); only object-typed entries are inspected for `caption`.
+*/
+function derivePositionFromAbs(partId, abs, isMain, speechHost, partLibrary) {
+	if (isMain) return { timePosition: { mode: "sequential" } };
+	const host = speechHost.get(partId);
+	if (host != null) return {
+		timePosition: {
+			mode: "anchored",
+			anchorPartId: host.hostPartId,
+			offsetMs: host.offsetMs
+		},
+		fallbackAbsMs: abs
+	};
+	const part = partLibrary[partId];
+	const captionPart = typeof part === "object" && part != null ? part.caption : void 0;
+	const speechId = captionPart?.speech_part_id ?? void 0;
+	if (speechId != null) return {
+		timePosition: {
+			mode: "anchored",
+			anchorPartId: speechId,
+			offsetMs: Math.round(captionPart?.start_ms ?? 0)
+		},
+		fallbackAbsMs: abs
+	};
+	return { timePosition: {
+		mode: "absolute",
+		offsetMs: abs
+	} };
+}
+/** Derive one item's authoritative `time_position` from its legacy abs + aggregation. */
+function deriveItem(item, isMain, speechHost, partLibrary) {
+	const partId = item.part_id ?? "";
+	const { timePosition, fallbackAbsMs } = derivePositionFromAbs(partId, Math.round(item.abs_time_position ?? 0), isMain, speechHost, partLibrary);
+	return fallbackAbsMs == null ? {
+		part_id: partId,
+		time_position: timePosition
+	} : {
+		part_id: partId,
+		time_position: timePosition,
+		fallback_abs_ms: fallbackAbsMs
+	};
+}
+/**
+* Project the authoritative `VideoDocument` back into the legacy `VideoDraft`
+* read-view, solving each item's absolute position, the `part_aggregations`, and
+* the total duration via the timeline-core cascade.
+*/
+function fromVideoDocument(document) {
+	assertValidVideoDocument(document);
+	const view = solveVideoDocument(document);
+	const tracks = document.tracks ?? [];
+	const mainTrack = tracks.find((t) => t.parts_kind === "video_clip");
+	const aboveTracks = tracks.filter((t) => t.parts_kind === "caption");
+	const belowTracks = tracks.filter((t) => t.parts_kind === "speech" || t.parts_kind === "bgm");
+	return {
+		id: document.meta.draft_id,
+		project_id: document.meta.project_id,
+		owner_id: document.meta.owner_id,
+		thumbnail_storage_key: document.meta.thumbnail_storage_key,
+		timeline: {
+			duration_ms: view.durationMs,
+			unit_time_ms: document.timeline?.unit_time_ms
+		},
+		video_creation_settings: clone(document.meta.video_creation_settings),
+		chat_session_id: document.meta.chat_session_id,
+		main_track: draftTrack(mainTrack, view.absByPartId),
+		above_main_tracks: aboveTracks.map((t) => draftTrack(t, view.absByPartId)),
+		below_main_tracks: belowTracks.map((t) => draftTrack(t, view.absByPartId)),
+		part_aggregations: view.aggregations,
+		part_library: toReadViewPartLibrary(view.partLibrary, view.durationMs),
+		version: document.meta.version
+	};
+}
+/**
+* Map the authoritative part library into the `VideoDraft` read-view shape,
+* re-injecting the derived effective `duration_ms` downstream expects
+* (reference/17 §5/§7) — the authoritative parts store no part-level duration:
+*
+* - video clip → `(play_out - play_in) / speed` (`effectiveVideoClipDurationMs`)
+* - speech → its intrinsic `media_duration_ms` (no trim/speed)
+* - caption → its generation-time `initial_duration_ms`
+* - bgm → the timeline total (`durationMs`)
+*
+* Parts are deep-cloned; the engine extensions (`media_duration_ms`,
+* `initial_duration_ms`) are kept alongside the injected `duration_ms`.
+*/
+function toReadViewPartLibrary(partLibrary, durationMs) {
+	const out = {};
+	for (const [partId, part] of Object.entries(partLibrary)) if (part.video_clip != null) {
+		const clip = clone(part.video_clip);
+		out[partId] = { video_clip: {
+			...clip,
+			duration_ms: effectiveVideoClipDurationMs(clip)
+		} };
+	} else if (part.speech != null) {
+		const speech = clone(part.speech);
+		out[partId] = { speech: {
+			...speech,
+			duration_ms: speech.media_duration_ms
+		} };
+	} else if (part.caption != null) {
+		const caption = clone(part.caption);
+		out[partId] = { caption: {
+			...caption,
+			duration_ms: caption.initial_duration_ms
+		} };
+	} else if (part.bgm != null) out[partId] = { bgm: {
+		...clone(part.bgm),
+		duration_ms: durationMs
+	} };
+	return out;
+}
+/** Deep-clone a part payload, dropping the derived read-view `duration_ms`. */
+function omitDurationMs(part) {
+	const { duration_ms: _drop, ...rest } = clone(part);
+	return rest;
+}
+/**
+* Migrate a legacy video clip into the authoritative trim-window-only shape: the
+* authoritative part stores no `duration_ms`, so it is dropped — but a legacy
+* clip with no explicit trim window (`play_in` / `play_out` absent) would then
+* compute an effective length of 0 and vanish from the layout. When that clip
+* carried a legacy `duration_ms`, backfill it as the trim window (`play_in` 0,
+* `play_out = duration_ms`, no speed) so the effective length is preserved, then
+* drop `duration_ms`. A clip that already has a trim window keeps it verbatim.
+*/
+function withTrimWindowFromDuration(clip) {
+	const stripped = omitDurationMs(clip);
+	if (clip.play_in != null || clip.play_out != null) return stripped;
+	const legacyDuration = clip.duration_ms;
+	if (legacyDuration == null || !Number.isFinite(legacyDuration)) return stripped;
+	return {
+		...stripped,
+		play_in: 0,
+		play_out: legacyDuration
+	};
+}
+/** Deep-clone a part payload, returning its `duration_ms` separately from the rest. */
+function splitDurationMs(part) {
+	const { duration_ms, ...rest } = clone(part);
+	return {
+		duration_ms,
+		rest
+	};
+}
+function draftTrack(track, absByPartId) {
+	if (track == null) return void 0;
+	return {
+		id: track.id,
+		parts_kind: track.parts_kind,
+		is_hidden: track.is_hidden,
+		items: (track.items ?? []).map((item) => ({
+			part_id: item.part_id,
+			abs_time_position: absByPartId.get(item.part_id) ?? 0
+		}))
+	};
+}
+function clone(value) {
+	if (Array.isArray(value)) return value.map((item) => clone(item));
+	if (value != null && typeof value === "object") {
+		const result = {};
+		for (const [key, child] of Object.entries(value)) result[key] = clone(child);
+		return result;
+	}
+	return value;
+}
+//#endregion
+//#region src/document/mirror-read.ts
+/**
+* Project the mirror state (`VideoDocumentDraft`) into the authoritative
+* `VideoDocument`. The storage shape is isomorphic to the domain shape (RFC 03
+* §4, reference/17 §4: meta map + a single `tracks` list + part_library), so this
+* is a near-identity — it reads `time_position` / `fallback_abs_ms` JSON blobs
+* back into structured values and trims empty strings, nothing more.
+*
+* It maps only authoritative facts (RFC 02 §6): `part_id` + `time_position`. The
+* projection-derived `VideoDraft` read-view (absolute time, `part_aggregations`,
+* total duration) is solved separately by the cascade, not here.
+*
+* It reads in-memory mirror state (O(n) over the document), not a Loro
+* `toJSON()` FFI rebuild — the cost the prior schema adapter paid on every
+* `snapshot()`.
+*/
+function readVideoDocumentFromDraft(draft) {
+	const partLibrary = {};
+	for (const [partId, payload] of recordEntries(draft.part_library)) {
+		const part = draftToPartUnion(payload);
+		if (part != null) partLibrary[partId] = part;
+	}
+	const timeline = draft.timeline;
+	const hasTimeline = timeline?.unit_time_ms != null;
+	const meta = draft.meta;
+	return {
+		meta: {
+			schema_version: VIDEO_DOCUMENT_SCHEMA_VERSION,
+			draft_id: emptyToUndefined(meta?.draft_id),
+			project_id: emptyToUndefined(meta?.project_id),
+			owner_id: emptyToUndefined(meta?.owner_id),
+			thumbnail_storage_key: emptyToUndefined(meta?.thumbnail_storage_key),
+			chat_session_id: emptyToUndefined(meta?.chat_session_id),
+			video_creation_settings: meta?.video_creation_settings ?? void 0,
+			version: meta?.version ?? void 0
+		},
+		timeline: hasTimeline ? { unit_time_ms: timeline.unit_time_ms } : void 0,
+		tracks: rowsToTracks(draft.tracks),
+		part_library: partLibrary
+	};
+}
+/** Map a movable-list of track rows (`$cid`-bearing) into domain tracks, dropping empty-id placeholders. */
+function rowsToTracks(rows) {
+	return (rows ?? []).filter((row) => row.id != null && row.id !== "").map(rowToTrack);
+}
+function rowToTrack(row) {
+	return {
+		id: row.id,
+		parts_kind: row.parts_kind ?? void 0,
+		is_hidden: row.is_hidden ?? void 0,
+		items: (row.items ?? []).map((item) => {
+			const result = {
+				part_id: item.part_id ?? "",
+				time_position: item.time_position
+			};
+			if (item.fallback_abs_ms != null) result.fallback_abs_ms = item.fallback_abs_ms;
+			return result;
+		})
+	};
+}
+function emptyToUndefined(value) {
+	return value == null || value === "" ? void 0 : value;
+}
+//#endregion
+//#region src/document/mirror-adapter.ts
+/**
+* Storage-layer adapter that backs a `VideoDocument` with `loro-mirror` (ADR
+* 0008). The mirror holds an in-memory immutable state synced to the `LoroDoc`
+* by declarative diff, replacing the hand-rolled `@mengine/schema` adapter:
+*
+* - `snapshot()` projects the mirror's in-memory state to the read model — no
+*   per-call `toJSON()` FFI rebuild.
+* - `transact(edit, audit)` runs the whole op in one `mirror.setState` callback:
+*   one diff, one `doc.commit` carrying the audit message. The callback edits an
+*   immer draft, so a throw inside it discards the draft and never touches Loro
+*   (natural rollback) — no `guard` / `rollback` / `openTransaction` machinery.
+* - mirror's `idSelector` (track items keyed by `part_id`) diffs reorders to
+*   real Loro `move` ops on every lane, so per-item CRDT identity survives on
+*   main and secondary tracks alike.
+*/
+var MirrorVideoDocumentAdapter = class {
+	doc;
+	mirror;
+	constructor(doc) {
+		this.doc = doc;
+		this.mirror = new Mirror({
+			doc,
+			schema: videoDocumentMirrorSchema
+		});
+	}
+	snapshot() {
+		return readVideoDocumentFromDraft(this.mirror.getState());
+	}
+	/**
+	* True once the doc holds real document content. A fresh mirror over an empty
+	* doc still reports defaulted root maps, so probe the stored `schema_version`
+	* (empty until a snapshot is bootstrapped or synced in).
+	*/
+	hasContent() {
+		return (this.mirror.getState().meta?.schema_version ?? "") !== "";
+	}
+	/**
+	* Apply one op as a single transaction. `edit` mutates the immer draft; mirror
+	* diffs the result and commits once with the audit `message`. A throw in `edit`
+	* discards the draft (Loro untouched). When `edit` produces no change, mirror
+	* skips the commit — matching the prior "empty op leaves no audit" behavior.
+	*/
+	transact(edit, audit) {
+		this.mirror.setState((draft) => {
+			edit(draft);
+		}, {
+			origin: "mengine.semantic_editor",
+			message: JSON.stringify({
+				semantic_op: audit.kind,
+				payload: audit.payload,
+				intent: audit.intent ?? null
+			})
+		});
+	}
+};
+/** Build a fresh Loro doc seeded with `document` through the mirror. */
+function createMirrorVideoDocument(document, options = {}) {
+	assertValidVideoDocument(document);
+	const doc = new LoroDoc();
+	if (options.peerId != null) doc.setPeerId(options.peerId);
+	new Mirror({
+		doc,
+		schema: videoDocumentMirrorSchema
+	}).setState((draft) => {
+		writeVideoDocumentToDraft(draft, document);
+	}, { origin: options.origin ?? "mengine.bootstrap" });
+	return doc;
+}
+/** Build a `MirrorVideoDocumentAdapter` over a fresh doc seeded with `document`. */
+function createMirrorVideoDocumentAdapter(document, options) {
+	return new MirrorVideoDocumentAdapter(createMirrorVideoDocument(document, options));
+}
+/** Write a whole `VideoDocument` into a draft (seed a fresh doc / plain-memory state). */
+function writeVideoDocumentToDraft(draft, document) {
+	draft.meta = {
+		schema_version: document.meta.schema_version,
+		draft_id: document.meta.draft_id ?? void 0,
+		project_id: document.meta.project_id ?? void 0,
+		owner_id: document.meta.owner_id ?? void 0,
+		thumbnail_storage_key: document.meta.thumbnail_storage_key ?? void 0,
+		chat_session_id: document.meta.chat_session_id ?? void 0,
+		video_creation_settings: document.meta.video_creation_settings ?? void 0,
+		version: document.meta.version ?? void 0
+	};
+	draft.timeline = { unit_time_ms: document.timeline?.unit_time_ms ?? void 0 };
+	draft.tracks = (document.tracks ?? []).map(toTrackRow);
+	draft.part_library = {};
+	for (const [partId, part] of Object.entries(document.part_library ?? {})) draft.part_library[partId] = partUnionToDraft(part);
+}
+/** Map a domain `Track` to a draft track row (no lane/lane_order — see schema). */
+function toTrackRow(track) {
+	return {
+		id: track.id ?? "",
+		parts_kind: track.parts_kind ?? void 0,
+		is_hidden: track.is_hidden ?? void 0,
+		items: (track.items ?? []).map((item) => ({
+			part_id: item.part_id,
+			time_position: item.time_position,
+			fallback_abs_ms: item.fallback_abs_ms
+		}))
+	};
+}
+//#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/document/plain-memory-adapter.ts
+/**
+* Pure in-memory `SemanticDocumentAdapter` — no Loro/WASM. Holds a
+* `VideoDocumentDraft` object and applies each `transact` via immer `produce`,
+* journaling every audit that actually mutated state (plus any ids minted
+* during that transact).
+*
+* Known benign difference vs `MirrorVideoDocumentAdapter`: the editor's
+* `setPart` assigns a fresh part object on every call, so a same-value rewrite
+* produces a new immer state and IS journaled here, while the mirror's deep
+* diff emits no commit. Terminal `snapshot()` stays equal; replay is idempotent.
+*/
+var PlainMemoryAdapter = class {
+	state;
+	_journal = [];
+	baseIdFactory;
+	/** Non-null only while a `transact` edit callback is running. */
+	pendingIds = null;
+	/**
+	* Recording wrapper around the underlying factory. Callers (sandbox editor)
+	* use this so every minted id is appended to the current transact's list.
+	*/
+	idFactory;
+	constructor(document, options) {
+		assertValidVideoDocument(document);
+		const draft = {};
+		writeVideoDocumentToDraft(draft, document);
+		this.state = draft;
+		this.baseIdFactory = options?.idFactory ?? generatePartId;
+		this.idFactory = (prefix) => {
+			const id = this.baseIdFactory(prefix);
+			if (this.pendingIds != null) this.pendingIds.push(id);
+			return id;
+		};
+	}
+	get journal() {
+		return this._journal;
+	}
+	hasContent() {
+		return (this.state.meta?.schema_version ?? "") !== "";
+	}
+	snapshot() {
+		return readVideoDocumentFromDraft(this.state);
+	}
+	/**
+	* Apply one op via immer. A throw in `edit` discards the draft (state and
+	* journal unchanged). When `produce` returns the same reference, there was
+	* no structural change — skip journal, matching mirror "no change, no commit".
+	*/
+	transact(edit, audit) {
+		this.pendingIds = [];
+		try {
+			const next = produce(this.state, edit);
+			if (next !== this.state) {
+				this.state = next;
+				this._journal.push({
+					...audit,
+					generated_ids: this.pendingIds
+				});
+			}
+		} finally {
+			this.pendingIds = null;
+		}
+	}
+};
+/** Build a `PlainMemoryAdapter` seeded with `document`. */
+function createPlainMemoryAdapter(document, options) {
+	return new PlainMemoryAdapter(document, options);
+}
+//#endregion
+export { isEmptyVideoClip as A, bytesToBase64 as B, fillMainTrackTimeGaps as C, resolveSpeechOverlapByShiftingVideos as D, resolveAllSpeechOverlaps as E, speedOf as F, partUnionToDraft as I, recordEntries as L, safeDurationMs as M, VIDEO_DOCUMENT_SCHEMA_VERSION as N, syncAggregatedClipsTimePosition as O, effectiveVideoClipDurationMs as P, videoDocumentMirrorSchema as R, arrangeMainTrackSeamlessly as S, recalculateTimelineDuration as T, videoDocumentSchema as _, createMirrorVideoDocument as a, solveVideoDocument as b, readVideoDocumentFromDraft as c, fromVideoDocument as d, toVideoDocument as f, partUnionSchema as g, validateVideoDocument as h, MirrorVideoDocumentAdapter as i, partDurationMs as j, TIMELINE_SKELETON_DURATION_MS as k, buildSpeechHostMap as l, assertValidVideoDocument as m, createPlainMemoryAdapter as n, createMirrorVideoDocumentAdapter as o, VideoDocumentValidationError as p, generatePartId as r, writeVideoDocumentToDraft as s, PlainMemoryAdapter as t, derivePositionFromAbs as u, ensureLaneTrack as v, reassignSpeechesToVideoClipsByTime as w, cascadeAfterVideoClipChanges as x, findLaneTrack as y, base64ToBytes as z };