mindoodb-app-sdk 0.0.49 → 0.0.53

package/README.md

@@ -229,6 +229,35 @@ Important constraints:
 - 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.
 
+### Host focus and notifications
+
+A click inside the iframe already asks Haven to focus this launch. Call `requestHostFocus()` when the app should take focus without a click.
+
+`hasHostFocus()` is true only when this launch is the surface the user is looking at: the focused tile on the active workspace page, or this launch open as a standalone runner. A background tile, another page, or another app is false. `onHostFocusChange()` fires when that answer changes, so a long task can decide whether to notify without polling.
+
+```ts
+const stop = session.onHostFocusChange((focused) => {
+  if (!focused) {
+    void session.notify({
+      id: "sync",
+      severity: "info",
+      text: "Sync finished",
+    });
+  }
+});
+
+await session.notify({
+  id: "progress",
+  severity: "info",
+  text: "10%",
+  durationMs: 1500,
+});
+```
+
+Show a notice when the app does not have host focus, or when a long task finishes and the user may have looked away. Do not notify while `hasHostFocus()` is true and the user is already looking at the app.
+
+Haven uses the app's registration label as the headline and ignores any title from the app. Pass the same `id` to update that notice in place. Omit `id` to add another notice. An id only matches notices from this launch. Omit `durationMs` and the notice stays until the user dismisses it or clicks it. A duration is clamped to about 1–8 seconds, which fits a short progress step such as "10%". Clicking the notice brings that launch back. The close button only dismisses it.
+
 ### Host-owned drag
 
 When two apps run as visible workspace chicklets, native HTML5 drag dies at the iframe boundary. The SDK therefore hands the gesture to Haven: the source starts it, Haven draws a PNG ghost above every frame, and the target hit-tests the drop.
@@ -458,7 +487,7 @@ A snapshot also carries `decryptionKeyId?: string` — the named shared key its
 
 - `set` -- assign top-level fields (shallow JSON merge).
 - `unset` -- remove top-level fields entirely.
-- `json` -- a **granular JSON patch** of `set` / `unset` / `listInsert` / `listDelete` operations applied at specific paths inside `document.data`, against a `baseHeads` version. See [Granular JSON edits](#granular-json-edits) below.
+- `json` -- a **granular JSON patch** of `set` / `unset` / `listInsert` / `listDelete` operations (plus text splices/marks and `counterIncrement`) applied at specific paths inside `document.data`, against a `baseHeads` version. See [Granular JSON edits](#granular-json-edits) and [Typed values](#typed-values-atomic-strings-counters-timestamps) below.
 - `text` -- one or more **granular text patches** applied to specific string paths. Each patch carries the `baseHeads` version it was authored against and is merged on the Haven side with any concurrent changes that arrived since. This is the recommended way to edit collaborative text fields like a markdown body. See [Collaborative text editing](#collaborative-text-editing) below.
 - `richText` -- one or more **rich-text span snapshots** for formatted-document fields (Word/.docx style). See [Collaborative rich-text editing](#collaborative-rich-text-editing) below.
 
@@ -614,6 +643,109 @@ Haven applies the patch causally at `baseHeads` and merges it with any concurren
 
 Patch flavors compose. `set`/`unset` (top-level fields), `json`, `text`, and `richText` can all appear in the same `documents.update()` call and are applied atomically to one new document revision. Prefer small, intentional operations over whole-document rewrites so MindooDB change tracking stays meaningful and Automerge produces cleaner merges.
 
+### Typed values: atomic strings, counters, timestamps
+
+`document.data` is JSON, and JSON has one kind of string and one kind of number. For collaborative data that is not enough, so the SDK adds three **typed values**. You create them with `MindooDBAppValue` and use them anywhere you write a value: `documents.create({ set })`, `documents.update({ set })`, and `set` / `listInsert` values of a JSON patch, also nested inside objects and arrays.
+
+```ts
+import { MindooDBAppValue } from "mindoodb-app-sdk";
+
+const task = await db.documents.create({
+  set: {
+    title: "Write release notes",                    // collaborative text
+    status: MindooDBAppValue.atomic("open"),          // atomic string
+    votes: MindooDBAppValue.counter(0),               // counter
+    dueAt: MindooDBAppValue.timestamp("2026-10-01T12:00:00Z"),
+    assignee: { userId: MindooDBAppValue.atomic("u-42"), name: "Ada" },
+  },
+});
+
+task.data.status; // "open"
+task.data.votes;  // 0
+task.data.dueAt;  // "2026-10-01T12:00:00.000Z"
+```
+
+| Helper | Use it for | Reads back as |
+|---|---|---|
+| `MindooDBAppValue.atomic(string)` | ids, status and enum values, URLs, hashes, stored text cursors | `string` |
+| `MindooDBAppValue.counter(initial = 0)` | tallies several people change: votes, likes, stock, seats | `number` |
+| `MindooDBAppValue.timestamp(Date \| ms \| ISO string)` | dates and times | ISO 8601 string (UTC, with ms) |
+
+Why they matter:
+
+- **Plain strings are collaborative text.** Concurrent edits are merged character by character, which is right for titles, notes and bodies. For a status that one user changes from `"open"` to `"closed"` while another changes it to `"blocked"`, text merging can produce a mix of both words. An **atomic** string is replaced as a whole: one of the two values wins. It is also cheaper to store.
+- **Plain numbers are last-writer-wins.** If two users both read `votes: 4` and each save `5`, one vote is lost. A **counter** sums concurrent increments, so the result is `6`.
+- **An ISO string written as a plain string is text**, not a date. A **timestamp** stays a date for everyone who reads the document.
+
+The helpers produce plain JSON (`{ "$mindoo": "atomic", "value": "open" }`), so the values pass the bridge unchanged, and Haven converts them into the matching collaborative type. The key `$mindoo` is reserved: an object carrying it must be one of these values, otherwise the write is rejected.
+
+Reads return plain JSON, so **a value keeps its type only if you write it again with the helper.** Writing `status: "done"` stores text; write `status: MindooDBAppValue.atomic("done")`. Haven's database browser keeps the type when a user edits such a field in the JSON view.
+
+#### Counters
+
+Create a counter once, then change it only with `counterIncrement`:
+
+```ts
+interface MindooDBAppJsonCounterIncrementPatch {
+  path: Array<string | number>;
+  delta: number; // safe integer, negative to decrement
+}
+
+await db.documents.update(docId, {
+  json: { counterIncrement: [{ path: ["votes"], delta: 1 }] },
+});
+```
+
+- Writing `MindooDBAppValue.counter(n)` or a plain number over an existing counter resets it. That is an assignment and does not merge with concurrent increments, so use it for creation and deliberate resets only.
+- `counterIncrement` on a missing field creates the counter with value `delta`. If two devices do that concurrently for the same field, only one creation survives, so create shared counters up front, ideally in `documents.create`.
+- `counterIncrement` on a plain number is rejected: the field is not a counter.
+- `counterIncrement` runs after the other operations of the same JSON patch, so a patch may create an object with `set` and increment a counter inside it.
+- In Haven's database browser a counter can be edited in the JSON view: the new value is saved as the difference to the loaded value, so increments made by others in the meantime are kept.
+
+### Text cursors (anchors for comments and highlights)
+
+An index like "character 120" breaks as soon as another user inserts text before it. A **text cursor** identifies a character instead of a position, so it keeps pointing at the same spot while the text around it changes. Use cursors for comment and review anchors, highlights, bookmarks, "continue reading here" markers or links into a long text.
+
+```ts
+// Anchor a comment to characters 120..134 of the body (end exclusive: 135).
+// The end cursor names the LAST character of the range, see below.
+const doc = await db.documents.get(docId);
+const { cursors } = await db.documents.getTextCursors(docId, ["body"], [120, 134], {
+  heads: doc!.heads, // the version the user selected in
+});
+await db.documents.update(docId, {
+  json: {
+    listInsert: [{
+      path: ["comments"],
+      index: 0,
+      values: [{
+        text: "Source?",
+        from: MindooDBAppValue.atomic(cursors[0]!),
+        to: MindooDBAppValue.atomic(cursors[1]!),
+      }],
+    }],
+  },
+});
+
+// Later, after other users edited the body
+const current = (await db.documents.get(docId))!;
+const comment = current.data.comments[0];
+const { positions } = await db.documents.resolveTextCursors(docId, ["body"], [comment.from, comment.to], {
+  heads: current.heads, // resolve in the version you are about to render
+});
+const [start, last] = positions;
+const quoted = current.data.body.slice(start, last + 1);
+```
+
+Details:
+
+- A cursor names the character at its index. Text inserted exactly at that index lands in front of the character, so the cursor moves right. For a range, anchor the start on its first character and the end on its **last** character, then add 1 after resolving. An end cursor on the character after the range would grow the range whenever someone types at its end.
+- `positions` accepts character indexes (clamped to the text length) and `"start"` / `"end"`. An `"end"` cursor stays at the end when text is appended.
+- A cursor whose character was deleted resolves to where the character used to be. `move: "before"` makes it resolve towards the start of the text instead of the end.
+- `heads` (or `revisionId`) creates or resolves cursors against that document version. Pass the heads your editor rendered from so positions the user selected are interpreted in the text they saw.
+- Cursors only work on collaborative text: plain strings and rich text. Atomic strings, numbers and missing fields are rejected. Store the cursor strings themselves as atomic strings.
+- Both calls need the `read` capability. The mock bridge from `mindoodb-app-sdk/testing` returns cursors that do not follow later edits; test anchoring behavior against Haven.
+
 ### Collaborative text editing
 
 MindooDB stores collaborative text fields as Automerge text CRDTs internally, but apps never touch Automerge directly -- the SDK bridge is JSON-only. Instead, your app describes text changes as **granular splice operations** against a known document version, and Haven applies and merges them on its side.
@@ -1060,6 +1192,18 @@ const setup = await db.getFulltextSetup(); // null when never configured
 - `attachments: true` indexes attachment text under the synthetic `_attachments` field using the host's extractors (Haven ships anydoc for Office/PDF/… plus plain-text extractors). Restrict a query to attachment content with `text: { query, fields: ["_attachments"] }`.
 - Changing the configuration (including `language`) rebuilds the index in the background; queries during the rebuild report `coverage: "rebuilding"`.
 
+**Making nested fields queryable** — `query()` only sees fields in the database's summary buffer. By default that is every top-level scalar or array of scalars up to 1 KB; nested objects and arrays of objects are skipped. Include what your list UIs need so they don't have to `documents.get` each document:
+
+```ts
+// Idempotent, synced via the `dbsetup` document. Requires the `update` capability.
+const current = await db.getSummarySetup(); // null = default auto-include
+const include = [...new Set([...(current?.include ?? []), "phases"])];
+await db.setSummarySetup({ ...current, include });
+```
+
+- `include` paths may be nested (`"meta.author"`) or non-scalar and bypass the size cap; `exclude` wins over both.
+- A change re-extracts all documents in the background; queries report `coverage: "rebuilding"` until the backfill finishes, so keep a fallback for missing fields.
+
 **Extracting text from bytes you already have** (requires `attachments`):
 
 ```ts
@@ -1535,6 +1679,40 @@ wrangler deploy
 
 Other static hosting options work just as well: Netlify, Vercel, any web server serving your `dist/` folder.
 
+### Sharing an app by its URL
+
+Anyone who opens your app's address directly — not from inside Haven — has no host to talk to. Instead of letting the bridge handshake time out into an error, branch on `isLaunchedByHaven()` before mounting and show a landing page:
+
+```ts
+import { isLaunchedByHaven, renderHavenAppLandingPage } from "mindoodb-app-sdk";
+
+if (isLaunchedByHaven()) {
+  createApp(App).mount("#app");
+} else {
+  void renderHavenAppLandingPage();
+}
+```
+
+Haven puts `mindoodbAppLaunchId` into every launch URL, so the check is synchronous. `renderHavenAppLandingPage()` reads `haven-app.json` from the same origin and shows the app's name, summary, description and screenshots, plus a button to `https://haven.mindoodb.com/?app=<your app URL>` (pass `havenUrl` for another Haven instance). Haven then walks a new user through setup with your app installed at the end, or offers an existing user to add it.
+
+What the page shows comes from the optional `listing` in `haven-app.json`. Haven's setup wizard shows the same fields:
+
+```json
+{
+  "listing": {
+    "summary": { "en": "Plan trips together.", "de": "Reisen gemeinsam planen." },
+    "description": { "en": "First paragraph.\n\nSecond paragraph." },
+    "icon": "icon.svg",
+    "screenshots": [{ "file": "screenshots/board.webp", "caption": { "en": "The trip board" } }],
+    "publisher": { "name": "Mindoo GmbH", "url": "https://mindoo.de" }
+  }
+}
+```
+
+Texts are a string or a per-locale map with an `en` fallback. Image paths are relative to the app origin or absolute `https:` URLs. The listing is display-only and grants nothing.
+
+For automated and manual tests use a separate test URL that frames the app with a mock host instead — see "Browser test host" in [`TESTING.md`](./TESTING.md). End users never see that page, and they never see mock data.
+
 ### Haven-hosted bundles
 
 Instead of Haven loading your app from your server on every launch, you can hand Haven the build itself. Haven stores it in its own cache and serves it from a service worker on an opaque origin, so the app loads offline and runs in a stricter sandbox than an external URL gets.
@@ -1636,6 +1814,10 @@ Connect options: `launchId?`, `targetOrigin?`, `connectTimeoutMs?`.
 | `closeSealedChannel(channelId)`       | `Promise<void>`                      |
 | `menus.show(input)`                   | `Promise<MindooDBAppShowMenuResult>` |
 | `menus.hide()`                        | `Promise<void>`                      |
+| `requestHostFocus()`                  | `Promise<void>`                      |
+| `hasHostFocus()`                      | `Promise<boolean>`                   |
+| `onHostFocusChange(listener)`         | `() => void` (unsubscribe)           |
+| `notify(input)`                       | `Promise<{ id: string }>`            |
 | `drag.setProfile(profile)`            | `Promise<void>`                      |
 | `drag.start(input)`                   | `Promise<MindooDBAppDragStartResult>` |
 | `drag.cancel()`                       | `Promise<void>`                      |
@@ -1670,6 +1852,8 @@ Host-kept key/value state, the only durable storage a hosted app has. See [Stora
 | `attachments`                | `MindooDBAppAttachmentApi`                     |
 | `getFulltextSetup()`         | `Promise<MindooDBAppFulltextSetup \| null>`    |
 | `setFulltextSetup(config)`   | `Promise<void>`                                |
+| `getSummarySetup()`          | `Promise<MindooDBAppSummarySetup \| null>`     |
+| `setSummarySetup(config)`    | `Promise<void>`                                |
 
 ### MindooDBAppDocumentApi
 

package/TESTING.md

@@ -107,6 +107,7 @@ Each database entry can provide:
 - `methods.views` for session-level `createView()` and `openView()` calls (overrides the default evaluating navigator)
 - `methods.attachments`
 - `fulltextSetup` — the initial config returned by `db.getFulltextSetup()`; `db.setFulltextSetup()` overwrites it for the lifetime of the handle. Use this to test your app's full-text bootstrap logic. Note the mock evaluates `text` query clauses regardless of this config.
+- `summarySetup` — the initial config returned by `db.getSummarySetup()`; `db.setSummarySetup()` overwrites it for the lifetime of the handle. The mock's `query()` reads seeded documents directly and ignores this config; use it to test your app's summary bootstrap logic.
 
 ### Evaluating VirtualViews
 
@@ -218,6 +219,30 @@ expect(result.rows[0].includes?.customer?.fields.name).toBe("Acme");
 An include slot naming a database that was not seeded fails, the same way Haven
 rejects a database the app is not mapped to.
 
+### Host focus and notifications
+
+A mock launch starts without host focus. `session.requestHostFocus()` sets it
+and fires `onHostFocusChange` listeners; `mock.emitHostFocusChange(focused)`
+simulates Haven moving focus to or away from the launch, so you can test code
+that only notifies while the user is looking elsewhere. `session.notify()` shows
+nothing and resolves with the passed `id`, or a fresh one when `id` is omitted:
+
+```ts
+const mock = createMockMindooDBAppSession();
+
+const seen: boolean[] = [];
+const stop = mock.session.onHostFocusChange((focused) => seen.push(focused));
+
+await mock.session.requestHostFocus();
+mock.emitHostFocusChange(false);
+expect(await mock.session.hasHostFocus()).toBe(false);
+expect(seen).toEqual([true, false]);
+stop();
+
+const { id } = await mock.session.notify({ id: "sync", severity: "info", text: "Sync finished" });
+expect(id).toBe("sync");
+```
+
 ## Level 2 example
 
 This pattern keeps the real `createMindooDBAppBridge()` code path and replaces only the host side.
@@ -287,12 +312,45 @@ Useful Level 2 methods:
 - `emitViewportChange()`
 - `emitQueryResult()` — push a `query-result` message to live query subscribers
 - `emitViewChanged()` — push a `view-changed` message to navigator `onDidUpdate` listeners
+- `emitHostFocusChange()` — set host focus and push a `host-focus-changed` message to `session.onHostFocusChange()` listeners
 - `setRequestHandler()`
 - `clearRequestHandler()`
 - `postPortMessage()`
 
 The built-in request handling also covers `documents.query` and the `documents.liveQuery.*` RPCs against the seeded documents, so `db.documents.query()` / `db.documents.liveQuery()` and `navigator.onDidUpdate()` work end-to-end over the real bridge transport in Level 2 tests.
 
+## Browser test host
+
+Level 1 and 2 run in Node/jsdom. To run the real app in a real browser — for Playwright, or to click through it yourself — mount the browser test host on a separate page. It frames the app exactly as Haven does (an iframe with `?mindoodbAppLaunchId=…`) and answers the bridge with the same mock state as the Vitest helpers:
+
+```ts
+// src/testHost/main.ts, loaded by /__haven-test/index.html
+import { mockDatabasesFromDefinition, mountHavenTestHost } from "mindoodb-app-sdk/testing";
+import definition from "../../public/haven-app.json";
+
+mountHavenTestHost({
+  appUrl: "/",
+  title: definition.label,
+  databases: mockDatabasesFromDefinition(definition, {
+    main: [{ id: "welcome", data: { type: "note", title: "Seeded note" } }],
+  }),
+});
+```
+
+The page shows the app next to a control panel: theme and host-focus toggles, a file picker that decides what the app's next `attachments.scan()` returns (none means the user cancelled), and a live log of notifications, attachment previews, scans and every RPC request. The same controls are scriptable as `window.__havenTestHost`:
+
+```ts
+await page.goto("/__haven-test/");
+const app = page.frameLocator('[data-testid="haven-test-app-frame"]');
+await page.evaluate(() => window.__havenTestHost!.setNextScan({ fileName: "receipt.pdf", mimeType: "application/pdf", size: 1024 }));
+await app.getByRole("button", { name: "Scan" }).click();
+expect(await page.evaluate(() => window.__havenTestHost!.log.scans)).toHaveLength(1);
+```
+
+Lower-level pieces, if you build your own page: `createBrowserTestHost({ frame, appUrl, ...mockOptions })` wires one iframe to a fake host, and `host.acceptConnection(message, ports)` answers a handshake you received yourself.
+
+Keep the test page out of production builds. The starter template builds it only for `vite dev` and when `HAVEN_TEST_HOST=1` is set (for preview deployments), so the app's public URL keeps showing its landing page.
+
 ## When to use which level
 
 Choose Level 1 when:

package/dist/{chunk-TPYDERAK.js → chunk-6NTVTL6G.js}

@@ -1,3 +1,45 @@
+// src/values.ts
+var MINDOODB_APP_VALUE_TAG = "$mindoo";
+var MindooDBAppValue = {
+  /**
+   * An atomic string for identifiers, status and enum values, URLs, hashes
+   * and stored text cursors. Plain strings are collaborative text, where two
+   * concurrent changes of `"open"` to `"closed"` and `"blocked"` can
+   * interleave into a mix of both words.
+   */
+  atomic(value) {
+    if (typeof value !== "string") {
+      throw new Error("MindooDBAppValue.atomic value must be a string");
+    }
+    return { $mindoo: "atomic", value };
+  },
+  /**
+   * A collaborative counter with an initial value (a safe integer). Create it
+   * once, then change it only with `json.counterIncrement`: writing a new
+   * counter is an assignment that does not merge with concurrent increments.
+   */
+  counter(value = 0) {
+    if (!Number.isSafeInteger(value)) {
+      throw new Error("MindooDBAppValue.counter value must be a safe integer");
+    }
+    return { $mindoo: "counter", value };
+  },
+  /** A timestamp from a `Date`, epoch milliseconds or an ISO 8601 string. */
+  timestamp(value) {
+    const date = value instanceof Date ? new Date(value.getTime()) : new Date(value);
+    if (typeof value === "string" && value.trim() === "" || Number.isNaN(date.getTime())) {
+      throw new Error(
+        "MindooDBAppValue.timestamp value must be a Date, epoch milliseconds or an ISO 8601 date-time string"
+      );
+    }
+    return { $mindoo: "timestamp", value: date.toISOString() };
+  },
+  /** Whether `value` is a tagged typed value (any kind). */
+  isTyped(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value) && Object.prototype.hasOwnProperty.call(value, MINDOODB_APP_VALUE_TAG);
+  }
+};
+
 // src/drag.ts
 var MINDOODB_APP_MAX_DRAG_TYPES = 8;
 var MINDOODB_APP_MAX_DRAG_PAYLOAD_BYTES = 32 * 1024;
@@ -392,11 +434,13 @@ function bindDragSource(element, options, start, follow) {
 // src/hostShortcuts.ts
 var DEFAULT_HAVEN_HOST_SHORTCUTS = [
   { action: "open-workspace", code: "Enter", shiftKey: true, metaOrCtrl: true },
-  { action: "toggle-app-drawer", code: "Space", shiftKey: true, metaOrCtrl: true }
+  { action: "toggle-app-drawer", code: "Space", shiftKey: true, metaOrCtrl: true },
+  { action: "toggle-workspace-maximize", code: "KeyM", shiftKey: true, metaOrCtrl: true }
 ];
 var HOST_SHORTCUT_ACTIONS = /* @__PURE__ */ new Set([
   "open-workspace",
-  "toggle-app-drawer"
+  "toggle-app-drawer",
+  "toggle-workspace-maximize"
 ]);
 function normalizeShortcutCode(code) {
   return code === "NumpadEnter" ? "Enter" : code;
@@ -450,7 +494,7 @@ function applyHostedDocumentOverscrollContain(doc = globalThis.document) {
   if (!doc?.documentElement) {
     return;
   }
-  doc.documentElement.style.overscrollBehavior = "contain";
+  doc.documentElement.style.overscrollBehavior = "none";
   if (doc.body) {
     doc.body.style.overscrollBehavior = "contain";
   }
@@ -627,6 +671,21 @@ var PortRpcClient = class {
   }
 };
 
+// src/hostFocus.ts
+function installHostFocusCapture(options) {
+  const target = options.target ?? (typeof document === "undefined" ? void 0 : document);
+  if (!target) {
+    return () => void 0;
+  }
+  const onPointerDown = () => {
+    options.onPointerDown();
+  };
+  target.addEventListener("pointerdown", onPointerDown, true);
+  return () => {
+    target.removeEventListener("pointerdown", onPointerDown, true);
+  };
+}
+
 // src/client/createMindooDBAppBridge.ts
 var PROTOCOL2 = "mindoodb-app-bridge";
 var DEFAULT_CONNECT_TIMEOUT_MS = 1e4;
@@ -1226,6 +1285,23 @@ var MindooDBAppDatabaseImpl = class {
         path,
         revisionId: options?.revisionId
       }),
+      getTextCursors: async (docId, path, positions, options) => await this.rpc.call("documents.textCursors.get", {
+        databaseId: this.databaseId,
+        docId,
+        path,
+        positions,
+        heads: options?.heads,
+        move: options?.move,
+        revisionId: options?.revisionId
+      }),
+      resolveTextCursors: async (docId, path, cursors, options) => await this.rpc.call("documents.textCursors.resolve", {
+        databaseId: this.databaseId,
+        docId,
+        path,
+        cursors,
+        heads: options?.heads,
+        revisionId: options?.revisionId
+      }),
       getAutomergeSnapshot: async (docId, options) => await this.rpc.call("documents.automerge.getSnapshot", {
         databaseId: this.databaseId,
         docId,
@@ -1236,6 +1312,26 @@ var MindooDBAppDatabaseImpl = class {
         docId,
         patch
       }),
+      applyAutomergeChangesBatch: async (items) => {
+        if (items.length === 0) return [];
+        try {
+          return await this.rpc.call("documents.automerge.applyChangesBatch", {
+            databaseId: this.databaseId,
+            items
+          });
+        } catch (error) {
+          if (!isMethodNotFoundError(error)) throw error;
+          const results = [];
+          for (const item of items) {
+            results.push(await this.rpc.call("documents.automerge.applyChanges", {
+              databaseId: this.databaseId,
+              docId: item.docId,
+              patch: item.patch
+            }));
+          }
+          return results;
+        }
+      },
       create: async (input) => await this.rpc.call("documents.create", {
         databaseId: this.databaseId,
         input
@@ -1576,6 +1672,21 @@ var MindooDBAppDatabaseImpl = class {
       config
     });
   }
+  /** Reads the summary buffer configuration from the synced `dbsetup` document. */
+  async getSummarySetup() {
+    const result = await this.rpc.call(
+      "database.getSummarySetup",
+      { databaseId: this.databaseId }
+    );
+    return result.config;
+  }
+  /** Writes (or removes, with `null`) the summary buffer configuration. */
+  async setSummarySetup(config) {
+    await this.rpc.call("database.setSummarySetup", {
+      databaseId: this.databaseId,
+      config
+    });
+  }
 };
 var MindooDBAppDragApiImpl = class {
   constructor(rpc) {
@@ -1718,6 +1829,18 @@ var MindooDBAppSessionImpl = class {
         }
       }
     }) : () => void 0;
+    this.stopHostFocus = installHostFocusCapture({
+      onPointerDown: () => {
+        try {
+          this.rpc.postMessage({
+            protocol: PROTOCOL2,
+            kind: "workspace-focus-requested"
+          });
+        } catch (error) {
+          console.warn("[mindoodb-app-sdk] Could not request host focus.", error);
+        }
+      }
+    });
   }
   rpc;
   onDisconnect;
@@ -1727,6 +1850,7 @@ var MindooDBAppSessionImpl = class {
   beforeCloseListeners = /* @__PURE__ */ new Set();
   hostShortcuts = DEFAULT_HAVEN_HOST_SHORTCUTS;
   stopHostShortcuts;
+  stopHostFocus;
   /**
    * Lets every listener finish, then tells the host it may proceed.
    *
@@ -1862,6 +1986,27 @@ var MindooDBAppSessionImpl = class {
       }
     });
   }
+  /** Ask Haven to treat this launch as the focused surface. */
+  async requestHostFocus() {
+    await this.rpc.call("session.requestHostFocus", {});
+  }
+  /** Whether this launch is the surface the user is looking at. */
+  async hasHostFocus() {
+    const result = await this.rpc.call("session.hasHostFocus", {});
+    return result?.focused === true;
+  }
+  /** Fires when the host-focus answer for this launch changes. */
+  onHostFocusChange(listener) {
+    return this.rpc.addMessageListener((message) => {
+      if (message.kind === "host-focus-changed") {
+        listener(message.focused);
+      }
+    });
+  }
+  /** Ask Haven to show or update a notice for this launch. */
+  async notify(input) {
+    return await this.rpc.call("notifications.show", input);
+  }
   /** Register work to run before the host tears this launch down. */
   onBeforeClose(listener) {
     this.beforeCloseListeners.add(listener);
@@ -1872,6 +2017,7 @@ var MindooDBAppSessionImpl = class {
   /** Disconnects from the host and always disposes the underlying port client. */
   async disconnect() {
     this.stopHostShortcuts();
+    this.stopHostFocus();
     this.drag.dispose();
     try {
       await this.rpc.call("session.disconnect", {});
@@ -1925,6 +2071,8 @@ function createMindooDBAppBridge() {
 }
 
 export {
+  MINDOODB_APP_VALUE_TAG,
+  MindooDBAppValue,
   MINDOODB_APP_MAX_DRAG_TYPES,
   MINDOODB_APP_MAX_DRAG_PAYLOAD_BYTES,
   MINDOODB_APP_MAX_DRAG_PREVIEW_BYTES,