@mengine/medeo-client 1.2.1-alpha.7 → 1.2.1-alpha.8

package/README.md

@@ -2,4 +2,66 @@
 
 Medeo domain client for the `mengine` document path.
 
-This package owns the shared `VideoDocument` contract, semantic editing layer, and runtime-neutral HTTP/SSE client used by medeo-web, agent-harness, and server-side validation code. UI adapters such as `DraftMutationDriver` stay in product repositories.
+This package owns graph-native Medeo editing, its one-way `VideoDocument`
+compatibility projection, and the runtime-neutral HTTP/SSE clients. UI intent
+adapters stay in product repositories; Harness only supplies environment and
+asset facts, not an entity store implementation.
+
+For entity-authoritative documents:
+
+1. `EntityGraphHttpClient.fetchState()` obtains the complete graph and revision.
+2. `importMediaAsset` reuses or creates media/Asset bindings from recalled facts.
+   Video duration must come from asset metadata, never a clip trim window. Asset
+   and media entities are not one-to-one; ambiguous graphs require an explicit
+   `MediaAssetSelection` (fourth argument), not an arbitrary first match.
+3. `EntityTimelineEditor` edits Clip/Marker/Track relations and payloads.
+4. `EntityGraphHttpClient.commit(baseState, nextRows)` performs revision CAS,
+   including explicit net deletions. The server writes entities and the derived
+   Loro read view in the same transaction.
+
+`SequenceMarker` owns source/target ranges, duration, and time remapping. `Clip`
+owns clip properties such as volume; `Track` owns track properties. References
+between entities belong in Relations, not in payload IDs. There is no separate
+timing profile. The compatibility reader supports the existing four lanes:
+one image/video main track, Voice, Caption, and background Audio. It accepts
+explicit millisecond media coordinates and linear visual remapping
+`{ kind: 'linear', rate: 2 }` (including still-image display speed). Nonlinear
+speed and multiple visual overlay tracks are not existing editor capabilities
+and remain outside this adapter; unsupported layouts fail before persistence.
+Effective duration and absolute target coordinates must be whole milliseconds
+for this reader; generic DSL coordinates are not globally restricted to that
+unit or precision. Sequential placement stays `Clip.order` plus no targetRange,
+so later duration edits continue to move following Clips.
+
+Entity-authoritative editor consumers use the Loro session only to receive the
+server-authored compatibility view. Configure that session as read-only: even
+cold-start reconciliation must not POST legacy `/updates`. Entity writes use
+the independent graph CAS endpoint.
+
+Anchored placement is a `clip-anchor` Relation from child Clip to host Clip
+plus `SequenceMarker.anchorOffset`. Voice anchors to a visual Clip; Caption
+anchors to a Voice Clip. `resolveEntityTimelineLayout` resolves this graph
+without reparenting or synthesizing content. Move/delete operations must write
+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
+the same script and Voice through provenance/alignment relations. External
+speech identity and physical storage key belong to Asset, separately from the
+placed Clip identity. Caption styles belong to Caption; text can have a real
+inline text Asset rather than a fabricated Memota ID. Background Audio's
+Marker declares `durationPolicy: 'timeline'`: its source duration stays factual,
+while the view fills the non-BGM timeline duration.
+
+`migrateLegacyTimelineToEntities` is a one-time migration utility, **not** an
+ordinary editing diff adapter. A configured legacy document requires a separate
+CAS commit with `migrationBaseVv` equal to its current canonical base64 Loro
+oplog version. The server calls `assertEntityProjectionPreservesLegacy` to reject
+stale or lossy migrations. Only then can a new edit be committed.
+
+The legacy `SemanticEditor` remains available for pre-cutover library consumers.
+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.