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

package/README.md

@@ -44,8 +44,7 @@ boundary already fails rows whose media variants lack `external` or carry a
 media is an explicit caller decision, and no implicit historical merge or
 identity rewriting occurs. The
 compatibility reader reads physical facts directly from the media variant;
-Caption inline text still resolves its inline Asset through
-`physical-asset`.
+Caption text is assembled from its required AudioScript composition and never stored in an inline Asset.
 
 `SequenceMarker` owns source/target ranges, duration, and time remapping. `Clip`
 owns clip properties such as volume; `Track` owns track properties. References
@@ -74,15 +73,25 @@ their follow, keep-absolute, cascade, or detach decisions into the same entity
 plan. A speech-overlap shift is explicit placement on the real visual Clips;
 an uncovered time interval does not require an invented empty-media entity.
 
-Voice links to its AudioScript through `audio-script-render`; Caption links to
-its source script and optional alignment Voice through separate provenance/alignment relations. External
-speech identity and physical storage key belong to the Voice Entity itself.
-`insertCaptionClip` creates a complete independent Caption placement;
-`upsertVoiceoverTake` accepts explicit `placement` for independent voice.
-AudioScript carries only text. `audio-script-marker` attaches directly assigned
-`segmentRanges` timing; those annotation Markers cannot be Clip display Markers.
-Caption styles belong to Caption; text can have a real inline text Asset rather
-than a fabricated Memota ID. Background Audio's Marker declares
+Generated Voice links to a pre-existing PhoneticScript through `phonetic-script-render`.
+Caption and PhoneticScript each compose a real AudioScript by directly holding `baseEntityIds`, an array that may compose multiple entities. AudioScript owns
+`segments[].text`; assembly never automatically persists a copy on the variants. Read complete content
+with `assembleCaptionContent` or `assemblePhoneticScriptContent`. Broken composition
+fails explicitly. Same-name fields from different bases are rejected even for equal values and even if the variant declares that field. After base fields are unambiguous, explicit own fields may override them without mutating the bases. Recorded Audio/Video/Voice can be the ASR source via
+`audio-script-source`, without creating a synthesis variant.
+
+`insertCaptionClip` requires `baseEntityIds` and `selections`. Each selection
+names a source `segmentId` and optionally a half-open Unicode code-point
+`textRange: {start, end}`. This permits display re-segmentation without rewriting
+the original script. `upsertVoiceoverTake` requires the real
+`phoneticScriptEntityId` used for synthesis; its captions supply their own `baseEntityIds` and select the same script.
+External speech identity and storage key stay on Voice.
+
+AudioScript has no intrinsic Sequence and cannot enter a Clip. `audio-script-marker`
+attaches directly assigned `segmentRanges` timing; annotation Markers never refer
+to upstream Markers and cannot be Clip display Markers. Moving or aligning a
+Caption changes its external display Marker, preserving intrinsic Caption extent.
+Caption owns its styles and text selection. Background Audio's Marker declares
 `durationPolicy: 'timeline'`: its source duration stays factual,
 while the view fills the non-BGM timeline duration.
 
@@ -97,3 +106,9 @@ It rejects `video-document/entity-projection-v1` documents. Production entity
 tools and editor adapters must not fall back to it or raw `/updates` on failure.
 For an entity projection, `meta.version` is the committed entity revision; the
 Loro version vector remains the transport-sync cursor.
+
+### Transparent variant fields in the DSL sandbox
+
+`entities.get/list` return complete assembled fields. Consumers do not query base IDs or merge source payloads. `entities.update` patches supplied fields, preserves omitted fields, and routes inherited fields to their declaring entity. Explicit own-field declarations use `entities.declareFields`; these override unambiguous base fields without changing the base. Persisted entity rows and command payloads contain owned fields only. Base collisions are validated before own overrides.
+
+`prepareCaptionContent` accepts caption authoring intent and handles source composition, visible text selection, and preservation of existing intrinsic timing inside the SDK.