mindoodb-app-sdk 0.0.7 → 0.0.8

package/README.md

@@ -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:
 
@@ -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-u5bAeQwY.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 MindooDBAppDatabase, T as MindooDBAppDatabaseInfo, U as MindooDBAppDocument, V as MindooDBAppDocumentApi, W as MindooDBAppDocumentHistoryEntry, X as MindooDBAppDocumentListQuery, Y as MindooDBAppDocumentListResult, Z as MindooDBAppDocumentSummary, _ as MindooDBAppHistoricalDocument, $ as MindooDBAppHistoryQuery, a0 as MindooDBAppHostTheme, a1 as MindooDBAppLaunchContext, a2 as MindooDBAppReadableAttachmentStream, a3 as MindooDBAppResolvedViewDefinition, a4 as MindooDBAppResolvedViewSource, a5 as MindooDBAppRuntime, a6 as MindooDBAppSession, a7 as MindooDBAppThemeMode, a8 as MindooDBAppUpdateDocumentInput, a9 as MindooDBAppViewHandle, aa as MindooDBAppViewport, ab as MindooDBAppWritableAttachmentStream } from './types-u5bAeQwY.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 collapse(rowKey) {
-    return await this.rpc.call("views.expansion.collapse", {
-      viewId: this.viewId,
-      rowKey
+  async gotoParent() {
+    return await this.call("viewNavigators.goto.parent");
+  }
+  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 pageCategory(categoryKey, input) {
-    return await this.rpc.call("views.category.page", {
-      viewId: this.viewId,
-      categoryKey,
-      request: input ?? {}
+  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 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 {
@@ -638,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", {});
   }
@@ -646,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)) {
@@ -661,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 { a1 as MindooDBAppLaunchContext, T as MindooDBAppDatabaseInfo, V as MindooDBAppDocumentApi, a9 as MindooDBAppViewHandle, b as MindooDBAppAttachmentApi, a as MindooDBAppBridge, a6 as MindooDBAppSession, n as MindooDBAppBridgeRpcRequest, a0 as MindooDBAppHostTheme, aa as MindooDBAppViewport, k as MindooDBAppBridgePortMessage } from '../types-u5bAeQwY.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>;

package/dist/testing/index.js

@@ -172,17 +172,22 @@ function decodeMockListCursor(cursor) {
   const offset = Number.parseInt(cursor, 10);
   return Number.isFinite(offset) && offset >= 0 ? offset : 0;
 }
-function createDefaultViewHandle() {
+function createDefaultViewNavigator() {
   const definition = {
     title: "Mock View",
     columns: []
   };
-  const expansion = {
-    mode: "collapsed",
-    ids: []
+  let expansion = {
+    expandAllByDefault: false,
+    expandLevel: 0,
+    entryKeys: []
+  };
+  let selection = {
+    selectAllByDefault: false,
+    entryKeys: []
   };
   const emptyPage = {
-    rows: [],
+    entries: [],
     nextPosition: null,
     hasMore: false
   };
@@ -192,43 +197,174 @@ function createDefaultViewHandle() {
     },
     async refresh() {
     },
-    async page(_input) {
+    async getCurrentEntry() {
+      return null;
+    },
+    async gotoFirst() {
+      return false;
+    },
+    async gotoLast() {
+      return false;
+    },
+    async gotoNext() {
+      return false;
+    },
+    async gotoPrev() {
+      return false;
+    },
+    async gotoNextSibling() {
+      return false;
+    },
+    async gotoPrevSibling() {
+      return false;
+    },
+    async gotoParent() {
+      return false;
+    },
+    async gotoFirstChild() {
+      return false;
+    },
+    async gotoLastChild() {
+      return false;
+    },
+    async gotoPos(_position) {
+      return false;
+    },
+    async getPos(_position) {
+      return null;
+    },
+    async findCategoryEntryByParts(_parts) {
+      return null;
+    },
+    async entriesForward(_options) {
       return emptyPage;
     },
-    async getExpansionState() {
-      return expansion;
+    async entriesBackward(_options) {
+      return emptyPage;
     },
-    async setExpansionState(state) {
-      return state;
+    async gotoNextSelected() {
+      return false;
     },
-    async expand(rowKey) {
-      return {
-        mode: "collapsed",
-        ids: [rowKey]
+    async gotoPrevSelected() {
+      return false;
+    },
+    async select(origin, docId, selectParentCategories = false) {
+      const key = `${origin}:${docId}`;
+      selection = {
+        ...selection,
+        entryKeys: Array.from(/* @__PURE__ */ new Set([...selection.entryKeys, key]))
+      };
+      if (selectParentCategories) {
+        selection = {
+          ...selection,
+          entryKeys: [...selection.entryKeys]
+        };
+      }
+    },
+    async deselect(origin, docId) {
+      const key = `${origin}:${docId}`;
+      selection = {
+        ...selection,
+        entryKeys: selection.entryKeys.filter((entry) => entry !== key)
       };
     },
-    async collapse(_rowKey) {
-      return expansion;
+    async selectAllEntries() {
+      selection = {
+        selectAllByDefault: true,
+        entryKeys: []
+      };
+    },
+    async deselectAllEntries() {
+      selection = {
+        selectAllByDefault: false,
+        entryKeys: []
+      };
+    },
+    async isSelected(origin, docId) {
+      const key = `${origin}:${docId}`;
+      return selection.selectAllByDefault ? !selection.entryKeys.includes(key) : selection.entryKeys.includes(key);
+    },
+    async getSelectionState() {
+      return selection;
+    },
+    async setSelectionState(state) {
+      selection = {
+        selectAllByDefault: state.selectAllByDefault,
+        entryKeys: [...state.entryKeys]
+      };
+    },
+    async expand(origin, docId) {
+      const key = `${origin}:${docId}`;
+      expansion = {
+        ...expansion,
+        entryKeys: Array.from(/* @__PURE__ */ new Set([...expansion.entryKeys, key]))
+      };
+    },
+    async collapse(origin, docId) {
+      const key = `${origin}:${docId}`;
+      expansion = {
+        ...expansion,
+        entryKeys: expansion.entryKeys.filter((entry) => entry !== key)
+      };
     },
     async expandAll() {
-      return {
-        mode: "expanded",
-        ids: []
+      expansion = {
+        expandAllByDefault: true,
+        expandLevel: expansion.expandLevel,
+        entryKeys: []
       };
     },
     async collapseAll() {
+      expansion = {
+        expandAllByDefault: false,
+        expandLevel: 0,
+        entryKeys: []
+      };
+    },
+    async expandToLevel(level) {
+      expansion = {
+        ...expansion,
+        expandLevel: level
+      };
+    },
+    async isExpanded(_entryKey) {
+      return expansion.expandAllByDefault;
+    },
+    async getExpansionState() {
       return expansion;
     },
-    async getRow(_rowKey) {
-      return null;
+    async setExpansionState(state) {
+      expansion = {
+        expandAllByDefault: state.expandAllByDefault,
+        expandLevel: state.expandLevel,
+        entryKeys: [...state.entryKeys]
+      };
     },
-    async getCategory(_input) {
-      return null;
+    async childEntries(_entryKey, _descending) {
+      return [];
     },
-    async pageCategory(_categoryKey, _input) {
-      return emptyPage;
+    async childCategories(_entryKey, _descending) {
+      return [];
+    },
+    async childDocuments(_entryKey, _descending) {
+      return [];
+    },
+    async childCategoriesByKey(_entryKey, _key, _exact, _descending) {
+      return [];
+    },
+    async childDocumentsByKey(_entryKey, _key, _exact, _descending) {
+      return [];
+    },
+    async childCategoriesBetween(_entryKey, _range) {
+      return [];
+    },
+    async childDocumentsBetween(_entryKey, _range) {
+      return [];
     },
-    async listCategoryDocumentIds(_categoryKey) {
+    async getSortedDocIds(_descending) {
+      return [];
+    },
+    async getSortedDocIdsScoped(_entryKey, _descending) {
       return [];
     },
     async dispose() {
@@ -237,7 +373,7 @@ function createDefaultViewHandle() {
 }
 function createDatabaseHandle(definition) {
   let createCounter = 0;
-  const defaultViewFactory = async () => createDefaultViewHandle();
+  const defaultViewFactory = async () => createDefaultViewNavigator();
   const storedDocuments = /* @__PURE__ */ new Map();
   const defaultDocuments = {
     async list(query) {
@@ -341,7 +477,7 @@ function createDatabaseHandle(definition) {
     }
   };
   const defaultViews = {
-    async create(_definition) {
+    async create(_input) {
       return await defaultViewFactory();
     },
     async open(_viewId) {
@@ -404,11 +540,11 @@ function createMockSessionState(options = {}) {
     for (const definition of definitions) {
       databaseHandles.set(definition.info.id, createDatabaseHandle(definition));
       databaseViewApis.set(definition.info.id, {
-        async create(_definition) {
-          return await createDefaultViewHandle();
+        async create(_input) {
+          return await createDefaultViewNavigator();
         },
         async open(_viewId) {
-          return await createDefaultViewHandle();
+          return await createDefaultViewNavigator();
         },
         ...definition.methods?.views ?? {}
       });
@@ -433,17 +569,21 @@ function createMockSessionState(options = {}) {
       }
       return database;
     },
-    async createView(input) {
-      const api = databaseViewApis.get(input.databaseId);
+    async createViewNavigator(input) {
+      const firstDatabaseId = input.databaseIds[0];
+      if (!firstDatabaseId) {
+        throw new Error("At least one test database is required for view creation.");
+      }
+      const api = databaseViewApis.get(firstDatabaseId);
       if (!api) {
-        throw new Error(`Unknown test database for view creation: ${input.databaseId}`);
+        throw new Error(`Unknown test database for view creation: ${firstDatabaseId}`);
       }
-      const view = await api.create(input.definition);
+      const view = await api.create(input);
       const viewId = input.definition.id || crypto.randomUUID();
       sessionViews.set(viewId, view);
       return view;
     },
-    async openView(viewId) {
+    async openViewNavigator(viewId, options2) {
       const existing = sessionViews.get(viewId);
       if (existing) {
         return existing;
@@ -456,7 +596,7 @@ function createMockSessionState(options = {}) {
       if (!api) {
         throw new Error(`Unknown test database for view ${viewId}: ${sourceDatabaseId}`);
       }
-      const view = await api.open(viewId);
+      const view = await api.open(viewId, options2);
       sessionViews.set(viewId, view);
       return view;
     },
@@ -503,8 +643,8 @@ function createMockSessionState(options = {}) {
       }
       return database;
     },
-    createView: session.createView,
-    openView: session.openView,
+    createViewNavigator: session.createViewNavigator,
+    openViewNavigator: session.openViewNavigator,
     bridge,
     session,
     emitThemeChange(theme) {
@@ -634,14 +774,14 @@ function createFakeBridgeHost(options = {}) {
     });
     installed = true;
   }
-  async function resolveViewHandle(viewId) {
+  async function resolveViewNavigator(viewId) {
     const existing = viewSessions.get(viewId);
     if (existing) {
       return existing;
     }
-    const handle = await state.openView(viewId);
-    viewSessions.set(viewId, handle);
-    return handle;
+    const navigator = await state.openViewNavigator(viewId);
+    viewSessions.set(viewId, navigator);
+    return navigator;
   }
   function postRpcSuccess(port, requestId, result) {
     port.postMessage({
@@ -684,18 +824,25 @@ function createFakeBridgeHost(options = {}) {
       case "session.openDatabase":
         state.getDatabase(String(params.databaseId));
         return { ok: true };
-      case "session.createView": {
-        const viewId = `view-${viewCounter += 1}`;
-        const handle = await state.createView({
-          databaseId: String(params.databaseId),
-          definition: params.definition
+      case "session.createViewNavigator": {
+        const navigatorId = `navigator-${viewCounter += 1}`;
+        const navigator = await state.createViewNavigator({
+          databaseIds: Array.isArray(params.databaseIds) ? params.databaseIds.map((entry) => String(entry)) : [],
+          definition: params.definition,
+          options: params.options
         });
-        viewSessions.set(viewId, handle);
-        return { viewId };
+        viewSessions.set(navigatorId, navigator);
+        return { navigatorId };
+      }
+      case "session.openViewNavigator": {
+        const navigatorId = `navigator-${viewCounter += 1}`;
+        const navigator = await state.openViewNavigator(
+          String(params.viewId),
+          params.options
+        );
+        viewSessions.set(navigatorId, navigator);
+        return { navigatorId };
       }
-      case "session.openView":
-        await state.openView(String(params.viewId));
-        return { ok: true };
       case "session.disconnect":
         await state.session.disconnect();
         return { ok: true };
@@ -757,47 +904,131 @@ function createFakeBridgeHost(options = {}) {
           String(params.attachmentName),
           typeof params.timestamp === "number" ? { timestamp: params.timestamp } : void 0
         );
-      case "views.getDefinition":
-        return await (await resolveViewHandle(String(params.viewId))).getDefinition();
-      case "views.refresh":
-        return await (await resolveViewHandle(String(params.viewId))).refresh();
-      case "views.page":
-        return await (await resolveViewHandle(String(params.viewId))).page(
-          params.request
+      case "viewNavigators.getDefinition":
+        return await (await resolveViewNavigator(String(params.navigatorId))).getDefinition();
+      case "viewNavigators.refresh":
+        return await (await resolveViewNavigator(String(params.navigatorId))).refresh();
+      case "viewNavigators.current.get":
+        return await (await resolveViewNavigator(String(params.navigatorId))).getCurrentEntry();
+      case "viewNavigators.goto.first":
+        return await (await resolveViewNavigator(String(params.navigatorId))).gotoFirst();
+      case "viewNavigators.goto.last":
+        return await (await resolveViewNavigator(String(params.navigatorId))).gotoLast();
+      case "viewNavigators.goto.next":
+        return await (await resolveViewNavigator(String(params.navigatorId))).gotoNext();
+      case "viewNavigators.goto.prev":
+        return await (await resolveViewNavigator(String(params.navigatorId))).gotoPrev();
+      case "viewNavigators.goto.nextSibling":
+        return await (await resolveViewNavigator(String(params.navigatorId))).gotoNextSibling();
+      case "viewNavigators.goto.prevSibling":
+        return await (await resolveViewNavigator(String(params.navigatorId))).gotoPrevSibling();
+      case "viewNavigators.goto.parent":
+        return await (await resolveViewNavigator(String(params.navigatorId))).gotoParent();
+      case "viewNavigators.goto.firstChild":
+        return await (await resolveViewNavigator(String(params.navigatorId))).gotoFirstChild();
+      case "viewNavigators.goto.lastChild":
+        return await (await resolveViewNavigator(String(params.navigatorId))).gotoLastChild();
+      case "viewNavigators.goto.pos":
+        return await (await resolveViewNavigator(String(params.navigatorId))).gotoPos(String(params.position));
+      case "viewNavigators.pos.get":
+        return await (await resolveViewNavigator(String(params.navigatorId))).getPos(String(params.position));
+      case "viewNavigators.category.findByParts":
+        return await (await resolveViewNavigator(String(params.navigatorId))).findCategoryEntryByParts(
+          Array.isArray(params.parts) ? params.parts : []
+        );
+      case "viewNavigators.entries.forward":
+        return await (await resolveViewNavigator(String(params.navigatorId))).entriesForward(
+          params.options
+        );
+      case "viewNavigators.entries.backward":
+        return await (await resolveViewNavigator(String(params.navigatorId))).entriesBackward(
+          params.options
+        );
+      case "viewNavigators.goto.nextSelected":
+        return await (await resolveViewNavigator(String(params.navigatorId))).gotoNextSelected();
+      case "viewNavigators.goto.prevSelected":
+        return await (await resolveViewNavigator(String(params.navigatorId))).gotoPrevSelected();
+      case "viewNavigators.selection.select":
+        return await (await resolveViewNavigator(String(params.navigatorId))).select(
+          String(params.origin),
+          String(params.docId),
+          Boolean(params.selectParentCategories)
+        );
+      case "viewNavigators.selection.deselect":
+        return await (await resolveViewNavigator(String(params.navigatorId))).deselect(String(params.origin), String(params.docId));
+      case "viewNavigators.selection.selectAll":
+        return await (await resolveViewNavigator(String(params.navigatorId))).selectAllEntries();
+      case "viewNavigators.selection.deselectAll":
+        return await (await resolveViewNavigator(String(params.navigatorId))).deselectAllEntries();
+      case "viewNavigators.selection.isSelected":
+        return await (await resolveViewNavigator(String(params.navigatorId))).isSelected(String(params.origin), String(params.docId));
+      case "viewNavigators.selection.get":
+        return await (await resolveViewNavigator(String(params.navigatorId))).getSelectionState();
+      case "viewNavigators.selection.set":
+        return await (await resolveViewNavigator(String(params.navigatorId))).setSelectionState(
+          params.state
+        );
+      case "viewNavigators.expansion.expand":
+        return await (await resolveViewNavigator(String(params.navigatorId))).expand(String(params.origin), String(params.docId));
+      case "viewNavigators.expansion.collapse":
+        return await (await resolveViewNavigator(String(params.navigatorId))).collapse(String(params.origin), String(params.docId));
+      case "viewNavigators.expansion.expandAll":
+        return await (await resolveViewNavigator(String(params.navigatorId))).expandAll();
+      case "viewNavigators.expansion.collapseAll":
+        return await (await resolveViewNavigator(String(params.navigatorId))).collapseAll();
+      case "viewNavigators.expansion.expandToLevel":
+        return await (await resolveViewNavigator(String(params.navigatorId))).expandToLevel(Number(params.level));
+      case "viewNavigators.expansion.isExpanded":
+        return await (await resolveViewNavigator(String(params.navigatorId))).isExpanded(String(params.entryKey));
+      case "viewNavigators.expansion.get":
+        return await (await resolveViewNavigator(String(params.navigatorId))).getExpansionState();
+      case "viewNavigators.expansion.set":
+        return await (await resolveViewNavigator(String(params.navigatorId))).setExpansionState(
+          params.state
+        );
+      case "viewNavigators.children.entries":
+        return await (await resolveViewNavigator(String(params.navigatorId))).childEntries(String(params.entryKey), Boolean(params.descending));
+      case "viewNavigators.children.categories":
+        return await (await resolveViewNavigator(String(params.navigatorId))).childCategories(String(params.entryKey), Boolean(params.descending));
+      case "viewNavigators.children.documents":
+        return await (await resolveViewNavigator(String(params.navigatorId))).childDocuments(String(params.entryKey), Boolean(params.descending));
+      case "viewNavigators.children.categoriesByKey":
+        return await (await resolveViewNavigator(String(params.navigatorId))).childCategoriesByKey(
+          String(params.entryKey),
+          params.key,
+          typeof params.exact === "boolean" ? params.exact : void 0,
+          typeof params.descending === "boolean" ? params.descending : void 0
+        );
+      case "viewNavigators.children.documentsByKey":
+        return await (await resolveViewNavigator(String(params.navigatorId))).childDocumentsByKey(
+          String(params.entryKey),
+          params.key,
+          typeof params.exact === "boolean" ? params.exact : void 0,
+          typeof params.descending === "boolean" ? params.descending : void 0
         );
-      case "views.expansion.get":
-        return await (await resolveViewHandle(String(params.viewId))).getExpansionState();
-      case "views.expansion.set":
-        return await (await resolveViewHandle(String(params.viewId))).setExpansionState(
-          params.expansion
+      case "viewNavigators.children.categoriesBetween":
+        return await (await resolveViewNavigator(String(params.navigatorId))).childCategoriesBetween(
+          String(params.entryKey),
+          params.range
         );
-      case "views.expansion.expand":
-        return await (await resolveViewHandle(String(params.viewId))).expand(String(params.rowKey));
-      case "views.expansion.collapse":
-        return await (await resolveViewHandle(String(params.viewId))).collapse(String(params.rowKey));
-      case "views.expansion.expandAll":
-        return await (await resolveViewHandle(String(params.viewId))).expandAll();
-      case "views.expansion.collapseAll":
-        return await (await resolveViewHandle(String(params.viewId))).collapseAll();
-      case "views.row.get":
-        return await (await resolveViewHandle(String(params.viewId))).getRow(String(params.rowKey));
-      case "views.category.get":
-        return await (await resolveViewHandle(String(params.viewId))).getCategory(
-          params.lookup
+      case "viewNavigators.children.documentsBetween":
+        return await (await resolveViewNavigator(String(params.navigatorId))).childDocumentsBetween(
+          String(params.entryKey),
+          params.range
         );
-      case "views.category.page":
-        return await (await resolveViewHandle(String(params.viewId))).pageCategory(
-          String(params.categoryKey),
-          params.request
+      case "viewNavigators.sortedDocIds.get":
+        return await (await resolveViewNavigator(String(params.navigatorId))).getSortedDocIds(
+          typeof params.descending === "boolean" ? params.descending : void 0
         );
-      case "views.category.documentIds":
-        return await (await resolveViewHandle(String(params.viewId))).listCategoryDocumentIds(
-          String(params.categoryKey)
+      case "viewNavigators.sortedDocIds.scoped":
+        return await (await resolveViewNavigator(String(params.navigatorId))).getSortedDocIdsScoped(
+          String(params.entryKey),
+          typeof params.descending === "boolean" ? params.descending : void 0
         );
-      case "views.dispose": {
-        const key = String(params.viewId);
-        const handle = await resolveViewHandle(String(params.viewId));
-        await handle.dispose();
+      case "viewNavigators.dispose": {
+        const key = String(params.navigatorId);
+        const navigator = await resolveViewNavigator(key);
+        await navigator.dispose();
         viewSessions.delete(key);
         return void 0;
       }
@@ -877,7 +1108,7 @@ function createFakeBridgeHost(options = {}) {
           return;
         }
         const builtinResult = await handleBuiltinRequest(message);
-        if (builtinResult === void 0 && message.method !== "views.dispose") {
+        if (builtinResult === void 0 && message.method !== "viewNavigators.dispose") {
           postRpcError(port, message.id, {
             code: "unsupported-method",
             message: `No fake bridge handler is configured for ${message.method}.`

package/dist/{types-u5bAeQwY.d.ts → types-C_kZcG24.d.ts}

@@ -1,4 +1,4 @@
-import { MindooDBAppBooleanExpression, MindooDBAppExpression, MindooDBAppViewSortDirection, MindooDBAppViewTotalMode, MindooDBAppViewDefinition, MindooDBAppViewPageRequest, MindooDBAppViewPageResult, MindooDBAppViewExpansionState, MindooDBAppViewRow, MindooDBAppViewLookupByPath, MindooDBAppViewCategoryChildrenPageRequest } from 'mindoodb-view-language';
+import { MindooDBAppBooleanExpression, MindooDBAppExpression, MindooDBAppViewSortDirection, MindooDBAppViewTotalMode, MindooDBAppViewDefinition } from 'mindoodb-view-language';
 
 /** Launch target used by the Administrator when opening an app. */
 type MindooDBAppRuntime = "iframe" | "window";
@@ -336,28 +336,125 @@ interface MindooDBAppDocumentApi {
     listHistory(docId: string): Promise<MindooDBAppDocumentHistoryEntry[]>;
     getAtTimestamp(docId: string, timestamp: number): Promise<MindooDBAppHistoricalDocument>;
 }
-/** Handle for one created or opened virtual view. */
-interface MindooDBAppViewHandle {
+type MindooDBAppViewEntryKind = "category" | "document";
+/** Unique document identity within a multi-source view. */
+interface MindooDBAppScopedDocId {
+    origin: string;
+    docId: string;
+}
+/** Serialized view entry returned by the navigator APIs. */
+interface MindooDBAppViewEntry {
+    /** Unique occurrence key within the current navigator session. */
+    key: string;
+    kind: MindooDBAppViewEntryKind;
+    origin: string;
+    docId: string | null;
+    level: number;
+    parentKey: string | null;
+    categoryPath: unknown[];
+    columnValues: Record<string, unknown>;
+    descendantDocumentCount: number;
+    childCategoryCount: number;
+    childDocumentCount: number;
+    /** Stable continuation token for the current occurrence. */
+    position: string | null;
+    expanded: boolean;
+    selected: boolean;
+    isVisible: boolean;
+}
+/** Options that shape which subtree and entry kinds a navigator exposes. */
+interface MindooDBAppViewNavigatorOpenOptions {
+    includeCategories?: boolean;
+    includeDocuments?: boolean;
+    hideEmptyCategories?: boolean;
+    rootCategoryPath?: unknown[];
+    rootEntryKey?: string;
+}
+/** Input used when creating a dynamic view and immediately opening a navigator. */
+interface MindooDBAppCreateViewNavigatorInput {
+    databaseIds: string[];
+    definition: MindooDBAppViewDefinition;
+    options?: MindooDBAppViewNavigatorOpenOptions;
+}
+/** @deprecated Use `MindooDBAppCreateViewNavigatorInput`. */
+type MindooDBAppCreateViewInput = MindooDBAppCreateViewNavigatorInput;
+/** Range query options for key and key-range lookups within a category. */
+interface MindooDBAppViewNavigatorRangeQuery {
+    startKey?: unknown;
+    endKey?: unknown;
+    descending?: boolean;
+    exact?: boolean;
+}
+/** Options for batched navigator reads. */
+interface MindooDBAppViewNavigatorPageOptions {
+    limit?: number;
+    selectedOnly?: boolean;
+    startPosition?: string | null;
+}
+/** Paged batch of navigator entries. */
+interface MindooDBAppViewNavigatorPageResult {
+    entries: MindooDBAppViewEntry[];
+    nextPosition: string | null;
+    hasMore: boolean;
+}
+/** Serializable selection state for restoring a navigator session. */
+interface MindooDBAppViewNavigatorSelectionState {
+    selectAllByDefault: boolean;
+    entryKeys: string[];
+}
+/** Serializable expansion state for restoring a navigator session. */
+interface MindooDBAppViewNavigatorExpansionState {
+    expandAllByDefault: boolean;
+    expandLevel: number;
+    entryKeys: string[];
+}
+/** Stateful view navigator that closely mirrors the core VirtualViewNavigator. */
+interface MindooDBAppViewNavigator {
     getDefinition(): Promise<MindooDBAppViewDefinition>;
     refresh(): Promise<void>;
-    page(input?: MindooDBAppViewPageRequest): Promise<MindooDBAppViewPageResult>;
-    getExpansionState(): Promise<MindooDBAppViewExpansionState>;
-    setExpansionState(state: MindooDBAppViewExpansionState): Promise<MindooDBAppViewExpansionState>;
-    expand(rowKey: string): Promise<MindooDBAppViewExpansionState>;
-    collapse(rowKey: string): Promise<MindooDBAppViewExpansionState>;
-    expandAll(): Promise<MindooDBAppViewExpansionState>;
-    collapseAll(): Promise<MindooDBAppViewExpansionState>;
-    getRow(rowKey: string): Promise<MindooDBAppViewRow | null>;
-    getCategory(input: MindooDBAppViewLookupByPath): Promise<MindooDBAppViewRow | null>;
-    pageCategory(categoryKey: string, input?: MindooDBAppViewCategoryChildrenPageRequest): Promise<MindooDBAppViewPageResult>;
-    listCategoryDocumentIds(categoryKey: string): Promise<string[]>;
+    getCurrentEntry(): Promise<MindooDBAppViewEntry | null>;
+    gotoFirst(): Promise<boolean>;
+    gotoLast(): Promise<boolean>;
+    gotoNext(): Promise<boolean>;
+    gotoPrev(): Promise<boolean>;
+    gotoNextSibling(): Promise<boolean>;
+    gotoPrevSibling(): Promise<boolean>;
+    gotoParent(): Promise<boolean>;
+    gotoFirstChild(): Promise<boolean>;
+    gotoLastChild(): Promise<boolean>;
+    gotoPos(position: string): Promise<boolean>;
+    getPos(position: string): Promise<MindooDBAppViewEntry | null>;
+    findCategoryEntryByParts(parts: unknown[]): Promise<MindooDBAppViewEntry | null>;
+    entriesForward(options?: MindooDBAppViewNavigatorPageOptions): Promise<MindooDBAppViewNavigatorPageResult>;
+    entriesBackward(options?: MindooDBAppViewNavigatorPageOptions): Promise<MindooDBAppViewNavigatorPageResult>;
+    gotoNextSelected(): Promise<boolean>;
+    gotoPrevSelected(): Promise<boolean>;
+    select(origin: string, docId: string, selectParentCategories?: boolean): Promise<void>;
+    deselect(origin: string, docId: string): Promise<void>;
+    selectAllEntries(): Promise<void>;
+    deselectAllEntries(): Promise<void>;
+    isSelected(origin: string, docId: string): Promise<boolean>;
+    getSelectionState(): Promise<MindooDBAppViewNavigatorSelectionState>;
+    setSelectionState(state: MindooDBAppViewNavigatorSelectionState): Promise<void>;
+    expand(origin: string, docId: string): Promise<void>;
+    collapse(origin: string, docId: string): Promise<void>;
+    expandAll(): Promise<void>;
+    collapseAll(): Promise<void>;
+    expandToLevel(level: number): Promise<void>;
+    isExpanded(entryKey: string): Promise<boolean>;
+    getExpansionState(): Promise<MindooDBAppViewNavigatorExpansionState>;
+    setExpansionState(state: MindooDBAppViewNavigatorExpansionState): Promise<void>;
+    childEntries(entryKey: string, descending?: boolean): Promise<MindooDBAppViewEntry[]>;
+    childCategories(entryKey: string, descending?: boolean): Promise<MindooDBAppViewEntry[]>;
+    childDocuments(entryKey: string, descending?: boolean): Promise<MindooDBAppViewEntry[]>;
+    childCategoriesByKey(entryKey: string, key: unknown, exact?: boolean, descending?: boolean): Promise<MindooDBAppViewEntry[]>;
+    childDocumentsByKey(entryKey: string, key: unknown, exact?: boolean, descending?: boolean): Promise<MindooDBAppViewEntry[]>;
+    childCategoriesBetween(entryKey: string, range: MindooDBAppViewNavigatorRangeQuery): Promise<MindooDBAppViewEntry[]>;
+    childDocumentsBetween(entryKey: string, range: MindooDBAppViewNavigatorRangeQuery): Promise<MindooDBAppViewEntry[]>;
+    getSortedDocIds(descending?: boolean): Promise<MindooDBAppScopedDocId[]>;
+    getSortedDocIdsScoped(entryKey: string, descending?: boolean): Promise<MindooDBAppScopedDocId[]>;
     dispose(): Promise<void>;
 }
-/** Payload used when creating one dynamic view inside the current app session. */
-interface MindooDBAppCreateViewInput {
-    databaseId: string;
-    definition: MindooDBAppViewDefinition;
-}
 /** Attachment operations exposed by an opened database handle. */
 interface MindooDBAppAttachmentApi {
     list(docId: string): Promise<MindooDBAppAttachmentInfo[]>;
@@ -382,8 +479,8 @@ interface MindooDBAppSession {
     getLaunchContext(): Promise<MindooDBAppLaunchContext>;
     listDatabases(): Promise<MindooDBAppDatabaseInfo[]>;
     openDatabase(databaseId: string): Promise<MindooDBAppDatabase>;
-    createView(input: MindooDBAppCreateViewInput): Promise<MindooDBAppViewHandle>;
-    openView(viewId: string): Promise<MindooDBAppViewHandle>;
+    createViewNavigator(input: MindooDBAppCreateViewNavigatorInput): Promise<MindooDBAppViewNavigator>;
+    openViewNavigator(viewId: string, options?: MindooDBAppViewNavigatorOpenOptions): Promise<MindooDBAppViewNavigator>;
     onThemeChange(listener: (theme: MindooDBAppHostTheme) => void): () => void;
     onViewportChange(listener: (viewport: MindooDBAppViewport) => void): () => void;
     disconnect(): Promise<void>;
@@ -393,4 +490,4 @@ interface MindooDBAppBridge {
     connect(options?: MindooDBAppBridgeConnectOptions): Promise<MindooDBAppSession>;
 }
 
-export type { MindooDBAppHistoryQuery as $, MindooDBAppConfiguredViewCategorizationStyle as A, MindooDBAppConfiguredViewColumn as B, MindooDBAppConfiguredViewColumnRole as C, MindooDBAppConfiguredViewExpressionMode as D, MindooDBAppConfiguredViewFieldExpression as E, MindooDBAppConfiguredViewFilterDefinition as F, MindooDBAppConfiguredViewFilterMode as G, MindooDBAppConfiguredViewFilterRule as H, MindooDBAppConfiguredViewFormulaExpression as I, MindooDBAppConfiguredViewFormulaFilterDefinition as J, MindooDBAppConfiguredViewPreviewMode as K, MindooDBAppConfiguredViewRuleFilterDefinition as L, MindooDBAppAttachmentPreviewMode as M, MindooDBAppConfiguredViewRuleMatchMode as N, MindooDBAppConfiguredViewRuleOperator as O, MindooDBAppConfiguredViewValueExpression as P, MindooDBAppCreateDocumentInput as Q, MindooDBAppCreateViewInput as R, MindooDBAppDatabase as S, MindooDBAppDatabaseInfo as T, MindooDBAppDocument as U, MindooDBAppDocumentApi as V, MindooDBAppDocumentHistoryEntry as W, MindooDBAppDocumentListQuery as X, MindooDBAppDocumentListResult as Y, MindooDBAppDocumentSummary as Z, MindooDBAppHistoricalDocument as _, MindooDBAppBridge as a, MindooDBAppHostTheme as a0, MindooDBAppLaunchContext as a1, MindooDBAppReadableAttachmentStream as a2, MindooDBAppResolvedViewDefinition as a3, MindooDBAppResolvedViewSource as a4, MindooDBAppRuntime as a5, MindooDBAppSession as a6, MindooDBAppThemeMode as a7, MindooDBAppUpdateDocumentInput as a8, MindooDBAppViewHandle as a9, MindooDBAppViewport as aa, MindooDBAppWritableAttachmentStream as ab, MindooDBAppAttachmentApi as b, MindooDBAppAttachmentChunk as c, MindooDBAppAttachmentInfo as d, MindooDBAppAttachmentPreviewOptions as e, MindooDBAppAttachmentPreviewSession as f, MindooDBAppBridgeConnectMessage as g, MindooDBAppBridgeConnectOptions as h, MindooDBAppBridgeConnectedMessage as i, MindooDBAppBridgeErrorPayload as j, MindooDBAppBridgePortMessage as k, MindooDBAppBridgeRpcError as l, MindooDBAppBridgeRpcMessage as m, MindooDBAppBridgeRpcRequest as n, MindooDBAppBridgeRpcSuccess as o, MindooDBAppBridgeStreamAbortRequest as p, MindooDBAppBridgeStreamAck as q, MindooDBAppBridgeStreamCloseRequest as r, MindooDBAppBridgeStreamError as s, MindooDBAppBridgeStreamMessage as t, MindooDBAppBridgeStreamOpenResult as u, MindooDBAppBridgeStreamReadRequest as v, MindooDBAppBridgeStreamWriteRequest as w, MindooDBAppBridgeThemeChangedMessage as x, MindooDBAppBridgeViewportChangedMessage as y, MindooDBAppCapability as z };
+export type { MindooDBAppHistoricalDocument as $, MindooDBAppConfiguredViewCategorizationStyle as A, MindooDBAppConfiguredViewColumn as B, MindooDBAppConfiguredViewColumnRole as C, MindooDBAppConfiguredViewExpressionMode as D, MindooDBAppConfiguredViewFieldExpression as E, MindooDBAppConfiguredViewFilterDefinition as F, MindooDBAppConfiguredViewFilterMode as G, MindooDBAppConfiguredViewFilterRule as H, MindooDBAppConfiguredViewFormulaExpression as I, MindooDBAppConfiguredViewFormulaFilterDefinition as J, MindooDBAppConfiguredViewPreviewMode as K, MindooDBAppConfiguredViewRuleFilterDefinition as L, MindooDBAppAttachmentPreviewMode as M, MindooDBAppConfiguredViewRuleMatchMode as N, MindooDBAppConfiguredViewRuleOperator as O, MindooDBAppConfiguredViewValueExpression as P, MindooDBAppCreateDocumentInput as Q, MindooDBAppCreateViewInput as R, MindooDBAppCreateViewNavigatorInput as S, MindooDBAppDatabase as T, MindooDBAppDatabaseInfo as U, MindooDBAppDocument as V, MindooDBAppDocumentApi as W, MindooDBAppDocumentHistoryEntry as X, MindooDBAppDocumentListQuery as Y, MindooDBAppDocumentListResult as Z, MindooDBAppDocumentSummary as _, MindooDBAppBridge as a, MindooDBAppHistoryQuery as a0, MindooDBAppHostTheme as a1, MindooDBAppLaunchContext as a2, MindooDBAppReadableAttachmentStream as a3, MindooDBAppResolvedViewDefinition as a4, MindooDBAppResolvedViewSource as a5, MindooDBAppRuntime as a6, MindooDBAppScopedDocId as a7, MindooDBAppSession as a8, MindooDBAppThemeMode as a9, MindooDBAppUpdateDocumentInput as aa, MindooDBAppViewEntry as ab, MindooDBAppViewEntryKind as ac, MindooDBAppViewNavigator as ad, MindooDBAppViewNavigatorExpansionState as ae, MindooDBAppViewNavigatorOpenOptions as af, MindooDBAppViewNavigatorPageOptions as ag, MindooDBAppViewNavigatorPageResult as ah, MindooDBAppViewNavigatorRangeQuery as ai, MindooDBAppViewNavigatorSelectionState as aj, MindooDBAppViewport as ak, MindooDBAppWritableAttachmentStream as al, MindooDBAppAttachmentApi as b, MindooDBAppAttachmentChunk as c, MindooDBAppAttachmentInfo as d, MindooDBAppAttachmentPreviewOptions as e, MindooDBAppAttachmentPreviewSession as f, MindooDBAppBridgeConnectMessage as g, MindooDBAppBridgeConnectOptions as h, MindooDBAppBridgeConnectedMessage as i, MindooDBAppBridgeErrorPayload as j, MindooDBAppBridgePortMessage as k, MindooDBAppBridgeRpcError as l, MindooDBAppBridgeRpcMessage as m, MindooDBAppBridgeRpcRequest as n, MindooDBAppBridgeRpcSuccess as o, MindooDBAppBridgeStreamAbortRequest as p, MindooDBAppBridgeStreamAck as q, MindooDBAppBridgeStreamCloseRequest as r, MindooDBAppBridgeStreamError as s, MindooDBAppBridgeStreamMessage as t, MindooDBAppBridgeStreamOpenResult as u, MindooDBAppBridgeStreamReadRequest as v, MindooDBAppBridgeStreamWriteRequest as w, MindooDBAppBridgeThemeChangedMessage as x, MindooDBAppBridgeViewportChangedMessage as y, MindooDBAppCapability as z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mindoodb-app-sdk",
-  "version": "0.0.7",
+  "version": "0.0.8",
   "description": "MindooDB app SDK for building apps that connect to the Haven host bridge",
   "license": "ISC",
   "author": "Mindoo GmbH",