@mengine/medeo-client 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,2373 @@
+import { InferInputType } from "loro-mirror";
+import { z } from "zod";
+import { LoroDoc, PeerID } from "loro-crdt";
+import { DocState } from "@mengine/sync";
+import { BaseDocStorage, Connection, DocDiff, DocSnapshotRecord, DocStorage, DocStorageOptions, DocUpdate, DocUpdateRecord } from "@mengine/storage";
+
+//#region src/client/base64.d.ts
+declare function bytesToBase64(bytes: Uint8Array): string;
+declare function base64ToBytes(base64: string): Uint8Array;
+//#endregion
+//#region src/client/wire.d.ts
+interface MengineDocumentVersion {
+  update_seq: number;
+  /** base64 `VersionVector.encode` of the server oplog — the sync anchor. */
+  server_vv: string;
+  /** base64 `encodeFrontiers` of the server oplog heads. */
+  frontiers: string;
+}
+interface MengineSnapshotResponse {
+  snapshot: string;
+  version: MengineDocumentVersion;
+}
+/** Business + causal metadata for one update (audit / rollback anchor). */
+interface MengineUpdateMeta {
+  semantic_op: string | null;
+  payload: unknown;
+  intent: string | null;
+  message: string | null;
+  parse_error: boolean;
+  peer: string;
+  counter: number;
+  lamport: number;
+  timestamp: number;
+  frontiers: string;
+}
+/**
+ * Response to `GET .../sync?from=<vv b64>`: the ops the caller is missing as one
+ * merged Loro update blob (`export({mode:'update', from})`) plus the server's
+ * current oplog VV. Loro resolves the causal partial order inside the blob, so
+ * there is no per-update envelope; `import` is idempotent, so an already-current
+ * caller gets a framing-only blob that applies as a no-op. Mirrors the server's
+ * `SyncWireResponse`.
+ */
+interface MengineSyncResponse {
+  /** base64 merged Loro update blob (empty string when the caller is current). */
+  update: string;
+  server_vv: string;
+}
+interface MengineAuditEntry extends MengineUpdateMeta {
+  update_seq: number;
+}
+interface MengineAuditResponse {
+  entries: MengineAuditEntry[];
+}
+interface MenginePushUpdateResponse {
+  kind: 'ack' | 'duplicate';
+  update_seq: number | null;
+  version: MengineDocumentVersion;
+}
+interface MengineRejectedResponse {
+  kind: 'rejected';
+  code: string;
+  message: string;
+  server_version: MengineDocumentVersion;
+}
+interface MengineSseUpdateEvent {
+  update_seq: number;
+  updates: string[];
+  meta: MengineUpdateMeta;
+  version: MengineDocumentVersion;
+}
+type MenginePushResponse = MenginePushUpdateResponse | MengineRejectedResponse;
+//#endregion
+//#region src/client/http-client.d.ts
+interface MengineHttpClientOptions {
+  docId: string;
+  httpOrigin: string;
+  authToken?: string;
+  /**
+   * The end-user id sent as the `medeo-user-id` header. Accepts either a static
+   * string or a getter evaluated per request. Prefer the getter when the login
+   * state hydrates asynchronously (e.g. the browser editor): the client is
+   * constructed eagerly but each request reads the latest id, so an id that is
+   * not yet ready at construction time is picked up once it settles — no need to
+   * defer client/session creation until auth is ready.
+   */
+  userId?: string | (() => string | undefined);
+  fetchImpl?: typeof fetch;
+}
+declare class MengineHttpRequestError extends Error {
+  readonly status: number;
+  readonly payload: unknown;
+  constructor(status: number, payload: unknown);
+}
+declare class MengineHttpClient {
+  private readonly options;
+  private readonly fetchImpl;
+  constructor(options: MengineHttpClientOptions);
+  fetchSnapshot(): Promise<MengineSnapshotResponse>;
+  bootstrapSnapshot(snapshot: Uint8Array): Promise<MengineSnapshotResponse>;
+  /**
+   * Loro VV-diff pull: send the caller's oplog `VersionVector.encode` as `from`
+   * (omit for a full pull) and receive exactly the updates it is missing plus
+   * the server's current VV. Replaces the old integer `after_update_id` cursor.
+   */
+  sync(fromVV?: Uint8Array): Promise<MengineSyncResponse>;
+  /** Audit trail: extracted metadata per accepted update, in log order. */
+  audit(): Promise<MengineAuditResponse>;
+  pushUpdate(update: Uint8Array, baseVersion?: unknown): Promise<MenginePushUpdateResponse>;
+  eventsUrl(): string;
+  headers(): Headers;
+  fetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response>;
+  private requestJson;
+  private endpoint;
+}
+//#endregion
+//#region src/client/sse.d.ts
+interface MengineEventStreamOptions {
+  client: MengineHttpClient;
+  signal?: AbortSignal;
+  /** Fired once the stream response is established (HTTP ok, body readable). */
+  onOpen?(): void;
+  onUpdate(event: MengineSseUpdateEvent): void;
+}
+declare function readMengineEventStream(options: MengineEventStreamOptions): Promise<void>;
+//#endregion
+//#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;
+}
+/**
+ * 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/schemas/add-speeches.d.ts
+/**
+ * Add speeches (and their captions). TTS runs upstream; the stable speech /
+ * caption parts arrive materialized (see `speech-assets.ts`). The op writes the
+ * parts and each speech's `{ mode:'anchored', anchorPartId, offsetMs }` fact
+ * verbatim — no write-time host-picking, no cascade (RFC 02 §4). The projection
+ * derives absolute positions on read.
+ */
+declare const addSpeechesInputSchema: z.ZodObject<{
+  speeches: z.ZodArray<z.ZodObject<{
+    speech_id: z.ZodString;
+    anchor_part_id: z.ZodString;
+    offset_ms: z.ZodNumber;
+    audio_storage_key: z.ZodString;
+    duration_ms: z.ZodNumber;
+    audio_script: z.ZodString;
+    volume: z.ZodNumber;
+    voice: z.ZodObject<{
+      id: z.ZodString;
+      name: z.ZodString;
+    }, z.core.$strip>;
+    origin_speech_id: z.ZodString;
+    caption_ids: z.ZodArray<z.ZodString>;
+  }, z.core.$strip>>;
+  captions: z.ZodArray<z.ZodObject<{
+    caption_id: z.ZodString;
+    speech_part_id: z.ZodString;
+    text: z.ZodString;
+    start_ms: z.ZodNumber;
+    duration_ms: z.ZodNumber;
+  }, z.core.$strip>>;
+}, z.core.$strip>;
+type AddSpeechesInput = z.infer<typeof addSpeechesInputSchema>;
+//#endregion
+//#region src/editor/schemas/add-video-clips.d.ts
+/**
+ * Add video clips to a track. Each clip's duration facts are separated so a
+ * single number is never overloaded (RFC 02 / `reference/16` §0b):
+ *
+ * - `media_duration_ms` is the source media's intrinsic full length (a resource
+ *   fact, written to the part);
+ * - `play_in` / `play_out` are the optional trim window into that media; when
+ *   omitted the whole media is used (`play_in=0`, `play_out=media_duration_ms`).
+ *
+ * The clip's effective timeline duration is derived by the projection from the
+ * trim window and `speed_shift` — it is never an input here.
+ */
+declare const addVideoClipsInputSchema: z.ZodObject<{
+  clips: z.ZodArray<z.ZodObject<{
+    media_id: z.ZodString;
+    start_ms: z.ZodOptional<z.ZodNumber>;
+    media_duration_ms: z.ZodNumber;
+    play_in: z.ZodOptional<z.ZodNumber>;
+    play_out: z.ZodOptional<z.ZodNumber>;
+    track_id: z.ZodOptional<z.ZodString>;
+  }, z.core.$strip>>;
+  before_clip_id: z.ZodOptional<z.ZodString>;
+  after_clip_id: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type AddVideoClipsInput = z.infer<typeof addVideoClipsInputSchema>;
+//#endregion
+//#region src/editor/schemas/adjust-bgm-volume.d.ts
+declare const adjustBgmVolumeInputSchema: z.ZodObject<{
+  bgm: z.ZodArray<z.ZodObject<{
+    bgm_id: z.ZodString;
+    volume: z.ZodNumber;
+  }, z.core.$strip>>;
+}, z.core.$strip>;
+type AdjustBgmVolumeInput = z.infer<typeof adjustBgmVolumeInputSchema>;
+//#endregion
+//#region src/editor/schemas/adjust-speech-volume.d.ts
+declare const adjustSpeechVolumeInputSchema: z.ZodObject<{
+  speeches: z.ZodArray<z.ZodObject<{
+    speech_id: z.ZodString;
+    volume: z.ZodNumber;
+  }, z.core.$strip>>;
+}, z.core.$strip>;
+type AdjustSpeechVolumeInput = z.infer<typeof adjustSpeechVolumeInputSchema>;
+//#endregion
+//#region src/editor/schemas/adjust-video-clip-duration.d.ts
+/**
+ * Re-trim existing video clips (the user-facing "adjust duration" gesture is a
+ * trim of the source window). The new `play_in` / `play_out` are the facts; the
+ * effective timeline duration is derived from them and the clip's `speed_shift`,
+ * and the change reflows downstream clips, speeches, and the timeline inside the
+ * op's transaction (no caller-materialized cascade).
+ */
+declare const adjustVideoClipDurationInputSchema: z.ZodObject<{
+  clips: z.ZodArray<z.ZodObject<{
+    clip_id: z.ZodString;
+    play_in: z.ZodNumber;
+    play_out: z.ZodNumber;
+  }, z.core.$strip>>;
+}, z.core.$strip>;
+type AdjustVideoClipDurationInput = z.infer<typeof adjustVideoClipDurationInputSchema>;
+//#endregion
+//#region src/editor/schemas/adjust-video-clip-volume.d.ts
+declare const adjustVideoClipVolumeInputSchema: z.ZodObject<{
+  clips: z.ZodArray<z.ZodObject<{
+    clip_id: z.ZodString;
+    volume: z.ZodNumber;
+  }, z.core.$strip>>;
+}, z.core.$strip>;
+type AdjustVideoClipVolumeInput = z.infer<typeof adjustVideoClipVolumeInputSchema>;
+//#endregion
+//#region src/editor/schemas/change-speech.d.ts
+/**
+ * Change a speech's script or voice. Both re-run TTS upstream and return the
+ * regenerated speech / caption parts in the same materialized shape as
+ * `AddSpeeches` (`speech-assets.ts`); the op upserts them by id (the speech part
+ * id is preserved across a re-TTS), re-seats at `start_ms`, and reflows. Old
+ * caption parts no longer owned by the speech are removed via `caption_ids`.
+ */
+declare const changeSpeechScriptInputSchema: z.ZodObject<{
+  speeches: z.ZodArray<z.ZodObject<{
+    speech_id: z.ZodString;
+    anchor_part_id: z.ZodString;
+    offset_ms: z.ZodNumber;
+    audio_storage_key: z.ZodString;
+    duration_ms: z.ZodNumber;
+    audio_script: z.ZodString;
+    volume: z.ZodNumber;
+    voice: z.ZodObject<{
+      id: z.ZodString;
+      name: z.ZodString;
+    }, z.core.$strip>;
+    origin_speech_id: z.ZodString;
+    caption_ids: z.ZodArray<z.ZodString>;
+  }, z.core.$strip>>;
+  captions: z.ZodArray<z.ZodObject<{
+    caption_id: z.ZodString;
+    speech_part_id: z.ZodString;
+    text: z.ZodString;
+    start_ms: z.ZodNumber;
+    duration_ms: z.ZodNumber;
+  }, z.core.$strip>>;
+}, z.core.$strip>;
+declare const changeSpeechVoiceInputSchema: z.ZodObject<{
+  speeches: z.ZodArray<z.ZodObject<{
+    speech_id: z.ZodString;
+    anchor_part_id: z.ZodString;
+    offset_ms: z.ZodNumber;
+    audio_storage_key: z.ZodString;
+    duration_ms: z.ZodNumber;
+    audio_script: z.ZodString;
+    volume: z.ZodNumber;
+    voice: z.ZodObject<{
+      id: z.ZodString;
+      name: z.ZodString;
+    }, z.core.$strip>;
+    origin_speech_id: z.ZodString;
+    caption_ids: z.ZodArray<z.ZodString>;
+  }, z.core.$strip>>;
+  captions: z.ZodArray<z.ZodObject<{
+    caption_id: z.ZodString;
+    speech_part_id: z.ZodString;
+    text: z.ZodString;
+    start_ms: z.ZodNumber;
+    duration_ms: z.ZodNumber;
+  }, z.core.$strip>>;
+}, z.core.$strip>;
+type ChangeSpeechScriptInput = z.infer<typeof changeSpeechScriptInputSchema>;
+type ChangeSpeechVoiceInput = z.infer<typeof changeSpeechVoiceInputSchema>;
+//#endregion
+//#region src/editor/schemas/delete-bgm.d.ts
+/**
+ * Remove the document BGM. Pure document edit: clears the bgm lane and removes
+ * the bgm part. Takes no input (a document holds at most one bgm); an empty
+ * object keeps the op signature uniform with the rest.
+ */
+declare const deleteBgmInputSchema: z.ZodObject<{}, z.core.$strip>;
+type DeleteBgmInput = z.infer<typeof deleteBgmInputSchema>;
+//#endregion
+//#region src/editor/schemas/delete-speeches.d.ts
+/**
+ * Delete speeches with their captions. Pure document edit (no side effect): the
+ * op removes each speech part, cascade-deletes the captions it owns (via
+ * `caption_ids` / `speech_part_id`), drops their track items, and reflows.
+ */
+declare const deleteSpeechesInputSchema: z.ZodObject<{
+  speech_ids: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+type DeleteSpeechesInput = z.infer<typeof deleteSpeechesInputSchema>;
+//#endregion
+//#region src/editor/schemas/delete-video-clips.d.ts
+/**
+ * How a delete handles the anchored subtree (speeches anchored to a deleted clip,
+ * and their captions) — a delete-op policy, not a data-model field (reference/17
+ * §6). `cascade` (default) removes the subtree; `detach` keeps the direct
+ * anchored children, re-pinning them to `absolute` so they stay on the timeline.
+ */
+declare const anchoredDeletePolicySchema: z.ZodEnum<{
+  cascade: "cascade";
+  detach: "detach";
+}>;
+type AnchoredDeletePolicy = z.infer<typeof anchoredDeletePolicySchema>;
+declare const deleteVideoClipsInputSchema: z.ZodObject<{
+  clip_ids: z.ZodArray<z.ZodString>;
+  on_anchored: z.ZodOptional<z.ZodEnum<{
+    cascade: "cascade";
+    detach: "detach";
+  }>>;
+}, z.core.$strip>;
+type DeleteVideoClipsInput = z.infer<typeof deleteVideoClipsInputSchema>;
+//#endregion
+//#region src/editor/schemas/move-speeches.d.ts
+/**
+ * Move speeches in time. Pure document edit: the op re-seats each speech at its
+ * new absolute `start_ms`; the cascade reassigns it to the host video clip,
+ * resolves overlaps, and reflows. Captions follow their speech.
+ */
+declare const moveSpeechesInputSchema: z.ZodObject<{
+  speeches: z.ZodArray<z.ZodObject<{
+    speech_id: z.ZodString;
+    new_start_ms: z.ZodNumber;
+  }, z.core.$strip>>;
+}, z.core.$strip>;
+type MoveSpeechesInput = z.infer<typeof moveSpeechesInputSchema>;
+//#endregion
+//#region src/editor/schemas/move-video-clips.d.ts
+declare const moveVideoClipsInputSchema: z.ZodObject<{
+  clips: z.ZodArray<z.ZodObject<{
+    clip_id: z.ZodString;
+    new_start_ms: z.ZodNumber;
+    new_track_id: z.ZodOptional<z.ZodString>;
+  }, z.core.$strip>>;
+}, z.core.$strip>;
+type MoveVideoClipsInput = z.infer<typeof moveVideoClipsInputSchema>;
+//#endregion
+//#region src/editor/schemas/replace-video-clip-content.d.ts
+/**
+ * Replace the media backing existing video clips. The media import runs upstream
+ * (Director); its stable result — the new media id, intrinsic length, and the
+ * reset trim window — arrives materialized (see
+ * `results/phase-4-side-effect-payload-contract.md` §4). Director resets
+ * `play_in=0` / `play_out=media_duration_ms` and clears `speed_shift` on
+ * replacement. The clip `part_id`s (hence their track items) are unchanged; the
+ * editor reflows the main track from the new effective durations.
+ */
+declare const replaceVideoClipContentInputSchema: z.ZodObject<{
+  clips: z.ZodArray<z.ZodObject<{
+    clip_id: z.ZodString;
+    origin_media_id: z.ZodString;
+    media_duration_ms: z.ZodNumber;
+    play_in: z.ZodNumber;
+    play_out: z.ZodNumber;
+    volume: z.ZodNumber;
+  }, z.core.$strip>>;
+}, z.core.$strip>;
+type ReplaceVideoClipContentInput = z.infer<typeof replaceVideoClipContentInputSchema>;
+//#endregion
+//#region src/editor/schemas/set-bgm.d.ts
+/**
+ * Set the document BGM. The media's stable result (storage key) arrives
+ * materialized from upstream (see
+ * `results/phase-4-side-effect-payload-contract.md` §3). The op upserts the bgm
+ * part and seats it on the bgm lane; its effective length is always the whole
+ * timeline, derived by the projection on read — so there is no `duration_ms`
+ * input or fact (RFC 02 / `reference/16` §0b). A `bgm_id` lets the op replace an
+ * existing bgm part by id.
+ */
+declare const setBgmInputSchema: z.ZodObject<{
+  bgm_id: z.ZodString;
+  audio_storage_key: z.ZodString;
+  origin_media_id: z.ZodString;
+  volume: z.ZodNumber;
+}, z.core.$strip>;
+type SetBgmInput = z.infer<typeof setBgmInputSchema>;
+//#endregion
+//#region src/editor/schemas/set-caption-style.d.ts
+/**
+ * Set the caption visual style. GLOBAL by design: the style applies to every
+ * caption part in the document — it carries NO `caption_id`. This mirrors the FE,
+ * whose caption-style store (`caption-style.ts:persistCaptionStylePatch`) iterates
+ * ALL captions and writes the same normalized style to each; the product has a
+ * single document-wide caption style, not per-caption styling.
+ *
+ * Every field is optional and maps to a `CaptionStyle` attribute (snake_case
+ * IDL). A field present in the input is written to every caption; a field ABSENT
+ * from the input is left untouched on each caption (the editor merges the patch
+ * onto each caption's existing style — this is a value edit, not a full-style
+ * replace, so a partial patch such as "recolor only" does not wipe font size).
+ *
+ * Pure document edit, no cascade — captions keep their positions; only the style
+ * sub-map of each caption part changes.
+ */
+declare const setCaptionStyleInputSchema: 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.$strip>;
+type SetCaptionStyleInput = z.infer<typeof setCaptionStyleInputSchema>;
+//#endregion
+//#region src/editor/schemas/set-caption-visibility.d.ts
+/**
+ * Toggle caption visibility (the caption track's `is_hidden` flag). Pure
+ * document edit, no cascade — captions keep their positions; only the lane's
+ * hidden flag changes.
+ */
+declare const setCaptionVisibilityInputSchema: z.ZodObject<{
+  is_hidden: z.ZodBoolean;
+}, z.core.$strip>;
+type SetCaptionVisibilityInput = z.infer<typeof setCaptionVisibilityInputSchema>;
+//#endregion
+//#region src/editor/schemas/set-video-clip-speed-shift.d.ts
+/**
+ * Set the playback speed of existing video clips. Per the speed-shift decision
+ * (`reference/16` §0): the op writes only the `speed_shift` fact — it does NOT
+ * store an effective `duration_ms` (projection derives it from the trim window /
+ * speed) and does NOT scale anchored speeches' relative offsets (offsets stay
+ * put; the cascade reflows absolute positions). A `null` speed_shift clears the
+ * speed back to original (1×).
+ */
+declare const setVideoClipSpeedShiftInputSchema: z.ZodObject<{
+  clips: z.ZodArray<z.ZodObject<{
+    clip_id: z.ZodString;
+    speed_shift: z.ZodNullable<z.ZodObject<{
+      category: z.ZodEnum<{
+        curve: "curve";
+        linear: "linear";
+      }>;
+      mode: z.ZodString;
+      config: z.ZodUnion<readonly [z.ZodObject<{
+        linear: z.ZodObject<{
+          speed: z.ZodNumber;
+        }, z.core.$strip>;
+      }, z.core.$strip>, z.ZodObject<{
+        curve: z.ZodObject<{
+          keyframes: z.ZodArray<z.ZodObject<{
+            position: z.ZodNumber;
+            rate: z.ZodNumber;
+            in_tangent: z.ZodOptional<z.ZodObject<{
+              x: z.ZodNumber;
+              y: z.ZodNumber;
+            }, z.core.$strip>>;
+            out_tangent: z.ZodOptional<z.ZodObject<{
+              x: z.ZodNumber;
+              y: z.ZodNumber;
+            }, z.core.$strip>>;
+          }, z.core.$strip>>;
+        }, z.core.$strip>;
+      }, z.core.$strip>]>;
+    }, z.core.$strip>>;
+  }, z.core.$strip>>;
+}, z.core.$strip>;
+type SetVideoClipSpeedShiftInput = z.infer<typeof setVideoClipSpeedShiftInputSchema>;
+//#endregion
+//#region src/editor/schemas/shared.d.ts
+declare const clipIdSchema: z.ZodString;
+declare const clipIdsSchema: z.ZodArray<z.ZodString>;
+declare const mediaIdSchema: z.ZodString;
+declare const speechIdSchema: z.ZodString;
+declare const timelineMsSchema: z.ZodNumber;
+declare const positiveMsSchema: z.ZodNumber;
+declare const volumeSchema: z.ZodNumber;
+declare const speechIdsSchema: z.ZodArray<z.ZodString>;
+/**
+ * A clip's playback-speed fact, the only thing `SetVideoClipSpeedShift` writes.
+ * Mirrors the IDL `SpeedShift`: `category` is `linear` | `curve`, and `config`
+ * is a discriminated union — `{ linear: { speed } }` for a constant multiplier
+ * (the multiplier projection reads at `config.linear.speed`) or `{ curve: {
+ * keyframes } }` for a Bezier-controlled variable speed (RFC 02 / `reference/16`
+ * §0). Exactly one of `linear` / `curve` is present.
+ */
+declare const speedShiftSchema: z.ZodObject<{
+  category: z.ZodEnum<{
+    curve: "curve";
+    linear: "linear";
+  }>;
+  mode: z.ZodString;
+  config: z.ZodUnion<readonly [z.ZodObject<{
+    linear: z.ZodObject<{
+      speed: z.ZodNumber;
+    }, z.core.$strip>;
+  }, z.core.$strip>, z.ZodObject<{
+    curve: z.ZodObject<{
+      keyframes: z.ZodArray<z.ZodObject<{
+        position: z.ZodNumber;
+        rate: z.ZodNumber;
+        in_tangent: z.ZodOptional<z.ZodObject<{
+          x: z.ZodNumber;
+          y: z.ZodNumber;
+        }, z.core.$strip>>;
+        out_tangent: z.ZodOptional<z.ZodObject<{
+          x: z.ZodNumber;
+          y: z.ZodNumber;
+        }, z.core.$strip>>;
+      }, z.core.$strip>>;
+    }, z.core.$strip>;
+  }, z.core.$strip>]>;
+}, z.core.$strip>;
+declare const voiceSchema: z.ZodObject<{
+  id: z.ZodString;
+  name: z.ZodString;
+}, z.core.$strip>;
+//#endregion
+//#region src/editor/schemas/speech-assets.d.ts
+/**
+ * The materialized TTS result shared by `AddSpeeches` / `ChangeSpeechScript` /
+ * `ChangeSpeechVoice` (see `results/phase-4-side-effect-payload-contract.md`
+ * §1/§2). The side effect (TTS/ASR + billing) runs upstream; the op receives the
+ * stable speech + caption parts and writes them as authoritative facts. No
+ * cascade runs on write — the projection derives absolute positions on read.
+ *
+ * Each speech carries the anchoring fact directly (RFC 02 §4): the host video
+ * clip `anchor_part_id` and the `offset_ms` within it. The upstream caller
+ * already knows which clip a speech attaches to, so the op writes
+ * `{ mode:'anchored', anchorPartId, offsetMs }` verbatim — no write-time
+ * host-picking. Captions anchor to their speech via the caption part's
+ * `start_ms` (offset within the speech).
+ */
+declare const speechAssetSchema: z.ZodObject<{
+  speech_id: z.ZodString;
+  anchor_part_id: z.ZodString;
+  offset_ms: z.ZodNumber;
+  audio_storage_key: z.ZodString;
+  duration_ms: z.ZodNumber;
+  audio_script: z.ZodString;
+  volume: z.ZodNumber;
+  voice: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+  }, z.core.$strip>;
+  origin_speech_id: z.ZodString;
+  caption_ids: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+declare const captionAssetSchema: z.ZodObject<{
+  caption_id: z.ZodString;
+  speech_part_id: z.ZodString;
+  text: z.ZodString;
+  start_ms: z.ZodNumber;
+  duration_ms: z.ZodNumber;
+}, z.core.$strip>;
+/** A materialized speech-subtree write (speeches + their captions). */
+declare const speechAssetsSchema: z.ZodObject<{
+  speeches: z.ZodArray<z.ZodObject<{
+    speech_id: z.ZodString;
+    anchor_part_id: z.ZodString;
+    offset_ms: z.ZodNumber;
+    audio_storage_key: z.ZodString;
+    duration_ms: z.ZodNumber;
+    audio_script: z.ZodString;
+    volume: z.ZodNumber;
+    voice: z.ZodObject<{
+      id: z.ZodString;
+      name: z.ZodString;
+    }, z.core.$strip>;
+    origin_speech_id: z.ZodString;
+    caption_ids: z.ZodArray<z.ZodString>;
+  }, z.core.$strip>>;
+  captions: z.ZodArray<z.ZodObject<{
+    caption_id: z.ZodString;
+    speech_part_id: z.ZodString;
+    text: z.ZodString;
+    start_ms: z.ZodNumber;
+    duration_ms: z.ZodNumber;
+  }, z.core.$strip>>;
+}, z.core.$strip>;
+type SpeechAsset = z.infer<typeof speechAssetSchema>;
+type CaptionAsset = z.infer<typeof captionAssetSchema>;
+type SpeechAssets = z.infer<typeof speechAssetsSchema>;
+declare namespace index_d_exports {
+  export { AddSpeechesInput, AddVideoClipsInput, AdjustBgmVolumeInput, AdjustSpeechVolumeInput, AdjustVideoClipDurationInput, AdjustVideoClipVolumeInput, AnchoredDeletePolicy, CaptionAsset, ChangeSpeechScriptInput, ChangeSpeechVoiceInput, DeleteBgmInput, DeleteSpeechesInput, DeleteVideoClipsInput, MoveSpeechesInput, MoveVideoClipsInput, ReplaceVideoClipContentInput, SetBgmInput, SetCaptionStyleInput, SetCaptionVisibilityInput, SetVideoClipSpeedShiftInput, SpeechAsset, SpeechAssets, addSpeechesInputSchema, addVideoClipsInputSchema, adjustBgmVolumeInputSchema, adjustSpeechVolumeInputSchema, adjustVideoClipDurationInputSchema, adjustVideoClipVolumeInputSchema, anchoredDeletePolicySchema, changeSpeechScriptInputSchema, changeSpeechVoiceInputSchema, clipIdSchema, clipIdsSchema, deleteBgmInputSchema, deleteSpeechesInputSchema, deleteVideoClipsInputSchema, mediaIdSchema, moveSpeechesInputSchema, moveVideoClipsInputSchema, positiveMsSchema, replaceVideoClipContentInputSchema, setBgmInputSchema, setCaptionStyleInputSchema, setCaptionVisibilityInputSchema, setVideoClipSpeedShiftInputSchema, speechAssetsSchema, speechIdSchema, speechIdsSchema, speedShiftSchema, timelineMsSchema, voiceSchema, volumeSchema };
+}
+//#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 {
+  intent?: {
+    kind: string;
+    payload: 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;
+  constructor(doc: SemanticDocumentAdapter, validator?: SchemaValidator);
+  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;
+//#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
+//#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;
+//#endregion
+//#region src/editor/snapshot-utils.d.ts
+/** Main-track item identity read from a raw snapshot (only `part_id` is needed). */
+interface MainTrackItemRef {
+  part_id: string | undefined;
+}
+declare function isMap(value: unknown): value is Map<unknown, unknown>;
+declare function snapshotToPlain(value: unknown): unknown;
+declare function getAt(snapshot: unknown, ...keys: string[]): unknown;
+declare function readMainTrackItems(snapshot: unknown): MainTrackItemRef[];
+/**
+ * The effective timeline duration of a part read from a raw snapshot. No part
+ * stores a derived `duration_ms` in authoritative state (reference/17 §5): a
+ * video clip's length is its trim window `play_out - play_in` over the speed
+ * multiplier; a speech's is its intrinsic `media_duration_ms`; a caption's is its
+ * `initial_duration_ms`. Falls back to `fallback` when no source value is
+ * resolvable (e.g. an unknown/raw part).
+ */
+declare function readPartDurationMs(snapshot: unknown, partId: string, fallback?: number): number;
+declare function readPart(snapshot: unknown, partId: string): (Record<string, unknown> & {
+  part_kind?: PartKind;
+}) | null;
+//#endregion
+//#region src/session/types.d.ts
+/**
+ * Local storage contract the runtime depends on. Aliased to the engine
+ * `DocStorage` so browsers can inject `IndexedDBDocStorage` and Node can inject
+ * `MemoryDocStorage` without medeo-client taking a hard dependency on either
+ * concrete implementation.
+ */
+type DocStorageLike = DocStorage;
+//#endregion
+//#region src/session/mengine-doc-session.d.ts
+interface MengineDocSessionUpdateEvent {
+  source: 'remote' | 'local';
+  snapshot: VideoDocument;
+}
+interface MengineDocSessionOptions {
+  docId: string;
+  client: MengineHttpClient;
+  peerId?: PeerID;
+  /**
+   * Local storage peer. Defaults to in-memory so the session works in Node.
+   * Browsers should pass an `IndexedDBDocStorage` for refresh/cross-tab support.
+   */
+  localStorage?: DocStorageLike;
+  sseReconnectDelayMs?: number;
+}
+/**
+ * A live editing session for one Medeo document — the single entry point clients
+ * (FE draft driver, Agent, embeds) use to open, edit, and observe a document.
+ *
+ * It assembles the engine sync stack around one Medeo document:
+ *
+ *   local DocStorage  ─┐
+ *                      ├─ ClientServerSynchronizer ── DocManager ── LoroDoc
+ *   MedeoHttpDocStorage┘                                              │
+ *                          (remote = Rust mengine-server)             ▼
+ *                                                   MirrorVideoDocumentAdapter + SemanticEditor
+ *
+ * `DocManager` owns the `LoroDoc`: local edits committed on the adapter are
+ * picked up via `subscribeLocalUpdates`, saved to local storage, then pushed to
+ * the server by the synchronizer. Remote SSE updates flow server → synchronizer
+ * → local storage → manager → `LoroDoc`. A single `LoroDoc.subscribe` turns any
+ * resulting change into a snapshot event, so callers never track update ids by
+ * hand.
+ *
+ * Replaces the per-consumer hand-written pull/SSE loops that previously lived in
+ * the standalone client session and `MengineDraftDriver` with one verified path.
+ */
+declare class MengineDocSession {
+  private readonly options;
+  private readonly docId;
+  private readonly local;
+  private readonly server;
+  private readonly synchronizer;
+  private readonly manager;
+  private readonly events;
+  private readonly disposables;
+  private adapterValue;
+  private editorValue;
+  private started;
+  constructor(options: MengineDocSessionOptions);
+  /**
+   * The editor for local edits. Each op method validates, writes, and commits
+   * itself as one SemanticOp (single commit carrying its audit message), so
+   * callers just call `session.editor.someOp(...)` — there is no separate commit
+   * step. The committed change drives DocManager's local-update push.
+   */
+  get editor(): SemanticEditor;
+  /** Current document snapshot (read model). */
+  snapshot(): VideoDocument;
+  /**
+   * Start the sync stack and connect the document.
+   *
+   * Returns once the local snapshot has loaded into the Loro doc so callers can
+   * read an initial snapshot. Remote convergence continues in the background and
+   * surfaces through `subscribe`.
+   */
+  start(): Promise<VideoDocument>;
+  subscribe(cb: (event: MengineDocSessionUpdateEvent) => void): () => void;
+  onStateChange(cb: (state: DocState) => void): () => void;
+  getState(): DocState;
+  destroy(): void;
+  /**
+   * Resolve once the Loro doc holds the document root.
+   *
+   * `DocManager` loads from local storage, which starts empty for a fresh
+   * client; the server snapshot arrives asynchronously via the first sync job.
+   * `loaded` only means the local load ran, so we wait for actual content
+   * (populated schema roots) instead, surfaced by the doc subscription set up
+   * in `start()`.
+   */
+  private waitForContent;
+  private hasContent;
+}
+//#endregion
+//#region src/storage/medeo-http-doc-storage.d.ts
+interface MedeoHttpDocStorageOptions {
+  docId: string;
+  client: MengineHttpClient;
+  sseReconnectDelayMs?: number;
+  readonlyMode?: boolean;
+}
+/**
+ * Adapts the mengine-server HTTP/SSE protocol to the engine `DocStorage`
+ * contract so `ClientServerSynchronizer` can treat it as a remote peer.
+ *
+ * Deliberately thin (mirrors the socket `DocStorage` in the playground): it
+ * forwards live SSE updates and exposes a version-vector diff, and keeps NO
+ * sync state of its own.
+ *
+ * - `getDocDiff(docId, knownVersion)` pulls the server-computed VV-diff via
+ *   `GET /sync?from=<vv>` — the synchronizer passes the real `doc.version()`, so
+ *   the response carries exactly the ops the doc is missing. `getDoc` (full
+ *   `/snapshot`) stays for cold start, when the caller holds no version yet.
+ * - `pushDocUpdate` forwards a Loro update; the server appends it.
+ * - `subscribeDocUpdate` registers a callback for live SSE updates. It does no
+ *   catch-up and keeps no cursor: after an SSE drop the connection reports a
+ *   status change, and the synchronizer re-runs its cycle to catch up via
+ *   `getDocDiff(doc.version())`. `LoroDoc.import` is idempotent (OpId/VV), so
+ *   re-forwarded or echoed updates are harmless.
+ *
+ * It is bound to a single `docId` because `MengineHttpClient` is per-document.
+ */
+declare class MedeoHttpDocStorage implements DocStorage {
+  private readonly options;
+  readonly connection: Connection;
+  private readonly client;
+  private readonly docId;
+  private readonly events;
+  constructor(options: MedeoHttpDocStorageOptions);
+  get isReadonly(): boolean;
+  getDoc(docId: string): Promise<DocSnapshotRecord | null>;
+  getDocDiff(docId: string, knownVersion?: Uint8Array): Promise<DocDiff | null>;
+  pushDocUpdate(update: DocUpdate, _origin: unknown): Promise<void>;
+  deleteDoc(_docId: string): Promise<void>;
+  subscribeDocUpdate(callback: (update: DocUpdate, origin: unknown) => void): () => void;
+  private assertDocId;
+  private emitUpdate;
+}
+//#endregion
+//#region src/storage/memory-doc-storage.d.ts
+/**
+ * Runtime-neutral local `DocStorage` backed by in-process memory.
+ *
+ * `IndexedDBDocStorage` is the browser-side local storage, but it requires
+ * `indexedDB`/`idb`, which is absent in Node (FE/agent tests, unit tests, SSR).
+ * The mengine runtime injects this implementation as the local peer in those
+ * environments so the same `DocManager` + `ClientServerSynchronizer` wiring
+ * works without a browser. It mirrors the merge-on-read and update-sequence
+ * behavior of `IndexedDBDocStorage` so sync semantics are identical.
+ */
+declare class MemoryDocStorage extends BaseDocStorage {
+  readonly connection: Connection;
+  private readonly entries;
+  constructor(options?: DocStorageOptions);
+  pushDocUpdate(update: DocUpdate, origin: unknown): Promise<void>;
+  deleteDoc(docId: string): Promise<void>;
+  protected getDocSnapshot(docId: string): Promise<DocSnapshotRecord | null>;
+  protected setDocSnapshot(snapshot: DocSnapshotRecord): Promise<boolean>;
+  protected getDocUpdates(docId: string): Promise<DocUpdateRecord[]>;
+  protected markUpdatesMerged(docId: string, updates: DocUpdateRecord[]): Promise<number>;
+  private entry;
+  private now;
+}
+//#endregion
+//#region src/timeline-core/types.d.ts
+/** Total document duration when there is no real content (matches FE bgm fallback). */
+declare const TIMELINE_SKELETON_DURATION_MS = 20000;
+/**
+ * Plain-JSON working shape the timeline-core cascade functions operate on.
+ *
+ * It is a flat, lane-as-array view of the document — close to agent-harness's
+ * `NormalizedDraftRow` and to the legacy `VideoDraft`, deliberately *not* the
+ * mirror's keyed-track-map storage shape. The editor converts a
+ * `VideoDocumentDraft` into this view, runs the cascade, and writes the result
+ * back (see `timeline-core/index.ts`). Keeping the algorithms on a structured
+ * shape makes them readable and 1:1 comparable with the canonical reference.
+ *
+ * All times are integer milliseconds (ADR 0009 §4): callers normalize on the
+ * way in and the cascade preserves that.
+ */
+interface TimelineDoc {
+  main_track: TimelineItem[];
+  /** speech lane (below main). */
+  speech_track: TimelineItem[];
+  /** caption lane (above main). */
+  caption_track: TimelineItem[];
+  /** bgm lane (below main). */
+  bgm_track: TimelineItem[];
+  part_library: Record<string, PartUnion>;
+  /** body_part_id -> { attachment part_id -> relative_time_position }. */
+  aggregations: Aggregation[];
+  timeline: {
+    duration_ms: number;
+    unit_time_ms: number;
+  };
+}
+/**
+ * Working item the cascade solves over. `part_id` is the placement identity
+ * (unique per lane). `time_position` is the authoritative input read from the
+ * draft; `abs_time_position` is the cascade's solve variable (derived output),
+ * seeded from `time_position` (or `fallback_abs_ms`) on read.
+ *
+ * `fallback_abs_ms` is the authoritative orphan-recovery snapshot carried beside
+ * `time_position` (RFC 02 §11.1). On read it seeds the solve variable for
+ * `anchored` items; on write it is refreshed to the freshly solved absolute
+ * position.
+ */
+interface TimelineItem {
+  part_id: string;
+  time_position: TrackItemTimePosition;
+  abs_time_position: number;
+  fallback_abs_ms?: number | undefined;
+}
+interface Aggregation {
+  body_part_id: string;
+  attachments: Array<{
+    part_id: string;
+    relative_time_position: number;
+  }>;
+}
+/** Empty placeholder clip marker: a video_clip part with no backing media. */
+declare function isEmptyVideoClip(part: PartUnion | undefined): boolean;
+/** Clamp a duration to a non-negative integer (NaN/Infinity/negative → 0). */
+declare function safeDurationMs(value: number | undefined): number;
+declare function partDurationMs(doc: TimelineDoc, partId: string): number;
+//#endregion
+//#region src/timeline-core/cascade.d.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.
+ */
+declare function arrangeMainTrackSeamlessly(doc: TimelineDoc): void;
+/**
+ * Sync attached parts' absolute positions from their host:
+ *   speech.abs   = host_video.abs + relative_time_position
+ *   caption.abs  = speech.abs + caption.start_ms
+ */
+declare function syncAggregatedClipsTimePosition(doc: TimelineDoc): void;
+/**
+ * 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.
+ */
+declare function reassignSpeechesToVideoClipsByTime(doc: TimelineDoc): void;
+/**
+ * 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.
+ */
+declare function recalculateTimelineDuration(doc: TimelineDoc): void;
+/**
+ * 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).
+ */
+declare function resolveSpeechOverlapByShiftingVideos(doc: TimelineDoc): boolean;
+/**
+ * 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.
+ */
+declare function resolveAllSpeechOverlaps(doc: TimelineDoc): void;
+/**
+ * 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).
+ */
+declare function fillMainTrackTimeGaps(doc: TimelineDoc, makeEmptyPart: (durationMs: number) => {
+  partId: string;
+}): void;
+//#endregion
+//#region src/timeline-core/entrypoints.d.ts
+/**
+ * The composed cascade the read-side projection runs (RFC 02 §7): the ordered
+ * step sequence `solveVideoDocument` applies to derive every absolute position,
+ * aggregation, gap filler, and the total duration from the position-only facts.
+ *
+ * `makeEmptyPart` mints placeholder clips for gap filling; the projection
+ * supplies a bounded id generator.
+ */
+type MakeEmptyPart = (durationMs: number) => {
+  partId: string;
+};
+/**
+ * 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).
+ */
+declare function cascadeAfterVideoClipChanges(doc: TimelineDoc, makeEmptyPart: MakeEmptyPart): void;
+//#endregion
+//#region src/timeline-core/bridge.d.ts
+/**
+ * Bridge between the authoritative `VideoDocument` (position-only facts) and the
+ * flat `TimelineDoc` the cascade primitives solve over.
+ *
+ * The data flow is single-directional (RFC 02 §7/§10): ops write only facts
+ * (`time_position`, parts) to `VideoDocument`; absolute time, `part_aggregations`,
+ * total duration, and gap fillers are NOT stored — the projection derives them
+ * on read by running the cascade. There is no write-back of solved positions.
+ *
+ * - `solveVideoDocument` seeds a `TimelineDoc` from each item's `time_position`,
+ *   runs the full cascade, and returns the derived read-view (abs / aggregations
+ *   / duration). It is the single solve shared by the legacy `VideoDraft`
+ *   projection.
+ * - `ensureLaneTrack` / `findLaneTrack` locate (or mint) a secondary lane's
+ *   track row in the draft, so ops can write authoritative facts onto the right
+ *   named container (lane = container).
+ */
+/** The projection-derived read-view of a `VideoDocument` (RFC 02 §7). */
+interface SolvedVideoDocument {
+  absByPartId: Map<string, number>;
+  aggregations: PartAggregation[];
+  durationMs: number;
+  partLibrary: Record<string, PartUnion>;
+}
+/**
+ * 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.
+ */
+declare function solveVideoDocument(document: VideoDocument): SolvedVideoDocument;
+/** The named container a secondary lane lives in. */
+type SecondaryLane = 'speech' | 'caption' | 'bgm';
+/**
+ * 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`).
+ */
+declare function ensureLaneTrack(draft: VideoDocumentDraft, kind: SecondaryLane | 'video_clip'): TrackDraft;
+/** Find a secondary lane's track row without minting it. */
+declare function findLaneTrack(draft: VideoDocumentDraft, kind: SecondaryLane): TrackDraft | undefined;
+//#endregion
+//#region src/timeline-core/locate.d.ts
+/**
+ * Forward positioning for write-time ops (RFC 02 §9.1) — NOT a cascade.
+ *
+ * The authoritative model stores only `position`; absolute time is derived at
+ * read time by the projection. But two write-time ops legitimately need to turn
+ * an *absolute target* into a `relative` `position` fact:
+ *
+ * - moving / reordering main-track video clips re-parents each affected speech
+ *   to the video clip its (unchanged) absolute landing now falls in (§9.1);
+ * - moving a speech places it at a new absolute time, then anchors it to the
+ *   host clip it lands in.
+ *
+ * Both need one forward computation: lay out the main track from flow order +
+ * effective durations, find the clip whose range contains the target ms, and
+ * emit `{ mode:'anchored', anchorPartId, offsetMs }`. This reads the current
+ * facts and writes one new fact — it never solves and writes back the whole
+ * layout (that stays the projection's job, read-side only).
+ */
+interface MainClipRange {
+  partId: string;
+  startMs: number;
+  endMs: number;
+}
+/**
+ * The flow-ordered main-track clip ranges (cumulative effective durations from
+ * 0). Empty-media gap fillers are not in authoritative state, so this reflects
+ * only the real clips the draft stores.
+ */
+declare function mainTrackRanges(draft: VideoDocumentDraft): MainClipRange[];
+/**
+ * Pick the host video clip an absolute time lands in, with the harness two-sided
+ * fallback: before the first clip → first clip; after the last → last clip.
+ * Returns null only when there is no clip at all (caller leaves the item as-is).
+ */
+declare function hostForAbsMs(ranges: MainClipRange[], absMs: number): MainClipRange | null;
+/**
+ * Build an `anchored` time position anchoring `absMs` to the host clip it lands
+ * in (offset clamped to a non-negative integer). Falls back to `absolute` when
+ * there is no host clip. Pair with `fallbackAbsMs = absMs` on the item.
+ */
+declare function relativePositionForAbs(ranges: MainClipRange[], absMs: number): TrackItemTimePosition;
+//#endregion
+export { type Aggregation, type Attachment, type BgmPart, type CaptionPart, type CaptionStyle, type CommitOptions, type DerivedItemPosition, type DocStorageLike, IMPLEMENTED_SEMANTIC_OP_KINDS, type ImplementedSemanticOpKind, type MainClipRange, type MakeEmptyPart, MedeoHttpDocStorage, type MedeoHttpDocStorageOptions, MemoryDocStorage, type MengineAuditEntry, type MengineAuditResponse, MengineDocSession, type MengineDocSessionOptions, type MengineDocSessionUpdateEvent, type MengineDocumentVersion, type MengineEventStreamOptions, MengineHttpClient, type MengineHttpClientOptions, MengineHttpRequestError, type MenginePushResponse, type MenginePushUpdateResponse, type MengineRejectedResponse, type MengineSnapshotResponse, type MengineSseUpdateEvent, type MengineSyncResponse, type MengineUpdateMeta, MirrorVideoDocumentAdapter, type MirrorVideoDocumentOptions, type PartAggregation, type PartKind, type PartUnion, type PlannedSemanticOpKind, SchemaValidator, type SemanticDocumentAdapter, SemanticEditor, type SemanticOpInput, type SemanticOpKind, type SemanticOpName, type SnapshotReadable, type SolvedVideoDocument, type SpeechHostMap, type SpeechPart, type SpeedShift, TIMELINE_SKELETON_DURATION_MS, type Timeline, type TimelineDoc, type TimelineItem, type Track, type TrackDraft, type TrackItem, type TrackItemDraft, type TrackItemTimePosition, type TransactAudit, VIDEO_DOCUMENT_SCHEMA_VERSION, ValidationError, type VideoClipPart, type VideoDocument, type VideoDocumentDraft, type VideoDocumentMirrorSchema, type VideoDocumentSchemaVersion, VideoDocumentValidationError, type VideoDocumentValidationIssue, type VideoDocumentValidationIssueCode, type VideoDraft, type CaptionPart$1 as VideoDraftCaptionPart, type Timeline$1 as VideoDraftTimeline, type Track$1 as VideoDraftTrack, type TrackItem$1 as VideoDraftTrackItem, arrangeMainTrackSeamlessly, assertValidVideoDocument, base64ToBytes, buildSpeechHostMap, bytesToBase64, cascadeAfterVideoClipChanges, createMirrorVideoDocument, createMirrorVideoDocumentAdapter, derivePositionFromAbs, ensureLaneTrack, fillMainTrackTimeGaps, findLaneTrack, fromVideoDocument, generatePartId, getAt, hostForAbsMs, isEmptyVideoClip, isImplementedSemanticOpKind, isMap, mainTrackRanges, partDurationMs, partUnionSchema, readMainTrackItems, readMengineEventStream, readPart, readPartDurationMs, readVideoDocumentFromDraft, reassignSpeechesToVideoClipsByTime, recalculateTimelineDuration, relativePositionForAbs, resolveAllSpeechOverlaps, resolveSpeechOverlapByShiftingVideos, safeDurationMs, index_d_exports as schemas, snapshotToPlain, solveVideoDocument, syncAggregatedClipsTimePosition, toVideoDocument, validateVideoDocument, videoDocumentMirrorSchema, videoDocumentSchema };