@mengine/medeo-client 1.3.1-alpha.8 → 1.4.0

package/README.md

@@ -2,113 +2,24 @@
 
 Medeo domain client for the `mengine` document path.
 
-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.
+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.
 
-For entity-authoritative documents:
+## Session undo/redo
 
-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.
+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.
 
-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 and never stored in an inline Asset.
+`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.
 
-`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.
+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.
 
-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.
+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.
 
-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.
+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.
 
-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.
+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.
 
-`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.
+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.
 
-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.
+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.
 
-`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.
+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.