@mengine/medeo-client 2.0.1 → 2.1.0

package/README.md

@@ -8,6 +8,20 @@ This package owns the shared `VideoDocument` contract, semantic editing layer, a
 
 `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 until the local save queue drains, including in-flight writes and edits made while waiting (default deadline: 15 seconds). Continuous editing may keep it pending. 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.

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { $ as VideoDraft, A as assertValidVideoDocument, B as CaptionPart, C as index_d_exports, D as VideoDocumentMirrorSchema, E as VideoDocumentDraft, F as buildSpeechHostMap, G as Timeline, H as PartKind, I as derivePositionFromAbs, J as TrackItemTimePosition, K as Track, L as fromVideoDocument, M as buildInitialVideoDocument, N as DerivedItemPosition, O as videoDocumentMirrorSchema, P as SpeechHostMap, Q as VideoDocumentValidationIssueCode, R as toVideoDocument, S as ValidationError, T as TrackItemDraft, U as PartUnion, V as DEFAULT_UNIT_TIME_MS, W as SpeechPart, X as VideoDocument, Y as VideoClipPart, Z as VideoDocumentValidationIssue, _ as PlannedSemanticOpKind, a as MirrorVideoDocumentOptions, at as PartAggregation, b as SchemaValidator, c as CommitOptions, ct as Track$1, d as SemanticEditor, et as VideoDraftContent, f as SemanticOpInput, g as ImplementedSemanticOpKind, h as IMPLEMENTED_SEMANTIC_OP_KINDS, i as MirrorVideoDocumentAdapter, it as CaptionStyle, j as validateVideoDocument, k as VideoDocumentValidationError, l as OpActor, lt as TrackItem$1, m as TransactAudit, n as videoDocumentSchema, nt as Attachment, o as createMirrorVideoDocument, ot as SpeedShift, p as SemanticOpName, q as TrackItem, r as readVideoDocumentFromDraft, rt as CaptionPart$1, s as createMirrorVideoDocumentAdapter, st as Timeline$1, t as partUnionSchema, tt as VideoDraftPartUnion, u as SemanticDocumentAdapter, v as SemanticOpKind, w as TrackDraft, x as SnapshotReadable, y as isImplementedSemanticOpKind, z as BgmPart } from "./index-CnZ9l3rb.js";
 import { LoroDoc, PeerID } from "loro-crdt";
-import { DocState } from "@mengine/sync";
+import { DocState, LocalSaveState } from "@mengine/sync";
 import { BaseDocStorage, Connection, DocDiff, DocPushReceipt, DocSnapshotRecord, DocStorage, DocStorageOptions, DocUpdate, DocUpdateRecord } from "@mengine/storage";
 
 //#region src/client/base64.d.ts
@@ -632,13 +632,18 @@ declare class MengineAckFailedError extends Error {
   readonly cause: Error | undefined;
   constructor(reason: 'timeout' | 'rejected' | 'failed', code: string | undefined, cause: Error | undefined, message: string);
 }
+type MengineLocalSaveState = LocalSaveState;
+interface WaitForLocalSaveOptions {
+  /** Only limits waiting, never cancels persistence. */
+  timeoutMs?: number;
+}
 interface WaitForServerAckOptions {
   /** Deadline in ms. Rejects with reason `timeout` when it elapses. */
   timeoutMs?: number;
 }
 /** Document-level confirmation is independent of local operation completion. */
 interface MengineDocSyncState {
-  /** Remote-only imports do not create a new local confirmation obligation. */
+  /** Server-originated imports do not create a new local confirmation obligation. */
   readonly confirmation: 'unknown' | 'pending' | 'confirmed';
   /** Transport/activity phase. Idle does not imply confirmation; failure details
    * remain available through push outcomes and confirmation wait errors. */
@@ -653,6 +658,9 @@ interface MengineDocSessionOptions {
    * Browsers should pass an `IndexedDBDocStorage` for refresh/cross-tab support.
    */
   localStorage?: DocStorageLike;
+  /** A freshly fetched remote snapshot to merge into storage before loading.
+   * Existing local changes are retained; the host owns any online startup gate. */
+  initialSnapshot?: Uint8Array;
   sseReconnectDelayMs?: number;
 }
 /**
@@ -689,6 +697,7 @@ declare class MengineDocSession {
   private started;
   private startTask;
   private destroyed;
+  private closeTask;
   private lifetime;
   private hasConnected;
   private initialVersionValue;
@@ -782,7 +791,17 @@ declare class MengineDocSession {
    */
   start(): Promise<VideoDocument>;
   private open;
+  getLocalSaveState(): MengineLocalSaveState;
+  /** Immediately reports local transaction state; independent of server confirmation. */
+  subscribeLocalSaveState(cb: (state: MengineLocalSaveState) => void): () => void;
+  /** Waits until all local saves finish, including edits made while waiting. Does not wait for the network. */
+  waitForLocalSave(options?: WaitForLocalSaveOptions): Promise<void>;
+  /** Stop accepting edits and drain local persistence before releasing resources.
+   * A failed local write keeps retrying, even after the host has unmounted.
+   * Hosts should use this for normal teardown; destroy() is immediate cancellation. */
+  close(): Promise<void>;
   getSyncState(): MengineDocSyncState;
+  private trackLocalVersion;
   private confirmationTarget;
   /** Immediately supplies current state; unsubscribe when the host changes docs. */
   subscribeSyncState(cb: (state: MengineDocSyncState) => void): () => void;
@@ -1119,4 +1138,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, DEFAULT_UNIT_TIME_MS, type DerivedItemPosition, type DocStorageLike, type DocVersionMark, IMPLEMENTED_SEMANTIC_OP_KINDS, type ImplementedSemanticOpKind, 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 MengineDocSyncState, type MengineDocumentVersion, type MengineEventStreamOptions, MengineHttpClient, type MengineHttpClientOptions, MengineHttpRequestError, MenginePushRejectedError, type MenginePushResponse, type MenginePushUpdateResponse, type MengineRejectedResponse, type MengineSnapshotResponse, type MengineSseUpdateEvent, type MengineSyncResponse, type MengineUndoState, 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, ValidationError, type VideoClipPart, type VideoDocument, type VideoDocumentDraft, type VideoDocumentMirrorSchema, VideoDocumentValidationError, type VideoDocumentValidationIssue, type VideoDocumentValidationIssueCode, type VideoDraft, type CaptionPart$1 as VideoDraftCaptionPart, type VideoDraftContent, 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, 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 MengineDocSyncState, type MengineDocumentVersion, type MengineEventStreamOptions, MengineHttpClient, type MengineHttpClientOptions, MengineHttpRequestError, type MengineLocalSaveState, MenginePushRejectedError, type MenginePushResponse, type MenginePushUpdateResponse, type MengineRejectedResponse, type MengineSnapshotResponse, type MengineSseUpdateEvent, type MengineSyncResponse, type MengineUndoState, 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, ValidationError, type VideoClipPart, type VideoDocument, type VideoDocumentDraft, type VideoDocumentMirrorSchema, VideoDocumentValidationError, type VideoDocumentValidationIssue, type VideoDocumentValidationIssueCode, type VideoDraft, type CaptionPart$1 as VideoDraftCaptionPart, type VideoDraftContent, type VideoDraftPartUnion, type Timeline$1 as VideoDraftTimeline, type Track$1 as VideoDraftTrack, type TrackItem$1 as VideoDraftTrackItem, type WaitForLocalSaveOptions, 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 };

package/dist/index.js

@@ -1,7 +1,7 @@
 import { t as __exportAll } from "./chunk-D7D4PA-g.js";
 import { A as isEmptyVideoClip, C as fillMainTrackTimeGaps, D as resolveSpeechOverlapByShiftingVideos, E as resolveAllSpeechOverlaps, F as partUnionToDraft, I as recordEntries, L as videoDocumentMirrorSchema, M as safeDurationMs, N as DEFAULT_UNIT_TIME_MS, O as syncAggregatedClipsTimePosition, P as effectiveVideoClipDurationMs, R as base64ToBytes, S as arrangeMainTrackSeamlessly, T as recalculateTimelineDuration, _ as ensureLaneTrack, a as DocumentMutationGuard, b as solveVideoDocument, c as derivePositionFromAbs, d as VideoDocumentValidationError, f as assertValidVideoDocument, g as LANE_KINDS_IN_STACK_ORDER, h as videoDocumentSchema, i as readVideoDocumentFromDraft, j as partDurationMs, k as TIMELINE_SKELETON_DURATION_MS, l as fromVideoDocument, m as partUnionSchema, n as createMirrorVideoDocument, o as buildInitialVideoDocument, p as validateVideoDocument, r as createMirrorVideoDocumentAdapter, s as buildSpeechHostMap, t as MirrorVideoDocumentAdapter, u as toVideoDocument, v as findLaneTrack, w as reassignSpeechesToVideoClipsByTime, x as cascadeAfterVideoClipChanges, y as laneTrackId, z as bytesToBase64 } from "./document-B_JQwrC5.js";
 import { z } from "zod";
-import { LoroDoc, UndoManager, VersionVector } from "loro-crdt";
+import { LoroDoc, UndoManager, VersionVector, decodeImportBlobMeta } from "loro-crdt";
 import { ClientServerSynchronizer, DocManager } from "@mengine/sync";
 import { DisposableSet, EventBus, Task } from "@mengine/utils";
 import { BaseDocStorage, DummyConnection } from "@mengine/storage";
@@ -2713,6 +2713,7 @@ var MengineDocSession = class {
 	started = false;
 	startTask = null;
 	destroyed = false;
+	closeTask = null;
 	lifetime = null;
 	hasConnected = false;
 	initialVersionValue = null;
@@ -2913,6 +2914,13 @@ var MengineDocSession = class {
 		this.local.connection.connect();
 		await this.local.connection.waitForConnected().abortOn(this.lifetime.signal);
 		if (this.destroyed) throw new Error("mengine doc session destroyed");
+		if (this.options.initialSnapshot) {
+			await this.local.pushDocUpdate({
+				docId: this.docId,
+				data: this.options.initialSnapshot
+			}, "initial-snapshot");
+			if (this.destroyed) throw new Error("mengine doc session destroyed");
+		}
 		this.server.connection.connect();
 		this.synchronizer.start();
 		this.manager.start();
@@ -2924,7 +2932,7 @@ var MengineDocSession = class {
 		this.adapterValue = new MirrorVideoDocumentAdapter(doc, this.mutationGuard);
 		const unsubscribe = doc.subscribe((event) => {
 			if (this.adapterValue == null) return;
-			if (event.by === "local") this.localVersionValue = doc.version();
+			if (event.by === "local") this.trackLocalVersion(doc.version());
 			this.emitSyncState();
 			this.events.emit("update", {
 				source: event.by === "local" ? "local" : "remote",
@@ -2932,6 +2940,10 @@ var MengineDocSession = class {
 			});
 		});
 		this.disposables.add(unsubscribe);
+		this.disposables.add(this.manager.onLocalUpdateReceived(this.docId, (update) => {
+			this.trackLocalVersion(decodeImportBlobMeta(update, true).partialEndVersionVector);
+			this.emitSyncState();
+		}));
 		this.disposables.add(this.manager.onDocStateChange(this.docId, (state) => {
 			this.events.emit("state", state);
 			this.emitSyncState();
@@ -2942,9 +2954,39 @@ var MengineDocSession = class {
 		this.undoManagerValue = new DocumentUndoManager(doc, this.mutationGuard, () => this.events.emit("undoState"));
 		this.editorValue = new SemanticEditor(this.adapterValue);
 		this.initialVersionValue = doc.version();
+		if (this.localVersionValue) this.trackLocalVersion(this.initialVersionValue);
 		this.emitSyncState();
 		return this.snapshot();
 	}
+	getLocalSaveState() {
+		return this.getState().localSave;
+	}
+	/** Immediately reports local transaction state; independent of server confirmation. */
+	subscribeLocalSaveState(cb) {
+		const off = this.events.on("state", () => cb(this.getLocalSaveState()));
+		cb(this.getLocalSaveState());
+		return off;
+	}
+	/** Waits until all local saves finish, including edits made while waiting. Does not wait for the network. */
+	async waitForLocalSave(options = {}) {
+		if (!this.editorValue || this.destroyed) throw new Error("mengine doc session is not started");
+		await this.manager.waitForLocalSave(this.docId).timeout(options.timeoutMs ?? 15e3);
+	}
+	/** Stop accepting edits and drain local persistence before releasing resources.
+	* A failed local write keeps retrying, even after the host has unmounted.
+	* Hosts should use this for normal teardown; destroy() is immediate cancellation. */
+	close() {
+		if (this.closeTask) return this.closeTask;
+		if (this.destroyed || !this.editorValue) {
+			this.destroy();
+			return Promise.resolve();
+		}
+		this.mutationGuard.close();
+		this.synchronizer.stop();
+		this.server.connection.disconnect();
+		this.closeTask = this.manager.waitForLocalSave(this.docId).then(() => this.destroy());
+		return this.closeTask;
+	}
 	getSyncState() {
 		const state = this.getState();
 		const target = this.confirmationTarget();
@@ -2955,6 +2997,14 @@ var MengineDocSession = class {
 			phase: connection === "disconnected" ? "offline" : this.pushErrorValue != null || state.error != null ? "failed" : connection === "connecting" ? "connecting" : state.syncing ? "syncing" : "idle"
 		};
 	}
+	trackLocalVersion(version) {
+		const target = VersionVector.parseJSON(this.confirmationTarget()?.toJSON() ?? /* @__PURE__ */ new Map());
+		for (const [peer, counter] of version.toJSON()) if ((target.get(peer) ?? 0) < counter) target.setEnd({
+			peer,
+			counter
+		});
+		this.localVersionValue = target;
+	}
 	confirmationTarget() {
 		return this.localVersionValue ?? this.initialVersionValue;
 	}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mengine/medeo-client",
-  "version": "2.0.1",
+  "version": "2.1.0",
   "license": "UNLICENSED",
   "repository": {
     "type": "git",
@@ -25,9 +25,9 @@
   "dependencies": {
     "loro-mirror": "^2.3.3",
     "zod": "^4.4.3",
-    "@mengine/storage": "2.0.1",
-    "@mengine/sync": "2.0.1",
-    "@mengine/utils": "2.0.1"
+    "@mengine/sync": "2.1.0",
+    "@mengine/storage": "2.1.0",
+    "@mengine/utils": "2.1.0"
   },
   "devDependencies": {
     "@types/node": "^25.9.1",