mindoodb-app-sdk 0.0.19 → 0.0.20

package/README.md

@@ -772,7 +772,126 @@ Like the text buffer, the rich-text handle always sends the original `baseHeads`
 
 #### End-to-end sample
 
-The Word/.docx mode in [`mindoodb-app-teamedit`](https://github.com/klehmann/mindoodb-app-teamedit) wires `MindooDBRichTextHandle` to an `@eigenpal/docx-editor-vue` editor and is the recommended starting point for building your own collaborative rich-text app.
+The Word/.docx mode in [`mindoodb-app-teamedit`](https://github.com/klehmann/mindoodb-app-teamedit) is the **only supported in-repo use case** for the Automerge binary sync API below — it needs a local replica and binary flush because `set`/`unset` and the JSON patch APIs are not sufficient for that editor. For span-only rich-text apps, use `createMindooDBRichTextHandle` instead.
+
+### Automerge binary sync (advanced)
+
+> **Avoid these APIs unless you have no alternative.** For normal app editing, use `documents.update({ set })`, `documents.update({ unset })`, and the JSON patch operations (`text`, `richText`, `json`) documented above. `getAutomergeSnapshot` and `applyAutomergeChanges` were added as an **escape hatch** for the one case where those APIs are not enough: TeamEdit's Word/.docx mode, which hosts a local `@automerge/automerge` replica and flushes raw change bytes on save. Do not adopt binary sync for new features unless you have the same constraint — you take on an Automerge dependency, manual replica lifecycle, and a much harder integration path.
+
+If you must use binary sync, Haven decrypts the canonical document, merges incoming change batches with `Automerge.applyChanges`, and persists the result. Your app never sends encrypted blobs or sync metadata; it only sends the same binary change format Automerge produces locally.
+
+Typical flow:
+
+```
+            ┌────────────────────────────────────────────────────┐
+  open  ──► │ getAutomergeSnapshot → load local replica          │
+            └─────────────────────────┬──────────────────────────┘
+                                      │
+  edit  ──► │ Local Automerge doc (or span edits applied locally)  │
+            └─────────────────────────┬──────────────────────────┘
+                                      │ getChangesSince(baseHeads)
+                                      ▼
+            ┌────────────────────────────────────────────────────┐
+  save  ──► │ applyAutomergeChanges({ baseHeads, replicaHeads,   │
+            │                       changes })                   │
+            └─────────────────────────┬──────────────────────────┘
+                                      │ Haven merges + persists
+                                      ▼
+            ┌────────────────────────────────────────────────────┐
+            │ Apply result.changesSince locally (or skip if empty) │
+            └────────────────────────────────────────────────────┘
+```
+
+Bridge RPCs: `documents.automerge.getSnapshot` and `documents.automerge.applyChanges`.
+
+#### `getAutomergeSnapshot`
+
+Export the full internal Automerge document as a binary snapshot plus the current document heads:
+
+```ts
+const snapshot = await db.documents.getAutomergeSnapshot(docId);
+// snapshot = { binary: Uint8Array, heads: string[] }
+
+const localDoc = Automerge.load(snapshot.binary);
+const baseHeads = [...snapshot.heads];
+```
+
+Options:
+
+```ts
+interface MindooDBAppAutomergeGetOptions {
+  revisionId?: MindooDBAppDocumentRevisionId; // historical read via documents.listHistory()
+}
+```
+
+Only call this when binary sync is unavoidable — e.g. opening a local replica, refreshing after `applyAutomergeChanges`, or read-only historical preview at a `revisionId`. For normal reads, use `getRichText` or `documents.get`.
+
+#### `applyAutomergeChanges`
+
+Merge a batch of raw Automerge change bytes into the canonical document on Haven:
+
+```ts
+const changes = Automerge.getChangesSince(localDoc, baseHeads as Automerge.Heads);
+const replicaHeads = Automerge.getHeads(localDoc);
+
+const result = await db.documents.applyAutomergeChanges(docId, {
+  baseHeads, // optional metadata: heads when the local batch was authored
+  replicaHeads, // local heads after authoring; enables incremental catch-up in the response
+  changes: changes.map((change) => new Uint8Array(change)),
+});
+
+// result.document — updated MindooDBAppDocument snapshot (includes merged data + heads)
+// result.heads     — new Automerge heads after the merge
+// result.changesSince — incremental bytes to reconcile the local replica (when replicaHeads was sent)
+if (result.changesSince?.changes.length) {
+  [localDoc] = Automerge.applyChanges(
+    localDoc,
+    result.changesSince.changes.map((change) => new Uint8Array(change)),
+  );
+}
+baseHeads = [...result.heads];
+```
+
+Patch and result types:
+
+```ts
+interface MindooDBAppAutomergeChangesPatch {
+  baseHeads?: string[];   // correlation only; merge is not rejected when Haven moved on
+  replicaHeads?: string[]; // local heads after authoring `changes`; enables `changesSince` in the response
+  changes: Uint8Array[];  // from Automerge.getChangesSince (or equivalent)
+}
+
+interface MindooDBAppAutomergeChangesSince {
+  sinceHeads: string[];   // echo of `replicaHeads`
+  changes: Uint8Array[];  // apply locally with Automerge.applyChanges
+}
+
+interface MindooDBAppAutomergePatchResult {
+  document: MindooDBAppDocument;
+  heads: string[];
+  changesSince?: MindooDBAppAutomergeChangesSince;
+}
+```
+
+Haven applies `changes` with `Automerge.applyChanges` against its **current** document, so concurrent edits from other clients are merged by Automerge's CRDT logic rather than rejected. `baseHeads` is optional logging metadata — it does not gate the merge.
+
+When you include `replicaHeads` (the local replica's heads after authoring your batch), the response includes `changesSince`: the incremental change bytes your replica still needs after the merge. Apply them locally with `Automerge.applyChanges` and set `baseHeads = result.heads`. When there was no concurrent edit, `changesSince.changes` is empty and your local doc is already up to date — no full snapshot download needed. Omit `replicaHeads` only if you plan to reload via `getAutomergeSnapshot` instead.
+
+#### When to use binary sync vs JSON patches
+
+| Approach | App sends | When to use |
+| -------- | --------- | ----------- |
+| `documents.update({ set })` / `{ unset }` | Field paths | **Default** for structured document data |
+| `documents.update({ richText })` | JSON span snapshots | **Default** for rich-text fields |
+| `documents.update({ text })` | Text splices | Plain markdown / string fields |
+| `documents.update({ json })` | JSON Patch (RFC 6902) | Arbitrary nested JSON paths |
+| `applyAutomergeChanges` | Binary change bytes | **Last resort only** — TeamEdit Word/.docx with a local Automerge replica |
+
+Requires the `update` capability (same as other write operations). For historical reads, prefer `getRichText(..., { revisionId })`; only use `getAutomergeSnapshot(..., { revisionId })` when you truly need the full binary at a revision.
+
+#### Reference implementation (not a template)
+
+TeamEdit's Word/.docx mode is why these RPCs exist — see `wordAutomergeHandle.ts` in [`mindoodb-app-teamedit`](https://github.com/klehmann/mindoodb-app-teamedit). Treat it as a reference for an unsupported edge case, not as a pattern to copy into new apps.
 
 ### Incremental sync
 
@@ -1208,6 +1327,8 @@ Connect options: `launchId?`, `targetOrigin?`, `connectTimeoutMs?`.
 | `list(query?)`                     | `Promise<MindooDBAppDocumentListResult>`     |
 | `get(docId)`                       | `Promise<MindooDBAppDocument \| null>`       |
 | `getRichText(docId, path, opts?)`  | `Promise<MindooDBAppRichTextSnapshot>`       |
+| `getAutomergeSnapshot(docId, opts?)` | `Promise<MindooDBAppAutomergeSnapshot>`   |
+| `applyAutomergeChanges(docId, patch)` | `Promise<MindooDBAppAutomergePatchResult>` |
 | `create(input)`                    | `Promise<MindooDBAppDocument>`               |
 | `update(docId, patch)`             | `Promise<MindooDBAppDocument>`               |
 | `delete(docId)`                    | `Promise<{ ok: true }>`                      |
@@ -1216,6 +1337,8 @@ Connect options: `launchId?`, `targetOrigin?`, `connectTimeoutMs?`.
 | `getAtTimestamp(docId, timestamp)` | `Promise<MindooDBAppHistoricalDocument>`     |
 | `getAtRevision(docId, revisionId)` | `Promise<MindooDBAppHistoricalDocument>`     |
 
+`getAutomergeSnapshot` and `applyAutomergeChanges` are **discouraged** escape-hatch APIs for binary Automerge sync. Prefer `set`/`unset` and JSON patches (`text`, `richText`, `json`) instead. See [Automerge binary sync (advanced)](#automerge-binary-sync-advanced).
+
 `list(query?)` accepts the changefeed query options documented above. The `cursor` value is an opaque checkpoint string managed by Haven and should be stored and passed back unchanged.
 
 For `create(input)`, use `MindooDBAppCreateDocumentInput` with shape `{ set: Record<string, unknown>; decryptionKeyId?: string; id?: string }`. The optional `id` lets the app pick the document id instead of letting MindooDB generate a UUID7; when provided it must match `/^[A-Za-z][A-Za-z0-9_]*$/` and existing live documents with that id are returned as-is (idempotent create-if-missing). If an existing custom-id document is deleted, `create({ id })` undeletes it and preserves the previous document body. Documents created with the same custom id on different replicas converge correctly when synced.

package/dist/chunk-QGM4M3NI.js

@@ -0,0 +1,37 @@
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined") return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+var __commonJS = (cb, mod) => function __require2() {
+  return mod || (0, cb[__getOwnPropNames(cb)[0]])((mod = { exports: {} }).exports, mod), mod.exports;
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+
+export {
+  __require,
+  __commonJS,
+  __toESM
+};

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { M as MindooDBAppAttachmentPreviewMode, a as MindooDBAppBridge, b as MindooDBAppDatabase, c as MindooDBAppDocument, d as MindooDBAppRichTextSpan, e as MindooDBAppRichTextSnapshot } from './types-nFt-aryL.js';
-export { f as MindooDBAppAttachmentApi, g as MindooDBAppAttachmentChunk, h as MindooDBAppAttachmentInfo, i as MindooDBAppAttachmentPreviewOptions, j as MindooDBAppAttachmentPreviewSession, k as MindooDBAppBridgeConnectMessage, l as MindooDBAppBridgeConnectOptions, m as MindooDBAppBridgeConnectedMessage, n as MindooDBAppBridgeErrorPayload, o as MindooDBAppBridgeHandshakeErrorMessage, p as MindooDBAppBridgePortMessage, q as MindooDBAppBridgeRpcError, r as MindooDBAppBridgeRpcMessage, s as MindooDBAppBridgeRpcRequest, t as MindooDBAppBridgeRpcSuccess, u as MindooDBAppBridgeStreamAbortRequest, v as MindooDBAppBridgeStreamAck, w as MindooDBAppBridgeStreamCloseRequest, x as MindooDBAppBridgeStreamError, y as MindooDBAppBridgeStreamMessage, z as MindooDBAppBridgeStreamOpenResult, A as MindooDBAppBridgeStreamReadRequest, B as MindooDBAppBridgeStreamWriteRequest, C as MindooDBAppBridgeThemeChangedMessage, D as MindooDBAppBridgeUiPreferencesChangedMessage, E as MindooDBAppBridgeViewportChangedMessage, F as MindooDBAppCapability, G as MindooDBAppConfiguredViewCategorizationStyle, H as MindooDBAppConfiguredViewColumn, I as MindooDBAppConfiguredViewColumnRole, J as MindooDBAppConfiguredViewExpressionMode, K as MindooDBAppConfiguredViewFieldExpression, L as MindooDBAppConfiguredViewFilterDefinition, N as MindooDBAppConfiguredViewFilterMode, O as MindooDBAppConfiguredViewFilterRule, P as MindooDBAppConfiguredViewFormulaExpression, Q as MindooDBAppConfiguredViewFormulaFilterDefinition, R as MindooDBAppConfiguredViewPreviewMode, S as MindooDBAppConfiguredViewRuleFilterDefinition, T as MindooDBAppConfiguredViewRuleMatchMode, U as MindooDBAppConfiguredViewRuleOperator, V as MindooDBAppConfiguredViewValueExpression, W as MindooDBAppCreateDocumentInput, X as MindooDBAppCreateViewInput, Y as MindooDBAppCreateViewNavigatorInput, Z as MindooDBAppDatabaseInfo, _ as MindooDBAppDocumentApi, $ as MindooDBAppDocumentHeadCursorResult, a0 as MindooDBAppDocumentHistoryEntry, a1 as MindooDBAppDocumentListQuery, a2 as MindooDBAppDocumentListResult, a3 as MindooDBAppDocumentRevisionId, a4 as MindooDBAppDocumentScanPreset, a5 as MindooDBAppDocumentSummary, a6 as MindooDBAppHistoricalDocument, a7 as MindooDBAppHistoryQuery, a8 as MindooDBAppHostTheme, a9 as MindooDBAppJsonListDeletePatch, aa as MindooDBAppJsonListInsertPatch, ab as MindooDBAppJsonPatch, ac as MindooDBAppJsonSetPatch, ad as MindooDBAppJsonUnsetPatch, ae as MindooDBAppLaunchContext, af as MindooDBAppMenuAnchor, ag as MindooDBAppMenuApi, ah as MindooDBAppMenuCommandItem, ai as MindooDBAppMenuDismissReason, aj as MindooDBAppMenuDismissedResult, ak as MindooDBAppMenuItem, al as MindooDBAppMenuKind, am as MindooDBAppMenuPlacement, an as MindooDBAppMenuPointAnchor, ao as MindooDBAppMenuRect, ap as MindooDBAppMenuRectAnchor, aq as MindooDBAppMenuSelectionResult, ar as MindooDBAppMenuSeparatorItem, as as MindooDBAppReadableAttachmentStream, at as MindooDBAppResolvedViewDefinition, au as MindooDBAppResolvedViewSource, av as MindooDBAppRichTextBlockSpan, aw as MindooDBAppRichTextGetOptions, ax as MindooDBAppRichTextImmutableString, ay as MindooDBAppRichTextMaterializeValue, az as MindooDBAppRichTextPatch, aA as MindooDBAppRichTextScalar, aB as MindooDBAppRichTextTextSpan, aC as MindooDBAppRuntime, aD as MindooDBAppScanAttachmentOptions, aE as MindooDBAppScanAttachmentResult, aF as MindooDBAppScopedDocId, aG as MindooDBAppScopedDocumentSummary, aH as MindooDBAppSession, aI as MindooDBAppShowMenuInput, aJ as MindooDBAppShowMenuResult, aK as MindooDBAppTextEdit, aL as MindooDBAppTextPatch, aM as MindooDBAppThemeMode, aN as MindooDBAppUiPreferences, aO as MindooDBAppUpdateDocumentInput, aP as MindooDBAppViewCursorDocumentListResult, aQ as MindooDBAppViewCursorResult, aR as MindooDBAppViewEntry, aS as MindooDBAppViewEntryKind, aT as MindooDBAppViewNavigator, aU as MindooDBAppViewNavigatorExpansionState, aV as MindooDBAppViewNavigatorOpenOptions, aW as MindooDBAppViewNavigatorPageOptions, aX as MindooDBAppViewNavigatorPageResult, aY as MindooDBAppViewNavigatorRangeQuery, aZ as MindooDBAppViewNavigatorSelectionState, a_ as MindooDBAppViewport, a$ as MindooDBAppWritableAttachmentStream } from './types-nFt-aryL.js';
+import { M as MindooDBAppAttachmentPreviewMode, a as MindooDBAppBridge, b as MindooDBAppDatabase, c as MindooDBAppDocument, d as MindooDBAppRichTextSpan, e as MindooDBAppRichTextSnapshot } from './types-CQt2ObMu.js';
+export { f as MindooDBAppAttachmentApi, g as MindooDBAppAttachmentChunk, h as MindooDBAppAttachmentInfo, i as MindooDBAppAttachmentPreviewOptions, j as MindooDBAppAttachmentPreviewSession, k as MindooDBAppAutomergeChangesPatch, l as MindooDBAppAutomergeChangesSince, m as MindooDBAppAutomergeGetOptions, n as MindooDBAppAutomergePatchResult, o as MindooDBAppAutomergeSnapshot, p as MindooDBAppBridgeConnectMessage, q as MindooDBAppBridgeConnectOptions, r as MindooDBAppBridgeConnectedMessage, s as MindooDBAppBridgeErrorPayload, t as MindooDBAppBridgeHandshakeErrorMessage, u as MindooDBAppBridgePortMessage, v as MindooDBAppBridgeRpcError, w as MindooDBAppBridgeRpcMessage, x as MindooDBAppBridgeRpcRequest, y as MindooDBAppBridgeRpcSuccess, z as MindooDBAppBridgeStreamAbortRequest, A as MindooDBAppBridgeStreamAck, B as MindooDBAppBridgeStreamCloseRequest, C as MindooDBAppBridgeStreamError, D as MindooDBAppBridgeStreamMessage, E as MindooDBAppBridgeStreamOpenResult, F as MindooDBAppBridgeStreamReadRequest, G as MindooDBAppBridgeStreamWriteRequest, H as MindooDBAppBridgeThemeChangedMessage, I as MindooDBAppBridgeUiPreferencesChangedMessage, J as MindooDBAppBridgeViewportChangedMessage, K as MindooDBAppCapability, L as MindooDBAppConfiguredViewCategorizationStyle, N as MindooDBAppConfiguredViewColumn, O as MindooDBAppConfiguredViewColumnRole, P as MindooDBAppConfiguredViewExpressionMode, Q as MindooDBAppConfiguredViewFieldExpression, R as MindooDBAppConfiguredViewFilterDefinition, S as MindooDBAppConfiguredViewFilterMode, T as MindooDBAppConfiguredViewFilterRule, U as MindooDBAppConfiguredViewFormulaExpression, V as MindooDBAppConfiguredViewFormulaFilterDefinition, W as MindooDBAppConfiguredViewPreviewMode, X as MindooDBAppConfiguredViewRuleFilterDefinition, Y as MindooDBAppConfiguredViewRuleMatchMode, Z as MindooDBAppConfiguredViewRuleOperator, _ as MindooDBAppConfiguredViewValueExpression, $ as MindooDBAppCreateDocumentInput, a0 as MindooDBAppCreateViewInput, a1 as MindooDBAppCreateViewNavigatorInput, a2 as MindooDBAppDatabaseInfo, a3 as MindooDBAppDocumentApi, a4 as MindooDBAppDocumentHeadCursorResult, a5 as MindooDBAppDocumentHistoryEntry, a6 as MindooDBAppDocumentListQuery, a7 as MindooDBAppDocumentListResult, a8 as MindooDBAppDocumentRevisionId, a9 as MindooDBAppDocumentScanPreset, aa as MindooDBAppDocumentSummary, ab as MindooDBAppHistoricalDocument, ac as MindooDBAppHistoryQuery, ad as MindooDBAppHostTheme, ae as MindooDBAppJsonListDeletePatch, af as MindooDBAppJsonListInsertPatch, ag as MindooDBAppJsonPatch, ah as MindooDBAppJsonSetPatch, ai as MindooDBAppJsonTextMarkPatch, aj as MindooDBAppJsonTextSplicePatch, ak as MindooDBAppJsonTextUnmarkPatch, al as MindooDBAppJsonUnsetPatch, am as MindooDBAppLaunchContext, an as MindooDBAppMenuAnchor, ao as MindooDBAppMenuApi, ap as MindooDBAppMenuCommandItem, aq as MindooDBAppMenuDismissReason, ar as MindooDBAppMenuDismissedResult, as as MindooDBAppMenuItem, at as MindooDBAppMenuKind, au as MindooDBAppMenuPlacement, av as MindooDBAppMenuPointAnchor, aw as MindooDBAppMenuRect, ax as MindooDBAppMenuRectAnchor, ay as MindooDBAppMenuSelectionResult, az as MindooDBAppMenuSeparatorItem, aA as MindooDBAppReadableAttachmentStream, aB as MindooDBAppResolvedViewDefinition, aC as MindooDBAppResolvedViewSource, aD as MindooDBAppRichTextBlockSpan, aE as MindooDBAppRichTextGetOptions, aF as MindooDBAppRichTextImmutableString, aG as MindooDBAppRichTextMarkRange, aH as MindooDBAppRichTextMaterializeValue, aI as MindooDBAppRichTextPatch, aJ as MindooDBAppRichTextScalar, aK as MindooDBAppRichTextSpliceStep, aL as MindooDBAppRichTextStep, aM as MindooDBAppRichTextStepPatch, aN as MindooDBAppRichTextTextSpan, aO as MindooDBAppRuntime, aP as MindooDBAppScanAttachmentOptions, aQ as MindooDBAppScanAttachmentResult, aR as MindooDBAppScopedDocId, aS as MindooDBAppScopedDocumentSummary, aT as MindooDBAppSession, aU as MindooDBAppShowMenuInput, aV as MindooDBAppShowMenuResult, aW as MindooDBAppTextEdit, aX as MindooDBAppTextPatch, aY as MindooDBAppThemeMode, aZ as MindooDBAppUiPreferences, a_ as MindooDBAppUpdateDocumentInput, a$ as MindooDBAppViewCursorDocumentListResult, b0 as MindooDBAppViewCursorResult, b1 as MindooDBAppViewEntry, b2 as MindooDBAppViewEntryKind, b3 as MindooDBAppViewNavigator, b4 as MindooDBAppViewNavigatorExpansionState, b5 as MindooDBAppViewNavigatorOpenOptions, b6 as MindooDBAppViewNavigatorPageOptions, b7 as MindooDBAppViewNavigatorPageResult, b8 as MindooDBAppViewNavigatorRangeQuery, b9 as MindooDBAppViewNavigatorSelectionState, ba as MindooDBAppViewport, bb as MindooDBAppWritableAttachmentStream } from './types-CQt2ObMu.js';
 export { MindooDBAppBooleanExpression, MindooDBAppExpression, MindooDBAppFilterDefinition, MindooDBAppViewCategoryChildrenPageRequest, MindooDBAppViewColumn, MindooDBAppViewColumnRole, MindooDBAppViewDefinition, MindooDBAppViewExpansionState, MindooDBAppViewExpressionBase, MindooDBAppViewExpressionDatePart, MindooDBAppViewExpressionOperation, MindooDBAppViewFieldExpression, MindooDBAppViewIfExpression, MindooDBAppViewLetExpression, MindooDBAppViewLiteralExpression, MindooDBAppViewLookupByPath, MindooDBAppViewOperationExpression, MindooDBAppViewOriginExpression, MindooDBAppViewPageRequest, MindooDBAppViewPageResult, MindooDBAppViewRow, MindooDBAppViewSortDirection, MindooDBAppViewTotalMode, MindooDBAppViewValueExpressionRef, MindooDBAppViewVariableExpression, createViewLanguage } from 'mindoodb-view-language';
 
 /**
@@ -53,13 +53,15 @@ type MindooDBRichTextHandleChangeListener = (snapshot: MindooDBAppRichTextSnapsh
 /**
  * Local rich-text span buffer for SDK apps.
  *
- * The helper deliberately mirrors the causal shape of `MindooDBTextBuffer`:
- * local editor code replaces the current span snapshot, then `flush()` sends a
- * separate `richText` patch with the document heads the snapshot was based on.
+ * Mirrors `MindooDBTextBuffer`: track edits against a base snapshot, then flush
+ * with causal `baseHeads`. Text edits prefer positional `richTextSteps` so
+ * concurrent saves merge like plain-text splices; formatting-only or structural
+ * changes fall back to full `richText` span snapshots.
  */
 declare class MindooDBRichTextHandle {
     private readonly options;
     private spansInternal;
+    private baseMaterializedText;
     private heads;
     private dirtyInternal;
     private listeners;
@@ -77,6 +79,7 @@ declare class MindooDBRichTextHandle {
     refresh(): Promise<MindooDBAppRichTextSnapshot>;
     pollOnce(): Promise<boolean>;
     flush(updateSpansConfig?: Record<string, unknown>): Promise<MindooDBRichTextHandleFlushResult>;
+    private flushTextSteps;
     private emitChange;
 }
 declare function createMindooDBRichTextHandle(options: CreateMindooDBRichTextHandleOptions): MindooDBRichTextHandle;

package/dist/index.js

@@ -1,3 +1,5 @@
+import "./chunk-QGM4M3NI.js";
+
 // src/attachmentPreview.ts
 function canPreviewAttachment(fileName, mimeType) {
   const normalizedMimeType = mimeType.toLowerCase();
@@ -732,6 +734,16 @@ var MindooDBAppDatabaseImpl = class {
         path,
         revisionId: options?.revisionId
       }),
+      getAutomergeSnapshot: async (docId, options) => await this.rpc.call("documents.automerge.getSnapshot", {
+        databaseId: this.databaseId,
+        docId,
+        revisionId: options?.revisionId
+      }),
+      applyAutomergeChanges: async (docId, patch) => await this.rpc.call("documents.automerge.applyChanges", {
+        databaseId: this.databaseId,
+        docId,
+        patch
+      }),
       create: async (input) => await this.rpc.call("documents.create", {
         databaseId: this.databaseId,
         input
@@ -997,11 +1009,18 @@ function createMindooDBAppBridge() {
 var MindooDBRichTextHandle = class {
   constructor(options) {
     this.options = options;
-    this.spansInternal = cloneSpans(options.spans ?? []);
+    const initialSpans = cloneSpans(options.spans ?? []);
+    this.spansInternal = initialSpans;
+    this.baseMaterializedText = readMaterializedRichTextText(
+      options.document.data,
+      options.path,
+      initialSpans
+    );
     this.heads = options.document.heads ? [...options.document.heads] : [];
   }
   options;
   spansInternal;
+  baseMaterializedText;
   heads;
   dirtyInternal = false;
   listeners = /* @__PURE__ */ new Set();
@@ -1041,6 +1060,7 @@ var MindooDBRichTextHandle = class {
   reconcile(document, snapshot) {
     const previous = JSON.stringify(this.spansInternal);
     this.spansInternal = cloneSpans(snapshot.spans);
+    this.baseMaterializedText = spansToPlainText(snapshot.spans);
     this.heads = snapshot.heads ?? document.heads ?? [];
     this.dirtyInternal = false;
     const changed = JSON.stringify(this.spansInternal) !== previous;
@@ -1081,14 +1101,16 @@ var MindooDBRichTextHandle = class {
         reconciled: false
       };
     }
-    const localSpansAtFlush = JSON.stringify(this.spansInternal);
-    const document = await this.options.database.documents.update(
+    const localSpansAtFlush = cloneSpans(this.spansInternal);
+    const localTextAtFlush = spansToPlainText(localSpansAtFlush);
+    const textChanged = localTextAtFlush !== this.baseMaterializedText;
+    const document = textChanged ? await this.flushTextSteps(localTextAtFlush) : await this.options.database.documents.update(
       this.options.document.id,
       {
         richText: [{
           path: this.options.path,
           baseHeads: this.heads,
-          spans: cloneSpans(this.spansInternal),
+          spans: localSpansAtFlush,
           updateSpansConfig
         }]
       }
@@ -1097,8 +1119,9 @@ var MindooDBRichTextHandle = class {
       this.options.document.id,
       this.options.path
     );
-    const reconciled = JSON.stringify(snapshot.spans) !== localSpansAtFlush;
+    const reconciled = JSON.stringify(snapshot.spans) !== JSON.stringify(localSpansAtFlush);
     this.spansInternal = cloneSpans(snapshot.spans);
+    this.baseMaterializedText = spansToPlainText(snapshot.spans);
     this.heads = snapshot.heads ?? document.heads ?? [];
     this.dirtyInternal = false;
     if (reconciled) {
@@ -1110,6 +1133,21 @@ var MindooDBRichTextHandle = class {
       reconciled
     };
   }
+  async flushTextSteps(localTextAtFlush) {
+    const edit = computeSingleSplice(this.baseMaterializedText, localTextAtFlush);
+    return this.options.database.documents.update(this.options.document.id, {
+      richTextSteps: [{
+        path: this.options.path,
+        baseHeads: this.heads,
+        steps: [{
+          type: "splice",
+          index: edit.index,
+          deleteCount: edit.deleteCount,
+          insert: edit.insert ?? ""
+        }]
+      }]
+    });
+  }
   emitChange() {
     const snapshot = {
       path: [...this.options.path],
@@ -1127,6 +1165,44 @@ function createMindooDBRichTextHandle(options) {
 function cloneSpans(spans) {
   return structuredClone(spans);
 }
+function spansToPlainText(spans) {
+  return spans.filter((span) => span.type === "text").map((span) => span.type === "text" ? span.value : "").join("");
+}
+function readMaterializedRichTextText(data, path, fallbackSpans) {
+  let value = data;
+  for (const segment of path) {
+    if (value == null || typeof value !== "object") {
+      return spansToPlainText(fallbackSpans);
+    }
+    value = value[segment];
+  }
+  if (typeof value === "string") {
+    return value.replace(/\uFFFC/g, "");
+  }
+  if (Array.isArray(value)) {
+    return spansToPlainText(value);
+  }
+  return spansToPlainText(fallbackSpans);
+}
+function computeSingleSplice(previous, next) {
+  let prefixLength = 0;
+  const maxPrefix = Math.min(previous.length, next.length);
+  while (prefixLength < maxPrefix && previous[prefixLength] === next[prefixLength]) {
+    prefixLength += 1;
+  }
+  let suffixLength = 0;
+  const previousRemaining = previous.length - prefixLength;
+  const nextRemaining = next.length - prefixLength;
+  const maxSuffix = Math.min(previousRemaining, nextRemaining);
+  while (suffixLength < maxSuffix && previous[previous.length - 1 - suffixLength] === next[next.length - 1 - suffixLength]) {
+    suffixLength += 1;
+  }
+  return {
+    index: prefixLength,
+    deleteCount: previous.length - prefixLength - suffixLength,
+    insert: next.slice(prefixLength, next.length - suffixLength)
+  };
+}
 
 // src/textBuffer.ts
 var MindooDBTextBuffer = class {
@@ -1181,7 +1257,7 @@ var MindooDBTextBuffer = class {
     if (nextValue === this.valueInternal) {
       return;
     }
-    const edit = computeSingleSplice(this.valueInternal, nextValue);
+    const edit = computeSingleSplice2(this.valueInternal, nextValue);
     this.splice(edit.index, edit.deleteCount, edit.insert ?? "");
   }
   /**
@@ -1248,7 +1324,7 @@ function readTextAtPath(data, path) {
   }
   return typeof value === "string" ? value : "";
 }
-function computeSingleSplice(previous, next) {
+function computeSingleSplice2(previous, next) {
   let prefixLength = 0;
   const maxPrefix = Math.min(previous.length, next.length);
   while (prefixLength < maxPrefix && previous[prefixLength] === next[prefixLength]) {

package/dist/testing/index.d.ts

@@ -1,4 +1,4 @@
-import { ae as MindooDBAppLaunchContext, Z as MindooDBAppDatabaseInfo, _ as MindooDBAppDocumentApi, Y as MindooDBAppCreateViewNavigatorInput, aT as MindooDBAppViewNavigator, aV as MindooDBAppViewNavigatorOpenOptions, f as MindooDBAppAttachmentApi, a as MindooDBAppBridge, aH as MindooDBAppSession, s as MindooDBAppBridgeRpcRequest, a8 as MindooDBAppHostTheme, a_ as MindooDBAppViewport, aN as MindooDBAppUiPreferences, p as MindooDBAppBridgePortMessage } from '../types-nFt-aryL.js';
+import { am as MindooDBAppLaunchContext, a2 as MindooDBAppDatabaseInfo, a3 as MindooDBAppDocumentApi, a1 as MindooDBAppCreateViewNavigatorInput, b3 as MindooDBAppViewNavigator, b5 as MindooDBAppViewNavigatorOpenOptions, f as MindooDBAppAttachmentApi, a as MindooDBAppBridge, aT as MindooDBAppSession, x as MindooDBAppBridgeRpcRequest, ad as MindooDBAppHostTheme, ba as MindooDBAppViewport, aZ as MindooDBAppUiPreferences, u as MindooDBAppBridgePortMessage } from '../types-CQt2ObMu.js';
 import 'mindoodb-view-language';
 
 type MaybePromise<T> = T | Promise<T>;