@mengine/medeo-client 2.1.1-dsl.7 → 2.1.1-dsl.9

package/README.md

@@ -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.
+- 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.
 
 ## 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` / `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,7 +154,7 @@ 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