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

package/dist/index-DRUGsbm2.d.ts

@@ -0,0 +1,1421 @@
+import { E as MoveVideoClipsInput, H as AdjustVideoClipVolumeInput, I as DeleteBgmInput, J as AdjustBgmVolumeInput, K as AdjustSpeechVolumeInput, O as MoveSpeechesInput, P as DeleteSpeechesInput, Q as AddSpeechesInput, R as ChangeSpeechScriptInput, S as SetBgmInput, W as AdjustVideoClipDurationInput, X as AddVideoClipsInput, b as SetCaptionStyleInput, g as SetVideoClipSpeedShiftInput, j as DeleteVideoClipsInput, v as SetCaptionVisibilityInput, w as ReplaceVideoClipContentInput, z as ChangeSpeechVoiceInput } from "./index-6e5cbdM3.js";
+import { InferInputType } from "loro-mirror";
+import { z } from "zod";
+import { LoroDoc, PeerID } from "loro-crdt";
+
+//#region src/document/generated/video-draft-idl.d.ts
+/**
+ * @generated by @mengine/idl-codegen — DO NOT EDIT MANUALLY.
+ *
+ * VideoDraft read-view types extracted from the Smithy IDL
+ * (medeo-v2-design-materials). Re-run `vp run @mengine/idl-codegen#sync`.
+ * Source IDL commit: 902e82e3fec1e94b36e14ef671de91abd210dc86
+ *
+ * WHY EVERY FIELD IS `T | undefined`:
+ * AWS `smithy-typescript-codegen` widens every structure member to
+ * `T | undefined` regardless of the Smithy `@required` trait — it favours
+ * deserialization robustness (a peer may omit a field on the wire) over
+ * encoding requiredness in the static type. So these generated types are NOT
+ * the source of truth for which fields are required: the Smithy `.smithy`
+ * model is. Many fields here (e.g. `VideoClipPart.play_in` / `play_out` /
+ * `volume` / `origin_media_id`) are `@required` in the contract.
+ *
+ * Requiredness is restored at the write-time gate, not here: see the part
+ * schemas in `../zod-schema.ts`, which re-mark the `@required` fields as
+ * mandatory before a VideoDocument is committed to Loro. Do not assume a
+ * field is optional just because its type is `| undefined`.
+ */
+/**
+ * @public
+ * @enum
+ */
+declare const PartKind$1: {
+  readonly BGM: 'bgm';
+  readonly CAPTION: 'caption';
+  readonly SPEECH: 'speech';
+  readonly VIDEO_CLIP: 'video_clip';
+};
+/**
+ * @public
+ */
+type PartKind$1 = (typeof PartKind$1)[keyof typeof PartKind$1];
+/**
+ * @public
+ */
+interface VoiceSummary {
+  name: string | undefined;
+  id: string | undefined;
+}
+/**
+ * @public
+ */
+interface SpeechPart$1 {
+  id: string | undefined;
+  duration_ms: number | undefined;
+  /**
+   * Types of parts that can be contained in tracks
+   * @public
+   */
+  kind: PartKind$1 | undefined;
+  audio_script: string | undefined;
+  volume: number | undefined;
+  audio_storage_key: string | undefined;
+  origin_speech_id: string | undefined;
+  voice: VoiceSummary | undefined;
+  caption_ids: string[] | undefined;
+}
+/**
+ * Caption visual style configuration
+ * @public
+ */
+interface CaptionStyle {
+  /**
+   * Font ID referencing a font from the font library. Defaults to system font if not provided
+   * @public
+   */
+  font_id?: string | undefined;
+  /**
+   * Font size in points
+   * @public
+   */
+  font_size?: number | undefined;
+  /**
+   * Font color as hex string (e.g. "#FFFFFF")
+   * @public
+   */
+  font_color?: string | undefined;
+  /**
+   * Numeric font weight, e.g. 400 for regular or 700 for bold
+   * @public
+   */
+  font_weight?: number | undefined;
+  /**
+   * Caption entrance animation preset ID, e.g. "fade", "slideUp", or "none"
+   * @public
+   */
+  entrance_animation?: string | undefined;
+  /**
+   * Caption entrance animation duration in milliseconds
+   * @public
+   */
+  entrance_animation_duration_ms?: number | undefined;
+  /**
+   * Caption outline/stroke color as hex string (e.g. "#000000")
+   * @public
+   */
+  stroke_color?: string | undefined;
+  /**
+   * Caption outline/stroke width in pixels
+   * @public
+   */
+  stroke_width?: number | undefined;
+  /**
+   * Caption center X position as a percentage (0.0 to 1.0)
+   * @public
+   */
+  position_x?: number | undefined;
+  /**
+   * Caption center Y position as a percentage (0.0 to 1.0)
+   * @public
+   */
+  position_y?: number | undefined;
+}
+/**
+ * @public
+ */
+interface CaptionPart$1 {
+  id: string | undefined;
+  duration_ms: number | undefined;
+  /**
+   * Types of parts that can be contained in tracks
+   * @public
+   */
+  kind: PartKind$1 | undefined;
+  speech_part_id: string | undefined;
+  text: string | undefined;
+  start_ms: number | undefined;
+  /**
+   * Caption visual style (font, size, color, weight, animation, outline). Uses default style if not provided
+   * @public
+   */
+  style?: CaptionStyle | undefined;
+}
+/**
+ * @public
+ * @enum
+ */
+declare const AspectRatio: {
+  readonly RATIO_16_9: '16:9';
+  readonly RATIO_9_16: '9:16';
+};
+/**
+ * @public
+ */
+type AspectRatio = (typeof AspectRatio)[keyof typeof AspectRatio];
+/**
+ * @public
+ * @enum
+ */
+declare const AssetSource: {
+  readonly AI_IMAGES: 'ai_images';
+  readonly AI_VIDEOS: 'ai_videos';
+  readonly MY_UPLOADED_ASSETS: 'my_uploaded_assets';
+  readonly STOCK_VIDEOS: 'stock_videos';
+};
+/**
+ * @public
+ */
+type AssetSource = (typeof AssetSource)[keyof typeof AssetSource];
+/**
+ * An extra aspect ratio variant with independent storage keys for thumbnail,
+ * preview video, and highlight video. Stored inside video_settings JSONB.
+ * @public
+ */
+interface RatioVariant {
+  aspect_ratio: string | undefined;
+  thumb_storage_key: string | undefined;
+  video_storage_key: string | undefined;
+  highlight_video_storage_key?: string | undefined;
+}
+/**
+ * @public
+ */
+interface VideoCreationSettings$1 {
+  voice_id?: string | undefined;
+  duration_ms?: number | undefined;
+  aspect_ratio?: AspectRatio | undefined;
+  video_style_id?: string | undefined;
+  asset_sources?: AssetSource[] | undefined;
+  recipe_id?: string | undefined;
+  enable_high_cost_confirm?: boolean | undefined;
+  user_confirm_cost_threshold?: number | undefined;
+  /**
+   * Extra aspect ratio variants with independent storage keys.
+   * Each variant carries its own thumbnail, preview video, and optional highlight video.
+   * Used when a recipe supports multiple aspect ratios (e.g. both 16:9 and 9:16).
+   * @public
+   */
+  extra_ratios?: RatioVariant[] | undefined;
+}
+/**
+ * @public
+ */
+interface TrackItem$1 {
+  abs_time_position: number | undefined;
+  part_id: string | undefined;
+}
+/**
+ * @public
+ */
+interface Track$1 {
+  id: string | undefined;
+  /**
+   * Types of parts that can be contained in tracks
+   * @public
+   */
+  parts_kind: PartKind$1 | undefined;
+  is_hidden: boolean | undefined;
+  items: TrackItem$1[] | undefined;
+}
+/**
+ * @public
+ */
+interface Attachment {
+  part_id: string | undefined;
+  relative_time_position: number | undefined;
+}
+/**
+ * @public
+ */
+interface PartAggregation {
+  body_part_id: string | undefined;
+  attachments: Attachment[] | undefined;
+}
+/**
+ * @public
+ */
+interface BgmPart$1 {
+  id: string | undefined;
+  duration_ms: number | undefined;
+  /**
+   * Types of parts that can be contained in tracks
+   * @public
+   */
+  kind: PartKind$1 | undefined;
+  audio_storage_key: string | undefined;
+  volume: number | undefined;
+  origin_media_id: string | undefined;
+}
+/**
+ * @public
+ * @enum
+ */
+declare const SpeedShiftCategory: {
+  /**
+   * Variable speed controlled by Bezier keyframes
+   */
+  readonly CURVE: 'curve';
+  /**
+   * Constant speed multiplier across the entire clip
+   */
+  readonly LINEAR: 'linear';
+};
+/**
+ * @public
+ */
+type SpeedShiftCategory = (typeof SpeedShiftCategory)[keyof typeof SpeedShiftCategory];
+/**
+ * @public
+ */
+interface TangentHandle {
+  x: number | undefined;
+  y: number | undefined;
+}
+/**
+ * @public
+ */
+interface SpeedKeyframe {
+  position: number | undefined;
+  rate: number | undefined;
+  in_tangent?: TangentHandle | undefined;
+  out_tangent?: TangentHandle | undefined;
+}
+/**
+ * @public
+ */
+interface CurveConfig {
+  keyframes: SpeedKeyframe[] | undefined;
+}
+/**
+ * @public
+ */
+interface LinearConfig {
+  speed: number | undefined;
+}
+/**
+ * @public
+ */
+type SpeedShiftConfigUnion = SpeedShiftConfigUnion.CurveMember | SpeedShiftConfigUnion.LinearMember | SpeedShiftConfigUnion.$UnknownMember;
+/**
+ * @public
+ */
+declare namespace SpeedShiftConfigUnion {
+  interface LinearMember {
+    linear: LinearConfig;
+    curve?: never;
+    $unknown?: never;
+  }
+  interface CurveMember {
+    linear?: never;
+    curve: CurveConfig;
+    $unknown?: never;
+  }
+  /**
+   * @public
+   */
+  interface $UnknownMember {
+    linear?: never;
+    curve?: never;
+    $unknown: [string, any];
+  }
+  interface Visitor<T> {
+    linear: (value: LinearConfig) => T;
+    curve: (value: CurveConfig) => T;
+    _: (name: string, value: any) => T;
+  }
+  const visit: <T>(value: SpeedShiftConfigUnion, visitor: Visitor<T>) => T;
+}
+/**
+ * @public
+ */
+interface SpeedShift {
+  category: SpeedShiftCategory | undefined;
+  mode: string | undefined;
+  config: SpeedShiftConfigUnion | undefined;
+}
+/**
+ * @public
+ */
+interface VideoClipPart$1 {
+  id: string | undefined;
+  duration_ms: number | undefined;
+  /**
+   * Types of parts that can be contained in tracks
+   * @public
+   */
+  kind: PartKind$1 | undefined;
+  play_in: number | undefined;
+  play_out: number | undefined;
+  volume: number | undefined;
+  origin_media_id: string | undefined;
+  speed_shift?: SpeedShift | undefined;
+}
+/**
+ * @public
+ */
+type PartUnion$1 = PartUnion$1.BgmMember | PartUnion$1.CaptionMember | PartUnion$1.SpeechMember | PartUnion$1.Video_clipMember | PartUnion$1.$UnknownMember;
+/**
+ * @public
+ */
+declare namespace PartUnion$1 {
+  interface Video_clipMember {
+    video_clip: VideoClipPart$1;
+    bgm?: never;
+    speech?: never;
+    caption?: never;
+    $unknown?: never;
+  }
+  interface BgmMember {
+    video_clip?: never;
+    bgm: BgmPart$1;
+    speech?: never;
+    caption?: never;
+    $unknown?: never;
+  }
+  interface SpeechMember {
+    video_clip?: never;
+    bgm?: never;
+    speech: SpeechPart$1;
+    caption?: never;
+    $unknown?: never;
+  }
+  interface CaptionMember {
+    video_clip?: never;
+    bgm?: never;
+    speech?: never;
+    caption: CaptionPart$1;
+    $unknown?: never;
+  }
+  /**
+   * @public
+   */
+  interface $UnknownMember {
+    video_clip?: never;
+    bgm?: never;
+    speech?: never;
+    caption?: never;
+    $unknown: [string, any];
+  }
+  interface Visitor<T> {
+    video_clip: (value: VideoClipPart$1) => T;
+    bgm: (value: BgmPart$1) => T;
+    speech: (value: SpeechPart$1) => T;
+    caption: (value: CaptionPart$1) => T;
+    _: (name: string, value: any) => T;
+  }
+  const visit: <T>(value: PartUnion$1, visitor: Visitor<T>) => T;
+}
+/**
+ * Timeline configuration for video editing
+ * @public
+ */
+interface Timeline$1 {
+  duration_ms: number | undefined;
+  unit_time_ms: number | undefined;
+}
+/**
+ * Complete video draft information with timeline and tracks
+ * @public
+ */
+interface VideoDraft$1 {
+  id?: string | undefined;
+  project_id: string | undefined;
+  owner_id: string | undefined;
+  /**
+   * for-code-gen: property value may be empty string ("")
+   * @public
+   */
+  thumbnail_storage_key: string | undefined;
+  /**
+   * Timeline configuration for video editing
+   * @public
+   */
+  timeline?: Timeline$1 | undefined;
+  video_creation_settings?: VideoCreationSettings$1 | undefined;
+  chat_session_id: string | undefined;
+  main_track?: Track$1 | undefined;
+  above_main_tracks: Track$1[] | undefined;
+  below_main_tracks: Track$1[] | undefined;
+  part_aggregations: PartAggregation[] | undefined;
+  part_library: Record<string, PartUnion$1> | undefined;
+  version: number | undefined;
+}
+//#endregion
+//#region src/document/types.d.ts
+declare const VIDEO_DOCUMENT_SCHEMA_VERSION: 'video-document/v0';
+type VideoDocumentSchemaVersion = typeof VIDEO_DOCUMENT_SCHEMA_VERSION;
+type PartKind = 'video_clip' | 'speech' | 'caption' | 'bgm';
+/**
+ * Project-level creation settings. Mirrors the IDL, but keeps the two fields the
+ * upstream (Director / FE) sends as an explicit `null` nullable — the IDL models
+ * "absent" only as `undefined`, whereas these arrive as `null` to mean
+ * "explicitly cleared". Relaxing the type here avoids forcing every caller to
+ * map `null` → `undefined`.
+ */
+type VideoCreationSettings = Omit<VideoCreationSettings$1, 'video_style_id' | 'duration_ms'> & {
+  video_style_id?: string | null | undefined;
+  duration_ms?: number | null | undefined;
+};
+/**
+ * Video clip part. `duration_ms` is dropped from the authoritative type
+ * (reference/17 §5): it is the derived effective length and is re-derived into
+ * the read-view by the projection. `play_in` / `play_out` are required (smithy
+ * `@required`), so the timeline length is always the trim window over the speed
+ * multiplier — no need to store the media's intrinsic length either. `speed_shift`
+ * is the IDL type. See `effectiveVideoClipDurationMs`.
+ */
+type VideoClipPart = Omit<VideoClipPart$1, 'duration_ms'>;
+/**
+ * Speech part. `duration_ms` is dropped from the authoritative type
+ * (reference/17 §5) in favour of the engine-only `media_duration_ms`: a speech
+ * cannot be trimmed or speed-shifted, so its effective timeline duration equals
+ * the TTS audio's intrinsic length. The read-view `duration_ms` is re-derived
+ * from it by the projection.
+ */
+type SpeechPart = Omit<SpeechPart$1, 'duration_ms'> & {
+  media_duration_ms?: number | undefined;
+};
+/**
+ * Authoritative caption part. The IDL `CaptionPart` carries `duration_ms` (the
+ * effective display length, a derived read-view value); the authoritative store
+ * instead keeps `initial_duration_ms` — the caption's length at generation time,
+ * parsed from the voiceover, a resource-intrinsic fact that does not change
+ * (reference/17 §5; onscreen-caption plan). The effective `duration_ms` is
+ * re-derived into the `VideoDraft` read-view by the projection.
+ *
+ * `speech_part_id` / `start_ms` are kept as resource-intrinsic facts (which
+ * speech it was split from, and its offset in that source) — reference/17
+ * principle 4.
+ */
+type CaptionPart = Omit<CaptionPart$1, 'duration_ms'> & {
+  initial_duration_ms?: number | undefined;
+};
+/**
+ * Background music. The IDL marks `duration_ms` required (via its part mixin),
+ * but a bgm has no authoritative duration — its effective length is always the
+ * whole timeline, derived on read (RFC 02 §0b). The engine therefore keeps it
+ * optional rather than carrying the IDL's required field into storage.
+ */
+type BgmPart = Omit<BgmPart$1, 'duration_ms'> & {
+  duration_ms?: number | undefined;
+};
+/**
+ * How a `TrackItem`'s start is determined — the authoritative positioning fact
+ * (RFC 02 §4, reference/17 §3). The absolute time is never stored; it is solved
+ * by the cascade at projection time. The three modes express "where the start
+ * comes from": `sequential` follows the track's flow order, `anchored` hangs off
+ * another part plus an offset, `absolute` pins to the timeline origin.
+ * `anchorPartId` points at another item's `part_id` (a part is placed at most
+ * once per lane, so `part_id` is the placement identity).
+ *
+ * `time_position` carries only the real editing intent (mode + anchor + offset),
+ * so it is a single last-writer-wins unit safe to overwrite wholesale. The
+ * derived fallback snapshot lives outside it on `TrackItem.fallback_abs_ms`.
+ */
+type TrackItemTimePosition = {
+  mode: 'sequential';
+} | {
+  mode: 'anchored';
+  anchorPartId: string;
+  offsetMs: number;
+} | {
+  mode: 'absolute';
+  offsetMs: number;
+};
+/**
+ * Authoritative track item: only facts. Absolute time is derived, not stored.
+ *
+ * `fallback_abs_ms` is the one deliberately-retained derived snapshot in
+ * authoritative state: the `relative` item's absolute landing, so that when its
+ * anchor is concurrently deleted (orphan, RFC 02 §11.1), the item can be put
+ * back on the timeline and re-parented to the nearest video — orphan handling
+ * needs an absolute anchor and cannot guess one.
+ *
+ * It is written by the write-side ops that create or move a `relative` item:
+ * each resolves the item's absolute landing from its anchor once (add/change
+ * speech from the host clip's start + offset; `moveSpeeches` from the requested
+ * start; §9.1 reparent from the preserved abs) and stamps it here. The read-side
+ * projection never writes it back — the authoritative model stays write-derived,
+ * not read-derived. It is a field of its own (not inside `time_position`) so the
+ * two are separate LWW units: a fallback refresh can never clobber a concurrent
+ * `offsetMs` edit, since they carry unequal business value. When the anchor's
+ * absolute position cannot be resolved at write time it is left undefined. Only
+ * meaningful for `anchored` items.
+ */
+interface TrackItem {
+  part_id: string;
+  time_position: TrackItemTimePosition;
+  fallback_abs_ms?: number | undefined;
+}
+interface Track {
+  id: string | undefined;
+  parts_kind: PartKind | undefined;
+  is_hidden: boolean | undefined;
+  items: TrackItem[] | undefined;
+}
+/** The linear speed multiplier of a `speed_shift`, defaulting to 1 (original). */
+declare function speedOf(speedShift: SpeedShift | undefined): number;
+/**
+ * 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×).
+ */
+declare function effectiveVideoClipDurationMs(clip: VideoClipPart): number;
+/**
+ * Authoritative part union: a flat discriminated union over the four part kinds.
+ * Deliberately *not* the IDL's namespace union (no `$unknown` / `visit`): engine
+ * storage rejects unknown kinds, and projection / validation read parts by plain
+ * `part.video_clip` / `part.speech` property access, which this shape supports.
+ */
+type PartUnion = {
+  video_clip: VideoClipPart;
+  speech?: never;
+  caption?: never;
+  bgm?: never;
+} | {
+  video_clip?: never;
+  speech: SpeechPart;
+  caption?: never;
+  bgm?: never;
+} | {
+  video_clip?: never;
+  speech?: never;
+  caption: CaptionPart;
+  bgm?: never;
+} | {
+  video_clip?: never;
+  speech?: never;
+  caption?: never;
+  bgm: BgmPart;
+};
+/**
+ * Read-view part union for the derived `VideoDraft` (reference/17 §5/§7). The
+ * authoritative parts drop their derived durations; the projection re-injects an
+ * effective `duration_ms` for downstream compatibility — for a video clip it is
+ * `(play_out - play_in) / speed`, for a speech it is `media_duration_ms`, for a
+ * caption it is `initial_duration_ms`, for a bgm it is the timeline total. Each
+ * read-view part is therefore the authoritative part plus a derived `duration_ms`.
+ */
+type VideoDraftPartUnion = {
+  video_clip: VideoClipPart & {
+    duration_ms?: number;
+  };
+  speech?: never;
+  caption?: never;
+  bgm?: never;
+} | {
+  video_clip?: never;
+  speech: SpeechPart & {
+    duration_ms?: number;
+  };
+  caption?: never;
+  bgm?: never;
+} | {
+  video_clip?: never;
+  speech?: never;
+  caption: CaptionPart & {
+    duration_ms?: number;
+  };
+  bgm?: never;
+} | {
+  video_clip?: never;
+  speech?: never;
+  caption?: never;
+  bgm: BgmPart & {
+    duration_ms?: number;
+  };
+};
+/**
+ * Derived `VideoDraft` read-view. The shape follows the IDL verbatim except for
+ * `part_library`: the IDL types its parts with the generated namespace
+ * `PartUnion`, but the engine's projection emits `VideoDraftPartUnion` — the
+ * authoritative parts with the derived `duration_ms` re-injected (reference/17 §7)
+ * plus the engine extensions (`media_duration_ms`, the looser `SpeedShift`). This
+ * is the intentional superset over the IDL `VideoDraft` (see the extensions note).
+ */
+type VideoDraft = Omit<VideoDraft$1, 'part_library' | 'video_creation_settings'> & {
+  part_library: Record<string, VideoDraftPartUnion> | undefined;
+  video_creation_settings?: VideoCreationSettings | undefined;
+};
+/** Authoritative timeline: `duration_ms` is derived (= longest track), not stored. */
+interface Timeline {
+  unit_time_ms: number | undefined;
+}
+/**
+ * Project-level scalars that do not participate in track ordering. Grouped under
+ * `meta` because the loro-mirror `schema()` root only accepts container schemas,
+ * not bare scalars — so these must live inside a map container in storage. The
+ * domain type mirrors that storage shape 1:1 (RFC 03 §4) rather than flattening,
+ * keeping `VideoDocument` and the loro draft isomorphic and the mapping layer a
+ * near-identity. `schema_version` lives here too (it is a scalar fact).
+ */
+interface VideoDocumentMeta {
+  schema_version: VideoDocumentSchemaVersion;
+  draft_id?: string | undefined;
+  project_id: VideoDraft['project_id'];
+  owner_id: VideoDraft['owner_id'];
+  thumbnail_storage_key: VideoDraft['thumbnail_storage_key'];
+  chat_session_id: VideoDraft['chat_session_id'];
+  video_creation_settings: VideoDraft['video_creation_settings'];
+  version: VideoDraft['version'];
+}
+/**
+ * Authoritative collaborative document: only facts. Positioning lives on each
+ * `TrackItem.time_position`; absolute time, `part_aggregations`, and total
+ * duration are derived in the `VideoDraft` projection, not stored here (RFC 02 §6).
+ *
+ * The shape mirrors the loro storage structure 1:1 (RFC 03 §4): a `meta` map of
+ * project scalars, plus a single ordered `tracks` list (reference/17 §4). A
+ * track's lane is expressed by its `parts_kind`, not by which container it lives
+ * in — the `main` / `above` / `below` three-pane view is reconstructed at
+ * projection time. Order is the list order itself, so there is no `lane` /
+ * `lane_order` field to diverge under concurrent edits.
+ */
+interface VideoDocument {
+  meta: VideoDocumentMeta;
+  timeline: Timeline | undefined;
+  tracks: Track[] | undefined;
+  part_library: Record<string, PartUnion> | undefined;
+}
+type VideoDocumentValidationIssueCode = 'invalid_schema' | 'duplicate_track_item_identity' | 'unknown_part_kind' | 'part_kind_mismatch' | 'missing_part_reference' | 'track_kind_mismatch' | 'main_track_non_video_clip' | 'invalid_part_value' | 'invalid_speech_caption_reference' | 'invalid_position_anchor';
+/**
+ * Issue severity (RFC 02 §11.1). `error` is a hard reject — the document is not
+ * a legal `VideoDocument` and must not be projected. `recoverable` marks a
+ * business inconsistency the projection is designed to heal on read (currently
+ * only a dangling `anchorPartId`: the orphan condition, recovered via the item's
+ * `fallback_abs_ms` snapshot + cascade reassign), so it is surfaced for
+ * observability but does NOT block projection. Absent `severity` means `error`.
+ */
+type VideoDocumentValidationIssueSeverity = 'error' | 'recoverable';
+interface VideoDocumentValidationIssue {
+  code: VideoDocumentValidationIssueCode;
+  path: string;
+  message: string;
+  severity?: VideoDocumentValidationIssueSeverity;
+}
+//#endregion
+//#region src/document/projection.d.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.
+ */
+declare function toVideoDocument(draft: VideoDraft): VideoDocument;
+/** speech/attachment part_id → its host video part_id + relative offset. */
+type SpeechHostMap = Map<string, {
+  hostPartId: string;
+  offsetMs: number;
+}>;
+/**
+ * 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).
+ */
+declare function buildSpeechHostMap(aggregations: Array<{
+  body_part_id?: string | null;
+  attachments?: Array<{
+    part_id?: string | null;
+    relative_time_position?: number | null;
+  }> | null;
+}> | null | undefined): SpeechHostMap;
+/** The derived time position + orphan-recovery snapshot for one item. */
+interface DerivedItemPosition {
+  timePosition: TrackItemTimePosition;
+  /** Present only for `anchored` items (RFC 02 §11.1). */
+  fallbackAbsMs?: number;
+}
+/**
+ * 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`.
+ */
+declare function derivePositionFromAbs(partId: string, abs: number, isMain: boolean, speechHost: SpeechHostMap, partLibrary: Record<string, PartUnion | string | undefined>): DerivedItemPosition;
+/**
+ * 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.
+ */
+declare function fromVideoDocument(document: VideoDocument): VideoDraft;
+//#endregion
+//#region src/document/validation.d.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`.
+ */
+declare class VideoDocumentValidationError extends Error {
+  readonly issues: VideoDocumentValidationIssue[];
+  constructor(issues: VideoDocumentValidationIssue[]);
+}
+/**
+ * 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.
+ */
+declare function assertValidVideoDocument(document: unknown): asserts document is VideoDocument;
+declare function validateVideoDocument(document: unknown): VideoDocumentValidationIssue[];
+//#endregion
+//#region src/document/mirror-schema.d.ts
+declare const videoDocumentMirrorSchema: import("loro-mirror").RootSchemaType<{
+  meta: import("loro-mirror").LoroMapSchema<{
+    schema_version: /*elided*/any;
+    draft_id: /*elided*/any;
+    project_id: /*elided*/any;
+    owner_id: /*elided*/any;
+    thumbnail_storage_key: /*elided*/any;
+    chat_session_id: /*elided*/any;
+    video_creation_settings: /*elided*/any;
+    version: /*elided*/any;
+  }> & {
+    options: {};
+  } & {
+    catchall: <C extends import("loro-mirror").SchemaType>(catchallSchema: C) => import("loro-mirror").LoroMapSchemaWithCatchall<{
+      schema_version: /*elided*/any;
+      draft_id: /*elided*/any;
+      project_id: /*elided*/any;
+      owner_id: /*elided*/any;
+      thumbnail_storage_key: /*elided*/any;
+      chat_session_id: /*elided*/any;
+      video_creation_settings: /*elided*/any;
+      version: /*elided*/any;
+    }, C>;
+  };
+  timeline: import("loro-mirror").LoroMapSchema<{
+    unit_time_ms: /*elided*/any;
+  }> & {
+    options: {};
+  } & {
+    catchall: <C extends import("loro-mirror").SchemaType>(catchallSchema: C) => import("loro-mirror").LoroMapSchemaWithCatchall<{
+      unit_time_ms: /*elided*/any;
+    }, C>;
+  };
+  tracks: import("loro-mirror").LoroMovableListSchema<import("loro-mirror").LoroMapSchema<{
+    id: /*elided*/any;
+    parts_kind: /*elided*/any;
+    is_hidden: /*elided*/any;
+    items: /*elided*/any;
+  }> & {
+    options: {};
+  } & {
+    catchall: <C extends import("loro-mirror").SchemaType>(catchallSchema: C) => import("loro-mirror").LoroMapSchemaWithCatchall<{
+      id: /*elided*/any;
+      parts_kind: /*elided*/any;
+      is_hidden: /*elided*/any;
+      items: /*elided*/any;
+    }, C>;
+  }> & {
+    options: {};
+  };
+  part_library: import("loro-mirror").LoroMapSchemaWithCatchall<{}, import("loro-mirror").LoroMapSchema<{
+    video_clip: /*elided*/any;
+    speech: /*elided*/any;
+    caption: /*elided*/any;
+    bgm: /*elided*/any;
+  }> & {
+    options: {};
+  } & {
+    catchall: <C extends import("loro-mirror").SchemaType>(catchallSchema: C) => import("loro-mirror").LoroMapSchemaWithCatchall<{
+      video_clip: /*elided*/any;
+      speech: /*elided*/any;
+      caption: /*elided*/any;
+      bgm: /*elided*/any;
+    }, C>;
+  }> & {
+    options: {};
+  };
+}> & {
+  options: {};
+};
+type VideoDocumentMirrorSchema = typeof videoDocumentMirrorSchema;
+/**
+ * The mutable draft an op's `transact` callback edits, inferred from the schema.
+ *
+ * `InferInputType` is the schema's *input* shape: the declared business fields
+ * with the `$cid` container ids (which mirror injects into its output
+ * `InferType`) made optional, so ops assign plain objects without supplying
+ * `$cid`. Deriving it from the schema keeps draft and storage in lockstep — a
+ * schema change is a compile error at every edit site, not a silent drift.
+ * Reorders within `items` still diff to real Loro `move` ops because the schema
+ * keys items by `part_id`.
+ */
+type VideoDocumentDraft = InferInputType<VideoDocumentMirrorSchema>;
+/** Track value as it appears in a draft. Derived from the single `tracks` movable list. */
+type TrackDraft = NonNullable<NonNullable<VideoDocumentDraft['tracks']>[number]>;
+/** A single track item in a draft. */
+type TrackItemDraft = NonNullable<NonNullable<TrackDraft['items']>[number]>;
+//#endregion
+//#region src/editor/id-gen.d.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.
+ */
+/**
+ * Online part-id semantic prefixes. `clip` (video clip) is the only value the
+ * engine currently mints (see `addVideoClips`); the rest are declared so the
+ * type documents the shared vocabulary and guards against reintroducing the old
+ * `vc`/`sp`/`cp`/`bg` names. Speech/caption/bgm ids arrive pre-minted in op
+ * payloads, so the engine never generates them itself.
+ */
+type PartIdPrefix = 'clip' | 'spe' | 'cap' | 'bgm' | 'ti';
+declare function generatePartId(prefix: PartIdPrefix): string;
+/** Injectable part-id mint; defaults to `generatePartId` on `SemanticEditor`. */
+type PartIdFactory = (prefix: PartIdPrefix) => string;
+//#endregion
+//#region src/editor/schema-validator.d.ts
+interface SnapshotReadable {
+  snapshot(): VideoDocument;
+}
+declare class ValidationError extends Error {
+  readonly code: string;
+  readonly context?: Record<string, unknown>;
+  constructor(code: string, message: string, context?: Record<string, unknown>);
+}
+declare class SchemaValidator {
+  validateMoveVideoClips(input: MoveVideoClipsInput, doc: SnapshotReadable): void;
+  validateDeleteVideoClips(input: DeleteVideoClipsInput, doc: SnapshotReadable): void;
+  validateAddVideoClips(input: AddVideoClipsInput, doc: SnapshotReadable): void;
+  validateAdjustVideoClipVolume(input: AdjustVideoClipVolumeInput, doc: SnapshotReadable): void;
+  validateSetVideoClipSpeedShift(input: SetVideoClipSpeedShiftInput, doc: SnapshotReadable): void;
+  validateReplaceVideoClipContent(input: ReplaceVideoClipContentInput, doc: SnapshotReadable): void;
+  validateAdjustVideoClipDuration(input: AdjustVideoClipDurationInput, doc: SnapshotReadable): void;
+  validateAdjustSpeechVolume(input: AdjustSpeechVolumeInput, doc: SnapshotReadable): void;
+  validateAdjustBgmVolume(input: AdjustBgmVolumeInput, doc: SnapshotReadable): void;
+  validateAddSpeeches(input: AddSpeechesInput, doc: SnapshotReadable): void;
+  validateChangeSpeechScript(input: ChangeSpeechScriptInput, doc: SnapshotReadable): void;
+  validateChangeSpeechVoice(input: ChangeSpeechVoiceInput, doc: SnapshotReadable): void;
+  validateDeleteSpeeches(input: DeleteSpeechesInput, doc: SnapshotReadable): void;
+  validateMoveSpeeches(input: MoveSpeechesInput, doc: SnapshotReadable): void;
+  validateSetBgm(input: SetBgmInput, _doc: SnapshotReadable): void;
+  validateDeleteBgm(input: DeleteBgmInput, _doc: SnapshotReadable): void;
+  validateSetCaptionVisibility(input: SetCaptionVisibilityInput, _doc: SnapshotReadable): void;
+  validateSetCaptionStyle(input: SetCaptionStyleInput, _doc: SnapshotReadable): void;
+  private parse;
+  private mainTrackIds;
+  /** Every caption a speech declares in `caption_ids` must be supplied in `captions`. */
+  private assertCaptionsOwned;
+  /** Each regenerated speech (re-TTS) must already exist in the document. */
+  private assertSpeechesExist;
+  /**
+   * Each speech's `anchor_part_id` must point at a video clip that already
+   * exists. A relative speech anchored to a missing clip cannot be positioned
+   * by the projection and has no host to recover to (RFC 02 §4/§11.1), so the
+   * write must be rejected rather than landing a dangling reference. (Restores
+   * the dangling-reference guard the old `validateMaterializedPatch` carried;
+   * ADR 0009.)
+   */
+  private assertAnchorsExist;
+  private assertPartKind;
+}
+//#endregion
+//#region src/editor/types.d.ts
+/**
+ * `SemanticOp` contract surface — the frozen catalogue of business write
+ * operations the collaborative editor recognises.
+ *
+ * This is the single source of truth; `SemanticEditor` derives its method set
+ * (`SemanticOpName`) from `ImplementedSemanticOpKind`, so adding a method
+ * without listing it here (or vice versa) is a type error.
+ *
+ * Mapping of each kind to UI Operation / agent tool / side-effect routing is
+ * maintained in
+ * `docs/projects/medeo-integration/reference/operation-semantic-matrix.md`; the
+ * frozen contract narrative lives in
+ * `docs/projects/medeo-integration/results/phase-4-semantic-op-contract.md`.
+ */
+/**
+ * Operations implemented by `SemanticEditor`. FROZEN: each entry has a
+ * `SemanticEditor` method, a narrow zod input schema (business intent +
+ * materialized side-effect assets, never a document slice), and validation. The
+ * editor runs the timeline-core cascade in-transaction to derive every position
+ * (ADR 0009 — no caller-materialized layout).
+ *
+ * Effectful ops (TTS for `AddSpeeches` / `ChangeSpeechScript` /
+ * `ChangeSpeechVoice`, media import for `ReplaceVideoClipContent`, BGM for
+ * `SetBgm`) receive their stable side-effect result already materialized — the
+ * editor only writes the document; it never performs the side effect. See the
+ * side-effect payload contract in
+ * `docs/projects/medeo-integration/results/phase-4-side-effect-payload-contract.md`.
+ */
+type ImplementedSemanticOpKind = 'MoveVideoClips' | 'DeleteVideoClips' | 'AddVideoClips' | 'AdjustVideoClipVolume' | 'SetVideoClipSpeedShift' | 'ReplaceVideoClipContent' | 'AdjustVideoClipDuration' | 'AddSpeeches' | 'DeleteSpeeches' | 'MoveSpeeches' | 'ChangeSpeechScript' | 'ChangeSpeechVoice' | 'AdjustSpeechVolume' | 'SetCaptionVisibility' | 'SetCaptionStyle' | 'SetBgm' | 'DeleteBgm' | 'AdjustBgmVolume';
+/**
+ * Operations on the roadmap but NOT yet implemented by `SemanticEditor`. Empty:
+ * Phase 4 covers every op with a real entry point. Kept as a named type so the
+ * contract surface stays explicit and re-expanding the roadmap is a typed edit.
+ * To re-add planned kinds, list them here and add them back to the
+ * `SemanticOpKind` union below.
+ */
+type PlannedSemanticOpKind = never;
+/**
+ * Every SemanticOp kind. Currently equals `ImplementedSemanticOpKind` because
+ * `PlannedSemanticOpKind` is empty; re-add `| PlannedSemanticOpKind` when the
+ * roadmap is re-expanded.
+ */
+type SemanticOpKind = ImplementedSemanticOpKind;
+/** Runtime list of the frozen, implemented kinds (for guards / introspection). */
+declare const IMPLEMENTED_SEMANTIC_OP_KINDS: readonly ImplementedSemanticOpKind[];
+declare function isImplementedSemanticOpKind(kind: string): kind is ImplementedSemanticOpKind;
+//#endregion
+//#region src/editor/semantic-editor.d.ts
+interface CommitOptions {
+  /**
+   * Caller-supplied intent attached to the op's audit message.
+   *
+   * Typed as `unknown` to match `TransactAudit.intent`. The wire (real
+   * mengine-server and the in-memory test double) only surfaces **string**
+   * intents onto the audit log — non-string values stay in the Loro commit
+   * message but parse to `null`. Agent callers should pass a string.
+   */
+  intent?: unknown;
+}
+type SemanticOpInput = MoveVideoClipsInput | DeleteVideoClipsInput | AddVideoClipsInput | AdjustVideoClipVolumeInput | AdjustSpeechVolumeInput | AdjustBgmVolumeInput | SetVideoClipSpeedShiftInput | ReplaceVideoClipContentInput | AdjustVideoClipDurationInput | AddSpeechesInput | DeleteSpeechesInput | MoveSpeechesInput | SetCaptionVisibilityInput | SetCaptionStyleInput | SetBgmInput | DeleteBgmInput;
+type SemanticOpName = ImplementedSemanticOpKind;
+/** Audit metadata committed alongside an op's writes. */
+interface TransactAudit {
+  kind: SemanticOpName;
+  payload: unknown;
+  intent?: unknown;
+}
+/**
+ * Narrow write surface the `SemanticEditor` drives (ADR 0008 / 0009). It stays
+ * off raw Loro: every op runs its document mutations inside a single `transact`
+ * callback, which the storage adapter applies as one CRDT transaction + commit
+ * carrying the audit message.
+ *
+ * The callback edits a `VideoDocumentDraft` — an immer draft of the whole
+ * document state. A throw inside it discards the draft and never touches Loro,
+ * so partial writes roll back naturally (no `commit`/`rollback` machinery). The
+ * adapter's declarative diff turns the edited draft into minimal CRDT ops,
+ * including real `move`s for reordered track items (keyed by `part_id`), so
+ * per-item identity survives on every lane.
+ *
+ * Each op takes a narrow business input (intent + materialized side-effect
+ * assets, never a document slice); the editor applies the authoritative facts
+ * and runs the timeline-core cascade inside the callback to derive every
+ * position. The caller never materializes a layout (ADR 0009).
+ */
+interface SemanticDocumentAdapter extends SnapshotReadable {
+  /** True once the document holds real content (a bootstrapped/synced snapshot). */
+  hasContent(): boolean;
+  /**
+   * Apply one op's whole mutation in a single transaction. `edit` mutates the
+   * document draft; the adapter diffs the result and commits once with `audit`.
+   * A throw in `edit` rolls back (the draft is discarded, Loro untouched). An
+   * edit that changes nothing produces no commit (no phantom audit entry).
+   */
+  transact(edit: (draft: VideoDocumentDraft) => void, audit: TransactAudit): void;
+}
+declare class SemanticEditor {
+  private readonly doc;
+  private readonly validator;
+  private readonly idFactory;
+  constructor(doc: SemanticDocumentAdapter, validator?: SchemaValidator, idFactory?: PartIdFactory);
+  moveVideoClips(input: MoveVideoClipsInput, options?: CommitOptions): Promise<void>;
+  deleteVideoClips(input: DeleteVideoClipsInput, options?: CommitOptions): Promise<void>;
+  addVideoClips(input: AddVideoClipsInput, options?: CommitOptions): Promise<void>;
+  adjustVideoClipVolume(input: AdjustVideoClipVolumeInput, options?: CommitOptions): Promise<void>;
+  setVideoClipSpeedShift(input: SetVideoClipSpeedShiftInput, options?: CommitOptions): Promise<void>;
+  adjustSpeechVolume(input: AdjustSpeechVolumeInput, options?: CommitOptions): Promise<void>;
+  adjustBgmVolume(input: AdjustBgmVolumeInput, options?: CommitOptions): Promise<void>;
+  /**
+   * Replace the media backing existing video clips. The new media's stable
+   * result (new media id, intrinsic length, reset trim window) is materialized
+   * upstream; the clip ids and their track items are unchanged. Only the part
+   * facts change — effective duration and downstream positions are derived by
+   * the projection on read.
+   */
+  replaceVideoClipContent(input: ReplaceVideoClipContentInput, options?: CommitOptions): Promise<void>;
+  /**
+   * Re-trim clips. Only the `play_in` / `play_out` facts change; the new
+   * effective duration and the resulting downstream reflow are derived by the
+   * projection on read (anchored speeches follow their host clip automatically).
+   */
+  adjustVideoClipDuration(input: AdjustVideoClipDurationInput, options?: CommitOptions): Promise<void>;
+  /**
+   * Add speeches (and their captions). TTS runs upstream; the materialized
+   * speech / caption parts arrive in `input`, each carrying its host clip
+   * `anchor_part_id` + `offset_ms`. The editor writes the parts and their
+   * `anchored` `time_position` facts verbatim — no write-time host-picking, no
+   * cascade. The projection derives absolute positions on read.
+   */
+  addSpeeches(input: AddSpeechesInput, options?: CommitOptions): Promise<void>;
+  /** Delete speeches with their captions; the subtree is removed (§9.2). Surviving lanes keep their facts. */
+  deleteSpeeches(input: DeleteSpeechesInput, options?: CommitOptions): Promise<void>;
+  /**
+   * Move speeches in time (§9.1). One forward positioning pass: anchor each
+   * speech to the main-track clip its new absolute start lands in and write the
+   * resulting `anchored` `time_position` fact. No cascade — the projection
+   * derives absolute positions on read.
+   */
+  moveSpeeches(input: MoveSpeechesInput, options?: CommitOptions): Promise<void>;
+  /** Change a speech's script. Re-TTS runs upstream; the regenerated parts arrive materialized (no cascade). */
+  changeSpeechScript(input: ChangeSpeechScriptInput, options?: CommitOptions): Promise<void>;
+  /** Change a speech's voice. Re-TTS runs upstream; the regenerated parts arrive materialized (no cascade). */
+  changeSpeechVoice(input: ChangeSpeechVoiceInput, options?: CommitOptions): Promise<void>;
+  /**
+   * Set the document BGM. The media's stable result arrives materialized.
+   *
+   * KNOWN GAP (non-blocking): when the BGM comes from the public library, the
+   * Director must also register project-level stock media ownership. That is a
+   * separate "register-only, no draft write" side effect Director does not yet
+   * expose; until it does, a public-library BGM set here will not auto-appear in
+   * the project media library. The document edit itself is complete and correct.
+   * See `docs/projects/medeo-integration/results/phase-4-op-side-effect-classification.md`.
+   */
+  setBgm(input: SetBgmInput, options?: CommitOptions): Promise<void>;
+  /** Remove the document BGM; clears the bgm lane and removes the part. */
+  deleteBgm(input: DeleteBgmInput, options?: CommitOptions): Promise<void>;
+  /** Toggle caption visibility (caption track `is_hidden`). */
+  setCaptionVisibility(input: SetCaptionVisibilityInput, options?: CommitOptions): Promise<void>;
+  /**
+   * Set the document-wide caption style. GLOBAL (no `caption_id`): the patch is
+   * merged onto EVERY caption part's `style`, mirroring the FE, which applies a
+   * single style to all captions (`caption-style.ts:persistCaptionStylePatch`).
+   *
+   * Merge, not replace: only the fields present in the input overwrite the
+   * caption's existing style; absent fields are carried forward. So a partial
+   * patch ("recolor only") keeps the caption's font size. Pure document edit, no
+   * cascade — positions are untouched.
+   */
+  setCaptionStyle(input: SetCaptionStyleInput, options?: CommitOptions): Promise<void>;
+  /**
+   * Resolve the main-track sequential layout from `source`. Callers inside a
+   * `transact` MUST pass the live `draft` so item order reflects in-progress
+   * mutations; the default `this.doc.snapshot()` is only committed state and is
+   * correct for read-only callers outside a transaction. `readMainTrackItems` /
+   * `readPartDurationMs` accept both an immer draft and a raw snapshot.
+   */
+  private computeMainTrackLayout;
+  private indexForStartMs;
+  private computeAddInsertIndex;
+}
+//#endregion
+//#region src/document/mirror-adapter.d.ts
+interface MirrorVideoDocumentOptions {
+  peerId?: PeerID;
+  origin?: string;
+}
+/**
+ * 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.
+ */
+declare class MirrorVideoDocumentAdapter implements SemanticDocumentAdapter {
+  readonly doc: LoroDoc;
+  private readonly mirror;
+  constructor(doc: LoroDoc);
+  snapshot(): VideoDocument;
+  /**
+   * 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(): boolean;
+  /**
+   * 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: (draft: VideoDocumentDraft) => void, audit: TransactAudit): void;
+}
+/** Build a fresh Loro doc seeded with `document` through the mirror. */
+declare function createMirrorVideoDocument(document: VideoDocument, options?: MirrorVideoDocumentOptions): LoroDoc;
+/** Build a `MirrorVideoDocumentAdapter` over a fresh doc seeded with `document`. */
+declare function createMirrorVideoDocumentAdapter(document: VideoDocument, options?: MirrorVideoDocumentOptions): MirrorVideoDocumentAdapter;
+/** Write a whole `VideoDocument` into a draft (seed a fresh doc / plain-memory state). */
+declare function writeVideoDocumentToDraft(draft: VideoDocumentDraft, document: VideoDocument): void;
+//#endregion
+//#region src/document/plain-memory-adapter.d.ts
+/**
+ * A `TransactAudit` widened with the ordered ids minted during that transact.
+ * `generated_ids` is empty when the op never called the id factory.
+ */
+interface JournalEntry extends TransactAudit {
+  /** Ids produced by the adapter's id factory during this transact, in mint order. */
+  generated_ids: string[];
+}
+interface PlainMemoryAdapterOptions {
+  /** Underlying id mint; wrapped so each call inside a transact is journaled. */
+  idFactory?: PartIdFactory;
+}
+/**
+ * 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.
+ */
+declare class PlainMemoryAdapter implements SemanticDocumentAdapter {
+  private state;
+  private readonly _journal;
+  private readonly baseIdFactory;
+  /** Non-null only while a `transact` edit callback is running. */
+  private pendingIds;
+  /**
+   * Recording wrapper around the underlying factory. Callers (sandbox editor)
+   * use this so every minted id is appended to the current transact's list.
+   */
+  readonly idFactory: PartIdFactory;
+  constructor(document: VideoDocument, options?: PlainMemoryAdapterOptions);
+  get journal(): readonly JournalEntry[];
+  hasContent(): boolean;
+  snapshot(): VideoDocument;
+  /**
+   * 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: (draft: VideoDocumentDraft) => void, audit: TransactAudit): void;
+}
+/** Build a `PlainMemoryAdapter` seeded with `document`. */
+declare function createPlainMemoryAdapter(document: VideoDocument, options?: PlainMemoryAdapterOptions): PlainMemoryAdapter;
+//#endregion
+//#region src/document/mirror-read.d.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()`.
+ */
+declare function readVideoDocumentFromDraft(draft: VideoDocumentDraft): VideoDocument;
+//#endregion
+//#region src/document/zod-schema.d.ts
+declare const partUnionSchema: z.ZodUnion<readonly [z.ZodObject<{
+  video_clip: z.ZodObject<{
+    id: z.ZodOptional<z.ZodString>;
+    kind: z.ZodLiteral<"video_clip">;
+    duration_ms: z.ZodOptional<z.ZodNumber>;
+    play_in: z.ZodNumber;
+    play_out: z.ZodNumber;
+    volume: z.ZodNumber;
+    origin_media_id: z.ZodString;
+    speed_shift: z.ZodOptional<z.ZodObject<{
+      category: z.ZodOptional<z.ZodString>;
+      mode: z.ZodOptional<z.ZodString>;
+      config: z.ZodOptional<z.ZodObject<{
+        linear: z.ZodOptional<z.ZodObject<{
+          speed: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$loose>>;
+      }, z.core.$loose>>;
+    }, z.core.$loose>>;
+  }, z.core.$loose>;
+}, z.core.$loose>, z.ZodObject<{
+  speech: z.ZodObject<{
+    id: z.ZodOptional<z.ZodString>;
+    kind: z.ZodLiteral<"speech">;
+    media_duration_ms: z.ZodNumber;
+    duration_ms: z.ZodOptional<z.ZodNumber>;
+    audio_script: z.ZodString;
+    volume: z.ZodNumber;
+    audio_storage_key: z.ZodString;
+    origin_speech_id: z.ZodString;
+    voice: z.ZodUnknown;
+    caption_ids: z.ZodArray<z.ZodString>;
+  }, z.core.$loose>;
+}, z.core.$loose>, z.ZodObject<{
+  caption: z.ZodObject<{
+    id: z.ZodOptional<z.ZodString>;
+    kind: z.ZodLiteral<"caption">;
+    initial_duration_ms: z.ZodNumber;
+    speech_part_id: z.ZodString;
+    text: z.ZodString;
+    start_ms: z.ZodNumber;
+    style: z.ZodOptional<z.ZodObject<{
+      font_id: z.ZodOptional<z.ZodString>;
+      font_size: z.ZodOptional<z.ZodNumber>;
+      font_color: z.ZodOptional<z.ZodString>;
+      font_weight: z.ZodOptional<z.ZodNumber>;
+      entrance_animation: z.ZodOptional<z.ZodString>;
+      entrance_animation_duration_ms: z.ZodOptional<z.ZodNumber>;
+      stroke_color: z.ZodOptional<z.ZodString>;
+      stroke_width: z.ZodOptional<z.ZodNumber>;
+      position_x: z.ZodOptional<z.ZodNumber>;
+      position_y: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$loose>>;
+  }, z.core.$loose>;
+}, z.core.$loose>, z.ZodObject<{
+  bgm: z.ZodObject<{
+    id: z.ZodOptional<z.ZodString>;
+    kind: z.ZodLiteral<"bgm">;
+    audio_storage_key: z.ZodString;
+    volume: z.ZodNumber;
+    origin_media_id: z.ZodString;
+  }, z.core.$loose>;
+}, z.core.$loose>]>;
+declare const videoDocumentSchema: z.ZodObject<{
+  meta: z.ZodObject<{
+    schema_version: z.ZodLiteral<"video-document/v0">;
+    draft_id: z.ZodOptional<z.ZodString>;
+    project_id: z.ZodOptional<z.ZodString>;
+    owner_id: z.ZodOptional<z.ZodString>;
+    thumbnail_storage_key: z.ZodOptional<z.ZodString>;
+    chat_session_id: z.ZodOptional<z.ZodString>;
+    video_creation_settings: z.ZodOptional<z.ZodUnknown>;
+    version: z.ZodOptional<z.ZodNumber>;
+  }, z.core.$loose>;
+  timeline: z.ZodOptional<z.ZodObject<{
+    unit_time_ms: z.ZodOptional<z.ZodNumber>;
+  }, z.core.$loose>>;
+  tracks: z.ZodOptional<z.ZodArray<z.ZodObject<{
+    id: z.ZodOptional<z.ZodString>;
+    parts_kind: z.ZodOptional<z.ZodEnum<{
+      bgm: "bgm";
+      caption: "caption";
+      speech: "speech";
+      video_clip: "video_clip";
+    }>>;
+    is_hidden: z.ZodOptional<z.ZodBoolean>;
+    items: z.ZodOptional<z.ZodArray<z.ZodObject<{
+      part_id: z.ZodString;
+      time_position: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        mode: z.ZodLiteral<"sequential">;
+      }, z.core.$loose>, z.ZodObject<{
+        mode: z.ZodLiteral<"anchored">;
+        anchorPartId: z.ZodString;
+        offsetMs: z.ZodNumber;
+      }, z.core.$loose>, z.ZodObject<{
+        mode: z.ZodLiteral<"absolute">;
+        offsetMs: z.ZodNumber;
+      }, z.core.$loose>], "mode">;
+      fallback_abs_ms: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$loose>>>;
+  }, z.core.$loose>>>;
+  part_library: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodObject<{
+    video_clip: z.ZodObject<{
+      id: z.ZodOptional<z.ZodString>;
+      kind: z.ZodLiteral<"video_clip">;
+      duration_ms: z.ZodOptional<z.ZodNumber>;
+      play_in: z.ZodNumber;
+      play_out: z.ZodNumber;
+      volume: z.ZodNumber;
+      origin_media_id: z.ZodString;
+      speed_shift: z.ZodOptional<z.ZodObject<{
+        category: z.ZodOptional<z.ZodString>;
+        mode: z.ZodOptional<z.ZodString>;
+        config: z.ZodOptional<z.ZodObject<{
+          linear: z.ZodOptional<z.ZodObject<{
+            speed: z.ZodOptional<z.ZodNumber>;
+          }, z.core.$loose>>;
+        }, z.core.$loose>>;
+      }, z.core.$loose>>;
+    }, z.core.$loose>;
+  }, z.core.$loose>, z.ZodObject<{
+    speech: z.ZodObject<{
+      id: z.ZodOptional<z.ZodString>;
+      kind: z.ZodLiteral<"speech">;
+      media_duration_ms: z.ZodNumber;
+      duration_ms: z.ZodOptional<z.ZodNumber>;
+      audio_script: z.ZodString;
+      volume: z.ZodNumber;
+      audio_storage_key: z.ZodString;
+      origin_speech_id: z.ZodString;
+      voice: z.ZodUnknown;
+      caption_ids: z.ZodArray<z.ZodString>;
+    }, z.core.$loose>;
+  }, z.core.$loose>, z.ZodObject<{
+    caption: z.ZodObject<{
+      id: z.ZodOptional<z.ZodString>;
+      kind: z.ZodLiteral<"caption">;
+      initial_duration_ms: z.ZodNumber;
+      speech_part_id: z.ZodString;
+      text: z.ZodString;
+      start_ms: z.ZodNumber;
+      style: z.ZodOptional<z.ZodObject<{
+        font_id: z.ZodOptional<z.ZodString>;
+        font_size: z.ZodOptional<z.ZodNumber>;
+        font_color: z.ZodOptional<z.ZodString>;
+        font_weight: z.ZodOptional<z.ZodNumber>;
+        entrance_animation: z.ZodOptional<z.ZodString>;
+        entrance_animation_duration_ms: z.ZodOptional<z.ZodNumber>;
+        stroke_color: z.ZodOptional<z.ZodString>;
+        stroke_width: z.ZodOptional<z.ZodNumber>;
+        position_x: z.ZodOptional<z.ZodNumber>;
+        position_y: z.ZodOptional<z.ZodNumber>;
+      }, z.core.$loose>>;
+    }, z.core.$loose>;
+  }, z.core.$loose>, z.ZodObject<{
+    bgm: z.ZodObject<{
+      id: z.ZodOptional<z.ZodString>;
+      kind: z.ZodLiteral<"bgm">;
+      audio_storage_key: z.ZodString;
+      volume: z.ZodNumber;
+      origin_media_id: z.ZodString;
+    }, z.core.$loose>;
+  }, z.core.$loose>]>>>;
+}, z.core.$loose>;
+//#endregion
+export { VideoClipPart as $, TrackItemDraft as A, derivePositionFromAbs as B, isImplementedSemanticOpKind as C, PartIdFactory as D, ValidationError as E, assertValidVideoDocument as F, PartKind as G, toVideoDocument as H, validateVideoDocument as I, Timeline as J, PartUnion as K, DerivedItemPosition as L, VideoDocumentMirrorSchema as M, videoDocumentMirrorSchema as N, generatePartId as O, VideoDocumentValidationError as P, VIDEO_DOCUMENT_SCHEMA_VERSION as Q, SpeechHostMap as R, SemanticOpKind as S, SnapshotReadable as T, BgmPart as U, fromVideoDocument as V, CaptionPart as W, TrackItem as X, Track as Y, TrackItemTimePosition as Z, SemanticOpName as _, PlainMemoryAdapter as a, effectiveVideoClipDurationMs as at, ImplementedSemanticOpKind as b, MirrorVideoDocumentAdapter as c, CaptionPart$1 as ct, createMirrorVideoDocumentAdapter as d, SpeedShift as dt, VideoDocument as et, writeVideoDocumentToDraft as f, Timeline$1 as ft, SemanticOpInput as g, SemanticEditor as h, JournalEntry as i, VideoDraft as it, VideoDocumentDraft as j, TrackDraft as k, MirrorVideoDocumentOptions as l, CaptionStyle as lt, SemanticDocumentAdapter as m, TrackItem$1 as mt, videoDocumentSchema as n, VideoDocumentValidationIssue as nt, PlainMemoryAdapterOptions as o, speedOf as ot, CommitOptions as p, Track$1 as pt, SpeechPart as q, readVideoDocumentFromDraft as r, VideoDocumentValidationIssueCode as rt, createPlainMemoryAdapter as s, Attachment as st, partUnionSchema as t, VideoDocumentSchemaVersion as tt, createMirrorVideoDocument as u, PartAggregation as ut, TransactAudit as v, SchemaValidator as w, PlannedSemanticOpKind as x, IMPLEMENTED_SEMANTIC_OP_KINDS as y, buildSpeechHostMap as z };