@designcrowd/library.brand-page 6.2.11-builder-v2-1 → 6.2.12

package/lib/src/brand-page/utils/migration/migration-22.js

@@ -0,0 +1,909 @@
+import { BRAND_PAGE_TYPES, } from '../../models';
+import { TEXT_STYLE_TYPES, isCanonicalTextStyleType, isLegacyTextStyleType, } from '../../models/styles.model';
+import { CONTENT_TEXT_STYLE_PROPERTY_KEYS, FONT_FAMILY_CONFIGS, DEFAULT_FONT_FAMILY_KEY, FONT_SIZE_BODY, LINE_HEIGHT_BODY, ALIGN_LEFT_ALIGNED, ALIGN_RIGHT_ALIGNED, MAX_IMAGES_SECTION_ALIGNMENT_ITEMS_LENGTH, } from '../../constants';
+import { computeLegacyTargets, reconnectTextStyleRoles, contentFieldReconnectSpec, drawnFontFamily, siteTextFontName, FAMILY_TIERS, } from '../text-role-reconnect.util';
+import { pairedRteTextField, rteStyleFieldsFor, } from '@shared/color-strategies/rte-field-pairs';
+import { containerTextColorDefaults, titleSurfaceContrastFill, } from '../container-text-color.util';
+import { stripLiftContentRte, textRunFontFamilies, } from '../rte-role-lift.util';
+import { collectRteTextColors, fillUncolouredRteText, } from '@shared/color-strategies/rte-color';
+import { isBlankColorValue } from '../color-palette.util';
+import { plainTextToRteJson, resolveHtmlParser, isTiptapDocument, } from '@shared/rte-render.util';
+// SNAPSHOT DEPENDENCY NOTICE: B/C/D import live shared helpers above. Their source modules carry
+// `MIGRATION-22 SNAPSHOT DEPENDENCY` notices; once v22 ships, copy the v22 semantics here before
+// changing any of them. B1 already owns an inline snapshot of its typography fill.
+// `migration-22.fixed-input.test.ts` fails when a helper change moves this migration's output.
+/**
+ * BP-5969 migration-22 — the single-source text-style migration. Version-gated: runs
+ * once when `v < 22`. The durable decisions are `0019-retire-rte-object-style-sync.md`,
+ * `0020-role-is-typography-only-colour-is-contrast-derived.md`, and
+ * `0021-migrated-content-reconnects-to-nearest-role-with-override.md`.
+ *
+ * A/B/C are appearance-preserving. D/E/G finish the ADR-0020 colour decouple in the same
+ * (still-unreleased) migration — they too preserve appearance, by freezing each element's
+ * currently-resolved colour before the role colour and base coat that fed it are removed.
+ * One decided exception (ADR-0020, Update 2026-09-29): a social-links section with no base
+ * coat to freeze bakes its icon fill to the title's contrast colour instead — a new colour,
+ * not a literal freeze of whatever `currentColor` happened to paint under `:root`.
+ *  A.  Seed each old role's colour onto its target tier (D3 base coat) — `seedRoleColours`.
+ *      Roles keep their §4 size, weight and line height; the old size is preserved as a per-block
+ *      override by B. The legacy → tier map is computed per-site by `computeLegacyTargets`.
+ *  A2. (R16) Count the font the site's title/heading, description/paragraph and button text shows,
+ *      and give each family the winner — each family's font comes from the site's text, not §4 —
+ *      before B and C link equal text to it — `seedRoleFonts`.
+ *  B.  Seed the absent header-button / brand.contact Save Contact styles (they rendered as
+ *      `buttons`), then reconnect every text field outside the ten — content, text items, footer
+ *      copyright, nav, header button, Save Contact — to its nearest role, keeping its look as
+ *      overrides — `reconnectContentRoles` (the shared `text-role-reconnect.util`). The three old
+ *      no-role renderer defaults (mailing-list title, Support Me title, text block) are materialised
+ *      here only, before reconnect persists their effective values; no runtime reader keeps them. A colourless nav
+ *      link's colour is baked here, not in D: it comes from the legacy role, which B replaces. A
+ *      payment or shop success message with no role of its own gets the look it drew
+ *      (`seedSuccessMessageStyle`); D then bakes its colour, like any non-RTE style.
+ *  C.  Baked→override strip/lift on RTE fields (D4) — `stripLiftContentRte`; per field it also folds
+ *      legacy bold/italic/underline/strike marks into the run's textStyle attrs (`foldSemanticFormattingMarks`)
+ *      and pins a not-bold legacy block's weight so a bold heading tier can't bold it (`pinLegacyRunWeight`).
+ *  B1. Convert plain-text RTE-eligible fields to Tiptap docs — `convertPlainRteFields`.
+ *  D.  Bake each element's resolved colour explicitly, social-links icon fills included —
+ *      `bakeElementColours`.
+ *  E.  Clear the retired role colour — `clearRoleColours`.
+ *  G.  Colour-decouple RTE-paired style objects: remove `color` only — `stripRteStyleColours`.
+ *  H.  Delete the retired site text font and its footer copies — `deleteTextFontFamily`
+ *      (`0036-retire-text-font-family.md`). A2 and B read it through `siteTextFontName`.
+ *
+ * Ordering is load-bearing: D reads the base coat off `paragraph1` and the role colours (which A
+ * seeds from the old roles), so it must run after A and before E; B must run before C and D, which
+ * read each field's reconnected role and pinned typography; G removes the RTE style object's
+ * colour, so it must run after D has baked that colour into the mark. B1 runs after C (so C's
+ * per-run typography bake sees real editor-baked docs, not a freshly-converted placeholder) and
+ * before D (so D colours the converted runs like any other doc). A2 runs before B, C, B1, which
+ * read the role's font: on the untouched model, so it counts what a legacy-role or no-role field
+ * showed before B relinks it, and links B and C to bake against the winner it seeds. H runs last,
+ * after every reader of the site text font.
+ *
+ * Version-gated (v only moves forward), so this runs exactly once. A hypothetical re-run is a
+ * no-op throughout: B (seed + reconnect), C (strip + weight pin) and B1 (convert) find every button
+ * style present and every field on one of the ten, no baked role-equal typography, every bare run
+ * already weight-pinned and no plain strings left; D/E/G find every element already coloured, role
+ * colours already cleared and RTE style objects already colourless; H finds nothing to delete; and
+ * A (`seedRoleColours`) finds nothing to copy — E already cleared the legacy roles' colour
+ * (persisted), so the tiers keep their §4 typography untouched. A2 re-counts what the migrated
+ * site shows, the same fonts, so it picks the same winners — also a no-op. Unreachable behind the
+ * gate; documented here per the migration rules.
+ */
+export { computeLegacyTargets };
+export { stripLiftRteDoc, foldSemanticFormattingMarks, pinLegacyRunWeight, stripLiftContentRte, } from '../rte-role-lift.util';
+/**
+ * Seed each old legacy role's colour onto its target tier — COLOUR ONLY; the tier keeps its
+ * §4 default typography. `bakeElementColours` (D) freezes each element's colour by reading its
+ * tier, and the base coat off `paragraph1`, so a legacy block's colour is preserved exactly as
+ * long as the tier it links to carries the old role's colour. `clearRoleColours` (E) then wipes
+ * the seed once D has read it — the tier ends typography-only, per ADR-0020.
+ */
+export const seedRoleColours = (options, targets) => {
+    for (const legacy of Object.keys(targets)) {
+        const source = options[legacy]?.style;
+        const colour = source?.color;
+        if (colour === undefined || colour === null || colour === '')
+            continue;
+        const target = options[targets[legacy]]?.style;
+        // The canonical target normally pre-exists (the model constructor seeds all 10); guard
+        // defensively for pre-10-role metadata rather than assume it.
+        if (target)
+            target.color = colour;
+    }
+};
+// An absent header-button or brand.contact Save Contact style rendered as `buttons`. Seeding
+// it lets the reconnect move it to `button` with that look kept as overrides.
+const seedAbsentButtonStyles = (brandPageModel) => {
+    for (const header of [
+        brandPageModel.pageHeaderDesktop,
+        brandPageModel.pageHeaderMobile,
+    ]) {
+        const headerButton = header?.headerButton;
+        if (headerButton) {
+            headerButton.buttonTextStyle ??= {
+                textStyleType: TEXT_STYLE_TYPES.buttons,
+            };
+        }
+    }
+    if (brandPageModel.brandPageType !== BRAND_PAGE_TYPES.brandContact)
+        return;
+    // The same defaults the view model and the maker store apply when none are saved.
+    brandPageModel.saveContactSettings ??= {
+        isSavingEnabled: true,
+        hideBranding: false,
+    };
+    brandPageModel.saveContactSettings.buttonTextStyle ??= {
+        textStyleType: TEXT_STYLE_TYPES.buttons,
+    };
+};
+// ── R16 — job A2: role fonts on upgrade ───────────────────────────────────
+const LATO = FONT_FAMILY_CONFIGS[DEFAULT_FONT_FAMILY_KEY].name;
+// Every display NAME a stored font can resolve to — built once, not re-scanned per vote.
+const FONT_FAMILY_NAMES = new Set(Object.values(FONT_FAMILY_CONFIGS).map((config) => config.name));
+// A stored font counts by its display NAME: a key spelling ('nunito') counts as its name
+// ('Nunito'); a font outside the list casts no vote (Q11) and the stored override survives
+// (B/C compare strictly, so a key-spelled override never drops).
+const voteFontName = (fontFamily) => {
+    if (!fontFamily)
+        return undefined;
+    const byKey = FONT_FAMILY_CONFIGS[fontFamily]?.name;
+    if (byKey)
+        return byKey;
+    return FONT_FAMILY_NAMES.has(fontFamily) ? fontFamily : undefined;
+};
+// One tally per family. A `Map` keeps first-insertion order, and a later count never overtakes an
+// EQUAL earlier one, so the winner scan gives the tie to whichever font was first voted for
+// (migration-21's first-seen rule, D11).
+class FontTally {
+    votes = new Map();
+    add(fontFamily) {
+        const name = voteFontName(fontFamily);
+        if (!name)
+            return;
+        this.votes.set(name, (this.votes.get(name) ?? 0) + 1);
+    }
+    winner(defaultFont) {
+        let winner = defaultFont;
+        let max = 0;
+        for (const [font, count] of this.votes) {
+            if (count > max) {
+                max = count;
+                winner = font;
+            }
+        }
+        return winner;
+    }
+}
+// Depth-first through the nav from its home page (`orders[0]`), then any page with no route, in
+// its stored order — `page-settings-store.ts` `syncPagesWithOrders`'s algorithm, read-only here.
+const sitePageOrder = (brandPageModel) => {
+    const routes = brandPageModel.nav?.routes ?? [];
+    const pageIds = [];
+    const collect = (orders) => {
+        for (const order of orders ?? []) {
+            const route = routes.find((r) => r.id === order.routeId);
+            if (route?.pageId)
+                pageIds.push(route.pageId);
+            collect(order.subRoutes);
+        }
+    };
+    collect(brandPageModel.nav?.orders);
+    const pages = brandPageModel.pages ?? [];
+    const byId = new Map(pages.map((page) => [page.id, page]));
+    const ordered = [];
+    for (const id of pageIds) {
+        const page = byId.get(id);
+        if (page) {
+            ordered.push(page);
+            byId.delete(id);
+        }
+    }
+    ordered.push(...byId.values());
+    return ordered;
+};
+// Same predicate as `vcard.util`'s `hasProfileContent`, checked directly against the raw model:
+// that one is typed for the rendered view model, which migration runs before building.
+const hasProfileContent = (brandPageModel) => (brandPageModel.pages ?? []).some((page) => page.contents?.some((content) => content.type === 'profile'));
+// A Tiptap doc gives the distinct fonts its non-empty runs show; a non-blank plain string gives
+// the block font; anything else (blank, `false`, absent) casts no vote — read the same way the
+// reconnect will (`drawnFontFamily`), so the count can't disagree with what B and C keep.
+const voteText = (tally, style, text, options, siteFont) => {
+    if (!style)
+        return;
+    if (isTiptapDocument(text)) {
+        const blockFont = drawnFontFamily(style, options, siteFont);
+        for (const font of textRunFontFamilies(text, blockFont))
+            tally.add(font);
+        return;
+    }
+    if (typeof text !== 'string' || text.trim() === '')
+        return;
+    tally.add(drawnFontFamily(style, options, siteFont));
+};
+// The content-level style key → its plain text field, for the sections whose title/description
+// isn't RTE-paired (`pairedRteTextField` returns nothing for them) — a link button's `title`
+// (`ButtonContent`) and a direct section button's `buttonText` (banner, booking, mailing-list…).
+const CONTENT_LEVEL_TEXT_FIELD = {
+    titleStyle: 'title',
+    descriptionStyle: 'description',
+    paragraphStyle: 'paragraph',
+    buttonTextStyle: 'buttonText',
+};
+// Payment (Continue/Done) and Support Me (the same widget, `Payment.vue`) always show their
+// fixed-label button whenever the section renders — no persisted field holds the label, so
+// there's nothing to check for blank. Shop's fixed-label "View cart" (`Shop.vue:59`) shows only
+// once it has a product to sell; with none, its button (like an empty title) casts no vote.
+const showsFixedLabelButton = (contentType, fields) => contentType === 'request-payment' ||
+    contentType === 'support-me' ||
+    (contentType === 'shop-section' &&
+        Array.isArray(fields.products) &&
+        fields.products.length > 0);
+// One content: its own title/description/paragraph/button-text field, then (images/shapes only)
+// each item's title/paragraph/buttonText against the section's single heading/paragraph/button
+// style. `headingStyle` never has content-level text of its own, so it only votes per item.
+const voteContentFields = (tallies, fields, options, siteFont) => {
+    const contentType = fields.type;
+    for (const key of [
+        'titleStyle',
+        'descriptionStyle',
+        'paragraphStyle',
+        'buttonTextStyle',
+    ]) {
+        const style = fields[key];
+        if (!style || typeof style !== 'object')
+            continue;
+        if (key === 'buttonTextStyle' &&
+            showsFixedLabelButton(contentType, fields)) {
+            // A fixed-label button's text is an i18n string, never model data — there's nothing to
+            // check for blank, so vote its font directly rather than through `voteText`'s text gate.
+            tallies.button.add(drawnFontFamily(style, options, siteFont));
+            continue;
+        }
+        // `pairedRteTextField` returns nothing for `buttonTextStyle` (never RTE-paired) and for a
+        // button content's own `titleStyle` (a link's plain-text label) — `CONTENT_LEVEL_TEXT_FIELD`
+        // is exactly the fallback those two need.
+        const textField = pairedRteTextField(contentType ?? '', key) ??
+            CONTENT_LEVEL_TEXT_FIELD[key];
+        // The reconnect's own family (`contentFieldReconnectSpec`), so the vote and the reconnect
+        // share one classification: Button text for a link button's `titleStyle` or any
+        // `buttonTextStyle`, otherwise fixed by the key.
+        const family = contentFieldReconnectSpec(contentType, key).family;
+        if (!textField || !family)
+            continue;
+        voteText(tallies[family], style, fields[textField], options, siteFont);
+    }
+    const items = fields.items;
+    if (!Array.isArray(items))
+        return;
+    // Items belong only to `MediaSection`s (images/shapes) — the section's own `paragraphStyle`
+    // never also pairs an RTE field at content level there (only `about-section` does, and it has
+    // no items), so an item's paragraph vote never double-counts the section's own.
+    const perItemVotes = [
+        [
+            'headings',
+            fields.headingStyle,
+            'title',
+        ],
+        [
+            'paragraphs',
+            fields.paragraphStyle,
+            'paragraph',
+        ],
+        [
+            'button',
+            fields.buttonTextStyle,
+            'buttonText',
+        ],
+    ];
+    // A left/right-aligned images-section renders only its first few items
+    // (`view-model.util.ts` `mapToImagesSectionViewModel`) — an item past that cutoff never shows,
+    // so it casts no vote either.
+    const displayStyle = fields.displayStyle;
+    const renderedItems = contentType === 'images-section' &&
+        (displayStyle === ALIGN_LEFT_ALIGNED ||
+            displayStyle === ALIGN_RIGHT_ALIGNED)
+        ? items.slice(0, MAX_IMAGES_SECTION_ALIGNMENT_ITEMS_LENGTH)
+        : items;
+    for (const item of renderedItems) {
+        if (!item || typeof item !== 'object')
+            continue;
+        for (const [family, itemStyle, textField] of perItemVotes) {
+            if (itemStyle) {
+                voteText(tallies[family], itemStyle, item[textField], options, siteFont);
+            }
+        }
+    }
+};
+// The header button renders only with a non-blank label (`view-model.util.ts:1215`) — `isVisible`
+// alone isn't enough, or a visible-but-blank desktop button would wrongly stop the mobile one
+// (which might otherwise render) from getting a turn.
+const headerButtonRenders = (headerButton) => !!headerButton?.isVisible && !!headerButton.text?.trim();
+/**
+ * A2 — count the font the site's title/heading, description/paragraph and button text shows
+ * (`business-rules.md` *Text style roles*), and give each family the winner, before B and C link
+ * equal text to it. Runs on the untouched v21 model, after A and before B: a field's font is read
+ * the same way B will read its look (`drawnFontFamily`), so the count and the reconnect can't
+ * disagree about what a field showed. Only `fontFamily` changes on the ten canonical roles — size,
+ * weight and line height stay at their §4 defaults. A family with no vote keeps Lato.
+ */
+export const seedRoleFonts = (brandPageModel, options) => {
+    const siteFont = siteTextFontName(brandPageModel) ?? LATO;
+    const tallies = {
+        headings: new FontTally(),
+        paragraphs: new FontTally(),
+        button: new FontTally(),
+    };
+    // The header button votes once — the desktop header's, else the mobile one (Q12c).
+    for (const header of [
+        brandPageModel.pageHeaderDesktop,
+        brandPageModel.pageHeaderMobile,
+    ]) {
+        const headerButton = header?.headerButton;
+        if (!headerButtonRenders(headerButton))
+            continue;
+        voteText(tallies.button, headerButton.buttonTextStyle ?? {
+            textStyleType: TEXT_STYLE_TYPES.buttons,
+        }, headerButton.text, options, siteFont);
+        break;
+    }
+    for (const page of sitePageOrder(brandPageModel)) {
+        for (const content of page.contents ?? []) {
+            voteContentFields(tallies, content, options, siteFont);
+        }
+    }
+    // brand.contact only, and only once the widget is actually turned on (`Page.mixin.ts:535`) and the
+    // site has a profile section for it to attach to (`Page.mixin.ts` `shouldShowSaveContactWidget`,
+    // `checkHasProfileContent`) — otherwise it never renders, the same "nothing to show" rule as an
+    // empty title.
+    if (brandPageModel.brandPageType === BRAND_PAGE_TYPES.brandContact &&
+        brandPageModel.saveContactSettings?.isSavingEnabled !== false &&
+        hasProfileContent(brandPageModel)) {
+        tallies.button.add(drawnFontFamily(brandPageModel.saveContactSettings?.buttonTextStyle ?? {
+            textStyleType: TEXT_STYLE_TYPES.buttons,
+        }, options, siteFont));
+    }
+    // The canonical roles normally pre-exist (the model constructor seeds all 10); guard
+    // defensively for pre-10-role metadata rather than assume it (as `seedRoleColours` does). A
+    // family with no vote keeps Lato — never the site font, which is only what an UNCOUNTED field
+    // inherits (`drawnFontFamily`), not a family-wide default.
+    for (const family of Object.keys(tallies)) {
+        const winner = tallies[family].winner(LATO);
+        for (const role of FAMILY_TIERS[family]) {
+            if (options[role])
+                options[role].style.fontFamily = winner;
+        }
+    }
+};
+/**
+ * B — seed the absent button styles, then reconnect every text field outside the ten to its
+ * nearest role, keeping the look production drew: a field on a role drew only that role's
+ * typography (`drawnBeforeCascade`). After this every text field links one of the ten (R14).
+ */
+const isUnset = (value) => value === undefined || value === null || value === '';
+const isUnlinkedLegacyStyle = (style) => {
+    if (!style || typeof style !== 'object')
+        return false;
+    const type = style.textStyleType;
+    return (!isCanonicalTextStyleType(type) &&
+        !isLegacyTextStyleType(type));
+};
+const setIfUnset = (style, key, value) => {
+    if (isUnset(style[key]) && !isUnset(value))
+        style[key] = value;
+};
+const styleRecord = (value) => value && typeof value === 'object' && !Array.isArray(value)
+    ? value
+    : {};
+/**
+ * B0 — production composed three no-role text styles in its view-model layer. Recreate those
+ * values once on the persisted field before B picks the nearest canonical role. A valid legacy
+ * role was resolved instead of these component defaults, so it must remain untouched.
+ */
+const materialiseNoRoleRendererDefaults = (brandPageModel) => {
+    for (const page of brandPageModel.pages ?? []) {
+        for (const content of page.contents ?? []) {
+            const fields = content;
+            if (content.type === 'mailing-list') {
+                const style = fields.titleStyle;
+                if (isUnlinkedLegacyStyle(style)) {
+                    setIfUnset(style, 'fontSize', FONT_SIZE_BODY);
+                    setIfUnset(style, 'fontWeight', 'bold');
+                }
+            }
+            if (content.type === 'support-me') {
+                const style = fields.titleStyle;
+                if (isUnlinkedLegacyStyle(style)) {
+                    setIfUnset(style, 'fontWeight', 'bold');
+                }
+            }
+            if (content.type === 'text') {
+                const original = styleRecord(fields.textStyle);
+                const isUnlinked = isUnlinkedLegacyStyle(original);
+                // Production's text mapper merged these deprecated sibling objects before the style
+                // object. Alignment and colour mattered even on an old role; textSize and the 1.5
+                // default only mattered without one, because a role replaced all typography.
+                fields.textStyle = isUnlinked
+                    ? {
+                        lineHeight: LINE_HEIGHT_BODY,
+                        ...styleRecord(fields.textSize),
+                        ...styleRecord(fields.textAlignment),
+                        ...styleRecord(fields.textColor),
+                        ...styleRecord(original),
+                    }
+                    : {
+                        ...styleRecord(fields.textAlignment),
+                        ...styleRecord(fields.textColor),
+                        ...styleRecord(original),
+                    };
+                delete fields.textSize;
+                delete fields.textAlignment;
+                delete fields.textColor;
+            }
+        }
+    }
+};
+const legacyRenderedDefaults = (content, key) => {
+    const style = content[key];
+    if (!isUnlinkedLegacyStyle(style))
+        return undefined;
+    if (content.type === 'mailing-list' && key === 'titleStyle') {
+        return { fontSize: FONT_SIZE_BODY, fontWeight: 'bold' };
+    }
+    if (content.type === 'support-me' && key === 'titleStyle') {
+        return { fontWeight: 'bold' };
+    }
+    if (content.type === 'text' && key === 'textStyle') {
+        return { lineHeight: LINE_HEIGHT_BODY };
+    }
+    return undefined;
+};
+export const reconnectContentRoles = (brandPageModel, targets, options) => {
+    seedAbsentButtonStyles(brandPageModel);
+    materialiseNoRoleRendererDefaults(brandPageModel);
+    reconnectTextStyleRoles(brandPageModel, targets, options, {
+        drawnBeforeCascade: true,
+        renderedDefaultsForContent: legacyRenderedDefaults,
+    });
+};
+const hasNoRole = (style) => {
+    if (!style || typeof style !== 'object')
+        return false;
+    const textStyleType = style.textStyleType;
+    return (!isCanonicalTextStyleType(textStyleType) &&
+        !isLegacyTextStyleType(textStyleType));
+};
+/**
+ * Job B assigns a canonical role to every unlinked field. Job D must still use the colour the
+ * field rendered with before that assignment: its own colour, container default, then the base coat
+ * (never the role B selected merely for typography). Keep the location rather than the style object,
+ * because reconnect replaces each style object.
+ */
+const captureNoRoleTextStyles = (brandPageModel) => {
+    const locations = new WeakMap();
+    const record = (holder, key) => {
+        if (!hasNoRole(holder[key]))
+            return;
+        const keys = locations.get(holder) ?? new Set();
+        keys.add(key);
+        locations.set(holder, keys);
+    };
+    for (const page of brandPageModel.pages ?? []) {
+        for (const content of page.contents ?? []) {
+            const fields = content;
+            for (const key of Object.keys(CONTENT_TEXT_STYLE_PROPERTY_KEYS)) {
+                record(fields, key);
+            }
+            const textItems = fields.textItems;
+            if (Array.isArray(textItems)) {
+                for (const item of textItems) {
+                    if (item && typeof item === 'object') {
+                        record(item, 'textStyle');
+                    }
+                }
+            }
+        }
+    }
+    for (const footer of [
+        brandPageModel.pageFooterDesktop,
+        brandPageModel.pageFooterMobile,
+    ]) {
+        if (footer && typeof footer === 'object') {
+            record(footer, 'copyrightStyle');
+        }
+    }
+    return locations;
+};
+/**
+ * An RTE-eligible field that is a plain string, not a Tiptap doc. On an old site nothing
+ * converts plain text → doc (migration-20 only converts HTML), so such a field renders via
+ * `TextWrapper`'s PLAIN path from `style.color` — it has no run mark to hold colour. So its
+ * colour must be baked onto (D) and never stripped from (G) the style object; only a genuine
+ * doc's colour moves into a mark. A non-string field is NOT plain text: a real doc holds its
+ * colour in the mark, and an absent (`undefined`/`null`) field renders nothing — either way G
+ * safely strips the (now inert) style-object colour. An empty string `''` DOES count as plain
+ * text and is kept: a field later filled with plain text must not have lost its colour.
+ * `convertPlainRteFields` completes that conversion in this migration; regular runtime paths do not rewrap.
+ */
+const isPlainTextValue = (value) => typeof value === 'string';
+/** A linked role's colour, read defensively (the typed property is retired). */
+const roleColour = (options, textStyleType) => textStyleType
+    ? (options[textStyleType]?.style?.color ?? undefined)
+    : undefined;
+/**
+ * D — freeze each text element's currently-resolved colour so removing the base coat (F)
+ * and the role colour (E) changes no pixels. migration-21 already baked element→frame→role
+ * colour into RTE runs, so the only uncoloured runs reaching here inherit the base coat;
+ * non-RTE fields (21 left them alone) resolve element→container-default→role→base coat.
+ * `buttonTextStyle` is excluded — the button label takes its colour from `buttonStyles`,
+ * never the base coat. A social-links section's unset icon fill is frozen here too.
+ */
+export const bakeElementColours = (brandPageModel, options, noRoleTextStyles = new WeakMap()) => {
+    const baseCoat = roleColour(options, 'paragraph1');
+    for (const page of brandPageModel.pages ?? []) {
+        for (const content of page.contents ?? []) {
+            const fields = content;
+            const containerDefaults = containerTextColorDefaults(content, brandPageModel.styles, brandPageModel.brandPageType);
+            const rteStyleFields = new Set(rteStyleFieldsFor(content.type));
+            const resolvedColour = (style, holder, key) => style?.color ||
+                containerDefaults[key] ||
+                (noRoleTextStyles.get(holder)?.has(key)
+                    ? undefined
+                    : roleColour(options, style?.textStyleType)) ||
+                baseCoat;
+            // Non-RTE style objects → bake onto `style.color`.
+            for (const key of Object.keys(CONTENT_TEXT_STYLE_PROPERTY_KEYS)) {
+                if (key === 'buttonTextStyle' || rteStyleFields.has(key))
+                    continue;
+                const style = fields[key];
+                if (!style || !isBlankColorValue(style.color))
+                    continue;
+                const resolved = resolvedColour(style, fields, key);
+                if (!isBlankColorValue(resolved))
+                    style.color = resolved;
+            }
+            // RTE-eligible fields. A real doc holds colour in its run marks → fill the runs the mark
+            // left uncoloured (the base-coat stragglers). A plain string (an old site never converted
+            // to a doc) has NO mark, so its colour lives on the style object → bake it there, like a
+            // non-RTE field; G then leaves that colour alone (it only strips when a doc holds it).
+            for (const styleField of rteStyleFields) {
+                const textField = pairedRteTextField(content.type, styleField);
+                if (!textField)
+                    continue;
+                const doc = fields[textField];
+                if (isPlainTextValue(doc)) {
+                    const style = fields[styleField];
+                    if (style && isBlankColorValue(style.color)) {
+                        const resolved = resolvedColour(style, fields, styleField);
+                        if (!isBlankColorValue(resolved))
+                            style.color = resolved;
+                    }
+                    continue;
+                }
+                if (!collectRteTextColors(doc)?.hasUncolouredRuns)
+                    continue;
+                const resolved = resolvedColour(fields[styleField], fields, styleField);
+                if (!isBlankColorValue(resolved)) {
+                    fields[textField] =
+                        fillUncolouredRteText(doc, resolved) ?? doc;
+                }
+            }
+            // Social icons had no colour of their own: they painted the base coat (the paragraphs
+            // seed, or `currentColor` under `:root`). Freeze it; with no base coat, the title's
+            // contrast colour, so every icon ends with a stored fill.
+            if (content.type === 'social-links') {
+                const iconFillStyles = (fields.iconFillStyles ?? {});
+                if (isBlankColorValue(iconFillStyles.fill)) {
+                    const fill = !isBlankColorValue(baseCoat)
+                        ? baseCoat
+                        : titleSurfaceContrastFill(content, brandPageModel.styles, brandPageModel.brandPageType);
+                    if (!isBlankColorValue(fill)) {
+                        fields.iconFillStyles = { ...iconFillStyles, fill };
+                    }
+                }
+            }
+            // brandSite text `textItems` — same rule per item (RTE doc, else the style object).
+            const textItems = fields.textItems;
+            if (Array.isArray(textItems)) {
+                for (const item of textItems) {
+                    if (!item || typeof item !== 'object')
+                        continue;
+                    const resolved = resolvedColour(item.textStyle, item, 'textStyle');
+                    if (isBlankColorValue(resolved))
+                        continue;
+                    if (collectRteTextColors(item.text)?.hasUncolouredRuns) {
+                        item.text =
+                            fillUncolouredRteText(item.text, resolved) ?? item.text;
+                    }
+                    else if (item.textStyle &&
+                        isBlankColorValue(item.textStyle.color)) {
+                        item.textStyle.color = resolved;
+                    }
+                }
+            }
+        }
+    }
+    // Footer copyright is non-RTE text that resolved through role → base coat, but lives
+    // OUTSIDE `pages[].contents`, so freeze it here too — else it loses its colour when E
+    // clears the role and F removes the base coat (the copyright-on-dark-footer regression).
+    for (const footer of [
+        brandPageModel.pageFooterDesktop,
+        brandPageModel.pageFooterMobile,
+    ]) {
+        const style = footer?.copyrightStyle;
+        if (!style || !isBlankColorValue(style.color))
+            continue;
+        const resolved = (noRoleTextStyles.get(footer)?.has('copyrightStyle')
+            ? undefined
+            : roleColour(options, style.textStyleType)) || baseCoat;
+        if (!isBlankColorValue(resolved))
+            style.color = resolved;
+    }
+};
+/** E — clear the retired role colour from every role definition (run after D reads it). */
+export const clearRoleColours = (options) => {
+    for (const key of Object.keys(options)) {
+        const style = options[key]?.style;
+        if (style && 'color' in style)
+            delete style.color;
+    }
+};
+/**
+ * G — colour-decouple the RTE-paired style objects: remove ONLY `color` (D baked it into the
+ * mark). Everything else stays — a block-level typography override (a title set to a non-role
+ * font/size, `textAlign`, `applyAutoScale`, the role link) is genuine state the renderer
+ * applies via `overrideTypographyStyle`; dropping it would lose the override through migration.
+ * So the RTE style object becomes `Omit<TextStyleDeclaration, 'color'>`, not a bare role link.
+ * Non-RTE per-item styles (`headingStyle`, shapes/images `paragraphStyle`, `testimonialStyle`,
+ * …) are not RTE and are untouched.
+ */
+const stripRteStyleColour = (style) => {
+    if (style && 'color' in style)
+        delete style.color;
+};
+export const stripRteStyleColours = (brandPageModel) => {
+    for (const page of brandPageModel.pages ?? []) {
+        for (const content of page.contents ?? []) {
+            const fields = content;
+            for (const styleField of rteStyleFieldsFor(content.type)) {
+                const textField = pairedRteTextField(content.type, styleField);
+                // A plain-string field keeps its style-object colour — that's its only home (D baked it
+                // there, there's no mark). A real doc holds colour in its mark, so strip the object.
+                if (textField && isPlainTextValue(fields[textField]))
+                    continue;
+                stripRteStyleColour(fields[styleField]);
+            }
+            const textItems = fields.textItems;
+            if (Array.isArray(textItems)) {
+                for (const item of textItems) {
+                    if (!item || typeof item !== 'object')
+                        continue;
+                    if (isPlainTextValue(item.text))
+                        continue; // plain-text item keeps its baked colour
+                    stripRteStyleColour(item.textStyle);
+                }
+            }
+        }
+    }
+};
+/** H — delete the retired site text font and the footers' stray copies. */
+export const deleteTextFontFamily = (brandPageModel) => {
+    const holders = [
+        brandPageModel.styles?.textStyles,
+        brandPageModel.pageFooterDesktop,
+        brandPageModel.pageFooterMobile,
+    ];
+    for (const holder of holders) {
+        if (holder)
+            delete holder['textFontFamily'];
+    }
+};
+/**
+ * B1 — convert plain-text RTE-eligible fields to Tiptap docs, so every such field is a doc at
+ * load and the editor never runs its plain→RTE "rewrap" (the runtime anti-pattern this retires).
+ *
+ * Only PLAIN strings are converted: migration-20 already did HTML→doc, and the plain-by-design
+ * sections (`shop-section`/`request-payment`/`support-me`) are excluded because `rteStyleFieldsFor`
+ * returns `[]` for them — they render via `TextWrapper`'s plain path and keep their `style.color`.
+ * A converted field's colour is filled by D (into the mark) and its style-object colour stripped
+ * by G, exactly like any other doc.
+ *
+ * Runs AFTER C (see orchestrator) so C only ever sees editor-baked docs and its per-run typography
+ * bake operates on the real runs, not a freshly-converted placeholder.
+ *
+ * Error-tolerant like migration-20: a parse failure (or no DOM parser in this runtime) leaves the
+ * plain string in place, and Path A's D/G plain-text branches keep its colour resolvable — so the
+ * two together are total. `textAlign` is stamped onto the block node from the style object, as the
+ * runtime conversion (`getUpdatedHTMLFromEditor`) does via `setTextAlign`.
+ *
+ * The converted run is then baked with this migration's frozen typography resolver, so it carries all
+ * 7 typography attrs as a role var (follows role edits) or a literal override, not colour alone. Job C
+ * never saw this field (it was still a plain string), so without this bake the run would carry only
+ * colour and the maker toolbar (which reads the run, not the style object) would fall back to the role,
+ * ignoring a block-level override (e.g. a banner title set to a non-role font/size). It stays
+ * appearance-preserving: the fill is idempotent over an already-baked run, so the persisted doc renders
+ * identically — it is now just self-describing.
+ */
+const setBlockTextAlign = (doc, textAlign) => {
+    if (!textAlign)
+        return;
+    for (const block of doc.content ?? []) {
+        block.attrs = { ...(block.attrs ?? {}), textAlign };
+    }
+};
+// Snapshot the B1 resolver here rather than calling the live render helper. A versioned migration
+// defines one permanent v21 -> v22 transformation; later renderer fixes must not change its output.
+const MIGRATION_RTE_TYPOGRAPHY_ATTRS = [
+    ['fontFamily', '--role-font-family'],
+    ['fontSize', '--role-font-size'],
+    ['lineHeight', '--role-line-height'],
+    ['letterSpacing', '--role-letter-spacing'],
+    ['fontWeight', '--role-font-weight'],
+    ['fontStyle', '--role-font-style'],
+    ['textDecoration', '--role-text-decoration'],
+];
+const MIGRATION_RTE_NEUTRAL_TYPOGRAPHY = {
+    fontWeight: 'normal',
+    fontStyle: 'normal',
+    textDecoration: 'none',
+    letterSpacing: 'normal',
+};
+const UNQUOTED_FONT_FAMILY_TOKEN = /^-?[A-Za-z_][A-Za-z0-9_-]*$/;
+const migrationCssFontFamilyValue = (value) => value
+    .split(',')
+    .map((raw) => {
+    const family = raw.trim();
+    if (!family ||
+        family.startsWith('"') ||
+        family.startsWith("'") ||
+        family.startsWith('var(')) {
+        return family;
+    }
+    return family
+        .split(/\s+/)
+        .every((token) => UNQUOTED_FONT_FAMILY_TOKEN.test(token))
+        ? family
+        : `"${family}"`;
+})
+    .filter(Boolean)
+    .join(', ');
+const migrationRoleVarRef = (attr) => {
+    const variable = MIGRATION_RTE_TYPOGRAPHY_ATTRS.find(([name]) => name === attr)?.[1];
+    return `var(${variable})`;
+};
+const migrationRunTypographyFillValue = (attr, roleStyle, style) => {
+    const roleValue = roleStyle?.[attr];
+    const blockValue = style?.[attr];
+    const neutral = MIGRATION_RTE_NEUTRAL_TYPOGRAPHY[attr];
+    const hasRole = roleValue != null && roleValue !== '';
+    const hasBlock = blockValue != null && blockValue !== '';
+    if (roleStyle == null)
+        return hasBlock ? blockValue : undefined;
+    const effectiveRole = hasRole ? roleValue : neutral;
+    if (hasBlock && blockValue !== effectiveRole)
+        return blockValue;
+    return hasRole || neutral != null ? migrationRoleVarRef(attr) : undefined;
+};
+const fillMigration22RunTypography = (doc, roleStyle, style) => {
+    const clone = JSON.parse(JSON.stringify(doc));
+    const runs = [];
+    const collect = (node) => {
+        if (!node)
+            return;
+        if (node.type === 'text')
+            runs.push(node);
+        node.content?.forEach(collect);
+    };
+    collect(clone);
+    for (const run of runs) {
+        let mark = run.marks?.find((candidate) => candidate.type === 'textStyle');
+        for (const [attr] of MIGRATION_RTE_TYPOGRAPHY_ATTRS) {
+            const existing = mark?.attrs?.[attr];
+            if (existing !== undefined && existing !== null && existing !== '')
+                continue;
+            let value = migrationRunTypographyFillValue(attr, roleStyle, style);
+            if (value == null)
+                continue;
+            if (attr === 'fontFamily')
+                value = migrationCssFontFamilyValue(value);
+            if (!mark) {
+                mark = { type: 'textStyle', attrs: {} };
+                (run.marks ??= []).push(mark);
+            }
+            mark.attrs ??= {};
+            mark.attrs[attr] = value;
+        }
+    }
+    return clone;
+};
+// B1 converts a plain string after job C has run, so it needs C3's not-bold protection locally
+// too. Keep the whole B1 transform frozen: changing `rte-role-lift.util.ts` must not alter v22.
+const pinMigration22RunWeight = (doc, roleWeight, blockWeight) => {
+    if (blockWeight === undefined ||
+        blockWeight === null ||
+        blockWeight === '' ||
+        blockWeight === roleWeight) {
+        return;
+    }
+    const runs = [];
+    const collect = (node) => {
+        if (!node)
+            return;
+        if (node.type === 'text')
+            runs.push(node);
+        node.content?.forEach(collect);
+    };
+    collect(doc);
+    for (const run of runs) {
+        let mark = run.marks?.find((candidate) => candidate.type === 'textStyle');
+        if (mark?.attrs?.fontWeight != null && mark.attrs.fontWeight !== '')
+            continue;
+        if (!mark) {
+            mark = { type: 'textStyle', attrs: {} };
+            (run.marks ??= []).push(mark);
+        }
+        mark.attrs ??= {};
+        mark.attrs.fontWeight = blockWeight;
+    }
+};
+export const convertPlainRteFields = async (brandPageModel, options) => {
+    let parser;
+    try {
+        parser = await resolveHtmlParser();
+    }
+    catch (error) {
+        // No DOM parser here (e.g. jsdom failed to load on the server). Skip conversion — plain
+        // strings survive to D/G, whose Path A branches keep their colour. Mirrors migration-20.
+        console.error('migration-22: no HTML parser available, skipping plain→RTE conversion', error);
+        return;
+    }
+    const convert = (value, style) => {
+        if (!isPlainTextValue(value) || value.length === 0)
+            return undefined;
+        try {
+            // Pin the schema to v22 too: B1's structure and its attr-fill snapshot together define
+            // the permanent v21 -> v22 result.
+            const doc = plainTextToRteJson(value, parser, 22);
+            if (!doc)
+                return undefined;
+            setBlockTextAlign(doc, style?.textAlign);
+            // Bake the block override + role typography onto the bare run (job C skipped this field
+            // while it was a plain string) so the doc is self-describing for the maker toolbar.
+            const roleStyle = style?.textStyleType
+                ? options[style.textStyleType]?.style
+                : undefined;
+            // C3 (before the fill): pin a not-bold legacy block's weight as a literal so the fill can't
+            // treat its `normal` as inert and let the run inherit a bold heading tier. The plain string had
+            // no bold marks, so every run is bare — the fill then keeps this literal and completes the rest.
+            pinMigration22RunWeight(doc, roleStyle?.fontWeight, style?.fontWeight);
+            return fillMigration22RunTypography(doc, roleStyle, style);
+        }
+        catch (error) {
+            // Leave the plain string; Path A keeps its colour resolvable.
+            console.error('migration-22: failed to convert plain RTE field, leaving as text', error);
+            return undefined;
+        }
+    };
+    for (const page of brandPageModel.pages ?? []) {
+        for (const content of page.contents ?? []) {
+            const fields = content;
+            for (const styleField of rteStyleFieldsFor(content.type)) {
+                const textField = pairedRteTextField(content.type, styleField);
+                if (!textField)
+                    continue;
+                const style = fields[styleField];
+                const doc = convert(fields[textField], style);
+                if (doc)
+                    fields[textField] = doc;
+            }
+            const textItems = fields.textItems;
+            if (Array.isArray(textItems)) {
+                for (const item of textItems) {
+                    if (!item || typeof item !== 'object')
+                        continue;
+                    const doc = convert(item.text, item.textStyle);
+                    if (doc)
+                        item.text = doc;
+                }
+            }
+        }
+    }
+};
+export const migration22 = async (migrationResult, _options) => {
+    const { brandPageModel } = migrationResult;
+    const options = brandPageModel.styles?.textStyles?.textStyleOptions;
+    if (options) {
+        const targets = computeLegacyTargets(options); // per-site legacy → nearest tier
+        seedRoleColours(options, targets); // A — seed each old role's colour onto its tier
+        seedRoleFonts(brandPageModel, options); // A2 — count the site's fonts onto each role family
+        const noRoleTextStyles = captureNoRoleTextStyles(brandPageModel);
+        reconnectContentRoles(brandPageModel, targets, options); // B — seed button styles, reconnect every text field
+        stripLiftContentRte(brandPageModel, options); // C — RTE baked → override
+        await convertPlainRteFields(brandPageModel, options); // B1 — plain text → Tiptap doc (after C)
+        bakeElementColours(brandPageModel, options, noRoleTextStyles); // D — freeze resolved colour
+        clearRoleColours(options); // E — retire role colour
+        stripRteStyleColours(brandPageModel); // G — colour-decouple RTE style objects
+    }
+    deleteTextFontFamily(brandPageModel); // H — after every reader of the site text font
+    return migrationResult;
+};