mindoodb-app-sdk 0.0.51 → 0.0.53

package/dist/index.js

@@ -23,7 +23,7 @@ import {
   releaseMindooDBAppBridgeSessions,
   sanitizeHostShortcutBindings,
   snapshotElementToPng
-} from "./chunk-R76XXRJ6.js";
+} from "./chunk-6NTVTL6G.js";
 import {
   MINDOODB_APP_BUNDLE_ARCHIVE_FILE_NAME,
   MINDOODB_APP_BUNDLE_MANIFEST_FILE_NAME,
@@ -61,6 +61,9 @@ var MINDOODB_APP_DEFINITION_PERMISSIONS = [
   "proposeapps"
 ];
 var MINDOODB_APP_DEFINITION_REGISTRATION_PERMISSIONS = ["proposeapps"];
+var MINDOODB_APP_LISTING_SUMMARY_MAX = 300;
+var MINDOODB_APP_LISTING_DESCRIPTION_MAX = 4e3;
+var MINDOODB_APP_LISTING_MAX_SCREENSHOTS = 8;
 var LOGICAL_DATABASE_ID_PATTERN = /^[a-z0-9][a-z0-9._-]*$/i;
 function isPlainObject(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
@@ -200,6 +203,156 @@ function readDatabases(value, errors) {
   });
   return result.length ? result : void 0;
 }
+function readLocalizedText(value, label, maxLength, errors) {
+  if (value === void 0 || value === null) {
+    return void 0;
+  }
+  if (typeof value === "string") {
+    const trimmed = value.trim();
+    if (trimmed.length > maxLength) {
+      errors.push(`${label} must not be longer than ${maxLength} characters.`);
+      return void 0;
+    }
+    return trimmed || void 0;
+  }
+  if (!isPlainObject(value)) {
+    errors.push(`${label} must be a string or an object of per-locale strings.`);
+    return void 0;
+  }
+  const result = {};
+  for (const [locale, text] of Object.entries(value)) {
+    if (typeof text !== "string") {
+      errors.push(`${label}.${locale} must be a string.`);
+      continue;
+    }
+    const trimmed = text.trim();
+    if (trimmed.length > maxLength) {
+      errors.push(`${label}.${locale} must not be longer than ${maxLength} characters.`);
+      continue;
+    }
+    if (trimmed) {
+      result[locale] = trimmed;
+    }
+  }
+  if (!Object.keys(result).length) {
+    return void 0;
+  }
+  if (!result.en) {
+    errors.push(`${label} must include an "en" entry as the fallback for other locales.`);
+    return void 0;
+  }
+  return result;
+}
+function readListingAssetPath(value, label, errors) {
+  if (value === void 0 || value === null) {
+    return void 0;
+  }
+  if (typeof value !== "string" || !value.trim()) {
+    errors.push(`${label} must be a non-empty string.`);
+    return void 0;
+  }
+  const trimmed = value.trim();
+  const scheme = /^([a-z][a-z0-9+.-]*):/i.exec(trimmed)?.[1]?.toLowerCase();
+  if (scheme && scheme !== "https") {
+    errors.push(`${label} must be a path on the app origin or an https: URL.`);
+    return void 0;
+  }
+  if (trimmed.startsWith("//")) {
+    errors.push(`${label} must be a path on the app origin or an https: URL.`);
+    return void 0;
+  }
+  return trimmed;
+}
+function readListing(value, errors) {
+  if (value === void 0 || value === null) {
+    return void 0;
+  }
+  if (!isPlainObject(value)) {
+    errors.push("App definition listing must be an object.");
+    return void 0;
+  }
+  const listing = {};
+  const summary = readLocalizedText(
+    value.summary,
+    "App definition listing.summary",
+    MINDOODB_APP_LISTING_SUMMARY_MAX,
+    errors
+  );
+  if (summary) listing.summary = summary;
+  const description = readLocalizedText(
+    value.description,
+    "App definition listing.description",
+    MINDOODB_APP_LISTING_DESCRIPTION_MAX,
+    errors
+  );
+  if (description) listing.description = description;
+  const icon = readListingAssetPath(value.icon, "App definition listing.icon", errors);
+  if (icon) listing.icon = icon;
+  if (value.screenshots !== void 0 && value.screenshots !== null) {
+    if (!Array.isArray(value.screenshots)) {
+      errors.push("App definition listing.screenshots must be an array.");
+    } else if (value.screenshots.length > MINDOODB_APP_LISTING_MAX_SCREENSHOTS) {
+      errors.push(
+        `App definition listing.screenshots must not list more than ${MINDOODB_APP_LISTING_MAX_SCREENSHOTS} images.`
+      );
+    } else {
+      const screenshots = [];
+      value.screenshots.forEach((entry, index) => {
+        const label = `App definition listing.screenshots[${index}]`;
+        const raw = typeof entry === "string" ? { file: entry } : entry;
+        if (!isPlainObject(raw)) {
+          errors.push(`${label} must be a path or an object with a file.`);
+          return;
+        }
+        const file = readListingAssetPath(raw.file, `${label}.file`, errors);
+        if (!file) {
+          return;
+        }
+        const caption = readLocalizedText(raw.caption, `${label}.caption`, MINDOODB_APP_LISTING_SUMMARY_MAX, errors);
+        screenshots.push(caption ? { file, caption } : { file });
+      });
+      if (screenshots.length) listing.screenshots = screenshots;
+    }
+  }
+  if (value.publisher !== void 0 && value.publisher !== null) {
+    const publisher = isPlainObject(value.publisher) ? value.publisher : {};
+    const name = typeof publisher.name === "string" ? publisher.name.trim() : "";
+    if (!name) {
+      errors.push("App definition listing.publisher must be an object with a non-empty name.");
+    } else {
+      const url = readListingAssetPath(publisher.url, "App definition listing.publisher.url", errors);
+      if (url && !/^https:\/\//i.test(url)) {
+        errors.push("App definition listing.publisher.url must be an absolute https: URL.");
+      } else {
+        listing.publisher = url ? { name, url } : { name };
+      }
+    }
+  }
+  return Object.keys(listing).length ? listing : void 0;
+}
+function resolveMindooDBAppLocalizedText(text, locale) {
+  if (text === void 0) {
+    return "";
+  }
+  if (typeof text === "string") {
+    return text;
+  }
+  const normalized = locale.trim();
+  const language = normalized.split(/[-_]/)[0]?.toLowerCase() ?? "";
+  return text[normalized] ?? text[normalized.toLowerCase()] ?? (language ? text[language] : void 0) ?? text.en;
+}
+function resolveMindooDBAppListingAssetUrl(path, originUrl) {
+  try {
+    const base = new URL(originUrl.endsWith("/") ? originUrl : `${originUrl}/`);
+    const resolved = new URL(path, base);
+    if (resolved.protocol !== "https:" && resolved.protocol !== base.protocol) {
+      return null;
+    }
+    return resolved.toString();
+  } catch {
+    return null;
+  }
+}
 function validateMindooDBAppDefinition(raw) {
   const errors = [];
   if (!isPlainObject(raw)) {
@@ -251,6 +404,7 @@ function validateMindooDBAppDefinition(raw) {
   const allowGeolocation = readOptionalBoolean(raw, "allowGeolocation", errors);
   const allowWebRtc = readOptionalBoolean(raw, "allowWebRtc", errors);
   const allowWorkers = readOptionalBoolean(raw, "allowWorkers", errors);
+  const listing = readListing(raw.listing, errors);
   if (defaultLaunchDatabaseId && databases && !databases.some((database) => database.logicalDatabaseId === defaultLaunchDatabaseId)) {
     errors.push(
       `App definition defaultLaunchDatabaseId "${defaultLaunchDatabaseId}" is not one of the declared databases.`
@@ -279,7 +433,8 @@ function validateMindooDBAppDefinition(raw) {
       permissions,
       launchParameters,
       defaultLaunchDatabaseId,
-      databases
+      databases,
+      listing
     },
     errors: []
   };
@@ -389,6 +544,22 @@ function expandAbbreviatedName(value) {
 
 // src/client/hosting.ts
 var MINDOODB_APP_HOSTING_QUERY_PARAM = "mindoodbAppHosting";
+var MINDOODB_APP_LAUNCH_ID_QUERY_PARAM = "mindoodbAppLaunchId";
+function readMindooDBAppLaunchId(search) {
+  const raw = search ?? (typeof window === "undefined" ? "" : window.location.search);
+  if (!raw) {
+    return null;
+  }
+  try {
+    const launchId = new URLSearchParams(raw).get(MINDOODB_APP_LAUNCH_ID_QUERY_PARAM)?.trim();
+    return launchId || null;
+  } catch {
+    return null;
+  }
+}
+function isLaunchedByHaven(search) {
+  return readMindooDBAppLaunchId(search) !== null;
+}
 function readMindooDBAppHostingMode(search) {
   const raw = search ?? (typeof window === "undefined" ? "" : window.location.search);
   if (!raw) {
@@ -404,6 +575,195 @@ function isHostedBundleRuntime(search) {
   return readMindooDBAppHostingMode(search) === "hosted";
 }
 
+// src/landing.ts
+var DEFAULT_HAVEN_URL = "https://haven.mindoodb.com";
+var APP_ICON_FALLBACKS = ["appicon.png", "appicon.webp", "appicon.svg"];
+var STRINGS = {
+  en: {
+    eyebrow: "App for MindooDB Haven",
+    cta: "Open in MindooDB Haven",
+    ctaHint: "Haven sets up your encrypted workspace and installs {label}. Already using Haven? Then the app is simply added.",
+    from: "from {origin}",
+    by: "by {publisher}",
+    screenshots: "Screenshots",
+    footer: "{label} runs inside MindooDB Haven, which keeps its data end-to-end encrypted and local-first. Opening this address on its own shows only this page.",
+    learnMore: "What is MindooDB?",
+    fallbackSummary: "This app runs inside MindooDB Haven."
+  },
+  de: {
+    eyebrow: "App f\xFCr MindooDB Haven",
+    cta: "In MindooDB Haven \xF6ffnen",
+    ctaHint: "Haven richtet deine verschl\xFCsselte Umgebung ein und installiert {label}. Du nutzt Haven schon? Dann wird die App einfach hinzugef\xFCgt.",
+    from: "von {origin}",
+    by: "von {publisher}",
+    screenshots: "Screenshots",
+    footer: "{label} l\xE4uft in MindooDB Haven, das ihre Daten Ende-zu-Ende-verschl\xFCsselt und lokal h\xE4lt. Direkt aufgerufen zeigt diese Adresse nur diese Seite.",
+    learnMore: "Was ist MindooDB?",
+    fallbackSummary: "Diese App l\xE4uft in MindooDB Haven."
+  }
+};
+function stringsFor(locale) {
+  return locale.toLowerCase().startsWith("de") ? STRINGS.de : STRINGS.en;
+}
+function format(template, values) {
+  return template.replace(/\{(\w+)\}/g, (match, key) => values[key] ?? match);
+}
+function resolveCurrentHavenAppUrl(href = window.location.href) {
+  const url = new URL(href);
+  url.search = "";
+  url.hash = "";
+  url.pathname = url.pathname.replace(/\/index\.html?$/i, "/");
+  return url.toString();
+}
+function buildHavenAppInstallUrl(appUrl, havenUrl = DEFAULT_HAVEN_URL) {
+  const url = new URL(havenUrl);
+  url.searchParams.set("app", appUrl);
+  return url.toString();
+}
+async function loadDefinition(appUrl) {
+  try {
+    const definitionUrl = new URL(MINDOODB_APP_DEFINITION_FILE_NAME, appUrl.endsWith("/") ? appUrl : `${appUrl}/`);
+    const response = await fetch(definitionUrl, { headers: { Accept: "application/json" } });
+    if (!response.ok) {
+      return null;
+    }
+    return validateMindooDBAppDefinition(await response.json()).definition;
+  } catch {
+    return null;
+  }
+}
+function el(tag, className, text) {
+  const node = document.createElement(tag);
+  if (className) node.className = className;
+  if (text !== void 0) node.textContent = text;
+  return node;
+}
+var STYLE_ID = "mdb-landing-style";
+var STYLE = `
+.mdb-landing{--bg:#f4f6fb;--card:#fff;--text:#172033;--muted:#5b6478;--line:#e2e6ef;--accent:#1f3a8a;--accent-text:#fff;
+  min-height:100vh;box-sizing:border-box;margin:0;padding:48px 16px;background:var(--bg);color:var(--text);
+  font:16px/1.55 system-ui,-apple-system,"Segoe UI",Roboto,sans-serif}
+@media (prefers-color-scheme:dark){.mdb-landing{--bg:#0e1320;--card:#161d2e;--text:#e8ecf5;--muted:#9aa3b8;--line:#263049;--accent:#8fb0ff;--accent-text:#0e1320}}
+.mdb-landing *{box-sizing:border-box}
+.mdb-landing__card{max-width:880px;margin:0 auto;background:var(--card);border:1px solid var(--line);border-radius:24px;padding:40px;box-shadow:0 20px 60px rgba(15,23,42,.08)}
+.mdb-landing__head{display:flex;gap:24px;align-items:center}
+.mdb-landing__icon{width:96px;height:96px;border-radius:22px;object-fit:cover;flex:none;box-shadow:0 10px 30px rgba(15,23,42,.18)}
+.mdb-landing__eyebrow{margin:0 0 4px;font-size:12px;letter-spacing:.12em;text-transform:uppercase;color:var(--muted)}
+.mdb-landing__title{margin:0;font-size:clamp(26px,4vw,36px);line-height:1.15}
+.mdb-landing__meta{margin:6px 0 0;color:var(--muted);font-size:14px}
+.mdb-landing__summary{margin:28px 0 0;font-size:19px}
+.mdb-landing__cta{display:flex;flex-wrap:wrap;gap:16px;align-items:center;margin:28px 0 0}
+.mdb-landing__button{display:inline-block;padding:14px 22px;border-radius:12px;background:var(--accent);color:var(--accent-text);font-weight:600;text-decoration:none}
+.mdb-landing__button:focus-visible{outline:3px solid var(--accent);outline-offset:3px}
+.mdb-landing__hint{margin:0;max-width:420px;color:var(--muted);font-size:14px}
+.mdb-landing__description{margin:32px 0 0}
+.mdb-landing__description p{margin:0 0 12px}
+.mdb-landing__shots-title{margin:32px 0 12px;font-size:15px;color:var(--muted);font-weight:600}
+.mdb-landing__shots{display:grid;grid-auto-flow:column;grid-auto-columns:min(78%,420px);gap:16px;overflow-x:auto;padding-bottom:8px;scroll-snap-type:x mandatory}
+.mdb-landing__shot{margin:0;scroll-snap-align:start}
+.mdb-landing__shot img{width:100%;border-radius:14px;border:1px solid var(--line);display:block}
+.mdb-landing__shot figcaption{margin-top:8px;font-size:13px;color:var(--muted)}
+.mdb-landing__footer{margin:36px 0 0;padding-top:20px;border-top:1px solid var(--line);color:var(--muted);font-size:13px}
+.mdb-landing__footer a{color:inherit}
+@media (max-width:560px){.mdb-landing{padding:16px}.mdb-landing__card{padding:24px;border-radius:18px}.mdb-landing__head{flex-direction:column;align-items:flex-start}.mdb-landing__icon{width:72px;height:72px}}
+`;
+async function renderHavenAppLandingPage(options = {}) {
+  const appUrl = options.appUrl ?? resolveCurrentHavenAppUrl();
+  const locale = options.locale ?? (typeof navigator === "undefined" ? "en" : navigator.language || "en");
+  const strings = stringsFor(locale);
+  const definition = options.definition ?? await loadDefinition(appUrl);
+  const installUrl = buildHavenAppInstallUrl(appUrl, options.havenUrl);
+  const listing = definition?.listing;
+  const label = definition?.label ?? (document.title || new URL(appUrl).host);
+  const origin = new URL(appUrl).host;
+  if (!document.getElementById(STYLE_ID)) {
+    const style = el("style");
+    style.id = STYLE_ID;
+    style.textContent = STYLE;
+    document.head.append(style);
+  }
+  document.title = label;
+  const root = el("main", "mdb-landing");
+  root.dataset.testid = "haven-app-landing";
+  const card = el("article", "mdb-landing__card");
+  root.append(card);
+  const head = el("header", "mdb-landing__head");
+  const iconCandidates = (listing?.icon ? [listing.icon] : [...APP_ICON_FALLBACKS]).map((path) => resolveMindooDBAppListingAssetUrl(path, appUrl)).filter((url) => Boolean(url));
+  if (iconCandidates.length) {
+    const icon = el("img", "mdb-landing__icon");
+    let next = 0;
+    icon.alt = "";
+    icon.addEventListener("error", () => {
+      next += 1;
+      if (next < iconCandidates.length) {
+        icon.src = iconCandidates[next];
+      } else {
+        icon.remove();
+      }
+    });
+    icon.src = iconCandidates[0];
+    head.append(icon);
+  }
+  const titles = el("div");
+  titles.append(el("p", "mdb-landing__eyebrow", strings.eyebrow), el("h1", "mdb-landing__title", label));
+  const meta = [format(strings.from, { origin })];
+  if (listing?.publisher) {
+    meta.unshift(format(strings.by, { publisher: listing.publisher.name }));
+  }
+  titles.append(el("p", "mdb-landing__meta", meta.join(" \xB7 ")));
+  head.append(titles);
+  card.append(head);
+  const summary = resolveMindooDBAppLocalizedText(listing?.summary, locale) || definition?.description || strings.fallbackSummary;
+  card.append(el("p", "mdb-landing__summary", summary));
+  const cta = el("div", "mdb-landing__cta");
+  const button = el("a", "mdb-landing__button", strings.cta);
+  button.href = installUrl;
+  button.rel = "noopener";
+  button.dataset.testid = "haven-app-landing-install";
+  cta.append(button, el("p", "mdb-landing__hint", format(strings.ctaHint, { label })));
+  card.append(cta);
+  const description = resolveMindooDBAppLocalizedText(listing?.description, locale);
+  if (description) {
+    const block = el("section", "mdb-landing__description");
+    for (const paragraph of description.split(/\n\s*\n/)) {
+      if (paragraph.trim()) block.append(el("p", void 0, paragraph.trim()));
+    }
+    card.append(block);
+  }
+  const screenshots = (listing?.screenshots ?? []).map((shot) => ({
+    url: resolveMindooDBAppListingAssetUrl(shot.file, appUrl),
+    caption: resolveMindooDBAppLocalizedText(shot.caption, locale)
+  })).filter((shot) => Boolean(shot.url));
+  if (screenshots.length) {
+    card.append(el("h2", "mdb-landing__shots-title", strings.screenshots));
+    const strip = el("div", "mdb-landing__shots");
+    for (const shot of screenshots) {
+      const figure = el("figure", "mdb-landing__shot");
+      const image = el("img");
+      image.src = shot.url;
+      image.alt = shot.caption;
+      image.loading = "lazy";
+      figure.append(image);
+      if (shot.caption) figure.append(el("figcaption", void 0, shot.caption));
+      strip.append(figure);
+    }
+    card.append(strip);
+  }
+  const footer = el("footer", "mdb-landing__footer");
+  footer.append(format(strings.footer, { label }), " ");
+  const learnMore = el("a", void 0, strings.learnMore);
+  learnMore.href = "https://mindoodb.com";
+  learnMore.rel = "noopener";
+  footer.append(learnMore);
+  card.append(footer);
+  const container = options.container ?? document.body;
+  container.replaceChildren(root);
+  if (container === document.body) {
+    document.body.style.margin = "0";
+  }
+  return { definition, installUrl };
+}
+
 // src/client/havenStorageShim.ts
 var DEFAULT_QUOTA_BYTES = 256 * 1024;
 var DEFAULT_MAX_VALUE_BYTES = 64 * 1024;
@@ -731,11 +1091,11 @@ var MindooDBRichTextHandle = class {
       this.pollTimer = null;
     }
   }
-  reconcile(document, snapshot) {
+  reconcile(document2, snapshot) {
     const previous = JSON.stringify(this.spansInternal);
     this.spansInternal = cloneSpans(snapshot.spans);
     this.baseMaterializedText = spansToPlainText(snapshot.spans);
-    this.heads = snapshot.heads ?? document.heads ?? [];
+    this.heads = snapshot.heads ?? document2.heads ?? [];
     this.dirtyInternal = false;
     const changed = JSON.stringify(this.spansInternal) !== previous;
     if (changed) {
@@ -754,14 +1114,14 @@ var MindooDBRichTextHandle = class {
     if (this.dirtyInternal) {
       return false;
     }
-    const document = await this.options.database.documents.get(
+    const document2 = await this.options.database.documents.get(
       this.options.document.id
     );
-    if (!document) {
+    if (!document2) {
       return false;
     }
     const snapshot = await this.refresh();
-    return this.reconcile(document, snapshot);
+    return this.reconcile(document2, snapshot);
   }
   async flush(updateSpansConfig) {
     if (!this.dirtyInternal) {
@@ -778,7 +1138,7 @@ var MindooDBRichTextHandle = class {
     const localSpansAtFlush = cloneSpans(this.spansInternal);
     const localTextAtFlush = spansToPlainText(localSpansAtFlush);
     const textChanged = localTextAtFlush !== this.baseMaterializedText;
-    const document = textChanged ? await this.flushTextSteps(localTextAtFlush) : await this.options.database.documents.update(
+    const document2 = textChanged ? await this.flushTextSteps(localTextAtFlush) : await this.options.database.documents.update(
       this.options.document.id,
       {
         richText: [{
@@ -796,13 +1156,13 @@ var MindooDBRichTextHandle = class {
     const reconciled = JSON.stringify(snapshot.spans) !== JSON.stringify(localSpansAtFlush);
     this.spansInternal = cloneSpans(snapshot.spans);
     this.baseMaterializedText = spansToPlainText(snapshot.spans);
-    this.heads = snapshot.heads ?? document.heads ?? [];
+    this.heads = snapshot.heads ?? document2.heads ?? [];
     this.dirtyInternal = false;
     if (reconciled) {
       this.emitChange();
     }
     return {
-      document,
+      document: document2,
       snapshot,
       reconciled
     };
@@ -940,11 +1300,11 @@ var MindooDBTextBuffer = class {
    * Returns whether the text value changed. Use this after an external refresh
    * or after receiving a document update through another app-level mechanism.
    */
-  reconcile(document) {
-    const nextValue = readTextAtPath(document.data, this.options.path);
+  reconcile(document2) {
+    const nextValue = readTextAtPath(document2.data, this.options.path);
     const changed = nextValue !== this.valueInternal;
     this.valueInternal = nextValue;
-    this.heads = document.heads ? [...document.heads] : [];
+    this.heads = document2.heads ? [...document2.heads] : [];
     this.pendingEdits = [];
     return changed;
   }
@@ -966,20 +1326,20 @@ var MindooDBTextBuffer = class {
       };
     }
     const localValueAtFlush = this.valueInternal;
-    const document = await this.options.database.documents.update(this.options.document.id, {
+    const document2 = await this.options.database.documents.update(this.options.document.id, {
       text: [{
         path: this.options.path,
         baseHeads: this.heads,
         edits: this.pendingEdits.map((edit) => ({ ...edit }))
       }]
     });
-    const nextValue = readTextAtPath(document.data, this.options.path);
+    const nextValue = readTextAtPath(document2.data, this.options.path);
     const reconciled = nextValue !== localValueAtFlush;
     this.valueInternal = nextValue;
-    this.heads = document.heads ? [...document.heads] : [];
+    this.heads = document2.heads ? [...document2.heads] : [];
     this.pendingEdits = [];
     return {
-      document,
+      document: document2,
       value: this.valueInternal,
       reconciled
     };
@@ -1055,6 +1415,7 @@ export {
   DEFAULT_DRAG_LONG_PRESS_MS,
   DEFAULT_DRAG_POINTER_THRESHOLD_PX,
   DEFAULT_HAVEN_HOST_SHORTCUTS,
+  DEFAULT_HAVEN_URL,
   MINDOODB_APP_BUNDLE_ARCHIVE_FILE_NAME,
   MINDOODB_APP_BUNDLE_MANIFEST_FILE_NAME,
   MINDOODB_APP_BUNDLE_MANIFEST_FORMAT,
@@ -1065,6 +1426,10 @@ export {
   MINDOODB_APP_DEFINITION_REGISTRATION_PERMISSIONS,
   MINDOODB_APP_DEFINITION_VERSION,
   MINDOODB_APP_HOSTING_QUERY_PARAM,
+  MINDOODB_APP_LAUNCH_ID_QUERY_PARAM,
+  MINDOODB_APP_LISTING_DESCRIPTION_MAX,
+  MINDOODB_APP_LISTING_MAX_SCREENSHOTS,
+  MINDOODB_APP_LISTING_SUMMARY_MAX,
   MINDOODB_APP_MAX_DRAG_PAYLOAD_BYTES,
   MINDOODB_APP_MAX_DRAG_PREVIEW_BYTES,
   MINDOODB_APP_MAX_DRAG_PREVIEW_EDGE,
@@ -1080,6 +1445,7 @@ export {
   abbreviateCanonicalName,
   applyHostedDocumentOverscrollContain,
   bindDragSource,
+  buildHavenAppInstallUrl,
   buildMindooDBAppBundleContentHashInput,
   canPreviewAttachment,
   createMindooDBAppBridge,
@@ -1092,6 +1458,7 @@ export {
   installHostShortcutCapture,
   isHostShortcutAction,
   isHostedBundleRuntime,
+  isLaunchedByHaven,
   isMindooDBAppBundleHash,
   isMindooDBAppDragType,
   matchHostShortcut,
@@ -1101,8 +1468,13 @@ export {
   normalizeMindooDBAppBundlePath,
   queryDocuments,
   readMindooDBAppHostingMode,
+  readMindooDBAppLaunchId,
   releaseMindooDBAppBridgeSessions,
+  renderHavenAppLandingPage,
+  resolveCurrentHavenAppUrl,
   resolveMindooDBAppDefinitionUrl,
+  resolveMindooDBAppListingAssetUrl,
+  resolveMindooDBAppLocalizedText,
   sanitizeHostShortcutBindings,
   snapshotElementToPng,
   validateMindooDBAppBundleManifest,

package/dist/testing/index.d.ts

@@ -1,4 +1,4 @@
-import { au as MindooDBAppCreateViewNavigatorInput, cw as MindooDBAppViewNavigator, bg as MindooDBAppLaunchContext, av as MindooDBAppDatabaseInfo, aD as MindooDBAppDocumentApi, cy as MindooDBAppViewNavigatorOpenOptions, w as MindooDBAppAttachmentApi, b3 as MindooDBAppIdentityApi, cm as MindooDBAppTimestampApi, aB as MindooDBAppDirectoryApi, j as MindooDBAppDocument, a$ as MindooDBAppFulltextSetup, a_ as MindooDBAppExtractionSetup, ce as MindooDBAppSummarySetup, by as MindooDBAppProposeAppInput, bz as MindooDBAppProposeAppResult, e as MindooDBAppBridge, c6 as MindooDBAppSession, X as MindooDBAppBridgeRpcRequest, b2 as MindooDBAppHostTheme, cE as MindooDBAppViewport, cq as MindooDBAppUiPreferences, bE as MindooDBAppQueryResult, cD as MindooDBAppViewUpdateStats, T as MindooDBAppBridgePortMessage, c as MindooDBAppDragStartResult, aU as MindooDBAppDragProfile } from '../types-BLyV6Ejy.js';
+import { ay as MindooDBAppCreateViewNavigatorInput, cC as MindooDBAppViewNavigator, $ as MindooDBAppBridgeRpcRequest, b7 as MindooDBAppHostTheme, ag as MindooDBAppCapability, i as MindooDBAppDefinition, e as MindooDBAppBridge, cc as MindooDBAppSession, bE as MindooDBAppProposeAppInput, cK as MindooDBAppViewport, cw as MindooDBAppUiPreferences, bK as MindooDBAppQueryResult, cJ as MindooDBAppViewUpdateStats, X as MindooDBAppBridgePortMessage, bl as MindooDBAppLaunchContext, az as MindooDBAppDatabaseInfo, aI as MindooDBAppDocumentApi, cE as MindooDBAppViewNavigatorOpenOptions, A as MindooDBAppAttachmentApi, b8 as MindooDBAppIdentityApi, cs as MindooDBAppTimestampApi, aG as MindooDBAppDirectoryApi, k as MindooDBAppDocument, b4 as MindooDBAppFulltextSetup, b3 as MindooDBAppExtractionSetup, ck as MindooDBAppSummarySetup, bF as MindooDBAppProposeAppResult, c as MindooDBAppDragStartResult, aZ as MindooDBAppDragProfile } from '../types-CsKw_niD.js';
 import * as mindoodb from 'mindoodb';
 import 'mindoodb-view-language';
 
@@ -21,6 +21,92 @@ declare function loadMindoodbForTesting(): Promise<MindoodbVirtualViews | null>;
  */
 declare function createEvaluatingViewNavigator(input: MindooDBAppCreateViewNavigatorInput, documents: EvaluatingViewDocument[]): Promise<MindooDBAppViewNavigator | null>;
 
+/**
+ * A stand-in Haven for a real browser: the app runs in an iframe, exactly as Haven frames
+ * it, and talks to the same in-memory mock host the Vitest helpers use.
+ *
+ * This is what an app's test URL (`/__haven-test/` in the starter) mounts, so Playwright
+ * and a developer's own eyes see the real app — real bridge handshake, real DOM — with
+ * seeded data and scriptable host services, and without setting up an identity, a
+ * tenant and an install in a real Haven. It is never meant to be deployed where end
+ * users can reach it.
+ */
+/** A scan the test host hands out on the app's next `attachments.scan()` call. */
+interface BrowserTestHostScan {
+    fileName: string;
+    mimeType: "image/jpeg" | "image/png" | "application/pdf";
+    size: number;
+}
+/** What the test host recorded, in the order the app asked. */
+interface BrowserTestHostLog {
+    notifications: Array<{
+        id?: string;
+        severity?: string;
+        text?: string;
+        durationMs?: number;
+    }>;
+    previews: Array<{
+        databaseId: string;
+        docId: string;
+        attachmentName: string;
+    }>;
+    scans: Array<{
+        databaseId: string;
+        docId: string;
+        result: "scanned" | "cancelled";
+    }>;
+    focusRequests: number;
+    requests: MindooDBAppBridgeRpcRequest[];
+}
+interface CreateBrowserTestHostOptions extends CreateFakeBridgeHostOptions {
+    /** The iframe the app runs in. Its `src` is set by the host. */
+    frame: HTMLIFrameElement;
+    /** URL of the app page, relative to the test page or absolute. */
+    appUrl: string;
+    /** Called after every request, e.g. to re-render a control panel. */
+    onChange?: () => void;
+}
+interface BrowserTestHost {
+    host: FakeBridgeHostController;
+    log: BrowserTestHostLog;
+    /**
+     * Decides the outcome of the app's next `attachments.scan()`: a file description to
+     * "scan", or `null` to act as if the user cancelled. Without a call, scans cancel.
+     */
+    setNextScan(scan: BrowserTestHostScan | null): void;
+    setTheme(theme: MindooDBAppHostTheme): void;
+    setHostFocus(focused: boolean): void;
+    /** Reloads the app frame. The mock data survives; the app's in-memory state does not. */
+    reloadApp(): void;
+    dispose(): void;
+}
+/**
+ * The capabilities Haven grants for the permissions a definition requests. `read` is
+ * implied by the mapping, `write` is create plus update.
+ */
+declare function capabilitiesForDefinitionPermissions(permissions: readonly string[] | undefined): MindooDBAppCapability[];
+/** Mock databases for every database a `haven-app.json` declares, granted as requested. */
+declare function mockDatabasesFromDefinition(definition: Pick<MindooDBAppDefinition, "databases">, seed?: Record<string, MockMindooDBAppDatabaseDefinition["documents"]>): MockMindooDBAppDatabaseDefinition[];
+declare function createBrowserTestHost(options: CreateBrowserTestHostOptions): BrowserTestHost;
+interface MountHavenTestHostOptions extends Omit<CreateBrowserTestHostOptions, "frame" | "onChange"> {
+    /** Element to render into. Defaults to `document.body`, which is cleared. */
+    container?: HTMLElement;
+    /** Heading of the control panel, e.g. the app label. */
+    title?: string;
+}
+declare global {
+    interface Window {
+        /** Set by {@link mountHavenTestHost} so Playwright can script the host. */
+        __havenTestHost?: BrowserTestHost;
+    }
+}
+/**
+ * Renders the full test page: the app frame plus a control panel for theme, host focus
+ * and the next scan, and a live log of notifications, previews, scans and requests.
+ * The returned host is also available as `window.__havenTestHost`.
+ */
+declare function mountHavenTestHost(options: MountHavenTestHostOptions): BrowserTestHost;
+
 type MaybePromise<T> = T | Promise<T>;
 type MockViewApi = {
     create(input: MindooDBAppCreateViewNavigatorInput): MaybePromise<MindooDBAppViewNavigator>;
@@ -149,6 +235,8 @@ type FakeBridgePortMessageHandler = (message: Exclude<MindooDBAppBridgePortMessa
 interface CreateFakeBridgeHostOptions extends CreateMockMindooDBAppSessionOptions {
     windowMode?: "parent" | "opener";
     requestHandlers?: Record<string, FakeBridgeRequestHandler>;
+    /** Called for every RPC request the app sends, before it is answered. */
+    onRequest?: (request: MindooDBAppBridgeRpcRequest) => void;
     onPortMessage?: FakeBridgePortMessageHandler;
 }
 interface FakeBridgeHostController {
@@ -159,6 +247,13 @@ interface FakeBridgeHostController {
     /** Every `apps.propose` call the app under test made, in order. */
     readonly proposedApps: ReadonlyArray<MindooDBAppProposeAppInput>;
     install(): void;
+    /**
+     * Answers a `mindoodb-app:connect` handshake received some other way than through
+     * `install()` — in a real browser, from the app frame's `message` event
+     * (`host.acceptConnection(event.data, event.ports)`). Returns `false` for messages
+     * that are not a handshake for this launch.
+     */
+    acceptConnection(message: unknown, transfer?: readonly Transferable[]): boolean;
     dispose(): void;
     emitThemeChange(theme: MindooDBAppHostTheme): void;
     emitViewportChange(viewport: MindooDBAppViewport): void;
@@ -180,4 +275,4 @@ interface FakeBridgeHostController {
 }
 declare function createFakeBridgeHost(options?: CreateFakeBridgeHostOptions): FakeBridgeHostController;
 
-export { type CreateFakeBridgeHostOptions, type CreateMockMindooDBAppSessionOptions, type EvaluatingViewDocument, type FakeBridgeHostController, type FakeBridgePortMessageHandler, type FakeBridgeRequestHandler, type MockMindooDBAppDatabaseDefinition, type MockMindooDBAppSessionController, type MockSealedChannelOptions, type MockSeedDocument, createEvaluatingViewNavigator, createFakeBridgeHost, createMockMindooDBAppBridge, createMockMindooDBAppSession, loadMindoodbForTesting };
+export { type BrowserTestHost, type BrowserTestHostLog, type BrowserTestHostScan, type CreateBrowserTestHostOptions, type CreateFakeBridgeHostOptions, type CreateMockMindooDBAppSessionOptions, type EvaluatingViewDocument, type FakeBridgeHostController, type FakeBridgePortMessageHandler, type FakeBridgeRequestHandler, type MockMindooDBAppDatabaseDefinition, type MockMindooDBAppSessionController, type MockSealedChannelOptions, type MockSeedDocument, type MountHavenTestHostOptions, capabilitiesForDefinitionPermissions, createBrowserTestHost, createEvaluatingViewNavigator, createFakeBridgeHost, createMockMindooDBAppBridge, createMockMindooDBAppSession, loadMindoodbForTesting, mockDatabasesFromDefinition, mountHavenTestHost };