@mengine/medeo-client 2.0.1-alpha.4 → 2.0.1-alpha.5

package/README.md

@@ -2,48 +2,113 @@
 
 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.
-
-`MengineDocSession.start()` waits for DocManager to load a local snapshot, or for the first remote sync if no local snapshot exists, then validates the content. A cached document can open before SSE connects; a cold start waits for SSE and the existing sync cycle. Session does not prefetch or import an initial snapshot itself.
-
-`getState().loaded` means the first local load completed. Once loaded, `loadedFromLocal` reports whether that load imported a snapshot, including a valid empty document. It stays unchanged by later edits and remote updates. Document readiness does not depend on metadata or nonempty tracks.
-
-## Local persistence
-
-Browser hosts can inject `IndexedDBDocStorage` through `localStorage`. An optional `initialSnapshot` merges a freshly fetched server snapshot into that storage before DocManager loads it; it never replaces locally saved, unconfirmed edits. The host can require a successful online fetch before constructing the session.
-
-`getLocalSaveState()` / `subscribeLocalSaveState()` report `{ status: 'saving' | 'saved' | 'failed', error }` for this session's local commits. This is separate from `getSyncState()` and server confirmation. The storage adapter determines durability: IndexedDB resolves only after its transaction commits; MemoryDocStorage remains in memory. Failed saves retain their causal order and retry without blocking other documents.
-
-`waitForLocalSave({ timeoutMs? })` waits for the commits present at invocation (default deadline: 15 seconds). Later edits do not extend that target. Timing out only stops the wait; persistence continues. This does not wait for server acknowledgement.
-
-For normal teardown, use `await session.close()`. It immediately rejects new edits and stops synchronization, then keeps local persistence alive until pending commits are saved before releasing connections. Storage failures remain retryable while closing. `destroy()` is immediate cancellation for exceptional teardown, including failed startup; it can discard unpersisted in-memory work. Neither API can guarantee a save after the browser process is forcibly terminated. Only completed local saves survive reopening.
-
-Edits received from another local-storage peer also remain unconfirmed until covered by an authoritative server version. Receiving a cross-tab notification is not a server acknowledgement.
-
-Reopening uses the stored Loro history and the server's version vector to derive missing updates, without replaying semantic operations or their external side effects. Undo history remains limited to the current session.
-
-## Session undo/redo
-
-After `await session.start()`, `session.undo(options?)` and `session.redo(options?)` synchronously apply local history and return whether they produced a document update. `options` accepts the same actor/intent metadata as semantic edits. Read the resulting document through `session.snapshot()`; use `waitForServerAck()` only when durable confirmation is required.
-
-`getUndoState()` returns the current `{ canUndo, canRedo }` immediately. `subscribeUndoState(callback)` immediately provides that state, then coalesces subsequent stack changes in a microtask after mutations settle. Several synchronous commands may produce only one availability notification; use the getter when reading directly after a command. Teardown publishes empty availability synchronously and cancels pending notifications. Dispose the returned subscription with the host. Loading and closed sessions report an empty history; history commands require a ready session.
-
-History belongs to one document/session peer. The loaded baseline and remote imports are not recorded. Each semantic commit is a separate step (up to 100); a new local edit invalidates redo. Reconnecting preserves history, while reopening starts empty. Empty or ineffective history actions return false. Never reuse a peer ID across concurrent sessions.
-
-Use `beginUndoGroup()` / `endUndoGroup()` to combine existing semantic operations into one undo step, or to combine repeated commits during one gesture. Always end in `finally`. Every constituent commit is immediately visible locally and enters synchronization independently; if a later operation fails, earlier commits remain applied. Conflicting remote imports may split/end a group early, and unrelated local edits in the same session would join an open group.
-
-Mirror's draft callback and commit are synchronous. SemanticEditor methods return promises, but their document mutations currently finish synchronously before the promise resolves. Await external asset generation before opening a group, then compose the local semantic operations. Keeping a group open across asynchronous work does not provide transaction isolation, deferred publication, or rollback. If several changes must be atomic, implement one semantic operation with one synchronous draft callback. A gesture that uses only local previews and commits once on release already needs no group.
-
-Flush pending local preview/debounce work before undo/redo. Mutating again from a document-update observer during a mutation is rejected; schedule the next command after the current one returns.
-
-The session assembles SemanticEditor with MirrorVideoDocumentAdapter directly. DocumentUndoManager independently observes the same LoroDoc and owns undo/redo, grouping and audit metadata. Both write paths share a synchronous DocumentMutationGuard; the session closes it before teardown callbacks, and each component releases its own resources. Standalone adapters create their own guard by default and reject use after disposal while leaving the borrowed LoroDoc usable.
-
-Undo/redo append ordinary synchronized updates and retain audit metadata (`Undo`/`Redo`, actor, and `payload.source` identifying an original local change). Existing revision bindings remain immutable. Redo reuses already materialized assets without repeating generation, billing, or attachment requests. Network failures do not automatically reverse history.
-
-Loro history uses new writes: undo on a shared LWW field restores its value before the local edit, potentially overwriting a later remote write to the same field; redo restores the value visible before undo. Unrelated remote fields remain intact. Undoing a local insertion removes the object and makes dependent remote edits invisible until redo restores the object. Caption creation includes its style container, even when empty, so a later style edit only changes fields and undo preserves another peer's independently edited fields. Initial document seeding preserves supplied styles and creates empty maps for captions without styles. No write-time repair or migration of older CRDT documents is provided.
-
-## Large-update resynchronization
-
-`MengineDocSession` handles SSE `event: resync` by scheduling the existing version-vector sync on the current connection. The event carries no Loro bytes and does not create an edit or undo step. A hint arriving while an HTTP sync is in flight schedules another diff so changes newer than that response are still fetched. Low-level users of `readMengineEventStream` can handle the same hint with `onResync`; `MedeoHttpDocStorage` exposes `subscribeResync`.
-
-Deploy this client before enabling server-side resync notifications. Older clients ignore the event. Large HTTP pushes remain valid: the server chooses inline update or resync notification after persistence, rather than requiring client-side fragmentation. Base64 encoding uses `Uint8Array.toBase64()` where available, with a chunked fallback preserving the same padded wire representation.
+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. `ensureEditorFoundation` gets or creates one Timeline and four role Tracks,
+   retaining all existing identities and settings. `importMediaAsset` groups and
+   deduplicates only by direct media variants carrying the same external asset
+   id `(system, key)`. Imports mint exactly one media variant Entity
+   (Video/Image/Audio/Voice) that carries the Asset locator itself; no separate
+   `asset` Entity and no `physical-asset` Relation are created, and the returned
+   identity is that single Entity. Video duration must come from asset
+   metadata, never a clip trim window. Dual-entity media graphs (`asset` row
+   plus a `physical-asset` binding) are not reused and fail explicitly instead
+   of minting a second identity. This policy is local to the MEngine editor, not
+   the general-purpose DSL.
+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.
+
+Repeated placement reuses the same single media identity but creates independent
+Clips and SequenceMarkers. Asset generation alone still does not create editor
+Entities. Two commit-level guards protect the single-identity policy:
+`assertCanonicalEditorResources(rows)` checks one complete state — every media
+variant carries its own external locator, one external asset id has exactly one
+claimant, and no media variant is bound through a `physical-asset` Relation.
+The exported `assertMediaAssetWritePolicy(before, after)` checks one CAS
+transition and is reusable by the host tool and the entity stores: it applies
+the same rules to the complete after state, and a self-carried identity cannot
+be rewritten to another asset id. The editor applies it to every transaction
+and `EntityGraphHttpClient.commit` applies it to `(baseState.rows, nextRows)`
+before any request. There is no historical exemption: dual-entity media graphs
+are rejected rather than kept editable — the shared `decodeEntityRelationRows`
+boundary already fails rows whose media variants lack `external` or carry a
+`physical-asset` binding, so editors and commits never observe them — deleting
+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 text is assembled from its required AudioScript composition. The host may associate Caption with a real text Asset through `physical-asset`, keyed by Caption identity; the sandbox does not manage Assets. The association is optional and does not replace composition. Editing inherited text through Caption advances the AudioScript version and its base reference, preserving the Caption ID unless its own fields change.
+
+`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 and Caption can be independently
+placed or explicitly anchored; generation relations do not choose a host. `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.
+
+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 one `selection` object; its optional `captionEntityId` preserves a generation-provided business identity independently of `captionClipEntityId`. The 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.
+
+`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.
+
+### 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.