@mengine/medeo-client 1.3.1-alpha.4 → 1.3.1-alpha.6

package/dist/index.d.ts

@@ -1,4 +1,5 @@
-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-DdnuQf17.js";
+import { t as index_d_exports } from "./index-CMa6ZCtX.js";
+import { $ as VoiceDescriptor, A as generatePartId, At as effectiveVideoClipDurationMs, B as ResolvedEntityClipPlacement, C as PlannedSemanticOpKind, Ct as VideoClipPart, D as SnapshotReadable, Dt as VideoDocumentValidationIssueCode, E as SchemaValidator, Et as VideoDocumentValidationIssue, F as videoDocumentMirrorSchema, Ft as PartAggregation, G as EntityTimelineProjectionError, H as ResolvedEntityTrack, I as VideoDocumentValidationError, It as SpeedShift, J as CaptionSegmentSelection, K as EntityRelationRows, L as assertValidVideoDocument, Lt as Timeline$1, M as TrackItemDraft, Mt as Attachment, N as VideoDocumentDraft, Nt as CaptionPart$1, O as ValidationError, Ot as VideoDraft, P as VideoDocumentMirrorSchema, Pt as CaptionStyle, Q as SequenceRange, R as validateVideoDocument, Rt as Track$1, S as ImplementedSemanticOpKind, St as VIDEO_DOCUMENT_SCHEMA_VERSION, T as isImplementedSemanticOpKind, Tt as VideoDocumentSchemaVersion, U as resolveEntityTimelineLayout, V as ResolvedEntityTimelineLayout, W as projectEntityTimeline, X as ScriptTextSegment, Y as CaptionStyleFields, Z as SequenceDuration, _ as SemanticEditor, _t as SpeechPart, a as PlainMemoryAdapter, at as DerivedItemPosition, b as TransactAudit, bt as TrackItem, c as MirrorVideoDocumentAdapter, ct as derivePositionFromAbs, d as createMirrorVideoDocument, dt as BgmPart, et as JsonObject, f as createMirrorVideoDocumentAdapter, ft as CaptionPart, g as SemanticDocumentAdapter, gt as PartUnion, h as OpActor, ht as PartKind, i as JournalEntry, it as buildInitialVideoDocument, j as TrackDraft, jt as speedOf, k as PartIdFactory, kt as VideoDraftPartUnion, l as MirrorVideoDocumentOptions, lt as fromVideoDocument, m as CommitOptions, mt as ENTITY_TIMELINE_PROJECTION_SCHEMA_VERSION, n as videoDocumentSchema, nt as EntityId, o as PlainMemoryAdapterOptions, ot as SpeechHostMap, p as writeVideoDocumentToDraft, pt as DEFAULT_UNIT_TIME_MS, q as EntityRow, r as readVideoDocumentFromDraft, rt as InitialDocumentFacts, s as createPlainMemoryAdapter, st as buildSpeechHostMap, t as partUnionSchema, tt as JsonValue, u as applyEntityTimelineProjection, ut as toVideoDocument, v as SemanticOpInput, vt as Timeline, w as SemanticOpKind, wt as VideoDocument, x as IMPLEMENTED_SEMANTIC_OP_KINDS, xt as TrackItemTimePosition, y as SemanticOpName, yt as Track, z as EntityTimelineTrackRole, zt as TrackItem$1 } from "./index-BUkDsU7c.js";
 import { PeerID } from "loro-crdt";
 import { DocState } from "@mengine/sync";
 import { BaseDocStorage, Connection, DocDiff, DocPushReceipt, DocSnapshotRecord, DocStorage, DocStorageOptions, DocUpdate, DocUpdateRecord } from "@mengine/storage";
@@ -177,33 +178,498 @@ 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;
 /**
- * Part-id generation, aligned with the online ecosystem.
+ * 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 selectAudioScriptSegments(script: EntityRow<'audio-script'>, selections: readonly CaptionSegmentSelection[]): readonly ScriptTextSegment[];
+//#endregion
+//#region src/entity-editor/entity-graph-http-client.d.ts
+/** One authenticated revision of the authoritative Medeo Entity graph. */
+interface EntityGraphState {
+  readonly revision: number;
+  readonly rows: EntityRelationRows;
+}
+interface EntityGraphCommitOptions {
+  /** Server version vector proving the explicit legacy-to-Entity migration baseline. */
+  readonly migrationBaseVv?: string;
+}
+/** Browser-safe authenticated CAS 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>;
+  /**
+   * Replace the complete Entity graph under the baseline revision.
+   *
+   * 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: EntityGraphState, nextRows: EntityRelationRows, options?: EntityGraphCommitOptions): 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 selections: readonly 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;
+  /** 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 selections: readonly 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.
  *
- * 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.
+ * 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>>;
+}
+/**
+ * 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 has no 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 or Caption;
+ * 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']): 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 selections?: readonly 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/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). */
@@ -296,9 +762,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;
@@ -422,16 +886,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.
@@ -576,9 +1051,6 @@ 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;
@@ -627,14 +1099,6 @@ 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;
@@ -645,6 +1109,11 @@ interface MengineDocSessionOptions {
    */
   localStorage?: DocStorageLike;
   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
@@ -680,15 +1149,8 @@ declare class MengineDocSession {
   private adapterValue;
   private editorValue;
   private started;
-  private startTask;
-  private destroyed;
-  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).
    */
@@ -703,14 +1165,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
@@ -732,6 +1194,18 @@ declare class MengineDocSession {
    * step. The committed change drives DocManager's local-update push.
    */
   get editor(): SemanticEditor;
+  /**
+   * 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.
+   */
+  version(): string;
+  /**
+   * 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.
+   */
+  get documentAdapter(): SemanticDocumentAdapter;
   /** Current document snapshot (read model). */
   snapshot(): VideoDocument;
   /**
@@ -742,18 +1216,21 @@ declare class MengineDocSession {
    * surfaces 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;
-  /** Merge persisted local edits before exposing the initial content. */
-  private waitForLocalLoad;
+  /**
+   * 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
@@ -1080,4 +1557,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, MenginePushRejectedError, type MenginePushResponse, type MenginePushUpdateResponse, type MengineRejectedResponse, type MengineSnapshotResponse, type MengineSseUpdateEvent, type MengineSyncResponse, 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 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 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, ENTITY_TIMELINE_PROJECTION_SCHEMA_VERSION, type EditorFoundation, type EntityGraphCommitOptions, EntityGraphHttpClient, type EntityGraphState, EntityTimelineEditor, type EntityTimelineIdFactory, EntityTimelineProjectionError, type EntityTimelineTrackRole, 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, type LaneKind, type LinearClipSpeed, 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, applyEntityTimelineProjection, arrangeMainTrackSeamlessly, assembleCaptionContent, assembleEntityContent, assemblePhoneticScriptContent, assembleScriptText, assertCanonicalEditorResources, assertEntityProjectionPreservesLegacy, assertMediaAssetWritePolicy, assertValidVideoDocument, base64ToBytes, buildInitialVideoDocument, buildSpeechHostMap, bytesToBase64, cascadeAfterVideoClipChanges, 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, readMainTrackItems, readMengineEventStream, readPart, readPartDurationMs, readVideoDocumentFromDraft, reassignSpeechesToVideoClipsByTime, recalculateTimelineDuration, relativePositionForAbs, replayJournal, resolveAllSpeechOverlaps, resolveEntityTimelineLayout, resolveSpeechOverlapByShiftingVideos, safeDurationMs, index_d_exports as schemas, selectAudioScriptSegments, snapshotToPlain, solveVideoDocument, speedOf, syncAggregatedClipsTimePosition, toVideoDocument, validateVideoDocument, videoDocumentMirrorSchema, videoDocumentSchema, writeVideoDocumentToDraft };