mindoodb-app-sdk 0.0.20 → 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.
 
@@ -893,9 +893,106 @@ Requires the `update` capability (same as other write operations). For historica
 
 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:**
 
@@ -1225,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:
@@ -1243,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.
 
@@ -1314,16 +1426,20 @@ 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>`       |
@@ -1378,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-CQt2ObMu.js';
-export { f as MindooDBAppAttachmentApi, g as MindooDBAppAttachmentChunk, h as MindooDBAppAttachmentInfo, i as MindooDBAppAttachmentPreviewOptions, j as MindooDBAppAttachmentPreviewSession, k as MindooDBAppAutomergeChangesPatch, l as MindooDBAppAutomergeChangesSince, m as MindooDBAppAutomergeGetOptions, n as MindooDBAppAutomergePatchResult, o as MindooDBAppAutomergeSnapshot, p as MindooDBAppBridgeConnectMessage, q as MindooDBAppBridgeConnectOptions, r as MindooDBAppBridgeConnectedMessage, s as MindooDBAppBridgeErrorPayload, t as MindooDBAppBridgeHandshakeErrorMessage, u as MindooDBAppBridgePortMessage, v as MindooDBAppBridgeRpcError, w as MindooDBAppBridgeRpcMessage, x as MindooDBAppBridgeRpcRequest, y as MindooDBAppBridgeRpcSuccess, z as MindooDBAppBridgeStreamAbortRequest, A as MindooDBAppBridgeStreamAck, B as MindooDBAppBridgeStreamCloseRequest, C as MindooDBAppBridgeStreamError, D as MindooDBAppBridgeStreamMessage, E as MindooDBAppBridgeStreamOpenResult, F as MindooDBAppBridgeStreamReadRequest, G as MindooDBAppBridgeStreamWriteRequest, H as MindooDBAppBridgeThemeChangedMessage, I as MindooDBAppBridgeUiPreferencesChangedMessage, J as MindooDBAppBridgeViewportChangedMessage, K as MindooDBAppCapability, L as MindooDBAppConfiguredViewCategorizationStyle, N as MindooDBAppConfiguredViewColumn, O as MindooDBAppConfiguredViewColumnRole, P as MindooDBAppConfiguredViewExpressionMode, Q as MindooDBAppConfiguredViewFieldExpression, R as MindooDBAppConfiguredViewFilterDefinition, S as MindooDBAppConfiguredViewFilterMode, T as MindooDBAppConfiguredViewFilterRule, U as MindooDBAppConfiguredViewFormulaExpression, V as MindooDBAppConfiguredViewFormulaFilterDefinition, W as MindooDBAppConfiguredViewPreviewMode, X as MindooDBAppConfiguredViewRuleFilterDefinition, Y as MindooDBAppConfiguredViewRuleMatchMode, Z as MindooDBAppConfiguredViewRuleOperator, _ as MindooDBAppConfiguredViewValueExpression, $ as MindooDBAppCreateDocumentInput, a0 as MindooDBAppCreateViewInput, a1 as MindooDBAppCreateViewNavigatorInput, a2 as MindooDBAppDatabaseInfo, a3 as MindooDBAppDocumentApi, a4 as MindooDBAppDocumentHeadCursorResult, a5 as MindooDBAppDocumentHistoryEntry, a6 as MindooDBAppDocumentListQuery, a7 as MindooDBAppDocumentListResult, a8 as MindooDBAppDocumentRevisionId, a9 as MindooDBAppDocumentScanPreset, aa as MindooDBAppDocumentSummary, ab as MindooDBAppHistoricalDocument, ac as MindooDBAppHistoryQuery, ad as MindooDBAppHostTheme, ae as MindooDBAppJsonListDeletePatch, af as MindooDBAppJsonListInsertPatch, ag as MindooDBAppJsonPatch, ah as MindooDBAppJsonSetPatch, ai as MindooDBAppJsonTextMarkPatch, aj as MindooDBAppJsonTextSplicePatch, ak as MindooDBAppJsonTextUnmarkPatch, al as MindooDBAppJsonUnsetPatch, am as MindooDBAppLaunchContext, an as MindooDBAppMenuAnchor, ao as MindooDBAppMenuApi, ap as MindooDBAppMenuCommandItem, aq as MindooDBAppMenuDismissReason, ar as MindooDBAppMenuDismissedResult, as as MindooDBAppMenuItem, at as MindooDBAppMenuKind, au as MindooDBAppMenuPlacement, av as MindooDBAppMenuPointAnchor, aw as MindooDBAppMenuRect, ax as MindooDBAppMenuRectAnchor, ay as MindooDBAppMenuSelectionResult, az as MindooDBAppMenuSeparatorItem, aA as MindooDBAppReadableAttachmentStream, aB as MindooDBAppResolvedViewDefinition, aC as MindooDBAppResolvedViewSource, aD as MindooDBAppRichTextBlockSpan, aE as MindooDBAppRichTextGetOptions, aF as MindooDBAppRichTextImmutableString, aG as MindooDBAppRichTextMarkRange, aH as MindooDBAppRichTextMaterializeValue, aI as MindooDBAppRichTextPatch, aJ as MindooDBAppRichTextScalar, aK as MindooDBAppRichTextSpliceStep, aL as MindooDBAppRichTextStep, aM as MindooDBAppRichTextStepPatch, aN as MindooDBAppRichTextTextSpan, aO as MindooDBAppRuntime, aP as MindooDBAppScanAttachmentOptions, aQ as MindooDBAppScanAttachmentResult, aR as MindooDBAppScopedDocId, aS as MindooDBAppScopedDocumentSummary, aT as MindooDBAppSession, aU as MindooDBAppShowMenuInput, aV as MindooDBAppShowMenuResult, aW as MindooDBAppTextEdit, aX as MindooDBAppTextPatch, aY as MindooDBAppThemeMode, aZ as MindooDBAppUiPreferences, a_ as MindooDBAppUpdateDocumentInput, a$ as MindooDBAppViewCursorDocumentListResult, b0 as MindooDBAppViewCursorResult, b1 as MindooDBAppViewEntry, b2 as MindooDBAppViewEntryKind, b3 as MindooDBAppViewNavigator, b4 as MindooDBAppViewNavigatorExpansionState, b5 as MindooDBAppViewNavigatorOpenOptions, b6 as MindooDBAppViewNavigatorPageOptions, b7 as MindooDBAppViewNavigatorPageResult, b8 as MindooDBAppViewNavigatorRangeQuery, b9 as MindooDBAppViewNavigatorSelectionState, ba as MindooDBAppViewport, bb as MindooDBAppWritableAttachmentStream } from './types-CQt2ObMu.js';
+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.
@@ -177,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 };

package/dist/index.js

@@ -1,5 +1,3 @@
-import "./chunk-QGM4M3NI.js";
-
 // src/attachmentPreview.ts
 function canPreviewAttachment(fileName, mimeType) {
   const normalizedMimeType = mimeType.toLowerCase();
@@ -82,6 +80,9 @@ function expandAbbreviatedName(value) {
   ].join("/");
 }
 
+// src/client/createMindooDBAppBridge.ts
+import { parseMindooDBFormulaBooleanExpression } from "mindoodb-view-language";
+
 // src/client/portRpcClient.ts
 var PROTOCOL = "mindoodb-app-bridge";
 function normalizeRpcValue(value, seen = /* @__PURE__ */ new WeakMap()) {
@@ -234,6 +235,9 @@ var PortRpcClient = class {
 // src/client/createMindooDBAppBridge.ts
 var PROTOCOL2 = "mindoodb-app-bridge";
 var DEFAULT_CONNECT_TIMEOUT_MS = 1e4;
+function isMethodNotFoundError(error) {
+  return error instanceof Error && error.name === "method-not-found";
+}
 function toTransferableArrayBuffer(chunk) {
   return chunk.buffer.slice(
     chunk.byteOffset,
@@ -249,6 +253,24 @@ function isStreamAckFor(streamId, message) {
 function isStreamErrorFor(streamId, message) {
   return message.kind === "stream-error" && message.streamId === streamId;
 }
+function isQueryResultFor(subscriptionId, message) {
+  return message.kind === "query-result" && message.subscriptionId === subscriptionId;
+}
+function isViewChangedFor(navigatorId, message) {
+  return message.kind === "view-changed" && message.navigatorId === navigatorId;
+}
+function normalizeDocumentQuery(query) {
+  if (!query) {
+    return {};
+  }
+  const { filter, ...rest } = query;
+  return {
+    ...rest,
+    ...filter !== void 0 ? {
+      filter: typeof filter === "string" ? parseMindooDBFormulaBooleanExpression(filter) : filter
+    } : {}
+  };
+}
 function isThemeChangedMessage(message) {
   return message.kind === "theme-changed";
 }
@@ -258,6 +280,9 @@ function isViewportChangedMessage(message) {
 function isUiPreferencesChangedMessage(message) {
   return message.kind === "ui-preferences-changed";
 }
+function isLocaleChangedMessage(message) {
+  return message.kind === "locale-changed";
+}
 function toStreamError(message) {
   const error = new Error(message.error.message);
   error.name = message.error.code || "MindooDBAppBridgeStreamError";
@@ -380,6 +405,13 @@ var MindooDBAppViewNavigatorImpl = class {
     this.viewCursor = result.viewCursor;
     return this.viewCursor;
   }
+  onDidUpdate(listener) {
+    return this.rpc.addMessageListener((message) => {
+      if (isViewChangedFor(this.navigatorId, message)) {
+        listener(message.stats);
+      }
+    });
+  }
   async getCurrentEntry() {
     return await this.call("viewNavigators.current.get");
   }
@@ -721,6 +753,44 @@ var MindooDBAppDatabaseImpl = class {
         databaseId: this.databaseId,
         query: query ?? {}
       }),
+      query: async (query) => await this.rpc.call("documents.query", {
+        databaseId: this.databaseId,
+        query: normalizeDocumentQuery(query)
+      }),
+      liveQuery: async (query, onResult) => {
+        const { subscriptionId, result } = await this.rpc.call("documents.liveQuery.subscribe", {
+          databaseId: this.databaseId,
+          query: normalizeDocumentQuery(query)
+        });
+        let disposed = false;
+        const unsubscribe = this.rpc.addMessageListener((message) => {
+          if (!disposed && isQueryResultFor(subscriptionId, message)) {
+            onResult(message.result);
+          }
+        });
+        onResult(result);
+        const subscription = {
+          refresh: async () => {
+            if (disposed) {
+              return;
+            }
+            await this.rpc.call("documents.liveQuery.refresh", {
+              subscriptionId
+            });
+          },
+          dispose: async () => {
+            if (disposed) {
+              return;
+            }
+            disposed = true;
+            unsubscribe();
+            await this.rpc.call("documents.liveQuery.unsubscribe", {
+              subscriptionId
+            });
+          }
+        };
+        return subscription;
+      },
       getHeadCursor: async () => await this.rpc.call("documents.getHeadCursor", {
         databaseId: this.databaseId
       }),
@@ -748,6 +818,30 @@ var MindooDBAppDatabaseImpl = class {
         databaseId: this.databaseId,
         input
       }),
+      createMany: async (inputs) => {
+        if (inputs.length === 0) {
+          return { ids: [] };
+        }
+        try {
+          return await this.rpc.call("documents.createMany", {
+            databaseId: this.databaseId,
+            inputs
+          });
+        } catch (error) {
+          if (!isMethodNotFoundError(error)) {
+            throw error;
+          }
+          const ids = [];
+          for (const input of inputs) {
+            const document = await this.rpc.call("documents.create", {
+              databaseId: this.databaseId,
+              input
+            });
+            ids.push(document.id);
+          }
+          return { ids };
+        }
+      },
       update: async (docId, patch) => await this.rpc.call("documents.update", {
         databaseId: this.databaseId,
         docId,
@@ -757,10 +851,51 @@ var MindooDBAppDatabaseImpl = class {
         databaseId: this.databaseId,
         docId
       }),
+      deleteMany: async (docIds) => {
+        if (docIds.length === 0) {
+          return { ok: true };
+        }
+        try {
+          return await this.rpc.call("documents.deleteMany", {
+            databaseId: this.databaseId,
+            docIds
+          });
+        } catch (error) {
+          if (!isMethodNotFoundError(error)) {
+            throw error;
+          }
+          for (const docId of docIds) {
+            await this.rpc.call("documents.delete", {
+              databaseId: this.databaseId,
+              docId
+            });
+          }
+          return { ok: true };
+        }
+      },
       undelete: async (docId) => await this.rpc.call("documents.undelete", {
         databaseId: this.databaseId,
         docId
       }),
+      canCreate: async (input) => await this.rpc.call("documents.canCreate", {
+        databaseId: this.databaseId,
+        input: input ?? {}
+      }),
+      canChange: async (docId) => await this.rpc.call("documents.canChange", {
+        databaseId: this.databaseId,
+        docId
+      }),
+      canDelete: async (docId) => await this.rpc.call("documents.canDelete", {
+        databaseId: this.databaseId,
+        docId
+      }),
+      canUndelete: async (docId) => await this.rpc.call("documents.canUndelete", {
+        databaseId: this.databaseId,
+        docId
+      }),
+      getDefaultCreateKeyId: async () => await this.rpc.call("documents.getDefaultCreateKeyId", {
+        databaseId: this.databaseId
+      }),
       listHistory: async (docId) => await this.rpc.call("documents.history.list", {
         databaseId: this.databaseId,
         docId
@@ -901,6 +1036,36 @@ var MindooDBAppDatabaseImpl = class {
       databaseId: this.databaseId
     });
   }
+  /** Reads the full-text configuration from the synced `dbsetup` document. */
+  async getFulltextSetup() {
+    const result = await this.rpc.call(
+      "database.getFulltextSetup",
+      { databaseId: this.databaseId }
+    );
+    return result.config;
+  }
+  /** Writes (or removes, with `null`) the full-text configuration. */
+  async setFulltextSetup(config) {
+    await this.rpc.call("database.setFulltextSetup", {
+      databaseId: this.databaseId,
+      config
+    });
+  }
+  /** Reads the attachment extraction configuration from the synced `dbsetup` document. */
+  async getExtractionSetup() {
+    const result = await this.rpc.call(
+      "database.getExtractionSetup",
+      { databaseId: this.databaseId }
+    );
+    return result.config;
+  }
+  /** Writes (or removes, with `null`) the attachment extraction configuration. */
+  async setExtractionSetup(config) {
+    await this.rpc.call("database.setExtractionSetup", {
+      databaseId: this.databaseId,
+      config
+    });
+  }
 };
 var MindooDBAppSessionImpl = class {
   constructor(rpc) {
@@ -918,6 +1083,10 @@ var MindooDBAppSessionImpl = class {
   async getLaunchContext() {
     return await this.rpc.call("session.getLaunchContext", {});
   }
+  /** Returns the product names currently licensed in the Haven host. */
+  async getLicensedProducts() {
+    return await this.rpc.call("session.getLicensedProducts", {});
+  }
   /** Lists the databases that the host has made available for this app session. */
   async listDatabases() {
     return await this.rpc.call("session.listDatabases", {});
@@ -985,6 +1154,14 @@ var MindooDBAppSessionImpl = class {
       }
     });
   }
+  /** Subscribe to host-pushed UI language changes. */
+  onLocaleChange(listener) {
+    return this.rpc.addMessageListener((message) => {
+      if (isLocaleChangedMessage(message)) {
+        listener(message.locale);
+      }
+    });
+  }
   /** Disconnects from the host and always disposes the underlying port client. */
   async disconnect() {
     try {
@@ -1345,12 +1522,20 @@ function computeSingleSplice2(previous, next) {
 }
 
 // src/viewLanguage.ts
+import { parseMindooDBFormulaBooleanExpression as parseMindooDBFormulaBooleanExpression2 } from "mindoodb-view-language";
 import {
   createViewLanguage,
   getMindooDBViewLanguageHelper,
   mindooDBViewLanguageHelpers,
   mindooDBViewLanguageHelpersByName
 } from "mindoodb-view-language";
+async function queryDocuments(db, filter, sortBy, options) {
+  if (!db.query) {
+    throw new Error("This MindooDB instance does not support ad-hoc queries.");
+  }
+  const expression = typeof filter === "string" ? parseMindooDBFormulaBooleanExpression2(filter) : filter;
+  return db.query({ filter: expression, sortBy }, options);
+}
 export {
   MindooDBRichTextHandle,
   MindooDBTextBuffer,
@@ -1360,5 +1545,6 @@ export {
   createMindooDBRichTextHandle,
   createMindooDBTextBuffer,
   createViewLanguage,
-  expandAbbreviatedName
+  expandAbbreviatedName,
+  queryDocuments
 };

package/dist/testing/index.d.ts

@@ -1,4 +1,4 @@
-import { am as MindooDBAppLaunchContext, a2 as MindooDBAppDatabaseInfo, a3 as MindooDBAppDocumentApi, a1 as MindooDBAppCreateViewNavigatorInput, b3 as MindooDBAppViewNavigator, b5 as MindooDBAppViewNavigatorOpenOptions, f as MindooDBAppAttachmentApi, a as MindooDBAppBridge, aT as MindooDBAppSession, x as MindooDBAppBridgeRpcRequest, ad as MindooDBAppHostTheme, ba as MindooDBAppViewport, aZ as MindooDBAppUiPreferences, u as MindooDBAppBridgePortMessage } from '../types-CQt2ObMu.js';
+import { au as MindooDBAppLaunchContext, a7 as MindooDBAppDatabaseInfo, a8 as MindooDBAppDocumentApi, a6 as MindooDBAppCreateViewNavigatorInput, bh as MindooDBAppViewNavigator, bj as MindooDBAppViewNavigatorOpenOptions, h as MindooDBAppAttachmentApi, ai as MindooDBAppFulltextSetup, ah as MindooDBAppExtractionSetup, a as MindooDBAppBridge, b5 as MindooDBAppSession, B as MindooDBAppBridgeRpcRequest, al as MindooDBAppHostTheme, bp as MindooDBAppViewport, bb as MindooDBAppUiPreferences, aK as MindooDBAppQueryResult, bo as MindooDBAppViewUpdateStats, x as MindooDBAppBridgePortMessage } from '../types-B6vEy1VC.js';
 import 'mindoodb-view-language';
 
 type MaybePromise<T> = T | Promise<T>;
@@ -14,6 +14,21 @@ type MockDatabaseMethods = {
 interface MockMindooDBAppDatabaseDefinition {
     info: MindooDBAppDatabaseInfo;
     methods?: MockDatabaseMethods;
+    /**
+     * Initial full-text configuration returned by `getFulltextSetup()`.
+     * `setFulltextSetup()` overwrites it for the lifetime of the handle.
+     * Note the mock evaluates `text` query clauses regardless of this
+     * config (see TESTING.md) — it exists so apps can test their setup/
+     * bootstrap logic.
+     */
+    fulltextSetup?: MindooDBAppFulltextSetup | null;
+    /**
+     * Initial extraction configuration returned by `getExtractionSetup()`.
+     * `setExtractionSetup()` overwrites it for the lifetime of the handle.
+     * The mock runs no extraction service — this exists so apps can test
+     * their setup/bootstrap logic.
+     */
+    extractionSetup?: MindooDBAppExtractionSetup | null;
 }
 interface CreateMockMindooDBAppSessionOptions {
     launchContext?: Partial<MindooDBAppLaunchContext>;
@@ -25,11 +40,13 @@ interface MockMindooDBAppSessionController {
     session: MindooDBAppSession;
     getLaunchContext(): MindooDBAppLaunchContext;
     setLaunchContext(patch?: Partial<MindooDBAppLaunchContext>): MindooDBAppLaunchContext;
+    getLicensedProducts(): string[];
     listDatabases(): MindooDBAppDatabaseInfo[];
     setDatabases(definitions: MockMindooDBAppDatabaseDefinition[]): void;
     emitThemeChange(theme: MindooDBAppHostTheme): void;
     emitViewportChange(viewport: MindooDBAppViewport): void;
     emitUiPreferencesChange(uiPreferences: MindooDBAppUiPreferences): void;
+    emitLocaleChange(locale: string): void;
 }
 declare function createMockMindooDBAppSession(options?: CreateMockMindooDBAppSessionOptions): MockMindooDBAppSessionController;
 declare function createMockMindooDBAppBridge(options?: CreateMockMindooDBAppSessionOptions): MockMindooDBAppSessionController;
@@ -57,6 +74,11 @@ interface FakeBridgeHostController {
     emitThemeChange(theme: MindooDBAppHostTheme): void;
     emitViewportChange(viewport: MindooDBAppViewport): void;
     emitUiPreferencesChange(uiPreferences: MindooDBAppUiPreferences): void;
+    emitLocaleChange(locale: string): void;
+    /** Push a live-query result to connected apps, as the Haven host would. */
+    emitQueryResult(subscriptionId: string, result: MindooDBAppQueryResult): void;
+    /** Push a navigator view-changed event to connected apps. */
+    emitViewChanged(navigatorId: string, stats: MindooDBAppViewUpdateStats): void;
     postPortMessage(message: MindooDBAppBridgePortMessage, transfer?: Transferable[]): void;
     setRequestHandler(method: string, handler: FakeBridgeRequestHandler): void;
     clearRequestHandler(method: string): void;