@mengine/medeo-client 2.0.1-alpha.3 → 2.0.1-alpha.30

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 derivePositionFromAbs, A as assertValidVideoDocument, At as VideoDraftContent, B as EntityRow, Bt as Track$1, C as isImplementedSemanticOpKind, Ct as TrackItem, D as PartIdFactory, Dt as VideoDocumentValidationIssue, E as ValidationError, Et as VideoDocument, F as ResolvedEntityTrack, Ft as CaptionPart$1, G as VoiceDescriptor, H as CaptionSegmentSelection, I as resolveEntityTimelineLayout, It as CaptionStyle, J as EntityId, K as JsonObject, L as projectEntityTimeline, Lt as PartAggregation, M as EntityTimelineTrackRole, Mt as effectiveVideoClipDurationMs, N as ResolvedEntityClipPlacement, Nt as speedOf, O as generatePartId, Ot as VideoDocumentValidationIssueCode, P as ResolvedEntityTimelineLayout, Pt as Attachment, Q as buildSpeechHostMap, R as EntityTimelineProjectionError, Rt as SpeedShift, S as SemanticOpKind, St as Track, T as SnapshotReadable, Tt as VideoClipPart, U as CaptionStyleFields, V as RelationRow, Vt as TrackItem$1, W as ScriptTextSegment, X as DerivedItemPosition, Y as buildInitialVideoDocument, Z as SpeechHostMap, _ as SemanticOpName, _t as DEFAULT_UNIT_TIME_MS, a as PlainMemoryAdapter, at as ensureLaneTrack, b as ImplementedSemanticOpKind, bt as SpeechPart, c as MirrorVideoDocumentAdapter, ct as solveVideoDocument, d as createMirrorVideoDocumentAdapter, dt as VideoDocumentDraft, et as fromVideoDocument, f as CommitOptions, ft as VideoDocumentMirrorSchema, g as SemanticOpInput, gt as CaptionPart, h as SemanticEditor, ht as CaptionDisplayCue, i as JournalEntry, it as SolvedVideoDocument, j as validateVideoDocument, jt as VideoDraftPartUnion, k as VideoDocumentValidationError, kt as VideoDraft, l as MirrorVideoDocumentOptions, lt as TrackDraft, m as SemanticDocumentAdapter, mt as BgmPart, n as videoDocumentSchema, nt as LANE_KINDS_IN_STACK_ORDER, o as PlainMemoryAdapterOptions, ot as findLaneTrack, p as OpActor, pt as videoDocumentMirrorSchema, q as JsonValue, r as readVideoDocumentFromDraft, rt as LaneKind, s as createPlainMemoryAdapter, st as laneTrackId, t as partUnionSchema, tt as toVideoDocument, u as createMirrorVideoDocument, ut as TrackItemDraft, v as TransactAudit, vt as PartKind, w as SchemaValidator, wt as TrackItemTimePosition, x as PlannedSemanticOpKind, xt as Timeline, y as IMPLEMENTED_SEMANTIC_OP_KINDS, yt as PartUnion, z as EntityRelationRows, zt as Timeline$1 } from "./index-DaabF2vA.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
@@ -178,33 +179,840 @@ 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[];
+  /**
+   * Where the selected segment sits in the AudioScript's ordered segments.
+   *
+   * A Caption locates its text as AudioScript plus index. The selection is
+   * stored as the segment's own stable id rather than this ordinal, so a
+   * concurrent insert or re-segmentation cannot silently slide a Caption onto
+   * different text; the ordinal is derived here for readers that want the
+   * position.
+   */
+  readonly segmentIndex: number;
+  /** Complete display text: the selected segments' text joined in order. */
+  readonly text: string;
+}
+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 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 attached to the project, or null until one is written. */
+  readonly audioScriptEntityId: string | null;
+  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;
+}
+interface EntityGraphRevisionConflictPayload {
+  readonly error: {
+    readonly code: 'revision_conflict';
+    readonly message: string;
+    readonly expected_revision: number;
+    readonly current_revision: number;
+  };
+}
+declare class EntityGraphRevisionConflictError extends MengineHttpRequestError {
+  readonly expectedRevision: number;
+  readonly currentRevision: number;
+  constructor(expectedRevision: number, currentRevision: number, payload: EntityGraphRevisionConflictPayload);
+}
+/** 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.
+   * The base revision is sent as an optimistic precondition, so a stale adoption
+   * fails loudly instead of letting Loro choose between concurrent selections.
+   *
+   * 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 prepared bytes directly; omit `expectedRevision` for immutable fact publication. */
+  commitUpdate(update: string, expectedRevision?: number): 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;
+}
+/** A synthesized speech result. Uploaded recordings remain raw `audio`. */
+interface VoiceoverMediaAssetFact {
+  /** Stable external speech result id, independent of the placed Clip id. */
+  readonly assetId: string;
+  readonly kind: 'voiceover-recording';
+  readonly durationMs: number;
+  readonly storageKey: string;
+  /**
+   * The PhoneticScript this take was spoken from, when the caller minting it
+   * knows. A migration that rebuilds the whole chain relates it itself; either
+   * way a take that never names one is refused when a plan is built.
+   */
+  readonly phoneticScriptEntityId?: string;
+  /** Timbre identity used for synthesis, when the caller has it. */
+  readonly voice?: VoiceDescriptor;
+}
+/** Facts resolved from media storage. A trim window never substitutes for intrinsic duration. */
+type MediaAssetFact = ImageMediaAssetFact | VideoMediaAssetFact | AudioMediaAssetFact | VoiceoverMediaAssetFact;
+/** Where a Clip starts: in flow by order, or at a stated start on its Track or inside its host. */
+type ClipPlacement = {
+  readonly kind: 'sequential';
+  readonly order: number;
+} | {
+  readonly kind: 'absolute';
+  readonly startMs: number;
+} | {
+  readonly kind: 'anchored';
+  readonly hostClipEntityId: string;
+  readonly startMs: number;
+};
+interface InsertPlacedClipInput {
+  readonly trackEntityId: string;
+  readonly contentEntityId: string;
+  readonly inMs: number;
+  readonly outMs: 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 the voiceover was rendered from. */
+  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: VoiceoverMediaAssetFact; /** 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 startMs?: never;
+} | {
+  readonly placement?: never;
+  readonly hostClipEntityId: string;
+  readonly startMs: number;
+});
+type VisualMediaAssetFact = ImageMediaAssetFact | VideoMediaAssetFact;
+interface InsertMediaClipInput {
+  readonly timelineEntityId: string;
+  readonly clipEntityId?: string;
+  readonly media: VisualMediaAssetFact;
+  /** Window on the source, whole milliseconds. An Image uses it as its finite display span. */
+  readonly inMs: number;
+  readonly outMs: number;
+  readonly placement: ClipPlacement;
+  readonly volume?: number;
+}
+interface ReplaceMediaClipInput {
+  readonly clipEntityId: string;
+  readonly media: VisualMediaAssetFact;
+  readonly inMs: number;
+  readonly outMs: number;
+}
+interface ReplacementMediaClipInput {
+  readonly clipEntityId?: string;
+  readonly media: VisualMediaAssetFact;
+  readonly inMs: number;
+  readonly outMs: 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;
+  /** Linear speed; null restores the source's own pace. */
+  readonly rate: number | null;
+}
+interface TrimClipInput {
+  readonly clipEntityId: string;
+  readonly inMs: number;
+  readonly outMs: number;
+}
+interface VoiceoverTakeResult {
+  readonly voiceoverClipEntityId: string;
+  /** The rendered voiceover Audio entity. */
+  readonly voiceoverAudioEntityId: string;
+  /** The timbre identity it was synthesized with, when the take declared one. */
+  readonly voiceEntityId?: string;
+  /** The pronunciation variant the voiceover was rendered from. */
+  readonly phoneticScriptEntityId: string;
+  /** The base-text owner resolved from the PhoneticScript baseEntityIds. */
+  readonly audioScriptEntityId: string;
+  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 inMs: number;
+  readonly outMs: number;
+  readonly startMs?: number;
+  /** Where among its Track's Clips it lands; appended when omitted. */
+  readonly order?: number;
+  readonly clipPayload?: JsonObject;
+}
+interface UpdateClipMarkerInput {
+  readonly clipEntityId: string;
+  readonly inMs?: number;
+  readonly outMs?: number;
+  /** Passing `undefined` explicitly removes the optional start. */
+  readonly startMs?: number | undefined;
+  /** Passing `undefined` explicitly removes the optional rate. */
+  readonly rate?: number | 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 inMs: number;
+  readonly outMs: number;
+  readonly startMs?: number;
+  readonly rate?: number;
+}
+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 voiceover consumes; composition is required. */
+  private requireComposedPhoneticScript;
+  /** Preserve the factual synthesis input as `[rendered Audio, PhoneticScript]`. */
+  private ensurePhoneticRender;
+  private reconcileVoiceoverCaptions;
+  private ensureRoleTrackForClip;
+  /**
+   * 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/visual-assets-effect.d.ts
+type MediaFact = MediaAssetFact;
+interface VisualAssetsEffectInput {
+  /** Stable command identity. A retried command must reuse it; a new placement must use a new one. */
+  effect_id: string;
+  clips: ReadonlyArray<{
+    media_id: string;
+    media_kind: 'image' | 'video';
+    media_duration_ms: number;
+    storage_key?: string;
+    start_ms?: number;
+    play_in?: number;
+    play_out?: number;
+    volume?: number;
+    lineage?: {
+      generation_job_id: string;
+      sources: ReadonlyArray<MediaFact>;
+      script?: {
+        entity_id: string;
+        segments: ReadonlyArray<{
+          segment_id: string;
+          text: string;
+          language?: string;
+        }>;
+        content_hash: string;
+      };
+    };
+  }>;
+  before_clip_id?: string;
+  after_clip_id?: string;
+}
+/** Read the authoritative timeline receipt, not a media-id heuristic. */
+declare function hasVisualAssetsEffect(rows: EntityRelationRows, effectId: string): boolean;
+/**
+ * Materialize a host-resolved visual command into native Entity/Relation rows.
+ * The result is suitable for one revision-checked `EntityGraphHttpClient.commit`.
+ * This does not fetch Assets or write remotely; callers must supply factual media
+ * and lineage inputs after their own ownership checks.
+ */
+declare function applyVisualAssetsEffect(rows: EntityRelationRows, input: VisualAssetsEffectInput): EntityRelationRows;
+//#endregion
+//#region src/entity-editor/revise-audio-script.d.ts
+interface ReviseAudioScriptInput {
+  readonly editId: string;
+  readonly sourceAudioScriptEntityId: string;
+  readonly edits: readonly {
+    readonly segmentId: string;
+    readonly text: string;
+  }[];
+  readonly captionUsages?: readonly {
+    readonly clipEntityId: string;
+    readonly captionEntityId: string;
+    readonly markerEntityId: string;
+    readonly selection?: CaptionSegmentSelection;
+  }[];
+}
+interface ReviseAudioScriptResult {
+  readonly rows: EntityRelationRows;
+  readonly audioScriptEntityId: string;
+  readonly captionUsages: readonly {
+    readonly clipEntityId: string;
+    readonly previousCaptionEntityId: string;
+    readonly captionEntityId: string;
+    readonly markerEntityId: string;
+  }[];
+  readonly changed: boolean;
+}
+/** Revise text as an independent authored document, never as a version-family mutation. */
+declare function reviseAudioScript(rows: EntityRelationRows, input: ReviseAudioScriptInput): ReviseAudioScriptResult;
+//#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 | null;
+}
+/**
+ * MEngine editor policy, not a cardinality restriction on the general-purpose DSL.
  *
- * 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.
+ * Resources live on Asset entities and are reached through `from-asset`: no
+ * other entity carries a locator, one Asset claims each `(system, key)` pair,
+ * and media reaches at most one Asset. Media whose bytes are not named through
+ * that Relation is rejected rather than guessed at.
  */
+declare function assertCanonicalEditorResources(rows: EntityRelationRows): void;
 /**
- * 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.
+ * 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 resource rules on the complete
+ * after state, with no exemption for historical graphs:
+ *
+ * 1. every media Entity reaches exactly one Asset through `from-asset`;
+ * 2. no entity other than an Asset carries a locator;
+ * 3. an Asset's locator is immutable — pointing it at other bytes would
+ *    silently rewrite every entity already made from it.
+ *
+ * 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 media entity for this asset id. */
+  readonly contentEntityId: string;
+  /** The Asset the media was made from; shared by every entity naming the same bytes. */
+  readonly assetEntityId: string;
+  /** The timbre identity of a synthesized voiceover; absent for recorded media. */
+  readonly voiceEntityId?: string;
+}
+/**
+ * Import at the editor boundary, not at asset generation time. Existing
+ * provenance is retained.
+ *
+ * The bytes are named once, on an Asset entity, and the media entity reaches
+ * them through a `from-asset` Relation. Re-importing the same `(system, key)`
+ * reuses that Asset and the media already made from it, so one stored resource
+ * is never copied into several rows.
  */
-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, or null until a script is transcribed or written. */
+  readonly audioScriptEntityId: string | null;
+}
+/** Read only the attached version and preserve every segment; never aggregate other scripts. */
+declare function readDocumentAudioScript(state: DocumentAudioScriptState): DocumentAudioScript;
+//#endregion
+//#region src/entity-crdt/field-changes.d.ts
+/** List members are addressed by identity, never a transient array offset. */
+type FieldPath = readonly (string | {
+  elementId: string;
+})[];
+type FieldChange = {
+  op: 'set';
+  path: FieldPath;
+  value: JsonValue;
+} | {
+  op: 'unset';
+  path: FieldPath;
+} | {
+  op: 'text.splice';
+  path: FieldPath;
+  index: number;
+  deleteCount: number;
+  text: string;
+} | {
+  op: 'list.insert';
+  path: FieldPath;
+  value: JsonValue;
+  beforeElementId: string | null;
+} | {
+  op: 'list.move';
+  path: FieldPath;
+  elementId: string;
+  beforeElementId: string | null;
+} | {
+  op: 'list.remove';
+  path: FieldPath;
+  elementId: string;
+};
+declare function assertFieldChanges(changes: readonly FieldChange[]): void;
+/** Resolve against the sequential causal view; the numeric path never crosses the API boundary. */
+declare function resolveFieldPath(payload: JsonObject, path: FieldPath): (string | number)[];
+/** Detached plan evaluation. Native compilation replays the original operations, not this snapshot. */
+declare function applyFieldChanges(payload: JsonObject, changes: readonly FieldChange[]): JsonObject;
+//#endregion
+//#region src/entity-crdt/entity-document.d.ts
+declare const LORO_ENTITY_SCHEMA = "medeo.entities.loro.v1";
+interface EntityDocumentState {
+  readonly rows: EntityRelationRows;
+  readonly project: Readonly<Record<string, string>>;
+  readonly phoneticScriptSelections?: Readonly<Record<string, string>>;
+}
+/** One stable native relation root, including records tombstoned from the active projection. */
+interface EntityRelationRecord extends RelationRow {
+  readonly deleted: boolean;
+}
+/** Read persisted relation roots before current entity versions are projected. */
+declare function readEntityRelationRecords(doc: LoroDoc): readonly EntityRelationRecord[];
+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: 'select-clip-content';
+  clipRoot: string;
+  relationRoot: string;
+} | {
+  type: 'select-phonetic-script';
+  clipRoot: string;
+  phoneticScriptRoot: 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[];
+  /** Resolve a queued edit target through its native identity without changing history. */
+  resolveCurrentEntityId(id: string): string;
+  getVersion(id: string): EntityRow | undefined;
+  /** The callback and every domain validation execute on a causally complete fork first. */
+  transact(edit: (draft: LoroEntityDraft) => void): Uint8Array;
+  /** Validate remote operations on a fork before importing their native identities. */
+  import(update: Uint8Array): void;
+  /**
+   * Bind a saved snapshot without rewriting text operations or resolving
+   * selection conflicts. The script names the bytes the same way everything
+   * else does — an Asset entity plus a Relation — and keeps only the
+   * fingerprint that tells a stale snapshot from a current one. The Relation is
+   * `to-asset`: these bytes are the script's own content written out, not a
+   * source it was made from.
+   */
+  bindAudioScriptAsset(entityId: string, assetId: string, expectedContentHash: string): Uint8Array;
+  canUndo(): boolean;
+  canRedo(): boolean;
+  undo(): boolean;
+  redo(): boolean;
+  private historyEdit;
+}
+declare class LoroEntityDraft {
+  private readonly doc;
+  readonly commands: Command[];
+  private readonly selectedRoots;
+  private readonly relationAliases;
+  constructor(doc: LoroDoc);
+  snapshot(): EntityDocumentState;
+  order(groupId: string, entityIds: readonly string[]): void;
+  /** Project the final scalar placement intents onto the existing native ordering containers. */
+  reconcileOrder(rows: EntityRelationRows): void;
+  create(row: EntityRow): void;
+  delete(entityId: string): void;
+  attach(slot: string, entityId: string): void;
+  link(row: RelationRow): void;
+  patchRelationTrace(relationId: string, trace: JsonObject): void;
+  unlink(relationId: string): void;
+  /** Select the one content membership projected for this stable Clip identity. */
+  selectClipContent(relationId: string): void;
+  /** Select the pending immutable pronunciation variant for one stable Speech Clip. */
+  selectPhoneticScript(clipEntityId: string, phoneticScriptEntityId: 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;
+  private assertGenericMutationAllowed;
+  changeRelation(relationId: string, changes: readonly FieldChange[]): void;
+  captureSelectionBaselines(): void;
+  private record;
+}
+//#endregion
+//#region src/entity-crdt/compile-rows.d.ts
+interface ApplyEntityRowsOptions {
+  readonly projectAttachments?: Readonly<Record<string, string>>;
+  readonly phoneticScriptSelections?: Readonly<Record<string, string>>;
+}
+/** Lower a detached ordinary-object edit against its actual causal Loro baseline. */
+declare function compileEntityRows(snapshot: Uint8Array, rows: EntityRelationRows, validate?: (state: EntityDocumentState) => void, options?: ApplyEntityRowsOptions): {
+  update: Uint8Array;
+  state: EntityDocumentState;
+};
+/** Publish final rows as imported causal operations, outside the caller's local undo history. */
+declare function publishEntityRows(editor: LoroEntityDocument, rows: EntityRelationRows, options?: ApplyEntityRowsOptions): {
+  update: Uint8Array;
+  state: EntityDocumentState;
+};
+/** Compile an edit on an existing peer, retaining its native local undo history. */
+declare function applyEntityRows(editor: LoroEntityDocument, rows: EntityRelationRows, options?: ApplyEntityRowsOptions): {
+  update: Uint8Array;
+  state: EntityDocumentState;
+};
+//#endregion
+//#region src/entity-crdt/legacy-schema-migration.d.ts
+/** Replace only the four positionally equivalent alpha23 relation kinds. */
+declare function migrateAlpha23EntityDocument(doc: LoroDoc): Uint8Array | undefined;
+//#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). */
@@ -393,6 +1201,8 @@ declare class ManualSyncDoc {
   private readonly client;
   private readonly doc;
   private readonly adapter;
+  /** Whether this document's timeline is owned by the Entity graph. */
+  isEntityDocument(): boolean;
   readonly editor: SemanticEditor;
   /**
    * The version the server is known to hold. Starts empty (nothing confirmed)
@@ -424,6 +1234,16 @@ declare class ManualSyncDoc {
   editorPeerId(): PeerID;
   /** Current content projected into the compatible track and part read shape. */
   content(): VideoDraftContent;
+  /**
+   * 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}.
@@ -632,18 +1452,13 @@ 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. */
+  /** 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. */
@@ -658,10 +1473,12 @@ 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
@@ -697,7 +1514,6 @@ declare class MengineDocSession {
   private started;
   private startTask;
   private destroyed;
-  private closeTask;
   private lifetime;
   private hasConnected;
   private initialVersionValue;
@@ -748,6 +1564,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;
   /** Current-session undo/redo availability. Loading and closed sessions report false. */
@@ -791,17 +1619,7 @@ declare class MengineDocSession {
    */
   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;
@@ -998,103 +1816,6 @@ type MakeEmptyPart = (durationMs: number) => {
  */
 declare function cascadeAfterVideoClipChanges(doc: TimelineDoc, makeEmptyPart: MakeEmptyPart): void;
 //#endregion
-//#region src/timeline-core/bridge.d.ts
-/**
- * Bridge between the authoritative `VideoDocument` (position-only facts) and the
- * flat `TimelineDoc` the cascade primitives solve over.
- *
- * The data flow is single-directional (RFC 02 §7/§10): ops write only facts
- * (`time_position`, parts) to `VideoDocument`; absolute time, `part_aggregations`,
- * total duration, and gap fillers are NOT stored — the projection derives them
- * on read by running the cascade. There is no write-back of solved positions.
- *
- * - `solveVideoDocument` seeds a `TimelineDoc` from each item's `time_position`,
- *   runs the full cascade, and returns the derived read-view (abs / aggregations
- *   / duration). It is the single solve shared by the legacy `VideoDraft`
- *   projection.
- * - `ensureLaneTrack` / `findLaneTrack` locate (or mint) a secondary lane's
- *   track row in the draft, so ops can write authoritative facts onto the right
- *   named container (lane = container).
- */
-/** The projection-derived read-view of a `VideoDocument` (RFC 02 §7). */
-interface SolvedVideoDocument {
-  absByPartId: Map<string, number>;
-  aggregations: PartAggregation[];
-  durationMs: number;
-  partLibrary: Record<string, PartUnion>;
-  /**
-   * Part ids of the gap fillers this solve minted.
-   *
-   * They exist only inside the solve: gap filling needs them so the clips after a
-   * gap land at the right absolute time, but they are not authoritative state and
-   * the read view does not carry them (see `fromVideoDocument`).
-   *
-   * Reported as ids rather than left for the caller to detect, because the caller
-   * *cannot* detect them. The obvious predicate — `origin_media_id === ''` — also
-   * matches an empty clip a writer placed on purpose (`batch_replace_video_clip_sequence`
-   * documents "Omit to create an empty clip placeholder"), and those are
-   * authoritative parts that must survive the projection. The mint callback is the
-   * only place that knows the difference.
-   *
-   * Note this deliberately excludes the fillers that gap filling *extended* rather
-   * than minted (`fillMainTrackTimeGaps` cases 1 and 2): those are authoritative
-   * empty clips already in `part_library`, and only their length is derived.
-   */
-  derivedFillerPartIds: Set<string>;
-}
-/**
- * Solve a `VideoDocument` (authoritative, position-only) into its derived
- * read-view: absolute time per item, `part_aggregations`, and total duration.
- * This is the read side of the single-directional flow — never written back.
- */
-declare function solveVideoDocument(document: VideoDocument): SolvedVideoDocument;
-/** The named container a secondary lane lives in. */
-type SecondaryLane = 'speech' | 'caption' | 'bgm';
-/** A lane's track kind: the `video_clip` main lane plus the three secondary lanes. */
-type LaneKind = SecondaryLane | 'video_clip';
-/**
- * The four lanes in top-to-bottom stack order — the order a `tracks` list holds
- * them in (see {@link laneRank}).
- *
- * Exported so a document can be seeded with all four lanes up front. That seed is
- * not cosmetic: {@link ensureLaneTrack} is find-then-mint over a `LoroMovableList`,
- * so two concurrent writers that each mint the same absent lane both keep their
- * row, and the merged document holds two tracks for one lane. For the main lane
- * that is fatal — `videoDocumentSchema` allows at most one `video_clip` track, so
- * the merged document stops being projectable at all, symmetrically on both
- * replicas. Pre-seeding every lane makes `ensureLaneTrack` always take its find
- * branch, which removes the race by construction rather than by detection.
- *
- * What closes the race is that a track with the lane's `parts_kind` EXISTS — the
- * lookup is by kind, not by id. So a seed is only safe if it covers every lane:
- * a partial seed leaves the uncovered lanes exactly as exposed as before.
- */
-declare const LANE_KINDS_IN_STACK_ORDER: readonly LaneKind[];
-/**
- * The conventional track id for a lane (`main_track`, `<kind>_track`). Shared by
- * the up-front seed and {@link ensureLaneTrack}'s lazy mint so a document's lane
- * ids do not depend on which of the two created the track.
- *
- * Ids are cosmetic to the merge itself — lane lookup goes by `parts_kind`, so
- * drifting them apart would not reopen the concurrent-mint race. They matter to
- * readers that address a lane by id (the FE editor's panes, fixtures), which is
- * why there is one convention rather than two.
- */
-declare function laneTrackId(kind: LaneKind): string;
-/**
- * Locate a lane's track row in the single `tracks` list by kind, minting an empty
- * row in lane-stacking order if absent (reference/17 §4: lane = `parts_kind`).
- * Ops use this to write authoritative items onto the right lane. The track id
- * comes from {@link laneTrackId}, shared with the up-front seed.
- *
- * The mint branch is a concurrency hazard, not a convenience: see
- * {@link LANE_KINDS_IN_STACK_ORDER}. A document seeded with all four lanes never
- * reaches it.
- */
-declare function ensureLaneTrack(draft: VideoDocumentDraft, kind: LaneKind): TrackDraft;
-/** Find a secondary lane's track row without minting it. */
-declare function findLaneTrack(draft: VideoDocumentDraft, kind: SecondaryLane): TrackDraft | undefined;
-//#endregion
 //#region src/timeline-core/locate.d.ts
 /**
  * Forward positioning for write-time ops (RFC 02 §9.1) — NOT a cascade.
@@ -1138,4 +1859,37 @@ 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 };
+//#region src/entity-crdt/audio-script-assets.d.ts
+/** A resource is a snapshot of text; the native Loro text remains the editing authority. */
+declare function audioScriptAssetContent(payload: JsonObject): JsonObject;
+declare function audioScriptAssetHash(payload: JsonObject): string;
+/**
+ * The Asset a script was written out to. It is a snapshot the script owns, so
+ * it is reached by `to-asset` — not `from-asset`, which would say the script
+ * was produced from bytes it cannot change.
+ */
+declare function audioScriptAssetOf(rows: EntityRelationRows, entityId: string): EntityRow | undefined;
+/**
+ * The Asset a script was made from — a transcript it does not own. A script
+ * that has one never writes a snapshot of its own: the bytes it would describe
+ * are already named, and rewriting them would contradict their source.
+ */
+declare function scriptSourceAssetOf(rows: EntityRelationRows, entityId: string): EntityRow | undefined;
+/** Internal fingerprint prevents a resource from silently describing an older text revision. */
+declare function audioScriptAssetFields(payload: JsonObject): JsonObject;
+/**
+ * What a PhoneticScript hands to synthesis: the base AudioScript's text as the
+ * variant pronounces it, plus the variant's own phoneme and prosody control.
+ *
+ * The variant's content is written by a model — deciding how words are said is
+ * text work, not a mechanical copy — but the bytes a synthesizer reads have to
+ * leave the entity graph to reach it, because synthesis does not handle
+ * entities. Writing this resource down is that crossing, and it is why speech
+ * can only come from a PhoneticScript.
+ */
+declare function phoneticScriptAssetContent(rows: EntityRelationRows, entityId: string): JsonObject;
+declare function phoneticScriptAssetHash(rows: EntityRelationRows, entityId: string): string;
+/** The Asset a PhoneticScript was written out to, read from the graph. */
+declare function phoneticScriptAssetOf(rows: EntityRelationRows, entityId: string): EntityRow | undefined;
+//#endregion
+export { type Aggregation, ApplyEntityRowsOptions, 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, type EditorFoundation, EntityDocumentState, type EntityGraphCommitOptions, EntityGraphHttpClient, EntityGraphRevisionConflictError, type EntityGraphRevisionConflictPayload, type EntityGraphState, EntityRelationRecord, EntityTimelineEditor, type EntityTimelineIdFactory, EntityTimelineProjectionError, type EntityTimelineTrackRole, type FieldChange, type FieldPath, IMPLEMENTED_SEMANTIC_OP_KINDS, type ImageMediaAssetFact, type ImplementedSemanticOpKind, type ImportedMediaAsset, type InsertCaptionClipInput, type InsertClipInput, type InsertMediaClipInput, type InsertMediaClipsInput, type InsertPlacedClipInput, type JournalEntry, LANE_KINDS_IN_STACK_ORDER, LORO_ENTITY_SCHEMA, type LaneKind, type LinearClipSpeed, LoroEntityDocument, LoroEntityDraft, type MainClipRange, type MakeEmptyPart, ManualSyncDoc, type ManualSyncDocOptions, MedeoHttpDocStorage, type MedeoHttpDocStorageOptions, type MediaAssetFact, type MediaClipInsertion, MemoryDocStorage, MengineAckFailedError, type MengineAuditEntry, type MengineAuditResponse, MengineDocSession, type MengineDocSessionOptions, type MengineDocSessionUpdateEvent, type MengineDocSyncState, type MengineDocumentVersion, type MengineEventStreamOptions, MengineHttpClient, type MengineHttpClientOptions, MengineHttpRequestError, MenginePushRejectedError, type MenginePushResponse, type MenginePushUpdateResponse, type MengineRejectedResponse, type MengineSnapshotResponse, type MengineSseUpdateEvent, type MengineSyncResponse, type MengineUndoState, type MengineUpdateMeta, MirrorVideoDocumentAdapter, type MirrorVideoDocumentOptions, type MoveClipInput, type MoveClipsToStartsInput, type MoveSequentialClipsInput, type MoveVoiceoverInput, type OpActor, type PartAggregation, type PartIdFactory, type PartKind, type PartUnion, type PatchCaptionStyleInput, PlainMemoryAdapter, type PlainMemoryAdapterOptions, type PlannedSemanticOpKind, type PullFailureReason, type PullResult, type PushOutcome, type PushOutcomeKind, type PushResult, type PushResultKind, type ReplaceClipContentInput, type ReplaceMediaClipInput, type ReplaceSequentialClipsInput, type ReplacementMediaClipInput, type ResolvedEntityClipPlacement, type ResolvedEntityTimelineLayout, type ResolvedEntityTrack, type ReviseAudioScriptInput, type ReviseAudioScriptResult, 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, 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 VideoMediaAssetFact, type VisualAssetsEffectInput, type VisualMediaAssetFact, type VoiceoverCaptionFact, type VoiceoverMediaAssetFact, type VoiceoverTakeInput, type VoiceoverTakeResult, type WaitForServerAckOptions, applyEntityRows, applyFieldChanges, applyVisualAssetsEffect, arrangeMainTrackSeamlessly, assembleCaptionContent, assembleEntityContent, assemblePhoneticScriptContent, assembleScriptText, assertCanonicalEditorResources, assertEntityProjectionPreservesLegacy, assertFieldChanges, assertMediaAssetWritePolicy, assertValidVideoDocument, audioScriptAssetContent, audioScriptAssetFields, audioScriptAssetHash, audioScriptAssetOf, base64ToBytes, buildInitialVideoDocument, buildSpeechHostMap, bytesToBase64, cascadeAfterVideoClipChanges, compileEntityRows, createEditSandbox, createMirrorVideoDocument, createMirrorVideoDocumentAdapter, createPlainMemoryAdapter, decodeDocVersionMark, derivePositionFromAbs, effectiveVideoClipDurationMs, encodeDocVersionMark, ensureEditorFoundation, ensureLaneTrack, fillMainTrackTimeGaps, findComposedAudioScript, findLaneTrack, fromVideoDocument, generatePartId, getAt, hasVisualAssetsEffect, hostForAbsMs, importMediaAsset, isEmptyVideoClip, isImplementedSemanticOpKind, isMap, laneTrackId, mainTrackRanges, migrateAlpha23EntityDocument, migrateLegacyTimelineToEntities, partDurationMs, partUnionSchema, phoneticScriptAssetContent, phoneticScriptAssetHash, phoneticScriptAssetOf, prepareCaptionContent, projectEntityTimeline, publishEntityRows, readDocumentAudioScript, readEntityDocument, readEntityRelationRecords, readMainTrackItems, readMengineEventStream, readPart, readPartDurationMs, readVideoDocumentFromDraft, reassignSpeechesToVideoClipsByTime, recalculateTimelineDuration, relativePositionForAbs, replayJournal, resolveAllSpeechOverlaps, resolveEntityTimelineLayout, resolveFieldPath, resolveSpeechOverlapByShiftingVideos, reviseAudioScript, safeDurationMs, index_d_exports as schemas, scriptSourceAssetOf, selectAudioScriptSegment, snapshotToPlain, solveVideoDocument, speedOf, syncAggregatedClipsTimePosition, toVideoDocument, validateVideoDocument, videoDocumentMirrorSchema, videoDocumentSchema };