@mengine/medeo-client 2.0.1-alpha.2 → 2.0.1-alpha.21

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { t as index_d_exports } from "./index-CMa6ZCtX.js";
-import { $ as SequenceRange, A as generatePartId, At as VideoDraft, B as ResolvedEntityClipPlacement, Bt as Track$1, C as PlannedSemanticOpKind, Ct as TrackItemTimePosition, D as SnapshotReadable, Dt as VideoDocumentSchemaVersion, E as SchemaValidator, Et as VideoDocument, F as videoDocumentMirrorSchema, Ft as CaptionPart$1, G as EntityTimelineProjectionError, H as ResolvedEntityTrack, I as VideoDocumentValidationError, It as CaptionStyle, J as RelationRow, K as EntityRelationRows, L as assertValidVideoDocument, Lt as PartAggregation, M as TrackItemDraft, Mt as effectiveVideoClipDurationMs, N as VideoDocumentDraft, Nt as speedOf, O as ValidationError, Ot as VideoDocumentValidationIssue, P as VideoDocumentMirrorSchema, Pt as Attachment, Q as SequenceDuration, R as validateVideoDocument, Rt as SpeedShift, S as ImplementedSemanticOpKind, St as TrackItem, T as isImplementedSemanticOpKind, Tt as VideoClipPart, U as resolveEntityTimelineLayout, V as ResolvedEntityTimelineLayout, Vt as TrackItem$1, W as projectEntityTimeline, X as CaptionStyleFields, Y as CaptionSegmentSelection, Z as ScriptTextSegment, _ as SemanticEditor, _t as PartKind, a as PlainMemoryAdapter, at as buildInitialVideoDocument, b as TransactAudit, bt as Timeline, c as MirrorVideoDocumentAdapter, ct as buildSpeechHostMap, d as createMirrorVideoDocument, dt as toVideoDocument, et as VoiceDescriptor, f as createMirrorVideoDocumentAdapter, ft as BgmPart, g as SemanticDocumentAdapter, gt as ENTITY_TIMELINE_PROJECTION_SCHEMA_VERSION, h as OpActor, ht as DEFAULT_UNIT_TIME_MS, i as JournalEntry, it as InitialDocumentFacts, j as TrackDraft, jt as VideoDraftPartUnion, k as PartIdFactory, kt as VideoDocumentValidationIssueCode, l as MirrorVideoDocumentOptions, lt as derivePositionFromAbs, m as CommitOptions, mt as CaptionPart, n as videoDocumentSchema, nt as JsonValue, o as PlainMemoryAdapterOptions, ot as DerivedItemPosition, p as writeVideoDocumentToDraft, pt as CaptionDisplayCue, q as EntityRow, r as readVideoDocumentFromDraft, rt as EntityId, s as createPlainMemoryAdapter, st as SpeechHostMap, t as partUnionSchema, tt as JsonObject, u as applyEntityTimelineProjection, ut as fromVideoDocument, v as SemanticOpInput, vt as PartUnion, w as SemanticOpKind, wt as VIDEO_DOCUMENT_SCHEMA_VERSION, x as IMPLEMENTED_SEMANTIC_OP_KINDS, xt as Track, y as SemanticOpName, yt as SpeechPart, z as EntityTimelineTrackRole, zt as Timeline$1 } from "./index-B31KeDzA.js";
+import { $ as DerivedItemPosition, A as assertValidVideoDocument, At as VideoDocument, B as EntityRelationRows, Bt as CaptionStyle, C as isImplementedSemanticOpKind, Ct as SpeechOriginAssetSystem, D as PartIdFactory, Dt as TrackItem, E as ValidationError, Et as Track, F as ResolvedEntityTrack, Ft as VideoDraftPartUnion, G as ScriptTextSegment, Gt as TrackItem$1, H as RelationRow, Ht as SpeedShift, I as resolveEntityTimelineLayout, It as effectiveVideoClipDurationMs, J as VoiceDescriptor, K as SequenceDuration, L as EntityTimelineProjectionDocument, Lt as speedOf, M as EntityTimelineTrackRole, Mt as VideoDocumentValidationIssueCode, N as ResolvedEntityClipPlacement, Nt as VideoDraft, O as generatePartId, Ot as TrackItemTimePosition, P as ResolvedEntityTimelineLayout, Pt as VideoDraftContent, Q as buildInitialVideoDocument, R as projectEntityTimeline, Rt as Attachment, S as SemanticOpKind, St as PartUnion, T as SnapshotReadable, Tt as Timeline, U as CaptionSegmentSelection, Ut as Timeline$1, V as EntityRow, Vt as PartAggregation, W as CaptionStyleFields, Wt as Track$1, X as JsonValue, Y as JsonObject, Z as EntityId, _ as SemanticOpName, _t as BgmPart, a as PlainMemoryAdapter, at as LANE_KINDS_IN_STACK_ORDER, b as ImplementedSemanticOpKind, bt as DEFAULT_UNIT_TIME_MS, c as MirrorVideoDocumentAdapter, ct as ensureLaneTrack, d as createMirrorVideoDocumentAdapter, dt as solveVideoDocument, et as SpeechHostMap, f as CommitOptions, ft as TrackDraft, g as SemanticOpInput, gt as videoDocumentMirrorSchema, h as SemanticEditor, ht as VideoDocumentMirrorSchema, i as JournalEntry, it as toVideoDocument, j as validateVideoDocument, jt as VideoDocumentValidationIssue, k as VideoDocumentValidationError, kt as VideoClipPart, l as MirrorVideoDocumentOptions, lt as findLaneTrack, m as SemanticDocumentAdapter, mt as VideoDocumentDraft, n as videoDocumentSchema, nt as derivePositionFromAbs, o as PlainMemoryAdapterOptions, ot as LaneKind, p as OpActor, pt as TrackItemDraft, q as SequenceRange, r as readVideoDocumentFromDraft, rt as fromVideoDocument, s as createPlainMemoryAdapter, st as SolvedVideoDocument, t as partUnionSchema, tt as buildSpeechHostMap, u as createMirrorVideoDocument, ut as laneTrackId, v as TransactAudit, vt as CaptionDisplayCue, w as SchemaValidator, wt as SpeechPart, x as PlannedSemanticOpKind, xt as PartKind, y as IMPLEMENTED_SEMANTIC_OP_KINDS, yt as CaptionPart, z as EntityTimelineProjectionError, zt as CaptionPart$1 } from "./index-CzDNr1Tb.js";
 import { LoroDoc, PeerID } from "loro-crdt";
 import { DocState } from "@mengine/sync";
 import { BaseDocStorage, Connection, DocDiff, DocPushReceipt, DocSnapshotRecord, DocStorage, DocStorageOptions, DocUpdate, DocUpdateRecord } from "@mengine/storage";
@@ -134,7 +134,6 @@ declare class MengineHttpClient {
   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
@@ -175,6 +174,8 @@ interface MengineEventStreamOptions {
   /** Fired once the stream response is established (HTTP ok, body readable). */
   onOpen?(): void;
   onUpdate(event: MengineSseUpdateEvent): void;
+  /** A committed update omitted from live transport; fetch the missing operations by VV. */
+  onResync?(): void;
 }
 declare function readMengineEventStream(options: MengineEventStreamOptions): Promise<void>;
 //#endregion
@@ -191,6 +192,16 @@ interface AssembledCaptionContent {
   readonly audioScript: EntityRow<'audio-script'>;
   /** Selected AudioScript segments in Caption selection order. */
   readonly segments: readonly ScriptTextSegment[];
+  /**
+   * Where the selected segment sits in the AudioScript's ordered segments.
+   *
+   * A Caption locates its text as AudioScript plus index. The selection is
+   * stored as the segment's own stable id rather than this ordinal, so a
+   * concurrent insert or re-segmentation cannot silently slide a Caption onto
+   * different text; the ordinal is derived here for readers that want the
+   * position.
+   */
+  readonly segmentIndex: number;
   /** Complete display text: the selected segments' text joined in order. */
   readonly text: string;
 }
@@ -221,8 +232,8 @@ declare function selectAudioScriptSegment(script: EntityRow<'audio-script'>, sel
 //#region src/entity-editor/entity-graph-http-client.d.ts
 /** One authenticated revision of the authoritative Medeo Entity graph. */
 interface EntityGraphState {
-  /** Current AudioScript content version attached to the project. */
-  readonly audioScriptEntityId: string;
+  /** Current AudioScript attached to the project, or null until one is written. */
+  readonly audioScriptEntityId: string | null;
   readonly revision: number;
   readonly loroSnapshot: string;
   readonly rows: EntityRelationRows;
@@ -251,6 +262,171 @@ declare class EntityGraphHttpClient {
   private request;
 }
 //#endregion
+//#region src/entity-crdt/field-changes.d.ts
+/** List members are addressed by identity, never a transient array offset. */
+type FieldPath = readonly (string | {
+  elementId: string;
+})[];
+type FieldChange = {
+  op: 'set';
+  path: FieldPath;
+  value: JsonValue;
+} | {
+  op: 'unset';
+  path: FieldPath;
+} | {
+  op: 'text.splice';
+  path: FieldPath;
+  index: number;
+  deleteCount: number;
+  text: string;
+} | {
+  op: 'list.insert';
+  path: FieldPath;
+  value: JsonValue;
+  beforeElementId: string | null;
+} | {
+  op: 'list.move';
+  path: FieldPath;
+  elementId: string;
+  beforeElementId: string | null;
+} | {
+  op: 'list.remove';
+  path: FieldPath;
+  elementId: string;
+};
+declare function assertFieldChanges(changes: readonly FieldChange[]): void;
+/** Resolve against the sequential causal view; the numeric path never crosses the API boundary. */
+declare function resolveFieldPath(payload: JsonObject, path: FieldPath): (string | number)[];
+/** Detached plan evaluation. Native compilation replays the original operations, not this snapshot. */
+declare function applyFieldChanges(payload: JsonObject, changes: readonly FieldChange[]): JsonObject;
+//#endregion
+//#region src/entity-crdt/entity-document.d.ts
+declare const LORO_ENTITY_SCHEMA = "medeo.entities.loro.v1";
+interface EntityDocumentState {
+  readonly rows: EntityRelationRows;
+  readonly project: Readonly<Record<string, string>>;
+}
+type Command = {
+  type: 'create';
+  row: EntityRow;
+} | {
+  type: 'selection-baseline';
+  root: string;
+  fingerprint: string;
+} | {
+  type: 'order';
+  group: string;
+  roots: string[];
+  token: string;
+} | {
+  type: 'write';
+  root: string;
+  payload: JsonObject;
+  token: string;
+} | {
+  type: 'text';
+  root: string;
+  path: readonly (string | number)[];
+  start: number;
+  deleteCount: number;
+  text: string;
+  token: string;
+} | {
+  type: 'field';
+  root: string;
+  path: (string | number)[];
+  change: FieldChange;
+  token: string;
+} | {
+  type: 'relation-field';
+  root: string;
+  path: (string | number)[];
+  change: FieldChange;
+} | {
+  type: 'delete';
+  root: string;
+} | {
+  type: 'relation';
+  row: RelationRow;
+} | {
+  type: 'relation-fields';
+  root: string;
+  metadata: JsonObject;
+  trace: JsonObject;
+} | {
+  type: 'unlink';
+  root: string;
+} | {
+  type: 'attach';
+  slot: string;
+  entityId: string;
+};
+/** Plain domain objects assembled from native Loro state, never a second writable authority. */
+declare function readEntityDocument(doc: LoroDoc, allowSelectionConflicts?: boolean): EntityDocumentState;
+/** Native editing containers survive domain version changes and merge independently. */
+declare class LoroEntityDocument {
+  readonly doc: LoroDoc;
+  private readonly validate?;
+  private readonly undoManager;
+  constructor(doc: LoroDoc, validate?: ((state: EntityDocumentState) => void) | undefined);
+  /** Open a causal snapshot using the same Loro runtime as the compiler. */
+  static fromSnapshot(snapshot: Uint8Array, validate?: (state: EntityDocumentState) => void): LoroEntityDocument;
+  static create(rows: EntityRelationRows, project?: Readonly<Record<string, string>>, peerId?: PeerID): LoroEntityDocument;
+  snapshot(): EntityDocumentState;
+  relationsOf(entityId: string): readonly RelationRow[];
+  /** Read unlinked Relation records for durable effect receipts; never part of the current semantic graph. */
+  tombstonedRelations(): readonly RelationRow[];
+  /** Resolve a queued edit target through its native identity without changing history. */
+  resolveCurrentEntityId(id: string): string;
+  getVersion(id: string): EntityRow | undefined;
+  /** The callback and every domain validation execute on a causally complete fork first. */
+  transact(edit: (draft: LoroEntityDraft) => void): Uint8Array;
+  /** Import preserves native operation identities; projection errors never discard remote operations. */
+  import(update: Uint8Array): void;
+  /**
+   * Bind a saved snapshot without rewriting text operations or resolving
+   * selection conflicts. The script names the bytes the same way everything
+   * else does — an Asset entity plus a Relation — and keeps only the
+   * fingerprint that tells a stale snapshot from a current one. The Relation is
+   * `to-asset`: these bytes are the script's own content written out, not a
+   * source it was made from.
+   */
+  bindAudioScriptAsset(entityId: string, assetId: string, expectedContentHash: string): Uint8Array;
+  canUndo(): boolean;
+  canRedo(): boolean;
+  undo(): boolean;
+  redo(): boolean;
+  private historyEdit;
+}
+declare class LoroEntityDraft {
+  private readonly doc;
+  readonly commands: Command[];
+  private readonly selectedRoots;
+  private readonly relationAliases;
+  constructor(doc: LoroDoc);
+  snapshot(): EntityDocumentState;
+  order(groupId: string, entityIds: readonly string[]): void;
+  /** Project the final scalar placement intents onto the existing native ordering containers. */
+  reconcileOrder(rows: EntityRelationRows): void;
+  create(row: EntityRow): void;
+  delete(entityId: string): void;
+  attach(slot: string, entityId: string): void;
+  link(row: RelationRow): void;
+  patchRelation(relationId: string, metadata: JsonObject, trace: JsonObject): void;
+  unlink(relationId: string): void;
+  private relationRoot;
+  update(entityId: string, fields: JsonObject): void;
+  declare(entityId: string, fields: JsonObject): void;
+  replaceOwned(entityId: string, payload: JsonObject): void;
+  editText(entityId: string, path: readonly (string | number)[], start: number, deleteCount: number, text: string): void;
+  /** Generic assembled-field edit compiled at the author's causal position. */
+  change(entityId: string, changes: readonly FieldChange[]): void;
+  changeRelation(relationId: string, changes: readonly FieldChange[]): void;
+  captureSelectionBaselines(): void;
+  private record;
+}
+//#endregion
 //#region src/entity-editor/types.d.ts
 /** Injectable domain-id mint shared by Entity and Relation authoring surfaces. */
 type EntityTimelineIdFactory = (prefix: 'entity' | 'relation') => string;
@@ -271,17 +447,94 @@ interface AudioMediaAssetFact {
   readonly durationMs: number;
   readonly storageKey: string;
 }
-interface VoiceMediaAssetFact {
+/**
+ * Speech. It materializes as a `voiceover` entity — its own kind, because only
+ * speech answers which words it said; `voice` names the timbre identity it was
+ * synthesized with, which becomes its own Voice entity linked by a
+ * `voice-timbre` Relation.
+ */
+interface VoiceoverMediaAssetFact {
   /** Stable external speech result id, independent of the placed Clip id. */
   readonly assetId: string;
-  readonly kind: 'voice';
+  readonly kind: 'voiceover';
   readonly durationMs: number;
   readonly storageKey: string;
-  /** Present for synthesized voice, absent for original recorded audio. */
+  /**
+   * The PhoneticScript this take was spoken from, when the caller minting it
+   * knows. A migration that rebuilds the whole chain relates it itself; either
+   * way a take that never names one is refused when a plan is built.
+   */
+  readonly phoneticScriptEntityId?: string;
+  /** Present for synthesized speech, absent for original recorded audio. */
   readonly voice?: VoiceDescriptor;
 }
 /** Facts resolved from media storage. A trim window never substitutes for intrinsic duration. */
-type MediaAssetFact = ImageMediaAssetFact | VideoMediaAssetFact | AudioMediaAssetFact | VoiceMediaAssetFact;
+type MediaAssetFact = ImageMediaAssetFact | VideoMediaAssetFact | AudioMediaAssetFact | VoiceoverMediaAssetFact;
+/** Host-resolved ASR artifact. The SDK treats its storage fields as opaque facts. */
+interface CaptionAssetFact {
+  readonly assetId: string;
+  readonly storageKey?: string;
+}
+interface AsrCaptionSegment extends ScriptTextSegment {
+  readonly startMs: number;
+  readonly endMs: number;
+}
+/** One closed host command for materializing an ASR result into the Entity graph. */
+interface ApplyCaptionAssetsInput {
+  readonly effectId: string;
+  readonly timelineEntityId: string;
+  readonly trackEntityId: string;
+  readonly source: {
+    readonly entityId: string;
+    readonly entityKind: 'audio' | 'video';
+  };
+  /** The exact placed use whose source-relative ASR timing is being materialized. */
+  readonly sourceOccurrence: {
+    readonly clipEntityId: string;
+    readonly markerEntityId: string;
+  };
+  readonly captionAsset: CaptionAssetFact;
+  readonly segments: readonly AsrCaptionSegment[];
+}
+interface ApplyCaptionAssetsResult {
+  readonly audioScriptEntityId: string;
+  readonly audioScriptMarkerEntityId: string;
+  readonly captionAssetEntityId: string;
+  readonly captionEntityIds: readonly string[];
+  readonly captionClipEntityIds: readonly string[];
+}
+interface CaptionAssetsEffectEnvelope {
+  readonly version: 1;
+  readonly baselineFingerprint: string;
+  readonly effectId: string;
+  readonly signature: string;
+  readonly input: ApplyCaptionAssetsInput;
+  readonly decisions: {
+    readonly sourceOccurrence: {
+      readonly sourceStartMs: number;
+      readonly sourceEndMs: number;
+      readonly timelineStartMs: number;
+      readonly rate: number;
+    };
+    readonly targetRanges: readonly {
+      readonly segmentId: string;
+      readonly start: number;
+      readonly end: number;
+    }[];
+    readonly captionAsset: {
+      readonly mode: 'create' | 'reuse' | 'replace';
+      readonly priorAssetEntityId?: string;
+      readonly resultAssetEntityId: string;
+      readonly reboundRelationIds: readonly string[];
+    };
+  };
+}
+interface CompiledCaptionAssetsEffect {
+  readonly result: ApplyCaptionAssetsResult;
+  readonly replayed: boolean;
+  readonly update?: Uint8Array;
+  readonly rows: EntityRelationRows;
+}
 type ClipPlacement = {
   readonly kind: 'sequential';
   readonly order: number;
@@ -333,7 +586,7 @@ interface DeleteClipTreeInput {
 interface VoiceoverCaptionFact {
   /** Stable placed caption identity supplied by the materialized side effect. */
   readonly captionClipEntityId: string;
-  /** Directly held bases; includes the AudioScript used by the Voice. */
+  /** Directly held bases; includes the AudioScript the voiceover was rendered from. */
   readonly baseEntityIds: readonly string[];
   /** Ordered selection of AudioScript segments; caption text is never passed inline. */
   readonly selection: CaptionSegmentSelection;
@@ -344,7 +597,7 @@ interface VoiceoverCaptionFact {
 type VoiceoverTakeInput = {
   readonly timelineEntityId: string; /** Stable placed speech identity, distinct from media.assetId. */
   readonly voiceoverClipEntityId: string;
-  readonly media: VoiceMediaAssetFact; /** Existing pronunciation variant; its composed AudioScript stays the text owner. */
+  readonly media: VoiceoverMediaAssetFact; /** Existing pronunciation variant; its composed AudioScript stays the text owner. */
   readonly phoneticScriptEntityId: string;
   readonly volume: number;
   readonly captions: readonly VoiceoverCaptionFact[];
@@ -414,14 +667,168 @@ interface SetClipSpeedInput {
   readonly clipEntityId: string;
   readonly timeRemapping: LinearClipSpeed | null;
 }
+type VideoClipSpeedMode = '0.5x' | '0.75x' | '1.0x' | '1.5x' | '2.0x';
+interface SetVideoClipSpeedEffectInput {
+  readonly clips: readonly {
+    readonly videoClipEntityId: string;
+    readonly mode: VideoClipSpeedMode;
+  }[];
+}
+interface GeneratedVisualClipFact {
+  readonly media: VisualMediaAssetFact;
+  /** Finite timeline use duration. Required for still images and bounded for video. */
+  readonly durationMs: number;
+  readonly generationJobId: string;
+  readonly sourceMediaEntityIds: readonly string[];
+  readonly volume?: number;
+}
+interface GeneratedVisualsInputBase {
+  readonly effectId: string;
+  readonly timelineEntityId: string;
+  readonly clips: readonly GeneratedVisualClipFact[];
+}
+/** An omitted occurrence anchor means the start of the main visual Track. */
+type AddGeneratedVisualsInput = GeneratedVisualsInputBase & ({
+  readonly beforeClipEntityId: string;
+  readonly afterClipEntityId?: never;
+} | {
+  readonly beforeClipEntityId?: never;
+  readonly afterClipEntityId: string;
+} | {
+  readonly beforeClipEntityId?: never;
+  readonly afterClipEntityId?: never;
+});
+interface ContinueVideoInput {
+  readonly effectId: string;
+  readonly timelineEntityId: string;
+  readonly afterClipEntityId: string;
+  readonly tailFrameEntityId: string;
+  readonly sourceMediaEntityId: string;
+  readonly media: VideoMediaAssetFact;
+}
+interface GeneratedVisualEffectEnvelope {
+  readonly version: 1;
+  readonly baselineFingerprint: string;
+  readonly effectId: string;
+  readonly signature: string;
+  readonly input: AddGeneratedVisualsInput;
+  readonly decisions: {
+    readonly trackEntityId: string;
+    readonly anchorOrder: number | null;
+    readonly anchorPosition: 'before' | 'after' | 'track_start';
+    readonly insertionOrders: readonly number[];
+  };
+}
+interface GeneratedVisualEffectResult {
+  readonly clipEntityIds: readonly string[];
+  readonly mediaEntityIds: readonly string[];
+}
+interface CompiledGeneratedVisualEffect {
+  readonly result: GeneratedVisualEffectResult;
+  readonly replayed: boolean;
+  readonly update?: Uint8Array;
+  readonly rows: EntityRelationRows;
+}
+interface GeneratedSpeechCaptionFact {
+  readonly startMs: number;
+  readonly endMs: number;
+  readonly selection: CaptionSegmentSelection;
+}
+/** Host-resolved current Loro segment; arbitrary immutable JSON fields remain owned by the script. */
+type ResolvedSpeechScriptSegment = ScriptTextSegment & JsonObject;
+type ResolvedAsrSpeechSegment = AsrCaptionSegment & JsonObject;
+type GeneratedSpeechSourceFact = {
+  readonly kind: 'phonetic-script';
+  readonly audioScriptEntityId: string;
+  readonly phoneticScriptEntityId: string;
+  readonly segments: readonly ResolvedSpeechScriptSegment[];
+  readonly phonemeScript?: string;
+} | {
+  readonly kind: 'audio-script';
+  readonly audioScriptEntityId?: string;
+  readonly segments: readonly ResolvedAsrSpeechSegment[];
+  readonly sourceMediaEntityIds: readonly string[];
+  readonly sourceStartMs: number;
+};
+interface GeneratedSpeechFactBase {
+  readonly source: GeneratedSpeechSourceFact;
+  readonly captions: readonly GeneratedSpeechCaptionFact[];
+  readonly volume?: number;
+}
+type GeneratedSpeechFact = GeneratedSpeechFactBase & ({
+  readonly renderMode: 'recorded';
+  readonly media: AudioMediaAssetFact;
+  readonly source: Extract<GeneratedSpeechSourceFact, {
+    kind: 'audio-script';
+  }>;
+} | {
+  readonly renderMode: 'synthesized';
+  readonly media: Omit<VoiceoverMediaAssetFact, 'voice'> & {
+    readonly voice: VoiceDescriptor;
+  };
+});
+interface AddSpeechAssetsInput {
+  readonly effectId: string;
+  readonly timelineEntityId: string;
+  readonly items: readonly (GeneratedSpeechFact & {
+    readonly placementStartMs: number;
+  })[];
+}
+interface ReplaceVoiceSpeechAssetsInput {
+  readonly effectId: string;
+  readonly timelineEntityId: string;
+  readonly items: readonly (Extract<GeneratedSpeechFact, {
+    renderMode: 'synthesized';
+  }> & {
+    readonly targetSpeechClipEntityId: string; /** Explicit current Caption uses replaced with this selected speech use. */
+    readonly targetCaptionClipEntityIds: readonly string[];
+  })[];
+}
+type SpeechAssetsEffectInput = {
+  readonly mode: 'add';
+  readonly value: AddSpeechAssetsInput;
+} | {
+  readonly mode: 'replace-voice';
+  readonly value: ReplaceVoiceSpeechAssetsInput;
+};
+interface SpeechAssetsEffectEnvelope {
+  readonly version: 1;
+  readonly baselineFingerprint: string;
+  readonly effectId: string;
+  readonly signature: string;
+  readonly input: SpeechAssetsEffectInput;
+  readonly decisions: {
+    readonly speechTrackEntityId: string;
+    readonly captionTrackEntityId?: string;
+    readonly targetStartsMs: readonly number[]; /** Existing raw-Audio occurrences reused by recorded items; positional with input items. */
+    readonly recordedSpeechClipEntityIds: readonly (string | null)[];
+  };
+}
+interface SpeechAssetsEffectResult {
+  readonly speechClipEntityIds: readonly string[];
+  readonly speechAudioEntityIds: readonly string[];
+  readonly audioScriptEntityIds: readonly string[];
+  /** Positional per input item; recorded audio has no pronunciation variant. */
+  readonly phoneticScriptEntityIds: readonly (string | null)[];
+  readonly captionClipEntityIds: readonly (readonly string[])[];
+}
+interface CompiledSpeechAssetsEffect {
+  readonly result: SpeechAssetsEffectResult;
+  readonly replayed: boolean;
+  readonly update?: Uint8Array;
+  readonly rows: EntityRelationRows;
+}
 interface TrimClipInput {
   readonly clipEntityId: string;
   readonly sourceRange: SequenceRange<number>;
 }
 interface VoiceoverTakeResult {
   readonly voiceoverClipEntityId: string;
-  readonly voiceEntityId: string;
-  /** The pronunciation variant the Voice was rendered from. */
+  /** The rendered voiceover Audio entity. */
+  readonly voiceoverAudioEntityId: string;
+  /** The timbre identity it was synthesized with, when the take declared one. */
+  readonly voiceEntityId?: string;
+  /** The pronunciation variant the voiceover was rendered from. */
   readonly phoneticScriptEntityId: string;
   /** The base-text owner resolved from the PhoneticScript baseEntityIds. */
   readonly audioScriptEntityId: string;
@@ -516,6 +923,7 @@ type ClipEntityId = EntityId;
  * and committed only after validation succeeds.
  */
 declare class EntityTimelineEditor {
+  #private;
   private readonly idFactory;
   private state;
   constructor(initialRows: EntityRelationRows, idFactory?: EntityTimelineIdFactory);
@@ -533,6 +941,9 @@ declare class EntityTimelineEditor {
   replaceMediaClip(input: ReplaceMediaClipInput): void;
   setClipVolume(input: SetClipVolumeInput): void;
   setClipSpeed(input: SetClipSpeedInput): void;
+  /** Apply one typed Director speed effect as a single graph transaction. */
+  setVideoClipSpeeds(input: SetVideoClipSpeedEffectInput): void;
+  private setClipSpeedIntoDraft;
   trimClip(input: TrimClipInput): void;
   replaceSequentialClips(input: ReplaceSequentialClipsInput): readonly ClipEntityId[];
   deleteClip(input: DeleteClipInput): void;
@@ -553,9 +964,12 @@ declare class EntityTimelineEditor {
    * never the Caption entity or the AudioScript.
    */
   insertCaptionClip(input: InsertCaptionClipInput): ClipEntityId;
+  static compileCaptionAssetsEffect(base: LoroEntityDocument, envelope: CaptionAssetsEffectEnvelope): CompiledCaptionAssetsEffect;
+  static compileGeneratedVisualEffect(base: LoroEntityDocument, envelope: GeneratedVisualEffectEnvelope): CompiledGeneratedVisualEffect;
+  static compileSpeechAssetsEffect(base: LoroEntityDocument, envelope: SpeechAssetsEffectEnvelope): CompiledSpeechAssetsEffect;
   private insertPlacedClipIntoDraft;
   private ensureRoleTrack;
-  /** The existing pronunciation variant a Voice consumes; composition is required. */
+  /** The existing pronunciation variant a voiceover consumes; composition is required. */
   private requireComposedPhoneticScript;
   /** Preserve the factual synthesis input, regardless of persisted endpoint positions. */
   private ensurePhoneticRender;
@@ -581,6 +995,21 @@ declare class EntityTimelineEditor {
   private relinkRelation;
   private mintRelationId;
 }
+/** Freeze every state-dependent choice once in the sole FE tool-effect handler. */
+declare function prepareCaptionAssetsEffect(base: LoroEntityDocument, rawInput: ApplyCaptionAssetsInput): CaptionAssetsEffectEnvelope;
+/**
+ * Compile only a frozen envelope on its exact causal baseline. Collaborators
+ * receive the resulting Loro update, never the raw effect.
+ */
+declare function compileCaptionAssetsEffect(base: LoroEntityDocument, envelope: CaptionAssetsEffectEnvelope): CompiledCaptionAssetsEffect;
+/** Freeze the insertion position and lineage on one causal baseline. */
+declare function prepareGeneratedVisualEffect(base: LoroEntityDocument, rawInput: AddGeneratedVisualsInput): GeneratedVisualEffectEnvelope;
+declare function prepareContinueVideoEffect(base: LoroEntityDocument, input: ContinueVideoInput): GeneratedVisualEffectEnvelope;
+/** Compile once at the FE authority; retain the returned update bytes for retry and collaborators. */
+declare function compileGeneratedVisualEffect(base: LoroEntityDocument, envelope: GeneratedVisualEffectEnvelope): CompiledGeneratedVisualEffect;
+declare function prepareSpeechAssetsEffect(base: LoroEntityDocument, rawInput: SpeechAssetsEffectInput): SpeechAssetsEffectEnvelope;
+/** Compile once at the FE authority; retain the returned update bytes for retry and collaborators. */
+declare function compileSpeechAssetsEffect(base: LoroEntityDocument, envelope: SpeechAssetsEffectEnvelope): CompiledSpeechAssetsEffect;
 //#endregion
 //#region src/entity-editor/editor-resources.d.ts
 declare const roleOrder: {
@@ -595,32 +1024,29 @@ interface EditorFoundation {
   readonly timelineEntityId: string;
   readonly trackEntityIds: Readonly<Record<EditorTrackRole, string>>;
   /** Initial or current AudioScript content ID selected by the foundation. */
-  readonly audioScriptEntityId: string;
+  readonly audioScriptEntityId: string | null;
 }
 /**
  * MEngine editor policy, not a cardinality restriction on the general-purpose DSL.
  *
- * Media variants share one entity identity with their Asset: every
- * Image/Video/Audio/Voice Entity must carry its own external locator, every
- * external asset id has exactly one claimant, and no media variant may be
- * bound through a legacy `physical-asset` Relation. Dual-entity media graphs
- * are rejected, not migrated. Caption composes AudioScript text and may associate with a physical text Asset.
+ * Resources live on Asset entities and are reached through `from-asset`: no
+ * other entity carries a locator, one Asset claims each `(system, key)` pair,
+ * and media reaches at most one Asset. Media whose bytes are not named through
+ * that Relation is rejected rather than guessed at.
  */
 declare function assertCanonicalEditorResources(rows: EntityRelationRows): void;
 /**
  * Commit-transition policy shared by the editor, the HTTP commit boundary, the
  * host tool, and the entity stores. It compares the authoritative before and
- * after rows of one CAS commit and enforces the single-identity write rules
- * on the complete after state, with no exemption for historical graphs:
+ * after rows of one CAS commit and enforces the resource rules on the complete
+ * after state, with no exemption for historical graphs:
  *
- * 1. every Image/Video/Audio/Voice Entity carries its own Asset `external`
- *    identity;
- * 2. no `physical-asset` Relation may bind a media variant;
- * 3. a self-carried media identity is immutable — it cannot be rewritten to
- *    another asset id.
+ * 1. every media Entity reaches exactly one Asset through `from-asset`;
+ * 2. no entity other than an Asset carries a locator;
+ * 3. an Asset's locator is immutable — pointing it at other bytes would
+ *    silently rewrite every entity already made from it.
  *
- * Dual-entity media graphs are rejected instead of being migrated or merged
- * implicitly. Deleting media is explicit and allowed.
+ * Deleting media is explicit and allowed.
  */
 declare function assertMediaAssetWritePolicy(before: EntityRelationRows, after: EntityRelationRows): void;
 /** Add only missing editor structure; existing identities and owned settings are never replaced. */
@@ -629,19 +1055,27 @@ declare function ensureEditorFoundation(initial: EntityRelationRows, idFactory?:
 //#region src/entity-editor/media-asset-import.d.ts
 interface ImportedMediaAsset {
   readonly rows: EntityRelationRows;
-  /** The single media variant identity for this asset id; it is its own Asset. */
+  /** The media entity for this asset id. */
   readonly contentEntityId: string;
+  /** The Asset the media was made from; shared by every entity naming the same bytes. */
+  readonly assetEntityId: string;
+  /** The timbre identity of a synthesized voiceover; absent for recorded media. */
+  readonly voiceEntityId?: string;
+}
+interface ImportedCaptionAsset {
+  readonly rows: EntityRelationRows;
+  readonly assetEntityId: string;
 }
+/** Import only the fixed ASR artifact; Caption entities are authored separately. */
+declare function importCaptionAsset(initial: EntityRelationRows, fact: CaptionAssetFact, idFactory?: EntityTimelineIdFactory): ImportedCaptionAsset;
 /**
  * Import at the editor boundary, not at asset generation time. Existing
  * provenance is retained.
  *
- * A media variant is a logical facet of its Asset and shares one entity
- * identity: the import mints exactly one entity of the media kind that carries
- * the external locator itself, and deduplicates only against existing variants
- * that already carry the same `(system, key)`. Legacy dual-entity graphs
- * (`asset` row plus a `physical-asset` binding) are not reused and are
- * rejected by the canonical resource policy instead of being migrated.
+ * The bytes are named once, on an Asset entity, and the media entity reaches
+ * them through a `from-asset` Relation. Re-importing the same `(system, key)`
+ * reuses that Asset and the media already made from it, so one stored resource
+ * is never copied into several rows.
  */
 declare function importMediaAsset(initial: EntityRelationRows, fact: MediaAssetFact, idFactory?: EntityTimelineIdFactory): ImportedMediaAsset;
 //#endregion
@@ -670,164 +1104,12 @@ interface DocumentAudioScript {
 /** State exposing the current AudioScript content version attached to the project. */
 interface DocumentAudioScriptState {
   readonly rows: EntityRelationRows;
-  /** Current attachment; initialized projects point to a real script, including an empty one. */
+  /** Current attachment, or null until a script is transcribed or written. */
   readonly audioScriptEntityId: string | null;
 }
 /** Read only the attached version and preserve every segment; never aggregate other scripts. */
 declare function readDocumentAudioScript(state: DocumentAudioScriptState): DocumentAudioScript;
 //#endregion
-//#region src/entity-crdt/field-changes.d.ts
-/** List members are addressed by identity, never a transient array offset. */
-type FieldPath = readonly (string | {
-  elementId: string;
-})[];
-type FieldChange = {
-  op: 'set';
-  path: FieldPath;
-  value: JsonValue;
-} | {
-  op: 'unset';
-  path: FieldPath;
-} | {
-  op: 'text.splice';
-  path: FieldPath;
-  index: number;
-  deleteCount: number;
-  text: string;
-} | {
-  op: 'list.insert';
-  path: FieldPath;
-  value: JsonValue;
-  beforeElementId: string | null;
-} | {
-  op: 'list.move';
-  path: FieldPath;
-  elementId: string;
-  beforeElementId: string | null;
-} | {
-  op: 'list.remove';
-  path: FieldPath;
-  elementId: string;
-};
-declare function assertFieldChanges(changes: readonly FieldChange[]): void;
-/** Resolve against the sequential causal view; the numeric path never crosses the API boundary. */
-declare function resolveFieldPath(payload: JsonObject, path: FieldPath): (string | number)[];
-/** Detached plan evaluation. Native compilation replays the original operations, not this snapshot. */
-declare function applyFieldChanges(payload: JsonObject, changes: readonly FieldChange[]): JsonObject;
-//#endregion
-//#region src/entity-crdt/entity-document.d.ts
-declare const LORO_ENTITY_SCHEMA = "medeo.entities.loro.v1";
-interface EntityDocumentState {
-  readonly rows: EntityRelationRows;
-  readonly project: Readonly<Record<string, string>>;
-}
-type Command = {
-  type: 'create';
-  row: EntityRow;
-} | {
-  type: 'selection-baseline';
-  root: string;
-  fingerprint: string;
-} | {
-  type: 'order';
-  group: string;
-  roots: string[];
-  token: string;
-} | {
-  type: 'write';
-  root: string;
-  payload: JsonObject;
-  token: string;
-} | {
-  type: 'text';
-  root: string;
-  path: readonly (string | number)[];
-  start: number;
-  deleteCount: number;
-  text: string;
-  token: string;
-} | {
-  type: 'field';
-  root: string;
-  path: (string | number)[];
-  change: FieldChange;
-  token: string;
-} | {
-  type: 'relation-field';
-  root: string;
-  path: (string | number)[];
-  change: FieldChange;
-} | {
-  type: 'delete';
-  root: string;
-} | {
-  type: 'relation';
-  row: RelationRow;
-} | {
-  type: 'relation-fields';
-  root: string;
-  metadata: JsonObject;
-  trace: JsonObject;
-} | {
-  type: 'unlink';
-  root: string;
-} | {
-  type: 'attach';
-  slot: string;
-  entityId: string;
-};
-/** Plain domain objects assembled from native Loro state, never a second writable authority. */
-declare function readEntityDocument(doc: LoroDoc, allowSelectionConflicts?: boolean): EntityDocumentState;
-/** Native editing containers survive domain version changes and merge independently. */
-declare class LoroEntityDocument {
-  readonly doc: LoroDoc;
-  private readonly validate?;
-  private readonly undoManager;
-  constructor(doc: LoroDoc, validate?: ((state: EntityDocumentState) => void) | undefined);
-  /** Open a causal snapshot using the same Loro runtime as the compiler. */
-  static fromSnapshot(snapshot: Uint8Array, validate?: (state: EntityDocumentState) => void): LoroEntityDocument;
-  static create(rows: EntityRelationRows, project?: Readonly<Record<string, string>>, peerId?: PeerID): LoroEntityDocument;
-  snapshot(): EntityDocumentState;
-  relationsOf(entityId: string): readonly RelationRow[];
-  getVersion(id: string): EntityRow | undefined;
-  /** The callback and every domain validation execute on a causally complete fork first. */
-  transact(edit: (draft: LoroEntityDraft) => void): Uint8Array;
-  /** Import preserves native operation identities; projection errors never discard remote operations. */
-  import(update: Uint8Array): void;
-  canUndo(): boolean;
-  canRedo(): boolean;
-  undo(): boolean;
-  redo(): boolean;
-  private historyEdit;
-}
-declare class LoroEntityDraft {
-  private readonly doc;
-  readonly commands: Command[];
-  private readonly selectedRoots;
-  private readonly relationAliases;
-  constructor(doc: LoroDoc);
-  snapshot(): EntityDocumentState;
-  order(groupId: string, entityIds: readonly string[]): void;
-  /** Project the final scalar placement intents onto the existing native ordering containers. */
-  reconcileOrder(rows: EntityRelationRows): void;
-  create(row: EntityRow): void;
-  delete(entityId: string): void;
-  attach(slot: string, entityId: string): void;
-  link(row: RelationRow): void;
-  patchRelation(relationId: string, metadata: JsonObject, trace: JsonObject): void;
-  unlink(relationId: string): void;
-  private relationRoot;
-  update(entityId: string, fields: JsonObject): void;
-  declare(entityId: string, fields: JsonObject): void;
-  replaceOwned(entityId: string, payload: JsonObject): void;
-  editText(entityId: string, path: readonly (string | number)[], start: number, deleteCount: number, text: string): void;
-  /** Generic assembled-field edit compiled at the author's causal position. */
-  change(entityId: string, changes: readonly FieldChange[]): void;
-  changeRelation(relationId: string, changes: readonly FieldChange[]): void;
-  captureSelectionBaselines(): void;
-  private record;
-}
-//#endregion
 //#region src/entity-crdt/compile-rows.d.ts
 /** Lower a detached ordinary-object edit against its actual causal Loro baseline. */
 declare function compileEntityRows(snapshot: Uint8Array, rows: EntityRelationRows, validate?: (state: EntityDocumentState) => void): {
@@ -949,7 +1231,9 @@ type PushResultKind = 'ack' | 'duplicate' | 'rejected' | 'failed' | 'nothing_to_
  */
 interface PushResult {
   kind: PushResultKind;
-  /** Server-allocated sequence number; only present for `ack`. */
+  /** Server document sequence observed after a successful `ack` or `duplicate`. */
+  mengineUpdateSeq?: number | undefined;
+  /** @deprecated Ack-only sequence retained until consumers adopt `mengineUpdateSeq`. */
   updateSeq?: number | undefined;
   /** Whether the server held ops the local document lacked. See above. */
   collaborated: boolean;
@@ -1043,6 +1327,8 @@ declare class ManualSyncDoc {
   private readonly client;
   private readonly doc;
   private readonly adapter;
+  /** Whether this document's timeline is owned by the Entity graph. */
+  isEntityDocument(): boolean;
   readonly editor: SemanticEditor;
   /**
    * The version the server is known to hold. Starts empty (nothing confirmed)
@@ -1056,8 +1342,7 @@ declare class ManualSyncDoc {
    * Fetches the snapshot up front rather than starting empty and converging: the
    * agent's first act is to read the document, so there is no useful state before
    * the snapshot lands. This also fails fast and loudly on a document that does
-   * not exist, instead of `MengineDocSession.waitForContent()`'s behavior of
-   * waiting forever for content that will never arrive.
+   * not exist or whose first snapshot is incomplete or invalid.
    */
   static open(options: ManualSyncDocOptions): Promise<ManualSyncDoc>;
   /** Current document read model (authoritative shape). */
@@ -1073,8 +1358,8 @@ declare class ManualSyncDoc {
    * was passed to the constructor.
    */
   editorPeerId(): PeerID;
-  /** Current document projected to the legacy `VideoDraft` read shape. */
-  draft(): VideoDraft;
+  /** Current content projected into the compatible track and part read shape. */
+  content(): VideoDraftContent;
   /**
    * Replay a deterministic sandbox journal into this document.
    *
@@ -1091,9 +1376,8 @@ declare class ManualSyncDoc {
    *
    * This pair replaces the legacy integer-version comparison that
    * `DraftVersionDetector` used to tell the LLM "the draft was modified
-   * externally, reload before editing". Under mengine `meta.version` never
-   * changes, so that detector would go permanently silent; comparing version
-   * vectors restores the same capability.
+   * externally, reload before editing". Comparing Loro version vectors covers
+   * all collaborative edits without a business revision field in the document.
    *
    * Same capability, not a stronger one: like the legacy detector, this only
    * reports what changed between two moments the caller chose to sample.
@@ -1238,12 +1522,24 @@ declare class MedeoHttpDocStorage implements DocStorage {
    * tool-level ack wait) subscribe here.
    */
   subscribePushOutcome(callback: (outcome: PushOutcome) => void): () => void;
+  /** Observe live hints that require VV catch-up without replacing the SSE connection. */
+  subscribeResync(callback: () => void): () => void;
+  /** Authoritative HTTP reads and accepted pushes, never inferred from SSE bytes. */
+  subscribeServerVersion(callback: (version: Uint8Array) => void): () => void;
+  private reportServerVersion;
   deleteDoc(_docId: string): Promise<void>;
   subscribeDocUpdate(callback: (update: DocUpdate, origin: unknown) => void): () => void;
   private assertDocId;
   private emitUpdate;
 }
 //#endregion
+//#region src/session/document-undo-manager.d.ts
+/** Availability for this document's current editing session, not server revisions. */
+interface MengineUndoState {
+  readonly canUndo: boolean;
+  readonly canRedo: boolean;
+}
+//#endregion
 //#region src/session/types.d.ts
 /**
  * Local storage contract the runtime depends on. Aliased to the engine
@@ -1286,6 +1582,14 @@ interface WaitForServerAckOptions {
   /** Deadline in ms. Rejects with reason `timeout` when it elapses. */
   timeoutMs?: number;
 }
+/** Document-level confirmation is independent of local operation completion. */
+interface MengineDocSyncState {
+  /** Remote-only imports do not create a new local confirmation obligation. */
+  readonly confirmation: 'unknown' | 'pending' | 'confirmed';
+  /** Transport/activity phase. Idle does not imply confirmation; failure details
+   * remain available through push outcomes and confirmation wait errors. */
+  readonly phase: 'connecting' | 'idle' | 'syncing' | 'offline' | 'failed';
+}
 interface MengineDocSessionOptions {
   docId: string;
   client: MengineHttpClient;
@@ -1306,13 +1610,9 @@ interface MengineDocSessionOptions {
  * 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
+ * SemanticEditor writes through MirrorVideoDocumentAdapter directly, while
+ * DocumentUndoManager observes the same LoroDoc independently. Both mutation
+ * paths use the session's DocumentMutationGuard, closed before teardown.
  *
  * `DocManager` owns the `LoroDoc`: local edits committed on the adapter are
  * picked up via `subscribeLocalUpdates`, saved to local storage, then pushed to
@@ -1333,11 +1633,20 @@ declare class MengineDocSession {
   private readonly manager;
   private readonly events;
   private readonly disposables;
+  private readonly mutationGuard;
   private adapterValue;
   private editorValue;
+  private undoManagerValue;
   private started;
+  private startTask;
+  private destroyed;
+  private lifetime;
+  private hasConnected;
+  private initialVersionValue;
+  private localVersionValue;
+  private pushErrorValue;
   /**
-   * Latest server oplog version seen on a push outcome. Lets `waitForServerAck`
+   * Latest server oplog version seen on an authoritative HTTP response. Lets `waitForServerAck`
    * return without waiting when the server is already known to cover the local
    * doc (e.g. nothing was edited since the last confirmed push).
    */
@@ -1352,14 +1661,14 @@ declare class MengineDocSession {
    */
   subscribePushOutcome(callback: (outcome: PushOutcome) => void): () => void;
   /**
-   * Resolve once the server has durably accepted the local document state as of
+   * Resolve once the server has durably accepted the local commits as of
    * *now* — the capability an Agent tool needs to answer "did my edit land?"
    * before reporting success.
    *
    * Call it right after the editor ops whose durability matters. It snapshots the
-   * local doc's current version and resolves on the first push outcome whose
-   * `serverVV` covers that version, i.e. the server log is at least as advanced as
-   * the local doc was when this was called.
+   * latest local commit's version (or the loaded baseline before any edit) and
+   * resolves when an authoritative server version covers it. Remote-only
+   * imports do not extend this target, matching the displayed confirmation state.
    *
    * Version coverage, not byte identity, is the acceptance test — for two reasons:
    * the ops may reach the server inside a merged blob rather than as the exact
@@ -1395,29 +1704,58 @@ declare class MengineDocSession {
   get documentAdapter(): SemanticDocumentAdapter;
   /** Current document snapshot (read model). */
   snapshot(): VideoDocument;
+  /** Current-session undo/redo availability. Loading and closed sessions report false. */
+  getUndoState(): MengineUndoState;
+  /**
+   * Supplies current availability immediately, then coalesces stack changes in a
+   * microtask. Session teardown publishes empty availability synchronously.
+   */
+  subscribeUndoState(cb: (state: MengineUndoState) => void): () => void;
+  /**
+   * Undo a local edit immediately; server confirmation remains asynchronous.
+   * On a shared LWW field this writes its prior value, potentially overwriting a
+   * later remote edit to that same field. Returns false if no update is produced.
+   */
+  undo(options?: CommitOptions): boolean;
+  /**
+   * Restore the state visible before undo without rerunning external side effects.
+   * Returns false if no update is produced; durable confirmation is separate.
+   */
+  redo(options?: CommitOptions): boolean;
+  /**
+   * Combine existing semantic operations (e.g. trim a clip and adjust its volume)
+   * or repeated commits during one drag gesture into a single undo step. A gesture
+   * that only previews locally and commits once on release needs no group.
+   * Each commit is immediately visible locally and enters sync independently;
+   * a later failure does not roll it back.
+   * Always pair with endUndoGroup in a finally block. Conflicting remote imports
+   * can end/split the group early, and unrelated local edits would join it.
+   * Complete asynchronous asset preparation before opening the group.
+   */
+  beginUndoGroup(): void;
+  /** End a gesture, including one already split by a conflicting remote import. */
+  endUndoGroup(): void;
   /**
    * 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`.
+   * Returns after DocManager loads a local snapshot, or after the first remote
+   * sync when no local snapshot exists. A valid empty document is ready too.
+   * Cached documents can open before SSE connects; subsequent remote changes
+   * surface through `subscribe`.
    */
   start(): Promise<VideoDocument>;
+  private open;
+  getSyncState(): MengineDocSyncState;
+  private confirmationTarget;
+  /** Immediately supplies current state; unsubscribe when the host changes docs. */
+  subscribeSyncState(cb: (state: MengineDocSyncState) => void): () => void;
+  private emitSyncState;
   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;
+  /** Local absence needs a remote sync; empty business content does not. */
+  private waitForInitialLoad;
 }
 //#endregion
 //#region src/storage/memory-doc-storage.d.ts
@@ -1604,103 +1942,6 @@ type MakeEmptyPart = (durationMs: number) => {
  */
 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>;
-  /**
-   * Part ids of the gap fillers this solve minted.
-   *
-   * They exist only inside the solve: gap filling needs them so the clips after a
-   * gap land at the right absolute time, but they are not authoritative state and
-   * the read view does not carry them (see `fromVideoDocument`).
-   *
-   * Reported as ids rather than left for the caller to detect, because the caller
-   * *cannot* detect them. The obvious predicate — `origin_media_id === ''` — also
-   * matches an empty clip a writer placed on purpose (`batch_replace_video_clip_sequence`
-   * documents "Omit to create an empty clip placeholder"), and those are
-   * authoritative parts that must survive the projection. The mint callback is the
-   * only place that knows the difference.
-   *
-   * Note this deliberately excludes the fillers that gap filling *extended* rather
-   * than minted (`fillMainTrackTimeGaps` cases 1 and 2): those are authoritative
-   * empty clips already in `part_library`, and only their length is derived.
-   */
-  derivedFillerPartIds: Set<string>;
-}
-/**
- * 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';
-/** A lane's track kind: the `video_clip` main lane plus the three secondary lanes. */
-type LaneKind = SecondaryLane | 'video_clip';
-/**
- * The four lanes in top-to-bottom stack order — the order a `tracks` list holds
- * them in (see {@link laneRank}).
- *
- * Exported so a document can be seeded with all four lanes up front. That seed is
- * not cosmetic: {@link ensureLaneTrack} is find-then-mint over a `LoroMovableList`,
- * so two concurrent writers that each mint the same absent lane both keep their
- * row, and the merged document holds two tracks for one lane. For the main lane
- * that is fatal — `videoDocumentSchema` allows at most one `video_clip` track, so
- * the merged document stops being projectable at all, symmetrically on both
- * replicas. Pre-seeding every lane makes `ensureLaneTrack` always take its find
- * branch, which removes the race by construction rather than by detection.
- *
- * What closes the race is that a track with the lane's `parts_kind` EXISTS — the
- * lookup is by kind, not by id. So a seed is only safe if it covers every lane:
- * a partial seed leaves the uncovered lanes exactly as exposed as before.
- */
-declare const LANE_KINDS_IN_STACK_ORDER: readonly LaneKind[];
-/**
- * The conventional track id for a lane (`main_track`, `<kind>_track`). Shared by
- * the up-front seed and {@link ensureLaneTrack}'s lazy mint so a document's lane
- * ids do not depend on which of the two created the track.
- *
- * Ids are cosmetic to the merge itself — lane lookup goes by `parts_kind`, so
- * drifting them apart would not reopen the concurrent-mint race. They matter to
- * readers that address a lane by id (the FE editor's panes, fixtures), which is
- * why there is one convention rather than two.
- */
-declare function laneTrackId(kind: LaneKind): string;
-/**
- * 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
- * comes from {@link laneTrackId}, shared with the up-front seed.
- *
- * The mint branch is a concurrency hazard, not a convenience: see
- * {@link LANE_KINDS_IN_STACK_ORDER}. A document seeded with all four lanes never
- * reaches it.
- */
-declare function ensureLaneTrack(draft: VideoDocumentDraft, kind: LaneKind): 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.
@@ -1744,4 +1985,37 @@ declare function hostForAbsMs(ranges: MainClipRange[], absMs: number): MainClipR
  */
 declare function relativePositionForAbs(ranges: MainClipRange[], absMs: number): TrackItemTimePosition;
 //#endregion
-export { type Aggregation, type AssembledCaptionContent, type AssembledPhoneticScriptContent, type Attachment, type AudioMediaAssetFact, type BgmPart, type CaptionContentInput, type CaptionDisplayCue, type CaptionPart, type CaptionSegmentSelection, type CaptionStyle, type ClipEntityId, type ClipPlacement, type CommitOptions, DEFAULT_UNIT_TIME_MS, type DeleteBgmInput, type DeleteClipInput, type DeleteClipTreeInput, type DeleteVoiceoverInput, type DerivedItemPosition, type DocStorageLike, type DocVersionMark, type DocumentAudioScript, type DocumentAudioScriptState, ENTITY_TIMELINE_PROJECTION_SCHEMA_VERSION, type EditorFoundation, EntityDocumentState, type EntityGraphCommitOptions, EntityGraphHttpClient, type EntityGraphState, EntityTimelineEditor, type EntityTimelineIdFactory, EntityTimelineProjectionError, type EntityTimelineTrackRole, type FieldChange, type FieldPath, IMPLEMENTED_SEMANTIC_OP_KINDS, type ImageMediaAssetFact, type ImplementedSemanticOpKind, type ImportedMediaAsset, type InitialDocumentFacts, type InsertCaptionClipInput, type InsertClipInput, type InsertMediaClipInput, type InsertMediaClipsInput, type InsertPlacedClipInput, type JournalEntry, LANE_KINDS_IN_STACK_ORDER, LORO_ENTITY_SCHEMA, type LaneKind, type LinearClipSpeed, LoroEntityDocument, LoroEntityDraft, type MainClipRange, type MakeEmptyPart, ManualSyncDoc, type ManualSyncDocOptions, MedeoHttpDocStorage, type MedeoHttpDocStorageOptions, type MediaAssetFact, type MediaClipInsertion, MemoryDocStorage, MengineAckFailedError, type MengineAuditEntry, type MengineAuditResponse, MengineDocSession, type MengineDocSessionOptions, type MengineDocSessionUpdateEvent, type MengineDocumentVersion, type MengineEventStreamOptions, MengineHttpClient, type MengineHttpClientOptions, MengineHttpRequestError, MenginePushRejectedError, type MenginePushResponse, type MenginePushUpdateResponse, type MengineRejectedResponse, type MengineSnapshotResponse, type MengineSseUpdateEvent, type MengineSyncResponse, type MengineUpdateMeta, MirrorVideoDocumentAdapter, type MirrorVideoDocumentOptions, type MoveClipInput, type MoveClipsToStartsInput, type MoveSequentialClipsInput, type MoveVoiceoverInput, type OpActor, type PartAggregation, type PartIdFactory, type PartKind, type PartUnion, type PatchCaptionStyleInput, PlainMemoryAdapter, type PlainMemoryAdapterOptions, type PlannedSemanticOpKind, type PullFailureReason, type PullResult, type PushOutcome, type PushOutcomeKind, type PushResult, type PushResultKind, type ReplaceClipContentInput, type ReplaceMediaClipInput, type ReplaceSequentialClipsInput, type ReplacementMediaClipInput, type ResolvedEntityClipPlacement, type ResolvedEntityTimelineLayout, type ResolvedEntityTrack, SchemaValidator, ScriptCompositionError, type SemanticDocumentAdapter, SemanticEditor, type SemanticOpInput, type SemanticOpKind, type SemanticOpName, type SequentialClipAnchor, type SetBgmInput, type SetCaptionVisibilityInput, type SetClipPlacementInput, type SetClipSpeedInput, type SetClipVolumeInput, 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, type TrimClipInput, type UpdateClipInput, type UpdateClipMarkerInput, 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 VideoDraftPartUnion, type Timeline$1 as VideoDraftTimeline, type Track$1 as VideoDraftTrack, type TrackItem$1 as VideoDraftTrackItem, type VideoMediaAssetFact, type VisualMediaAssetFact, type VoiceMediaAssetFact, type VoiceoverCaptionFact, type VoiceoverTakeInput, type VoiceoverTakeResult, type WaitForServerAckOptions, applyEntityRows, applyEntityTimelineProjection, applyFieldChanges, arrangeMainTrackSeamlessly, assembleCaptionContent, assembleEntityContent, assemblePhoneticScriptContent, assembleScriptText, assertCanonicalEditorResources, assertEntityProjectionPreservesLegacy, assertFieldChanges, assertMediaAssetWritePolicy, assertValidVideoDocument, base64ToBytes, buildInitialVideoDocument, buildSpeechHostMap, bytesToBase64, cascadeAfterVideoClipChanges, compileEntityRows, createEditSandbox, createMirrorVideoDocument, createMirrorVideoDocumentAdapter, createPlainMemoryAdapter, decodeDocVersionMark, derivePositionFromAbs, effectiveVideoClipDurationMs, encodeDocVersionMark, ensureEditorFoundation, ensureLaneTrack, fillMainTrackTimeGaps, findComposedAudioScript, findLaneTrack, fromVideoDocument, generatePartId, getAt, hostForAbsMs, importMediaAsset, isEmptyVideoClip, isImplementedSemanticOpKind, isMap, laneTrackId, mainTrackRanges, migrateLegacyTimelineToEntities, partDurationMs, partUnionSchema, prepareCaptionContent, projectEntityTimeline, readDocumentAudioScript, readEntityDocument, readMainTrackItems, readMengineEventStream, readPart, readPartDurationMs, readVideoDocumentFromDraft, reassignSpeechesToVideoClipsByTime, recalculateTimelineDuration, relativePositionForAbs, replayJournal, resolveAllSpeechOverlaps, resolveEntityTimelineLayout, resolveFieldPath, resolveSpeechOverlapByShiftingVideos, safeDurationMs, index_d_exports as schemas, selectAudioScriptSegment, snapshotToPlain, solveVideoDocument, speedOf, syncAggregatedClipsTimePosition, toVideoDocument, validateVideoDocument, videoDocumentMirrorSchema, videoDocumentSchema, writeVideoDocumentToDraft };
+//#region src/entity-crdt/audio-script-assets.d.ts
+/** A resource is a snapshot of text; the native Loro text remains the editing authority. */
+declare function audioScriptAssetContent(payload: JsonObject): JsonObject;
+declare function audioScriptAssetHash(payload: JsonObject): string;
+/**
+ * The Asset a script was written out to. It is a snapshot the script owns, so
+ * it is reached by `to-asset` — not `from-asset`, which would say the script
+ * was produced from bytes it cannot change.
+ */
+declare function audioScriptAssetOf(rows: EntityRelationRows, entityId: string): EntityRow | undefined;
+/**
+ * The Asset a script was made from — a transcript it does not own. A script
+ * that has one never writes a snapshot of its own: the bytes it would describe
+ * are already named, and rewriting them would contradict their source.
+ */
+declare function scriptSourceAssetOf(rows: EntityRelationRows, entityId: string): EntityRow | undefined;
+/** Internal fingerprint prevents a resource from silently describing an older text revision. */
+declare function audioScriptAssetFields(payload: JsonObject): JsonObject;
+/**
+ * What a PhoneticScript hands to synthesis: the base AudioScript's text as the
+ * variant pronounces it, plus the variant's own phoneme and prosody control.
+ *
+ * The variant's content is written by a model — deciding how words are said is
+ * text work, not a mechanical copy — but the bytes a synthesizer reads have to
+ * leave the entity graph to reach it, because synthesis does not handle
+ * entities. Writing this resource down is that crossing, and it is why speech
+ * can only come from a PhoneticScript.
+ */
+declare function phoneticScriptAssetContent(rows: EntityRelationRows, entityId: string): JsonObject;
+declare function phoneticScriptAssetHash(rows: EntityRelationRows, entityId: string): string;
+/** The Asset a PhoneticScript was written out to, read from the graph. */
+declare function phoneticScriptAssetOf(rows: EntityRelationRows, entityId: string): EntityRow | undefined;
+//#endregion
+export { type AddGeneratedVisualsInput, type AddSpeechAssetsInput, type Aggregation, type ApplyCaptionAssetsInput, type ApplyCaptionAssetsResult, type AsrCaptionSegment, type AssembledCaptionContent, type AssembledPhoneticScriptContent, type Attachment, type AudioMediaAssetFact, type BgmPart, type CaptionAssetFact, type CaptionAssetsEffectEnvelope, type CaptionContentInput, type CaptionDisplayCue, type CaptionPart, type CaptionSegmentSelection, type CaptionStyle, type ClipEntityId, type ClipPlacement, type CommitOptions, type CompiledCaptionAssetsEffect, type CompiledGeneratedVisualEffect, type CompiledSpeechAssetsEffect, type ContinueVideoInput, DEFAULT_UNIT_TIME_MS, type DeleteBgmInput, type DeleteClipInput, type DeleteClipTreeInput, type DeleteVoiceoverInput, type DerivedItemPosition, type DocStorageLike, type DocVersionMark, type DocumentAudioScript, type DocumentAudioScriptState, type EditorFoundation, EntityDocumentState, type EntityGraphCommitOptions, EntityGraphHttpClient, type EntityGraphState, EntityTimelineEditor, type EntityTimelineIdFactory, type EntityTimelineProjectionDocument, EntityTimelineProjectionError, type EntityTimelineTrackRole, type FieldChange, type FieldPath, type GeneratedSpeechCaptionFact, type GeneratedSpeechFact, type GeneratedSpeechSourceFact, type GeneratedVisualClipFact, type GeneratedVisualEffectEnvelope, type GeneratedVisualEffectResult, IMPLEMENTED_SEMANTIC_OP_KINDS, type ImageMediaAssetFact, type ImplementedSemanticOpKind, type ImportedCaptionAsset, type ImportedMediaAsset, type InsertCaptionClipInput, type InsertClipInput, type InsertMediaClipInput, type InsertMediaClipsInput, type InsertPlacedClipInput, type JournalEntry, LANE_KINDS_IN_STACK_ORDER, LORO_ENTITY_SCHEMA, type LaneKind, type LinearClipSpeed, LoroEntityDocument, LoroEntityDraft, type MainClipRange, type MakeEmptyPart, ManualSyncDoc, type ManualSyncDocOptions, MedeoHttpDocStorage, type MedeoHttpDocStorageOptions, type MediaAssetFact, type MediaClipInsertion, MemoryDocStorage, MengineAckFailedError, type MengineAuditEntry, type MengineAuditResponse, MengineDocSession, type MengineDocSessionOptions, type MengineDocSessionUpdateEvent, type MengineDocSyncState, type MengineDocumentVersion, type MengineEventStreamOptions, MengineHttpClient, type MengineHttpClientOptions, MengineHttpRequestError, MenginePushRejectedError, type MenginePushResponse, type MenginePushUpdateResponse, type MengineRejectedResponse, type MengineSnapshotResponse, type MengineSseUpdateEvent, type MengineSyncResponse, type MengineUndoState, type MengineUpdateMeta, MirrorVideoDocumentAdapter, type MirrorVideoDocumentOptions, type MoveClipInput, type MoveClipsToStartsInput, type MoveSequentialClipsInput, type MoveVoiceoverInput, type OpActor, type PartAggregation, type PartIdFactory, type PartKind, type PartUnion, type PatchCaptionStyleInput, PlainMemoryAdapter, type PlainMemoryAdapterOptions, type PlannedSemanticOpKind, type PullFailureReason, type PullResult, type PushOutcome, type PushOutcomeKind, type PushResult, type PushResultKind, type ReplaceClipContentInput, type ReplaceMediaClipInput, type ReplaceSequentialClipsInput, type ReplaceVoiceSpeechAssetsInput, type ReplacementMediaClipInput, type ResolvedAsrSpeechSegment, type ResolvedEntityClipPlacement, type ResolvedEntityTimelineLayout, type ResolvedEntityTrack, type ResolvedSpeechScriptSegment, SchemaValidator, ScriptCompositionError, type SemanticDocumentAdapter, SemanticEditor, type SemanticOpInput, type SemanticOpKind, type SemanticOpName, type SequentialClipAnchor, type SetBgmInput, type SetCaptionVisibilityInput, type SetClipPlacementInput, type SetClipSpeedInput, type SetClipVolumeInput, type SetVideoClipSpeedEffectInput, type SnapshotReadable, type SolvedVideoDocument, type SpeechAssetsEffectEnvelope, type SpeechAssetsEffectInput, type SpeechAssetsEffectResult, type SpeechHostMap, type SpeechOriginAssetSystem, 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, type TrimClipInput, type UpdateClipInput, type UpdateClipMarkerInput, ValidationError, type VideoClipPart, type VideoClipSpeedMode, type VideoDocument, type VideoDocumentDraft, type VideoDocumentMirrorSchema, VideoDocumentValidationError, type VideoDocumentValidationIssue, type VideoDocumentValidationIssueCode, type VideoDraft, type CaptionPart$1 as VideoDraftCaptionPart, type VideoDraftContent, type VideoDraftPartUnion, type Timeline$1 as VideoDraftTimeline, type Track$1 as VideoDraftTrack, type TrackItem$1 as VideoDraftTrackItem, type VideoMediaAssetFact, type VisualMediaAssetFact, type VoiceoverCaptionFact, type VoiceoverMediaAssetFact, type VoiceoverTakeInput, type VoiceoverTakeResult, type WaitForServerAckOptions, applyEntityRows, applyFieldChanges, arrangeMainTrackSeamlessly, assembleCaptionContent, assembleEntityContent, assemblePhoneticScriptContent, assembleScriptText, assertCanonicalEditorResources, assertEntityProjectionPreservesLegacy, assertFieldChanges, assertMediaAssetWritePolicy, assertValidVideoDocument, audioScriptAssetContent, audioScriptAssetFields, audioScriptAssetHash, audioScriptAssetOf, base64ToBytes, buildInitialVideoDocument, buildSpeechHostMap, bytesToBase64, cascadeAfterVideoClipChanges, compileCaptionAssetsEffect, compileEntityRows, compileGeneratedVisualEffect, compileSpeechAssetsEffect, createEditSandbox, createMirrorVideoDocument, createMirrorVideoDocumentAdapter, createPlainMemoryAdapter, decodeDocVersionMark, derivePositionFromAbs, effectiveVideoClipDurationMs, encodeDocVersionMark, ensureEditorFoundation, ensureLaneTrack, fillMainTrackTimeGaps, findComposedAudioScript, findLaneTrack, fromVideoDocument, generatePartId, getAt, hostForAbsMs, importCaptionAsset, importMediaAsset, isEmptyVideoClip, isImplementedSemanticOpKind, isMap, laneTrackId, mainTrackRanges, migrateLegacyTimelineToEntities, partDurationMs, partUnionSchema, phoneticScriptAssetContent, phoneticScriptAssetHash, phoneticScriptAssetOf, prepareCaptionAssetsEffect, prepareCaptionContent, prepareContinueVideoEffect, prepareGeneratedVisualEffect, prepareSpeechAssetsEffect, projectEntityTimeline, readDocumentAudioScript, readEntityDocument, readMainTrackItems, readMengineEventStream, readPart, readPartDurationMs, readVideoDocumentFromDraft, reassignSpeechesToVideoClipsByTime, recalculateTimelineDuration, relativePositionForAbs, replayJournal, resolveAllSpeechOverlaps, resolveEntityTimelineLayout, resolveFieldPath, resolveSpeechOverlapByShiftingVideos, safeDurationMs, index_d_exports as schemas, scriptSourceAssetOf, selectAudioScriptSegment, snapshotToPlain, solveVideoDocument, speedOf, syncAggregatedClipsTimePosition, toVideoDocument, validateVideoDocument, videoDocumentMirrorSchema, videoDocumentSchema };