mindoodb-app-sdk 0.0.18 → 0.0.20

package/README.md

@@ -390,11 +390,13 @@ Every `MindooDBAppDocument` snapshot also exposes a `heads?: string[]` field. Th
 
 `nextCursor` is the latest checkpoint reached by the page. Persist it after each successful call when you are building your own index or sync loop. If there were no changes after the supplied cursor, `nextCursor` is `null`.
 
-`documents.update()` accepts three independent operations on the same call:
+`documents.update()` accepts five independent kinds of operations on the same call, applied atomically to one new document revision:
 
 - `set` -- assign top-level fields (shallow JSON merge).
 - `unset` -- remove top-level fields entirely.
-- `text` -- one or more **granular text patches** applied to specific JSON paths. Each patch carries the `baseHeads` version it was authored against and is merged on the Haven side with any concurrent changes that arrived since. This is the recommended way to edit collaborative text fields like a markdown body. See [Collaborative text editing](#collaborative-text-editing) below.
+- `json` -- a **granular JSON patch** of `set` / `unset` / `listInsert` / `listDelete` operations applied at specific paths inside `document.data`, against a `baseHeads` version. See [Granular JSON edits](#granular-json-edits) below.
+- `text` -- one or more **granular text patches** applied to specific string paths. Each patch carries the `baseHeads` version it was authored against and is merged on the Haven side with any concurrent changes that arrived since. This is the recommended way to edit collaborative text fields like a markdown body. See [Collaborative text editing](#collaborative-text-editing) below.
+- `richText` -- one or more **rich-text span snapshots** for formatted-document fields (Word/.docx style). See [Collaborative rich-text editing](#collaborative-rich-text-editing) below.
 
 Prefer sending small, intentional field-level changes instead of rewriting whole documents when only a few fields changed. This keeps MindooDB change tracking more meaningful and helps Automerge produce cleaner merge results.
 
@@ -444,6 +446,85 @@ const pointInTime = await db.documents.getAtTimestamp(
 
 Historical snapshots include the document data payload as it existed at that revision. When the snapshot has attachments, `attachments` reflects the historical `_attachments` array for that same revision, including the attachment reference that Haven needs to stop at the correct historical `lastChunkId`.
 
+### Granular JSON edits
+
+When you need to edit nested objects or lists inside a document — not just top-level fields — describe the change as a **granular JSON patch** rather than rewriting the whole document. This is the model behind structured collaborative editing in apps like [`mindoodb-app-teamgrid`](https://github.com/klehmann/mindoodb-app-teamgrid), where two users can insert different rows into the same worksheet on different devices and the merge keeps both sides cleanly.
+
+A JSON patch is a bag of four operation kinds applied at specific JSON paths inside `document.data`, all carried with the document version (`baseHeads`) the app was looking at when it composed them:
+
+- `set` — assign or replace a value at a path
+- `unset` — remove a key (or list entry, when the host accepts it) at a path
+- `listInsert` — splice values into a list at a position
+- `listDelete` — remove a contiguous run of entries from a list
+
+```ts
+interface MindooDBAppJsonSetPatch {
+  path: Array<string | number>;
+  value: unknown;
+}
+
+interface MindooDBAppJsonUnsetPatch {
+  path: Array<string | number>;
+}
+
+interface MindooDBAppJsonListInsertPatch {
+  path: Array<string | number>;
+  index: number;
+  values: unknown[];
+}
+
+interface MindooDBAppJsonListDeletePatch {
+  path: Array<string | number>;
+  index: number;
+  deleteCount: number;
+}
+
+interface MindooDBAppJsonPatch {
+  baseHeads?: string[];
+  set?: MindooDBAppJsonSetPatch[];
+  unset?: MindooDBAppJsonUnsetPatch[];
+  listInsert?: MindooDBAppJsonListInsertPatch[];
+  listDelete?: MindooDBAppJsonListDeletePatch[];
+}
+```
+
+Send the patch through `documents.update({ json })`:
+
+```ts
+const doc = await db.documents.get(docId);
+
+await db.documents.update(docId, {
+  json: {
+    baseHeads: doc!.heads,
+    set: [
+      { path: ["worksheets", "ws-1", "title"], value: "Q1 numbers" },
+      {
+        path: ["worksheets", "ws-1", "cellsByRowCol", "row-3:col-2", "value"],
+        value: 42,
+      },
+    ],
+    listInsert: [
+      {
+        path: ["worksheets", "ws-1", "rowOrder"],
+        index: 5,
+        values: ["row-new"],
+      },
+    ],
+    listDelete: [
+      {
+        path: ["worksheets", "ws-1", "tombstoneRows"],
+        index: 0,
+        deleteCount: 1,
+      },
+    ],
+  },
+});
+```
+
+Haven applies the patch causally at `baseHeads` and merges it with any concurrent changes that arrived since, the same way the text and rich-text APIs do. List inserts authored against the same `baseHeads` interleave cleanly via Automerge's list CRDT instead of overwriting each other — which is exactly what makes two users inserting different rows on the same worksheet at the same time merge into a consistent grid rather than a last-writer-wins.
+
+Patch flavors compose. `set`/`unset` (top-level fields), `json`, `text`, and `richText` can all appear in the same `documents.update()` call and are applied atomically to one new document revision. Prefer small, intentional operations over whole-document rewrites so MindooDB change tracking stays meaningful and Automerge produces cleaner merges.
+
 ### Collaborative text editing
 
 MindooDB stores collaborative text fields as Automerge text CRDTs internally, but apps never touch Automerge directly -- the SDK bridge is JSON-only. Instead, your app describes text changes as **granular splice operations** against a known document version, and Haven applies and merges them on its side.
@@ -579,6 +660,239 @@ Buffer API at a glance:
 
 The [`mindoodb-app-teamedit`](https://github.com/klehmann/mindoodb-app-teamedit) sample wires `MindooDBTextBuffer` to a Milkdown markdown editor with Save / Refresh / preview pane, and is the recommended starting point for building your own collaborative text app.
 
+### Collaborative rich-text editing
+
+For structured documents that need formatting — headings, bold/italic runs, lists, tables, fonts, colors — use the **rich-text patch API**. This is the surface behind the Word/.docx mode in [`mindoodb-app-teamedit`](https://github.com/klehmann/mindoodb-app-teamedit), where two users can edit the same document at the same time and Haven merges both formatting and structure on its side via Automerge's rich-text CRDT.
+
+Rich-text fields are stored internally as Automerge rich-text, but apps never see Automerge directly. The bridge speaks JSON and represents a rich-text field as an ordered list of **spans** — text runs with marks for inline formatting, plus block markers for paragraphs, headings, lists, and tables:
+
+```ts
+interface MindooDBAppRichTextTextSpan {
+  type: "text";
+  value: string;
+  // Inline marks: bold, italic, underline, font, color, link, ...
+  marks?: Record<string, MindooDBAppRichTextMaterializeValue>;
+}
+
+interface MindooDBAppRichTextBlockSpan {
+  type: "block";
+  // Block markers: paragraph, heading, list item, table cell, ...
+  value: Record<string, MindooDBAppRichTextMaterializeValue>;
+}
+
+type MindooDBAppRichTextSpan =
+  | MindooDBAppRichTextTextSpan
+  | MindooDBAppRichTextBlockSpan;
+```
+
+#### Reading the current spans
+
+```ts
+const snapshot = await db.documents.getRichText(docId, ["body"]);
+// snapshot = { path: ["body"], heads: ["<commit>"], spans: [...] }
+
+editor.loadFromSpans(snapshot.spans);
+```
+
+`getRichText(docId, path, options?)` also accepts `{ revisionId }` so you can load the rich-text spans of an exact historical document revision (handy for read-only revision pickers).
+
+#### Writing back a span snapshot
+
+The simplest write is a full snapshot — replace the field's spans with the editor's current state:
+
+```ts
+await db.documents.update(docId, {
+  richText: [
+    {
+      path: ["body"],
+      baseHeads: snapshot.heads,
+      spans: editor.toSpans(),
+    },
+  ],
+});
+```
+
+Haven applies the snapshot via Automerge's `updateSpans` and merges it with any concurrent rich-text changes that arrived since `baseHeads`. The optional `updateSpansConfig` field is forwarded to Automerge for editors that need to tune merge behavior at the span level.
+
+#### High-level: `createMindooDBRichTextHandle`
+
+For editors that emit a complete spans array after each transaction, the SDK ships a buffer helper that mirrors `MindooDBTextBuffer`:
+
+```ts
+import { createMindooDBRichTextHandle } from "mindoodb-app-sdk";
+
+const doc = await db.documents.get(docId);
+const initial = await db.documents.getRichText(doc!.id, ["body"]);
+
+const handle = createMindooDBRichTextHandle({
+  database: db,
+  document: doc!,
+  path: ["body"],
+  spans: initial.spans,
+});
+
+editor.loadFromSpans(handle.spans);
+
+// Editor reports a fresh spans array after every change.
+editor.on("change", (spans) => {
+  handle.replaceSpans(spans);
+});
+
+// On save (e.g. Cmd+S) flush the local snapshot to Haven.
+async function save() {
+  const result = await handle.flush();
+  if (result.reconciled) {
+    // Haven merged in concurrent rich-text edits; show the canonical merged spans.
+    editor.loadFromSpans(result.snapshot.spans);
+  }
+}
+
+// Optional: poll for remote changes while the editor is idle.
+handle.startPolling(2000);
+handle.on("change", (snapshot) => {
+  if (!handle.dirty) editor.loadFromSpans(snapshot.spans);
+});
+```
+
+Handle API at a glance:
+
+| Member                               | Description                                                                   |
+| ------------------------------------ | ----------------------------------------------------------------------------- |
+| `spans`                              | Current local span snapshot                                                   |
+| `dirty`                              | Whether local edits are buffered                                              |
+| `baseHeads`                          | Heads the local snapshot was authored against                                 |
+| `replaceSpans(spans)`                | Replace the local spans buffer with a fresh snapshot                          |
+| `refresh()`                          | Re-read `getRichText` and return the canonical snapshot                       |
+| `pollOnce()`                         | Re-read and reconcile if the document advanced and there are no local edits  |
+| `startPolling(ms)` / `stopPolling()` | Poll `pollOnce` on a timer                                                    |
+| `flush(updateSpansConfig?)`          | Send pending spans to Haven; resolves to `{ document, snapshot, reconciled }` |
+| `on/off("change", listener)`         | Subscribe to local or reconciled-change events                                |
+
+Like the text buffer, the rich-text handle always sends the original `baseHeads` captured when it was created or last reconciled, so two windows editing the same document at the same heads merge correctly without overwriting each other.
+
+#### End-to-end sample
+
+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
 
 The changefeed-backed `documents.list()` API is also the right primitive for app-side indexes, search, and other derived caches.
@@ -675,12 +989,41 @@ const scan = await db.attachments.scan(docId, {
   preset: "a4-portrait",
   mimeType: "application/pdf",
 });
+// scan = { ok: true, attachment: { attachmentId, fileName, mimeType, size } }
+//   or { ok: false }                    if the user cancelled the scanner
+//   or rejected with an error           if the host has no scanner UI
 
 // Remove
 await db.attachments.remove(docId, "old-file.txt");
 ```
 
-`attachments.scan()` asks Haven to open its document scanner UI. Haven handles camera/file selection, edge detection, manual corner correction, output sizing, and filename confirmation, then writes the resulting image as a normal attachment. Hosts that do not provide scanner UI may reject this method or return `{ ok: false }`.
+`attachments.scan()` asks Haven to open its document scanner UI on top of your app. Haven handles camera or file selection, runs edge detection through a slim on-device OpenCV WebAssembly pipeline, lets the user fine-tune the corners, applies the perspective correction to the chosen output size, and writes the resulting bytes as a normal MindooDoc attachment via the same path `openWriteStream` would have taken. The scanner runs entirely locally — the picked image and the perspective-corrected result never leave the browser tab.
+
+Options shape:
+
+```ts
+type MindooDBAppDocumentScanPreset =
+  | "auto"            // free-form, keep the detected aspect ratio
+  | "a4-portrait"
+  | "a4-landscape"
+  | "letter-portrait"
+  | "letter-landscape";
+
+interface MindooDBAppScanAttachmentOptions {
+  defaultFileName?: string;                                  // suggested filename in the dialog
+  preset?: MindooDBAppDocumentScanPreset;                    // output page geometry
+  mimeType?: "image/jpeg" | "image/png" | "application/pdf"; // output format
+}
+
+interface MindooDBAppScanAttachmentResult {
+  ok: boolean;
+  attachment?: MindooDBAppAttachmentInfo | null;
+}
+```
+
+Apps need both the `attachments` and `update` capabilities for this method, because the scanner writes the resulting bytes back to the document. Hosts that do not provide scanner UI may reject this method or return `{ ok: false }`.
+
+The same scanner is also reachable as a top-level **Quick Scan** entry in Haven's sidebar. There it runs detached from any document — the user can download the resulting file or hand it to the operating system's share sheet, but the "Add to document" action is hidden because there is no document context. Apps do not need to do anything to support this; it is part of Haven, not the SDK.
 
 For historical reads, pass the same `revisionId` you received from `documents.listHistory()` or from a `MindooDBAppHistoricalDocument`. This tells Haven to resolve the attachment from that revision's document payload instead of the latest document state:
 
@@ -983,6 +1326,9 @@ 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 }>`                      |
@@ -991,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.
@@ -1003,11 +1351,13 @@ For `update(docId, patch)`, use `MindooDBAppUpdateDocumentInput`:
 interface MindooDBAppUpdateDocumentInput {
   set?: Record<string, unknown>; // shallow assign top-level fields
   unset?: string[]; // remove top-level fields entirely
+  json?: MindooDBAppJsonPatch; // granular structured edits at JSON paths
   text?: MindooDBAppTextPatch[]; // granular collaborative text edits
+  richText?: MindooDBAppRichTextPatch[]; // collaborative rich-text span snapshots
 }
 ```
 
-`set` and `unset` apply to top-level fields only. `text` patches operate on string fields at any JSON path inside `document.data` and are merged on the Haven side using the document's Automerge heads. See [Collaborative text editing](#collaborative-text-editing).
+`set` and `unset` apply to top-level fields only. `json`, `text`, and `richText` patches operate at any JSON path inside `document.data` and are merged on the Haven side using the document's Automerge heads. See [Granular JSON edits](#granular-json-edits), [Collaborative text editing](#collaborative-text-editing), and [Collaborative rich-text editing](#collaborative-rich-text-editing).
 
 ### MindooDBAppAttachmentApi
 
@@ -1070,6 +1420,7 @@ interface MindooDBAppUpdateDocumentInput {
 | ------------------------------------------ | ------------------------------------------------------------------------------------------- |
 | `createMindooDBAppBridge()`                | Create the bridge object used to connect to Haven                                           |
 | `createMindooDBTextBuffer(options)`        | Create an editor-friendly buffer for granular collaborative text edits on a document field  |
+| `createMindooDBRichTextHandle(options)`    | Create an editor-friendly handle for collaborative rich-text span snapshots on a document field |
 | `canPreviewAttachment(fileName, mimeType)` | Check if Haven can preview a file (returns mode or `null`)                                  |
 | `createViewLanguage<T>()`                  | Create a typed expression builder for view definitions                                      |
 | `abbreviateCanonicalName(value)`           | Convert a canonical Notes-style name like `cn=Jane/ou=Dev/o=Mindoo` to `Jane/Dev/Mindoo`    |

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 } from './types-jzokkBX5.js';
-export { d as MindooDBAppAttachmentApi, e as MindooDBAppAttachmentChunk, f as MindooDBAppAttachmentInfo, g as MindooDBAppAttachmentPreviewOptions, h as MindooDBAppAttachmentPreviewSession, i as MindooDBAppBridgeConnectMessage, j as MindooDBAppBridgeConnectOptions, k as MindooDBAppBridgeConnectedMessage, l as MindooDBAppBridgeErrorPayload, m as MindooDBAppBridgeHandshakeErrorMessage, n as MindooDBAppBridgePortMessage, o as MindooDBAppBridgeRpcError, p as MindooDBAppBridgeRpcMessage, q as MindooDBAppBridgeRpcRequest, r as MindooDBAppBridgeRpcSuccess, s as MindooDBAppBridgeStreamAbortRequest, t as MindooDBAppBridgeStreamAck, u as MindooDBAppBridgeStreamCloseRequest, v as MindooDBAppBridgeStreamError, w as MindooDBAppBridgeStreamMessage, x as MindooDBAppBridgeStreamOpenResult, y as MindooDBAppBridgeStreamReadRequest, z as MindooDBAppBridgeStreamWriteRequest, A as MindooDBAppBridgeThemeChangedMessage, B as MindooDBAppBridgeUiPreferencesChangedMessage, C as MindooDBAppBridgeViewportChangedMessage, D as MindooDBAppCapability, E as MindooDBAppConfiguredViewCategorizationStyle, F as MindooDBAppConfiguredViewColumn, G as MindooDBAppConfiguredViewColumnRole, H as MindooDBAppConfiguredViewExpressionMode, I as MindooDBAppConfiguredViewFieldExpression, J as MindooDBAppConfiguredViewFilterDefinition, K as MindooDBAppConfiguredViewFilterMode, L as MindooDBAppConfiguredViewFilterRule, N as MindooDBAppConfiguredViewFormulaExpression, O as MindooDBAppConfiguredViewFormulaFilterDefinition, P as MindooDBAppConfiguredViewPreviewMode, Q as MindooDBAppConfiguredViewRuleFilterDefinition, R as MindooDBAppConfiguredViewRuleMatchMode, S as MindooDBAppConfiguredViewRuleOperator, T as MindooDBAppConfiguredViewValueExpression, U as MindooDBAppCreateDocumentInput, V as MindooDBAppCreateViewInput, W as MindooDBAppCreateViewNavigatorInput, X as MindooDBAppDatabaseInfo, Y as MindooDBAppDocumentApi, Z as MindooDBAppDocumentHeadCursorResult, _ as MindooDBAppDocumentHistoryEntry, $ as MindooDBAppDocumentListQuery, a0 as MindooDBAppDocumentListResult, a1 as MindooDBAppDocumentRevisionId, a2 as MindooDBAppDocumentScanPreset, a3 as MindooDBAppDocumentSummary, a4 as MindooDBAppHistoricalDocument, a5 as MindooDBAppHistoryQuery, a6 as MindooDBAppHostTheme, a7 as MindooDBAppJsonListDeletePatch, a8 as MindooDBAppJsonListInsertPatch, a9 as MindooDBAppJsonPatch, aa as MindooDBAppJsonSetPatch, ab as MindooDBAppJsonUnsetPatch, ac as MindooDBAppLaunchContext, ad as MindooDBAppMenuAnchor, ae as MindooDBAppMenuApi, af as MindooDBAppMenuCommandItem, ag as MindooDBAppMenuDismissReason, ah as MindooDBAppMenuDismissedResult, ai as MindooDBAppMenuItem, aj as MindooDBAppMenuKind, ak as MindooDBAppMenuPlacement, al as MindooDBAppMenuPointAnchor, am as MindooDBAppMenuRect, an as MindooDBAppMenuRectAnchor, ao as MindooDBAppMenuSelectionResult, ap as MindooDBAppMenuSeparatorItem, aq as MindooDBAppReadableAttachmentStream, ar as MindooDBAppResolvedViewDefinition, as as MindooDBAppResolvedViewSource, at as MindooDBAppRuntime, au as MindooDBAppScanAttachmentOptions, av as MindooDBAppScanAttachmentResult, aw as MindooDBAppScopedDocId, ax as MindooDBAppScopedDocumentSummary, ay as MindooDBAppSession, az as MindooDBAppShowMenuInput, aA as MindooDBAppShowMenuResult, aB as MindooDBAppTextEdit, aC as MindooDBAppTextPatch, aD as MindooDBAppThemeMode, aE as MindooDBAppUiPreferences, aF as MindooDBAppUpdateDocumentInput, aG as MindooDBAppViewCursorDocumentListResult, aH as MindooDBAppViewCursorResult, aI as MindooDBAppViewEntry, aJ as MindooDBAppViewEntryKind, aK as MindooDBAppViewNavigator, aL as MindooDBAppViewNavigatorExpansionState, aM as MindooDBAppViewNavigatorOpenOptions, aN as MindooDBAppViewNavigatorPageOptions, aO as MindooDBAppViewNavigatorPageResult, aP as MindooDBAppViewNavigatorRangeQuery, aQ as MindooDBAppViewNavigatorSelectionState, aR as MindooDBAppViewport, aS as MindooDBAppWritableAttachmentStream } from './types-jzokkBX5.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';
 
 /**
@@ -37,6 +37,53 @@ declare function expandAbbreviatedName(value: string): string;
  */
 declare function createMindooDBAppBridge(): MindooDBAppBridge;
 
+interface CreateMindooDBRichTextHandleOptions {
+    database: MindooDBAppDatabase;
+    document: MindooDBAppDocument;
+    path: Array<string | number>;
+    spans?: MindooDBAppRichTextSpan[];
+    pollIntervalMs?: number;
+}
+interface MindooDBRichTextHandleFlushResult {
+    document: MindooDBAppDocument;
+    snapshot: MindooDBAppRichTextSnapshot;
+    reconciled: boolean;
+}
+type MindooDBRichTextHandleChangeListener = (snapshot: MindooDBAppRichTextSnapshot) => void;
+/**
+ * Local rich-text span buffer for SDK apps.
+ *
+ * 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;
+    private pollTimer;
+    constructor(options: CreateMindooDBRichTextHandleOptions);
+    get spans(): MindooDBAppRichTextSpan[];
+    get dirty(): boolean;
+    get baseHeads(): string[];
+    on(event: "change", listener: MindooDBRichTextHandleChangeListener): void;
+    off(event: "change", listener: MindooDBRichTextHandleChangeListener): void;
+    replaceSpans(spans: MindooDBAppRichTextSpan[]): void;
+    startPolling(intervalMs?: number): void;
+    stopPolling(): void;
+    reconcile(document: MindooDBAppDocument, snapshot: MindooDBAppRichTextSnapshot): boolean;
+    refresh(): Promise<MindooDBAppRichTextSnapshot>;
+    pollOnce(): Promise<boolean>;
+    flush(updateSpansConfig?: Record<string, unknown>): Promise<MindooDBRichTextHandleFlushResult>;
+    private flushTextSteps;
+    private emitChange;
+}
+declare function createMindooDBRichTextHandle(options: CreateMindooDBRichTextHandleOptions): MindooDBRichTextHandle;
+
 /**
  * Options used to create a text buffer for one string field in a MindooDB
  * document.
@@ -130,4 +177,4 @@ declare class MindooDBTextBuffer {
 /** Create a local text buffer for one string field in a document. */
 declare function createMindooDBTextBuffer(options: CreateMindooDBTextBufferOptions): MindooDBTextBuffer;
 
-export { type CreateMindooDBTextBufferOptions, MindooDBAppAttachmentPreviewMode, MindooDBAppBridge, MindooDBAppDatabase, MindooDBAppDocument, MindooDBTextBuffer, type MindooDBTextBufferFlushResult, abbreviateCanonicalName, canPreviewAttachment, createMindooDBAppBridge, createMindooDBTextBuffer, expandAbbreviatedName };
+export { type CreateMindooDBRichTextHandleOptions, type CreateMindooDBTextBufferOptions, MindooDBAppAttachmentPreviewMode, MindooDBAppBridge, MindooDBAppDatabase, MindooDBAppDocument, MindooDBAppRichTextSnapshot, MindooDBAppRichTextSpan, MindooDBRichTextHandle, type MindooDBRichTextHandleChangeListener, type MindooDBRichTextHandleFlushResult, MindooDBTextBuffer, type MindooDBTextBufferFlushResult, abbreviateCanonicalName, canPreviewAttachment, createMindooDBAppBridge, createMindooDBRichTextHandle, createMindooDBTextBuffer, expandAbbreviatedName };