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

package/src/brand-page/utils/migration/migration-22.ts

@@ -0,0 +1,1336 @@
+import type { MigrationData, MigrationOptions } from '../migration.util';
+import {
+  BRAND_PAGE_TYPES,
+  type BrandPageModel,
+  type HeaderButton,
+  type NavOrder,
+  type PageModel,
+  type TextStyleDeclaration,
+} from '../../models';
+import {
+  TEXT_STYLE_TYPES,
+  isCanonicalTextStyleType,
+  isLegacyTextStyleType,
+  type TextStyleOptions,
+  type TextStyleType,
+  type LegacyTextStyleType,
+} from '../../models/styles.model';
+import {
+  CONTENT_TEXT_STYLE_PROPERTY_KEYS,
+  type ContentTextStylePropertyKey,
+  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,
+  type FontFamilyKey,
+} from '../../constants';
+import {
+  computeLegacyTargets,
+  reconnectTextStyleRoles,
+  contentFieldReconnectSpec,
+  drawnFontFamily,
+  siteTextFontName,
+  FAMILY_TIERS,
+  type LegacyTargetMap,
+  type TextRoleFamily,
+  type RenderedDefaultsForContent,
+} 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,
+  type HtmlParser,
+} from '@shared/rte-render.util';
+import type { JSONContent } from '@tiptap/vue-3';
+
+// 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: TextStyleOptions,
+  targets: LegacyTargetMap,
+): void => {
+  for (const legacy of Object.keys(targets) as LegacyTextStyleType[]) {
+    const source = options[legacy]?.style as unknown as
+      | Record<string, unknown>
+      | undefined;
+    const colour = source?.color;
+
+    if (colour === undefined || colour === null || colour === '') continue;
+
+    const target = options[targets[legacy]]?.style as unknown as
+      | Record<string, unknown>
+      | undefined;
+
+    // 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: BrandPageModel): void => {
+  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: string | undefined): string | undefined => {
+  if (!fontFamily) return undefined;
+
+  const byKey = FONT_FAMILY_CONFIGS[fontFamily as FontFamilyKey]?.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 {
+  private readonly votes = new Map<string, number>();
+
+  add(fontFamily: string | undefined): void {
+    const name = voteFontName(fontFamily);
+
+    if (!name) return;
+
+    this.votes.set(name, (this.votes.get(name) ?? 0) + 1);
+  }
+
+  winner(defaultFont: string): string {
+    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: BrandPageModel): PageModel[] => {
+  const routes = brandPageModel.nav?.routes ?? [];
+  const pageIds: string[] = [];
+
+  const collect = (orders: NavOrder[] | undefined): void => {
+    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: PageModel[] = [];
+
+  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): boolean =>
+  (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: FontTally,
+  style: TextStyleDeclaration | undefined,
+  text: unknown,
+  options: TextStyleOptions,
+  siteFont: string,
+): void => {
+  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: Partial<Record<string, string>> = {
+  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: string | undefined,
+  fields: Record<string, unknown>,
+): boolean =>
+  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: Record<TextRoleFamily, FontTally>,
+  fields: Record<string, unknown>,
+  options: TextStyleOptions,
+  siteFont: string,
+): void => {
+  const contentType = fields.type as string | undefined;
+
+  for (const key of [
+    'titleStyle',
+    'descriptionStyle',
+    'paragraphStyle',
+    'buttonTextStyle',
+  ] as const) {
+    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 as TextStyleDeclaration, 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 as TextStyleDeclaration,
+      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: [
+    TextRoleFamily,
+    TextStyleDeclaration | undefined,
+    string,
+  ][] = [
+    [
+      'headings',
+      fields.headingStyle as TextStyleDeclaration | undefined,
+      'title',
+    ],
+    [
+      'paragraphs',
+      fields.paragraphStyle as TextStyleDeclaration | undefined,
+      'paragraph',
+    ],
+    [
+      'button',
+      fields.buttonTextStyle as TextStyleDeclaration | undefined,
+      '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 as Record<string, unknown>[]).slice(
+          0,
+          MAX_IMAGES_SECTION_ALIGNMENT_ITEMS_LENGTH,
+        )
+      : (items as Record<string, unknown>[]);
+
+  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 | undefined,
+): headerButton is 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: BrandPageModel,
+  options: TextStyleOptions,
+): void => {
+  const siteFont = siteTextFontName(brandPageModel) ?? LATO;
+  const tallies: Record<TextRoleFamily, FontTally> = {
+    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 as unknown as Record<string, unknown>,
+        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) as TextRoleFamily[]) {
+    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: unknown): boolean =>
+  value === undefined || value === null || value === '';
+
+const isUnlinkedLegacyStyle = (
+  style: unknown,
+): style is Record<string, unknown> => {
+  if (!style || typeof style !== 'object') return false;
+
+  const type = (style as Record<string, unknown>).textStyleType;
+
+  return (
+    !isCanonicalTextStyleType(type as string | undefined) &&
+    !isLegacyTextStyleType(type as string | undefined)
+  );
+};
+
+const setIfUnset = (
+  style: Record<string, unknown>,
+  key: string,
+  value: unknown,
+): void => {
+  if (isUnset(style[key]) && !isUnset(value)) style[key] = value;
+};
+
+const styleRecord = (value: unknown): Record<string, unknown> =>
+  value && typeof value === 'object' && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : {};
+
+/**
+ * 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: BrandPageModel,
+): void => {
+  for (const page of brandPageModel.pages ?? []) {
+    for (const content of page.contents ?? []) {
+      const fields = content as unknown as Record<string, unknown>;
+
+      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: RenderedDefaultsForContent = (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: BrandPageModel,
+  targets: LegacyTargetMap,
+  options: TextStyleOptions,
+): void => {
+  seedAbsentButtonStyles(brandPageModel);
+  materialiseNoRoleRendererDefaults(brandPageModel);
+  reconnectTextStyleRoles(brandPageModel, targets, options, {
+    drawnBeforeCascade: true,
+    renderedDefaultsForContent: legacyRenderedDefaults,
+  });
+};
+
+// ── BP-5969 ADR-0020: colour decouple (jobs D, E, G) ──────────────────────────
+// Appended to the appearance-preserving A/B/C above. Colour is read via bracket access
+// because `GlobalTextStyleDeclaration.color` is retired from the typed model.
+
+type RawStyleObject = {
+  color?: string;
+  textStyleType?: string;
+  applyAutoScale?: boolean;
+  textAlign?: string;
+  fontWeight?: string;
+};
+
+type NoRoleTextStyles = WeakMap<object, Set<string>>;
+
+const hasNoRole = (style: unknown): boolean => {
+  if (!style || typeof style !== 'object') return false;
+
+  const textStyleType = (style as RawStyleObject).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: BrandPageModel,
+): NoRoleTextStyles => {
+  const locations: NoRoleTextStyles = new WeakMap();
+  const record = (holder: Record<string, unknown>, key: string): void => {
+    if (!hasNoRole(holder[key])) return;
+
+    const keys = locations.get(holder) ?? new Set<string>();
+
+    keys.add(key);
+    locations.set(holder, keys);
+  };
+
+  for (const page of brandPageModel.pages ?? []) {
+    for (const content of page.contents ?? []) {
+      const fields = content as unknown as Record<string, unknown>;
+
+      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 as Record<string, unknown>, 'textStyle');
+          }
+        }
+      }
+    }
+  }
+
+  for (const footer of [
+    brandPageModel.pageFooterDesktop,
+    brandPageModel.pageFooterMobile,
+  ]) {
+    if (footer && typeof footer === 'object') {
+      record(footer as unknown as Record<string, unknown>, '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: unknown): value is string =>
+  typeof value === 'string';
+
+/** A linked role's colour, read defensively (the typed property is retired). */
+const roleColour = (
+  options: TextStyleOptions,
+  textStyleType: string | undefined,
+): string | undefined =>
+  textStyleType
+    ? (((
+        options[textStyleType as TextStyleType]?.style as unknown as
+          | Record<string, unknown>
+          | undefined
+      )?.color as string | undefined) ?? 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: BrandPageModel,
+  options: TextStyleOptions,
+  noRoleTextStyles: NoRoleTextStyles = new WeakMap(),
+): void => {
+  const baseCoat = roleColour(options, 'paragraph1');
+
+  for (const page of brandPageModel.pages ?? []) {
+    for (const content of page.contents ?? []) {
+      const fields = content as unknown as Record<string, unknown>;
+      const containerDefaults = containerTextColorDefaults(
+        content,
+        brandPageModel.styles,
+        brandPageModel.brandPageType,
+      );
+      const rteStyleFields = new Set(rteStyleFieldsFor(content.type));
+
+      const resolvedColour = (
+        style: RawStyleObject | undefined,
+        holder: object,
+        key: string,
+      ): string | undefined =>
+        style?.color ||
+        containerDefaults[key as ContentTextStylePropertyKey] ||
+        (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] as RawStyleObject | undefined;
+
+        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] as RawStyleObject | undefined;
+
+          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] as RawStyleObject | undefined,
+          fields,
+          styleField,
+        );
+
+        if (!isBlankColorValue(resolved)) {
+          fields[textField] =
+            fillUncolouredRteText(doc, resolved as string) ?? 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 ?? {}) as Record<
+          string,
+          unknown
+        >;
+
+        if (isBlankColorValue(iconFillStyles.fill as string | undefined)) {
+          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 as
+        | { text?: unknown; textStyle?: RawStyleObject }[]
+        | undefined;
+
+      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 as string) ?? 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 as RawStyleObject | undefined;
+
+    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: TextStyleOptions): void => {
+  for (const key of Object.keys(options)) {
+    const style = options[key as TextStyleType]?.style as unknown as
+      | Record<string, unknown>
+      | undefined;
+
+    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: RawStyleObject | undefined): void => {
+  if (style && 'color' in style) delete style.color;
+};
+
+export const stripRteStyleColours = (brandPageModel: BrandPageModel): void => {
+  for (const page of brandPageModel.pages ?? []) {
+    for (const content of page.contents ?? []) {
+      const fields = content as unknown as Record<string, unknown>;
+
+      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] as RawStyleObject | undefined);
+      }
+
+      const textItems = fields.textItems as
+        | { text?: unknown; textStyle?: RawStyleObject }[]
+        | undefined;
+
+      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: BrandPageModel): void => {
+  const holders = [
+    brandPageModel.styles?.textStyles,
+    brandPageModel.pageFooterDesktop,
+    brandPageModel.pageFooterMobile,
+  ] as unknown as (Record<string, unknown> | undefined)[];
+
+  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: JSONContent,
+  textAlign: string | undefined,
+): void => {
+  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'],
+] as const;
+
+type MigrationRteTypographyAttr =
+  (typeof MIGRATION_RTE_TYPOGRAPHY_ATTRS)[number][0];
+
+type MigrationRteTypography = Partial<
+  Record<MigrationRteTypographyAttr, string>
+>;
+
+const MIGRATION_RTE_NEUTRAL_TYPOGRAPHY: Partial<
+  Record<MigrationRteTypographyAttr, string>
+> = {
+  fontWeight: 'normal',
+  fontStyle: 'normal',
+  textDecoration: 'none',
+  letterSpacing: 'normal',
+};
+
+const UNQUOTED_FONT_FAMILY_TOKEN = /^-?[A-Za-z_][A-Za-z0-9_-]*$/;
+
+const migrationCssFontFamilyValue = (value: string): string =>
+  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(', ');
+
+type MigrationRteNode = {
+  type?: string;
+  marks?: { type: string; attrs?: Record<string, unknown> }[];
+  content?: MigrationRteNode[];
+};
+
+const migrationRoleVarRef = (attr: MigrationRteTypographyAttr): string => {
+  const variable = MIGRATION_RTE_TYPOGRAPHY_ATTRS.find(
+    ([name]) => name === attr,
+  )?.[1];
+
+  return `var(${variable})`;
+};
+
+const migrationRunTypographyFillValue = (
+  attr: MigrationRteTypographyAttr,
+  roleStyle: MigrationRteTypography | undefined,
+  style: MigrationRteTypography | undefined,
+): string | undefined => {
+  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: JSONContent,
+  roleStyle: MigrationRteTypography | undefined,
+  style: MigrationRteTypography | undefined,
+): JSONContent => {
+  const clone = JSON.parse(JSON.stringify(doc)) as MigrationRteNode;
+  const runs: MigrationRteNode[] = [];
+
+  const collect = (node: MigrationRteNode | undefined): void => {
+    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 as JSONContent;
+};
+
+// 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: JSONContent,
+  roleWeight: string | undefined,
+  blockWeight: string | undefined,
+): void => {
+  if (
+    blockWeight === undefined ||
+    blockWeight === null ||
+    blockWeight === '' ||
+    blockWeight === roleWeight
+  ) {
+    return;
+  }
+
+  const runs: MigrationRteNode[] = [];
+  const collect = (node: MigrationRteNode | undefined): void => {
+    if (!node) return;
+
+    if (node.type === 'text') runs.push(node);
+
+    node.content?.forEach(collect);
+  };
+
+  collect(doc as MigrationRteNode);
+
+  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: BrandPageModel,
+  options: TextStyleOptions,
+): Promise<void> => {
+  let parser: HtmlParser;
+
+  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: unknown,
+    style: RawStyleObject | undefined,
+  ): JSONContent | undefined => {
+    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 as TextStyleType]?.style as
+            | MigrationRteTypography
+            | undefined)
+        : 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 as MigrationRteTypography,
+      );
+    } 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 as unknown as Record<string, unknown>;
+
+      for (const styleField of rteStyleFieldsFor(content.type)) {
+        const textField = pairedRteTextField(content.type, styleField);
+
+        if (!textField) continue;
+
+        const style = fields[styleField] as RawStyleObject | undefined;
+        const doc = convert(fields[textField], style);
+
+        if (doc) fields[textField] = doc;
+      }
+
+      const textItems = fields.textItems as
+        | { text?: unknown; textStyle?: RawStyleObject }[]
+        | undefined;
+
+      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: MigrationData,
+  _options: MigrationOptions,
+): Promise<MigrationData> => {
+  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;
+};