@fias/arche-sdk 2.12.0 → 2.14.0

package/dist/index.mjs

@@ -124,6 +124,12 @@ var FiasBridge = class {
     // useFiasPreviewState() callers don't collide. Providers produce a snapshot
     // on `preview_state_capture`; restore listeners receive it after the reload.
     this.previewStateProviders = /* @__PURE__ */ new Map();
+    /**
+     * The plugin's handler for host-dispatched Fias AI actions (one per plugin
+     * — `useFiasAIActions` owns registration). Throw/reject to report failure;
+     * the assistant awaits the result before telling the model it applied.
+     */
+    this.aiActionHandler = null;
     this.previewStateRestoreListeners = /* @__PURE__ */ new Map();
     // A restore payload that arrived before its hook registered (the host
     // restores on `ready`, but the React effect that registers runs later).
@@ -211,6 +217,30 @@ var FiasBridge = class {
         }
         return;
       }
+      if (data.type === "ai_action_dispatch") {
+        const { messageId } = data;
+        const payload = data.payload;
+        const handler = this.aiActionHandler;
+        void (async () => {
+          try {
+            if (typeof payload?.actionId !== "string") {
+              throw new Error("malformed dispatch: missing actionId");
+            }
+            if (!handler) {
+              throw new Error("the plugin has no Fias AI action handler registered");
+            }
+            await handler(payload.actionId, payload.params ?? {});
+            this.send("ai_action_result", { ok: true }, messageId);
+          } catch (err) {
+            this.send(
+              "ai_action_result",
+              { ok: false, error: err instanceof Error ? err.message : String(err) },
+              messageId
+            );
+          }
+        })();
+        return;
+      }
       if (data.type === "subscription_event") {
         const payload = data.payload;
         if (typeof payload?.subscriptionId === "string" && payload.event) {
@@ -491,6 +521,32 @@ var FiasBridge = class {
     this.subscriptionEndedListeners.delete(subscriptionId);
     this.send("subscription_unsubscribe", { subscriptionId });
   }
+  /**
+   * Register (or clear, with null) THE handler for host-dispatched Fias AI
+   * actions. One per plugin — `useFiasAIActions` owns this; last write wins.
+   */
+  setAiActionHandler(handler) {
+    this.aiActionHandler = handler;
+  }
+  /**
+   * Declare (or clear, with null) the plugin's runtime Fias AI actions.
+   * Fire-and-forget; the host validates, bounds, and throttles (~1/s), and
+   * honours the runtime lane only for TRUSTED arches — non-trusted plugins
+   * declare statically via the manifest `fiasAI` block. Requires the
+   * `ai:actions` permission.
+   */
+  declareAiActions(declaration) {
+    this.send("ai_actions_declare", declaration);
+  }
+  /**
+   * Push the state snapshot the assistant sees (and `availableWhen` filters
+   * against). Keep it SMALL and flag-shaped ({documentOpen: true, …}): the
+   * host drops snapshots over its byte cap, and accepted ones are embedded
+   * in the assistant's system prompt every turn.
+   */
+  sendAiState(state) {
+    this.send("ai_state", state);
+  }
   send(type, payload, messageId) {
     if (typeof window === "undefined") return;
     const message = {
@@ -1191,7 +1247,8 @@ function useFiasDataStore() {
           searchable: options?.searchable,
           writeMinRole: options?.writeMinRole,
           readMinRole: options?.readMinRole,
-          writePolicy: options?.writePolicy
+          writePolicy: options?.writePolicy,
+          constraints: options?.constraints
         }
       );
       return res.collection;
@@ -1214,12 +1271,18 @@ function useFiasDataStore() {
   );
   const put = useCallback(
     async (collection, key, data, options) => {
-      await invokeEntityOp(bridge, PLUGIN_DATASTORE_ENTITY_ID, "put", {
-        collection,
-        key,
-        data,
-        workspaceId: options?.workspaceId
-      });
+      const res = await invokeEntityOp(
+        bridge,
+        PLUGIN_DATASTORE_ENTITY_ID,
+        "put",
+        {
+          collection,
+          key,
+          data,
+          workspaceId: options?.workspaceId
+        }
+      );
+      return { version: res?.version };
     },
     [bridge]
   );
@@ -1251,6 +1314,7 @@ function useFiasDataStore() {
         key: res.key ?? key,
         data: res.data,
         updatedAt: res.updatedAt ?? "",
+        ...res.version !== void 0 ? { version: res.version } : {},
         ...res.authoredByCollaborator !== void 0 ? { authoredByCollaborator: res.authoredByCollaborator } : {}
       };
     },
@@ -1294,8 +1358,17 @@ function useFiasDataStore() {
     [bridge]
   );
   const batch = useCallback(
-    async (operations) => {
-      await invokeEntityOp(bridge, PLUGIN_DATASTORE_ENTITY_ID, "batch", { operations });
+    async (operations, options) => {
+      const res = await invokeEntityOp(
+        bridge,
+        PLUGIN_DATASTORE_ENTITY_ID,
+        "batch",
+        {
+          operations,
+          ...options?.preconditions?.length ? { preconditions: options.preconditions } : {}
+        }
+      );
+      return { written: res?.written };
     },
     [bridge]
   );
@@ -1694,6 +1767,12 @@ function useVaultDocuments() {
     ]
   );
 }
+function base64ToBytes(base64) {
+  const binary = atob(base64);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+  return bytes;
+}
 function bytesToBase64(bytes) {
   let binary = "";
   const chunk = 32768;
@@ -1859,7 +1938,21 @@ function useVaultUserDocuments() {
     },
     [bridge]
   );
-  return useMemo2(() => ({ pick, list, get, getDownloadUrl }), [pick, list, get, getDownloadUrl]);
+  const getBytes = useCallback(
+    async (documentId) => {
+      const res = await invokeEntityOp(bridge, VAULT_USER_DOCUMENTS_ENTITY_ID, "get_consented_document_bytes", { documentId });
+      return {
+        document: res.document,
+        bytes: base64ToBytes(res.bytesBase64),
+        contentType: res.contentType
+      };
+    },
+    [bridge]
+  );
+  return useMemo2(
+    () => ({ pick, list, get, getDownloadUrl, getBytes }),
+    [pick, list, get, getDownloadUrl, getBytes]
+  );
 }
 var COMMUNITY_ASSET_URL_REFRESH_BUFFER_MS = 3e4;
 var communityAssetUrlCache = /* @__PURE__ */ new Map();
@@ -2034,6 +2127,48 @@ function useCommunityAssets() {
     [publish, publishMany, unpublish, listMine, listCommunity, get, getUrl, getUrls, report]
   );
 }
+function useFiasAIActions(config) {
+  const bridge = useBridge();
+  const onActionRef = useRef(config?.onAction ?? null);
+  onActionRef.current = config?.onAction ?? null;
+  useEffect2(() => {
+    bridge.setAiActionHandler((actionId, params) => {
+      const handler = onActionRef.current;
+      if (!handler) {
+        throw new Error("no Fias AI action handler is currently registered");
+      }
+      return handler(actionId, params);
+    });
+    return () => bridge.setAiActionHandler(null);
+  }, [bridge]);
+  const declarationJson = config ? JSON.stringify({ description: config.description, actions: config.actions }) : null;
+  useEffect2(() => {
+    let cancelled = false;
+    void bridge.waitForInit().then(() => {
+      if (cancelled) return;
+      bridge.declareAiActions(
+        declarationJson ? JSON.parse(declarationJson) : null
+      );
+    });
+    return () => {
+      cancelled = true;
+    };
+  }, [bridge, declarationJson]);
+  useEffect2(() => {
+    return () => bridge.declareAiActions(null);
+  }, [bridge]);
+  const stateJson = config?.state ? JSON.stringify(config.state) : null;
+  useEffect2(() => {
+    if (stateJson === null) return;
+    let cancelled = false;
+    void bridge.waitForInit().then(() => {
+      if (!cancelled) bridge.sendAiState(JSON.parse(stateJson));
+    });
+    return () => {
+      cancelled = true;
+    };
+  }, [bridge, stateJson]);
+}
 
 // src/generated/surfaces.ts
 var AUDIO_AUDIO_ISOLATION_SURFACE_KEY = "audio.audio-isolation";
@@ -2101,6 +2236,7 @@ var useIntegrationWebSearch = () => useSurface(
 
 // src/generated/permissions.ts
 var VALID_PLUGIN_PERMISSIONS = [
+  "ai:actions",
   "assets:community:publish",
   "assets:community:read",
   "assets:read",
@@ -2127,6 +2263,7 @@ function isValidPluginPermission(perm) {
   return VALID_PLUGIN_PERMISSIONS.includes(perm);
 }
 var PLUGIN_PERMISSION_DESCRIPTIONS = {
+  "ai:actions": "Let Fias AI operate this app for you \u2014 only actions you could do yourself in its interface, and risky ones ask you first.",
   "assets:community:publish": "Share images you made here so other people using this app can see them, and manage what you have shared.",
   "assets:community:read": "Show you images that other people using this app have shared. Everything shared is checked before anyone can see it.",
   "assets:read": "Show images from this app's published asset library.",
@@ -2186,7 +2323,8 @@ var fias = {
           name,
           userScope: options?.userScope ?? "user",
           searchable: options?.searchable,
-          writePolicy: options?.writePolicy
+          writePolicy: options?.writePolicy,
+          constraints: options?.constraints
         }
       );
       return res.collection;
@@ -2202,12 +2340,16 @@ var fias = {
     async deleteCollection(name) {
       await invokeEntityOp(getBridge(), PLUGIN_DATASTORE_ENTITY_ID, "delete_collection", { name });
     },
+    /** Write a document. Resolves with the document's post-write `version`
+     *  (ADR-014) so a follow-up CAS batch needs no read-back. */
     async put(collection, key, data) {
-      await invokeEntityOp(getBridge(), PLUGIN_DATASTORE_ENTITY_ID, "put", {
-        collection,
-        key,
-        data
-      });
+      const res = await invokeEntityOp(
+        getBridge(),
+        PLUGIN_DATASTORE_ENTITY_ID,
+        "put",
+        { collection, key, data }
+      );
+      return { version: res?.version };
     },
     async get(collection, key) {
       const res = await invokeEntityOp(
@@ -2227,6 +2369,7 @@ var fias = {
         key: res.key ?? key,
         data: res.data,
         updatedAt: res.updatedAt ?? "",
+        ...res.version !== void 0 ? { version: res.version } : {},
         ...res.authoredByCollaborator !== void 0 ? { authoredByCollaborator: res.authoredByCollaborator } : {}
       };
     },
@@ -2250,9 +2393,20 @@ var fias = {
     async delete(collection, key) {
       await invokeEntityOp(getBridge(), PLUGIN_DATASTORE_ENTITY_ID, "delete", { collection, key });
     },
-    /** Apply up to 25 put/delete ops in one all-or-nothing transaction. */
-    async batch(operations) {
-      await invokeEntityOp(getBridge(), PLUGIN_DATASTORE_ENTITY_ID, "batch", { operations });
+    /** Apply up to 25 put/delete ops in one all-or-nothing transaction.
+     *  Pass `options.preconditions` (ADR-014) to make the batch conditional;
+     *  the result carries each put's post-write version. */
+    async batch(operations, options) {
+      const res = await invokeEntityOp(
+        getBridge(),
+        PLUGIN_DATASTORE_ENTITY_ID,
+        "batch",
+        {
+          operations,
+          ...options?.preconditions?.length ? { preconditions: options.preconditions } : {}
+        }
+      );
+      return { written: res?.written };
     }
   }
 };
@@ -4213,6 +4367,371 @@ function raceWithTimeout(promise, ms) {
 function useFiasFonts() {
   return useMemo3(() => ({ fonts: FONT_CATALOG, ensureFontLoaded }), []);
 }
+
+// src/panels.ts
+var PANEL_MIN_ELEMENTS = 1;
+var PANEL_MAX_ELEMENTS = 24;
+var PANEL_TITLE_MAX_LENGTH = 80;
+var PANEL_TEXT_MAX_LENGTH = 500;
+var PANEL_IMAGE_ALT_MAX_LENGTH = 120;
+var PANEL_IMAGE_KEY_MAX_LENGTH = 500;
+var PANEL_IMAGE_MIN_HEIGHT = 24;
+var PANEL_IMAGE_MAX_HEIGHT = 512;
+var PANEL_BUTTON_LABEL_MAX_LENGTH = 40;
+var PANEL_ACTION_MAX_LENGTH = 2048;
+var PANEL_EMIT_TOKEN_MAX_LENGTH = 64;
+var PANEL_ITEMS_EMPTY_TEXT_MAX_LENGTH = 120;
+var PANEL_ITEMS_SLOT_MAX_LENGTH = 64;
+var PANEL_SHOW_IF_MAX_LENGTH = 64;
+var PANEL_PRIORITY_ABS_MAX = 1e3;
+var PANEL_THEME_FONT_MAX_LENGTH = 200;
+var PANEL_THEME_AMOUNT_FORMAT_MAX_LENGTH = 24;
+var PANEL_THEME_Z_MAX = 1e6;
+var PANEL_THEME_LENGTH_MAX_INTEGER_DIGITS = 4;
+var PANEL_IMAGE_ROOTS = ["dfe-icons", "dfe-avatars"];
+var PANEL_ELEMENT_KINDS = [
+  "text",
+  "conditionalText",
+  "image",
+  "assetImage",
+  "items",
+  "slottedItems",
+  "button",
+  "spacer"
+];
+var PANEL_ID_PATTERN = /^[a-z0-9][a-z0-9-]{1,63}$/;
+var SLOT_PATTERN = new RegExp(`^[a-z0-9][a-z0-9_-]{0,${PANEL_ITEMS_SLOT_MAX_LENGTH - 1}}$`);
+var EMIT_TOKEN_PATTERN = new RegExp(`^[a-z0-9][a-z0-9_-]{0,${PANEL_EMIT_TOKEN_MAX_LENGTH - 1}}$`);
+var SHOW_IF_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+var ASSET_ID_PATTERN = /^as_[a-f0-9]{32}$/;
+var ARCHE_ID_PATTERN = /^arc_[a-f0-9]{32}$/;
+var IMAGE_KEY_PATTERN = new RegExp(
+  `^(?:${PANEL_IMAGE_ROOTS.join("|")})/[A-Za-z0-9._/-]+\\.(?:png|jpe?g|webp|gif|svg)$`,
+  "i"
+);
+var THEME_COLOR_PATTERN = /^(?:#(?:[0-9a-f]{3,4}|[0-9a-f]{6}|[0-9a-f]{8})|rgba?\(\s*\d{1,3}\s*,\s*\d{1,3}\s*,\s*\d{1,3}\s*(?:,\s*(?:0|1|0?\.\d{1,3})\s*)?\))$/i;
+var THEME_LENGTH_PATTERN = new RegExp(
+  `^\\d{1,${PANEL_THEME_LENGTH_MAX_INTEGER_DIGITS}}(?:\\.\\d{1,3})?(?:px|rem|em)$`
+);
+var THEME_FONT_PATTERN = /^[A-Za-z0-9 '",._-]+$/;
+var TEXT_STYLES = ["title", "body", "caption"];
+var TEXT_ALIGNS = ["left", "center", "right"];
+var SIZES = ["small", "medium", "large"];
+var BUTTON_VARIANTS = ["primary", "secondary"];
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function rejectUnknownKeys(value, allowed, path, issues) {
+  for (const key of Object.keys(value)) {
+    if (!allowed.includes(key)) issues.push(`${path}: unknown field "${key}"`);
+  }
+}
+function checkString(value, path, issues, opts) {
+  if (typeof value !== "string") {
+    issues.push(`${path}: expected a string`);
+    return;
+  }
+  if (value.length < (opts.min ?? 1)) issues.push(`${path}: must not be empty`);
+  if (value.length > opts.max) issues.push(`${path}: longer than ${opts.max} characters`);
+  if (opts.pattern && !opts.pattern.test(value)) {
+    issues.push(`${path}: ${opts.hint ?? "does not match the required format"}`);
+  }
+}
+function checkOptionalEnum(value, path, issues, allowed) {
+  if (value === void 0) return;
+  if (typeof value !== "string" || !allowed.includes(value)) {
+    issues.push(`${path}: must be one of ${allowed.join(" | ")}`);
+  }
+}
+function checkOptionalBoolean(value, path, issues) {
+  if (value !== void 0 && typeof value !== "boolean") issues.push(`${path}: expected a boolean`);
+}
+function checkOptionalIntRange(value, path, issues, min, max) {
+  if (value === void 0) return;
+  if (typeof value !== "number" || !Number.isInteger(value) || value < min || value > max) {
+    issues.push(`${path}: must be an integer between ${min} and ${max}`);
+  }
+}
+function validatePanelAction(action, path, issues) {
+  if (typeof action !== "string" || action.length === 0) {
+    issues.push(`${path}: expected an action string`);
+    return;
+  }
+  if (action.length > PANEL_ACTION_MAX_LENGTH) {
+    issues.push(`${path}: longer than ${PANEL_ACTION_MAX_LENGTH} characters`);
+    return;
+  }
+  if (action === "close") return;
+  if (action.startsWith("emit:")) {
+    if (!EMIT_TOKEN_PATTERN.test(action.slice("emit:".length))) {
+      issues.push(
+        `${path}: emit token must be 1\u2013${PANEL_EMIT_TOKEN_MAX_LENGTH} chars \u2014 lowercase letters, digits, hyphens and underscores, not starting with a separator`
+      );
+    }
+    return;
+  }
+  if (action.startsWith("open_arche:")) {
+    if (!ARCHE_ID_PATTERN.test(action.slice("open_arche:".length))) {
+      issues.push(`${path}: open_arche target must be an arche id (arc_ + 32 hex chars)`);
+    }
+    return;
+  }
+  if (action.startsWith("open_url:")) {
+    if (/\s/.test(action)) {
+      issues.push(`${path}: action must not contain whitespace`);
+      return;
+    }
+    let parsed;
+    try {
+      parsed = new URL(action.slice("open_url:".length));
+    } catch {
+      issues.push(`${path}: open_url must be a valid absolute URL`);
+      return;
+    }
+    if (parsed.protocol !== "https:") issues.push(`${path}: open_url scheme must be https`);
+    return;
+  }
+  issues.push(
+    `${path}: must be one of close | emit:<token> | open_arche:arc_<32 hex> | open_url:https://\u2026`
+  );
+}
+function validateTextFields(element, path, issues) {
+  checkString(element.text, `${path}.text`, issues, { max: PANEL_TEXT_MAX_LENGTH });
+  checkOptionalEnum(element.style, `${path}.style`, issues, TEXT_STYLES);
+  checkOptionalEnum(element.align, `${path}.align`, issues, TEXT_ALIGNS);
+  checkOptionalBoolean(element.joinNext, `${path}.joinNext`, issues);
+}
+function validateItemsFields(element, path, issues) {
+  checkOptionalBoolean(element.showIcons, `${path}.showIcons`, issues);
+  checkOptionalEnum(element.iconSize, `${path}.iconSize`, issues, SIZES);
+  if (element.emptyText !== void 0) {
+    checkString(element.emptyText, `${path}.emptyText`, issues, {
+      min: 0,
+      max: PANEL_ITEMS_EMPTY_TEXT_MAX_LENGTH
+    });
+  }
+}
+function validateImageFields(element, path, issues) {
+  if (element.alt !== void 0) {
+    checkString(element.alt, `${path}.alt`, issues, { min: 0, max: PANEL_IMAGE_ALT_MAX_LENGTH });
+  }
+  checkOptionalIntRange(
+    element.maxHeight,
+    `${path}.maxHeight`,
+    issues,
+    PANEL_IMAGE_MIN_HEIGHT,
+    PANEL_IMAGE_MAX_HEIGHT
+  );
+}
+function validateElement(value, path, issues) {
+  if (!isRecord(value)) {
+    issues.push(`${path}: expected an object`);
+    return;
+  }
+  const kind = value.kind;
+  if (typeof kind !== "string" || !PANEL_ELEMENT_KINDS.includes(kind)) {
+    issues.push(
+      `${path}.kind: unknown element kind ${JSON.stringify(kind)} \u2014 expected one of ${PANEL_ELEMENT_KINDS.join(" | ")}`
+    );
+    return;
+  }
+  switch (kind) {
+    case "text":
+      rejectUnknownKeys(value, ["kind", "text", "style", "align", "joinNext"], path, issues);
+      validateTextFields(value, path, issues);
+      return;
+    case "conditionalText":
+      rejectUnknownKeys(
+        value,
+        ["kind", "text", "style", "align", "joinNext", "showIf"],
+        path,
+        issues
+      );
+      validateTextFields(value, path, issues);
+      checkString(value.showIf, `${path}.showIf`, issues, {
+        max: PANEL_SHOW_IF_MAX_LENGTH,
+        pattern: SHOW_IF_PATTERN,
+        hint: "must be a value NAME (letters, digits, underscore; not starting with a digit) \u2014 expressions and operators are not supported"
+      });
+      return;
+    case "image":
+      rejectUnknownKeys(value, ["kind", "imageKey", "alt", "maxHeight"], path, issues);
+      checkString(value.imageKey, `${path}.imageKey`, issues, {
+        max: PANEL_IMAGE_KEY_MAX_LENGTH,
+        pattern: IMAGE_KEY_PATTERN,
+        hint: `must be a relative key under ${PANEL_IMAGE_ROOTS.join(" or ")}/ ending in an image extension (no URL, no leading slash)`
+      });
+      if (typeof value.imageKey === "string" && value.imageKey.includes("..")) {
+        issues.push(`${path}.imageKey: must not contain ".."`);
+      }
+      validateImageFields(value, path, issues);
+      return;
+    case "assetImage":
+      rejectUnknownKeys(value, ["kind", "assetId", "alt", "maxHeight"], path, issues);
+      checkString(value.assetId, `${path}.assetId`, issues, {
+        max: 64,
+        pattern: ASSET_ID_PATTERN,
+        hint: "must be an arche asset id (as_ + 32 hex chars)"
+      });
+      validateImageFields(value, path, issues);
+      return;
+    case "items":
+      rejectUnknownKeys(value, ["kind", "showIcons", "iconSize", "emptyText"], path, issues);
+      validateItemsFields(value, path, issues);
+      return;
+    case "slottedItems":
+      rejectUnknownKeys(
+        value,
+        ["kind", "slot", "showIcons", "iconSize", "emptyText"],
+        path,
+        issues
+      );
+      checkString(value.slot, `${path}.slot`, issues, {
+        max: PANEL_ITEMS_SLOT_MAX_LENGTH,
+        pattern: SLOT_PATTERN,
+        hint: "must be lowercase letters, digits, hyphens and underscores, not starting with a separator"
+      });
+      validateItemsFields(value, path, issues);
+      return;
+    case "button":
+      rejectUnknownKeys(value, ["kind", "label", "action", "variant"], path, issues);
+      checkString(value.label, `${path}.label`, issues, { max: PANEL_BUTTON_LABEL_MAX_LENGTH });
+      validatePanelAction(value.action, `${path}.action`, issues);
+      checkOptionalEnum(value.variant, `${path}.variant`, issues, BUTTON_VARIANTS);
+      return;
+    case "spacer":
+      rejectUnknownKeys(value, ["kind", "size"], path, issues);
+      checkOptionalEnum(value.size, `${path}.size`, issues, SIZES);
+      return;
+  }
+}
+var THEME_COLOR_FIELDS = ["bg", "fg", "border", "accent", "accentFg", "scrim"];
+var THEME_LENGTH_FIELDS = [
+  "radius",
+  "buttonRadius",
+  "gap",
+  "fontSize",
+  "widthSmall",
+  "widthMedium",
+  "widthLarge"
+];
+function validatePanelTheme(value, path = "theme") {
+  const issues = [];
+  if (!isRecord(value)) return { ok: false, issues: [`${path}: expected an object`] };
+  rejectUnknownKeys(
+    value,
+    [...THEME_COLOR_FIELDS, ...THEME_LENGTH_FIELDS, "font", "z", "amountFormat"],
+    path,
+    issues
+  );
+  for (const field of THEME_COLOR_FIELDS) {
+    if (value[field] === void 0) continue;
+    checkString(value[field], `${path}.${field}`, issues, {
+      max: 64,
+      pattern: THEME_COLOR_PATTERN,
+      hint: "must be a hex colour (#rgb, #rgba, #rrggbb, #rrggbbaa) or rgb()/rgba() with numeric components"
+    });
+  }
+  for (const field of THEME_LENGTH_FIELDS) {
+    if (value[field] === void 0) continue;
+    checkString(value[field], `${path}.${field}`, issues, {
+      max: 16,
+      pattern: THEME_LENGTH_PATTERN,
+      hint: `must be a non-negative number (max ${PANEL_THEME_LENGTH_MAX_INTEGER_DIGITS} digits before the point) followed by px, rem or em`
+    });
+  }
+  if (value.font !== void 0) {
+    checkString(value.font, `${path}.font`, issues, {
+      max: PANEL_THEME_FONT_MAX_LENGTH,
+      pattern: THEME_FONT_PATTERN,
+      hint: "must be a font-family stack (names, commas, quotes) \u2014 no parentheses, so no url() or var()"
+    });
+  }
+  checkOptionalIntRange(value.z, `${path}.z`, issues, 0, PANEL_THEME_Z_MAX);
+  if (value.amountFormat !== void 0) {
+    checkString(value.amountFormat, `${path}.amountFormat`, issues, {
+      max: PANEL_THEME_AMOUNT_FORMAT_MAX_LENGTH
+    });
+    if (typeof value.amountFormat === "string" && !value.amountFormat.includes("{n}")) {
+      issues.push(`${path}.amountFormat: must contain the placeholder {n}`);
+    }
+  }
+  return issues.length === 0 ? { ok: true, issues: [] } : { ok: false, issues };
+}
+function validatePanelDefinition(value, path = "panel") {
+  const issues = [];
+  if (!isRecord(value)) return { ok: false, issues: [`${path}: expected an object`] };
+  rejectUnknownKeys(value, ["id", "title", "elements", "presentation"], path, issues);
+  checkString(value.id, `${path}.id`, issues, {
+    max: 64,
+    pattern: PANEL_ID_PATTERN,
+    hint: "must be 2\u201364 chars: lowercase letters, digits and hyphens, not starting with a hyphen"
+  });
+  checkString(value.title, `${path}.title`, issues, { max: PANEL_TITLE_MAX_LENGTH });
+  if (!Array.isArray(value.elements)) {
+    issues.push(`${path}.elements: expected an array`);
+  } else {
+    if (value.elements.length < PANEL_MIN_ELEMENTS) {
+      issues.push(`${path}.elements: needs at least ${PANEL_MIN_ELEMENTS} element`);
+    }
+    if (value.elements.length > PANEL_MAX_ELEMENTS) {
+      issues.push(`${path}.elements: more than ${PANEL_MAX_ELEMENTS} elements`);
+    }
+    value.elements.forEach(
+      (element, index) => validateElement(element, `${path}.elements[${index}]`, issues)
+    );
+  }
+  if (value.presentation !== void 0) {
+    if (!isRecord(value.presentation)) {
+      issues.push(`${path}.presentation: expected an object`);
+    } else {
+      rejectUnknownKeys(
+        value.presentation,
+        ["size", "dismissible", "priority"],
+        `${path}.presentation`,
+        issues
+      );
+      checkOptionalEnum(value.presentation.size, `${path}.presentation.size`, issues, SIZES);
+      checkOptionalBoolean(
+        value.presentation.dismissible,
+        `${path}.presentation.dismissible`,
+        issues
+      );
+      checkOptionalIntRange(
+        value.presentation.priority,
+        `${path}.presentation.priority`,
+        issues,
+        -PANEL_PRIORITY_ABS_MAX,
+        PANEL_PRIORITY_ABS_MAX
+      );
+    }
+  }
+  return issues.length === 0 ? { ok: true, issues: [] } : { ok: false, issues };
+}
+function validatePanelCatalog(value) {
+  const issues = [];
+  if (!isRecord(value)) return { ok: false, issues: ["catalog: expected an object"] };
+  rejectUnknownKeys(value, ["panels", "theme"], "catalog", issues);
+  if (value.theme !== void 0) {
+    const theme = validatePanelTheme(value.theme, "catalog.theme");
+    if (!theme.ok) issues.push(...theme.issues);
+  }
+  if (!Array.isArray(value.panels)) {
+    issues.push("catalog.panels: expected an array");
+    return { ok: false, issues };
+  }
+  const seen = /* @__PURE__ */ new Set();
+  value.panels.forEach((panel, index) => {
+    const path = `catalog.panels[${index}]`;
+    const result = validatePanelDefinition(panel, path);
+    if (!result.ok) issues.push(...result.issues);
+    if (isRecord(panel) && typeof panel.id === "string") {
+      if (seen.has(panel.id)) issues.push(`${path}.id: duplicate panel id "${panel.id}"`);
+      seen.add(panel.id);
+    }
+  });
+  return issues.length === 0 ? { ok: true, issues: [] } : { ok: false, issues };
+}
 export {
   AUDIO_AUDIO_ISOLATION_SURFACE_KEY,
   AUDIO_FORCED_ALIGNMENT_SURFACE_KEY,
@@ -4245,6 +4764,21 @@ export {
   LIGHT_THEME,
   NLLB_LANGUAGES,
   NLLB_TRANSLATION_ENTITY_ID,
+  PANEL_BUTTON_LABEL_MAX_LENGTH,
+  PANEL_ELEMENT_KINDS,
+  PANEL_EMIT_TOKEN_MAX_LENGTH,
+  PANEL_IMAGE_ROOTS,
+  PANEL_ITEMS_SLOT_MAX_LENGTH,
+  PANEL_MAX_ELEMENTS,
+  PANEL_MIN_ELEMENTS,
+  PANEL_PRIORITY_ABS_MAX,
+  PANEL_SHOW_IF_MAX_LENGTH,
+  PANEL_TEXT_MAX_LENGTH,
+  PANEL_THEME_AMOUNT_FORMAT_MAX_LENGTH,
+  PANEL_THEME_FONT_MAX_LENGTH,
+  PANEL_THEME_LENGTH_MAX_INTEGER_DIGITS,
+  PANEL_THEME_Z_MAX,
+  PANEL_TITLE_MAX_LENGTH,
   PLUGIN_PERMISSION_DESCRIPTIONS,
   SDK_BRIDGE_PROTOCOL_VERSION,
   SDK_REQUIRES_HOST_PROTOCOL_VERSION,
@@ -4273,6 +4807,7 @@ export {
   useElevenLabsVoiceChanger,
   useElevenLabsVoiceDesign,
   useEntityInvocation,
+  useFiasAIActions,
   useFiasDataStore,
   useFiasFonts,
   useFiasNavigation,
@@ -4302,5 +4837,9 @@ export {
   useStepNavigation,
   useSurface,
   useVaultDocuments,
-  useVaultUserDocuments
+  useVaultUserDocuments,
+  validatePanelAction,
+  validatePanelCatalog,
+  validatePanelDefinition,
+  validatePanelTheme
 };