mindoodb-app-sdk 0.0.59 → 0.0.61

package/dist/{chunk-SKPP4T6S.js → chunk-U4NXI7EH.js}

@@ -66,6 +66,679 @@ function assertValidMindooDBCreateIds(input, methodName = "createDocument") {
   }
 }
 
+// src/appDefinition.ts
+var MINDOODB_APP_DEFINITION_FORMAT = "mindoodb.haven.app";
+var MINDOODB_APP_DEFINITION_VERSION = 1;
+var MINDOODB_APP_DEFINITION_FILE_NAME = "haven-app.json";
+var MINDOODB_APP_DEFINITION_PERMISSIONS = [
+  "write",
+  "delete",
+  "history",
+  "attachments",
+  "views",
+  "sign",
+  "timestamps",
+  "directory",
+  "sealedchannel",
+  "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);
+}
+function readOptionalString(raw, key, errors) {
+  const value = raw[key];
+  if (value === void 0 || value === null) {
+    return void 0;
+  }
+  if (typeof value !== "string") {
+    errors.push(`App definition ${key} must be a string.`);
+    return void 0;
+  }
+  const trimmed = value.trim();
+  return trimmed || void 0;
+}
+function readOptionalBoolean(raw, key, errors) {
+  const value = raw[key];
+  if (value === void 0 || value === null) {
+    return void 0;
+  }
+  if (typeof value !== "boolean") {
+    errors.push(`App definition ${key} must be a boolean.`);
+    return void 0;
+  }
+  return value || void 0;
+}
+function readStringRecord(raw, key, errors) {
+  const value = raw[key];
+  if (value === void 0 || value === null) {
+    return void 0;
+  }
+  if (!isPlainObject(value)) {
+    errors.push(`App definition ${key} must be an object of string values.`);
+    return void 0;
+  }
+  const result = {};
+  for (const [entryKey, entryValue] of Object.entries(value)) {
+    if (typeof entryValue !== "string") {
+      errors.push(`App definition ${key}.${entryKey} must be a string.`);
+      continue;
+    }
+    result[entryKey] = entryValue;
+  }
+  return Object.keys(result).length ? result : void 0;
+}
+function readPermissions(value, label, allowed, errors) {
+  if (value === void 0 || value === null) {
+    return void 0;
+  }
+  if (!Array.isArray(value)) {
+    errors.push(`${label} must be an array of permission names.`);
+    return void 0;
+  }
+  const result = [];
+  for (const entry of value) {
+    if (typeof entry !== "string" || !allowed.includes(entry)) {
+      errors.push(`${label} contains the unknown permission ${JSON.stringify(entry)}.`);
+      continue;
+    }
+    if (!result.includes(entry)) {
+      result.push(entry);
+    }
+  }
+  return result.length ? result : void 0;
+}
+function readNetworkAllowlist(value, errors) {
+  if (value === void 0 || value === null) {
+    return void 0;
+  }
+  if (!Array.isArray(value)) {
+    errors.push("App definition networkAllowlist must be an array of origins.");
+    return void 0;
+  }
+  const result = [];
+  for (const entry of value) {
+    if (typeof entry !== "string" || !entry.trim()) {
+      errors.push(`App definition networkAllowlist contains the invalid entry ${JSON.stringify(entry)}.`);
+      continue;
+    }
+    const trimmed = entry.trim();
+    if (!result.includes(trimmed)) {
+      result.push(trimmed);
+    }
+  }
+  return result.length ? result : void 0;
+}
+function readDatabases(value, errors) {
+  if (value === void 0 || value === null) {
+    return void 0;
+  }
+  if (!Array.isArray(value)) {
+    errors.push("App definition databases must be an array.");
+    return void 0;
+  }
+  const result = [];
+  const seen = /* @__PURE__ */ new Set();
+  value.forEach((entry, index) => {
+    if (!isPlainObject(entry)) {
+      errors.push(`App definition database #${index} must be an object.`);
+      return;
+    }
+    const logicalDatabaseId = typeof entry.logicalDatabaseId === "string" ? entry.logicalDatabaseId.trim() : "";
+    if (!logicalDatabaseId) {
+      errors.push(`App definition database #${index} is missing a non-empty logicalDatabaseId.`);
+      return;
+    }
+    if (!LOGICAL_DATABASE_ID_PATTERN.test(logicalDatabaseId)) {
+      errors.push(
+        `App definition database "${logicalDatabaseId}" must match ${String(LOGICAL_DATABASE_ID_PATTERN)}.`
+      );
+      return;
+    }
+    if (seen.has(logicalDatabaseId)) {
+      errors.push(`App definition lists the database "${logicalDatabaseId}" more than once.`);
+      return;
+    }
+    seen.add(logicalDatabaseId);
+    const databaseId = typeof entry.databaseId === "string" ? entry.databaseId.trim() : "";
+    if (entry.databaseId !== void 0 && entry.databaseId !== null && !databaseId) {
+      errors.push(`App definition database "${logicalDatabaseId}" has an empty databaseId.`);
+    }
+    result.push({
+      logicalDatabaseId,
+      label: typeof entry.label === "string" && entry.label.trim() ? entry.label.trim() : void 0,
+      databaseId: databaseId || void 0,
+      permissions: readPermissions(
+        entry.permissions,
+        `App definition database "${logicalDatabaseId}" permissions`,
+        MINDOODB_APP_DEFINITION_PERMISSIONS.filter(
+          (permission) => !MINDOODB_APP_DEFINITION_REGISTRATION_PERMISSIONS.includes(permission)
+        ),
+        errors
+      ),
+      create: entry.create === false ? false : void 0
+    });
+  });
+  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;
+}
+var MINDOODB_APP_ACCEPTS_MAX = 16;
+var ACCEPT_ID_PATTERN = /^[a-z0-9][a-z0-9_-]{0,47}$/;
+var ACCEPT_TYPE_PATTERN = /^(\*|[a-z0-9][a-z0-9.+-]*)\/(\*|[a-z0-9][a-z0-9.+-]*)$/i;
+function readAccepts(value, errors) {
+  if (value === void 0 || value === null) {
+    return void 0;
+  }
+  if (!Array.isArray(value)) {
+    errors.push("App definition accepts must be an array.");
+    return void 0;
+  }
+  if (value.length > MINDOODB_APP_ACCEPTS_MAX) {
+    errors.push(`App definition accepts must not have more than ${MINDOODB_APP_ACCEPTS_MAX} entries.`);
+    return void 0;
+  }
+  const result = [];
+  const ids = /* @__PURE__ */ new Set();
+  value.forEach((entry, index) => {
+    const label = `App definition accepts[${index}]`;
+    if (!isPlainObject(entry)) {
+      errors.push(`${label} must be an object.`);
+      return;
+    }
+    const id = typeof entry.id === "string" ? entry.id.trim() : "";
+    if (!ACCEPT_ID_PATTERN.test(id)) {
+      errors.push(`${label}.id must be 1-48 lowercase letters, digits, "-" or "_", received ${JSON.stringify(entry.id)}.`);
+      return;
+    }
+    if (ids.has(id)) {
+      errors.push(`${label}.id "${id}" is used twice.`);
+      return;
+    }
+    ids.add(id);
+    const text = readLocalizedText(entry.label, `${label}.label`, 80, errors);
+    if (!text) {
+      errors.push(`${label}.label is required.`);
+      return;
+    }
+    if (!Array.isArray(entry.types) || !entry.types.length) {
+      errors.push(`${label}.types must be a non-empty array of MIME patterns.`);
+      return;
+    }
+    const types = [];
+    for (const type of entry.types) {
+      if (typeof type !== "string" || !ACCEPT_TYPE_PATTERN.test(type.trim())) {
+        errors.push(`${label}.types contains an invalid MIME pattern ${JSON.stringify(type)}.`);
+        return;
+      }
+      types.push(type.trim().toLowerCase());
+    }
+    const folders = readOptionalBoolean(entry, "folders", errors);
+    const multiple = entry.multiple === false ? false : readOptionalBoolean(entry, "multiple", errors);
+    let maxBytes;
+    if (entry.maxBytes !== void 0) {
+      if (typeof entry.maxBytes !== "number" || !Number.isSafeInteger(entry.maxBytes) || entry.maxBytes <= 0) {
+        errors.push(`${label}.maxBytes must be a positive integer.`);
+        return;
+      }
+      maxBytes = entry.maxBytes;
+    }
+    result.push({ id, label: text, types, folders, multiple, maxBytes });
+  });
+  return result.length ? result : void 0;
+}
+function validateMindooDBAppAccepts(value) {
+  const errors = [];
+  const accepts = readAccepts(value, errors);
+  return { accepts: errors.length ? void 0 : accepts, errors };
+}
+function mindooDBAppAcceptMatchesType(pattern, type) {
+  const [patternMajor, patternMinor] = pattern.toLowerCase().split("/");
+  const [major, minor] = (type || "application/octet-stream").toLowerCase().split(";")[0].trim().split("/");
+  return (patternMajor === "*" || patternMajor === major) && (patternMinor === "*" || patternMinor === minor);
+}
+var MINDOODB_APP_COMPONENTS_MAX = 16;
+var COMPONENT_ID_PATTERN = /^[a-z0-9][a-z0-9_-]{0,47}$/;
+var COMPONENT_FIELD_PATTERN = /^[A-Za-z_][A-Za-z0-9_]{0,63}$/;
+var COMPONENT_INTENTS = ["create", "edit", "view"];
+var COMPONENT_CREATE_MAX_BYTES = 16 * 1024;
+function readComponentFieldMatch(value, label, errors) {
+  if (!isPlainObject(value)) {
+    errors.push(`${label} must be an object of field values.`);
+    return void 0;
+  }
+  const result = {};
+  for (const [field, fieldValue] of Object.entries(value)) {
+    if (!COMPONENT_FIELD_PATTERN.test(field)) {
+      errors.push(`${label} has an invalid field name ${JSON.stringify(field)}.`);
+      return void 0;
+    }
+    if (typeof fieldValue !== "string" && typeof fieldValue !== "number" && typeof fieldValue !== "boolean") {
+      errors.push(`${label}.${field} must be a string, number or boolean.`);
+      return void 0;
+    }
+    result[field] = fieldValue;
+  }
+  return result;
+}
+function readComponents(value, errors) {
+  if (value === void 0 || value === null) {
+    return void 0;
+  }
+  if (!Array.isArray(value)) {
+    errors.push("App definition components must be an array.");
+    return void 0;
+  }
+  if (value.length > MINDOODB_APP_COMPONENTS_MAX) {
+    errors.push(`App definition components must not have more than ${MINDOODB_APP_COMPONENTS_MAX} entries.`);
+    return void 0;
+  }
+  const result = [];
+  const ids = /* @__PURE__ */ new Set();
+  value.forEach((entry, index) => {
+    const label = `App definition components[${index}]`;
+    const errorCount = errors.length;
+    if (!isPlainObject(entry)) {
+      errors.push(`${label} must be an object.`);
+      return;
+    }
+    const id = typeof entry.id === "string" ? entry.id.trim() : "";
+    if (!COMPONENT_ID_PATTERN.test(id)) {
+      errors.push(`${label}.id must be 1-48 lowercase letters, digits, "-" or "_", received ${JSON.stringify(entry.id)}.`);
+      return;
+    }
+    if (ids.has(id)) {
+      errors.push(`${label}.id "${id}" is used twice.`);
+      return;
+    }
+    ids.add(id);
+    const text = readLocalizedText(entry.label, `${label}.label`, 80, errors);
+    if (!text) {
+      if (errors.length === errorCount) {
+        errors.push(`${label}.label is required.`);
+      }
+      return;
+    }
+    const description = readLocalizedText(entry.description, `${label}.description`, 300, errors);
+    const icon = readListingAssetPath(entry.icon, `${label}.icon`, errors);
+    if (!Array.isArray(entry.intents) || !entry.intents.length) {
+      errors.push(`${label}.intents must be a non-empty array of "create", "edit" or "view".`);
+      return;
+    }
+    const intents = [];
+    for (const intent of entry.intents) {
+      if (!COMPONENT_INTENTS.includes(intent)) {
+        errors.push(`${label}.intents contains an unknown intent ${JSON.stringify(intent)}.`);
+        return;
+      }
+      if (!intents.includes(intent)) {
+        intents.push(intent);
+      }
+    }
+    const match = readComponentFieldMatch(entry.match, `${label}.match`, errors);
+    if (!match) {
+      return;
+    }
+    if (!Object.keys(match).length) {
+      errors.push(`${label}.match must name at least one field, or the component would claim every document.`);
+      return;
+    }
+    let create;
+    if (entry.create !== void 0) {
+      if (!isPlainObject(entry.create)) {
+        errors.push(`${label}.create must be an object of initial field values.`);
+        return;
+      }
+      for (const field of Object.keys(entry.create)) {
+        if (!COMPONENT_FIELD_PATTERN.test(field)) {
+          errors.push(`${label}.create has an invalid field name ${JSON.stringify(field)}.`);
+          return;
+        }
+        if (field in match) {
+          errors.push(`${label}.create must not repeat the match field "${field}".`);
+          return;
+        }
+      }
+      let serialized;
+      try {
+        serialized = JSON.stringify(entry.create);
+      } catch {
+        errors.push(`${label}.create must be plain JSON.`);
+        return;
+      }
+      if (serialized.length > COMPONENT_CREATE_MAX_BYTES) {
+        errors.push(`${label}.create must not be larger than ${COMPONENT_CREATE_MAX_BYTES} bytes.`);
+        return;
+      }
+      create = JSON.parse(serialized);
+    }
+    let children;
+    if (entry.children !== void 0) {
+      if (!isPlainObject(entry.children)) {
+        errors.push(`${label}.children must be an object.`);
+        return;
+      }
+      const linkField = typeof entry.children.linkField === "string" ? entry.children.linkField.trim() : "";
+      if (!COMPONENT_FIELD_PATTERN.test(linkField)) {
+        errors.push(`${label}.children.linkField must be a top-level field name.`);
+        return;
+      }
+      const childMatch = entry.children.match === void 0 ? void 0 : readComponentFieldMatch(entry.children.match, `${label}.children.match`, errors);
+      if (entry.children.match !== void 0 && !childMatch) {
+        return;
+      }
+      if (childMatch && linkField in childMatch) {
+        errors.push(`${label}.children.match must not name the link field "${linkField}".`);
+        return;
+      }
+      children = { linkField, ...childMatch && Object.keys(childMatch).length ? { match: childMatch } : {} };
+    }
+    if (errors.length !== errorCount) {
+      return;
+    }
+    result.push({
+      id,
+      label: text,
+      ...description ? { description } : {},
+      ...icon ? { icon } : {},
+      intents,
+      match,
+      ...create ? { create } : {},
+      ...children ? { children } : {}
+    });
+  });
+  return result.length ? result : void 0;
+}
+function validateMindooDBAppComponents(value) {
+  const errors = [];
+  const components = readComponents(value, errors);
+  return { components: errors.length ? void 0 : components, errors };
+}
+function mindooDBAppComponentFieldsMatch(match, data) {
+  if (!data) {
+    return false;
+  }
+  return Object.entries(match).every(([field, value]) => data[field] === value);
+}
+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 descriptionMarkdown = readLocalizedText(
+    value.descriptionMarkdown,
+    "App definition listing.descriptionMarkdown",
+    MINDOODB_APP_LISTING_DESCRIPTION_MAX,
+    errors
+  );
+  if (descriptionMarkdown) listing.descriptionMarkdown = descriptionMarkdown;
+  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)) {
+    return { definition: null, errors: ["App definition must be a JSON object."] };
+  }
+  if (raw.format !== MINDOODB_APP_DEFINITION_FORMAT) {
+    errors.push(
+      `App definition format must be "${MINDOODB_APP_DEFINITION_FORMAT}", received ${JSON.stringify(raw.format)}.`
+    );
+  }
+  if (raw.formatVersion !== MINDOODB_APP_DEFINITION_VERSION) {
+    errors.push(
+      `Unsupported app definition version ${JSON.stringify(raw.formatVersion)}, expected ${MINDOODB_APP_DEFINITION_VERSION}.`
+    );
+  }
+  const appId = typeof raw.appId === "string" ? raw.appId.trim() : "";
+  if (!appId) {
+    errors.push("App definition is missing a non-empty appId.");
+  }
+  const label = typeof raw.label === "string" ? raw.label.trim() : "";
+  if (!label) {
+    errors.push("App definition is missing a non-empty label.");
+  }
+  const runtime = raw.runtime;
+  if (runtime !== void 0 && runtime !== "iframe" && runtime !== "window") {
+    errors.push(`App definition runtime must be "iframe" or "window", received ${JSON.stringify(runtime)}.`);
+  }
+  const hosting = raw.hosting;
+  if (hosting !== void 0 && hosting !== "external" && hosting !== "hosted") {
+    errors.push(
+      `App definition hosting must be "external" or "hosted", received ${JSON.stringify(hosting)}.`
+    );
+  }
+  const description = readOptionalString(raw, "description", errors);
+  const version = readOptionalString(raw, "version", errors);
+  const defaultLaunchDatabaseId = readOptionalString(raw, "defaultLaunchDatabaseId", errors);
+  const networkAllowlist = readNetworkAllowlist(raw.networkAllowlist, errors);
+  const launchParameters = readStringRecord(raw, "launchParameters", errors);
+  const databases = readDatabases(raw.databases, errors);
+  const permissions = readPermissions(
+    raw.permissions,
+    "App definition permissions",
+    MINDOODB_APP_DEFINITION_REGISTRATION_PERMISSIONS,
+    errors
+  );
+  const allowPopups = readOptionalBoolean(raw, "allowPopups", errors);
+  const allowCamera = readOptionalBoolean(raw, "allowCamera", errors);
+  const allowMicrophone = readOptionalBoolean(raw, "allowMicrophone", errors);
+  const allowGeolocation = readOptionalBoolean(raw, "allowGeolocation", errors);
+  const allowClipboardWrite = readOptionalBoolean(raw, "allowClipboardWrite", errors);
+  const allowMotion = readOptionalBoolean(raw, "allowMotion", errors);
+  const allowWebRtc = readOptionalBoolean(raw, "allowWebRtc", errors);
+  const allowWorkers = readOptionalBoolean(raw, "allowWorkers", errors);
+  const listing = readListing(raw.listing, errors);
+  const accepts = readAccepts(raw.accepts, errors);
+  const components = readComponents(raw.components, errors);
+  const agentToolPrefix = readOptionalString(raw, "agentToolPrefix", errors);
+  if (agentToolPrefix !== void 0 && (!/^[a-z][a-z0-9_]{0,15}$/.test(agentToolPrefix) || agentToolPrefix.endsWith("_") || /^haven(?:_|$)/.test(agentToolPrefix))) {
+    errors.push(
+      `App definition agentToolPrefix must be 1-16 lowercase letters, digits or "_", start with a letter and not be "haven", received ${JSON.stringify(agentToolPrefix)}.`
+    );
+  }
+  if (defaultLaunchDatabaseId && databases && !databases.some((database) => database.logicalDatabaseId === defaultLaunchDatabaseId)) {
+    errors.push(
+      `App definition defaultLaunchDatabaseId "${defaultLaunchDatabaseId}" is not one of the declared databases.`
+    );
+  }
+  if (errors.length) {
+    return { definition: null, errors };
+  }
+  return {
+    definition: {
+      format: MINDOODB_APP_DEFINITION_FORMAT,
+      formatVersion: MINDOODB_APP_DEFINITION_VERSION,
+      appId,
+      label,
+      description,
+      version,
+      runtime,
+      hosting,
+      networkAllowlist,
+      allowPopups,
+      allowCamera,
+      allowMicrophone,
+      allowGeolocation,
+      allowClipboardWrite,
+      allowMotion,
+      allowWebRtc,
+      allowWorkers,
+      agentToolPrefix,
+      permissions,
+      launchParameters,
+      defaultLaunchDatabaseId,
+      databases,
+      accepts,
+      components,
+      listing
+    },
+    errors: []
+  };
+}
+function resolveMindooDBAppDefinitionUrl(baseUrl) {
+  const trimmed = baseUrl.trim();
+  if (!trimmed) {
+    return "";
+  }
+  const suffix = `/${MINDOODB_APP_DEFINITION_FILE_NAME}`;
+  try {
+    const url = new URL(trimmed);
+    const path = url.pathname.replace(/\/+$/, "") || "/";
+    url.search = "";
+    url.hash = "";
+    url.pathname = path.endsWith(suffix) || path === suffix ? path : `${path === "/" ? "" : path}${suffix}`;
+    return url.toString();
+  } catch {
+    const withoutSlash = trimmed.replace(/\/+$/, "");
+    return withoutSlash.toLowerCase().endsWith(suffix) ? withoutSlash : `${withoutSlash}${suffix}`;
+  }
+}
+
 // src/drag.ts
 var MINDOODB_APP_MAX_DRAG_TYPES = 8;
 var MINDOODB_APP_MAX_DRAG_PAYLOAD_BYTES = 32 * 1024;
@@ -665,6 +1338,238 @@ function installHostShortcutCapture(options) {
 // src/client/createMindooDBAppBridge.ts
 import { parseMindooDBFormulaBooleanExpression } from "mindoodb-view-language";
 
+// src/client/embeds.ts
+function isEmbedEventMessage(message) {
+  return message.kind === "embed-event";
+}
+function toRect(rect) {
+  return {
+    left: Number(rect.left) || 0,
+    top: Number(rect.top) || 0,
+    width: Math.max(0, Number(rect.width) || 0),
+    height: Math.max(0, Number(rect.height) || 0)
+  };
+}
+function containerRect(container) {
+  const bounds = container.getBoundingClientRect();
+  return toRect({ left: bounds.left, top: bounds.top, width: bounds.width, height: bounds.height });
+}
+var ContainerTracker = class {
+  constructor(container, report) {
+    this.container = container;
+    this.report = report;
+    this.observer = typeof ResizeObserver === "undefined" ? null : new ResizeObserver(this.schedule);
+    this.observer?.observe(container);
+    window.addEventListener("resize", this.schedule);
+    window.addEventListener("scroll", this.schedule, true);
+  }
+  container;
+  report;
+  frameRequest = null;
+  observer;
+  schedule = () => {
+    if (this.frameRequest !== null) {
+      return;
+    }
+    this.frameRequest = window.requestAnimationFrame(() => {
+      this.frameRequest = null;
+      this.report(containerRect(this.container));
+    });
+  };
+  dispose() {
+    this.observer?.disconnect();
+    window.removeEventListener("resize", this.schedule);
+    window.removeEventListener("scroll", this.schedule, true);
+    if (this.frameRequest !== null) {
+      window.cancelAnimationFrame(this.frameRequest);
+    }
+  }
+};
+function createComponentFrame(container, url, allow) {
+  const frame = container.ownerDocument.createElement("iframe");
+  frame.src = url;
+  if (allow) {
+    frame.setAttribute("allow", allow);
+  }
+  frame.setAttribute("referrerpolicy", "strict-origin-when-cross-origin");
+  frame.dataset.mindoodbEmbed = "";
+  Object.assign(frame.style, {
+    position: "absolute",
+    inset: "0",
+    width: "100%",
+    height: "100%",
+    border: "0",
+    display: "block"
+  });
+  container.appendChild(frame);
+  return frame;
+}
+var MindooDBAppEmbedImpl = class {
+  constructor(rpc, embedId, componentKey, databaseId, docId, frame, container) {
+    this.rpc = rpc;
+    this.embedId = embedId;
+    this.componentKey = componentKey;
+    this.databaseId = databaseId;
+    this.docId = docId;
+    this.frame = frame;
+    this.closed = new Promise((resolve) => {
+      this.resolveClosed = resolve;
+    });
+    if (container) {
+      this.tracker = new ContainerTracker(container, (rect) => {
+        void this.setRect(rect).catch(() => {
+        });
+      });
+    }
+  }
+  rpc;
+  embedId;
+  componentKey;
+  databaseId;
+  docId;
+  frame;
+  closed;
+  resolveClosed;
+  closedEvent = null;
+  listeners = /* @__PURE__ */ new Set();
+  tracker = null;
+  get placement() {
+    return this.frame ? "frame" : "overlay";
+  }
+  async setRect(rect) {
+    if (this.closedEvent) {
+      return;
+    }
+    await this.rpc.call("embeds.setRect", { embedId: this.embedId, rect: toRect(rect) });
+  }
+  async setVisible(visible) {
+    if (this.closedEvent) {
+      return;
+    }
+    if (this.frame) {
+      this.frame.style.visibility = visible ? "" : "hidden";
+      return;
+    }
+    await this.rpc.call("embeds.setVisible", { embedId: this.embedId, visible: visible === true });
+  }
+  async close() {
+    if (!this.closedEvent) {
+      await this.rpc.call("embeds.close", { embedId: this.embedId });
+    }
+    return await this.closed;
+  }
+  onClosed(listener) {
+    if (this.closedEvent) {
+      const event = this.closedEvent;
+      queueMicrotask(() => listener(event));
+      return () => {
+      };
+    }
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+  settle(event) {
+    if (this.closedEvent) {
+      return;
+    }
+    this.closedEvent = event;
+    this.tracker?.dispose();
+    this.tracker = null;
+    this.frame?.remove();
+    this.resolveClosed(event);
+    this.listeners.forEach((listener) => {
+      try {
+        listener(event);
+      } catch (error) {
+        console.error("MindooDB embed closed listener failed.", error);
+      }
+    });
+    this.listeners.clear();
+  }
+};
+var MindooDBAppEmbedsClient = class {
+  constructor(rpc) {
+    this.rpc = rpc;
+    this.stopListening = this.rpc.addMessageListener((message) => {
+      if (!isEmbedEventMessage(message) || message.event?.type !== "closed") {
+        return;
+      }
+      const { type: _type, ...event } = message.event;
+      const embed = this.open.get(event.embedId);
+      if (embed) {
+        this.open.delete(event.embedId);
+        embed.settle(event);
+      } else {
+        this.early.set(event.embedId, event);
+      }
+    });
+    this.components = {
+      list: async (query) => {
+        const response = await this.rpc.call("components.list", {
+          query: query ?? {}
+        });
+        return response?.components ?? [];
+      }
+    };
+    this.embeds = {
+      open: async (input) => {
+        const { container, rect, ...rest } = input;
+        const initialRect = container ? containerRect(container) : toRect(rect ?? { left: 0, top: 0, width: 0, height: 0 });
+        const response = await this.rpc.call("embeds.open", {
+          // `frame`: Haven hands back a page for the container instead of laying
+          // the component over this app. Havens that do not know it ignore it.
+          input: { ...rest, rect: initialRect, ...container ? { placement: "frame" } : {} }
+        });
+        const frame = container && response.frame?.url ? createComponentFrame(container, response.frame.url, response.frame.allow) : null;
+        const embed = new MindooDBAppEmbedImpl(
+          this.rpc,
+          response.embedId,
+          input.componentKey,
+          input.databaseId,
+          input.docId,
+          frame,
+          container
+        );
+        const early = this.early.get(embed.embedId);
+        if (early) {
+          this.early.delete(embed.embedId);
+          embed.settle(early);
+        } else {
+          this.open.set(embed.embedId, embed);
+        }
+        return embed;
+      }
+    };
+    this.embedding = {
+      complete: async (result) => {
+        await this.rpc.call("embedding.finish", {
+          reason: "completed",
+          ...result === void 0 ? {} : { result: JSON.parse(JSON.stringify(result)) }
+        });
+      },
+      cancel: async (message) => {
+        await this.rpc.call("embedding.finish", {
+          reason: "cancelled",
+          ...message ? { message: String(message) } : {}
+        });
+      }
+    };
+  }
+  rpc;
+  components;
+  embeds;
+  embedding;
+  open = /* @__PURE__ */ new Map();
+  /** Events that arrived before `embeds.open` resolved with their id. */
+  early = /* @__PURE__ */ new Map();
+  stopListening;
+  dispose() {
+    this.stopListening();
+  }
+};
+
 // src/client/incomingContent.ts
 var MINDOODB_APP_INCOMING_READ_CHUNK_BYTES = 1024 * 1024;
 function isIncomingContentMessage(message) {
@@ -2051,6 +2956,10 @@ var MindooDBAppSessionImpl = class {
     this.drag = new MindooDBAppDragApiImpl(this.rpc);
     this.agent = new MindooDBAppAgentApiImpl(this.rpc);
     this.incoming = new MindooDBAppIncomingApiImpl(this.rpc);
+    this.embedsClient = new MindooDBAppEmbedsClient(this.rpc);
+    this.components = this.embedsClient.components;
+    this.embeds = this.embedsClient.embeds;
+    this.embedding = this.embedsClient.embedding;
     this.storage = {
       snapshot: async (options) => await this.rpc.call("appStorage.snapshot", {
         prefixes: options?.prefixes
@@ -2115,6 +3024,10 @@ var MindooDBAppSessionImpl = class {
   storage;
   agent;
   incoming;
+  embedsClient;
+  components;
+  embeds;
+  embedding;
   beforeCloseListeners = /* @__PURE__ */ new Set();
   hostShortcuts = DEFAULT_HAVEN_HOST_SHORTCUTS;
   stopHostShortcuts;
@@ -2293,6 +3206,7 @@ var MindooDBAppSessionImpl = class {
     this.drag.dispose();
     this.agent.dispose();
     this.incoming.dispose();
+    this.embedsClient.dispose();
     try {
       await this.rpc.call("session.disconnect", {});
     } finally {
@@ -2352,6 +3266,24 @@ export {
   isValidMindooDBDocumentId,
   mindooDBDocumentId,
   assertValidMindooDBCreateIds,
+  MINDOODB_APP_DEFINITION_FORMAT,
+  MINDOODB_APP_DEFINITION_VERSION,
+  MINDOODB_APP_DEFINITION_FILE_NAME,
+  MINDOODB_APP_DEFINITION_PERMISSIONS,
+  MINDOODB_APP_DEFINITION_REGISTRATION_PERMISSIONS,
+  MINDOODB_APP_LISTING_SUMMARY_MAX,
+  MINDOODB_APP_LISTING_DESCRIPTION_MAX,
+  MINDOODB_APP_LISTING_MAX_SCREENSHOTS,
+  MINDOODB_APP_ACCEPTS_MAX,
+  validateMindooDBAppAccepts,
+  mindooDBAppAcceptMatchesType,
+  MINDOODB_APP_COMPONENTS_MAX,
+  validateMindooDBAppComponents,
+  mindooDBAppComponentFieldsMatch,
+  resolveMindooDBAppLocalizedText,
+  resolveMindooDBAppListingAssetUrl,
+  validateMindooDBAppDefinition,
+  resolveMindooDBAppDefinitionUrl,
   MINDOODB_APP_MAX_DRAG_TYPES,
   MINDOODB_APP_MAX_DRAG_PAYLOAD_BYTES,
   MINDOODB_APP_MAX_DRAG_PREVIEW_BYTES,