@mengine/medeo-client 2.1.1-dsl.0 → 2.1.1-dsl.2

package/README.md

@@ -23,6 +23,20 @@ session.destroy();
 
 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.
+
+`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.
+
 ## Editing and conversion
 
 - Track: create, reorder, hide and delete.
@@ -111,7 +125,7 @@ Each handle owns one long-lived Mirror. Ordinary fields and Tree read from its i
 
 Mirror 2.3.3 cannot safely move an existing node under a parent created in the same draft. The document transaction rejects this combination before writing. When a business Action actually needs it, implement its scoped native path with one audited commit as specified by [K03](../../docs/projects/medeo-dsl/known-unfixed.md#k03-mirror-同批新建父节点并移入已有节点); that fallback is not implemented yet.
 
-Loro 1.16.1 and loro-mirror 2.3.3 are the lockfile baseline. Mirror is pinned with a [workspace dependency patch](../../patches/README.md): its optional `setState(..., {applyNative})` hook runs after the ordinary draft reaches Loro and before one commit. The full native event updates Mirror before DSL subscribers are notified. The hook is internal to the DSL adapter; Actions never receive a native-write callback. It supports non-ephemeral Mirror instances, and must not commit/export/import or await. Native writes preserve marks and actual container identities; a plain Mirror string snapshot still does not contain rich-text marks. Tests cover snapshot/update round trips, concurrent moves and replacements, field merging, optional reset, malformed codecs, deletion/recreation, rich text, Cursor ownership, subscriptions and Action failure preflight. The conversion library is implemented; production server/editor/player entry points have not switched.
+Loro 1.16.1 and loro-mirror 2.3.3 are the lockfile baseline. Mirror is pinned with a [workspace dependency patch](../../patches/README.md): its optional `setState(..., {applyNative})` hook runs after the ordinary draft reaches Loro and before one commit. The full native event updates Mirror before DSL subscribers are notified. The hook is internal to the DSL adapter; Actions never receive a native-write callback. It supports non-ephemeral Mirror instances, and must not commit/export/import or await. A registry install of loro-mirror never carries the patch, so the published package bundles the patched Mirror, runtime and declarations; consumers install only the `loro-crdt` peer and configure no patch. Transactions probe the Mirror once and refuse to write when the hook is missing rather than drop native edits. Native writes preserve marks and actual container identities; a plain Mirror string snapshot still does not contain rich-text marks. Tests cover snapshot/update round trips, concurrent moves and replacements, field merging, optional reset, malformed codecs, deletion/recreation, rich text, Cursor ownership, subscriptions and Action failure preflight. The conversion library is implemented; production server/editor/player entry points have not switched.
 
 Run the package test/build tasks through `vp run @mengine/medeo-client#test` and `vp run @mengine/medeo-client#build`.