@mengine/medeo-tool 1.0.1-alpha.2 → 1.2.1-alpha.10

package/dist/sandbox-api.d.mts

@@ -1,669 +1,502 @@
-//#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: 18
- *
- * 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;
+//#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;
+}
+interface BoundedDerivedSequencePayload extends JsonObject {
+  extent: {
+    kind: 'bounded';
+    start: number;
+    end: number;
+  };
+  sampling: 'derived';
+  coordinateSpace: JsonValue;
+}
+interface BoundedNativeSequencePayload extends JsonObject {
+  /** Factual coordinates from recalled media metadata; never invent an end/duration. */
+  extent: {
+    kind: 'bounded';
+    start: number;
+    end: number;
+  };
+  sampling: 'native';
+  coordinateSpace: JsonValue;
+}
+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;
+  /** Find document resources by external Memota asset id, including directly composed media variants. */
+  findByAssetId(assetId: string): SandboxEntity<ResourceEntityKind>[];
+  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;
+  /** Get or create one typed Asset by factual external id and return its single content identity. Never creates a Clip. */
+  ensureMedia(fact: MediaAssetFact): {
+    contentEntityId: string;
+  };
+}
+type EntityId = string;
+interface EntityPayloadByKind {
+  axvideo: BoundedDerivedSequencePayload;
+  timeline: JsonObject;
+  track: JsonObject & {
+    hidden?: boolean;
+    role?: string;
+  };
+  clip: JsonObject;
+  /** Inline caption text; external media uses a typed Asset variant. */
+  asset: JsonObject;
+  video: BoundedNativeSequencePayload & MediaAssetPayload;
+  audio: BoundedNativeSequencePayload & MediaAssetPayload;
+  voice: BoundedNativeSequencePayload & MediaAssetPayload;
+  image: UnboundedConstantSequencePayload & MediaAssetPayload;
+  'sequence-marker': JsonObject & {
+    sourceRange: {
+      start: number;
+      end: number;
+    };
+    targetRange?: {
+      start: number;
+      end: 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;
-        };
-      }[];
+    duration: {
+      mode: 'from-source';
+    } | {
+      mode: 'fixed';
+      value: number;
     };
+    timeRemapping?: JsonValue;
+    anchorOffset?: number;
+    durationPolicy?: 'timeline';
+  };
+  viewport: JsonObject;
+  'audio-script': JsonObject & {
+    segments: ScriptTextSegment[];
   };
+  'phonetic-script': JsonObject & {
+    segments: ScriptTextSegment[];
+  };
+  caption: BoundedNativeSequencePayload;
 }
-/**
- * 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 EntityStoreSnapshot {
+  revision: number;
+  entities: SandboxEntity[];
+  relations: SandboxRelation[];
 }
-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;
-  }[];
+interface ImageMediaAssetFact {
+  readonly assetId: string;
+  readonly kind: 'image';
+  readonly storageKey?: string;
 }
-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;
-  }[];
+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;
 }
-/**
- * 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;
-  }[];
+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;
 }
-/**
- * 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;
-  }[];
+interface InsertMediaClipsInput {
+  readonly timelineEntityId: string;
+  readonly clips: readonly ReplacementMediaClipInput[];
+  /** One placement decision for the whole input-ordered block. */
+  readonly insertion: MediaClipInsertion;
 }
-/**
- * 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;
-  }[];
+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;
 }
-/**
- * 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;
-  }[];
+interface JsonObject {
+  [key: string]: JsonValue;
+}
+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;
 }
-/**
- * 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;
+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;
+  endpoint_0_entity_id: string;
+  endpoint_1_entity_id: string;
+  trace?: JsonObject;
+}
+type LinkRelationInput = (LinkRelationBase & {
+  relation_kind: EmptyRelationKind;
+  metadata?: {
+    [key: string]: never;
+  };
+}) | (LinkRelationBase & {
+  relation_kind: 'physical-asset';
+  metadata?: JsonObject;
+}) | (LinkRelationBase & {
+  relation_kind: 'phonetic-script-provenance' | 'caption-provenance';
+  metadata: JsonObject & {
+    segmentAlignment: JsonValue;
+  };
+}) | (LinkRelationBase & {
+  relation_kind: 'caption-alignment';
+  metadata: JsonObject & {
+    alignment: JsonValue;
+  };
+});
+/** Facts resolved from media storage. A trim window never substitutes for intrinsic duration. */
+type MediaAssetFact = ImageMediaAssetFact | VideoMediaAssetFact | AudioMediaAssetFact | VoiceMediaAssetFact;
+type MediaAssetPayload = JsonObject & {
+  external: {
+    system: 'memota' | 'memota-speech';
+    key: string;
+  };
+  storageKey?: string;
+};
+type MediaClipInsertion = {
+  readonly kind: 'before';
+  readonly clipEntityId: string;
+} | {
+  readonly kind: 'after';
+  readonly clipEntityId: string;
+} | {
+  readonly kind: 'firstStart';
+  readonly startMs: number;
+};
+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';
 }
-/**
- * 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 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;
+}
+interface RelationFacade {
+  list(): SandboxRelation[];
+  /** Incident lookup is endpoint-agnostic; persisted endpoint positions stay unchanged. */
+  of(entityId: string, relationKind?: KnownRelationKind): SandboxRelation[];
+  /** physical-asset binds inline Caption text, never external media. */
+  link(input: LinkRelationInput): string;
+  /** 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;
+}
+/** Asset identity, either an old physical-only row or a directly composed media variant. */
+type ResourceEntityKind = 'image' | 'video' | 'audio' | 'voice';
+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;
+};
+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 {
-  /**
-   * 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;
-  }[];
+  readonly timelineEntityId: string;
+  readonly bgmClipEntityId: string;
+  readonly media: AudioMediaAssetFact;
+  readonly volume: number;
 }
-/** Agent write surface — one method per SemanticOp kind. */
-interface EditApi {
-  moveVideoClips(input: MoveVideoClipsInput): 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>;
-  /** 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>;
-}
-/** 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;
+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;
   };
-  readonly [key: string]: unknown;
-};
-/** Agent read surface over the forked document. */
+  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;
-/** 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 script arguments (opaque). */
-declare const inputs: unknown;
+declare const inputs: Readonly<Record<string, unknown>>;
 //#endregion
-export type { AddSpeechesInput, AddVideoClipsInput, AdjustBgmVolumeInput, AdjustSpeechVolumeInput, AdjustVideoClipDurationInput, AdjustVideoClipVolumeInput, ChangeSpeechScriptInput, ChangeSpeechVoiceInput, DeleteBgmInput, DeleteSpeechesInput, DeleteVideoClipsInput, EditApi, MoveSpeechesInput, MoveVideoClipsInput, ReplaceVideoClipContentInput, SandboxCheckpoint, SetBgmInput, SetCaptionStyleInput, SetCaptionVisibilityInput, SetVideoClipSpeedShiftInput, SpeechAssets, SpeedShift, TimelineApi, TimelineClipDescriptor, TimelinePartDescriptor, VideoDraftProjection, Voice, checkpoint, edit, inputs, rollbackTo, timeline };
+export type { AudioMediaAssetFact, BoundedDerivedSequencePayload, BoundedNativeSequencePayload, CaptionFontDescriptor, CaptionStyleFields, ClipEntityId, ClipPlacement, CreateEntityInput, DeleteBgmInput, DeleteClipInput, DeleteClipTreeInput, DeleteEntityInput, DeleteVoiceoverInput, EditApi, EmptyRelationKind, EntityFacade, EntityId, EntityPayloadByKind, EntityStoreSnapshot, ImageMediaAssetFact, InsertClipInput, InsertMediaClipInput, InsertMediaClipsInput, InsertPlacedClipInput, JsonObject, JsonPrimitive, JsonValue, KnownEntityKind, KnownRelationKind, LinearClipSpeed, LinkAudioScriptRenderRelationInput, LinkClipAnchorRelationInput, LinkGeneratedRelationInput, LinkRelationInput, MediaAssetFact, MediaAssetPayload, MediaClipInsertion, MoveClipInput, MoveClipsToStartsInput, MoveSequentialClipsInput, MoveVoiceoverInput, PatchCaptionStyleInput, RelationFacade, ReplaceClipContentInput, ReplaceMediaClipInput, ReplaceSequentialClipsInput, ReplacementMediaClipInput, ResourceEntityKind, 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