@mengine/medeo-client 2.1.1-dsl.8 → 3.0.0

package/README.md

@@ -16,16 +16,14 @@ const [clipId] = session.editor.addClips({
 session.editor.setClipVolume(clipId, -3, { actor: { user_id: userId, role: 'user' } });
 await session.waitForServerAck(); // Local completion is separate from durable confirmation.
 const { content, diagnostics } = session.projectVideoDraft();
-session.destroy();
+await session.close();
 ```
 
 `start()`, `snapshot()` and subscription events expose `MedeoDslSnapshot`. `session.dsl` exposes controlled `transact`/`applyMutations`; ordinary business callers use `session.editor`. Rich text uses the native text adapter. `readonlyMode` blocks editing and Undo/Redo. Closing a session also invalidates captured editor/document references.
 
-For explicit synchronization, use `ManualSyncDoc.open({client, peerId})`, then `pull()`, `editor`, `push()` and `dispose()`. Both lifecycles use the same binary snapshot/update and version-coverage contracts. Neither silently upgrades old documents or overwrites an incompatible cache.
-
 ## 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.
+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 incoming snapshot and combined local history are format-checked before the merge is persisted. 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.
 
@@ -37,6 +35,8 @@ Edits received from another local-storage peer also remain unconfirmed until cov
 
 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.
 
+For explicit synchronization, use `ManualSyncDoc.open({client, peerId})`, then `pull()`, `editor`, `push()` and `dispose()`. Both lifecycles use the same binary snapshot/update and version-coverage contracts. Neither silently upgrades old documents or overwrites an incompatible cache.
+
 ## Editing and conversion
 
 - Track: create, reorder, hide and delete.
@@ -44,13 +44,14 @@ Reopening uses the stored Loro history and the server's version vector to derive
 - Placement: sequential, absolute or anchored. Reordering and replacement require an explicit associated-content policy.
 - Voiceover: `applyVoiceover` consumes materialized recording/script/caption results in one commit. Upload, ASR and TTS belong to the host.
 - BGM: `setBgm` requires full resource facts and explicitly fills the Timeline; trim/speed are not enabled.
-- Caption: independent native Text or AudioScript Cursor reference; style and source switching.
+- AudioScript: segmented text; segments are inserted, moved and deleted by id, each with its own native Text. A transcript names the transcription file it was read from, and its segments keep the `startMs`/`endMs` that file gave them (`tx.insertSegment(..., time)`); a segment's time is written when it is added and never edited.
+- Caption: independent native Text or a selection of one script segment (whole, or a Cursor run inside it); style and source switching.
 
-`resolveDslLayout`, `toVideoDraft`, `fromVideoDraft`, `MedeoDsl` and the model types are exported from the root and `/dsl`. Projection returns diagnostics; unrepresentable legacy output throws `DslProjectionError`. `MengineHttpClient.fetchDraft()` / `fetchDraftAt(seq)` read the server's content, diagnostics and matching version.
+`resolveDslLayout`, `toVideoDraft`, `fromVideoDraft`, `toAudioScriptViews`, `MedeoDsl` and the model types are exported from the root and `/dsl`. `toAudioScriptViews` (on a session, `projectAudioScripts()`) reads the same snapshot as the VideoDraft and lists every AudioScript with its segments — a transcript's with their `startMs`/`endMs` and a `timelineMs`, the position on the earliest Clip playing the transcribed medium whose window holds that moment — its PhoneticScripts with their digests, the speech Clips saying it (with `applied`) and the Caption Clips showing one of its segments. Projection returns diagnostics; unrepresentable legacy output throws `DslProjectionError`. `MengineHttpClient.fetchDraft()` / `fetchDraftAt(seq)` read the server's content, diagnostics and matching version.
 
 ## The DSL document
 
-The live document lives here: `src/dsl/document` holds the `MedeoDsl` handle, transactions, draft guards and native reads; `src/dsl/projection` holds layout solving, VideoDraft conversion and the generated IDL types. Definitions, the Loro schema and change constraints come from the private `@mengine/medeo-dsl` and are re-exported by name, so the published API does not grow when the DSL does. Transactions ask the DSL's constraint functions; only what needs a live Loro document — caption ranges in the current body, Tree identities, Mirror's K03 limit — is checked here. See [RFC 04](../../docs/projects/medeo-dsl/rfc/04-entity-relation-to-loro-mapping.md).
+The live document lives here: `src/dsl/document` holds the `MedeoDsl` handle, transactions, draft guards and native reads; `src/dsl/projection` holds layout solving, VideoDraft conversion and the generated IDL types. Definitions, the Loro schema and change constraints come from the private `@mengine/medeo-dsl` and are re-exported by name, so the published API does not grow when the DSL does. Transactions ask the DSL's constraint functions; only what needs a live Loro document — selections of a segment's current text, Tree identities, Mirror's K03 limit — is checked here. See [RFC 04](../../docs/projects/medeo-dsl/rfc/04-entity-relation-to-loro-mapping.md).
 
 ### Using the editor
 
@@ -86,10 +87,10 @@ dsl.dispose();
 - `getSnapshot()` returns a frozen, read-only `MedeoDslSnapshot`: entity tables, the voice-timbre and derived-from relation tables, effective containment, rich-text runs, resolved Caption text and diagnostics. A relation an entity holds at most one of is a field of its row: a Clip's `source` and `anchor`, a Caption's `selection`, a PhoneticScript's `phoneme`. An unreadable optional field is dropped from the row with a diagnostic; the row stays. A Caption's own text wins over its selection when a merge leaves both. It does not compute layout or VideoDraft. Reads reuse the same snapshot until a DSL content event invalidates it; no-op Actions and repeated imports retain it. Reading never commits changes.
 - `subscribe(listener)` includes text-only and marks-only changes. The returned function unsubscribes; dispose is idempotent. As with other synchronous document observers, listeners should not throw or initiate nested writes.
 - `applyMutations(mutations, audit)` is the preferred interface for typed entity, relation, Tree, Text and Caption-selection commands. It opens one `transact`; `tx.applyMutations` inside an existing callback uses the same draft and commit.
-- `transact(edit, audit)` exposes a guarded `tx.draft` for ordinary fields and Tree, `tx.editText(scriptId, edits, expectedBodyId?)`, `tx.editCaptionText(captionId, edits, expectedBodyId?)`, and `tx.setCaptionContent({captionId, audioScriptId, start, end})`. The synchronous callback and every draft reference expire on return. Async callbacks, nested writes, identity changes, direct overwrites of existing bodies, and same-transaction entity deletion/recreation are rejected. Catching a guard/command error inside the callback does not allow a partial commit.
-- `editText(scriptId, expectedBodyId, edits, audit)` delegates to the same transaction. Text supports insert/delete/mark/unmark/editing Delta; offsets are UTF-16 and cannot split surrogate pairs. `tx.draft` exposes the text preview after preceding edits, while existing body strings are never sent through Mirror's full-text diff. A supplied body identity must match the current Text; Actions editing an existing body retain that stale-view check.
+- `transact(edit, audit)` exposes a guarded `tx.draft` for ordinary fields and Tree, `tx.editText(scriptId, segmentId, edits, expectedBodyId?)`, `tx.editCaptionText(captionId, edits, expectedBodyId?)`, `tx.insertSegment(scriptId, segmentId, text, index?, time?)` / `tx.moveSegment` / `tx.deleteSegment`, `tx.setCaptionContent({captionId, audioScriptId, segmentId, start?, end?})` and `tx.setPhoneme({phoneticScriptId, audioScriptId, segmentId, start?, end?, phonemeScript?})`. The synchronous callback and every draft reference expire on return. Async callbacks, nested writes, identity changes, direct overwrites of existing bodies, and same-transaction entity deletion/recreation are rejected. Catching a guard/command error inside the callback does not allow a partial commit.
+- `editText(scriptId, segmentId, expectedBodyId, edits, audit)` delegates to the same transaction. Text supports insert/delete/mark/unmark/editing Delta; offsets are UTF-16 and cannot split surrogate pairs. `tx.draft` exposes the text preview after preceding edits, while existing body strings are never sent through Mirror's full-text diff. A supplied body identity must match the current Text; Actions editing an existing body retain that stale-view check.
 - Caption selections are interpreted at their position in the command sequence. Their Cursors are created after earlier native edits, and follow later edits. New selections are deferred commands, not synthetic Cursor values in `tx.draft`; do not read a Caption's `selection` from the draft to retrieve a pending one. Explicit Cursor values written to `selection`, and its removal, also replay in sequence with Text edits.
-- `textRange(scriptId, start, end)` returns native Cursors for a nonempty continuous selection. A Caption's `selection` stores their native bytes through the central codec. The permanent first-boundary limitation remains deferred.
+- `textRange(scriptId, segmentId, start, end)` returns native Cursors for a nonempty run inside one segment. A Caption's `selection` stores their native bytes through the central codec. The permanent first-boundary limitation remains deferred.
 
 Every business write requires a structured `DslAudit`: `{semantic_op, payload, intent?, actor?}`. The transaction exit serializes the existing server envelope exactly once; initialization alone uses an internal unaudited path. No-op transactions add no history. External pending native operations must be committed separately first. Known preparation failures write nothing; unexpected native/runtime failures do not receive database-style rollback.
 
@@ -101,11 +102,11 @@ const audit = {
 };
 
 dsl.transact((tx) => {
-  tx.draft['audio-script-entities']['script-1'] = { body: 'hello' };
+  tx.draft['audio-script-entities']['script-1'] = { segments: [{ id: 'segment-1', text: 'hello' }] };
   tx.draft['caption-entities']['caption-1'] = {};
-  tx.editText('script-1', [{ type: 'insert', at: 5, text: ' world' }]);
+  tx.editText('script-1', 'segment-1', [{ type: 'insert', at: 5, text: ' world' }]);
   // Reads the prepared preview: "hello world". The native Text does not yet exist.
-  tx.setCaptionContent({ captionId: 'caption-1', audioScriptId: 'script-1', start: 0, end: 5 });
+  tx.setCaptionContent({ captionId: 'caption-1', audioScriptId: 'script-1', segmentId: 'segment-1', start: 0, end: 5 });
 }, audit);
 ```
 
@@ -153,11 +154,11 @@ try {
 
 Caption text is matched forward in `speech.caption_ids` order. A failed exact match preserves the text in the Caption's own optional **LoroText**, without advancing the match cursor or inventing another AudioScript. Inline text is also available through `DslEditor.createCaption({text, style?})`, `setCaptionText`, and `editCaptionText`. Switching to a reference clears the inline field in the same transaction; direct `transact` callers must clear the other source explicitly. Concurrent coexistence reads the reference, even when it later becomes invalid (no stale-text fallback).
 
-`richText` is keyed by AudioScript or inline Caption entity ID; `captionText` resolves either content source. Optional Caption Texts have ordinary identities and are created in the native hook, preserving mergeable style/font while avoiding duplicate text on mergeable-Text deletion Undo. See [RFC 02](../../docs/projects/medeo-dsl/rfc/02-videodraft-projection.md) for layout, import normalization and compatibility limits.
+`richText` is keyed by script segment ID or inline Caption entity ID; `captionText` resolves either content source and `phoneticText` what each PhoneticScript selects. Optional Caption Texts have ordinary identities and are created in the native hook, preserving mergeable style/font while avoiding duplicate text on mergeable-Text deletion Undo. See [RFC 02](../../docs/projects/medeo-dsl/rfc/02-videodraft-projection.md) for layout, import normalization and compatibility limits.
 
-## Legacy consumers
+## Current entrypoints
 
-`SemanticEditor`, `VideoDocument`, their adapters and old timeline projection have been removed. `@mengine/medeo-client/legacy` retains only the old EntityTimelineEditor, entity transport and its direct VideoDraft projection. Old entity tool/sandbox imports use this entry until their business adaptation is implemented. The obsolete timeline-journal replay rejects nonempty plans before writing. They cannot open new DSL documents. `/schemas` remains the old tool's schema contract, not the new Editor input model.
+`SemanticEditor`, `VideoDocument`, `EntityTimelineEditor`, the old entity CRDT and their projections have been removed, along with `/legacy` and the old `/schemas` input contract. The current `ManualSyncDoc` remains the tool's explicit pull/push document handle over `MedeoDsl` and `DslEditor`; its shared transport is retained. The sandbox contract lives in medeo-dsl and is implemented by medeo-tool.
 
 `/relay` and `/testing` remain host/test-only entrypoints. The private DSL package is bundled into the client distribution.