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

package/dist/{index-WxMNUbOa.d.ts → index-Dxxu0Mi1.d.ts}

@@ -849,6 +849,13 @@ type RelationId = string & {
   readonly [relationIdBrand]: 'RelationId';
 };
 //#endregion
+//#region ../medeo-dsl/src/json-values.d.ts
+type JsonPrimitive = string | number | boolean | null;
+type JsonValue = JsonPrimitive | JsonObject | readonly JsonValue[];
+type JsonObject = {
+  readonly [key: string]: JsonValue;
+};
+//#endregion
 //#region ../medeo-dsl/src/entities.d.ts
 type KnownEntityKind = 'axvideo' | 'timeline' | 'track' | 'clip' | 'asset' | 'video' | 'audio' | 'voice' | 'image' | 'sequence-marker' | 'viewport' | 'audio-script' | 'phonetic-script' | 'caption';
 declare const extensionEntityKindBrand: unique symbol;
@@ -867,6 +874,11 @@ type SequenceDuration<Span = unknown> = {
   readonly mode: 'fixed';
   readonly value: Span;
 };
+interface ScriptTextSegment {
+  readonly segmentId: string;
+  readonly text: string;
+  readonly language?: string;
+}
 interface VoiceDescriptor {
   readonly system: 'voice-library';
   readonly key: string;
@@ -888,16 +900,31 @@ interface CaptionStyleFields {
   readonly positionX?: number;
   readonly positionY?: number;
 }
-//#endregion
-//#region ../medeo-dsl/src/json-values.d.ts
-type JsonPrimitive = string | number | boolean | null;
-type JsonValue = JsonPrimitive | JsonObject | readonly JsonValue[];
-type JsonObject = {
-  readonly [key: string]: JsonValue;
+/**
+ * Half-open `[start, end)` position window inside one Segment's text, counted
+ * in Unicode code points (not UTF-16 code units), so a boundary never splits a
+ * surrogate pair. Positions are non-negative safe integers with `start < end`;
+ * `end` must not exceed the Segment's code-point length.
+ */
+interface CaptionTextRange extends JsonObject {
+  readonly start: number;
+  readonly end: number;
+}
+/**
+ * One ordered entry of the Caption's segment selection. `segmentId` quotes the
+ * composed AudioScript's own stable segment identity — a local id quoted by the
+ * variant, never a peer Entity reference. Text itself is never copied here;
+ * complete Caption content is assembled through its direct baseEntityIds.
+ * The optional `textRange` narrows one Segment to an intra-Segment sub-span
+ * (intra-segment re-segmentation); without it the whole Segment text is selected.
+ */
+type CaptionSegmentSelection = JsonObject & {
+  readonly segmentId: string;
+  readonly textRange?: CaptionTextRange;
 };
 //#endregion
 //#region ../medeo-dsl/src/relations.d.ts
-type KnownRelationKind = 'timeline-track' | 'track-clip' | 'clip-marker' | 'marker-content' | 'axvideo-marker' | 'marker-timeline' | 'physical-asset' | 'generated' | 'phonetic-script-provenance' | 'caption-provenance' | 'caption-alignment' | 'clip-anchor' | 'audio-script-render' | 'audio-script-source' | 'audio-script-marker';
+type KnownRelationKind = 'timeline-track' | 'track-clip' | 'clip-marker' | 'marker-content' | 'axvideo-marker' | 'marker-timeline' | 'physical-asset' | 'generated' | 'caption-alignment' | 'clip-anchor' | 'phonetic-script-render' | 'audio-script-source' | 'audio-script-marker';
 type RelationKind = KnownRelationKind | (string & {});
 type RelationTrace = JsonObject;
 /**
@@ -1655,10 +1682,10 @@ declare const videoDocumentSchema: z.ZodObject<{
   tracks: z.ZodOptional<z.ZodArray<z.ZodObject<{
     id: z.ZodOptional<z.ZodString>;
     parts_kind: z.ZodOptional<z.ZodEnum<{
+      video_clip: "video_clip";
       speech: "speech";
       caption: "caption";
       bgm: "bgm";
-      video_clip: "video_clip";
     }>>;
     is_hidden: z.ZodOptional<z.ZodBoolean>;
     items: z.ZodOptional<z.ZodArray<z.ZodObject<{
@@ -1740,4 +1767,4 @@ declare const videoDocumentSchema: z.ZodObject<{
   }, z.core.$loose>]>>>;
 }, z.core.$loose>;
 //#endregion
-export { VoiceDescriptor as $, generatePartId as A, Attachment as At, ResolvedEntityClipPlacement as B, PlannedSemanticOpKind as C, VideoDocumentSchemaVersion as Ct, SnapshotReadable as D, VideoDraftPartUnion as Dt, SchemaValidator as E, VideoDraft as Et, videoDocumentMirrorSchema as F, Timeline$1 as Ft, EntityTimelineProjectionError as G, ResolvedEntityTrack as H, VideoDocumentValidationError as I, Track$1 as It, JsonObject as J, EntityRelationRows as K, assertValidVideoDocument as L, TrackItem$1 as Lt, TrackItemDraft as M, CaptionStyle as Mt, VideoDocumentDraft as N, PartAggregation as Nt, ValidationError as O, effectiveVideoClipDurationMs as Ot, VideoDocumentMirrorSchema as P, SpeedShift as Pt, SequenceRange as Q, validateVideoDocument as R, ImplementedSemanticOpKind as S, VideoDocument as St, isImplementedSemanticOpKind as T, VideoDocumentValidationIssueCode as Tt, resolveEntityTimelineLayout as U, ResolvedEntityTimelineLayout as V, projectEntityTimeline as W, CaptionStyleFields as X, JsonValue as Y, SequenceDuration as Z, SemanticEditor as _, Track as _t, PlainMemoryAdapter as a, buildSpeechHostMap as at, TransactAudit as b, VIDEO_DOCUMENT_SCHEMA_VERSION as bt, MirrorVideoDocumentAdapter as c, toVideoDocument as ct, createMirrorVideoDocument as d, DEFAULT_UNIT_TIME_MS as dt, EntityId as et, createMirrorVideoDocumentAdapter as f, ENTITY_TIMELINE_PROJECTION_SCHEMA_VERSION as ft, SemanticDocumentAdapter as g, Timeline as gt, OpActor as h, SpeechPart as ht, JournalEntry as i, SpeechHostMap as it, TrackDraft as j, CaptionPart$1 as jt, PartIdFactory as k, speedOf as kt, MirrorVideoDocumentOptions as l, BgmPart as lt, CommitOptions as m, PartUnion as mt, videoDocumentSchema as n, buildInitialVideoDocument as nt, PlainMemoryAdapterOptions as o, derivePositionFromAbs as ot, writeVideoDocumentToDraft as p, PartKind as pt, EntityRow as q, readVideoDocumentFromDraft as r, DerivedItemPosition as rt, createPlainMemoryAdapter as s, fromVideoDocument as st, partUnionSchema as t, InitialDocumentFacts as tt, applyEntityTimelineProjection as u, CaptionPart as ut, SemanticOpInput as v, TrackItem as vt, SemanticOpKind as w, VideoDocumentValidationIssue as wt, IMPLEMENTED_SEMANTIC_OP_KINDS as x, VideoClipPart as xt, SemanticOpName as y, TrackItemTimePosition as yt, EntityTimelineTrackRole as z };
+export { VoiceDescriptor as $, generatePartId as A, effectiveVideoClipDurationMs as At, ResolvedEntityClipPlacement as B, PlannedSemanticOpKind as C, VideoClipPart as Ct, SnapshotReadable as D, VideoDocumentValidationIssueCode as Dt, SchemaValidator as E, VideoDocumentValidationIssue as Et, videoDocumentMirrorSchema as F, PartAggregation as Ft, EntityTimelineProjectionError as G, ResolvedEntityTrack as H, VideoDocumentValidationError as I, SpeedShift as It, CaptionSegmentSelection as J, EntityRelationRows as K, assertValidVideoDocument as L, Timeline$1 as Lt, TrackItemDraft as M, Attachment as Mt, VideoDocumentDraft as N, CaptionPart$1 as Nt, ValidationError as O, VideoDraft as Ot, VideoDocumentMirrorSchema as P, CaptionStyle as Pt, SequenceRange as Q, validateVideoDocument as R, Track$1 as Rt, ImplementedSemanticOpKind as S, VIDEO_DOCUMENT_SCHEMA_VERSION as St, isImplementedSemanticOpKind as T, VideoDocumentSchemaVersion as Tt, resolveEntityTimelineLayout as U, ResolvedEntityTimelineLayout as V, projectEntityTimeline as W, ScriptTextSegment as X, CaptionStyleFields as Y, SequenceDuration as Z, SemanticEditor as _, SpeechPart as _t, PlainMemoryAdapter as a, DerivedItemPosition as at, TransactAudit as b, TrackItem as bt, MirrorVideoDocumentAdapter as c, derivePositionFromAbs as ct, createMirrorVideoDocument as d, BgmPart as dt, JsonObject as et, createMirrorVideoDocumentAdapter as f, CaptionPart as ft, SemanticDocumentAdapter as g, PartUnion as gt, OpActor as h, PartKind as ht, JournalEntry as i, buildInitialVideoDocument as it, TrackDraft as j, speedOf as jt, PartIdFactory as k, VideoDraftPartUnion as kt, MirrorVideoDocumentOptions as l, fromVideoDocument as lt, CommitOptions as m, ENTITY_TIMELINE_PROJECTION_SCHEMA_VERSION as mt, videoDocumentSchema as n, EntityId as nt, PlainMemoryAdapterOptions as o, SpeechHostMap as ot, writeVideoDocumentToDraft as p, DEFAULT_UNIT_TIME_MS as pt, EntityRow as q, readVideoDocumentFromDraft as r, InitialDocumentFacts as rt, createPlainMemoryAdapter as s, buildSpeechHostMap as st, partUnionSchema as t, JsonValue as tt, applyEntityTimelineProjection as u, toVideoDocument as ut, SemanticOpInput as v, Timeline as vt, SemanticOpKind as w, VideoDocument as wt, IMPLEMENTED_SEMANTIC_OP_KINDS as x, TrackItemTimePosition as xt, SemanticOpName as y, Track as yt, EntityTimelineTrackRole as z, TrackItem$1 as zt };

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-Dxxu0Mi1.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,46 @@ interface MengineEventStreamOptions {
 }
 declare function readMengineEventStream(options: MengineEventStreamOptions): Promise<void>;
 //#endregion
+//#region ../medeo-dsl/src/composition.d.ts
+type ScriptCompositionIssueCode = 'field_conflict' | 'composition_cycle' | 'invalid_bases' | 'composition_missing' | 'composition_ambiguous' | 'composition_dangling' | 'unknown_segment' | 'empty_selection' | 'invalid_script' | 'invalid_selection';
+/** Assembly fails explicitly when declared bases cannot provide valid, unambiguous content. */
+declare class ScriptCompositionError extends Error {
+  readonly code: ScriptCompositionIssueCode;
+  readonly entityId: EntityId;
+  constructor(code: ScriptCompositionIssueCode, entityId: EntityId, message: string);
+}
+interface AssembledCaptionContent {
+  readonly caption: EntityRow<'caption'>;
+  readonly audioScript: EntityRow<'audio-script'>;
+  /** Selected AudioScript segments in Caption selection order. */
+  readonly segments: readonly ScriptTextSegment[];
+  /** Complete display text: the selected segments' text joined in order. */
+  readonly text: string;
+}
+interface AssembledPhoneticScriptContent {
+  readonly phoneticScript: EntityRow<'phonetic-script'>;
+  readonly audioScript: EntityRow<'audio-script'>;
+  /** All AudioScript segments in script order; the pronunciation variant never reorders text. */
+  readonly segments: readonly ScriptTextSegment[];
+  /** Complete base text owned by the AudioScript. */
+  readonly text: string;
+}
+/** Validate all base providers before applying explicit own fields; ordering cannot resolve ambiguity. */
+declare function assembleEntityContent(rows: EntityRelationRows, entityId: EntityId): EntityRow;
+/** Find the actual AudioScript text owner through direct variant bases. */
+declare function findComposedAudioScript(rows: EntityRelationRows, variantEntityId: EntityId, variantKind: 'caption' | 'phonetic-script'): EntityRow<'audio-script'>;
+/** Join the whole AudioScript text in segment order. */
+declare function assembleScriptText(script: EntityRow<'audio-script'>): string;
+/** Assemble selected text after base-field validation and explicit variant overrides. */
+declare function assembleCaptionContent(rows: EntityRelationRows, captionEntityId: EntityId): AssembledCaptionContent;
+/**
+ * Assemble the complete Phonetic Script content for TTS: the composed
+ * AudioScript's base text plus the variant's own phoneme and prosody fields.
+ */
+declare function assemblePhoneticScriptContent(rows: EntityRelationRows, phoneticScriptEntityId: EntityId): AssembledPhoneticScriptContent;
+/** Select source text without creating another authoritative text field. */
+declare function 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 +328,10 @@ interface DeleteClipTreeInput {
 interface VoiceoverCaptionFact {
   /** Stable placed caption identity supplied by the materialized side effect. */
   readonly captionClipEntityId: string;
-  readonly text: string;
+  /** Directly held bases; includes the AudioScript used by the Voice. */
+  readonly baseEntityIds: readonly string[];
+  /** Ordered selection of AudioScript segments; caption text is never passed inline. */
+  readonly selections: readonly CaptionSegmentSelection[];
   readonly startMs: number;
   readonly durationMs: number;
   readonly style?: CaptionStyleFields;
@@ -296,8 +339,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 +416,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 from the PhoneticScript baseEntityIds. */
   readonly audioScriptEntityId: string;
   readonly captionClipEntityIds: readonly string[];
 }
@@ -405,7 +451,10 @@ interface InsertCaptionClipInput {
   readonly timelineEntityId: string;
   /** Stable placed caption identity, distinct from the Caption content identity. */
   readonly captionClipEntityId?: string;
-  readonly text: string;
+  /** Existing bases composed by this variant; includes an AudioScript text owner. */
+  readonly baseEntityIds: readonly string[];
+  /** Ordered selection of the AudioScript segments this Caption displays. */
+  readonly selections: readonly CaptionSegmentSelection[];
   /** Intrinsic cue length of the Caption entity itself; display comes from the placement. */
   readonly durationMs: number;
   readonly style?: CaptionStyleFields;
@@ -490,18 +539,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 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;
-  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;
+  private replaceCaptionAlignment;
+  /**
+   * Remove one placed Caption use. The composed AudioScript outlives the
+   * caption: it may anchor further captions and remains the text owner.
+   */
   private removeCaptionClipGraph;
   private replaceAnchorHost;
   /** Rebuild the legacy edit baseline from current visual order before a high-level cascade. */
@@ -538,8 +595,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 +606,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.
  *
@@ -587,6 +642,17 @@ declare function migrateLegacyTimelineToEntities(legacy: VideoDocument, assetFac
 /** Server gate: a cutover may change representation, never the existing render facts. */
 declare function assertEntityProjectionPreservesLegacy(legacy: VideoDocument, projection: VideoDocument, rows: EntityRelationRows): void;
 //#endregion
+//#region src/entity-editor/caption-content.d.ts
+interface CaptionContentInput {
+  readonly contentEntityId: string;
+  readonly audioScriptEntityId: string;
+  readonly text: string;
+  readonly selections?: readonly CaptionSegmentSelection[];
+  readonly durationMs: number;
+}
+/** Author Caption content from semantic intent; callers never reconcile variant bases or assembled fields. */
+declare function prepareCaptionContent(rows: EntityRelationRows, input: CaptionContentInput): EntityRow<'caption'>;
+//#endregion
 //#region src/editor/journal.d.ts
 /**
  * Wire a plain-memory adapter + editor that share a recording id factory, so
@@ -1491,4 +1557,4 @@ declare function hostForAbsMs(ranges: MainClipRange[], absMs: number): MainClipR
  */
 declare function relativePositionForAbs(ranges: MainClipRange[], absMs: number): TrackItemTimePosition;
 //#endregion
-export { type Aggregation, type Attachment, type 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 CaptionContentInput, type CaptionPart, type CaptionSegmentSelection, type CaptionStyle, type ClipEntityId, type ClipPlacement, type CommitOptions, DEFAULT_UNIT_TIME_MS, type DeleteBgmInput, type DeleteClipInput, type DeleteClipTreeInput, type DeleteVoiceoverInput, type DerivedItemPosition, type DocStorageLike, type DocVersionMark, ENTITY_TIMELINE_PROJECTION_SCHEMA_VERSION, type EditorFoundation, type EntityGraphCommitOptions, EntityGraphHttpClient, type EntityGraphState, EntityTimelineEditor, type EntityTimelineIdFactory, EntityTimelineProjectionError, type EntityTimelineTrackRole, IMPLEMENTED_SEMANTIC_OP_KINDS, type ImageMediaAssetFact, type ImplementedSemanticOpKind, type ImportedMediaAsset, type InitialDocumentFacts, type InsertCaptionClipInput, type InsertClipInput, type InsertMediaClipInput, type InsertMediaClipsInput, type InsertPlacedClipInput, type JournalEntry, LANE_KINDS_IN_STACK_ORDER, type LaneKind, type LinearClipSpeed, type MainClipRange, type MakeEmptyPart, ManualSyncDoc, type ManualSyncDocOptions, MedeoHttpDocStorage, type MedeoHttpDocStorageOptions, type MediaAssetFact, type MediaClipInsertion, MemoryDocStorage, MengineAckFailedError, type MengineAuditEntry, type MengineAuditResponse, MengineDocSession, type MengineDocSessionOptions, type MengineDocSessionUpdateEvent, type MengineDocumentVersion, type MengineEventStreamOptions, MengineHttpClient, type MengineHttpClientOptions, MengineHttpRequestError, MenginePushRejectedError, type MenginePushResponse, type MenginePushUpdateResponse, type MengineRejectedResponse, type MengineSnapshotResponse, type MengineSseUpdateEvent, type MengineSyncResponse, type MengineUpdateMeta, MirrorVideoDocumentAdapter, type MirrorVideoDocumentOptions, type MoveClipInput, type MoveClipsToStartsInput, type MoveSequentialClipsInput, type MoveVoiceoverInput, type OpActor, type PartAggregation, type PartIdFactory, type PartKind, type PartUnion, type PatchCaptionStyleInput, PlainMemoryAdapter, type PlainMemoryAdapterOptions, type PlannedSemanticOpKind, type PullFailureReason, type PullResult, type PushOutcome, type PushOutcomeKind, type PushResult, type PushResultKind, type ReplaceClipContentInput, type ReplaceMediaClipInput, type ReplaceSequentialClipsInput, type ReplacementMediaClipInput, type ResolvedEntityClipPlacement, type ResolvedEntityTimelineLayout, type ResolvedEntityTrack, SchemaValidator, ScriptCompositionError, type SemanticDocumentAdapter, SemanticEditor, type SemanticOpInput, type SemanticOpKind, type SemanticOpName, type SequentialClipAnchor, type SetBgmInput, type SetCaptionVisibilityInput, type SetClipPlacementInput, type SetClipSpeedInput, type SetClipVolumeInput, type SnapshotReadable, type SolvedVideoDocument, type SpeechHostMap, type SpeechPart, type SpeedShift, TIMELINE_SKELETON_DURATION_MS, type Timeline, type TimelineDoc, type TimelineItem, type Track, type TrackDraft, type TrackItem, type TrackItemDraft, type TrackItemTimePosition, type TransactAudit, type TrimClipInput, type UpdateClipInput, type UpdateClipMarkerInput, VIDEO_DOCUMENT_SCHEMA_VERSION, ValidationError, type VideoClipPart, type VideoDocument, type VideoDocumentDraft, type VideoDocumentMirrorSchema, type VideoDocumentSchemaVersion, VideoDocumentValidationError, type VideoDocumentValidationIssue, type VideoDocumentValidationIssueCode, type VideoDraft, type CaptionPart$1 as VideoDraftCaptionPart, type VideoDraftPartUnion, type Timeline$1 as VideoDraftTimeline, type Track$1 as VideoDraftTrack, type TrackItem$1 as VideoDraftTrackItem, type VideoMediaAssetFact, type VisualMediaAssetFact, type VoiceMediaAssetFact, type VoiceoverCaptionFact, type VoiceoverTakeInput, type VoiceoverTakeResult, type WaitForServerAckOptions, applyEntityTimelineProjection, arrangeMainTrackSeamlessly, assembleCaptionContent, assembleEntityContent, assemblePhoneticScriptContent, assembleScriptText, assertCanonicalEditorResources, assertEntityProjectionPreservesLegacy, assertMediaAssetWritePolicy, assertValidVideoDocument, base64ToBytes, buildInitialVideoDocument, buildSpeechHostMap, bytesToBase64, cascadeAfterVideoClipChanges, createEditSandbox, createMirrorVideoDocument, createMirrorVideoDocumentAdapter, createPlainMemoryAdapter, decodeDocVersionMark, derivePositionFromAbs, effectiveVideoClipDurationMs, encodeDocVersionMark, ensureEditorFoundation, ensureLaneTrack, fillMainTrackTimeGaps, findComposedAudioScript, findLaneTrack, fromVideoDocument, generatePartId, getAt, hostForAbsMs, importMediaAsset, isEmptyVideoClip, isImplementedSemanticOpKind, isMap, laneTrackId, mainTrackRanges, migrateLegacyTimelineToEntities, partDurationMs, partUnionSchema, prepareCaptionContent, projectEntityTimeline, readMainTrackItems, readMengineEventStream, readPart, readPartDurationMs, readVideoDocumentFromDraft, reassignSpeechesToVideoClipsByTime, recalculateTimelineDuration, relativePositionForAbs, replayJournal, resolveAllSpeechOverlaps, resolveEntityTimelineLayout, resolveSpeechOverlapByShiftingVideos, safeDurationMs, index_d_exports as schemas, selectAudioScriptSegments, snapshotToPlain, solveVideoDocument, speedOf, syncAggregatedClipsTimePosition, toVideoDocument, validateVideoDocument, videoDocumentMirrorSchema, videoDocumentSchema, writeVideoDocumentToDraft };