mindoodb-app-sdk 0.0.6 → 0.0.8

package/README.md

@@ -57,7 +57,7 @@ npm install mindoodb-app-sdk
 The fastest way to start building is to clone the **example app**, run it locally, and connect it to Haven:
 
 ```bash
-git clone https://github.com/niclas-niclas/mindoodb-app-example.git
+git clone https://github.com/klehmann/mindoodb-app-example.git
 cd mindoodb-app-example
 npm install
 npm run dev:local
@@ -73,9 +73,9 @@ Then, in Haven:
 
 From here, **fork or duplicate** the example project to start building your own app while exploring the platform in a running Haven client.
 
-The example app is also deployed at **https://mindoodb-app-example.mindoo.de** so you can register it in Haven without running anything locally.
+The example app is also deployed at **https://app-example.mindoodb.com** so you can register it in Haven without running anything locally.
 
-> See the [mindoodb-app-example README](https://github.com/niclas-niclas/mindoodb-app-example) for the full project walkthrough.
+> See the [mindoodb-app-example README](https://github.com/klehmann/mindoodb-app-example) for the full project walkthrough.
 
 ## Quick start (from scratch)
 
@@ -410,20 +410,26 @@ const unsupported = canPreviewAttachment("data.bin", "application/octet-stream")
 
 ### Virtual Views
 
-Views let you query documents with categorization, sorting, filtering, and aggregation -- similar to a spreadsheet pivot table. There are two ways to work with views:
+Views let you query documents with categorization, sorting, filtering, and aggregation -- similar to a spreadsheet pivot table. The SDK now exposes a **stateful navigator API** that mirrors the core `VirtualViewNavigator` closely.
 
-**App-defined views** -- create a view definition programmatically:
+There are two ways to open one:
+
+**App-defined multi-database views** -- create a view definition programmatically and immediately open a navigator:
 
 ```ts
 import { createViewLanguage } from "mindoodb-app-sdk";
 
 const v = createViewLanguage<{ employee: string; hours: number }>();
 
-const view = await session.createView({
-  databaseId: "main",
+const navigator = await session.createViewNavigator({
+  databaseIds: ["main", "archive"],
   definition: {
     title: "Hours by employee",
     defaultExpand: "collapsed",
+    filter: {
+      mode: "expression",
+      expression: v.gt(v.toNumber(v.field("hours")), v.number(0)),
+    },
     columns: [
       {
         name: "employee",
@@ -442,27 +448,98 @@ const view = await session.createView({
   },
 });
 
-const page = await view.page({ pageSize: 100 });
-console.log(page.rows);
-await view.dispose();
+const batch = await navigator.entriesForward({ limit: 100 });
+console.log(batch.entries);
+
+await navigator.dispose();
 ```
 
-**Haven-configured views** -- open views that the Haven administrator attached to the app registration:
+**Haven-configured views** -- open a view that Haven attached to the app registration:
 
 ```ts
 const viewDefs = ctx.views; // from launch context
 
-const view = await session.openView(viewDefs[0]!.id);
-const page = await view.page({ pageSize: 50 });
+const navigator = await session.openViewNavigator(viewDefs[0]!.id, {
+  includeCategories: true,
+  includeDocuments: true,
+  hideEmptyCategories: true,
+});
+
+await navigator.gotoFirst();
+const current = await navigator.getCurrentEntry();
+console.log(current);
+
+await navigator.dispose();
+```
+
+#### Common navigator patterns
+
+**Single-step traversal**:
+
+```ts
+await navigator.gotoFirst();
+
+do {
+  const entry = await navigator.getCurrentEntry();
+  if (entry) {
+    console.log(entry.kind, entry.categoryPath, entry.columnValues);
+  }
+} while (await navigator.gotoNext());
+```
+
+**Batch reads for UI rendering**:
+
+```ts
+const page1 = await navigator.entriesForward({ limit: 50 });
+const page2 = page1.nextPosition
+  ? await navigator.entriesForward({ limit: 50, startPosition: page1.nextPosition })
+  : null;
+```
+
+**Category lookup plus child traversal**:
 
-// Expand/collapse categories
-await view.expandAll();
-await view.collapse(someCategoryKey);
+```ts
+const category = await navigator.findCategoryEntryByParts(["Ada"]);
+if (category) {
+  const docs = await navigator.childDocuments(category.key);
+  console.log(docs.map((entry) => entry.docId));
+}
+```
 
-await view.dispose();
+**Key lookup and key-range lookup**:
+
+```ts
+const category = await navigator.findCategoryEntryByParts(["Ada"]);
+if (category) {
+  const exact = await navigator.childDocumentsByKey(category.key, "2026-04-14", true);
+  const range = await navigator.childDocumentsBetween(category.key, {
+    startKey: "2026-04-01",
+    endKey: "2026-04-30",
+  });
+}
 ```
 
-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.
+**Expansion and selection state**:
+
+```ts
+await navigator.expandAll();
+await navigator.select("main", "doc-123");
+
+const expansion = await navigator.getExpansionState();
+const selection = await navigator.getSelectionState();
+
+await navigator.setExpansionState(expansion);
+await navigator.setSelectionState(selection);
+```
+
+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
+
+- `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.
+- Child/key/range helpers operate on the same host-side navigator session. They do not create a separate query engine.
 
 Available expression helpers:
 
@@ -494,7 +571,7 @@ See [`TESTING.md`](./TESTING.md) for setup instructions and Vitest examples.
 
 MindooDB Apps are standard web applications -- deploy them anywhere you can serve static files.
 
-**Cloudflare Pages / Workers** is one of the easiest options. The [example app](https://github.com/niclas-niclas/mindoodb-app-example) is deployed this way at https://mindoodb-app-example.mindoo.de using a simple `wrangler.jsonc` configuration:
+**Cloudflare Pages / Workers** is one of the easiest options. The [example app](https://github.com/klehmann/mindoodb-app-example) is deployed this way at https://app-example.mindoodb.com using a simple `wrangler.jsonc` configuration:
 
 ```bash
 npm run build
@@ -534,8 +611,8 @@ Connect options: `launchId?`, `targetOrigin?`, `connectTimeoutMs?`.
 | `getLaunchContext()` | `Promise<MindooDBAppLaunchContext>` |
 | `listDatabases()` | `Promise<MindooDBAppDatabaseInfo[]>` |
 | `openDatabase(databaseId)` | `Promise<MindooDBAppDatabase>` |
-| `createView(input)` | `Promise<MindooDBAppViewHandle>` |
-| `openView(viewId)` | `Promise<MindooDBAppViewHandle>` |
+| `createViewNavigator(input)` | `Promise<MindooDBAppViewNavigator>` |
+| `openViewNavigator(viewId, options?)` | `Promise<MindooDBAppViewNavigator>` |
 | `onThemeChange(listener)` | `() => void` (unsubscribe) |
 | `onViewportChange(listener)` | `() => void` (unsubscribe) |
 | `disconnect()` | `Promise<void>` |
@@ -572,23 +649,45 @@ Connect options: `launchId?`, `targetOrigin?`, `connectTimeoutMs?`.
 | `openWriteStream(docId, attachmentName, contentType?)` | `Promise<MindooDBAppWritableAttachmentStream>` |
 | `openPreview(docId, attachmentName, options?)` | `Promise<{ ok: true }>` |
 
-### MindooDBAppViewHandle
+### MindooDBAppViewNavigator
 
 | Method | Returns |
 |---|---|
 | `getDefinition()` | `Promise<MindooDBAppViewDefinition>` |
 | `refresh()` | `Promise<void>` |
-| `page(input?)` | `Promise<MindooDBAppViewPageResult>` |
-| `getExpansionState()` | `Promise<MindooDBAppViewExpansionState>` |
-| `setExpansionState(state)` | `Promise<MindooDBAppViewExpansionState>` |
-| `expand(rowKey)` | `Promise<MindooDBAppViewExpansionState>` |
-| `collapse(rowKey)` | `Promise<MindooDBAppViewExpansionState>` |
-| `expandAll()` | `Promise<MindooDBAppViewExpansionState>` |
-| `collapseAll()` | `Promise<MindooDBAppViewExpansionState>` |
-| `getRow(rowKey)` | `Promise<MindooDBAppViewRow \| null>` |
-| `getCategory(input)` | `Promise<MindooDBAppViewRow \| null>` |
-| `pageCategory(categoryKey, input?)` | `Promise<MindooDBAppViewPageResult>` |
-| `listCategoryDocumentIds(categoryKey)` | `Promise<string[]>` |
+| `getCurrentEntry()` | `Promise<MindooDBAppViewEntry \| null>` |
+| `gotoFirst()` / `gotoLast()` | `Promise<boolean>` |
+| `gotoNext()` / `gotoPrev()` | `Promise<boolean>` |
+| `gotoNextSibling()` / `gotoPrevSibling()` | `Promise<boolean>` |
+| `gotoParent()` | `Promise<boolean>` |
+| `gotoFirstChild()` / `gotoLastChild()` | `Promise<boolean>` |
+| `gotoPos(position)` | `Promise<boolean>` |
+| `getPos(position)` | `Promise<MindooDBAppViewEntry \| null>` |
+| `findCategoryEntryByParts(parts)` | `Promise<MindooDBAppViewEntry \| null>` |
+| `entriesForward(options?)` | `Promise<MindooDBAppViewNavigatorPageResult>` |
+| `entriesBackward(options?)` | `Promise<MindooDBAppViewNavigatorPageResult>` |
+| `gotoNextSelected()` / `gotoPrevSelected()` | `Promise<boolean>` |
+| `select(origin, docId, selectParentCategories?)` | `Promise<void>` |
+| `deselect(origin, docId)` | `Promise<void>` |
+| `selectAllEntries()` / `deselectAllEntries()` | `Promise<void>` |
+| `isSelected(origin, docId)` | `Promise<boolean>` |
+| `getSelectionState()` | `Promise<MindooDBAppViewNavigatorSelectionState>` |
+| `setSelectionState(state)` | `Promise<void>` |
+| `expand(origin, docId)` / `collapse(origin, docId)` | `Promise<void>` |
+| `expandAll()` / `collapseAll()` | `Promise<void>` |
+| `expandToLevel(level)` | `Promise<void>` |
+| `isExpanded(entryKey)` | `Promise<boolean>` |
+| `getExpansionState()` | `Promise<MindooDBAppViewNavigatorExpansionState>` |
+| `setExpansionState(state)` | `Promise<void>` |
+| `childEntries(entryKey, descending?)` | `Promise<MindooDBAppViewEntry[]>` |
+| `childCategories(entryKey, descending?)` | `Promise<MindooDBAppViewEntry[]>` |
+| `childDocuments(entryKey, descending?)` | `Promise<MindooDBAppViewEntry[]>` |
+| `childCategoriesByKey(entryKey, key, exact?, descending?)` | `Promise<MindooDBAppViewEntry[]>` |
+| `childDocumentsByKey(entryKey, key, exact?, descending?)` | `Promise<MindooDBAppViewEntry[]>` |
+| `childCategoriesBetween(entryKey, range)` | `Promise<MindooDBAppViewEntry[]>` |
+| `childDocumentsBetween(entryKey, range)` | `Promise<MindooDBAppViewEntry[]>` |
+| `getSortedDocIds(descending?)` | `Promise<MindooDBAppScopedDocId[]>` |
+| `getSortedDocIdsScoped(entryKey, descending?)` | `Promise<MindooDBAppScopedDocId[]>` |
 | `dispose()` | `Promise<void>` |
 
 ### Exported functions

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { M as MindooDBAppAttachmentPreviewMode, a as MindooDBAppBridge } from './types-BDY_80wd.js';
-export { b as MindooDBAppAttachmentApi, c as MindooDBAppAttachmentChunk, d as MindooDBAppAttachmentInfo, e as MindooDBAppAttachmentPreviewOptions, f as MindooDBAppBridgeConnectMessage, g as MindooDBAppBridgeConnectOptions, h as MindooDBAppBridgeConnectedMessage, i as MindooDBAppBridgeErrorPayload, j as MindooDBAppBridgePortMessage, k as MindooDBAppBridgeRpcError, l as MindooDBAppBridgeRpcMessage, m as MindooDBAppBridgeRpcRequest, n as MindooDBAppBridgeRpcSuccess, o as MindooDBAppBridgeStreamAbortRequest, p as MindooDBAppBridgeStreamAck, q as MindooDBAppBridgeStreamCloseRequest, r as MindooDBAppBridgeStreamError, s as MindooDBAppBridgeStreamMessage, t as MindooDBAppBridgeStreamOpenResult, u as MindooDBAppBridgeStreamReadRequest, v as MindooDBAppBridgeStreamWriteRequest, w as MindooDBAppBridgeThemeChangedMessage, x as MindooDBAppBridgeViewportChangedMessage, y as MindooDBAppCapability, z as MindooDBAppConfiguredViewCategorizationStyle, A as MindooDBAppConfiguredViewColumn, B as MindooDBAppConfiguredViewColumnRole, C as MindooDBAppConfiguredViewExpressionMode, D as MindooDBAppConfiguredViewFieldExpression, E as MindooDBAppConfiguredViewFilterDefinition, F as MindooDBAppConfiguredViewFilterMode, G as MindooDBAppConfiguredViewFilterRule, H as MindooDBAppConfiguredViewFormulaExpression, I as MindooDBAppConfiguredViewFormulaFilterDefinition, J as MindooDBAppConfiguredViewPreviewMode, K as MindooDBAppConfiguredViewRuleFilterDefinition, L as MindooDBAppConfiguredViewRuleMatchMode, N as MindooDBAppConfiguredViewRuleOperator, O as MindooDBAppConfiguredViewValueExpression, P as MindooDBAppCreateDocumentInput, Q as MindooDBAppCreateViewInput, R as MindooDBAppDatabase, S as MindooDBAppDatabaseInfo, T as MindooDBAppDocument, U as MindooDBAppDocumentApi, V as MindooDBAppDocumentHistoryEntry, W as MindooDBAppDocumentListQuery, X as MindooDBAppDocumentListResult, Y as MindooDBAppDocumentSummary, Z as MindooDBAppHistoricalDocument, _ as MindooDBAppHistoryQuery, $ as MindooDBAppHostTheme, a0 as MindooDBAppLaunchContext, a1 as MindooDBAppReadableAttachmentStream, a2 as MindooDBAppResolvedViewDefinition, a3 as MindooDBAppResolvedViewSource, a4 as MindooDBAppRuntime, a5 as MindooDBAppSession, a6 as MindooDBAppThemeMode, a7 as MindooDBAppUpdateDocumentInput, a8 as MindooDBAppViewHandle, a9 as MindooDBAppViewport, aa as MindooDBAppWritableAttachmentStream } from './types-BDY_80wd.js';
+import { M as MindooDBAppAttachmentPreviewMode, a as MindooDBAppBridge } from './types-C_kZcG24.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 MindooDBAppBridgeViewportChangedMessage, z as MindooDBAppCapability, A as MindooDBAppConfiguredViewCategorizationStyle, B as MindooDBAppConfiguredViewColumn, C as MindooDBAppConfiguredViewColumnRole, D as MindooDBAppConfiguredViewExpressionMode, E as MindooDBAppConfiguredViewFieldExpression, F as MindooDBAppConfiguredViewFilterDefinition, G as MindooDBAppConfiguredViewFilterMode, H as MindooDBAppConfiguredViewFilterRule, I as MindooDBAppConfiguredViewFormulaExpression, J as MindooDBAppConfiguredViewFormulaFilterDefinition, K as MindooDBAppConfiguredViewPreviewMode, L as MindooDBAppConfiguredViewRuleFilterDefinition, N as MindooDBAppConfiguredViewRuleMatchMode, O as MindooDBAppConfiguredViewRuleOperator, P as MindooDBAppConfiguredViewValueExpression, Q as MindooDBAppCreateDocumentInput, R as MindooDBAppCreateViewInput, S as MindooDBAppCreateViewNavigatorInput, T as MindooDBAppDatabase, U as MindooDBAppDatabaseInfo, V as MindooDBAppDocument, W as MindooDBAppDocumentApi, X as MindooDBAppDocumentHistoryEntry, Y as MindooDBAppDocumentListQuery, Z as MindooDBAppDocumentListResult, _ as MindooDBAppDocumentSummary, $ as MindooDBAppHistoricalDocument, a0 as MindooDBAppHistoryQuery, a1 as MindooDBAppHostTheme, a2 as MindooDBAppLaunchContext, a3 as MindooDBAppReadableAttachmentStream, a4 as MindooDBAppResolvedViewDefinition, a5 as MindooDBAppResolvedViewSource, a6 as MindooDBAppRuntime, a7 as MindooDBAppScopedDocId, a8 as MindooDBAppSession, a9 as MindooDBAppThemeMode, aa as MindooDBAppUpdateDocumentInput, ab as MindooDBAppViewEntry, ac as MindooDBAppViewEntryKind, ad as MindooDBAppViewNavigator, ae as MindooDBAppViewNavigatorExpansionState, af as MindooDBAppViewNavigatorOpenOptions, ag as MindooDBAppViewNavigatorPageOptions, ah as MindooDBAppViewNavigatorPageResult, ai as MindooDBAppViewNavigatorRangeQuery, aj as MindooDBAppViewNavigatorSelectionState, ak as MindooDBAppViewport, al as MindooDBAppWritableAttachmentStream } from './types-C_kZcG24.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';
 
 /**

package/dist/index.js

@@ -307,89 +307,163 @@ function waitForConnectedPort(options, launchId) {
     targetWindow.postMessage(message, targetOrigin, [channel.port2]);
   });
 }
-var MindooDBAppViewHandleImpl = class {
-  constructor(rpc, viewId) {
+var MindooDBAppViewNavigatorImpl = class {
+  constructor(rpc, navigatorId) {
     this.rpc = rpc;
-    this.viewId = viewId;
+    this.navigatorId = navigatorId;
   }
-  async getDefinition() {
-    return await this.rpc.call("views.getDefinition", {
-      viewId: this.viewId
+  /** Shorthand: call an RPC method with the navigator ID automatically injected. */
+  async call(method, params = {}) {
+    return await this.rpc.call(method, {
+      navigatorId: this.navigatorId,
+      ...params
     });
   }
+  async getDefinition() {
+    return await this.call("viewNavigators.getDefinition");
+  }
   async refresh() {
-    await this.rpc.call("views.refresh", {
-      viewId: this.viewId
-    });
+    await this.call("viewNavigators.refresh");
   }
-  async page(input) {
-    return await this.rpc.call("views.page", {
-      viewId: this.viewId,
-      request: input ?? {}
-    });
+  async getCurrentEntry() {
+    return await this.call("viewNavigators.current.get");
   }
-  async getExpansionState() {
-    return await this.rpc.call("views.expansion.get", {
-      viewId: this.viewId
-    });
+  async gotoFirst() {
+    return await this.call("viewNavigators.goto.first");
   }
-  async setExpansionState(state) {
-    return await this.rpc.call("views.expansion.set", {
-      viewId: this.viewId,
-      expansion: state
-    });
+  async gotoLast() {
+    return await this.call("viewNavigators.goto.last");
   }
-  async expand(rowKey) {
-    return await this.rpc.call("views.expansion.expand", {
-      viewId: this.viewId,
-      rowKey
-    });
+  async gotoNext() {
+    return await this.call("viewNavigators.goto.next");
+  }
+  async gotoPrev() {
+    return await this.call("viewNavigators.goto.prev");
+  }
+  async gotoNextSibling() {
+    return await this.call("viewNavigators.goto.nextSibling");
+  }
+  async gotoPrevSibling() {
+    return await this.call("viewNavigators.goto.prevSibling");
+  }
+  async gotoParent() {
+    return await this.call("viewNavigators.goto.parent");
   }
-  async collapse(rowKey) {
-    return await this.rpc.call("views.expansion.collapse", {
-      viewId: this.viewId,
-      rowKey
+  async gotoFirstChild() {
+    return await this.call("viewNavigators.goto.firstChild");
+  }
+  async gotoLastChild() {
+    return await this.call("viewNavigators.goto.lastChild");
+  }
+  async gotoPos(position) {
+    return await this.call("viewNavigators.goto.pos", { position });
+  }
+  async getPos(position) {
+    return await this.call("viewNavigators.pos.get", { position });
+  }
+  async findCategoryEntryByParts(parts) {
+    return await this.call("viewNavigators.category.findByParts", { parts });
+  }
+  async entriesForward(options) {
+    return await this.call("viewNavigators.entries.forward", { options: options ?? {} });
+  }
+  async entriesBackward(options) {
+    return await this.call("viewNavigators.entries.backward", { options: options ?? {} });
+  }
+  async gotoNextSelected() {
+    return await this.call("viewNavigators.goto.nextSelected");
+  }
+  async gotoPrevSelected() {
+    return await this.call("viewNavigators.goto.prevSelected");
+  }
+  async select(origin, docId, selectParentCategories) {
+    await this.call("viewNavigators.selection.select", {
+      origin,
+      docId,
+      selectParentCategories
     });
   }
+  async deselect(origin, docId) {
+    await this.call("viewNavigators.selection.deselect", { origin, docId });
+  }
+  async selectAllEntries() {
+    await this.call("viewNavigators.selection.selectAll");
+  }
+  async deselectAllEntries() {
+    await this.call("viewNavigators.selection.deselectAll");
+  }
+  async isSelected(origin, docId) {
+    return await this.call("viewNavigators.selection.isSelected", { origin, docId });
+  }
+  async getSelectionState() {
+    return await this.call("viewNavigators.selection.get");
+  }
+  async setSelectionState(state) {
+    await this.call("viewNavigators.selection.set", { state });
+  }
+  async expand(origin, docId) {
+    await this.call("viewNavigators.expansion.expand", { origin, docId });
+  }
+  async collapse(origin, docId) {
+    await this.call("viewNavigators.expansion.collapse", { origin, docId });
+  }
   async expandAll() {
-    return await this.rpc.call("views.expansion.expandAll", {
-      viewId: this.viewId
-    });
+    await this.call("viewNavigators.expansion.expandAll");
   }
   async collapseAll() {
-    return await this.rpc.call("views.expansion.collapseAll", {
-      viewId: this.viewId
-    });
+    await this.call("viewNavigators.expansion.collapseAll");
   }
-  async getRow(rowKey) {
-    return await this.rpc.call("views.row.get", {
-      viewId: this.viewId,
-      rowKey
-    });
+  async expandToLevel(level) {
+    await this.call("viewNavigators.expansion.expandToLevel", { level });
   }
-  async getCategory(input) {
-    return await this.rpc.call("views.category.get", {
-      viewId: this.viewId,
-      lookup: input
-    });
+  async isExpanded(entryKey) {
+    return await this.call("viewNavigators.expansion.isExpanded", { entryKey });
+  }
+  async getExpansionState() {
+    return await this.call("viewNavigators.expansion.get");
+  }
+  async setExpansionState(state) {
+    await this.call("viewNavigators.expansion.set", { state });
+  }
+  async childEntries(entryKey, descending) {
+    return await this.call("viewNavigators.children.entries", { entryKey, descending });
+  }
+  async childCategories(entryKey, descending) {
+    return await this.call("viewNavigators.children.categories", { entryKey, descending });
   }
-  async pageCategory(categoryKey, input) {
-    return await this.rpc.call("views.category.page", {
-      viewId: this.viewId,
-      categoryKey,
-      request: input ?? {}
+  async childDocuments(entryKey, descending) {
+    return await this.call("viewNavigators.children.documents", { entryKey, descending });
+  }
+  async childCategoriesByKey(entryKey, key, exact, descending) {
+    return await this.call("viewNavigators.children.categoriesByKey", {
+      entryKey,
+      key,
+      exact,
+      descending
     });
   }
-  async listCategoryDocumentIds(categoryKey) {
-    return await this.rpc.call("views.category.documentIds", {
-      viewId: this.viewId,
-      categoryKey
+  async childDocumentsByKey(entryKey, key, exact, descending) {
+    return await this.call("viewNavigators.children.documentsByKey", {
+      entryKey,
+      key,
+      exact,
+      descending
     });
   }
+  async childCategoriesBetween(entryKey, range) {
+    return await this.call("viewNavigators.children.categoriesBetween", { entryKey, range });
+  }
+  async childDocumentsBetween(entryKey, range) {
+    return await this.call("viewNavigators.children.documentsBetween", { entryKey, range });
+  }
+  async getSortedDocIds(descending) {
+    return await this.call("viewNavigators.sortedDocIds.get", { descending });
+  }
+  async getSortedDocIdsScoped(entryKey, descending) {
+    return await this.call("viewNavigators.sortedDocIds.scoped", { entryKey, descending });
+  }
   async dispose() {
-    await this.rpc.call("views.dispose", {
-      viewId: this.viewId
-    });
+    await this.call("viewNavigators.dispose");
   }
 };
 var MindooDBAppReadableAttachmentStreamImpl = class {
@@ -607,6 +681,12 @@ var MindooDBAppDatabaseImpl = class {
         });
         return new MindooDBAppWritableAttachmentStreamImpl(this.rpc, result.streamId);
       },
+      preparePreviewSession: async (docId, attachmentName, options) => await this.rpc.call("attachments.preparePreviewSession", {
+        databaseId: this.databaseId,
+        docId,
+        attachmentName,
+        timestamp: options?.timestamp
+      }),
       openPreview: async (docId, attachmentName, options) => await this.rpc.call("attachments.openPreview", {
         databaseId: this.databaseId,
         docId,
@@ -632,6 +712,7 @@ var MindooDBAppSessionImpl = class {
   async getLaunchContext() {
     return await this.rpc.call("session.getLaunchContext", {});
   }
+  /** Lists the databases that the host has made available for this app session. */
   async listDatabases() {
     return await this.rpc.call("session.listDatabases", {});
   }
@@ -640,14 +721,28 @@ var MindooDBAppSessionImpl = class {
     await this.rpc.call("session.openDatabase", { databaseId });
     return new MindooDBAppDatabaseImpl(this.rpc, databaseId);
   }
-  async createView(input) {
-    const result = await this.rpc.call("session.createView", input);
-    return new MindooDBAppViewHandleImpl(this.rpc, result.viewId);
-  }
-  async openView(viewId) {
-    await this.rpc.call("session.openView", { viewId });
-    return new MindooDBAppViewHandleImpl(this.rpc, viewId);
-  }
+  /**
+   * Create a navigator from an ad-hoc view definition and one or more database bindings.
+   *
+   * The host builds a `VirtualView` from `input.definition`, optionally applying
+   * open options (root scoping, category filtering), and returns a `navigatorId`
+   * that all subsequent navigator RPCs reference.
+   */
+  async createViewNavigator(input) {
+    const result = await this.rpc.call("session.createViewNavigator", input);
+    return new MindooDBAppViewNavigatorImpl(this.rpc, result.navigatorId);
+  }
+  /**
+   * Open a navigator for a preconfigured view that the host already knows about.
+   *
+   * `viewId` must match one of the views declared in the launch context. The
+   * host resolves the full view definition and database bindings automatically.
+   */
+  async openViewNavigator(viewId, options) {
+    const result = await this.rpc.call("session.openViewNavigator", { viewId, options: options ?? {} });
+    return new MindooDBAppViewNavigatorImpl(this.rpc, result.navigatorId);
+  }
+  /** Subscribe to host-pushed theme changes (dark/light mode, color tokens). */
   onThemeChange(listener) {
     return this.rpc.addMessageListener((message) => {
       if (isThemeChangedMessage(message)) {
@@ -655,6 +750,7 @@ var MindooDBAppSessionImpl = class {
       }
     });
   }
+  /** Subscribe to host-pushed viewport dimension changes (resize, orientation). */
   onViewportChange(listener) {
     return this.rpc.addMessageListener((message) => {
       if (isViewportChangedMessage(message)) {

package/dist/testing/index.d.ts

@@ -1,10 +1,10 @@
-import { a0 as MindooDBAppLaunchContext, S as MindooDBAppDatabaseInfo, U as MindooDBAppDocumentApi, a8 as MindooDBAppViewHandle, b as MindooDBAppAttachmentApi, a as MindooDBAppBridge, a5 as MindooDBAppSession, m as MindooDBAppBridgeRpcRequest, $ as MindooDBAppHostTheme, a9 as MindooDBAppViewport, j as MindooDBAppBridgePortMessage } from '../types-BDY_80wd.js';
-import { MindooDBAppViewDefinition } from 'mindoodb-view-language';
+import { a2 as MindooDBAppLaunchContext, U as MindooDBAppDatabaseInfo, W as MindooDBAppDocumentApi, S as MindooDBAppCreateViewNavigatorInput, ad as MindooDBAppViewNavigator, af as MindooDBAppViewNavigatorOpenOptions, b as MindooDBAppAttachmentApi, a as MindooDBAppBridge, a8 as MindooDBAppSession, n as MindooDBAppBridgeRpcRequest, a1 as MindooDBAppHostTheme, ak as MindooDBAppViewport, k as MindooDBAppBridgePortMessage } from '../types-C_kZcG24.js';
+import 'mindoodb-view-language';
 
 type MaybePromise<T> = T | Promise<T>;
 type MockViewApi = {
-    create(definition: MindooDBAppViewDefinition): MaybePromise<MindooDBAppViewHandle>;
-    open(viewId: string): MaybePromise<MindooDBAppViewHandle>;
+    create(input: MindooDBAppCreateViewNavigatorInput): MaybePromise<MindooDBAppViewNavigator>;
+    open(viewId: string, options?: MindooDBAppViewNavigatorOpenOptions): MaybePromise<MindooDBAppViewNavigator>;
 };
 type MockDatabaseMethods = {
     documents?: Partial<MindooDBAppDocumentApi>;