mindoodb-app-sdk 0.0.71 → 0.0.73

package/dist/{chunk-GTNDGA7P.js → chunk-FKTNDDWB.js}

@@ -66,6 +66,297 @@ function assertValidMindooDBCreateIds(input, methodName = "createDocument") {
   }
 }
 
+// src/inspection.ts
+var MINDOODB_INSPECT_DOCUMENT = "mindoo.inspect.document@1";
+var MINDOODB_INSPECT_SPREADSHEET = "mindoo.inspect.spreadsheet@1";
+var MINDOODB_INSPECT_SLIDES = "mindoo.inspect.slides@1";
+var MINDOODB_APP_INSPECTION_FIELD = "inspection";
+var MINDOODB_APP_INSPECTION_SUMMARY_MAX_BYTES = 8 * 1024;
+var MINDOODB_APP_INSPECTION_MAX_BYTES = 256 * 1024;
+var MINDOODB_APP_ISSUES_MAX = 100;
+var MindooDBAppEmbedValidationError = class extends Error {
+  constructor(issues) {
+    const first = issues.find((issue) => issue.severity === "error") ?? issues[0];
+    super(first ? first.message : "The document was not saved.");
+    this.issues = issues;
+    this.name = "MindooDBAppEmbedValidationError";
+  }
+  issues;
+};
+var SUPPORTS_CAPABILITY = /^[a-z][a-z0-9-]{0,31}$/;
+function mindooDBAppComponentSupports(supports, requirement) {
+  const wanted = requirement.trim();
+  return (supports ?? []).some((entry) => entry === wanted || !wanted.includes(":") && entry.startsWith(`${wanted}:`));
+}
+function mindooDBAppInspectContracts(supports) {
+  return (supports ?? []).filter((entry) => entry.startsWith("inspect:")).map((entry) => entry.slice("inspect:".length));
+}
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function normalizeMindooDBAppInspectAnchor(raw) {
+  if (!isPlainObject(raw)) {
+    return void 0;
+  }
+  if (raw.kind === "heading" && typeof raw.id === "string" && raw.id && raw.id.length <= 200) {
+    return { kind: "heading", id: raw.id };
+  }
+  if (raw.kind === "cell" && typeof raw.ref === "string" && raw.ref && raw.ref.length <= 200) {
+    return { kind: "cell", ref: raw.ref };
+  }
+  if (raw.kind === "slide" && Number.isInteger(raw.index) && raw.index >= 0) {
+    return { kind: "slide", index: raw.index };
+  }
+  return void 0;
+}
+function normalizeMindooDBAppIssues(raw) {
+  if (!Array.isArray(raw)) {
+    return [];
+  }
+  const issues = [];
+  for (const entry of raw) {
+    if (issues.length >= MINDOODB_APP_ISSUES_MAX) {
+      break;
+    }
+    if (!isPlainObject(entry) || typeof entry.message !== "string" || !entry.message.trim()) {
+      continue;
+    }
+    const severity = entry.severity === "warning" || entry.severity === "info" ? entry.severity : entry.severity === "error" ? "error" : null;
+    if (!severity) {
+      continue;
+    }
+    const anchor = normalizeMindooDBAppInspectAnchor(entry.anchor);
+    const code = typeof entry.code === "string" && entry.code.trim() ? entry.code.trim().slice(0, 64) : void 0;
+    issues.push({
+      severity,
+      message: entry.message.trim().slice(0, 500),
+      ...anchor ? { anchor } : {},
+      ...code ? { code } : {}
+    });
+  }
+  return issues;
+}
+function normalizeMindooDBAppInspectRequest(raw) {
+  const input = isPlainObject(raw) ? raw : {};
+  const strings = (value, max) => Array.isArray(value) ? [...new Set(value.filter((entry) => typeof entry === "string" && !!entry && entry.length <= 200))].slice(0, max) : [];
+  const include = strings(input.include, 16);
+  const cells = strings(input.cells, 200);
+  const maxTextLength = Number(input.maxTextLength);
+  return {
+    ...typeof input.contract === "string" && input.contract ? { contract: input.contract.slice(0, 200) } : {},
+    ...include.length ? { include } : {},
+    ...cells.length ? { cells } : {},
+    ...Number.isFinite(maxTextLength) && maxTextLength > 0 ? { maxTextLength: Math.min(Math.floor(maxTextLength), 5e4) } : {}
+  };
+}
+function normalizeMindooDBAppInspection(raw) {
+  let json;
+  try {
+    json = JSON.stringify(raw);
+  } catch {
+    throw new Error("An inspection must be plain JSON.");
+  }
+  if (!json || json.length > MINDOODB_APP_INSPECTION_MAX_BYTES) {
+    throw new Error(`An inspection must not be larger than ${MINDOODB_APP_INSPECTION_MAX_BYTES / 1024} KiB.`);
+  }
+  const value = JSON.parse(json);
+  if (!isPlainObject(value) || typeof value.contract !== "string" || !value.contract) {
+    throw new Error("An inspection must be an object with a contract.");
+  }
+  return value;
+}
+var SUMMARY_TEXT_STEPS = [500, 200, 0];
+var SUMMARY_LIST_STEPS = [50, 20, 5, 0];
+function shorten(value, textMax, listMax, marks) {
+  if (typeof value === "string") {
+    if (value.length <= textMax) return value;
+    marks.truncated = true;
+    return value.slice(0, textMax);
+  }
+  if (Array.isArray(value)) {
+    if (value.length > listMax) marks.truncated = true;
+    return value.slice(0, listMax).map((entry) => shorten(entry, Math.min(textMax || 80, 80), listMax, marks));
+  }
+  if (isPlainObject(value)) {
+    return Object.fromEntries(Object.entries(value).map(([key, entry]) => [key, shorten(entry, textMax, listMax, marks)]));
+  }
+  return value;
+}
+function summarizeMindooDBAppInspection(inspection, maxBytes = MINDOODB_APP_INSPECTION_SUMMARY_MAX_BYTES) {
+  const { cells: _cells, ...rest } = inspection;
+  const base = JSON.parse(JSON.stringify(rest));
+  for (const textMax of SUMMARY_TEXT_STEPS) {
+    for (const listMax of SUMMARY_LIST_STEPS) {
+      const marks = { truncated: false };
+      const next = shorten(base, textMax, listMax, marks);
+      if (textMax === 0 && typeof next.text === "string") delete next.text;
+      next.contract = inspection.contract;
+      if (typeof inspection.subject === "string") next.subject = inspection.subject.slice(0, 200);
+      if (marks.truncated || inspection.truncated) next.truncated = true;
+      if (JSON.stringify(next).length <= maxBytes) {
+        return next;
+      }
+    }
+  }
+  return { contract: inspection.contract, truncated: true };
+}
+function mindooDBAppInspectionSummaryValue(inspection) {
+  return MindooDBAppValue.atomic(JSON.stringify(summarizeMindooDBAppInspection(inspection)));
+}
+function readMindooDBAppInspectionSummary(root) {
+  let value = root?.[MINDOODB_APP_INSPECTION_FIELD];
+  if (typeof value === "string") {
+    try {
+      value = JSON.parse(value);
+    } catch {
+      return null;
+    }
+  }
+  return isPlainObject(value) && typeof value.contract === "string" ? value : null;
+}
+function outcomeIssues(rule, outcome) {
+  if (!outcome) return [];
+  if (typeof outcome === "string") {
+    return [{ severity: rule.severity ?? "error", message: outcome, code: rule.code }];
+  }
+  return (Array.isArray(outcome) ? outcome : [outcome]).map((issue) => ({ code: rule.code, ...issue }));
+}
+function defineDocumentRules(definition) {
+  const request = normalizeMindooDBAppInspectRequest(definition);
+  function check(inspection) {
+    if (!inspection || definition.contract && inspection.contract !== definition.contract) {
+      return [];
+    }
+    const issues = definition.rules.flatMap((rule) => {
+      try {
+        return outcomeIssues(rule, rule.check(inspection));
+      } catch (error) {
+        return [
+          {
+            severity: "warning",
+            code: rule.code,
+            message: `Check "${rule.code}" failed: ${error instanceof Error ? error.message : String(error)}`
+          }
+        ];
+      }
+    });
+    return normalizeMindooDBAppIssues(issues);
+  }
+  const rules = {
+    request,
+    check,
+    checkRoot: (root) => check(readMindooDBAppInspectionSummary(root)),
+    beforeSave: ({ inspection }) => ({ issues: check(inspection) }),
+    attach: (embed) => embed.onBeforeSave(rules.beforeSave, { inspect: request })
+  };
+  return rules;
+}
+function plural(count, one, many) {
+  return `${count} ${count === 1 ? one : many}`;
+}
+var mindooDBAppInspectRules = {
+  /** Documents: no placeholder or MERGEFIELD left open. */
+  noOpenPlaceholders(severity = "error", message) {
+    return {
+      code: "open-placeholders",
+      severity,
+      check: (inspection) => {
+        const names = (inspection.placeholders ?? []).map((entry) => entry.name);
+        if (!names.length) return null;
+        return message?.(names) ?? `${plural(names.length, "placeholder is", "placeholders are")} not filled in: ${names.slice(0, 5).join(", ")}${names.length > 5 ? ", \u2026" : ""}`;
+      }
+    };
+  },
+  /** Documents: every comment resolved. */
+  noOpenComments(severity = "warning", message) {
+    return {
+      code: "open-comments",
+      severity,
+      check: (inspection) => inspection.openComments > 0 ? message?.(inspection.openComments) ?? `${plural(inspection.openComments, "comment is", "comments are")} not resolved.` : null
+    };
+  },
+  /** Documents: every tracked change accepted or rejected. */
+  noOpenTrackedChanges(severity = "warning", message) {
+    return {
+      code: "open-tracked-changes",
+      severity,
+      check: (inspection) => inspection.openTrackedChanges > 0 ? message?.(inspection.openTrackedChanges) ?? `${plural(inspection.openTrackedChanges, "tracked change is", "tracked changes are")} not accepted or rejected.` : null
+    };
+  },
+  /** Spreadsheets: no formula evaluates to an error; one issue per cell. */
+  noFormulaErrors(severity = "error") {
+    return {
+      code: "formula-errors",
+      severity,
+      check: (inspection) => (inspection.formulaErrors ?? []).map((entry) => ({
+        severity,
+        message: `${entry.ref}: ${entry.error}`,
+        anchor: { kind: "cell", ref: entry.ref }
+      }))
+    };
+  },
+  /** Presentations: no layout placeholder left empty; one issue per slide. */
+  noEmptySlidePlaceholders(severity = "warning") {
+    return {
+      code: "empty-placeholders",
+      severity,
+      check: (inspection) => {
+        const bySlide = /* @__PURE__ */ new Map();
+        for (const entry of inspection.emptyPlaceholders ?? []) {
+          bySlide.set(entry.slide, [...bySlide.get(entry.slide) ?? [], entry.placeholder]);
+        }
+        return [...bySlide.entries()].map(([slide, names]) => ({
+          severity,
+          message: `Slide ${slide + 1}: empty ${names.join(", ")}`,
+          anchor: { kind: "slide", index: slide }
+        }));
+      }
+    };
+  }
+};
+var SUPPORTS_ARGUMENT = /^[a-z0-9][a-z0-9-]{0,31}$/;
+function isMindooDBAppSupportsEntry(entry, contractPattern) {
+  const [capability, argument, ...rest] = entry.split(":");
+  if (rest.length || !capability || !SUPPORTS_CAPABILITY.test(capability)) {
+    return false;
+  }
+  return argument === void 0 || contractPattern.test(argument) || SUPPORTS_ARGUMENT.test(argument);
+}
+async function performMindooDBAppEmbeddingSave(steps) {
+  const validation = await steps.validate();
+  if (!validation.ok) {
+    if (validation.issues.length && steps.showIssues) {
+      try {
+        await steps.showIssues(validation.issues);
+      } catch (error) {
+        console.warn("[mindoodb-app-sdk] Showing issues failed.", error);
+      }
+    }
+    throw new MindooDBAppEmbedValidationError(validation.issues);
+  }
+  let inspection = null;
+  if (steps.provider) {
+    try {
+      inspection = mindooDBAppInspectionSummaryValue(normalizeMindooDBAppInspection(await steps.provider({})));
+    } catch (error) {
+      console.warn("[mindoodb-app-sdk] Could not summarize the document.", error);
+    }
+  }
+  await steps.flush({ inspection, issues: validation.issues });
+  await steps.saved();
+  return validation;
+}
+async function resolveMindooDBAppEmbedValidation(issues, interactive, confirm) {
+  if (issues.some((issue) => issue.severity === "error")) {
+    return { ok: false, issues };
+  }
+  const warnings = issues.filter((issue) => issue.severity === "warning");
+  if (!warnings.length || !interactive) {
+    return { ok: true, issues };
+  }
+  return { ok: await confirm(warnings) === true, issues };
+}
+
 // src/appDefinition.ts
 var MINDOODB_APP_DEFINITION_FORMAT = "mindoodb.haven.app";
 var MINDOODB_APP_DEFINITION_VERSION = 1;
@@ -96,7 +387,7 @@ var MINDOODB_APP_AGENT_LIMIT_MAX = 300;
 var MINDOODB_APP_AGENT_GUIDE_MAX_BYTES = 8 * 1024;
 var MINDOODB_APP_AGENT_TOOL_NAME_PATTERN = /^[a-z][a-z0-9_]{0,47}$/;
 var LOGICAL_DATABASE_ID_PATTERN = /^[a-z0-9][a-z0-9._-]*$/i;
-function isPlainObject(value) {
+function isPlainObject2(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function readOptionalString(raw, key, errors) {
@@ -127,7 +418,7 @@ function readStringRecord(raw, key, errors) {
   if (value === void 0 || value === null) {
     return void 0;
   }
-  if (!isPlainObject(value)) {
+  if (!isPlainObject2(value)) {
     errors.push(`App definition ${key} must be an object of string values.`);
     return void 0;
   }
@@ -193,7 +484,7 @@ function readDatabases(value, errors) {
   const result = [];
   const seen = /* @__PURE__ */ new Set();
   value.forEach((entry, index) => {
-    if (!isPlainObject(entry)) {
+    if (!isPlainObject2(entry)) {
       errors.push(`App definition database #${index} must be an object.`);
       return;
     }
@@ -246,7 +537,7 @@ function readLocalizedText(value, label, maxLength, errors) {
     }
     return trimmed || void 0;
   }
-  if (!isPlainObject(value)) {
+  if (!isPlainObject2(value)) {
     errors.push(`${label} must be a string or an object of per-locale strings.`);
     return void 0;
   }
@@ -293,7 +584,7 @@ function readAccepts(value, errors) {
   const ids = /* @__PURE__ */ new Set();
   value.forEach((entry, index) => {
     const label = `App definition accepts[${index}]`;
-    if (!isPlainObject(entry)) {
+    if (!isPlainObject2(entry)) {
       errors.push(`${label} must be an object.`);
       return;
     }
@@ -354,7 +645,7 @@ 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)) {
+  if (!isPlainObject2(value)) {
     errors.push(`${label} must be an object of field values.`);
     return void 0;
   }
@@ -377,6 +668,28 @@ var MINDOODB_APP_COMPONENT_CONTRACT_PATTERN = /^[a-z][a-z0-9-]*(\.[a-z][a-z0-9-]
 var COMPONENT_CONTRACTS_MAX = 8;
 var COMPONENT_REFERENCES_MAX = 8;
 var COMPONENT_REFERENCE_SHOW_MAX = 8;
+var COMPONENT_SUPPORTS_MAX = 16;
+function readComponentSupports(value, label, errors) {
+  if (value === void 0) {
+    return void 0;
+  }
+  if (!Array.isArray(value) || value.length > COMPONENT_SUPPORTS_MAX) {
+    errors.push(`${label} must be an array of at most ${COMPONENT_SUPPORTS_MAX} entries.`);
+    return void 0;
+  }
+  const result = [];
+  for (const entry of value) {
+    const text = typeof entry === "string" ? entry.trim() : "";
+    if (!isMindooDBAppSupportsEntry(text, MINDOODB_APP_COMPONENT_CONTRACT_PATTERN)) {
+      errors.push(`${label} entries must look like "validate", "export:pdf" or "inspect:mindoo.inspect.document@1", received ${JSON.stringify(entry)}.`);
+      return void 0;
+    }
+    if (!result.includes(text)) {
+      result.push(text);
+    }
+  }
+  return result.length ? result : void 0;
+}
 function readComponentContracts(value, label, errors) {
   if (value === void 0) {
     return void 0;
@@ -387,14 +700,14 @@ function readComponentContracts(value, label, errors) {
   }
   const result = [];
   for (const [index, entry] of value.entries()) {
-    const contract = isPlainObject(entry) && typeof entry.contract === "string" ? entry.contract.trim() : "";
+    const contract = isPlainObject2(entry) && typeof entry.contract === "string" ? entry.contract.trim() : "";
     if (!MINDOODB_APP_COMPONENT_CONTRACT_PATTERN.test(contract)) {
       errors.push(`${label}[${index}].contract must look like "mindoo.contacts.company@1".`);
       return void 0;
     }
     let fields;
-    if (isPlainObject(entry) && entry.fields !== void 0) {
-      if (!isPlainObject(entry.fields)) {
+    if (isPlainObject2(entry) && entry.fields !== void 0) {
+      if (!isPlainObject2(entry.fields)) {
         errors.push(`${label}[${index}].fields must map contract fields to document fields.`);
         return void 0;
       }
@@ -423,7 +736,7 @@ function readComponentReferences(value, label, rootMatch, errors) {
   const fieldsSeen = /* @__PURE__ */ new Set();
   for (const [index, entry] of value.entries()) {
     const at = `${label}[${index}]`;
-    if (!isPlainObject(entry)) {
+    if (!isPlainObject2(entry)) {
       errors.push(`${at} must be an object.`);
       return void 0;
     }
@@ -472,7 +785,7 @@ function readComponents(value, errors) {
   value.forEach((entry, index) => {
     const label = `App definition components[${index}]`;
     const errorCount = errors.length;
-    if (!isPlainObject(entry)) {
+    if (!isPlainObject2(entry)) {
       errors.push(`${label} must be an object.`);
       return;
     }
@@ -519,7 +832,7 @@ function readComponents(value, errors) {
     }
     let create;
     if (entry.create !== void 0) {
-      if (!isPlainObject(entry.create)) {
+      if (!isPlainObject2(entry.create)) {
         errors.push(`${label}.create must be an object of initial field values.`);
         return;
       }
@@ -548,7 +861,7 @@ function readComponents(value, errors) {
     }
     let children;
     if (entry.children !== void 0) {
-      if (!isPlainObject(entry.children)) {
+      if (!isPlainObject2(entry.children)) {
         errors.push(`${label}.children must be an object.`);
         return;
       }
@@ -577,6 +890,7 @@ function readComponents(value, errors) {
     }
     const provides = readComponentContracts(entry.provides, `${label}.provides`, errors);
     const references = readComponentReferences(entry.references, `${label}.references`, match, errors);
+    const supports = readComponentSupports(entry.supports, `${label}.supports`, errors);
     if (errors.length !== errorCount) {
       return;
     }
@@ -591,7 +905,8 @@ function readComponents(value, errors) {
       ...children ? { children } : {},
       ...category ? { category } : {},
       ...provides ? { provides } : {},
-      ...references ? { references } : {}
+      ...references ? { references } : {},
+      ...supports ? { supports } : {}
     });
   });
   return result.length ? result : void 0;
@@ -631,7 +946,7 @@ function readListing(value, errors) {
   if (value === void 0 || value === null) {
     return void 0;
   }
-  if (!isPlainObject(value)) {
+  if (!isPlainObject2(value)) {
     errors.push("App definition listing must be an object.");
     return void 0;
   }
@@ -671,7 +986,7 @@ function readListing(value, errors) {
       value.screenshots.forEach((entry, index) => {
         const label = `App definition listing.screenshots[${index}]`;
         const raw = typeof entry === "string" ? { file: entry } : entry;
-        if (!isPlainObject(raw)) {
+        if (!isPlainObject2(raw)) {
           errors.push(`${label} must be a path or an object with a file.`);
           return;
         }
@@ -686,7 +1001,7 @@ function readListing(value, errors) {
     }
   }
   if (value.publisher !== void 0 && value.publisher !== null) {
-    const publisher = isPlainObject(value.publisher) ? value.publisher : {};
+    const publisher = isPlainObject2(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.");
@@ -705,7 +1020,7 @@ var AGENT_CAPABILITY_ID_PATTERN = /^[a-z0-9][a-z0-9_-]{0,47}$/;
 var AGENT_LOCALE_PATTERN = /^[a-z]{2,3}(?:-[A-Za-z0-9]{2,8})*$/;
 var AGENT_GUIDE_PATH_PATTERN = /^[A-Za-z0-9_][A-Za-z0-9_.\/-]{0,199}\.md$/;
 function readAgentLocaleText(value, label, maxLength, errors) {
-  if (!isPlainObject(value)) {
+  if (!isPlainObject2(value)) {
     errors.push(`${label} must be an object of per-locale strings with an "en" entry.`);
     return void 0;
   }
@@ -736,7 +1051,7 @@ function readAgentLocaleList(value, label, maxLength, errors) {
   if (value === void 0) {
     return void 0;
   }
-  if (!isPlainObject(value)) {
+  if (!isPlainObject2(value)) {
     errors.push(`${label} must be an object of per-locale string arrays with an "en" entry.`);
     return void 0;
   }
@@ -777,7 +1092,7 @@ function readAgentCapabilities(value, errors) {
   const ids = /* @__PURE__ */ new Set();
   for (const [index, entry] of value.entries()) {
     const at = `${label}[${index}]`;
-    if (!isPlainObject(entry)) {
+    if (!isPlainObject2(entry)) {
       errors.push(`${at} must be an object.`);
       return void 0;
     }
@@ -820,7 +1135,7 @@ function readAgentProfile(value, errors) {
   if (value === void 0 || value === null) {
     return void 0;
   }
-  if (!isPlainObject(value)) {
+  if (!isPlainObject2(value)) {
     errors.push("App definition agent must be an object.");
     return void 0;
   }
@@ -883,7 +1198,7 @@ function resolveMindooDBAppListingAssetUrl(path, originUrl) {
 }
 function validateMindooDBAppDefinition(raw) {
   const errors = [];
-  if (!isPlainObject(raw)) {
+  if (!isPlainObject2(raw)) {
     return { definition: null, errors: ["App definition must be a JSON object."] };
   }
   if (raw.format !== MINDOODB_APP_DEFINITION_FORMAT) {
@@ -1397,29 +1712,29 @@ function bindDragSource(element, options, start, follow) {
 }
 
 // src/client/agentInput.ts
-function isPlainObject2(value) {
+function isPlainObject3(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function isPlaceholder(value) {
   if (value === null || value === void 0) return true;
   if (typeof value === "string") return value.trim() === "";
   if (Array.isArray(value)) return value.length === 0;
-  if (isPlainObject2(value)) return Object.keys(value).length === 0;
+  if (isPlainObject3(value)) return Object.keys(value).length === 0;
   return false;
 }
 function normalizeValue(value, schema) {
-  if (!isPlainObject2(schema)) return value;
+  if (!isPlainObject3(schema)) return value;
   if (Array.isArray(value)) {
     const items = schema.items;
-    return isPlainObject2(items) ? value.map((item) => normalizeValue(item, items)) : value;
+    return isPlainObject3(items) ? value.map((item) => normalizeValue(item, items)) : value;
   }
-  if (isPlainObject2(value) && isPlainObject2(schema.properties)) {
+  if (isPlainObject3(value) && isPlainObject3(schema.properties)) {
     return normalizeObject(value, schema);
   }
   return value;
 }
 function normalizeObject(input, schema) {
-  const properties = isPlainObject2(schema.properties) ? schema.properties : {};
+  const properties = isPlainObject3(schema.properties) ? schema.properties : {};
   const required = new Set(Array.isArray(schema.required) ? schema.required.filter((key) => typeof key === "string") : []);
   const result = {};
   for (const [key, raw] of Object.entries(input)) {
@@ -1434,7 +1749,7 @@ function normalizeObject(input, schema) {
   return result;
 }
 function normalizeAgentToolInput(input, schema) {
-  return isPlainObject2(input) ? normalizeObject(input, schema) : input;
+  return isPlainObject3(input) ? normalizeObject(input, schema) : input;
 }
 
 // src/client/agentTools.ts
@@ -1538,6 +1853,83 @@ var MindooDBAppAgentApiImpl = class {
   }
 };
 
+// src/embedExchange.ts
+var MINDOODB_APP_EMBED_VARIABLES_MAX = 200;
+var VARIABLE_KEY = /^[A-Za-z_][A-Za-z0-9_.-]{0,63}$/;
+function normalizeMindooDBAppEmbedVariables(raw) {
+  if (!Array.isArray(raw)) {
+    return [];
+  }
+  const byKey = /* @__PURE__ */ new Map();
+  for (const entry of raw) {
+    if (!entry || typeof entry !== "object") continue;
+    const { key, label, value, group } = entry;
+    if (typeof key !== "string" || !VARIABLE_KEY.test(key)) continue;
+    const text = (input, max) => typeof input === "string" ? input.slice(0, max) : "";
+    byKey.delete(key);
+    byKey.set(key, {
+      key,
+      label: text(label, 120).trim() || key,
+      value: typeof value === "number" || typeof value === "boolean" ? String(value) : text(value, 4e3),
+      ...typeof group === "string" && group.trim() ? { group: group.trim().slice(0, 80) } : {}
+    });
+    if (byKey.size >= MINDOODB_APP_EMBED_VARIABLES_MAX) break;
+  }
+  return [...byKey.values()];
+}
+function resolveMindooDBAppVariables(text, variables, options = {}) {
+  const values = new Map(variables.map((variable) => [variable.key, variable.value]));
+  return text.replace(/\{\{\s*([A-Za-z_][A-Za-z0-9_.-]{0,63})\s*\}\}/g, (match, key) => {
+    const value = values.get(key);
+    return value === void 0 || !value && !options.keepEmpty ? match : value;
+  });
+}
+var MINDOODB_APP_EMBED_EXPORT_MAX_BYTES = 64 * 1024 * 1024;
+var EXPORT_TYPES = {
+  pdf: "application/pdf",
+  docx: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+  xlsx: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+  pptx: "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+  png: "image/png",
+  md: "text/markdown",
+  csv: "text/csv"
+};
+function mindooDBAppExportMimeType(format) {
+  return EXPORT_TYPES[format] ?? "application/octet-stream";
+}
+function normalizeMindooDBAppEmbedExportRequest(raw) {
+  const input = raw && typeof raw === "object" ? raw : {};
+  const format = typeof input.format === "string" ? input.format.trim().toLowerCase() : "";
+  if (!/^[a-z0-9][a-z0-9-]{0,31}$/.test(format)) {
+    throw new Error('An export needs a format such as "pdf" or "png".');
+  }
+  const size = (value) => {
+    const number = Number(value);
+    return Number.isFinite(number) && number > 0 ? Math.min(Math.round(number), 8192) : void 0;
+  };
+  const maxWidth = size(input.maxWidth);
+  const maxHeight = size(input.maxHeight);
+  return { format, ...maxWidth ? { maxWidth } : {}, ...maxHeight ? { maxHeight } : {} };
+}
+async function mindooDBAppExportPayload(result, request, baseName = "document") {
+  const blob = result instanceof Blob ? result : null;
+  const data = blob ?? result.data;
+  const bytes = data instanceof Blob ? await data.arrayBuffer() : ArrayBuffer.isView(data) ? data.buffer.slice(data.byteOffset, data.byteOffset + data.byteLength) : data;
+  if (Object.prototype.toString.call(bytes) !== "[object ArrayBuffer]") {
+    throw new Error("An export must be a Blob, an ArrayBuffer or a Uint8Array.");
+  }
+  if (bytes.byteLength > MINDOODB_APP_EMBED_EXPORT_MAX_BYTES) {
+    throw new Error(`An export must not be larger than ${MINDOODB_APP_EMBED_EXPORT_MAX_BYTES / 1024 / 1024} MiB.`);
+  }
+  const named = blob ? blob.name : result.name;
+  const mimeType = !blob && result.mimeType || (blob?.type ? blob.type : "") || mindooDBAppExportMimeType(request.format);
+  const name = (typeof named === "string" && named.trim() ? named.trim() : `${baseName}.${request.format}`).slice(0, 200);
+  return { data: bytes, name, mimeType };
+}
+function mindooDBAppExportFile(payload) {
+  return new File([payload.data], payload.name, { type: payload.mimeType });
+}
+
 // src/directoryPaging.ts
 var LIST_USERS_DEFAULT_LIMIT = 50;
 var LIST_USERS_MAX_LIMIT = 500;
@@ -1651,6 +2043,15 @@ import { parseMindooDBFormulaBooleanExpression } from "mindoodb-view-language";
 function isEmbedEventMessage(message) {
   return message.kind === "embed-event";
 }
+function isEmbedRequestMessage(message) {
+  return message.kind === "embed-request";
+}
+function isMethodNotFound(error) {
+  return error instanceof Error && error.name === "method-not-found";
+}
+function errorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
 function isEmbeddingRequestMessage(message) {
   return message.kind === "embedding-request";
 }
@@ -1717,13 +2118,14 @@ function createComponentFrame(container, url, allow) {
   return frame;
 }
 var MindooDBAppEmbedImpl = class {
-  constructor(rpc, embedId, componentKey, databaseId, docId, frame, container) {
+  constructor(rpc, embedId, componentKey, databaseId, docId, frame, container, supports = []) {
     this.rpc = rpc;
     this.embedId = embedId;
     this.componentKey = componentKey;
     this.databaseId = databaseId;
     this.docId = docId;
     this.frame = frame;
+    this.supports = supports;
     this.closed = new Promise((resolve) => {
       this.resolveClosed = resolve;
     });
@@ -1740,6 +2142,7 @@ var MindooDBAppEmbedImpl = class {
   databaseId;
   docId;
   frame;
+  supports;
   closed;
   resolveClosed;
   closedEvent = null;
@@ -1749,6 +2152,8 @@ var MindooDBAppEmbedImpl = class {
   tracker = null;
   toolsState = null;
   toolsListeners = /* @__PURE__ */ new Set();
+  beforeSaveHandler = null;
+  savedListeners = /* @__PURE__ */ new Set();
   get placement() {
     return this.frame ? "frame" : "overlay";
   }
@@ -1831,6 +2236,104 @@ var MindooDBAppEmbedImpl = class {
       const stopClosed = this.onClosed(() => finish(null));
     });
   }
+  async inspect(request) {
+    const result = await this.rpc.call("embeds.inspect", {
+      embedId: this.embedId,
+      request: normalizeMindooDBAppInspectRequest(request)
+    });
+    return normalizeMindooDBAppInspection(result);
+  }
+  onBeforeSave(handler, options) {
+    this.beforeSaveHandler = handler;
+    this.announceBeforeSave(true, options?.inspect);
+    return () => {
+      if (this.beforeSaveHandler === handler) {
+        this.beforeSaveHandler = null;
+        this.announceBeforeSave(false);
+      }
+    };
+  }
+  /** Haven only asks hosts that said they check, and fetches the inspection they want. */
+  announceBeforeSave(enabled, inspect) {
+    if (this.closedEvent) {
+      return;
+    }
+    void this.rpc.call("embeds.setBeforeSave", {
+      embedId: this.embedId,
+      enabled,
+      ...enabled ? { inspect: normalizeMindooDBAppInspectRequest(inspect) } : {}
+    }).catch((error) => {
+      if (!isMethodNotFound(error)) {
+        console.warn("[mindoodb-app-sdk] Could not register the save check.", error);
+      }
+    });
+  }
+  /** Haven asks before the component saves: run the handler, never longer than Haven waits. */
+  async answerBeforeSave(params) {
+    const handler = this.beforeSaveHandler;
+    if (!handler || this.closedEvent) {
+      return { issues: [] };
+    }
+    const result = await handler({
+      embedId: this.embedId,
+      inspection: params?.inspection ?? null,
+      root: params?.root ?? null
+    });
+    return { issues: normalizeMindooDBAppIssues(result?.issues) };
+  }
+  onAfterSave(listener) {
+    this.savedListeners.add(listener);
+    return () => {
+      this.savedListeners.delete(listener);
+    };
+  }
+  /** The component reported that it saved. */
+  notifySaved() {
+    if (this.closedEvent) {
+      return;
+    }
+    const event = { embedId: this.embedId };
+    this.savedListeners.forEach((listener) => {
+      try {
+        listener(event);
+      } catch (error) {
+        console.error("MindooDB embed saved listener failed.", error);
+      }
+    });
+  }
+  async showIssues(issues) {
+    await this.rpc.call("embeds.showIssues", { embedId: this.embedId, issues: normalizeMindooDBAppIssues(issues) });
+  }
+  async reveal(anchor) {
+    const normalized = normalizeMindooDBAppInspectAnchor(anchor);
+    if (!normalized) {
+      throw new Error("Invalid anchor.");
+    }
+    await this.rpc.call("embeds.reveal", { embedId: this.embedId, anchor: normalized });
+  }
+  async setVariables(variables) {
+    await this.rpc.call("embeds.setVariables", {
+      embedId: this.embedId,
+      variables: normalizeMindooDBAppEmbedVariables(variables)
+    });
+  }
+  async export(request) {
+    const payload = await this.rpc.call("embeds.export", {
+      embedId: this.embedId,
+      request: normalizeMindooDBAppEmbedExportRequest(request)
+    });
+    if (!payload || Object.prototype.toString.call(payload.data) !== "[object ArrayBuffer]") {
+      throw new Error("The component handed over no file.");
+    }
+    return mindooDBAppExportFile(payload);
+  }
+  async callTool(name, input) {
+    return await this.rpc.call("embeds.callTool", {
+      embedId: this.embedId,
+      name: String(name),
+      input: input === void 0 ? {} : JSON.parse(JSON.stringify(input))
+    });
+  }
   async setRect(rect) {
     if (this.closedEvent) {
       return;
@@ -1885,6 +2388,8 @@ var MindooDBAppEmbedImpl = class {
     });
     this.listeners.clear();
     this.dirtyListeners.clear();
+    this.savedListeners.clear();
+    this.beforeSaveHandler = null;
     this.toolsState = null;
     this.toolsListeners.forEach((listener) => {
       try {
@@ -1904,6 +2409,10 @@ var MindooDBAppEmbedsClient = class {
         void this.answerRequest(message);
         return;
       }
+      if (isEmbedRequestMessage(message)) {
+        void this.answerEmbedRequest(message);
+        return;
+      }
       if (!isEmbedEventMessage(message)) {
         return;
       }
@@ -1927,6 +2436,10 @@ var MindooDBAppEmbedsClient = class {
         }
         return;
       }
+      if (message.event?.type === "saved") {
+        this.open.get(message.event.embedId)?.notifySaved();
+        return;
+      }
       if (message.event?.type !== "closed") {
         return;
       }
@@ -1951,10 +2464,17 @@ var MindooDBAppEmbedsClient = class {
       open: async (input) => {
         const { container, rect, ...rest } = input;
         const initialRect = container ? containerRect(container) : toRect(rect ?? { left: 0, top: 0, width: 0, height: 0 });
+        const { variables, template, ...plain } = rest;
         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" } : {} }
+          input: {
+            ...plain,
+            rect: initialRect,
+            ...container ? { placement: "frame" } : {},
+            ...variables ? { variables: normalizeMindooDBAppEmbedVariables(variables) } : {},
+            ...template ? { template: { docId: String(template.docId), ...template.databaseId ? { databaseId: String(template.databaseId) } : {} } } : {}
+          }
         });
         const frame = container && response.frame?.url ? createComponentFrame(container, response.frame.url, response.frame.allow) : null;
         const embed = new MindooDBAppEmbedImpl(
@@ -1964,7 +2484,8 @@ var MindooDBAppEmbedsClient = class {
           input.databaseId,
           input.docId,
           frame,
-          container
+          container,
+          Array.isArray(response.supports) ? response.supports.filter((entry) => typeof entry === "string") : []
         );
         const earlyDirty = this.earlyDirty.get(embed.embedId);
         if (earlyDirty !== void 0) {
@@ -2040,7 +2561,74 @@ var MindooDBAppEmbedsClient = class {
             this.saveHandler = null;
           }
         };
-      }
+      },
+      provideInspection: (provider) => {
+        this.inspectionProvider = provider;
+        return () => {
+          if (this.inspectionProvider === provider) {
+            this.inspectionProvider = null;
+          }
+        };
+      },
+      onShowIssues: (handler) => {
+        this.showIssuesHandler = handler;
+        return () => {
+          if (this.showIssuesHandler === handler) {
+            this.showIssuesHandler = null;
+          }
+        };
+      },
+      getVariables: async () => {
+        if (this.variables) {
+          return this.variables.map((variable) => ({ ...variable }));
+        }
+        try {
+          const result = await this.rpc.call("embedding.getVariables", {});
+          this.variables ??= normalizeMindooDBAppEmbedVariables(result?.variables);
+        } catch (error) {
+          if (!isMethodNotFound(error) && !(error instanceof Error && error.name === "unsupported")) {
+            throw error;
+          }
+          this.variables ??= [];
+        }
+        return this.variables.map((variable) => ({ ...variable }));
+      },
+      onVariablesChange: (listener) => {
+        this.variableListeners.add(listener);
+        return () => {
+          this.variableListeners.delete(listener);
+        };
+      },
+      provideExport: (provider) => {
+        this.exportProvider = provider;
+        return () => {
+          if (this.exportProvider === provider) {
+            this.exportProvider = null;
+          }
+        };
+      },
+      onReveal: (handler) => {
+        this.revealHandler = handler;
+        return () => {
+          if (this.revealHandler === handler) {
+            this.revealHandler = null;
+          }
+        };
+      },
+      validate: async (options) => await this.validate(options),
+      save: async (flush, options) => await performMindooDBAppEmbeddingSave({
+        validate: () => this.validate(options),
+        provider: this.inspectionProvider,
+        showIssues: this.showIssuesHandler,
+        flush,
+        // Only news for the host: a lost message must not fail a save that happened.
+        saved: () => this.rpc.call("embedding.saved", {}).then(
+          () => {
+          },
+          () => {
+          }
+        )
+      })
     };
   }
   rpc;
@@ -2055,18 +2643,71 @@ var MindooDBAppEmbedsClient = class {
   stopListening;
   /** This app as a component: what to do when its host asks it to save. */
   saveHandler = null;
-  /** Runs the save handler and tells Haven how it went; Haven answers the host. */
+  inspectionProvider = null;
+  showIssuesHandler = null;
+  revealHandler = null;
+  exportProvider = null;
+  /** The host's variables as last pushed; null until known (then asked for on first use). */
+  variables = null;
+  variableListeners = /* @__PURE__ */ new Set();
+  /** `embedding.validate`; ok when Haven cannot check (not embedded, older Haven). */
+  async validate(options) {
+    try {
+      const result = await this.rpc.call("embedding.validate", {
+        interactive: options?.interactive !== false
+      });
+      return {
+        ok: result?.ok !== false,
+        issues: normalizeMindooDBAppIssues(result?.issues),
+        ...result?.timedOut ? { timedOut: true } : {}
+      };
+    } catch (error) {
+      if (isMethodNotFound(error) || error instanceof Error && error.name === "unsupported") {
+        return { ok: true, issues: [] };
+      }
+      throw error;
+    }
+  }
+  /** Runs the matching handler and tells Haven how it went; Haven answers the host. */
   async answerRequest(message) {
     let response;
-    if (message.request !== "save" || !this.saveHandler) {
-      response = { ok: false, error: "unsupported" };
-    } else {
-      try {
+    try {
+      const params = message.params ?? {};
+      if (message.request === "save" && this.saveHandler) {
         await this.saveHandler();
         response = { ok: true };
-      } catch (error) {
-        response = { ok: false, error: error instanceof Error ? error.message : String(error) };
+      } else if (message.request === "inspect" && this.inspectionProvider) {
+        const inspection = await this.inspectionProvider(normalizeMindooDBAppInspectRequest(params.request));
+        response = { ok: true, result: normalizeMindooDBAppInspection(inspection) };
+      } else if (message.request === "showIssues" && this.showIssuesHandler) {
+        await this.showIssuesHandler(normalizeMindooDBAppIssues(params.issues));
+        response = { ok: true };
+      } else if (message.request === "reveal" && this.revealHandler) {
+        const anchor = normalizeMindooDBAppInspectAnchor(params.anchor);
+        if (!anchor) {
+          throw new Error("Invalid anchor.");
+        }
+        await this.revealHandler(anchor);
+        response = { ok: true };
+      } else if (message.request === "variables") {
+        this.variables = normalizeMindooDBAppEmbedVariables(params.variables);
+        const variables = this.variables;
+        this.variableListeners.forEach((listener) => {
+          try {
+            listener(variables.map((variable) => ({ ...variable })));
+          } catch (error) {
+            console.error("MindooDB embedding variables listener failed.", error);
+          }
+        });
+        response = { ok: true };
+      } else if (message.request === "export" && this.exportProvider) {
+        const request = normalizeMindooDBAppEmbedExportRequest(params.request);
+        response = { ok: true, result: await mindooDBAppExportPayload(await this.exportProvider(request), request) };
+      } else {
+        response = { ok: false, error: "unsupported" };
       }
+    } catch (error) {
+      response = { ok: false, error: errorMessage(error) };
     }
     try {
       await this.rpc.call("embedding.respond", { requestId: message.requestId, ...response });
@@ -2074,6 +2715,24 @@ var MindooDBAppEmbedsClient = class {
       console.warn("[mindoodb-app-sdk] Could not answer the host's request.", error);
     }
   }
+  /** This app as a host: Haven asks before one of its components saves. */
+  async answerEmbedRequest(message) {
+    let response;
+    const embed = this.open.get(message.embedId);
+    try {
+      response = message.request === "beforeSave" ? { ok: true, result: embed ? await embed.answerBeforeSave(message.params) : { issues: [] } } : { ok: false, error: "unsupported" };
+    } catch (error) {
+      response = {
+        ok: true,
+        result: { issues: [{ severity: "warning", message: `The check failed: ${errorMessage(error)}`, code: "check-failed" }] }
+      };
+    }
+    try {
+      await this.rpc.call("embeds.respond", { requestId: message.requestId, ...response });
+    } catch (error) {
+      console.warn("[mindoodb-app-sdk] Could not answer Haven's request.", error);
+    }
+  }
   dispose() {
     this.stopListening();
   }
@@ -3907,6 +4566,27 @@ export {
   isValidMindooDBDocumentId,
   mindooDBDocumentId,
   assertValidMindooDBCreateIds,
+  MINDOODB_INSPECT_DOCUMENT,
+  MINDOODB_INSPECT_SPREADSHEET,
+  MINDOODB_INSPECT_SLIDES,
+  MINDOODB_APP_INSPECTION_FIELD,
+  MINDOODB_APP_INSPECTION_SUMMARY_MAX_BYTES,
+  MINDOODB_APP_INSPECTION_MAX_BYTES,
+  MINDOODB_APP_ISSUES_MAX,
+  MindooDBAppEmbedValidationError,
+  mindooDBAppComponentSupports,
+  mindooDBAppInspectContracts,
+  normalizeMindooDBAppInspectAnchor,
+  normalizeMindooDBAppIssues,
+  normalizeMindooDBAppInspectRequest,
+  normalizeMindooDBAppInspection,
+  summarizeMindooDBAppInspection,
+  mindooDBAppInspectionSummaryValue,
+  readMindooDBAppInspectionSummary,
+  defineDocumentRules,
+  mindooDBAppInspectRules,
+  performMindooDBAppEmbeddingSave,
+  resolveMindooDBAppEmbedValidation,
   MINDOODB_APP_DEFINITION_FORMAT,
   MINDOODB_APP_DEFINITION_VERSION,
   MINDOODB_APP_DEFINITION_FILE_NAME,
@@ -3952,6 +4632,14 @@ export {
   bindDragSource,
   normalizeAgentToolInput,
   MindooDBAppAgentToolError,
+  MINDOODB_APP_EMBED_VARIABLES_MAX,
+  normalizeMindooDBAppEmbedVariables,
+  resolveMindooDBAppVariables,
+  MINDOODB_APP_EMBED_EXPORT_MAX_BYTES,
+  mindooDBAppExportMimeType,
+  normalizeMindooDBAppEmbedExportRequest,
+  mindooDBAppExportPayload,
+  mindooDBAppExportFile,
   pageUsers,
   DEFAULT_HAVEN_HOST_SHORTCUTS,
   matchHostShortcut,