@escapenavigator/utils 1.10.133 → 1.10.135

package/dist/email-builder/from-html.js

@@ -0,0 +1,1017 @@
+"use strict";
+/**
+ * Конвертер legacy HTML (Quill output, использовавшийся в marketing-
+ * emails: cross-sale, retargeting, up-sale, early-booking, birthday,
+ * birthdayChild, custom-client-booking, scenario-emails) в формат
+ * `EmailContentJsonV2` нового редактора (Maily/TipTap).
+ *
+ * Что обрабатывает:
+ *  - Параграфы `<p>` + переносы `<br>`, схлопывает пустые абзацы
+ *  - Inline-форматирование `<strong>`/`<em>`/`<u>`/`<s>` (marks)
+ *  - Ссылки `<a href="…">` → link-mark
+ *  - Изображения `<img>` → image-нода
+ *  - Плоские плейсхолдеры `{varName}` → `variable`-ноды
+ *  - Maily-style плейсхолдеры `{{varName}}` и `{{varName|"fallback"}}`
+ *    — тоже превращаются в `variable`-ноды (с учётом fallback'а)
+ *  - Управляющие конструкции:
+ *      • `{{#if X}}…{{/if}}` → `section` нода с `showIfKey: 'X'`
+ *      • `{{#manageBooking}}текст{{/manageBooking}}` → `button` нода
+ *        c `isUrlVariable: true, url: 'bookingManagementLink'`
+ *  - Блочные HTML-плейсхолдеры (`orderDetailsHtml`) — выносятся в
+ *    отдельный `htmlCodeBlock` (их значение содержит `<div>`/`<table>`,
+ *    нельзя оставить внутри `<p>`). `servicesList` тут не упоминается:
+ *    функция up-sale-листа в письмах выпилена, см. `isServicesListVariableNode`
+ *  - Цвета/фоны/font-size — выкидываются (как `clearQuill stripColors`)
+ *
+ * Что НЕ обрабатывает (по дизайну):
+ *  - Списки `<ul>`/`<ol>` — в legacy шаблонах не встречаются (Quill в
+ *    нашей конфигурации их не выставлял). Если попадутся — fallback на
+ *    обычный текст; добавим если потребуется по факту.
+ *  - Таблицы — то же самое.
+ *  - Заголовки `<h1>`-`<h6>` — Quill их не использовал в шаблонах.
+ *
+ * Преобразование чистое и идемпотентное: повторный вызов на той же
+ * строке даёт тот же результат.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizePlaceholderId = exports.LEGACY_TO_NAMESPACED_ID_MAP = exports.KNOWN_PLACEHOLDERS = exports.isKnownPlaceholder = exports.isBlockHtmlPlaceholder = exports.BLOCK_HTML_PLACEHOLDERS = void 0;
+exports.migratePhotosToImage = migratePhotosToImage;
+exports.convertLegacyHtmlToEmailContent = convertLegacyHtmlToEmailContent;
+exports.findUnknownPlaceholders = findUnknownPlaceholders;
+const email_builder_1 = require("@escapenavigator/types/dist/email-builder");
+const node_html_parser_1 = require("node-html-parser");
+const placeholders_1 = require("./placeholders");
+Object.defineProperty(exports, "BLOCK_HTML_PLACEHOLDERS", { enumerable: true, get: function () { return placeholders_1.BLOCK_HTML_PLACEHOLDERS; } });
+Object.defineProperty(exports, "isBlockHtmlPlaceholder", { enumerable: true, get: function () { return placeholders_1.isBlockHtmlPlaceholder; } });
+Object.defineProperty(exports, "isKnownPlaceholder", { enumerable: true, get: function () { return placeholders_1.isKnownPlaceholder; } });
+Object.defineProperty(exports, "KNOWN_PLACEHOLDERS", { enumerable: true, get: function () { return placeholders_1.KNOWN_PLACEHOLDERS; } });
+Object.defineProperty(exports, "LEGACY_TO_NAMESPACED_ID_MAP", { enumerable: true, get: function () { return placeholders_1.LEGACY_TO_NAMESPACED_ID_MAP; } });
+Object.defineProperty(exports, "normalizePlaceholderId", { enumerable: true, get: function () { return placeholders_1.normalizePlaceholderId; } });
+const VARIABLE_NODE_DEFAULTS = {
+    fallback: null,
+    required: false,
+    hideDefaultValue: false,
+};
+/**
+ * Sentinel HTML-теги, которые мы вставляем на этапе preprocess'а
+ * (`{{#if}}`, `{var}` и т.д.). Используем `data-mly-*` атрибуты,
+ * потому что они валидные с точки зрения HTML-парсера и легко
+ * фильтруются на этапе walk.
+ *
+ * Префикс `mly-` намеренно не совпадает с реальными data-атрибутами
+ * Maily/TipTap (чтобы случайный collision был исключён).
+ */
+const MARKER_IF = 'data-mly-conv-if';
+const MARKER_BUTTON = 'data-mly-conv-button';
+const MARKER_VAR = 'data-mly-conv-var';
+const MARKER_VAR_FALLBACK = 'data-mly-conv-fallback';
+/**
+ * Pre-processing: переписываем text-level конструкции (`{{#if}}`,
+ * `{{#manageBooking}}`, `{var}`) в HTML-теги-маркеры. После этого
+ * стандартный HTML-парсер видит чистый HTML с обычными узлами,
+ * которые на этапе walk'а превращаются в TipTap-ноды нужного типа.
+ *
+ * Порядок применения важен:
+ *  1. `{{#if X}}…{{/if}}` — самый внешний контейнер, может содержать
+ *     внутри другие конструкции
+ *  2. `{{#manageBooking}}текст{{/manageBooking}}` — содержит текст
+ *     кнопки (тоже может быть с переменными)
+ *  3. `{{var|"fallback"}}` — двойные с fallback (maily-style)
+ *  4. `{{var}}` — двойные без fallback (maily-style)
+ *  5. `{var}` — одинарные (Quill-style)
+ *
+ * Шаги 3-5 не должны зацеплять служебные `{{#…}}`/`{{/…}}` — поэтому
+ * сначала перерабатываем (1) и (2).
+ */
+function preprocessHtml(html) {
+    let out = html;
+    // (1) {{#if X}}…{{/if}} → <div data-mly-conv-if="X">…</div>
+    //
+    // Reverse-passes до тех пор, пока есть совпадения — на случай
+    // вложенных IF (редко, но в кастомных шаблонах возможны).
+    const IF_RE = /\{\{#if\s+(\w[\w.]*)\s*\}\}([\s\S]*?)\{\{\/if\}\}/g;
+    let prev = '';
+    while (prev !== out) {
+        prev = out;
+        out = out.replace(IF_RE, (_m, key, inner) => `<div ${MARKER_IF}="${escapeAttr(key)}">${inner}</div>`);
+    }
+    // (2) {{#manageBooking}}текст{{/manageBooking}} → <span data-mly-conv-button="bookingManagementLink">текст</span>
+    out = out.replace(/\{\{#manageBooking\s*\}\}([\s\S]*?)\{\{\/manageBooking\}\}/g, (_m, inner) => `<span ${MARKER_BUTTON}="bookingManagementLink">${inner.trim()}</span>`);
+    // (3) {{var|"fallback"}} — двойные с fallback
+    out = out.replace(/\{\{\s*([\w.]+)\s*\|\s*"([^"]*)"\s*\}\}/g, (_m, name, fallback) => `<span ${MARKER_VAR}="${escapeAttr(name)}" ${MARKER_VAR_FALLBACK}="${escapeAttr(fallback)}"></span>`);
+    // (4) {{var}} — двойные без fallback. Исключаем оставшиеся
+    // служебные блоки `{{#…}}` и `{{/…}}` (теоретически их не должно
+    // быть после шагов 1-2, но защищаемся).
+    out = out.replace(/\{\{\s*([\w.]+)\s*\}\}/g, (_m, name) => `<span ${MARKER_VAR}="${escapeAttr(name)}"></span>`);
+    // (5) {var} — одинарные (Quill-style). Имя — только буквы/цифры,
+    // чтобы не цеплять случайные `{` в тексте писем (например цифровые
+    // диапазоны "{5,10}" в правилах брони, хотя в marketing их не бывает).
+    out = out.replace(/\{([\w]+)\}/g, (_m, name) => `<span ${MARKER_VAR}="${escapeAttr(name)}"></span>`);
+    return out;
+}
+function escapeAttr(s) {
+    return s.replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;');
+}
+/**
+ * Карта inline-тэгов → имя TipTap-mark'а. Только теги, которые реально
+ * используются в legacy шаблонах. Span/font/style/color — игнорируем
+ * (стили вычищены `clearQuill stripColors` на момент сохранения, а
+ * если что-то осталось — теряем сознательно, см. dock'а вверху файла).
+ */
+const INLINE_MARK_BY_TAG = {
+    strong: 'bold',
+    b: 'bold',
+    em: 'italic',
+    i: 'italic',
+    u: 'underline',
+    s: 'strike',
+    strike: 'strike',
+    del: 'strike',
+};
+/**
+ * Имя TipTap-блока для тэга. `null` — значит «прозрачный контейнер»,
+ * у которого мы только рекурсивно собираем содержимое.
+ */
+function blockTypeForTag(tag) {
+    switch (tag) {
+        case 'p':
+            return 'paragraph';
+        case 'div':
+            return 'paragraph';
+        default:
+            return null;
+    }
+}
+/**
+ * Уровень `<h1>`/`<h2>`/`<h3>` → `attrs.level` для TipTap heading-ноды.
+ * `<h4>`-`<h6>` намеренно ОТСУТСТВУЮТ: Maily-renderer знает только три
+ * первых уровня (с собственной типографикой: 36/30/24 px), остальные
+ * у него падают на дефолтный h1-стиль. Чтобы такого визуального
+ * сюрприза не случилось, h4-h6 уходят в transparent-fallback и
+ * рендерятся как обычный inline-текст.
+ */
+const HEADING_LEVELS = { h1: 1, h2: 2, h3: 3 };
+function walk(root, ctx) {
+    const out = [];
+    for (const child of root.childNodes) {
+        const nodes = walkBlock(child, ctx);
+        for (const n of nodes)
+            out.push(n);
+    }
+    return out;
+}
+function walkBlock(node, ctx) {
+    // Голый текст на верхнем уровне (без обёртки в <p>): оборачиваем
+    // в параграф, чтобы получить валидный TipTap-doc. Пустые/whitespace
+    // текстовые ноды на блочном уровне игнорируем — это переносы строк
+    // между тегами в исходнике, в редакторе они не нужны.
+    if (node.nodeType === node_html_parser_1.NodeType.TEXT_NODE) {
+        const text = node.rawText;
+        if (!text?.trim())
+            return [];
+        return [paragraphFromInline([{ type: 'text', text: decodeText(text) }])];
+    }
+    if (node.nodeType !== node_html_parser_1.NodeType.ELEMENT_NODE)
+        return [];
+    const el = node;
+    const tag = el.tagName?.toLowerCase() || '';
+    // (a) IF-блок — превращаем в section с showIfKey
+    if (el.getAttribute(MARKER_IF) != null) {
+        const key = el.getAttribute(MARKER_IF) || '';
+        const innerBlocks = walk(el, ctx);
+        return [
+            {
+                type: 'section',
+                attrs: {
+                    showIfKey: key,
+                    /*
+                     * Всё обнулено, чтобы section не давала визуального
+                     * «ящика» вокруг IF-контента — кроме `marginBottom`.
+                     *
+                     * `marginBottom: 20` — повторяем поведение обычного
+                     * `<p>` (Maily эмитит `<p style="margin-bottom: 20px">`).
+                     * Если оставить 0, в превью соседние IF-секции и
+                     * следующие за ними параграфы слипаются: внутренний
+                     * `<p style="margin-bottom: 20">` рендерится внутри
+                     * `<table data-type="section">` и его margin не
+                     * прорывается наружу через table-ячейку (margin-
+                     * collapse в email-клиентах работает нестабильно).
+                     * Внешний `marginBottom` на самой section даёт
+                     * предсказуемые 20px gap снаружи.
+                     */
+                    borderRadius: 0,
+                    backgroundColor: 'transparent',
+                    borderWidth: 0,
+                    borderColor: 'transparent',
+                    paddingTop: 0,
+                    paddingRight: 0,
+                    paddingBottom: 0,
+                    paddingLeft: 0,
+                    marginTop: 0,
+                    marginRight: 0,
+                    marginBottom: 20,
+                    marginLeft: 0,
+                    align: 'left',
+                },
+                content: innerBlocks,
+            },
+        ];
+    }
+    // (b) Button-блок (бывшая кнопка бронирования)
+    if (el.getAttribute(MARKER_BUTTON)) {
+        const urlVar = el.getAttribute(MARKER_BUTTON) || 'bookingManagementLink';
+        const text = el.text?.trim() || 'Управлять бронью';
+        /*
+         * Минимальный набор attrs — см. развёрнутый комментарий в
+         * `bookingLinkButtonNode()`. Maily-дефолты:
+         * `alignment:'left'`, `variant:'filled'`, `borderRadius:'smooth'`,
+         * `padding*:null` (берётся из `theme.button` → фирменный оранжевый).
+         * Зашивать сюда явные значения нельзя — bubble-menu toolbar
+         * (выровнять влево/центр/вправо) тогда не реагирует.
+         */
+        return [
+            {
+                type: 'button',
+                attrs: {
+                    text,
+                    isTextVariable: false,
+                    url: urlVar,
+                    isUrlVariable: true,
+                },
+            },
+        ];
+    }
+    // (c) Изображение
+    if (tag === 'img') {
+        const src = el.getAttribute('src') || '';
+        if (!src)
+            return [];
+        return [
+            {
+                type: 'image',
+                attrs: {
+                    src,
+                    alt: el.getAttribute('alt') || '',
+                    title: el.getAttribute('title') || '',
+                    width: 'auto',
+                    height: 'auto',
+                    alignment: 'left',
+                    borderRadius: 0,
+                    externalLink: '',
+                },
+            },
+        ];
+    }
+    // (d) Heading — `<h1>`/`<h2>`/`<h3>`. Maily-renderer знает уровни
+    // 1..3 (см. `ne` в minified исходнике: h1=36px/40lh/800w,
+    // h2=30px/36lh/700w, h3=24px/38lh/600w); `<h4>`-`<h6>` рендерятся
+    // по дефолту как h1 (level<1 || >3 → 1) — мы их не маппим, пусть
+    // падают в общий transparent-fallback (е).
+    //
+    // Зачем: CDN-шаблоны хотят давать структурную иерархию через
+    // <h3>Лейбл</h3><p>значение</p> вместо <p><strong>Лейбл:</strong></p>
+    // <p>значение</p> — второй вариант визуально не отличается от
+    // соседних блоков (одинаковый margin-bottom: 20px у всех <p>).
+    const headingLevel = HEADING_LEVELS[tag];
+    if (headingLevel) {
+        const inline = collectInline(el, [], ctx);
+        if (inline.length === 0)
+            return [];
+        const hasMeaningful = inline.some((n) => n.type !== 'hardBreak' && (n.type !== 'text' || (n.text && n.text.trim() !== '')));
+        if (!hasMeaningful)
+            return [];
+        return [
+            {
+                type: 'heading',
+                /*
+                 * `textAlign: 'left'` — дефолт у Maily, выставляем явно,
+                 * чтобы heading-нода прошла валидацию TipTap-schema
+                 * (heading-extension объявляет `textAlign` обязательным
+                 * атрибутом, без него нода может выпасть на этапе
+                 * `parse → render`-цикла в редакторе).
+                 */
+                attrs: { level: headingLevel, textAlign: 'left' },
+                content: inline,
+            },
+        ];
+    }
+    // (e) Блочный контейнер — собираем inline content рекурсивно
+    const blockType = blockTypeForTag(tag);
+    if (blockType) {
+        const inline = collectInline(el, [], ctx);
+        if (inline.length === 0)
+            return [];
+        // Если параграф состоит только из пустых текстов (вроде <p><br></p>) — выкидываем
+        const hasMeaningfulContent = inline.some((n) => n.type !== 'hardBreak' && (n.type !== 'text' || (n.text && n.text.trim() !== '')));
+        if (!hasMeaningfulContent)
+            return [];
+        return [paragraphFromInline(inline)];
+    }
+    // (e) Неизвестный тэг на блочном уровне — раскрываем содержимое (transparent)
+    return walk(el, ctx);
+}
+/**
+ * Собирает inline-content (содержимое одного параграфа). Возвращает
+ * массив `text`/`variable`/`hardBreak`/`image` нод. Marks накапливаются
+ * через стек.
+ */
+function collectInline(el, marks, ctx) {
+    const out = [];
+    for (const child of el.childNodes) {
+        if (child.nodeType === node_html_parser_1.NodeType.TEXT_NODE) {
+            const text = child.rawText;
+            if (!text)
+                continue;
+            const decoded = decodeText(text);
+            if (!decoded)
+                continue;
+            out.push(textNode(decoded, marks));
+            continue;
+        }
+        if (child.nodeType !== node_html_parser_1.NodeType.ELEMENT_NODE)
+            continue;
+        const c = child;
+        const tag = c.tagName?.toLowerCase() || '';
+        // Variable-маркер
+        if (c.getAttribute(MARKER_VAR)) {
+            const id = c.getAttribute(MARKER_VAR) || '';
+            const fallback = c.getAttribute(MARKER_VAR_FALLBACK);
+            /*
+             * `inlineValues` — литеральная подстановка ДО любых других
+             * проверок. Используется для legacy-плейсхолдеров без
+             * резолвера (`profileTitle`): зашиваем буквальное название
+             * компании в текст, чтобы пользователь не получил пустую
+             * variable-ноду на месте уже не существующей переменной.
+             *
+             * Лукап по исходному (pre-mapping) id, потому что
+             * inline-value семантика — про legacy слово, а не про
+             * новый namespaced id (которого может вовсе не быть в
+             * `idMap`).
+             */
+            if (id in ctx.inlineValues) {
+                const literal = ctx.inlineValues[id];
+                if (literal) {
+                    out.push(textNode(literal, marks));
+                }
+                continue;
+            }
+            /*
+             * Особый случай: `{photos}` в legacy шаблонах — это HTML
+             * галерея <img>'ов всех загруженных фотографий команды.
+             * В новом редакторе мы заменяем это на одну `image`-ноду
+             * с переменной `src = photos` (которая на send-time
+             * резолвится в URL ПЕРВОЙ фотки игры). Так пользователь
+             * видит ОДНУ нормально стилизованную картинку, которую
+             * можно ресайзить/выравнивать через UI Maily, а не
+             * raw-HTML-блок, который нельзя редактировать.
+             *
+             * Если в order'е нет ни одной фотки — резолвер `photos`
+             * вернёт `''`, и v2-renderer корректно отрисует пустую
+             * `src=""` — почтовики такие image просто скрывают.
+             * См. также `order.resolver.ts → photos`.
+             */
+            if (id === 'photos') {
+                out.push(photoFirstImageNode());
+                continue;
+            }
+            /*
+             * `servicesList` (legacy up-sale list) — функция выпилена
+             * из email-системы целиком. Если приехало в HTML/JSON из
+             * старых данных, просто игнорим chip: `continue` без push'а
+             * пропускает variable-ноду, текст вокруг остаётся как был.
+             * См. также `LEGACY_BLOCK_VARIABLE_REPLACERS` (там тот же
+             * id мапится в пустой массив для уже сохранённых doc'ов).
+             */
+            if (id === 'servicesList')
+                continue;
+            /*
+             * `bookingManagementLink` — единственный смысловой вариант
+             * этой переменной: красивая центрированная кнопка «Manage
+             * booking». В legacy его иногда вставляли inline (`{bookingManagementLink}`
+             * прямо в текст ссылки), что давало `<a href="…токен…">…</a>`.
+             * Промоутим в полноценную button-ноду — `promoteBlockHtmlVariables`
+             * сам вынесет её наверх параграфа.
+             *
+             * Не трогаем варианты внутри `{{#manageBooking}}…{{/}}` —
+             * они уже стали `MARKER_BUTTON` на этапе preprocess'а и
+             * сюда не доходят (другая ветка с `MARKER_BUTTON`).
+             */
+            if (id === 'bookingManagementLink') {
+                out.push(bookingLinkButtonNode());
+                continue;
+            }
+            out.push(variableNode(id, fallback ?? null, ctx.labels));
+            continue;
+        }
+        // Button-маркер (manageBooking). Maily-button — block-level
+        // нода, но в исходнике он стоит внутри `<p>`, так что ловим
+        // его inline и потом промотируем наверх в `promoteBlockHtmlVariables`.
+        if (c.getAttribute(MARKER_BUTTON)) {
+            const urlVar = c.getAttribute(MARKER_BUTTON) || 'bookingManagementLink';
+            const text = c.text?.trim() || 'Управлять бронью';
+            // Минимальный набор attrs — см. `bookingLinkButtonNode()`.
+            out.push({
+                type: 'button',
+                attrs: {
+                    text,
+                    isTextVariable: false,
+                    url: urlVar,
+                    isUrlVariable: true,
+                },
+            });
+            continue;
+        }
+        // <br>
+        if (tag === 'br') {
+            out.push({ type: 'hardBreak' });
+            continue;
+        }
+        // <img> внутри inline — оставляем как inline (paragraph-level image
+        // тоже валиден, см. maily-render `image()`).
+        if (tag === 'img') {
+            const src = c.getAttribute('src') || '';
+            if (src) {
+                out.push({
+                    type: 'image',
+                    attrs: {
+                        src,
+                        alt: c.getAttribute('alt') || '',
+                        title: c.getAttribute('title') || '',
+                        width: 'auto',
+                        height: 'auto',
+                        alignment: 'left',
+                        borderRadius: 0,
+                        externalLink: '',
+                    },
+                });
+            }
+            continue;
+        }
+        // Inline-mark теги
+        const markName = INLINE_MARK_BY_TAG[tag];
+        if (markName) {
+            const next = [...marks, { type: markName }];
+            for (const n of collectInline(c, next, ctx))
+                out.push(n);
+            continue;
+        }
+        // <a> — link-mark
+        if (tag === 'a') {
+            const href = c.getAttribute('href') || '';
+            const next = [
+                ...marks,
+                {
+                    type: 'link',
+                    attrs: {
+                        href,
+                        target: c.getAttribute('target') || '_blank',
+                        rel: c.getAttribute('rel') || 'noopener noreferrer nofollow',
+                        class: null,
+                    },
+                },
+            ];
+            for (const n of collectInline(c, next, ctx))
+                out.push(n);
+            continue;
+        }
+        // Неизвестный inline-тэг → раскрываем содержимое
+        for (const n of collectInline(c, marks, ctx))
+            out.push(n);
+    }
+    return out;
+}
+function textNode(text, marks) {
+    if (marks.length === 0)
+        return { type: 'text', text };
+    return { type: 'text', text, marks: [...marks] };
+}
+function variableNode(id, fallback, labels) {
+    return {
+        type: 'variable',
+        attrs: {
+            id,
+            label: labels[id] || id,
+            fallback,
+            required: VARIABLE_NODE_DEFAULTS.required,
+            hideDefaultValue: VARIABLE_NODE_DEFAULTS.hideDefaultValue,
+        },
+    };
+}
+/**
+ * Image-нода с переменным `src = photos`. Заменяет legacy
+ * `{photos}`-плейсхолдер (HTML-галерею) на один редактируемый image,
+ * совместимый с Maily UI (resize/align). См. подробное объяснение
+ * выше, в ветке `id === 'photos'`.
+ *
+ * `isSrcVariable: true` — режим Maily, при котором `attrs.src` лечится
+ * как имя переменной, а не URL. На рендере (`@maily-to/render`) этот
+ * флаг включает подстановку через variable-resolvers.
+ *
+ * NB: variable id — flat `photos` (без namespace). Исторический
+ * legacy-token, в шаблонах клиентов годами лежит `{photos}`;
+ * переименование в `order.photo*` стоит миграции ради косметики.
+ * Семантика — «URL ПЕРВОЙ фотки игры» (см. `OrderVariableResolver`).
+ */
+function photoFirstImageNode() {
+    return {
+        type: 'image',
+        attrs: {
+            // Variable id — flat `photos` (без namespace), исторический
+            // legacy-token. Резолвится в URL ПЕРВОЙ фотки игры
+            // (`OrderVariableResolver`).
+            src: 'photos',
+            isSrcVariable: true,
+            alt: '',
+            title: '',
+            /*
+             * Жёсткий размер 200×200. Maily NodeView в редакторе показывает
+             * placeholder-картинку (broken-img icon) до подгрузки реального
+             * URL, и без явных width/height лейаут письма прыгает каждый
+             * раз, когда юзер открывает превью. 200×200 — тот же размер,
+             * который мы передаём в `@`-меню (`editor-inner.tsx`), и
+             * совпадает с размером миниатюры в большинстве почтовых
+             * клиентов.
+             */
+            width: 200,
+            height: 200,
+            alignment: 'center',
+            borderRadius: 8,
+            externalLink: '',
+        },
+    };
+}
+/*
+ * Все известные id'ы, которыми «фото первого заказа» когда-либо обоз-
+ * началось в TipTap-doc. Используется нормализатором ниже, чтобы при
+ * следующей операции с письмом (backfill, hydrate, refill) все варианты
+ * сходились к одному `image`-узлу с `src = photos`.
+ *
+ *  - `photos` — текущий id (flat, исторический legacy-token);
+ *  - `order.photoFirst` — временный namespaced id, существовал на
+ *    переходный период; ещё мог остаться в чьих-то локально-сохранённых
+ *    contentJson, нормализатор подменит его обратно на `photos`.
+ */
+const PHOTOS_VARIABLE_IDS = new Set(['photos', 'order.photoFirst']);
+const isPhotosVariableNode = (node) => node?.type === 'variable' &&
+    typeof node.attrs?.id === 'string' &&
+    PHOTOS_VARIABLE_IDS.has(node.attrs.id);
+/*
+ * `servicesList` — legacy up-sale list, функция выпилена из email-системы.
+ * Любой variable-chip с этим id (или wrapper-параграф вокруг него)
+ * должен молча выбрасываться при нормализации, чтобы старые
+ * сохранённые doc'и не показывали мёртвый плейсхолдер.
+ */
+const isServicesListVariableNode = (node) => node?.type === 'variable' && node?.attrs?.id === 'servicesList';
+/**
+ * Идемпотентный нормализатор устаревших variable-чипов, у которых
+ * есть выделенное block-представление в Maily:
+ *   - `{photos}` / `{order.photoFirst}` → одна `image`-нода
+ *     (`src = photos`, 200×200);
+ *   - `{servicesList}` → удаляется (функция up-sale-листа в письмах
+ *     выпилена; см. `isServicesListVariableNode` и factory `() => []`
+ *     в `LEGACY_BLOCK_VARIABLE_REPLACERS`).
+ *
+ * Используется во всех трёх каналах:
+ *   - финальный шаг `convertLegacyHtmlToEmailContent` — гарантия для
+ *     свежих конверсий из legacy HTML;
+ *   - `hydrateEmailLocales` на фронте — лечит уже-сохранённые
+ *     contentJson при открытии формы;
+ *   - `renderEmailV2Local` на бэке — последний рубеж перед send,
+ *     спасает scheduled / queue-задачи, идущие в обход UI.
+ *
+ * Имя сохранено по историческим причинам (когда-то функция занималась
+ * только photos). Сейчас правильнее читать его как «migrate legacy
+ * block variables» — добавление новой замены сводится к одной строке
+ * в `LEGACY_BLOCK_VARIABLE_REPLACERS`.
+ *
+ * Правила обхода:
+ *   1. Top-level `variable[id ∈ matchLegacyBlockVariable]` или
+ *      `htmlCodeBlock` с такой variable внутри (артефакт `promoteBlockHtmlVariables`)
+ *      — заменяются полностью на соответствующий block-узел.
+ *   2. `paragraph` с единственным непустым ребёнком-legacy-variable —
+ *      целиком заменяется на block-узел (image/repeat — block-level,
+ *      жить inline в параграфе не могут).
+ *   3. Variable посреди смешанного параграфа — оставляем как есть:
+ *      это пользовательский кейс, безопаснее не ломать layout.
+ *   4. Внутрь `section`/`repeat`/`for`/`show` и т.п. block-контейнеров
+ *      ходим рекурсивно.
+ *
+ * Возвращает НОВЫЙ объект, не мутирует входной. Идемпотентна:
+ *   повторный вызов — no-op (после первой замены variable-чипов
+ *   с такими id уже не остаётся).
+ */
+function migratePhotosToImage(content) {
+    const doc = content.doc;
+    const nextContent = migratePhotosInNodes(doc.content || []);
+    return {
+        ...content,
+        doc: {
+            ...doc,
+            content: nextContent,
+        },
+    };
+}
+/*
+ * Карта «найден variable с таким id → вставь ВОТ эти ноды». Используется
+ * `migratePhotosInNodes` для свёртки разнородных legacy-вариантов
+ * (`photos`) к единой Maily-репрезентации либо для УДАЛЕНИЯ выпиленных
+ * плейсхолдеров (`servicesList` — factory возвращает `[]`, узел просто
+ * пропадает из doc'а).
+ *
+ * Factory может вернуть как одну ноду, так и массив (включая пустой):
+ *   - 1 нода — обычная замена (photos → image).
+ *   - массив — multi-node-разворачивание (исторический use-case);
+ *     сегодня неиспользуем, но API сохраняется на будущее.
+ *   - пустой массив — узел удаляется без замены (servicesList).
+ *
+ * Каждый узел-замена возвращается ФАБРИКОЙ, а не одной shared-инстансой,
+ * потому что TipTap-доку нельзя shar'ить идентичные объекты между
+ * позициями (теряется reactivity в редакторе).
+ */
+const LEGACY_BLOCK_VARIABLE_REPLACERS = [
+    { match: isPhotosVariableNode, factory: photoFirstImageNode },
+    {
+        /*
+         * `servicesList` — функция up-sale-листа в письмах выпилена.
+         * Сохранённые doc'и могут всё ещё содержать variable-chip с
+         * этим id (или его обёртку в `<p>` / `htmlCodeBlock`) — заменяем
+         * на пустой массив, и `migratePhotosInNodes` просто удалит
+         * соответствующий узел из doc'а. См. `walkBlock → id ===
+         * 'servicesList'` для свежих HTML-конверсий.
+         */
+        match: isServicesListVariableNode,
+        factory: () => [],
+    },
+];
+const matchLegacyBlockVariable = (node) => {
+    for (const r of LEGACY_BLOCK_VARIABLE_REPLACERS) {
+        if (r.match(node))
+            return r.factory;
+    }
+    return null;
+};
+/**
+ * Развёртывает результат factory'а в плоский список. Factory может
+ * вернуть одну ноду или массив; на стороне walker'а удобнее иметь
+ * единый `TipTapNode[]`, чтобы просто `out.push(...factoryNodes)`.
+ */
+function expandReplacement(factory) {
+    const result = factory();
+    return Array.isArray(result) ? result : [result];
+}
+function migratePhotosInNodes(nodes) {
+    const out = [];
+    for (const node of nodes) {
+        /*
+         * (0) `section[showIfKey='servicesList']` — IF-обёртка вокруг
+         * списка доп. услуг. Раньше шаблоны типично выглядели как
+         * `{{#if servicesList}} <strong>Сделайте игру ярче…</strong>
+         * {servicesList} {{/if}}`. После выпиливания фичи сам chip
+         * выкидывается factory `() => []`, но IF-обёртка с
+         * заголовком оставалась бы пустой section'ой (на render-time
+         * `shouldShow('servicesList')` = false, в редакторе section
+         * видна как пустой блок с заголовком «Сделайте игру ярче…»).
+         *
+         * Удаляем секцию целиком: содержимое (заголовок-приглашение,
+         * legacy текст «Доп. услуги:» и т.п.) тоже больше не нужно,
+         * потому что без списка услуг оно теряет смысл. Это
+         * симметрично factory `() => []` для самой переменной.
+         */
+        if (node.type === 'section' &&
+            node.attrs?.showIfKey === 'servicesList') {
+            continue;
+        }
+        // (1) Прямая variable-нода на верхнем уровне.
+        const direct = matchLegacyBlockVariable(node);
+        if (direct) {
+            out.push(...expandReplacement(direct));
+            continue;
+        }
+        // (1b) `htmlCodeBlock` с единственной legacy variable
+        // (артефакт старого `promoteBlockHtmlVariables` — раньше он
+        // оборачивал {photos} в htmlCodeBlock).
+        if (node.type === 'htmlCodeBlock') {
+            const inner = (node.content || []);
+            if (inner.length === 1) {
+                const wrapped = matchLegacyBlockVariable(inner[0]);
+                if (wrapped) {
+                    out.push(...expandReplacement(wrapped));
+                    continue;
+                }
+            }
+        }
+        // (2) Параграф, содержащий ТОЛЬКО legacy variable.
+        if (node.type === 'paragraph') {
+            const children = (node.content || []);
+            const meaningful = children.filter((c) => !(c.type === 'text' && !(c.text || '').trim()));
+            if (meaningful.length === 1) {
+                const single = matchLegacyBlockVariable(meaningful[0]);
+                if (single) {
+                    out.push(...expandReplacement(single));
+                    continue;
+                }
+            }
+        }
+        // (4) Рекурсия по детям для block-контейнеров.
+        const innerNodes = node.content;
+        if (innerNodes && innerNodes.length > 0) {
+            out.push({
+                ...node,
+                content: migratePhotosInNodes(innerNodes),
+            });
+            continue;
+        }
+        out.push(node);
+    }
+    return out;
+}
+/**
+ * Кнопка «Manage booking» — единственная допустимая визуализация
+ * `bookingManagementLink`.
+ *
+ * Сетим МИНИМАЛЬНЫЙ набор attrs (text + url + флаги переменных).
+ * Остальное (`alignment` / `variant` / `borderRadius` / `padding*` /
+ * `buttonColor` / `textColor`) намеренно не зашиваем — Maily-button-
+ * extension берёт дефолты `left` / `filled` / `smooth` / `null`-padding
+ * (`null` → padding из `theme.button`, т.е. фирменный оранжевый), и
+ * bubble-menu toolbar в редакторе тогда корректно `updateAttributes`-ит
+ * эти поля. Если зашить значения сюда (как было раньше:
+ * `alignment:'center'`, `paddingTop:10`), toolbar-кнопки «выровнять
+ * влево/по центру/вправо» могут не реагировать — ProseMirror
+ * `updateAttributes` мерджит, но визуально предыдущие зашитые цифры
+ * перекрывают пользовательский выбор. См. attr-список button-extension
+ * в `@maily-to/core/dist/index.cjs` (`addAttributes` для node `button`:
+ * `text`, `isTextVariable`, `url`, `isUrlVariable`, `alignment`,
+ * `variant`, `borderRadius`, `showIfKey`, `buttonColor`, `textColor`,
+ * `padding[Top|Right|Bottom|Left]`).
+ *
+ * `isUrlVariable: true` → resolver подставит реальный signed-URL в
+ * момент отправки. Сам текст «Manage booking» — литерал (не переменная),
+ * пользователь может перевести его в редакторе.
+ */
+function bookingLinkButtonNode() {
+    return {
+        type: 'button',
+        attrs: {
+            text: 'Manage booking',
+            isTextVariable: false,
+            url: 'bookingManagementLink',
+            isUrlVariable: true,
+        },
+    };
+}
+function paragraphFromInline(content) {
+    return {
+        type: 'paragraph',
+        attrs: { textAlign: 'left' },
+        content,
+    };
+}
+/**
+ * Декодирование HTML-сущностей в текстовых нодах. node-html-parser
+ * не делает этого автоматически — отдаёт rawText с буквальными
+ * `&nbsp;` и т.п. Заодно нормализуем no-break space в обычный, чтобы
+ * редактор не показывал «странные» пробелы.
+ */
+function decodeText(text) {
+    return text
+        .replace(/&nbsp;/g, ' ')
+        .replace(/&#160;/g, ' ')
+        .replace(/&#xa0;/gi, ' ')
+        .replace(/\u00A0/g, ' ')
+        .replace(/&amp;/g, '&')
+        .replace(/&lt;/g, '<')
+        .replace(/&gt;/g, '>')
+        .replace(/&quot;/g, '"')
+        .replace(/&#39;/g, "'")
+        .replace(/&apos;/g, "'");
+}
+/**
+ * Пост-обработка: блочные HTML-плейсхолдеры (`orderDetailsHtml`,
+ * `photos`) внутри параграфов вырываются наверх в отдельные
+ * `htmlCodeBlock`-ноды. Параграф разрывается на «до» и «после»;
+ * пустые сегменты выбрасываются.
+ *
+ * Зачем: их значение — HTML с `<div>`/`<table>`. Если оставить как
+ * inline-variable в `<p>`, итоговый HTML письма получит `<div>`
+ * внутри `<p>`, что почтовые клиенты рендерят непредсказуемо.
+ */
+function promoteBlockHtmlVariables(content) {
+    const out = [];
+    for (const node of content) {
+        if (node.type === 'paragraph' && node.content) {
+            promotedFromParagraph(node, out);
+            continue;
+        }
+        if (node.type === 'section' && node.content) {
+            // Внутри `<section>` рекурсивно повторяем
+            out.push({ ...node, content: promoteBlockHtmlVariables(node.content) });
+            continue;
+        }
+        out.push(node);
+    }
+    return out;
+}
+function promotedFromParagraph(paragraph, out) {
+    const inline = paragraph.content || [];
+    let buffer = [];
+    const flushBuffer = () => {
+        if (buffer.length === 0)
+            return;
+        const hasMeaningfulContent = buffer.some((n) => n.type !== 'hardBreak' && (n.type !== 'text' || (n.text && n.text.trim() !== '')));
+        if (hasMeaningfulContent) {
+            out.push({ ...paragraph, content: buffer });
+        }
+        buffer = [];
+    };
+    for (const child of inline) {
+        if (child.type === 'variable' &&
+            child.attrs?.id &&
+            typeof child.attrs.id === 'string' &&
+            (0, placeholders_1.isBlockHtmlPlaceholder)(child.attrs.id)) {
+            flushBuffer();
+            out.push({
+                type: 'htmlCodeBlock',
+                attrs: { language: 'html' },
+                content: [child],
+            });
+            continue;
+        }
+        if (child.type === 'button') {
+            // Button — block-level в Maily. Внутри `collectInline` мы
+            // создаём его inline, чтобы поймать `{{#manageBooking}}…{{/}}`
+            // в любом месте параграфа; здесь поднимаем наверх,
+            // разрывая родительский параграф.
+            flushBuffer();
+            out.push(child);
+            continue;
+        }
+        if (child.type === 'image' &&
+            child.attrs?.isSrcVariable === true) {
+            /*
+             * Photos-image (Maily-style image с `src` = переменной).
+             * Промоутим наверх — чтобы Maily `alignment: 'center'`
+             * сработал без обёртки в параграф. Inline `<img>` из
+             * legacy `<img src="url">` НЕ трогаем — у них
+             * `isSrcVariable === false`, они валидно живут внутри `<p>`.
+             */
+            flushBuffer();
+            out.push(child);
+            continue;
+        }
+        if (child.type === 'repeat') {
+            /*
+             * `repeat`-нода (iterable list) — block-level: Maily
+             * рендерит её через `Row`/`Section`-компоненты, размещение
+             * inline внутри `<p>` поломает разметку. Поднимаем наверх,
+             * рвём родительский параграф на «до» и «после» — тот же
+             * принцип, что и для button/image. Сейчас наш converter
+             * `repeat`-ноды не порождает (single live use-case,
+             * `servicesList`, выпилен), но branch держится как страховка
+             * для legacy doc'ов, в которых нода уже могла оказаться.
+             */
+            flushBuffer();
+            out.push(child);
+            continue;
+        }
+        buffer.push(child);
+    }
+    flushBuffer();
+}
+/**
+ * Главная точка входа конвертера. Принимает legacy HTML (Quill-style
+ * с плоскими плейсхолдерами и handlebars-блоками) и возвращает готовый
+ * `EmailContentJsonV2`, готовый к сохранению в БД и открытию в
+ * EmailBuilder.
+ *
+ * Идемпотентен: пустой/null/whitespace вход даёт минимальный валидный
+ * `doc` (с логотипом если указан, иначе пустой массив content).
+ *
+ * Шаги обработки (в порядке выполнения):
+ *  1. `preprocessHtml` — text-level замены (`{{#if}}`, `{var}`, ...)
+ *  2. parse через node-html-parser
+ *  3. `walk` — построение TipTap-нод верхнего уровня
+ *  4. `promoteBlockHtmlVariables` — вынос block-payload плейсхолдеров
+ *  5. `normalizeVariableIds` — flat → namespaced id (если включено)
+ *  6. оборачивание в `EmailContentJsonV2` с логотипом и темой
+ */
+function convertLegacyHtmlToEmailContent(html, options = {}) {
+    const { logo, labels = {}, idMap = placeholders_1.LEGACY_TO_NAMESPACED_ID_MAP, inlineValues = {} } = options;
+    const content = [];
+    const logoNode = (0, email_builder_1.createLogoNode)(logo);
+    if (logoNode)
+        content.push(logoNode);
+    const cleaned = (html || '').trim();
+    if (cleaned) {
+        const preprocessed = preprocessHtml(cleaned);
+        const root = (0, node_html_parser_1.parse)(preprocessed, { lowerCaseTagName: true });
+        const blocks = walk(root, { labels, inlineValues });
+        const promoted = promoteBlockHtmlVariables(blocks);
+        const normalized = idMap ? normalizeVariableIds(promoted, idMap, labels) : promoted;
+        for (const b of normalized)
+            content.push(b);
+    }
+    const result = {
+        version: email_builder_1.EMAIL_CONTENT_VERSION_V2,
+        doc: { type: 'doc', content: content },
+        theme: email_builder_1.DEFAULT_EMAIL_THEME,
+    };
+    /*
+     * Финальный pass-проход через `migratePhotosToImage`: гарантирует,
+     * что даже если в legacy-HTML встречалось `{{order.photoFirst}}`
+     * как chip-variable (а не `{photos}`-block), оно тоже выльется
+     * в редактируемую `image`-ноду. Walk-логика выше обрабатывает
+     * только `id === 'photos'` напрямую — этот шаг закрывает все
+     * остальные углы.
+     */
+    return migratePhotosToImage(result);
+}
+/**
+ * Рекурсивный пост-проход: для каждой `variable`-ноды переписывает
+ * `attrs.id` через `idMap` (если в карте есть запись), и заодно
+ * освежает `attrs.label`, если для нового id есть конкретный лейбл в
+ * `labels`. Дерево не клонируется глубоко: меняем только то, что
+ * реально нужно (`attrs`); экономит выделения на больших шаблонах.
+ */
+function normalizeVariableIds(nodes, idMap, labels) {
+    return nodes.map((node) => {
+        if (node.type === 'variable' && node.attrs?.id && typeof node.attrs.id === 'string') {
+            const mapped = idMap[node.attrs.id];
+            if (mapped && mapped !== node.attrs.id) {
+                return {
+                    ...node,
+                    attrs: {
+                        ...node.attrs,
+                        id: mapped,
+                        label: labels[mapped] || mapped,
+                    },
+                };
+            }
+            return node;
+        }
+        /*
+         * `section.showIfKey` — id переменной, по которой v2-render
+         * проверяет truthy перед рендером содержимого секции. Если не
+         * отнормализовать, секции с legacy ключами вроде
+         * `howToFindLocation` всегда будут схлопываться (резолверы
+         * возвращают `location.howToFind`).
+         */
+        if (node.type === 'section' &&
+            node.attrs?.showIfKey &&
+            typeof node.attrs.showIfKey === 'string') {
+            const mapped = idMap[node.attrs.showIfKey];
+            const nextAttrs = mapped && mapped !== node.attrs.showIfKey
+                ? { ...node.attrs, showIfKey: mapped }
+                : node.attrs;
+            return {
+                ...node,
+                attrs: nextAttrs,
+                content: node.content
+                    ? normalizeVariableIds(node.content, idMap, labels)
+                    : node.content,
+            };
+        }
+        if (node.content) {
+            return { ...node, content: normalizeVariableIds(node.content, idMap, labels) };
+        }
+        return node;
+    });
+}
+/**
+ * Подсчёт неизвестных плейсхолдеров в legacy HTML. Возвращает уникальные
+ * имена `{X}` и `{{X}}`, которые **не входят** в `KNOWN_PLACEHOLDERS`.
+ * Используется до миграции, чтобы найти ручные/опечатанные токены в
+ * шаблонах клиентов и решить, что с ними делать (исправить → конвертим,
+ * проигнорить → оставляем как литеральный текст).
+ */
+function findUnknownPlaceholders(html) {
+    if (!html)
+        return [];
+    const found = new Set();
+    const SINGLE = /\{([\w]+)\}/g;
+    const DOUBLE = /\{\{\s*([\w.]+)\s*(?:\|\s*"[^"]*")?\s*\}\}/g;
+    const STRUCT = new Set([
+        'if',
+        '/if',
+        '#if',
+        'manageBooking',
+        '/manageBooking',
+        '#manageBooking',
+    ]);
+    for (const m of html.matchAll(SINGLE)) {
+        if (!(0, placeholders_1.isKnownPlaceholder)(m[1]))
+            found.add(m[1]);
+    }
+    for (const m of html.matchAll(DOUBLE)) {
+        const name = m[1];
+        if (STRUCT.has(name))
+            continue;
+        // Двойные `{{var}}` для известных плейсхолдеров (профильный
+        // title, и т.п.) — ok. Игнорируем `manageBooking` (служебный).
+        if (name === 'manageBooking')
+            continue;
+        if (!(0, placeholders_1.isKnownPlaceholder)(name) && !name.includes('.'))
+            found.add(name);
+    }
+    return [...found].sort();
+}