@unlayer/react-elements 0.1.16 → 0.1.18

package/README.md

@@ -47,6 +47,16 @@ function WelcomeEmail() {
 }
 ```
 
+## Using with AI agents (Claude, Cursor, etc.)
+
+Assembling these templates in code is something AI coding agents do well. The official **`unlayer-elements`** skill teaches them the strict structure, the canonical prop shapes, the image-sizing model, and the patterns that make generated emails actually look good:
+
+```bash
+npx skills add unlayer/unlayer-skills
+```
+
+This installs the `unlayer-elements` skill (alongside the other Unlayer skills). Your agent then knows how to build emails, pages, and documents with these components and render them via `renderToHtml` / `renderToJson`. See [unlayer/unlayer-skills](https://github.com/unlayer/unlayer-skills).
+
 ## Critical Rules
 
 These props have non-obvious shapes that **must** be followed exactly:
@@ -293,7 +303,7 @@ Each wrapper threads the correct mode to all children automatically.
 
 ## renderToHtml
 
-Render any element tree to a clean HTML string — no React hydration markers, perfect for email sending and PDF generation:
+Render any element tree to a complete, ready-to-use HTML document — from `<!DOCTYPE ...>` to `</html>` — with no React hydration markers. Perfect for email sending and PDF generation:
 
 ```tsx
 import { renderToHtml, Email, Row, Column, ColumnLayouts, Paragraph, Button } from '@unlayer/react-elements';
@@ -311,10 +321,44 @@ const html = renderToHtml(
         </Button>
       </Column>
     </Row>
+  </Email>,
+  { title: "Welcome" }
+);
+```
+
+The document shell matches the mode: `<Email>` gets the XHTML transitional doctype plus the MSO conditional comments Outlook needs, `<Page>` gets a standard HTML5 shell, and `<Document>` gets a print/PDF-friendly XHTML shell. Options accept config overrides plus:
+
+- `title` — document `<title>`
+- `fonts` — web-font stylesheet URLs to load via `<link>` tags, e.g. `[{ url: "https://fonts.googleapis.com/css2?family=Inter" }]`
+
+If your app owns the document shell (an existing page template, an ESP template, an iframe `srcdoc`), use `renderToHtmlParts` instead — it returns `{ head, body }` chunks for you to place yourself.
+
+## Custom Tools
+
+**A custom tool is the custom component you create.** We keep the editor's term — Custom Tools — because it's the same API across the Builder and Elements, and that shared vocabulary is where the power is: the same definition you pass to the editor's [`unlayer.registerTool`](https://docs.unlayer.com/builder/tools/custom) renders from code too. Elements uses the `renderer.exporters` and `renderer.head` halves of the definition; the editor-only parts (`label`, `icon`, `options`, `Viewer`, `validator`) are accepted and ignored:
+
+```tsx
+import { registerTool, Email, Row, Column, renderToHtml, renderToJson } from '@unlayer/react-elements';
+import { countdownTool } from './countdown-tool'; // the same object you register in the editor
+
+const Countdown = registerTool(countdownTool); // same term, same config as the editor
+
+const tree = (
+  <Email>
+    <Row><Column>
+      <Countdown endTime="2026-08-01T00:00:00Z" digitColor="#e11d48" />
+    </Column></Row>
   </Email>
 );
+
+renderToHtml(tree);  // renders via YOUR exporters — identical output to editor exports
+renderToJson(tree);  // emits { type: "custom", slug: "countdown", values } — opens in the Builder as the real tool
 ```
 
+- Props are the tool's `values` (flat), merged over the definition's defaults; `values={{...}}` works as an escape hatch.
+- Modes fall back like the editor: `document` uses the `web` exporter; an email-only tool renders via its `email` exporter everywhere.
+- **Sanitization:** when your config provides `toSafeHtml`, the tool's HTML output is passed through it (matching editor exports). The default config has no sanitizer — configure one if tool values can contain untrusted content.
+
 ## UnlayerProvider
 
 Configure global settings like CDN base URL, merge tags, text direction, and rendering mode:

package/dist/index.cjs

@@ -198,6 +198,50 @@ function textNodeToHtml(node) {
   }
   return html;
 }
+var NUMERIC_ALIGN = {
+  1: "left",
+  2: "center",
+  3: "right",
+  4: "justify"
+};
+function dirAttribute(direction) {
+  return direction === "ltr" || direction === "rtl" ? ` dir="${direction}"` : "";
+}
+function paragraphAlign(format) {
+  if (typeof format === "string") {
+    return ["left", "center", "right", "justify"].includes(format) ? format : void 0;
+  }
+  if (typeof format === "number") {
+    return NUMERIC_ALIGN[format];
+  }
+  return void 0;
+}
+function paragraphNodeToHtml(node, childrenHtml) {
+  const isInlineTool = !!node.isInlineTool;
+  const tag = isInlineTool ? "span" : "p";
+  const dir = dirAttribute(node.direction);
+  const styleParts = [];
+  if (node.style) {
+    styleParts.push(String(node.style).replace(/;+\s*$/, ""));
+  }
+  if (!isInlineTool) {
+    styleParts.push(
+      "margin: 0px",
+      "margin-block-start: 0px",
+      "margin-block-end: 0px"
+    );
+  }
+  const indent = Number(node.indent) || 0;
+  if (indent > 0) {
+    styleParts.push(`padding-inline-start: ${indent * 40}px`);
+  }
+  const align = paragraphAlign(node.format);
+  if (align) {
+    styleParts.push(`text-align: ${align}`);
+  }
+  const style = styleParts.length > 0 ? ` style="${escapeHtml(styleParts.join("; ") + ";")}"` : "";
+  return `<${tag}${dir}${style}>${childrenHtml || "<br>"}</${tag}>`;
+}
 function nodeToHtml(node) {
   if (!node || typeof node !== "object") return "";
   const type = node.type;
@@ -212,14 +256,11 @@ function nodeToHtml(node) {
     case "root":
       return childrenHtml;
     case "paragraph":
-    case "extended-paragraph": {
-      if (!childrenHtml) return "<p><br></p>";
-      const dir = node.direction ? ` dir="${node.direction}"` : "";
-      return `<p${dir}>${childrenHtml}</p>`;
-    }
+    case "extended-paragraph":
+      return paragraphNodeToHtml(node, childrenHtml);
     case "heading": {
-      const tag = node.tag || "h1";
-      const dir = node.direction ? ` dir="${node.direction}"` : "";
+      const tag = /^h[1-6]$/.test(node.tag) ? node.tag : "h1";
+      const dir = dirAttribute(node.direction);
       return `<${tag}${dir}>${childrenHtml}</${tag}>`;
     }
     case "link": {
@@ -579,16 +620,6 @@ function nextHtmlId(config, prefix) {
   ids[prefix] = (ids[prefix] || 0) + 1;
   return `${prefix}_${ids[prefix]}`;
 }
-function ensureMeta(values, type, index = 0) {
-  return {
-    ...values,
-    _meta: {
-      htmlID: `u_content_${type.toLowerCase()}_${index + 1}`,
-      htmlClassNames: `u_content_${type.toLowerCase()}`,
-      ...values._meta || {}
-    }
-  };
-}
 function renderComponent(config) {
   const { type, values, className, style, args = [], innerHTML, _config, exporter, metaContext } = config;
   try {
@@ -641,6 +672,7 @@ function createItemComponent(config) {
       style,
       // Internal props
       index = 0,
+      _metaHtmlId,
       colIndex = 0,
       cells = [],
       bodyValues = {},
@@ -658,11 +690,15 @@ function createItemComponent(config) {
       ...restProps
     });
     const finalValues = mergeValues(config.defaultValues, mappedValues);
-    const valuesWithMeta = ensureMeta(
-      finalValues,
-      config.name.toLowerCase(),
-      index
-    );
+    const metaName = config.metaName ?? config.name.toLowerCase();
+    const valuesWithMeta = {
+      ...finalValues,
+      _meta: {
+        htmlID: _metaHtmlId ?? `u_content_${metaName}_${index + 1}`,
+        htmlClassNames: `u_content_${metaName}`,
+        ...finalValues._meta || {}
+      }
+    };
     const safeBodyValues = {
       contentWidth: "500px",
       ...bodyValues
@@ -711,7 +747,11 @@ function createItemComponent(config) {
   ItemComponent[UNLAYER_CONFIG_KEY] = {
     name: config.name,
     defaultValues: config.defaultValues,
-    propMapper: config.propMapper
+    propMapper: config.propMapper,
+    contentType: config.contentType,
+    slug: config.slug,
+    metaName: config.metaName,
+    head: config.head
   };
   return ItemComponent;
 }
@@ -1122,7 +1162,7 @@ function getWidthPercentages(cells) {
     return { value, className };
   });
 }
-function generateGridCSS(cells, mode, contentWidth = 600, mobileBreakpoint = 620) {
+function generateGridCSS(cells, mode, contentWidth = 600, mobileBreakpoint = 480) {
   const widths = getWidthPercentages(cells);
   if (mode === "email") {
     const minQuery = `@media only screen and (min-width: ${contentWidth + 20}px)`;
@@ -1159,21 +1199,14 @@ ${widths.map(({ value, className }) => `  .no-stack .u-col-${className} { width:
   const columnCSS = widths.map(
     ({ value, className }) => `.u-row .u-col.u-col-${className} { flex: 0 0 ${value}%; max-width: ${value}%; }`
   ).join("\n");
-  const responsiveCSS = `
-@media only screen and (max-width: ${mobileBreakpoint}px) {
-  .u-row { width: 100% !important; }
-  .u-row .u-col {
-    display: block !important;
-    width: 100% !important;
-    min-width: 320px !important;
+  const responsiveCSS = mode === "document" ? "" : `
+@media (max-width: ${mobileBreakpoint}px) {
+  .u_row .container { max-width: 100% !important; }
+  .u-row:not(.no-stack) { flex-wrap: wrap; }
+  .u-row:not(.no-stack) .u-col {
+    flex: 0 0 100% !important;
     max-width: 100% !important;
   }
-  .u-row .u-col > div { margin: 0 auto; }
-  .no-stack .u-col {
-    min-width: 0 !important;
-    display: table-cell !important;
-  }
-${widths.map(({ value, className }) => `  .no-stack .u-col-${className} { width: ${value}% !important; }`).join("\n")}
 }`;
   return baseCSS + "\n" + columnCSS + "\n" + responsiveCSS;
 }
@@ -1340,9 +1373,12 @@ var Column = (props) => {
           if (typeof child.type === "function") {
             const ComponentType = child.type;
             const renderFn = ComponentType[UNLAYER_RENDER_KEY] || ComponentType;
+            const componentName = ComponentType?.[UNLAYER_CONFIG_KEY]?.metaName ?? (ComponentType?.displayName || ComponentType?.name || "component").toLowerCase();
+            const contentHtmlId = nextHtmlId(_config, `u_content_${componentName}`);
             const rendered = renderFn({
               ...child.props,
               _config,
+              _metaHtmlId: contentHtmlId,
               colIndex: index,
               cells,
               bodyValues,
@@ -1351,15 +1387,13 @@ var Column = (props) => {
             });
             if (rendered && typeof rendered === "object" && rendered.props && rendered.props.dangerouslySetInnerHTML) {
               const componentHTML = rendered.props.dangerouslySetInnerHTML.__html;
-              const componentType = child.type;
-              const componentName = (componentType?.displayName || componentType?.name || "component").toLowerCase();
               const childProps = child.props;
               const rawContainerPadding = childProps.containerPadding ?? childProps.values?.containerPadding ?? DEFAULT_CONTAINER_PADDING2;
               const containerPadding = typeof rawContainerPadding === "number" ? `${rawContainerPadding}px` : rawContainerPadding;
               const contentValues = {
                 containerPadding,
                 _meta: {
-                  htmlID: nextHtmlId(_config, `u_content_${componentName}`),
+                  htmlID: contentHtmlId,
                   htmlClassNames: `u_content_${componentName}`
                 }
               };
@@ -1530,7 +1564,7 @@ UnlayerProvider.displayName = "UnlayerProvider";
 function useUnlayerConfig() {
   return React.useContext(getUnlayerContext());
 }
-function ensureMeta2(values, type, index = 0) {
+function ensureMeta(values, type, index = 0) {
   return {
     ...values,
     _meta: {
@@ -1611,17 +1645,17 @@ function walkItem(element, bodyValues, displayMode, headConfig, counters, styles
   const { children, ...restProps } = element.props;
   const mappedValues = propMapper({ children, ...restProps });
   const finalValues = mergeValues(defaultValues, mappedValues);
-  const contentType = name.toLowerCase();
+  const contentType = config.metaName ?? name.toLowerCase();
   const count = nextCounter(counters, `u_content_${contentType}`);
-  const valuesWithMeta = ensureMeta2(finalValues, contentType, count - 1);
-  const head = exporters.heads[name];
+  const valuesWithMeta = ensureMeta(finalValues, contentType, count - 1);
+  const head = config.head ?? exporters.heads[name];
   callHead(head, valuesWithMeta, bodyValues, displayMode, headConfig, styles, scripts, tags);
 }
 function walkColumn(element, bodyValues, rowValues, displayMode, headConfig, counters, styles, scripts, tags) {
   const semanticProps = extractSemanticProps(element.props);
   const mapped = mapSemanticProps(semanticProps, COLUMN_DEFAULTS, "Column");
   const count = nextCounter(counters, "u_column");
-  const columnValues = ensureMeta2(mergeValues(COLUMN_DEFAULTS, mapped), "column", count - 1);
+  const columnValues = ensureMeta(mergeValues(COLUMN_DEFAULTS, mapped), "column", count - 1);
   const columnHead = exporters.heads["Column"];
   callHead(columnHead, columnValues, bodyValues, displayMode, headConfig, styles, scripts, tags);
   const children = collectChildren(element.props.children);
@@ -1633,7 +1667,7 @@ function walkRow(element, bodyValues, displayMode, headConfig, counters, styles,
   const semanticProps = extractSemanticProps(element.props, ["layout"]);
   const mapped = mapSemanticProps(semanticProps, ROW_DEFAULTS, "Row");
   const count = nextCounter(counters, "u_row");
-  const rowValues = ensureMeta2(mergeValues(ROW_DEFAULTS, mapped), "row", count - 1);
+  const rowValues = ensureMeta(mergeValues(ROW_DEFAULTS, mapped), "row", count - 1);
   const rowHead = exporters.heads["Row"];
   callHead(rowHead, rowValues, bodyValues, displayMode, headConfig, styles, scripts, tags);
   const children = collectChildren(element.props.children);
@@ -1656,7 +1690,7 @@ function extractHeadFromTree(element, options) {
   const counters = {};
   const semanticProps = extractSemanticProps(element.props);
   const mapped = mapSemanticProps(semanticProps, BODY_DEFAULTS, "Body");
-  const bodyValues = ensureMeta2(mergeValues(BODY_DEFAULTS, mapped), "body", 0);
+  const bodyValues = ensureMeta(mergeValues(BODY_DEFAULTS, mapped), "body", 0);
   const bodyHead = exporters.heads["Body"];
   callHead(bodyHead, bodyValues, bodyValues, displayMode, headConfig, styles, scripts, tags);
   const children = collectChildren(element.props.children);
@@ -1674,8 +1708,81 @@ function extractHeadFromTree(element, options) {
   };
 }
 
+// src/utils/document-layouts.ts
+function emailLayout(args) {
+  const { dir, titleTag, tagLines, styleTag, scriptTag, fontLinks, body } = args;
+  const head = [
+    titleTag,
+    tagLines,
+    styleTag,
+    scriptTag,
+    fontLinks && `<!--[if !mso]><!-->${fontLinks}<!--<![endif]-->`
+  ].filter(Boolean).join("\n  ");
+  return `<!DOCTYPE HTML PUBLIC "-//W3C//DTD XHTML 1.0 Transitional //EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html${dir} xmlns="http://www.w3.org/1999/xhtml" xmlns:v="urn:schemas-microsoft-com:vml" xmlns:o="urn:schemas-microsoft-com:office:office">
+<head>
+<!--[if gte mso 9]>
+<xml>
+  <o:OfficeDocumentSettings>
+    <o:AllowPNG/>
+    <o:PixelsPerInch>96</o:PixelsPerInch>
+  </o:OfficeDocumentSettings>
+</xml>
+<![endif]-->
+  <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <meta name="x-apple-disable-message-reformatting">
+  <!--[if !mso]><!--><meta http-equiv="X-UA-Compatible" content="IE=edge"><!--<![endif]-->
+  ${head}
+</head>
+${body}
+</html>
+`;
+}
+function documentLayout(args) {
+  const { dir, titleTag, tagLines, styleTag, scriptTag, fontLinks, body } = args;
+  const head = [titleTag, tagLines, styleTag, scriptTag, fontLinks].filter(Boolean).join("\n  ");
+  return `<!DOCTYPE HTML PUBLIC "-//W3C//DTD XHTML 1.0 Transitional //EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html${dir} xmlns="http://www.w3.org/1999/xhtml">
+<head>
+  <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+  ${head}
+</head>
+${body}
+</html>
+`;
+}
+function webLayout(args) {
+  const { dir, titleTag, tagLines, styleTag, scriptTag, fontLinks, body } = args;
+  const head = [titleTag, fontLinks, tagLines, styleTag, scriptTag].filter(Boolean).join("\n    ");
+  return `<!doctype html>
+<html${dir}>
+  <head>
+    <meta charset="utf-8">
+    <meta http-equiv="x-ua-compatible" content="ie=edge">
+    <meta name="description" content="">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    ${head}
+  </head>
+  <body>
+${body}
+  </body>
+</html>
+`;
+}
+
 // src/utils/render-to-html.tsx
-function renderToHtml(element, config) {
+var MODE_BY_WRAPPER = {
+  Email: "email",
+  Page: "web",
+  Document: "document"
+};
+function resolveDisplayMode(element, mergedConfig) {
+  const displayName = element.type?.displayName;
+  const wrapperMode = displayName ? MODE_BY_WRAPPER[displayName] : void 0;
+  return wrapperMode ?? element.props.mode ?? mergedConfig.mode ?? "web";
+}
+function renderBody(element, config) {
   const mergedConfig = { ...DEFAULT_CONFIG, ...config };
   try {
     const enriched = React__default.default.cloneElement(element, { config: mergedConfig });
@@ -1688,14 +1795,52 @@ Tip: Ensure your tree uses Body > Row > Column > Item structure.`
     );
   }
 }
+function stripOuterDiv(html) {
+  const match = html.match(/^\s*<div[^>]*>([\s\S]*)<\/div>\s*$/);
+  return match ? match[1] : html;
+}
+function escapeForHtml(text) {
+  return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+function renderToHtml(element, options) {
+  const { title, fonts = [], ...config } = options ?? {};
+  const mergedConfig = { ...DEFAULT_CONFIG, ...config };
+  const displayMode = resolveDisplayMode(element, mergedConfig);
+  const wrapperName = element.type?.displayName;
+  const isUnlayerWrapper = wrapperName === "Body" || (wrapperName ? wrapperName in MODE_BY_WRAPPER : false);
+  const rawBody = renderBody(element, config);
+  const body = isUnlayerWrapper ? stripOuterDiv(rawBody) : rawBody;
+  const { css, js, tags } = extractHeadFromTree(element, {
+    displayMode,
+    headConfig: mergedConfig.headConfig
+  });
+  const layoutArgs = {
+    dir: mergedConfig.textDirection ? ` dir="${escapeForHtml(String(mergedConfig.textDirection))}"` : "",
+    titleTag: title ? `<title>${escapeForHtml(title.trim())}</title>` : "",
+    styleTag: css ? `<style type="text/css">
+${css}
+</style>` : "",
+    scriptTag: js ? `<script type="application/javascript">
+${js}
+</script>` : "",
+    tagLines: tags.join("\n"),
+    fontLinks: fonts.filter((font) => font?.url).map(
+      (font) => `<link href="${escapeForHtml(font.url)}" rel="stylesheet" type="text/css">`
+    ).join(""),
+    body
+  };
+  if (displayMode === "email") return emailLayout(layoutArgs);
+  if (displayMode === "document") return documentLayout(layoutArgs);
+  return webLayout(layoutArgs);
+}
 function renderToPlainText(element, config) {
-  const html = renderToHtml(element, config);
+  const html = renderBody(element, config);
   return htmlToPlainText(html);
 }
 function renderToHtmlParts(element, config) {
-  const body = renderToHtml(element, config);
+  const body = renderBody(element, config);
   const mergedConfig = { ...DEFAULT_CONFIG, ...config };
-  const displayMode = element.props.mode ?? mergedConfig.mode ?? "web";
+  const displayMode = resolveDisplayMode(element, mergedConfig);
   const { css, js, tags } = extractHeadFromTree(element, {
     displayMode,
     headConfig: mergedConfig.headConfig
@@ -1818,10 +1963,11 @@ function processItem(element, counters, layout = {}) {
       `[Unlayer] renderToJson: <${name2}> is not a recognized Unlayer item component. Only components created with createItemComponent are supported.`
     );
   }
-  const { name, defaultValues, propMapper } = config;
-  const contentType = toContentType(name);
-  const count = nextCounter2(counters, `u_content_${contentType}`);
-  const id = makeId(`u_content_${contentType}`, count);
+  const { name, defaultValues, propMapper, slug } = config;
+  const contentType = config.contentType ?? toContentType(name);
+  const metaBase = `u_content_${config.metaName ?? contentType}`;
+  const count = nextCounter2(counters, metaBase);
+  const id = makeId(metaBase, count);
   const { children, ...restProps } = element.props;
   const mappedValues = propMapper({ children, ...restProps });
   const finalValues = mergeValues(defaultValues, mappedValues);
@@ -1834,7 +1980,7 @@ function processItem(element, counters, layout = {}) {
     ...finalValues,
     _meta: {
       htmlID: id,
-      htmlClassNames: `u_content_${contentType}`,
+      htmlClassNames: metaBase,
       ...finalValues._meta || {}
     },
     selectable: true,
@@ -1851,7 +1997,7 @@ function processItem(element, counters, layout = {}) {
     });
     values.src = pinImageSrc(itemSrc, availableWidth);
   }
-  return { type: contentType, values };
+  return slug ? { type: contentType, slug, values } : { type: contentType, values };
 }
 function processColumn(element, counters, layout = {}) {
   const count = nextCounter2(counters, "u_column");
@@ -1995,6 +2141,89 @@ function renderToJson(element) {
   };
 }
 
+// src/utils/register-tool.tsx
+function initialValuesFromOptions(options) {
+  const result = {};
+  for (const group of Object.values(options ?? {})) {
+    for (const [property, option] of Object.entries(group?.options ?? {})) {
+      if (!option || option.enabled === false) continue;
+      if (typeof option.defaultValue !== "undefined") {
+        result[property] = option.defaultValue;
+      }
+    }
+  }
+  return result;
+}
+function withSanitizer(exporter) {
+  return (values, ...args) => {
+    const html = String(exporter(values, ...args) ?? "");
+    const meta = args[args.length - 1];
+    const toSafeHtml = meta?.exporterConfig?.toSafeHtml;
+    return typeof toSafeHtml === "function" ? toSafeHtml(html) : html;
+  };
+}
+function withLinkNormalization(exporter, linkKeys) {
+  if (linkKeys.length === 0) return exporter;
+  return (values, ...args) => {
+    const out = { ...values };
+    for (const key of linkKeys) {
+      const normalized = normalizeLinkValue(out[key]);
+      if (normalized !== void 0) out[key] = normalized;
+    }
+    return exporter(out, ...args);
+  };
+}
+function linkWidgetKeys(options) {
+  const keys = [];
+  for (const group of Object.values(options ?? {})) {
+    for (const [key, option] of Object.entries(group?.options ?? {})) {
+      if (option && option.widget === "link") keys.push(key);
+    }
+  }
+  return keys;
+}
+function registerTool(tool) {
+  if (!tool?.name || typeof tool.name !== "string") {
+    throw new Error("[Unlayer] registerTool: `name` is required");
+  }
+  const exporters = tool.renderer?.exporters;
+  if (!exporters || !exporters.web && !exporters.email) {
+    throw new Error(
+      `[Unlayer] registerTool("${tool.name}"): \`renderer.exporters\` needs at least a \`web\` or \`email\` exporter`
+    );
+  }
+  const linkKeys = linkWidgetKeys(tool.options);
+  const sanitized = {};
+  for (const mode of ["web", "email", "document"]) {
+    const exporter = exporters[mode];
+    if (exporter) {
+      sanitized[mode] = withSanitizer(withLinkNormalization(exporter, linkKeys));
+    }
+  }
+  if (!sanitized.web && sanitized.email) sanitized.web = sanitized.email;
+  return createItemComponent({
+    name: tool.name,
+    displayName: tool.displayName ?? tool.name,
+    // Option-group widget defaults seed the values; tool-level `values`
+    // win — the editor's precedence.
+    defaultValues: {
+      ...initialValuesFromOptions(tool.options),
+      ...tool.values ?? {}
+    },
+    // Flat props are the tool's values; `values` is the escape hatch.
+    propMapper: ({ children: _children, values, ...rest }) => ({
+      ...values ?? {},
+      ...rest
+    }),
+    exporters: sanitized,
+    contentType: "custom",
+    slug: tool.name,
+    metaName: `custom_${tool.name}`,
+    head: tool.renderer.head
+  });
+}
+var registerElementsTool = registerTool;
+
 exports.Body = Body_default;
 exports.Button = Button_default;
 exports.Column = Column_default;
@@ -2015,6 +2244,8 @@ exports.Table = Table_default;
 exports.UnlayerProvider = UnlayerProvider;
 exports.Video = Video_default;
 exports.htmlToTextJson = htmlToTextJson;
+exports.registerElementsTool = registerElementsTool;
+exports.registerTool = registerTool;
 exports.renderRowToJson = renderRowToJson;
 exports.renderToHtml = renderToHtml;
 exports.renderToHtmlParts = renderToHtmlParts;