@mengine/medeo-client 1.1.0 → 1.2.1-alpha.0

package/dist/index.d.ts

@@ -1,7 +1,8 @@
-import { $ as VideoDocumentValidationIssue, A as assertValidVideoDocument, B as BgmPart, C as index_d_exports, D as VideoDocumentMirrorSchema, E as VideoDocumentDraft, F as SpeechHostMap, G as Timeline, H as PartKind, I as buildSpeechHostMap, J as TrackItemTimePosition, K as Track, L as derivePositionFromAbs, M as InitialDocumentFacts, N as buildInitialVideoDocument, O as videoDocumentMirrorSchema, P as DerivedItemPosition, Q as VideoDocumentSchemaVersion, R as fromVideoDocument, S as ValidationError, T as TrackItemDraft, U as PartUnion, V as CaptionPart, W as SpeechPart, X as VideoClipPart, Y as VIDEO_DOCUMENT_SCHEMA_VERSION, Z as VideoDocument, _ as PlannedSemanticOpKind, a as MirrorVideoDocumentOptions, at as CaptionStyle, b as SchemaValidator, c as CommitOptions, ct as Timeline$1, d as SemanticEditor, et as VideoDocumentValidationIssueCode, f as SemanticOpInput, g as ImplementedSemanticOpKind, h as IMPLEMENTED_SEMANTIC_OP_KINDS, i as MirrorVideoDocumentAdapter, it as CaptionPart$1, j as validateVideoDocument, k as VideoDocumentValidationError, l as OpActor, lt as Track$1, m as TransactAudit, n as videoDocumentSchema, nt as VideoDraftPartUnion, o as createMirrorVideoDocument, ot as PartAggregation, p as SemanticOpName, q as TrackItem, r as readVideoDocumentFromDraft, rt as Attachment, s as createMirrorVideoDocumentAdapter, st as SpeedShift, t as partUnionSchema, tt as VideoDraft, u as SemanticDocumentAdapter, ut as TrackItem$1, v as SemanticOpKind, w as TrackDraft, x as SnapshotReadable, y as isImplementedSemanticOpKind, z as toVideoDocument } from "./index-BUKA3L7o.js";
+import { t as index_d_exports } from "./index-InEWX9rk.js";
+import { $ as Track, A as TrackDraft, B as DerivedItemPosition, C as SemanticOpKind, D as ValidationError, E as SnapshotReadable, F as VideoDocumentValidationError, G as toVideoDocument, H as buildSpeechHostMap, I as assertValidVideoDocument, J as DEFAULT_UNIT_TIME_MS, K as BgmPart, L as validateVideoDocument, M as VideoDocumentDraft, N as VideoDocumentMirrorSchema, O as PartIdFactory, P as videoDocumentMirrorSchema, Q as Timeline, R as InitialDocumentFacts, S as PlannedSemanticOpKind, T as SchemaValidator, U as derivePositionFromAbs, V as SpeechHostMap, W as fromVideoDocument, X as PartUnion, Y as PartKind, Z as SpeechPart, _ as SemanticOpInput, _t as Timeline$1, a as PlainMemoryAdapter, at as VideoDocumentSchemaVersion, b as IMPLEMENTED_SEMANTIC_OP_KINDS, c as MirrorVideoDocumentAdapter, ct as VideoDraft, d as createMirrorVideoDocumentAdapter, dt as speedOf, et as TrackItem, f as writeVideoDocumentToDraft, ft as Attachment, g as SemanticEditor, gt as SpeedShift, h as SemanticDocumentAdapter, ht as PartAggregation, i as JournalEntry, it as VideoDocument, j as TrackItemDraft, k as generatePartId, l as MirrorVideoDocumentOptions, lt as VideoDraftPartUnion, m as OpActor, mt as CaptionStyle, n as videoDocumentSchema, nt as VIDEO_DOCUMENT_SCHEMA_VERSION, o as PlainMemoryAdapterOptions, ot as VideoDocumentValidationIssue, p as CommitOptions, pt as CaptionPart$1, q as CaptionPart, r as readVideoDocumentFromDraft, rt as VideoClipPart, s as createPlainMemoryAdapter, st as VideoDocumentValidationIssueCode, t as partUnionSchema, tt as TrackItemTimePosition, u as createMirrorVideoDocument, ut as effectiveVideoClipDurationMs, v as SemanticOpName, vt as Track$1, w as isImplementedSemanticOpKind, x as ImplementedSemanticOpKind, y as TransactAudit, yt as TrackItem$1, z as buildInitialVideoDocument } from "./index-BO2fSUKi.js";
 import { PeerID } from "loro-crdt";
 import { DocState } from "@mengine/sync";
-import { BaseDocStorage, Connection, DocDiff, DocSnapshotRecord, DocStorage, DocStorageOptions, DocUpdate, DocUpdateRecord } from "@mengine/storage";
+import { BaseDocStorage, Connection, DocDiff, DocPushReceipt, DocSnapshotRecord, DocStorage, DocStorageOptions, DocUpdate, DocUpdateRecord } from "@mengine/storage";
 
 //#region src/client/base64.d.ts
 declare function bytesToBase64(bytes: Uint8Array): string;
@@ -177,33 +178,23 @@ interface MengineEventStreamOptions {
 }
 declare function readMengineEventStream(options: MengineEventStreamOptions): Promise<void>;
 //#endregion
-//#region src/editor/id-gen.d.ts
+//#region src/editor/journal.d.ts
 /**
- * Part-id generation, aligned with the online ecosystem.
- *
- * The authoritative online producers — agent-harness (`@harness/shared`
- * `genObjId`) and director.v2 (`common/obj_id.py` `gen_obj_id`) — both mint part
- * ids as `` `${prefix}_${ulid()}` ``, and real captured drafts use exactly that
- * shape (`clip_…` / `spe_…` / `cap_…` / `bgm_…`, each a 26-char ULID). The engine
- * previously emitted `vc_<base36 timestamp><6 random>`, a different prefix AND a
- * different encoding — the sole cross-repo id divergence. This module removes it
- * by emitting the same `<prefix>_<ULID>` bytes.
- *
- * The ULID is generated inline (Crockford Base32, 48-bit time + 80-bit random)
- * rather than pulling the `ulid` npm package: the randomness class matches the
- * old generator (both `Math.random`-based) and it keeps `@mengine/medeo-client`
- * dependency-free for a purely mechanical id string. Part ids only need to be
- * unique and lexicographically time-sortable, which this satisfies.
+ * Wire a plain-memory adapter + editor that share a recording id factory, so
+ * every mutating transact lands in `journal` with ordered `generated_ids`.
  */
+declare function createEditSandbox(document: VideoDocument, options?: PlainMemoryAdapterOptions): {
+  adapter: PlainMemoryAdapter;
+  editor: SemanticEditor;
+  journal: readonly JournalEntry[];
+};
 /**
- * Online part-id semantic prefixes. `clip` (video clip) is the only value the
- * engine currently mints (see `addVideoClips`); the rest are declared so the
- * type documents the shared vocabulary and guards against reintroducing the old
- * `vc`/`sp`/`cp`/`bg` names. Speech/caption/bgm ids arrive pre-minted in op
- * payloads, so the engine never generates them itself.
+ * Re-drive `doc` from a recorded journal, forcing each entry's `generated_ids`
+ * through a queue-backed id factory. Never mints fresh ids: an empty queue on
+ * demand throws `unrecorded id`; leftover ids after an entry throws
+ * `unconsumed ids`. Legacy entries without `generated_ids` are treated as `[]`.
  */
-type PartIdPrefix = 'clip' | 'spe' | 'cap' | 'bgm' | 'ti';
-declare function generatePartId(prefix: PartIdPrefix): string;
+declare function replayJournal(doc: SemanticDocumentAdapter, journal: readonly JournalEntry[]): Promise<void>;
 //#endregion
 //#region src/editor/snapshot-utils.d.ts
 /** Main-track item identity read from a raw snapshot (only `part_id` is needed). */
@@ -549,19 +540,24 @@ declare class MedeoHttpDocStorage implements DocStorage {
   getDoc(docId: string): Promise<DocSnapshotRecord | null>;
   getDocDiff(docId: string, knownVersion?: Uint8Array): Promise<DocDiff | null>;
   /**
-   * Forward one update to the server.
+   * Forward one update to the server, returning what the server says it now holds.
+   *
+   * The returned `server_vv` is the server's own statement about itself, computed
+   * inside the write transaction. A caller tracking "what the remote has" can
+   * adopt it directly, which is strictly better than inferring that bound from
+   * the pushed blob: it also covers ops other peers wrote, so those stop being
+   * re-sent on every later push. `ack` and `duplicate` both carry it.
    *
-   * The `DocStorage` contract returns `void`, so the server's verdict cannot be
-   * the return value — it is published on {@link subscribePushOutcome} instead,
-   * for BOTH outcomes and failures. That channel is what makes the push
-   * observable; previously the verdict was read and dropped, so a `duplicate`
-   * (bytes contributed nothing) was indistinguishable from a successful write.
+   * The verdict itself stays on {@link subscribePushOutcome}, which reports
+   * failures too — a return value cannot. Previously the verdict was read and
+   * dropped, so a `duplicate` (bytes contributed nothing) was indistinguishable
+   * from a successful write.
    *
    * The error is still rethrown after being published: the synchronizer treats a
    * throw as "retry this cycle", and swallowing it here would strand the update.
    * Publishing is therefore additive observability, not error handling.
    */
-  pushDocUpdate(update: DocUpdate, _origin: unknown): Promise<void>;
+  pushDocUpdate(update: DocUpdate, _origin: unknown): Promise<DocPushReceipt>;
   /**
    * Observe the server's verdict for every pushed update, including failures.
    *
@@ -708,6 +704,18 @@ declare class MengineDocSession {
    * step. The committed change drives DocManager's local-update push.
    */
   get editor(): SemanticEditor;
+  /**
+   * Opaque version token of the local oplog (base64 `VersionVector.encode`).
+   * Equality-comparable only: equal means no observed change (local or
+   * remote-arrived) since the token was taken. Throws when not started.
+   */
+  version(): string;
+  /**
+   * The live document adapter, exposed for journal replay (commit channel).
+   * Replaying through it still goes SemanticEditor → Loro → mengine-server —
+   * no write bypass. Typed by the narrow interface on purpose.
+   */
+  get documentAdapter(): SemanticDocumentAdapter;
   /** Current document snapshot (read model). */
   snapshot(): VideoDocument;
   /**
@@ -750,7 +758,7 @@ declare class MemoryDocStorage extends BaseDocStorage {
   readonly connection: Connection;
   private readonly entries;
   constructor(options?: DocStorageOptions);
-  pushDocUpdate(update: DocUpdate, origin: unknown): Promise<void>;
+  pushDocUpdate(update: DocUpdate, origin: unknown): Promise<DocPushReceipt>;
   deleteDoc(docId: string): Promise<void>;
   protected getDocSnapshot(docId: string): Promise<DocSnapshotRecord | null>;
   protected setDocSnapshot(snapshot: DocSnapshotRecord): Promise<boolean>;
@@ -1059,4 +1067,4 @@ declare function hostForAbsMs(ranges: MainClipRange[], absMs: number): MainClipR
  */
 declare function relativePositionForAbs(ranges: MainClipRange[], absMs: number): TrackItemTimePosition;
 //#endregion
-export { type Aggregation, type Attachment, type BgmPart, type CaptionPart, type CaptionStyle, type CommitOptions, type DerivedItemPosition, type DocStorageLike, type DocVersionMark, IMPLEMENTED_SEMANTIC_OP_KINDS, type ImplementedSemanticOpKind, type InitialDocumentFacts, LANE_KINDS_IN_STACK_ORDER, type LaneKind, type MainClipRange, type MakeEmptyPart, ManualSyncDoc, type ManualSyncDocOptions, MedeoHttpDocStorage, type MedeoHttpDocStorageOptions, MemoryDocStorage, MengineAckFailedError, type MengineAuditEntry, type MengineAuditResponse, MengineDocSession, type MengineDocSessionOptions, type MengineDocSessionUpdateEvent, type MengineDocumentVersion, type MengineEventStreamOptions, MengineHttpClient, type MengineHttpClientOptions, MengineHttpRequestError, MenginePushRejectedError, type MenginePushResponse, type MenginePushUpdateResponse, type MengineRejectedResponse, type MengineSnapshotResponse, type MengineSseUpdateEvent, type MengineSyncResponse, type MengineUpdateMeta, MirrorVideoDocumentAdapter, type MirrorVideoDocumentOptions, type OpActor, type PartAggregation, type PartKind, type PartUnion, type PlannedSemanticOpKind, type PullFailureReason, type PullResult, type PushOutcome, type PushOutcomeKind, type PushResult, type PushResultKind, SchemaValidator, type SemanticDocumentAdapter, SemanticEditor, type SemanticOpInput, type SemanticOpKind, type SemanticOpName, type SnapshotReadable, type SolvedVideoDocument, type SpeechHostMap, type SpeechPart, type SpeedShift, TIMELINE_SKELETON_DURATION_MS, type Timeline, type TimelineDoc, type TimelineItem, type Track, type TrackDraft, type TrackItem, type TrackItemDraft, type TrackItemTimePosition, type TransactAudit, VIDEO_DOCUMENT_SCHEMA_VERSION, ValidationError, type VideoClipPart, type VideoDocument, type VideoDocumentDraft, type VideoDocumentMirrorSchema, type VideoDocumentSchemaVersion, VideoDocumentValidationError, type VideoDocumentValidationIssue, type VideoDocumentValidationIssueCode, type VideoDraft, type CaptionPart$1 as VideoDraftCaptionPart, type VideoDraftPartUnion, type Timeline$1 as VideoDraftTimeline, type Track$1 as VideoDraftTrack, type TrackItem$1 as VideoDraftTrackItem, type WaitForServerAckOptions, arrangeMainTrackSeamlessly, assertValidVideoDocument, base64ToBytes, buildInitialVideoDocument, buildSpeechHostMap, bytesToBase64, cascadeAfterVideoClipChanges, createMirrorVideoDocument, createMirrorVideoDocumentAdapter, decodeDocVersionMark, derivePositionFromAbs, encodeDocVersionMark, ensureLaneTrack, fillMainTrackTimeGaps, findLaneTrack, fromVideoDocument, generatePartId, getAt, hostForAbsMs, isEmptyVideoClip, isImplementedSemanticOpKind, isMap, laneTrackId, mainTrackRanges, partDurationMs, partUnionSchema, readMainTrackItems, readMengineEventStream, readPart, readPartDurationMs, readVideoDocumentFromDraft, reassignSpeechesToVideoClipsByTime, recalculateTimelineDuration, relativePositionForAbs, resolveAllSpeechOverlaps, resolveSpeechOverlapByShiftingVideos, safeDurationMs, index_d_exports as schemas, snapshotToPlain, solveVideoDocument, syncAggregatedClipsTimePosition, toVideoDocument, validateVideoDocument, videoDocumentMirrorSchema, videoDocumentSchema };
+export { type Aggregation, type Attachment, type BgmPart, type CaptionPart, type CaptionStyle, type CommitOptions, DEFAULT_UNIT_TIME_MS, type DerivedItemPosition, type DocStorageLike, type DocVersionMark, IMPLEMENTED_SEMANTIC_OP_KINDS, type ImplementedSemanticOpKind, type InitialDocumentFacts, type JournalEntry, LANE_KINDS_IN_STACK_ORDER, type LaneKind, type MainClipRange, type MakeEmptyPart, ManualSyncDoc, type ManualSyncDocOptions, MedeoHttpDocStorage, type MedeoHttpDocStorageOptions, MemoryDocStorage, MengineAckFailedError, type MengineAuditEntry, type MengineAuditResponse, MengineDocSession, type MengineDocSessionOptions, type MengineDocSessionUpdateEvent, type MengineDocumentVersion, type MengineEventStreamOptions, MengineHttpClient, type MengineHttpClientOptions, MengineHttpRequestError, MenginePushRejectedError, type MenginePushResponse, type MenginePushUpdateResponse, type MengineRejectedResponse, type MengineSnapshotResponse, type MengineSseUpdateEvent, type MengineSyncResponse, type MengineUpdateMeta, MirrorVideoDocumentAdapter, type MirrorVideoDocumentOptions, type OpActor, type PartAggregation, type PartIdFactory, type PartKind, type PartUnion, PlainMemoryAdapter, type PlainMemoryAdapterOptions, type PlannedSemanticOpKind, type PullFailureReason, type PullResult, type PushOutcome, type PushOutcomeKind, type PushResult, type PushResultKind, SchemaValidator, type SemanticDocumentAdapter, SemanticEditor, type SemanticOpInput, type SemanticOpKind, type SemanticOpName, type SnapshotReadable, type SolvedVideoDocument, type SpeechHostMap, type SpeechPart, type SpeedShift, TIMELINE_SKELETON_DURATION_MS, type Timeline, type TimelineDoc, type TimelineItem, type Track, type TrackDraft, type TrackItem, type TrackItemDraft, type TrackItemTimePosition, type TransactAudit, VIDEO_DOCUMENT_SCHEMA_VERSION, ValidationError, type VideoClipPart, type VideoDocument, type VideoDocumentDraft, type VideoDocumentMirrorSchema, type VideoDocumentSchemaVersion, VideoDocumentValidationError, type VideoDocumentValidationIssue, type VideoDocumentValidationIssueCode, type VideoDraft, type CaptionPart$1 as VideoDraftCaptionPart, type VideoDraftPartUnion, type Timeline$1 as VideoDraftTimeline, type Track$1 as VideoDraftTrack, type TrackItem$1 as VideoDraftTrackItem, type WaitForServerAckOptions, arrangeMainTrackSeamlessly, assertValidVideoDocument, base64ToBytes, buildInitialVideoDocument, buildSpeechHostMap, bytesToBase64, cascadeAfterVideoClipChanges, createEditSandbox, createMirrorVideoDocument, createMirrorVideoDocumentAdapter, createPlainMemoryAdapter, decodeDocVersionMark, derivePositionFromAbs, effectiveVideoClipDurationMs, encodeDocVersionMark, ensureLaneTrack, fillMainTrackTimeGaps, findLaneTrack, fromVideoDocument, generatePartId, getAt, hostForAbsMs, isEmptyVideoClip, isImplementedSemanticOpKind, isMap, laneTrackId, mainTrackRanges, partDurationMs, partUnionSchema, readMainTrackItems, readMengineEventStream, readPart, readPartDurationMs, readVideoDocumentFromDraft, reassignSpeechesToVideoClipsByTime, recalculateTimelineDuration, relativePositionForAbs, replayJournal, resolveAllSpeechOverlaps, resolveSpeechOverlapByShiftingVideos, safeDurationMs, index_d_exports as schemas, snapshotToPlain, solveVideoDocument, speedOf, syncAggregatedClipsTimePosition, toVideoDocument, validateVideoDocument, videoDocumentMirrorSchema, videoDocumentSchema, writeVideoDocumentToDraft };