@mengine/medeo-tool 1.2.1-alpha.7 → 1.2.1-alpha.8

package/dist/sandbox-api.d.mts

@@ -1,741 +1,94 @@
-//#region src/sandbox/generated/edit-sandbox-api.d.ts
-/**
- * @generated by gen:sandbox-dts — DO NOT EDIT MANUALLY
- *
- * Schema version: video-document/v0
- * Semantic ops: 20
- *
- * Boundary: zod `superRefine` / custom refine rules are NOT introspectable and
- * do not appear here. Business mutual-exclusion rules surface via runtime
- * validation errors (L3 feedback channel).
- *
- * @example 读取→计算→批量写
- * ```ts
- * const clips = timeline.clipsInRange(0, 10_000);
- * await edit.setVideoClipSpeedShift({
- *   clips: clips.map((c) => ({ clip_id: c.id, speed_shift: { category: 'linear', mode: 'constant', config: { linear: { speed: 1.5 } } } })),
- * });
- * ```
- *
- * @example anchored 删除
- * ```ts
- * await edit.deleteVideoClips({ clip_ids: ['clip_a'], on_anchored: 'detach' });
- * ```
- */
-/**
- * A clip's playback-speed fact, the only thing `SetVideoClipSpeedShift` writes.
- */
-interface SpeedShift {
-  category: 'linear' | 'curve';
-  mode: string;
-  config: {
-    linear: {
-      /**
-       * @constraint positive
-       */
-      speed: number;
-    };
-  } | {
-    curve: {
-      /**
-       * @constraint minLength(2)
-       */
-      keyframes: {
-        /**
-         * @constraint min(0)
-         * @constraint max(1)
-         */
-        position: number;
-        /**
-         * @constraint min(0)
-         */
-        rate: number;
-        /**
-         * Bezier tangent handle (x, y)
-         */
-        in_tangent?: {
-          x: number;
-          y: number;
-        };
-        /**
-         * Bezier tangent handle (x, y)
-         */
-        out_tangent?: {
-          x: number;
-          y: number;
-        };
-      }[];
-    };
-  };
-}
-/**
- * TTS voice summary attached to a speech
- */
-interface Voice {
-  /**
-   * @constraint minLength(1)
-   */
-  id: string;
-  name: string;
-}
-/**
- * A materialized speech-subtree write (speeches + their captions).
- */
-interface SpeechAssets {
-  /**
-   * Materialized speech parts to write
-   * @constraint minLength(1)
-   */
-  speeches: {
-    /**
-     * The speech part ID (= side-effect speech_parts[].id)
-     * @constraint minLength(1)
-     */
-    speech_id: string;
-    /**
-     * Host video clip part ID the speech anchors to (RFC 02 §4)
-     * @constraint minLength(1)
-     */
-    anchor_part_id: string;
-    /**
-     * Offset within the host clip (speech.abs = host.abs + offset_ms)
-     * @constraint int
-     * @constraint min(0)
-     */
-    offset_ms: number;
-    /**
-     * @constraint minLength(1)
-     */
-    audio_storage_key: string;
-    /**
-     * Duration in milliseconds (> 0)
-     * @constraint int
-     * @constraint positive
-     */
-    duration_ms: number;
-    audio_script: string;
-    /**
-     * Volume in decibels (-60.0 to 20.0; 0.0 = original, -60 = mute, +20 = max)
-     * @constraint min(-60)
-     * @constraint max(20)
-     */
-    volume: number;
-    /**
-     * TTS voice summary attached to a speech
-     */
-    voice: {
-      /**
-       * @constraint minLength(1)
-       */
-      id: string;
-      name: string;
-    };
-    /**
-     * @constraint minLength(1)
-     */
-    origin_speech_id: string;
-    /**
-     * Caption part IDs owned by this speech
-     */
-    caption_ids: string[];
-  }[];
-  /**
-   * Materialized caption parts owned by the speeches
-   */
-  captions: {
-    /**
-     * The caption part ID (= side-effect created_caption_parts[].id)
-     * @constraint minLength(1)
-     */
-    caption_id: string;
-    /**
-     * The owning speech part ID
-     * @constraint minLength(1)
-     */
-    speech_part_id: string;
-    text: string;
-    /**
-     * Offset within the host speech (caption.abs = speech.abs + start_ms)
-     * @constraint int
-     * @constraint min(0)
-     */
-    start_ms: number;
-    /**
-     * Duration in milliseconds (> 0)
-     * @constraint int
-     * @constraint positive
-     */
-    duration_ms: number;
-  }[];
-}
-interface MoveVideoClipsInput {
-  /**
-   * List of video clips to move to new positions
-   * @constraint minLength(1)
-   */
-  clips: {
-    /**
-     * The video clip part ID to move
-     * @constraint minLength(1)
-     */
-    clip_id: string;
-    /**
-     * New absolute start time in milliseconds on the timeline
-     * @constraint int
-     * @constraint min(0)
-     */
-    new_start_ms: number;
-    /**
-     * Target track ID to move the clip to (optional)
-     * @constraint minLength(1)
-     */
-    new_track_id?: string;
-  }[];
-}
-/**
- * Reorder a set of main-track clips relative to a reference clip.
- */
-interface MoveVideoClipsByAnchorInput {
-  /**
-   * Clips to move as one block, keeping their relative order. Need not be contiguous on the track.
-   * @constraint minLength(1)
-   */
-  clip_ids: string[];
-  /**
-   * Where the moved block lands: before/after a reference clip, or at the head of the track
-   */
-  anchor: {
-    position: 'before';
-    /**
-     * The moved block lands immediately before this clip
-     * @constraint minLength(1)
-     */
-    clip_id: string;
-  } | {
-    position: 'after';
-    /**
-     * The moved block lands immediately after this clip
-     * @constraint minLength(1)
-     */
-    clip_id: string;
-  } | {
-    position: 'track_start';
-  };
-  /**
-   * What happens to speeches anchored to the moved clips (required — see the policy doc)
-   */
-  on_anchored: 'follow' | 'keep_absolute';
-}
-interface DeleteVideoClipsInput {
-  /**
-   * List of video clip part IDs to delete from the main track
-   * @constraint minLength(1)
-   */
-  clip_ids: string[];
-  /**
-   * How to treat anchored children (default cascade)
-   */
-  on_anchored?: 'cascade' | 'detach';
-}
-/**
- * Add video clips to a track.
- */
-interface AddVideoClipsInput {
-  /**
-   * List of video clips to create
-   * @constraint minLength(1)
-   */
-  clips: {
-    /**
-     * The media asset ID for the video clip
-     * @constraint minLength(1)
-     */
-    media_id: string;
-    /**
-     * Absolute start time in milliseconds on the timeline
-     * @constraint int
-     * @constraint min(0)
-     */
-    start_ms?: number;
-    /**
-     * The source media's intrinsic full length in ms
-     * @constraint int
-     * @constraint positive
-     */
-    media_duration_ms: number;
-    /**
-     * Trim window start in the media (default 0)
-     * @constraint int
-     * @constraint min(0)
-     */
-    play_in?: number;
-    /**
-     * Trim window end in the media (default media_duration_ms)
-     * @constraint int
-     * @constraint positive
-     */
-    play_out?: number;
-    /**
-     * Target track ID (optional, defaults to main track)
-     * @constraint minLength(1)
-     */
-    track_id?: string;
-  }[];
-  /**
-   * Insert new clips before this clip ID
-   * @constraint minLength(1)
-   */
-  before_clip_id?: string;
-  /**
-   * Insert new clips after this clip ID
-   * @constraint minLength(1)
-   */
-  after_clip_id?: string;
-}
-interface AdjustVideoClipVolumeInput {
-  /**
-   * List of video clips with their new volume settings
-   * @constraint minLength(1)
-   */
-  clips: {
-    /**
-     * The video clip part ID to adjust volume for
-     * @constraint minLength(1)
-     */
-    clip_id: string;
-    /**
-     * Volume in decibels (-60.0 to 20.0; 0.0 = original)
-     * @constraint min(-60)
-     * @constraint max(20)
-     */
-    volume: number;
-  }[];
+//#region src/sandbox/generated/entity-edit-sandbox-api.d.ts
+/** @generated by gen:sandbox-dts. Entity-native editor contract; DO NOT EDIT. */
+interface AudioMediaAssetFact {
+  readonly assetId: string;
+  readonly kind: 'audio';
+  readonly durationMs: number;
+  readonly storageKey: string;
 }
-/**
- * Set the playback speed of existing video clips.
- */
-interface SetVideoClipSpeedShiftInput {
-  /**
-   * Video clips with their new speed settings
-   * @constraint minLength(1)
-   */
-  clips: {
-    /**
-     * The video clip part ID to set speed for
-     * @constraint minLength(1)
-     */
-    clip_id: string;
-    /**
-     * The new speed setting, or null to reset to 1×
-     */
-    speed_shift: {
-      category: 'linear' | 'curve';
-      mode: string;
-      config: {
-        linear: {
-          /**
-           * @constraint positive
-           */
-          speed: number;
-        };
-      } | {
-        curve: {
-          /**
-           * @constraint minLength(2)
-           */
-          keyframes: {
-            /**
-             * @constraint min(0)
-             * @constraint max(1)
-             */
-            position: number;
-            /**
-             * @constraint min(0)
-             */
-            rate: number;
-            /**
-             * Bezier tangent handle (x, y)
-             */
-            in_tangent?: {
-              x: number;
-              y: number;
-            };
-            /**
-             * Bezier tangent handle (x, y)
-             */
-            out_tangent?: {
-              x: number;
-              y: number;
-            };
-          }[];
-        };
-      };
-    } | null;
-  }[];
-}
-/**
- * Replace the media backing existing video clips.
- */
-interface ReplaceVideoClipContentInput {
-  /**
-   * Video clips whose media is being replaced
-   * @constraint minLength(1)
-   */
-  clips: {
-    /**
-     * Existing video clip part ID to re-point
-     * @constraint minLength(1)
-     */
-    clip_id: string;
-    /**
-     * The new media asset ID
-     * @constraint minLength(1)
-     */
-    origin_media_id: string;
-    /**
-     * The new media's intrinsic full length
-     * @constraint int
-     * @constraint positive
-     */
-    media_duration_ms: number;
-    /**
-     * Trim window start in the new media (usually 0)
-     * @constraint int
-     * @constraint min(0)
-     */
-    play_in: number;
-    /**
-     * Trim window end in the new media (usually = media_duration_ms)
-     * @constraint int
-     * @constraint positive
-     */
-    play_out: number;
-    /**
-     * Volume in decibels (-60.0 to 20.0; 0.0 = original, -60 = mute, +20 = max)
-     * @constraint min(-60)
-     * @constraint max(20)
-     */
-    volume: number;
-  }[];
-}
-/**
- * Replace a contiguous run of main-track clips with a new run.
- */
-interface ReplaceVideoClipSequenceInput {
-  /**
-   * The clips being replaced: a contiguous main-track run, listed in timeline order
-   * @constraint minLength(1)
-   */
-  old_clip_ids: string[];
-  /**
-   * The replacement clips, in the order they take on the track
-   * @constraint minLength(1)
-   */
-  new_clips: {
-    /**
-     * The replacement media asset ID. Omit to create an empty placeholder clip.
-     * @constraint minLength(1)
-     */
-    media_id?: string;
-    /**
-     * The source media's intrinsic full length in ms
-     * @constraint int
-     * @constraint positive
-     */
-    media_duration_ms: number;
-    /**
-     * Trim window start in the media (default 0)
-     * @constraint int
-     * @constraint min(0)
-     */
-    play_in?: number;
-    /**
-     * Trim window end in the media (default media_duration_ms)
-     * @constraint int
-     * @constraint positive
-     */
-    play_out?: number;
-  }[];
-  /**
-   * What happens to speeches anchored to the replaced clips (required — see the policy doc)
-   */
-  on_anchored: 'remap' | 'cascade';
-}
-/**
- * Re-trim existing video clips (the user-facing "adjust duration" gesture is a trim of the source window).
- */
-interface AdjustVideoClipDurationInput {
-  /**
-   * Video clips with their new trim windows
-   * @constraint minLength(1)
-   */
-  clips: {
-    /**
-     * The video clip part ID to re-trim
-     * @constraint minLength(1)
-     */
-    clip_id: string;
-    /**
-     * New trim window start in the source media
-     * @constraint int
-     * @constraint min(0)
-     */
-    play_in: number;
-    /**
-     * New trim window end in the source media
-     * @constraint int
-     * @constraint positive
-     */
-    play_out: number;
-  }[];
-}
-/**
- * Add speeches (and their captions).
- */
-interface AddSpeechesInput extends SpeechAssets {}
-/**
- * Delete speeches with their captions.
- */
-interface DeleteSpeechesInput {
-  /**
-   * Speech part IDs to delete (their captions cascade-delete)
-   * @constraint minLength(1)
-   */
-  speech_ids: string[];
-}
-/**
- * Move speeches in time.
- */
-interface MoveSpeechesInput {
-  /**
-   * Speeches to move to new positions
-   * @constraint minLength(1)
-   */
-  speeches: {
-    /**
-     * The speech part ID to move
-     * @constraint minLength(1)
-     */
-    speech_id: string;
-    /**
-     * New absolute start time on the timeline
-     * @constraint int
-     * @constraint min(0)
-     */
-    new_start_ms: number;
-  }[];
-}
-/**
- * Change a speech's script or voice.
- */
-interface ChangeSpeechScriptInput extends SpeechAssets {}
-interface ChangeSpeechVoiceInput extends SpeechAssets {}
-interface AdjustSpeechVolumeInput {
-  /**
-   * List of speeches with their new volume settings
-   * @constraint minLength(1)
-   */
-  speeches: {
-    /**
-     * The speech part ID to adjust volume for
-     * @constraint minLength(1)
-     */
-    speech_id: string;
-    /**
-     * Volume in decibels (-60.0 to 20.0; 0.0 = original)
-     * @constraint min(-60)
-     * @constraint max(20)
-     */
-    volume: number;
-  }[];
-}
-/**
- * Toggle caption visibility (the caption track's `is_hidden` flag).
- */
-interface SetCaptionVisibilityInput {
-  /**
-   * Whether the caption track is hidden
-   */
-  is_hidden: boolean;
-}
-/**
- * Set the caption visual style.
- */
-interface SetCaptionStyleInput {
-  /**
-   * Font ID referencing a font from the font library
-   * @constraint minLength(1)
-   */
-  font_id?: string;
-  /**
-   * Font size in points
-   * @constraint positive
-   */
-  font_size?: number;
-  /**
-   * Font color as hex string, e.g. "#FFFFFF"
-   * @constraint minLength(1)
-   */
-  font_color?: string;
-  /**
-   * Numeric font weight, e.g. 400 or 700
-   * @constraint int
-   */
-  font_weight?: number;
-  /**
-   * Entrance animation preset ID, e.g. "fade" or "none"
-   */
-  entrance_animation?: string;
-  /**
-   * Entrance animation duration in ms
-   * @constraint min(0)
-   */
-  entrance_animation_duration_ms?: number;
-  /**
-   * Outline/stroke color as hex string, e.g. "#000000"
-   * @constraint minLength(1)
-   */
-  stroke_color?: string;
-  /**
-   * Outline/stroke width in pixels
-   * @constraint min(0)
-   */
-  stroke_width?: number;
-  /**
-   * Caption center X as a fraction (0.0 to 1.0)
-   */
-  position_x?: number;
-  /**
-   * Caption center Y as a fraction (0.0 to 1.0)
-   */
-  position_y?: number;
-}
-/**
- * Set the document BGM.
- */
-interface SetBgmInput {
-  /**
-   * The bgm part ID to write
-   * @constraint minLength(1)
-   */
-  bgm_id: string;
-  /**
-   * @constraint minLength(1)
-   */
-  audio_storage_key: string;
-  /**
-   * The media asset ID
-   * @constraint minLength(1)
-   */
-  origin_media_id: string;
-  /**
-   * Volume in decibels (-60.0 to 20.0; 0.0 = original, -60 = mute, +20 = max)
-   * @constraint min(-60)
-   * @constraint max(20)
-   */
-  volume: number;
-}
-/**
- * Remove the document BGM.
- */
-interface DeleteBgmInput {
-  [key: string]: never;
-}
-interface AdjustBgmVolumeInput {
-  /**
-   * List of bgm parts with their new volume settings
-   * @constraint minLength(1)
-   */
-  bgm: {
-    /**
-     * The bgm part ID to adjust volume for
-     * @constraint minLength(1)
-     */
-    bgm_id: string;
-    /**
-     * Volume in decibels (-60.0 to 20.0; 0.0 = original)
-     * @constraint min(-60)
-     * @constraint max(20)
-     */
-    volume: number;
-  }[];
-}
-/** Agent write surface — one method per SemanticOp kind. */
-interface EditApi {
-  moveVideoClips(input: MoveVideoClipsInput): Promise<void>;
-  /** Reorder a set of main-track clips relative to a reference clip. */
-  moveVideoClipsByAnchor(input: MoveVideoClipsByAnchorInput): Promise<void>;
-  deleteVideoClips(input: DeleteVideoClipsInput): Promise<void>;
-  /** Add video clips to a track. */
-  addVideoClips(input: AddVideoClipsInput): Promise<void>;
-  adjustVideoClipVolume(input: AdjustVideoClipVolumeInput): Promise<void>;
-  /** Set the playback speed of existing video clips. */
-  setVideoClipSpeedShift(input: SetVideoClipSpeedShiftInput): Promise<void>;
-  /** Replace the media backing existing video clips. */
-  replaceVideoClipContent(input: ReplaceVideoClipContentInput): Promise<void>;
-  /** Replace a contiguous run of main-track clips with a new run. */
-  replaceVideoClipSequence(input: ReplaceVideoClipSequenceInput): Promise<void>;
-  /** Re-trim existing video clips (the user-facing "adjust duration" gesture is a trim of the source window). */
-  adjustVideoClipDuration(input: AdjustVideoClipDurationInput): Promise<void>;
-  /** Add speeches (and their captions). */
-  addSpeeches(input: AddSpeechesInput): Promise<void>;
-  /** Delete speeches with their captions. */
-  deleteSpeeches(input: DeleteSpeechesInput): Promise<void>;
-  /** Move speeches in time. */
-  moveSpeeches(input: MoveSpeechesInput): Promise<void>;
-  /** Change a speech's script or voice. */
-  changeSpeechScript(input: ChangeSpeechScriptInput): Promise<void>;
-  changeSpeechVoice(input: ChangeSpeechVoiceInput): Promise<void>;
-  adjustSpeechVolume(input: AdjustSpeechVolumeInput): Promise<void>;
-  /** Toggle caption visibility (the caption track's `is_hidden` flag). */
-  setCaptionVisibility(input: SetCaptionVisibilityInput): Promise<void>;
-  /** Set the caption visual style. */
-  setCaptionStyle(input: SetCaptionStyleInput): Promise<void>;
-  /** Set the document BGM. */
-  setBgm(input: SetBgmInput): Promise<void>;
-  /** Remove the document BGM. */
-  deleteBgm(input: DeleteBgmInput): Promise<void>;
-  adjustBgmVolume(input: AdjustBgmVolumeInput): Promise<void>;
-}
-type JsonPrimitive = string | number | boolean | null;
-type JsonValue = JsonPrimitive | JsonObject | JsonValue[];
-interface JsonObject {
-  [key: string]: JsonValue;
-}
-type KnownEntityKind = 'axvideo' | 'timeline' | 'track' | 'clip' | 'asset' | 'video' | 'audio' | 'voice' | 'image' | 'sequence-marker' | 'viewport' | 'audio-script' | 'phonetic-script' | 'caption';
-type KnownRelationKind = 'timeline-track' | 'track-clip' | 'clip-marker' | 'marker-content' | 'axvideo-marker' | 'marker-timeline' | 'physical-asset' | 'generated' | 'phonetic-script-provenance' | 'caption-provenance' | 'caption-alignment';
-interface BoundedNativeSequencePayload extends JsonObject {
-  /** Use factual recalled coordinates; never invent an end or duration. */
+interface BoundedDerivedSequencePayload extends JsonObject {
   extent: {
     kind: 'bounded';
     start: number;
     end: number;
   };
-  sampling: 'native';
-  coordinateSpace: JsonValue;
-}
-interface UnboundedConstantSequencePayload extends JsonObject {
-  extent: {
-    kind: 'unbounded';
-    start: number;
-  };
-  sampling: 'constant';
+  sampling: 'derived';
   coordinateSpace: JsonValue;
 }
-interface BoundedDerivedSequencePayload extends JsonObject {
+interface BoundedNativeSequencePayload extends JsonObject {
+  /** Factual coordinates from recalled media metadata; never invent an end/duration. */
   extent: {
     kind: 'bounded';
     start: number;
     end: number;
   };
-  sampling: 'derived';
+  sampling: 'native';
   coordinateSpace: JsonValue;
 }
-type ScriptTextSegment = JsonObject & {
-  segmentId: string;
-  text: string;
-  language?: string;
+interface CaptionFontDescriptor {
+  readonly system: 'font-library';
+  readonly key: string;
+}
+interface CaptionStyleFields {
+  readonly font?: CaptionFontDescriptor;
+  readonly fontSize?: number;
+  readonly fontColor?: string;
+  readonly fontWeight?: number;
+  readonly entranceAnimation?: string;
+  readonly entranceAnimationDurationMs?: number;
+  readonly strokeColor?: string;
+  readonly strokeWidth?: number;
+  readonly positionX?: number;
+  readonly positionY?: number;
+}
+type ClipEntityId = EntityId;
+type ClipPlacement = {
+  readonly kind: 'sequential';
+  readonly order: number;
+} | {
+  readonly kind: 'absolute';
+  readonly targetRange: SequenceRange<number>;
+} | {
+  readonly kind: 'anchored';
+  readonly hostClipEntityId: string;
+  readonly anchorOffset: number;
 };
+type CreateEntityInput = { [K in KnownEntityKind]: {
+  entity_id?: string;
+  entity_kind: K;
+  payload: EntityPayloadByKind[K];
+} }[KnownEntityKind];
+interface DeleteBgmInput {
+  readonly timelineEntityId: string;
+}
+interface DeleteClipInput {
+  readonly clipEntityId: string;
+}
+interface DeleteClipTreeInput {
+  readonly clipEntityIds: readonly string[];
+  readonly onAnchored: 'cascade' | 'detach';
+}
+interface DeleteEntityInput {
+  entity_id: string;
+}
+interface DeleteVoiceoverInput {
+  readonly voiceoverClipEntityIds: readonly string[];
+}
+type EmptyRelationKind = 'timeline-track' | 'track-clip' | 'clip-marker' | 'marker-content' | 'axvideo-marker' | 'marker-timeline';
+interface EntityFacade {
+  list(): SandboxEntity[];
+  get(entityId: string): SandboxEntity | null;
+  /** Return every explicitly imported Asset entity for a Memota asset id. */
+  findByAssetId(assetId: string): SandboxEntity<'asset'>[];
+  create(input: CreateEntityInput): string;
+  /** Replace one Entity's owned payload without changing its identity or kind. */
+  update(input: UpdateEntityInput): void;
+  /** Delete an Entity only after all of its incident Relations have been explicitly unlinked. */
+  delete(input: DeleteEntityInput): void;
+  /** Import one physical asset without implying a one-to-one media Entity mapping. */
+  importAsset(input: ImportAssetInput): string;
+}
+type EntityId = string;
 interface EntityPayloadByKind {
   axvideo: BoundedDerivedSequencePayload;
   timeline: JsonObject;
@@ -744,6 +97,7 @@ interface EntityPayloadByKind {
     role?: string;
   };
   clip: JsonObject;
+  /** Asset-owned metadata. Peer media associations belong in physical-asset Relations. */
   asset: JsonObject;
   video: BoundedNativeSequencePayload;
   audio: BoundedNativeSequencePayload;
@@ -765,6 +119,8 @@ interface EntityPayloadByKind {
       value: number;
     };
     timeRemapping?: JsonValue;
+    anchorOffset?: number;
+    durationPolicy?: 'timeline';
   };
   viewport: JsonObject;
   'audio-script': JsonObject & {
@@ -775,141 +131,364 @@ interface EntityPayloadByKind {
   };
   caption: BoundedNativeSequencePayload;
 }
-type CreateEntityInput = { [K in KnownEntityKind]: {
-  entity_id?: string;
-  entity_kind: K;
-  payload: EntityPayloadByKind[K];
-} }[KnownEntityKind];
+interface EntityStoreSnapshot {
+  revision: number;
+  entities: SandboxEntity[];
+  relations: SandboxRelation[];
+}
+interface ImageMediaAssetFact {
+  readonly assetId: string;
+  readonly kind: 'image';
+  readonly storageKey?: string;
+}
 interface ImportAssetInput {
   asset_id: string;
   entity_id?: string;
   payload?: JsonObject;
 }
-interface SandboxEntity<K extends KnownEntityKind = KnownEntityKind> {
-  entity_id: string;
-  entity_kind: K;
-  payload: EntityPayloadByKind[K];
+interface InsertClipInput {
+  readonly trackEntityId: string;
+  /** Existing Sequence media Entity id. Asset ids and URLs are not content ids. */
+  readonly contentEntityId: string;
+  readonly sourceRange: SequenceRange<number>;
+  readonly duration: SequenceDuration<number>;
+  readonly targetRange?: SequenceRange<number>;
+  readonly clipPayload?: JsonObject;
+}
+interface InsertMediaClipInput {
+  readonly timelineEntityId: string;
+  readonly clipEntityId?: string;
+  readonly media: VisualMediaAssetFact;
+  /** Source/display window in whole milliseconds. Images use this as their finite display span. */
+  readonly sourceRange: SequenceRange<number>;
+  readonly placement: ClipPlacement;
+  readonly volume?: number;
+}
+interface InsertMediaClipsInput {
+  readonly timelineEntityId: string;
+  readonly clips: readonly ReplacementMediaClipInput[];
+  /** One placement decision for the whole input-ordered block. */
+  readonly insertion: MediaClipInsertion;
+}
+interface InsertPlacedClipInput {
+  readonly trackEntityId: string;
+  readonly contentEntityId: string;
+  readonly sourceRange: SequenceRange<number>;
+  readonly duration: SequenceDuration<number>;
+  readonly placement: ClipPlacement;
+  readonly clipPayload?: JsonObject;
+  /** Stable caller-owned placement identity, when one already exists outside the graph. */
+  readonly clipEntityId?: string;
 }
-interface SandboxRelation {
-  relation_id: string;
-  relation_kind: KnownRelationKind;
-  endpoint_0_entity_id: string;
-  endpoint_1_entity_id: string;
-  metadata: JsonObject;
-  trace: JsonObject;
+interface JsonObject {
+  [key: string]: JsonValue;
 }
-type EmptyRelationKind = 'timeline-track' | 'track-clip' | 'clip-marker' | 'marker-content' | 'axvideo-marker' | 'marker-timeline';
-type LinkRelationInput = {
+type JsonPrimitive = string | number | boolean | null;
+type JsonValue = JsonPrimitive | JsonObject | JsonValue[];
+type KnownEntityKind = 'axvideo' | 'timeline' | 'track' | 'clip' | 'asset' | 'video' | 'audio' | 'voice' | 'image' | 'sequence-marker' | 'viewport' | 'audio-script' | 'phonetic-script' | 'caption';
+type KnownRelationKind = 'timeline-track' | 'track-clip' | 'clip-marker' | 'marker-content' | 'axvideo-marker' | 'marker-timeline' | 'physical-asset' | 'generated' | 'phonetic-script-provenance' | 'caption-provenance' | 'caption-alignment' | 'clip-anchor' | 'audio-script-render';
+interface LinearClipSpeed {
+  readonly kind: 'linear';
+  readonly rate: number;
+  readonly mode?: string;
+}
+interface LinkAudioScriptRenderRelationInput {
+  relation_id?: string;
+  output_entity_id: string;
+  script_entity_id: string;
+  trace?: JsonObject;
+}
+interface LinkClipAnchorRelationInput {
+  relation_id?: string;
+  child_clip_entity_id: string;
+  host_clip_entity_id: string;
+  trace?: JsonObject;
+}
+interface LinkGeneratedRelationInput {
+  relation_id?: string;
+  output_entity_id: string;
+  input_entity_id: string;
+  trace?: JsonObject;
+}
+interface LinkRelationBase {
   relation_id?: string;
-  relation_kind: EmptyRelationKind;
   endpoint_0_entity_id: string;
   endpoint_1_entity_id: string;
+  trace?: JsonObject;
+}
+type LinkRelationInput = (LinkRelationBase & {
+  relation_kind: EmptyRelationKind;
   metadata?: {
     [key: string]: never;
   };
-  trace?: JsonObject;
-} | {
-  relation_id?: string;
-  relation_kind: 'physical-asset'; /** Canonical endpoint 0 is sequence media; endpoint 1 is Asset. */
-  endpoint_0_entity_id: string;
-  endpoint_1_entity_id: string;
+}) | (LinkRelationBase & {
+  relation_kind: 'physical-asset';
   metadata?: JsonObject;
-  trace?: JsonObject;
-} | {
-  relation_id?: string;
+}) | (LinkRelationBase & {
   relation_kind: 'phonetic-script-provenance' | 'caption-provenance';
-  endpoint_0_entity_id: string;
-  endpoint_1_entity_id: string;
   metadata: JsonObject & {
     segmentAlignment: JsonValue;
   };
-  trace?: JsonObject;
-} | {
-  relation_id?: string;
+}) | (LinkRelationBase & {
   relation_kind: 'caption-alignment';
-  endpoint_0_entity_id: string;
-  endpoint_1_entity_id: string;
   metadata: JsonObject & {
     alignment: JsonValue;
   };
-  trace?: JsonObject;
+});
+type MediaClipInsertion = {
+  readonly kind: 'before';
+  readonly clipEntityId: string;
+} | {
+  readonly kind: 'after';
+  readonly clipEntityId: string;
+} | {
+  readonly kind: 'firstStart';
+  readonly startMs: number;
 };
-interface LinkGeneratedRelationInput {
-  relation_id?: string;
-  /** Generated output media Entity; persisted as endpoint 0. */
-  output_entity_id: string;
-  /** Input media Entity used to generate the output; persisted as endpoint 1. */
-  input_entity_id: string;
-  trace?: JsonObject;
+interface MoveClipInput {
+  readonly clipEntityId: string;
+  readonly trackEntityId: string;
+}
+interface MoveClipsToStartsInput {
+  readonly moves: readonly {
+    readonly clipEntityId: string;
+    readonly newStartMs: number;
+  }[];
+  /** Absolute-time drags preserve every voiceover's current visible landing. */
+  readonly onAnchored: 'keepAbsolute';
 }
-/** Explicit Entity authoring. Assets and media Entities are not one-to-one. */
-interface EntityApi {
-  list(): SandboxEntity[];
-  get(entityId: string): SandboxEntity | null;
-  /** Call before importAsset; inspect every match and decide whether to reuse one. */
-  findByAssetId(assetId: string): SandboxEntity<'asset'>[];
-  create(input: CreateEntityInput): string;
-  /** Create only an Asset Entity when no existing match should be reused; this does not infer media. */
-  importAsset(input: ImportAssetInput): string;
+interface MoveSequentialClipsInput {
+  readonly clipEntityIds: readonly string[];
+  readonly anchor: SequentialClipAnchor;
+  readonly onAnchored: 'follow' | 'keepAbsolute';
+}
+interface MoveVoiceoverInput {
+  readonly voiceoverClipEntityId: string;
+  /** Absolute requested timeline start; MEngine resolves and persists the host relation. */
+  readonly newStartMs: number;
+}
+interface PatchCaptionStyleInput {
+  readonly timelineEntityId: string;
+  readonly style: CaptionStyleFields;
 }
-/** Incident reads ignore endpoint position; relation semantics preserve it. */
-interface RelationApi {
+interface RelationFacade {
   list(): SandboxRelation[];
+  /** Incident lookup is endpoint-agnostic; persisted endpoint positions stay unchanged. */
   of(entityId: string, relationKind?: KnownRelationKind): SandboxRelation[];
+  /** For physical-asset use sequence media as endpoint 0 and Asset as endpoint 1. */
   link(input: LinkRelationInput): string;
-  /** Author ordered generated(output,input). */
+  /** Author ordered generated(output,input); generic link() deliberately rejects this kind. */
   linkGenerated(input: LinkGeneratedRelationInput): string;
+  /** Author ordered clip-anchor(child,host) without positional endpoint ambiguity. */
+  linkClipAnchor(input: LinkClipAnchorRelationInput): string;
+  /** Author ordered audio-script-render(output,script) without positional endpoint ambiguity. */
+  linkAudioScriptRender(input: LinkAudioScriptRenderRelationInput): string;
+  /** Remove a Relation by identity; endpoint replacement is an explicit unlink plus link. */
+  unlink(input: UnlinkRelationInput): void;
+}
+interface ReplaceClipContentInput {
+  readonly clipEntityId: string;
+  /** Existing Sequence media Entity id. Asset ids and URLs are not content ids. */
+  readonly contentEntityId: string;
+  readonly sourceRange: SequenceRange<number>;
+  readonly duration: SequenceDuration<number>;
+  readonly targetRange?: SequenceRange<number>;
+  readonly timeRemapping?: JsonValue;
+}
+interface ReplaceMediaClipInput {
+  readonly clipEntityId: string;
+  readonly media: VisualMediaAssetFact;
+  readonly sourceRange: SequenceRange<number>;
+}
+interface ReplaceSequentialClipsInput {
+  readonly timelineEntityId: string;
+  readonly oldClipEntityIds: readonly string[];
+  readonly newClips: readonly ReplacementMediaClipInput[];
+  readonly onAnchored: 'remap' | 'cascade';
+}
+interface ReplacementMediaClipInput {
+  readonly clipEntityId?: string;
+  readonly media: VisualMediaAssetFact;
+  readonly sourceRange: SequenceRange<number>;
+  readonly volume?: number;
 }
-/** Clip hit from `clipsInRange`. */
-interface TimelineClipDescriptor {
-  id: string;
-  start_ms: number;
-  end_ms: number;
-  duration_ms: number;
-  speed_shift: unknown;
-  volume: number | undefined;
-  media_id: string | undefined;
-}
-/** Part descriptor from `part(id)`. */
-interface TimelinePartDescriptor {
-  id: string;
-  kind: string;
-  lane: string;
-  start_ms: number;
-  end_ms: number;
-  duration_ms: number;
-  part: unknown;
-}
-/** Opaque VideoDraft projection (full IDL lives in host document types). */
-type VideoDraftProjection = {
-  readonly timeline?: {
-    readonly duration_ms?: number;
-  };
-  readonly [key: string]: unknown;
+interface SandboxEntity<K extends KnownEntityKind = KnownEntityKind> {
+  entity_id: string;
+  entity_kind: K;
+  payload: EntityPayloadByKind[K];
+}
+interface SandboxRelation {
+  relation_id: string;
+  relation_kind: KnownRelationKind;
+  endpoint_0_entity_id: string;
+  endpoint_1_entity_id: string;
+  metadata: JsonObject;
+  trace: JsonObject;
+}
+type ScriptTextSegment = JsonObject & {
+  segmentId: string;
+  text: string;
+  language?: string;
 };
-/** Agent read surface over the forked document. */
+type SequenceDuration<Span = unknown> = {
+  readonly mode: 'from-source';
+} | {
+  readonly mode: 'fixed';
+  readonly value: Span;
+};
+interface SequenceRange<Point = unknown> {
+  readonly start: Point;
+  readonly end: Point;
+}
+type SequentialClipAnchor = {
+  readonly position: 'before' | 'after';
+  readonly clipEntityId: string;
+} | {
+  readonly position: 'trackStart';
+};
+interface SetBgmInput {
+  readonly timelineEntityId: string;
+  readonly bgmClipEntityId: string;
+  readonly media: AudioMediaAssetFact;
+  readonly volume: number;
+}
+interface SetCaptionVisibilityInput {
+  readonly timelineEntityId: string;
+  readonly hidden: boolean;
+}
+interface SetClipPlacementInput {
+  readonly clipEntityId: string;
+  readonly placement: ClipPlacement;
+}
+interface SetClipSpeedInput {
+  readonly clipEntityId: string;
+  readonly timeRemapping: LinearClipSpeed | null;
+}
+interface SetClipVolumeInput {
+  readonly clipEntityId: string;
+  /** Playback gain in decibels. */
+  readonly volume: number;
+}
+interface TrimClipInput {
+  readonly clipEntityId: string;
+  readonly sourceRange: SequenceRange<number>;
+}
+interface UnboundedConstantSequencePayload extends JsonObject {
+  extent: {
+    kind: 'unbounded';
+    start: number;
+  };
+  sampling: 'constant';
+  coordinateSpace: JsonValue;
+}
+interface UnlinkRelationInput {
+  relation_id: string;
+}
+interface UpdateClipInput {
+  readonly clipEntityId: string;
+  /** Complete replacement for the Clip-owned payload. */
+  readonly payload: JsonObject;
+}
+interface UpdateClipMarkerInput {
+  readonly clipEntityId: string;
+  readonly sourceRange?: SequenceRange<number>;
+  /** Passing `undefined` explicitly removes the optional target range. */
+  readonly targetRange?: SequenceRange<number> | undefined;
+  readonly duration?: SequenceDuration<number>;
+  /** Passing `undefined` explicitly removes the optional remapping value. */
+  readonly timeRemapping?: JsonValue | undefined;
+}
+interface UpdateEntityInput {
+  entity_id: string;
+  payload: JsonObject;
+}
+interface VideoMediaAssetFact {
+  readonly assetId: string;
+  readonly kind: 'video';
+  readonly durationMs: number;
+  readonly storageKey?: string;
+}
+type VisualMediaAssetFact = ImageMediaAssetFact | VideoMediaAssetFact;
+interface VoiceDescriptor {
+  readonly system: 'voice-library';
+  readonly key: string;
+  readonly name?: string;
+}
+interface VoiceMediaAssetFact {
+  /** Stable external speech result id, independent of the placed Clip id. */
+  readonly assetId: string;
+  readonly kind: 'voice';
+  readonly durationMs: number;
+  readonly storageKey: string;
+  readonly voice: VoiceDescriptor;
+}
+interface VoiceoverCaptionFact {
+  /** Stable placed caption identity supplied by the materialized side effect. */
+  readonly captionClipEntityId: string;
+  readonly text: string;
+  readonly startMs: number;
+  readonly durationMs: number;
+  readonly style?: CaptionStyleFields;
+}
+interface VoiceoverTakeInput {
+  readonly timelineEntityId: string;
+  /** Stable placed speech identity, distinct from media.assetId. */
+  readonly voiceoverClipEntityId: string;
+  readonly hostClipEntityId: string;
+  readonly anchorOffset: number;
+  readonly media: VoiceMediaAssetFact;
+  /** Complete spoken text; the editor owns the deterministic local script segment identity. */
+  readonly scriptText: string;
+  readonly volume: number;
+  readonly captions: readonly VoiceoverCaptionFact[];
+}
+interface VoiceoverTakeResult {
+  readonly voiceoverClipEntityId: string;
+  readonly voiceEntityId: string;
+  readonly audioScriptEntityId: string;
+  readonly captionClipEntityIds: readonly string[];
+}
+/** Timeline writes accept existing media Entity ids, never Memota asset ids or URLs. */
+interface EditApi {
+  insertClip(input: InsertClipInput): ClipEntityId;
+  insertPlacedClip(input: InsertPlacedClipInput): ClipEntityId;
+  updateClipMarker(input: UpdateClipMarkerInput): void;
+  setClipPlacement(input: SetClipPlacementInput): void;
+  moveSequentialClips(input: MoveSequentialClipsInput): void;
+  moveClip(input: MoveClipInput): void;
+  replaceClipContent(input: ReplaceClipContentInput): void;
+  insertMediaClip(input: InsertMediaClipInput): ClipEntityId;
+  insertMediaClips(input: InsertMediaClipsInput): readonly ClipEntityId[];
+  replaceMediaClip(input: ReplaceMediaClipInput): void;
+  setClipVolume(input: SetClipVolumeInput): void;
+  setClipSpeed(input: SetClipSpeedInput): void;
+  trimClip(input: TrimClipInput): void;
+  replaceSequentialClips(input: ReplaceSequentialClipsInput): readonly ClipEntityId[];
+  deleteClip(input: DeleteClipInput): void;
+  deleteClipTree(input: DeleteClipTreeInput): void;
+  updateClip(input: UpdateClipInput): void;
+  upsertVoiceoverTake(input: VoiceoverTakeInput): VoiceoverTakeResult;
+  moveVoiceover(input: MoveVoiceoverInput): void;
+  moveClipsToStarts(input: MoveClipsToStartsInput): void;
+  deleteVoiceover(input: DeleteVoiceoverInput): void;
+  setBgm(input: SetBgmInput): ClipEntityId;
+  deleteBgm(input: DeleteBgmInput): void;
+  setCaptionVisibility(input: SetCaptionVisibilityInput): void;
+  patchCaptionStyle(input: PatchCaptionStyleInput): void;
+}
 interface TimelineApi {
-  /** Snapshot the current VideoDraft projection. */
-  snapshot(): VideoDraftProjection;
-  /** Clips whose midpoint falls in `[startMs, endMs)`. */
-  clipsInRange(startMs: number, endMs: number): TimelineClipDescriptor[];
-  /** Look up a part by id, or null if missing. */
-  part(id: string): TimelinePartDescriptor | null;
-}
-/** Opaque checkpoint handle for rollback. */
+  snapshot(): EntityStoreSnapshot;
+}
 interface SandboxCheckpoint {
   readonly index: number;
 }
 declare const edit: EditApi;
 declare const timeline: TimelineApi;
-declare const entities: EntityApi;
-declare const relations: RelationApi;
-/** Capture a rollback point. */
+declare const entities: EntityFacade;
+declare const relations: RelationFacade;
 declare function checkpoint(): SandboxCheckpoint;
-/** Roll the sandbox document back to a prior checkpoint. */
 declare function rollbackTo(cp: SandboxCheckpoint): void;
-/** Host-injected, pre-materialized facts. Validate each field before use. */
 declare const inputs: Readonly<Record<string, unknown>>;
 //#endregion
-export type { AddSpeechesInput, AddVideoClipsInput, AdjustBgmVolumeInput, AdjustSpeechVolumeInput, AdjustVideoClipDurationInput, AdjustVideoClipVolumeInput, BoundedDerivedSequencePayload, BoundedNativeSequencePayload, ChangeSpeechScriptInput, ChangeSpeechVoiceInput, CreateEntityInput, DeleteBgmInput, DeleteSpeechesInput, DeleteVideoClipsInput, EditApi, EmptyRelationKind, EntityApi, EntityPayloadByKind, ImportAssetInput, JsonObject, JsonPrimitive, JsonValue, KnownEntityKind, KnownRelationKind, LinkGeneratedRelationInput, LinkRelationInput, MoveSpeechesInput, MoveVideoClipsByAnchorInput, MoveVideoClipsInput, RelationApi, ReplaceVideoClipContentInput, ReplaceVideoClipSequenceInput, SandboxCheckpoint, SandboxEntity, SandboxRelation, ScriptTextSegment, SetBgmInput, SetCaptionStyleInput, SetCaptionVisibilityInput, SetVideoClipSpeedShiftInput, SpeechAssets, SpeedShift, TimelineApi, TimelineClipDescriptor, TimelinePartDescriptor, UnboundedConstantSequencePayload, VideoDraftProjection, Voice, checkpoint, edit, entities, inputs, relations, rollbackTo, timeline };
+export type { AudioMediaAssetFact, BoundedDerivedSequencePayload, BoundedNativeSequencePayload, CaptionFontDescriptor, CaptionStyleFields, ClipEntityId, ClipPlacement, CreateEntityInput, DeleteBgmInput, DeleteClipInput, DeleteClipTreeInput, DeleteEntityInput, DeleteVoiceoverInput, EditApi, EmptyRelationKind, EntityFacade, EntityId, EntityPayloadByKind, EntityStoreSnapshot, ImageMediaAssetFact, ImportAssetInput, InsertClipInput, InsertMediaClipInput, InsertMediaClipsInput, InsertPlacedClipInput, JsonObject, JsonPrimitive, JsonValue, KnownEntityKind, KnownRelationKind, LinearClipSpeed, LinkAudioScriptRenderRelationInput, LinkClipAnchorRelationInput, LinkGeneratedRelationInput, LinkRelationInput, MediaClipInsertion, MoveClipInput, MoveClipsToStartsInput, MoveSequentialClipsInput, MoveVoiceoverInput, PatchCaptionStyleInput, RelationFacade, ReplaceClipContentInput, ReplaceMediaClipInput, ReplaceSequentialClipsInput, ReplacementMediaClipInput, SandboxCheckpoint, SandboxEntity, SandboxRelation, ScriptTextSegment, SequenceDuration, SequenceRange, SequentialClipAnchor, SetBgmInput, SetCaptionVisibilityInput, SetClipPlacementInput, SetClipSpeedInput, SetClipVolumeInput, TimelineApi, TrimClipInput, UnboundedConstantSequencePayload, UnlinkRelationInput, UpdateClipInput, UpdateClipMarkerInput, UpdateEntityInput, VideoMediaAssetFact, VisualMediaAssetFact, VoiceDescriptor, VoiceMediaAssetFact, VoiceoverCaptionFact, VoiceoverTakeInput, VoiceoverTakeResult, checkpoint, edit, entities, inputs, relations, rollbackTo, timeline };
 //# sourceMappingURL=sandbox-api.d.mts.map