unlayer-types 1.516.0 → 1.520.0

package/embed.d.ts

@@ -2102,10 +2102,10 @@ declare module "packages/editor/src/engine/config/features" {
      * Model identifier for the AI copilot.
      *
      * Accepts either:
-     *   - a bare model id (e.g. `"gpt-5.6-luna"`, `"claude-opus-5"`), where the
+     *   - a bare model id (e.g. `"gpt-5.6-luna"`, `"claude-opus-5-5"`), where the
      *     server infers the provider from the id, or
      *   - a `"<provider>/<modelId>"` pair (e.g. `"openai/gpt-5.6-luna"`,
-     *     `"anthropic/claude-opus-5"`) — preferred when the model id is
+     *     `"anthropic/claude-opus-5-5"`) — preferred when the model id is
      *     ambiguous across providers.
      *
      * Typed as a template literal union so editors autocomplete the known
@@ -2300,7 +2300,7 @@ declare module "packages/editor/src/engine/config/features" {
              * Preferred AI model for the assistant. Accepts:
              *
              * - a `"<provider>/<modelId>"` pair (e.g. `"openai/gpt-5.6-luna"`,
-             *   `"anthropic/claude-opus-5"`) — pins both provider and model,
+             *   `"anthropic/claude-opus-5-5"`) — pins both provider and model,
              *   unambiguous;
              * - a bare model id (e.g. `"gpt-5.6-luna"`);
              * - a provider name (e.g. `"openai"`, `"anthropic"`) — selects the
@@ -2537,7 +2537,7 @@ declare module "packages/editor/src/engine/config/features" {
              * Preferred AI model for the assistant. Accepts:
              *
              * - a `"<provider>/<modelId>"` pair (e.g. `"openai/gpt-5.6-luna"`,
-             *   `"anthropic/claude-opus-5"`) — pins both provider and model,
+             *   `"anthropic/claude-opus-5-5"`) — pins both provider and model,
              *   unambiguous;
              * - a bare model id (e.g. `"gpt-5.6-luna"`);
              * - a provider name (e.g. `"openai"`, `"anthropic"`) — selects the
@@ -2874,6 +2874,15 @@ declare module "packages/editor/src/embed/Config" {
             defaultErrors: Audit[];
         }) => Audit[] | Promise<Audit[]>;
         tabs?: Tabs;
+        /**
+         * Lets AI agents operating the page (browser agents, automation scripts)
+         * find this editor through `unlayer.agent` and edit its design JSON instead
+         * of driving the drag-and-drop UI. Once the editor confirms it supports
+         * this (older pinned or stable versions don't), appends a short pointer to
+         * the editor iframe's accessible name; nothing changes on screen. Set to
+         * `false` to leave this editor out of `unlayer.agent`. Defaults to `true`.
+         */
+        agentApi?: boolean;
     }
     export interface SaveDesignOptions {
     }
@@ -2887,6 +2896,12 @@ declare module "packages/editor/src/embed/Config" {
         live?: boolean;
         mergeTags?: MergeTagsValues;
         minify?: boolean;
+        /**
+         * Include classic Outlook for Windows and legacy IE conditional markup in
+         * email HTML. Defaults to true. False also removes custom HTML conditionals;
+         * AMP HTML and other display modes are unchanged.
+         */
+        outlookSupport?: boolean;
         popupId?: string;
         title?: string;
         validateAmp?: boolean;
@@ -2908,7 +2923,7 @@ declare module "packages/editor/src/embed/Config" {
     }
     export interface ExportLiveHtmlResult<TDisplayMode extends DisplayMode | undefined = undefined> extends ExportHtmlResult<TDisplayMode> {
     }
-    export interface ExportPlainTextOptions extends Omit<ExportHtmlOptions, 'cleanup' | 'minify'> {
+    export interface ExportPlainTextOptions extends Omit<ExportHtmlOptions, 'cleanup' | 'minify' | 'outlookSupport'> {
         ignorePreheader?: boolean;
     }
     export interface ExportPlainTextResult<TDisplayMode extends DisplayMode | undefined = undefined> {
@@ -2990,6 +3005,11 @@ declare module "packages/editor/src/embed/Frame" {
          */
         iframeTextColor?: string;
     }
+    /** What this frame's editor build says it supports. */
+    export interface FrameCapabilities {
+        /** Answers `agent:*` messages (`unlayer.agent`). */
+        agentApi: boolean;
+    }
     export class Frame {
         id: number;
         ready: boolean;
@@ -2999,9 +3019,19 @@ declare module "packages/editor/src/embed/Frame" {
         callbacks: {
             [key: number]: ((...args: any[]) => any) | undefined;
         };
+        /** Null until the editor announces itself (or the iframe finishes loading). */
+        capabilities: FrameCapabilities | null;
+        private capabilityListeners;
         constructor(src: string, options?: FrameOptions);
         createIframe(src: string, { iframeBackgroundColor, iframeTextColor }?: FrameOptions): HTMLIFrameElement;
         destroy: () => void;
+        /**
+         * Calls `listener` with the editor's capabilities once they are known, and
+         * again if they improve: an `unlayer:ready` that arrives after the load
+         * fallback still turns a capability on. Capabilities never turn off.
+         */
+        onCapabilities(listener: (capabilities: FrameCapabilities) => void): void;
+        private setCapabilities;
         appendTo(el: Element): void;
         onWindowMessage: (event: MessageEvent<any>) => void;
         postMessage(action: string, message: Message): void;
@@ -4168,6 +4198,165 @@ declare module "packages/editor/src/embed/iframeBackground" {
     export const getIframeBackgroundColor: (theme: unknown) => string | undefined;
     export const getIframeTextColor: (theme: unknown) => string | undefined;
 }
+declare module "packages/editor/src/embed/agent/agentHint" {
+    export const EDITOR_NAME = "Design editor";
+    export const AGENT_HINT = "AI agents: skip the UI, call unlayer.agent.describe() or unlayer_describe_editor";
+    /**
+     * Names the editor iframe and, when this editor answers agent calls, appends
+     * the pointer to `unlayer.agent`. The `title` attribute is not rendered as a
+     * tooltip on iframes, so nothing changes on screen. The host page script owns
+     * these strings, so they are not localized. `EDITOR_NAME` has no vendor
+     * branding; the pointer does name `unlayer`, because that is the global
+     * (and the site tool prefix) agents have to call.
+     */
+    export function applyAgentHint(iframe: HTMLIFrameElement | undefined, { agentApi }: {
+        agentApi: boolean;
+    }): void;
+}
+declare module "packages/editor/src/embed/agent/registry" {
+    import type { Frame } from "packages/editor/src/embed/Frame";
+    /** The slice of `Editor` the agent API needs, kept narrow to avoid a cycle. */
+    export interface AgentEditor {
+        frame: Frame | null;
+        readonly version: string | undefined;
+        readonly agentContainerId: string | null;
+    }
+    /** The editor's iframe hasn't said yet whether it supports the agent API. */
+    export function markAgentEditorPending(editor: AgentEditor): void;
+    /** The editor's iframe answers agent calls. */
+    export function registerAgentEditor(editor: AgentEditor): void;
+    export function unregisterAgentEditor(editor: AgentEditor): void;
+    export function getAgentEditors(): AgentEditor[];
+    /**
+     * Resolves once no editor on the page is still waiting for its iframe, or
+     * after `timeoutMs`. Lets an agent that calls right after page load reach an
+     * editor that is still booting instead of being told there is none.
+     */
+    export function whenAgentEditorsKnown(timeoutMs: number): Promise<void>;
+    export function getAgentRevision(editor: AgentEditor): number | undefined;
+    export function setAgentRevision(editor: AgentEditor, revision: unknown): void;
+}
+declare module "packages/editor/src/embed/agent/AgentApi" {
+    import type { ExportHtmlOptions, ExportHtmlResult } from "packages/editor/src/embed/Config";
+    import type { JSONTemplate } from "packages/editor/src/state/types/types";
+    export interface AgentTarget {
+        /** Index into `describe().editors`. Defaults to the first editor. */
+        editor?: number;
+    }
+    export interface AgentDesignIssue {
+        path: string;
+        message: string;
+        code: string;
+    }
+    export interface AgentLoadDesignResult {
+        /** True when the design passed validation and was loaded. */
+        ok: boolean;
+        loaded: boolean;
+        errors: AgentDesignIssue[];
+        errorCount: number;
+        /**
+         * Ids of elements the template protects (locked, or not editable,
+         * deletable, or movable) that the design tried to change. They keep their
+         * current content; everything else was applied.
+         */
+        protectedElements?: string[];
+        /** The editor's quality checks on the loaded design; null if they couldn't run. */
+        audit?: {
+            status: 'PASS' | 'FAIL';
+            issues: Array<{
+                severity: 'ERROR' | 'WARNING';
+                title: string;
+                description: string;
+                elementId?: string;
+            }>;
+            issueCount: number;
+        } | null;
+    }
+    export interface AgentEditorSummary {
+        index: number;
+        containerId: string | null;
+        version: string | undefined;
+    }
+    export interface AgentDescription {
+        /** Markdown instructions for the agent. Read this first. */
+        guide: string;
+        editors: AgentEditorSummary[];
+        editor: number;
+        displayMode: string;
+        designMode: string | null;
+        schemaVersion: number;
+        contentTypes: string[];
+        customTools: Array<Record<string, unknown> & {
+            slug: string;
+        }>;
+        /** Merge tags to personalize text with, written exactly as `value`. */
+        mergeTags: Array<{
+            name: string;
+            value: string;
+        }>;
+        fonts: Array<{
+            label: string;
+            value: string;
+        }>;
+    }
+    /**
+     * `unlayer.agent`: a promise-based surface for AI agents operating the page.
+     *
+     * Agents fail at the drag-and-drop UI but write good design JSON once they
+     * know `loadDesign` exists. This gives them one discoverable entry point,
+     * `describe()`, that returns instructions plus this editor's real
+     * capabilities (content types, custom tools, fonts), and a `loadDesign` that
+     * reports schema errors instead of silently loading a broken design.
+     */
+    export interface AgentApi {
+        /** Instructions and this editor's capabilities. Call this first. */
+        describe(target?: AgentTarget): Promise<AgentDescription>;
+        /** Full JSON Schema of the design this editor accepts, custom tools included. */
+        schema(target?: AgentTarget): Promise<Record<string, unknown>>;
+        getDesign(target?: AgentTarget): Promise<JSONTemplate>;
+        /**
+         * Validates, then loads. On `{ ok: false, loaded: false }` nothing changed;
+         * fix `errors` and retry.
+         */
+        loadDesign(design: JSONTemplate, options?: AgentTarget): Promise<AgentLoadDesignResult>;
+        exportHtml(options?: AgentTarget & ExportHtmlOptions): Promise<ExportHtmlResult>;
+        /**
+         * Opens the editor's preview at a device size, so the agent can check its
+         * work in a screenshot; `null` closes it and puts the canvas back on the
+         * device it was on. Resolves once the change has rendered.
+         */
+        preview(device: AgentPreviewDevice | null, target?: AgentTarget): Promise<void>;
+    }
+    export type AgentPreviewDevice = 'desktop' | 'tablet' | 'mobile';
+    export const agentApi: AgentApi;
+}
+declare module "packages/editor/src/embed/agent/agentSiteTools" {
+    /**
+     * Registers `unlayer.agent` as WebMCP site tools (`document.modelContext`).
+     *
+     * Some agents can't run JavaScript in the page at all — ChatGPT's agent mode
+     * among them — so they can never call `unlayer.agent`, however clearly the
+     * hint points to it. They do list the tools a page registers, and call those
+     * instead of clicking through the UI. Each tool is a thin wrapper over the
+     * matching `unlayer.agent` call, so both paths behave identically.
+     *
+     * Registered from the host page (embed.js), not the editor iframe: tools in a
+     * cross-origin iframe need an `allow="tools"` permission the embedder would
+     * have to grant.
+     */
+    interface SiteTool {
+        name: string;
+        description: string;
+        inputSchema: Record<string, unknown>;
+        annotations?: Record<string, boolean>;
+        execute: (input: Record<string, any>) => Promise<unknown>;
+    }
+    export function buildAgentSiteTools(): SiteTool[];
+    /** Registers the tools once, when the first agent-enabled editor appears. */
+    export function ensureAgentSiteTools(): void;
+    /** Unregisters the tools once no agent-enabled editor is left. */
+    export function releaseAgentSiteTools(): void;
+}
 declare module "packages/editor/src/embed/Editor" {
     import { Frame } from "packages/editor/src/embed/Frame";
     import type { Config, ExportFromApiResult, ExportHtmlOptions, ExportHtmlResult, ExportPlainTextResult, ExportImageFromApiOptions, ExportLiveHtmlOptions, ExportPdfFromApiOptions, ExportPlainTextOptions, ExportZipFromApiOptions, SaveDesignOptions, ExportLiveHtmlResult } from "packages/editor/src/embed/Config";
@@ -4191,6 +4380,9 @@ declare module "packages/editor/src/embed/Editor" {
         frame: Frame | null;
         constructor(config?: Config);
         init(config?: Config): void;
+        /** Container element id, so agents can tell several editors apart. */
+        get agentContainerId(): string | null;
+        private initAgentApi;
         private captureTargetElement;
         destroy(): void;
         versions: {
@@ -4319,9 +4511,16 @@ declare module "packages/editor/src/embed/Editor" {
 }
 declare module "packages/editor/src/embed/index" {
     import { Editor } from "packages/editor/src/embed/Editor";
+    import { type AgentApi } from "packages/editor/src/embed/agent/AgentApi";
     import type { Config } from "packages/editor/src/embed/Config";
     import type { DisplayMode } from "packages/editor/src/state/types/types";
     class Embed extends Editor {
+        /**
+         * Entry point for AI agents operating the page: start with
+         * `await unlayer.agent.describe()`. Covers every editor on the page,
+         * including `createEditor()` instances.
+         */
+        agent: AgentApi;
         createEditor<TDisplayMode extends DisplayMode | undefined = undefined>(config: Config): Editor<TDisplayMode>;
     }
     const _default: Embed;

package/package.json

@@ -1,5 +1,5 @@
 {
   "name": "unlayer-types",
-  "version": "1.516.0",
+  "version": "1.520.0",
   "license": "MIT"
 }