@designcrowd/library.brand-page 6.2.11 → 6.2.12

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

@@ -1,20 +1,28 @@
 import { onBeforeUnmount, computed, 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 { createFormattingActions } from './formatting';
 import { useTextAlign } from './textAlign';
 import { useFont } from './font';
 import { useSpacing } from './spacing';
-import { buildInitialMarks, emToPx, isSameRteContent, isStyleChanged, pxToEm, sanitizeRteJson, skipStyleDetection, } from '@brand-page-maker/utils';
+import { buildInitialMarks, emToPx, isSameRteContent, sanitizeRteJson, skipStyleDetection, } from '@brand-page-maker/utils';
 import { HYPERLINK_TYPE, } from '@brand-page';
 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 { useUiColorPaletteStore } from '@shared/color-palette/store';
 import { useHyperlink } from './hyperlink';
 import { useBubbleMenu } from './bubbleMenu';
-import { hasLogoColorVar, getRTEColor, getToolbarColorFromMark, resolveInitialToolbarTextColor, } from '@brand-page-maker/utils/rich-text-editor.util';
+import { hasLogoColorVar, 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';
+// Outlasts the slowest debounced toolbar command (spacing, 300 ms). See undo-redo.md.
+const USER_COMMAND_WINDOW_MS = 1000;
 export const useExternalRichTextEditor = () => {
     const externalEditor = new Editor({
         editable: false,
@@ -25,19 +33,76 @@ export const useExternalRichTextEditor = () => {
     };
 };
 export const useRichTextEditor = (model, props, emit, fontSettings, fontStyleDropdownRef, 
-// One entry of `textStyleOptions`; `undefined` when the selection is "none".
+// The selected role's entry of `textStyleOptions`.
 selectedGlobalTextStyles, onSelectTextStyleType, updateRichTextEditor, textStyleTypeOptions, markedText, isHyperlinkPopupOpen, selectedLinkTypeValue) => {
     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 = () => {
+        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) => {
+        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,
+                            block: props.styles,
+                        }
+                        : undefined;
+                },
+            }),
+            RteClipboard.configure({
+                getContext: () => ({
+                    role: getRoleStyle(),
+                    block: props.styles,
+                    colors: colorPaletteStore.colors,
+                }),
+                getFirstInputMarks,
+            }),
+        ],
         editorProps: {
             handleDOMEvents: {
                 drop(view, event) {
@@ -46,86 +111,19 @@ selectedGlobalTextStyles, onSelectTextStyleType, updateRichTextEditor, textStyle
                 },
                 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 === '') {
-                        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();
+                    if (event.inputType !== 'insertText' ||
+                        state.doc.textContent !== '') {
+                        return false;
                     }
+                    const chain = editor.chain();
+                    // 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);
+                    skipStyleDetection(chain, getFirstInputMarks(state)).run();
                     return false;
                 },
-                copy(view, event) {
-                    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 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 = {
-                                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);
-                        onSelectTextStyleType({ label: 'None' });
-                    }
-                    dispatch(tr);
-                    return true;
-                },
                 click(view, event) {
                     if (isHyperlinkPopupOpen?.value)
                         return false;
@@ -145,11 +143,26 @@ selectedGlobalTextStyles, onSelectTextStyleType, updateRichTextEditor, textStyle
         },
     });
     const contentSettingStore = useUiContentSettingsStore();
+    const styleSettingsStore = useUiStyleSettingsStore();
     const eventTracker = useEventTracker();
-    const { toggleBold, toggleItalic, toggleUnderline, toggleStrike, toggleTextColor, toggleBackgroundColor, toggleBoldAll, toggleItalicAll, toggleUnderlineAll, toggleStrikeAll, toggleTextColorAll, unsetAllMarks, } = createFormattingActions(editor);
+    const { toggleBold, toggleItalic, toggleUnderline, toggleStrike, toggleTextColor, toggleBackgroundColor, boldActive, italicActive, underlineActive, strikeActive, } = createFormattingActions(editor, getRoleStyle, () => props.styles);
     const { currentAlignment, toggleTextAlign, idx: currentAlignmentIndex, keys: alignmentKeys, } = useTextAlign(editor);
-    const { selectedFont, toggleFont, toggleFontSize, toggleFontAll, toggleFontSizeAll, } = useFont(editor, fontSettings, fontStyleDropdownRef);
-    const { letterSpacingValue, lineHeightValue, letterSpacing, lineHeight, setLetterSpaceAll, setLineHeightAll, } = useSpacing(editor);
+    const { selectedFont, toggleFont, toggleFontSize } = useFont(editor, fontSettings, fontStyleDropdownRef, getRoleStyle);
+    const { letterSpacingValue: letterSpacingSlider, lineHeightValue: lineHeightSlider, letterSpacing, lineHeight, setLetterSpaceAll, setLineHeightAll, } = useSpacing(editor, getRoleStyle);
+    const letterSpacingValue = computed({
+        get: () => letterSpacingSlider.value,
+        set: (value) => {
+            markUserCommand();
+            letterSpacingSlider.value = value;
+        },
+    });
+    const lineHeightValue = computed({
+        get: () => lineHeightSlider.value,
+        set: (value) => {
+            markUserCommand();
+            lineHeightSlider.value = value;
+        },
+    });
     const { hyperlinkValue, setHyperlinkUrl, setHyperlinkUrlValue, removeHyperlink: removeHyperlinkFromComposable, applyHyperlinkToEditor, } = useHyperlink(editor);
     const { shouldShow, bubbleMenuOptions } = useBubbleMenu(editor, isHyperlinkPopupOpen);
     watch(() => props.styles.textAlign, (newAlignment) => {
@@ -190,44 +203,95 @@ selectedGlobalTextStyles, onSelectTextStyleType, updateRichTextEditor, textStyle
             });
         }
     });
-    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) {
+    // 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();
+    };
+    // Skipped while a history snapshot applies, as `selectionUpdate` is (BP-5506).
+    editor.on('transaction', () => {
+        if (historyStore.isApplyingSnapshot)
             return;
-        }
-        if (isStyleChanged(transaction) && props.styles.textStyleType) {
-            onSelectTextStyleType({
-                label: 'None',
-            });
-        }
+        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,
         });
     });
+    // 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', } = {}) => {
+        const textStyleAttributes = editor.getAttributes('textStyle');
+        const highlightAttributes = editor.getAttributes('highlight');
+        const focusedAlignment = editor.getAttributes(editor.state.selection.$anchor.node().type.name);
+        const roleStyle = getRoleStyle();
+        const markFontFamily = textStyleAttributes?.fontFamily;
+        const displayFont = markFontFamily && !isRoleVarRef(markFontFamily)
+            ? markFontFamily.replace(/^['"]|['"]$/g, '')
+            : (roleStyle?.fontFamily ?? 'Lato');
+        selectedFont.value = displayFont;
+        fontSettings.selectedFont = displayFont;
+        const markFontSize = textStyleAttributes?.fontSize;
+        const sizeSource = markFontSize && !isRoleVarRef(markFontSize)
+            ? markFontSize
+            : (roleStyle?.fontSize ?? fontSettings.selectedFontSize);
+        fontSettings.selectedFontSizePx = Math.ceil(parseFloat(emToPx(sizeSource)));
+        // 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, textColorFallback);
+        fontSettings.selectedBackgroundColor = getToolbarColorFromMark(highlightAttributes?.color, backgroundColorFallback);
+        syncFormattingActiveState();
+        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);
+            if (idx !== -1) {
+                currentAlignmentIndex.value = idx;
+            }
+        }
+        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
@@ -236,9 +300,6 @@ selectedGlobalTextStyles, onSelectTextStyleType, updateRichTextEditor, textStyle
         // after apply completes, which lands the correct values (BP-5506).
         if (historyStore.isApplyingSnapshot)
             return;
-        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;
         if (selection instanceof AllSelection) {
             // to prevent selecting editor state
@@ -250,54 +311,19 @@ selectedGlobalTextStyles, onSelectTextStyleType, updateRichTextEditor, textStyle
         }
         // TODO: resolve the issue of missing style on text between empty lines
         // retainStyleOnEmptyLine(editor, selection);
-        if (textStyleAttributes && textStyleAttributes.fontFamily) {
-            const font = textStyleAttributes.fontFamily.replace(/^['"]|['"]$/g, '');
-            selectedFont.value = font;
-            fontSettings.selectedFont = font;
-        }
-        else {
-            selectedFont.value = 'Lato';
-            fontSettings.selectedFont = 'Lato';
-        }
-        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.
-        fontSettings.selectedTextColor = getToolbarColorFromMark(textStyleAttributes?.color, '#000000');
-        fontSettings.selectedBackgroundColor = getToolbarColorFromMark(highlightAttributes?.color, 'transparent');
-        if (textStyleAttributes.lineHeight) {
-            lineHeight.value = textStyleAttributes.lineHeight;
-        }
-        else {
-            lineHeight.value = '1';
-        }
-        if (textStyleAttributes && textStyleAttributes.letterSpacing) {
-            letterSpacing.value = letterSpacingValueConvertor.convert({
-                letterSpacing: textStyleAttributes.letterSpacing,
-            });
-        }
-        else {
-            letterSpacing.value = '0';
-        }
-        if (focusedAlignment && focusedAlignment.textAlign) {
-            const idx = alignmentKeys.indexOf(focusedAlignment.textAlign);
-            if (idx !== -1) {
-                currentAlignmentIndex.value = idx;
-            }
-        }
-        else {
-            currentAlignmentIndex.value = 0;
-        }
+        syncToolbarFromEditor();
     });
     const setInitialStyleSettings = (selectedTextStyle) => {
         const globalStyles = selectedTextStyle ?? selectedGlobalTextStyles.value?.style;
         const currentAlignment = editor.getAttributes(editor.state.selection.$anchor.node().type.name);
         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
@@ -307,32 +333,39 @@ selectedGlobalTextStyles, onSelectTextStyleType, updateRichTextEditor, textStyle
                 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';
-            fontSettings.selectedFontSizePx = Math.ceil(parseFloat(emToPx(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(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).
-            fontSettings.selectedTextColor = resolveInitialToolbarTextColor(model.value, props.styles?.color, globalStyles.color);
+            // 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);
             // A global text style has no backgroundColor, so this resolves to undefined there.
             const backgroundColour = 'backgroundColor' in globalStyles
                 ? globalStyles.backgroundColor
@@ -348,142 +381,78 @@ selectedGlobalTextStyles, onSelectTextStyleType, updateRichTextEditor, textStyle
                 currentAlignment?.textAlign !== props.styles.textAlign) {
                 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) => {
-        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) => {
-        const fontStyleChanges = { ...props.styles, textStyleType: undefined };
+        markUserCommand();
         switch (editorOption.type) {
             case 'fontFamily':
                 toggleFont(editorOption.value);
-                fontStyleChanges.fontFamily = editorOption.value;
                 break;
-            case 'fontSize':
+            case 'fontSize': {
                 const size = editorOption.value;
                 fontSettings.selectedFontSizePx = size.includes('em')
                     ? Math.ceil(parseFloat(emToPx(size)))
                     : 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);
-                fontStyleChanges.color = editorOption.value;
                 break;
             case 'backgroundColor':
                 toggleBackgroundColor(editorOption.value);
-                fontStyleChanges.backgroundColor = editorOption.value;
                 break;
             case 'lineHeight':
                 setLineHeightAll(editorOption.value);
-                fontStyleChanges.lineHeight = editorOption.value;
                 break;
             case 'letterSpacing':
                 setLetterSpaceAll(editorOption.value);
-                fontStyleChanges.letterSpacing = letterSpacingValueConvertor.convert({
-                    letterSpacing: editorOption.value,
-                });
                 break;
             case 'textAlign':
                 toggleTextAlign();
-                fontStyleChanges.textAlign = currentAlignment.value.alignment;
+                persistBlockTextAlign(currentAlignment.value.alignment);
                 break;
             case 'hyperlink':
                 setHyperlinkUrl(editorOption.value);
                 break;
         }
-        syncContentSettings(fontStyleChanges);
     };
-    const syncContentSettings = (fontStyleChanges) => {
+    // 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) => {
+        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,
             });
         }
@@ -491,12 +460,83 @@ selectedGlobalTextStyles, onSelectTextStyleType, updateRichTextEditor, textStyle
             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 = () => {
+        const role = selectedGlobalTextStyles.value?.style;
+        if (!role)
+            return {};
+        const override = {};
+        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 = () => {
+        const role = getRoleStyle();
+        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 = () => 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();
+        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 };
+        const nextRole = { ...role, ...override };
+        markUserCommand();
+        styleSettingsStore.setTextStyleOption({ type, style: nextRole });
+        skipStyleDetection(relinkRoleEqualRunsChain(editor, nextRole, previousRole)).run();
+        contentSettingStore.renormalizeTextStylesForRole(type, previousRole, {
+            id: props.rawId,
+            name: props.name,
+            index: props.textItemIndex,
+            doc: sanitizeRteJson(editor.getJSON()),
+        });
+    };
     const onFocus = () => {
         emit('focus');
     };
@@ -561,6 +601,7 @@ selectedGlobalTextStyles, onSelectTextStyleType, updateRichTextEditor, textStyle
                 const selectionRange = selection
                     ? { from: selection.from, to: selection.to }
                     : undefined;
+                markUserCommand();
                 applyHyperlinkToEditor(url, text, selectionRange);
                 isHyperlinkPopupOpen.value = false;
                 break;
@@ -572,6 +613,7 @@ selectedGlobalTextStyles, onSelectTextStyleType, updateRichTextEditor, textStyle
                         content_type: props.contentType,
                     },
                 });
+                markUserCommand();
                 removeHyperlinkFromComposable();
                 isHyperlinkPopupOpen.value = false;
                 break;
@@ -599,8 +641,10 @@ selectedGlobalTextStyles, onSelectTextStyleType, updateRichTextEditor, textStyle
         lineHeightValue,
         selectedFont: computed(() => selectedFont.value),
         setInitialStyleSettings,
-        copyGlobalStyleSettings,
-        unsetAllMarks,
+        hasTypographyOverride,
+        canApplyTypographyToRole,
+        resetTypographyToRole,
+        applyTypographyToRole,
         handleHyperlink,
         hyperlinkValue,
         setHyperlinkUrlValue,