@designcrowd/library.brand-page 6.2.11 → 6.2.12

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

@@ -0,0 +1,4103 @@
+import { describe, it, expect, beforeAll, vi } from 'vitest';
+import {
+  seedRoleColours,
+  computeLegacyTargets,
+  reconnectContentRoles,
+  stripLiftContentRte,
+  stripLiftRteDoc,
+  foldSemanticFormattingMarks,
+  pinLegacyRunWeight,
+  bakeElementColours,
+  clearRoleColours,
+  stripRteStyleColours,
+  convertPlainRteFields,
+  migration22,
+} from './migration-22';
+import type { MigrationData, MigrationOptions } from '../migration.util';
+import {
+  BRAND_PAGE_TYPES,
+  NavigationDesktop,
+  PageHeaderDesktop,
+  PageStyles,
+  TextStyles,
+} from '../../models';
+import type { Content, HeaderButton } from '../../models';
+import {
+  mapToPageHeaderViewModel,
+  mapToViewModel,
+  resolveSaveContactTitleStyle,
+} from '../view-model.util';
+import { setLocaleAsync } from '@src/composables/useTranslate';
+import { HEADER_DISPLAY } from '../../constants';
+import {
+  createInitialBannerSectionContent,
+  createInitialBookingSectionContent,
+  createInitialButtonContent,
+  createInitialMailingListContent,
+  createInitialProfileContent,
+} from '@brand-page-maker/models';
+import type {
+  BrandPageModel,
+  TextStyleDeclaration,
+  TextStyleOptions,
+} from '../../models';
+import type { TextStyleType } from '../../models/styles.model';
+import { isTiptapDocument } from '@brand-page-maker/utils';
+import { resolveTextStyle, TEXT_STYLE_CASCADE_PROPS } from '../text-style.util';
+import { DETACHED_UNSET_EFFECTIVE } from '../text-role-reconnect.util';
+import * as textRoleCss from '../text-role-css.util';
+import * as rteRoleLift from '../rte-role-lift.util';
+import { applyTextContrast } from '../container-text-color.util';
+import {
+  PRODUCTION_BUTTON_DEFAULTS,
+  PRODUCTION_HEADER_BUTTON_STYLE,
+  PRODUCTION_PROFILE_DEFAULTS,
+  productionTypography,
+} from '../../__fixtures__/production-text-style-resolver.fixture';
+
+const modelWithContent = (content: Record<string, unknown>): BrandPageModel =>
+  ({ pages: [{ contents: [content] }] }) as unknown as BrandPageModel;
+
+// A model carrying the role options + button/palette styles that the colour bake reads.
+const modelWith = (
+  content: Record<string, unknown>,
+  options: TextStyleOptions,
+): BrandPageModel =>
+  ({
+    pages: [{ contents: [content] }],
+    styles: {
+      textStyles: { textStyleOptions: options },
+      buttonStyles: { style: {} },
+      colors: [],
+    },
+    brandPageType: 'default',
+  }) as unknown as BrandPageModel;
+
+// Read/write a role's colour through the retired-from-type property.
+const roleColorOf = (style: unknown): string | undefined =>
+  (style as Record<string, unknown>).color as string | undefined;
+const setRoleColor = (style: unknown, color: string): void => {
+  (style as Record<string, unknown>).color = color;
+};
+
+// The colour on the first text run's textStyle mark (after the RTE bake replaces the doc).
+const runMarkColor = (doc: unknown): string | undefined => {
+  const run = (doc as { content: { content: { marks?: unknown[] }[] }[] })
+    .content[0].content[0];
+
+  return (run.marks as { type: string; attrs?: { color?: string } }[])?.find(
+    (mark) => mark.type === 'textStyle',
+  )?.attrs?.color;
+};
+
+const roleType = (style: unknown): string | undefined =>
+  (style as { textStyleType?: string }).textStyleType;
+
+// A minimal Tiptap doc: one paragraph of text runs, each with a textStyle mark.
+const docOf = (runs: { text: string; attrs?: Record<string, unknown> }[]) => ({
+  type: 'doc',
+  content: [
+    {
+      type: 'paragraph',
+      content: runs.map((r) => ({
+        type: 'text',
+        text: r.text,
+        marks: r.attrs ? [{ type: 'textStyle', attrs: { ...r.attrs } }] : [],
+      })),
+    },
+  ],
+});
+
+const attrsOf = (doc: ReturnType<typeof docOf>, i: number) =>
+  (doc.content[0].content[i].marks[0] as { attrs?: Record<string, unknown> })
+    ?.attrs;
+
+// The seven typography properties a field renders with. An unset one renders its inherited
+// default; family and size left unset inherit from the page, so they stay undefined here.
+const lookOf = (
+  style: object | undefined,
+  role: object | undefined,
+): Record<string, string | undefined> => {
+  const resolved = resolveTextStyle(
+    style as TextStyleDeclaration | undefined,
+    role,
+  ) as Record<string, string | undefined>;
+
+  return Object.fromEntries(
+    TEXT_STYLE_CASCADE_PROPS.map((prop) => [
+      prop,
+      resolved[prop] || DETACHED_UNSET_EFFECTIVE[prop],
+    ]),
+  );
+};
+
+// Every property the field rendered before renders the same after; one it left to the page
+// (a field on no role) is not compared.
+const expectLookKept = (
+  after: object | undefined,
+  afterRole: object | undefined,
+  before: object | undefined,
+  beforeRole: object | undefined,
+): void => {
+  const look = lookOf(after, afterRole);
+
+  for (const [prop, value] of Object.entries(lookOf(before, beforeRole))) {
+    if (value !== undefined) expect(look[prop], prop).toBe(value);
+  }
+};
+
+const roleStyleOf = (
+  options: TextStyleOptions,
+  type: unknown,
+): TextStyleDeclaration | undefined =>
+  options[type as TextStyleType]?.style as TextStyleDeclaration | undefined;
+
+// A site whose legacy `buttons` role differs from Button text in family, size and line height.
+const withCustomButtons = (): TextStyleOptions => {
+  const options = TextStyles.GetDefaultTextStyle().textStyleOptions;
+
+  options.buttons.style.fontFamily = 'Oswald';
+  options.buttons.style.fontSize = '1.25em';
+
+  return options;
+};
+
+const siteWith = (
+  extra: Record<string, unknown>,
+  options: TextStyleOptions,
+  // A distinct site font (default 'lato') lets a test tell a real vote-driven winner apart from
+  // A2's fallback — both would otherwise read 'Lato' and hide a fallback-vs-vote bug (B1).
+  siteFontKey = 'lato',
+): BrandPageModel =>
+  ({
+    pages: [],
+    styles: {
+      textStyles: { textFontFamily: siteFontKey, textStyleOptions: options },
+      buttonStyles: { style: {} },
+      colors: [],
+    },
+    brandPageType: BRAND_PAGE_TYPES.brandSite,
+    ...extra,
+  }) as unknown as BrandPageModel;
+
+const runMigration22 = async (model: BrandPageModel): Promise<BrandPageModel> =>
+  (
+    await migration22(
+      { brandPageModel: model } as MigrationData,
+      {} as MigrationOptions,
+    )
+  ).brandPageModel;
+
+describe('migration-22 · computeLegacyTargets (D1 — per-site legacy → nearest tier)', () => {
+  it('pins paragraphs → paragraph1 and buttons → button', () => {
+    const options = TextStyles.GetDefaultTextStyle().textStyleOptions;
+
+    const targets = computeLegacyTargets(options);
+
+    expect(targets.paragraphs).toBe('paragraph1');
+    expect(targets.buttons).toBe('button');
+  });
+
+  it('maps titles/headings to the heading tier nearest their OLD size', () => {
+    const options = TextStyles.GetDefaultTextStyle().textStyleOptions;
+
+    options.titles.style.fontSize = '2.25em'; // nearest H4 (2.1875em)
+    options.headings.style.fontSize = '1.5em'; // nearest H5 (1.4375em)
+
+    const targets = computeLegacyTargets(options);
+
+    expect(targets.titles).toBe('heading4');
+    expect(targets.headings).toBe('heading5');
+  });
+
+  it('keeps titles and headings on DISTINCT tiers when their sizes collide', () => {
+    const options = TextStyles.GetDefaultTextStyle().textStyleOptions;
+
+    options.titles.style.fontSize = '2em';
+    options.headings.style.fontSize = '2em';
+
+    const targets = computeLegacyTargets(options);
+
+    expect(targets.titles).toBe('heading4'); // titles keeps the shared nearest
+    expect(targets.headings).not.toBe(targets.titles); // headings nudged off it
+  });
+
+  it('keeps headings distinct from titles even when headings has no parseable size', () => {
+    const options = TextStyles.GetDefaultTextStyle().textStyleOptions;
+
+    options.titles.style.fontSize = '2.25em'; // → heading4
+    // no parseable size → the fallback must still exclude titles' tier
+    delete (options.headings.style as unknown as Record<string, unknown>)
+      .fontSize;
+
+    const targets = computeLegacyTargets(options);
+
+    expect(targets.titles).toBe('heading4');
+    expect(targets.headings).not.toBe('heading4');
+  });
+});
+
+describe('migration-22 · seedRoleColours (A — colour only; roles keep §4 typography)', () => {
+  it('copies the paragraphs colour to paragraph1 (D3 base coat)', () => {
+    const options = TextStyles.GetDefaultTextStyle().textStyleOptions;
+
+    setRoleColor(options.paragraphs.style, 'var(--logo-text-color)');
+
+    seedRoleColours(options, computeLegacyTargets(options));
+
+    expect(roleColorOf(options.paragraph1.style)).toBe(
+      'var(--logo-text-color)',
+    );
+  });
+
+  it('copies each old role colour onto its target tier', () => {
+    const options = TextStyles.GetDefaultTextStyle().textStyleOptions;
+
+    options.titles.style.fontSize = '2.25em'; // → heading4
+    setRoleColor(options.titles.style, '#111111');
+    setRoleColor(options.buttons.style, '#222222');
+
+    const targets = computeLegacyTargets(options);
+
+    seedRoleColours(options, targets);
+
+    expect(roleColorOf(options[targets.titles].style)).toBe('#111111');
+    expect(roleColorOf(options.button.style)).toBe('#222222');
+  });
+
+  it('leaves role TYPOGRAPHY at the §4 defaults (the reported bug)', () => {
+    const options = TextStyles.GetDefaultTextStyle().textStyleOptions;
+
+    // a site that customised its legacy Titles size must NOT push it onto the role
+    options.titles.style.fontSize = '2.25em';
+    setRoleColor(options.titles.style, '#111111');
+
+    seedRoleColours(options, computeLegacyTargets(options));
+
+    expect(options.heading1.style.fontSize).toBe('6.875em'); // §4 default, untouched
+    expect(options.heading4.style.fontSize).toBe('2.1875em'); // §4 default, untouched
+  });
+
+  it('no-ops a legacy role that carries no colour', () => {
+    const options = TextStyles.GetDefaultTextStyle().textStyleOptions;
+
+    delete (options.paragraphs.style as unknown as Record<string, unknown>)
+      .color;
+    const before = roleColorOf(options.paragraph1.style);
+
+    seedRoleColours(options, computeLegacyTargets(options));
+
+    expect(roleColorOf(options.paragraph1.style)).toBe(before);
+  });
+});
+
+describe('migration-22 · reconnectContentRoles (D1/D5 — nearest tier + size override)', () => {
+  const withRoles = () => TextStyles.GetDefaultTextStyle().textStyleOptions;
+
+  it('relinks legacy blocks to their target tier, keeping the old role size production drew over the block’s own (D1)', () => {
+    const options = withRoles();
+    const targets = computeLegacyTargets(options);
+    const titlesSize = options.titles.style.fontSize;
+    const content = {
+      titleStyle: {
+        textStyleType: 'titles',
+        fontSize: '3.5em',
+      } as Record<string, unknown>,
+      descriptionStyle: { textStyleType: 'paragraphs' },
+      buttonTextStyle: { textStyleType: 'buttons' },
+    };
+    const model = modelWithContent(content);
+
+    reconnectContentRoles(model, targets, options);
+
+    expect(content.titleStyle.textStyleType).toBe(targets.titles);
+    expect(content.descriptionStyle.textStyleType).toBe('paragraph1');
+    expect(content.buttonTextStyle.textStyleType).toBe('button');
+    // production drew the titles size, not the block's 3.5em; unset draws the tier's own
+    expect(
+      content.titleStyle.fontSize ?? options[targets.titles].style.fontSize,
+    ).toBe(titlesSize);
+  });
+
+  it('pins the old role typography onto a non-RTE block that inherited it (honour the render)', () => {
+    const options = withRoles();
+
+    options.paragraphs.style.fontSize = '1em';
+    options.paragraphs.style.lineHeight = '1.6';
+    const targets = computeLegacyTargets(options);
+    // a non-RTE block linked to paragraphs with no own size — used to inherit from the role
+    const content = { descriptionStyle: { textStyleType: 'paragraphs' } };
+    const model = modelWithContent(content);
+
+    reconnectContentRoles(model, targets, options);
+
+    const style = content.descriptionStyle as Record<string, unknown>;
+
+    expect(style.textStyleType).toBe('paragraph1');
+    expect(style.fontSize).toBe('1em'); // pinned from the old role → override
+    expect(style.lineHeight).toBe('1.6');
+  });
+
+  it('preserves an inherited size on a legacy RTE field as a run literal, not the new tier default', () => {
+    const options = withRoles();
+
+    options.titles.style.fontSize = '2.25em'; // → heading4 (whose §4 default is 2.1875em)
+    const targets = computeLegacyTargets(options);
+    // a legacy RTE title whose size was role-inherited: a bare run (no fontSize mark) and no
+    // fontSize on the style object.
+    const content = {
+      type: 'mailing-list',
+      title: docOf([{ text: 'Hi' }]),
+      titleStyle: { textStyleType: 'titles' },
+    };
+    const model = modelWithContent(content);
+
+    reconnectContentRoles(model, targets, options); // materialises styleObj.fontSize = 2.25em
+    stripLiftContentRte(model, options); // C bakes it onto the bare run as a literal
+
+    expect(content.titleStyle.textStyleType).toBe('heading4');
+    // the run renders 2.25em (old role size), NOT heading4's §4 2.1875em nor a role var
+    expect(attrsOf(content.title, 0)?.fontSize).toBe('2.25em');
+  });
+
+  it('pins a not-bold legacy RTE title to normal so its bold heading tier can’t bold it (C3)', () => {
+    const options = withRoles();
+    const targets = computeLegacyTargets(options);
+    // a legacy RTE title with a bare run (no bold mark) linked to `titles` — which had no weight, so
+    // it rendered normal. It reconnects to a heading tier whose §4 default is bold.
+    const content = {
+      type: 'mailing-list',
+      title: docOf([{ text: 'Hi' }]),
+      titleStyle: { textStyleType: 'titles' },
+    };
+    const model = modelWithContent(content);
+
+    reconnectContentRoles(model, targets, options); // materialises styleObj.fontWeight = normal
+    stripLiftContentRte(model, options); // C3 bakes normal onto the bare run
+
+    expect(roleType(content.titleStyle)).toMatch(/^heading/);
+    expect(attrsOf(content.title, 0)?.fontWeight).toBe('normal'); // NOT the tier's bold
+  });
+
+  it('reconnects a detached big block to a heading tier, keeping its props (D5)', () => {
+    const options = withRoles();
+    const content = {
+      titleStyle: {
+        textStyleType: undefined,
+        fontSize: '2em',
+        fontWeight: '700',
+      },
+    };
+    const model = modelWithContent(content);
+
+    reconnectContentRoles(model, computeLegacyTargets(options), options);
+
+    expect(content.titleStyle.textStyleType).toBe('heading4'); // nearest heading to 2em (H4 = 2.1875em)
+    expect(content.titleStyle.fontWeight).toBe('700'); // kept as override
+  });
+
+  it('pins a detached block’s unset weight and line height so a heading tier can’t bold it', () => {
+    const options = withRoles();
+    const content = {
+      // a normal-weight block resized big, then detached — no own weight/style/decoration
+      titleStyle: { textStyleType: undefined, fontSize: '2em' },
+    };
+    const model = modelWithContent(content);
+
+    reconnectContentRoles(model, computeLegacyTargets(options), options);
+
+    const style = content.titleStyle as Record<string, unknown>;
+
+    expect(style.textStyleType).toBe('heading4'); // gets heading identity…
+    expect(style.fontWeight).toBe('normal'); // …but NOT the tier's bold default
+    expect(style.lineHeight).toBe('normal');
+    // style and decoration: the tier leaves them unset, so the neutral draws the same unpinned
+    expect(style.fontStyle).toBeUndefined();
+    expect(style.textDecoration).toBeUndefined();
+  });
+
+  it('reconnects a detached small block to a paragraph tier (D5)', () => {
+    const options = withRoles();
+    const content = { textStyle: { fontSize: '0.75em' } };
+    const model = modelWithContent(content);
+
+    reconnectContentRoles(model, computeLegacyTargets(options), options);
+
+    expect(roleType(content.textStyle)).toBe('paragraph3');
+  });
+
+  it('reconnects a detached block with no size to paragraph1', () => {
+    const options = withRoles();
+    const content = { textStyle: { textAlign: 'center' } };
+    const model = modelWithContent(content);
+
+    reconnectContentRoles(model, computeLegacyTargets(options), options);
+
+    expect(roleType(content.textStyle)).toBe('paragraph1');
+  });
+
+  it.each([
+    [
+      'mailing-list',
+      { fontSize: '1em', fontWeight: 'bold' },
+      { fontSize: '1em', fontWeight: 'bold' },
+    ],
+    ['support-me', {}, { fontWeight: 'bold' }],
+  ] as const)(
+    'materialises the old no-role %s title defaults before reconnecting it',
+    (type, storedStyle, expected) => {
+      const options = withRoles();
+      const content = { type, titleStyle: { ...storedStyle } };
+
+      reconnectContentRoles(
+        modelWithContent(content),
+        computeLegacyTargets(options),
+        options,
+      );
+
+      expect(content.titleStyle).toMatchObject({
+        textStyleType: type === 'mailing-list' ? 'paragraph2' : 'paragraph1',
+        ...expected,
+      });
+    },
+  );
+
+  it('keeps an explicit no-role title weight over the old component default', () => {
+    const options = withRoles();
+    const content = {
+      type: 'mailing-list',
+      titleStyle: { fontWeight: 'normal' },
+    };
+
+    reconnectContentRoles(
+      modelWithContent(content),
+      computeLegacyTargets(options),
+      options,
+    );
+
+    const migrated = content.titleStyle as Record<string, string>;
+
+    expect(migrated.textStyleType).toBe('paragraph2');
+    expect(migrated.fontWeight).toBe('normal');
+  });
+
+  it('does not apply the old component default when a legacy role determined the title look', () => {
+    const options = withRoles();
+
+    options.titles.style.fontWeight = 'normal';
+    const content = {
+      type: 'mailing-list',
+      titleStyle: { textStyleType: 'titles' },
+    };
+
+    reconnectContentRoles(
+      modelWithContent(content),
+      computeLegacyTargets(options),
+      options,
+    );
+
+    expect((content.titleStyle as Record<string, unknown>).fontWeight).toBe(
+      'normal',
+    );
+  });
+
+  it('materialises a no-role text block’s legacy textSize and line-height before reconnecting it', () => {
+    const options = withRoles();
+
+    options.paragraph1.style.lineHeight = '1.2';
+    const content = {
+      type: 'text',
+      textSize: { fontSize: '2em' },
+      textStyle: {},
+    };
+
+    reconnectContentRoles(
+      modelWithContent(content),
+      computeLegacyTargets(options),
+      options,
+    );
+
+    expect(content.textStyle).toMatchObject({
+      textStyleType: 'heading4',
+      fontSize: '2em',
+      lineHeight: '1.5',
+    });
+    expect(content).not.toHaveProperty('textSize');
+  });
+
+  it('keeps a text block’s explicit style over its legacy textSize defaults', () => {
+    const options = withRoles();
+
+    options.paragraph1.style.lineHeight = '1.2';
+    const content = {
+      type: 'text',
+      textSize: { fontSize: '2em', lineHeight: '1.4' },
+      textStyle: { fontSize: '1.5em', lineHeight: '1.3' },
+    };
+
+    reconnectContentRoles(
+      modelWithContent(content),
+      computeLegacyTargets(options),
+      options,
+    );
+
+    expect(content.textStyle).toMatchObject({
+      textStyleType: 'heading5',
+      fontSize: '1.5em',
+      lineHeight: '1.3',
+    });
+  });
+
+  it('folds a text block’s legacy alignment and colour into its persisted style', () => {
+    const options = withRoles();
+    const content = {
+      type: 'text',
+      textAlignment: { textAlign: 'left' },
+      textColor: { color: '#123456' },
+      textStyle: { textAlign: 'center' },
+    };
+
+    reconnectContentRoles(
+      modelWithContent(content),
+      computeLegacyTargets(options),
+      options,
+    );
+
+    expect(content.textStyle).toMatchObject({
+      textAlign: 'center',
+      color: '#123456',
+    });
+    expect(content).not.toHaveProperty('textAlignment');
+    expect(content).not.toHaveProperty('textColor');
+  });
+
+  it.each([
+    ['mailing-list', 'paragraph2'],
+    ['support-me', 'paragraph1'],
+  ] as const)(
+    'keeps the old no-role %s title bold through the full migration',
+    async (type, role) => {
+      const options = withRoles();
+      const content = {
+        type,
+        title: docOf([{ text: 'Legacy title' }]),
+        titleStyle: {},
+      };
+      const model = await runMigration22(
+        siteWith({ pages: [{ contents: [content] }] }, options),
+      );
+      const after = model.pages[0].contents[0] as unknown as typeof content;
+
+      expect(roleType(after.titleStyle)).toBe(role);
+      expect(attrsOf(after.title, 0)?.fontWeight).toBe('bold');
+    },
+  );
+
+  it('keeps a no-role text block’s legacy textSize through the full migration', async () => {
+    const options = withRoles();
+    const content = {
+      type: 'text',
+      text: docOf([{ text: 'Legacy text' }]),
+      textSize: { fontSize: '2em' },
+      textStyle: {},
+    };
+    const model = await runMigration22(
+      siteWith({ pages: [{ contents: [content] }] }, options),
+    );
+    const after = model.pages[0].contents[0] as unknown as typeof content;
+
+    expect(roleType(after.textStyle)).toBe('heading4');
+    expect(attrsOf(after.text, 0)).toMatchObject({
+      fontSize: '2em',
+      lineHeight: '1.5',
+    });
+    expect(after).not.toHaveProperty('textSize');
+  });
+
+  it('skips null items and text items throughout the migration', async () => {
+    const options = withRoles();
+    const model = await runMigration22(
+      siteWith(
+        {
+          pages: [
+            {
+              contents: [
+                { type: 'images-section', items: [null] },
+                { type: 'text', textItems: [null], textStyle: {} },
+              ],
+            },
+          ],
+        },
+        options,
+      ),
+    );
+
+    expect(model.pages[0].contents).toHaveLength(2);
+  });
+
+  it.each(['none', 'garbage'])(
+    "reconnects a '%s' role by its size instead of leaving it as if canonical (R14)",
+    (type) => {
+      const options = withRoles();
+      const content = {
+        titleStyle: { textStyleType: type, fontSize: '2.5em' },
+        textStyle: { textStyleType: type, fontSize: '0.875em' },
+        descriptionStyle: { textStyleType: type },
+      };
+
+      reconnectContentRoles(
+        modelWithContent(content),
+        computeLegacyTargets(options),
+        options,
+      );
+
+      expect(roleType(content.titleStyle)).toBe('heading4');
+      expect(roleType(content.textStyle)).toBe('paragraph3');
+      expect(roleType(content.descriptionStyle)).toBe('paragraph1');
+      // the heading tier gives identity, not its bold default
+      expect((content.titleStyle as Record<string, unknown>).fontWeight).toBe(
+        'normal',
+      );
+    },
+  );
+
+  it('leaves an already-canonical link untouched', () => {
+    const options = withRoles();
+    const content = { titleStyle: { textStyleType: 'heading2' } };
+    const model = modelWithContent(content);
+
+    reconnectContentRoles(model, computeLegacyTargets(options), options);
+
+    expect(content.titleStyle.textStyleType).toBe('heading2');
+  });
+
+  it('reconnects textItems[].textStyle', () => {
+    const options = withRoles();
+    const content = {
+      textItems: [{ textStyle: { textStyleType: 'paragraphs' } }],
+    };
+    const model = modelWithContent(content);
+
+    reconnectContentRoles(model, computeLegacyTargets(options), options);
+
+    expect(content.textItems[0].textStyle.textStyleType).toBe('paragraph1');
+  });
+
+  it('reconnects the footer copyright role (legacy → canonical), outside page.contents', () => {
+    const options = withRoles();
+    const model = modelWithContent({ type: 'shapes-section' });
+
+    (model as unknown as Record<string, unknown>).pageFooterDesktop = {
+      copyrightStyle: { textStyleType: 'paragraphs' },
+    };
+
+    reconnectContentRoles(model, computeLegacyTargets(options), options);
+
+    expect(
+      (
+        (model as unknown as { pageFooterDesktop: { copyrightStyle: unknown } })
+          .pageFooterDesktop.copyrightStyle as { textStyleType?: string }
+      ).textStyleType,
+    ).toBe('paragraph1');
+  });
+});
+
+// The look through the real view model (not `resolveTextStyle`), so renderer defaults are modelled:
+// the button view model's 1.4 line height, the profile's sizes. An unset family draws the site font
+// (Lato here), an unset size its parent's (1em), the rest their inherited defaults.
+//
+// BP-5969 (R1): page data now carries only a field's own typography — the role's values are a
+// CSS var reference resolved at render, not merged in here. So this helper resolves the same way
+// the renderer does (`roleTypographyStyle`): own, else the linked role's own definition (when
+// `options` and a canonical `textStyleType` are given), else the no-role/unset default.
+const drawn = (
+  style: (object & { textStyleType?: string }) | undefined,
+  options?: TextStyleOptions,
+): Record<string, string | undefined> => {
+  const record = (style ?? {}) as Record<string, string | undefined>;
+  const role =
+    options && record.textStyleType
+      ? (
+          options as unknown as Record<
+            string,
+            { style?: Record<string, string | undefined> }
+          >
+        )[record.textStyleType]?.style
+      : undefined;
+  const unset: Record<string, string | undefined> = {
+    ...DETACHED_UNSET_EFFECTIVE,
+    fontFamily: 'Lato',
+    fontSize: '1em',
+  };
+
+  return Object.fromEntries(
+    TEXT_STYLE_CASCADE_PROPS.map((prop) => [
+      prop,
+      record[prop] || role?.[prop] || unset[prop],
+    ]),
+  );
+};
+
+const pageStylesFor = (options: TextStyleOptions): PageStyles => {
+  const styles = new PageStyles();
+
+  styles.textStyles.textStyleOptions = options;
+
+  return styles;
+};
+
+const drawnHeaderButton = (
+  headerButton: HeaderButton,
+  options: TextStyleOptions,
+) =>
+  drawn(
+    mapToPageHeaderViewModel(
+      new PageHeaderDesktop({ headerButton }),
+      pageStylesFor(options),
+      [],
+    ).headerButtonViewModel?.titleStyle,
+    options,
+  );
+
+const drawnContent = (
+  content: unknown,
+  options: TextStyleOptions,
+  pick: (viewModel: Record<string, any>) => object | undefined,
+) =>
+  drawn(
+    pick(
+      mapToViewModel(
+        pageStylesFor(options),
+        BRAND_PAGE_TYPES.brandSite,
+        {},
+      )(JSON.parse(JSON.stringify(content)) as Content) as Record<string, any>,
+    ),
+    options,
+  );
+
+describe('migration-22 · header button (R7)', () => {
+  // Production drew a header button on `buttons` with only the role's typography, so its 1.5 line
+  // height, not the view model's 1.4, which only a button on no role drew.
+  it.each([
+    ['no text style', undefined, '1.5'],
+    ['buttons', { textStyleType: 'buttons' }, '1.5'],
+    ['no role', { fontSize: '1.25em', fontWeight: 'bold' }, '1.4'],
+  ] as const)(
+    'moves a header button on %s to button on both viewports, look kept as production drew it',
+    async (_label, buttonTextStyle, lineHeight) => {
+      const options = withCustomButtons();
+      const headerButton = (): HeaderButton => ({
+        isVisible: true,
+        text: 'Contact us',
+        buttonLinkType: 'url',
+        ...(buttonTextStyle
+          ? { buttonTextStyle: { ...buttonTextStyle } as TextStyleDeclaration }
+          : {}),
+      });
+      const before = drawn(
+        productionTypography(
+          (buttonTextStyle ??
+            PRODUCTION_HEADER_BUTTON_STYLE) as TextStyleDeclaration,
+          options,
+          PRODUCTION_BUTTON_DEFAULTS,
+        ),
+      );
+
+      const model = await runMigration22(
+        siteWith(
+          {
+            pageHeaderDesktop: { headerButton: headerButton() },
+            pageHeaderMobile: { headerButton: headerButton() },
+          },
+          options,
+        ),
+      );
+
+      for (const viewport of [
+        model.pageHeaderDesktop,
+        model.pageHeaderMobile,
+      ]) {
+        const after = viewport.headerButton!;
+
+        expect(after.buttonTextStyle?.textStyleType).toBe('button');
+        expect(drawnHeaderButton(after, options)).toEqual(before);
+        expect(drawnHeaderButton(after, options).lineHeight).toBe(lineHeight);
+      }
+    },
+  );
+});
+
+// Every button element starts on Button text; what makes it different stays an override, and the
+// look is unchanged through the view model (James Joung, 2026-09-28).
+describe('migration-22 · section button (R14, Q2)', () => {
+  // Factories translate their labels, so the table builds each content after the locale is set.
+  const withButtonStyle =
+    (create: () => unknown, key: string, style: Record<string, unknown>) =>
+    (): Record<string, unknown> => ({
+      ...(create() as Record<string, unknown>),
+      [key]: { ...style },
+    });
+
+  beforeAll(async () => {
+    await setLocaleAsync('en-US');
+  });
+
+  it.each([
+    [
+      'a banner button on buttons',
+      withButtonStyle(
+        () => createInitialBannerSectionContent(),
+        'buttonTextStyle',
+        { textStyleType: 'buttons', textAlign: 'center' },
+      ),
+      'buttonTextStyle',
+      (vm: Record<string, any>) => vm.buttonViewModel?.titleStyle,
+      PRODUCTION_BUTTON_DEFAULTS,
+    ],
+    [
+      'a banner button on no role',
+      withButtonStyle(
+        () => createInitialBannerSectionContent(),
+        'buttonTextStyle',
+        { fontSize: '1em', textAlign: 'center' },
+      ),
+      'buttonTextStyle',
+      (vm: Record<string, any>) => vm.buttonViewModel?.titleStyle,
+      PRODUCTION_BUTTON_DEFAULTS,
+    ],
+    [
+      'a booking button on buttons',
+      withButtonStyle(
+        () => createInitialBookingSectionContent(),
+        'buttonTextStyle',
+        { textStyleType: 'buttons' },
+      ),
+      'buttonTextStyle',
+      (vm: Record<string, any>) => vm.buttonViewModel?.titleStyle,
+      PRODUCTION_BUTTON_DEFAULTS,
+    ],
+    [
+      'a link button on buttons',
+      withButtonStyle(
+        createInitialButtonContent('general-link', ''),
+        'titleStyle',
+        { textStyleType: 'buttons', textAlign: 'center' },
+      ),
+      'titleStyle',
+      (vm: Record<string, any>) => vm.titleStyle,
+      PRODUCTION_BUTTON_DEFAULTS,
+    ],
+    [
+      'a banner button on no role at line height 1.2 (equal to Button text, which the view model would draw at 1.4)',
+      withButtonStyle(
+        () => createInitialBannerSectionContent(),
+        'buttonTextStyle',
+        { lineHeight: '1.2', textAlign: 'center' },
+      ),
+      'buttonTextStyle',
+      (vm: Record<string, any>) => vm.buttonViewModel?.titleStyle,
+      PRODUCTION_BUTTON_DEFAULTS,
+    ],
+    [
+      'a mailing list button on no role',
+      withButtonStyle(
+        () => createInitialMailingListContent(),
+        'buttonTextStyle',
+        { fontSize: '1.25em', textAlign: 'center' },
+      ),
+      'buttonTextStyle',
+      (vm: Record<string, any>) => vm.buttonTextStyle,
+      {},
+    ],
+    [
+      'a banner button on buttons carrying typography production ignored',
+      withButtonStyle(
+        () => createInitialBannerSectionContent(),
+        'buttonTextStyle',
+        {
+          textStyleType: 'buttons',
+          fontSize: '2em',
+          fontWeight: '300',
+          lineHeight: '1.1',
+          textAlign: 'center',
+        },
+      ),
+      'buttonTextStyle',
+      (vm: Record<string, any>) => vm.buttonViewModel?.titleStyle,
+      PRODUCTION_BUTTON_DEFAULTS,
+    ],
+  ] as const)(
+    'moves %s to button, look kept as production drew it',
+    async (_label, createContent, key, pick, defaults) => {
+      const options = withCustomButtons();
+      const content = createContent();
+      const before = drawn(
+        productionTypography(
+          (content as Record<string, TextStyleDeclaration>)[key],
+          options,
+          defaults,
+        ),
+      );
+
+      const model = await runMigration22(
+        siteWith(
+          { pages: [{ contents: [JSON.parse(JSON.stringify(content))] }] },
+          options,
+        ),
+      );
+      const after = model.pages[0].contents[0] as unknown as Record<
+        string,
+        TextStyleDeclaration
+      >;
+
+      expect(after[key].textStyleType).toBe('button');
+      expect(drawnContent(after, options, pick)).toEqual(before);
+    },
+  );
+});
+
+// Production drew a profile field on a role with only the role's typography; on no role, the view
+// model's defaults for an unset size and line height (1em / 1.5 title and description, 1.5em / 1.4
+// name). The upgrade keeps whichever it drew.
+describe('migration-22 · profile look (R14)', () => {
+  beforeAll(async () => {
+    await setLocaleAsync('en-US');
+  });
+
+  it.each([
+    ['titleStyle', { textStyleType: 'titles', textAlign: 'center' }],
+    ['descriptionStyle', { textStyleType: 'paragraphs', textAlign: 'center' }],
+    // its own size and line height never showed over the role
+    [
+      'nameStyle',
+      { textStyleType: 'headings', fontSize: '3em', lineHeight: '1' },
+    ],
+    // 0.875em lands on Paragraph 3 (equal), which the view model would draw at its own 1em
+    ['descriptionStyle', { fontSize: '0.875em', textAlign: 'center' }],
+    ['nameStyle', { textAlign: 'center' }],
+  ] as const)(
+    'keeps a profile %s look as production drew it',
+    async (key, style) => {
+      const options = TextStyles.GetDefaultTextStyle().textStyleOptions;
+      const content = {
+        ...createInitialProfileContent(),
+        [key]: { ...style },
+      };
+      const pick = (vm: Record<string, any>) => vm[key];
+      const before = drawn(
+        productionTypography(
+          style as TextStyleDeclaration,
+          options,
+          PRODUCTION_PROFILE_DEFAULTS[key],
+        ),
+      );
+
+      const model = await runMigration22(
+        siteWith(
+          { pages: [{ contents: [JSON.parse(JSON.stringify(content))] }] },
+          options,
+        ),
+      );
+
+      expect(drawnContent(model.pages[0].contents[0], options, pick)).toEqual(
+        before,
+      );
+    },
+  );
+});
+
+describe('migration-22 · navigation (R11)', () => {
+  const NAV_COLOUR = 'var(--palette-1)';
+
+  it.each([
+    [
+      'tab style on no role',
+      'tab',
+      { fontSize: '1em', fontFamily: 'Lato', textAlign: 'left' },
+      'paragraph1',
+    ],
+    ['tab style on buttons', 'tab', { textStyleType: 'buttons' }, 'paragraph1'],
+    [
+      'hamburger style on buttons',
+      'hamburger',
+      { textStyleType: 'buttons' },
+      'button',
+    ],
+    [
+      'hamburger style on no role',
+      'hamburger',
+      { fontSize: '1em', textAlign: 'left' },
+      'button',
+    ],
+  ] as const)(
+    'moves the navigation %s to %s on both viewports, look and colour kept',
+    async (_label, place, style, expected) => {
+      const options = withCustomButtons();
+      const before = { ...style, color: NAV_COLOUR } as TextStyleDeclaration;
+      const beforeRole = roleStyleOf(options, before.textStyleType);
+      const afterRole = { ...roleStyleOf(options, expected) };
+      const header = () => ({
+        navigation:
+          place === 'tab'
+            ? { defaultButtonStyle: { ...before } }
+            : { hamburgerMenuStyle: { defaultButtonStyle: { ...before } } },
+      });
+
+      const model = await runMigration22(
+        siteWith(
+          { pageHeaderDesktop: header(), pageHeaderMobile: header() },
+          options,
+        ),
+      );
+
+      for (const viewport of [
+        model.pageHeaderDesktop,
+        model.pageHeaderMobile,
+      ]) {
+        const after = (
+          place === 'tab'
+            ? viewport.navigation.defaultButtonStyle
+            : viewport.navigation.hamburgerMenuStyle.defaultButtonStyle
+        ) as TextStyleDeclaration;
+
+        expect(after.textStyleType).toBe(expected);
+        expect(after.color).toBe(NAV_COLOUR);
+        expectLookKept(after, afterRole, before, beforeRole);
+      }
+    },
+  );
+});
+
+// A nav link resolves `element || #000000` once linked (`getTextStyleByContentTextStyle`). Before,
+// one with no colour of its own drew its legacy role's colour (the production resolver), or on no
+// role inherited its parent's: a tab the header's colour, else the page base coat (the paragraphs
+// colour); the hamburger menu, beside the header under the page root (`Page.vue`), the base coat.
+describe('migration-22 · navigation colour (R11)', () => {
+  const PARAGRAPHS = 'var(--palette-0)';
+  const BUTTONS = 'var(--palette-2)';
+  const HEADER = '#445566';
+
+  const drawnNavColours = (
+    navigation: unknown,
+    options: TextStyleOptions,
+  ): [unknown, unknown] => {
+    const vm = mapToPageHeaderViewModel(
+      new PageHeaderDesktop({
+        // a header with no display style is rebuilt with a default navigation
+        displayStyle: HEADER_DISPLAY.DESKTOP_TAB_5,
+        navigation: new NavigationDesktop(navigation as never),
+      }),
+      pageStylesFor(options),
+      [],
+    );
+
+    return [
+      vm.navigation.defaultButtonStyle.color,
+      vm.navigation.hamburgerMenuStyle.defaultButtonStyle.color,
+    ];
+  };
+
+  it.each([
+    [
+      'on no role, under a coloured header',
+      { fontSize: '1em' },
+      HEADER,
+      [HEADER, PARAGRAPHS],
+    ],
+    [
+      'on no role, with no header colour',
+      { fontSize: '1em' },
+      undefined,
+      [PARAGRAPHS, PARAGRAPHS],
+    ],
+    ['on buttons', { textStyleType: 'buttons' }, HEADER, [BUTTONS, BUTTONS]],
+  ] as const)(
+    'keeps the colour a navigation link %s drew with no colour of its own',
+    async (_label, style, headerColour, expected) => {
+      const options = TextStyles.GetDefaultTextStyle().textStyleOptions;
+
+      (options.paragraphs.style as unknown as Record<string, unknown>).color =
+        PARAGRAPHS;
+      (options.buttons.style as unknown as Record<string, unknown>).color =
+        BUTTONS;
+
+      const header = () => ({
+        ...(headerColour ? { style: { color: headerColour } } : {}),
+        navigation: {
+          defaultButtonStyle: { ...style },
+          hamburgerMenuStyle: { defaultButtonStyle: { ...style } },
+        },
+      });
+
+      const model = await runMigration22(
+        siteWith(
+          { pageHeaderDesktop: header(), pageHeaderMobile: header() },
+          options,
+        ),
+      );
+
+      expect(
+        drawnNavColours(model.pageHeaderDesktop.navigation, options),
+      ).toEqual(expected);
+    },
+  );
+});
+
+describe('migration-22 · save contact (R15)', () => {
+  it('moves a brand.contact save contact button to button, keeping the buttons look and its settings', async () => {
+    const options = withCustomButtons();
+    // The widget drew the retired role's style directly (`SaveContactWidget.vue`, before this change).
+    const before = drawn(options.buttons.style);
+
+    const model = await runMigration22(
+      siteWith(
+        {
+          brandPageType: BRAND_PAGE_TYPES.brandContact,
+          saveContactSettings: { isSavingEnabled: false, hideBranding: true },
+        },
+        options,
+      ),
+    );
+
+    const after = model.saveContactSettings?.buttonTextStyle;
+
+    // Button text plus only the values that draw differently from it: weight `normal` equals the
+    // role, and style, decoration and spacing are neutrals Button text leaves unset, so a Button text
+    // edit to those still repaints it (R15). `isSavingEnabled: false` means the widget never renders
+    // (S4, Q12b's "nothing to show" rule), so it casts no A2 vote; Button text stays on Lato and
+    // Save Contact's own drawn font (Oswald, the old `buttons` role's) survives as an override.
+    expect(after).toEqual({
+      textStyleType: 'button',
+      fontFamily: 'Oswald',
+      fontSize: '1.25em',
+      lineHeight: '1.5',
+    });
+    expect(
+      drawn(
+        resolveSaveContactTitleStyle(after, pageStylesFor(options).textStyles),
+      ),
+    ).toEqual(before);
+    expect(model.saveContactSettings).toMatchObject({
+      isSavingEnabled: false,
+      hideBranding: true,
+    });
+  });
+
+  it('creates the save contact settings with their defaults on a brand.contact site that has none', async () => {
+    const model = await runMigration22(
+      siteWith(
+        { brandPageType: BRAND_PAGE_TYPES.brandContact },
+        withCustomButtons(),
+      ),
+    );
+
+    expect(model.saveContactSettings).toMatchObject({
+      isSavingEnabled: true,
+      hideBranding: false,
+      buttonTextStyle: { textStyleType: 'button' },
+    });
+  });
+
+  it.each([BRAND_PAGE_TYPES.brandSite, BRAND_PAGE_TYPES.default])(
+    'adds no save contact button style on a %s site',
+    async (brandPageType) => {
+      const withSettings = await runMigration22(
+        siteWith(
+          {
+            brandPageType,
+            saveContactSettings: { isSavingEnabled: true, hideBranding: false },
+          },
+          withCustomButtons(),
+        ),
+      );
+      const withoutSettings = await runMigration22(
+        siteWith({ brandPageType }, withCustomButtons()),
+      );
+
+      expect(withSettings.saveContactSettings).toEqual({
+        isSavingEnabled: true,
+        hideBranding: false,
+      });
+      expect(withoutSettings.saveContactSettings).toBeUndefined();
+    },
+  );
+});
+
+describe('migration-22 · role fonts on upgrade (R16)', () => {
+  const HEADING_ROLES = [
+    'heading1',
+    'heading2',
+    'heading3',
+    'heading4',
+    'heading5',
+    'heading6',
+  ] as const;
+  const PARAGRAPH_ROLES = ['paragraph1', 'paragraph2', 'paragraph3'] as const;
+
+  const fontsOf = (options: TextStyleOptions, roles: readonly string[]) =>
+    roles.map((role) => options[role as TextStyleType].style.fontFamily);
+
+  const banner = (
+    overrides: Record<string, unknown> = {},
+  ): Record<string, unknown> => ({
+    type: 'banner-section',
+    title: 'Banner title',
+    description: 'Banner description',
+    titleStyle: { textStyleType: 'titles' },
+    descriptionStyle: { textStyleType: 'paragraphs' },
+    buttonText: false,
+    buttonTextStyle: { textStyleType: 'buttons' },
+    ...overrides,
+  });
+
+  const imagesSection = (
+    overrides: Record<string, unknown> = {},
+  ): Record<string, unknown> => ({
+    type: 'images-section',
+    title: '',
+    description: '',
+    items: [],
+    ...overrides,
+  });
+
+  it('T16.1/T16.2 — gives the heading roles the font most title/heading text shows, and the paragraph roles the font most description/paragraph text shows; the look survives the drop, and an unequal override stays', async () => {
+    const options = TextStyles.GetDefaultTextStyle().textStyleOptions;
+
+    options.titles.style.fontFamily = 'Anton';
+    options.headings.style.fontFamily = 'Anton';
+    options.paragraphs.style.fontFamily = 'Nunito';
+
+    const model = await runMigration22(
+      siteWith(
+        {
+          pages: [
+            {
+              contents: [
+                banner({
+                  titleStyle: { textStyleType: 'titles' },
+                  descriptionStyle: { textStyleType: 'paragraphs' },
+                }),
+                banner({
+                  titleStyle: { textStyleType: 'headings' },
+                  descriptionStyle: { textStyleType: 'paragraphs' },
+                }),
+                // A title stored as an RTE doc, baked in Anton (what the old role drew) — once its
+                // font equals the winning role, the run must relink to the role var, not keep 'Anton'.
+                banner({
+                  title: docOf([
+                    { text: 'Baked title', attrs: { fontFamily: 'Anton' } },
+                  ]),
+                  titleStyle: { textStyleType: 'titles' },
+                }),
+                // An own literal that differs from the winning role (Nunito) survives as an override.
+                banner({
+                  descriptionStyle: { fontFamily: 'Lato', fontSize: '1em' },
+                }),
+                // The 'nunito' KEY spelling counts toward the Nunito vote (`voteFontName`), but is a
+                // different literal from the winning role's NAME ('Nunito'), so it stays an override.
+                banner({
+                  descriptionStyle: { fontFamily: 'nunito', fontSize: '1em' },
+                }),
+              ],
+            },
+          ],
+        },
+        options,
+      ),
+    );
+    const after = model.styles!.textStyles!.textStyleOptions;
+    const contents = model.pages[0].contents as unknown as Record<
+      string,
+      Record<string, unknown>
+    >[];
+
+    expect(fontsOf(after, HEADING_ROLES)).toEqual(Array(6).fill('Anton'));
+    expect(fontsOf(after, PARAGRAPH_ROLES)).toEqual(Array(3).fill('Nunito'));
+
+    // No title keeps a `fontFamily` override once it equals the role that now carries it.
+    expect(contents[0].titleStyle.fontFamily).toBeUndefined();
+    expect(contents[1].titleStyle.fontFamily).toBeUndefined();
+
+    // The baked run relinks to the role ref, since its literal ('Anton') now equals the role.
+    const bakedTitle = contents[2].title as {
+      content: {
+        content: {
+          marks?: { type: string; attrs?: Record<string, unknown> }[];
+        }[];
+      }[];
+    };
+    const bakedMark = bakedTitle.content[0].content[0].marks?.find(
+      (mark) => mark.type === 'textStyle',
+    );
+
+    expect(bakedMark?.attrs?.fontFamily).toBe('var(--role-font-family)');
+
+    // A Lato override differs from the winning role (Nunito) and survives.
+    expect(contents[3].descriptionStyle.fontFamily).toBe('Lato');
+
+    // The 'nunito' key spelling differs (strictly) from the role's name ('Nunito') too.
+    expect(contents[4].descriptionStyle.fontFamily).toBe('nunito');
+  });
+
+  it('T16.3 — a tie goes to the first font found, reading the pages in nav (site) order from the home page, not the stored pages[] order', async () => {
+    const options = TextStyles.GetDefaultTextStyle().textStyleOptions;
+
+    options.paragraphs.style.fontFamily = 'Aleo'; // page "home" (routed second in `pages`)
+    options.headings.style.fontFamily = 'Nunito'; // page "other" (stored first in `pages`)
+
+    const model = await runMigration22(
+      siteWith(
+        {
+          pages: [
+            {
+              id: 'other',
+              contents: [
+                banner({ descriptionStyle: { textStyleType: 'headings' } }),
+              ],
+            },
+            {
+              id: 'home',
+              contents: [
+                banner({ descriptionStyle: { textStyleType: 'paragraphs' } }),
+              ],
+            },
+          ],
+          nav: {
+            routes: [
+              { id: 'r-home', pageId: 'home' },
+              { id: 'r-other', pageId: 'other' },
+            ],
+            orders: [
+              { routeId: 'r-home', subRoutes: [] },
+              { routeId: 'r-other', subRoutes: [] },
+            ],
+          },
+        },
+        options,
+      ),
+    );
+
+    expect(
+      fontsOf(model.styles!.textStyles!.textStyleOptions, PARAGRAPH_ROLES),
+    ).toEqual(Array(3).fill('Aleo'));
+  });
+
+  it('T16.3 — reversing the nav order flips which page is read first', async () => {
+    const options = TextStyles.GetDefaultTextStyle().textStyleOptions;
+
+    options.paragraphs.style.fontFamily = 'Aleo'; // page "home", ranked second below
+    options.headings.style.fontFamily = 'Nunito'; // page "other", ranked first below
+
+    const model = await runMigration22(
+      siteWith(
+        {
+          pages: [
+            {
+              id: 'other',
+              contents: [
+                banner({ descriptionStyle: { textStyleType: 'headings' } }),
+              ],
+            },
+            {
+              id: 'home',
+              contents: [
+                banner({ descriptionStyle: { textStyleType: 'paragraphs' } }),
+              ],
+            },
+          ],
+          nav: {
+            routes: [
+              { id: 'r-home', pageId: 'home' },
+              { id: 'r-other', pageId: 'other' },
+            ],
+            // 'other' ranked first this time — the OPPOSITE of the test above.
+            orders: [
+              { routeId: 'r-other', subRoutes: [] },
+              { routeId: 'r-home', subRoutes: [] },
+            ],
+          },
+        },
+        options,
+      ),
+    );
+
+    expect(
+      fontsOf(model.styles!.textStyles!.textStyleOptions, PARAGRAPH_ROLES),
+    ).toEqual(Array(3).fill('Nunito'));
+  });
+
+  it('T16.3 — a tie WITHIN one page goes to the upper section, top to bottom', async () => {
+    const options = TextStyles.GetDefaultTextStyle().textStyleOptions;
+
+    options.paragraphs.style.fontFamily = 'Aleo'; // the upper section
+    options.headings.style.fontFamily = 'Nunito'; // the lower section
+
+    const model = await runMigration22(
+      siteWith(
+        {
+          pages: [
+            {
+              contents: [
+                banner({ descriptionStyle: { textStyleType: 'paragraphs' } }),
+                banner({ descriptionStyle: { textStyleType: 'headings' } }),
+              ],
+            },
+          ],
+        },
+        options,
+      ),
+    );
+
+    expect(
+      fontsOf(model.styles!.textStyles!.textStyleOptions, PARAGRAPH_ROLES),
+    ).toEqual(Array(3).fill('Aleo'));
+  });
+
+  // Each run's own literal (Aleo, Nunito) votes and the block font (Oswald) does not — proves
+  // per-run voting happens at all. A block-plus-literals implementation also passes this case
+  // (see the tally comment below); the D13 case right after this one is what actually tells
+  // the two apart.
+  it("T16.4 — one vote for each font a doc's runs show", async () => {
+    const options = TextStyles.GetDefaultTextStyle().textStyleOptions;
+
+    const model = await runMigration22(
+      siteWith(
+        {
+          pages: [
+            {
+              contents: [
+                // Every run here carries its own literal — the block font (Oswald) must cast no
+                // vote; a block-font-only implementation would instead read it from both runs.
+                banner({
+                  description: docOf([
+                    { text: 'Aleo run', attrs: { fontFamily: 'Aleo' } },
+                    { text: 'Nunito run', attrs: { fontFamily: 'Nunito' } },
+                  ]),
+                  descriptionStyle: { fontFamily: 'Oswald', fontSize: '1em' },
+                }),
+                banner({
+                  description: 'Plain Nunito description',
+                  descriptionStyle: { fontFamily: 'Nunito', fontSize: '1em' },
+                }),
+                banner({
+                  description: 'Another plain Nunito description',
+                  descriptionStyle: { fontFamily: 'Nunito', fontSize: '1em' },
+                }),
+              ],
+            },
+          ],
+        },
+        options,
+      ),
+    );
+
+    // Nunito 3 (the mixed doc's own Nunito run + the two plain descriptions) vs Aleo 1. This
+    // tally is also produced by a block-plus-literals implementation (it would add Oswald once
+    // more, but Nunito's 3 still wins) — it doesn't by itself rule that rule out; the case below
+    // does.
+    expect(
+      fontsOf(model.styles!.textStyles!.textStyleOptions, PARAGRAPH_ROLES),
+    ).toEqual(Array(3).fill('Nunito'));
+
+    // The Aleo run's literal differs from the winning role and survives; the Nunito run's now
+    // equals it and relinks to the role ref (look kept through `fillRteRunTypography`).
+    const mixedDescription = (
+      model.pages[0].contents as unknown as {
+        description: {
+          content: {
+            content: {
+              marks?: { type: string; attrs?: Record<string, unknown> }[];
+            }[];
+          }[];
+        };
+      }[]
+    )[0].description;
+    const runMark = (i: number) =>
+      mixedDescription.content[0].content[i].marks?.find(
+        (mark) => mark.type === 'textStyle',
+      );
+
+    expect(runMark(0)?.attrs?.fontFamily).toBe('Aleo');
+    expect(runMark(1)?.attrs?.fontFamily).toBe('var(--role-font-family)');
+  });
+
+  it('T16.4 (D13) — a plain-Oswald banner, the mixed Aleo/Nunito doc under a block Oswald, and an Aleo-only doc under a block Nunito together tell the correct per-run rule apart from three wrong ones', async () => {
+    const options = TextStyles.GetDefaultTextStyle().textStyleOptions;
+
+    const model = await runMigration22(
+      siteWith(
+        {
+          pages: [
+            {
+              contents: [
+                banner({
+                  description: 'Plain Oswald description',
+                  descriptionStyle: { fontFamily: 'Oswald', fontSize: '1em' },
+                }),
+                banner({
+                  description: docOf([
+                    { text: 'Aleo run', attrs: { fontFamily: 'Aleo' } },
+                    { text: 'Nunito run', attrs: { fontFamily: 'Nunito' } },
+                  ]),
+                  descriptionStyle: { fontFamily: 'Oswald', fontSize: '1em' },
+                }),
+                banner({
+                  description: docOf([
+                    { text: 'Aleo-only run', attrs: { fontFamily: 'Aleo' } },
+                  ]),
+                  descriptionStyle: { fontFamily: 'Nunito', fontSize: '1em' },
+                }),
+              ],
+            },
+          ],
+        },
+        options,
+      ),
+    );
+
+    // Correct rule: Oswald 1 (the plain banner's block vote) · Aleo 2 (both docs' own Aleo runs,
+    // neither doc's block font votes since every run in each carries its own literal) · Nunito 1
+    // (the mixed doc's own Nunito run) → Aleo wins outright. Three wrong rules all give Oswald
+    // instead, so this is the case that rules each of them out:
+    //   - block-plus-literals (the block font AND every literal run vote): Oswald 2, Aleo 2,
+    //     Nunito 2 — a three-way tie, broken to Oswald as the first font read.
+    //   - block-only (a run's own literal never votes, only the block font): Oswald 2, Nunito 1.
+    //   - no-doc-vote (a doc with any literal run casts no vote at all, not even its runs'):
+    //     Oswald 1, uncontested.
+    expect(
+      fontsOf(model.styles!.textStyles!.textStyleOptions, PARAGRAPH_ROLES),
+    ).toEqual(Array(3).fill('Aleo'));
+  });
+
+  it('T16.4 (B2) — a colour-only run mark (fontFamily: "") votes the block font, not nothing', async () => {
+    const options = TextStyles.GetDefaultTextStyle().textStyleOptions;
+
+    const model = await runMigration22(
+      siteWith(
+        {
+          pages: [
+            {
+              contents: [
+                banner({
+                  descriptionStyle: { fontFamily: 'Oswald', fontSize: '1em' },
+                }),
+                banner({
+                  // A colour-only mark parsed from pasted HTML carries `fontFamily: ''`
+                  // (FontFamily.ts) — it must vote the block font (Nunito), not cast no vote.
+                  description: docOf([
+                    {
+                      text: 'Coloured run',
+                      attrs: { color: '#111111', fontFamily: '' },
+                    },
+                  ]),
+                  descriptionStyle: { fontFamily: 'Nunito', fontSize: '1em' },
+                }),
+                banner({
+                  descriptionStyle: { fontFamily: 'Nunito', fontSize: '1em' },
+                }),
+              ],
+            },
+          ],
+        },
+        options,
+      ),
+    );
+
+    // Nunito 2 (the coloured run's block font + the plain description) beats Oswald 1 — red
+    // without the fix: the coloured run casts no vote, so it ties 1-1 and Oswald (voted first)
+    // wins the tie-break instead.
+    expect(
+      fontsOf(model.styles!.textStyles!.textStyleOptions, PARAGRAPH_ROLES),
+    ).toEqual(Array(3).fill('Nunito'));
+  });
+
+  it('T16.5 — testimonial name/position, profile name, itemTextStyle and success messages cast no vote', async () => {
+    const options = TextStyles.GetDefaultTextStyle().textStyleOptions;
+
+    const model = await runMigration22(
+      siteWith(
+        {
+          pages: [
+            {
+              contents: [
+                {
+                  type: 'testimonial-section',
+                  title: '',
+                  items: [
+                    {
+                      id: '1',
+                      name: 'A name',
+                      position: 'A position',
+                      testimonials: 'A quote',
+                    },
+                  ],
+                  nameStyle: { fontFamily: 'Oswald' },
+                  positionStyle: { fontFamily: 'Oswald' },
+                  testimonialStyle: { fontFamily: 'Oswald' },
+                },
+                {
+                  type: 'support-me',
+                  title: '',
+                  description: 'Support description',
+                  titleStyle: {},
+                  descriptionStyle: { fontFamily: 'Nunito', fontSize: '1em' },
+                  headingStyle: { fontFamily: 'Oswald' }, // fixed i18n labels, not a vote source
+                  successMessageStyle: { fontFamily: 'Oswald' },
+                  itemTextStyle: { fontFamily: 'Oswald' },
+                },
+              ],
+            },
+          ],
+        },
+        options,
+      ),
+    );
+
+    expect(
+      fontsOf(model.styles!.textStyles!.textStyleOptions, PARAGRAPH_ROLES),
+    ).toEqual(Array(3).fill('Nunito'));
+    // No title/heading text anywhere on this site — the family keeps its default.
+    expect(
+      fontsOf(model.styles!.textStyles!.textStyleOptions, HEADING_ROLES),
+    ).toEqual(Array(6).fill('Lato'));
+  });
+
+  it("T16.6 — counts the font a legacy-role field DREW (the role's), not its own stored override; a title on Paragraphs counts for the headings", async () => {
+    const options = TextStyles.GetDefaultTextStyle().textStyleOptions;
+
+    options.paragraphs.style.fontFamily = 'Tenor Sans';
+
+    const model = await runMigration22(
+      siteWith(
+        {
+          pages: [
+            {
+              contents: [
+                banner({
+                  // Production ignored this field's own font (it drew the role's) — the count
+                  // must agree, or it would disagree with what B keeps.
+                  descriptionStyle: {
+                    textStyleType: 'paragraphs',
+                    fontFamily: 'Oswald',
+                  },
+                  // A title linked to the (legacy) Paragraphs role counts for the HEADINGS family.
+                  titleStyle: { textStyleType: 'paragraphs' },
+                }),
+              ],
+            },
+          ],
+        },
+        options,
+      ),
+    );
+    const after = model.styles!.textStyles!.textStyleOptions;
+
+    expect(fontsOf(after, PARAGRAPH_ROLES)).toEqual(
+      Array(3).fill('Tenor Sans'),
+    );
+    expect(fontsOf(after, HEADING_ROLES)).toEqual(Array(6).fill('Tenor Sans'));
+  });
+
+  it("T16.6 — a description on no role with no font counts the site's own font, read from its stored KEY", async () => {
+    const options = TextStyles.GetDefaultTextStyle().textStyleOptions;
+
+    const model = await runMigration22(
+      siteWith(
+        {
+          pages: [{ contents: [banner({ descriptionStyle: {} })] }],
+        },
+        options,
+        'anton', // the site's font KEY — resolves to the display name 'Anton'
+      ),
+    );
+
+    expect(
+      fontsOf(model.styles!.textStyles!.textStyleOptions, PARAGRAPH_ROLES),
+    ).toEqual(Array(3).fill('Anton'));
+  });
+
+  it('T16.7 — the button family counts the header button, a link button label and Save Contact, by field kind not role', async () => {
+    const options = TextStyles.GetDefaultTextStyle().textStyleOptions;
+
+    options.buttons.style.fontFamily = 'Oswald';
+
+    const model = await runMigration22(
+      siteWith(
+        {
+          brandPageType: BRAND_PAGE_TYPES.brandSite,
+          pageHeaderDesktop: {
+            headerButton: {
+              isVisible: true,
+              text: 'Contact us',
+              buttonLinkType: 'url',
+            },
+          },
+          pageHeaderMobile: {
+            headerButton: { isVisible: false, text: '', buttonLinkType: 'url' },
+          },
+          pages: [
+            {
+              contents: [
+                {
+                  type: 'general-link',
+                  title: 'Visit us',
+                  titleStyle: { textStyleType: 'buttons' },
+                  url: 'https://example.com',
+                },
+              ],
+            },
+          ],
+        },
+        options,
+      ),
+    );
+
+    // Both the (visible, desktop) header button and the link button label drew `buttons`'s Oswald.
+    expect(
+      model.styles!.textStyles!.textStyleOptions.button.style.fontFamily,
+    ).toBe('Oswald');
+  });
+
+  it('T16.7(b) — the header button counts once even when both desktop and mobile are visible', async () => {
+    const options = TextStyles.GetDefaultTextStyle().textStyleOptions;
+
+    const model = await runMigration22(
+      siteWith(
+        {
+          pageHeaderDesktop: {
+            headerButton: {
+              isVisible: true,
+              text: 'Contact us',
+              buttonLinkType: 'url',
+              buttonTextStyle: { fontFamily: 'Aleo', fontSize: '1em' },
+            },
+          },
+          pageHeaderMobile: {
+            headerButton: {
+              isVisible: true,
+              text: 'Contact us',
+              buttonLinkType: 'url',
+              buttonTextStyle: { fontFamily: 'Oswald', fontSize: '1em' },
+            },
+          },
+          pages: [
+            {
+              contents: [
+                {
+                  type: 'general-link',
+                  title: 'Visit us',
+                  titleStyle: { fontFamily: 'Oswald', fontSize: '1em' },
+                  url: 'https://example.com',
+                },
+              ],
+            },
+          ],
+        },
+        options,
+      ),
+    );
+
+    // Aleo (desktop, counted once, voted before the page content) wins the 1-1 tie against the
+    // link button's Oswald vote — double-counting the mobile header too would make Oswald 2-1.
+    expect(
+      model.styles!.textStyles!.textStyleOptions.button.style.fontFamily,
+    ).toBe('Aleo');
+  });
+
+  it('T16.7(b) — a profile title votes for the headings, not the button family', async () => {
+    const options = TextStyles.GetDefaultTextStyle().textStyleOptions;
+
+    const model = await runMigration22(
+      siteWith(
+        {
+          pages: [
+            {
+              contents: [
+                {
+                  type: 'profile',
+                  name: 'A name',
+                  title: 'Head of Design',
+                  description: '',
+                  titleStyle: { fontFamily: 'Anton', fontSize: '1em' },
+                  nameStyle: {},
+                  descriptionStyle: {},
+                },
+              ],
+            },
+          ],
+        },
+        options,
+      ),
+    );
+    const after = model.styles!.textStyles!.textStyleOptions;
+
+    expect(fontsOf(after, HEADING_ROLES)).toEqual(Array(6).fill('Anton'));
+    expect(after.button.style.fontFamily).toBe('Lato'); // no vote from this field
+  });
+
+  it('T16.7(c) — a hidden header button, a banner with its button off and an empty title cast no vote', async () => {
+    const options = TextStyles.GetDefaultTextStyle().textStyleOptions;
+
+    options.buttons.style.fontFamily = 'Oswald'; // would win if anything voted
+
+    const model = await runMigration22(
+      siteWith(
+        {
+          pageHeaderDesktop: {
+            headerButton: {
+              isVisible: false,
+              text: 'Hidden',
+              buttonLinkType: 'url',
+            },
+          },
+          pages: [
+            {
+              contents: [
+                banner({
+                  buttonText: false,
+                  buttonTextStyle: { textStyleType: 'buttons' },
+                }),
+                {
+                  type: 'general-link',
+                  title: '',
+                  titleStyle: { textStyleType: 'buttons' },
+                  url: '',
+                },
+              ],
+            },
+          ],
+        },
+        options,
+      ),
+    );
+
+    expect(
+      model.styles!.textStyles!.textStyleOptions.button.style.fontFamily,
+    ).toBe('Lato');
+  });
+
+  it('T16.7(d) — Save Contact votes button text on brand.contact only, from its own font when it has one', async () => {
+    const withSaveContact = await runMigration22(
+      siteWith(
+        {
+          brandPageType: BRAND_PAGE_TYPES.brandContact,
+          pages: [{ contents: [{ type: 'profile', name: 'A name' }] }],
+          saveContactSettings: {
+            isSavingEnabled: true,
+            hideBranding: false,
+            buttonTextStyle: { fontFamily: 'Oswald', fontSize: '1em' },
+          },
+        },
+        TextStyles.GetDefaultTextStyle().textStyleOptions,
+      ),
+    );
+
+    expect(
+      withSaveContact.styles!.textStyles!.textStyleOptions.button.style
+        .fontFamily,
+    ).toBe('Oswald');
+
+    // brand.site: the same field never votes (the widget doesn't render there).
+    const brandSite = await runMigration22(
+      siteWith(
+        {
+          brandPageType: BRAND_PAGE_TYPES.brandSite,
+          pages: [{ contents: [{ type: 'profile', name: 'A name' }] }],
+          saveContactSettings: {
+            isSavingEnabled: true,
+            hideBranding: false,
+            buttonTextStyle: { fontFamily: 'Oswald', fontSize: '1em' },
+          },
+        },
+        TextStyles.GetDefaultTextStyle().textStyleOptions,
+      ),
+    );
+
+    expect(
+      brandSite.styles!.textStyles!.textStyleOptions.button.style.fontFamily,
+    ).toBe('Lato');
+  });
+
+  it('T16.7(d) — Save Contact casts no vote on a brand.contact site with no profile section (S4: the widget never renders without one)', async () => {
+    const model = await runMigration22(
+      siteWith(
+        {
+          brandPageType: BRAND_PAGE_TYPES.brandContact,
+          // A page WITH a (non-profile) section, so this proves the no-vote rule keys off the
+          // missing profile section specifically, not merely an empty `pages` array.
+          pages: [{ contents: [banner()] }],
+          saveContactSettings: {
+            isSavingEnabled: true,
+            hideBranding: false,
+            buttonTextStyle: { fontFamily: 'Oswald', fontSize: '1em' },
+          },
+        },
+        TextStyles.GetDefaultTextStyle().textStyleOptions,
+      ),
+    );
+
+    expect(
+      model.styles!.textStyles!.textStyleOptions.button.style.fontFamily,
+    ).toBe('Lato');
+  });
+
+  it('T16.7(e) — three link-button labels vote the button family, not headings (Q10: a link button is a button element); a profile title votes the headings', async () => {
+    const options = TextStyles.GetDefaultTextStyle().textStyleOptions;
+
+    const model = await runMigration22(
+      siteWith(
+        {
+          brandPageType: BRAND_PAGE_TYPES.default,
+          pages: [
+            {
+              contents: [
+                {
+                  type: 'general-link',
+                  title: 'Visit us',
+                  titleStyle: { fontFamily: 'Oswald', fontSize: '1em' },
+                  url: 'https://example.com',
+                },
+                {
+                  type: 'general-link',
+                  title: 'Follow us',
+                  titleStyle: { fontFamily: 'Oswald', fontSize: '1em' },
+                  url: 'https://example.com',
+                },
+                {
+                  type: 'general-link',
+                  title: 'Email us',
+                  titleStyle: { fontFamily: 'Oswald', fontSize: '1em' },
+                  url: 'mailto:hi@example.com',
+                },
+                {
+                  type: 'profile',
+                  name: 'A name',
+                  title: 'Head of Design',
+                  description: '',
+                  titleStyle: { fontFamily: 'Anton', fontSize: '1em' },
+                  nameStyle: {},
+                  descriptionStyle: {},
+                },
+              ],
+            },
+          ],
+        },
+        options,
+      ),
+    );
+    const after = model.styles!.textStyles!.textStyleOptions;
+
+    // If a link's title voted the headings instead, headings would flip to Oswald (3-1) and button
+    // would stay on Lato (no vote) — both assertions below catch that misclassification.
+    expect(after.button.style.fontFamily).toBe('Oswald');
+    expect(fontsOf(after, HEADING_ROLES)).toEqual(Array(6).fill('Anton'));
+  });
+
+  it('T16.7(f) — a direct section button (banner) counts its own non-blank buttonText, not just a link label or the header button', async () => {
+    const options = TextStyles.GetDefaultTextStyle().textStyleOptions;
+
+    const model = await runMigration22(
+      siteWith(
+        {
+          pages: [
+            {
+              contents: [
+                banner({
+                  buttonText: 'Shop',
+                  buttonTextStyle: { fontFamily: 'Oswald', fontSize: '1em' },
+                }),
+              ],
+            },
+          ],
+        },
+        options,
+      ),
+    );
+
+    expect(
+      model.styles!.textStyles!.textStyleOptions.button.style.fontFamily,
+    ).toBe('Oswald');
+  });
+
+  it("T16.7(g) — a visible-but-blank desktop header button (S3) doesn't stop the visible mobile one from voting", async () => {
+    const options = TextStyles.GetDefaultTextStyle().textStyleOptions;
+
+    const model = await runMigration22(
+      siteWith(
+        {
+          pageHeaderDesktop: {
+            headerButton: { isVisible: true, text: '', buttonLinkType: 'url' },
+          },
+          pageHeaderMobile: {
+            headerButton: {
+              isVisible: true,
+              text: 'Contact us',
+              buttonLinkType: 'url',
+              buttonTextStyle: { fontFamily: 'Oswald', fontSize: '1em' },
+            },
+          },
+        },
+        options,
+      ),
+    );
+
+    expect(
+      model.styles!.textStyles!.textStyleOptions.button.style.fontFamily,
+    ).toBe('Oswald');
+  });
+
+  it('T16.7(h) — a fixed-label button (request-payment) votes the button family from its own font (S3)', async () => {
+    const options = TextStyles.GetDefaultTextStyle().textStyleOptions;
+
+    const model = await runMigration22(
+      siteWith(
+        {
+          pages: [
+            {
+              contents: [
+                {
+                  type: 'request-payment',
+                  title: 'Support us',
+                  description: '',
+                  buttonTextStyle: { fontFamily: 'Oswald', fontSize: '1em' },
+                },
+              ],
+            },
+          ],
+        },
+        options,
+      ),
+    );
+
+    expect(
+      model.styles!.textStyles!.textStyleOptions.button.style.fontFamily,
+    ).toBe('Oswald');
+  });
+
+  it('T16.7(h) — support-me votes the button family the same way, with no persisted label to check for blank (S3)', async () => {
+    const options = TextStyles.GetDefaultTextStyle().textStyleOptions;
+
+    const model = await runMigration22(
+      siteWith(
+        {
+          pages: [
+            {
+              contents: [
+                {
+                  type: 'support-me',
+                  title: 'Buy me a coffee',
+                  description: '',
+                  buttonTextStyle: { fontFamily: 'Oswald', fontSize: '1em' },
+                },
+              ],
+            },
+          ],
+        },
+        options,
+      ),
+    );
+
+    expect(
+      model.styles!.textStyles!.textStyleOptions.button.style.fontFamily,
+    ).toBe('Oswald');
+  });
+
+  it("T16.7(h) — shop's fixed-label button votes only once it has a product to sell (S3)", async () => {
+    const options = TextStyles.GetDefaultTextStyle().textStyleOptions;
+
+    const shopSection = (
+      products: Record<string, unknown>[],
+    ): Record<string, unknown> => ({
+      type: 'shop-section',
+      title: '',
+      description: '',
+      products,
+      buttonTextStyle: { fontFamily: 'Oswald', fontSize: '1em' },
+    });
+
+    const noProducts = await runMigration22(
+      siteWith({ pages: [{ contents: [shopSection([])] }] }, options),
+    );
+
+    expect(
+      noProducts.styles!.textStyles!.textStyleOptions.button.style.fontFamily,
+    ).toBe('Lato');
+
+    const oneProduct = await runMigration22(
+      siteWith(
+        { pages: [{ contents: [shopSection([{ id: '1' }])] }] },
+        options,
+      ),
+    );
+
+    expect(
+      oneProduct.styles!.textStyles!.textStyleOptions.button.style.fontFamily,
+    ).toBe('Oswald');
+  });
+
+  it('T16.8 — nav, footer copyright and their fonts cast no vote', async () => {
+    const options = TextStyles.GetDefaultTextStyle().textStyleOptions;
+
+    const model = await runMigration22(
+      siteWith(
+        {
+          pageHeaderDesktop: {
+            navigation: { defaultButtonStyle: { fontFamily: 'Oswald' } },
+          },
+          pageFooterDesktop: { copyrightStyle: { fontFamily: 'Oswald' } },
+          pages: [
+            {
+              contents: [
+                banner({
+                  descriptionStyle: { fontFamily: 'Nunito', fontSize: '1em' },
+                }),
+              ],
+            },
+          ],
+        },
+        options,
+      ),
+    );
+
+    expect(
+      fontsOf(model.styles!.textStyles!.textStyleOptions, PARAGRAPH_ROLES),
+    ).toEqual(Array(3).fill('Nunito'));
+  });
+
+  it('T16.10 — a site with no counted text at all keeps every role on Lato', async () => {
+    const options = TextStyles.GetDefaultTextStyle().textStyleOptions;
+
+    const model = await runMigration22(siteWith({ pages: [] }, options));
+    const after = model.styles!.textStyles!.textStyleOptions;
+
+    expect(
+      fontsOf(after, [...HEADING_ROLES, ...PARAGRAPH_ROLES, 'button']),
+    ).toEqual(Array(10).fill('Lato'));
+  });
+
+  it('T16.10 (B1) — a family with no vote keeps Lato, even when the site text font is something else', async () => {
+    const options = TextStyles.GetDefaultTextStyle().textStyleOptions;
+
+    // A distinct site font (Anton) — red without the fix: a zero-vote family fell back to the
+    // SITE font, not Lato.
+    const model = await runMigration22(
+      siteWith({ pages: [] }, options, 'anton'),
+    );
+    const after = model.styles!.textStyles!.textStyleOptions;
+
+    expect(
+      fontsOf(after, [...HEADING_ROLES, ...PARAGRAPH_ROLES, 'button']),
+    ).toEqual(Array(10).fill('Lato'));
+  });
+
+  it('T16.10 — counted text that is all Lato wins on its own votes, not because it happens to match the site font', async () => {
+    const options = TextStyles.GetDefaultTextStyle().textStyleOptions;
+
+    const model = await runMigration22(
+      siteWith(
+        {
+          pages: [
+            {
+              contents: [
+                banner({
+                  descriptionStyle: { fontFamily: 'Lato', fontSize: '1em' },
+                }),
+              ],
+            },
+          ],
+        },
+        options,
+        'anton', // a DIFFERENT site font, so a Lato winner can only come from the vote
+      ),
+    );
+
+    expect(
+      fontsOf(model.styles!.textStyles!.textStyleOptions, PARAGRAPH_ROLES),
+    ).toEqual(Array(3).fill('Lato'));
+
+    // S6: the counted field's own literal (Lato) now equals the winning role and drops, rather
+    // than surviving as a redundant override.
+    const contents = model.pages[0].contents as unknown as {
+      descriptionStyle: { fontFamily?: string };
+    }[];
+
+    expect(contents[0].descriptionStyle.fontFamily).toBeUndefined();
+  });
+
+  it('T16.11 — a font outside the font list casts no vote, and its own text keeps it as an override', async () => {
+    const options = TextStyles.GetDefaultTextStyle().textStyleOptions;
+
+    const model = await runMigration22(
+      siteWith(
+        {
+          pages: [
+            {
+              contents: [
+                banner({
+                  descriptionStyle: { fontFamily: 'Calibri', fontSize: '1em' },
+                }),
+                banner({
+                  descriptionStyle: { fontFamily: 'Calibri', fontSize: '1em' },
+                }),
+                banner({
+                  descriptionStyle: { fontFamily: 'Calibri', fontSize: '1em' },
+                }),
+                banner({
+                  descriptionStyle: { fontFamily: 'Nunito', fontSize: '1em' },
+                }),
+              ],
+            },
+          ],
+        },
+        options,
+      ),
+    );
+
+    expect(
+      fontsOf(model.styles!.textStyles!.textStyleOptions, PARAGRAPH_ROLES),
+    ).toEqual(Array(3).fill('Nunito'));
+  });
+
+  it("T16.12 — each list item votes on its own, against the section's single paragraphStyle", async () => {
+    const options = TextStyles.GetDefaultTextStyle().textStyleOptions;
+
+    const model = await runMigration22(
+      siteWith(
+        {
+          pages: [
+            {
+              contents: [
+                imagesSection({
+                  paragraphStyle: { fontFamily: 'Oswald', fontSize: '1em' },
+                  items: [
+                    { id: '1', paragraph: 'one' },
+                    { id: '2', paragraph: 'two' },
+                    { id: '3', paragraph: 'three' },
+                    { id: '4', paragraph: 'four' },
+                  ],
+                }),
+                banner({
+                  descriptionStyle: { fontFamily: 'Nunito', fontSize: '1em' },
+                }),
+                banner({
+                  descriptionStyle: { fontFamily: 'Nunito', fontSize: '1em' },
+                }),
+                banner({
+                  descriptionStyle: { fontFamily: 'Nunito', fontSize: '1em' },
+                }),
+              ],
+            },
+          ],
+        },
+        options,
+      ),
+    );
+
+    // 4 item votes for Oswald vs 3 for Nunito.
+    expect(
+      fontsOf(model.styles!.textStyles!.textStyleOptions, PARAGRAPH_ROLES),
+    ).toEqual(Array(3).fill('Oswald'));
+  });
+
+  it('T16.12 — an item with a blank paragraph casts no vote', async () => {
+    const options = TextStyles.GetDefaultTextStyle().textStyleOptions;
+
+    const model = await runMigration22(
+      siteWith(
+        {
+          pages: [
+            {
+              contents: [
+                imagesSection({
+                  paragraphStyle: { fontFamily: 'Oswald', fontSize: '1em' },
+                  items: [
+                    { id: '1', paragraph: 'one' },
+                    { id: '2', paragraph: 'two' },
+                    { id: '3', paragraph: '' }, // blank — no vote
+                    { id: '4', paragraph: '   ' }, // whitespace-only — no vote
+                  ],
+                }),
+                banner({
+                  descriptionStyle: { fontFamily: 'Nunito', fontSize: '1em' },
+                }),
+                banner({
+                  descriptionStyle: { fontFamily: 'Nunito', fontSize: '1em' },
+                }),
+                banner({
+                  descriptionStyle: { fontFamily: 'Nunito', fontSize: '1em' },
+                }),
+              ],
+            },
+          ],
+        },
+        options,
+      ),
+    );
+
+    // 2 real item votes for Oswald vs 3 for Nunito — the two blank items must not tip Oswald to
+    // a tie or a win at 4.
+    expect(
+      fontsOf(model.styles!.textStyles!.textStyleOptions, PARAGRAPH_ROLES),
+    ).toEqual(Array(3).fill('Nunito'));
+  });
+
+  it('T16.12 (S8) — a left/right-aligned images-section item past the render cutoff casts no vote', async () => {
+    const options = TextStyles.GetDefaultTextStyle().textStyleOptions;
+
+    const model = await runMigration22(
+      siteWith(
+        {
+          pages: [
+            {
+              contents: [
+                // Only the first 3 items render in a left-aligned layout
+                // (`MAX_IMAGES_SECTION_ALIGNMENT_ITEMS_LENGTH`) — 3 real Oswald votes, not 4.
+                imagesSection({
+                  displayStyle: 'left-aligned',
+                  paragraphStyle: { fontFamily: 'Oswald', fontSize: '1em' },
+                  items: [
+                    { id: '1', paragraph: 'one' },
+                    { id: '2', paragraph: 'two' },
+                    { id: '3', paragraph: 'three' },
+                    { id: '4', paragraph: 'four' }, // past the cutoff — no vote
+                  ],
+                }),
+                banner({
+                  descriptionStyle: { fontFamily: 'Nunito', fontSize: '1em' },
+                }),
+                banner({
+                  descriptionStyle: { fontFamily: 'Nunito', fontSize: '1em' },
+                }),
+                banner({
+                  descriptionStyle: { fontFamily: 'Nunito', fontSize: '1em' },
+                }),
+                banner({
+                  descriptionStyle: { fontFamily: 'Nunito', fontSize: '1em' },
+                }),
+              ],
+            },
+          ],
+        },
+        options,
+      ),
+    );
+
+    // 3 real item votes for Oswald vs 4 for Nunito — Nunito wins. Counting the excluded 4th item
+    // too would tie it 4-4, and Oswald (voted first, the images-section comes first) would win
+    // the tie-break instead.
+    expect(
+      fontsOf(model.styles!.textStyles!.textStyleOptions, PARAGRAPH_ROLES),
+    ).toEqual(Array(3).fill('Nunito'));
+  });
+
+  it("T16.12 (S5) — each item title votes the headings family against a shapes section's single headingStyle", async () => {
+    const options = TextStyles.GetDefaultTextStyle().textStyleOptions;
+
+    const model = await runMigration22(
+      siteWith(
+        {
+          pages: [
+            {
+              contents: [
+                imagesSection({
+                  type: 'shapes-section',
+                  headingStyle: { fontFamily: 'Anton', fontSize: '1em' },
+                  items: [
+                    { id: '1', title: 'One' },
+                    { id: '2', title: 'Two' },
+                  ],
+                }),
+                banner({
+                  titleStyle: { fontFamily: 'Nunito', fontSize: '1em' },
+                }),
+              ],
+            },
+          ],
+        },
+        options,
+      ),
+    );
+
+    // 2 item votes for Anton vs 1 for the banner's own title (Nunito).
+    expect(
+      fontsOf(model.styles!.textStyles!.textStyleOptions, HEADING_ROLES),
+    ).toEqual(Array(6).fill('Anton'));
+  });
+
+  it("T16.12 (S5) — each item's buttonText votes the button family against an images section's single buttonTextStyle", async () => {
+    const options = TextStyles.GetDefaultTextStyle().textStyleOptions;
+
+    const model = await runMigration22(
+      siteWith(
+        {
+          pages: [
+            {
+              contents: [
+                imagesSection({
+                  buttonTextStyle: { fontFamily: 'Oswald', fontSize: '1em' },
+                  items: [
+                    { id: '1', buttonText: 'Shop' },
+                    { id: '2', buttonText: 'Buy' },
+                  ],
+                }),
+                banner({
+                  buttonText: 'Contact',
+                  buttonTextStyle: { fontFamily: 'Nunito', fontSize: '1em' },
+                }),
+              ],
+            },
+          ],
+        },
+        options,
+      ),
+    );
+
+    // 2 item votes for Oswald vs 1 for the banner's own direct button (Nunito).
+    expect(
+      model.styles!.textStyles!.textStyleOptions.button.style.fontFamily,
+    ).toBe('Oswald');
+  });
+
+  it('T16.9 — a dropped (role-equal) override follows a later role font edit; a kept literal (outside the font list) does not', async () => {
+    const options = TextStyles.GetDefaultTextStyle().textStyleOptions;
+
+    const model = await runMigration22(
+      siteWith(
+        {
+          pages: [
+            {
+              contents: [
+                banner({
+                  descriptionStyle: { fontFamily: 'Nunito', fontSize: '1em' },
+                }),
+                banner({
+                  descriptionStyle: { fontFamily: 'Nunito', fontSize: '1em' },
+                }),
+                // Outside the font list — casts no vote, and keeps its own literal.
+                banner({
+                  descriptionStyle: { fontFamily: 'Calibri', fontSize: '1em' },
+                }),
+              ],
+            },
+          ],
+        },
+        options,
+      ),
+    );
+    const after = model.styles!.textStyles!.textStyleOptions;
+    const contents = model.pages[0].contents as unknown as Record<
+      string,
+      Record<string, unknown>
+    >[];
+
+    expect(after.paragraph1.style.fontFamily).toBe('Nunito');
+    // A new item on Paragraph 1 (`addOption`'s shape) resolves the role's current font.
+    expect(
+      (
+        resolveTextStyle(
+          { textStyleType: 'paragraph1' } as unknown as TextStyleDeclaration,
+          after.paragraph1.style,
+        ) as Record<string, string>
+      ).fontFamily,
+    ).toBe('Nunito');
+
+    // A later role font edit reaches the content whose (role-equal) override B dropped…
+    after.paragraph1.style.fontFamily = 'Aleo';
+
+    expect(
+      (
+        resolveTextStyle(
+          contents[0].descriptionStyle as TextStyleDeclaration,
+          after.paragraph1.style,
+        ) as Record<string, string>
+      ).fontFamily,
+    ).toBe('Aleo');
+    // …but not the Calibri block, whose literal survived (it never equalled the role).
+    expect(
+      (
+        resolveTextStyle(
+          contents[2].descriptionStyle as TextStyleDeclaration,
+          after.paragraph1.style,
+        ) as Record<string, string>
+      ).fontFamily,
+    ).toBe('Calibri');
+  });
+});
+
+describe('migration-22 · stripLiftRteDoc (C — baked → role var / literal)', () => {
+  const role = { fontFamily: 'Lato', fontSize: '2em', lineHeight: '1.2' };
+
+  it('converts a baked attr that EQUALS the role to the role var token', () => {
+    const doc = docOf([
+      { text: 'Our ', attrs: { fontSize: '2em', color: 'red' } },
+      { text: 'Mission', attrs: { fontSize: '2em', color: 'red' } },
+    ]);
+
+    stripLiftRteDoc(doc, role);
+
+    expect(attrsOf(doc, 0)?.fontSize).toBe('var(--role-font-size)'); // referenced
+    expect(attrsOf(doc, 1)?.fontSize).toBe('var(--role-font-size)');
+    expect(attrsOf(doc, 0)?.color).toBe('red'); // colour untouched
+  });
+
+  it('keeps a baked attr that DIFFERS from the role as a literal override', () => {
+    const doc = docOf([
+      { text: 'Our ', attrs: { fontSize: '3em' } },
+      { text: 'Mission', attrs: { fontSize: '3em' } },
+    ]);
+
+    stripLiftRteDoc(doc, role);
+
+    expect(attrsOf(doc, 0)?.fontSize).toBe('3em'); // kept literal (an override)
+  });
+
+  it('reconciles per-run: role-equal → var, divergent → literal', () => {
+    const doc = docOf([
+      { text: 'Our ', attrs: { fontSize: '2em' } }, // equals role
+      { text: 'Mission', attrs: { fontSize: '3em' } }, // one word differs
+    ]);
+
+    stripLiftRteDoc(doc, role);
+
+    expect(attrsOf(doc, 0)?.fontSize).toBe('var(--role-font-size)');
+    expect(attrsOf(doc, 1)?.fontSize).toBe('3em');
+  });
+
+  it('leaves an already-referenced value untouched', () => {
+    const doc = docOf([
+      { text: 'hi', attrs: { fontSize: 'var(--role-font-size)' } },
+    ]);
+
+    stripLiftRteDoc(doc, role);
+
+    expect(attrsOf(doc, 0)?.fontSize).toBe('var(--role-font-size)');
+  });
+
+  it('fills a run missing a role-defined attr with the role ref (container applies nothing)', () => {
+    // colour-only run: the role's typography must be referenced on the run itself, since the
+    // container class no longer applies it.
+    const doc = docOf([{ text: 'hi', attrs: { color: 'red' } }]);
+
+    stripLiftRteDoc(doc, role);
+
+    const attrs = attrsOf(doc, 0);
+
+    expect(attrs?.fontFamily).toBe('var(--role-font-family)'); // filled
+    expect(attrs?.fontSize).toBe('var(--role-font-size)'); // filled
+    expect(attrs?.lineHeight).toBe('var(--role-line-height)'); // filled
+    expect(attrs?.letterSpacing).toBeUndefined(); // role has none → not filled
+    expect(attrs?.color).toBe('red'); // colour untouched
+  });
+
+  it('bakes a block-level typography override onto the runs as a literal (element applies nothing now)', () => {
+    // colour-only run; the block (styleObj) overrides family to Inter (role is Lato).
+    const doc = docOf([{ text: 'hi', attrs: { color: 'red' } }]);
+
+    stripLiftRteDoc(doc, role, { fontFamily: 'Inter' });
+
+    const attrs = attrsOf(doc, 0);
+
+    expect(attrs?.fontFamily).toBe('Inter'); // block override → literal on the run
+    expect(attrs?.fontSize).toBe('var(--role-font-size)'); // matches role → ref
+    expect(attrs?.lineHeight).toBe('var(--role-line-height)'); // matches role → ref
+  });
+
+  it('keeps a per-run override even when the block also overrides (per-run wins)', () => {
+    const doc = docOf([{ text: 'hi', attrs: { fontFamily: 'Georgia' } }]);
+
+    stripLiftRteDoc(doc, role, { fontFamily: 'Inter' });
+
+    // the run's own override wins over both the block override and the role
+    expect(attrsOf(doc, 0)?.fontFamily).toBe('Georgia');
+  });
+
+  it('never touches colour', () => {
+    const doc = docOf([{ text: 'hi', attrs: { color: 'var(--x)' } }]);
+
+    stripLiftRteDoc(doc, role);
+
+    expect(attrsOf(doc, 0)?.color).toBe('var(--x)');
+  });
+
+  it('skips a non-Tiptap value (legacy HTML string)', () => {
+    expect(() => stripLiftRteDoc('<p>legacy</p>', role)).not.toThrow();
+  });
+});
+
+describe('migration-22 · foldSemanticFormattingMarks (C2 — marks → textStyle attrs)', () => {
+  const markDoc = (runs: { text: string; marks?: string[] }[]) => ({
+    type: 'doc',
+    content: [
+      {
+        type: 'paragraph',
+        content: runs.map((r) => ({
+          type: 'text',
+          text: r.text,
+          marks: (r.marks ?? []).map((type) => ({ type })),
+        })),
+      },
+    ],
+  });
+
+  const firstRun = (doc: ReturnType<typeof markDoc>) =>
+    doc.content[0].content[0] as {
+      marks: { type: string; attrs?: Record<string, string> }[];
+    };
+  const attrsOf = (doc: ReturnType<typeof markDoc>) =>
+    firstRun(doc).marks.find((m) => m.type === 'textStyle')?.attrs ?? {};
+  const markTypes = (doc: ReturnType<typeof markDoc>) =>
+    firstRun(doc).marks.map((m) => m.type);
+
+  it('folds a bold mark into a fontWeight literal and removes the mark (role not bold)', () => {
+    const doc = markDoc([{ text: 'hi', marks: ['bold'] }]);
+
+    foldSemanticFormattingMarks(doc, { fontWeight: 'normal' });
+
+    expect(attrsOf(doc).fontWeight).toBe('bold'); // differs from role → literal override
+    expect(markTypes(doc)).not.toContain('bold');
+  });
+
+  it('re-links a bold mark to the role var when the role is bold', () => {
+    const doc = markDoc([{ text: 'hi', marks: ['bold'] }]);
+
+    foldSemanticFormattingMarks(doc, { fontWeight: 'bold' });
+
+    expect(attrsOf(doc).fontWeight).toBe('var(--role-font-weight)');
+    expect(markTypes(doc)).not.toContain('bold');
+  });
+
+  it('composes underline + strike into one textDecoration attr and removes both marks', () => {
+    const doc = markDoc([{ text: 'hi', marks: ['underline', 'strike'] }]);
+
+    foldSemanticFormattingMarks(doc, {});
+
+    expect(attrsOf(doc).textDecoration).toBe('underline line-through');
+    expect(markTypes(doc)).not.toContain('underline');
+    expect(markTypes(doc)).not.toContain('strike');
+  });
+
+  it('leaves a run with no formatting marks untouched', () => {
+    const doc = markDoc([
+      {
+        text: 'hi',
+        marks: [], // will carry only a textStyle colour mark below
+      },
+    ]);
+
+    firstRun(doc).marks.push({ type: 'textStyle', attrs: { color: 'red' } });
+
+    foldSemanticFormattingMarks(doc, { fontWeight: 'bold' });
+
+    expect(attrsOf(doc)).toEqual({ color: 'red' }); // no weight added
+    expect(markTypes(doc)).toEqual(['textStyle']);
+  });
+
+  it('keeps an existing textStyle attr rather than overwriting it', () => {
+    const doc = markDoc([{ text: 'hi', marks: ['bold'] }]);
+
+    firstRun(doc).marks.push({
+      type: 'textStyle',
+      attrs: { fontWeight: '900' },
+    });
+
+    foldSemanticFormattingMarks(doc, { fontWeight: 'bold' });
+
+    expect(attrsOf(doc).fontWeight).toBe('900'); // pre-existing attr wins
+    expect(markTypes(doc)).not.toContain('bold');
+  });
+});
+
+describe('migration-22 · pinLegacyRunWeight (C3 — not-bold legacy weight override)', () => {
+  const runDoc = (attrs?: Record<string, string>) => ({
+    type: 'doc',
+    content: [
+      {
+        type: 'paragraph',
+        content: [
+          {
+            type: 'text',
+            text: 'hi',
+            marks: attrs ? [{ type: 'textStyle', attrs }] : [],
+          },
+        ],
+      },
+    ],
+  });
+  const weightOf = (doc: ReturnType<typeof runDoc>) =>
+    (
+      doc.content[0].content[0].marks.find((m) => m.type === 'textStyle') as
+        | { attrs?: Record<string, string> }
+        | undefined
+    )?.attrs?.fontWeight;
+
+  it('pins a not-bold legacy block to a `normal` literal under a bold heading tier', () => {
+    const doc = runDoc();
+
+    // block weight resolved to `normal` by job B; the reconnected tier is bold.
+    pinLegacyRunWeight(doc, 'bold', 'normal');
+
+    expect(weightOf(doc)).toBe('normal'); // literal override beats the tier's bold at render
+  });
+
+  it('no-ops when block weight equals the tier (render var-fill follows the role)', () => {
+    const doc = runDoc();
+
+    pinLegacyRunWeight(doc, 'bold', 'bold');
+
+    expect(weightOf(doc)).toBeUndefined(); // left bare → the fill supplies var(--role-font-weight)
+  });
+
+  it('no-ops when the block carries no weight (a non-legacy/canonical block)', () => {
+    const doc = runDoc();
+
+    pinLegacyRunWeight(doc, 'bold', undefined);
+
+    expect(weightOf(doc)).toBeUndefined();
+  });
+
+  it('leaves a run that already carries a weight (a folded bold mark) untouched', () => {
+    const doc = runDoc({ fontWeight: 'bold' });
+
+    pinLegacyRunWeight(doc, 'bold', 'normal');
+
+    expect(weightOf(doc)).toBe('bold'); // per-run weight is authoritative
+  });
+
+  it('leaves a folded role-var weight untouched (bold + bare runs coexisting in one block)', () => {
+    // a bold run under a bold tier folds to the role var — the pin must not overwrite it with the
+    // block’s `normal`, or a mixed heading block would lose its bold runs.
+    const doc = runDoc({ fontWeight: 'var(--role-font-weight)' });
+
+    pinLegacyRunWeight(doc, 'bold', 'normal');
+
+    expect(weightOf(doc)).toBe('var(--role-font-weight)');
+  });
+
+  it('pins a block-bold override as a literal under a normal tier', () => {
+    const doc = runDoc();
+
+    pinLegacyRunWeight(doc, 'normal', 'bold');
+
+    expect(weightOf(doc)).toBe('bold');
+  });
+
+  it('skips a non-Tiptap value (legacy HTML string)', () => {
+    expect(() =>
+      pinLegacyRunWeight('<p>legacy</p>', 'bold', 'normal'),
+    ).not.toThrow();
+  });
+});
+
+describe('migration-22 · bakeElementColours (D — freeze resolved colour)', () => {
+  const optionsWithBaseCoat = (baseCoat: string): TextStyleOptions => {
+    const options = TextStyles.GetDefaultTextStyle().textStyleOptions;
+
+    setRoleColor(options.paragraph1.style, baseCoat);
+
+    return options;
+  };
+
+  it('bakes the base coat onto a non-RTE field that has no colour', () => {
+    const options = optionsWithBaseCoat('#123456');
+    // headingStyle is a shapes per-item style — non-RTE, so baked onto style.color.
+    const content = {
+      type: 'shapes-section',
+      headingStyle: { textStyleType: 'heading2' },
+    };
+
+    bakeElementColours(modelWith(content, options), options);
+
+    expect((content.headingStyle as { color?: string }).color).toBe('#123456');
+  });
+
+  it('prefers the role colour over the base coat', () => {
+    const options = optionsWithBaseCoat('#000000');
+
+    setRoleColor(options.heading2.style, '#ff0000');
+
+    const content = {
+      type: 'shapes-section',
+      headingStyle: { textStyleType: 'heading2' },
+    };
+
+    bakeElementColours(modelWith(content, options), options);
+
+    expect((content.headingStyle as { color?: string }).color).toBe('#ff0000');
+  });
+
+  it('keeps a no-role field on the original base coat after reconnect assigns a heading role', async () => {
+    const options = TextStyles.GetDefaultTextStyle().textStyleOptions;
+
+    options.titles.style.fontSize = '2.25em';
+    setRoleColor(options.titles.style, '#ff0000');
+    setRoleColor(options.paragraphs.style, '#000000');
+
+    const content = {
+      type: 'banner-section',
+      title: 'Unlinked heading',
+      titleStyle: { fontSize: '2.25em' },
+    };
+    const model = await runMigration22(
+      siteWith({ pages: [{ contents: [content] }] }, options),
+    );
+    const migrated = model.pages[0].contents[0] as unknown as {
+      title: unknown;
+      titleStyle: { textStyleType?: string; color?: string };
+    };
+
+    expect(migrated.titleStyle.textStyleType).toBe('heading4');
+    expect(runMarkColor(migrated.title)).toBe('#000000');
+  });
+
+  it('leaves an already-coloured field untouched', () => {
+    const options = optionsWithBaseCoat('#000000');
+    const content = {
+      type: 'shapes-section',
+      headingStyle: { textStyleType: 'heading2', color: '#abcdef' },
+    };
+
+    bakeElementColours(modelWith(content, options), options);
+
+    expect(content.headingStyle.color).toBe('#abcdef');
+  });
+
+  it('never bakes onto buttonTextStyle (button label colour comes from buttonStyles)', () => {
+    const options = optionsWithBaseCoat('#000000');
+    const content = {
+      type: 'banner-section',
+      buttonTextStyle: { textStyleType: 'button' },
+    };
+
+    bakeElementColours(modelWith(content, options), options);
+
+    expect(
+      (content.buttonTextStyle as { color?: string }).color,
+    ).toBeUndefined();
+  });
+
+  it('fills an uncoloured RTE run with the resolved colour (into the mark)', () => {
+    const options = optionsWithBaseCoat('#00aa00');
+    const content = {
+      type: 'banner-section',
+      title: docOf([{ text: 'Hello' }]), // no attrs → uncoloured run
+      titleStyle: { textStyleType: 'heading1' },
+    };
+
+    bakeElementColours(modelWith(content, options), options);
+
+    expect(runMarkColor(content.title)).toBe('#00aa00');
+  });
+
+  it('leaves an already-coloured RTE run alone (fill-only)', () => {
+    const options = optionsWithBaseCoat('#000000');
+    const content = {
+      type: 'banner-section',
+      title: docOf([{ text: 'Hello', attrs: { color: '#eeeeee' } }]),
+      titleStyle: { textStyleType: 'heading1' },
+    };
+
+    bakeElementColours(modelWith(content, options), options);
+
+    expect(runMarkColor(content.title)).toBe('#eeeeee');
+  });
+
+  it('bakes shop title colour into the run mark (shop is RTE, BP-5969)', () => {
+    const options = optionsWithBaseCoat('#654321');
+    // shop is RTE now: B1 already made the title a doc, so D bakes colour into the mark.
+    const content = {
+      type: 'shop-section',
+      title: docOf([{ text: 'My shop' }]),
+      titleStyle: { textStyleType: 'heading1' },
+    };
+
+    bakeElementColours(modelWith(content, options), options);
+
+    expect(runMarkColor(content.title)).toBe('#654321');
+  });
+
+  it('bakes onto the style object when a normally-RTE field is a plain string (old site, no mark)', () => {
+    const options = optionsWithBaseCoat('#00aa00');
+    // banner title is normally a doc, but an un-migrated old site left it plain text — there
+    // is no run mark to hold colour, so D must bake onto the style object like a non-RTE field.
+    const content = {
+      type: 'banner-section',
+      title: 'Untouched legacy title',
+      titleStyle: { textStyleType: 'heading1' },
+    };
+
+    bakeElementColours(modelWith(content, options), options);
+
+    expect((content.titleStyle as { color?: string }).color).toBe('#00aa00');
+  });
+
+  it('D then G leave a plain-string RTE field with a resolvable colour (totality gap closed)', () => {
+    const options = optionsWithBaseCoat('#00aa00');
+    const content = {
+      type: 'banner-section',
+      title: 'Untouched legacy title', // plain string → no mark
+      titleStyle: { textStyleType: 'heading1' },
+    };
+    const model = modelWith(content, options);
+
+    bakeElementColours(model, options); // D bakes the resolved colour onto the object
+    stripRteStyleColours(model); // G must NOT strip it — there's no mark to hold it
+
+    expect((content.titleStyle as { color?: string }).color).toBe('#00aa00');
+  });
+
+  it('bakes the footer copyright colour (it lives outside page.contents)', () => {
+    const options = optionsWithBaseCoat('#334455');
+    const model = modelWith({ type: 'shapes-section' }, options);
+
+    // Footer copyright: role-linked, no colour of its own — must be frozen or it loses its
+    // colour once E clears the role and the base coat is removed.
+    (model as unknown as Record<string, unknown>).pageFooterDesktop = {
+      copyrightStyle: { textStyleType: 'paragraph1', textAlign: 'center' },
+    };
+    (model as unknown as Record<string, unknown>).pageFooterMobile = {
+      copyrightStyle: { textStyleType: 'paragraph1', textAlign: 'center' },
+    };
+
+    bakeElementColours(model, options);
+
+    const footerColour = (m: BrandPageModel, key: string): string | undefined =>
+      (m as unknown as Record<string, { copyrightStyle: { color?: string } }>)[
+        key
+      ].copyrightStyle.color;
+
+    expect(footerColour(model, 'pageFooterDesktop')).toBe('#334455');
+    expect(footerColour(model, 'pageFooterMobile')).toBe('#334455');
+  });
+
+  // FB-1 (QA scope): a plain text block on a dark section band freezes to the dark base coat.
+  // bakeElementColours resolves colour from style → containerDefaults → role → base coat, and
+  // NEVER reads the block's own section background. Only the container-bound types
+  // (mailing-list / request-payment / support-me / contact-form) re-contrast against their
+  // surface, so a plain text block on a dark band is baked dark = black-on-dark. This test
+  // characterises the current behaviour; if migration ever contrasts plain text blocks, flip it.
+  it('FB-1 — freezes the dark base coat onto a text block on a dark band (no band contrast)', () => {
+    const options = optionsWithBaseCoat('#000000');
+    const content = {
+      type: 'banner-section',
+      backgroundStyle: { backgroundColor: '#0a0a0a' }, // dark band — not read by the bake
+      title: 'On a dark band', // plain string → colour bakes onto the style object
+      titleStyle: { textStyleType: 'paragraph1' },
+    };
+
+    bakeElementColours(modelWith(content, options), options);
+
+    expect((content.titleStyle as { color?: string }).color).toBe('#000000');
+  });
+
+  describe('social-links icon fill (always stored, never read from the title)', () => {
+    const socialLinks = (
+      iconFillStyles?: BrandPageCssStyle,
+    ): Record<string, unknown> => ({
+      type: 'social-links',
+      title: docOf([{ text: 'Follow us', attrs: { color: '#0000ff' } }]),
+      titleStyle: { textStyleType: 'heading4' },
+      ...(iconFillStyles ? { iconFillStyles } : {}),
+    });
+
+    const iconFill = (content: Record<string, unknown>): string | undefined =>
+      (content.iconFillStyles as BrandPageCssStyle | undefined)?.fill;
+
+    it('freezes the base coat the icons painted onto an unset fill', () => {
+      const options = optionsWithBaseCoat('#123456');
+      const content = socialLinks({});
+
+      bakeElementColours(modelWith(content, options), options);
+
+      expect(iconFill(content)).toBe('#123456');
+    });
+
+    it('bakes a section with no iconFillStyles at all', () => {
+      const options = optionsWithBaseCoat('#123456');
+      const content = socialLinks();
+
+      bakeElementColours(modelWith(content, options), options);
+
+      expect(iconFill(content)).toBe('#123456');
+    });
+
+    it('leaves an explicit icon fill untouched', () => {
+      const options = optionsWithBaseCoat('#123456');
+      const content = socialLinks({ fill: '#abcdef' });
+
+      bakeElementColours(modelWith(content, options), options);
+
+      expect(iconFill(content)).toBe('#abcdef');
+    });
+
+    it('bakes over a stored empty-string fill, same as an absent one', () => {
+      const options = optionsWithBaseCoat('#123456');
+      const content = socialLinks({ fill: '' });
+
+      bakeElementColours(modelWith(content, options), options);
+
+      expect(iconFill(content)).toBe('#123456');
+    });
+
+    // migration-22.ts's docblock names this job D's one exception (ADR-0020). Run through the
+    // real pipeline (`runMigration22`), not hand-strung internal functions, so what composing
+    // A and D actually does — not each in isolation — is what's proved.
+    it('the v21 → A → D chain: no legacy paragraphs colour means no base coat for D to freeze', async () => {
+      const options = TextStyles.GetDefaultTextStyle().textStyleOptions;
+
+      expect(roleColorOf(options.paragraphs.style)).toBeUndefined(); // the v21 fixture's premise
+
+      const content = socialLinks({});
+      const model = await runMigration22(
+        siteWith({ pages: [{ contents: [content] }] }, options),
+      );
+      const migrated = model.pages[0].contents[0] as unknown as Record<
+        string,
+        unknown
+      >;
+
+      // No base coat for D to freeze → the icon gets the same NEW contrast colour a fresh
+      // title would, not the title's own run mark colour (#0000ff).
+      expect(iconFill(migrated)).toBeTruthy();
+      expect(iconFill(migrated)).not.toBe('#0000ff');
+    });
+
+    it('the v21 → A → D chain: a legacy paragraphs colour becomes the base coat D freezes', async () => {
+      const options = TextStyles.GetDefaultTextStyle().textStyleOptions;
+
+      setRoleColor(options.paragraphs.style, '#123456');
+
+      const content = socialLinks({});
+      const model = await runMigration22(
+        siteWith({ pages: [{ contents: [content] }] }, options),
+      );
+      const migrated = model.pages[0].contents[0] as unknown as Record<
+        string,
+        unknown
+      >;
+
+      // A seeds paragraph1 from the legacy `paragraphs` colour; D freezes THAT base coat,
+      // not a fresh contrast colour.
+      expect(iconFill(migrated)).toBe('#123456');
+    });
+
+    it('with no base coat, bakes the contrast colour a new title gets — not the title mark', () => {
+      const options = TextStyles.GetDefaultTextStyle().textStyleOptions;
+      const content = socialLinks({});
+      const model = modelWith(content, options);
+      const newTitle = {
+        type: 'social-links',
+        titleStyle: { textStyleType: 'heading4' },
+      } as unknown as Content;
+
+      bakeElementColours(model, options);
+      applyTextContrast(newTitle, model.styles, model.brandPageType);
+
+      const contrastColour = (
+        newTitle as unknown as { titleStyle: { color?: string } }
+      ).titleStyle.color;
+
+      expect(contrastColour).toBeTruthy();
+      expect(iconFill(content)).toBe(contrastColour);
+      expect(iconFill(content)).not.toBe('#0000ff');
+    });
+  });
+});
+
+describe('migration-22 · convertPlainRteFields (B1 — plain text → Tiptap doc)', () => {
+  it('converts a plain-string RTE field to a Tiptap doc', async () => {
+    const content = {
+      type: 'banner-section',
+      title: 'Hello world',
+      titleStyle: { textStyleType: 'heading1' },
+    };
+
+    await convertPlainRteFields(
+      modelWithContent(content),
+      TextStyles.GetDefaultTextStyle().textStyleOptions,
+    );
+
+    expect(isTiptapDocument(content.title)).toBe(true);
+    expect(JSON.stringify(content.title)).toContain('Hello world');
+  });
+
+  it('stamps textAlign from the style object onto the block node', async () => {
+    const content = {
+      type: 'banner-section',
+      title: 'Centered',
+      titleStyle: { textStyleType: 'heading1', textAlign: 'center' },
+    };
+
+    await convertPlainRteFields(
+      modelWithContent(content),
+      TextStyles.GetDefaultTextStyle().textStyleOptions,
+    );
+
+    const doc = content.title as unknown as {
+      content: { attrs?: { textAlign?: string } }[];
+    };
+
+    expect(doc.content[0].attrs?.textAlign).toBe('center');
+  });
+
+  it('bakes a not-bold legacy weight as a normal literal when converting under a bold tier (C3)', async () => {
+    const content = {
+      type: 'banner-section',
+      title: 'Plain heading',
+      // the post-reconnect state: linked to a bold heading tier, weight materialised to normal.
+      titleStyle: { textStyleType: 'heading1', fontWeight: 'normal' },
+    };
+
+    await convertPlainRteFields(
+      modelWithContent(content),
+      TextStyles.GetDefaultTextStyle().textStyleOptions,
+    );
+
+    const run = (
+      content.title as unknown as {
+        content: {
+          content: {
+            marks?: { type: string; attrs?: Record<string, string> }[];
+          }[];
+        }[];
+      }
+    ).content[0].content[0];
+    const weight = run.marks?.find((m) => m.type === 'textStyle')?.attrs
+      ?.fontWeight;
+
+    expect(weight).toBe('normal'); // literal override, NOT var(--role-font-weight) = bold
+  });
+
+  // S4 — this job bakes the block override + role typography onto the run with migration-22's
+  // local resolver snapshot. It preserves D3's current effective-role rule: a stored neutral is
+  // literal only when it differs from what the role actually resolves to, not merely its raw value.
+  it('bakes a neutral fontStyle/textDecoration/letterSpacing as a literal under a role that sets the opposite (D3)', async () => {
+    const options = TextStyles.GetDefaultTextStyle().textStyleOptions;
+
+    options.heading1.style.fontStyle = 'italic';
+    options.heading1.style.textDecoration = 'underline';
+    options.heading1.style.letterSpacing = '0.5px';
+
+    const content = {
+      type: 'banner-section',
+      title: 'Plain heading',
+      titleStyle: {
+        textStyleType: 'heading1',
+        fontStyle: 'normal',
+        textDecoration: 'none',
+        letterSpacing: 'normal',
+      },
+    };
+
+    await convertPlainRteFields(modelWithContent(content), options);
+
+    const run = (
+      content.title as unknown as {
+        content: {
+          content: {
+            marks?: { type: string; attrs?: Record<string, string> }[];
+          }[];
+        }[];
+      }
+    ).content[0].content[0];
+    const attrs = run.marks?.find((m) => m.type === 'textStyle')?.attrs;
+
+    expect(attrs?.fontStyle).toBe('normal'); // literal, NOT var(--role-font-style) = italic
+    expect(attrs?.textDecoration).toBe('none'); // literal, NOT var(--role-text-decoration)
+    expect(attrs?.letterSpacing).toBe('normal'); // literal, NOT var(--role-letter-spacing)
+  });
+
+  it('uses the migration-local typography snapshot, not the mutable render helper', async () => {
+    const runtimeFill = vi
+      .spyOn(textRoleCss, 'fillRteRunTypography')
+      .mockImplementation(() => {
+        throw new Error('runtime fill must not affect migration-22');
+      });
+    const runtimeWeightPin = vi
+      .spyOn(rteRoleLift, 'pinLegacyRunWeight')
+      .mockImplementation(() => {
+        throw new Error('runtime C3 pin must not affect migration-22');
+      });
+    const options = TextStyles.GetDefaultTextStyle().textStyleOptions;
+    const content = {
+      type: 'banner-section',
+      title: 'Frozen output',
+      titleStyle: {
+        textStyleType: 'heading1',
+        fontStyle: 'normal',
+      },
+    };
+
+    try {
+      await convertPlainRteFields(modelWithContent(content), options);
+
+      const attrs = (
+        content.title as unknown as {
+          content: {
+            content: {
+              marks: { type: string; attrs: Record<string, string> }[];
+            }[];
+          }[];
+        }
+      ).content[0].content[0].marks.find(
+        (mark) => mark.type === 'textStyle',
+      )?.attrs;
+
+      expect(runtimeFill).not.toHaveBeenCalled();
+      expect(runtimeWeightPin).not.toHaveBeenCalled();
+      expect(attrs?.fontStyle).toBe('var(--role-font-style)');
+    } finally {
+      runtimeFill.mockRestore();
+      runtimeWeightPin.mockRestore();
+    }
+  });
+
+  it('converts shop title (plain string) to a Tiptap doc — RTE restored (BP-5969)', async () => {
+    const content = {
+      type: 'shop-section',
+      title: 'My shop',
+      titleStyle: { textStyleType: 'heading1' },
+    };
+
+    await convertPlainRteFields(
+      modelWithContent(content),
+      TextStyles.GetDefaultTextStyle().textStyleOptions,
+    );
+
+    expect(isTiptapDocument(content.title)).toBe(true);
+  });
+
+  it('leaves an existing Tiptap doc untouched (no reconversion)', async () => {
+    const doc = docOf([{ text: 'Rich' }]);
+    const content = {
+      type: 'banner-section',
+      title: doc,
+      titleStyle: { textStyleType: 'heading1' },
+    };
+
+    await convertPlainRteFields(
+      modelWithContent(content),
+      TextStyles.GetDefaultTextStyle().textStyleOptions,
+    );
+
+    expect(content.title).toBe(doc); // same reference — untouched
+  });
+
+  it('converts a plain-string textItems[].text to a Tiptap doc', async () => {
+    const content = {
+      type: 'text',
+      textItems: [
+        { text: 'plain item', textStyle: { textStyleType: 'paragraph1' } },
+      ],
+    };
+
+    await convertPlainRteFields(
+      modelWithContent(content),
+      TextStyles.GetDefaultTextStyle().textStyleOptions,
+    );
+
+    expect(isTiptapDocument(content.textItems[0].text)).toBe(true);
+    expect(JSON.stringify(content.textItems[0].text)).toContain('plain item');
+  });
+
+  it('leaves an empty string alone', async () => {
+    const content = {
+      type: 'banner-section',
+      title: '',
+      titleStyle: { textStyleType: 'heading1' },
+    };
+
+    await convertPlainRteFields(
+      modelWithContent(content),
+      TextStyles.GetDefaultTextStyle().textStyleOptions,
+    );
+
+    expect(content.title).toBe('');
+  });
+
+  it('converts percent-encoded newlines (%0A) into hard breaks, not a literal run', async () => {
+    const content = {
+      type: 'banner-section',
+      title: 'Line one%0ALine two',
+      titleStyle: { textStyleType: 'heading1' },
+    };
+
+    await convertPlainRteFields(
+      modelWithContent(content),
+      TextStyles.GetDefaultTextStyle().textStyleOptions,
+    );
+
+    expect(isTiptapDocument(content.title)).toBe(true);
+
+    const runs = (
+      content.title as unknown as {
+        content: { content: { type: string; text?: string }[] }[];
+      }
+    ).content[0].content;
+
+    // The line break survives as text + hardBreak + text — never a literal "%0A".
+    expect(runs.some((n) => n.type === 'hardBreak')).toBe(true);
+    expect(JSON.stringify(content.title)).not.toContain('%0A');
+    expect(runs.filter((n) => n.type === 'text').map((n) => n.text)).toEqual([
+      'Line one',
+      'Line two',
+    ]);
+  });
+
+  // Regression (fa0e0db3 "Lift off"): a plain-text field carrying a block-level typography
+  // override never passed through job C (still a string), so the converted run must be baked
+  // here — else it holds colour only and the maker toolbar falls back to the role, showing the
+  // wrong font/size while the renderer still paints the override (editor ≠ render).
+  it('bakes the block-level typography override onto the converted run (role var or literal)', async () => {
+    const options = TextStyles.GetDefaultTextStyle().textStyleOptions;
+    const role = options.heading2.style;
+
+    role.fontFamily = 'Lato';
+    role.fontSize = '5.25em';
+    role.fontWeight = 'bold';
+
+    const content = {
+      type: 'banner-section',
+      title: 'Lift off',
+      titleStyle: {
+        textStyleType: 'heading2',
+        fontFamily: 'Playwrite AT', // block override ≠ role → literal
+        fontSize: '5.75em', // block override ≠ role → literal
+        fontWeight: 'bold', // equals role → role var (follows role edits)
+        fontStyle: 'normal', // inert neutral → role var
+        textDecoration: 'none', // inert neutral → role var
+      },
+    };
+
+    await convertPlainRteFields(modelWithContent(content), options);
+
+    const attrs = (
+      content.title as unknown as {
+        content: {
+          content: {
+            marks: { type: string; attrs: Record<string, string> }[];
+          }[];
+        }[];
+      }
+    ).content[0].content[0].marks.find((m) => m.type === 'textStyle')?.attrs;
+
+    // Genuine overrides ride through as raw literals — the toolbar reads the real font + size.
+    expect(attrs?.fontFamily).toBe('Playwrite AT');
+    expect(attrs?.fontSize).toBe('5.75em');
+    // Role-equal / inert-neutral attrs follow the role via its var (a role edit repaints them).
+    expect(attrs?.fontWeight).toBe('var(--role-font-weight)');
+    expect(attrs?.fontStyle).toBe('var(--role-font-style)');
+    expect(attrs?.textDecoration).toBe('var(--role-text-decoration)');
+  });
+});
+
+describe('migration-22 · clearRoleColours (E — retire role colour)', () => {
+  it('clears colour from every role definition', () => {
+    const options = TextStyles.GetDefaultTextStyle().textStyleOptions;
+
+    setRoleColor(options.heading1.style, '#ff0000');
+    setRoleColor(options.paragraph1.style, '#00ff00');
+
+    clearRoleColours(options);
+
+    expect(roleColorOf(options.heading1.style)).toBeUndefined();
+    expect(roleColorOf(options.paragraph1.style)).toBeUndefined();
+    // typography is untouched
+    expect(options.heading1.style.fontSize).toBeDefined();
+  });
+});
+
+describe('migration-22 · stripRteStyleColours (G — colour-decouple RTE style objects)', () => {
+  it('removes ONLY colour from an RTE-paired field (typography kept) and leaves non-RTE fields untouched', () => {
+    const content = {
+      type: 'shapes-section',
+      // titleStyle/descriptionStyle are RTE-paired on shapes → colour removed, typography kept
+      titleStyle: {
+        textStyleType: 'heading1',
+        color: '#ff0000',
+        fontSize: '2em',
+        textAlign: 'center',
+        applyAutoScale: true,
+      },
+      // headingStyle is a per-item style → NOT RTE → left fully intact (colour included)
+      headingStyle: {
+        textStyleType: 'heading2',
+        color: '#0000ff',
+        fontSize: '1em',
+      },
+    };
+
+    stripRteStyleColours(modelWithContent(content));
+
+    // colour gone; typography/textAlign/applyAutoScale (a real block override) preserved.
+    expect(content.titleStyle).toEqual({
+      textStyleType: 'heading1',
+      fontSize: '2em',
+      textAlign: 'center',
+      applyAutoScale: true,
+    });
+    expect(content.headingStyle).toEqual({
+      textStyleType: 'heading2',
+      color: '#0000ff',
+      fontSize: '1em',
+    });
+  });
+
+  it('strips shop titleStyle colour once it is doc-backed (shop is RTE, BP-5969)', () => {
+    const content = {
+      type: 'shop-section',
+      // colour now lives in the run mark, so G removes it from the style object; typography stays.
+      title: docOf([{ text: 'My shop', attrs: { color: '#ff0000' } }]),
+      titleStyle: {
+        textStyleType: 'heading1',
+        color: '#ff0000',
+        fontSize: '2em',
+      },
+    };
+
+    stripRteStyleColours(modelWithContent(content));
+
+    expect(content.titleStyle).toEqual({
+      textStyleType: 'heading1',
+      fontSize: '2em',
+    });
+  });
+
+  it('keeps colour on a plain-string RTE field (no mark) but strips a doc-backed sibling', () => {
+    const content = {
+      type: 'banner-section',
+      // plain string → colour lives on the object (its only home) → must survive G
+      title: 'Legacy plain title',
+      titleStyle: {
+        textStyleType: 'heading1',
+        color: '#ff0000',
+        fontSize: '2em',
+      },
+      // real doc → colour lives in the mark → style-object colour is stripped
+      description: docOf([{ text: 'Rich', attrs: { color: '#00ff00' } }]),
+      descriptionStyle: {
+        textStyleType: 'paragraph1',
+        color: '#00ff00',
+        fontSize: '1em',
+      },
+    };
+
+    stripRteStyleColours(modelWithContent(content));
+
+    expect(content.titleStyle).toEqual({
+      textStyleType: 'heading1',
+      color: '#ff0000',
+      fontSize: '2em',
+    });
+    expect(content.descriptionStyle).toEqual({
+      textStyleType: 'paragraph1',
+      fontSize: '1em',
+    });
+  });
+
+  it('keeps colour on a plain-string textItems[].text but strips a doc-backed one', () => {
+    const content = {
+      type: 'text',
+      textItems: [
+        {
+          text: 'legacy plain item',
+          textStyle: { textStyleType: 'paragraph1', color: '#111111' },
+        },
+        {
+          text: docOf([{ text: 'rich item', attrs: { color: '#222222' } }]),
+          textStyle: { textStyleType: 'paragraph2', color: '#222222' },
+        },
+      ],
+    };
+
+    stripRteStyleColours(modelWithContent(content));
+
+    expect(content.textItems[0].textStyle).toEqual({
+      textStyleType: 'paragraph1',
+      color: '#111111',
+    });
+    expect(content.textItems[1].textStyle).toEqual({
+      textStyleType: 'paragraph2',
+    });
+  });
+
+  it('removes colour from the text section textStyle and each textItems[].textStyle (typography kept)', () => {
+    const content = {
+      type: 'text',
+      textStyle: {
+        textStyleType: 'paragraph1',
+        color: '#ff0000',
+        fontSize: '1em',
+      },
+      textItems: [
+        {
+          textStyle: {
+            textStyleType: 'paragraph2',
+            color: '#00ff00',
+            applyAutoScale: false,
+          },
+        },
+      ],
+    };
+
+    stripRteStyleColours(modelWithContent(content));
+
+    expect(content.textStyle).toEqual({
+      textStyleType: 'paragraph1',
+      fontSize: '1em',
+    });
+    expect(content.textItems[0].textStyle).toEqual({
+      textStyleType: 'paragraph2',
+      applyAutoScale: false,
+    });
+  });
+});
+
+// The version gate owns "runs once" (v→22), so this is hygiene, not a correctness gate
+// (legacy-migrations rule): a re-run over already-converted output must be a no-op.
+describe('migration-22 · migration22 (idempotency hygiene)', () => {
+  const legacyModel = (): BrandPageModel =>
+    ({
+      pages: [
+        {
+          contents: [
+            {
+              type: 'banner-section',
+              title: 'Hello',
+              titleStyle: { textStyleType: 'titles' },
+            },
+          ],
+        },
+      ],
+      styles: {
+        textStyles: {
+          textStyleOptions: TextStyles.GetDefaultTextStyle().textStyleOptions,
+        },
+        buttonStyles: { style: {} },
+        colors: [],
+      },
+      brandPageType: 'default',
+    }) as unknown as BrandPageModel;
+
+  it('a second run over converted output changes nothing', async () => {
+    const once = await migration22(
+      { brandPageModel: legacyModel() } as MigrationData,
+      {} as MigrationOptions,
+    );
+    const snapshot = JSON.parse(JSON.stringify(once.brandPageModel));
+
+    const twice = await migration22(
+      {
+        brandPageModel: JSON.parse(JSON.stringify(once.brandPageModel)),
+      } as MigrationData,
+      {} as MigrationOptions,
+    );
+
+    expect(twice.brandPageModel).toEqual(snapshot);
+  });
+});
+
+// Production drew the payment success message with the description's style (`Payment.vue`). The
+// upgrade gives it its own, copied from the reconnected description, so it draws the same.
+describe('migration-22 · payment success message (R11)', () => {
+  const BUTTON_FILL = '#101010';
+  const BUTTON_TEXT = '#fafafa';
+
+  const paymentSite = (
+    content: Record<string, unknown>,
+    options: TextStyleOptions,
+  ): BrandPageModel =>
+    siteWith(
+      {
+        pages: [{ contents: [content] }],
+        styles: {
+          textStyles: { textFontFamily: 'lato', textStyleOptions: options },
+          buttonStyles: {
+            style: { backgroundColor: BUTTON_FILL, color: BUTTON_TEXT },
+          },
+          colors: [],
+        },
+      },
+      options,
+    );
+
+  const paymentContent = (
+    type: string,
+    extra: Record<string, unknown>,
+  ): Record<string, unknown> => ({
+    id: `${type}-1`,
+    type,
+    title: 'Pay',
+    description: 'Pay me',
+    successMessage: '',
+    ...extra,
+  });
+
+  // A site whose Paragraphs role differs from Paragraph 1, so its look stays as overrides.
+  const withCustomParagraphs = (): TextStyleOptions => {
+    const options = TextStyles.GetDefaultTextStyle().textStyleOptions;
+
+    options.paragraphs.style.fontFamily = 'Oswald';
+    options.paragraphs.style.fontSize = '1.125em';
+
+    return options;
+  };
+
+  const viewModelOf = (
+    content: unknown,
+    model: BrandPageModel,
+  ): Record<string, any> => {
+    const styles = pageStylesFor(model.styles.textStyles.textStyleOptions);
+
+    styles.buttonStyles.style = { ...model.styles.buttonStyles.style };
+
+    return mapToViewModel(
+      styles,
+      BRAND_PAGE_TYPES.brandSite,
+      {},
+    )(clone(content) as Content) as Record<string, any>;
+  };
+
+  const clone = <T>(value: T): T => JSON.parse(JSON.stringify(value));
+
+  const withoutColour = (style: Record<string, unknown>) => {
+    const { color: _color, ...rest } = style;
+
+    return rest;
+  };
+
+  it.each([
+    [
+      'support-me',
+      'a legacy role',
+      { textStyleType: 'paragraphs', textAlign: 'center' },
+    ],
+    [
+      'request-payment',
+      'a legacy role',
+      { textStyleType: 'paragraphs', textAlign: 'center' },
+    ],
+    [
+      'support-me',
+      'no role',
+      { fontSize: '1.25em', fontFamily: 'Oswald', textAlign: 'center' },
+    ],
+    [
+      'request-payment',
+      'no role',
+      { fontSize: '1.25em', fontFamily: 'Oswald', textAlign: 'center' },
+    ],
+  ] as const)(
+    'gives a %s success message the description on %s: its role and overrides, look kept',
+    async (type, _label, descriptionStyle) => {
+      const options = withCustomParagraphs();
+      const before = drawn(
+        productionTypography(
+          descriptionStyle as TextStyleDeclaration,
+          withCustomParagraphs(),
+        ),
+      );
+
+      const model = await runMigration22(
+        paymentSite(
+          paymentContent(type, { descriptionStyle: { ...descriptionStyle } }),
+          options,
+        ),
+      );
+      const after = model.pages[0].contents[0] as unknown as Record<
+        string,
+        any
+      >;
+
+      expect(after.successMessageStyle).toBeDefined();
+      expect(after.successMessageStyle).not.toBe(after.descriptionStyle);
+      expect(withoutColour(after.successMessageStyle)).toEqual(
+        withoutColour(after.descriptionStyle),
+      );
+
+      const vm = viewModelOf(after, model);
+
+      expect(drawn(vm.successMessageStyle, options)).toEqual(before);
+      expect(drawn(vm.successMessageStyle, options)).toEqual(
+        drawn(vm.descriptionStyle, options),
+      );
+    },
+  );
+
+  it.each(['support-me', 'request-payment'])(
+    'keeps the colour a %s success message drew from its description',
+    async (type) => {
+      const options = TextStyles.GetDefaultTextStyle().textStyleOptions;
+
+      // On the button fill, a description with no colour of its own drew the button text colour.
+      const onFill = await runMigration22(
+        paymentSite(
+          paymentContent(type, {
+            descriptionStyle: { textStyleType: 'paragraphs' },
+          }),
+          options,
+        ),
+      );
+
+      expect(
+        viewModelOf(onFill.pages[0].contents[0], onFill).successMessageStyle
+          .color,
+      ).toBe(BUTTON_TEXT);
+
+      // Its own colour (migration-21's frame bake) it keeps.
+      const ownColour = await runMigration22(
+        paymentSite(
+          paymentContent(type, {
+            backgroundStyle: { backgroundColor: '#ecb6d7' },
+            descriptionStyle: { textStyleType: 'paragraphs', color: '#654321' },
+          }),
+          TextStyles.GetDefaultTextStyle().textStyleOptions,
+        ),
+      );
+
+      expect(
+        viewModelOf(ownColour.pages[0].contents[0], ownColour)
+          .successMessageStyle.color,
+      ).toBe('#654321');
+    },
+  );
+
+  it('keeps a success message style of its own, and leaves the message untouched', async () => {
+    const options = TextStyles.GetDefaultTextStyle().textStyleOptions;
+    const successMessage = {
+      type: 'doc',
+      content: [
+        {
+          type: 'paragraph',
+          content: [
+            {
+              type: 'text',
+              text: 'Thanks!',
+              marks: [{ type: 'textStyle', attrs: { color: '#e11d48' } }],
+            },
+          ],
+        },
+      ],
+    };
+
+    const model = await runMigration22(
+      paymentSite(
+        paymentContent('support-me', {
+          successMessage: clone(successMessage),
+          successMessageStyle: { textStyleType: 'heading6' },
+          descriptionStyle: { textStyleType: 'paragraphs' },
+        }),
+        options,
+      ),
+    );
+    const after = model.pages[0].contents[0] as unknown as Record<string, any>;
+
+    expect(after.successMessageStyle.textStyleType).toBe('heading6');
+    expect(after.successMessage).toEqual(successMessage);
+  });
+
+  // The old maker editor wrote `{ textAlign }` here, but production never drew it.
+  it.each(['support-me', 'request-payment'])(
+    'replaces a %s success message style it never drew with a copy of the description',
+    async (type) => {
+      const options = withCustomParagraphs();
+      const descriptionStyle = {
+        textStyleType: 'paragraphs',
+        textAlign: 'center',
+      };
+      const before = drawn(
+        productionTypography(
+          descriptionStyle as TextStyleDeclaration,
+          withCustomParagraphs(),
+        ),
+      );
+
+      const model = await runMigration22(
+        paymentSite(
+          paymentContent(type, {
+            descriptionStyle: { ...descriptionStyle },
+            successMessageStyle: { textAlign: 'left' },
+          }),
+          options,
+        ),
+      );
+      const after = model.pages[0].contents[0] as unknown as Record<
+        string,
+        any
+      >;
+
+      expect(withoutColour(after.successMessageStyle)).toEqual(
+        withoutColour(after.descriptionStyle),
+      );
+      expect(
+        drawn(viewModelOf(after, model).successMessageStyle, options),
+      ).toEqual(before);
+    },
+  );
+
+  it.each(['support-me', 'request-payment'])(
+    'starts a %s success message with no description on Paragraph 2, keeping the page defaults it drew',
+    async (type) => {
+      const options = withCustomParagraphs();
+      const model = await runMigration22(
+        paymentSite(paymentContent(type, { successMessage: '' }), options),
+      );
+      const after = model.pages[0].contents[0] as unknown as Record<
+        string,
+        any
+      >;
+      const vm = viewModelOf(after, model);
+
+      expect(after.successMessageStyle.textStyleType).toBe('paragraph2');
+      // S5 — the drawn look it kept is pinned as literal overrides (the reconnect's inherited-
+      // font-size/DETACHED_UNSET_EFFECTIVE pins), not paragraph2's real role default, so the
+      // RHS stays `drawn(undefined)` (the pinned values happen to equal the generic no-role
+      // draw). Passing `options` on the LHS only is what makes this catch a missing pin: an
+      // un-pinned prop would fall through to paragraph2's REAL default (1.125em/1.5em) instead
+      // of coincidentally matching the RHS, where the old comparison (no options either side)
+      // couldn't tell the two apart.
+      expect(drawn(vm.successMessageStyle, options)).toEqual(drawn(undefined));
+      // It inherited the frame's colour, the button text colour on the button fill.
+      expect(vm.successMessageStyle.color).toBe(BUTTON_TEXT);
+    },
+  );
+
+  // A rich-text run draws from its marks, filled at render against its role (`TextWrapper`); a role
+  // var draws the role's value, or the neutral the role class emits for one it leaves unset.
+  const drawnRun = (
+    doc: unknown,
+    style: Record<string, unknown> | undefined,
+    role: Record<string, unknown> | undefined,
+  ): Record<string, string | undefined> => {
+    const filled = textRoleCss.fillRteRunTypography(
+      doc as never,
+      role as never,
+      style as never,
+    ) as {
+      content: {
+        content: {
+          marks?: { type: string; attrs: Record<string, string> }[];
+        }[];
+      }[];
+    };
+    const attrs =
+      filled.content[0].content[0].marks?.find(
+        (mark) => mark.type === 'textStyle',
+      )?.attrs ?? {};
+    const neutral: Record<string, string> = {
+      fontWeight: 'normal',
+      fontStyle: 'normal',
+      textDecoration: 'none',
+      letterSpacing: 'normal',
+    };
+
+    return Object.fromEntries(
+      TEXT_STYLE_CASCADE_PROPS.map((prop) => {
+        const value = attrs[prop];
+
+        if (!value) return [prop, drawn(undefined)[prop]];
+
+        if (value.startsWith('var(--role-'))
+          return [prop, (role?.[prop] as string) || neutral[prop]];
+
+        return [prop, value.replace(/['"]/g, '')];
+      }),
+    );
+  };
+
+  // migration-21 wrapped a non-empty message into a doc whose runs carry only colour, and
+  // production's `TextWrapper` gave rich text no typography from its style object.
+  it.each([
+    ['support-me', 'a legacy role', { textStyleType: 'paragraphs' }],
+    ['request-payment', 'a legacy role', { textStyleType: 'paragraphs' }],
+    ['support-me', 'no role', { fontSize: '1.25em', fontFamily: 'Oswald' }],
+    [
+      'request-payment',
+      'no role',
+      { fontSize: '1.25em', fontFamily: 'Oswald' },
+    ],
+  ] as const)(
+    'keeps a rich-text %s success message drawing the page defaults, on the role of its description on %s',
+    async (type, _label, descriptionStyle) => {
+      const options = withCustomParagraphs();
+      const successMessage = {
+        type: 'doc',
+        content: [
+          {
+            type: 'paragraph',
+            attrs: { textAlign: 'center' },
+            content: [
+              {
+                type: 'text',
+                text: 'Thanks!',
+                marks: [{ type: 'textStyle', attrs: { color: '#654321' } }],
+              },
+            ],
+          },
+        ],
+      };
+      const before = drawnRun(successMessage, undefined, undefined);
+
+      const model = await runMigration22(
+        paymentSite(
+          paymentContent(type, {
+            successMessage: clone(successMessage),
+            descriptionStyle: { ...descriptionStyle, textAlign: 'center' },
+          }),
+          options,
+        ),
+      );
+      const after = model.pages[0].contents[0] as unknown as Record<
+        string,
+        any
+      >;
+      const style = after.successMessageStyle;
+
+      expect(style.textStyleType).toBe(after.descriptionStyle.textStyleType);
+      expect(
+        drawnRun(
+          after.successMessage,
+          style,
+          roleStyleOf(options, style.textStyleType) as never,
+        ),
+      ).toEqual(before);
+      expect(runMarkColor(after.successMessage)).toBe('#654321');
+    },
+  );
+
+  // migration-21 actually bakes the description's fontFamily/fontSize onto the run too
+  // (migration-21.ts:760-765), not colour alone — a doc from that step already carries them, and
+  // re-lifting it for migration-22's role must leave what it drew unchanged.
+  it('keeps a rich-text support-me success message drawing what migration-21 already baked onto its runs', async () => {
+    const options = withCustomParagraphs();
+    const descriptionStyle = {
+      fontSize: '1.25em',
+      fontFamily: 'Oswald',
+      textAlign: 'center' as const,
+    };
+    const successMessage = {
+      type: 'doc',
+      content: [
+        {
+          type: 'paragraph',
+          attrs: { textAlign: 'center' },
+          content: [
+            {
+              type: 'text',
+              text: 'Thanks!',
+              marks: [
+                {
+                  type: 'textStyle',
+                  attrs: {
+                    color: '#654321',
+                    fontFamily: descriptionStyle.fontFamily,
+                    fontSize: descriptionStyle.fontSize,
+                  },
+                },
+              ],
+            },
+          ],
+        },
+      ],
+    };
+    const before = drawnRun(successMessage, undefined, undefined);
+
+    const model = await runMigration22(
+      paymentSite(
+        paymentContent('support-me', {
+          successMessage: clone(successMessage),
+          descriptionStyle,
+        }),
+        options,
+      ),
+    );
+    const after = model.pages[0].contents[0] as unknown as Record<string, any>;
+    const style = after.successMessageStyle;
+
+    expect(style.textStyleType).toBe(after.descriptionStyle.textStyleType);
+    expect(
+      drawnRun(
+        after.successMessage,
+        style,
+        roleStyleOf(options, style.textStyleType) as never,
+      ),
+    ).toEqual(before);
+    expect(runMarkColor(after.successMessage)).toBe('#654321');
+  });
+
+  // The shop checkout (`PaymentModal.vue`) drew its message with only the description's colour.
+  it.each([
+    ['its own colour', { textStyleType: 'paragraphs', color: '#654321' }],
+    ['its role colour', { textStyleType: 'paragraphs' }],
+  ] as const)(
+    'starts the shop checkout success message on Paragraph 2, keeping the page defaults and the description colour (%s)',
+    async (_label, descriptionStyle) => {
+      const options = withCustomParagraphs();
+
+      (options.paragraphs.style as unknown as Record<string, string>).color =
+        '#123456';
+
+      const model = await runMigration22(
+        paymentSite(
+          {
+            id: 'shop-1',
+            type: 'shop-section',
+            title: 'Shop',
+            description: '',
+            successMessage: 'Thanks!',
+            descriptionStyle: { ...descriptionStyle },
+            successMessageStyle: { textAlign: 'left' },
+          },
+          options,
+        ),
+      );
+      const after = model.pages[0].contents[0] as unknown as Record<
+        string,
+        any
+      >;
+      const vm = viewModelOf(after, model);
+
+      expect(after.successMessageStyle.textStyleType).toBe('paragraph2');
+      // S5 — see the support-me/request-payment case above: the RHS stays `drawn(undefined)`
+      // (the pinned drawn look happens to equal the generic no-role draw); passing `options` on
+      // the LHS only is what makes this catch a missing pin.
+      expect(drawn(vm.successMessageStyle, options)).toEqual(drawn(undefined));
+      expect(vm.successMessageStyle.color).toBe(
+        (descriptionStyle as { color?: string }).color ?? '#123456',
+      );
+      expect(vm.successMessageStyle.color).toBe(vm.descriptionStyle.color);
+      expect(vm.successMessageStyle.textAlign).toBe('center');
+    },
+  );
+
+  // A description on no role and with no colour gave the modal `inherit`: fe-shared-lib's `Modal`
+  // sets no colour, so it drew the page root's, the Paragraphs colour (`Page.mixin`
+  // `rootElementStyles`). Never the colour of the tier the description reconnects to.
+  it('keeps the page colour a shop checkout success message inherited from a description on no role', async () => {
+    const options = withCustomParagraphs();
+    const colourOf = (type: TextStyleType, color: string) => {
+      (options[type].style as unknown as Record<string, string>).color = color;
+    };
+
+    colourOf('paragraphs', '#123456');
+    colourOf('paragraph3', '#abcdef');
+
+    const model = await runMigration22(
+      paymentSite(
+        {
+          id: 'shop-1',
+          type: 'shop-section',
+          title: 'Shop',
+          description: '',
+          successMessage: 'Thanks!',
+          // Paragraph 3's size, so the description reconnects to a tier with its own colour.
+          descriptionStyle: { fontSize: '0.875em' },
+        },
+        options,
+      ),
+    );
+    const after = model.pages[0].contents[0] as unknown as Record<string, any>;
+
+    expect(after.descriptionStyle.textStyleType).toBe('paragraph3');
+    expect(viewModelOf(after, model).successMessageStyle.color).toBe('#123456');
+  });
+});