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

package/src/brand-page-maker/utils/rich-text-editor.util.test.ts

@@ -1,12 +1,11 @@
-import { describe, it, expect, vi, type Mock } from 'vitest';
+import { describe, it, expect, vi, afterAll, type Mock } from 'vitest';
 import type { Transaction } from 'prosemirror-state';
-import type { ChainedCommands, Editor } from '@tiptap/vue-3';
+import type { ChainedCommands } from '@tiptap/vue-3';
 import {
   isStyleChanged,
   skipStyleDetection,
   hasRTEContent,
   isRteHtmlString,
-  getUpdatedHTMLFromEditor,
   sanitiseClientSideRTE,
   getRTEColor,
   isColorVar,
@@ -14,8 +13,18 @@ import {
   getToolbarColorFromMark,
   resolveToolbarTextColor,
   resolveInitialToolbarTextColor,
-  transformToRTE,
+  buildInitialMarks,
+  isCanonicalLinked,
+  isRoleVarRef,
+  normTypographyValue,
+  roleVarOrLiteral,
+  relinkRoleEqualMarks,
+  relinkDocToRole,
+  mergePickedMarks,
 } from './rich-text-editor.util';
+import { Editor } from '@tiptap/vue-3';
+import { getRteExtensions } from '@shared/rte-extensions.util';
+import { roleVarRef } from '@shared/text-role-typography.util';
 import type { TextStyleDeclaration } from '@brand-page';
 
 describe('isStyleChanged', () => {
@@ -179,412 +188,6 @@ describe('getRteTextLength', () => {
   });
 });
 
-describe('getUpdatedHTMLFromEditor', () => {
-  it('applies style commands and returns updated JSON', () => {
-    // Mock editor
-    const runMock = vi.fn();
-    const chain = {
-      selectAll: () => chain,
-      setFontFamily: () => chain,
-      setFontSize: () => chain,
-      setLetterSpacing: () => chain,
-      setLineHeight: () => chain,
-      setMark: () => chain,
-      setStrike: () => chain,
-      unsetStrike: () => chain,
-      setUnderline: () => chain,
-      unsetUnderline: () => chain,
-      setBold: () => chain,
-      unsetBold: () => chain,
-      setItalic: () => chain,
-      unsetItalic: () => chain,
-      run: runMock,
-    };
-
-    const externalEditor = {
-      commands: {
-        setContent: vi.fn(),
-      },
-      getAttributes: vi.fn(() => ({
-        fontFamily: 'Arial',
-        fontSize: '2.5em',
-        letterSpacing: '1.2',
-        lineHeight: '1.5',
-        color: '#333',
-        textDecoration: 'underline line-through',
-        fontWeight: 'bold',
-        fontStyle: 'italic',
-      })),
-      state: {
-        selection: {
-          $anchor: {
-            node: () => ({ type: { name: 'paragraph' } }),
-          },
-        },
-      },
-      chain: () => chain as any,
-      getJSON: () => ({ type: 'doc', content: [{ type: 'paragraph' }] }),
-    } as unknown as Editor;
-
-    const newStyle = {
-      fontFamily: 'Arial',
-      fontSize: '2.5em',
-      letterSpacing: '1.2',
-      lineHeight: '1.5',
-      color: '#333',
-      textDecoration: 'underline line-through',
-      fontWeight: 'bold',
-      fontStyle: 'italic',
-    } as TextStyleDeclaration;
-
-    const result = getUpdatedHTMLFromEditor(externalEditor, 'foo', newStyle);
-
-    expect(externalEditor.commands.setContent).toHaveBeenCalledWith('foo');
-    expect(runMock).toHaveBeenCalled();
-    // BP-5787: returns the JSON form (consistent with JSON storage).
-    expect(result).toEqual({ type: 'doc', content: [{ type: 'paragraph' }] });
-  });
-});
-
-describe('transformToRTE — element-first colour (BP-5886)', () => {
-  // The plain→RTE rewrap (on section select / add) bakes the linked global text style
-  // into the title's marks. It must honour an element-level colour override
-  // (a creation-time contrast bake, or a colour picked while linked) instead of
-  // overpainting it with the global colour — mirroring `resolveTextColor`.
-  const buildEditor = () => {
-    const setMarkCalls: { name: string; attrs: any }[] = [];
-    const chain: any = new Proxy(
-      {},
-      {
-        get(_t, prop) {
-          if (prop === 'run') return () => undefined;
-
-          if (prop === 'setMark')
-            return (name: string, attrs: any) => {
-              setMarkCalls.push({ name, attrs });
-
-              return chain;
-            };
-
-          return () => chain;
-        },
-      },
-    );
-
-    const editor = {
-      commands: { setContent: vi.fn() },
-      getAttributes: () => ({}),
-      state: {
-        selection: {
-          $anchor: { node: () => ({ type: { name: 'paragraph' } }) },
-        },
-      },
-      chain: () => chain,
-      getJSON: () => ({ type: 'doc', content: [{ type: 'paragraph' }] }),
-    } as unknown as Editor;
-
-    return { editor, setMarkCalls };
-  };
-
-  const styleStore = (headingsColor: string) =>
-    ({
-      textStyles: {
-        textStyleOptions: {
-          headings: {
-            style: {
-              color: headingsColor,
-              fontFamily: 'Lato',
-              fontSize: '1.5em',
-            },
-          },
-        },
-      },
-    }) as any;
-
-  const pageStoreWithMailingList = (titleStyle: any) =>
-    ({
-      pages: [
-        {
-          contents: [
-            {
-              id: 'ml',
-              type: 'mailing-list',
-              settings: {
-                content: {
-                  id: 'ml',
-                  type: 'mailing-list',
-                  title: 'Join mailing list',
-                  titleStyle,
-                },
-              },
-            },
-          ],
-        },
-      ],
-    }) as any;
-
-  const textStyleColor = (calls: { name: string; attrs: any }[]) =>
-    calls.find((c) => c.name === 'textStyle')?.attrs?.color as
-      | string
-      | undefined;
-
-  it('bakes the element colour override into the title mark, not the global colour', () => {
-    const { editor, setMarkCalls } = buildEditor();
-
-    transformToRTE(
-      pageStoreWithMailingList({
-        textStyleType: 'headings',
-        textAlign: 'center',
-        color: 'var(--palette-1)', // the contrast bake / linked override
-      }),
-      editor,
-      styleStore('var(--palette-0)'), // global headings colour differs
-    );
-
-    expect(textStyleColor(setMarkCalls)).toContain('palette-1');
-    expect(textStyleColor(setMarkCalls)).not.toContain('palette-0');
-  });
-
-  it('falls back to the global colour when the element has none (no regression)', () => {
-    const { editor, setMarkCalls } = buildEditor();
-
-    transformToRTE(
-      pageStoreWithMailingList({
-        textStyleType: 'headings',
-        textAlign: 'center',
-      }),
-      editor,
-      styleStore('var(--palette-0)'),
-    );
-
-    expect(textStyleColor(setMarkCalls)).toContain('palette-0');
-  });
-});
-
-describe('transformToRTE — respects existing RTE marks on selection (BP-5886)', () => {
-  // Section-select / add-content call transformToRTE with the style store (store-driven),
-  // which walks EVERY section. Before the fix it re-derived `element || global` and
-  // `selectAll().setMark`'d it over every linked field's mark — flipping migrated frame
-  // colours to the global site-wide the moment any section was selected. A global-style
-  // *edit* (type-driven) must still re-stamp existing RTE to propagate the change.
-  const RESTAMPED = {
-    type: 'doc',
-    content: [{ type: 'paragraph', restamped: true }],
-  };
-
-  const buildEditor = () => {
-    const chain: any = new Proxy(
-      {},
-      {
-        get(_t, prop) {
-          if (prop === 'run') return () => undefined;
-
-          return () => chain;
-        },
-      },
-    );
-
-    return {
-      commands: { setContent: vi.fn() },
-      getAttributes: () => ({}),
-      state: {
-        selection: {
-          $anchor: { node: () => ({ type: { name: 'paragraph' } }) },
-        },
-      },
-      chain: () => chain,
-      getJSON: () => RESTAMPED,
-    } as unknown as Editor;
-  };
-
-  const styleStore = () =>
-    ({
-      textStyles: {
-        textStyleOptions: {
-          headings: {
-            style: { color: 'var(--palette-1)', fontFamily: 'Lato' },
-          },
-        },
-      },
-    }) as any;
-
-  // titleStyle links to the headings global with NO element colour override — the exact
-  // legacy shape the migration bake leaves (mark carries the colour, element style blank).
-  const pageStoreWithTitle = (title: unknown) =>
-    ({
-      pages: [
-        {
-          contents: [
-            {
-              id: 'ml',
-              type: 'mailing-list',
-              settings: {
-                content: {
-                  id: 'ml',
-                  type: 'mailing-list',
-                  title,
-                  titleStyle: {
-                    textStyleType: 'headings',
-                    textAlign: 'center',
-                  },
-                },
-              },
-            },
-          ],
-        },
-      ],
-    }) as any;
-
-  const existingRteTitle = () => ({
-    type: 'doc',
-    content: [
-      {
-        type: 'paragraph',
-        content: [
-          {
-            type: 'text',
-            text: 'Join mailing list',
-            marks: [
-              { type: 'textStyle', attrs: { color: 'var(--palette-0)' } },
-            ],
-          },
-        ],
-      },
-    ],
-  });
-
-  // A `text` section — single-block (`text` + section-level `textStyle`, the
-  // brandPage/brandContact shape) or per-item (`textItems`, brandSite). These exercise the
-  // other two rewrap blocks in `transformToRTE`, distinct from the field-pair path above.
-  const pageStoreWithSingleBlockText = (text: unknown) =>
-    ({
-      pages: [
-        {
-          contents: [
-            {
-              id: 't',
-              type: 'text',
-              settings: {
-                content: {
-                  id: 't',
-                  type: 'text',
-                  text,
-                  textStyle: { textStyleType: 'paragraphs', textAlign: 'left' },
-                },
-              },
-            },
-          ],
-        },
-      ],
-    }) as any;
-
-  const pageStoreWithTextItem = (text: unknown) =>
-    ({
-      pages: [
-        {
-          contents: [
-            {
-              id: 't',
-              type: 'text',
-              settings: {
-                content: {
-                  id: 't',
-                  type: 'text',
-                  textItems: [
-                    {
-                      id: 'i',
-                      text,
-                      textStyle: {
-                        textStyleType: 'paragraphs',
-                        textAlign: 'left',
-                      },
-                    },
-                  ],
-                },
-              },
-            },
-          ],
-        },
-      ],
-    }) as any;
-
-  it('store-driven select leaves an already-RTE mark untouched', () => {
-    // The fix-pinning case: this one FAILS on the pre-fix guard (which re-stamped every
-    // already-RTE field on any select). The two positive tests below also pass pre-fix.
-    const editor = buildEditor();
-    const title = existingRteTitle();
-    const pageStore = pageStoreWithTitle(title);
-
-    // Store-driven (section-select): no `type`, style store present.
-    transformToRTE(pageStore, editor, styleStore());
-
-    const content = pageStore.pages[0].contents[0].settings.content;
-
-    expect(content.title).toBe(title); // same reference — never rewrapped
-    expect(editor.commands.setContent).not.toHaveBeenCalled();
-  });
-
-  it('store-driven select leaves an already-RTE single-block text section untouched', () => {
-    const editor = buildEditor();
-    const text = existingRteTitle();
-    const pageStore = pageStoreWithSingleBlockText(text);
-
-    transformToRTE(pageStore, editor, styleStore());
-
-    const content = pageStore.pages[0].contents[0].settings.content;
-
-    expect(content.text).toBe(text); // single-block `text` path — mark preserved
-    expect(editor.commands.setContent).not.toHaveBeenCalled();
-  });
-
-  it('store-driven select leaves an already-RTE text item untouched', () => {
-    const editor = buildEditor();
-    const text = existingRteTitle();
-    const pageStore = pageStoreWithTextItem(text);
-
-    transformToRTE(pageStore, editor, styleStore());
-
-    const item = pageStore.pages[0].contents[0].settings.content.textItems[0];
-
-    expect(item.text).toBe(text); // `textItems` loop — mark preserved
-    expect(editor.commands.setContent).not.toHaveBeenCalled();
-  });
-
-  it('store-driven select still converts a genuine plain-text field to RTE', () => {
-    const editor = buildEditor();
-    const pageStore = pageStoreWithTitle('Join mailing list');
-
-    transformToRTE(pageStore, editor, styleStore());
-
-    const content = pageStore.pages[0].contents[0].settings.content;
-
-    expect(content.title).toBe(RESTAMPED); // plain string → converted
-    expect(editor.commands.setContent).toHaveBeenCalled();
-  });
-
-  it('type-driven global-style change still re-stamps an already-RTE field', () => {
-    const editor = buildEditor();
-    const pageStore = pageStoreWithTitle(existingRteTitle());
-
-    // Type-driven (global-style edit): `type` matches, no style store.
-    transformToRTE(
-      pageStore,
-      editor,
-      undefined,
-      undefined,
-      'headings' as any,
-      {
-        color: 'var(--palette-1)',
-      } as any,
-    );
-
-    const content = pageStore.pages[0].contents[0].settings.content;
-
-    expect(content.title).toBe(RESTAMPED); // propagated the global edit into the mark
-    expect(editor.commands.setContent).toHaveBeenCalled();
-  });
-});
-
 describe('sanitiseClientSideRTE', () => {
   it('removes forbidden tags entirely', () => {
     const input =
@@ -1166,3 +769,437 @@ describe('resolveInitialToolbarTextColor (BP-5886)', () => {
     expect(resolveInitialToolbarTextColor(undefined)).toBe('#000000');
   });
 });
+
+describe('buildInitialMarks — BP-5969 bakeTypography gate', () => {
+  const buildState = () => {
+    const created: { type: string; attrs: any }[] = [];
+    const markFactory = (type: string) => ({
+      create: (attrs: any = {}) => {
+        created.push({ type, attrs });
+
+        return { type, attrs };
+      },
+    });
+    const state = {
+      schema: {
+        marks: {
+          textStyle: markFactory('textStyle'),
+          highlight: markFactory('highlight'),
+          bold: markFactory('bold'),
+          italic: markFactory('italic'),
+          underline: markFactory('underline'),
+          strike: markFactory('strike'),
+        },
+      },
+    } as any;
+
+    return { state, created };
+  };
+
+  const fullStyle = {
+    fontFamily: 'Lato',
+    fontSize: '2.5em',
+    color: 'red',
+    lineHeight: '1.2',
+    letterSpacing: '0.1em',
+    fontWeight: 'bold',
+    fontStyle: 'italic',
+    textDecoration: 'underline line-through',
+  } as TextStyleDeclaration;
+
+  it('references the role via vars when bakeTypography is false (class supplies typography)', () => {
+    const { state, created } = buildState();
+
+    buildInitialMarks(state, fullStyle, false);
+
+    const textStyle = created.find((m) => m.type === 'textStyle');
+
+    expect(textStyle?.attrs).toEqual({
+      color: expect.stringContaining('red'),
+      fontFamily: 'var(--role-font-family)',
+      fontSize: 'var(--role-font-size)',
+      lineHeight: 'var(--role-line-height)',
+      letterSpacing: 'var(--role-letter-spacing)',
+      // BP-5969 Phase A: weight/style/decoration are var-backed textStyle attrs too, so linked text
+      // references the role for these — not baked as semantic <strong>/<u> marks.
+      fontWeight: 'var(--role-font-weight)',
+      fontStyle: 'var(--role-font-style)',
+      textDecoration: 'var(--role-text-decoration)',
+    });
+    // …and NOT as per-run semantic marks
+    expect(created.some((m) => m.type === 'bold')).toBe(false);
+    expect(created.some((m) => m.type === 'italic')).toBe(false);
+    expect(created.some((m) => m.type === 'underline')).toBe(false);
+  });
+
+  it('bakes full typography when bakeTypography is true (default)', () => {
+    const { state, created } = buildState();
+
+    buildInitialMarks(state, fullStyle);
+
+    const textStyle = created.find((m) => m.type === 'textStyle');
+
+    expect(textStyle?.attrs.fontFamily).toBe('Lato');
+    expect(textStyle?.attrs.fontSize).toBe('2.5em');
+    expect(created.some((m) => m.type === 'bold')).toBe(true);
+    expect(created.some((m) => m.type === 'underline')).toBe(true);
+  });
+
+  it('omits the empty textStyle mark when there is nothing to reference or bake', () => {
+    const { state, created } = buildState();
+
+    // no typography and no colour → nothing to reference → no textStyle mark at all
+    buildInitialMarks(state, {} as TextStyleDeclaration, false);
+
+    expect(created.some((m) => m.type === 'textStyle')).toBe(false);
+  });
+});
+
+describe('roleVarOrLiteral / isRoleVarRef / normTypographyValue (BP-5969)', () => {
+  const role = {
+    fontFamily: 'Pacifico',
+    fontSize: '2.25em',
+  } as TextStyleDeclaration;
+
+  it('writes the role var when the pick equals the role (re-links)', () => {
+    expect(roleVarOrLiteral('fontFamily', 'Pacifico', role)).toBe(
+      'var(--role-font-family)',
+    );
+  });
+
+  it('writes the literal when the pick differs from the role (override)', () => {
+    expect(roleVarOrLiteral('fontFamily', 'Inter', role)).toBe('Inter');
+  });
+
+  it('normalises quotes/whitespace so a quoted family still matches the role', () => {
+    expect(roleVarOrLiteral('fontFamily', '"Pacifico"', role)).toBe(
+      'var(--role-font-family)',
+    );
+  });
+
+  it('always writes the literal for a legacy/unlinked block (no role)', () => {
+    expect(roleVarOrLiteral('fontFamily', 'Pacifico', undefined)).toBe(
+      'Pacifico',
+    );
+  });
+
+  it('the Pacifico → Inter → Pacifico round-trip re-links (no pin)', () => {
+    expect(roleVarOrLiteral('fontFamily', 'Inter', role)).toBe('Inter');
+    // returning to the role value stores the ref, not a baked literal
+    expect(roleVarOrLiteral('fontFamily', 'Pacifico', role)).toBe(
+      'var(--role-font-family)',
+    );
+  });
+
+  it('isRoleVarRef distinguishes a role ref from a literal', () => {
+    expect(isRoleVarRef('var(--role-font-family)')).toBe(true);
+    expect(isRoleVarRef('var(--palette-3)')).toBe(false);
+    expect(isRoleVarRef('Pacifico')).toBe(false);
+    expect(isRoleVarRef(undefined)).toBe(false);
+  });
+
+  it('normTypographyValue strips quotes for fontFamily only', () => {
+    expect(normTypographyValue('fontFamily', ' "Open Sans" ')).toBe(
+      'Open Sans',
+    );
+    expect(normTypographyValue('fontSize', ' 2em ')).toBe('2em');
+  });
+
+  it('normTypographyValue folds a prop default keyword to empty (normal/none == unset)', () => {
+    // A prop's CSS default keyword renders identically to the prop being absent, so both normalise
+    // to '' — a block's `normal`/`none` matches a role that simply omits the prop (no false override).
+    expect(normTypographyValue('fontWeight', 'normal')).toBe('');
+    expect(normTypographyValue('fontStyle', 'normal')).toBe('');
+    expect(normTypographyValue('textDecoration', 'none')).toBe('');
+    expect(normTypographyValue('letterSpacing', 'normal')).toBe('');
+    expect(normTypographyValue('lineHeight', 'normal')).toBe('');
+    expect(normTypographyValue('fontWeight', undefined)).toBe('');
+    expect(normTypographyValue('fontWeight', '')).toBe('');
+  });
+
+  it('normTypographyValue keeps a real value and folds only the matching key', () => {
+    expect(normTypographyValue('fontWeight', 'bold')).toBe('bold');
+    expect(normTypographyValue('fontStyle', 'italic')).toBe('italic');
+    expect(normTypographyValue('textDecoration', 'underline')).toBe(
+      'underline',
+    );
+    // 'none' is only the default for textDecoration; for fontWeight it is a plain value, not folded.
+    expect(normTypographyValue('fontWeight', 'none')).toBe('none');
+    // fontFamily has no default keyword — a family literally named 'normal' is kept.
+    expect(normTypographyValue('fontFamily', 'normal')).toBe('normal');
+  });
+
+  it('roleVarOrLiteral re-links when block default keyword equals the role default (normal)', () => {
+    const bodyRole = { fontWeight: 'normal' } as TextStyleDeclaration;
+
+    // Toggling bold OFF writes 'normal'; against a role whose weight is 'normal' it must re-link,
+    // not pin a redundant literal.
+    expect(roleVarOrLiteral('fontWeight', 'normal', bodyRole)).toBe(
+      'var(--role-font-weight)',
+    );
+  });
+});
+
+describe('isCanonicalLinked (BP-5969)', () => {
+  it('is true only for a canonical role type', () => {
+    expect(isCanonicalLinked({ textStyleType: 'heading1' })).toBe(true);
+    expect(isCanonicalLinked({ textStyleType: 'button' })).toBe(true);
+    expect(isCanonicalLinked({ textStyleType: 'headings' })).toBe(false); // legacy
+    expect(isCanonicalLinked({ textStyleType: undefined })).toBe(false);
+    expect(isCanonicalLinked(undefined)).toBe(false);
+  });
+});
+
+describe('relinkRoleEqualMarks (R8 sibling relink)', () => {
+  const NEW_ROLE = {
+    fontFamily: 'Oswald',
+    fontSize: '3.5em',
+    fontWeight: 'bold',
+  };
+  const OLD_ROLE = {
+    fontFamily: 'Lato',
+    fontSize: '3.1875em',
+    fontWeight: 'bold',
+  };
+
+  const run = (attrs: Record<string, unknown>, extraMarks: object[] = []) => ({
+    type: 'text',
+    text: 'x',
+    marks: [{ type: 'textStyle', attrs }, ...extraMarks],
+  });
+  const docOf = (...runs: object[]) => ({
+    type: 'doc',
+    content: [{ type: 'paragraph', content: runs }],
+  });
+  const marksOf = (doc: unknown, index: number) =>
+    (
+      doc as {
+        content: {
+          content: {
+            marks: { type: string; attrs?: Record<string, unknown> }[];
+          }[];
+        }[];
+      }
+    ).content[0].content[index].marks;
+  const textStyleOf = (doc: unknown, index: number) =>
+    marksOf(doc, index).find((mark) => mark.type === 'textStyle')?.attrs;
+
+  it('relinkRoleEqualMarks relinks each run on its own: new-role and old-role literals, not a real override', () => {
+    const doc = docOf(
+      run({ fontSize: '3.5em' }),
+      run({ fontFamily: 'Lato' }),
+      run({ fontSize: '4em' }),
+    );
+
+    const out = relinkRoleEqualMarks(doc, [NEW_ROLE, OLD_ROLE]);
+
+    expect(textStyleOf(out, 0)?.fontSize).toBe(roleVarRef('fontSize'));
+    expect(textStyleOf(out, 1)?.fontFamily).toBe(roleVarRef('fontFamily'));
+    expect(textStyleOf(out, 2)?.fontSize).toBe('4em');
+  });
+
+  it('relinkRoleEqualMarks unsets a literal the linked role leaves undefined; normal equals an unset role value', () => {
+    const doc = docOf(run({ fontStyle: 'normal', color: '#111111' }));
+
+    const out = relinkRoleEqualMarks(doc, [NEW_ROLE, OLD_ROLE]);
+
+    expect(textStyleOf(out, 0)?.fontStyle).toBeNull();
+    expect(textStyleOf(out, 0)?.color).toBe('#111111');
+  });
+
+  it('relinkRoleEqualMarks leaves colour, link marks and role refs alone, and returns the same doc when nothing changes', () => {
+    const link = { type: 'link', attrs: { href: 'https://example.com' } };
+    const doc = docOf(
+      run({ fontSize: roleVarRef('fontSize'), color: '#222222' }, [link]),
+    );
+
+    const out = relinkRoleEqualMarks(doc, [NEW_ROLE, OLD_ROLE]);
+
+    expect(out).toBe(doc);
+    expect(marksOf(out, 0)).toContainEqual(link);
+  });
+
+  it('relinkRoleEqualMarks drops a textStyle mark left with nothing in it', () => {
+    const doc = docOf(run({ fontStyle: 'normal' }));
+
+    const out = relinkRoleEqualMarks(doc, [NEW_ROLE]);
+
+    expect(marksOf(out, 0).some((mark) => mark.type === 'textStyle')).toBe(
+      false,
+    );
+  });
+
+  it('relinkRoleEqualMarks drops the reset marker with the decoration it qualified', () => {
+    const doc = docOf(
+      run({ textDecoration: 'line-through', textDecorationReset: true }),
+    );
+
+    const out = relinkRoleEqualMarks(doc, [
+      { ...NEW_ROLE, textDecoration: 'line-through' },
+    ]);
+
+    expect(textStyleOf(out, 0)?.textDecoration).toBe(
+      roleVarRef('textDecoration'),
+    );
+    expect(textStyleOf(out, 0)).not.toHaveProperty('textDecorationReset');
+  });
+});
+
+describe('relinkDocToRole (R19 reset-to-role, document form)', () => {
+  const NEW_ROLE = {
+    fontFamily: 'Oswald',
+    fontSize: '3.5em',
+    fontWeight: 'bold',
+  };
+
+  const run = (attrs: Record<string, unknown>, extraMarks: object[] = []) => ({
+    type: 'text',
+    text: 'x',
+    marks: [{ type: 'textStyle', attrs }, ...extraMarks],
+  });
+  const docOf = (...runs: object[]) => ({
+    type: 'doc',
+    content: [{ type: 'paragraph', content: runs }],
+  });
+  const marksOf = (doc: unknown, index: number) =>
+    (
+      doc as {
+        content: {
+          content: {
+            marks: { type: string; attrs?: Record<string, unknown> }[];
+          }[];
+        }[];
+      }
+    ).content[0].content[index].marks;
+  const textStyleOf = (doc: unknown, index: number) =>
+    marksOf(doc, index).find((mark) => mark.type === 'textStyle')?.attrs;
+
+  it('relinks every run to the new role — a deliberate accent override included, unlike relinkRoleEqualMarks', () => {
+    const doc = docOf(run({ fontFamily: 'Playfair Display', fontSize: '5em' }));
+
+    const out = relinkDocToRole(doc, NEW_ROLE);
+
+    expect(textStyleOf(out, 0)?.fontFamily).toBe(roleVarRef('fontFamily'));
+    expect(textStyleOf(out, 0)?.fontSize).toBe(roleVarRef('fontSize'));
+  });
+
+  it("drops the reset marker so the run follows the new role's lines", () => {
+    const doc = docOf(
+      run({
+        textDecoration: 'line-through',
+        textDecorationReset: true,
+        color: '#111111',
+      }),
+    );
+
+    const out = relinkDocToRole(doc, {
+      ...NEW_ROLE,
+      textDecoration: 'underline',
+    });
+
+    expect(textStyleOf(out, 0)?.textDecoration).toBe(
+      roleVarRef('textDecoration'),
+    );
+    expect(textStyleOf(out, 0)).not.toHaveProperty('textDecorationReset');
+  });
+
+  it('unsets a typography attr the new role leaves undefined', () => {
+    const doc = docOf(run({ letterSpacing: '0.1em' }));
+
+    const out = relinkDocToRole(doc, NEW_ROLE);
+
+    expect(textStyleOf(out, 0)?.letterSpacing).toBeNull();
+  });
+
+  it('removes the legacy semantic emphasis marks (bold/italic/underline/strike)', () => {
+    const doc = docOf(
+      run({}, [{ type: 'bold' }, { type: 'italic' }, { type: 'strike' }]),
+    );
+
+    const out = relinkDocToRole(doc, NEW_ROLE);
+
+    expect(
+      marksOf(out, 0).some((mark) =>
+        ['bold', 'italic', 'underline', 'strike'].includes(mark.type),
+      ),
+    ).toBe(false);
+  });
+
+  it("keeps a link's underline and drops a plain run's", () => {
+    const link = { type: 'link', attrs: { href: 'https://example.com' } };
+    const doc = docOf(
+      run({}, [{ type: 'underline' }]),
+      run({}, [link, { type: 'underline' }]),
+    );
+
+    const out = relinkDocToRole(doc, NEW_ROLE);
+
+    expect(marksOf(out, 0).map((mark) => mark.type)).not.toContain('underline');
+    expect(marksOf(out, 1).map((mark) => mark.type)).toContain('underline');
+  });
+
+  it('keeps colour and the link mark untouched', () => {
+    const link = { type: 'link', attrs: { href: 'https://example.com' } };
+    const doc = docOf(
+      run({ color: '#222222', fontFamily: 'Playfair Display' }, [link]),
+    );
+
+    const out = relinkDocToRole(doc, NEW_ROLE);
+
+    expect(textStyleOf(out, 0)?.color).toBe('#222222');
+    expect(marksOf(out, 0)).toContainEqual(link);
+  });
+
+  it('drops a mark left with no colour and every typography attr unset (no role to relink against)', () => {
+    const doc = docOf(run({ fontFamily: 'Playfair Display', fontSize: '5em' }));
+
+    const out = relinkDocToRole(doc, undefined);
+
+    expect(marksOf(out, 0)).toEqual([]);
+  });
+});
+
+describe('mergePickedMarks (R9 first-type seed)', () => {
+  const editor = new Editor({ extensions: getRteExtensions() });
+  const { textStyle, highlight } = editor.schema.marks;
+  const seed = [
+    textStyle.create({
+      color: '#111111',
+      fontFamily: roleVarRef('fontFamily'),
+      fontWeight: roleVarRef('fontWeight'),
+    }),
+    highlight.create({ color: '#ffeeaa' }),
+  ];
+
+  afterAll(() => editor.destroy());
+
+  it('mergePickedMarks keeps the seed colour and role refs and adds the picked bold', () => {
+    const [merged, keptHighlight] = mergePickedMarks(seed, [
+      textStyle.create({ fontWeight: 'bold' }),
+    ]);
+
+    expect(merged.attrs).toMatchObject({
+      color: '#111111',
+      fontFamily: roleVarRef('fontFamily'),
+      fontWeight: 'bold', // the pick wins over the seed's role ref
+    });
+    expect(keptHighlight.attrs.color).toBe('#ffeeaa');
+  });
+
+  it('mergePickedMarks adds a picked mark the seed lacks', () => {
+    const out = mergePickedMarks(
+      [seed[0]],
+      [highlight.create({ color: '#000' })],
+    );
+
+    expect(out.map((mark) => mark.type.name)).toEqual([
+      'textStyle',
+      'highlight',
+    ]);
+  });
+
+  it('mergePickedMarks with nothing picked is the seed', () => {
+    expect(mergePickedMarks(seed, null)).toEqual(seed);
+    expect(mergePickedMarks(seed, [])).toEqual(seed);
+  });
+});