mindoodb-app-sdk 0.0.19 → 0.0.26

package/README.md

@@ -1,12 +1,12 @@
 # mindoodb-app-sdk
 
-Build apps that run inside **MindooDB Haven** -- the browser-based workspace for end-to-end encrypted, offline-first data.
+Build apps that run inside **MindooDB Haven** -- the browser-based workspace for end-to-end encrypted, local-first data.
 
 `mindoodb-app-sdk` is the TypeScript SDK that connects your web application to Haven through a secure message bridge. Your app runs in a sandboxed iframe (or a separate browser window) and gains access to databases, documents, attachments, virtual views, and live host events -- all without ever touching encryption keys or raw sync state.
 
 ## What is a MindooDB App?
 
-[MindooDB](https://mindoodb.com) is an **end-to-end encrypted, offline-first sync database**. Data is encrypted on the client before it ever leaves the device. Under the hood it uses [Automerge](https://automerge.org/) CRDTs so multiple users can edit concurrently and conflicts resolve automatically.
+[MindooDB](https://mindoodb.com) is an **end-to-end encrypted, local-first sync database**. Data is encrypted on the client before it ever leaves the device. Under the hood it uses [Automerge](https://automerge.org/) CRDTs so multiple users can edit concurrently and conflicts resolve automatically.
 
 **Haven** is the browser-based workspace that sits on top of MindooDB. Users organize databases, applications, notes, and media on a visual grid -- think of it as a customizable home screen for encrypted data that works offline and syncs in the background.
 
@@ -772,11 +772,227 @@ Like the text buffer, the rich-text handle always sends the original `baseHeads`
 
 #### End-to-end sample
 
-The Word/.docx mode in [`mindoodb-app-teamedit`](https://github.com/klehmann/mindoodb-app-teamedit) wires `MindooDBRichTextHandle` to an `@eigenpal/docx-editor-vue` editor and is the recommended starting point for building your own collaborative rich-text app.
+The Word/.docx mode in [`mindoodb-app-teamedit`](https://github.com/klehmann/mindoodb-app-teamedit) is the **only supported in-repo use case** for the Automerge binary sync API below — it needs a local replica and binary flush because `set`/`unset` and the JSON patch APIs are not sufficient for that editor. For span-only rich-text apps, use `createMindooDBRichTextHandle` instead.
+
+### Automerge binary sync (advanced)
+
+> **Avoid these APIs unless you have no alternative.** For normal app editing, use `documents.update({ set })`, `documents.update({ unset })`, and the JSON patch operations (`text`, `richText`, `json`) documented above. `getAutomergeSnapshot` and `applyAutomergeChanges` were added as an **escape hatch** for the one case where those APIs are not enough: TeamEdit's Word/.docx mode, which hosts a local `@automerge/automerge` replica and flushes raw change bytes on save. Do not adopt binary sync for new features unless you have the same constraint — you take on an Automerge dependency, manual replica lifecycle, and a much harder integration path.
+
+If you must use binary sync, Haven decrypts the canonical document, merges incoming change batches with `Automerge.applyChanges`, and persists the result. Your app never sends encrypted blobs or sync metadata; it only sends the same binary change format Automerge produces locally.
+
+Typical flow:
+
+```
+            ┌────────────────────────────────────────────────────┐
+  open  ──► │ getAutomergeSnapshot → load local replica          │
+            └─────────────────────────┬──────────────────────────┘
+                                      │
+  edit  ──► │ Local Automerge doc (or span edits applied locally)  │
+            └─────────────────────────┬──────────────────────────┘
+                                      │ getChangesSince(baseHeads)
+                                      ▼
+            ┌────────────────────────────────────────────────────┐
+  save  ──► │ applyAutomergeChanges({ baseHeads, replicaHeads,   │
+            │                       changes })                   │
+            └─────────────────────────┬──────────────────────────┘
+                                      │ Haven merges + persists
+                                      ▼
+            ┌────────────────────────────────────────────────────┐
+            │ Apply result.changesSince locally (or skip if empty) │
+            └────────────────────────────────────────────────────┘
+```
+
+Bridge RPCs: `documents.automerge.getSnapshot` and `documents.automerge.applyChanges`.
+
+#### `getAutomergeSnapshot`
+
+Export the full internal Automerge document as a binary snapshot plus the current document heads:
+
+```ts
+const snapshot = await db.documents.getAutomergeSnapshot(docId);
+// snapshot = { binary: Uint8Array, heads: string[] }
+
+const localDoc = Automerge.load(snapshot.binary);
+const baseHeads = [...snapshot.heads];
+```
+
+Options:
+
+```ts
+interface MindooDBAppAutomergeGetOptions {
+  revisionId?: MindooDBAppDocumentRevisionId; // historical read via documents.listHistory()
+}
+```
+
+Only call this when binary sync is unavoidable — e.g. opening a local replica, refreshing after `applyAutomergeChanges`, or read-only historical preview at a `revisionId`. For normal reads, use `getRichText` or `documents.get`.
+
+#### `applyAutomergeChanges`
+
+Merge a batch of raw Automerge change bytes into the canonical document on Haven:
+
+```ts
+const changes = Automerge.getChangesSince(localDoc, baseHeads as Automerge.Heads);
+const replicaHeads = Automerge.getHeads(localDoc);
+
+const result = await db.documents.applyAutomergeChanges(docId, {
+  baseHeads, // optional metadata: heads when the local batch was authored
+  replicaHeads, // local heads after authoring; enables incremental catch-up in the response
+  changes: changes.map((change) => new Uint8Array(change)),
+});
+
+// result.document — updated MindooDBAppDocument snapshot (includes merged data + heads)
+// result.heads     — new Automerge heads after the merge
+// result.changesSince — incremental bytes to reconcile the local replica (when replicaHeads was sent)
+if (result.changesSince?.changes.length) {
+  [localDoc] = Automerge.applyChanges(
+    localDoc,
+    result.changesSince.changes.map((change) => new Uint8Array(change)),
+  );
+}
+baseHeads = [...result.heads];
+```
+
+Patch and result types:
+
+```ts
+interface MindooDBAppAutomergeChangesPatch {
+  baseHeads?: string[];   // correlation only; merge is not rejected when Haven moved on
+  replicaHeads?: string[]; // local heads after authoring `changes`; enables `changesSince` in the response
+  changes: Uint8Array[];  // from Automerge.getChangesSince (or equivalent)
+}
+
+interface MindooDBAppAutomergeChangesSince {
+  sinceHeads: string[];   // echo of `replicaHeads`
+  changes: Uint8Array[];  // apply locally with Automerge.applyChanges
+}
+
+interface MindooDBAppAutomergePatchResult {
+  document: MindooDBAppDocument;
+  heads: string[];
+  changesSince?: MindooDBAppAutomergeChangesSince;
+}
+```
+
+Haven applies `changes` with `Automerge.applyChanges` against its **current** document, so concurrent edits from other clients are merged by Automerge's CRDT logic rather than rejected. `baseHeads` is optional logging metadata — it does not gate the merge.
+
+When you include `replicaHeads` (the local replica's heads after authoring your batch), the response includes `changesSince`: the incremental change bytes your replica still needs after the merge. Apply them locally with `Automerge.applyChanges` and set `baseHeads = result.heads`. When there was no concurrent edit, `changesSince.changes` is empty and your local doc is already up to date — no full snapshot download needed. Omit `replicaHeads` only if you plan to reload via `getAutomergeSnapshot` instead.
+
+#### When to use binary sync vs JSON patches
+
+| Approach | App sends | When to use |
+| -------- | --------- | ----------- |
+| `documents.update({ set })` / `{ unset }` | Field paths | **Default** for structured document data |
+| `documents.update({ richText })` | JSON span snapshots | **Default** for rich-text fields |
+| `documents.update({ text })` | Text splices | Plain markdown / string fields |
+| `documents.update({ json })` | JSON Patch (RFC 6902) | Arbitrary nested JSON paths |
+| `applyAutomergeChanges` | Binary change bytes | **Last resort only** — TeamEdit Word/.docx with a local Automerge replica |
+
+Requires the `update` capability (same as other write operations). For historical reads, prefer `getRichText(..., { revisionId })`; only use `getAutomergeSnapshot(..., { revisionId })` when you truly need the full binary at a revision.
+
+#### Reference implementation (not a template)
+
+TeamEdit's Word/.docx mode is why these RPCs exist — see `wordAutomergeHandle.ts` in [`mindoodb-app-teamedit`](https://github.com/klehmann/mindoodb-app-teamedit). Treat it as a reference for an unsupported edge case, not as a pattern to copy into new apps.
+
+### Queries & Live Queries
+
+`documents.query()` runs ad-hoc queries against the database's **document summary buffer** on the host: declarative filtering, dynamic sorting, paging, and field projection — without materializing documents. This is the fastest way to find and order documents from an app and the right default for lists, search results, and dashboards.
+
+```ts
+import { createViewLanguage } from "mindoodb-app-sdk";
+
+const v = createViewLanguage<{ type: string; total: number }>();
+
+const result = await db.documents.query({
+  filter: v.and(
+    v.eq(v.field("type"), v.string("invoice")),
+    v.gt(v.toNumber(v.field("total")), v.number(100)),
+  ),
+  sortBy: [{ field: "total", direction: "descending" }],
+  limit: 50,
+  offset: 0,
+  fields: ["total", "customer"],
+});
+
+console.log(result.total); // matching docs before paging
+console.log(result.coverage); // "full" | "rebuilding" | "full-scan"
+for (const row of result.rows) {
+  console.log(row.docId, row.fields, row.lastModified);
+}
+```
+
+The `filter` also accepts formula source text, which the SDK parses locally before it crosses the bridge (only the JSON expression AST travels):
+
+```ts
+const invoices = await db.documents.query({
+  filter: 'v.eq(v.field("type"), "invoice")',
+});
+```
+
+Notes:
+
+- The host caps `limit` (default 200, maximum 1000) so result payloads stay bounded. Page with `offset` for more rows.
+- `coverage: "rebuilding"` means the summary buffer is still backfilling — results may be incomplete and will improve on their own.
+- Queries that reference encrypted fields or fields outside the summary configuration are rejected with a `query-not-supported` bridge error. Use a view with `useFullDocuments` (see below) or `documents.list()` for those cases.
+- Queries require the `read` capability and are not available in time-travel launches (the summary buffer reflects the live state only).
+
+**Full-text search** — a query can additionally carry a `text` clause, evaluated against the database's client-side full-text index on the host and combined with `filter` as a logical AND:
+
+```ts
+const result = await db.documents.query({
+  text: { query: "solar panels" },              // full-text match + relevance score
+  filter: 'v.eq(v.field("type"), "article")',   // optional structured filter
+});
+
+for (const row of result.rows) {
+  console.log(row.docId, row.textScore);        // higher score = better match
+}
+```
+
+- Options: `fields` (restrict matching to specific index fields), `prefix` (default `true` — `"sol"` matches `"solar"`), `fuzzy` (edit-distance tolerance, default off), `combineWith` (`"AND"` default | `"OR"`).
+- Rows gain a `textScore`; without an explicit `sortBy`, results come best score first. Sorting can reference the score explicitly with `sortBy: [{ special: "textScore", direction: "descending" }]`.
+- Full-text indexing is **opt-in per database** (`fulltextSetup` in the `dbsetup` document). A `text` clause against a database without it is rejected with a `fulltext-not-enabled` bridge error — catch it and hide/disable the search UI.
+- `liveQuery` supports `text` clauses unchanged; the host rounds scores in its result fingerprint so minor relevance drift does not spam your callback.
+
+**Enabling full-text indexing** — apps turn indexing on themselves through the database handle. The configuration is stored in the synced `dbsetup` document, so it applies on every replica (each device builds its own local, encrypted index):
+
+```ts
+// Idempotent — safe to call on every app start (no write when unchanged).
+// Requires the `update` capability.
+await db.setFulltextSetup({
+  enabled: true,
+  attachments: true, // index text extracted from attachments (PDF, Office, …)
+  language: "de",    // BCP-47 tag steering tokenization; omit for language-neutral
+});
+
+const setup = await db.getFulltextSetup(); // null when never configured
+```
+
+- Without `include`, every non-underscore top-level field with extractable text is indexed (auto mode). Pass `include: ["subject", "body"]` to pin the indexed fields, including nested/long-text fields outside the summary buffer.
+- `attachments: true` indexes attachment text under the synthetic `_attachments` field using the host's extractors (Haven ships PDF, Office, and plain-text extractors). Restrict a query to attachment content with `text: { query, fields: ["_attachments"] }`.
+- Changing the configuration (including `language`) rebuilds the index in the background; queries during the rebuild report `coverage: "rebuilding"`.
+
+**Live queries** keep a query result up to date. The callback receives the initial result and runs again whenever the result actually changed — the host coalesces bursts of writes and fingerprints results, so you only hear about real changes:
+
+```ts
+const subscription = await db.documents.liveQuery(
+  { filter: 'v.eq(v.field("status"), "open")', limit: 100 },
+  (result) => {
+    renderList(result.rows);
+  },
+);
+
+// Force a re-evaluation (delivers a result even when nothing changed):
+await subscription.refresh();
+
+// Always dispose when the consuming UI goes away:
+await subscription.dispose();
+```
+
+Live query results are pushed from the host over the bridge port — no polling. Subscriptions are cleaned up automatically when the app disconnects, but dispose them explicitly when the UI that consumes them unmounts.
 
 ### Incremental sync
 
-The changefeed-backed `documents.list()` API is also the right primitive for app-side indexes, search, and other derived caches.
+The changefeed-backed `documents.list()` API is also the right primitive for app-side indexes, search, and other derived caches. For plain "show me matching documents" use cases, prefer [`documents.query()`](#queries--live-queries); the changefeed shines when you need deletions and a durable resume checkpoint for derived state.
 
 **Initial scan from the beginning:**
 
@@ -1106,13 +1322,28 @@ await navigator.setExpansionState(expansion);
 await navigator.setSelectionState(selection);
 ```
 
+**Live updates** -- the host keeps the view bound to its source databases' change feeds. Subscribe with `onDidUpdate` and re-read the visible page when it fires; there is no need to poll or call `refresh()`:
+
+```ts
+const unsubscribe = navigator.onDidUpdate(({ addedCount, removedCount }) => {
+  console.log(`view changed: +${addedCount} / -${removedCount}`);
+  void rerenderVisiblePage();
+});
+
+// later, when the consuming UI unmounts:
+unsubscribe();
+```
+
 The expression language is fully declarative: apps define filter and column logic through a typed builder API that compiles to JSON-safe expression objects. No app-provided JavaScript runs inside the bridge host.
 
 #### Performance notes
 
+- Navigator views are built **summary-first**: whenever the view definition (filter + column expressions) can be answered from the database's document summary buffer, the host feeds the view from the summary without materializing a single document. Views fall back to the (slower) document path automatically when they need decrypted fields, JS value functions, or fields outside the summary configuration.
+- Pass `useFullDocuments: true` in `createViewNavigator` input to force the document path explicitly — the escape hatch for views that deliberately need full document data.
 - `goto*()` and `getCurrentEntry()` are lightweight stateful cursor operations. They may still produce many bridge round-trips if you call them for every rendered row.
 - `entriesForward()` and `entriesBackward()` exist specifically to reduce those round-trips for UI rendering.
-- `refresh()` rebuilds or invalidates the host-side navigator state and should be treated as an expensive operation compared to simple cursor movement.
+- `refresh()` performs an incremental catch-up on the host-side view (no pipeline rebuild). With `onDidUpdate` in place you rarely need it — the host pushes updates on its own.
+- `session.listDocumentsSinceViewCursor(cursor)` remains available as a **legacy polling/delta-sync path**; prefer `onDidUpdate` pushes and `documents.liveQuery()` for keeping UI current.
 - Child/key/range helpers operate on the same host-side navigator session. They do not create a separate query engine.
 
 Available expression helpers:
@@ -1124,7 +1355,7 @@ Available expression helpers:
 - **String helpers:** `concat()`, `lower()`, `upper()`, `trim()`, `contains()`, `startsWith()`, `endsWith()`
 - **Null/existence:** `coalesce()`, `exists()`, `notExists()`
 - **Date/path:** `datePart()`, `pathJoin()`
-- **Control flow:** `ifElse()`, `let()`
+- **Control flow:** `ifElse()`, `let()` — `ifElse()` accepts multiple condition/value pairs followed by a default, like Domino's `@If`: `v.ifElse(cond1, val1, cond2, val2, default)`
 
 The full language guide lives in the `mindoodb-view-language` package. The SDK re-exports `createViewLanguage()` for convenience.
 
@@ -1195,19 +1426,25 @@ Connect options: `launchId?`, `targetOrigin?`, `connectTimeoutMs?`.
 
 ### MindooDBAppDatabase
 
-| Property / Method | Returns                            |
-| ----------------- | ---------------------------------- |
-| `info()`          | `Promise<MindooDBAppDatabaseInfo>` |
-| `documents`       | `MindooDBAppDocumentApi`           |
-| `attachments`     | `MindooDBAppAttachmentApi`         |
+| Property / Method            | Returns                                        |
+| ---------------------------- | ---------------------------------------------- |
+| `info()`                     | `Promise<MindooDBAppDatabaseInfo>`             |
+| `documents`                  | `MindooDBAppDocumentApi`                       |
+| `attachments`                | `MindooDBAppAttachmentApi`                     |
+| `getFulltextSetup()`         | `Promise<MindooDBAppFulltextSetup \| null>`    |
+| `setFulltextSetup(config)`   | `Promise<void>`                                |
 
 ### MindooDBAppDocumentApi
 
 | Method                             | Returns                                      |
 | ---------------------------------- | -------------------------------------------- |
+| `query(query?)`                    | `Promise<MindooDBAppQueryResult>`            |
+| `liveQuery(query, onResult)`       | `Promise<MindooDBAppLiveQuerySubscription>`  |
 | `list(query?)`                     | `Promise<MindooDBAppDocumentListResult>`     |
 | `get(docId)`                       | `Promise<MindooDBAppDocument \| null>`       |
 | `getRichText(docId, path, opts?)`  | `Promise<MindooDBAppRichTextSnapshot>`       |
+| `getAutomergeSnapshot(docId, opts?)` | `Promise<MindooDBAppAutomergeSnapshot>`   |
+| `applyAutomergeChanges(docId, patch)` | `Promise<MindooDBAppAutomergePatchResult>` |
 | `create(input)`                    | `Promise<MindooDBAppDocument>`               |
 | `update(docId, patch)`             | `Promise<MindooDBAppDocument>`               |
 | `delete(docId)`                    | `Promise<{ ok: true }>`                      |
@@ -1216,6 +1453,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.
@@ -1255,7 +1494,9 @@ interface MindooDBAppUpdateDocumentInput {
 | Method                                                     | Returns                                           |
 | ---------------------------------------------------------- | ------------------------------------------------- |
 | `getDefinition()`                                          | `Promise<MindooDBAppViewDefinition>`              |
-| `refresh()`                                                | `Promise<void>`                                   |
+| `refresh()`                                                | `Promise<string \| null>` (new view cursor)       |
+| `onDidUpdate(listener)`                                    | `() => void` (unsubscribe)                        |
+| `getViewCursor()`                                          | `Promise<string \| null>`                         |
 | `getCurrentEntry()`                                        | `Promise<MindooDBAppViewEntry \| null>`           |
 | `gotoFirst()` / `gotoLast()`                               | `Promise<boolean>`                                |
 | `gotoNext()` / `gotoPrev()`                                | `Promise<boolean>`                                |

package/TESTING.md

@@ -12,6 +12,15 @@ import {
 } from "mindoodb-app-sdk/testing";
 ```
 
+The testing entrypoint emulates document storage with real Automerge documents,
+so `@automerge/automerge` is declared as an optional peer dependency. Add it to
+your app's `devDependencies` when you import `mindoodb-app-sdk/testing`
+(the runtime SDK entrypoint does not need it):
+
+```bash
+pnpm add -D @automerge/automerge
+```
+
 ## Pick a level
 
 ### Level 1: simple app tests
@@ -93,6 +102,30 @@ Each database entry can provide:
 - `methods.documents`
 - `methods.views` for session-level `createView()` and `openView()` calls
 - `methods.attachments`
+- `fulltextSetup` — the initial config returned by `db.getFulltextSetup()`; `db.setFulltextSetup()` overwrites it for the lifetime of the handle. Use this to test your app's full-text bootstrap logic. Note the mock evaluates `text` query clauses regardless of this config.
+
+The default in-memory document store also implements `documents.query()` and `documents.liveQuery()`: expression and formula-string filters are evaluated against the seeded documents, `sortBy`/`limit`/`offset` work as documented, and live query callbacks fire automatically after `create`/`update`/`delete`/`undelete` mutations. Full-text `text` clauses are supported with a deterministic mock implementation (token matching with prefix/AND semantics and an occurrence-count `textScore`) — assert on membership and relative ordering, not absolute scores, since real hosts use a BM25-style engine. That means app code built on queries and live queries is testable at Level 1 without any extra setup:
+
+```ts
+const session = await mock.bridge.connect();
+const db = await session.openDatabase("main");
+
+await db.documents.create({ set: { type: "invoice", total: 120 } });
+
+const result = await db.documents.query({
+  filter: 'v.eq(v.field("type"), "invoice")',
+  sortBy: [{ field: "total", direction: "descending" }],
+});
+expect(result.rows).toHaveLength(1);
+
+const updates: number[] = [];
+const sub = await db.documents.liveQuery(
+  { filter: 'v.eq(v.field("type"), "invoice")' },
+  (r) => updates.push(r.total),
+);
+await db.documents.create({ set: { type: "invoice", total: 50 } });
+await sub.dispose();
+```
 
 ## Level 2 example
 
@@ -161,10 +194,14 @@ Useful Level 2 methods:
 - `dispose()`
 - `emitThemeChange()`
 - `emitViewportChange()`
+- `emitQueryResult()` — push a `query-result` message to live query subscribers
+- `emitViewChanged()` — push a `view-changed` message to navigator `onDidUpdate` listeners
 - `setRequestHandler()`
 - `clearRequestHandler()`
 - `postPortMessage()`
 
+The built-in request handling also covers `documents.query` and the `documents.liveQuery.*` RPCs against the seeded documents, so `db.documents.query()` / `db.documents.liveQuery()` and `navigator.onDidUpdate()` work end-to-end over the real bridge transport in Level 2 tests.
+
 ## When to use which level
 
 Choose Level 1 when:

package/dist/index.d.ts

@@ -1,6 +1,8 @@
-import { M as MindooDBAppAttachmentPreviewMode, a as MindooDBAppBridge, b as MindooDBAppDatabase, c as MindooDBAppDocument, d as MindooDBAppRichTextSpan, e as MindooDBAppRichTextSnapshot } from './types-nFt-aryL.js';
-export { f as MindooDBAppAttachmentApi, g as MindooDBAppAttachmentChunk, h as MindooDBAppAttachmentInfo, i as MindooDBAppAttachmentPreviewOptions, j as MindooDBAppAttachmentPreviewSession, k as MindooDBAppBridgeConnectMessage, l as MindooDBAppBridgeConnectOptions, m as MindooDBAppBridgeConnectedMessage, n as MindooDBAppBridgeErrorPayload, o as MindooDBAppBridgeHandshakeErrorMessage, p as MindooDBAppBridgePortMessage, q as MindooDBAppBridgeRpcError, r as MindooDBAppBridgeRpcMessage, s as MindooDBAppBridgeRpcRequest, t as MindooDBAppBridgeRpcSuccess, u as MindooDBAppBridgeStreamAbortRequest, v as MindooDBAppBridgeStreamAck, w as MindooDBAppBridgeStreamCloseRequest, x as MindooDBAppBridgeStreamError, y as MindooDBAppBridgeStreamMessage, z as MindooDBAppBridgeStreamOpenResult, A as MindooDBAppBridgeStreamReadRequest, B as MindooDBAppBridgeStreamWriteRequest, C as MindooDBAppBridgeThemeChangedMessage, D as MindooDBAppBridgeUiPreferencesChangedMessage, E as MindooDBAppBridgeViewportChangedMessage, F as MindooDBAppCapability, G as MindooDBAppConfiguredViewCategorizationStyle, H as MindooDBAppConfiguredViewColumn, I as MindooDBAppConfiguredViewColumnRole, J as MindooDBAppConfiguredViewExpressionMode, K as MindooDBAppConfiguredViewFieldExpression, L as MindooDBAppConfiguredViewFilterDefinition, N as MindooDBAppConfiguredViewFilterMode, O as MindooDBAppConfiguredViewFilterRule, P as MindooDBAppConfiguredViewFormulaExpression, Q as MindooDBAppConfiguredViewFormulaFilterDefinition, R as MindooDBAppConfiguredViewPreviewMode, S as MindooDBAppConfiguredViewRuleFilterDefinition, T as MindooDBAppConfiguredViewRuleMatchMode, U as MindooDBAppConfiguredViewRuleOperator, V as MindooDBAppConfiguredViewValueExpression, W as MindooDBAppCreateDocumentInput, X as MindooDBAppCreateViewInput, Y as MindooDBAppCreateViewNavigatorInput, Z as MindooDBAppDatabaseInfo, _ as MindooDBAppDocumentApi, $ as MindooDBAppDocumentHeadCursorResult, a0 as MindooDBAppDocumentHistoryEntry, a1 as MindooDBAppDocumentListQuery, a2 as MindooDBAppDocumentListResult, a3 as MindooDBAppDocumentRevisionId, a4 as MindooDBAppDocumentScanPreset, a5 as MindooDBAppDocumentSummary, a6 as MindooDBAppHistoricalDocument, a7 as MindooDBAppHistoryQuery, a8 as MindooDBAppHostTheme, a9 as MindooDBAppJsonListDeletePatch, aa as MindooDBAppJsonListInsertPatch, ab as MindooDBAppJsonPatch, ac as MindooDBAppJsonSetPatch, ad as MindooDBAppJsonUnsetPatch, ae as MindooDBAppLaunchContext, af as MindooDBAppMenuAnchor, ag as MindooDBAppMenuApi, ah as MindooDBAppMenuCommandItem, ai as MindooDBAppMenuDismissReason, aj as MindooDBAppMenuDismissedResult, ak as MindooDBAppMenuItem, al as MindooDBAppMenuKind, am as MindooDBAppMenuPlacement, an as MindooDBAppMenuPointAnchor, ao as MindooDBAppMenuRect, ap as MindooDBAppMenuRectAnchor, aq as MindooDBAppMenuSelectionResult, ar as MindooDBAppMenuSeparatorItem, as as MindooDBAppReadableAttachmentStream, at as MindooDBAppResolvedViewDefinition, au as MindooDBAppResolvedViewSource, av as MindooDBAppRichTextBlockSpan, aw as MindooDBAppRichTextGetOptions, ax as MindooDBAppRichTextImmutableString, ay as MindooDBAppRichTextMaterializeValue, az as MindooDBAppRichTextPatch, aA as MindooDBAppRichTextScalar, aB as MindooDBAppRichTextTextSpan, aC as MindooDBAppRuntime, aD as MindooDBAppScanAttachmentOptions, aE as MindooDBAppScanAttachmentResult, aF as MindooDBAppScopedDocId, aG as MindooDBAppScopedDocumentSummary, aH as MindooDBAppSession, aI as MindooDBAppShowMenuInput, aJ as MindooDBAppShowMenuResult, aK as MindooDBAppTextEdit, aL as MindooDBAppTextPatch, aM as MindooDBAppThemeMode, aN as MindooDBAppUiPreferences, aO as MindooDBAppUpdateDocumentInput, aP as MindooDBAppViewCursorDocumentListResult, aQ as MindooDBAppViewCursorResult, aR as MindooDBAppViewEntry, aS as MindooDBAppViewEntryKind, aT as MindooDBAppViewNavigator, aU as MindooDBAppViewNavigatorExpansionState, aV as MindooDBAppViewNavigatorOpenOptions, aW as MindooDBAppViewNavigatorPageOptions, aX as MindooDBAppViewNavigatorPageResult, aY as MindooDBAppViewNavigatorRangeQuery, aZ as MindooDBAppViewNavigatorSelectionState, a_ as MindooDBAppViewport, a$ as MindooDBAppWritableAttachmentStream } from './types-nFt-aryL.js';
+import { M as MindooDBAppAttachmentPreviewMode, a as MindooDBAppBridge, b as MindooDBAppDatabase, c as MindooDBAppDocument, d as MindooDBAppRichTextSpan, e as MindooDBAppRichTextSnapshot } from './types-B6vEy1VC.js';
+export { f as MindooDBAppAccessDecision, g as MindooDBAppAccessTier, h as MindooDBAppAttachmentApi, i as MindooDBAppAttachmentChunk, j as MindooDBAppAttachmentInfo, k as MindooDBAppAttachmentPreviewOptions, l as MindooDBAppAttachmentPreviewSession, m as MindooDBAppAutomergeChangesPatch, n as MindooDBAppAutomergeChangesSince, o as MindooDBAppAutomergeGetOptions, p as MindooDBAppAutomergePatchResult, q as MindooDBAppAutomergeSnapshot, r as MindooDBAppBridgeConnectMessage, s as MindooDBAppBridgeConnectOptions, t as MindooDBAppBridgeConnectedMessage, u as MindooDBAppBridgeErrorPayload, v as MindooDBAppBridgeHandshakeErrorMessage, w as MindooDBAppBridgeLocaleChangedMessage, x as MindooDBAppBridgePortMessage, y as MindooDBAppBridgeQueryResultMessage, z as MindooDBAppBridgeRpcError, A as MindooDBAppBridgeRpcMessage, B as MindooDBAppBridgeRpcRequest, C as MindooDBAppBridgeRpcSuccess, D as MindooDBAppBridgeStreamAbortRequest, E as MindooDBAppBridgeStreamAck, F as MindooDBAppBridgeStreamCloseRequest, G as MindooDBAppBridgeStreamError, H as MindooDBAppBridgeStreamMessage, I as MindooDBAppBridgeStreamOpenResult, J as MindooDBAppBridgeStreamReadRequest, K as MindooDBAppBridgeStreamWriteRequest, L as MindooDBAppBridgeThemeChangedMessage, N as MindooDBAppBridgeUiPreferencesChangedMessage, O as MindooDBAppBridgeViewChangedMessage, P as MindooDBAppBridgeViewportChangedMessage, Q as MindooDBAppCapability, R as MindooDBAppConfiguredViewCategorizationStyle, S as MindooDBAppConfiguredViewColumn, T as MindooDBAppConfiguredViewColumnRole, U as MindooDBAppConfiguredViewExpressionMode, V as MindooDBAppConfiguredViewFieldExpression, W as MindooDBAppConfiguredViewFilterDefinition, X as MindooDBAppConfiguredViewFilterMode, Y as MindooDBAppConfiguredViewFilterRule, Z as MindooDBAppConfiguredViewFormulaExpression, _ as MindooDBAppConfiguredViewFormulaFilterDefinition, $ as MindooDBAppConfiguredViewPreviewMode, a0 as MindooDBAppConfiguredViewRuleFilterDefinition, a1 as MindooDBAppConfiguredViewRuleMatchMode, a2 as MindooDBAppConfiguredViewRuleOperator, a3 as MindooDBAppConfiguredViewValueExpression, a4 as MindooDBAppCreateDocumentInput, a5 as MindooDBAppCreateViewInput, a6 as MindooDBAppCreateViewNavigatorInput, a7 as MindooDBAppDatabaseInfo, a8 as MindooDBAppDocumentApi, a9 as MindooDBAppDocumentHeadCursorResult, aa as MindooDBAppDocumentHistoryEntry, ab as MindooDBAppDocumentListQuery, ac as MindooDBAppDocumentListResult, ad as MindooDBAppDocumentQuery, ae as MindooDBAppDocumentRevisionId, af as MindooDBAppDocumentScanPreset, ag as MindooDBAppDocumentSummary, ah as MindooDBAppExtractionSetup, ai as MindooDBAppFulltextSetup, aj as MindooDBAppHistoricalDocument, ak as MindooDBAppHistoryQuery, al as MindooDBAppHostTheme, am as MindooDBAppJsonListDeletePatch, an as MindooDBAppJsonListInsertPatch, ao as MindooDBAppJsonPatch, ap as MindooDBAppJsonSetPatch, aq as MindooDBAppJsonTextMarkPatch, ar as MindooDBAppJsonTextSplicePatch, as as MindooDBAppJsonTextUnmarkPatch, at as MindooDBAppJsonUnsetPatch, au as MindooDBAppLaunchContext, av as MindooDBAppLiveQuerySubscription, aw as MindooDBAppMenuAnchor, ax as MindooDBAppMenuApi, ay as MindooDBAppMenuCommandItem, az as MindooDBAppMenuDismissReason, aA as MindooDBAppMenuDismissedResult, aB as MindooDBAppMenuItem, aC as MindooDBAppMenuKind, aD as MindooDBAppMenuPlacement, aE as MindooDBAppMenuPointAnchor, aF as MindooDBAppMenuRect, aG as MindooDBAppMenuRectAnchor, aH as MindooDBAppMenuSelectionResult, aI as MindooDBAppMenuSeparatorItem, aJ as MindooDBAppQueryCoverage, aK as MindooDBAppQueryResult, aL as MindooDBAppQueryRow, aM as MindooDBAppQuerySortKey, aN as MindooDBAppQueryTextClause, aO as MindooDBAppReadableAttachmentStream, aP as MindooDBAppResolvedViewDefinition, aQ as MindooDBAppResolvedViewSource, aR as MindooDBAppRichTextBlockSpan, aS as MindooDBAppRichTextGetOptions, aT as MindooDBAppRichTextImmutableString, aU as MindooDBAppRichTextMarkRange, aV as MindooDBAppRichTextMaterializeValue, aW as MindooDBAppRichTextPatch, aX as MindooDBAppRichTextScalar, aY as MindooDBAppRichTextSpliceStep, aZ as MindooDBAppRichTextStep, a_ as MindooDBAppRichTextStepPatch, a$ as MindooDBAppRichTextTextSpan, b0 as MindooDBAppRuntime, b1 as MindooDBAppScanAttachmentOptions, b2 as MindooDBAppScanAttachmentResult, b3 as MindooDBAppScopedDocId, b4 as MindooDBAppScopedDocumentSummary, b5 as MindooDBAppSession, b6 as MindooDBAppShowMenuInput, b7 as MindooDBAppShowMenuResult, b8 as MindooDBAppTextEdit, b9 as MindooDBAppTextPatch, ba as MindooDBAppThemeMode, bb as MindooDBAppUiPreferences, bc as MindooDBAppUpdateDocumentInput, bd as MindooDBAppViewCursorDocumentListResult, be as MindooDBAppViewCursorResult, bf as MindooDBAppViewEntry, bg as MindooDBAppViewEntryKind, bh as MindooDBAppViewNavigator, bi as MindooDBAppViewNavigatorExpansionState, bj as MindooDBAppViewNavigatorOpenOptions, bk as MindooDBAppViewNavigatorPageOptions, bl as MindooDBAppViewNavigatorPageResult, bm as MindooDBAppViewNavigatorRangeQuery, bn as MindooDBAppViewNavigatorSelectionState, bo as MindooDBAppViewUpdateStats, bp as MindooDBAppViewport, bq as MindooDBAppWritableAttachmentStream } from './types-B6vEy1VC.js';
+import { MindooDBAppBooleanExpression } from 'mindoodb-view-language';
 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';
+import { MindooDB, MindooQuerySortKey, MindooQueryOptions, MindooQueryResult } from 'mindoodb';
 
 /**
  * Resolves whether Haven can render a built-in preview for an attachment.
@@ -53,13 +55,15 @@ type MindooDBRichTextHandleChangeListener = (snapshot: MindooDBAppRichTextSnapsh
 /**
  * Local rich-text span buffer for SDK apps.
  *
- * The helper deliberately mirrors the causal shape of `MindooDBTextBuffer`:
- * local editor code replaces the current span snapshot, then `flush()` sends a
- * separate `richText` patch with the document heads the snapshot was based on.
+ * Mirrors `MindooDBTextBuffer`: track edits against a base snapshot, then flush
+ * with causal `baseHeads`. Text edits prefer positional `richTextSteps` so
+ * concurrent saves merge like plain-text splices; formatting-only or structural
+ * changes fall back to full `richText` span snapshots.
  */
 declare class MindooDBRichTextHandle {
     private readonly options;
     private spansInternal;
+    private baseMaterializedText;
     private heads;
     private dirtyInternal;
     private listeners;
@@ -77,6 +81,7 @@ declare class MindooDBRichTextHandle {
     refresh(): Promise<MindooDBAppRichTextSnapshot>;
     pollOnce(): Promise<boolean>;
     flush(updateSpansConfig?: Record<string, unknown>): Promise<MindooDBRichTextHandleFlushResult>;
+    private flushTextSteps;
     private emitChange;
 }
 declare function createMindooDBRichTextHandle(options: CreateMindooDBRichTextHandleOptions): MindooDBRichTextHandle;
@@ -174,4 +179,11 @@ declare class MindooDBTextBuffer {
 /** Create a local text buffer for one string field in a document. */
 declare function createMindooDBTextBuffer(options: CreateMindooDBTextBufferOptions): MindooDBTextBuffer;
 
-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 };
+/**
+ * Thin convenience wrapper around `db.query()`: accepts the filter either
+ * as a prebuilt expression (from `createViewLanguage()`) or as formula
+ * source text, which is parsed with the shared formula parser.
+ */
+declare function queryDocuments(db: Pick<MindooDB, "query">, filter: MindooDBAppBooleanExpression | string, sortBy?: MindooQuerySortKey[], options?: MindooQueryOptions): Promise<MindooQueryResult>;
+
+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, queryDocuments };