mindoodb-app-sdk 0.0.7 → 0.0.9

package/README.md

@@ -137,6 +137,74 @@ interface MindooDBAppLaunchContext {
 
 `viewport` is the iframe size at launch time. It is `null` when the app runs in `window` mode (separate browser tab). Later changes arrive through `onViewportChange()`.
 
+You can use `runtime` to decide when a host-rendered overlay is necessary:
+
+```ts
+const ctx = await session.getLaunchContext();
+
+if (ctx.runtime === "iframe") {
+  // Prefer host-rendered menus when clipping outside the iframe matters.
+} else {
+  // A regular in-app menu is often fine in a separate window.
+}
+```
+
+### Host-rendered menus
+
+When your app runs inside an iframe, Haven can render a structured menu above the iframe chrome. This is useful for context menus, toolbar drop-downs, and simple pickers such as font-family or font-size lists.
+
+```ts
+const result = await session.menus.show({
+  anchor: {
+    type: "point",
+    x: event.clientX,
+    y: event.clientY,
+  },
+  kind: "context",
+  items: [
+    { id: "rename", label: "Rename" },
+    { separator: true },
+    { id: "delete", label: "Delete", destructive: true },
+  ],
+});
+
+if (result.action === "selected") {
+  console.log("Chosen action:", result.itemId);
+}
+```
+
+Rect anchors work well for button-triggered menus:
+
+```ts
+const bounds = button.getBoundingClientRect();
+const frameBounds = document.documentElement.getBoundingClientRect();
+
+await session.menus.show({
+  anchor: {
+    type: "rect",
+    rect: {
+      left: bounds.left - frameBounds.left,
+      top: bounds.top - frameBounds.top,
+      width: bounds.width,
+      height: bounds.height,
+    },
+  },
+  kind: "dropdown",
+  placement: "bottom-start",
+  items: [
+    { id: "sans", label: "Sans Serif", checked: true },
+    { id: "serif", label: "Serif" },
+  ],
+});
+```
+
+Important constraints:
+
+- Menus are host-rendered and data-only. Apps cannot pass HTML, CSS, or script.
+- `show()` resolves to either `{ action: "selected", itemId }` or `{ action: "dismissed", reason }`.
+- Call `session.menus.hide()` if your app needs to explicitly dismiss a pending host menu.
+- Host-rendered menus are intended for `runtime === "iframe"`. Window-mode apps can usually show local menus instead.
+
 ### Databases and capabilities
 
 Each database mapped to your app carries a set of **capabilities** that Haven controls. Your app should check capabilities before attempting operations and adapt its UI accordingly.
@@ -410,20 +478,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 +516,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());
+```
 
-// Expand/collapse categories
-await view.expandAll();
-await view.collapse(someCategoryKey);
+**Batch reads for UI rendering**:
 
-await view.dispose();
+```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**:
+
+```ts
+const category = await navigator.findCategoryEntryByParts(["Ada"]);
+if (category) {
+  const docs = await navigator.childDocuments(category.key);
+  console.log(docs.map((entry) => entry.docId));
+}
 ```
 
-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.
+**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",
+  });
+}
+```
+
+**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 +679,10 @@ 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>` |
+| `menus.show(input)` | `Promise<MindooDBAppShowMenuResult>` |
+| `menus.hide()` | `Promise<void>` |
 | `onThemeChange(listener)` | `() => void` (unsubscribe) |
 | `onViewportChange(listener)` | `() => void` (unsubscribe) |
 | `disconnect()` | `Promise<void>` |
@@ -572,23 +719,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-Bh1Q2qGN.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 MindooDBAppMenuAnchor, a4 as MindooDBAppMenuApi, a5 as MindooDBAppMenuCommandItem, a6 as MindooDBAppMenuDismissReason, a7 as MindooDBAppMenuDismissedResult, a8 as MindooDBAppMenuItem, a9 as MindooDBAppMenuKind, aa as MindooDBAppMenuPlacement, ab as MindooDBAppMenuPointAnchor, ac as MindooDBAppMenuRect, ad as MindooDBAppMenuRectAnchor, ae as MindooDBAppMenuSelectionResult, af as MindooDBAppMenuSeparatorItem, ag as MindooDBAppReadableAttachmentStream, ah as MindooDBAppResolvedViewDefinition, ai as MindooDBAppResolvedViewSource, aj as MindooDBAppRuntime, ak as MindooDBAppScopedDocId, al as MindooDBAppSession, am as MindooDBAppShowMenuInput, an as MindooDBAppShowMenuResult, ao as MindooDBAppThemeMode, ap as MindooDBAppUpdateDocumentInput, aq as MindooDBAppViewEntry, ar as MindooDBAppViewEntryKind, as as MindooDBAppViewNavigator, at as MindooDBAppViewNavigatorExpansionState, au as MindooDBAppViewNavigatorOpenOptions, av as MindooDBAppViewNavigatorPageOptions, aw as MindooDBAppViewNavigatorPageResult, ax as MindooDBAppViewNavigatorRangeQuery, ay as MindooDBAppViewNavigatorSelectionState, az as MindooDBAppViewport, aA as MindooDBAppWritableAttachmentStream } from './types-Bh1Q2qGN.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 setExpansionState(state) {
+    await this.call("viewNavigators.expansion.set", { state });
   }
-  async pageCategory(categoryKey, input) {
-    return await this.rpc.call("views.category.page", {
-      viewId: this.viewId,
-      categoryKey,
-      request: input ?? {}
+  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 {
@@ -633,11 +707,19 @@ var MindooDBAppDatabaseImpl = class {
 var MindooDBAppSessionImpl = class {
   constructor(rpc) {
     this.rpc = rpc;
+    this.menus = {
+      show: async (input) => await this.rpc.call("menus.show", input),
+      hide: async () => {
+        await this.rpc.call("menus.hide", {});
+      }
+    };
   }
+  menus;
   /** Returns the launch context provided by the Administrator host. */
   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 +728,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 +757,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, as as MindooDBAppViewNavigator, au as MindooDBAppViewNavigatorOpenOptions, b as MindooDBAppAttachmentApi, a as MindooDBAppBridge, al as MindooDBAppSession, n as MindooDBAppBridgeRpcRequest, a1 as MindooDBAppHostTheme, az as MindooDBAppViewport, k as MindooDBAppBridgePortMessage } from '../types-Bh1Q2qGN.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>;