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

package/dist/index.d.ts

@@ -1,6 +1,7 @@
-import { $ as VideoDraft, A as assertValidVideoDocument, B as CaptionPart, C as index_d_exports, D as VideoDocumentMirrorSchema, E as VideoDocumentDraft, F as buildSpeechHostMap, G as Timeline, H as PartKind, I as derivePositionFromAbs, J as TrackItemTimePosition, K as Track, L as fromVideoDocument, M as buildInitialVideoDocument, N as DerivedItemPosition, O as videoDocumentMirrorSchema, P as SpeechHostMap, Q as VideoDocumentValidationIssueCode, R as toVideoDocument, S as ValidationError, T as TrackItemDraft, U as PartUnion, V as DEFAULT_UNIT_TIME_MS, W as SpeechPart, X as VideoDocument, Y as VideoClipPart, Z as VideoDocumentValidationIssue, _ as PlannedSemanticOpKind, a as MirrorVideoDocumentOptions, at as PartAggregation, b as SchemaValidator, c as CommitOptions, ct as Track$1, d as SemanticEditor, et as VideoDraftContent, f as SemanticOpInput, g as ImplementedSemanticOpKind, h as IMPLEMENTED_SEMANTIC_OP_KINDS, i as MirrorVideoDocumentAdapter, it as CaptionStyle, j as validateVideoDocument, k as VideoDocumentValidationError, l as OpActor, lt as TrackItem$1, m as TransactAudit, n as videoDocumentSchema, nt as Attachment, o as createMirrorVideoDocument, ot as SpeedShift, p as SemanticOpName, q as TrackItem, r as readVideoDocumentFromDraft, rt as CaptionPart$1, s as createMirrorVideoDocumentAdapter, st as Timeline$1, t as partUnionSchema, tt as VideoDraftPartUnion, u as SemanticDocumentAdapter, v as SemanticOpKind, w as TrackDraft, x as SnapshotReadable, y as isImplementedSemanticOpKind, z as BgmPart } from "./index-CnZ9l3rb.js";
+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 { LoroDoc, PeerID } from "loro-crdt";
-import { DocState, LocalSaveState } from "@mengine/sync";
+import { DocState } from "@mengine/sync";
 import { BaseDocStorage, Connection, DocDiff, DocPushReceipt, DocSnapshotRecord, DocStorage, DocStorageOptions, DocUpdate, DocUpdateRecord } from "@mengine/storage";
 
 //#region src/client/base64.d.ts
@@ -133,6 +134,7 @@ 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
@@ -176,33 +178,685 @@ interface MengineEventStreamOptions {
 }
 declare function readMengineEventStream(options: MengineEventStreamOptions): Promise<void>;
 //#endregion
-//#region src/editor/id-gen.d.ts
+//#region ../medeo-dsl/src/composition.d.ts
+type ScriptCompositionIssueCode = 'field_conflict' | 'composition_cycle' | 'invalid_bases' | 'composition_missing' | 'composition_ambiguous' | 'composition_dangling' | 'unknown_segment' | 'empty_selection' | 'invalid_script' | 'invalid_selection';
+/** Assembly fails explicitly when declared bases cannot provide valid, unambiguous content. */
+declare class ScriptCompositionError extends Error {
+  readonly code: ScriptCompositionIssueCode;
+  readonly entityId: EntityId;
+  constructor(code: ScriptCompositionIssueCode, entityId: EntityId, message: string);
+}
+interface AssembledCaptionContent {
+  readonly caption: EntityRow<'caption'>;
+  readonly audioScript: EntityRow<'audio-script'>;
+  /** Selected AudioScript segments in Caption selection order. */
+  readonly segments: readonly ScriptTextSegment[];
+  /** Complete display text: the selected segments' text joined in order. */
+  readonly text: string;
+}
+interface AssembledPhoneticScriptContent {
+  readonly phoneticScript: EntityRow<'phonetic-script'>;
+  readonly audioScript: EntityRow<'audio-script'>;
+  /** All AudioScript segments in script order; the pronunciation variant never reorders text. */
+  readonly segments: readonly ScriptTextSegment[];
+  /** Complete base text owned by the AudioScript. */
+  readonly text: string;
+}
+/** Validate all base providers before applying explicit own fields; ordering cannot resolve ambiguity. */
+declare function assembleEntityContent(rows: EntityRelationRows, entityId: EntityId): EntityRow;
+/** Find the actual AudioScript text owner through direct variant bases. */
+declare function findComposedAudioScript(rows: EntityRelationRows, variantEntityId: EntityId, variantKind: 'caption' | 'phonetic-script'): EntityRow<'audio-script'>;
+/** Join the whole AudioScript text in segment order. */
+declare function assembleScriptText(script: EntityRow<'audio-script'>): string;
+/** Assemble selected text after base-field validation and explicit variant overrides. */
+declare function assembleCaptionContent(rows: EntityRelationRows, captionEntityId: EntityId): AssembledCaptionContent;
+/**
+ * Assemble the complete Phonetic Script content for TTS: the composed
+ * AudioScript's base text plus the variant's own phoneme and prosody fields.
+ */
+declare function assemblePhoneticScriptContent(rows: EntityRelationRows, phoneticScriptEntityId: EntityId): AssembledPhoneticScriptContent;
+/** Select source text without creating another authoritative text field. */
+declare function selectAudioScriptSegment(script: EntityRow<'audio-script'>, selection: CaptionSegmentSelection): ScriptTextSegment;
+//#endregion
+//#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;
+  readonly revision: number;
+  readonly loroSnapshot: string;
+  readonly rows: EntityRelationRows;
+}
+interface EntityGraphCommitOptions {
+  /** Server version vector proving the explicit legacy-to-Entity migration baseline. */
+  readonly migrationBaseVv?: string;
+}
+/** Browser-safe authenticated Loro client for a document's Entity graph. */
+declare class EntityGraphHttpClient {
+  private readonly options;
+  private readonly transport;
+  private readonly endpoint;
+  constructor(options: MengineHttpClientOptions);
+  fetchState(): Promise<EntityGraphState>;
+  /**
+   * Compile edits against the original causal snapshot and publish native Loro operations.
+   *
+   * Deletion intent is derived from baseline IDs omitted from `nextRows`, so a
+   * transient create-then-remove never becomes a request to delete unknown
+   * persisted data.
+   */
+  commit(baseState: Pick<EntityGraphState, 'revision' | 'rows' | 'loroSnapshot'>, nextRows: EntityRelationRows, options?: EntityGraphCommitOptions): Promise<EntityGraphState>;
+  /** Send the same prepared bytes on retry; never recompile an unconfirmed edit. */
+  commitUpdate(update: string): Promise<EntityGraphState>;
+  private request;
+}
+//#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;
+interface ImageMediaAssetFact {
+  readonly assetId: string;
+  readonly kind: 'image';
+  readonly storageKey?: string;
+}
+interface VideoMediaAssetFact {
+  readonly assetId: string;
+  readonly kind: 'video';
+  readonly durationMs: number;
+  readonly storageKey?: string;
+}
+interface AudioMediaAssetFact {
+  readonly assetId: string;
+  readonly kind: 'audio';
+  readonly durationMs: number;
+  readonly storageKey: 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;
+  /** Present for synthesized voice, 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 ClipPlacement = {
+  readonly kind: 'sequential';
+  readonly order: number;
+} | {
+  readonly kind: 'absolute';
+  readonly targetRange: SequenceRange<number>;
+} | {
+  readonly kind: 'anchored';
+  readonly hostClipEntityId: string;
+  readonly anchorOffset: 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;
+}
+interface SetClipPlacementInput {
+  readonly clipEntityId: string;
+  readonly placement: ClipPlacement;
+}
+type SequentialClipAnchor = {
+  readonly position: 'before' | 'after';
+  readonly clipEntityId: string;
+} | {
+  readonly position: 'trackStart';
+};
+interface MoveSequentialClipsInput {
+  readonly clipEntityIds: readonly string[];
+  readonly anchor: SequentialClipAnchor;
+  readonly onAnchored: 'follow' | 'keepAbsolute';
+}
+interface MoveClipsToStartsInput {
+  readonly moves: readonly {
+    readonly clipEntityId: string;
+    readonly newStartMs: number;
+  }[];
+  /** Absolute-time drags preserve every voiceover's current visible landing. */
+  readonly onAnchored: 'keepAbsolute';
+}
+interface DeleteClipTreeInput {
+  readonly clipEntityIds: readonly string[];
+  readonly onAnchored: 'cascade' | 'detach';
+}
+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. */
+  readonly baseEntityIds: readonly string[];
+  /** Ordered selection of AudioScript segments; caption text is never passed inline. */
+  readonly selection: CaptionSegmentSelection;
+  readonly startMs: number;
+  readonly durationMs: number;
+  readonly style?: CaptionStyleFields;
+}
+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 phoneticScriptEntityId: string;
+  readonly volume: number;
+  readonly captions: readonly VoiceoverCaptionFact[];
+} & ({
+  readonly placement: ClipPlacement;
+  readonly hostClipEntityId?: never;
+  readonly anchorOffset?: never;
+} | {
+  readonly placement?: never;
+  readonly hostClipEntityId: string;
+  readonly anchorOffset: number;
+});
+type VisualMediaAssetFact = ImageMediaAssetFact | VideoMediaAssetFact;
+interface InsertMediaClipInput {
+  readonly timelineEntityId: string;
+  readonly clipEntityId?: string;
+  readonly media: VisualMediaAssetFact;
+  /** Source/display window in whole milliseconds. Images use this as their finite display span. */
+  readonly sourceRange: SequenceRange<number>;
+  readonly placement: ClipPlacement;
+  readonly volume?: number;
+}
+interface ReplaceMediaClipInput {
+  readonly clipEntityId: string;
+  readonly media: VisualMediaAssetFact;
+  readonly sourceRange: SequenceRange<number>;
+}
+interface ReplacementMediaClipInput {
+  readonly clipEntityId?: string;
+  readonly media: VisualMediaAssetFact;
+  readonly sourceRange: SequenceRange<number>;
+  readonly volume?: number;
+}
+type MediaClipInsertion = {
+  readonly kind: 'before';
+  readonly clipEntityId: string;
+} | {
+  readonly kind: 'after';
+  readonly clipEntityId: string;
+} | {
+  readonly kind: 'firstStart';
+  readonly startMs: number;
+};
+interface InsertMediaClipsInput {
+  readonly timelineEntityId: string;
+  readonly clips: readonly ReplacementMediaClipInput[];
+  /** One placement decision for the whole input-ordered block. */
+  readonly insertion: MediaClipInsertion;
+}
+interface ReplaceSequentialClipsInput {
+  readonly timelineEntityId: string;
+  readonly oldClipEntityIds: readonly string[];
+  readonly newClips: readonly ReplacementMediaClipInput[];
+  readonly onAnchored: 'remap' | 'cascade';
+}
+interface SetClipVolumeInput {
+  readonly clipEntityId: string;
+  /** Playback gain in decibels. */
+  readonly volume: number;
+}
+interface LinearClipSpeed {
+  readonly kind: 'linear';
+  readonly rate: number;
+  readonly mode?: string;
+}
+interface SetClipSpeedInput {
+  readonly clipEntityId: string;
+  readonly timeRemapping: LinearClipSpeed | null;
+}
+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. */
+  readonly phoneticScriptEntityId: string;
+  /** The base-text owner resolved from the PhoneticScript baseEntityIds. */
+  readonly audioScriptEntityId: string;
+  readonly captionClipEntityIds: readonly string[];
+}
+interface MoveVoiceoverInput {
+  readonly voiceoverClipEntityId: string;
+  /** Absolute requested timeline start; MEngine resolves and persists the host relation. */
+  readonly newStartMs: number;
+}
+interface DeleteVoiceoverInput {
+  readonly voiceoverClipEntityIds: readonly string[];
+}
+interface SetBgmInput {
+  readonly timelineEntityId: string;
+  readonly bgmClipEntityId: string;
+  readonly media: AudioMediaAssetFact;
+  readonly volume: number;
+}
+interface DeleteBgmInput {
+  readonly timelineEntityId: string;
+}
+interface SetCaptionVisibilityInput {
+  readonly timelineEntityId: string;
+  readonly hidden: boolean;
+}
+interface PatchCaptionStyleInput {
+  readonly timelineEntityId: string;
+  readonly style: CaptionStyleFields;
+}
+interface InsertCaptionClipInput {
+  readonly timelineEntityId: string;
+  /** Existing generation identity for newly materialized Caption content, distinct from its Clip. */
+  readonly captionEntityId?: string;
+  /** Stable placed caption identity, distinct from the Caption content identity. */
+  readonly captionClipEntityId?: string;
+  /** Existing bases composed by this variant; includes an AudioScript text owner. */
+  readonly baseEntityIds: readonly string[];
+  /** Ordered selection of the AudioScript segments this Caption displays. */
+  readonly selection: CaptionSegmentSelection;
+  /** Intrinsic cue length of the Caption entity itself; display comes from the placement. */
+  readonly durationMs: number;
+  readonly style?: CaptionStyleFields;
+  readonly placement: ClipPlacement;
+}
+interface InsertClipInput {
+  readonly trackEntityId: string;
+  /** Existing Sequence media Entity id. Asset ids and URLs are not content ids. */
+  readonly contentEntityId: string;
+  readonly sourceRange: SequenceRange<number>;
+  readonly duration: SequenceDuration<number>;
+  readonly targetRange?: SequenceRange<number>;
+  readonly clipPayload?: JsonObject;
+}
+interface 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 MoveClipInput {
+  readonly clipEntityId: string;
+  readonly trackEntityId: string;
+}
+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 DeleteClipInput {
+  readonly clipEntityId: string;
+}
+interface UpdateClipInput {
+  readonly clipEntityId: string;
+  /** Complete replacement for the Clip-owned payload. */
+  readonly payload: JsonObject;
+}
+type ClipEntityId = EntityId;
+//#endregion
+//#region src/entity-editor/entity-timeline-editor.d.ts
+/**
+ * Graph-native timeline authoring over authoritative Medeo Entity and Relation rows.
+ *
+ * Each mutation is applied to a detached graph, validated as a complete DSL set,
+ * and committed only after validation succeeds.
+ */
+declare class EntityTimelineEditor {
+  private readonly idFactory;
+  private state;
+  constructor(initialRows: EntityRelationRows, idFactory?: EntityTimelineIdFactory);
+  rows(): EntityRelationRows;
+  insertClip(input: InsertClipInput): ClipEntityId;
+  insertPlacedClip(input: InsertPlacedClipInput): ClipEntityId;
+  updateClipMarker(input: UpdateClipMarkerInput): void;
+  setClipPlacement(input: SetClipPlacementInput): void;
+  moveSequentialClips(input: MoveSequentialClipsInput): void;
+  moveClipsToStarts(input: MoveClipsToStartsInput): 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;
+  deleteVoiceover(input: DeleteVoiceoverInput): void;
+  setBgm(input: SetBgmInput): ClipEntityId;
+  deleteBgm(input: DeleteBgmInput): void;
+  setCaptionVisibility(input: SetCaptionVisibilityInput): void;
+  patchCaptionStyle(input: PatchCaptionStyleInput): void;
+  /**
+   * Place a Caption as a composed variant of an existing AudioScript: the
+   * entity stores baseEntityIds, selection, optional style, and inherent cue-bounded
+   * Sequence. This helper does not copy base text. The Clip and its display Marker describe this use;
+   * moving or stretching the returned Clip later changes the Clip/Marker,
+   * never the Caption entity or the AudioScript.
+   */
+  insertCaptionClip(input: InsertCaptionClipInput): ClipEntityId;
+  private insertPlacedClipIntoDraft;
+  private ensureRoleTrack;
+  /** The existing pronunciation variant a Voice consumes; composition is required. */
+  private requireComposedPhoneticScript;
+  /** Preserve the factual synthesis input, regardless of persisted endpoint positions. */
+  private ensurePhoneticRender;
+  private reconcileVoiceoverCaptions;
+  private ensureRoleTrackForClip;
+  private replaceCaptionAlignment;
+  /**
+   * Remove one placed Caption use. The composed AudioScript outlives the
+   * caption: it may anchor further captions and remains the text owner.
+   */
+  private removeCaptionClipGraph;
+  private replaceAnchorHost;
+  /** Rebuild the legacy edit baseline from current visual order before a high-level cascade. */
+  private normalizeMainSequential;
+  private resolveOneVoiceoverOverlap;
+  private applyClipPlacement;
+  private reanchorAtAbsolute;
+  private removeAnchoredDescendants;
+  private removeClipGraph;
+  private transact;
+  private mintEntityId;
+  private createRelation;
+  private relinkRelation;
+  private mintRelationId;
+}
+//#endregion
+//#region src/entity-editor/editor-resources.d.ts
+declare const roleOrder: {
+  readonly caption: 0;
+  readonly video_clip: 1;
+  readonly speech: 2;
+  readonly bgm: 3;
+};
+type EditorTrackRole = keyof typeof roleOrder;
+interface EditorFoundation {
+  readonly rows: EntityRelationRows;
+  readonly timelineEntityId: string;
+  readonly trackEntityIds: Readonly<Record<EditorTrackRole, string>>;
+  /** Initial or current AudioScript content ID selected by the foundation. */
+  readonly audioScriptEntityId: string;
+}
 /**
- * Part-id generation, aligned with the online ecosystem.
+ * MEngine editor policy, not a cardinality restriction on the general-purpose DSL.
  *
- * The authoritative online producers — agent-harness (`@harness/shared`
- * `genObjId`) and director.v2 (`common/obj_id.py` `gen_obj_id`) — both mint part
- * ids as `` `${prefix}_${ulid()}` ``, and real captured drafts use exactly that
- * shape (`clip_…` / `spe_…` / `cap_…` / `bgm_…`, each a 26-char ULID). The engine
- * previously emitted `vc_<base36 timestamp><6 random>`, a different prefix AND a
- * different encoding — the sole cross-repo id divergence. This module removes it
- * by emitting the same `<prefix>_<ULID>` bytes.
+ * 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.
+ */
+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:
+ *
+ * 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.
  *
- * The ULID is generated inline (Crockford Base32, 48-bit time + 80-bit random)
- * rather than pulling the `ulid` npm package: the randomness class matches the
- * old generator (both `Math.random`-based) and it keeps `@mengine/medeo-client`
- * dependency-free for a purely mechanical id string. Part ids only need to be
- * unique and lexicographically time-sortable, which this satisfies.
+ * Dual-entity media graphs are rejected instead of being migrated or merged
+ * implicitly. 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. */
+declare function ensureEditorFoundation(initial: EntityRelationRows, idFactory?: EntityTimelineIdFactory, timelinePayload?: EntityRow['payload'], selectedAudioScriptEntityId?: string | null): EditorFoundation;
+//#endregion
+//#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. */
+  readonly contentEntityId: string;
+}
 /**
- * Online part-id semantic prefixes. `clip` (video clip) is the only value the
- * engine currently mints (see `addVideoClips`); the rest are declared so the
- * type documents the shared vocabulary and guards against reintroducing the old
- * `vc`/`sp`/`cp`/`bg` names. Speech/caption/bgm ids arrive pre-minted in op
- * payloads, so the engine never generates them itself.
+ * 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.
  */
-type PartIdPrefix = 'clip' | 'spe' | 'cap' | 'bgm' | 'ti';
-declare function generatePartId(prefix: PartIdPrefix): string;
+declare function importMediaAsset(initial: EntityRelationRows, fact: MediaAssetFact, idFactory?: EntityTimelineIdFactory): ImportedMediaAsset;
+//#endregion
+//#region src/entity-editor/legacy-entity-migration.d.ts
+/** One-time import only. Ordinary editor operations must never reverse-diff a legacy document. */
+declare function migrateLegacyTimelineToEntities(legacy: VideoDocument, assetFacts: readonly MediaAssetFact[], initial?: EntityRelationRows, idFactory?: EntityTimelineIdFactory): EntityRelationRows;
+/** Server gate: a cutover may change representation, never the existing render facts. */
+declare function assertEntityProjectionPreservesLegacy(legacy: VideoDocument, projection: VideoDocument, rows: EntityRelationRows): void;
+//#endregion
+//#region src/entity-editor/caption-content.d.ts
+interface CaptionContentInput {
+  readonly contentEntityId: string;
+  readonly audioScriptEntityId: string;
+  readonly text: string;
+  readonly selection?: CaptionSegmentSelection;
+  readonly durationMs: number;
+}
+/** Author Caption content from semantic intent; callers never reconcile variant bases or assembled fields. */
+declare function prepareCaptionContent(rows: EntityRelationRows, input: CaptionContentInput): EntityRow<'caption'>;
+//#endregion
+//#region src/entity-editor/document-audio-script.d.ts
+interface DocumentAudioScript {
+  readonly entityId: string;
+  readonly segments: readonly (ScriptTextSegment & Readonly<Record<string, unknown>>)[];
+}
+/** 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. */
+  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): {
+  update: Uint8Array;
+  state: EntityDocumentState;
+};
+/** Compile an edit on an existing peer, retaining its native local undo history. */
+declare function applyEntityRows(editor: LoroEntityDocument, rows: EntityRelationRows): {
+  update: Uint8Array;
+  state: EntityDocumentState;
+};
+//#endregion
+//#region src/editor/journal.d.ts
+/**
+ * Wire a plain-memory adapter + editor that share a recording id factory, so
+ * every mutating transact lands in `journal` with ordered `generated_ids`.
+ */
+declare function createEditSandbox(document: VideoDocument, options?: PlainMemoryAdapterOptions): {
+  adapter: PlainMemoryAdapter;
+  editor: SemanticEditor;
+  journal: readonly JournalEntry[];
+};
+/**
+ * Re-drive `doc` from a recorded journal, forcing each entry's `generated_ids`
+ * through a queue-backed id factory. Never mints fresh ids: an empty queue on
+ * demand throws `unrecorded id`; leftover ids after an entry throws
+ * `unconsumed ids`. Legacy entries without `generated_ids` are treated as `[]`.
+ */
+declare function replayJournal(doc: SemanticDocumentAdapter, journal: readonly JournalEntry[]): Promise<void>;
 //#endregion
 //#region src/editor/snapshot-utils.d.ts
 /** Main-track item identity read from a raw snapshot (only `part_id` is needed). */
@@ -295,9 +949,7 @@ type PushResultKind = 'ack' | 'duplicate' | 'rejected' | 'failed' | 'nothing_to_
  */
 interface PushResult {
   kind: PushResultKind;
-  /** Server document sequence observed after a successful `ack` or `duplicate`. */
-  mengineUpdateSeq?: number | undefined;
-  /** @deprecated Ack-only sequence retained until consumers adopt `mengineUpdateSeq`. */
+  /** Server-allocated sequence number; only present for `ack`. */
   updateSeq?: number | undefined;
   /** Whether the server held ops the local document lacked. See above. */
   collaborated: boolean;
@@ -404,7 +1056,8 @@ 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 or whose first snapshot is incomplete or invalid.
+   * not exist, instead of `MengineDocSession.waitForContent()`'s behavior of
+   * waiting forever for content that will never arrive.
    */
   static open(options: ManualSyncDocOptions): Promise<ManualSyncDoc>;
   /** Current document read model (authoritative shape). */
@@ -420,16 +1073,27 @@ declare class ManualSyncDoc {
    * was passed to the constructor.
    */
   editorPeerId(): PeerID;
-  /** Current content projected into the compatible track and part read shape. */
-  content(): VideoDraftContent;
+  /** Current document projected to the legacy `VideoDraft` read shape. */
+  draft(): VideoDraft;
+  /**
+   * Replay a deterministic sandbox journal into this document.
+   *
+   * The adapter stays private so callers cannot bypass the manual-sync
+   * lifecycle; journal replay is the one host-side operation that needs the
+   * adapter's transaction boundary and recorded id queue. Durability is still
+   * explicit: call {@link push} after replay and report success only from its
+   * verdict.
+   */
+  replayJournal(journal: readonly JournalEntry[]): Promise<void>;
   /**
    * Mark the document state the caller has just observed, for a later
    * {@link hasChangedSince}.
    *
    * This pair replaces the legacy integer-version comparison that
    * `DraftVersionDetector` used to tell the LLM "the draft was modified
-   * externally, reload before editing". Comparing Loro version vectors covers
-   * all collaborative edits without a business revision field in the document.
+   * externally, reload before editing". Under mengine `meta.version` never
+   * changes, so that detector would go permanently silent; comparing version
+   * vectors restores the same capability.
    *
    * Same capability, not a stronger one: like the legacy detector, this only
    * reports what changed between two moments the caller chose to sample.
@@ -574,22 +1238,12 @@ declare class MedeoHttpDocStorage implements DocStorage {
    * tool-level ack wait) subscribe here.
    */
   subscribePushOutcome(callback: (outcome: PushOutcome) => 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
@@ -628,23 +1282,10 @@ declare class MengineAckFailedError extends Error {
   readonly cause: Error | undefined;
   constructor(reason: 'timeout' | 'rejected' | 'failed', code: string | undefined, cause: Error | undefined, message: string);
 }
-type MengineLocalSaveState = LocalSaveState;
-interface WaitForLocalSaveOptions {
-  /** Only limits waiting, never cancels persistence. */
-  timeoutMs?: number;
-}
 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 {
-  /** Server-originated 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;
@@ -654,18 +1295,24 @@ interface MengineDocSessionOptions {
    * Browsers should pass an `IndexedDBDocStorage` for refresh/cross-tab support.
    */
   localStorage?: DocStorageLike;
-  /** A freshly fetched remote snapshot to merge into storage before loading.
-   * Existing local changes are retained; the host owns any online startup gate. */
-  initialSnapshot?: Uint8Array;
   sseReconnectDelayMs?: number;
+  /**
+   * Keep remote synchronization read-only: pull snapshot/diffs and subscribe to
+   * SSE updates, but never POST local Loro updates to the server.
+   */
+  readonlyMode?: boolean;
 }
 /**
  * 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.
  *
- * SemanticEditor writes through MirrorVideoDocumentAdapter directly, while
- * DocumentUndoManager observes the same LoroDoc independently. Both mutation
- * paths use the session's DocumentMutationGuard, closed before teardown.
+ * It assembles the engine sync stack around one Medeo document:
+ *
+ *   local DocStorage  ─┐
+ *                      ├─ ClientServerSynchronizer ── DocManager ── LoroDoc
+ *   MedeoHttpDocStorage┘                                              │
+ *                          (remote = Rust mengine-server)             ▼
+ *                                                   MirrorVideoDocumentAdapter + SemanticEditor
  *
  * `DocManager` owns the `LoroDoc`: local edits committed on the adapter are
  * picked up via `subscribeLocalUpdates`, saved to local storage, then pushed to
@@ -686,21 +1333,11 @@ 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 closeTask;
-  private lifetime;
-  private hasConnected;
-  private initialVersionValue;
-  private localVersionValue;
-  private pushErrorValue;
   /**
-   * Latest server oplog version seen on an authoritative HTTP response. Lets `waitForServerAck`
+   * Latest server oplog version seen on a push outcome. 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).
    */
@@ -715,14 +1352,14 @@ declare class MengineDocSession {
    */
   subscribePushOutcome(callback: (outcome: PushOutcome) => void): () => void;
   /**
-   * Resolve once the server has durably accepted the local commits as of
+   * Resolve once the server has durably accepted the local document state 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
-   * 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.
+   * 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.
    *
    * 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
@@ -744,70 +1381,43 @@ declare class MengineDocSession {
    * step. The committed change drives DocManager's local-update push.
    */
   get editor(): SemanticEditor;
-  /** 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.
+   * Opaque version token of the local oplog (base64 `VersionVector.encode`).
+   * Equality-comparable only: equal means no observed change (local or
+   * remote-arrived) since the token was taken. Throws when not started.
    */
-  subscribeUndoState(cb: (state: MengineUndoState) => void): () => void;
+  version(): string;
   /**
-   * 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.
+   * The live document adapter, exposed for journal replay (commit channel).
+   * Replaying through it still goes SemanticEditor → Loro → mengine-server —
+   * no write bypass. Typed by the narrow interface on purpose.
    */
-  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;
+  get documentAdapter(): SemanticDocumentAdapter;
+  /** Current document snapshot (read model). */
+  snapshot(): VideoDocument;
   /**
    * Start the sync stack and connect the document.
    *
-   * 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`.
+   * Returns once the local snapshot has loaded into the Loro doc so callers can
+   * read an initial snapshot. Remote convergence continues in the background and
+   * surfaces through `subscribe`.
    */
   start(): Promise<VideoDocument>;
-  private open;
-  getLocalSaveState(): MengineLocalSaveState;
-  /** Immediately reports local transaction state; independent of server confirmation. */
-  subscribeLocalSaveState(cb: (state: MengineLocalSaveState) => void): () => void;
-  /** Waits for commits present now to reach local storage. Does not wait for the network. */
-  waitForLocalSave(options?: WaitForLocalSaveOptions): Promise<void>;
-  /** Stop accepting edits and drain local persistence before releasing resources.
-   * A failed local write keeps retrying, even after the host has unmounted.
-   * Hosts should use this for normal teardown; destroy() is immediate cancellation. */
-  close(): Promise<void>;
-  getSyncState(): MengineDocSyncState;
-  private trackLocalVersion;
-  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;
-  /** Local absence needs a remote sync; empty business content does not. */
-  private waitForInitialLoad;
+  /**
+   * Resolve once the Loro doc holds the document root.
+   *
+   * `DocManager` loads from local storage, which starts empty for a fresh
+   * client; the server snapshot arrives asynchronously via the first sync job.
+   * `loaded` only means the local load ran, so we wait for actual content
+   * (populated schema roots) instead, surfaced by the doc subscription set up
+   * in `start()`.
+   */
+  private waitForContent;
+  private hasContent;
 }
 //#endregion
 //#region src/storage/memory-doc-storage.d.ts
@@ -1134,4 +1744,4 @@ declare function hostForAbsMs(ranges: MainClipRange[], absMs: number): MainClipR
  */
 declare function relativePositionForAbs(ranges: MainClipRange[], absMs: number): TrackItemTimePosition;
 //#endregion
-export { type Aggregation, type Attachment, type BgmPart, type CaptionPart, type CaptionStyle, type CommitOptions, DEFAULT_UNIT_TIME_MS, type DerivedItemPosition, type DocStorageLike, type DocVersionMark, IMPLEMENTED_SEMANTIC_OP_KINDS, type ImplementedSemanticOpKind, LANE_KINDS_IN_STACK_ORDER, type LaneKind, type MainClipRange, type MakeEmptyPart, ManualSyncDoc, type ManualSyncDocOptions, MedeoHttpDocStorage, type MedeoHttpDocStorageOptions, MemoryDocStorage, MengineAckFailedError, type MengineAuditEntry, type MengineAuditResponse, MengineDocSession, type MengineDocSessionOptions, type MengineDocSessionUpdateEvent, type MengineDocSyncState, type MengineDocumentVersion, type MengineEventStreamOptions, MengineHttpClient, type MengineHttpClientOptions, MengineHttpRequestError, type MengineLocalSaveState, MenginePushRejectedError, type MenginePushResponse, type MenginePushUpdateResponse, type MengineRejectedResponse, type MengineSnapshotResponse, type MengineSseUpdateEvent, type MengineSyncResponse, type MengineUndoState, type MengineUpdateMeta, MirrorVideoDocumentAdapter, type MirrorVideoDocumentOptions, type OpActor, type PartAggregation, type PartKind, type PartUnion, type PlannedSemanticOpKind, type PullFailureReason, type PullResult, type PushOutcome, type PushOutcomeKind, type PushResult, type PushResultKind, SchemaValidator, type SemanticDocumentAdapter, SemanticEditor, type SemanticOpInput, type SemanticOpKind, type SemanticOpName, type SnapshotReadable, type SolvedVideoDocument, type SpeechHostMap, type SpeechPart, type SpeedShift, TIMELINE_SKELETON_DURATION_MS, type Timeline, type TimelineDoc, type TimelineItem, type Track, type TrackDraft, type TrackItem, type TrackItemDraft, type TrackItemTimePosition, type TransactAudit, ValidationError, type VideoClipPart, 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 WaitForLocalSaveOptions, type WaitForServerAckOptions, arrangeMainTrackSeamlessly, assertValidVideoDocument, base64ToBytes, buildInitialVideoDocument, buildSpeechHostMap, bytesToBase64, cascadeAfterVideoClipChanges, createMirrorVideoDocument, createMirrorVideoDocumentAdapter, decodeDocVersionMark, derivePositionFromAbs, encodeDocVersionMark, ensureLaneTrack, fillMainTrackTimeGaps, findLaneTrack, fromVideoDocument, generatePartId, getAt, hostForAbsMs, isEmptyVideoClip, isImplementedSemanticOpKind, isMap, laneTrackId, mainTrackRanges, partDurationMs, partUnionSchema, readMainTrackItems, readMengineEventStream, readPart, readPartDurationMs, readVideoDocumentFromDraft, reassignSpeechesToVideoClipsByTime, recalculateTimelineDuration, relativePositionForAbs, resolveAllSpeechOverlaps, resolveSpeechOverlapByShiftingVideos, safeDurationMs, index_d_exports as schemas, snapshotToPlain, solveVideoDocument, syncAggregatedClipsTimePosition, toVideoDocument, validateVideoDocument, videoDocumentMirrorSchema, videoDocumentSchema };
+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 };