mindoodb-app-sdk 0.0.51 → 0.0.54

package/README.md

@@ -22,26 +22,17 @@ A **MindooDB App** is any web application that uses this SDK to communicate with
 
 ## 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   │              │  │
-│  │              └─────────────────────┘              │  │
-│  └───────────────────────────────────────────────────┘  │
-└─────────────────────────────────────────────────────────┘
+```mermaid
+flowchart TB
+  subgraph haven["Haven (browser tab)"]
+    direction TB
+    ui["Haven UI<br/>(theme, viewport)"] --> bridge["Bridge Host<br/>(RPC + streams)"]
+    bridge --> db["MindooDB<br/>(encrypted databases)"]
+    subgraph app["Your App (sandboxed iframe / window)"]
+      sdk["mindoodb-app-sdk"]
+    end
+    bridge -- "postMessage + MessagePort" --> sdk
+  end
 ```
 
 The bridge carries RPC calls (documents, views, database info), binary attachment streams, and push events (theme changes, viewport resizes) over a single `MessagePort`.
@@ -757,23 +748,11 @@ Two layers are available:
 
 The end-to-end flow is the same in both cases:
 
-```
-            ┌────────────────────────────────────────────────────┐
-  edit ───► │ App buffer (local string + pending splices)        │ ──► flush
-            └─────────────────────────┬──────────────────────────┘
-                                      │ documents.update({
-                                      │   text: [{ path, baseHeads, edits }]
-                                      │ })
-                                      ▼
-            ┌────────────────────────────────────────────────────┐
-            │ Haven applies edits at `baseHeads` and merges with │
-            │ concurrent changes via Automerge                   │
-            └─────────────────────────┬──────────────────────────┘
-                                      │ canonical merged document
-                                      ▼
-            ┌────────────────────────────────────────────────────┐
-            │ App reconciles its editor with the canonical text  │
-            └────────────────────────────────────────────────────┘
+```mermaid
+flowchart TB
+  edit(["edit"]) --> buffer["App buffer<br/>(local string + pending splices)"]
+  buffer -- "flush: documents.update({ text: [{ path, baseHeads, edits }] })" --> merge["Haven applies edits at baseHeads<br/>and merges with concurrent changes via Automerge"]
+  merge -- "canonical merged document" --> reconcile["App reconciles its editor<br/>with the canonical text"]
 ```
 
 #### Text patch shape
@@ -1003,24 +982,14 @@ If you must use binary sync, Haven decrypts the canonical document, merges incom
 
 Typical flow:
 
-```
-            ┌────────────────────────────────────────────────────┐
-  open  ──► │ getAutomergeSnapshot → load local replica          │
-            └─────────────────────────┬──────────────────────────┘
-                                      │
-  edit  ──► │ Local Automerge doc (or span edits applied locally)  │
-            └─────────────────────────┬──────────────────────────┘
-                                      │ getChangesSince(baseHeads)
-                                      ▼
-            ┌────────────────────────────────────────────────────┐
-  save  ──► │ applyAutomergeChanges({ baseHeads, replicaHeads,   │
-            │                       changes })                   │
-            └─────────────────────────┬──────────────────────────┘
-                                      │ Haven merges + persists
-                                      ▼
-            ┌────────────────────────────────────────────────────┐
-            │ Apply result.changesSince locally (or skip if empty) │
-            └────────────────────────────────────────────────────┘
+```mermaid
+flowchart TB
+  open(["open"]) --> snapshot["getAutomergeSnapshot<br/>→ load local replica"]
+  snapshot --> local["Local Automerge doc<br/>(or span edits applied locally)"]
+  editStep(["edit"]) --> local
+  local -- "getChangesSince(baseHeads)" --> apply["applyAutomergeChanges({<br/>baseHeads, replicaHeads, changes })"]
+  saveStep(["save"]) --> apply
+  apply -- "Haven merges + persists" --> result["Apply result.changesSince locally<br/>(or skip if empty)"]
 ```
 
 Bridge RPCs: `documents.automerge.getSnapshot` and `documents.automerge.applyChanges`.
@@ -1679,6 +1648,45 @@ 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." },
+    "descriptionMarkdown": { "en": "**Plan** together.\n\n- Shared board\n- [Website](https://trips.example.com)" },
+    "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.
+
+Opening the app URL directly also puts share tags into `index.html` (`twitter:card` = `summary`, plus the Open Graph tags other apps read), with the app icon as the image. A production build takes the absolute URL from `publicUrl` in `haven-app.json`. `vite dev` uses the dev server's own origin instead, so `http://127.0.0.1:<port>/` previews against itself. Crawlers do not run the landing page's JavaScript, which is why the tags are in the HTML file.
+
+`description` is plain text. `descriptionMarkdown` is the same text with formatting, in a small Markdown subset: paragraphs, headings, bullet and numbered lists, `**bold**`, `_italic_`, `` `code` ``, `[text](https://…)`, `[text](mailto:…)` and bare `https://…` links. Links to any other scheme render as plain text. Readers that know `descriptionMarkdown` show it instead of `description`; older Haven versions ignore it, so set both if they matter. `listingMarkdownToPlainText()` derives the plain version. A publisher `url` (`https:` only) turns the publisher name into a link.
+
+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.

package/TESTING.md

@@ -219,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.
@@ -288,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-R76XXRJ6.js → chunk-6NTVTL6G.js}

@@ -494,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";
   }

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { M as MindooDBAppAttachmentPreviewMode, a as MindooDBAppDragBindSourceOptions, b as MindooDBAppDragStartInput, c as MindooDBAppDragStartResult, d as MindooDBAppDragPreview, e as MindooDBAppBridge, f as MindooDBAppHostShortcutBinding, g as MindooDBAppHostShortcutAction, h as MindooDBAppHostingMode, i as MindooDBAppDatabase, j as MindooDBAppDocument, k as MindooDBAppRichTextSpan, l as MindooDBAppRichTextSnapshot, m as MindooDBAppCreateDocumentInput } from './types-BLyV6Ejy.js';
-export { n as MINDOODB_APP_DEFINITION_FILE_NAME, o as MINDOODB_APP_DEFINITION_FORMAT, p as MINDOODB_APP_DEFINITION_PERMISSIONS, q as MINDOODB_APP_DEFINITION_REGISTRATION_PERMISSIONS, r as MINDOODB_APP_DEFINITION_VERSION, s as MINDOODB_APP_SEAL_SIGNING_DOMAIN, t as MINDOODB_APP_WELL_KNOWN_DRAG_TYPES, u as MindooDBAppAccessDecision, v as MindooDBAppAccessTier, w as MindooDBAppAttachmentApi, x as MindooDBAppAttachmentChunk, y as MindooDBAppAttachmentInfo, z as MindooDBAppAttachmentPreviewOptions, A as MindooDBAppAttachmentPreviewSession, B as MindooDBAppAutomergeChangesPatch, C as MindooDBAppAutomergeChangesSince, D as MindooDBAppAutomergeGetOptions, E as MindooDBAppAutomergePatchResult, F as MindooDBAppAutomergeSnapshot, G as MindooDBAppBridgeBeforeCloseAck, H as MindooDBAppBridgeBeforeCloseMessage, I as MindooDBAppBridgeConnectMessage, J as MindooDBAppBridgeConnectOptions, K as MindooDBAppBridgeConnectedMessage, L as MindooDBAppBridgeDragDropMessage, N as MindooDBAppBridgeDragLeaveMessage, O as MindooDBAppBridgeDragOverMessage, P as MindooDBAppBridgeErrorPayload, Q as MindooDBAppBridgeHandshakeErrorMessage, R as MindooDBAppBridgeHostFocusChangedMessage, S as MindooDBAppBridgeLocaleChangedMessage, T as MindooDBAppBridgePortMessage, U as MindooDBAppBridgeQueryResultMessage, V as MindooDBAppBridgeRpcError, W as MindooDBAppBridgeRpcMessage, X as MindooDBAppBridgeRpcRequest, Y as MindooDBAppBridgeRpcSuccess, Z as MindooDBAppBridgeShortcutInvokedMessage, _ as MindooDBAppBridgeShortcutsChangedMessage, $ as MindooDBAppBridgeStreamAbortRequest, a0 as MindooDBAppBridgeStreamAck, a1 as MindooDBAppBridgeStreamCloseRequest, a2 as MindooDBAppBridgeStreamError, a3 as MindooDBAppBridgeStreamMessage, a4 as MindooDBAppBridgeStreamOpenResult, a5 as MindooDBAppBridgeStreamReadRequest, a6 as MindooDBAppBridgeStreamWriteRequest, a7 as MindooDBAppBridgeThemeChangedMessage, a8 as MindooDBAppBridgeUiPreferencesChangedMessage, a9 as MindooDBAppBridgeViewChangedMessage, aa as MindooDBAppBridgeViewportChangedMessage, ab as MindooDBAppBridgeWorkspaceFocusRequestedMessage, ac as MindooDBAppCapability, ad as MindooDBAppConfiguredViewCategorizationStyle, ae as MindooDBAppConfiguredViewColumn, af as MindooDBAppConfiguredViewColumnRole, ag as MindooDBAppConfiguredViewExpressionMode, ah as MindooDBAppConfiguredViewFieldExpression, ai as MindooDBAppConfiguredViewFilterDefinition, aj as MindooDBAppConfiguredViewFilterMode, ak as MindooDBAppConfiguredViewFilterRule, al as MindooDBAppConfiguredViewFormulaExpression, am as MindooDBAppConfiguredViewFormulaFilterDefinition, an as MindooDBAppConfiguredViewPreviewMode, ao as MindooDBAppConfiguredViewRuleFilterDefinition, ap as MindooDBAppConfiguredViewRuleMatchMode, aq as MindooDBAppConfiguredViewRuleOperator, ar as MindooDBAppConfiguredViewValueExpression, as as MindooDBAppCreateKeyInfo, at as MindooDBAppCreateViewInput, au as MindooDBAppCreateViewNavigatorInput, av as MindooDBAppDatabaseInfo, aw as MindooDBAppDefinition, ax as MindooDBAppDefinitionDatabase, ay as MindooDBAppDefinitionPermission, az as MindooDBAppDefinitionRegistrationPermission, aA as MindooDBAppDefinitionValidation, aB as MindooDBAppDirectoryApi, aC as MindooDBAppDirectoryEntry, aD as MindooDBAppDocumentApi, aE as MindooDBAppDocumentHeadCursorResult, aF as MindooDBAppDocumentHistoryEntry, aG as MindooDBAppDocumentListQuery, aH as MindooDBAppDocumentListResult, aI as MindooDBAppDocumentQuery, aJ as MindooDBAppDocumentRevisionId, aK as MindooDBAppDocumentScanPreset, aL as MindooDBAppDocumentSummary, aM as MindooDBAppDragApi, aN as MindooDBAppDragCancelReason, aO as MindooDBAppDragDropEvent, aP as MindooDBAppDragEffect, aQ as MindooDBAppDragHoverResult, aR as MindooDBAppDragOffer, aS as MindooDBAppDragOverEvent, aT as MindooDBAppDragPointer, aU as MindooDBAppDragProfile, aV as MindooDBAppEntryAttachmentRef, aW as MindooDBAppEntryProvenance, aX as MindooDBAppExtractDocumentTextInput, aY as MindooDBAppExtractDocumentTextResult, aZ as MindooDBAppExtractTextFormat, a_ as MindooDBAppExtractionSetup, a$ as MindooDBAppFulltextSetup, b0 as MindooDBAppHistoricalDocument, b1 as MindooDBAppHistoryQuery, b2 as MindooDBAppHostTheme, b3 as MindooDBAppIdentityApi, b4 as MindooDBAppInaccessibleDocument, b5 as MindooDBAppInaccessibleDocumentListQuery, b6 as MindooDBAppInaccessibleDocumentListResult, b7 as MindooDBAppJsonCounterIncrementPatch, b8 as MindooDBAppJsonListDeletePatch, b9 as MindooDBAppJsonListInsertPatch, ba as MindooDBAppJsonPatch, bb as MindooDBAppJsonSetPatch, bc as MindooDBAppJsonTextMarkPatch, bd as MindooDBAppJsonTextSplicePatch, be as MindooDBAppJsonTextUnmarkPatch, bf as MindooDBAppJsonUnsetPatch, bg as MindooDBAppLaunchContext, bh as MindooDBAppLiveQuerySubscription, bi as MindooDBAppMenuAnchor, bj as MindooDBAppMenuApi, bk as MindooDBAppMenuCommandItem, bl as MindooDBAppMenuDismissReason, bm as MindooDBAppMenuDismissedResult, bn as MindooDBAppMenuItem, bo as MindooDBAppMenuKind, bp as MindooDBAppMenuPlacement, bq as MindooDBAppMenuPointAnchor, br as MindooDBAppMenuRect, bs as MindooDBAppMenuRectAnchor, bt as MindooDBAppMenuSelectionResult, bu as MindooDBAppMenuSeparatorItem, bv as MindooDBAppNotificationSeverity, bw as MindooDBAppNotifyInput, bx as MindooDBAppNotifyResult, by as MindooDBAppProposeAppInput, bz as MindooDBAppProposeAppResult, bA as MindooDBAppQueryCoverage, bB as MindooDBAppQueryInclude, bC as MindooDBAppQueryIncludeCardinality, bD as MindooDBAppQueryIncludeSlots, bE as MindooDBAppQueryResult, bF as MindooDBAppQueryRow, bG as MindooDBAppQuerySortKey, bH as MindooDBAppQueryTextClause, bI as MindooDBAppReadableAttachmentStream, bJ as MindooDBAppRecipientOptions, bK as MindooDBAppResolvedViewDefinition, bL as MindooDBAppResolvedViewSource, bM as MindooDBAppRevisionPhase, bN as MindooDBAppRevisionVerification, bO as MindooDBAppRichTextBlockSpan, bP as MindooDBAppRichTextGetOptions, bQ as MindooDBAppRichTextImmutableString, bR as MindooDBAppRichTextMarkRange, bS as MindooDBAppRichTextMaterializeValue, bT as MindooDBAppRichTextPatch, bU as MindooDBAppRichTextScalar, bV as MindooDBAppRichTextSpliceStep, bW as MindooDBAppRichTextStep, bX as MindooDBAppRichTextStepPatch, bY as MindooDBAppRichTextTextSpan, bZ as MindooDBAppRuntime, b_ as MindooDBAppScanAttachmentOptions, b$ as MindooDBAppScanAttachmentResult, c0 as MindooDBAppScopedDocId, c1 as MindooDBAppScopedDocumentSummary, c2 as MindooDBAppSealIntent, c3 as MindooDBAppSealedChannelOpenInput, c4 as MindooDBAppSealedChannelOpenResult, c5 as MindooDBAppSealedChannelRequestInput, c6 as MindooDBAppSession, c7 as MindooDBAppShowMenuInput, c8 as MindooDBAppShowMenuResult, c9 as MindooDBAppSignPreview, ca as MindooDBAppSignPreviewScope, cb as MindooDBAppSignStatementInput, cc as MindooDBAppSignStatementResult, cd as MindooDBAppStorageApi, ce as MindooDBAppSummarySetup, cf as MindooDBAppTextCursorOptions, cg as MindooDBAppTextCursorPosition, ch as MindooDBAppTextCursorPositionsResult, ci as MindooDBAppTextCursorsResult, cj as MindooDBAppTextEdit, ck as MindooDBAppTextPatch, cl as MindooDBAppThemeMode, cm as MindooDBAppTimestampApi, cn as MindooDBAppTimestampInput, co as MindooDBAppTimestampProvider, cp as MindooDBAppTimestampResult, cq as MindooDBAppUiPreferences, cr as MindooDBAppUpdateDocumentInput, cs as MindooDBAppViewCursorDocumentListResult, ct as MindooDBAppViewCursorResult, cu as MindooDBAppViewEntry, cv as MindooDBAppViewEntryKind, cw as MindooDBAppViewNavigator, cx as MindooDBAppViewNavigatorExpansionState, cy as MindooDBAppViewNavigatorOpenOptions, cz as MindooDBAppViewNavigatorPageOptions, cA as MindooDBAppViewNavigatorPageResult, cB as MindooDBAppViewNavigatorRangeQuery, cC as MindooDBAppViewNavigatorSelectionState, cD as MindooDBAppViewUpdateStats, cE as MindooDBAppViewport, cF as MindooDBAppWellKnownDragType, cG as MindooDBAppWritableAttachmentStream, cH as resolveMindooDBAppDefinitionUrl, cI as validateMindooDBAppDefinition } from './types-BLyV6Ejy.js';
+import { M as MindooDBAppAttachmentPreviewMode, a as MindooDBAppDragBindSourceOptions, b as MindooDBAppDragStartInput, c as MindooDBAppDragStartResult, d as MindooDBAppDragPreview, e as MindooDBAppBridge, f as MindooDBAppHostShortcutBinding, g as MindooDBAppHostShortcutAction, h as MindooDBAppHostingMode, i as MindooDBAppDefinition, j as MindooDBAppDatabase, k as MindooDBAppDocument, l as MindooDBAppRichTextSpan, m as MindooDBAppRichTextSnapshot, n as MindooDBAppCreateDocumentInput } from './types-CX-o1Xyq.js';
+export { o as MINDOODB_APP_DEFINITION_FILE_NAME, p as MINDOODB_APP_DEFINITION_FORMAT, q as MINDOODB_APP_DEFINITION_PERMISSIONS, r as MINDOODB_APP_DEFINITION_REGISTRATION_PERMISSIONS, s as MINDOODB_APP_DEFINITION_VERSION, t as MINDOODB_APP_LISTING_DESCRIPTION_MAX, u as MINDOODB_APP_LISTING_MAX_SCREENSHOTS, v as MINDOODB_APP_LISTING_SUMMARY_MAX, w as MINDOODB_APP_SEAL_SIGNING_DOMAIN, x as MINDOODB_APP_WELL_KNOWN_DRAG_TYPES, y as MindooDBAppAccessDecision, z as MindooDBAppAccessTier, A as MindooDBAppAttachmentApi, B as MindooDBAppAttachmentChunk, C as MindooDBAppAttachmentInfo, D as MindooDBAppAttachmentPreviewOptions, E as MindooDBAppAttachmentPreviewSession, F as MindooDBAppAutomergeChangesPatch, G as MindooDBAppAutomergeChangesSince, H as MindooDBAppAutomergeGetOptions, I as MindooDBAppAutomergePatchResult, J as MindooDBAppAutomergeSnapshot, K as MindooDBAppBridgeBeforeCloseAck, L as MindooDBAppBridgeBeforeCloseMessage, N as MindooDBAppBridgeConnectMessage, O as MindooDBAppBridgeConnectOptions, P as MindooDBAppBridgeConnectedMessage, Q as MindooDBAppBridgeDragDropMessage, R as MindooDBAppBridgeDragLeaveMessage, S as MindooDBAppBridgeDragOverMessage, T as MindooDBAppBridgeErrorPayload, U as MindooDBAppBridgeHandshakeErrorMessage, V as MindooDBAppBridgeHostFocusChangedMessage, W as MindooDBAppBridgeLocaleChangedMessage, X as MindooDBAppBridgePortMessage, Y as MindooDBAppBridgeQueryResultMessage, Z as MindooDBAppBridgeRpcError, _ as MindooDBAppBridgeRpcMessage, $ as MindooDBAppBridgeRpcRequest, a0 as MindooDBAppBridgeRpcSuccess, a1 as MindooDBAppBridgeShortcutInvokedMessage, a2 as MindooDBAppBridgeShortcutsChangedMessage, a3 as MindooDBAppBridgeStreamAbortRequest, a4 as MindooDBAppBridgeStreamAck, a5 as MindooDBAppBridgeStreamCloseRequest, a6 as MindooDBAppBridgeStreamError, a7 as MindooDBAppBridgeStreamMessage, a8 as MindooDBAppBridgeStreamOpenResult, a9 as MindooDBAppBridgeStreamReadRequest, aa as MindooDBAppBridgeStreamWriteRequest, ab as MindooDBAppBridgeThemeChangedMessage, ac as MindooDBAppBridgeUiPreferencesChangedMessage, ad as MindooDBAppBridgeViewChangedMessage, ae as MindooDBAppBridgeViewportChangedMessage, af as MindooDBAppBridgeWorkspaceFocusRequestedMessage, ag as MindooDBAppCapability, ah as MindooDBAppConfiguredViewCategorizationStyle, ai as MindooDBAppConfiguredViewColumn, aj as MindooDBAppConfiguredViewColumnRole, ak as MindooDBAppConfiguredViewExpressionMode, al as MindooDBAppConfiguredViewFieldExpression, am as MindooDBAppConfiguredViewFilterDefinition, an as MindooDBAppConfiguredViewFilterMode, ao as MindooDBAppConfiguredViewFilterRule, ap as MindooDBAppConfiguredViewFormulaExpression, aq as MindooDBAppConfiguredViewFormulaFilterDefinition, ar as MindooDBAppConfiguredViewPreviewMode, as as MindooDBAppConfiguredViewRuleFilterDefinition, at as MindooDBAppConfiguredViewRuleMatchMode, au as MindooDBAppConfiguredViewRuleOperator, av as MindooDBAppConfiguredViewValueExpression, aw as MindooDBAppCreateKeyInfo, ax as MindooDBAppCreateViewInput, ay as MindooDBAppCreateViewNavigatorInput, az as MindooDBAppDatabaseInfo, aA as MindooDBAppDefinitionDatabase, aB as MindooDBAppDefinitionListing, aC as MindooDBAppDefinitionPermission, aD as MindooDBAppDefinitionRegistrationPermission, aE as MindooDBAppDefinitionScreenshot, aF as MindooDBAppDefinitionValidation, aG as MindooDBAppDirectoryApi, aH as MindooDBAppDirectoryEntry, aI as MindooDBAppDocumentApi, aJ as MindooDBAppDocumentHeadCursorResult, aK as MindooDBAppDocumentHistoryEntry, aL as MindooDBAppDocumentListQuery, aM as MindooDBAppDocumentListResult, aN as MindooDBAppDocumentQuery, aO as MindooDBAppDocumentRevisionId, aP as MindooDBAppDocumentScanPreset, aQ as MindooDBAppDocumentSummary, aR as MindooDBAppDragApi, aS as MindooDBAppDragCancelReason, aT as MindooDBAppDragDropEvent, aU as MindooDBAppDragEffect, aV as MindooDBAppDragHoverResult, aW as MindooDBAppDragOffer, aX as MindooDBAppDragOverEvent, aY as MindooDBAppDragPointer, aZ as MindooDBAppDragProfile, a_ as MindooDBAppEntryAttachmentRef, a$ as MindooDBAppEntryProvenance, b0 as MindooDBAppExtractDocumentTextInput, b1 as MindooDBAppExtractDocumentTextResult, b2 as MindooDBAppExtractTextFormat, b3 as MindooDBAppExtractionSetup, b4 as MindooDBAppFulltextSetup, b5 as MindooDBAppHistoricalDocument, b6 as MindooDBAppHistoryQuery, b7 as MindooDBAppHostTheme, b8 as MindooDBAppIdentityApi, b9 as MindooDBAppInaccessibleDocument, ba as MindooDBAppInaccessibleDocumentListQuery, bb as MindooDBAppInaccessibleDocumentListResult, bc as MindooDBAppJsonCounterIncrementPatch, bd as MindooDBAppJsonListDeletePatch, be as MindooDBAppJsonListInsertPatch, bf as MindooDBAppJsonPatch, bg as MindooDBAppJsonSetPatch, bh as MindooDBAppJsonTextMarkPatch, bi as MindooDBAppJsonTextSplicePatch, bj as MindooDBAppJsonTextUnmarkPatch, bk as MindooDBAppJsonUnsetPatch, bl as MindooDBAppLaunchContext, bm as MindooDBAppLiveQuerySubscription, bn as MindooDBAppLocalizedText, bo as MindooDBAppMenuAnchor, bp as MindooDBAppMenuApi, bq as MindooDBAppMenuCommandItem, br as MindooDBAppMenuDismissReason, bs as MindooDBAppMenuDismissedResult, bt as MindooDBAppMenuItem, bu as MindooDBAppMenuKind, bv as MindooDBAppMenuPlacement, bw as MindooDBAppMenuPointAnchor, bx as MindooDBAppMenuRect, by as MindooDBAppMenuRectAnchor, bz as MindooDBAppMenuSelectionResult, bA as MindooDBAppMenuSeparatorItem, bB as MindooDBAppNotificationSeverity, bC as MindooDBAppNotifyInput, bD as MindooDBAppNotifyResult, bE as MindooDBAppProposeAppInput, bF as MindooDBAppProposeAppResult, bG as MindooDBAppQueryCoverage, bH as MindooDBAppQueryInclude, bI as MindooDBAppQueryIncludeCardinality, bJ as MindooDBAppQueryIncludeSlots, bK as MindooDBAppQueryResult, bL as MindooDBAppQueryRow, bM as MindooDBAppQuerySortKey, bN as MindooDBAppQueryTextClause, bO as MindooDBAppReadableAttachmentStream, bP as MindooDBAppRecipientOptions, bQ as MindooDBAppResolvedViewDefinition, bR as MindooDBAppResolvedViewSource, bS as MindooDBAppRevisionPhase, bT as MindooDBAppRevisionVerification, bU as MindooDBAppRichTextBlockSpan, bV as MindooDBAppRichTextGetOptions, bW as MindooDBAppRichTextImmutableString, bX as MindooDBAppRichTextMarkRange, bY as MindooDBAppRichTextMaterializeValue, bZ as MindooDBAppRichTextPatch, b_ as MindooDBAppRichTextScalar, b$ as MindooDBAppRichTextSpliceStep, c0 as MindooDBAppRichTextStep, c1 as MindooDBAppRichTextStepPatch, c2 as MindooDBAppRichTextTextSpan, c3 as MindooDBAppRuntime, c4 as MindooDBAppScanAttachmentOptions, c5 as MindooDBAppScanAttachmentResult, c6 as MindooDBAppScopedDocId, c7 as MindooDBAppScopedDocumentSummary, c8 as MindooDBAppSealIntent, c9 as MindooDBAppSealedChannelOpenInput, ca as MindooDBAppSealedChannelOpenResult, cb as MindooDBAppSealedChannelRequestInput, cc as MindooDBAppSession, cd as MindooDBAppShowMenuInput, ce as MindooDBAppShowMenuResult, cf as MindooDBAppSignPreview, cg as MindooDBAppSignPreviewScope, ch as MindooDBAppSignStatementInput, ci as MindooDBAppSignStatementResult, cj as MindooDBAppStorageApi, ck as MindooDBAppSummarySetup, cl as MindooDBAppTextCursorOptions, cm as MindooDBAppTextCursorPosition, cn as MindooDBAppTextCursorPositionsResult, co as MindooDBAppTextCursorsResult, cp as MindooDBAppTextEdit, cq as MindooDBAppTextPatch, cr as MindooDBAppThemeMode, cs as MindooDBAppTimestampApi, ct as MindooDBAppTimestampInput, cu as MindooDBAppTimestampProvider, cv as MindooDBAppTimestampResult, cw as MindooDBAppUiPreferences, cx as MindooDBAppUpdateDocumentInput, cy as MindooDBAppViewCursorDocumentListResult, cz as MindooDBAppViewCursorResult, cA as MindooDBAppViewEntry, cB as MindooDBAppViewEntryKind, cC as MindooDBAppViewNavigator, cD as MindooDBAppViewNavigatorExpansionState, cE as MindooDBAppViewNavigatorOpenOptions, cF as MindooDBAppViewNavigatorPageOptions, cG as MindooDBAppViewNavigatorPageResult, cH as MindooDBAppViewNavigatorRangeQuery, cI as MindooDBAppViewNavigatorSelectionState, cJ as MindooDBAppViewUpdateStats, cK as MindooDBAppViewport, cL as MindooDBAppWellKnownDragType, cM as MindooDBAppWritableAttachmentStream, cN as resolveMindooDBAppDefinitionUrl, cO as resolveMindooDBAppListingAssetUrl, cP as resolveMindooDBAppLocalizedText, cQ as validateMindooDBAppDefinition } from './types-CX-o1Xyq.js';
 export { M as MINDOODB_APP_BUNDLE_ARCHIVE_FILE_NAME, a as MINDOODB_APP_BUNDLE_MANIFEST_FILE_NAME, b as MINDOODB_APP_BUNDLE_MANIFEST_FORMAT, c as MINDOODB_APP_BUNDLE_MANIFEST_VERSION, d as MindooDBAppBundleArchive, e as MindooDBAppBundleFileEntry, f as MindooDBAppBundleHash, g as MindooDBAppBundleManifest, h as MindooDBAppBundleManifestValidation, i as buildMindooDBAppBundleContentHashInput, j as isMindooDBAppBundleHash, n as normalizeMindooDBAppBundlePath, v as validateMindooDBAppBundleManifest } from './appBundleManifest-B0xfpaXG.js';
 import { MindooDBAppBooleanExpression } from 'mindoodb-view-language';
 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';
@@ -186,6 +186,10 @@ declare function sanitizeHostShortcutBindings(value: unknown): MindooDBAppHostSh
 /**
  * Stops wheel chaining out of a hosted app document into Haven's workspace
  * scroller once the app page (or its `body`) has reached its end.
+ *
+ * The root gets `none`, not `contain`: `contain` still lets iOS rubber-band
+ * the frame's own root scroller, so a drag on a non-scrollable area (a fixed
+ * dialog header, say) slides every fixed overlay in the app with the finger.
  */
 declare function applyHostedDocumentOverscrollContain(doc?: Document | undefined): void;
 /**
@@ -203,6 +207,28 @@ declare function installHostShortcutCapture(options: {
  * delivered before any asynchronous work has happened.
  */
 declare const MINDOODB_APP_HOSTING_QUERY_PARAM = "mindoodbAppHosting";
+/**
+ * Query parameter Haven appends to every app launch URL. The bridge handshake is keyed
+ * on it, so its absence means nobody launched this page.
+ */
+declare const MINDOODB_APP_LAUNCH_ID_QUERY_PARAM = "mindoodbAppLaunchId";
+/**
+ * Reads the launch id Haven put into the current URL, or `null` when there is none.
+ *
+ * @param search Optional query string, defaults to `window.location.search`.
+ */
+declare function readMindooDBAppLaunchId(search?: string): string | null;
+/**
+ * True when Haven (or a test host) launched this page, decided synchronously from the URL.
+ *
+ * Someone who opens the app's address directly — a link in an email, a shared URL — has
+ * no host to talk to. Branch on this before calling `connect()` and show a landing page
+ * instead (see `renderHavenAppLandingPage`), rather than letting the handshake time out
+ * into an error message.
+ *
+ * @param search Optional query string, defaults to `window.location.search`.
+ */
+declare function isLaunchedByHaven(search?: string): boolean;
 /**
  * Reads the hosting mode synchronously from the current URL.
  *
@@ -224,6 +250,109 @@ declare function readMindooDBAppHostingMode(search?: string): MindooDBAppHosting
  */
 declare function isHostedBundleRuntime(search?: string): boolean;
 
+/**
+ * The page an app shows when someone opens its address directly instead of launching it
+ * from Haven — a link in an email, a URL the App Builder printed.
+ *
+ * Without it that person gets a half-rendered app and "could not reach the Haven host".
+ * With it they get what the app is, taken from the `listing` in `haven-app.json`, and one
+ * button that opens Haven with `?app=<this app's URL>`: Haven then sets up a new
+ * environment with the app in it, or adds the app to the one that already exists.
+ *
+ * Framework-free on purpose: it runs before (and instead of) the app's own UI, so it must
+ * not pull the app's bundle into the first paint. Every publisher-supplied string goes in
+ * through `textContent`, never as markup.
+ */
+declare const DEFAULT_HAVEN_URL = "https://haven.mindoodb.com";
+interface RenderHavenAppLandingPageOptions {
+    /** Haven instance the button opens. Defaults to {@link DEFAULT_HAVEN_URL}. */
+    havenUrl?: string;
+    /**
+     * The app URL Haven installs from. Defaults to the current page without query, hash and
+     * a trailing `index.html` — the same URL that serves `haven-app.json`.
+     */
+    appUrl?: string;
+    /** Skips the fetch of `haven-app.json`, e.g. when the app bundles its definition. */
+    definition?: MindooDBAppDefinition;
+    /** Element the page renders into. Defaults to `document.body`, which is cleared. */
+    container?: HTMLElement;
+    /** Defaults to `navigator.language`. The page itself speaks English and German. */
+    locale?: string;
+}
+interface HavenAppLandingPage {
+    /** The definition shown, or `null` when `haven-app.json` could not be read. */
+    definition: MindooDBAppDefinition | null;
+    /** The Haven link behind the main button. */
+    installUrl: string;
+}
+/** The current page as the app URL: no query, no hash, no trailing `index.html`. */
+declare function resolveCurrentHavenAppUrl(href?: string): string;
+/** `https://haven.mindoodb.com/?app=<appUrl>` — the link that installs `appUrl`. */
+declare function buildHavenAppInstallUrl(appUrl: string, havenUrl?: string): string;
+/**
+ * Replaces the page with the app's landing page. Call it instead of mounting the app
+ * when {@link isLaunchedByHaven} is `false`.
+ */
+declare function renderHavenAppLandingPage(options?: RenderHavenAppLandingPageOptions): Promise<HavenAppLandingPage>;
+
+/**
+ * The Markdown subset a publisher may use in `listing.descriptionMarkdown`.
+ *
+ * The text comes from a file on the publisher's server and is shown before anyone has
+ * agreed to install the app, so it is parsed into a small tree here and rendered with
+ * `createElement`/`textContent` (or Vue render functions) — never as HTML. What the
+ * subset knows:
+ *
+ * - paragraphs (blank lines), headings (`#`), bullet (`-`, `*`, `+`) and numbered lists
+ * - `**bold**`, `__bold__`, `*italic*`, `_italic_`, `` `code` ``, `\` escapes
+ * - `[text](https://…)`, `[text](mailto:…)` and bare `https://…` links
+ *
+ * Anything else stays literal text. Links are limited to `https:` and `mailto:` by
+ * {@link sanitizeListingHref}; a link with any other target renders as its text only.
+ *
+ * DOM-free on purpose, so Haven, the landing page and build scripts can share it.
+ */
+type ListingInline = {
+    type: "text";
+    text: string;
+} | {
+    type: "code";
+    text: string;
+} | {
+    type: "strong";
+    children: ListingInline[];
+} | {
+    type: "em";
+    children: ListingInline[];
+} | {
+    type: "link";
+    href: string;
+    children: ListingInline[];
+};
+type ListingBlock = {
+    type: "paragraph";
+    children: ListingInline[];
+} | {
+    type: "heading";
+    children: ListingInline[];
+} | {
+    type: "list";
+    ordered: boolean;
+    items: ListingInline[][];
+};
+/**
+ * `https:` and `mailto:` only. Embedded tab/LF/CR are stripped first, as browsers do,
+ * so `java\nscript:` cannot slip past the scheme check.
+ */
+declare function sanitizeListingHref(raw: string): string | null;
+/** Parses a description into blocks. Unknown syntax stays text; nothing is dropped. */
+declare function parseListingMarkdown(markdown: string): ListingBlock[];
+/**
+ * The same text for readers that only show plain paragraphs (`listing.description`):
+ * one paragraph per block and per list item, links as "text (url)".
+ */
+declare function listingMarkdownToPlainText(markdown: string): string;
+
 interface InstallHavenStorageShimOptions {
     /**
      * Key prefixes whose values are written through to the host and restored on the next
@@ -430,4 +559,4 @@ declare function inheritDocumentEncryption(parent: Pick<MindooDBAppDocument, "de
  */
 declare function watchWordChunks(database: MindooDBAppDatabase, parentId: string, listener: (docIds: string[]) => void): Promise<() => Promise<void>>;
 
-export { type CreateMindooDBRichTextHandleOptions, type CreateMindooDBTextBufferOptions, DEFAULT_DRAG_LONG_PRESS_MS, DEFAULT_DRAG_POINTER_THRESHOLD_PX, DEFAULT_HAVEN_HOST_SHORTCUTS, type HavenStorageShimHandle, type InstallHavenStorageShimOptions, MINDOODB_APP_HOSTING_QUERY_PARAM, MINDOODB_APP_MAX_DRAG_PAYLOAD_BYTES, MINDOODB_APP_MAX_DRAG_PREVIEW_BYTES, MINDOODB_APP_MAX_DRAG_PREVIEW_EDGE, MINDOODB_APP_MAX_DRAG_TYPES, MINDOODB_APP_VALUE_TAG, MINIMAL_DRAG_PREVIEW_PNG, type MindooDBAppAtomicValue, MindooDBAppAttachmentPreviewMode, MindooDBAppBridge, type MindooDBAppCounterValue, MindooDBAppCreateDocumentInput, MindooDBAppDatabase, MindooDBAppDocument, MindooDBAppDragBindSourceOptions, MindooDBAppDragInputError, MindooDBAppDragPreview, MindooDBAppDragStartInput, MindooDBAppDragStartResult, MindooDBAppHostShortcutAction, MindooDBAppHostShortcutBinding, MindooDBAppHostingMode, MindooDBAppRichTextSnapshot, MindooDBAppRichTextSpan, type MindooDBAppTimestampValue, type MindooDBAppTypedValue, MindooDBAppValue, MindooDBRichTextHandle, type MindooDBRichTextHandleChangeListener, type MindooDBRichTextHandleFlushResult, MindooDBTextBuffer, type MindooDBTextBufferFlushResult, abbreviateCanonicalName, applyHostedDocumentOverscrollContain, bindDragSource, canPreviewAttachment, createMindooDBAppBridge, createMindooDBRichTextHandle, createMindooDBTextBuffer, expandAbbreviatedName, inheritDocumentEncryption, installHavenStorageShim, installHostShortcutCapture, isHostShortcutAction, isHostedBundleRuntime, isMindooDBAppDragType, matchHostShortcut, normalizeDragAccepts, normalizeDragPointerInput, normalizeDragStartInput, queryDocuments, readMindooDBAppHostingMode, releaseMindooDBAppBridgeSessions, sanitizeHostShortcutBindings, snapshotElementToPng, watchWordChunks };
+export { type CreateMindooDBRichTextHandleOptions, type CreateMindooDBTextBufferOptions, DEFAULT_DRAG_LONG_PRESS_MS, DEFAULT_DRAG_POINTER_THRESHOLD_PX, DEFAULT_HAVEN_HOST_SHORTCUTS, DEFAULT_HAVEN_URL, type HavenAppLandingPage, type HavenStorageShimHandle, type InstallHavenStorageShimOptions, type ListingBlock, type ListingInline, MINDOODB_APP_HOSTING_QUERY_PARAM, MINDOODB_APP_LAUNCH_ID_QUERY_PARAM, MINDOODB_APP_MAX_DRAG_PAYLOAD_BYTES, MINDOODB_APP_MAX_DRAG_PREVIEW_BYTES, MINDOODB_APP_MAX_DRAG_PREVIEW_EDGE, MINDOODB_APP_MAX_DRAG_TYPES, MINDOODB_APP_VALUE_TAG, MINIMAL_DRAG_PREVIEW_PNG, type MindooDBAppAtomicValue, MindooDBAppAttachmentPreviewMode, MindooDBAppBridge, type MindooDBAppCounterValue, MindooDBAppCreateDocumentInput, MindooDBAppDatabase, MindooDBAppDefinition, MindooDBAppDocument, MindooDBAppDragBindSourceOptions, MindooDBAppDragInputError, MindooDBAppDragPreview, MindooDBAppDragStartInput, MindooDBAppDragStartResult, MindooDBAppHostShortcutAction, MindooDBAppHostShortcutBinding, MindooDBAppHostingMode, MindooDBAppRichTextSnapshot, MindooDBAppRichTextSpan, type MindooDBAppTimestampValue, type MindooDBAppTypedValue, MindooDBAppValue, MindooDBRichTextHandle, type MindooDBRichTextHandleChangeListener, type MindooDBRichTextHandleFlushResult, MindooDBTextBuffer, type MindooDBTextBufferFlushResult, type RenderHavenAppLandingPageOptions, abbreviateCanonicalName, applyHostedDocumentOverscrollContain, bindDragSource, buildHavenAppInstallUrl, canPreviewAttachment, createMindooDBAppBridge, createMindooDBRichTextHandle, createMindooDBTextBuffer, expandAbbreviatedName, inheritDocumentEncryption, installHavenStorageShim, installHostShortcutCapture, isHostShortcutAction, isHostedBundleRuntime, isLaunchedByHaven, isMindooDBAppDragType, listingMarkdownToPlainText, matchHostShortcut, normalizeDragAccepts, normalizeDragPointerInput, normalizeDragStartInput, parseListingMarkdown, queryDocuments, readMindooDBAppHostingMode, readMindooDBAppLaunchId, releaseMindooDBAppBridgeSessions, renderHavenAppLandingPage, resolveCurrentHavenAppUrl, sanitizeHostShortcutBindings, sanitizeListingHref, snapshotElementToPng, watchWordChunks };