@mengine/medeo-client 1.3.1-alpha.0 → 1.3.1-alpha.1

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { t as index_d_exports } from "./index-CMa6ZCtX.js";
-import { $ as VoiceDescriptor, A as generatePartId, At as Attachment, B as ResolvedEntityClipPlacement, C as PlannedSemanticOpKind, Ct as VideoDocumentSchemaVersion, D as SnapshotReadable, Dt as VideoDraftPartUnion, E as SchemaValidator, Et as VideoDraft, F as videoDocumentMirrorSchema, Ft as Timeline$1, G as EntityTimelineProjectionError, H as ResolvedEntityTrack, I as VideoDocumentValidationError, It as Track$1, J as JsonObject, K as EntityRelationRows, L as assertValidVideoDocument, Lt as TrackItem$1, M as TrackItemDraft, Mt as CaptionStyle, N as VideoDocumentDraft, Nt as PartAggregation, O as ValidationError, Ot as effectiveVideoClipDurationMs, P as VideoDocumentMirrorSchema, Pt as SpeedShift, Q as SequenceRange, R as validateVideoDocument, S as ImplementedSemanticOpKind, St as VideoDocument, T as isImplementedSemanticOpKind, Tt as VideoDocumentValidationIssueCode, U as resolveEntityTimelineLayout, V as ResolvedEntityTimelineLayout, W as projectEntityTimeline, X as CaptionStyleFields, Y as JsonValue, Z as SequenceDuration, _ as SemanticEditor, _t as Track, a as PlainMemoryAdapter, at as buildSpeechHostMap, b as TransactAudit, bt as VIDEO_DOCUMENT_SCHEMA_VERSION, c as MirrorVideoDocumentAdapter, ct as toVideoDocument, d as createMirrorVideoDocument, dt as DEFAULT_UNIT_TIME_MS, et as EntityId, f as createMirrorVideoDocumentAdapter, ft as ENTITY_TIMELINE_PROJECTION_SCHEMA_VERSION, g as SemanticDocumentAdapter, gt as Timeline, h as OpActor, ht as SpeechPart, i as JournalEntry, it as SpeechHostMap, j as TrackDraft, jt as CaptionPart$1, k as PartIdFactory, kt as speedOf, l as MirrorVideoDocumentOptions, lt as BgmPart, m as CommitOptions, mt as PartUnion, n as videoDocumentSchema, nt as buildInitialVideoDocument, o as PlainMemoryAdapterOptions, ot as derivePositionFromAbs, p as writeVideoDocumentToDraft, pt as PartKind, q as EntityRow, r as readVideoDocumentFromDraft, rt as DerivedItemPosition, s as createPlainMemoryAdapter, st as fromVideoDocument, t as partUnionSchema, tt as InitialDocumentFacts, u as applyEntityTimelineProjection, ut as CaptionPart, v as SemanticOpInput, vt as TrackItem, w as SemanticOpKind, wt as VideoDocumentValidationIssue, x as IMPLEMENTED_SEMANTIC_OP_KINDS, xt as VideoClipPart, y as SemanticOpName, yt as TrackItemTimePosition, z as EntityTimelineTrackRole } from "./index-WxMNUbOa.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-PYtGeXNk.js";
 import { PeerID } from "loro-crdt";
 import { DocState } from "@mengine/sync";
 import { BaseDocStorage, Connection, DocDiff, DocPushReceipt, DocSnapshotRecord, DocStorage, DocStorageOptions, DocUpdate, DocUpdateRecord } from "@mengine/storage";
@@ -178,6 +178,57 @@ interface MengineEventStreamOptions {
 }
 declare function readMengineEventStream(options: MengineEventStreamOptions): Promise<void>;
 //#endregion
+//#region ../medeo-dsl/src/composition.d.ts
+type ScriptCompositionIssueCode = 'composition_missing' | 'composition_ambiguous' | 'composition_dangling' | 'unknown_segment' | 'empty_selection' | 'invalid_script' | 'invalid_selection';
+/**
+ * Raised when a variant's complete content cannot be assembled from its
+ * required composition Relation. Assembly never falls back to variant-local
+ * text: a missing, ambiguous, or dangling source is an error, not an empty
+ * read.
+ */
+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;
+}
+/**
+ * Resolve the one AudioScript a variant composes. Relations are queried from
+ * both endpoints, so persisted endpoint positions do not matter.
+ */
+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 the complete Caption content from its AudioScript: the selected
+ * segments in selection order, joined as display text. The Caption payload
+ * never carries text, so a broken composition fails here instead of silently
+ * rendering an empty caption.
+ */
+declare function assembleCaptionContent(rows: EntityRelationRows, captionEntityId: EntityId): AssembledCaptionContent;
+/**
+ * Assemble the complete Phonetic Script content for TTS: the composed
+ * AudioScript's base text plus the variant's own phoneme and prosody fields.
+ */
+declare function assemblePhoneticScriptContent(rows: EntityRelationRows, phoneticScriptEntityId: EntityId): AssembledPhoneticScriptContent;
+/** Select source text without creating another authoritative text field. */
+declare function 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 {
@@ -288,7 +339,8 @@ interface DeleteClipTreeInput {
 interface VoiceoverCaptionFact {
   /** Stable placed caption identity supplied by the materialized side effect. */
   readonly captionClipEntityId: string;
-  readonly text: 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;
@@ -296,8 +348,8 @@ interface VoiceoverCaptionFact {
 type VoiceoverTakeInput = {
   readonly timelineEntityId: string; /** Stable placed speech identity, distinct from media.assetId. */
   readonly voiceoverClipEntityId: string;
-  readonly media: VoiceMediaAssetFact; /** Complete spoken text; the editor owns the deterministic local script segment identity. */
-  readonly scriptText: string;
+  readonly media: VoiceMediaAssetFact; /** Existing pronunciation variant; its composed AudioScript stays the text owner. */
+  readonly phoneticScriptEntityId: string;
   readonly volume: number;
   readonly captions: readonly VoiceoverCaptionFact[];
 } & ({
@@ -373,6 +425,9 @@ interface TrimClipInput {
 interface VoiceoverTakeResult {
   readonly voiceoverClipEntityId: string;
   readonly voiceEntityId: string;
+  /** The pronunciation variant the Voice was rendered from. */
+  readonly phoneticScriptEntityId: string;
+  /** The base-text owner resolved along the phonetic composition Relation. */
   readonly audioScriptEntityId: string;
   readonly captionClipEntityIds: readonly string[];
 }
@@ -405,7 +460,10 @@ interface InsertCaptionClipInput {
   readonly timelineEntityId: string;
   /** Stable placed caption identity, distinct from the Caption content identity. */
   readonly captionClipEntityId?: string;
-  readonly text: string;
+  /** Existing base-text owner; the Caption composes it instead of storing text. */
+  readonly audioScriptEntityId: 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;
@@ -490,18 +548,26 @@ declare class EntityTimelineEditor {
   setCaptionVisibility(input: SetCaptionVisibilityInput): void;
   patchCaptionStyle(input: PatchCaptionStyleInput): void;
   /**
-   * Place an independent Caption: its own content entity, inline text Asset,
-   * and Clip with a display Marker. No Voice, provenance, or alignment is
-   * required — the placement describes only this use. Moving or stretching
-   * the returned Clip later changes the Clip/Marker, never the Caption entity.
+   * Place a Caption as a composed variant of an existing AudioScript: the
+   * entity stores only its selection, style, and inherent cue-bounded
+   * Sequence — never 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;
-  private ensureAudioScript;
+  /** 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 replaceCaptionSemanticRelations;
+  /**
+   * 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. */
@@ -538,8 +604,7 @@ interface EditorFoundation {
  * 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 inline text keeps its inline Asset and
- * `physical-asset` binding.
+ * are rejected, not migrated. Caption composes AudioScript text and has no physical text Asset.
  */
 declare function assertCanonicalEditorResources(rows: EntityRelationRows): void;
 /**
@@ -550,8 +615,7 @@ declare function assertCanonicalEditorResources(rows: EntityRelationRows): void;
  *
  * 1. every Image/Video/Audio/Voice Entity carries its own Asset `external`
  *    identity;
- * 2. no `physical-asset` Relation may bind a media variant (Caption inline
- *    text keeps its inline Asset and binding);
+ * 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.
  *
@@ -1491,4 +1555,4 @@ declare function hostForAbsMs(ranges: MainClipRange[], absMs: number): MainClipR
  */
 declare function relativePositionForAbs(ranges: MainClipRange[], absMs: number): TrackItemTimePosition;
 //#endregion
-export { type Aggregation, type Attachment, type AudioMediaAssetFact, type BgmPart, type CaptionPart, 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, 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, assertCanonicalEditorResources, assertEntityProjectionPreservesLegacy, assertMediaAssetWritePolicy, assertValidVideoDocument, base64ToBytes, buildInitialVideoDocument, buildSpeechHostMap, bytesToBase64, cascadeAfterVideoClipChanges, createEditSandbox, createMirrorVideoDocument, createMirrorVideoDocumentAdapter, createPlainMemoryAdapter, decodeDocVersionMark, derivePositionFromAbs, effectiveVideoClipDurationMs, encodeDocVersionMark, ensureEditorFoundation, ensureLaneTrack, fillMainTrackTimeGaps, findLaneTrack, fromVideoDocument, generatePartId, getAt, hostForAbsMs, importMediaAsset, isEmptyVideoClip, isImplementedSemanticOpKind, isMap, laneTrackId, mainTrackRanges, migrateLegacyTimelineToEntities, partDurationMs, partUnionSchema, projectEntityTimeline, readMainTrackItems, readMengineEventStream, readPart, readPartDurationMs, readVideoDocumentFromDraft, reassignSpeechesToVideoClipsByTime, recalculateTimelineDuration, relativePositionForAbs, replayJournal, resolveAllSpeechOverlaps, resolveEntityTimelineLayout, resolveSpeechOverlapByShiftingVideos, safeDurationMs, index_d_exports as schemas, snapshotToPlain, solveVideoDocument, speedOf, syncAggregatedClipsTimePosition, toVideoDocument, validateVideoDocument, videoDocumentMirrorSchema, videoDocumentSchema, writeVideoDocumentToDraft };
+export { type Aggregation, type AssembledCaptionContent, type AssembledPhoneticScriptContent, type Attachment, type AudioMediaAssetFact, type BgmPart, 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, 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, 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 };

package/dist/index.js

@@ -1,4 +1,4 @@
-import { $ as videoDocumentMirrorSchema, A as ensureLaneTrack, B as resolveSpeechOverlapByShiftingVideos, C as toVideoDocument, D as partUnionSchema, E as validateVideoDocument, F as arrangeMainTrackSeamlessly, G as safeDurationMs, H as TIMELINE_SKELETON_DURATION_MS, I as fillMainTrackTimeGaps, J as VIDEO_DOCUMENT_SCHEMA_VERSION, K as DEFAULT_UNIT_TIME_MS, L as reassignSpeechesToVideoClipsByTime, M as laneTrackId, N as solveVideoDocument, O as videoDocumentSchema, P as cascadeAfterVideoClipChanges, Q as recordEntries, R as recalculateTimelineDuration, S as fromVideoDocument, T as assertValidVideoDocument, U as isEmptyVideoClip, V as syncAggregatedClipsTimePosition, W as partDurationMs, X as speedOf, Y as effectiveVideoClipDurationMs, Z as partUnionToDraft, _ as hasSequence, a as applyEntityTimelineProjection, b as buildSpeechHostMap, c as writeVideoDocumentToDraft, d as resolveEntityTimelineLayout, et as base64ToBytes, f as EntityTimelineProjectionError, g as createRelationId, h as createEntityId, i as MirrorVideoDocumentAdapter, j as findLaneTrack, k as LANE_KINDS_IN_STACK_ORDER, l as readVideoDocumentFromDraft, m as isJsonObject, n as createPlainMemoryAdapter, o as createMirrorVideoDocument, p as decodeEntityRelationRows, q as ENTITY_TIMELINE_PROJECTION_SCHEMA_VERSION, r as generatePartId, s as createMirrorVideoDocumentAdapter, t as PlainMemoryAdapter, tt as bytesToBase64, u as projectEntityTimeline, v as isMediaAssetVariantKind, w as VideoDocumentValidationError, x as derivePositionFromAbs, y as buildInitialVideoDocument, z as resolveAllSpeechOverlaps } from "./document-Caidonf8.js";
+import { $ as ENTITY_TIMELINE_PROJECTION_SCHEMA_VERSION, A as VideoDocumentValidationError, B as cascadeAfterVideoClipChanges, C as hasSequence, D as derivePositionFromAbs, E as buildSpeechHostMap, F as LANE_KINDS_IN_STACK_ORDER, G as resolveAllSpeechOverlaps, H as fillMainTrackTimeGaps, I as ensureLaneTrack, J as TIMELINE_SKELETON_DURATION_MS, K as resolveSpeechOverlapByShiftingVideos, L as findLaneTrack, M as validateVideoDocument, N as partUnionSchema, O as fromVideoDocument, P as videoDocumentSchema, Q as DEFAULT_UNIT_TIME_MS, R as laneTrackId, S as selectAudioScriptSegments, T as buildInitialVideoDocument, U as reassignSpeechesToVideoClipsByTime, V as arrangeMainTrackSeamlessly, W as recalculateTimelineDuration, X as partDurationMs, Y as isEmptyVideoClip, Z as safeDurationMs, _ as ScriptCompositionError, a as applyEntityTimelineProjection, at as videoDocumentMirrorSchema, b as assembleScriptText, c as writeVideoDocumentToDraft, d as resolveEntityTimelineLayout, et as VIDEO_DOCUMENT_SCHEMA_VERSION, f as EntityTimelineProjectionError, g as createRelationId, h as createEntityId, i as MirrorVideoDocumentAdapter, it as recordEntries, j as assertValidVideoDocument, k as toVideoDocument, l as readVideoDocumentFromDraft, m as isJsonObject, n as createPlainMemoryAdapter, nt as speedOf, o as createMirrorVideoDocument, ot as base64ToBytes, p as decodeEntityRelationRows, q as syncAggregatedClipsTimePosition, r as generatePartId, rt as partUnionToDraft, s as createMirrorVideoDocumentAdapter, st as bytesToBase64, t as PlainMemoryAdapter, tt as effectiveVideoClipDurationMs, u as projectEntityTimeline, v as assembleCaptionContent, w as isMediaAssetVariantKind, x as findComposedAudioScript, y as assemblePhoneticScriptContent, z as solveVideoDocument } from "./document-Bf200CmD.js";
 import { addSpeechesInputSchema, addVideoClipsInputSchema, adjustBgmVolumeInputSchema, adjustSpeechVolumeInputSchema, adjustVideoClipDurationInputSchema, adjustVideoClipVolumeInputSchema, changeSpeechScriptInputSchema, changeSpeechVoiceInputSchema, deleteBgmInputSchema, deleteSpeechesInputSchema, deleteVideoClipsInputSchema, moveSpeechesInputSchema, moveVideoClipsByAnchorInputSchema, moveVideoClipsInputSchema, replaceVideoClipContentInputSchema, replaceVideoClipSequenceInputSchema, setBgmInputSchema, setCaptionStyleInputSchema, setCaptionVisibilityInputSchema, setVideoClipSpeedShiftInputSchema, t as schemas_exports } from "./schemas.js";
 import { LoroDoc, VersionVector } from "loro-crdt";
 import { ClientServerSynchronizer, DocManager } from "@mengine/sync";
@@ -231,8 +231,7 @@ const roleOrder$1 = {
 * 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 inline text keeps its inline Asset and
-* `physical-asset` binding.
+* are rejected, not migrated. Caption composes AudioScript text and has no physical text Asset.
 */
 function assertCanonicalEditorResources(rows) {
 	if (rows.entities.filter((row) => row.entityKind === "timeline").length > 1) throw new EntityTimelineProjectionError("Editor requires exactly one Timeline");
@@ -263,8 +262,7 @@ function assertCanonicalEditorResources(rows) {
 *
 * 1. every Image/Video/Audio/Voice Entity carries its own Asset `external`
 *    identity;
-* 2. no `physical-asset` Relation may bind a media variant (Caption inline
-*    text keeps its inline Asset and binding);
+* 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.
 *
@@ -608,6 +606,19 @@ function sameVoice(left, right) {
 }
 //#endregion
 //#region src/entity-editor/entity-timeline-editor.ts
+/**
+* Resolve the AudioScript a PhoneticScript composes. The composition is the
+* required text source: a variant without it has no content and fails here.
+*/
+function requireComposedAudioScript(rows, phoneticScriptEntityId) {
+	return assemblePhoneticScriptContent(rows, phoneticScriptEntityId).audioScript.entityId;
+}
+function captionSelections(selections) {
+	return structuredClone(selections);
+}
+function assertSelectionNamesScriptSegments(rows, audioScriptEntityId, selections) {
+	selectAudioScriptSegments(requireEntityKind(rows, audioScriptEntityId, "audio-script"), selections);
+}
 const roleOrder = {
 	caption: 0,
 	video_clip: 1,
@@ -1129,7 +1140,8 @@ var EntityTimelineEditor = class {
 			const imported = importMediaAsset(draft, input.media, this.idFactory);
 			replaceRows(draft, imported.rows);
 			const voice = requireEntityKind(draft, imported.contentEntityId, "voice");
-			const script = this.ensureAudioScript(draft, voice.entityId, input.scriptText);
+			const phonetic = this.requireComposedPhoneticScript(draft, input.phoneticScriptEntityId);
+			this.ensurePhoneticRender(draft, voice.entityId, phonetic.entityId);
 			const speechTrack = this.ensureRoleTrack(draft, input.timelineEntityId, "speech");
 			const existing = draft.entities.find((row) => row.entityId === input.voiceoverClipEntityId);
 			let voiceoverClipEntityId;
@@ -1179,12 +1191,13 @@ var EntityTimelineEditor = class {
 					}
 				});
 			}
-			this.reconcileVoiceoverCaptions(draft, voiceoverClipEntityId, voice.entityId, script.entityId, input.captions);
+			this.reconcileVoiceoverCaptions(draft, voiceoverClipEntityId, voice.entityId, phonetic.entityId, input.captions);
 			this.resolveOneVoiceoverOverlap(draft);
 			return {
 				voiceoverClipEntityId,
 				voiceEntityId: voice.entityId,
-				audioScriptEntityId: script.entityId,
+				phoneticScriptEntityId: phonetic.entityId,
+				audioScriptEntityId: requireComposedAudioScript(draft, phonetic.entityId),
 				captionClipEntityIds: input.captions.map((caption) => caption.captionClipEntityId)
 			};
 		});
@@ -1287,14 +1300,18 @@ var EntityTimelineEditor = class {
 		});
 	}
 	/**
-	* Place an independent Caption: its own content entity, inline text Asset,
-	* and Clip with a display Marker. No Voice, provenance, or alignment is
-	* required — the placement describes only this use. Moving or stretching
-	* the returned Clip later changes the Clip/Marker, never the Caption entity.
+	* Place a Caption as a composed variant of an existing AudioScript: the
+	* entity stores only its selection, style, and inherent cue-bounded
+	* Sequence — never 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) {
 		return this.transact((draft) => {
 			const durationMs = finitePositive(input.durationMs, "Caption durationMs");
+			const selections = captionSelections(input.selections);
+			const script = requireEntityKind(draft, input.audioScriptEntityId, "audio-script");
+			assertSelectionNamesScriptSegments(draft, script.entityId, selections);
 			const track = this.ensureRoleTrack(draft, input.timelineEntityId, "caption");
 			const content = {
 				entityId: this.mintEntityId(draft),
@@ -1307,20 +1324,12 @@ var EntityTimelineEditor = class {
 					},
 					sampling: "native",
 					coordinateSpace: "milliseconds",
-					text: input.text,
+					selections,
 					...input.style === void 0 ? {} : { style: cloneJsonObject(input.style, "Caption style") }
 				}
 			};
-			const asset = {
-				entityId: this.mintEntityId(draft),
-				entityKind: "asset",
-				payload: { inline: {
-					mediaType: "text/plain",
-					text: input.text
-				} }
-			};
-			draft.entities.push(content, asset);
-			draft.relations.push(this.createRelation(draft, "physical-asset", content.entityId, asset.entityId));
+			draft.entities.push(content);
+			draft.relations.push(this.createRelation(draft, "caption-composition", content.entityId, script.entityId, { segmentAlignment: [] }));
 			return this.insertPlacedClipIntoDraft(draft, {
 				trackEntityId: track.entityId,
 				contentEntityId: content.entityId,
@@ -1398,34 +1407,24 @@ var EntityTimelineEditor = class {
 		draft.relations.push(this.createRelation(draft, "timeline-track", timeline.entityId, track.entityId));
 		return track;
 	}
-	ensureAudioScript(draft, voiceEntityId, text) {
-		const renders = draft.relations.filter((relation) => relation.relationKind === "audio-script-render" && relation.endpoint0EntityId === voiceEntityId);
-		if (renders.length > 1) throw new Error(`Voice "${voiceEntityId}" has multiple AudioScript relations`);
+	/** The existing pronunciation variant a Voice consumes; composition is required. */
+	requireComposedPhoneticScript(draft, phoneticScriptEntityId) {
+		const phonetic = requireEntityKind(draft, phoneticScriptEntityId, "phonetic-script");
+		requireComposedAudioScript(draft, phonetic.entityId);
+		return phonetic;
+	}
+	/** Preserve the factual synthesis input, regardless of persisted endpoint positions. */
+	ensurePhoneticRender(draft, voiceEntityId, phoneticScriptEntityId) {
+		const renders = draft.relations.filter((relation) => relation.relationKind === "phonetic-script-render" && (relation.endpoint0EntityId === voiceEntityId || relation.endpoint1EntityId === voiceEntityId));
+		if (renders.length > 1) throw new Error(`Voice "${voiceEntityId}" has multiple PhoneticScript render relations`);
 		if (renders[0] !== void 0) {
-			const script = requireEntityKind(draft, renders[0].endpoint1EntityId, "audio-script");
-			const replacement = {
-				...script,
-				payload: { segments: [{
-					segmentId: "segment-0",
-					text
-				}] }
-			};
-			replaceEntity(draft, script.entityId, replacement);
-			return replacement;
+			if (otherEndpoint(renders[0], voiceEntityId) === phoneticScriptEntityId) return;
+			throw new Error(`Voice "${voiceEntityId}" already has a different PhoneticScript synthesis input`);
 		}
-		const script = {
-			entityId: this.mintEntityId(draft),
-			entityKind: "audio-script",
-			payload: { segments: [{
-				segmentId: "segment-0",
-				text
-			}] }
-		};
-		draft.entities.push(script);
-		draft.relations.push(this.createRelation(draft, "audio-script-render", voiceEntityId, script.entityId));
-		return script;
+		draft.relations.push(this.createRelation(draft, "phonetic-script-render", voiceEntityId, phoneticScriptEntityId));
 	}
-	reconcileVoiceoverCaptions(draft, voiceoverClipEntityId, voiceEntityId, scriptEntityId, captions) {
+	reconcileVoiceoverCaptions(draft, voiceoverClipEntityId, voiceEntityId, phoneticScriptEntityId, captions) {
+		const audioScriptEntityId = requireComposedAudioScript(draft, phoneticScriptEntityId);
 		const requested = new Set(captions.map((caption) => caption.captionClipEntityId));
 		if (requested.size !== captions.length) throw new Error("Caption Clip ids must be unique within a voiceover take");
 		const existing = directAnchorChildren(draft, voiceoverClipEntityId).filter((clipId) => clipRole(draft, clipId) === "caption");
@@ -1434,6 +1433,8 @@ var EntityTimelineEditor = class {
 		for (const caption of captions) {
 			const startMs = finiteNonNegative(caption.startMs, "Caption startMs");
 			const durationMs = finitePositive(caption.durationMs, "Caption durationMs");
+			const selections = captionSelections(caption.selections);
+			assertSelectionNamesScriptSegments(draft, audioScriptEntityId, selections);
 			if (draft.entities.find((entity) => entity.entityId === caption.captionClipEntityId) === void 0) {
 				const content = {
 					entityId: this.mintEntityId(draft),
@@ -1446,23 +1447,15 @@ var EntityTimelineEditor = class {
 						},
 						sampling: "native",
 						coordinateSpace: "milliseconds",
-						text: caption.text,
+						selections,
 						...caption.style === void 0 ? {} : { style: cloneJsonObject(caption.style, "Caption style") }
 					}
 				};
-				const asset = {
-					entityId: this.mintEntityId(draft),
-					entityKind: "asset",
-					payload: { inline: {
-						mediaType: "text/plain",
-						text: caption.text
-					} }
-				};
-				draft.entities.push(content, asset);
-				draft.relations.push(this.createRelation(draft, "physical-asset", content.entityId, asset.entityId), this.createRelation(draft, "caption-alignment", content.entityId, voiceEntityId, { alignment: {
+				draft.entities.push(content);
+				draft.relations.push(this.createRelation(draft, "caption-composition", content.entityId, audioScriptEntityId, { segmentAlignment: [] }), this.createRelation(draft, "caption-alignment", content.entityId, voiceEntityId, { alignment: {
 					start: startMs,
 					end: startMs + durationMs
-				} }), this.createRelation(draft, "caption-provenance", content.entityId, scriptEntityId, { segmentAlignment: [] }));
+				} }));
 				this.insertPlacedClipIntoDraft(draft, {
 					clipEntityId: caption.captionClipEntityId,
 					trackEntityId: captionTrack.entityId,
@@ -1494,27 +1487,10 @@ var EntityTimelineEditor = class {
 				...content,
 				payload: {
 					...content.payload,
-					extent: {
-						kind: "bounded",
-						start: 0,
-						end: durationMs
-					},
-					text: caption.text,
+					selections,
 					...Object.keys(style).length === 0 ? {} : { style }
 				}
 			});
-			const asset = requireEntityKind(draft, otherEndpoint(requireOneRelation(draft, content.entityId, "physical-asset"), content.entityId), "asset");
-			if (asset.payload.inline === void 0) throw new Error(`Caption "${caption.captionClipEntityId}" is not inline`);
-			replaceEntity(draft, asset.entityId, {
-				...asset,
-				payload: {
-					...asset.payload,
-					inline: {
-						mediaType: "text/plain",
-						text: caption.text
-					}
-				}
-			});
 			this.applyClipPlacement(draft, topology.clip.entityId, {
 				kind: "anchored",
 				hostClipEntityId: voiceoverClipEntityId,
@@ -1525,17 +1501,13 @@ var EntityTimelineEditor = class {
 				...placed.marker,
 				payload: {
 					...placed.marker.payload,
-					sourceRange: {
-						start: 0,
-						end: durationMs
-					},
 					duration: {
 						mode: "fixed",
 						value: durationMs
 					}
 				}
 			});
-			this.replaceCaptionSemanticRelations(draft, content.entityId, voiceEntityId, scriptEntityId, startMs, durationMs);
+			this.replaceCaptionSemanticRelations(draft, content.entityId, voiceEntityId, audioScriptEntityId, startMs, durationMs);
 		}
 	}
 	ensureRoleTrackForClip(draft, clipEntityId, role) {
@@ -1545,22 +1517,24 @@ var EntityTimelineEditor = class {
 		return this.ensureRoleTrack(draft, timeline.entityId, role);
 	}
 	replaceCaptionSemanticRelations(draft, captionEntityId, voiceEntityId, scriptEntityId, startMs, durationMs) {
-		const removed = new Set(incidentRelations(draft, captionEntityId).filter((relation) => relation.relationKind === "caption-alignment" || relation.relationKind === "caption-provenance").map((relation) => relation.relationId));
+		const removed = new Set(incidentRelations(draft, captionEntityId).filter((relation) => relation.relationKind === "caption-alignment" || relation.relationKind === "caption-composition").map((relation) => relation.relationId));
 		draft.relations = draft.relations.filter((relation) => !removed.has(relation.relationId));
 		draft.relations.push(this.createRelation(draft, "caption-alignment", captionEntityId, voiceEntityId, { alignment: {
 			start: startMs,
 			end: startMs + durationMs
-		} }), this.createRelation(draft, "caption-provenance", captionEntityId, scriptEntityId, { segmentAlignment: [] }));
+		} }), this.createRelation(draft, "caption-composition", captionEntityId, scriptEntityId, { segmentAlignment: [] }));
 	}
+	/**
+	* Remove one placed Caption use. The composed AudioScript outlives the
+	* caption: it may anchor further captions and remains the text owner.
+	*/
 	removeCaptionClipGraph(draft, clipEntityId) {
 		const topology = requireClipOnRole(draft, clipEntityId, "caption");
 		const caption = requireEntityKind(draft, otherEndpoint(topology.markerContentRelation, topology.marker.entityId), "caption");
-		const asset = requireEntityKind(draft, otherEndpoint(requireOneRelation(draft, caption.entityId, "physical-asset"), caption.entityId), "asset");
 		const contentRelations = incidentRelations(draft, caption.entityId);
 		const allowed = new Set([
-			"physical-asset",
+			"caption-composition",
 			"caption-alignment",
-			"caption-provenance",
 			"marker-content"
 		]);
 		const unsupported = contentRelations.filter((relation) => !allowed.has(relation.relationKind));
@@ -1568,10 +1542,8 @@ var EntityTimelineEditor = class {
 		this.removeClipGraph(draft, clipEntityId);
 		if (incidentRelations(draft, caption.entityId).some((relation) => relation.relationKind === "marker-content")) return;
 		const removed = new Set(incidentRelations(draft, caption.entityId).map((relation) => relation.relationId));
-		const assetIncidents = incidentRelations(draft, asset.entityId);
-		const deleteAsset = asset.payload.inline !== void 0 && assetIncidents.every((relation) => removed.has(relation.relationId));
 		draft.relations = draft.relations.filter((relation) => !removed.has(relation.relationId));
-		draft.entities = draft.entities.filter((entity) => entity.entityId !== caption.entityId && (!deleteAsset || entity.entityId !== asset.entityId));
+		draft.entities = draft.entities.filter((entity) => entity.entityId !== caption.entityId);
 	}
 	replaceAnchorHost(draft, childClipEntityId, hostClipEntityId) {
 		const anchors = draft.relations.filter((relation) => relation.relationKind === "clip-anchor" && relation.endpoint0EntityId === childClipEntityId);
@@ -1992,7 +1964,6 @@ function migrateLegacyTimelineToEntities(legacy, assetFacts, initial = {
 		facts.set(fact.assetId, fact);
 	}
 	const contentByPartId = /* @__PURE__ */ new Map();
-	const scriptBySpeechClipId = /* @__PURE__ */ new Map();
 	for (const track of legacy.tracks ?? []) for (const item of track.items ?? []) {
 		const part = requirePart(legacy, item.part_id);
 		if (part.video_clip !== void 0) {
@@ -2026,7 +1997,8 @@ function migrateLegacyTimelineToEntities(legacy, assetFacts, initial = {
 			entities = [...imported.rows.entities];
 			relations = [...imported.rows.relations];
 			contentByPartId.set(item.part_id, imported.contentEntityId);
-			scriptBySpeechClipId.set(item.part_id, ensureAudioScript(imported.contentEntityId, speech.audio_script, entities, relations, addEntity, link));
+			const phonemeScript = speech.phoneme_script;
+			ensureSpeechPhoneticChain(imported.contentEntityId, speech.audio_script, typeof phonemeScript === "string" ? phonemeScript : void 0, entities, relations, addEntity, link);
 		} else if (part.bgm !== void 0) {
 			const bgm = part.bgm;
 			const fact = facts.get(bgm.origin_media_id);
@@ -2101,6 +2073,22 @@ function migrateLegacyTimelineToEntities(legacy, assetFacts, initial = {
 			} else if (part.caption !== void 0) {
 				const caption = part.caption;
 				duration = caption.initial_duration_ms;
+				const voice = contentByPartId.get(caption.speech_part_id);
+				const render = relations.find((relation) => relation.relationKind === "phonetic-script-render" && relation.endpoint0EntityId === voice);
+				const phonetic = entities.find((entity) => entity.entityId === render?.endpoint1EntityId);
+				const script = phonetic === void 0 ? void 0 : composedAudioScript(phonetic, entities, relations);
+				if (script === void 0) fail("Legacy Caption has no composed AudioScript");
+				const sourceText = scriptText(script);
+				const captionText = caption.text;
+				const offset = sourceText.indexOf(captionText);
+				if (!captionText.trim() || offset < 0 || sourceText.indexOf(captionText, offset + 1) >= 0) fail("Legacy Caption needs explicit unambiguous AudioScript selections before cutover");
+				const selections = [{
+					segmentId: "segment-0",
+					...sourceText === captionText ? {} : { textRange: {
+						start: Array.from(sourceText.slice(0, offset)).length,
+						end: Array.from(sourceText.slice(0, offset + captionText.length)).length
+					} }
+				}];
 				content = addEntity("caption", {
 					extent: {
 						kind: "bounded",
@@ -2109,21 +2097,14 @@ function migrateLegacyTimelineToEntities(legacy, assetFacts, initial = {
 					},
 					sampling: "native",
 					coordinateSpace: "milliseconds",
-					text: caption.text,
+					selections,
 					...caption.style === void 0 ? {} : { style: toEntityCaptionStyle(caption.style) }
 				});
-				const asset = addEntity("asset", { inline: {
-					mediaType: "text/plain",
-					text: caption.text
-				} });
-				link("physical-asset", content, asset);
-				const voice = contentByPartId.get(caption.speech_part_id);
-				const script = scriptBySpeechClipId.get(caption.speech_part_id);
+				link("caption-composition", content, script.entityId, { segmentAlignment: [] });
 				link("caption-alignment", content, voice, { alignment: {
 					start: caption.start_ms,
 					end: caption.start_ms + duration
 				} });
-				link("caption-provenance", content, script, { segmentAlignment: [] });
 				markerPayload = {
 					sourceRange: {
 						start: 0,
@@ -2339,7 +2320,7 @@ function assertPartSupported(id, part, role) {
 		if (speech.voice?.name !== void 0 && typeof speech.voice.name !== "string") fail("Migration requires a string voice name when present");
 		if (!Array.isArray(speech.caption_ids) || speech.caption_ids.some((captionId) => !trimmed(captionId))) fail("Migration requires explicit Speech caption identities");
 		if (new Set(speech.caption_ids).size !== speech.caption_ids.length) fail("Migration requires unique Speech caption identities");
-		if (phonemeScript !== void 0 && phonemeScript !== null) fail("Non-null phoneme_script requires a phonetic-script migration adapter");
+		if (phonemeScript !== void 0 && phonemeScript !== null && typeof phonemeScript !== "string") fail("Migration requires a string phoneme_script when present");
 		assertKnownFields(speech.voice, ["id", "name"], "voice");
 		assertKnownFields(speech, [
 			"id",
@@ -2463,20 +2444,31 @@ function requirePart(document, partId) {
 	if (part === void 0) fail(`Placed Clip ${partId} has no part payload`);
 	return part;
 }
-function ensureAudioScript(voiceEntityId, text, entities, relations, addEntity, link) {
-	const renders = relations.filter((relation) => relation.relationKind === "audio-script-render" && relation.endpoint0EntityId === voiceEntityId);
-	if (renders.length > 1) fail(`Voice ${voiceEntityId} has ambiguous AudioScript provenance`);
+function ensureSpeechPhoneticChain(voiceEntityId, audioScriptText, phonemeScript, entities, relations, addEntity, link) {
+	const renders = relations.filter((relation) => relation.relationKind === "phonetic-script-render" && relation.endpoint0EntityId === voiceEntityId);
+	if (renders.length > 1) fail(`Voice ${voiceEntityId} has ambiguous PhoneticScript provenance`);
 	if (renders.length === 1) {
-		const script = entities.find((entity) => entity.entityId === renders[0].endpoint1EntityId && entity.entityKind === "audio-script");
-		if (script === void 0 || scriptText(script) !== text) fail(`Voice ${voiceEntityId} conflicts with the legacy Speech script`);
-		return script.entityId;
+		const phonetic = entities.find((entity) => entity.entityId === renders[0].endpoint1EntityId && entity.entityKind === "phonetic-script");
+		if (phonetic === void 0) fail(`Voice ${voiceEntityId} has a dangling PhoneticScript render`);
+		const script = composedAudioScript(phonetic, entities, relations);
+		if (script === void 0 || scriptText(script) !== audioScriptText) fail(`Voice ${voiceEntityId} conflicts with the legacy Speech script`);
+		return phonetic.entityId;
 	}
 	const script = addEntity("audio-script", { segments: [{
 		segmentId: "segment-0",
-		text
+		text: audioScriptText
 	}] });
-	link("audio-script-render", voiceEntityId, script);
-	return script;
+	const phonetic = addEntity("phonetic-script", phonemeScript === void 0 ? {} : { phonemeScript });
+	link("phonetic-script-composition", phonetic, script, { segmentAlignment: [] });
+	link("phonetic-script-render", voiceEntityId, phonetic);
+	return phonetic;
+}
+function composedAudioScript(phonetic, entities, relations) {
+	const edges = relations.filter((relation) => relation.relationKind === "phonetic-script-composition" && (relation.endpoint0EntityId === phonetic.entityId || relation.endpoint1EntityId === phonetic.entityId));
+	if (edges.length !== 1) return void 0;
+	const edge = edges[0];
+	const otherId = edge.endpoint0EntityId === phonetic.entityId ? edge.endpoint1EntityId : edge.endpoint0EntityId;
+	return entities.find((entity) => entity.entityId === otherId);
 }
 function scriptText(script) {
 	const segments = script.payload.segments;
@@ -4704,4 +4696,4 @@ function serverCovers(serverVV, target) {
 	return covers(server, target);
 }
 //#endregion
-export { DEFAULT_UNIT_TIME_MS, ENTITY_TIMELINE_PROJECTION_SCHEMA_VERSION, EntityGraphHttpClient, EntityTimelineEditor, EntityTimelineProjectionError, IMPLEMENTED_SEMANTIC_OP_KINDS, LANE_KINDS_IN_STACK_ORDER, ManualSyncDoc, MedeoHttpDocStorage, MemoryDocStorage, MengineAckFailedError, MengineDocSession, MengineHttpClient, MengineHttpRequestError, MenginePushRejectedError, MirrorVideoDocumentAdapter, PlainMemoryAdapter, SchemaValidator, SemanticEditor, TIMELINE_SKELETON_DURATION_MS, VIDEO_DOCUMENT_SCHEMA_VERSION, ValidationError, VideoDocumentValidationError, applyEntityTimelineProjection, arrangeMainTrackSeamlessly, assertCanonicalEditorResources, assertEntityProjectionPreservesLegacy, assertMediaAssetWritePolicy, assertValidVideoDocument, base64ToBytes, buildInitialVideoDocument, buildSpeechHostMap, bytesToBase64, cascadeAfterVideoClipChanges, createEditSandbox, createMirrorVideoDocument, createMirrorVideoDocumentAdapter, createPlainMemoryAdapter, decodeDocVersionMark, derivePositionFromAbs, effectiveVideoClipDurationMs, encodeDocVersionMark, ensureEditorFoundation, ensureLaneTrack, fillMainTrackTimeGaps, findLaneTrack, fromVideoDocument, generatePartId, getAt, hostForAbsMs, importMediaAsset, isEmptyVideoClip, isImplementedSemanticOpKind, isMap, laneTrackId, mainTrackRanges, migrateLegacyTimelineToEntities, partDurationMs, partUnionSchema, projectEntityTimeline, readMainTrackItems, readMengineEventStream, readPart, readPartDurationMs, readVideoDocumentFromDraft, reassignSpeechesToVideoClipsByTime, recalculateTimelineDuration, relativePositionForAbs, replayJournal, resolveAllSpeechOverlaps, resolveEntityTimelineLayout, resolveSpeechOverlapByShiftingVideos, safeDurationMs, schemas_exports as schemas, snapshotToPlain, solveVideoDocument, speedOf, syncAggregatedClipsTimePosition, toVideoDocument, validateVideoDocument, videoDocumentMirrorSchema, videoDocumentSchema, writeVideoDocumentToDraft };
+export { DEFAULT_UNIT_TIME_MS, ENTITY_TIMELINE_PROJECTION_SCHEMA_VERSION, EntityGraphHttpClient, EntityTimelineEditor, EntityTimelineProjectionError, IMPLEMENTED_SEMANTIC_OP_KINDS, LANE_KINDS_IN_STACK_ORDER, ManualSyncDoc, MedeoHttpDocStorage, MemoryDocStorage, MengineAckFailedError, MengineDocSession, MengineHttpClient, MengineHttpRequestError, MenginePushRejectedError, MirrorVideoDocumentAdapter, PlainMemoryAdapter, SchemaValidator, ScriptCompositionError, SemanticEditor, TIMELINE_SKELETON_DURATION_MS, VIDEO_DOCUMENT_SCHEMA_VERSION, ValidationError, VideoDocumentValidationError, applyEntityTimelineProjection, arrangeMainTrackSeamlessly, assembleCaptionContent, 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, projectEntityTimeline, readMainTrackItems, readMengineEventStream, readPart, readPartDurationMs, readVideoDocumentFromDraft, reassignSpeechesToVideoClipsByTime, recalculateTimelineDuration, relativePositionForAbs, replayJournal, resolveAllSpeechOverlaps, resolveEntityTimelineLayout, resolveSpeechOverlapByShiftingVideos, safeDurationMs, schemas_exports as schemas, selectAudioScriptSegments, snapshotToPlain, solveVideoDocument, speedOf, syncAggregatedClipsTimePosition, toVideoDocument, validateVideoDocument, videoDocumentMirrorSchema, videoDocumentSchema, writeVideoDocumentToDraft };

package/dist/testing.d.ts

@@ -1,4 +1,4 @@
-import { Et as VideoDraft, c as MirrorVideoDocumentAdapter } from "./index-WxMNUbOa.js";
+import { Ot as VideoDraft, c as MirrorVideoDocumentAdapter } from "./index-PYtGeXNk.js";
 
 //#region src/testing/in-memory-mengine-server.d.ts
 /**

package/dist/testing.js

@@ -1,4 +1,4 @@
-import { J as VIDEO_DOCUMENT_SCHEMA_VERSION, et as base64ToBytes, s as createMirrorVideoDocumentAdapter, tt as bytesToBase64 } from "./document-Caidonf8.js";
+import { et as VIDEO_DOCUMENT_SCHEMA_VERSION, ot as base64ToBytes, s as createMirrorVideoDocumentAdapter, st as bytesToBase64 } from "./document-Bf200CmD.js";
 import { t as classifyUpdate } from "./loro-relay-doc-ssdYpuef.js";
 import { LoroDoc, VersionVector, encodeFrontiers } from "loro-crdt";
 //#region src/testing/in-memory-mengine-server.ts