mindoodb-app-sdk 0.0.5 → 0.0.7

package/README.md

@@ -1,29 +1,50 @@
 # mindoodb-app-sdk
 
-`mindoodb-app-sdk` is the browser-side SDK for building apps that run inside MindooDB Haven and talk to the Haven host bridge.
+Build apps that run inside **MindooDB Haven** -- the browser-based workspace for end-to-end encrypted, offline-first data.
 
-Use it when your app is launched by Haven in an iframe or in a separate window and needs:
+`mindoodb-app-sdk` is the TypeScript SDK that connects your web application to Haven through a secure message bridge. Your app runs in a sandboxed iframe (or a separate browser window) and gains access to databases, documents, attachments, virtual views, and live host events -- all without ever touching encryption keys or raw sync state.
 
-- launch metadata such as user, runtime, theme, and current iframe viewport
-- access to the databases Haven mapped into the app session
-- document, history, attachment, and view operations through a stable bridge API
-- host-driven UI events such as theme and viewport changes
+## What is a MindooDB App?
 
-## What the Haven host bridge provides
+[MindooDB](https://mindoodb.com) is an **end-to-end encrypted, offline-first sync database**. Data is encrypted on the client before it ever leaves the device. Under the hood it uses [Automerge](https://automerge.org/) CRDTs so multiple users can edit concurrently and conflicts resolve automatically.
 
-The Haven host bridge is a `postMessage` + `MessageChannel` / `MessagePort` connection between your app and Haven.
+**Haven** is the browser-based workspace that sits on top of MindooDB. Users organize databases, applications, notes, and media on a visual grid -- think of it as a customizable home screen for encrypted data that works offline and syncs in the background.
 
-Once connected, Haven provides:
+A **MindooDB App** is any web application that uses this SDK to communicate with Haven. When Haven launches your app, it opens it inside a sandboxed iframe (or a new browser tab) and establishes a `postMessage` + `MessagePort` bridge. Through this bridge your app can:
 
-- a `MindooDBAppSession` for the current launch
-- a `launchContext` snapshot with app id, user, runtime, theme, launch parameters, and current viewport
-- database handles that are already permission-scoped and mapped by Haven
-- live host events:
-  - `onThemeChange()` when Haven switches between light and dark mode or theme presets
-  - `onViewportChange()` when the iframe size changes inside Haven
-- CRUD, history, attachments, and app-defined virtual views over the same bridge
+- read launch metadata (user, theme, viewport, mapped databases, configured views)
+- perform CRUD operations on JSON documents with full change history
+- upload, download, and preview file attachments
+- query virtual views with categorization, sorting, and aggregation
+- react to live theme and viewport events from Haven
 
-Your app does not open arbitrary MindooDB databases directly. Haven decides which logical databases are visible and what permissions each one has.
+**Security model:** Every app runs on a **separate origin** inside a sandboxed iframe. It cannot access Haven's storage, cookies, or other apps. Haven decides exactly which databases and permissions each app receives -- your app only sees data that was explicitly shared with it.
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────┐
+│  Haven (browser tab)                                    │
+│                                                         │
+│  ┌──────────────┐   ┌─────────────┐   ┌─────────────┐  │
+│  │  Haven UI    │──▶│ Bridge Host │──▶│  MindooDB    │  │
+│  │  (theme,     │   │  (RPC +     │   │  (encrypted  │  │
+│  │   viewport)  │   │   streams)  │   │   databases) │  │
+│  └──────────────┘   └──────┬──────┘   └─────────────┘  │
+│                            │                            │
+│              postMessage + MessagePort                  │
+│                            │                            │
+│  ┌─────────────────────────┼─────────────────────────┐  │
+│  │  Your App (sandboxed iframe / window)             │  │
+│  │                         │                         │  │
+│  │              ┌──────────▼──────────┐              │  │
+│  │              │  mindoodb-app-sdk   │              │  │
+│  │              └─────────────────────┘              │  │
+│  └───────────────────────────────────────────────────┘  │
+└─────────────────────────────────────────────────────────┘
+```
+
+The bridge carries RPC calls (documents, views, database info), binary attachment streams, and push events (theme changes, viewport resizes) over a single `MessagePort`.
 
 ## Install
 
@@ -31,310 +52,430 @@ Your app does not open arbitrary MindooDB databases directly. Haven decides whic
 npm install mindoodb-app-sdk
 ```
 
-For local development against an unpublished workspace copy, prefer `npm link`:
+## Get started in 5 minutes
 
-```bash
-# In the SDK package
-npm link
+The fastest way to start building is to clone the **example app**, run it locally, and connect it to Haven:
 
-# In your app project
-npm link mindoodb-app-sdk
+```bash
+git clone https://github.com/klehmann/mindoodb-app-example.git
+cd mindoodb-app-example
+npm install
+npm run dev:local
 ```
 
-When you want to switch back to the published npm version, run `npm unlink mindoodb-app-sdk` in the app project and then `npm install`.
+This spins up a local Vite dev server on `http://localhost:4200` with hot module reload.
 
-## Getting started
+Then, in Haven:
 
-### 1. Register an app in Haven
+1. Go to **Application settings** and register a new app pointing to `http://localhost:4200`.
+2. Map one or more databases (and optionally views) to the app.
+3. Launch the app -- it connects via the SDK bridge and displays live data.
+
+From here, **fork or duplicate** the example project to start building your own app while exploring the platform in a running Haven client.
+
+The example app is also deployed at **https://app-example.mindoodb.com** so you can register it in Haven without running anything locally.
+
+> See the [mindoodb-app-example README](https://github.com/klehmann/mindoodb-app-example) for the full project walkthrough.
+
+## Quick start (from scratch)
+
+If you prefer starting from an empty project:
+
+```ts
+import { createMindooDBAppBridge } from "mindoodb-app-sdk";
 
-Create an app registration in Haven that points to either:
+// 1. Create the bridge and connect to Haven
+const bridge = createMindooDBAppBridge();
+const session = await bridge.connect();
 
-- an external dev server or deployment URL, such as `http://localhost:4173`
-- a hosted app bundle imported into Haven
+// 2. Read the launch context
+const ctx = await session.getLaunchContext();
+console.log("Runtime:", ctx.runtime);   // "iframe" | "window"
+console.log("Theme:", ctx.theme.mode);  // "light" | "dark"
+console.log("Databases:", ctx.databases.map((db) => db.title));
 
-Pick one runtime:
+// 3. Subscribe to live host events
+session.onThemeChange((theme) => {
+  document.documentElement.dataset.theme = theme.mode;
+});
 
-- `iframe`: the app is embedded in Haven
-- `window`: the app opens in its own tab or popup
+session.onViewportChange((viewport) => {
+  console.log("Iframe resized:", viewport.width, viewport.height);
+});
 
-### 2. Let Haven launch the app
+// 4. Open a database and list documents
+const db = await session.openDatabase(ctx.databases[0]!.id);
+const result = await db.documents.list({ limit: 25 });
+console.log("Documents:", result.items);
+```
 
-When Haven launches an app, it injects bridge launch parameters into the app URL:
+When Haven launches your app it injects a `mindoodbAppLaunchId` query parameter into the URL. `connect()` reads it automatically -- no manual wiring needed.
 
-- `mindoodbAppLaunchId`
-- `mindoodbAppId`
-- `mindoodbAppRuntime`
+## Core concepts
 
-`createMindooDBAppBridge().connect()` reads `mindoodbAppLaunchId` from the current browser URL automatically.
+### Launch context
 
-### 3. Connect to the bridge
+After connecting, call `session.getLaunchContext()` to receive the initial host snapshot:
 
 ```ts
-import { createMindooDBAppBridge } from "mindoodb-app-sdk";
+interface MindooDBAppLaunchContext {
+  appId: string;
+  appInstanceId: string;
+  appVersion?: string;
+  launchId: string;
+  runtime: "iframe" | "window";
+  theme: { mode: "light" | "dark"; preset: string };
+  viewport: { width: number; height: number } | null;
+  tenantId?: string;
+  preferredDatabaseId?: string;
+  user: { id: string; username: string };
+  launchParameters: Record<string, string>;
+  databases: MindooDBAppDatabaseInfo[];
+  views: MindooDBAppResolvedViewDefinition[];
+}
+```
 
-const bridge = createMindooDBAppBridge();
-const session = await bridge.connect();
-const launchContext = await session.getLaunchContext();
+`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()`.
+
+### 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.
+
+| Capability | Allows |
+|---|---|
+| `read` | List and read documents |
+| `create` | Create new documents |
+| `update` | Update existing documents |
+| `delete` | Delete documents |
+| `history` | Access document revision history and historical snapshots |
+| `attachments` | List, upload, download, remove, and preview file attachments |
+| `views` | Create app-defined virtual views for this database |
+
+```ts
+const db = ctx.databases[0]!;
+
+if (db.capabilities.includes("history")) {
+  // show history UI
+}
+if (!db.capabilities.includes("delete")) {
+  // hide delete button
+}
 ```
 
-If you need to override the launch id or target origin manually:
+When the database is readable, `documents.list()` can also expose deleted document IDs by setting `status: "all"` or `status: "deleted"`. This is useful for app-side indexes and sync checkpoints.
+
+### Theme and viewport events
+
+Haven pushes two types of live events to your app:
+
+**Theme changes** occur when the user switches between light/dark mode or changes the UI theme preset:
 
 ```ts
-const session = await createMindooDBAppBridge().connect({
-  launchId: "custom-launch-id",
-  targetOrigin: "https://haven.example.com",
+// Initial snapshot from launch context
+const { mode, preset } = ctx.theme; // e.g. { mode: "dark", preset: "aura" }
+
+// Live updates
+const stopTheme = session.onThemeChange((theme) => {
+  document.documentElement.dataset.theme = theme.mode;
+  document.documentElement.dataset.themePreset = theme.preset;
 });
 ```
 
-### 4. Read the launch context
-
-The launch context is your initial snapshot of the Haven host state:
+**Viewport changes** fire when the iframe is resized inside Haven (e.g. the user resizes a chicklet on the workspace grid):
 
 ```ts
-const launchContext = await session.getLaunchContext();
-
-console.log(launchContext.runtime);      // "iframe" | "window"
-console.log(launchContext.theme.mode);   // "light" | "dark"
-console.log(launchContext.viewport);     // { width, height } | null
-console.log(launchContext.user.username);
-console.log(launchContext.launchParameters);
-console.log(launchContext.databases);
-console.log(launchContext.views);
+// Initial snapshot (null in window mode)
+const viewport = ctx.viewport; // { width: 800, height: 600 }
+
+// Live updates
+const stopViewport = session.onViewportChange((viewport) => {
+  console.log(viewport.width, viewport.height);
+});
 ```
 
-`launchContext.viewport` is especially useful for responsive layouts inside embedded iframes. It is the initial viewport snapshot; later changes arrive through `onViewportChange()`.
+Both subscription functions return an unsubscribe callback. Call it during teardown.
 
-### 5. Subscribe to host-driven events
+### Documents
+
+Open a database, then use the `documents` API for CRUD, history, and changefeed-backed document listing:
 
 ```ts
-const stopThemeSync = session.onThemeChange((theme) => {
-  console.log("Theme changed:", theme.mode, theme.preset);
+const db = await session.openDatabase(databaseId);
+
+// List the first page of existing documents
+const result = await db.documents.list({ limit: 50, fields: ["title"] });
+console.log(result.items);
+console.log(result.nextCursor); // opaque changefeed checkpoint or null
+
+// Continue from the last checkpoint
+const nextPage = result.nextCursor
+  ? await db.documents.list({ cursor: result.nextCursor, limit: 50, fields: ["title"] })
+  : null;
+
+// Fast metadata-only listing (IDs + deletion state only)
+const ids = await db.documents.list({
+  limit: 200,
+  status: "all",
+  metadataOnly: true,
 });
 
-const stopViewportSync = session.onViewportChange((viewport) => {
-  console.log("Viewport changed:", viewport.width, viewport.height);
+// Skip N matching entries before returning results
+const window = await db.documents.list({
+  cursor: result.nextCursor,
+  skip: 100,
+  limit: 25,
+  status: "existing",
 });
 
-// Later, during teardown:
-stopThemeSync();
-stopViewportSync();
+// Read
+const doc = await db.documents.get(docId);
+
+// Create (optionally with a named document key)
+const created = await db.documents.create({
+  data: { title: "Meeting notes", content: "..." },
+  decryptionKeyId: "team-key",  // omit to use "default"
+});
+
+// Update
+const updated = await db.documents.update(docId, {
+  data: { title: "Updated title" },
+});
+
+// Delete
+await db.documents.delete(docId);
 ```
 
-The intended pattern is:
+`documents.list()` is backed by Haven's internal changefeed, not by a positional offset. The query object supports:
+
+| Field | Meaning |
+|---|---|
+| `cursor?: string \| null` | Opaque changefeed checkpoint previously returned by `nextCursor` |
+| `limit?: number` | Maximum number of matching entries to return (default `50`) |
+| `skip?: number` | Skip matching entries after the cursor without loading full document bodies |
+| `status?: "all" \| "existing" \| "deleted"` | Filter by deletion state (default `"existing"`) |
+| `metadataOnly?: boolean` | Return only `{ id, isDeleted }` for speed |
+| `fields?: string[]` | Project specific JSON fields when `metadataOnly` is `false` |
+| `filter?: Record<string, unknown>` | Simple equality filter applied to document data when `metadataOnly` is `false` |
+
+`nextCursor` is the latest checkpoint reached by the page. Persist it after each successful call when you are building your own index or sync loop. If there were no changes after the supplied cursor, `nextCursor` is `null`.
 
-- use `getLaunchContext()` for the initial host snapshot
-- use `onThemeChange()` and `onViewportChange()` for live updates
+When Haven can resolve the signing identity from the tenant directory, list items may also include `identityLabel` and `publicKeyFingerprint` for the latest visible change. Apps can use this to show who last touched a document without loading the full revision history first.
 
-### 6. Discover the databases Haven exposed
+### Document history
+
+When the `history` capability is granted, you can walk the full revision timeline of any document:
 
 ```ts
-const databases = launchContext.databases;
+// List all revisions
+const history = await db.documents.listHistory(docId);
+// Each entry: { timestamp, publicKey, identityLabel?, isDeleted, isCurrent, summary? }
 
-for (const database of databases) {
-  console.log(database.id, database.title, database.capabilities);
-}
+// Load the document state at a specific point in time
+const snapshot = await db.documents.getAtTimestamp(docId, history[0]!.timestamp);
+// { id, timestamp, state: "exists" | "deleted" | "missing", data }
 ```
 
-Prefer `launchContext.databases` for the initial snapshot so your app discovers databases and views from the same source. `session.listDatabases()` is still available when you want to refresh database metadata later.
+### Incremental sync
+
+The changefeed-backed `documents.list()` API is also the right primitive for app-side indexes, search, and other derived caches.
 
-### 7. Open a database and work with documents
+**Initial scan from the beginning:**
 
 ```ts
-const databases = launchContext.databases;
-const db = await session.openDatabase(databases[0]!.id);
+let cursor: string | null = null;
+
+while (true) {
+  const page = await db.documents.list({
+    cursor,
+    limit: 500,
+    status: "all",
+    metadataOnly: true,
+  });
+
+  for (const item of page.items) {
+    if (!item.isDeleted) {
+      const doc = await db.documents.get(item.id);
+      // add or rebuild the derived index entry
+    }
+  }
+
+  if (!page.nextCursor) {
+    break;
+  }
+  cursor = page.nextCursor;
+}
+
+// Save `cursor` after the last non-empty page.
+```
 
-const list = await db.documents.list({ limit: 25 });
-const firstDoc = list.items[0] ? await db.documents.get(list.items[0].id) : null;
+**Resume later from the saved checkpoint:**
 
-await db.documents.create({
-  data: {
-    employee: "Jane Doe",
-    workDate: "2026-04-04",
-    hours: 8,
-  },
-  decryptionKeyId: "payroll",
+```ts
+const page = await db.documents.list({
+  cursor: savedCursor,
+  limit: 500,
+  status: "all",
+  metadataOnly: true,
 });
+
+let updated = 0;
+let deleted = 0;
+
+for (const item of page.items) {
+  if (item.isDeleted) {
+    deleted += 1;
+    // remove from index
+  } else {
+    updated += 1;
+    const doc = await db.documents.get(item.id);
+    // update index
+  }
+}
+
+console.log(`Updated index with ${updated} changes and ${deleted} deletions.`);
 ```
 
-Omit `decryptionKeyId` to keep using the tenant's `"default"` document key.
+Use `status: "all"` for external indexes so deletions are visible and can be removed from your derived state.
 
-Document operations:
+### Attachments
 
-- `documents.list()`
-- `documents.get()`
-- `documents.create()`
-- `documents.update()`
-- `documents.delete()`
-- `documents.listHistory()`
-- `documents.getAtTimestamp()`
+When the `attachments` capability is granted, each document can carry file attachments. The SDK uses **chunked binary streams** over the bridge for uploads and downloads:
 
-When creating a document, apps can optionally pass `decryptionKeyId` to use a named document key instead of `"default"`.
+```ts
+// List attachments for a document
+const files = await db.attachments.list(docId);
+// Each: { attachmentId, fileName, mimeType, size }
+
+// Download (pull-based read stream)
+const reader = await db.attachments.openReadStream(docId, "report.pdf");
+const chunks: Uint8Array[] = [];
+let chunk = await reader.read();
+while (chunk !== null) {
+  chunks.push(chunk);
+  chunk = await reader.read();
+}
+await reader.close();
 
-Attachment operations:
+// Upload (push-based write stream)
+const writer = await db.attachments.openWriteStream(docId, "photo.jpg", "image/jpeg");
+await writer.write(fileBytes);
+await writer.close();
 
-- `attachments.list(docId)`
-- `attachments.remove(docId, attachmentName)`
-- `attachments.openReadStream(docId, attachmentName)`
-- `attachments.openWriteStream(docId, attachmentName, contentType?)`
+// Remove
+await db.attachments.remove(docId, "old-file.txt");
+```
 
-## Quick start example
+### Attachment previews
 
-```ts
-import { createMindooDBAppBridge, createViewLanguage } from "mindoodb-app-sdk";
+Haven includes a **built-in file viewer** that your app can open for common attachment formats. This is one of the most powerful SDK features -- it works with both online and offline data, and media formats support streaming playback with skip/seek.
 
-const bridge = createMindooDBAppBridge();
-const session = await bridge.connect();
+**Supported preview formats:**
 
-const launchContext = await session.getLaunchContext();
-console.log("Connected runtime:", launchContext.runtime);
-console.log("Initial viewport:", launchContext.viewport);
+| Mode | Formats |
+|---|---|
+| `image` | All common image formats (JPEG, PNG, GIF, WebP, SVG, ...) |
+| `pdf` | PDF documents |
+| `text` | Plain text, Markdown, CSV, JSON, XML, YAML, SVG, log files |
+| `docx` | Microsoft Word (.docx) |
+| `pptx` | Microsoft PowerPoint (.pptx) |
+| `spreadsheet` | Microsoft Excel (.xls, .xlsx, .xlsm, .xlsb) |
+| `video` | Video files with embedded player (streaming + seek support) |
+| `audio` | Audio files with embedded player (streaming + seek support) |
 
-session.onThemeChange((theme) => {
-  document.documentElement.dataset.theme = theme.mode;
-});
+**Open the Haven preview dialog:**
 
-session.onViewportChange((viewport) => {
-  console.log("Resize:", viewport.width, viewport.height);
+```ts
+await db.attachments.openPreview(docId, "presentation.pptx");
+```
+
+You can also preview attachments from a **historical document snapshot**:
+
+```ts
+await db.attachments.openPreview(docId, "report.pdf", {
+  timestamp: historyEntry.timestamp,
 });
+```
 
-const databases = launchContext.databases;
-const db = await session.openDatabase(databases[0]!.id);
+**Check preview support locally** before showing a preview button:
 
-const list = await db.documents.list({ limit: 25 });
-const firstDoc = list.items[0] ? await db.documents.get(list.items[0].id) : null;
+```ts
+import { canPreviewAttachment } from "mindoodb-app-sdk";
 
-const v = createViewLanguage<{ employee: string; hours: number; rate?: number }>();
-const view = await session.createView({
-  databaseId: databases[0]!.id,
-  definition: {
-  title: "Hours by employee",
-  defaultExpand: "collapsed",
-  filter: {
-    mode: "expression",
-    expression: v.gt(v.toNumber(v.field("hours")), v.number(0)),
-  },
-  columns: [
-    {
-      name: "employee",
-      title: "Employee",
-      role: "category",
-      expression: v.field("employee"),
-      sorting: "ascending",
-    },
-    {
-      name: "amount",
-      title: "Amount",
-      role: "display",
-      expression: v.let(
-        {
-          hours: v.toNumber(v.field("hours")),
-          rate: v.coalesce(v.toNumber(v.field("rate")), v.number(1)),
-        },
-        ({ hours, rate }) => v.mul(v.coalesce(hours, v.number(0)), v.coalesce(rate, v.number(0))),
-      ),
-    },
-  ],
-  },
-});
+const mode = canPreviewAttachment("slides.pptx", "application/octet-stream");
+// Returns "pptx" -- Haven can preview this file
 
-const page = await view.page({ pageSize: 100 });
-console.log(page.rows);
-await view.dispose();
+const unsupported = canPreviewAttachment("data.bin", "application/octet-stream");
+// Returns null -- no built-in preview available
 ```
 
-## Views and expression language
+### 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 are app-defined and session-scoped. Create a definition with `session.createView()`, open Haven-configured mappings with `session.openView()`, page through rows, inspect categories, manage expansion state, then dispose the handle when done.
+**App-defined views** -- create a view definition programmatically:
 
 ```ts
 import { createViewLanguage } from "mindoodb-app-sdk";
 
-const v = createViewLanguage<{
-  employee: string;
-  workDate: string;
-  hours: number;
-  rate?: number;
-  note?: string;
-}>();
+const v = createViewLanguage<{ employee: string; hours: number }>();
 
 const view = await session.createView({
   databaseId: "main",
   definition: {
-  title: "By employee",
-  defaultExpand: "collapsed",
-  filter: {
-    mode: "expression",
-    expression: v.gt(v.toNumber(v.field("hours")), v.number(0)),
-  },
-  columns: [
-    {
-      name: "employee",
-      title: "Employee",
-      role: "category",
-      expression: v.field("employee"),
-      sorting: "ascending",
-    },
-    {
-      name: "amount",
-      title: "Amount",
-      role: "display",
-      expression: v.let(
-        {
-          hours: v.toNumber(v.field("hours")),
-          rate: v.coalesce(v.toNumber(v.field("rate")), v.number(1)),
-        },
-        ({ hours, rate }) => v.mul(v.coalesce(hours, v.number(0)), v.coalesce(rate, v.number(0))),
-      ),
-      sorting: "descending",
-    },
-  ],
+    title: "Hours by employee",
+    defaultExpand: "collapsed",
+    columns: [
+      {
+        name: "employee",
+        title: "Employee",
+        role: "category",
+        expression: v.field("employee"),
+        sorting: "ascending",
+      },
+      {
+        name: "hours",
+        title: "Hours",
+        role: "display",
+        expression: v.toNumber(v.field("hours")),
+      },
+    ],
   },
 });
 
 const page = await view.page({ pageSize: 100 });
-const firstCategory = page.rows.find((row) => row.type === "category");
+console.log(page.rows);
+await view.dispose();
+```
 
-if (firstCategory) {
-  await view.expand(firstCategory.key);
-  const categoryRows = await view.pageCategory(firstCategory.key, { pageSize: 25 });
-  const categoryDocumentIds = await view.listCategoryDocumentIds(firstCategory.key);
-  const sameCategory = await view.getCategory({ path: firstCategory.categoryPath });
-}
+**Haven-configured views** -- open views that the Haven administrator 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 });
+
+// Expand/collapse categories
+await view.expandAll();
+await view.collapse(someCategoryKey);
 
 await view.dispose();
 ```
 
-Available view-handle operations:
-
-- `view.getDefinition()`
-- `view.refresh()`
-- `view.page({ pageSize, position, expansion, rootRowKey })`
-- `view.getExpansionState()`
-- `view.setExpansionState(state)`
-- `view.expand(rowKey)`
-- `view.collapse(rowKey)`
-- `view.expandAll()`
-- `view.collapseAll()`
-- `view.getRow(rowKey)`
-- `view.getCategory({ path })`
-- `view.pageCategory(categoryKey, { pageSize, position })`
-- `view.listCategoryDocumentIds(categoryKey)`
-- `view.dispose()`
-
-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.
-
-Helpers currently include:
-
-- field/value access: `field()`, `value()`, `origin()`
-- literals and conversion: `literal()`, `string()`, `number()`, `boolean()`, `toNumber()`, `toString()`, `toBoolean()`
-- math and comparisons: `add()`, `sub()`, `mul()`, `div()`, `mod()`, `eq()`, `neq()`, `gt()`, `gte()`, `lt()`, `lte()`
-- boolean logic: `and()`, `or()`, `not()`
-- string helpers: `concat()`, `lower()`, `upper()`, `trim()`, `contains()`, `startsWith()`, `endsWith()`
-- null/existence helpers: `coalesce()`, `exists()`, `notExists()`
-- date/path helpers: `datePart()`, `pathJoin()`
-- control flow: `ifElse()`, `let()`
-
-The dedicated language guide lives in the `mindoodb-view-language` package. The SDK re-exports `createViewLanguage()` for convenience.
+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.
+
+Available expression helpers:
+
+- **Field access:** `field()`, `value()`, `origin()`
+- **Literals and conversion:** `literal()`, `string()`, `number()`, `boolean()`, `toNumber()`, `toString()`, `toBoolean()`
+- **Math and comparisons:** `add()`, `sub()`, `mul()`, `div()`, `mod()`, `eq()`, `neq()`, `gt()`, `gte()`, `lt()`, `lte()`
+- **Boolean logic:** `and()`, `or()`, `not()`
+- **String helpers:** `concat()`, `lower()`, `upper()`, `trim()`, `contains()`, `startsWith()`, `endsWith()`
+- **Null/existence:** `coalesce()`, `exists()`, `notExists()`
+- **Date/path:** `datePart()`, `pathJoin()`
+- **Control flow:** `ifElse()`, `let()`
+
+The full language guide lives in the `mindoodb-view-language` package. The SDK re-exports `createViewLanguage()` for convenience.
 
 ## Testing without Haven
 
@@ -342,51 +483,142 @@ You do **not** need a full Haven environment to test apps that use `mindoodb-app
 
 The SDK ships a dedicated `mindoodb-app-sdk/testing` entrypoint with two levels of test helpers:
 
-- Level 1: simple app-test helpers that return a fake `MindooDBAppSession` and bridge object for unit, composable, store, and component tests
-- Level 2: a fake bridge host harness for tests that should exercise the real `createMindooDBAppBridge()` handshake over `postMessage` and `MessageChannel`
+- **Level 1 -- app tests:** Returns a fake `MindooDBAppSession` and bridge for unit, composable, store, and component tests. No `postMessage` or `MessageChannel` involved.
+- **Level 2 -- bridge protocol tests:** A fake host harness that exercises the real `createMindooDBAppBridge()` handshake over `postMessage` and `MessageChannel`. Useful for integration-style tests.
 
-Use Level 1 when you only need app behavior. Use Level 2 when you want to validate your bridge integration itself.
+Use Level 1 when you are testing app behavior. Use Level 2 when you want to validate the bridge transport itself.
 
 See [`TESTING.md`](./TESTING.md) for setup instructions and Vitest examples.
 
-## Local development workflow
+## Deployment
 
-The recommended local setup is:
+MindooDB Apps are standard web applications -- deploy them anywhere you can serve static files.
 
-1. Run Haven locally.
-2. Run your app on its own dev server, for example Vite on `http://localhost:4173`.
-3. Register that URL in Haven as an external app.
-4. Launch the app from Haven so it receives a real `mindoodbAppLaunchId`.
+**Cloudflare Pages / Workers** is one of the easiest options. The [example app](https://github.com/klehmann/mindoodb-app-example) is deployed this way at https://app-example.mindoodb.com using a simple `wrangler.jsonc` configuration:
 
-This gives you:
+```bash
+npm run build
+wrangler deploy
+```
+
+Other static hosting options work just as well: Netlify, Vercel, any web server serving your `dist/` folder.
 
-- normal browser dev-server behavior
-- hot module reload
-- the full Haven host bridge
-- realistic iframe sizing and theme changes during development
+**Haven-hosted bundles** are an alternative: import your built app directly into Haven, where it is served by a service worker on an opaque origin. Haven-hosted apps load without a network connection and receive a stricter sandbox.
 
-The sample `mindoodb-timerecords` app in this workspace is a good reference for this setup.
+## Local development workflow
+
+For interactive development with the full Haven host bridge:
 
-This local development workflow is separate from the automated testing workflow above. Running Haven locally is useful for interactive development, but it is not required for Level 1 or Level 2 automated tests.
+1. Run Haven locally.
+2. Run your app on its own dev server (e.g. `npm run dev` with Vite).
+3. Register the dev server URL in Haven's Application settings.
+4. Map databases and optionally views to the app.
+5. Launch from Haven -- you get hot reload, real bridge communication, and live theme/viewport events.
+
+This is separate from the automated testing workflow above. Running Haven is useful for interactive development but not required for Level 1 or Level 2 tests.
+
+## API reference
+
+### MindooDBAppBridge
+
+| Method | Returns |
+|---|---|
+| `connect(options?)` | `Promise<MindooDBAppSession>` |
+
+Connect options: `launchId?`, `targetOrigin?`, `connectTimeoutMs?`.
+
+### MindooDBAppSession
+
+| Method | Returns |
+|---|---|
+| `getLaunchContext()` | `Promise<MindooDBAppLaunchContext>` |
+| `listDatabases()` | `Promise<MindooDBAppDatabaseInfo[]>` |
+| `openDatabase(databaseId)` | `Promise<MindooDBAppDatabase>` |
+| `createView(input)` | `Promise<MindooDBAppViewHandle>` |
+| `openView(viewId)` | `Promise<MindooDBAppViewHandle>` |
+| `onThemeChange(listener)` | `() => void` (unsubscribe) |
+| `onViewportChange(listener)` | `() => void` (unsubscribe) |
+| `disconnect()` | `Promise<void>` |
+
+### MindooDBAppDatabase
+
+| Property / Method | Returns |
+|---|---|
+| `info()` | `Promise<MindooDBAppDatabaseInfo>` |
+| `documents` | `MindooDBAppDocumentApi` |
+| `attachments` | `MindooDBAppAttachmentApi` |
+
+### MindooDBAppDocumentApi
+
+| Method | Returns |
+|---|---|
+| `list(query?)` | `Promise<MindooDBAppDocumentListResult>` |
+| `get(docId)` | `Promise<MindooDBAppDocument \| null>` |
+| `create(input)` | `Promise<MindooDBAppDocument>` |
+| `update(docId, patch)` | `Promise<MindooDBAppDocument>` |
+| `delete(docId)` | `Promise<{ ok: true }>` |
+| `listHistory(docId)` | `Promise<MindooDBAppDocumentHistoryEntry[]>` |
+| `getAtTimestamp(docId, timestamp)` | `Promise<MindooDBAppHistoricalDocument>` |
+
+`list(query?)` accepts the changefeed query options documented above. The `cursor` value is an opaque checkpoint string managed by Haven and should be stored and passed back unchanged.
+
+### MindooDBAppAttachmentApi
+
+| Method | Returns |
+|---|---|
+| `list(docId)` | `Promise<MindooDBAppAttachmentInfo[]>` |
+| `remove(docId, attachmentName)` | `Promise<{ ok: true }>` |
+| `openReadStream(docId, attachmentName)` | `Promise<MindooDBAppReadableAttachmentStream>` |
+| `openWriteStream(docId, attachmentName, contentType?)` | `Promise<MindooDBAppWritableAttachmentStream>` |
+| `openPreview(docId, attachmentName, options?)` | `Promise<{ ok: true }>` |
+
+### MindooDBAppViewHandle
+
+| 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[]>` |
+| `dispose()` | `Promise<void>` |
+
+### Exported functions
+
+| Function | Description |
+|---|---|
+| `createMindooDBAppBridge()` | Create the bridge object used to connect to Haven |
+| `canPreviewAttachment(fileName, mimeType)` | Check if Haven can preview a file (returns mode or `null`) |
+| `createViewLanguage<T>()` | Create a typed expression builder for view definitions |
+| `abbreviateCanonicalName(value)` | Convert a canonical Notes-style name like `cn=Jane/ou=Dev/o=Mindoo` to `Jane/Dev/Mindoo` |
+| `expandAbbreviatedName(value)` | Convert an abbreviated Notes-style name like `Jane/Dev/Mindoo` to `cn=Jane/ou=Dev/o=Mindoo` |
 
 ## Permissions and mappings
 
-Apps never choose arbitrary database targets themselves. Haven decides:
+Apps never choose arbitrary database targets. Haven decides:
 
-- which logical database handles are visible to the app
-- whether each handle can read, create, update, delete, inspect history, access attachments, or create views
-- how each logical handle maps to a concrete tenant/database target
+- which databases are visible to the app
+- what capabilities each database has (`read`, `create`, `update`, `delete`, `history`, `attachments`, `views`)
+- how each logical database maps to a concrete tenant and database target
 
-Your app should always react to what Haven grants instead of assuming a fixed environment.
+Your app should always adapt to what Haven grants instead of assuming a fixed environment.
 
 ## When not to use this SDK
 
-`mindoodb-app-sdk` is for MindooDB apps that intentionally integrate with the Haven host bridge.
+`mindoodb-app-sdk` is for web apps that integrate with the Haven host bridge.
 
-If you are embedding generic third-party web content that does not speak the MindooDB bridge protocol, use a general iframe integration such as `iframe-resizer` instead of this SDK.
+If you are embedding generic third-party web content that does not speak the MindooDB bridge protocol, use a general iframe integration instead of this SDK.
 
 ## Current limitations
 
-- the bridge currently expects a browser environment with `window`, `postMessage`, and `MessagePort`
-- viewport updates are host-driven and only available when the app is actually launched by Haven
-- your app is still responsible for its own UI layout and responsive behavior after receiving host theme and viewport updates
+- The bridge expects a browser environment with `window`, `postMessage`, and `MessagePort`.
+- Viewport updates are host-driven and only available when the app is launched by Haven.
+- Your app is responsible for its own UI layout and responsive behavior after receiving host theme and viewport updates.

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { M as MindooDBAppAttachmentPreviewMode, a as MindooDBAppBridge } from './types-Cvlkh3vJ.js';
-export { b as MindooDBAppAttachmentApi, c as MindooDBAppAttachmentChunk, d as MindooDBAppAttachmentInfo, e as MindooDBAppAttachmentPreviewOptions, f as MindooDBAppBridgeConnectMessage, g as MindooDBAppBridgeConnectOptions, h as MindooDBAppBridgeConnectedMessage, i as MindooDBAppBridgeErrorPayload, j as MindooDBAppBridgePortMessage, k as MindooDBAppBridgeRpcError, l as MindooDBAppBridgeRpcMessage, m as MindooDBAppBridgeRpcRequest, n as MindooDBAppBridgeRpcSuccess, o as MindooDBAppBridgeStreamAbortRequest, p as MindooDBAppBridgeStreamAck, q as MindooDBAppBridgeStreamCloseRequest, r as MindooDBAppBridgeStreamError, s as MindooDBAppBridgeStreamMessage, t as MindooDBAppBridgeStreamOpenResult, u as MindooDBAppBridgeStreamReadRequest, v as MindooDBAppBridgeStreamWriteRequest, w as MindooDBAppBridgeThemeChangedMessage, x as MindooDBAppBridgeViewportChangedMessage, y as MindooDBAppCapability, z as MindooDBAppConfiguredViewCategorizationStyle, A as MindooDBAppConfiguredViewColumn, B as MindooDBAppConfiguredViewColumnRole, C as MindooDBAppConfiguredViewExpressionMode, D as MindooDBAppConfiguredViewFieldExpression, E as MindooDBAppConfiguredViewFilterDefinition, F as MindooDBAppConfiguredViewFilterMode, G as MindooDBAppConfiguredViewFilterRule, H as MindooDBAppConfiguredViewFormulaExpression, I as MindooDBAppConfiguredViewFormulaFilterDefinition, J as MindooDBAppConfiguredViewPreviewMode, K as MindooDBAppConfiguredViewRuleFilterDefinition, L as MindooDBAppConfiguredViewRuleMatchMode, N as MindooDBAppConfiguredViewRuleOperator, O as MindooDBAppConfiguredViewValueExpression, P as MindooDBAppCreateDocumentInput, Q as MindooDBAppCreateViewInput, R as MindooDBAppDatabase, S as MindooDBAppDatabaseInfo, T as MindooDBAppDocument, U as MindooDBAppDocumentApi, V as MindooDBAppDocumentHistoryEntry, W as MindooDBAppDocumentListQuery, X as MindooDBAppDocumentListResult, Y as MindooDBAppDocumentSummary, Z as MindooDBAppHistoricalDocument, _ as MindooDBAppHistoryQuery, $ as MindooDBAppHostTheme, a0 as MindooDBAppLaunchContext, a1 as MindooDBAppReadableAttachmentStream, a2 as MindooDBAppResolvedViewDefinition, a3 as MindooDBAppResolvedViewSource, a4 as MindooDBAppRuntime, a5 as MindooDBAppSession, a6 as MindooDBAppThemeMode, a7 as MindooDBAppUpdateDocumentInput, a8 as MindooDBAppViewHandle, a9 as MindooDBAppViewport, aa as MindooDBAppWritableAttachmentStream } from './types-Cvlkh3vJ.js';
+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';
 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';
 
 /**
@@ -10,6 +10,24 @@ export { MindooDBAppBooleanExpression, MindooDBAppExpression, MindooDBAppFilterD
  */
 declare function canPreviewAttachment(fileName: string, mimeType: string): MindooDBAppAttachmentPreviewMode | null;
 
+/**
+ * Convert a canonical Notes name like `cn=Jane/ou=Dev/o=Mindoo`
+ * into the abbreviated form `Jane/Dev/Mindoo`.
+ *
+ * If the input is not a slash-separated canonical name, the trimmed
+ * original value is returned unchanged.
+ */
+declare function abbreviateCanonicalName(value: string): string;
+/**
+ * Convert an abbreviated Notes name like `Jane/Dev/Mindoo`
+ * into canonical form `cn=Jane/ou=Dev/o=Mindoo`.
+ *
+ * The first segment becomes `cn=`, the last becomes `o=`, and any
+ * middle segments become `ou=` parts in order. Values with fewer than
+ * two segments are returned unchanged.
+ */
+declare function expandAbbreviatedName(value: string): string;
+
 /**
  * Creates the browser-side bridge entry point used by MindooDB apps.
  *
@@ -19,4 +37,4 @@ declare function canPreviewAttachment(fileName: string, mimeType: string): Mindo
  */
 declare function createMindooDBAppBridge(): MindooDBAppBridge;
 
-export { MindooDBAppAttachmentPreviewMode, MindooDBAppBridge, canPreviewAttachment, createMindooDBAppBridge };
+export { MindooDBAppAttachmentPreviewMode, MindooDBAppBridge, abbreviateCanonicalName, canPreviewAttachment, createMindooDBAppBridge, expandAbbreviatedName };

package/dist/index.js

@@ -29,6 +29,48 @@ function canPreviewAttachment(fileName, mimeType) {
   return null;
 }
 
+// src/canonicalNames.ts
+var CANONICAL_PART_PATTERN = /^\s*([^=]+)\s*=\s*(.*?)\s*$/;
+function splitNameParts(value) {
+  return value.split("/").map((part) => part.trim()).filter(Boolean);
+}
+function abbreviateCanonicalName(value) {
+  const parts = splitNameParts(value);
+  if (!parts.length) {
+    return value.trim();
+  }
+  const abbreviatedParts = [];
+  for (const part of parts) {
+    const match = CANONICAL_PART_PATTERN.exec(part);
+    if (!match) {
+      return value.trim();
+    }
+    const partValue = match[2].trim();
+    if (!partValue) {
+      return value.trim();
+    }
+    abbreviatedParts.push(partValue);
+  }
+  return abbreviatedParts.join("/");
+}
+function expandAbbreviatedName(value) {
+  const parts = splitNameParts(value);
+  if (parts.length < 2) {
+    return value.trim();
+  }
+  const [commonName, ...rest] = parts;
+  const organization = rest.at(-1);
+  if (!commonName || !organization) {
+    return value.trim();
+  }
+  const organizationUnits = rest.slice(0, -1);
+  return [
+    `cn=${commonName}`,
+    ...organizationUnits.map((part) => `ou=${part}`),
+    `o=${organization}`
+  ].join("/");
+}
+
 // src/client/portRpcClient.ts
 var PROTOCOL = "mindoodb-app-bridge";
 function normalizeRpcValue(value, seen = /* @__PURE__ */ new WeakMap()) {
@@ -565,6 +607,12 @@ var MindooDBAppDatabaseImpl = class {
         });
         return new MindooDBAppWritableAttachmentStreamImpl(this.rpc, result.streamId);
       },
+      preparePreviewSession: async (docId, attachmentName, options) => await this.rpc.call("attachments.preparePreviewSession", {
+        databaseId: this.databaseId,
+        docId,
+        attachmentName,
+        timestamp: options?.timestamp
+      }),
       openPreview: async (docId, attachmentName, options) => await this.rpc.call("attachments.openPreview", {
         databaseId: this.databaseId,
         docId,
@@ -648,7 +696,9 @@ import {
   mindooDBViewLanguageHelpersByName
 } from "mindoodb-view-language";
 export {
+  abbreviateCanonicalName,
   canPreviewAttachment,
   createMindooDBAppBridge,
-  createViewLanguage
+  createViewLanguage,
+  expandAbbreviatedName
 };

package/dist/testing/index.d.ts

@@ -1,4 +1,4 @@
-import { a0 as MindooDBAppLaunchContext, S as MindooDBAppDatabaseInfo, U as MindooDBAppDocumentApi, a8 as MindooDBAppViewHandle, b as MindooDBAppAttachmentApi, a as MindooDBAppBridge, a5 as MindooDBAppSession, m as MindooDBAppBridgeRpcRequest, $ as MindooDBAppHostTheme, a9 as MindooDBAppViewport, j as MindooDBAppBridgePortMessage } from '../types-Cvlkh3vJ.js';
+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';
 
 type MaybePromise<T> = T | Promise<T>;

package/dist/testing/index.js

@@ -151,6 +151,27 @@ function createDefaultWritableAttachmentStream() {
     }
   };
 }
+function getFieldValue(source, field) {
+  return field.split(".").reduce((current, part) => {
+    if (current && typeof current === "object" && part in current) {
+      return current[part];
+    }
+    return void 0;
+  }, source);
+}
+function matchesDocumentFilter(document, filter) {
+  if (!filter) {
+    return true;
+  }
+  return Object.entries(filter).every(([field, expected]) => getFieldValue(document.data, field) === expected);
+}
+function decodeMockListCursor(cursor) {
+  if (!cursor) {
+    return 0;
+  }
+  const offset = Number.parseInt(cursor, 10);
+  return Number.isFinite(offset) && offset >= 0 ? offset : 0;
+}
 function createDefaultViewHandle() {
   const definition = {
     title: "Mock View",
@@ -217,32 +238,94 @@ function createDefaultViewHandle() {
 function createDatabaseHandle(definition) {
   let createCounter = 0;
   const defaultViewFactory = async () => createDefaultViewHandle();
+  const storedDocuments = /* @__PURE__ */ new Map();
   const defaultDocuments = {
-    async list(_query) {
+    async list(query) {
+      const status = query?.status ?? "existing";
+      const skip = Math.max(0, query?.skip ?? 0);
+      const limit = Math.max(1, query?.limit ?? 50);
+      const offset = decodeMockListCursor(query?.cursor) + skip;
+      const metadataOnly = query?.metadataOnly ?? false;
+      const items = Array.from(storedDocuments.values()).filter((document) => status === "all" ? true : status === "deleted" ? document.isDeleted : !document.isDeleted).filter((document) => metadataOnly ? true : matchesDocumentFilter(document, query?.filter)).sort((left, right) => left.id.localeCompare(right.id));
+      const page = items.slice(offset, offset + limit).map((document) => {
+        if (metadataOnly) {
+          return {
+            id: document.id,
+            isDeleted: document.isDeleted
+          };
+        }
+        const projectedData = query?.fields ? Object.fromEntries(query.fields.map((field) => [field, getFieldValue(document.data, field)])) : document.data;
+        return {
+          id: document.id,
+          data: projectedData,
+          attachmentCount: document.attachments?.length ?? 0,
+          updatedAt: document.updatedAt,
+          isDeleted: status !== "existing" ? document.isDeleted : void 0
+        };
+      });
+      const nextCursor = offset + page.length < items.length ? String(offset + page.length) : null;
       return {
-        items: [],
-        nextCursor: null
+        items: page,
+        nextCursor
       };
     },
     async get(_docId) {
-      return null;
+      const document = storedDocuments.get(_docId);
+      if (!document || document.isDeleted) {
+        return null;
+      }
+      return {
+        id: document.id,
+        data: structuredClone(document.data),
+        attachments: document.attachments ? structuredClone(document.attachments) : [],
+        updatedAt: document.updatedAt
+      };
     },
     async create(input) {
       createCounter += 1;
-      return {
+      const createdAt = (/* @__PURE__ */ new Date()).toISOString();
+      const created = {
         id: `doc-${createCounter}`,
         data: { ...input.data },
-        attachments: []
+        attachments: [],
+        updatedAt: createdAt
+      };
+      storedDocuments.set(created.id, {
+        ...created,
+        data: structuredClone(created.data),
+        attachments: [],
+        isDeleted: false
+      });
+      return {
+        ...created
       };
     },
     async update(docId, patch) {
-      return {
+      const updatedAt = (/* @__PURE__ */ new Date()).toISOString();
+      const existing = storedDocuments.get(docId);
+      const updated = {
         id: docId,
         data: { ...patch.data },
-        attachments: []
+        attachments: existing?.attachments ? structuredClone(existing.attachments) : [],
+        updatedAt
       };
+      storedDocuments.set(docId, {
+        ...updated,
+        data: structuredClone(updated.data),
+        attachments: updated.attachments ? structuredClone(updated.attachments) : [],
+        isDeleted: false
+      });
+      return updated;
     },
     async delete(_docId) {
+      const existing = storedDocuments.get(_docId);
+      if (existing) {
+        storedDocuments.set(_docId, {
+          ...existing,
+          isDeleted: true,
+          updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+        });
+      }
       return { ok: true };
     },
     async listHistory(_docId) {
@@ -278,6 +361,12 @@ function createDatabaseHandle(definition) {
     async openWriteStream(_docId, _attachmentName, _contentType) {
       return createDefaultWritableAttachmentStream();
     },
+    async preparePreviewSession(_docId, _attachmentName, _options) {
+      return {
+        sessionId: "preview-session-1",
+        previewUrl: "about:blank"
+      };
+    },
     async openPreview(_docId, _attachmentName, _options) {
       return { ok: true };
     }
@@ -662,6 +751,12 @@ function createFakeBridgeHost(options = {}) {
           String(params.attachmentName),
           typeof params.timestamp === "number" ? { timestamp: params.timestamp } : void 0
         );
+      case "attachments.preparePreviewSession":
+        return await state.getDatabase(String(params.databaseId)).attachments.preparePreviewSession(
+          String(params.docId),
+          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":

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

@@ -126,6 +126,11 @@ interface MindooDBAppAttachmentPreviewOptions {
     /** Historical snapshot timestamp previously obtained from `documents.history.getAtTimestamp()`. */
     timestamp?: number;
 }
+/** Resolved Haven preview session prepared for opening in a separate tab or window. */
+interface MindooDBAppAttachmentPreviewSession {
+    sessionId: string;
+    previewUrl: string;
+}
 /** Database entry visible to the app during launch and database listing. */
 interface MindooDBAppDatabaseInfo {
     id: string;
@@ -139,6 +144,9 @@ interface MindooDBAppDocumentSummary {
     data?: Record<string, unknown>;
     attachmentCount?: number;
     updatedAt?: string;
+    identityLabel?: string;
+    publicKeyFingerprint?: string;
+    isDeleted?: boolean;
 }
 /** Fully loaded document returned by `get()`, `create()`, or `update()`. */
 interface MindooDBAppDocument {
@@ -164,10 +172,13 @@ interface MindooDBAppHistoricalDocument {
     state: "missing" | "deleted" | "exists";
     data: Record<string, unknown> | null;
 }
-/** Query options for paging through documents in a database. */
+/** Query options for paging through changefeed-backed document listings in a database. */
 interface MindooDBAppDocumentListQuery {
-    limit?: number;
     cursor?: string | null;
+    limit?: number;
+    skip?: number;
+    status?: "all" | "existing" | "deleted";
+    metadataOnly?: boolean;
     fields?: string[];
     filter?: Record<string, unknown>;
 }
@@ -355,6 +366,7 @@ interface MindooDBAppAttachmentApi {
     }>;
     openReadStream(docId: string, attachmentName: string): Promise<MindooDBAppReadableAttachmentStream>;
     openWriteStream(docId: string, attachmentName: string, contentType?: string): Promise<MindooDBAppWritableAttachmentStream>;
+    preparePreviewSession(docId: string, attachmentName: string, options?: MindooDBAppAttachmentPreviewOptions): Promise<MindooDBAppAttachmentPreviewSession>;
     openPreview(docId: string, attachmentName: string, options?: MindooDBAppAttachmentPreviewOptions): Promise<{
         ok: true;
     }>;
@@ -381,4 +393,4 @@ interface MindooDBAppBridge {
     connect(options?: MindooDBAppBridgeConnectOptions): Promise<MindooDBAppSession>;
 }
 
-export type { MindooDBAppHostTheme as $, MindooDBAppConfiguredViewColumn as A, MindooDBAppConfiguredViewColumnRole as B, MindooDBAppConfiguredViewExpressionMode as C, MindooDBAppConfiguredViewFieldExpression as D, MindooDBAppConfiguredViewFilterDefinition as E, MindooDBAppConfiguredViewFilterMode as F, MindooDBAppConfiguredViewFilterRule as G, MindooDBAppConfiguredViewFormulaExpression as H, MindooDBAppConfiguredViewFormulaFilterDefinition as I, MindooDBAppConfiguredViewPreviewMode as J, MindooDBAppConfiguredViewRuleFilterDefinition as K, MindooDBAppConfiguredViewRuleMatchMode as L, MindooDBAppAttachmentPreviewMode as M, MindooDBAppConfiguredViewRuleOperator as N, MindooDBAppConfiguredViewValueExpression as O, MindooDBAppCreateDocumentInput as P, MindooDBAppCreateViewInput as Q, MindooDBAppDatabase as R, MindooDBAppDatabaseInfo as S, MindooDBAppDocument as T, MindooDBAppDocumentApi as U, MindooDBAppDocumentHistoryEntry as V, MindooDBAppDocumentListQuery as W, MindooDBAppDocumentListResult as X, MindooDBAppDocumentSummary as Y, MindooDBAppHistoricalDocument as Z, MindooDBAppHistoryQuery as _, MindooDBAppBridge as a, MindooDBAppLaunchContext as a0, MindooDBAppReadableAttachmentStream as a1, MindooDBAppResolvedViewDefinition as a2, MindooDBAppResolvedViewSource as a3, MindooDBAppRuntime as a4, MindooDBAppSession as a5, MindooDBAppThemeMode as a6, MindooDBAppUpdateDocumentInput as a7, MindooDBAppViewHandle as a8, MindooDBAppViewport as a9, MindooDBAppWritableAttachmentStream as aa, MindooDBAppAttachmentApi as b, MindooDBAppAttachmentChunk as c, MindooDBAppAttachmentInfo as d, MindooDBAppAttachmentPreviewOptions as e, MindooDBAppBridgeConnectMessage as f, MindooDBAppBridgeConnectOptions as g, MindooDBAppBridgeConnectedMessage as h, MindooDBAppBridgeErrorPayload as i, MindooDBAppBridgePortMessage as j, MindooDBAppBridgeRpcError as k, MindooDBAppBridgeRpcMessage as l, MindooDBAppBridgeRpcRequest as m, MindooDBAppBridgeRpcSuccess as n, MindooDBAppBridgeStreamAbortRequest as o, MindooDBAppBridgeStreamAck as p, MindooDBAppBridgeStreamCloseRequest as q, MindooDBAppBridgeStreamError as r, MindooDBAppBridgeStreamMessage as s, MindooDBAppBridgeStreamOpenResult as t, MindooDBAppBridgeStreamReadRequest as u, MindooDBAppBridgeStreamWriteRequest as v, MindooDBAppBridgeThemeChangedMessage as w, MindooDBAppBridgeViewportChangedMessage as x, MindooDBAppCapability as y, MindooDBAppConfiguredViewCategorizationStyle as z };
+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 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mindoodb-app-sdk",
-  "version": "0.0.5",
+  "version": "0.0.7",
   "description": "MindooDB app SDK for building apps that connect to the Haven host bridge",
   "license": "ISC",
   "author": "Mindoo GmbH",
@@ -40,7 +40,7 @@
     "prepublishOnly": "npm run build && npm run test"
   },
   "dependencies": {
-    "mindoodb-view-language": "file:../mindoodb-view-language"
+    "mindoodb-view-language": "0.0.7"
   },
   "devDependencies": {
     "@types/node": "^25.5.0",