mindoodb-app-sdk 0.0.13 → 0.0.16

package/README.md

@@ -319,21 +319,56 @@ const window = await db.documents.list({
 // Read
 const doc = await db.documents.get(docId);
 
-// Create (optionally with a named document key)
+// Create (MindooDB generates a UUID7 id; optionally use a named document key)
 const created = await db.documents.create({
-  data: { title: "Meeting notes", content: "..." },
+  set: { title: "Meeting notes", content: "..." },
   decryptionKeyId: "team-key",  // omit to use "default"
 });
 
-// Update
+// Create with a caller-provided id (e.g. a known well-known document the app
+// always loads on launch, or migrating an id from another system).
+const settings = await db.documents.create({
+  id: "AppSettings",
+  set: { theme: "dark" },
+});
+// Subsequent calls with the same id return the existing document and DO NOT
+// overwrite `set`, so `documents.create({ id })` is safe to call on every app
+// launch as a "create-if-missing" primitive. Custom ids must match
+// /^[A-Za-z][A-Za-z0-9_]*$/ (first char must be a letter, subsequent chars
+// may be letters, digits, or `_`). Documents created with the same custom id
+// on different replicas merge correctly when synced.
+
+// Update top-level fields
 const updated = await db.documents.update(docId, {
-  data: { title: "Updated title" },
+  set: { title: "Updated title" },
+  unset: ["legacyField"],
+});
+
+// Update with a granular text patch (see "Collaborative text editing" below).
+// `baseHeads` is the document version this edit was authored against; Haven
+// merges these splices with any concurrent changes since `baseHeads`.
+const merged = await db.documents.update(docId, {
+  text: [
+    {
+      path: ["body"],
+      baseHeads: doc!.heads,
+      edits: [
+        { index: 0,  deleteCount: 0, insert: "Hello, " },
+        { index: 12, deleteCount: 5, insert: "team"     },
+      ],
+    },
+  ],
 });
 
 // Delete
 await db.documents.delete(docId);
+
+// Undelete (resurrect a deleted document)
+await db.documents.undelete(docId);
 ```
 
+Every `MindooDBAppDocument` snapshot also exposes a `heads?: string[]` field. Those heads identify the document's current Automerge version and are the value you pass to `baseHeads` when issuing the next text patch. After Haven applies and merges your patch, the returned document carries the new `heads` you should use for the following edit cycle.
+
 `documents.list()` is backed by Haven's internal changefeed, not by a positional offset. The query object supports:
 
 | Field | Meaning |
@@ -348,22 +383,187 @@ await db.documents.delete(docId);
 
 `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:
+
+- `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.
+
+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.
+
 When Haven can resolve the signing identity from the tenant directory, list items may also include `identityLabel` and `publicKeyFingerprint` for the latest visible change. Apps can use this to show who last touched a document without loading the full revision history first.
 
 ### Document history
 
-When the `history` capability is granted, you can walk the full revision timeline of any document:
+When the `history` capability is granted, you can walk the document revision list and load historical snapshots. Prefer `revisionId` for follow-up reads: it is a stable, DAG-backed identifier for the exact document revision, while timestamps are mainly useful for display and backwards-compatible point-in-time lookups.
 
 ```ts
 // List all revisions
 const history = await db.documents.listHistory(docId);
-// Each entry: { timestamp, publicKey, identityLabel?, isDeleted, isCurrent, summary? }
+// Each entry:
+// {
+//   revisionId,
+//   timestamp,
+//   heads?,
+//   publicKey,
+//   identityLabel?,
+//   isDeleted,
+//   isCurrent,
+//   summary?
+// }
+
+// Load the document state at an exact DAG revision
+const snapshot = await db.documents.getAtRevision(docId, history[0]!.revisionId);
+// {
+//   id,
+//   revisionId,
+//   timestamp,
+//   heads?,
+//   state: "exists" | "deleted" | "missing",
+//   data,
+//   attachments?,
+//   attachmentSnapshotRevisionId?
+// }
+
+// Timestamp lookup is still available when all you have is a timestamp.
+const pointInTime = await db.documents.getAtTimestamp(docId, history[0]!.timestamp);
+```
+
+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`.
+
+### 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.
+
+Two layers are available:
+
+- **Low level**: raw text patches via `documents.update({ text: [...] })`.
+- **High level**: `createMindooDBTextBuffer(...)` -- a small editor-friendly helper that tracks local edits and flushes them as one patch.
+
+The end-to-end flow is the same in both cases:
+
+```
+            ┌────────────────────────────────────────────────────┐
+  edit ───► │ App buffer (local string + pending splices)        │ ──► flush
+            └─────────────────────────┬──────────────────────────┘
+                                      │ documents.update({
+                                      │   text: [{ path, baseHeads, edits }]
+                                      │ })
+                                      ▼
+            ┌────────────────────────────────────────────────────┐
+            │ Haven applies edits at `baseHeads` and merges with │
+            │ concurrent changes via Automerge                   │
+            └─────────────────────────┬──────────────────────────┘
+                                      │ canonical merged document
+                                      ▼
+            ┌────────────────────────────────────────────────────┐
+            │ App reconciles its editor with the canonical text  │
+            └────────────────────────────────────────────────────┘
+```
 
-// Load the document state at a specific point in time
-const snapshot = await db.documents.getAtTimestamp(docId, history[0]!.timestamp);
-// { id, timestamp, state: "exists" | "deleted" | "missing", data }
+#### Text patch shape
+
+```ts
+interface MindooDBAppTextEdit {
+  index: number;        // 0-based position in the current string at baseHeads
+  deleteCount: number;  // number of characters to remove at `index`
+  insert?: string;      // text to insert at `index` after deletion
+}
+
+interface MindooDBAppTextPatch {
+  path: Array<string | number>; // path inside `document.data`, e.g. ["body"]
+  baseHeads?: string[];         // document version the edits were authored against
+  edits: MindooDBAppTextEdit[]; // applied in order
+}
+```
+
+Each edit is a JavaScript-style `splice(index, deleteCount, insert)`. Multiple patches in a single `update()` call are applied atomically.
+
+#### Low-level: `documents.update({ text: [...] })`
+
+If your editor already exposes raw text operations (e.g. ProseMirror or CodeMirror transactions), forward them directly:
+
+```ts
+const doc = await db.documents.get(docId);
+
+// User typed "Hello, " at the beginning of the body.
+const result = await db.documents.update(docId, {
+  text: [{
+    path: ["body"],
+    baseHeads: doc!.heads,
+    edits: [{ index: 0, deleteCount: 0, insert: "Hello, " }],
+  }],
+});
+
+// `result.data.body`  -- canonical merged text
+// `result.heads`      -- new heads to use as `baseHeads` next time
 ```
 
+When two app instances send patches concurrently against the same `baseHeads`, Haven merges both via Automerge and returns the canonical text. If the merged result differs from what your editor currently displays, replace the editor content with `result.data[path]`.
+
+#### High-level: `createMindooDBTextBuffer`
+
+For WYSIWYG editors that emit a full markdown / plain-text string after each transaction (Milkdown, TinyMCE, etc.), the SDK ships a small buffer helper that does the splice diffing and flush bookkeeping for you:
+
+```ts
+import { createMindooDBTextBuffer } from "mindoodb-app-sdk";
+
+const doc    = await db.documents.get(docId);
+const buffer = createMindooDBTextBuffer({
+  database: db,
+  document: doc!,
+  path: ["body"], // string field inside `document.data`
+});
+
+editor.value = buffer.value;
+
+// Editor reports a new full markdown value -- the buffer turns it into one splice.
+editor.on("update", (next: string) => {
+  buffer.replaceText(next);
+});
+
+// On save (e.g. Cmd+S), flush all pending edits to Haven.
+async function save() {
+  const result = await buffer.flush();
+  if (result.reconciled) {
+    // Haven merged in concurrent changes; show the canonical merged text.
+    editor.value = result.value;
+  }
+}
+
+// Re-read the document without saving (e.g. a Refresh button).
+async function refresh() {
+  const fresh = await db.documents.get(docId);
+  if (fresh && buffer.reconcile(fresh)) {
+    editor.value = buffer.value;
+  }
+}
+```
+
+Buffer API at a glance:
+
+| Member | Description |
+|---|---|
+| `value` / `toString()` | Current local text value |
+| `dirty` / `pendingCount` | Whether/how many local splices are buffered |
+| `splice(index, deleteCount, insert?)` | Record an exact text operation |
+| `replaceText(next)` | Diff `value` against `next` and record one minimal splice |
+| `reconcile(document)` | Adopt a fresh document snapshot, drop pending edits |
+| `flush()` | Send pending edits to Haven; resolves to `{ document, value, reconciled }` |
+
+`flush()` always sends the original `baseHeads` captured when the buffer was created (or last reconciled), so two windows editing the same document at the same heads will both produce a clean merge -- they will not overwrite each other.
+
+#### Concurrent-edit walkthrough
+
+1. Window A and window B both `documents.get(docId)` and create a buffer at the same `baseHeads`.
+2. Window A inserts text at the top, window B deletes a paragraph in the middle.
+3. Window A calls `buffer.flush()` first. Haven applies its patch, advances the document heads, and returns the canonical text to A.
+4. Window B calls `buffer.flush()` next. Haven still applies B's patch causally at B's original `baseHeads`, then merges with A's already-stored change. B's `result.reconciled` is `true` and `result.value` contains both A's and B's edits.
+
+#### End-to-end sample
+
+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.
+
 ### Incremental sync
 
 The changefeed-backed `documents.list()` API is also the right primitive for app-side indexes, search, and other derived caches.
@@ -454,6 +654,26 @@ await writer.close();
 await db.attachments.remove(docId, "old-file.txt");
 ```
 
+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:
+
+```ts
+const history = await db.documents.listHistory(docId);
+const revisionId = history[0]!.revisionId;
+const historical = await db.documents.getAtRevision(docId, revisionId);
+
+const historicalFiles = await db.attachments.list(docId, {
+  revisionId,
+});
+
+const historicalReader = await db.attachments.openReadStream(
+  docId,
+  historicalFiles[0]!.fileName,
+  { revisionId },
+);
+```
+
+Use `revisionId` instead of `timestamp` whenever possible. Attachment blobs can grow over time by appending chunks and changing the attachment's `lastChunkId` in newer document revisions; `revisionId` ensures Haven reads from the historical attachment reference and does not accidentally include chunks added later.
+
 ### Attachment previews
 
 Haven includes a **built-in file viewer** that your app can open for common attachment formats. This is one of the most powerful SDK features -- it works with both online and offline data, and media formats support streaming playback with skip/seek.
@@ -482,10 +702,12 @@ You can also preview attachments from a **historical document snapshot**:
 
 ```ts
 await db.attachments.openPreview(docId, "report.pdf", {
-  timestamp: historyEntry.timestamp,
+  revisionId: historyEntry.revisionId,
 });
 ```
 
+`timestamp` is still accepted in attachment options for compatibility, but `revisionId` is the preferred identifier because it targets an exact DAG revision.
+
 **Check preview support locally** before showing a preview button:
 
 ```ts
@@ -726,21 +948,42 @@ Connect options: `launchId?`, `targetOrigin?`, `connectTimeoutMs?`.
 | `create(input)` | `Promise<MindooDBAppDocument>` |
 | `update(docId, patch)` | `Promise<MindooDBAppDocument>` |
 | `delete(docId)` | `Promise<{ ok: true }>` |
+| `undelete(docId)` | `Promise<{ ok: true }>` |
 | `listHistory(docId)` | `Promise<MindooDBAppDocumentHistoryEntry[]>` |
 | `getAtTimestamp(docId, timestamp)` | `Promise<MindooDBAppHistoricalDocument>` |
+| `getAtRevision(docId, revisionId)` | `Promise<MindooDBAppHistoricalDocument>` |
 
 `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.
+
+`delete(docId)` writes a lifecycle tombstone; it does not erase the document body from the append-only history. Use `undelete(docId)` to make the latest document state live again. If you want to record a deletion reason, first call `update(docId, { set: { intendedDeletionReason: "..." } })`, then call `delete(docId)`.
+
+For `update(docId, patch)`, use `MindooDBAppUpdateDocumentInput`:
+
+```ts
+interface MindooDBAppUpdateDocumentInput {
+  set?: Record<string, unknown>;     // shallow assign top-level fields
+  unset?: string[];                  // remove top-level fields entirely
+  text?: MindooDBAppTextPatch[];     // granular collaborative text edits
+}
+```
+
+`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).
+
 ### MindooDBAppAttachmentApi
 
 | Method | Returns |
 |---|---|
-| `list(docId)` | `Promise<MindooDBAppAttachmentInfo[]>` |
+| `list(docId, options?)` | `Promise<MindooDBAppAttachmentInfo[]>` |
 | `remove(docId, attachmentName)` | `Promise<{ ok: true }>` |
-| `openReadStream(docId, attachmentName)` | `Promise<MindooDBAppReadableAttachmentStream>` |
+| `openReadStream(docId, attachmentName, options?)` | `Promise<MindooDBAppReadableAttachmentStream>` |
 | `openWriteStream(docId, attachmentName, contentType?)` | `Promise<MindooDBAppWritableAttachmentStream>` |
+| `preparePreviewSession(docId, attachmentName, options?)` | `Promise<MindooDBAppAttachmentPreviewSession>` |
 | `openPreview(docId, attachmentName, options?)` | `Promise<{ ok: true }>` |
 
+`options` accepts `{ timestamp?: number; revisionId?: string }` for read-only historical attachment access. Mutation methods (`openWriteStream`, `remove`) always target the current document.
+
 ### MindooDBAppViewNavigator
 
 | Method | Returns |
@@ -787,6 +1030,7 @@ Connect options: `launchId?`, `targetOrigin?`, `connectTimeoutMs?`.
 | Function | Description |
 |---|---|
 | `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 |
 | `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/index.d.ts

@@ -1,5 +1,5 @@
-import { M as MindooDBAppAttachmentPreviewMode, a as MindooDBAppBridge } from './types-Cqa7AQZl.js';
-export { b as MindooDBAppAttachmentApi, c as MindooDBAppAttachmentChunk, d as MindooDBAppAttachmentInfo, e as MindooDBAppAttachmentPreviewOptions, f as MindooDBAppAttachmentPreviewSession, g as MindooDBAppBridgeConnectMessage, h as MindooDBAppBridgeConnectOptions, i as MindooDBAppBridgeConnectedMessage, j as MindooDBAppBridgeErrorPayload, k as MindooDBAppBridgePortMessage, l as MindooDBAppBridgeRpcError, m as MindooDBAppBridgeRpcMessage, n as MindooDBAppBridgeRpcRequest, o as MindooDBAppBridgeRpcSuccess, p as MindooDBAppBridgeStreamAbortRequest, q as MindooDBAppBridgeStreamAck, r as MindooDBAppBridgeStreamCloseRequest, s as MindooDBAppBridgeStreamError, t as MindooDBAppBridgeStreamMessage, u as MindooDBAppBridgeStreamOpenResult, v as MindooDBAppBridgeStreamReadRequest, w as MindooDBAppBridgeStreamWriteRequest, x as MindooDBAppBridgeThemeChangedMessage, y as MindooDBAppBridgeUiPreferencesChangedMessage, z as MindooDBAppBridgeViewportChangedMessage, A as MindooDBAppCapability, B as MindooDBAppConfiguredViewCategorizationStyle, C as MindooDBAppConfiguredViewColumn, D as MindooDBAppConfiguredViewColumnRole, E as MindooDBAppConfiguredViewExpressionMode, F as MindooDBAppConfiguredViewFieldExpression, G as MindooDBAppConfiguredViewFilterDefinition, H as MindooDBAppConfiguredViewFilterMode, I as MindooDBAppConfiguredViewFilterRule, J as MindooDBAppConfiguredViewFormulaExpression, K as MindooDBAppConfiguredViewFormulaFilterDefinition, L as MindooDBAppConfiguredViewPreviewMode, N as MindooDBAppConfiguredViewRuleFilterDefinition, O as MindooDBAppConfiguredViewRuleMatchMode, P as MindooDBAppConfiguredViewRuleOperator, Q as MindooDBAppConfiguredViewValueExpression, R as MindooDBAppCreateDocumentInput, S as MindooDBAppCreateViewInput, T as MindooDBAppCreateViewNavigatorInput, U as MindooDBAppDatabase, V as MindooDBAppDatabaseInfo, W as MindooDBAppDocument, X as MindooDBAppDocumentApi, Y as MindooDBAppDocumentHeadCursorResult, Z as MindooDBAppDocumentHistoryEntry, _ as MindooDBAppDocumentListQuery, $ as MindooDBAppDocumentListResult, a0 as MindooDBAppDocumentSummary, a1 as MindooDBAppHistoricalDocument, a2 as MindooDBAppHistoryQuery, a3 as MindooDBAppHostTheme, a4 as MindooDBAppLaunchContext, a5 as MindooDBAppMenuAnchor, a6 as MindooDBAppMenuApi, a7 as MindooDBAppMenuCommandItem, a8 as MindooDBAppMenuDismissReason, a9 as MindooDBAppMenuDismissedResult, aa as MindooDBAppMenuItem, ab as MindooDBAppMenuKind, ac as MindooDBAppMenuPlacement, ad as MindooDBAppMenuPointAnchor, ae as MindooDBAppMenuRect, af as MindooDBAppMenuRectAnchor, ag as MindooDBAppMenuSelectionResult, ah as MindooDBAppMenuSeparatorItem, ai as MindooDBAppReadableAttachmentStream, aj as MindooDBAppResolvedViewDefinition, ak as MindooDBAppResolvedViewSource, al as MindooDBAppRuntime, am as MindooDBAppScopedDocId, an as MindooDBAppScopedDocumentSummary, ao as MindooDBAppSession, ap as MindooDBAppShowMenuInput, aq as MindooDBAppShowMenuResult, ar as MindooDBAppThemeMode, as as MindooDBAppUiPreferences, at as MindooDBAppUpdateDocumentInput, au as MindooDBAppViewCursorDocumentListResult, av as MindooDBAppViewCursorResult, aw as MindooDBAppViewEntry, ax as MindooDBAppViewEntryKind, ay as MindooDBAppViewNavigator, az as MindooDBAppViewNavigatorExpansionState, aA as MindooDBAppViewNavigatorOpenOptions, aB as MindooDBAppViewNavigatorPageOptions, aC as MindooDBAppViewNavigatorPageResult, aD as MindooDBAppViewNavigatorRangeQuery, aE as MindooDBAppViewNavigatorSelectionState, aF as MindooDBAppViewport, aG as MindooDBAppWritableAttachmentStream } from './types-Cqa7AQZl.js';
+import { M as MindooDBAppAttachmentPreviewMode, a as MindooDBAppBridge, b as MindooDBAppDatabase, c as MindooDBAppDocument } from './types-D0vtIHBf.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 MindooDBAppDocumentSummary, a3 as MindooDBAppHistoricalDocument, a4 as MindooDBAppHistoryQuery, a5 as MindooDBAppHostTheme, a6 as MindooDBAppLaunchContext, a7 as MindooDBAppMenuAnchor, a8 as MindooDBAppMenuApi, a9 as MindooDBAppMenuCommandItem, aa as MindooDBAppMenuDismissReason, ab as MindooDBAppMenuDismissedResult, ac as MindooDBAppMenuItem, ad as MindooDBAppMenuKind, ae as MindooDBAppMenuPlacement, af as MindooDBAppMenuPointAnchor, ag as MindooDBAppMenuRect, ah as MindooDBAppMenuRectAnchor, ai as MindooDBAppMenuSelectionResult, aj as MindooDBAppMenuSeparatorItem, ak as MindooDBAppReadableAttachmentStream, al as MindooDBAppResolvedViewDefinition, am as MindooDBAppResolvedViewSource, an as MindooDBAppRuntime, ao as MindooDBAppScopedDocId, ap as MindooDBAppScopedDocumentSummary, aq as MindooDBAppSession, ar as MindooDBAppShowMenuInput, as as MindooDBAppShowMenuResult, at as MindooDBAppTextEdit, au as MindooDBAppTextPatch, av as MindooDBAppThemeMode, aw as MindooDBAppUiPreferences, ax as MindooDBAppUpdateDocumentInput, ay as MindooDBAppViewCursorDocumentListResult, az as MindooDBAppViewCursorResult, aA as MindooDBAppViewEntry, aB as MindooDBAppViewEntryKind, aC as MindooDBAppViewNavigator, aD as MindooDBAppViewNavigatorExpansionState, aE as MindooDBAppViewNavigatorOpenOptions, aF as MindooDBAppViewNavigatorPageOptions, aG as MindooDBAppViewNavigatorPageResult, aH as MindooDBAppViewNavigatorRangeQuery, aI as MindooDBAppViewNavigatorSelectionState, aJ as MindooDBAppViewport, aK as MindooDBAppWritableAttachmentStream } from './types-D0vtIHBf.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';
 
 /**
@@ -32,9 +32,102 @@ declare function expandAbbreviatedName(value: string): string;
  * Creates the browser-side bridge entry point used by MindooDB apps.
  *
  * The returned object performs the initial postMessage handshake with the
- * Administrator host and exposes a session with document, view, and attachment
+ * Haven host and exposes a session with document, view, and attachment
  * APIs over a dedicated `MessagePort`.
  */
 declare function createMindooDBAppBridge(): MindooDBAppBridge;
 
-export { MindooDBAppAttachmentPreviewMode, MindooDBAppBridge, abbreviateCanonicalName, canPreviewAttachment, createMindooDBAppBridge, expandAbbreviatedName };
+/**
+ * Options used to create a text buffer for one string field in a MindooDB
+ * document.
+ *
+ * The buffer keeps a local editable string and records text operations that can
+ * later be flushed over the JSON bridge. `path` points to the string inside
+ * `document.data`, for example `["body"]` for a markdown body field.
+ */
+interface CreateMindooDBTextBufferOptions {
+    /** Open database handle used when `flush()` sends the buffered text patch. */
+    database: MindooDBAppDatabase;
+    /** Document snapshot the local editor state is based on. */
+    document: MindooDBAppDocument;
+    /** Path to the string field inside `document.data`. */
+    path: Array<string | number>;
+}
+/**
+ * Result returned after flushing pending text edits.
+ */
+interface MindooDBTextBufferFlushResult {
+    /** Updated document returned by Haven after applying and reconciling edits. */
+    document: MindooDBAppDocument;
+    /** Canonical text value at the configured path after the flush. */
+    value: string;
+    /**
+     * `true` when the canonical value returned by Haven differs from the local
+     * value that was flushed. This usually means concurrent edits from another
+     * app instance or sync source were merged during save and the editor should
+     * replace its visible content with `value`.
+     */
+    reconciled: boolean;
+}
+/**
+ * Local text editing buffer for SDK apps.
+ *
+ * `MindooDBTextBuffer` is intentionally not an Automerge document. It is a
+ * small app-side helper that behaves like a mutable string, keeps track of
+ * local text edits, and flushes those edits as JSON-safe operations to Haven.
+ * Haven then applies the operations against the real Automerge document using
+ * the document heads captured when this buffer was created or last reconciled.
+ *
+ * Use `splice()` when your editor can report exact text operations. Use
+ * `replaceText()` for WYSIWYG or markdown editors that expose only the full
+ * current text value; the buffer computes a minimal single-splice diff.
+ */
+declare class MindooDBTextBuffer {
+    private readonly options;
+    private valueInternal;
+    private heads;
+    private pendingEdits;
+    constructor(options: CreateMindooDBTextBufferOptions);
+    get value(): string;
+    /** Whether there are local edits that have not been flushed yet. */
+    get dirty(): boolean;
+    /** Number of pending text operations currently buffered. */
+    get pendingCount(): number;
+    /** Return the current local text value. */
+    toString(): string;
+    /**
+     * Apply an exact local text splice and queue it for the next flush.
+     *
+     * Offsets use JavaScript string indexing. The delete count is clamped to the
+     * remaining local text length so callers can safely delete to the end.
+     */
+    splice(index: number, deleteCount: number, insert?: string): void;
+    /**
+     * Replace the current local text value and queue the change as one splice.
+     *
+     * This is useful for editors such as Milkdown that can produce the full
+     * markdown string after each transaction but do not expose raw text splices.
+     */
+    replaceText(nextValue: string): void;
+    /**
+     * Replace local state from a fresh document snapshot and clear pending edits.
+     *
+     * Returns whether the text value changed. Use this after an external refresh
+     * or after receiving a document update through another app-level mechanism.
+     */
+    reconcile(document: MindooDBAppDocument): boolean;
+    /**
+     * Flush pending edits to Haven using `documents.update({ text: ... })`.
+     *
+     * The request includes the document heads this buffer is based on, allowing
+     * Haven to apply the text operations at the original causal version and merge
+     * them with any concurrent document changes. After a successful flush the
+     * buffer adopts the returned canonical value and heads, and clears the
+     * pending edit queue.
+     */
+    flush(): Promise<MindooDBTextBufferFlushResult>;
+}
+/** 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 };

package/dist/index.js

@@ -281,7 +281,7 @@ function resolveTargetWindow() {
   if (window.opener) {
     return window.opener;
   }
-  throw new Error("Could not find a MindooDB Administrator host window.");
+  throw new Error("Could not find a MindooDB Haven host window.");
 }
 function waitForConnectedPort(options, launchId) {
   const targetWindow = resolveTargetWindow();
@@ -298,16 +298,25 @@ function waitForConnectedPort(options, launchId) {
     };
     const handleMessage = (event) => {
       const payload = event.data;
-      if (!payload || payload.protocol !== PROTOCOL2 || payload.type !== "mindoodb-app:connected") {
+      if (!payload || payload.protocol !== PROTOCOL2) {
         return;
       }
-      cleanup();
-      resolve(channel.port1);
+      if (payload.type === "mindoodb-app:connected") {
+        cleanup();
+        resolve(channel.port1);
+        return;
+      }
+      if (payload.type === "mindoodb-app:error") {
+        cleanup();
+        channel.port1.close();
+        const message2 = typeof payload.error === "string" && payload.error.trim() ? payload.error : "MindooDB Haven bridge connection failed.";
+        reject(new Error(message2));
+      }
     };
     timeoutId = window.setTimeout(() => {
       cleanup();
       channel.port1.close();
-      reject(new Error(`Timed out while connecting to the MindooDB Administrator bridge for launch ${launchId}.`));
+      reject(new Error(`Timed out while connecting to the MindooDB Haven bridge for launch ${launchId}.`));
     }, timeoutMs);
     channel.port1.addEventListener("message", handleMessage);
     channel.port1.start();
@@ -665,6 +674,10 @@ var MindooDBAppDatabaseImpl = class {
         databaseId: this.databaseId,
         docId
       }),
+      undelete: async (docId) => await this.rpc.call("documents.undelete", {
+        databaseId: this.databaseId,
+        docId
+      }),
       listHistory: async (docId) => await this.rpc.call("documents.history.list", {
         databaseId: this.databaseId,
         docId
@@ -673,23 +686,32 @@ var MindooDBAppDatabaseImpl = class {
         databaseId: this.databaseId,
         docId,
         timestamp
+      }),
+      getAtRevision: async (docId, revisionId) => await this.rpc.call("documents.history.getAtRevision", {
+        databaseId: this.databaseId,
+        docId,
+        revisionId
       })
     };
     this.attachments = {
-      list: async (docId) => await this.rpc.call("attachments.list", {
+      list: async (docId, options) => await this.rpc.call("attachments.list", {
         databaseId: this.databaseId,
-        docId
+        docId,
+        timestamp: options?.timestamp,
+        revisionId: options?.revisionId
       }),
       remove: async (docId, attachmentName) => await this.rpc.call("attachments.remove", {
         databaseId: this.databaseId,
         docId,
         attachmentName
       }),
-      openReadStream: async (docId, attachmentName) => {
+      openReadStream: async (docId, attachmentName, options) => {
         const result = await this.rpc.call("attachments.openReadStream", {
           databaseId: this.databaseId,
           docId,
-          attachmentName
+          attachmentName,
+          timestamp: options?.timestamp,
+          revisionId: options?.revisionId
         });
         return new MindooDBAppReadableAttachmentStreamImpl(this.rpc, result.streamId);
       },
@@ -706,13 +728,15 @@ var MindooDBAppDatabaseImpl = class {
         databaseId: this.databaseId,
         docId,
         attachmentName,
-        timestamp: options?.timestamp
+        timestamp: options?.timestamp,
+        revisionId: options?.revisionId
       }),
       openPreview: async (docId, attachmentName, options) => await this.rpc.call("attachments.openPreview", {
         databaseId: this.databaseId,
         docId,
         attachmentName,
-        timestamp: options?.timestamp
+        timestamp: options?.timestamp,
+        revisionId: options?.revisionId
       })
     };
   }
@@ -736,7 +760,7 @@ var MindooDBAppSessionImpl = class {
     };
   }
   menus;
-  /** Returns the launch context provided by the Administrator host. */
+  /** Returns the launch context provided by the Haven host. */
   async getLaunchContext() {
     return await this.rpc.call("session.getLaunchContext", {});
   }
@@ -817,6 +841,145 @@ function createMindooDBAppBridge() {
   };
 }
 
+// src/textBuffer.ts
+var MindooDBTextBuffer = class {
+  constructor(options) {
+    this.options = options;
+    this.valueInternal = readTextAtPath(options.document.data, options.path);
+    this.heads = options.document.heads ? [...options.document.heads] : [];
+  }
+  valueInternal;
+  heads;
+  pendingEdits = [];
+  get value() {
+    return this.valueInternal;
+  }
+  /** Whether there are local edits that have not been flushed yet. */
+  get dirty() {
+    return this.pendingEdits.length > 0;
+  }
+  /** Number of pending text operations currently buffered. */
+  get pendingCount() {
+    return this.pendingEdits.length;
+  }
+  /** Return the current local text value. */
+  toString() {
+    return this.valueInternal;
+  }
+  /**
+   * Apply an exact local text splice and queue it for the next flush.
+   *
+   * Offsets use JavaScript string indexing. The delete count is clamped to the
+   * remaining local text length so callers can safely delete to the end.
+   */
+  splice(index, deleteCount, insert = "") {
+    if (!Number.isInteger(index) || index < 0 || index > this.valueInternal.length) {
+      throw new RangeError("Text splice index is out of range");
+    }
+    if (!Number.isInteger(deleteCount) || deleteCount < 0) {
+      throw new RangeError("Text splice deleteCount must be a non-negative integer");
+    }
+    const clampedDeleteCount = Math.min(deleteCount, this.valueInternal.length - index);
+    this.valueInternal = this.valueInternal.slice(0, index) + insert + this.valueInternal.slice(index + clampedDeleteCount);
+    this.pendingEdits.push({ index, deleteCount: clampedDeleteCount, insert });
+  }
+  /**
+   * Replace the current local text value and queue the change as one splice.
+   *
+   * This is useful for editors such as Milkdown that can produce the full
+   * markdown string after each transaction but do not expose raw text splices.
+   */
+  replaceText(nextValue) {
+    if (nextValue === this.valueInternal) {
+      return;
+    }
+    const edit = computeSingleSplice(this.valueInternal, nextValue);
+    this.splice(edit.index, edit.deleteCount, edit.insert ?? "");
+  }
+  /**
+   * Replace local state from a fresh document snapshot and clear pending edits.
+   *
+   * Returns whether the text value changed. Use this after an external refresh
+   * or after receiving a document update through another app-level mechanism.
+   */
+  reconcile(document) {
+    const nextValue = readTextAtPath(document.data, this.options.path);
+    const changed = nextValue !== this.valueInternal;
+    this.valueInternal = nextValue;
+    this.heads = document.heads ? [...document.heads] : [];
+    this.pendingEdits = [];
+    return changed;
+  }
+  /**
+   * Flush pending edits to Haven using `documents.update({ text: ... })`.
+   *
+   * The request includes the document heads this buffer is based on, allowing
+   * Haven to apply the text operations at the original causal version and merge
+   * them with any concurrent document changes. After a successful flush the
+   * buffer adopts the returned canonical value and heads, and clears the
+   * pending edit queue.
+   */
+  async flush() {
+    if (this.pendingEdits.length === 0) {
+      return {
+        document: this.options.document,
+        value: this.valueInternal,
+        reconciled: false
+      };
+    }
+    const localValueAtFlush = this.valueInternal;
+    const document = await this.options.database.documents.update(this.options.document.id, {
+      text: [{
+        path: this.options.path,
+        baseHeads: this.heads,
+        edits: this.pendingEdits.map((edit) => ({ ...edit }))
+      }]
+    });
+    const nextValue = readTextAtPath(document.data, this.options.path);
+    const reconciled = nextValue !== localValueAtFlush;
+    this.valueInternal = nextValue;
+    this.heads = document.heads ? [...document.heads] : [];
+    this.pendingEdits = [];
+    return {
+      document,
+      value: this.valueInternal,
+      reconciled
+    };
+  }
+};
+function createMindooDBTextBuffer(options) {
+  return new MindooDBTextBuffer(options);
+}
+function readTextAtPath(data, path) {
+  let value = data;
+  for (const segment of path) {
+    if (value == null || typeof value !== "object") {
+      return "";
+    }
+    value = value[segment];
+  }
+  return typeof value === "string" ? value : "";
+}
+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/viewLanguage.ts
 import {
   createViewLanguage,
@@ -825,9 +988,11 @@ import {
   mindooDBViewLanguageHelpersByName
 } from "mindoodb-view-language";
 export {
+  MindooDBTextBuffer,
   abbreviateCanonicalName,
   canPreviewAttachment,
   createMindooDBAppBridge,
+  createMindooDBTextBuffer,
   createViewLanguage,
   expandAbbreviatedName
 };

package/dist/testing/index.d.ts

@@ -1,4 +1,4 @@
-import { a4 as MindooDBAppLaunchContext, V as MindooDBAppDatabaseInfo, X as MindooDBAppDocumentApi, T as MindooDBAppCreateViewNavigatorInput, ay as MindooDBAppViewNavigator, aA as MindooDBAppViewNavigatorOpenOptions, b as MindooDBAppAttachmentApi, a as MindooDBAppBridge, ao as MindooDBAppSession, n as MindooDBAppBridgeRpcRequest, a3 as MindooDBAppHostTheme, aF as MindooDBAppViewport, as as MindooDBAppUiPreferences, k as MindooDBAppBridgePortMessage } from '../types-Cqa7AQZl.js';
+import { a6 as MindooDBAppLaunchContext, X as MindooDBAppDatabaseInfo, Y as MindooDBAppDocumentApi, W as MindooDBAppCreateViewNavigatorInput, aC as MindooDBAppViewNavigator, aE as MindooDBAppViewNavigatorOpenOptions, d as MindooDBAppAttachmentApi, a as MindooDBAppBridge, aq as MindooDBAppSession, q as MindooDBAppBridgeRpcRequest, a5 as MindooDBAppHostTheme, aJ as MindooDBAppViewport, aw as MindooDBAppUiPreferences, n as MindooDBAppBridgePortMessage } from '../types-D0vtIHBf.js';
 import 'mindoodb-view-language';
 
 type MaybePromise<T> = T | Promise<T>;

package/dist/testing/index.js

@@ -12,6 +12,45 @@ function createBridgeErrorPayload(error, fallbackCode = "bridge-error") {
 function cloneBytes(chunk) {
   return new Uint8Array(chunk.buffer.slice(chunk.byteOffset, chunk.byteOffset + chunk.byteLength));
 }
+function applyDocumentUpdatePatch(current, patch) {
+  const next = {
+    ...structuredClone(current),
+    ...patch.set ? structuredClone(patch.set) : {}
+  };
+  for (const key of patch.unset ?? []) {
+    Reflect.deleteProperty(next, key);
+  }
+  for (const textPatch of patch.text ?? []) {
+    applyMockTextPatch(next, textPatch.path, textPatch.edits);
+  }
+  return next;
+}
+function applyMockTextPatch(target, path, edits) {
+  if (path.length === 0) {
+    throw new Error("Text patch path must contain at least one segment");
+  }
+  let parent = target;
+  for (let index = 0; index < path.length - 1; index += 1) {
+    const segment = path[index];
+    const nextSegment = path[index + 1];
+    if (parent[segment] == null) {
+      parent[segment] = typeof nextSegment === "number" ? [] : {};
+    }
+    parent = parent[segment];
+  }
+  const leaf = path[path.length - 1];
+  let value = parent[leaf];
+  if (value == null) {
+    value = "";
+  }
+  if (typeof value !== "string") {
+    throw new Error(`Cannot apply text patch to non-string value at ${path.map(String).join(".")}`);
+  }
+  for (const edit of edits) {
+    value = value.slice(0, edit.index) + (edit.insert ?? "") + value.slice(edit.index + edit.deleteCount);
+  }
+  parent[leaf] = value;
+}
 function mergeLaunchContext(current, patch) {
   if (!patch) {
     return {
@@ -383,6 +422,7 @@ function createDefaultViewNavigator() {
 }
 function createDatabaseHandle(definition) {
   let createCounter = 0;
+  let changeCounter = 0;
   const defaultViewFactory = async () => createDefaultViewNavigator();
   const storedDocuments = /* @__PURE__ */ new Map();
   const defaultDocuments = {
@@ -428,16 +468,42 @@ function createDatabaseHandle(definition) {
       return {
         id: document.id,
         data: structuredClone(document.data),
+        heads: document.heads ? [...document.heads] : void 0,
         attachments: document.attachments ? structuredClone(document.attachments) : [],
         updatedAt: document.updatedAt
       };
     },
     async create(input) {
-      createCounter += 1;
+      const callerId = typeof input.id === "string" && input.id.length > 0 ? input.id : null;
+      if (callerId) {
+        const existing = storedDocuments.get(callerId);
+        if (existing) {
+          if (existing.isDeleted) {
+            existing.isDeleted = false;
+            existing.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
+            existing.heads = [`mock-head-${++changeCounter}`];
+          }
+          return {
+            id: existing.id,
+            data: structuredClone(existing.data),
+            heads: existing.heads ? [...existing.heads] : void 0,
+            attachments: existing.attachments ? structuredClone(existing.attachments) : [],
+            updatedAt: existing.updatedAt
+          };
+        }
+      }
+      let id;
+      if (callerId) {
+        id = callerId;
+      } else {
+        createCounter += 1;
+        id = `doc-${createCounter}`;
+      }
       const createdAt = (/* @__PURE__ */ new Date()).toISOString();
       const created = {
-        id: `doc-${createCounter}`,
-        data: { ...input.data },
+        id,
+        data: { ...input.set },
+        heads: [`mock-head-${++changeCounter}`],
         attachments: [],
         updatedAt: createdAt
       };
@@ -456,7 +522,8 @@ function createDatabaseHandle(definition) {
       const existing = storedDocuments.get(docId);
       const updated = {
         id: docId,
-        data: { ...patch.data },
+        data: applyDocumentUpdatePatch(existing?.data ?? {}, patch),
+        heads: [`mock-head-${++changeCounter}`],
         attachments: existing?.attachments ? structuredClone(existing.attachments) : [],
         updatedAt
       };
@@ -479,6 +546,18 @@ function createDatabaseHandle(definition) {
       }
       return { ok: true };
     },
+    async undelete(_docId) {
+      const existing = storedDocuments.get(_docId);
+      if (existing) {
+        storedDocuments.set(_docId, {
+          ...existing,
+          isDeleted: false,
+          heads: [`mock-head-${++changeCounter}`],
+          updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+        });
+      }
+      return { ok: true };
+    },
     async listHistory(_docId) {
       return [];
     },
@@ -487,7 +566,19 @@ function createDatabaseHandle(definition) {
         id: docId,
         timestamp,
         state: "missing",
-        data: null
+        data: null,
+        attachments: []
+      };
+    },
+    async getAtRevision(docId, revisionId) {
+      return {
+        id: docId,
+        revisionId,
+        timestamp: Date.now(),
+        heads: [],
+        state: "missing",
+        data: null,
+        attachments: []
       };
     }
   };
@@ -500,13 +591,13 @@ function createDatabaseHandle(definition) {
     }
   };
   const defaultAttachments = {
-    async list(_docId) {
+    async list(_docId, _options) {
       return [];
     },
     async remove(_docId, _attachmentName) {
       return { ok: true };
     },
-    async openReadStream(_docId, _attachmentName) {
+    async openReadStream(_docId, _attachmentName, _options) {
       return createDefaultReadableAttachmentStream();
     },
     async openWriteStream(_docId, _attachmentName, _contentType) {
@@ -921,6 +1012,8 @@ function createFakeBridgeHost(options = {}) {
         );
       case "documents.delete":
         return await state.getDatabase(String(params.databaseId)).documents.delete(String(params.docId));
+      case "documents.undelete":
+        return await state.getDatabase(String(params.databaseId)).documents.undelete(String(params.docId));
       case "documents.history.list":
         return await state.getDatabase(String(params.databaseId)).documents.listHistory(String(params.docId));
       case "documents.history.getAtTimestamp":
@@ -928,8 +1021,16 @@ function createFakeBridgeHost(options = {}) {
           String(params.docId),
           Number(params.timestamp)
         );
+      case "documents.history.getAtRevision":
+        return await state.getDatabase(String(params.databaseId)).documents.getAtRevision(
+          String(params.docId),
+          String(params.revisionId)
+        );
       case "attachments.list":
-        return await state.getDatabase(String(params.databaseId)).attachments.list(String(params.docId));
+        return await state.getDatabase(String(params.databaseId)).attachments.list(
+          String(params.docId),
+          typeof params.revisionId === "string" ? { revisionId: params.revisionId } : typeof params.timestamp === "number" ? { timestamp: params.timestamp } : void 0
+        );
       case "attachments.remove":
         return await state.getDatabase(String(params.databaseId)).attachments.remove(
           String(params.docId),
@@ -938,7 +1039,8 @@ function createFakeBridgeHost(options = {}) {
       case "attachments.openReadStream": {
         const stream = await state.getDatabase(String(params.databaseId)).attachments.openReadStream(
           String(params.docId),
-          String(params.attachmentName)
+          String(params.attachmentName),
+          typeof params.revisionId === "string" ? { revisionId: params.revisionId } : typeof params.timestamp === "number" ? { timestamp: params.timestamp } : void 0
         );
         const streamId = `read-${streamCounter += 1}`;
         readStreams.set(streamId, stream);
@@ -958,13 +1060,13 @@ function createFakeBridgeHost(options = {}) {
         return await state.getDatabase(String(params.databaseId)).attachments.openPreview(
           String(params.docId),
           String(params.attachmentName),
-          typeof params.timestamp === "number" ? { timestamp: params.timestamp } : void 0
+          typeof params.revisionId === "string" ? { revisionId: params.revisionId } : typeof params.timestamp === "number" ? { timestamp: params.timestamp } : void 0
         );
       case "attachments.preparePreviewSession":
         return await state.getDatabase(String(params.databaseId)).attachments.preparePreviewSession(
           String(params.docId),
           String(params.attachmentName),
-          typeof params.timestamp === "number" ? { timestamp: params.timestamp } : void 0
+          typeof params.revisionId === "string" ? { revisionId: params.revisionId } : typeof params.timestamp === "number" ? { timestamp: params.timestamp } : void 0
         );
       case "viewNavigators.getDefinition":
         return await (await resolveViewNavigator(String(params.navigatorId))).getDefinition();

package/dist/{types-Cqa7AQZl.d.ts → types-D0vtIHBf.d.ts}

@@ -1,8 +1,8 @@
 import { MindooDBAppBooleanExpression, MindooDBAppExpression, MindooDBAppViewSortDirection, MindooDBAppViewTotalMode, MindooDBAppViewDefinition } from 'mindoodb-view-language';
 
-/** Launch target used by the Administrator when opening an app. */
+/** Launch target used by the Haven when opening an app. */
 type MindooDBAppRuntime = "iframe" | "window";
-/** Theme mode currently active in the Administrator host UI. */
+/** Theme mode currently active in the Haven host UI. */
 type MindooDBAppThemeMode = "light" | "dark";
 /** Host theme snapshot exposed to running apps. */
 interface MindooDBAppHostTheme {
@@ -130,6 +130,8 @@ type MindooDBAppAttachmentPreviewMode = "image" | "pdf" | "text" | "markdown" |
 interface MindooDBAppAttachmentPreviewOptions {
     /** Historical snapshot timestamp previously obtained from `documents.history.getAtTimestamp()`. */
     timestamp?: number;
+    /** Stable revision id previously obtained from `documents.listHistory()`. */
+    revisionId?: MindooDBAppDocumentRevisionId;
 }
 /** Resolved Haven preview session prepared for opening in a separate tab or window. */
 interface MindooDBAppAttachmentPreviewSession {
@@ -157,12 +159,18 @@ interface MindooDBAppDocumentSummary {
 interface MindooDBAppDocument {
     id: string;
     data: Record<string, unknown>;
+    /** Current Automerge heads for causal text edit reconciliation. */
+    heads?: string[];
     attachments?: MindooDBAppAttachmentInfo[];
     updatedAt?: string;
 }
+/** Opaque persisted id for a document revision in the MindooDB DAG. */
+type MindooDBAppDocumentRevisionId = string;
 /** One entry in the document history timeline. */
 interface MindooDBAppDocumentHistoryEntry {
+    revisionId: MindooDBAppDocumentRevisionId;
     timestamp: number;
+    heads?: string[];
     publicKey: string;
     publicKeyFingerprint?: string;
     identityLabel?: string;
@@ -173,9 +181,13 @@ interface MindooDBAppDocumentHistoryEntry {
 /** Historical snapshot returned for a document at a specific timestamp. */
 interface MindooDBAppHistoricalDocument {
     id: string;
+    revisionId?: MindooDBAppDocumentRevisionId;
     timestamp: number;
+    heads?: string[];
     state: "missing" | "deleted" | "exists";
     data: Record<string, unknown> | null;
+    attachments?: MindooDBAppAttachmentInfo[];
+    attachmentSnapshotRevisionId?: MindooDBAppDocumentRevisionId | null;
 }
 /** Query options for paging through changefeed-backed document listings in a database. */
 interface MindooDBAppDocumentListQuery {
@@ -210,15 +222,58 @@ interface MindooDBAppViewCursorDocumentListResult {
     items: MindooDBAppScopedDocumentSummary[];
     nextCursor: string | null;
 }
-/** Payload used when creating a new document. */
+/**
+ * Payload used when creating a new document.
+ *
+ * `set` becomes the initial top-level document state, mirroring the update
+ * API's field-assignment language while still creating a brand-new document.
+ */
 interface MindooDBAppCreateDocumentInput {
-    data: Record<string, unknown>;
+    set: Record<string, unknown>;
     /** Optional named document key. Defaults to `"default"` when omitted. */
     decryptionKeyId?: string;
-}
-/** Patch payload used when updating an existing document. */
+    /**
+     * Optional caller-provided document id. When omitted, MindooDB generates a
+     * UUID7. When provided, the id must match `^[A-Za-z][A-Za-z0-9_]*$`: the
+     * first character is an ASCII letter and subsequent characters may be ASCII
+     * letters, ASCII digits, or `_`.
+     *
+     * If a document with this id already exists locally, MindooDB returns the
+     * existing document instead of creating a new one (idempotent create), and
+     * the values in `set` are NOT applied. Caller-provided ids are useful for
+     * loading a known well-known document directly without first building a
+     * view, and for migrations that want to preserve external ids.
+     *
+     * Documents created with the same caller-provided id on independent replicas
+     * share Automerge ancestry, so subsequent edits on either replica still
+     * merge correctly when the replicas sync.
+     */
+    id?: string;
+}
+interface MindooDBAppTextEdit {
+    index: number;
+    deleteCount: number;
+    insert?: string;
+}
+interface MindooDBAppTextPatch {
+    path: Array<string | number>;
+    baseHeads?: string[];
+    edits: MindooDBAppTextEdit[];
+}
+/**
+ * Sparse patch payload used when updating an existing document.
+ *
+ * Prefer targeted `set` / `unset` operations over whole-document rewrites so
+ * MindooDB can preserve more meaningful change history and Automerge can merge
+ * smaller, more intentional updates.
+ */
 interface MindooDBAppUpdateDocumentInput {
-    data: Record<string, unknown>;
+    /** Top-level fields to assign on the document. */
+    set?: Record<string, unknown>;
+    /** Top-level fields to remove from the document entirely. */
+    unset?: string[];
+    /** Granular text edits to apply at document paths. */
+    text?: MindooDBAppTextPatch[];
 }
 /** Query used for history lookups at a specific timestamp. */
 interface MindooDBAppHistoryQuery {
@@ -230,17 +285,23 @@ interface MindooDBAppBridgeConnectOptions {
     targetOrigin?: string;
     connectTimeoutMs?: number;
 }
-/** Initial postMessage handshake sent from the app to the Administrator. */
+/** Initial postMessage handshake sent from the app to the Haven. */
 interface MindooDBAppBridgeConnectMessage {
     protocol: "mindoodb-app-bridge";
     type: "mindoodb-app:connect";
     launchId: string;
 }
-/** Handshake acknowledgement returned by the Administrator host. */
+/** Handshake acknowledgement returned by the Haven host. */
 interface MindooDBAppBridgeConnectedMessage {
     protocol: "mindoodb-app-bridge";
     type: "mindoodb-app:connected";
 }
+/** Handshake error returned when the Haven host rejects a launch. */
+interface MindooDBAppBridgeHandshakeErrorMessage {
+    protocol: "mindoodb-app-bridge";
+    type: "mindoodb-app:error";
+    error: string;
+}
 /** Structured error payload transported over bridge RPC or stream messages. */
 interface MindooDBAppBridgeErrorPayload {
     code: string;
@@ -322,7 +383,7 @@ interface MindooDBAppBridgeStreamError {
 }
 /** Union of all non-RPC stream transport messages. */
 type MindooDBAppBridgeStreamMessage = MindooDBAppBridgeStreamReadRequest | MindooDBAppBridgeStreamWriteRequest | MindooDBAppBridgeStreamCloseRequest | MindooDBAppBridgeStreamAbortRequest | MindooDBAppAttachmentChunk | MindooDBAppBridgeStreamAck | MindooDBAppBridgeStreamError;
-/** Host-pushed event emitted when the Administrator theme changes. */
+/** Host-pushed event emitted when the Haven theme changes. */
 interface MindooDBAppBridgeThemeChangedMessage {
     protocol: "mindoodb-app-bridge";
     kind: "theme-changed";
@@ -431,8 +492,12 @@ interface MindooDBAppDocumentApi {
     delete(docId: string): Promise<{
         ok: true;
     }>;
+    undelete(docId: string): Promise<{
+        ok: true;
+    }>;
     listHistory(docId: string): Promise<MindooDBAppDocumentHistoryEntry[]>;
     getAtTimestamp(docId: string, timestamp: number): Promise<MindooDBAppHistoricalDocument>;
+    getAtRevision(docId: string, revisionId: MindooDBAppDocumentRevisionId): Promise<MindooDBAppHistoricalDocument>;
 }
 type MindooDBAppViewEntryKind = "category" | "document";
 /** Unique document identity within a multi-source view. */
@@ -556,11 +621,11 @@ interface MindooDBAppViewNavigator {
 }
 /** Attachment operations exposed by an opened database handle. */
 interface MindooDBAppAttachmentApi {
-    list(docId: string): Promise<MindooDBAppAttachmentInfo[]>;
+    list(docId: string, options?: MindooDBAppAttachmentPreviewOptions): Promise<MindooDBAppAttachmentInfo[]>;
     remove(docId: string, attachmentName: string): Promise<{
         ok: true;
     }>;
-    openReadStream(docId: string, attachmentName: string): Promise<MindooDBAppReadableAttachmentStream>;
+    openReadStream(docId: string, attachmentName: string, options?: MindooDBAppAttachmentPreviewOptions): Promise<MindooDBAppReadableAttachmentStream>;
     openWriteStream(docId: string, attachmentName: string, contentType?: string): Promise<MindooDBAppWritableAttachmentStream>;
     preparePreviewSession(docId: string, attachmentName: string, options?: MindooDBAppAttachmentPreviewOptions): Promise<MindooDBAppAttachmentPreviewSession>;
     openPreview(docId: string, attachmentName: string, options?: MindooDBAppAttachmentPreviewOptions): Promise<{
@@ -573,7 +638,7 @@ interface MindooDBAppDatabase {
     documents: MindooDBAppDocumentApi;
     attachments: MindooDBAppAttachmentApi;
 }
-/** Connected session between the running app and the Administrator host. */
+/** Connected session between the running app and the Haven host. */
 interface MindooDBAppSession {
     getLaunchContext(): Promise<MindooDBAppLaunchContext>;
     listDatabases(): Promise<MindooDBAppDatabaseInfo[]>;
@@ -592,4 +657,4 @@ interface MindooDBAppBridge {
     connect(options?: MindooDBAppBridgeConnectOptions): Promise<MindooDBAppSession>;
 }
 
-export type { MindooDBAppDocumentListResult as $, MindooDBAppCapability as A, MindooDBAppConfiguredViewCategorizationStyle as B, MindooDBAppConfiguredViewColumn as C, MindooDBAppConfiguredViewColumnRole as D, MindooDBAppConfiguredViewExpressionMode as E, MindooDBAppConfiguredViewFieldExpression as F, MindooDBAppConfiguredViewFilterDefinition as G, MindooDBAppConfiguredViewFilterMode as H, MindooDBAppConfiguredViewFilterRule as I, MindooDBAppConfiguredViewFormulaExpression as J, MindooDBAppConfiguredViewFormulaFilterDefinition as K, MindooDBAppConfiguredViewPreviewMode as L, MindooDBAppAttachmentPreviewMode as M, MindooDBAppConfiguredViewRuleFilterDefinition as N, MindooDBAppConfiguredViewRuleMatchMode as O, MindooDBAppConfiguredViewRuleOperator as P, MindooDBAppConfiguredViewValueExpression as Q, MindooDBAppCreateDocumentInput as R, MindooDBAppCreateViewInput as S, MindooDBAppCreateViewNavigatorInput as T, MindooDBAppDatabase as U, MindooDBAppDatabaseInfo as V, MindooDBAppDocument as W, MindooDBAppDocumentApi as X, MindooDBAppDocumentHeadCursorResult as Y, MindooDBAppDocumentHistoryEntry as Z, MindooDBAppDocumentListQuery as _, MindooDBAppBridge as a, MindooDBAppDocumentSummary as a0, MindooDBAppHistoricalDocument as a1, MindooDBAppHistoryQuery as a2, MindooDBAppHostTheme as a3, MindooDBAppLaunchContext as a4, MindooDBAppMenuAnchor as a5, MindooDBAppMenuApi as a6, MindooDBAppMenuCommandItem as a7, MindooDBAppMenuDismissReason as a8, MindooDBAppMenuDismissedResult as a9, MindooDBAppViewNavigatorOpenOptions as aA, MindooDBAppViewNavigatorPageOptions as aB, MindooDBAppViewNavigatorPageResult as aC, MindooDBAppViewNavigatorRangeQuery as aD, MindooDBAppViewNavigatorSelectionState as aE, MindooDBAppViewport as aF, MindooDBAppWritableAttachmentStream as aG, MindooDBAppMenuItem as aa, MindooDBAppMenuKind as ab, MindooDBAppMenuPlacement as ac, MindooDBAppMenuPointAnchor as ad, MindooDBAppMenuRect as ae, MindooDBAppMenuRectAnchor as af, MindooDBAppMenuSelectionResult as ag, MindooDBAppMenuSeparatorItem as ah, MindooDBAppReadableAttachmentStream as ai, MindooDBAppResolvedViewDefinition as aj, MindooDBAppResolvedViewSource as ak, MindooDBAppRuntime as al, MindooDBAppScopedDocId as am, MindooDBAppScopedDocumentSummary as an, MindooDBAppSession as ao, MindooDBAppShowMenuInput as ap, MindooDBAppShowMenuResult as aq, MindooDBAppThemeMode as ar, MindooDBAppUiPreferences as as, MindooDBAppUpdateDocumentInput as at, MindooDBAppViewCursorDocumentListResult as au, MindooDBAppViewCursorResult as av, MindooDBAppViewEntry as aw, MindooDBAppViewEntryKind as ax, MindooDBAppViewNavigator as ay, MindooDBAppViewNavigatorExpansionState as az, MindooDBAppAttachmentApi as b, MindooDBAppAttachmentChunk as c, MindooDBAppAttachmentInfo as d, MindooDBAppAttachmentPreviewOptions as e, MindooDBAppAttachmentPreviewSession as f, MindooDBAppBridgeConnectMessage as g, MindooDBAppBridgeConnectOptions as h, MindooDBAppBridgeConnectedMessage as i, MindooDBAppBridgeErrorPayload as j, MindooDBAppBridgePortMessage as k, MindooDBAppBridgeRpcError as l, MindooDBAppBridgeRpcMessage as m, MindooDBAppBridgeRpcRequest as n, MindooDBAppBridgeRpcSuccess as o, MindooDBAppBridgeStreamAbortRequest as p, MindooDBAppBridgeStreamAck as q, MindooDBAppBridgeStreamCloseRequest as r, MindooDBAppBridgeStreamError as s, MindooDBAppBridgeStreamMessage as t, MindooDBAppBridgeStreamOpenResult as u, MindooDBAppBridgeStreamReadRequest as v, MindooDBAppBridgeStreamWriteRequest as w, MindooDBAppBridgeThemeChangedMessage as x, MindooDBAppBridgeUiPreferencesChangedMessage as y, MindooDBAppBridgeViewportChangedMessage as z };
+export type { MindooDBAppDocumentListQuery as $, MindooDBAppBridgeThemeChangedMessage as A, MindooDBAppBridgeUiPreferencesChangedMessage as B, MindooDBAppBridgeViewportChangedMessage as C, MindooDBAppCapability as D, MindooDBAppConfiguredViewCategorizationStyle as E, MindooDBAppConfiguredViewColumn as F, MindooDBAppConfiguredViewColumnRole as G, MindooDBAppConfiguredViewExpressionMode as H, MindooDBAppConfiguredViewFieldExpression as I, MindooDBAppConfiguredViewFilterDefinition as J, MindooDBAppConfiguredViewFilterMode as K, MindooDBAppConfiguredViewFilterRule as L, MindooDBAppAttachmentPreviewMode as M, MindooDBAppConfiguredViewFormulaExpression as N, MindooDBAppConfiguredViewFormulaFilterDefinition as O, MindooDBAppConfiguredViewPreviewMode as P, MindooDBAppConfiguredViewRuleFilterDefinition as Q, MindooDBAppConfiguredViewRuleMatchMode as R, MindooDBAppConfiguredViewRuleOperator as S, MindooDBAppConfiguredViewValueExpression as T, MindooDBAppCreateDocumentInput as U, MindooDBAppCreateViewInput as V, MindooDBAppCreateViewNavigatorInput as W, MindooDBAppDatabaseInfo as X, MindooDBAppDocumentApi as Y, MindooDBAppDocumentHeadCursorResult as Z, MindooDBAppDocumentHistoryEntry as _, MindooDBAppBridge as a, MindooDBAppDocumentListResult as a0, MindooDBAppDocumentRevisionId as a1, MindooDBAppDocumentSummary as a2, MindooDBAppHistoricalDocument as a3, MindooDBAppHistoryQuery as a4, MindooDBAppHostTheme as a5, MindooDBAppLaunchContext as a6, MindooDBAppMenuAnchor as a7, MindooDBAppMenuApi as a8, MindooDBAppMenuCommandItem as a9, MindooDBAppViewEntry as aA, MindooDBAppViewEntryKind as aB, MindooDBAppViewNavigator as aC, MindooDBAppViewNavigatorExpansionState as aD, MindooDBAppViewNavigatorOpenOptions as aE, MindooDBAppViewNavigatorPageOptions as aF, MindooDBAppViewNavigatorPageResult as aG, MindooDBAppViewNavigatorRangeQuery as aH, MindooDBAppViewNavigatorSelectionState as aI, MindooDBAppViewport as aJ, MindooDBAppWritableAttachmentStream as aK, MindooDBAppMenuDismissReason as aa, MindooDBAppMenuDismissedResult as ab, MindooDBAppMenuItem as ac, MindooDBAppMenuKind as ad, MindooDBAppMenuPlacement as ae, MindooDBAppMenuPointAnchor as af, MindooDBAppMenuRect as ag, MindooDBAppMenuRectAnchor as ah, MindooDBAppMenuSelectionResult as ai, MindooDBAppMenuSeparatorItem as aj, MindooDBAppReadableAttachmentStream as ak, MindooDBAppResolvedViewDefinition as al, MindooDBAppResolvedViewSource as am, MindooDBAppRuntime as an, MindooDBAppScopedDocId as ao, MindooDBAppScopedDocumentSummary as ap, MindooDBAppSession as aq, MindooDBAppShowMenuInput as ar, MindooDBAppShowMenuResult as as, MindooDBAppTextEdit as at, MindooDBAppTextPatch as au, MindooDBAppThemeMode as av, MindooDBAppUiPreferences as aw, MindooDBAppUpdateDocumentInput as ax, MindooDBAppViewCursorDocumentListResult as ay, MindooDBAppViewCursorResult as az, MindooDBAppDatabase as b, MindooDBAppDocument as c, MindooDBAppAttachmentApi as d, MindooDBAppAttachmentChunk as e, MindooDBAppAttachmentInfo as f, MindooDBAppAttachmentPreviewOptions as g, MindooDBAppAttachmentPreviewSession as h, MindooDBAppBridgeConnectMessage as i, MindooDBAppBridgeConnectOptions as j, MindooDBAppBridgeConnectedMessage as k, MindooDBAppBridgeErrorPayload as l, MindooDBAppBridgeHandshakeErrorMessage as m, MindooDBAppBridgePortMessage as n, MindooDBAppBridgeRpcError as o, MindooDBAppBridgeRpcMessage as p, MindooDBAppBridgeRpcRequest as q, MindooDBAppBridgeRpcSuccess as r, MindooDBAppBridgeStreamAbortRequest as s, MindooDBAppBridgeStreamAck as t, MindooDBAppBridgeStreamCloseRequest as u, MindooDBAppBridgeStreamError as v, MindooDBAppBridgeStreamMessage as w, MindooDBAppBridgeStreamOpenResult as x, MindooDBAppBridgeStreamReadRequest as y, MindooDBAppBridgeStreamWriteRequest as z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mindoodb-app-sdk",
-  "version": "0.0.13",
+  "version": "0.0.16",
   "description": "MindooDB app SDK for building apps that connect to the Haven host bridge",
   "license": "ISC",
   "author": "Mindoo GmbH",
@@ -40,7 +40,7 @@
     "prepublishOnly": "npm run build && npm run test"
   },
   "dependencies": {
-    "mindoodb-view-language": "0.0.10"
+    "mindoodb-view-language": "0.0.11"
   },
   "devDependencies": {
     "@types/node": "^25.5.0",