@designcrowd/library.brand-page 6.2.11 → 6.2.12

package/src/brand-page-maker/composables/rich-text-editor/useRichTextEditor.ts

@@ -8,7 +8,13 @@ import {
   watch,
 } from 'vue';
 import { Editor } from '@tiptap/vue-3';
-import { getRteExtensions } from './getRteExtensions';
+import { getRteExtensions } from '@shared/rte-extensions.util';
+import {
+  KeepMarksOnEmpty,
+  keepMarksOnEmptyPluginKey,
+} from './keepMarksOnEmpty';
+import { RoleTypographyFill } from './extensions/RoleTypographyFill';
+import { RteClipboard } from './extensions/RteClipboard';
 import type { StyleTextFontFamilyOption } from '@shared/style-settings/models';
 import { createFormattingActions } from './formatting';
 import { useTextAlign } from './textAlign';
@@ -18,8 +24,6 @@ import {
   buildInitialMarks,
   emToPx,
   isSameRteContent,
-  isStyleChanged,
-  pxToEm,
   sanitizeRteJson,
   skipStyleDetection,
 } from '@brand-page-maker/utils';
@@ -32,16 +36,28 @@ import {
 import type { ButtonGroupOption } from '@brand-page-maker/models/button-group.model';
 import { letterSpacingValueConvertor } from '@brand-page-maker/convertors';
 import { useUiContentSettingsStore } from '@shared/content-settings/store';
+import { useUiStyleSettingsStore } from '@shared/style-settings/store';
 import { useHistoryStore } from '@brand-page-maker/stores/history/history-store';
 import { AllSelection } from 'prosemirror-state';
+import type { EditorState } from 'prosemirror-state';
+import type { Mark } from 'prosemirror-model';
+import { useUiColorPaletteStore } from '@shared/color-palette/store';
 import { useHyperlink } from './hyperlink';
 import { useBubbleMenu } from './bubbleMenu';
 import {
   hasLogoColorVar,
-  getRTEColor,
   getToolbarColorFromMark,
   resolveInitialToolbarTextColor,
+  hasRunTypographyOverride,
+  isCanonicalLinked,
+  isRoleVarRef,
+  mergePickedMarks,
+  normTypographyValue,
+  readBlockTypography,
+  relinkRoleEqualRunsChain,
+  relinkTypographyChain,
 } from '@brand-page-maker/utils/rich-text-editor.util';
+import { composeTextDecoration } from '@shared/text-role-typography.util';
 import { useEventTracker, EVENTS } from '../useEventTracker';
 
 interface UseRichTextEditorReturn {
@@ -63,12 +79,14 @@ interface UseRichTextEditorReturn {
   }>;
   toggleFont: (font: string) => void;
   toggleFontSize: (size: string) => void;
-  letterSpacingValue: ComputedRef<string>;
-  lineHeightValue: ComputedRef<string>;
+  letterSpacingValue: WritableComputedRef<string>;
+  lineHeightValue: WritableComputedRef<string>;
   selectedFont: ComputedRef<string>;
   setInitialStyleSettings: (selectedTextStyle?: BrandPageCssStyle) => void;
-  copyGlobalStyleSettings: (selectedTextStyle?: BrandPageCssStyle) => void;
-  unsetAllMarks: () => void;
+  hasTypographyOverride: () => boolean;
+  canApplyTypographyToRole: () => boolean;
+  resetTypographyToRole: () => void;
+  applyTypographyToRole: () => void;
   handleHyperlink: (
     action: 'toggle' | 'apply' | 'remove',
     data?: { href?: string; text?: string },
@@ -100,6 +118,9 @@ interface EditorOptionType {
   value: string | StyleTextFontFamilyOption;
 }
 
+// Outlasts the slowest debounced toolbar command (spacing, 300 ms). See undo-redo.md.
+const USER_COMMAND_WINDOW_MS = 1000;
+
 export const useExternalRichTextEditor = (): {
   externalEditor: Editor;
 } => {
@@ -135,12 +156,18 @@ export const useRichTextEditor = (
     selectedFontSizePx: number;
     selectedTextColor: string;
     selectedBackgroundColor: string;
+    // BP-5969: bold/italic/underline/strike toolbar active-state, resolved from the effective
+    // textStyle attr OR a legacy semantic mark (set in selectionUpdate).
+    isBold: boolean;
+    isItalic: boolean;
+    isUnderline: boolean;
+    isStrike: boolean;
   },
   fontStyleDropdownRef: Ref<
     DropdownInstance | undefined,
     DropdownInstance | undefined
   >,
-  // One entry of `textStyleOptions`; `undefined` when the selection is "none".
+  // The selected role's entry of `textStyleOptions`.
   selectedGlobalTextStyles: WritableComputedRef<
     TextStyleOption | undefined,
     string
@@ -153,17 +180,88 @@ export const useRichTextEditor = (
   selectedLinkTypeValue: Ref<HyperlinkType>,
 ): UseRichTextEditorReturn => {
   const historyStore = useHistoryStore();
+  const colorPaletteStore = useUiColorPaletteStore();
+
+  // A toolbar click moves focus off the editor before its command runs (Tiptap's `.focus()` restores
+  // it a frame later), so `isFocused` alone would file the user's edit as a mount write-back.
+  let userCommandUntil = 0;
+
+  const markUserCommand = (): void => {
+    userCommandUntil = Date.now() + USER_COMMAND_WINDOW_MS;
+  };
+
+  // The linked role's style for the var-or-literal write rule (BP-5969): a canonical-linked
+  // block resolves typography from its role, so a toolbar pick equal to the role is stored as
+  // the role var, not a literal. Undefined for legacy/unlinked blocks (they bake literals).
+  // Declared above the editor so RteClipboard's getContext (below) can close over it too.
+  const getRoleStyle = () =>
+    isCanonicalLinked(props.styles)
+      ? selectedGlobalTextStyles.value?.style
+      : undefined;
+
+  // The first-type seed a genuinely fresh field takes, or the previous run's marks when the
+  // field was just cleared (KeepMarksOnEmpty's capture) — shared by `beforeinput` below and
+  // RteClipboard's text-only paste into an empty field, so a paste matches typing.
+  const getFirstInputMarks = (state: EditorState): Mark[] => {
+    const clearedMarks = keepMarksOnEmptyPluginKey.getState(state);
+    const pickedMarks = state.storedMarks;
+
+    if (clearedMarks && clearedMarks.length > 0) {
+      return mergePickedMarks(clearedMarks, pickedMarks);
+    }
+
+    const globalStyle = selectedGlobalTextStyles.value?.style;
+    // Element-first colour: see the matching comment in `beforeinput` below.
+    const styleSource = globalStyle
+      ? { ...globalStyle, color: props.styles?.color }
+      : props.styles;
+
+    const marks = buildInitialMarks(
+      state,
+      styleSource,
+      !isCanonicalLinked(props.styles),
+    );
+
+    return mergePickedMarks(marks, pickedMarks);
+  };
 
   const editor = new Editor({
     content: model.value ?? '',
     editable: !props.readOnly,
-    extensions: getRteExtensions({
-      restrictStarterKit: true,
-      editing: {
-        placeholder: props.placeholder,
-        maxLength: props.maxLength,
-      },
-    }),
+    extensions: [
+      ...getRteExtensions({
+        restrictStarterKit: true,
+        editing: {
+          placeholder: props.placeholder,
+          maxLength: props.maxLength,
+        },
+      }),
+      // Captures a cleared run's marks so the first-type seed below can restore the
+      // style on retype (rather than reseeding from the role).
+      KeepMarksOnEmpty,
+      RoleTypographyFill.configure({
+        getFillSource: () => {
+          const role = isCanonicalLinked(props.styles)
+            ? selectedGlobalTextStyles.value?.style
+            : undefined;
+
+          return role
+            ? {
+                role: role as unknown as Record<string, string>,
+                block: props.styles as unknown as Record<string, string>,
+              }
+            : undefined;
+        },
+      }),
+      RteClipboard.configure({
+        getContext: () => ({
+          role: getRoleStyle(),
+          block: props.styles,
+          colors: colorPaletteStore.colors,
+        }),
+        getFirstInputMarks,
+      }),
+    ],
     editorProps: {
       handleDOMEvents: {
         drop(view, event: DragEvent) {
@@ -173,109 +271,25 @@ export const useRichTextEditor = (
         },
         beforeinput(view, event) {
           const { state } = view;
-          // On first insert into an empty doc, set storedMarks to global styles so all typed chars inherit them
 
           if (
-            event.inputType === 'insertText' &&
-            state.doc.textContent === ''
+            event.inputType !== 'insertText' ||
+            state.doc.textContent !== ''
           ) {
-            const globalStyle = selectedGlobalTextStyles.value?.style;
-            // Element-first colour: once the doc is emptied, freshly-typed text must
-            // inherit a linked element's colour override (a creation-time contrast bake,
-            // or a colour picked while linked), not the linked global colour. Typography
-            // still comes from the global style (the element is linked), mirroring
-            // resolveTextColor's colour-only cascade.
-            const styleSource = globalStyle
-              ? {
-                  ...globalStyle,
-                  color: props.styles?.color || globalStyle.color,
-                }
-              : props.styles;
-
-            const marks = buildInitialMarks(state, styleSource);
-
-            const chain = editor.chain();
-
-            if (props.styles.textAlign)
-              chain.setTextAlign(props.styles.textAlign);
-
-            skipStyleDetection(chain, marks).run();
-          }
-
-          return false;
-        },
-        copy(view, event: ClipboardEvent) {
-          const selection = view.state.selection;
-
-          if (selection.empty) return;
-
-          const data = event.clipboardData;
-
-          const styleData = JSON.stringify(props.styles);
-
-          const slice = selection.content(),
-            { dom, text } = view.serializeForClipboard(slice);
-
-          if (data) {
-            event.preventDefault();
-            data.clearData();
-            data.setData('text/html', dom.innerHTML);
-            data.setData('text/plain', text);
-
-            if (styleData) data.setData('application/x-rte-styles', styleData);
+            return false;
           }
 
-          return true;
-        },
-
-        paste(view, event) {
-          // Unified paste handler: strip styles if no styleData, enforce maxLength, handle selection
-          const styleData = event.clipboardData?.getData(
-            'application/x-rte-styles',
-          );
-          const pastedText = event.clipboardData?.getData('text/plain') || '';
-          const { state, dispatch } = view;
-          const { from, to } = state.selection;
-
-          let tr = state.tr;
-
-          if (styleData) {
-            try {
-              const pastedStyles = JSON.parse(styleData);
-              const fontStyleChanges: TextStyleDeclaration = {
-                color: pastedStyles.color,
-                fontFamily: pastedStyles.fontFamily,
-                fontSize: pastedStyles.fontSize,
-                fontWeight: pastedStyles.fontWeight,
-                fontStyle: pastedStyles.fontStyle,
-                textDecoration: pastedStyles.textDecoration,
-                lineHeight: pastedStyles.lineHeight,
-                letterSpacing: pastedStyles.letterSpacing,
-                textAlign: pastedStyles.textAlign,
-                backgroundColor: pastedStyles.backgroundColor,
-                textStyleType: undefined,
-              };
-
-              syncContentSettings(fontStyleChanges);
-
-              return false;
-            } catch {
-              // ignore malformed styleData
-            }
-          } else {
-            event.preventDefault();
-            tr.delete(from, to);
-
-            const createdMarks = buildInitialMarks(state, props.styles);
-
-            tr = tr.setStoredMarks(createdMarks).insertText(pastedText, from);
+          const chain = editor.chain();
 
-            onSelectTextStyleType({ label: 'None' } as ButtonGroupOption);
-          }
+          // textAlign is a block-node attr, not a mark, and a full clear resets it — so
+          // re-apply the element's alignment regardless of which seed `getFirstInputMarks`
+          // takes below (it's the one thing that survives a full clear).
+          if (props.styles.textAlign)
+            chain.setTextAlign(props.styles.textAlign);
 
-          dispatch(tr);
+          skipStyleDetection(chain, getFirstInputMarks(state)).run();
 
-          return true;
+          return false;
         },
         click(view, event) {
           if (isHyperlinkPopupOpen?.value) return false;
@@ -303,6 +317,7 @@ export const useRichTextEditor = (
   });
 
   const contentSettingStore = useUiContentSettingsStore();
+  const styleSettingsStore = useUiStyleSettingsStore();
   const eventTracker = useEventTracker();
 
   const {
@@ -312,13 +327,11 @@ export const useRichTextEditor = (
     toggleStrike,
     toggleTextColor,
     toggleBackgroundColor,
-    toggleBoldAll,
-    toggleItalicAll,
-    toggleUnderlineAll,
-    toggleStrikeAll,
-    toggleTextColorAll,
-    unsetAllMarks,
-  } = createFormattingActions(editor);
+    boldActive,
+    italicActive,
+    underlineActive,
+    strikeActive,
+  } = createFormattingActions(editor, getRoleStyle, () => props.styles);
 
   const {
     currentAlignment,
@@ -327,22 +340,37 @@ export const useRichTextEditor = (
     keys: alignmentKeys,
   } = useTextAlign(editor);
 
-  const {
-    selectedFont,
-    toggleFont,
-    toggleFontSize,
-    toggleFontAll,
-    toggleFontSizeAll,
-  } = useFont(editor, fontSettings, fontStyleDropdownRef);
+  const { selectedFont, toggleFont, toggleFontSize } = useFont(
+    editor,
+    fontSettings,
+    fontStyleDropdownRef,
+    getRoleStyle,
+  );
 
   const {
-    letterSpacingValue,
-    lineHeightValue,
+    letterSpacingValue: letterSpacingSlider,
+    lineHeightValue: lineHeightSlider,
     letterSpacing,
     lineHeight,
     setLetterSpaceAll,
     setLineHeightAll,
-  } = useSpacing(editor);
+  } = useSpacing(editor, getRoleStyle);
+
+  const letterSpacingValue = computed<string>({
+    get: () => letterSpacingSlider.value,
+    set: (value) => {
+      markUserCommand();
+      letterSpacingSlider.value = value;
+    },
+  });
+
+  const lineHeightValue = computed<string>({
+    get: () => lineHeightSlider.value,
+    set: (value) => {
+      markUserCommand();
+      lineHeightSlider.value = value;
+    },
+  });
 
   const {
     hyperlinkValue,
@@ -410,121 +438,123 @@ export const useRichTextEditor = (
     },
   );
 
-  editor.on('transaction', ({ transaction }) => {
-    // Style detection only makes sense for user styling — an unfocused
-    // editor's transactions are mount rehydration / programmatic setContent
-    // churn, and clearing textStyleType from those would push a phantom
-    // style write into the model (BP-5810 family).
-    if (!editor.isFocused) {
-      return;
-    }
+  // BP-5969 (ADR-0019): the auto-detach that cleared `textStyleType` whenever the doc's
+  // style changed is gone — a style edit is now a per-run mark and the block keeps its
+  // role. (Was: `editor.on('transaction')` → `onSelectTextStyleType('None')`.)
+
+  // Refresh the B/I/U/S button state from the effective formatting (textStyle attr, resolved
+  // against the role, OR a legacy semantic mark). It runs on every transaction: a format picked with
+  // nothing selected only sets a stored mark, which fires neither `update` nor `selectionUpdate`.
+  const syncFormattingActiveState = () => {
+    fontSettings.isBold = boldActive();
+    fontSettings.isItalic = italicActive();
+    fontSettings.isUnderline = underlineActive();
+    fontSettings.isStrike = strikeActive();
+  };
 
-    if (isStyleChanged(transaction) && props.styles.textStyleType) {
-      onSelectTextStyleType({
-        label: 'None',
-      } as ButtonGroupOption);
-    }
+  // Skipped while a history snapshot applies, as `selectionUpdate` is (BP-5506).
+  editor.on('transaction', () => {
+    if (historyStore.isApplyingSnapshot) return;
+
+    syncFormattingActiveState();
   });
 
+  // A role edit (Style tab, AI) reaches the editor without a transaction. An empty one repaints
+  // the B/I/U/S state and the box's role fill (`RoleTypographyFill`) without touching the doc.
+  watch(
+    () => selectedGlobalTextStyles.value?.style,
+    () => {
+      if (editor.isDestroyed) return;
+
+      editor.view.dispatch(editor.state.tr.setMeta('addToHistory', false));
+    },
+    { deep: true },
+  );
+
   // Update model when editor content changes. RTE content is stored as Tiptap
   // JSON (BP-5787). getJSON() is already in hand (the editor holds the doc) and
   // is sanitised natively — no getHTML(), no DOMPurify, no extra editor — so
   // the per-keystroke path allocates nothing heavy.
   editor.on('update', () => {
-    // An update fired while the editor is unfocused is TipTap rewriting the
-    // model back into its canonical form during mount rehydration or a
-    // programmatic setContent — not a user edit. Tag the emit so the write
-    // folds into the current undo head instead of pushing a phantom entry
-    // (BP-5810). The flag travels WITH the value through the debounced
-    // field → store chain and arms the history merge at the moment of the
-    // store write — arming here at emit time would lapse before the
-    // debounce fires. Genuine edits happen while focused and commit
-    // normally.
-    //
-    // Known limitation: a programmatic toolbar command run on an editor the
-    // user hasn't focused yet would also merge (losing that undo step). Today
-    // the RTE only mounts inside an already-open settings drawer and the user
-    // focuses it before formatting, so this doesn't occur — revisit if a
-    // consumer ever drives toolbar actions on an unfocused editor.
+    // An update fired while the editor is unfocused and no toolbar command is in flight is
+    // TipTap rewriting the model into its canonical form during mount rehydration or a
+    // programmatic setContent — not a user edit. Tag the emit so the write folds into the
+    // current undo head instead of pushing a phantom entry (BP-5810). The flag travels WITH
+    // the value through the debounced field → store chain and arms the history merge at the
+    // moment of the store write — arming here at emit time would lapse before the debounce
+    // fires. Typing (focused) and toolbar commands (`markUserCommand`) commit normally.
     emit('update:modelValue', sanitizeRteJson(editor.getJSON()), {
-      isHydrationWrite: !editor.isFocused,
+      isHydrationWrite: !editor.isFocused && Date.now() > userCommandUntil,
     });
   });
 
-  editor.on('selectionUpdate', () => {
-    // Skip while a history snapshot is being applied — `setContent` fires
-    // selectionUpdate before the editor has fully rehydrated, which causes
-    // toolbar buttons (alignment, letter-spacing) to flash through bogus
-    // active states before settling. The editor emits a final selectionUpdate
-    // after apply completes, which lands the correct values (BP-5506).
-    if (historyStore.isApplyingSnapshot) return;
-
+  // The toolbar's read of the editor at the cursor: a mark holding a role var (or no mark) shows the
+  // linked role's value, a literal shows itself. Colours fall back to the given values when the run
+  // has none, so the mount-time seed can pass the element colour it resolved.
+  const syncToolbarFromEditor = ({
+    textColorFallback = '#000000',
+    backgroundColorFallback = 'transparent',
+  }: {
+    textColorFallback?: string;
+    backgroundColorFallback?: string;
+  } = {}): void => {
     const textStyleAttributes = editor.getAttributes('textStyle');
     const highlightAttributes = editor.getAttributes('highlight');
     const focusedAlignment = editor.getAttributes(
       editor.state.selection.$anchor.node().type.name,
     );
 
-    const selection = editor.state.selection;
+    const roleStyle = getRoleStyle();
 
-    if (selection instanceof AllSelection) {
-      // to prevent selecting editor state
-      // when user presses ctrl + a the beforeinput event doesn't get triggered
-      editor.commands.setTextSelection({
-        from: selection.from + 1,
-        to: selection.to - 1,
-      });
-    }
+    const markFontFamily = textStyleAttributes?.fontFamily;
+    const displayFont =
+      markFontFamily && !isRoleVarRef(markFontFamily)
+        ? markFontFamily.replace(/^['"]|['"]$/g, '')
+        : (roleStyle?.fontFamily ?? 'Lato');
 
-    // TODO: resolve the issue of missing style on text between empty lines
-    // retainStyleOnEmptyLine(editor, selection);
+    selectedFont.value = displayFont;
+    fontSettings.selectedFont = displayFont;
 
-    if (textStyleAttributes && textStyleAttributes.fontFamily) {
-      const font = textStyleAttributes.fontFamily.replace(/^['"]|['"]$/g, '');
+    const markFontSize = textStyleAttributes?.fontSize;
+    const sizeSource =
+      markFontSize && !isRoleVarRef(markFontSize)
+        ? markFontSize
+        : (roleStyle?.fontSize ?? fontSettings.selectedFontSize);
 
-      selectedFont.value = font;
-      fontSettings.selectedFont = font;
-    } else {
-      selectedFont.value = 'Lato';
-      fontSettings.selectedFont = 'Lato';
-    }
+    fontSettings.selectedFontSizePx = Math.ceil(parseFloat(emToPx(sizeSource)));
 
-    if (textStyleAttributes && textStyleAttributes.fontSize) {
-      fontSettings.selectedFontSizePx = Math.ceil(
-        parseFloat(emToPx(textStyleAttributes.fontSize)),
-      );
-    } else {
-      fontSettings.selectedFontSizePx = Math.ceil(
-        parseFloat(emToPx(fontSettings.selectedFontSize)),
-      );
-    }
-
-    // Reflect the active mark colour on the toolbar. A palette reference is kept
-    // verbatim (so ColorField can highlight the swatch); a literal is hex-normalised —
-    // Color().hex() throws on a var(), so the split lives in getToolbarColorFromMark.
+    // A palette reference is kept verbatim (so ColorField can highlight the swatch); a literal is
+    // hex-normalised — Color().hex() throws on a var(), so the split lives in getToolbarColorFromMark.
     fontSettings.selectedTextColor = getToolbarColorFromMark(
       textStyleAttributes?.color,
-      '#000000',
+      textColorFallback,
     );
 
     fontSettings.selectedBackgroundColor = getToolbarColorFromMark(
       highlightAttributes?.color,
-      'transparent',
+      backgroundColorFallback,
     );
 
-    if (textStyleAttributes.lineHeight) {
-      lineHeight.value = textStyleAttributes.lineHeight;
-    } else {
-      lineHeight.value = '1';
-    }
+    syncFormattingActiveState();
 
-    if (textStyleAttributes && textStyleAttributes.letterSpacing) {
-      letterSpacing.value = letterSpacingValueConvertor.convert({
-        letterSpacing: textStyleAttributes.letterSpacing,
-      });
-    } else {
-      letterSpacing.value = '0';
-    }
+    const markLineHeight = textStyleAttributes.lineHeight;
+
+    lineHeight.value =
+      markLineHeight && !isRoleVarRef(markLineHeight)
+        ? markLineHeight
+        : (roleStyle?.lineHeight ?? '1');
+
+    const markLetterSpacing = textStyleAttributes?.letterSpacing;
+    const letterSpacingSource =
+      markLetterSpacing && !isRoleVarRef(markLetterSpacing)
+        ? markLetterSpacing
+        : roleStyle?.letterSpacing;
+
+    letterSpacing.value = letterSpacingSource
+      ? letterSpacingValueConvertor.convert({
+          letterSpacing: letterSpacingSource,
+        })
+      : '0';
 
     if (focusedAlignment && focusedAlignment.textAlign) {
       const idx = alignmentKeys.indexOf(focusedAlignment.textAlign);
@@ -535,6 +565,31 @@ export const useRichTextEditor = (
     } else {
       currentAlignmentIndex.value = 0;
     }
+  };
+
+  editor.on('selectionUpdate', () => {
+    // Skip while a history snapshot is being applied — `setContent` fires
+    // selectionUpdate before the editor has fully rehydrated, which causes
+    // toolbar buttons (alignment, letter-spacing) to flash through bogus
+    // active states before settling. The editor emits a final selectionUpdate
+    // after apply completes, which lands the correct values (BP-5506).
+    if (historyStore.isApplyingSnapshot) return;
+
+    const selection = editor.state.selection;
+
+    if (selection instanceof AllSelection) {
+      // to prevent selecting editor state
+      // when user presses ctrl + a the beforeinput event doesn't get triggered
+      editor.commands.setTextSelection({
+        from: selection.from + 1,
+        to: selection.to - 1,
+      });
+    }
+
+    // TODO: resolve the issue of missing style on text between empty lines
+    // retainStyleOnEmptyLine(editor, selection);
+
+    syncToolbarFromEditor();
   });
 
   const setInitialStyleSettings = (selectedTextStyle?: BrandPageCssStyle) => {
@@ -546,6 +601,14 @@ export const useRichTextEditor = (
     );
 
     if (globalStyles) {
+      // A canonical-linked block inherits typography from the role CSS class and stores
+      // only its per-property OVERRIDES (BP-5969). Re-deriving the role's typography onto
+      // the element on every RTE mount clobbered those overrides — selecting a block
+      // reverted its title to the role font/size — so bake typography here only for
+      // legacy/unlinked blocks (which still carry the resolved style inline). Mirrors the
+      // isCanonicalLinked gate in buildInitialMarks / getUpdatedHTMLFromEditor.
+      const bakeTypography = !isCanonicalLinked(props.styles);
+
       // sync content settings style — a mount-time re-derivation, not a user
       // edit. Flag it so the store folds it into the current undo head: this
       // write lands ~100ms BEFORE the editor's canonical text write-back, and
@@ -555,38 +618,46 @@ export const useRichTextEditor = (
         id: props.rawId,
         name: props.name,
         value: {
-          fontSize: globalStyles.fontSize,
-          fontFamily: globalStyles.fontFamily,
-          fontWeight: globalStyles.fontWeight,
-          fontStyle: globalStyles.fontStyle,
-          textDecoration: globalStyles.textDecoration,
-          // Keep an element colour override (a creation-time contrast bake, or a
-          // colour picked while linked) — only fall back to the global style's colour
-          // when the element has none, mirroring `resolveTextColor`'s element-first
-          // cascade. Blindly taking `globalStyles.color` here re-derived the linked
-          // colour on every RTE mount and clobbered the override.
-          color: props.styles?.color || globalStyles.color,
-          lineHeight: globalStyles.lineHeight,
-          letterSpacing: globalStyles.letterSpacing,
+          ...(bakeTypography
+            ? {
+                fontSize: globalStyles.fontSize,
+                fontFamily: globalStyles.fontFamily,
+                fontWeight: globalStyles.fontWeight,
+                fontStyle: globalStyles.fontStyle,
+                textDecoration: globalStyles.textDecoration,
+                lineHeight: globalStyles.lineHeight,
+                letterSpacing: globalStyles.letterSpacing,
+              }
+            : {}),
+          // The element's own colour override (a creation-time contrast bake, or a colour
+          // picked while linked). ADR-0020: the role carries no colour, so there is no
+          // global fallback — an uncoloured element renders the page base coat.
+          color: props.styles?.color,
         },
         isHydrationWrite: !editor.isFocused,
       });
 
-      // sync toolbar editor styles
-      fontSettings.selectedFont = globalStyles?.fontFamily ?? 'Lato';
-      fontSettings.selectedFontSize = globalStyles?.fontSize ?? '2.25em';
+      // sync toolbar editor styles — show the block's EFFECTIVE typography (its override,
+      // else the linked role) so the toolbar matches the render, not the role blindly.
+      const effectiveFontSize =
+        props.styles?.fontSize ?? globalStyles?.fontSize ?? '2.25em';
+
+      fontSettings.selectedFont =
+        props.styles?.fontFamily ?? globalStyles?.fontFamily ?? 'Lato';
+      fontSettings.selectedFontSize = effectiveFontSize;
       fontSettings.selectedFontSizePx = Math.ceil(
-        parseFloat(emToPx(globalStyles?.fontSize ?? '2.25em')),
+        parseFloat(emToPx(effectiveFontSize)),
       );
       // For an RTE field the mark is the source of truth — the render and the focus-time
       // `selectionUpdate` both paint from it — so seed the swatch from the mark's first
       // coloured run, falling back to the element→global cascade. Otherwise the unfocused
       // swatch shows the linked global while the text renders its baked frame/override
       // colour, and only snaps to the right colour on focus (BP-5886).
+      // BP-5969 (ADR-0020): the role contributes no colour — seed the swatch from the RTE
+      // mark, else the element's own colour.
       fontSettings.selectedTextColor = resolveInitialToolbarTextColor(
         model.value,
         props.styles?.color,
-        globalStyles.color,
       );
       // A global text style has no backgroundColor, so this resolves to undefined there.
       const backgroundColour =
@@ -612,83 +683,31 @@ export const useRichTextEditor = (
       ) {
         toggleTextAlign(props.styles.textAlign);
       }
-    } else if (props.styles) {
-      // copy the content settings styles to the editor
-      fontSettings.selectedFont = props.styles?.fontFamily ?? 'Lato';
-      fontSettings.selectedFontSize = props.styles?.fontSize ?? '2.25em';
-      fontSettings.selectedFontSizePx = Math.ceil(
-        parseFloat(emToPx(props.styles?.fontSize ?? '2.25em')),
-      );
-      // No linked global (props.styles carries no textStyleType) — still resolve the RTE
-      // mark first, so a field whose colour lives only in its mark (e.g. the tipping/payment
-      // success message, which has no style object) shows it instead of collapsing to black.
-      fontSettings.selectedTextColor = resolveInitialToolbarTextColor(
-        model.value,
-        props.styles?.color,
-      );
-      fontSettings.selectedBackgroundColor = hasLogoColorVar(
-        props.styles?.backgroundColor ?? '',
-      )
-        ? 'transparent'
-        : (props.styles?.backgroundColor ?? 'transparent');
-      lineHeight.value = props.styles?.lineHeight?.includes('em')
-        ? emToPx(props.styles?.lineHeight ?? '1em')
-        : (props.styles?.lineHeight ?? '1');
-      letterSpacing.value = letterSpacingValueConvertor.convert(
-        props.styles ?? {},
-      );
-
-      if (
-        props.styles?.textAlign &&
-        currentAlignment?.textAlign !== props.styles.textAlign
-      ) {
-        toggleTextAlign(props.styles.textAlign);
-      }
-    }
-  };
-
-  const copyGlobalStyleSettings = (selectedTextStyle?: BrandPageCssStyle) => {
-    const globalStyles =
-      selectedTextStyle ?? selectedGlobalTextStyles.value?.style;
-
-    if (globalStyles) {
-      globalStyles.fontWeight === 'bold' && toggleBoldAll();
-      globalStyles.fontStyle && toggleItalicAll();
-      globalStyles.textDecoration?.includes('underline') &&
-        toggleUnderlineAll();
-      globalStyles.textDecoration?.includes('line-through') &&
-        toggleStrikeAll();
-
-      if (globalStyles.color) {
-        if (!hasLogoColorVar(globalStyles.color)) {
-          toggleTextColorAll(globalStyles.color);
-          fontSettings.selectedTextColor = globalStyles.color;
-        } else {
-          // Apply logo color using CSS variable
-          toggleTextColorAll(getRTEColor(globalStyles.color, 'text'));
-          fontSettings.selectedTextColor = '#000000';
-        }
-      }
 
-      globalStyles.fontFamily && toggleFontAll(globalStyles.fontFamily);
-      globalStyles.fontSize && toggleFontSizeAll(globalStyles.fontSize);
-      globalStyles.lineHeight && setLineHeightAll(globalStyles.lineHeight);
-      globalStyles.letterSpacing &&
-        setLetterSpaceAll(globalStyles.letterSpacing);
-      props.styles.textAlign &&
-        toggleTextAlign(props.styles.textAlign ?? 'none');
+      // Show the runs' own values (the role, or a per-run override) before the first click.
+      syncToolbarFromEditor({
+        textColorFallback: fontSettings.selectedTextColor,
+        backgroundColorFallback: fontSettings.selectedBackgroundColor,
+      });
     }
   };
 
+  // BP-5969 (ADR-0019): a toolbar edit applies a TipTap mark ONLY. The old sync wrote
+  // the flattened style back onto the block object AND cleared its role link
+  // (`textStyleType: undefined`) — that dual source of truth is the "a per-run colour
+  // edit repaints the whole block / drops the role" bug class. Now per-run formatting
+  // lives on marks; the block stays linked; whole-box size/family are authored from the
+  // sidebar. Alignment is the one block-level toolbar action, so it still persists — but
+  // without detaching the role.
   const triggerEditorStyleChange = (editorOption: EditorOptionType) => {
-    const fontStyleChanges = { ...props.styles, textStyleType: undefined };
+    markUserCommand();
 
     switch (editorOption.type) {
       case 'fontFamily':
         toggleFont(editorOption.value as string);
-        fontStyleChanges.fontFamily = editorOption.value as string;
         break;
-      case 'fontSize':
+
+      case 'fontSize': {
         const size = editorOption.value as string;
 
         fontSettings.selectedFontSizePx = size.includes('em')
@@ -696,93 +715,168 @@ export const useRichTextEditor = (
           : parseInt(size);
 
         toggleFontSize(size);
-        fontStyleChanges.fontSize = size.includes('em') ? size : pxToEm(size);
         break;
+      }
+
       case 'fontWeight':
         toggleBold();
-        editor.isActive('bold')
-          ? (fontStyleChanges.fontWeight = 'bold')
-          : (fontStyleChanges.fontWeight = undefined);
         break;
       case 'fontStyle':
         toggleItalic();
-        editor.isActive('italic')
-          ? (fontStyleChanges.fontStyle = 'italic')
-          : (fontStyleChanges.fontStyle = undefined);
         break;
       case 'textDecorationLine':
         toggleUnderline();
-        editor.isActive('underline')
-          ? fontStyleChanges.textDecoration
-            ? (fontStyleChanges.textDecoration =
-                fontStyleChanges.textDecoration + ' underline')
-            : (fontStyleChanges.textDecoration = 'underline')
-          : (fontStyleChanges.textDecoration =
-              fontStyleChanges.textDecoration?.replace('underline', ''));
-
         break;
       case 'textDecorationStrike':
         toggleStrike();
-        editor.isActive('strike')
-          ? fontStyleChanges.textDecoration
-            ? (fontStyleChanges.textDecoration =
-                fontStyleChanges.textDecoration + ' line-through')
-            : (fontStyleChanges.textDecoration = 'line-through')
-          : (fontStyleChanges.textDecoration =
-              fontStyleChanges.textDecoration?.replace('line-through', ''));
         break;
       case 'textColor':
         toggleTextColor(editorOption.value as string);
-        fontStyleChanges.color = editorOption.value as string;
         break;
       case 'backgroundColor':
         toggleBackgroundColor(editorOption.value as string);
-        fontStyleChanges.backgroundColor = editorOption.value as string;
         break;
       case 'lineHeight':
         setLineHeightAll(editorOption.value as string);
-        fontStyleChanges.lineHeight = editorOption.value as string;
         break;
       case 'letterSpacing':
         setLetterSpaceAll(editorOption.value as string);
-        fontStyleChanges.letterSpacing = letterSpacingValueConvertor.convert({
-          letterSpacing: editorOption.value as string,
-        });
         break;
       case 'textAlign':
         toggleTextAlign();
-        fontStyleChanges.textAlign = currentAlignment.value.alignment;
+        persistBlockTextAlign(currentAlignment.value.alignment);
         break;
       case 'hyperlink':
         setHyperlinkUrl(editorOption.value as string);
         break;
     }
-
-    syncContentSettings(fontStyleChanges);
   };
 
-  const syncContentSettings = (fontStyleChanges: TextStyleDeclaration) => {
+  // Alignment is block-level (not a per-run mark, not a role property), so it persists to
+  // the block/item style — writing ONLY `textAlign`, so the role link is untouched.
+  const persistBlockTextAlign = (textAlign: string | undefined) => {
+    if (!textAlign) return;
+
+    const value = { textAlign };
+
     if (props.name === 'textItems') {
       contentSettingStore.updateTextItemTextStyleTypeWithStyles({
         id: props.rawId,
         name: props.name,
-        value: {
-          ...fontStyleChanges,
-          fontSize: fontSettings.selectedFontSize,
-        },
+        value,
         index: props.textItemIndex,
       });
     } else {
       contentSettingStore.updateTextStyles({
         id: props.rawId,
         name: props.name,
-        value: {
-          ...fontStyleChanges,
-        },
+        value,
       });
     }
   };
 
+  // The subset of the block's typography that DIFFERS from its linked role — the promotable
+  // override set. Empty when the block matches its role (colour is element-first, excluded).
+  const getTypographyOverride = (): Record<string, string> => {
+    const role = selectedGlobalTextStyles.value?.style as
+      | Record<string, string>
+      | undefined;
+
+    if (!role) return {};
+
+    const override: Record<string, string> = {};
+
+    Object.entries(readBlockTypography(editor)).forEach(([key, value]) => {
+      // A role-var mark is linked, not an override — the value IS the role.
+      if (isRoleVarRef(value)) return;
+
+      const promoted =
+        key === 'textDecoration'
+          ? composeTextDecoration(role[key], value)
+          : value;
+
+      if (
+        typeof promoted === 'string' &&
+        normTypographyValue(key, promoted) !==
+          normTypographyValue(key, role[key])
+      ) {
+        override[key] = promoted;
+      }
+    });
+
+    return override;
+  };
+
+  // Drives the role dropdown's `*` and the "modified style" toggle: true when any run of this
+  // linked block differs from its role's typography — one bold word counts.
+  const hasTypographyOverride = (): boolean => {
+    const role = getRoleStyle() as Record<string, unknown> | undefined;
+
+    return !!role && hasRunTypographyOverride(editor, role);
+  };
+
+  // A word-level override has no single value to promote, so "Apply changes to all" needs a
+  // whole-block one.
+  const canApplyTypographyToRole = (): boolean =>
+    isCanonicalLinked(props.styles) &&
+    Object.keys(getTypographyOverride()).length > 0;
+
+  // Reset to default: re-link this block's typography to its role (see `relinkTypographyChain`).
+  // skipStyleDetection keeps the role link so this doesn't read as a detaching style edit.
+  const resetTypographyToRole = () => {
+    const role = getRoleStyle() as Record<string, unknown> | undefined;
+
+    markUserCommand();
+    skipStyleDetection(relinkTypographyChain(editor, role)).run();
+  };
+
+  // A role switch resets only typography (ADR-0020): runs relink to the new role, colour stays.
+  // An undo/redo restores the doc that went with the role, so it only moves the dropdown tick —
+  // the apply bumps `snapshotAppliedToken` in the same tick as it writes the role.
+  watch(
+    [() => props.styles.textStyleType, () => historyStore.snapshotAppliedToken],
+    ([newType, token], [oldType, oldToken]) => {
+      if (!newType || newType === oldType) return;
+
+      textStyleTypeOptions.forEach((item) => {
+        item.isSelected = item.value === newType;
+      });
+
+      if (token === oldToken) resetTypographyToRole();
+    },
+  );
+
+  // Apply to all: promote this block's whole-block typography into the role definition (every
+  // block linked to the role adopts it), relink this block's runs that now equal the role —
+  // word-level overrides stay, unlike Reset — and re-normalize siblings against the new role.
+  // Mirrors the sidebar TextStyleField.saveToGlobal, sourcing the overrides from the RTE marks.
+  const applyTypographyToRole = () => {
+    const type = props.styles.textStyleType;
+    const role = selectedGlobalTextStyles.value?.style;
+    const override = getTypographyOverride();
+
+    if (!type || !role || !Object.keys(override).length) return;
+
+    const previousRole = { ...role } as unknown as Record<string, unknown>;
+    const nextRole = { ...role, ...override } as TextStyleDeclaration;
+
+    markUserCommand();
+    styleSettingsStore.setTextStyleOption({ type, style: nextRole });
+    skipStyleDetection(
+      relinkRoleEqualRunsChain(
+        editor,
+        nextRole as unknown as Record<string, unknown>,
+        previousRole,
+      ),
+    ).run();
+    contentSettingStore.renormalizeTextStylesForRole(type, previousRole, {
+      id: props.rawId,
+      name: props.name,
+      index: props.textItemIndex,
+      doc: sanitizeRteJson(editor.getJSON()),
+    });
+  };
+
   const onFocus = () => {
     emit('focus');
   };
@@ -871,6 +965,7 @@ export const useRichTextEditor = (
           ? { from: selection.from, to: selection.to }
           : undefined;
 
+        markUserCommand();
         applyHyperlinkToEditor(url, text, selectionRange);
         isHyperlinkPopupOpen.value = false;
         break;
@@ -883,6 +978,7 @@ export const useRichTextEditor = (
             content_type: props.contentType,
           },
         });
+        markUserCommand();
         removeHyperlinkFromComposable();
         isHyperlinkPopupOpen.value = false;
         break;
@@ -912,8 +1008,10 @@ export const useRichTextEditor = (
     lineHeightValue,
     selectedFont: computed(() => selectedFont.value),
     setInitialStyleSettings,
-    copyGlobalStyleSettings,
-    unsetAllMarks,
+    hasTypographyOverride,
+    canApplyTypographyToRole,
+    resetTypographyToRole,
+    applyTypographyToRole,
     handleHyperlink,
     hyperlinkValue,
     setHyperlinkUrlValue,