loro-dev
diff --git a/‎AGENTS.md‎
Lines changed: 2 additions & 2 deletions b/‎AGENTS.md‎
Lines changed: 2 additions & 2 deletions
diff --git a/‎README.md‎
Lines changed: 50 additions & 14 deletions b/‎README.md‎
Lines changed: 50 additions & 14 deletions
@@ -44,8 +44,8 @@
 - `Mirror(options: MirrorOptions<S>)`
     - `doc` (required), `schema?`, `initialState?`, `validateUpdates?`, `throwOnValidationError?`, `debug?`, `checkStateConsistency?`, `inferOptions?`.
     - Methods: `getState()`, `setState(updater, options?)`, `subscribe(cb)`, `dispose()`, `checkStateConsistency()`, `getContainerIds()`.
-    - `SetStateOptions` supports `{ tags?: string | string[] }`; subscriber metadata includes `{ direction: SyncDirection; tags?: string[] }`.
+    - `SetStateOptions` supports `{ tags?: string | string[] }`; subscriber metadata includes `{ source: UpdateSource; tags?: string[] }`.
 - `schema(definition, options?)` plus builders: `.String()`, `.Number()`, `.Boolean()`, `.Ignore()`, `.LoroMap()`, `.LoroMapRecord()`, `.LoroList()`, `.LoroMovableList()`, `.LoroText()`, `.LoroTree()`.
 - Runtime helpers from the schema module: `validateSchema`, `getDefaultValue`, `createValueFromSchema`, and type guards such as `isContainerSchema`, `isLoroMapSchema`, `isLoroListSchema`, `isLoroMovableListSchema`, `isLoroTextSchema`, `isLoroTreeSchema`, `isRootSchemaType`, `isListLikeSchema`.
-- Types re-exported at the root: `MirrorOptions`, `SetStateOptions`, `UpdateMetadata`, `InferType`, `InferInputType`, `InferContainerOptions`, `SchemaType`, `ContainerSchemaType`, `RootSchemaType`, `LoroMapSchema`, `LoroListSchema`, `LoroMovableListSchema`, `LoroTextSchemaType`, `LoroTreeSchema`, `SchemaOptions`, `ChangeKinds`, `MapChangeKinds`, `ListChangeKinds`, `MovableListChangeKinds`, `TreeChangeKinds`, `TextChangeKinds`, `SubscriberCallback`, `SyncDirection`.
+- Types re-exported at the root: `MirrorOptions`, `SetStateOptions`, `UpdateMetadata`, `InferType`, `InferInputType`, `InferContainerOptions`, `SchemaType`, `ContainerSchemaType`, `RootSchemaType`, `LoroMapSchema`, `LoroListSchema`, `LoroMovableListSchema`, `LoroTextSchemaType`, `LoroTreeSchema`, `SchemaOptions`, `ChangeKinds`, `MapChangeKinds`, `ListChangeKinds`, `MovableListChangeKinds`, `TreeChangeKinds`, `TextChangeKinds`, `SubscriberCallback`, `UpdateSource`.
 - Utilities: `toNormalizedJson(doc)` for tree normalization. `$cid` is a reserved property injected into mirrored map values but there is no exported constant.
@@ -365,15 +365,16 @@ const mySchema = schema({ outline: schema.LoroTree(node) });
     - **`validateUpdates`**: boolean (default `true`) – validate new state against schema.
     - **`throwOnValidationError`**: boolean (default `false`) – throw on invalid updates.
     - **`debug`**: boolean (default `false`) – log diffs and applied changes.
-    - **`checkStateConsistency`**: boolean (default `false`) – after each `setState`, assert the in-memory state equals the normalized `LoroDoc` snapshot.
+    - **`checkStateConsistency`**: boolean (default `false`) – after non-ephemeral `setState` calls, assert the doc-backed base state equals the normalized `LoroDoc` snapshot.
     - **`inferOptions`**: `{ defaultLoroText?: boolean; defaultMovableList?: boolean }` – influence container-type inference when inserting containers from plain values.
 
 - `getState(): State`: Returns the current in-memory state view.
-- `setState(updater, options?)`: Update state and sync to Loro. Runs synchronously.
+- `setState(updater, options?)`: Update state and sync to Loro. Runs synchronously. When `ephemeralStore` is configured, eligible changes are automatically routed through EphemeralStore. See [Ephemeral Patches](#ephemeral-patches).
     - **`updater`**: either a partial object to shallow-merge or a function that may mutate a draft (Immer-style) or return a new state object.
-    - **`options`**: `{ tags?: string | string[] }` – arbitrary tags attached to this update; delivered to subscribers in metadata.
+    - **`options`**: `{ tags?: string | string[]; finalizeTimeout?: number }` – tags are delivered to subscribers in metadata; `finalizeTimeout` (default 50 000 ms) controls the debounce delay before ephemeral values auto-commit.
+- `finalizeEphemeralPatches()`: Immediately commit pending ephemeral patches to LoroDoc (e.g. on `mouseup`).
 - `subscribe(callback): () => void`: Subscribe to state changes. `callback` receives `(state, metadata)` where `metadata` includes:
-    - **`direction`**: `SyncDirection` – `FROM_LORO` when changes came from the doc, `TO_LORO` when produced locally, `BIDIRECTIONAL` for manual/initial syncs.
+    - **`source`**: `UpdateSource` – `LORO` when changes came from the doc, `MIRROR` when a local Mirror API changed state, `EPHEMERAL` when state changed due to an EphemeralStore update.
     - **`tags`**: `string[] | undefined` – tags provided via `setState`.
 - `dispose()`: Unsubscribe internal listeners and clear subscribers.
 - `checkStateConsistency()`: Manually trigger the consistency assertion described above.
@@ -383,22 +384,22 @@ const mySchema = schema({ outline: schema.LoroTree(node) });
 
 - **Lists and IDs**: If your list schema provides an `idSelector`, list updates use minimal add/remove/update/move operations; otherwise index-based diffs are applied.
 - **Container inference**: When schema is missing/ambiguous for a field, the mirror infers container types from values. `inferOptions.defaultLoroText` makes strings become `LoroText`; `inferOptions.defaultMovableList` makes arrays become `LoroMovableList`.
-- **Consistency checks**: Enabling `checkStateConsistency` (or calling the method directly) is useful while developing or writing tests; it throws if Mirror state diverges from the normalized document snapshot.
+- **Consistency checks**: Enabling `checkStateConsistency` is useful while developing or writing tests; it auto-checks only non-ephemeral `setState` calls. Calling `checkStateConsistency()` manually compares the doc-backed base state against the normalized document snapshot, so active ephemeral overlay values are intentionally ignored.
 
 ### Types
 
-- `SyncDirection`:
-    - `FROM_LORO` – applied due to incoming `LoroDoc` changes
-    - `TO_LORO` – applied due to local `setState`
-    - `BIDIRECTIONAL` – initial/manual sync context
-- `UpdateMetadata`: `{ direction: SyncDirection; tags?: string[] }`
-- `SetStateOptions`: `{ tags?: string | string[] }`
+- `UpdateSource`:
+    - `LORO` – applied due to incoming `LoroDoc` changes
+    - `MIRROR` – applied due to a local Mirror API call such as `setState` or `finalizeEphemeralPatches`
+    - `EPHEMERAL` – state recomposed due to an EphemeralStore change
+- `UpdateMetadata`: `{ source: UpdateSource; tags?: string[] }`
+- `SetStateOptions`: `{ tags?: string | string[]; origin?: string; timestamp?: number; message?: string; finalizeTimeout?: number }`
 
 ### Example
 
 ```ts
 import { LoroDoc } from "loro-crdt";
-import { Mirror, schema, SyncDirection } from "loro-mirror";
+import { Mirror, schema, UpdateSource } from "loro-mirror";
 
 const todoSchema = schema({
     todos: schema.LoroList(
@@ -414,8 +415,8 @@ const doc = new LoroDoc();
 const mirror = new Mirror({ doc, schema: todoSchema, validateUpdates: true });
 
 // Subscribe with metadata
-const unsubscribe = mirror.subscribe((state, { direction, tags }) => {
-    if (direction === SyncDirection.FROM_LORO) {
+const unsubscribe = mirror.subscribe((state, { source, tags }) => {
+    if (source === UpdateSource.LORO) {
         console.log("Remote update", tags);
     } else {
         console.log("Local update", tags);
@@ -432,6 +433,41 @@ mirror.setState(
     },
     { tags: ["ui:add"] },
 );
+```
+
+### Ephemeral Patches
+
+For high-frequency temporary changes (dragging, resizing, scrubbing), pass an `ephemeralStore` to `MirrorOptions`. This changes how `setState` works: eligible changes (primitive values on existing Map keys) are automatically routed to the EphemeralStore for real-time sync without creating LoroDoc editing history. No separate API is needed — the same `setState` handles both persistent and ephemeral updates.
+
+```ts
+import { LoroDoc, EphemeralStore } from "loro-crdt";
+
+const doc = new LoroDoc();
+const eph = new EphemeralStore();
+const mirror = new Mirror({ doc, schema: mySchema, ephemeralStore: eph });
+
+// Network sync for ephemeral state (your responsibility)
+eph.subscribeLocalUpdates((bytes) => channel.send(bytes));
+channel.on("ephemeral", (bytes) => eph.apply(bytes));
+
+// During drag — x/y are primitives on existing keys → EphemeralStore
+mirror.setState(
+    (s) => { s.items[0].x = e.clientX; s.items[0].y = e.clientY; },
+    { finalizeTimeout: 1_000 }, // auto-commit after 1s of inactivity
+);
+
+// On mouseup — commit ephemeral values to LoroDoc immediately
+mirror.finalizeEphemeralPatches();
+```
+
+**Routing rules** (with `ephemeralStore` configured):
+
+| Change type | Destination |
+|---|---|
+| Primitive value on an existing key of an existing Map | `EphemeralStore` |
+| New Map / new key / container value / List·Text·Tree ops | `LoroDoc` directly |
+
+Without `ephemeralStore`, all changes go to LoroDoc as usual. See the [core package README](./packages/core/README.md#ephemeral-patches) for full details.
 
 ### How `$cid` Works